import * as kms from "@distilled.cloud/aws/kms";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags } from "alchemy/Tags";
import { toWireDays } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { AccountID } from "../Environment.ts";
import type { PolicyDocument } from "../IAM/Policy.ts";
import { normalizePolicyDocument, stringifyPolicyDocument } from "../IAM/Policy.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
export type KeyId = string;
export type KeyArn = `arn:aws:kms:${RegionID}:${AccountID}:key/${KeyId}`;
export type { KeySpec, KeyState, KeyUsageType } from "@distilled.cloud/aws/kms";
export interface KeyProps {
/**
* Description for the KMS key.
*/
description?: string;
/**
* Cryptographic operations that the key supports.
* @default "ENCRYPT_DECRYPT"
*/
keyUsage?: kms.KeyUsageType;
/**
* Type of key material for the KMS key.
* @default "SYMMETRIC_DEFAULT"
*/
keySpec?: kms.KeySpec;
/**
* Key policy, either as a structured {@link PolicyDocument} or a raw JSON
* string (escape hatch). If omitted, AWS creates and manages the default
* key policy.
*/
policy?: PolicyDocument | string;
/**
* Whether to bypass KMS policy lockout safety checks when creating or updating
* the key policy.
* @default false
*/
bypassPolicyLockoutSafetyCheck?: boolean;
/**
* Whether the KMS key is enabled.
* @default true
*/
enabled?: boolean;
/**
* Whether automatic key rotation is enabled.
* @default false
*/
enableKeyRotation?: boolean;
/**
* Rotation period when automatic key rotation is enabled. Accepts any
* `Duration.Input` (e.g. `"90 days"`, `Duration.days(90)`; a bare number
* is milliseconds); the wire unit is whole days.
*/
rotationPeriod?: Duration.Input;
/**
* Whether to create a multi-region primary key.
* @default false
*/
multiRegion?: boolean;
/**
* Waiting period before AWS permanently deletes the key after destroy
* schedules deletion. Accepts any `Duration.Input` (e.g. `"7 days"`,
* `Duration.days(7)`; a bare number is milliseconds); the wire unit is
* whole days.
* @default 30 days
*/
deletionWindow?: Duration.Input;
/**
* User-defined tags to apply to the key.
*/
tags?: Record<string, string>;
}
export interface Key extends Resource<
"AWS.KMS.Key",
KeyProps,
{
keyId: KeyId;
keyArn: KeyArn;
description: string | undefined;
keyUsage: kms.KeyUsageType;
keySpec: kms.KeySpec;
keyState: kms.KeyState | undefined;
enabled: boolean;
keyRotationEnabled: boolean | undefined;
rotationPeriodInDays: number | undefined;
multiRegion: boolean;
policy: string | undefined;
deletionWindowInDays: number;
tags: Record<string, string>;
},
never,
Providers
> {}
/**
* A customer managed AWS KMS key.
*
* ### Creating Keys
* **Example:** Symmetric Encryption Key
* ```typescript
* import * as KMS from "@alchemy.run/aws/KMS";
*
* const key = yield* KMS.Key("AppKey", {
* description: "Application encryption key",
* enableKeyRotation: true,
* deletionWindow: "7 days",
* });
* ```
*
* ### Key Policies
* **Example:** Key with Inline Policy
* ```typescript
* const key = yield* KMS.Key("PolicyKey", {
* policy: {
* Version: "2012-10-17",
* Statement: [{
* Effect: "Allow",
* Principal: { AWS: "arn:aws:iam::123456789012:root" },
* Action: ["kms:*"],
* Resource: "*",
* }],
* },
* });
* ```
*
* ### Runtime Operations
* Bind the KMS crypto operations to the key inside a Lambda function.
* Each binding grants least-privilege IAM (the exact key ARN) and injects
* the `KeyId` automatically.
*
* **Example:** Encrypt and Decrypt from a Lambda Function
* ```typescript
* // init
* const key = yield* AWS.KMS.Key("AppKey");
* const encrypt = yield* AWS.KMS.Encrypt(key);
* const decrypt = yield* AWS.KMS.Decrypt(key);
*
* // runtime
* const { CiphertextBlob } = yield* encrypt({
* Plaintext: new TextEncoder().encode("secret"),
* });
* const { Plaintext } = yield* decrypt({ CiphertextBlob });
* ```
*
* **Example:** Envelope Encryption with a Data Key
* ```typescript
* // init
* const generateDataKey = yield* AWS.KMS.GenerateDataKey(key);
*
* // runtime — encrypt locally with the plaintext key, store the blob
* const { Plaintext, CiphertextBlob } = yield* generateDataKey({
* KeySpec: "AES_256",
* });
* ```
*/
export const Key = Resource<Key>("AWS.KMS.Key");
const defaultKeyUsage = "ENCRYPT_DECRYPT" as const;
const defaultKeySpec = "SYMMETRIC_DEFAULT" as const;
const defaultDeletionWindowInDays = 30;
export const KeyProvider = () =>
Provider.succeed(Key, {
stables: ["keyId", "keyArn"],
list: () =>
Effect.gen(function* () {
const keys = yield* kms.listKeys.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.Keys ?? [])
.map((key) => key.KeyId)
.filter((keyId): keyId is string => keyId !== undefined),
),
),
);
const hydrated = yield* Effect.forEach(
keys,
(keyId) =>
readKey({
keyId,
deletionWindowInDays: defaultDeletionWindowInDays,
}),
{ concurrency: 5 },
);
return hydrated.filter(
(key): key is Key["Attributes"] =>
key !== undefined && key.keyState !== "PendingDeletion",
);
}),
read: Effect.fn(function* ({ olds = {}, output }) {
// KMS keys have no stable user-assignable identity — only a
// cloud-generated keyId — so there is nothing to adopt. We only refresh
// a key we already own (via output.keyId); with no prior output the
// engine treats this as a greenfield create and mints a fresh key.
if (!output?.keyId) return undefined;
return yield* readKey({
keyId: output.keyId,
deletionWindowInDays:
output.deletionWindowInDays ??
toWireDays(olds.deletionWindow) ??
defaultDeletionWindowInDays,
});
}),
diff: Effect.fn(function* ({ news = {}, olds = {} }) {
if (!isResolved(news)) return;
if (
(news.keyUsage ?? defaultKeyUsage) !== (olds.keyUsage ?? defaultKeyUsage) ||
(news.keySpec ?? defaultKeySpec) !== (olds.keySpec ?? defaultKeySpec) ||
(news.multiRegion ?? false) !== (olds.multiRegion ?? false)
) {
return { action: "replace" } as const;
}
}),
reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...news.tags };
const keyUsage = news.keyUsage ?? defaultKeyUsage;
const keySpec = news.keySpec ?? defaultKeySpec;
const enabled = news.enabled ?? true;
const enableKeyRotation = news.enableKeyRotation ?? false;
const multiRegion = news.multiRegion ?? false;
const deletionWindowInDays = toWireDays(news.deletionWindow) ?? defaultDeletionWindowInDays;
const rotationPeriodInDays = toWireDays(news.rotationPeriod);
const desiredPolicy =
news.policy === undefined
? undefined
: typeof news.policy === "string"
? news.policy
: stringifyPolicyDocument(news.policy);
// Observe via the cached identifier only — no tag-based discovery. On a
// create or replacement the engine calls reconcile with
// `output === undefined`, so we fall through to `createKey` and mint a
// fresh key rather than adopting an unrelated one (which would collapse a
// replacement into a no-op).
let state = output?.keyId
? yield* readKey({ keyId: output.keyId, deletionWindowInDays })
: undefined;
if (state?.keyState === "PendingDeletion") {
yield* kms
.cancelKeyDeletion({ KeyId: state.keyId })
.pipe(Effect.catchTag("NotFoundException", () => Effect.void));
state = yield* readKey({ keyId: state.keyId, deletionWindowInDays });
}
if (state === undefined) {
const created = yield* kms.createKey({
Description: news.description,
KeyUsage: keyUsage,
KeySpec: keySpec,
Policy: desiredPolicy,
BypassPolicyLockoutSafetyCheck: news.bypassPolicyLockoutSafetyCheck,
Tags: toKmsTags(desiredTags),
MultiRegion: multiRegion,
});
const keyId = created.KeyMetadata?.KeyId;
if (!keyId) {
return yield* Effect.die(new Error("createKey returned no key ID"));
}
state = yield* readKey({ keyId, deletionWindowInDays });
if (!state) {
return yield* Effect.die(new Error(`failed to read created KMS key ${keyId}`));
}
}
const desiredDescription = news.description ?? "";
if ((state.description ?? "") !== desiredDescription) {
yield* kms
.updateKeyDescription({
KeyId: state.keyId,
Description: desiredDescription,
})
.pipe(
Effect.retry({
while: isKmsEventuallyConsistent,
schedule: kmsRetrySchedule,
}),
);
}
if (enabled && !state.enabled) {
yield* kms.enableKey({ KeyId: state.keyId }).pipe(
Effect.retry({
while: isKmsEventuallyConsistent,
schedule: kmsRetrySchedule,
}),
);
}
if (desiredPolicy !== undefined && !samePolicy(state.policy, desiredPolicy)) {
yield* kms
.putKeyPolicy({
KeyId: state.keyId,
PolicyName: "default",
Policy: desiredPolicy,
BypassPolicyLockoutSafetyCheck: news.bypassPolicyLockoutSafetyCheck,
})
.pipe(
Effect.retry({
while: isKmsEventuallyConsistent,
schedule: kmsRetrySchedule,
}),
);
}
if (
enableKeyRotation &&
(state.keyRotationEnabled !== true ||
(rotationPeriodInDays !== undefined &&
state.rotationPeriodInDays !== rotationPeriodInDays))
) {
yield* kms
.enableKeyRotation({
KeyId: state.keyId,
RotationPeriodInDays: rotationPeriodInDays,
})
.pipe(
Effect.retry({
while: isKmsEventuallyConsistent,
schedule: kmsRetrySchedule,
}),
);
} else if (!enableKeyRotation && state.keyRotationEnabled) {
yield* kms.disableKeyRotation({ KeyId: state.keyId }).pipe(
Effect.retry({
while: isKmsEventuallyConsistent,
schedule: kmsRetrySchedule,
}),
);
}
if (!enabled && state.enabled) {
yield* kms.disableKey({ KeyId: state.keyId }).pipe(
Effect.retry({
while: isKmsEventuallyConsistent,
schedule: kmsRetrySchedule,
}),
);
}
const observedTags = yield* listKeyTags(state.keyId);
const { removed, upsert } = diffTags(observedTags, desiredTags);
if (upsert.length > 0) {
yield* kms
.tagResource({
KeyId: state.keyId,
Tags: toKmsTags(Object.fromEntries(upsert.map((tag) => [tag.Key, tag.Value]))),
})
.pipe(
Effect.retry({
while: isKmsEventuallyConsistent,
schedule: kmsRetrySchedule,
}),
);
}
if (removed.length > 0) {
yield* kms
.untagResource({
KeyId: state.keyId,
TagKeys: removed,
})
.pipe(
Effect.retry({
while: isKmsEventuallyConsistent,
schedule: kmsRetrySchedule,
}),
);
}
const updated = yield* readConvergedKey({
keyId: state.keyId,
deletionWindowInDays,
desiredDescription,
desiredEnabled: enabled,
desiredKeyRotationEnabled: enableKeyRotation,
desiredPolicy,
desiredRotationPeriodInDays: rotationPeriodInDays,
desiredTags,
});
yield* session.note(updated.keyArn);
return updated;
}),
delete: Effect.fn(function* ({ output, session }) {
yield* kms
.scheduleKeyDeletion({
KeyId: output.keyId,
PendingWindowInDays: output.deletionWindowInDays,
})
.pipe(
Effect.catchTags({
NotFoundException: () => Effect.void,
KMSInvalidStateException: () => Effect.void,
}),
);
const remaining = yield* Effect.repeat(
kms.describeKey({ KeyId: output.keyId }).pipe(
Effect.map((response) => response.KeyMetadata?.KeyState),
Effect.catchTag("NotFoundException", () => Effect.undefined),
),
{
schedule: Schedule.fixed("250 millis"),
until: (state) => state === undefined || state === "PendingDeletion",
times: 20,
},
);
if (remaining !== undefined && remaining !== "PendingDeletion") {
return yield* Effect.die(
new Error(`KMS key ${output.keyId} remained ${remaining} after scheduling deletion`),
);
}
yield* session.note(`Scheduled KMS key deletion: ${output.keyId}`);
}),
});
const readKey = Effect.fn(function* ({
keyId,
deletionWindowInDays,
}: {
keyId: string;
deletionWindowInDays: number;
}) {
const described = yield* kms
.describeKey({ KeyId: keyId })
.pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
const metadata = described?.KeyMetadata;
if (!metadata?.Arn) return undefined;
if (metadata.KeyManager !== undefined && metadata.KeyManager !== "CUSTOMER") {
return undefined;
}
const [tags, rotation, policy] = yield* Effect.all(
[listKeyTags(metadata.KeyId), readKeyRotation(metadata.KeyId), readKeyPolicy(metadata.KeyId)],
{ concurrency: "unbounded" },
);
return toAttrs({
metadata,
tags,
rotation,
policy,
deletionWindowInDays,
});
});
const readConvergedKey = Effect.fn(function* ({
keyId,
deletionWindowInDays,
desiredDescription,
desiredEnabled,
desiredKeyRotationEnabled,
desiredPolicy,
desiredRotationPeriodInDays,
desiredTags,
}: {
keyId: string;
deletionWindowInDays: number;
desiredDescription: string;
desiredEnabled: boolean;
desiredKeyRotationEnabled: boolean;
desiredPolicy: string | undefined;
desiredRotationPeriodInDays: number | undefined;
desiredTags: Record<string, string>;
}) {
const observeConverged = Effect.gen(function* () {
const key = yield* readKey({ keyId, deletionWindowInDays });
if (!key) {
return yield* new KmsKeyNotConverged();
}
if ((key.description ?? "") !== desiredDescription) {
return yield* new KmsKeyNotConverged();
}
if (key.enabled !== desiredEnabled) {
return yield* new KmsKeyNotConverged();
}
if (
!Object.entries(desiredTags).every(([name, value]) => key.tags[name] === value) ||
!Object.keys(key.tags).every((name) => desiredTags[name] === key.tags[name])
) {
return yield* new KmsKeyNotConverged();
}
if (desiredPolicy !== undefined && !samePolicy(key.policy, desiredPolicy)) {
return yield* new KmsKeyNotConverged();
}
if (desiredEnabled) {
if (desiredKeyRotationEnabled && key.keyRotationEnabled !== true) {
return yield* new KmsKeyNotConverged();
}
if (!desiredKeyRotationEnabled && key.keyRotationEnabled === true) {
return yield* new KmsKeyNotConverged();
}
if (
desiredKeyRotationEnabled &&
desiredRotationPeriodInDays !== undefined &&
key.rotationPeriodInDays !== desiredRotationPeriodInDays
) {
return yield* new KmsKeyNotConverged();
}
}
return key;
});
return yield* Effect.gen(function* () {
// KMS reads can briefly move backwards after a successful mutation (for
// example, GetKeyPolicy may serve the new policy once and then an older
// replica's default policy). A single matching read is therefore not a
// sufficient convergence signal under high concurrency. Require two
// consecutive observations before returning the resource to the engine.
yield* observeConverged;
yield* Effect.sleep("500 millis");
return yield* observeConverged;
}).pipe(
Effect.retry({
while: (error: { _tag: string }) =>
error._tag === "KmsKeyNotConverged" || isKmsEventuallyConsistent(error),
schedule: kmsRetrySchedule,
}),
);
});
const listKeyTags = Effect.fn(function* (keyId: string) {
const pages = yield* kms.listResourceTags.pages({ KeyId: keyId }).pipe(
Stream.runCollect,
Effect.catchTag("NotFoundException", () => Effect.succeed([])),
);
return toTagRecord(Array.from(pages).flatMap((page) => page.Tags ?? []));
});
const readKeyRotation = Effect.fn(function* (keyId: string) {
return yield* kms.getKeyRotationStatus({ KeyId: keyId }).pipe(
Effect.map((response) => ({
enabled: response.KeyRotationEnabled,
periodInDays: response.RotationPeriodInDays,
})),
Effect.catchTags({
UnsupportedOperationException: () => Effect.undefined,
KMSInvalidStateException: () => Effect.undefined,
NotFoundException: () => Effect.undefined,
}),
);
});
const readKeyPolicy = Effect.fn(function* (keyId: string) {
return yield* kms.getKeyPolicy({ KeyId: keyId, PolicyName: "default" }).pipe(
Effect.map((response) => response.Policy),
Effect.catchTags({
KMSInvalidStateException: () => Effect.undefined,
NotFoundException: () => Effect.undefined,
}),
);
});
const toAttrs = ({
metadata,
tags,
rotation,
policy,
deletionWindowInDays,
}: {
metadata: kms.KeyMetadata;
tags: Record<string, string>;
rotation: { enabled?: boolean; periodInDays?: number } | undefined;
policy: string | undefined;
deletionWindowInDays: number;
}): Key["Attributes"] => ({
keyId: metadata.KeyId,
keyArn: metadata.Arn as KeyArn,
description: metadata.Description,
keyUsage: metadata.KeyUsage ?? defaultKeyUsage,
keySpec: metadata.KeySpec ?? defaultKeySpec,
keyState: metadata.KeyState,
enabled: metadata.Enabled ?? false,
keyRotationEnabled: rotation?.enabled,
rotationPeriodInDays: rotation?.periodInDays,
multiRegion: metadata.MultiRegion ?? false,
policy,
deletionWindowInDays,
tags,
});
const toTagRecord = (tags: kms.Tag[] | undefined): Record<string, string> =>
Object.fromEntries(
(tags ?? [])
.filter(
(tag): tag is kms.Tag => typeof tag.TagKey === "string" && typeof tag.TagValue === "string",
)
.map((tag) => [tag.TagKey, tag.TagValue]),
);
const toKmsTags = (tags: Record<string, string>): kms.Tag[] =>
Object.entries(tags).map(([TagKey, TagValue]) => ({ TagKey, TagValue }));
/**
* Compare the observed key policy against the desired one using the shared
* IAM canonicalizer so a re-deploy of an equivalent document (different key
* order, whitespace, or PolicyDocument-vs-string form) is a no-op.
*/
const samePolicy = (observed: string | undefined, desired: string | undefined) => {
if (observed === desired) return true;
if (observed === undefined || desired === undefined) return false;
return normalizePolicyDocument(observed) === normalizePolicyDocument(desired);
};
const isKmsEventuallyConsistent = (error: { _tag: string }) =>
error._tag === "DependencyTimeoutException" ||
error._tag === "KMSInternalException" ||
error._tag === "KMSInvalidStateException";
class KmsKeyNotConverged extends Data.TaggedError("KmsKeyNotConverged") {}
const kmsRetrySchedule = Schedule.max([Schedule.exponential(250), Schedule.recurs(7)]);