@pithy-sh/secrets 0.1.0

package/src/http/routes.ts

@@ -0,0 +1,300 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import type { ControlPlaneContext } from "@pithy-sh/core/src/controlPlane/context";
+import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
+import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
+import { pageLimit } from "@pithy-sh/core/src/data/cursor";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { VerificationStrategy } from "@pithy-sh/core/src/http/verification";
+import type { Context, Hono } from "hono";
+import { dueForRotation } from "../admin/health";
+import { readSecretRotations, readSecretStatus } from "../admin/status";
+import { type SecretsAuditAction, SecretsAuditActions } from "../audit/actions";
+import { secretsStatusDatabase } from "../data/statusDb";
+import { SecretNotFoundError } from "../error/errors";
+import type { SecretRegistry, SecretRegistryEntry } from "../registry";
+import type { SecretRotationOutcome } from "../rotation/rotateValue";
+import { SECRETS_ROTATE_SCOPE, SECRETS_STATUS_READ_SCOPE } from "./guards";
+import type { SecretRotateResponse, SecretRotationsResponse, SecretsStatusResponse } from "./responses";
+import { runWorkerRotation, workerRotationDeps, workerRotationEnvironment } from "./rotate";
+import { RotationsQuery, SecretNameParam } from "./schemas";
+import { secretRotationOutcomeView, secretRotationView, secretStatusView } from "./view";
+
+/**
+ * The secrets capability's management surface — two reads and one write, all control-plane, none of them
+ * carrying a value:
+ *
+ *   GET  /secrets/admin/status                  → every declared secret's status   (control-plane: secrets:status:read)
+ *   GET  /secrets/admin/status/:name/rotations  → one secret's rotation history    (control-plane: secrets:status:read)  param: SecretNameParam, query: RotationsQuery
+ *   POST /secrets/admin/status/:name/rotate     → replace one secret, here         (control-plane: secrets:rotate)       param: SecretNameParam
+ *
+ * ## The write is a rotation and nothing else, and that is what makes it possible
+ *
+ * This surface was two reads because **a management client cannot supply a value.** It holds neither the
+ * adopter's registry nor their Zod schemas, so a create or an update here would write a value against a
+ * schema it could not check (`management/writeSecret.ts` explains why the Worker cannot be that
+ * validator), and a route that writes a secret it cannot check is not a feature.
+ *
+ * A rotation supplies nothing. The successor is produced *inside* the Worker — minted from the entry's own
+ * recipe for a `local` secret, or returned by the rotator the registry entry carries for a `provider` one —
+ * so the value never crosses a boundary in either direction, and the schema that governs it is the one that
+ * produced it. That is the whole of why this write can exist where create and update still cannot, and it
+ * is a fact about rotation rather than an exception granted to it.
+ *
+ * **What a Worker can rotate is narrower than what the CLI can**, and `./rotate.ts` is where that is argued
+ * and refused: one environment's D1, its own master key, and nothing that lives in Cloudflare's Secrets
+ * Store or has to be identical across environments.
+ *
+ * ## There is no route that reads a value, and there is no scope that could grant one
+ *
+ * Not an omission to be filled in later. The whole point of storing secrets in the customer's own D1,
+ * under a master key their Worker holds, is that no third party has a path to a plaintext. A route here
+ * would be that path, and it would exist in every deployment whether or not anybody granted it. The
+ * rotation route does not weaken this: it produces a value, stores it, and answers with a shape that has no
+ * field one could sit in (`SecretRotationOutcomeView`). A rotation that cannot store its successor discards
+ * it and says so — it never hands it back rather than lose it.
+ *
+ * ## The rotation is a `POST` with no body, and CSRF has nothing to ride
+ *
+ * `control-plane` is not a cookie strategy. `requireControlPlane` verifies a detached EdDSA token in the
+ * `CONTROL_PLANE_HEADER`, signed over the request body, against a key the adopter registered — there is no
+ * ambient credential a browser attaches on its own, so a cross-site form post carries no authority. CSRF
+ * middleware belongs with `session`, and stacking it here would guard a door that has no hinge. The route
+ * takes **no body at all**: everything it needs is the `:name` it is addressed at and the environment its
+ * own verified context names, and a body it does not read is a body nobody can smuggle a value into.
+ *
+ * ## `requireAuth()` is never on these lines
+ *
+ * The seam leaves `c.var.auth` null on a control-plane call by design, so an auth gate would deny every
+ * legitimate management call permanently and no credential could fix it. `requireControlPlane`
+ * **replaces** it; it does not stack with it.
+ *
+ * Validators sit **after** the guard on every route line: an unverified caller is turned away before its
+ * request is parsed, so a malformed request can never downgrade a 403 to a 400 and tell a caller with no
+ * credential which requests were well-formed. On a surface that enumerates a project's credentials, that
+ * is a live oracle.
+ */
+
+/**
+ * Where the secrets management surface mounts when an adopter names nothing.
+ *
+ * Exported because two places must agree on it: the router below, and `secretsAdminRoutes` in
+ * `guards.ts`. A default living only in the registrar would let the manifest advertise `/secrets/...`
+ * while the routes mounted somewhere else, and a management client composing its calls from the
+ * manifest would 404 with nothing to diagnose.
+ */
+export const SECRETS_DEFAULT_BASE_PATH = "/secrets";
+
+/**
+ * What every route this capability mounts declares: its path, its verification strategy, and the
+ * control-plane scope it checks.
+ *
+ * Exported so a test can assert against the declaration rather than against a middleware count.
+ * Counting middleware proves that *something* runs before the handler; it cannot prove *what*, and a
+ * bare `zValidator` satisfies a count. `routeContract.test.ts` checks this list against the routes Hono
+ * actually registered in both directions.
+ */
+export interface SecretsRouteDeclaration {
+  readonly method: "GET" | "POST";
+  /** The path relative to the configured `basePath`, e.g. `/admin/status`. */
+  readonly path: string;
+  readonly strategy: VerificationStrategy;
+  /** The control-plane scope this route checks. */
+  readonly scope: ControlPlaneScope;
+}
+
+/** Every route, and how it is gated. */
+export const SECRETS_ROUTES: readonly SecretsRouteDeclaration[] = [
+  { method: "GET", path: "/admin/status", strategy: "control-plane", scope: SECRETS_STATUS_READ_SCOPE },
+  { method: "GET", path: "/admin/status/:name/rotations", strategy: "control-plane", scope: SECRETS_STATUS_READ_SCOPE },
+  { method: "POST", path: "/admin/status/:name/rotate", strategy: "control-plane", scope: SECRETS_ROTATE_SCOPE },
+];
+
+export interface SecretsRoutesOptions {
+  /**
+   * The registry to report over, read **per request** rather than captured.
+   *
+   * A function, because the set worth reporting is not the one this capability was constructed with. The
+   * combined registry — every composed capability's slice, auth's signing key and email's link key
+   * included — only exists once `compose` has run, which is after the router is built. Capturing the
+   * value here would report the adopter's own secrets and silently omit every capability's, which is
+   * most of them.
+   */
+  registry: () => SecretRegistry;
+  /** Mount the surface somewhere other than `/secrets`. Moves the advertised paths with it. */
+  basePath?: string;
+}
+
+/**
+ * The verified management client behind a control-plane call.
+ *
+ * `requireControlPlane()` has run on every route that calls this, so `c.var.controlPlane` is populated
+ * by the time a handler reads it. The throw is a programming-error guard rather than a runtime path:
+ * reaching it would mean a management route was mounted without its gate, which is the one mistake this
+ * file is arranged to make impossible.
+ */
+function caller(c: Context<PithyHonoEnv>): ControlPlaneContext {
+  const context = c.var.controlPlane;
+  if (!context) {
+    throw new InternalError({
+      message: "The secrets surface could not identify the management caller.",
+      detail: "requireControlPlane() must run before a secrets management handler reads the caller.",
+    });
+  }
+  return context;
+}
+
+/**
+ * The registry entry this call is addressed at, or a 404.
+ *
+ * **Membership is the gate, not the string's shape.** Without it the history route would read rotation
+ * rows by arbitrary name — including the sentinel the whole-store key rotation records itself under, and
+ * any row left by a secret since removed from the registry — and the rotation route would be pointed at a
+ * name no capability has ever declared. A keyed entry is refused with the rest: a keyspace has no single
+ * value, so neither call has an answer for one.
+ */
+function declared(registry: SecretRegistry, name: string): SecretRegistryEntry {
+  const entry = registry[name];
+  if (!entry || entry.keyed) {
+    throw new SecretNotFoundError({
+      message: `No secret named '${name}' is declared.`,
+      action: "Read the declared names from the status listing.",
+      detail: `secret status: '${name}' is not a named entry of the composed registry`,
+    });
+  }
+  return entry;
+}
+
+/** Record a management read. Names and counts only — there is nothing else to record, by construction. */
+async function record(
+  c: Context<PithyHonoEnv>,
+  action: SecretsAuditAction,
+  resourceId: string | null,
+  metadata: Record<string, unknown>,
+): Promise<void> {
+  const who = caller(c);
+  await c.var.emit({
+    action,
+    outcome: "success",
+    actorType: "control-plane",
+    actorId: who.subject,
+    resourceType: "secret",
+    resourceId,
+    requestId: c.req.header("cf-ray"),
+    ip: c.req.header("cf-connecting-ip"),
+    userAgent: c.req.header("user-agent"),
+    metadata: { connectionId: who.connectionId, ...metadata },
+  });
+}
+
+/**
+ * Record a rotation — the one administrative act on this surface, on success and on failure alike.
+ *
+ * `severity` is the field an incident review scans, and `unrecorded` is `critical` because it is the only
+ * outcome here that leaves a system broken: a credential dead at its issuer and its successor never stored.
+ * `rollFailed` is written down rather than left to be inferred from an empty `recorded`, because *was
+ * rolled* and *may have been rolled* is the distinction the review turns on and the two are the same
+ * absence otherwise.
+ *
+ * Names, environments and flags. Nothing about a value is here, and nothing about one is available to put
+ * here — `SecretRotationOutcome` has no field that could carry one.
+ */
+async function recordRotation(c: Context<PithyHonoEnv>, outcome: SecretRotationOutcome): Promise<void> {
+  const who = caller(c);
+  await c.var.emit({
+    action: SecretsAuditActions.rotated,
+    outcome: outcome.status === "rotated" ? "success" : "failure",
+    severity: outcome.status === "unrecorded" ? "critical" : "warning",
+    actorType: "control-plane",
+    actorId: who.subject,
+    resourceType: "secret",
+    resourceId: outcome.name,
+    requestId: c.req.header("cf-ray"),
+    ip: c.req.header("cf-connecting-ip"),
+    userAgent: c.req.header("user-agent"),
+    metadata: {
+      connectionId: who.connectionId,
+      name: outcome.name,
+      status: outcome.status,
+      rotation: outcome.kind,
+      rolled: outcome.rolled,
+      environments: outcome.recorded,
+      ...(outcome.rollFailed === undefined ? {} : { rollFailed: outcome.rollFailed }),
+      ...(outcome.stranded.length > 0 ? { stranded: outcome.stranded } : {}),
+    },
+  });
+}
+
+export function registerSecretsRoutes(options: SecretsRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
+  const base = options.basePath ?? SECRETS_DEFAULT_BASE_PATH;
+
+  return (app) => {
+    app.get(`${base}/admin/status`, requireControlPlane(SECRETS_STATUS_READ_SCOPE), async (c) => {
+      const entries = await readSecretStatus(secretsStatusDatabase(c), options.registry());
+      // Narrowed, not filtered by shape. An entry whose row would not decode has no `status` to render, so
+      // it cannot reach `secretStatusView` — the union is what makes that a compile error rather than an
+      // `undefined` on the wire (#387).
+      const secrets = entries.flatMap((entry) => (entry.state === "readable" ? [secretStatusView(entry.status)] : []));
+      const unreadable = entries.flatMap((entry) => (entry.state === "unreadable" ? [entry.name] : []));
+      await record(c, SecretsAuditActions.statusRead, null, {
+        declared: entries.length,
+        overdue: dueForRotation(entries),
+        unreadable: unreadable.length,
+      });
+      return c.json({ secrets, unreadable } satisfies SecretsStatusResponse, 200);
+    });
+
+    app.get(
+      `${base}/admin/status/:name/rotations`,
+      requireControlPlane(SECRETS_STATUS_READ_SCOPE),
+      zValidator("param", SecretNameParam, validationHook),
+      zValidator("query", RotationsQuery, validationHook),
+      async (c) => {
+        const { name } = c.req.valid("param");
+        declared(options.registry(), name);
+        const entries = await readSecretRotations(
+          secretsStatusDatabase(c),
+          name,
+          pageLimit(c.req.valid("query").limit),
+        );
+        const rotations = entries.flatMap((entry) =>
+          entry.state === "readable" ? [secretRotationView(entry.record)] : [],
+        );
+        const unreadable = entries.length - rotations.length;
+        await record(c, SecretsAuditActions.rotationsRead, name, { name, returned: rotations.length, unreadable });
+        return c.json({ name, rotations, unreadable } satisfies SecretRotationsResponse, 200);
+      },
+    );
+
+    app.post(
+      `${base}/admin/status/:name/rotate`,
+      requireControlPlane(SECRETS_ROTATE_SCOPE),
+      zValidator("param", SecretNameParam, validationHook),
+      async (c) => {
+        const { name } = c.req.valid("param");
+        const who = caller(c);
+        const entry = declared(options.registry(), name);
+        const outcome = await runWorkerRotation(await workerRotationDeps(c), {
+          name,
+          entry,
+          // From the verified context, not from a body and not from a raw binding. A caller cannot name
+          // the environment it wants to write, because a caller naming an environment would be a caller
+          // choosing which of the adopter's deployments to touch.
+          environment: workerRotationEnvironment(who.environment),
+          actor: who.subject,
+        });
+        // Audited on both outcomes, and never for a rotation that did nothing — a trail logging a
+        // rotation for a secret nothing touched is a trail nobody can read. The metadata is the same set
+        // `pithy secrets rotate` records, so one query answers the question whichever door was used.
+        if (outcome.status !== "unchanged") {
+          await recordRotation(c, outcome);
+        }
+        return c.json({ rotation: secretRotationOutcomeView(outcome) } satisfies SecretRotateResponse, 200);
+      },
+    );
+  };
+}

package/src/http/schemas.ts

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
+import { z } from "zod";
+
+/**
+ * The HTTP boundary shapes for the secrets management routes. Everything a client can send is declared
+ * here and parsed on the route line, so reading a route tells you what it accepts without opening the
+ * handler. There are no bodies: this surface is read-only.
+ *
+ * ## Why `:name` carries no character pattern
+ *
+ * `defineSecretRegistry` refuses only two things in a name — empty, and the keyspace separator — so any
+ * other spelling an adopter chose is a legitimate registry entry. A charset pattern here would 400 a
+ * name the project genuinely declares, and a status read that cannot address a secret is worse than one
+ * that answers 404 for a name that does not exist.
+ *
+ * The safety comes from the shape of the check instead of from the shape of the string: the handler
+ * looks the name up in the composed registry by exact match and refuses anything it does not find, so
+ * the only names that reach a query or a response are ones the project itself declared. Routing does
+ * the rest — a keyspace member is `<keyspace>/<key>`, and a slash cannot appear in one path segment.
+ *
+ * The length bound is not the security control; it is the ordinary refusal to run a query over an
+ * unbounded string a caller chose.
+ */
+
+/** How many rotation rows one call returns. Bounded, because a verified client can still have a bug. */
+const Limit = z.coerce
+  .number()
+  .int()
+  .min(1)
+  .max(MAX_PAGE_SIZE)
+  .optional()
+  .describe(`How many rotation rows to return, from 1 to ${MAX_PAGE_SIZE}. Defaults to a page a screen can render.`);
+
+export const SecretNameParam = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .max(256)
+      .describe(
+        "The secret to read — the `:name` path segment, matched exactly against the composed registry. A name no capability declares is a 404, not an empty history.",
+      ),
+  })
+  .describe("The `:name` path segment naming one declared secret.");
+export type SecretNameParam = z.output<typeof SecretNameParam>;
+
+export const RotationsQuery = z
+  .object({ limit: Limit })
+  .describe("The rotation-history query: how many attempts to return, newest first.");
+export type RotationsQuery = z.output<typeof RotationsQuery>;

package/src/http/view.ts

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { SecretRotationRecord, SecretStatus } from "../admin/status";
+import type { SecretRotationOutcome } from "../rotation/rotateValue";
+import type { SecretRotationOutcomeView, SecretRotationView, SecretStatusView } from "./responses";
+
+/**
+ * What a client is shown. Nothing in this capability's management surface ever returns a raw row.
+ *
+ * The only work here is the date rendering — ms-epoch in SQLite, `Date` in TypeScript, ISO-8601 on the
+ * wire — and it is a function rather than a spread for one reason: **a spread would carry any field the
+ * reader shape later gained, straight to a client, silently.** Naming every field means a new fact has
+ * to be added here, to `responses.ts`, and to the test that asserts both field sets, which is three
+ * places somebody has to mean it.
+ *
+ * Null passes through as null, in every case, because null is a fact on this surface: never rotated,
+ * not stored here, no cadence declared, unanswerable. See `admin/status.ts`.
+ */
+
+/** One secret's status, rendered for the wire. */
+export function secretStatusView(status: SecretStatus): SecretStatusView {
+  return {
+    name: status.name,
+    backend: status.backend,
+    valueType: status.valueType,
+    rotatable: status.rotatable,
+    rotation: status.rotation,
+    keyVersion: status.keyVersion,
+    createdAt: status.createdAt?.toISOString() ?? null,
+    updatedAt: status.updatedAt?.toISOString() ?? null,
+    lastRotatedAt: status.lastRotatedAt?.toISOString() ?? null,
+    rotationCount: status.rotationCount,
+    rotateEveryDays: status.rotateEveryDays,
+    overdue: status.overdue,
+  };
+}
+
+/**
+ * One rotation outcome, rendered for the wire.
+ *
+ * **Two fields of the core's outcome are not named here, and that is the whole of what this function is
+ * for.** `cause` is an `unknown` thrown by a store — an exception raised where a value was in scope — and
+ * it does not cross. Optionality is flattened rather than forwarded: `rollFailed` becomes a plain boolean
+ * because absent and false mean the same thing beside `rolled`, while `reason` and `attempts` become null,
+ * because for those two the absence *is* the fact — nothing was skipped, nothing was stored.
+ *
+ * Naming every field rather than spreading, for the reason `secretStatusView` states: a spread would carry
+ * a field the core's outcome later gained straight to a client, silently.
+ */
+export function secretRotationOutcomeView(outcome: SecretRotationOutcome): SecretRotationOutcomeView {
+  return {
+    name: outcome.name,
+    status: outcome.status,
+    kind: outcome.kind,
+    rolled: outcome.rolled,
+    rollFailed: outcome.rollFailed ?? false,
+    recorded: [...outcome.recorded],
+    stranded: [...outcome.stranded],
+    reason: outcome.reason ?? null,
+    attempts: outcome.attempts ?? null,
+  };
+}
+
+/** One rotation attempt, rendered for the wire. */
+export function secretRotationView(record: SecretRotationRecord): SecretRotationView {
+  return {
+    startedAt: record.startedAt.toISOString(),
+    completedAt: record.completedAt?.toISOString() ?? null,
+    status: record.status,
+    trigger: record.trigger,
+    rotatedBy: record.rotatedBy,
+  };
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add secrets` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory, the registry helper and the schemas a registry entry is written
+ * against, the two accessors a Worker reads secrets through, and the table map. Every other module is
+ * imported by deep path (`@pithy-sh/secrets/src/...`); this is the documented contract, not a barrel.
+ *
+ * It exists because `pithy add` writes `import { secrets } from "@pithy-sh/secrets/src/index";`, and
+ * for a while nothing answered that specifier. `@pithy-sh/core/src/index.ts` says the same thing for
+ * the same reason.
+ */
+
+export {
+  isSecretsCapability,
+  type SecretsCapability,
+  type SecretsConfig,
+  secrets,
+  secretsTokenProfile,
+} from "./capability";
+export { type SecretsTables, secretsTables } from "./data/tables";
+// A keyspace member's stored name. Exported because the app that mints per-tenant credentials writes
+// them, and composing that name by hand is exactly the mistake `keyedSecretName` exists to prevent.
+export { keyedSecretName, SecretKey } from "./keyspace";
+export type { KeyedWriteMode } from "./keyspaceWrite";
+export {
+  defineSecretRegistry,
+  type KeyedSecretName,
+  SecretBackend,
+  type SecretName,
+  type SecretRegistry,
+  type SecretRegistryEntry,
+  SecretScope,
+  type SecretValue,
+  SecretValueType,
+} from "./registry";
+// `SecretsAccessor` is a type here, not the class. Its constructor takes already-resolved plaintext,
+// and an entrypoint that calls itself narrow has no business handing out a way to mint one over
+// arbitrary values. `secretsStore` is how a Worker gets one.
+export {
+  type KeyedPutOptions,
+  type KeyedWriteAudit,
+  type KeyedWriteOptions,
+  type KeyedWriteResult,
+  type SecretsAccessor,
+  secretsStore,
+  type VersionedSecret,
+} from "./secretsStore";
+export { DEFAULT_SECRETS_CACHE_TTL_SECONDS, sharedSecretsStore } from "./sharedSecretsStore";

package/src/keyspace.ts

@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+
+/**
+ * Keyspaces — the naming rule behind a `keyed` registry entry.
+ *
+ * A named entry is one secret with one value. A keyed entry declares a *keyspace*: one schema, one
+ * backend, and an unbounded set of members whose keys only exist at runtime — one signing key per
+ * customer connection, one credential per tenant. The registry can no more list those names than it
+ * can list next month's customers.
+ *
+ * A member is stored under `<entry>/<key>` in the same encrypted store as everything else, so at-rest
+ * rotation, the audit and teardown all keep working with no second storage path. `/` is the one
+ * separator, and `defineSecretRegistry` refuses it in an entry name — so a keyspace member can never
+ * collide with a declared secret, and no key can compose its way into a neighboring keyspace.
+ *
+ * That is the whole security argument, and it rests on {@link SecretKey}: every key is validated
+ * before it is composed, so `../OTHER/victim` is refused at the call rather than resolved at the
+ * store. One tenant's credential is not reachable with another tenant's key.
+ */
+
+/** The one separator between a keyspace and a member key. Illegal in a registry entry name. */
+export const KEYSPACE_SEPARATOR = "/";
+
+/** Longest member key. Generous for a uuid or a prefixed id; short enough to keep a stored name bounded. */
+const MAX_KEY_LENGTH = 128;
+
+export const SecretKey = z
+  .string()
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/)
+  .max(MAX_KEY_LENGTH)
+  .describe(
+    "A keyspace member key supplied at runtime — a tenant, connection, or installation id. Letters, digits, dot, dash and underscore only, starting with a letter or digit, at most 128 characters: the separator, whitespace and control characters are excluded so a key can never compose its way out of its keyspace.",
+  );
+export type SecretKey = z.output<typeof SecretKey>;
+
+/**
+ * The stored name of one keyspace member. The only sanctioned way to compose one — read and write
+ * both go through here, so there is a single place where a key is proven legal.
+ *
+ * The refusal names the keyspace and never the key. `detail` reaches logs verbatim, and a rejected
+ * key is unvalidated input: echoing it would put attacker-chosen bytes, newlines included, in the
+ * operator's log.
+ */
+export function keyedSecretName(name: string, key: string): string {
+  const parsed = SecretKey.safeParse(key);
+  if (!parsed.success) {
+    throw new ValidationError({
+      message: "That secret key is not valid.",
+      action: "Use letters, digits, dot, dash or underscore — starting with a letter or digit, up to 128 characters.",
+      detail: `keyspace '${name}': the supplied key failed SecretKey validation`,
+    });
+  }
+  return `${name}${KEYSPACE_SEPARATOR}${parsed.data}`;
+}
+
+/**
+ * Split a stored name back into its keyspace and key, or `undefined` when it is not a keyspace
+ * member. The audit uses it to attribute a stored member to the keyspace that declared it, so a
+ * tenant's credential is not reported as an orphan.
+ */
+export function parseKeyedSecretName(stored: string): { name: string; key: string } | undefined {
+  const at = stored.indexOf(KEYSPACE_SEPARATOR);
+  if (at <= 0) return undefined;
+  const key = stored.slice(at + 1);
+  return SecretKey.safeParse(key).success ? { name: stored.slice(0, at), key } : undefined;
+}