@pithy-sh/cloudflare 0.3.1 → 0.4.0

package/dist/client/errors.d.ts

@@ -68,7 +68,7 @@ export interface CloudflareApiError {
     documentationUrl?: string;
 }
 /**
- * Run a Cloudflare SDK call and turn any failure into a `CloudflareRequestError`, preserving the
+ * Run a Cloudflare SDK call and turn any failure into a typed refusal, preserving the
  * original error as `cause` and its message as internal `detail`. `operation` names the call for
  * the audit trail (`"KV get for key 'x'"`). A `PithyError` already in flight (e.g. a
  * not-configured guard) passes through untouched — only foreign throws get wrapped.
@@ -111,8 +111,11 @@ export declare function cloudflareRequest<T>(operation: string, fn: () => Promis
  * translating client can render them under the error code. "Add this grant, then re-run" names a
  * console the operator is sitting in front of, so it is an `action`. The raw body stays `detail`.
  *
- * The code stays `cloudflare/request_failed` at 502: a dedicated sibling of `core/upstream_failed`,
- * already the upstream class CLAUDE.md asks for, and pinned by `core`'s payload test.
+ * **The code is keyed on the status, because a retry policy reads it and nothing else can.** See
+ * {@link isTransientStatus}. A refusal Cloudflare answered with a 4xx stays `cloudflare/request_failed`
+ * at 502 — a dedicated sibling of `core/upstream_failed`, already the upstream class CLAUDE.md asks
+ * for, and pinned by `core`'s payload test. The words are composed the same way either side of that
+ * branch, so only the two machine-readable fields differ.
  *
  * **The message is one line, and that is a kit-wide rule this had to learn the hard way.** Round one
  * of #534 made it a small document — problem line, `errors[]` indented beneath, action last — which
@@ -143,7 +146,7 @@ export declare function cloudflareRefusal(args: {
     detail: string;
     /** The original throw. */
     cause?: unknown;
-}): CloudflareRequestError;
+}): PithyError;
 /**
  * Pithy's problem line with Cloudflare's own answer on the end of it, and the same answer as `params`.
  *

package/dist/client/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"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"}

package/dist/client/errors.js

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { PithyError, UpstreamTimeoutError } from "@pithy-sh/core/src/error/pithyError";
+import { PithyError, UpstreamError, UpstreamTimeoutError } from "@pithy-sh/core/src/error/pithyError";
 import { MAX_WORKFLOW_STEP_TEXT } from "@pithy-sh/core/src/workflow/stepMessage";
 //#region src/client/errors.ts
 /** A required piece of configuration (token, account id, resource id) is missing. */
@@ -144,7 +144,7 @@ const ACCOUNT_PERMISSIONS = {
 	workers: "Workers Scripts"
 };
 /**
-* Run a Cloudflare SDK call and turn any failure into a `CloudflareRequestError`, preserving the
+* Run a Cloudflare SDK call and turn any failure into a typed refusal, preserving the
 * original error as `cause` and its message as internal `detail`. `operation` names the call for
 * the audit trail (`"KV get for key 'x'"`). A `PithyError` already in flight (e.g. a
 * not-configured guard) passes through untouched — only foreign throws get wrapped.
@@ -204,8 +204,11 @@ async function cloudflareRequest(operation, fn, options) {
 * translating client can render them under the error code. "Add this grant, then re-run" names a
 * console the operator is sitting in front of, so it is an `action`. The raw body stays `detail`.
 *
-* The code stays `cloudflare/request_failed` at 502: a dedicated sibling of `core/upstream_failed`,
-* already the upstream class CLAUDE.md asks for, and pinned by `core`'s payload test.
+* **The code is keyed on the status, because a retry policy reads it and nothing else can.** See
+* {@link isTransientStatus}. A refusal Cloudflare answered with a 4xx stays `cloudflare/request_failed`
+* at 502 — a dedicated sibling of `core/upstream_failed`, already the upstream class CLAUDE.md asks
+* for, and pinned by `core`'s payload test. The words are composed the same way either side of that
+* branch, so only the two machine-readable fields differ.
 *
 * **The message is one line, and that is a kit-wide rule this had to learn the hard way.** Round one
 * of #534 made it a small document — problem line, `errors[]` indented beneath, action last — which
@@ -221,12 +224,78 @@ async function cloudflareRequest(operation, fn, options) {
 function cloudflareRefusal(args) {
 	const shown = args.apiErrors.slice(0, MAX_API_ERRORS);
 	const said = cloudflareSaid(args.problem, shown);
-	return new CloudflareRequestError({
+	const refusal = {
 		message: said.message,
 		action: permissionAction(shown, args.status, args.permission),
 		params: said.params,
 		detail: args.detail
-	}, { cause: args.cause });
+	};
+	if (isTransientStatus(args.status) || isConnectionFailure(args.cause)) return new UpstreamError(refusal, { cause: args.cause });
+	return new CloudflareRequestError(refusal, { cause: args.cause });
+}
+/**
+* Whether the status Cloudflare answered under means "ask again" rather than "this request is wrong".
+*
+* **The classification lives here because here is where the status is still in hand.** Everything a
+* refusal crosses afterwards — a durable step record, a `--json` line, a retry policy — sees the
+* `code` and nothing else, so a fault that is worth retrying has to say so in the code at the moment
+* it is raised. `@pithy-sh/secrets`' `secretsWorkflowRetry` lists `core/upstream_failed` and
+* `core/upstream_timeout` and treats everything absent as terminal; with every non-timeout failure
+* arriving as `cloudflare/request_failed`, a 503 on the at-rest master-key write ended the rotation
+* instance permanently, in the one state where ending it is expensive.
+*
+* **It is keyed here and not relaxed in the policy, and the difference is a revoked token.** Making
+* the whole `cloudflare/*` family retryable would loop a 403 forever at whatever cadence the Workflow
+* sleeps on, and nothing would ever say why. 4xx is Cloudflare answering and refusing — the same call
+* refuses again — so it stays terminal, and CLAUDE.md §Errors is what says the other half belongs to
+* the upstream pair: a failure in something we do not control is never a code that says we broke.
+*
+* 5xx is every server-side status, Cloudflare's own `52x` family included; `429` is rate limiting,
+* which is the transient failure by definition. The timeout statuses never reach here — `isTimeout`
+* claims 408, 504 and 524 first, and they are the 504 half of the same pair.
+*
+* **A statusless failure is not covered here, and deliberately so (#647 review).** A connection that reset
+* mid-write is genuinely transient and ending a rotation on one is expensive — but "carries no status" is
+* far wider than "the network faltered". A `TypeError` raised in our own request builder carries no status
+* either, and a predicate that called it transient would retry a code defect on the Workflow's own cadence,
+* forever, silently. `errors.test.ts` pins that: a throw that never reached Cloudflare stays terminal.
+* {@link isConnectionFailure} names the narrow case instead, the way {@link statesTimeout} already does.
+*/
+function isTransientStatus(status) {
+	return status !== void 0 && (status === 429 || status >= 500);
+}
+/**
+* The producer names for "the connection did not hold", as distinct from "out of time" and from a defect
+* in our own code.
+*
+* Duck-typed by name and `code`, for the reason {@link TIMEOUT_NAMES} gives: the SDK is one producer and
+* `fetch` is another, and an `instanceof` across two copies of the SDK answers false.
+*/
+const CONNECTION_NAMES = /* @__PURE__ */ new Set(["APIConnectionError", "FetchError"]);
+const CONNECTION_CODES = /* @__PURE__ */ new Set([
+	"ECONNRESET",
+	"ECONNREFUSED",
+	"ENOTFOUND",
+	"EAI_AGAIN",
+	"EPIPE",
+	"UND_ERR_SOCKET"
+]);
+/**
+* Whether a failure is a connection that did not hold — a reset, a refused socket, a name that would not
+* resolve. Cloudflare never answered, so nothing was refused, and the next attempt may well succeed.
+*
+* Narrow on purpose. This is the half of "no status" that is genuinely worth another attempt; everything
+* else with no status stays terminal, so a defect in our own code still stops rather than looping.
+*/
+function isConnectionFailure(error) {
+	let current = error;
+	for (let depth = 0; depth < 5 && current !== null && typeof current === "object"; depth++) {
+		const { name, code } = current;
+		if (typeof name === "string" && CONNECTION_NAMES.has(name)) return true;
+		if (typeof code === "string" && CONNECTION_CODES.has(code)) return true;
+		current = current.cause;
+	}
+	return false;
 }
 /**
 * Pithy's problem line with Cloudflare's own answer on the end of it, and the same answer as `params`.

package/dist/secrets/secretsStoreManager.d.ts

@@ -17,6 +17,7 @@ export declare const CfSecretEntry: z.ZodObject<{
     }>;
     created: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
     modified: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    comment: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type CfSecretEntry = z.output<typeof CfSecretEntry>;
 /** What {@link CloudflareSecretsStoreManager.createSecretIfAbsent} did — see it for each value. */
@@ -48,8 +49,17 @@ export declare class CloudflareSecretsStoreManager extends CloudflareManager {
      * update leaves the prior value intact and bound — there is no window where the secret is absent
      * from the store (which, for a secret like the master encryption key, is a platform-level outage).
      * Scopes are re-sent so an entry converges on the same shape whichever branch wrote it.
+     *
+     * **It upserts, and at a name nothing reads that is the whole problem.** A caller replacing a value
+     * that must already exist wants {@link updateExistingSecret}: here a stale or misspelled name finds
+     * nothing, creates an entry, and answers 200 — leaving live key material at an address no binding
+     * resolves while the value the caller meant to replace goes on being served. This one is for a
+     * caller that genuinely means either branch.
+     *
+     * `comment` is the non-secret text written beside the value, and the only thing about a value REST
+     * can read back. Omit it and whatever comment is on the entry is left exactly as it stands.
      */
-    putSecret(name: string, value: string): Promise<void>;
+    putSecret(name: string, value: string, comment?: string): Promise<void>;
     /**
      * Create a secret only if no entry of that name is there, and say what happened — never "somebody else did"
      * when this call cannot know that.
@@ -66,7 +76,35 @@ export declare class CloudflareSecretsStoreManager extends CloudflareManager {
      * if another is older this one is the loser and removes itself. The oldest wins, deterministically, whichever
      * run looks. A failure with no entry there afterwards — an outage, a refused token — is thrown as it came.
      */
-    createSecretIfAbsent(name: string, value: string): Promise<CreateSecretOutcome>;
+    createSecretIfAbsent(name: string, value: string, comment?: string): Promise<CreateSecretOutcome>;
+    /**
+     * Write a value to an entry that must already be there, refusing to create one.
+     *
+     * **The verb that exists because {@link putSecret} upserts.** A put addressed to a name nothing reads
+     * — a composed name gone stale, a misspelled binding, an environment segment that never got
+     * substituted — finds no entry, creates one, and answers 200. The caller hears success, the value it
+     * meant to replace is untouched and still bound, and an orphan entry nobody reads sits in the store
+     * holding live key material. That is how a sibling codebase lost an environment's secrets: the
+     * master-key envelope went to a name the `SECRETS_ENCRYPTION_KEYS` binding does not resolve, every
+     * row was re-encrypted under the new key, and the binding kept serving the old one. Nothing returned
+     * an error, anywhere.
+     *
+     * So the create branch is removed rather than guarded. A caller replacing a value has already
+     * asserted the entry exists — it is bound, something reads it — and where that assertion is false the
+     * honest answer is a refusal before any write, not a second entry. {@link createSecretIfAbsent}
+     * establishes a secret, this replaces one, and `putSecret` stays for a caller that means either.
+     *
+     * **Two live entries of one name is a refusal too, and the same one in spirit.** The oldest wins
+     * everywhere else here, which is right for a create that raced. It is wrong for a replace: editing
+     * one of two is a coin toss over which value the binding goes on serving. The store is ambiguous, so
+     * the caller is told, before anything is written.
+     *
+     * Name-addressed rather than id-addressed, deliberately: the name is what a caller composes and what
+     * a binding resolves, so addressing by it keeps the misaddressing this verb exists to catch inside
+     * the one thing that can catch it. Returns the entry id written, so a caller reading back afterwards
+     * can assert it is looking at the same address. `comment` is written beside the value when given.
+     */
+    updateExistingSecret(name: string, value: string, comment?: string): Promise<string>;
     /** Delete a secret by name. Resolves the id via `listSecrets`, then issues DELETE by id. */
     deleteSecret(name: string): Promise<void>;
     /**
@@ -89,6 +127,20 @@ export declare class CloudflareSecretsStoreManager extends CloudflareManager {
      * full set in one array. Each entry is Zod-validated (`CfSecretEntry`) at the wire boundary.
      */
     listSecrets(): Promise<CfSecretEntry[]>;
+    /**
+     * Every live entry carrying this name, oldest first.
+     *
+     * **The plural is the point.** Cloudflare does not document that the store refuses a duplicate name,
+     * and #643 established that it does not — so "the entry named X" is a claim rather than a given. A
+     * caller whose correctness depends on there being exactly one checks `length` here and says what it
+     * wants done when the store disagrees; {@link findByName} is the answer for a caller that only needs
+     * the entry the rest of this manager would act on.
+     *
+     * **A `deleted` entry is not one** (#643): Cloudflare lists a secret's lifecycle status as `pending`,
+     * `active` or `deleted` without saying what each means, and a deleted entry is the one reading that
+     * cannot be "there". `pending` is taken as there, since creating over it would duplicate it.
+     */
+    entriesNamed(name: string): Promise<CfSecretEntry[]>;
     /** Whether a secret with the given name currently exists in the store. */
     exists(name: string): Promise<boolean>;
     /** The store this manager targets and the account it lives in. */
@@ -99,10 +151,9 @@ export declare class CloudflareSecretsStoreManager extends CloudflareManager {
     /** Create a single secret with the default scopes, and return the id Cloudflare gave it when it says one. */
     private createSecret;
     /**
-     * The entry of this name, or `undefined`. **A `deleted` entry is not one** (#643): Cloudflare lists a secret's
-     * lifecycle status as `pending`, `active` or `deleted` without saying what each means, and a deleted entry is
-     * the one reading that cannot be "there". `pending` is taken as there, since creating over it would duplicate
-     * it. Of several entries of one name, the oldest, which is the one {@link createSecretIfAbsent} leaves standing.
+     * The entry of this name every verb here acts on, or `undefined`. Of several entries of one name, the
+     * oldest — which is the one {@link createSecretIfAbsent} leaves standing. See {@link entriesNamed} for
+     * why there can be several, and for what counts as being there at all.
      */
     private findByName;
 }

package/dist/secrets/secretsStoreManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secretsStoreManager.d.ts","sourceRoot":"","sources":["../../src/secrets/secretsStoreManager.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAKpF;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;iBAQqE,CAAC;AAChG,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,mGAAmG;AACnG,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AAOxE,gGAAgG;AAChG,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACxE,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,iBAAiB;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,YAAY,MAAM,EAAE,yBAAyB,EAM5C;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,iEAAiE;IAC3D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;;OAQG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1D;IAED;;;;;;;;;;;;;;;OAeG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAoBpF;IAED,4FAA4F;IACtF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc9C;IAED;;;;;;;;;;;;;OAaG;IACG,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1D;IAED;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAU5C;IAED,0EAA0E;IACpE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAED,kEAAkE;IAClE,mBAAmB,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAE5D;IAED,6GAA6G;YAC/F,YAAY;IAiB1B;;;;;OAKG;YACW,UAAU;CAIzB"}
+{"version":3,"file":"secretsStoreManager.d.ts","sourceRoot":"","sources":["../../src/secrets/secretsStoreManager.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAKpF;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;iBAeqE,CAAC;AAChG,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,mGAAmG;AACnG,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AA4BxE,gGAAgG;AAChG,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACxE,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,iBAAiB;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,YAAY,MAAM,EAAE,yBAAyB,EAM5C;IAED,cAAc,IAAI,MAAM,CAEvB;IAED,iEAAiE;IAC3D,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9C;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB5E;IAED;;;;;;;;;;;;;;;OAeG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmBtG;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BzF;IAED,4FAA4F;IACtF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc9C;IAED;;;;;;;;;;;;;OAaG;IACG,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1D;IAED;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAU5C;IAED;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAEzD;IAED,0EAA0E;IACpE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAED,kEAAkE;IAClE,mBAAmB,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAE5D;IAED,6GAA6G;YAC/F,YAAY;IAiB1B;;;;OAIG;YACW,UAAU;CAGzB"}

package/dist/secrets/secretsStoreManager.js

@@ -3,7 +3,7 @@
 import { CloudflareNotConfiguredError, cloudflareRequest, decodeResponse } from "../client/errors.js";
 import { CloudflareManager } from "../client/manager.js";
 import { z } from "zod";
-import { NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { ConflictError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
 import { JsonDate } from "@pithy-sh/core/src/data/codecs";
 //#region src/secrets/secretsStoreManager.ts
 /** Scopes attached to every secret we create. CF requires at least one; "workers" is the bind target. */
@@ -22,11 +22,31 @@ const CfSecretEntry = z.object({
 		"deleted"
 	]).describe("The secret's lifecycle status in the store."),
 	created: JsonDate.describe("When the secret was created (ISO string on the wire, Date in app)."),
-	modified: JsonDate.describe("When the secret was last modified (ISO string on the wire, Date in app).")
+	modified: JsonDate.describe("When the secret was last modified (ISO string on the wire, Date in app)."),
+	comment: z.string().nullable().optional().describe("Freeform text Cloudflare stores beside the value and returns on list and get. The one field of an entry a write sets and a read answers, so it is the only REST-readable fact *about* a value — never key material, and never a substitute for reading the value through its binding. Nullable **and** optional because the live API returns an explicit `null` for an entry nothing annotated, not an absent key: declared `.optional()` alone, every list against a store holding one un-annotated entry failed its own schema and threw `cloudflare/invalid_response`, which took `entriesNamed` and therefore the rotation's edit-only write with it. Found against a real store, not a mock (#647).")
 }).describe("A single Cloudflare Secrets Store secret's metadata (never its plaintext value).");
-/** The oldest of some entries by creation time, the smaller id breaking a tie — one answer whoever asks. */
-function oldestEntry(entries) {
-	return [...entries].sort((a, b) => a.created.getTime() - b.created.getTime() || a.id.localeCompare(b.id))[0];
+/** Oldest first, the smaller id breaking a tie — one order whoever asks, so two readers never disagree. */
+function byAge(a, b) {
+	return a.created.getTime() - b.created.getTime() || a.id.localeCompare(b.id);
+}
+/**
+* A `deleted` entry is not there (#643); a `pending` one is, since creating over it would duplicate it.
+* Cloudflare lists the three statuses without saying what each means, and a deleted entry is the one
+* reading that cannot be "there".
+*/
+function isLive(entry) {
+	return entry.status !== "deleted";
+}
+/**
+* The `comment` a write sends, or no such field at all when the caller passed none.
+*
+* Omitted rather than sent empty, so a write with no comment is byte-identical to what this manager
+* sent before the field existed — and so a caller that has nothing to say cannot blank an annotation
+* somebody else wrote. The comment is a plain string here on purpose: what belongs in one is
+* `@pithy-sh/secrets`' question, and the codec lives where it is read rather than where it is posted.
+*/
+function commentField(comment) {
+	return comment === void 0 ? {} : { comment };
 }
 /**
 * Out-of-Worker access to the account-level Cloudflare Secrets Store over the REST API: provisioning
@@ -63,18 +83,28 @@ var CloudflareSecretsStoreManager = class extends CloudflareManager {
 	* update leaves the prior value intact and bound — there is no window where the secret is absent
 	* from the store (which, for a secret like the master encryption key, is a platform-level outage).
 	* Scopes are re-sent so an entry converges on the same shape whichever branch wrote it.
+	*
+	* **It upserts, and at a name nothing reads that is the whole problem.** A caller replacing a value
+	* that must already exist wants {@link updateExistingSecret}: here a stale or misspelled name finds
+	* nothing, creates an entry, and answers 200 — leaving live key material at an address no binding
+	* resolves while the value the caller meant to replace goes on being served. This one is for a
+	* caller that genuinely means either branch.
+	*
+	* `comment` is the non-secret text written beside the value, and the only thing about a value REST
+	* can read back. Omit it and whatever comment is on the entry is left exactly as it stands.
 	*/
-	async putSecret(name, value) {
+	async putSecret(name, value, comment) {
 		const existing = await this.findByName(name);
 		if (!existing) {
-			await this.createSecret(name, value);
+			await this.createSecret(name, value, comment);
 			return;
 		}
 		await cloudflareRequest(`put secret ${name}`, () => this.getClient().secretsStore.stores.secrets.edit(existing.id, {
 			account_id: this.accountId,
 			store_id: this.storeId,
 			value,
-			scopes: [...DEFAULT_SCOPES]
+			scopes: [...DEFAULT_SCOPES],
+			...commentField(comment)
 		}));
 	}
 	/**
@@ -93,16 +123,16 @@ var CloudflareSecretsStoreManager = class extends CloudflareManager {
 	* if another is older this one is the loser and removes itself. The oldest wins, deterministically, whichever
 	* run looks. A failure with no entry there afterwards — an outage, a refused token — is thrown as it came.
 	*/
-	async createSecretIfAbsent(name, value) {
+	async createSecretIfAbsent(name, value, comment) {
 		if (await this.findByName(name)) return "present";
 		let ownId;
 		try {
-			ownId = await this.createSecret(name, value);
+			ownId = await this.createSecret(name, value, comment);
 		} catch (error) {
 			if (await this.findByName(name)) return "unconfirmed";
 			throw error;
 		}
-		const oldest = oldestEntry((await this.listSecrets()).filter((entry) => entry.name === name && entry.status !== "deleted"));
+		const oldest = (await this.entriesNamed(name))[0];
 		if (oldest === void 0 || ownId === void 0 || oldest.id === ownId) return "created";
 		await cloudflareRequest(`delete duplicate secret ${name}`, () => this.getClient().secretsStore.stores.secrets.delete(ownId, {
 			account_id: this.accountId,
@@ -110,6 +140,55 @@ var CloudflareSecretsStoreManager = class extends CloudflareManager {
 		}));
 		return "present";
 	}
+	/**
+	* Write a value to an entry that must already be there, refusing to create one.
+	*
+	* **The verb that exists because {@link putSecret} upserts.** A put addressed to a name nothing reads
+	* — a composed name gone stale, a misspelled binding, an environment segment that never got
+	* substituted — finds no entry, creates one, and answers 200. The caller hears success, the value it
+	* meant to replace is untouched and still bound, and an orphan entry nobody reads sits in the store
+	* holding live key material. That is how a sibling codebase lost an environment's secrets: the
+	* master-key envelope went to a name the `SECRETS_ENCRYPTION_KEYS` binding does not resolve, every
+	* row was re-encrypted under the new key, and the binding kept serving the old one. Nothing returned
+	* an error, anywhere.
+	*
+	* So the create branch is removed rather than guarded. A caller replacing a value has already
+	* asserted the entry exists — it is bound, something reads it — and where that assertion is false the
+	* honest answer is a refusal before any write, not a second entry. {@link createSecretIfAbsent}
+	* establishes a secret, this replaces one, and `putSecret` stays for a caller that means either.
+	*
+	* **Two live entries of one name is a refusal too, and the same one in spirit.** The oldest wins
+	* everywhere else here, which is right for a create that raced. It is wrong for a replace: editing
+	* one of two is a coin toss over which value the binding goes on serving. The store is ambiguous, so
+	* the caller is told, before anything is written.
+	*
+	* Name-addressed rather than id-addressed, deliberately: the name is what a caller composes and what
+	* a binding resolves, so addressing by it keeps the misaddressing this verb exists to catch inside
+	* the one thing that can catch it. Returns the entry id written, so a caller reading back afterwards
+	* can assert it is looking at the same address. `comment` is written beside the value when given.
+	*/
+	async updateExistingSecret(name, value, comment) {
+		const named = await this.entriesNamed(name);
+		const target = named[0];
+		if (!target) throw new NotFoundError({
+			message: `Secret '${name}' is not in the store, so there is nothing to update.`,
+			action: "Run `pithy secrets provision` to establish the entry, then run this again.",
+			detail: `update secret ${name}: no live entry of that name, and this verb never creates one`
+		});
+		if (named.length > 1) throw new ConflictError({
+			message: `Secret '${name}' names ${named.length} live entries in the store, so a replacement is ambiguous.`,
+			action: "Delete the entries nothing binds from the Secrets Store in the Cloudflare dashboard, then re-run.",
+			detail: `update secret ${name}: ${named.map((entry) => entry.id).join(", ")}`
+		});
+		await cloudflareRequest(`update secret ${name}`, () => this.getClient().secretsStore.stores.secrets.edit(target.id, {
+			account_id: this.accountId,
+			store_id: this.storeId,
+			value,
+			scopes: [...DEFAULT_SCOPES],
+			...commentField(comment)
+		}));
+		return target.id;
+	}
 	/** Delete a secret by name. Resolves the id via `listSecrets`, then issues DELETE by id. */
 	async deleteSecret(name) {
 		const existing = await this.findByName(name);
@@ -156,6 +235,22 @@ var CloudflareSecretsStoreManager = class extends CloudflareManager {
 			return out;
 		});
 	}
+	/**
+	* Every live entry carrying this name, oldest first.
+	*
+	* **The plural is the point.** Cloudflare does not document that the store refuses a duplicate name,
+	* and #643 established that it does not — so "the entry named X" is a claim rather than a given. A
+	* caller whose correctness depends on there being exactly one checks `length` here and says what it
+	* wants done when the store disagrees; {@link findByName} is the answer for a caller that only needs
+	* the entry the rest of this manager would act on.
+	*
+	* **A `deleted` entry is not one** (#643): Cloudflare lists a secret's lifecycle status as `pending`,
+	* `active` or `deleted` without saying what each means, and a deleted entry is the one reading that
+	* cannot be "there". `pending` is taken as there, since creating over it would duplicate it.
+	*/
+	async entriesNamed(name) {
+		return (await this.listSecrets()).filter((entry) => entry.name === name && isLive(entry)).sort(byAge);
+	}
 	/** Whether a secret with the given name currently exists in the store. */
 	async exists(name) {
 		return await this.findByName(name) !== void 0;
@@ -168,14 +263,15 @@ var CloudflareSecretsStoreManager = class extends CloudflareManager {
 		};
 	}
 	/** Create a single secret with the default scopes, and return the id Cloudflare gave it when it says one. */
-	async createSecret(name, value) {
+	async createSecret(name, value, comment) {
 		return cloudflareRequest(`create secret ${name}`, async () => {
 			const response = await this.getClient().secretsStore.stores.secrets.create(this.storeId, {
 				account_id: this.accountId,
 				body: [{
 					name,
 					value,
-					scopes: [...DEFAULT_SCOPES]
+					scopes: [...DEFAULT_SCOPES],
+					...commentField(comment)
 				}]
 			});
 			const items = response?.result ?? response;
@@ -184,13 +280,12 @@ var CloudflareSecretsStoreManager = class extends CloudflareManager {
 		});
 	}
 	/**
-	* The entry of this name, or `undefined`. **A `deleted` entry is not one** (#643): Cloudflare lists a secret's
-	* lifecycle status as `pending`, `active` or `deleted` without saying what each means, and a deleted entry is
-	* the one reading that cannot be "there". `pending` is taken as there, since creating over it would duplicate
-	* it. Of several entries of one name, the oldest, which is the one {@link createSecretIfAbsent} leaves standing.
+	* The entry of this name every verb here acts on, or `undefined`. Of several entries of one name, the
+	* oldest — which is the one {@link createSecretIfAbsent} leaves standing. See {@link entriesNamed} for
+	* why there can be several, and for what counts as being there at all.
 	*/
 	async findByName(name) {
-		return oldestEntry((await this.listSecrets()).filter((entry) => entry.name === name && entry.status !== "deleted"));
+		return (await this.entriesNamed(name))[0];
 	}
 };
 //#endregion

package/dist/test-utils/fixtures.d.ts

@@ -159,6 +159,13 @@ export declare const LIVE_FIXTURES: {
         readonly consequence: "Turnstile sign-in gating on a workers.dev hostname (#84) skips.";
         readonly doc: "docs/FIXTURES.md#turnstile-widget";
     };
+    readonly "workers-route-zone": {
+        readonly name: "workers-route-zone";
+        readonly keys: readonly ["WORKERS_ROUTE_ZONE"];
+        readonly shape: "credential";
+        readonly consequence: "The route-scoped CI token round trip (#651) skips: nothing proves a minted token can attach a route.";
+        readonly doc: "docs/FIXTURES.md#workers-route-zone";
+    };
 };
 /** Every declared fixture name. A typo is a type error rather than a silently skipped suite. */
 export type FixtureName = keyof typeof LIVE_FIXTURES;

package/dist/test-utils/fixtures.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../src/test-utils/fixtures.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../src/test-utils/fixtures.ts"],"names":[],"mappings":"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"}

package/dist/test-utils/fixtures.js

@@ -107,6 +107,13 @@ const LIVE_FIXTURES = {
 		shape: "credential",
 		consequence: "Turnstile sign-in gating on a workers.dev hostname (#84) skips.",
 		doc: "docs/FIXTURES.md#turnstile-widget"
+	},
+	"workers-route-zone": {
+		name: "workers-route-zone",
+		keys: ["WORKERS_ROUTE_ZONE"],
+		shape: "credential",
+		consequence: "The route-scoped CI token round trip (#651) skips: nothing proves a minted token can attach a route.",
+		doc: "docs/FIXTURES.md#workers-route-zone"
 	}
 };
 /**

package/dist/tokens/accountTokensManager.d.ts

@@ -23,6 +23,18 @@ export interface TokenPermission {
  * exact resource key format lives in a single place instead of being hand-spelled per use case.
  */
 export declare function accountResource(accountId: string): Record<string, string>;
+/**
+ * The resource scope for a **zone-level** policy: one `com.cloudflare.api.account.zone.<id>` key per
+ * zone, each `"*"`.
+ *
+ * Every zone is named individually, and that is the point (#651). Cloudflare also spells "every zone in
+ * this account" — `{ "com.cloudflare.api.account.<id>": { "com.cloudflare.api.account.zone.*": "*" } }` —
+ * and a `ci-system` token must never carry it: the credential a pipeline runs under gets the zones the
+ * project's own declared domains sit in and no others, so an account holding a customer's zone beside
+ * this project's is not one compromise away from both. De-duped, because two environments and two
+ * Workers routinely share one zone.
+ */
+export declare function zoneResources(zoneIds: readonly string[]): Record<string, string>;
 /**
  * A permission group available to account-owned tokens, as returned by the permission-groups list.
  * Only the id and name matter for resolution — the manager maps a requested name to its id.
@@ -41,26 +53,60 @@ export declare const MintedAccountToken: z.ZodObject<{
     id: z.ZodString;
     value: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
-    status: z.ZodOptional<z.ZodEnum<{
+    status: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
         active: "active";
         disabled: "disabled";
         expired: "expired";
-    }>>;
+    }>>>;
 }, z.core.$strip>;
 export type MintedAccountToken = z.output<typeof MintedAccountToken>;
+/**
+ * One access policy on an existing token, as the token list returns it.
+ *
+ * **Every field is `nullish`, and that is load-bearing rather than defensive.** `listTokens` decodes
+ * each entry with `safeParse` and drops what fails, so a single `null` where this expected a value
+ * makes a live token invisible to `findTokenByName` — and the next roll mints a *second* credential of
+ * the same name beside the first, with nothing saying so (#651).
+ */
+export declare const AccountTokenPolicy: z.ZodObject<{
+    effect: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>>>;
+    permission_groups: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>>>>;
+    resources: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type AccountTokenPolicy = z.output<typeof AccountTokenPolicy>;
 /**
  * An existing account-owned token's metadata, as returned by list/get. No `value` — Cloudflare never
- * returns a token's secret after creation — so this is only enough to find a token by name and
- * address it for deletion.
+ * returns a token's secret after creation — so this is only enough to find a token by name, report on
+ * it, and address it for deletion.
+ *
+ * **It reads what it uses and nothing more.** It briefly carried `expires_on`, `not_before` and
+ * `condition` so a re-scoping mint could resend them; that mint is gone (see {@link
+ * CloudflareAccountTokensManager.rollToken}), and reading a field only to hand it straight back is a
+ * field that can be read wrong.
  */
 export declare const AccountTokenSummary: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
-    status: z.ZodOptional<z.ZodEnum<{
+    status: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
         active: "active";
         disabled: "disabled";
         expired: "expired";
-    }>>;
+    }>>>;
+    policies: z.ZodCatch<z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        effect: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+        }>>>;
+        permission_groups: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>>>>;
+        resources: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>>>>;
 }, z.core.$strip>;
 export type AccountTokenSummary = z.output<typeof AccountTokenSummary>;
 /**
@@ -153,6 +199,18 @@ export declare class CloudflareAccountTokensManager extends CloudflareManager {
      * Either way the caller gets a usable secret to store — the idempotent path for a credential that
      * lives in the Secrets Store, since Cloudflare never returns a token's existing secret. Mirrors the
      * dashboard's roll-or-create.
+     *
+     * **A roll never changes the policy set, and that is a decision rather than an omission (#651).** It
+     * briefly did: `pithy token list` tells an adopter their CI token predates zone-scoped routes, and
+     * re-scoping here made the remedy one command. But Cloudflare's token update is a full
+     * representation, so doing it meant every mint had to resend the whole token correctly — `condition`,
+     * `expires_on`, `not_before`, `status` — and three review rounds each found a new way that went
+     * wrong: a cleared IP allowlist, a re-enabled disabled token, a `null` that hid the token and minted a
+     * duplicate beside it.
+     *
+     * {@link mintToken} plus a delete is what actually re-scopes, and `pithy token rotate` has always been
+     * exactly that. So the remedy names rotate, and this stays the one thing it can be relied on to be:
+     * a new secret on the same token, with nothing else touched.
      */
     rollToken(name: string, permissions: TokenPermission[]): Promise<MintedAccountToken>;
 }