import * as paymentcryptography from "@distilled.cloud/aws/payment-cryptography";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireDays } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
export interface KeyModesOfUse {
/**
* Whether the key can be used to encrypt data.
* @default false
*/
encrypt?: boolean;
/**
* Whether the key can be used to decrypt data.
* @default false
*/
decrypt?: boolean;
/**
* Whether the key can be used to wrap other keys.
* @default false
*/
wrap?: boolean;
/**
* Whether the key can be used to unwrap other keys.
* @default false
*/
unwrap?: boolean;
/**
* Whether the key can be used to generate cryptograms and MACs.
* @default false
*/
generate?: boolean;
/**
* Whether the key can be used for signing.
* @default false
*/
sign?: boolean;
/**
* Whether the key can be used to verify signatures, cryptograms and MACs.
* @default false
*/
verify?: boolean;
/**
* Whether the key can be used to derive new keys.
* @default false
*/
deriveKey?: boolean;
/**
* Whether the key usage is unrestricted.
* @default false
*/
noRestrictions?: boolean;
}
export interface KeyAttributes {
/**
* The key algorithm to be used, e.g. `TDES_2KEY`, `AES_128`, `AES_256`,
* `RSA_2048`, `ECC_NIST_P256`. Immutable — changing it replaces the key.
*/
keyAlgorithm: string;
/**
* The type of key, e.g. `SYMMETRIC_KEY`, `ASYMMETRIC_KEY_PAIR`,
* `PRIVATE_KEY`, `PUBLIC_KEY`. Immutable — changing it replaces the key.
*/
keyClass: string;
/**
* The TR-31 cryptographic usage of the key, e.g.
* `TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY`, `TR31_M7_HMAC_KEY`,
* `TR31_P0_PIN_ENCRYPTION_KEY`. Immutable — changing it replaces the key.
*/
keyUsage: string;
/**
* The cryptographic operations the key may perform. Immutable — changing
* any mode replaces the key.
*/
keyModesOfUse: KeyModesOfUse;
}
export interface KeyProps {
/**
* The immutable cryptographic attributes of the key: algorithm, class,
* usage and modes of use. Changing any of these replaces the key.
*/
keyAttributes: KeyAttributes;
/**
* Whether the key can be exported out of the service (e.g. via TR-31/TR-34
* key blocks). Immutable — changing it replaces the key.
* @default false
*/
exportable?: boolean;
/**
* Whether the key is enabled for cryptographic operations. Toggling this
* calls StartKeyUsage/StopKeyUsage in place.
* @default true
*/
enabled?: boolean;
/**
* The algorithm used to compute the key check value, `CMAC` or
* `ANSI_X9_24`. Immutable — changing it replaces the key.
* @default ANSI_X9_24 for TDES keys, CMAC otherwise
*/
keyCheckValueAlgorithm?: string;
/**
* For ECC key pairs used in ECDH key agreement, the usage bound to the
* derived symmetric key. Immutable — changing it replaces the key.
*/
deriveKeyUsage?: string;
/**
* The waiting period before a deleted key is permanently removed, e.g.
* `"7 days"` or `Duration.days(7)` (`3` - `180` days; sent to the API as
* whole days — a bare number is milliseconds). During the window the key
* is `DELETE_PENDING` and can be restored.
* @default "3 days"
*/
deleteWindow?: Duration.Input;
/**
* Tags to apply to the key. Merged with internal Alchemy tags.
*/
tags?: Record<string, string>;
}
export interface Key extends Resource<
"AWS.PaymentCryptography.Key",
KeyProps,
{
/**
* ARN of the key.
*/
keyArn: string;
/**
* Key state (e.g. `CREATE_COMPLETE`, `DELETE_PENDING`).
*/
keyState: string;
/**
* Key check value (KCV) used to verify the key material.
*/
keyCheckValue: string;
/**
* Whether the key is enabled for cryptographic operations.
*/
enabled: boolean;
/**
* Whether the key material can be exported.
*/
exportable: boolean;
},
never,
Providers
> {}
/**
* An AWS Payment Cryptography key — a managed cryptographic key with TR-31
* attributes (algorithm, class, usage, modes of use) used for data
* encryption, MAC generation/verification, and other payment-domain
* cryptographic operations.
*
* The key ARN is auto-assigned by the service; attach an {@link Alias} for a
* stable human-readable identifier. Deletion schedules the key for removal
* after a waiting window (minimum 3 days) during which it can be restored.
* ### Creating Keys
* **Example:** Symmetric data-encryption key
* ```typescript
* import * as PaymentCryptography from "@alchemy.run/aws/PaymentCryptography";
*
* const key = yield* PaymentCryptography.Key("DataKey", {
* keyAttributes: {
* keyAlgorithm: "AES_128",
* keyClass: "SYMMETRIC_KEY",
* keyUsage: "TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY",
* keyModesOfUse: { encrypt: true, decrypt: true, wrap: true, unwrap: true },
* },
* });
* ```
*
* **Example:** HMAC key for MAC generation and verification
* ```typescript
* const macKey = yield* PaymentCryptography.Key("MacKey", {
* keyAttributes: {
* keyAlgorithm: "HMAC_SHA256",
* keyClass: "SYMMETRIC_KEY",
* keyUsage: "TR31_M7_HMAC_KEY",
* keyModesOfUse: { generate: true, verify: true },
* },
* });
* ```
*
* ### Managing Key State
* **Example:** Disable a key without deleting it
* ```typescript
* const key = yield* PaymentCryptography.Key("DataKey", {
* keyAttributes: { ... },
* enabled: false,
* });
* ```
*
* ### Using Keys at Runtime
* **Example:** Encrypt data from a Lambda handler
* ```typescript
* // init
* const encrypt = yield* PaymentCryptography.EncryptData(key);
*
* return {
* fetch: Effect.gen(function* () {
* // runtime — PlainText is hex-encoded
* const result = yield* encrypt({
* PlainText: "31323334353637383930313233343536",
* EncryptionAttributes: { Symmetric: { Mode: "CBC" } },
* });
* return HttpServerResponse.json({ cipherText: result.CipherText });
* }),
* };
* ```
*
* @resource
*/
export const Key = Resource<Key>("AWS.PaymentCryptography.Key");
const toWireKeyAttributes = (attributes: KeyAttributes): paymentcryptography.KeyAttributes => ({
KeyAlgorithm: attributes.keyAlgorithm,
KeyClass: attributes.keyClass,
KeyUsage: attributes.keyUsage,
KeyModesOfUse: {
Encrypt: attributes.keyModesOfUse.encrypt ?? false,
Decrypt: attributes.keyModesOfUse.decrypt ?? false,
Wrap: attributes.keyModesOfUse.wrap ?? false,
Unwrap: attributes.keyModesOfUse.unwrap ?? false,
Generate: attributes.keyModesOfUse.generate ?? false,
Sign: attributes.keyModesOfUse.sign ?? false,
Verify: attributes.keyModesOfUse.verify ?? false,
DeriveKey: attributes.keyModesOfUse.deriveKey ?? false,
NoRestrictions: attributes.keyModesOfUse.noRestrictions ?? false,
},
});
const toAttrs = (key: paymentcryptography.Key): Key["Attributes"] => ({
keyArn: key.KeyArn,
keyState: key.KeyState,
keyCheckValue: key.KeyCheckValue,
enabled: key.Enabled,
exportable: key.Exportable,
});
const tagsToRecord = (tags: readonly paymentcryptography.Tag[]): Record<string, string> =>
Object.fromEntries(tags.map((t) => [t.Key, t.Value ?? ""]));
const fetchKeyTags = (keyArn: string) =>
paymentcryptography.listTagsForResource.items({ ResourceArn: keyArn }).pipe(
Stream.runCollect,
Effect.map((chunk) => tagsToRecord(Array.from(chunk))),
Effect.orElseSucceed(() => ({}) as Record<string, string>),
);
export const KeyProvider = () =>
Provider.effect(
Key,
Effect.gen(function* () {
// Fetch a key by ARN; a missing or fully-deleted key observes as
// `undefined`. A key inside its deletion window (DELETE_PENDING) is
// still returned so reconcile can restore it.
const observeKey = Effect.fn(function* (keyArn: string) {
const found = yield* paymentcryptography.getKey({ KeyIdentifier: keyArn }).pipe(
Effect.map((r) => r.Key),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
if (found === undefined || found.KeyState === "DELETE_COMPLETE") {
return undefined;
}
return found;
});
// Keys have service-assigned identity (no name), so locating one
// without a cached ARN falls back to scanning for the internal
// Alchemy tags.
const findKeyByTags = Effect.fn(function* (id: string) {
const summaries = yield* paymentcryptography.listKeys.items({}).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).filter((k) => k.KeyState !== "DELETE_COMPLETE")),
);
for (const summary of summaries) {
const tags = yield* fetchKeyTags(summary.KeyArn);
if (yield* hasAlchemyTags(id, tags)) {
return summary.KeyArn;
}
}
return undefined;
});
return Key.Provider.of({
stables: ["keyArn", "keyCheckValue"],
list: () =>
paymentcryptography.listKeys.items({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk)
// Keys already inside their deletion window are as deleted
// as the API allows — a second DeleteKey is a no-op, so they
// are not orphans (mirrors KMS PendingDeletion filtering).
.filter((k) => k.KeyState !== "DELETE_PENDING" && k.KeyState !== "DELETE_COMPLETE")
.map((k): Key["Attributes"] => ({
keyArn: k.KeyArn,
keyState: k.KeyState,
keyCheckValue: k.KeyCheckValue,
enabled: k.Enabled,
exportable: k.Exportable,
})),
),
),
read: Effect.fn(function* ({ id, output }) {
const keyArn = output?.keyArn ?? (yield* findKeyByTags(id));
if (keyArn === undefined) return undefined;
const key = yield* observeKey(keyArn);
if (key === undefined) return undefined;
const attrs = toAttrs(key);
const tags = yield* fetchKeyTags(key.KeyArn);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return undefined;
const wireOld = toWireKeyAttributes(olds.keyAttributes);
const wireNew = toWireKeyAttributes(news.keyAttributes);
if (
JSON.stringify(wireOld) !== JSON.stringify(wireNew) ||
(olds.exportable ?? false) !== (news.exportable ?? false) ||
olds.keyCheckValueAlgorithm !== news.keyCheckValueAlgorithm ||
olds.deriveKeyUsage !== news.deriveKeyUsage
) {
return { action: "replace" } as const;
}
// fall through: undefined → default update (enabled / tags sync)
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const desiredEnabled = news.enabled ?? true;
const internalTags = yield* createInternalTags(id);
// 1. Observe — output.keyArn is only an identity cache; the cloud
// is authoritative. Fall back to a tag scan for adoption after
// state-persistence failures.
const cachedArn = output?.keyArn ?? (yield* findKeyByTags(id));
let key = cachedArn === undefined ? undefined : yield* observeKey(cachedArn);
// A key inside its deletion window is restored rather than
// recreated — the material (and dependent ciphertext) survives.
if (key !== undefined && key.KeyState === "DELETE_PENDING") {
key = yield* paymentcryptography
.restoreKey({ KeyIdentifier: key.KeyArn })
.pipe(Effect.map((r) => r.Key));
}
// 2. Ensure — create when missing.
if (key === undefined) {
key = yield* paymentcryptography
.createKey({
KeyAttributes: toWireKeyAttributes(news.keyAttributes),
Exportable: news.exportable ?? false,
Enabled: desiredEnabled,
KeyCheckValueAlgorithm: news.keyCheckValueAlgorithm,
DeriveKeyUsage: news.deriveKeyUsage,
Tags: Object.entries({
...news.tags,
...internalTags,
}).map(([Key, Value]) => ({ Key, Value })),
})
.pipe(Effect.map((r) => r.Key));
}
// 3a. Sync enabled state against OBSERVED cloud state.
if (key.Enabled !== desiredEnabled) {
key = desiredEnabled
? yield* paymentcryptography
.startKeyUsage({ KeyIdentifier: key.KeyArn })
.pipe(Effect.map((r) => r.Key))
: yield* paymentcryptography
.stopKeyUsage({ KeyIdentifier: key.KeyArn })
.pipe(Effect.map((r) => r.Key));
}
// 3b. Sync tags — diff against observed cloud tags so adoption
// (foreign tags) converges.
const observedTags = yield* fetchKeyTags(key.KeyArn);
const desiredTags: Record<string, string> = {
...news.tags,
...internalTags,
};
const { upsert, removed } = diffTags(observedTags, desiredTags);
if (upsert.length > 0) {
yield* paymentcryptography.tagResource({
ResourceArn: key.KeyArn,
Tags: upsert,
});
}
if (removed.length > 0) {
yield* paymentcryptography.untagResource({
ResourceArn: key.KeyArn,
TagKeys: removed,
});
}
yield* session.note(key.KeyArn);
return toAttrs(key);
}),
delete: Effect.fn(function* ({ output, olds }) {
yield* paymentcryptography
.deleteKey({
KeyIdentifier: output.keyArn,
DeleteKeyInDays: toWireDays(olds.deleteWindow) ?? 3,
})
.pipe(
Effect.catchTags({
ResourceNotFoundException: () => Effect.void,
// A key already scheduled for deletion rejects a second
// DeleteKey with a conflict — that is the desired end state,
// so treat it as success. Any other conflict is re-raised.
ConflictException: (error) =>
paymentcryptography.getKey({ KeyIdentifier: output.keyArn }).pipe(
Effect.flatMap((r) =>
r.Key.KeyState === "DELETE_PENDING" || r.Key.KeyState === "DELETE_COMPLETE"
? Effect.void
: Effect.fail(error),
),
Effect.catchTag("ResourceNotFoundException", () => Effect.void),
),
}),
);
}),
});
}),
);