import type { RuntimeServices } from "@alchemy.run/cloudflare-runtime/core";
import * as secretsStore from "@distilled.cloud/cloudflare/secrets-store";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as ProviderLayer from "alchemy/Local/ProviderLayer";
import * as RpcProvider from "alchemy/Local/RpcProvider";
import * as Provider from "alchemy/Provider";
import { isResourceOfType, Resource } from "alchemy/Resource";
import * as Console from "effect/Console";
import * as Effect from "effect/Effect";
import * as HttpClient from "effect/http/HttpClient";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import { generateLocalId, LOCAL_PROVIDERS_URL, localRuntimeServices } from "../LocalRuntime.ts";
import type { Providers } from "../Providers.ts";
import { deleteLocalSecret, seedLocalSecret } from "./LocalSecretsStoreGateway.ts";
export type StoreSecretProps = {
/**
* The Secrets Store that owns this secret.
*/
store: {
storeId: string;
accountId: string;
};
/**
* The name of the secret within the store.
* If omitted, the resource's logical ID is used.
*/
name?: string;
/**
* The secret value. Treated as redacted and never logged.
* Changing it updates the secret in place, keeping its secret ID.
*/
value: Redacted.Redacted<string>;
/**
* Services allowed to reference this secret.
* @default ["workers"]
*/
scopes?: string[];
/**
* Optional free-form description.
*/
comment?: string;
};
export type Secret = Resource<
"Cloudflare.SecretsStore.Secret",
StoreSecretProps,
{
secretId: string;
secretName: string;
storeId: string;
accountId: string;
status: SecretStatus;
scopes: string[];
comment: string | undefined;
},
never,
Providers
>;
export const isSecret = (value: unknown): value is Secret =>
isResourceOfType(value, "Cloudflare.SecretsStore.Secret");
export type SecretStatus = "pending" | "active" | "deleted";
// Distilled widened generated string enums to open unions (`string & {}`); the
// API only ever returns the known variants, so narrow at the boundary.
const asSecretStatus = (status: string): SecretStatus => status as SecretStatus;
/**
* A single secret stored inside a Cloudflare Secrets Store.
*
* The secret value is treated as redacted and never logged. Changing
* `value`, `scopes`, or `comment` updates the secret in place (same
* secret ID); changing `name` or moving it to another store replaces it.
*
* ### Creating a Secret
* **Example:** Basic Secret
* ```typescript
* const store = yield* Cloudflare.SecretsStore.Store("MyStore");
* const apiKey = yield* Cloudflare.SecretsStore.Secret("ApiKey", {
* store,
* value: Redacted.make(process.env.API_KEY!),
* });
* ```
*
* ### Binding to a Worker
* **Example:** Reading a secret at runtime
* ```typescript
* const apiKey = yield* Cloudflare.SecretsStore.ReadSecret(ApiKey);
* // `apiKey` is itself an Effect that resolves to the secret value:
* const value = yield* apiKey;
* // Or call `.get()` explicitly:
* const value = yield* apiKey.get();
* ```
*
* @resource
* @product Secrets Store
* @category Storage & Databases
*/
export const Secret = Resource<Secret>("Cloudflare.SecretsStore.Secret");
export const SecretProviderLive = () =>
Provider.succeed(Secret, {
stables: ["secretId", "secretName", "storeId", "accountId"],
diff: Effect.fn(function* ({ id, olds = {} as any, news, output }) {
if (!isResolved(news)) return undefined;
const oldStoreId = output?.storeId ?? olds.store?.storeId;
const newStoreId = news.store.storeId;
const oldName = output?.secretName ?? resolveName(id, olds.name);
const newName = resolveName(id, news.name);
if (oldStoreId !== newStoreId || oldName !== newName) {
return { action: "replace" } as const;
}
const oldValue = olds.value ? Redacted.value(olds.value) : undefined;
const newValue = Redacted.value(news.value);
if (oldValue !== newValue) {
return { action: "update" } as const;
}
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
const name = resolveName(id, news.name);
const scopes = resolveScopes(news.scopes);
const accountId = news.store.accountId;
const storeId = news.store.storeId;
// Observe — re-fetch the cached secret; fall back to a lookup
// by name so we recover from out-of-band deletes or partial
// state-persistence failures.
let observed:
| {
id: string;
name: string;
storeId: string;
status: string;
comment?: string | null;
}
| undefined;
if (output?.secretId) {
observed = yield* secretsStore
.getStoreSecret({
accountId: output.accountId,
storeId: output.storeId,
secretId: output.secretId,
})
.pipe(
Effect.catchTags({
SecretNotFound: () => Effect.undefined,
StoreNotFound: () => Effect.undefined,
}),
);
}
if (!observed) {
observed = yield* findSecretByName({ accountId, storeId, name }).pipe(
Effect.catchTag("StoreNotFound", () => Effect.undefined),
);
}
// Ensure — create if missing. Cloudflare reports a concurrent
// create as `SecretNameAlreadyExists`; tolerate by re-listing
// the store and adopting the secret with the same name. The
// value can't be read back from the API; we trust an
// identically-named secret reflects the same intent.
if (!observed) {
const created = yield* secretsStore
.createStoreSecret({
accountId,
storeId,
body: [
{
name,
scopes,
value: Redacted.value(news.value),
comment: news.comment,
},
],
})
.pipe(Effect.catchTag("SecretNameAlreadyExists", () => Effect.undefined));
if (created) {
const secret = created.result[0]!;
// Freshly created secrets report "pending" until Cloudflare
// activates them; a worker deploy that references a pending
// secret is rejected with "Secrets Store binding ... which
// were not found". Wait (bounded) for activation so
// downstream deploys in the same run see an active secret.
const status = yield* waitForSecretActive(
{ accountId, storeId, secretId: secret.id },
asSecretStatus(secret.status),
);
return {
secretId: secret.id,
secretName: secret.name,
storeId: secret.storeId,
accountId,
status,
scopes,
comment: secret.comment ?? undefined,
};
}
const existing = yield* findSecretByName({ accountId, storeId, name });
if (!existing) {
return yield* Effect.die(
new Error(
`Secret '${name}' reported as already existing in store ${storeId} but could not be found on lookup.`,
),
);
}
observed = existing;
}
const patched = yield* secretsStore.patchStoreSecret({
accountId,
storeId,
secretId: observed.id,
scopes,
comment: news.comment,
value: Redacted.value(news.value),
});
const status = yield* waitForSecretActive(
{ accountId, storeId, secretId: observed.id },
asSecretStatus(patched.status),
);
return {
secretId: observed.id,
secretName: observed.name,
storeId: observed.storeId,
accountId,
status,
scopes,
comment: patched.comment ?? undefined,
};
}),
delete: Effect.fn(function* ({ output }) {
yield* secretsStore
.deleteStoreSecret({
accountId: output.accountId,
storeId: output.storeId,
secretId: output.secretId,
})
.pipe(
Effect.tap(() => Effect.log(`deleted ${output.secretId}`)),
Effect.tapError(Console.log),
Effect.catchTags({
SecretNotFound: () => Effect.void,
StoreNotFound: () => Effect.void,
NotFound: () => Effect.void,
}),
);
}),
read: Effect.fn(function* ({ id, olds, output }) {
if (output?.secretId) {
return yield* secretsStore
.getStoreSecret({
accountId: output.accountId,
storeId: output.storeId,
secretId: output.secretId,
})
.pipe(
Effect.map((secret) => ({
secretId: secret.id,
secretName: secret.name,
storeId: secret.storeId,
accountId: output.accountId,
status: asSecretStatus(secret.status),
scopes: output.scopes,
comment: secret.comment ?? undefined,
})),
Effect.catchTags({
SecretNotFound: () => Effect.undefined,
StoreNotFound: () => Effect.undefined,
}),
);
}
// An interrupted first deploy can persist `creating` props whose
// parent Outputs were stripped to holes (see stripUnresolved), so
// `olds.store` can survive as `{}`. Treat an unresolved parent
// reference like a missing one — the plan falls through to the
// create path instead of handing `undefined` to the API (#995).
if (!olds?.store?.storeId || !olds.store.accountId) return undefined;
const name = resolveName(id, olds.name);
const match = yield* findSecretByName({
accountId: olds.store.accountId,
storeId: olds.store.storeId,
name,
}).pipe(Effect.catchTag("StoreNotFound", () => Effect.undefined));
if (!match) return undefined;
// Secrets carry no ownership signal (Cloudflare doesn't expose
// tags on store secrets), so a name match is not proof we own
// it. Brand it `Unowned` so the engine surfaces
// `OwnedBySomeoneElse` unless the caller opted in via `--adopt`.
return Unowned({
secretId: match.id,
secretName: match.name,
storeId: match.storeId,
accountId: olds.store.accountId,
status: asSecretStatus(match.status),
scopes: resolveScopes(olds.scopes),
comment: match.comment ?? undefined,
});
}),
// Parent fan-out: secrets are sub-resources keyed by {accountId,
// storeId} and there is no account-wide secret enumeration API.
// Enumerate every Secrets Store in the account, then list the
// secrets inside each store with bounded concurrency, paginating
// both levels exhaustively. The secret value is write-only and is
// never returned by the API — matching `read`, it is omitted.
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const stores = yield* secretsStore.listStores.pages({ accountId }).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.result ?? [])),
);
const rows = yield* Effect.forEach(
stores,
(store) =>
secretsStore.listStoreSecrets.pages({ accountId, storeId: store.id }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? []).map((secret) => ({
secretId: secret.id,
secretName: secret.name,
storeId: secret.storeId,
accountId,
status: asSecretStatus(secret.status),
scopes: resolveScopes(secret.scopes ?? undefined),
comment: secret.comment ?? undefined,
})),
),
),
// A store deleted out-of-band between enumeration and
// listing its secrets surfaces as StoreNotFound — skip it.
Effect.catchTag("StoreNotFound", () =>
Effect.succeed([] as ReadonlyArray<Secret["Attributes"]>),
),
),
{ concurrency: 10 },
);
return rows.flat();
}),
});
/**
* Local (dev) provider — the secret's identity is virtual (a `dev:` id) but
* its VALUE is real: reconcile seeds it into the local workerd Secrets
* Store simulator (through the `SecretsStore.admin` gateway, see
* `LocalSecretsStoreGateway.ts`) so a dev worker's `env.SECRET.get()`
* returns it, and delete removes the key again. Data lands in the same
* `.alchemy/local/secrets-store` directory the worker's lowered
* `secrets_store_secret` binding reads.
*
* RPC-backed: under `alchemy dev` (an `RpcProviderProxy` in context) the
* whole lifecycle runs in the Cloudflare sidecar process — where
* `localRuntimeServices()` is real and shared with the Worker/Queue/D1
* local providers — instead of in the user's process where that layer is
* gated empty (the class of bug behind #1007). In-process runs (no proxy:
* `sidecar: false` tests, a plain deploy deleting a local-mode row) build
* the provider directly with the un-gated runtime from the `dual`
* registration.
*/
export const SecretProviderLocal = () =>
RpcProvider.effect(
Secret,
LOCAL_PROVIDERS_URL,
Effect.gen(function* () {
// The local runtime services (workerd `Runtime`, binding plugins) and
// the HTTP client are resolved once at layer build and closed over —
// lifecycle effects run with the engine's call-time context, which
// doesn't include them.
const runtimeContext = yield* Effect.context<RuntimeServices | HttpClient.HttpClient>();
return {
stables: ["accountId"],
diff: Effect.fn(function* ({ id, olds, news, output }) {
if (!output?.secretId) return { action: "update" } as const;
if (!isResolved(news)) return undefined;
// Mirror the live provider's rules: a new store or name replaces
// the secret; a new value updates it in place (re-seed).
const oldStoreId = output.storeId;
const oldName = output.secretName;
const newName = resolveName(id, news.name);
if (oldStoreId !== news.store.storeId || oldName !== newName) {
return { action: "replace" } as const;
}
const oldValue = olds?.value ? Redacted.value(olds.value) : undefined;
if (oldValue !== Redacted.value(news.value)) {
return { action: "update" } as const;
}
// Fall through to the engine's default prop diff (scopes/comment
// changes update in place).
}),
read: Effect.fn(function* ({ output }) {
// Virtual identity — the persisted state row is the source of
// truth (the seeded value converges on every reconcile).
return output ?? undefined;
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
const name = resolveName(id, news.name);
const storeId = news.store.storeId;
// Seed — write the value into the local simulator so the dev
// worker's `env.<binding>.get()` returns it. An overwrite is
// idempotent, so re-running after a crash converges.
yield* seedLocalSecret(storeId, name, Redacted.value(news.value)).pipe(
Effect.provideContext(runtimeContext),
);
return {
secretId: output?.secretId ?? generateLocalId(),
secretName: name,
storeId,
accountId: news.store.accountId,
status: "active" as const,
scopes: resolveScopes(news.scopes),
comment: news.comment,
};
}),
delete: Effect.fn(function* ({ output }) {
// Remove the seeded value (idempotent — deleting a missing key is
// a no-op). A create-first replacement's old generation deletes a
// different key than its successor seeded, so this never races.
yield* deleteLocalSecret(output.storeId, output.secretName).pipe(
Effect.provideContext(runtimeContext),
);
}),
};
}),
);
export const StoreSecretProvider = () =>
ProviderLayer.dual(Secret, {
// The local provider's reconcile/delete boot an ephemeral workerd
// gateway to seed the simulator, so it needs the shared local runtime
// layer. Under `alchemy dev` the provider is an RPC stub (this gated
// layer is empty and unused) and the provider group (`../Local.ts`)
// supplies the real runtime; without the proxy the provider builds
// in-process and this layer is real.
local: () => SecretProviderLocal().pipe(Layer.provide(localRuntimeServices())),
live: () => SecretProviderLive(),
});
/**
* Poll a secret until Cloudflare reports it "active" (bounded at
* ~10s). Returns the last observed status rather than failing on
* timeout — consumers that bind the secret retry the
* `SecretsStoreBindingNotFound` deploy rejection themselves, so a
* slow activation degrades to a retried deploy instead of a hard
* error here.
*/
/** @internal Wait (bounded) for a freshly created secret to become active. */
export const waitForSecretActive = (
key: { accountId: string; storeId: string; secretId: string },
initialStatus: SecretStatus,
) =>
initialStatus === "active"
? Effect.succeed<SecretStatus>("active")
: secretsStore.getStoreSecret(key).pipe(
Effect.map((s) => asSecretStatus(s.status)),
Effect.repeat({
schedule: Schedule.spaced("500 millis"),
until: (status) => status === "active",
times: 20,
}),
// The secret was observed moments ago; a NotFound here is a
// read-replica lag blip, not a deletion. Report the last known
// status and let the deploy-side retry take over.
Effect.catchTags({
SecretNotFound: () => Effect.succeed(initialStatus),
StoreNotFound: () => Effect.succeed(initialStatus),
}),
);
/**
* Find a store's secret by exact name. The store's default listing order
* is not stable across pages, so a scan of every page can skip a secret
* in a store with more than one page of them. The API's `search` filter
* (a match over name and comment) narrows the listing to a handful of
* candidates first, ordered by name so paging stays stable when the name
* is a substring of many others; the exact-name filter then picks the one.
*/
const findSecretByName = (key: { accountId: string; storeId: string; name: string }) =>
secretsStore.listStoreSecrets
.items({
accountId: key.accountId,
storeId: key.storeId,
search: key.name,
order: "name",
})
.pipe(
Stream.filter((s) => s.name === key.name),
Stream.runHead,
Effect.map(Option.getOrUndefined),
);
const resolveScopes = (scopes: string[] | undefined): string[] =>
scopes && scopes.length > 0 ? scopes : ["workers"];
const resolveName = (id: string, name: string | undefined): string => name ?? id;