import * as secretsmanager from "@distilled.cloud/aws/secrets-manager";
import { OwnedBySomeoneElse } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { PolicyDocument } from "../IAM/Policy.ts";
import { normalizePolicyDocument, stringifyPolicyDocument } from "../IAM/Policy.ts";
import type { Providers } from "../Providers.ts";
export class SecretUnexpectedResponse extends Data.TaggedError("SecretUnexpectedResponse")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export interface GenerateSecretStringProps extends secretsmanager.GetRandomPasswordRequest {
/**
* JSON template merged with the generated password.
* @default "{}"
*/
secretStringTemplate?: string;
/**
* Key written into the generated secret payload.
* @default "password"
*/
generateStringKey?: string;
}
export interface SecretProps {
/**
* Secret name. If omitted, Alchemy generates a deterministic physical name.
*/
name?: string;
/**
* Optional description for the secret.
*/
description?: string;
/**
* Optional KMS key used to encrypt the secret.
*/
kmsKeyId?: string;
/**
* Plain string secret value.
*/
secretString?: Redacted.Redacted<string>;
/**
* Binary secret value.
*/
secretBinary?: Redacted.Redacted<Uint8Array<ArrayBufferLike>>;
/**
* Generate a password and store it inside a JSON secret string.
*/
generateSecretString?: GenerateSecretStringProps;
/**
* Resource-based permission policy attached to the secret
* (`PutResourcePolicy`). Accepts a typed {@link PolicyDocument} or a raw
* JSON string as an escape hatch (e.g. for adoption of an existing
* policy). Omitting the prop removes any policy previously attached by
* Alchemy.
*/
resourcePolicy?: PolicyDocument | string;
/**
* Number of days (a whole number from 7 to 30) AWS keeps the secret recoverable after Alchemy
* deletes it (`DeleteSecret`'s `RecoveryWindowInDays`).
*
* When omitted, deletion is immediate: the secret is deleted with
* `ForceDeleteWithoutRecovery` and its value cannot be restored. When set,
* the secret stays scheduled for deletion for this many days and can be
* restored with `RestoreSecret`. While it is scheduled, AWS does not allow
* another secret with the same name, so re-adding a `Secret` with the same
* explicit {@link name} restores the pending secret and converges it to the
* desired props instead of creating a new one. (Without `name`, a re-added
* `Secret` gets a new generated name and creates a new secret.) Only a
* pending secret that carries this resource's Alchemy ownership tags is
* restored; any other one fails with `OwnedBySomeoneElse`.
*
* @default undefined (delete immediately, no recovery window)
*/
recoveryWindowInDays?: number;
/**
* User-defined tags for the secret.
*/
tags?: Record<string, string>;
}
export interface Secret extends Resource<
"AWS.SecretsManager.Secret",
SecretProps,
{
/**
* ARN of the secret.
*/
secretArn: string;
/**
* Name of the secret.
*/
secretName: string;
/**
* Version ID of the `AWSCURRENT` secret value, if a value has been set.
*/
versionId: string | undefined;
/**
* Description of the secret.
*/
description: string | undefined;
/**
* KMS key ID (or ARN) used to encrypt the secret value, if a
* customer-managed key was configured.
*/
kmsKeyId: string | undefined;
/**
* Tags on the secret.
*/
tags: Record<string, string>;
/**
* The resource-based policy (canonical JSON), as observed. Lets
* `alchemy drift` detect out-of-band changes.
*/
resourcePolicy?: string;
},
never,
Providers
> {}
/**
* An AWS Secrets Manager secret.
*
* `Secret` owns the lifecycle of the secret metadata and current value. It can
* store a caller-provided value or generate a password-backed JSON payload for
* downstream resources such as Aurora clusters and RDS proxies.
* ### Creating Secrets
* **Example:** Static Secret String
* ```typescript
* const secret = yield* Secret("DbSecret", {
* secretString: Redacted.make(JSON.stringify({
* username: "app",
* password: "super-secret",
* })),
* });
* ```
*
* **Example:** Generated Password Secret
* ```typescript
* const secret = yield* Secret("DbSecret", {
* generateSecretString: {
* secretStringTemplate: JSON.stringify({ username: "app" }),
* generateStringKey: "password",
* PasswordLength: 32,
* },
* });
* ```
*
* ### Resource Policies
* **Example:** Typed Resource Policy
* ```typescript
* const secret = yield* Secret("SharedSecret", {
* secretString: Redacted.make("shared-value"),
* resourcePolicy: {
* Version: "2012-10-17",
* Statement: [
* {
* Effect: "Allow",
* Principal: { AWS: `arn:aws:iam::${accountId}:root` },
* Action: ["secretsmanager:GetSecretValue"],
* Resource: "*",
* },
* ],
* },
* });
* ```
*
* @resource
*/
export const Secret = Resource<Secret>("AWS.SecretsManager.Secret");
const toTagRecord = (
tags: Array<{ Key?: string; Value?: string }> | undefined,
): Record<string, string> =>
Object.fromEntries(
(tags ?? [])
.filter(
(tag): tag is { Key: string; Value: string } =>
typeof tag.Key === "string" && typeof tag.Value === "string",
)
.map((tag) => [tag.Key, tag.Value]),
);
/**
* Bounded retry through the async `ForceDeleteWithoutRecovery` window
* (`InvalidRequestException` "already scheduled for deletion"; force
* deletions complete within seconds).
*
* Expressed as an explicitly-typed helper: inlining `Effect.retry` here
* leaves `Retry.Return`'s conditional type unresolved in the provider's
* inferred layer type, which TypeScript's declaration emit widens to an
* `unknown` R — poisoning the whole `AWS.providers()` union for every
* downstream consumer.
*/
const retryThroughDeletionWindow = <A, E extends { _tag: string }, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
Effect.retry(self, {
while: (e) =>
e._tag === "InvalidRequestException" &&
isDeletionInProgress((e as { message?: string }).message),
schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
});
const isDeletionInProgress = (message: string | undefined): boolean => {
const normalized = message?.toLowerCase();
return (
normalized?.includes("scheduled for deletion") === true ||
normalized?.includes("marked for deletion") === true
);
};
/**
* Raised when `recoveryWindowInDays` is not a whole number from 7 to 30, the
* range `DeleteSecret` accepts.
*/
export class SecretRecoveryWindowOutOfRange extends Data.TaggedError(
"SecretRecoveryWindowOutOfRange",
)<{
message: string;
recoveryWindowInDays: number;
}> {}
const validateRecoveryWindow = (recoveryWindowInDays: number | undefined) =>
recoveryWindowInDays === undefined ||
(Number.isInteger(recoveryWindowInDays) &&
recoveryWindowInDays >= 7 &&
recoveryWindowInDays <= 30)
? Effect.void
: Effect.fail(
new SecretRecoveryWindowOutOfRange({
message: `recoveryWindowInDays must be a whole number from 7 to 30, got ${recoveryWindowInDays}.`,
recoveryWindowInDays,
}),
);
class SecretNotVisible extends Data.TaggedError("SecretNotVisible")<{
readonly secretId: string;
}> {}
class SecretStillExists extends Data.TaggedError("SecretStillExists")<{
readonly secretId: string;
}> {}
export const SecretProvider = () =>
Provider.effect(
Secret,
Effect.gen(function* () {
const toSecretName = (id: string, props: SecretProps) =>
props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 512 });
const createValue = Effect.fn(function* (props: SecretProps) {
if (props.secretBinary !== undefined) {
return { SecretBinary: props.secretBinary } as const;
}
if (props.secretString !== undefined) {
return { SecretString: props.secretString } as const;
}
if (props.generateSecretString) {
const {
secretStringTemplate = "{}",
generateStringKey = "password",
...request
} = props.generateSecretString;
const password = yield* secretsmanager.getRandomPassword(request);
const generated = password.RandomPassword
? typeof password.RandomPassword === "string"
? password.RandomPassword
: Redacted.value(password.RandomPassword)
: "";
const template = JSON.parse(secretStringTemplate) as Record<string, unknown>;
return {
SecretString: JSON.stringify({
...template,
[generateStringKey]: generated,
}),
} as const;
}
return {} as const;
});
/**
* The attributes `read` and `reconcile` both report, observed on the
* secret, so a converged secret reads unchanged. The version is the
* live `AWSCURRENT` one, so a value written out of band shows up.
*/
const observeSecretAttributes = Effect.fn(function* (
described: secretsmanager.DescribeSecretResponse & { ARN: string; Name: string },
) {
const policy = yield* secretsmanager.getResourcePolicy({ SecretId: described.ARN }).pipe(
Effect.map((response) => response.ResourcePolicy),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
return {
secretArn: described.ARN,
secretName: described.Name,
versionId: Object.entries(described.VersionIdsToStages ?? {}).find(([, stages]) =>
stages?.includes("AWSCURRENT"),
)?.[0],
description: described.Description,
kmsKeyId: described.KmsKeyId,
tags: toTagRecord(described.Tags),
resourcePolicy: policy === undefined ? undefined : normalizePolicyDocument(policy),
};
});
const readSecret = Effect.fn(function* (secretId: string) {
const described = yield* secretsmanager
.describeSecret({
SecretId: secretId,
})
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
// A secret with `DeletedDate` set is scheduled for deletion (our
// delete uses `ForceDeleteWithoutRecovery`, which still completes
// asynchronously). It cannot be updated, so treat it as missing —
// reconcile recreates it once the pending deletion finishes.
return described?.DeletedDate ? undefined : described;
});
// `CreateSecret` may return before `DescribeSecret` can observe the new
// secret. Keep this wait provider-local so every caller (including nuke
// recovery and adoption) gets the same bounded consistency handling.
const readSecretAfterCreate = (secretId: string) =>
Effect.retry(
readSecret(secretId).pipe(
Effect.flatMap((secret) =>
secret?.ARN && secret.Name
? Effect.succeed(secret)
: Effect.fail(new SecretNotVisible({ secretId })),
),
),
{
while: (error) => error._tag === "SecretNotVisible",
schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
},
);
// A secret deleted with a recovery window keeps its name until the
// window ends, so re-adding the same `Secret` must bring it back rather
// than create a second one (`CreateSecret` would be refused). Only
// applies when the caller opted into a recovery window; the default
// force-deletion path keeps its create-through-the-window retry. A
// pending secret without this resource's ownership tags belongs to
// someone else and is never restored.
const restoreIfPendingDeletion = Effect.fn(function* (id: string, secretId: string) {
const described = yield* secretsmanager
.describeSecret({ SecretId: secretId })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
if (!described?.DeletedDate) {
return;
}
if (!(yield* hasAlchemyTags(id, toTagRecord(described.Tags)))) {
return yield* new OwnedBySomeoneElse({
message: `Secret '${secretId}' is scheduled for deletion and was not created by this resource, so it was not restored. Restore or delete it in Secrets Manager, or choose another name.`,
resourceType: Secret.Type,
logicalId: id,
physicalName: secretId,
});
}
yield* secretsmanager.restoreSecret({ SecretId: secretId });
});
// Force deletion is asynchronous. `DeletedDate` means the operation was
// accepted, not that the resource is absent, so deletion completion must
// be checked with the raw API rather than `readSecret`.
const waitForSecretAbsence = (secretId: string) =>
Effect.retry(
secretsmanager
.describeSecret({ SecretId: secretId })
.pipe(Effect.flatMap(() => Effect.fail(new SecretStillExists({ secretId })))),
{
while: (error) => error._tag === "SecretStillExists",
schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
},
).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
return {
stables: ["secretArn", "secretName"],
diff: Effect.fn(function* ({ id, olds, news }) {
if (!isResolved(news)) return undefined;
if ((yield* toSecretName(id, olds ?? {})) !== (yield* toSecretName(id, news ?? {}))) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const secretName = output?.secretName ?? (yield* toSecretName(id, olds ?? {}));
const described = yield* readSecret(output?.secretArn ?? secretName);
if (!described?.ARN || !described.Name) {
return undefined;
}
return yield* observeSecretAttributes({
...described,
ARN: described.ARN,
Name: described.Name,
});
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
yield* validateRecoveryWindow(news.recoveryWindowInDays);
const secretName = output?.secretName ?? (yield* toSecretName(id, news));
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...news.tags };
const hasNewValue =
news.secretString !== undefined ||
news.secretBinary !== undefined ||
news.generateSecretString !== undefined;
// Observe — describe the secret using whichever identifier we
// have (ARN preferred, name as fallback).
let observed = yield* readSecret(output?.secretArn ?? secretName);
// Ensure — create if missing. Tolerate `ResourceExistsException`
// by re-describing; the sync step below converges metadata and
// value. Recreating a physical name right after our own
// `ForceDeleteWithoutRecovery` can race the asynchronous deletion
// and fail with `InvalidRequestException` ("already scheduled for
// deletion") — force deletions complete within seconds, so retry
// through that window (bounded).
if (!observed?.ARN && news.recoveryWindowInDays !== undefined) {
yield* restoreIfPendingDeletion(id, secretName);
observed = yield* readSecret(secretName);
}
if (!observed?.ARN) {
// Data-FIRST `Effect.retry(self, options)`: the data-last form
// infers `Retry.Options<E>`'s `E` from BOTH `while` and the
// schedule's input slot (`unknown` for `Schedule.fixed`), and the
// unioned candidates collapse this provider's layer to an
// `unknown` R that then poisons all of `AWS.providers()`.
yield* retryThroughDeletionWindow(
secretsmanager
.createSecret({
Name: secretName,
Description: news.description,
KmsKeyId: news.kmsKeyId,
Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
Key,
Value,
})),
...(yield* createValue(news)),
})
.pipe(Effect.catchTag("ResourceExistsException", () => Effect.void)),
);
observed = yield* readSecretAfterCreate(secretName);
}
if (!observed?.ARN || !observed.Name) {
return yield* new SecretUnexpectedResponse({
message: `Failed to describe Secret '${secretName}'`,
});
}
const secretArn = observed.ARN;
// Sync metadata + value. `updateSecret` accepts description,
// KMS key, and the secret value in one call. We always send
// metadata (idempotent) and only send a new value if the user
// provided one — `updateSecret` requires SecretString or
// SecretBinary to actually rotate, but is fine to call without
// them to update description/kmsKeyId only.
const valuePayload = yield* createValue(news);
const updated = yield* secretsmanager.updateSecret({
SecretId: secretArn,
Description: news.description,
KmsKeyId: news.kmsKeyId,
...valuePayload,
});
// Sync tags — diff observed cloud tags against desired.
const observedTags = toTagRecord(observed.Tags);
const { removed, upsert } = diffTags(observedTags, desiredTags);
if (upsert.length > 0) {
yield* secretsmanager.tagResource({
SecretId: secretArn,
Tags: upsert,
});
}
if (removed.length > 0) {
yield* secretsmanager.untagResource({
SecretId: secretArn,
TagKeys: removed,
});
}
// Sync the resource-based policy — diff the observed policy
// against the desired one (both canonicalized via
// `normalizePolicyDocument`) so a re-deploy of an equivalent
// document is a no-op API-wise.
const desiredPolicy =
news.resourcePolicy === undefined
? undefined
: typeof news.resourcePolicy === "string"
? news.resourcePolicy
: stringifyPolicyDocument(news.resourcePolicy);
const observedPolicy = yield* secretsmanager
.getResourcePolicy({ SecretId: secretArn })
.pipe(
Effect.map((response) => response.ResourcePolicy),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
if (desiredPolicy !== undefined) {
if (
observedPolicy === undefined ||
normalizePolicyDocument(observedPolicy) !== normalizePolicyDocument(desiredPolicy)
) {
yield* secretsmanager.putResourcePolicy({
SecretId: secretArn,
ResourcePolicy: desiredPolicy,
});
}
} else if (observedPolicy !== undefined) {
yield* secretsmanager
.deleteResourcePolicy({ SecretId: secretArn })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}
yield* session.note(secretArn);
// DescribeSecret lags writes (and a just-restored secret), so poll
// until it reflects the description written above.
const final = yield* secretsmanager.describeSecret({ SecretId: secretArn }).pipe(
Effect.retry({
while: (e) => e._tag === "ResourceNotFoundException",
schedule: Schedule.spaced("1 second"),
times: 10,
}),
Effect.repeat({
until: (described) =>
news.description === undefined || described.Description === news.description,
schedule: Schedule.spaced("1 second"),
times: 10,
}),
);
const attributes = yield* observeSecretAttributes({
...final,
ARN: secretArn,
Name: observed.Name,
});
return {
...attributes,
// DescribeSecret can lag a just-written value.
versionId: hasNewValue
? (updated.VersionId ?? attributes.versionId)
: attributes.versionId,
tags: desiredTags,
};
}),
delete: Effect.fn(function* ({ olds, output }) {
const recoveryWindowInDays = olds?.recoveryWindowInDays;
yield* secretsmanager
.deleteSecret({
SecretId: output.secretArn,
...(recoveryWindowInDays === undefined
? { ForceDeleteWithoutRecovery: true }
: { RecoveryWindowInDays: recoveryWindowInDays }),
})
.pipe(
Effect.catchTags({
ResourceNotFoundException: () => Effect.void,
InvalidRequestException: (error) =>
isDeletionInProgress(error.message) ? Effect.void : Effect.fail(error),
}),
);
// With a recovery window the secret intentionally stays visible to
// `DescribeSecret` (scheduled for deletion) until the window ends.
if (recoveryWindowInDays === undefined) {
yield* waitForSecretAbsence(output.secretArn);
}
}),
// `listSecrets` returns full secret metadata (ARN, name, description,
// KMS key, and tags) inline, so we hydrate the exact `read` Attributes
// shape directly — without fetching plaintext values via
// `getSecretValue`. `versionId` is per-value state not surfaced by the
// list API, so it is `undefined` (matching `read` when there is no
// prior output).
list: () =>
secretsmanager.listSecrets.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.SecretList ?? [])
.filter(
(
entry,
): entry is secretsmanager.SecretListEntry & {
ARN: string;
Name: string;
} => entry.ARN != null && entry.Name != null,
)
.map((entry) => ({
secretArn: entry.ARN,
secretName: entry.Name,
versionId: undefined,
description: entry.Description,
kmsKeyId: entry.KmsKeyId,
tags: toTagRecord(entry.Tags),
})),
),
),
),
};
}),
);