The best way to control Claude Code, Codex and more from any computer or phone

main
ts 504 lines 19.1 KB
Raw
1 import type { RuntimeServices } from "@alchemy.run/cloudflare-runtime/core";
2 import * as secretsStore from "@distilled.cloud/cloudflare/secrets-store";
3 import { Unowned } from "alchemy/AdoptPolicy";
4 import { isResolved } from "alchemy/Diff";
5 import * as ProviderLayer from "alchemy/Local/ProviderLayer";
6 import * as RpcProvider from "alchemy/Local/RpcProvider";
7 import * as Provider from "alchemy/Provider";
8 import { isResourceOfType, Resource } from "alchemy/Resource";
9 import * as Console from "effect/Console";
10 import * as Effect from "effect/Effect";
11 import * as HttpClient from "effect/http/HttpClient";
12 import * as Layer from "effect/Layer";
13 import * as Option from "effect/Option";
14 import * as Redacted from "effect/Redacted";
15 import * as Schedule from "effect/Schedule";
16 import * as Stream from "effect/Stream";
17 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
18 import { generateLocalId, LOCAL_PROVIDERS_URL, localRuntimeServices } from "../LocalRuntime.ts";
19 import type { Providers } from "../Providers.ts";
20 import { deleteLocalSecret, seedLocalSecret } from "./LocalSecretsStoreGateway.ts";
21
22 export type StoreSecretProps = {
23 /**
24 * The Secrets Store that owns this secret.
25 */
26 store: {
27 storeId: string;
28 accountId: string;
29 };
30 /**
31 * The name of the secret within the store.
32 * If omitted, the resource's logical ID is used.
33 */
34 name?: string;
35 /**
36 * The secret value. Treated as redacted and never logged.
37 * Changing it updates the secret in place, keeping its secret ID.
38 */
39 value: Redacted.Redacted<string>;
40 /**
41 * Services allowed to reference this secret.
42 * @default ["workers"]
43 */
44 scopes?: string[];
45 /**
46 * Optional free-form description.
47 */
48 comment?: string;
49 };
50
51 export type Secret = Resource<
52 "Cloudflare.SecretsStore.Secret",
53 StoreSecretProps,
54 {
55 secretId: string;
56 secretName: string;
57 storeId: string;
58 accountId: string;
59 status: SecretStatus;
60 scopes: string[];
61 comment: string | undefined;
62 },
63 never,
64 Providers
65 >;
66
67 export const isSecret = (value: unknown): value is Secret =>
68 isResourceOfType(value, "Cloudflare.SecretsStore.Secret");
69
70 export type SecretStatus = "pending" | "active" | "deleted";
71
72 // Distilled widened generated string enums to open unions (`string & {}`); the
73 // API only ever returns the known variants, so narrow at the boundary.
74 const asSecretStatus = (status: string): SecretStatus => status as SecretStatus;
75
76 /**
77 * A single secret stored inside a Cloudflare Secrets Store.
78 *
79 * The secret value is treated as redacted and never logged. Changing
80 * `value`, `scopes`, or `comment` updates the secret in place (same
81 * secret ID); changing `name` or moving it to another store replaces it.
82 *
83 * ### Creating a Secret
84 * **Example:** Basic Secret
85 * ```typescript
86 * const store = yield* Cloudflare.SecretsStore.Store("MyStore");
87 * const apiKey = yield* Cloudflare.SecretsStore.Secret("ApiKey", {
88 * store,
89 * value: Redacted.make(process.env.API_KEY!),
90 * });
91 * ```
92 *
93 * ### Binding to a Worker
94 * **Example:** Reading a secret at runtime
95 * ```typescript
96 * const apiKey = yield* Cloudflare.SecretsStore.ReadSecret(ApiKey);
97 * // `apiKey` is itself an Effect that resolves to the secret value:
98 * const value = yield* apiKey;
99 * // Or call `.get()` explicitly:
100 * const value = yield* apiKey.get();
101 * ```
102 *
103 * @resource
104 * @product Secrets Store
105 * @category Storage & Databases
106 */
107 export const Secret = Resource<Secret>("Cloudflare.SecretsStore.Secret");
108
109 export const SecretProviderLive = () =>
110 Provider.succeed(Secret, {
111 stables: ["secretId", "secretName", "storeId", "accountId"],
112 diff: Effect.fn(function* ({ id, olds = {} as any, news, output }) {
113 if (!isResolved(news)) return undefined;
114 const oldStoreId = output?.storeId ?? olds.store?.storeId;
115 const newStoreId = news.store.storeId;
116 const oldName = output?.secretName ?? resolveName(id, olds.name);
117 const newName = resolveName(id, news.name);
118 if (oldStoreId !== newStoreId || oldName !== newName) {
119 return { action: "replace" } as const;
120 }
121 const oldValue = olds.value ? Redacted.value(olds.value) : undefined;
122 const newValue = Redacted.value(news.value);
123 if (oldValue !== newValue) {
124 return { action: "update" } as const;
125 }
126 }),
127 reconcile: Effect.fn(function* ({ id, news, output }) {
128 const name = resolveName(id, news.name);
129 const scopes = resolveScopes(news.scopes);
130 const accountId = news.store.accountId;
131 const storeId = news.store.storeId;
132
133 // Observe — re-fetch the cached secret; fall back to a lookup
134 // by name so we recover from out-of-band deletes or partial
135 // state-persistence failures.
136 let observed:
137 | {
138 id: string;
139 name: string;
140 storeId: string;
141 status: string;
142 comment?: string | null;
143 }
144 | undefined;
145 if (output?.secretId) {
146 observed = yield* secretsStore
147 .getStoreSecret({
148 accountId: output.accountId,
149 storeId: output.storeId,
150 secretId: output.secretId,
151 })
152 .pipe(
153 Effect.catchTags({
154 SecretNotFound: () => Effect.undefined,
155 StoreNotFound: () => Effect.undefined,
156 }),
157 );
158 }
159 if (!observed) {
160 observed = yield* findSecretByName({ accountId, storeId, name }).pipe(
161 Effect.catchTag("StoreNotFound", () => Effect.undefined),
162 );
163 }
164
165 // Ensure — create if missing. Cloudflare reports a concurrent
166 // create as `SecretNameAlreadyExists`; tolerate by re-listing
167 // the store and adopting the secret with the same name. The
168 // value can't be read back from the API; we trust an
169 // identically-named secret reflects the same intent.
170 if (!observed) {
171 const created = yield* secretsStore
172 .createStoreSecret({
173 accountId,
174 storeId,
175 body: [
176 {
177 name,
178 scopes,
179 value: Redacted.value(news.value),
180 comment: news.comment,
181 },
182 ],
183 })
184 .pipe(Effect.catchTag("SecretNameAlreadyExists", () => Effect.undefined));
185 if (created) {
186 const secret = created.result[0]!;
187 // Freshly created secrets report "pending" until Cloudflare
188 // activates them; a worker deploy that references a pending
189 // secret is rejected with "Secrets Store binding ... which
190 // were not found". Wait (bounded) for activation so
191 // downstream deploys in the same run see an active secret.
192 const status = yield* waitForSecretActive(
193 { accountId, storeId, secretId: secret.id },
194 asSecretStatus(secret.status),
195 );
196 return {
197 secretId: secret.id,
198 secretName: secret.name,
199 storeId: secret.storeId,
200 accountId,
201 status,
202 scopes,
203 comment: secret.comment ?? undefined,
204 };
205 }
206 const existing = yield* findSecretByName({ accountId, storeId, name });
207 if (!existing) {
208 return yield* Effect.die(
209 new Error(
210 `Secret '${name}' reported as already existing in store ${storeId} but could not be found on lookup.`,
211 ),
212 );
213 }
214 observed = existing;
215 }
216
217 const patched = yield* secretsStore.patchStoreSecret({
218 accountId,
219 storeId,
220 secretId: observed.id,
221 scopes,
222 comment: news.comment,
223 value: Redacted.value(news.value),
224 });
225 const status = yield* waitForSecretActive(
226 { accountId, storeId, secretId: observed.id },
227 asSecretStatus(patched.status),
228 );
229 return {
230 secretId: observed.id,
231 secretName: observed.name,
232 storeId: observed.storeId,
233 accountId,
234 status,
235 scopes,
236 comment: patched.comment ?? undefined,
237 };
238 }),
239 delete: Effect.fn(function* ({ output }) {
240 yield* secretsStore
241 .deleteStoreSecret({
242 accountId: output.accountId,
243 storeId: output.storeId,
244 secretId: output.secretId,
245 })
246 .pipe(
247 Effect.tap(() => Effect.log(`deleted ${output.secretId}`)),
248 Effect.tapError(Console.log),
249 Effect.catchTags({
250 SecretNotFound: () => Effect.void,
251 StoreNotFound: () => Effect.void,
252 NotFound: () => Effect.void,
253 }),
254 );
255 }),
256 read: Effect.fn(function* ({ id, olds, output }) {
257 if (output?.secretId) {
258 return yield* secretsStore
259 .getStoreSecret({
260 accountId: output.accountId,
261 storeId: output.storeId,
262 secretId: output.secretId,
263 })
264 .pipe(
265 Effect.map((secret) => ({
266 secretId: secret.id,
267 secretName: secret.name,
268 storeId: secret.storeId,
269 accountId: output.accountId,
270 status: asSecretStatus(secret.status),
271 scopes: output.scopes,
272 comment: secret.comment ?? undefined,
273 })),
274 Effect.catchTags({
275 SecretNotFound: () => Effect.undefined,
276 StoreNotFound: () => Effect.undefined,
277 }),
278 );
279 }
280 // An interrupted first deploy can persist `creating` props whose
281 // parent Outputs were stripped to holes (see stripUnresolved), so
282 // `olds.store` can survive as `{}`. Treat an unresolved parent
283 // reference like a missing one — the plan falls through to the
284 // create path instead of handing `undefined` to the API (#995).
285 if (!olds?.store?.storeId || !olds.store.accountId) return undefined;
286 const name = resolveName(id, olds.name);
287 const match = yield* findSecretByName({
288 accountId: olds.store.accountId,
289 storeId: olds.store.storeId,
290 name,
291 }).pipe(Effect.catchTag("StoreNotFound", () => Effect.undefined));
292 if (!match) return undefined;
293 // Secrets carry no ownership signal (Cloudflare doesn't expose
294 // tags on store secrets), so a name match is not proof we own
295 // it. Brand it `Unowned` so the engine surfaces
296 // `OwnedBySomeoneElse` unless the caller opted in via `--adopt`.
297 return Unowned({
298 secretId: match.id,
299 secretName: match.name,
300 storeId: match.storeId,
301 accountId: olds.store.accountId,
302 status: asSecretStatus(match.status),
303 scopes: resolveScopes(olds.scopes),
304 comment: match.comment ?? undefined,
305 });
306 }),
307 // Parent fan-out: secrets are sub-resources keyed by {accountId,
308 // storeId} and there is no account-wide secret enumeration API.
309 // Enumerate every Secrets Store in the account, then list the
310 // secrets inside each store with bounded concurrency, paginating
311 // both levels exhaustively. The secret value is write-only and is
312 // never returned by the API — matching `read`, it is omitted.
313 list: Effect.fn(function* () {
314 const { accountId } = yield* yield* CloudflareEnvironment;
315 const stores = yield* secretsStore.listStores.pages({ accountId }).pipe(
316 Stream.runCollect,
317 Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.result ?? [])),
318 );
319 const rows = yield* Effect.forEach(
320 stores,
321 (store) =>
322 secretsStore.listStoreSecrets.pages({ accountId, storeId: store.id }).pipe(
323 Stream.runCollect,
324 Effect.map((chunk) =>
325 Array.from(chunk).flatMap((page) =>
326 (page.result ?? []).map((secret) => ({
327 secretId: secret.id,
328 secretName: secret.name,
329 storeId: secret.storeId,
330 accountId,
331 status: asSecretStatus(secret.status),
332 scopes: resolveScopes(secret.scopes ?? undefined),
333 comment: secret.comment ?? undefined,
334 })),
335 ),
336 ),
337 // A store deleted out-of-band between enumeration and
338 // listing its secrets surfaces as StoreNotFound — skip it.
339 Effect.catchTag("StoreNotFound", () =>
340 Effect.succeed([] as ReadonlyArray<Secret["Attributes"]>),
341 ),
342 ),
343 { concurrency: 10 },
344 );
345 return rows.flat();
346 }),
347 });
348
349 /**
350 * Local (dev) provider — the secret's identity is virtual (a `dev:` id) but
351 * its VALUE is real: reconcile seeds it into the local workerd Secrets
352 * Store simulator (through the `SecretsStore.admin` gateway, see
353 * `LocalSecretsStoreGateway.ts`) so a dev worker's `env.SECRET.get()`
354 * returns it, and delete removes the key again. Data lands in the same
355 * `.alchemy/local/secrets-store` directory the worker's lowered
356 * `secrets_store_secret` binding reads.
357 *
358 * RPC-backed: under `alchemy dev` (an `RpcProviderProxy` in context) the
359 * whole lifecycle runs in the Cloudflare sidecar process — where
360 * `localRuntimeServices()` is real and shared with the Worker/Queue/D1
361 * local providers — instead of in the user's process where that layer is
362 * gated empty (the class of bug behind #1007). In-process runs (no proxy:
363 * `sidecar: false` tests, a plain deploy deleting a local-mode row) build
364 * the provider directly with the un-gated runtime from the `dual`
365 * registration.
366 */
367 export const SecretProviderLocal = () =>
368 RpcProvider.effect(
369 Secret,
370 LOCAL_PROVIDERS_URL,
371 Effect.gen(function* () {
372 // The local runtime services (workerd `Runtime`, binding plugins) and
373 // the HTTP client are resolved once at layer build and closed over —
374 // lifecycle effects run with the engine's call-time context, which
375 // doesn't include them.
376 const runtimeContext = yield* Effect.context<RuntimeServices | HttpClient.HttpClient>();
377
378 return {
379 stables: ["accountId"],
380 diff: Effect.fn(function* ({ id, olds, news, output }) {
381 if (!output?.secretId) return { action: "update" } as const;
382 if (!isResolved(news)) return undefined;
383 // Mirror the live provider's rules: a new store or name replaces
384 // the secret; a new value updates it in place (re-seed).
385 const oldStoreId = output.storeId;
386 const oldName = output.secretName;
387 const newName = resolveName(id, news.name);
388 if (oldStoreId !== news.store.storeId || oldName !== newName) {
389 return { action: "replace" } as const;
390 }
391 const oldValue = olds?.value ? Redacted.value(olds.value) : undefined;
392 if (oldValue !== Redacted.value(news.value)) {
393 return { action: "update" } as const;
394 }
395 // Fall through to the engine's default prop diff (scopes/comment
396 // changes update in place).
397 }),
398 read: Effect.fn(function* ({ output }) {
399 // Virtual identity — the persisted state row is the source of
400 // truth (the seeded value converges on every reconcile).
401 return output ?? undefined;
402 }),
403 reconcile: Effect.fn(function* ({ id, news, output }) {
404 const name = resolveName(id, news.name);
405 const storeId = news.store.storeId;
406
407 // Seed — write the value into the local simulator so the dev
408 // worker's `env.<binding>.get()` returns it. An overwrite is
409 // idempotent, so re-running after a crash converges.
410 yield* seedLocalSecret(storeId, name, Redacted.value(news.value)).pipe(
411 Effect.provideContext(runtimeContext),
412 );
413
414 return {
415 secretId: output?.secretId ?? generateLocalId(),
416 secretName: name,
417 storeId,
418 accountId: news.store.accountId,
419 status: "active" as const,
420 scopes: resolveScopes(news.scopes),
421 comment: news.comment,
422 };
423 }),
424 delete: Effect.fn(function* ({ output }) {
425 // Remove the seeded value (idempotent — deleting a missing key is
426 // a no-op). A create-first replacement's old generation deletes a
427 // different key than its successor seeded, so this never races.
428 yield* deleteLocalSecret(output.storeId, output.secretName).pipe(
429 Effect.provideContext(runtimeContext),
430 );
431 }),
432 };
433 }),
434 );
435
436 export const StoreSecretProvider = () =>
437 ProviderLayer.dual(Secret, {
438 // The local provider's reconcile/delete boot an ephemeral workerd
439 // gateway to seed the simulator, so it needs the shared local runtime
440 // layer. Under `alchemy dev` the provider is an RPC stub (this gated
441 // layer is empty and unused) and the provider group (`../Local.ts`)
442 // supplies the real runtime; without the proxy the provider builds
443 // in-process and this layer is real.
444 local: () => SecretProviderLocal().pipe(Layer.provide(localRuntimeServices())),
445 live: () => SecretProviderLive(),
446 });
447
448 /**
449 * Poll a secret until Cloudflare reports it "active" (bounded at
450 * ~10s). Returns the last observed status rather than failing on
451 * timeout — consumers that bind the secret retry the
452 * `SecretsStoreBindingNotFound` deploy rejection themselves, so a
453 * slow activation degrades to a retried deploy instead of a hard
454 * error here.
455 */
456 /** @internal Wait (bounded) for a freshly created secret to become active. */
457 export const waitForSecretActive = (
458 key: { accountId: string; storeId: string; secretId: string },
459 initialStatus: SecretStatus,
460 ) =>
461 initialStatus === "active"
462 ? Effect.succeed<SecretStatus>("active")
463 : secretsStore.getStoreSecret(key).pipe(
464 Effect.map((s) => asSecretStatus(s.status)),
465 Effect.repeat({
466 schedule: Schedule.spaced("500 millis"),
467 until: (status) => status === "active",
468 times: 20,
469 }),
470 // The secret was observed moments ago; a NotFound here is a
471 // read-replica lag blip, not a deletion. Report the last known
472 // status and let the deploy-side retry take over.
473 Effect.catchTags({
474 SecretNotFound: () => Effect.succeed(initialStatus),
475 StoreNotFound: () => Effect.succeed(initialStatus),
476 }),
477 );
478
479 /**
480 * Find a store's secret by exact name. The store's default listing order
481 * is not stable across pages, so a scan of every page can skip a secret
482 * in a store with more than one page of them. The API's `search` filter
483 * (a match over name and comment) narrows the listing to a handful of
484 * candidates first, ordered by name so paging stays stable when the name
485 * is a substring of many others; the exact-name filter then picks the one.
486 */
487 const findSecretByName = (key: { accountId: string; storeId: string; name: string }) =>
488 secretsStore.listStoreSecrets
489 .items({
490 accountId: key.accountId,
491 storeId: key.storeId,
492 search: key.name,
493 order: "name",
494 })
495 .pipe(
496 Stream.filter((s) => s.name === key.name),
497 Stream.runHead,
498 Effect.map(Option.getOrUndefined),
499 );
500
501 const resolveScopes = (scopes: string[] | undefined): string[] =>
502 scopes && scopes.length > 0 ? scopes : ["workers"];
503
504 const resolveName = (id: string, name: string | undefined): string => name ?? id;