@greatwait/contracts 0.1.0-alpha.1

package/dist/secrets.d.ts

@@ -0,0 +1,383 @@
+import { z } from "zod";
+/**
+ * Secret handling and redaction.
+ *
+ * A secret is shown exactly once, at creation. After that only its non-secret
+ * prefix and metadata are readable — by the API, by MCP tools, by the
+ * dashboard, and by support. There is no "reveal" endpoint, because a store
+ * that can reveal a secret is a store that can leak one.
+ */
+/** `pt_` + environment + `_` + public prefix. The secret half is never stored. */
+export declare const CREDENTIAL_PREFIX_PATTERN: RegExp;
+/** How many characters of a credential are the non-secret display prefix. */
+export declare const CREDENTIAL_PREFIX_LENGTH = 16;
+/** How many characters of high-entropy secret follow the display prefix. */
+export declare const CREDENTIAL_SECRET_LENGTH = 32;
+/**
+ * A whole credential: the display prefix, followed immediately by the secret
+ * half. `pt_test_a1b2c3d4` is the prefix of `pt_test_a1b2c3d4<32 more>`, which
+ * is what lets a presented credential be looked up by prefix before anything is
+ * compared — a store that had to scan every row to find a candidate would leak
+ * timing, and a separator would be one more thing for a client to get wrong.
+ *
+ * **This pattern is enforced where credentials are issued and verified, and
+ * deliberately not by `credentialCreatedSchema` below.** A response schema is
+ * projected into a committed example, and an example matching this pattern is
+ * indistinguishable from a real credential to `npm run check:secrets`, which
+ * would refuse it — correctly. So the wire schema states the length floor, the
+ * issuer states the format, and the published example is visibly a placeholder.
+ */
+export declare const CREDENTIAL_SECRET_PATTERN: RegExp;
+/**
+ * A credential as any read shape shows it: what it can do, where it can do it,
+ * and enough to recognise which one it is. Never the secret.
+ */
+export declare const credentialMetadataSchema: z.ZodObject<{
+    createdAt: z.ZodString;
+    displayPrefix: z.ZodString;
+    environmentKind: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    issuedBy: z.ZodOptional<z.ZodString>;
+    lastUsedAt: z.ZodOptional<z.ZodString>;
+    project: z.ZodString;
+    revokedAt: z.ZodOptional<z.ZodString>;
+    supersededBy: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "credentials:administer": "credentials:administer";
+        "credentials:read": "credentials:read";
+        "credentials:write": "credentials:write";
+        "endpoints:read": "endpoints:read";
+        "endpoints:write": "endpoints:write";
+        "forecast:read": "forecast:read";
+        "grants:read": "grants:read";
+        "grants:write": "grants:write";
+        "occurrences:read": "occurrences:read";
+        "occurrences:redeliver": "occurrences:redeliver";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "schedules:read": "schedules:read";
+        "schedules:write": "schedules:write";
+        "usage:read": "usage:read";
+    }>>;
+}, z.core.$strip>;
+export type CredentialMetadata = z.infer<typeof credentialMetadataSchema>;
+/**
+ * A page of credentials.
+ *
+ * Built from `pageSchema` rather than written out, so paging is defined once:
+ * the cursor, the bounded limit and the freshness discriminator on this
+ * collection are the same ones every later collection gets, and a client that
+ * can page one can page all of them.
+ *
+ * The item is `credentialMetadataSchema` — the read shape — so there is no
+ * shape in the contract in which a list could carry a secret. That is a
+ * property of the type rather than of the query behind it.
+ */
+export declare const credentialPageSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        createdAt: z.ZodString;
+        displayPrefix: z.ZodString;
+        environmentKind: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        issuedBy: z.ZodOptional<z.ZodString>;
+        lastUsedAt: z.ZodOptional<z.ZodString>;
+        project: z.ZodString;
+        revokedAt: z.ZodOptional<z.ZodString>;
+        supersededBy: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodArray<z.ZodEnum<{
+            "credentials:administer": "credentials:administer";
+            "credentials:read": "credentials:read";
+            "credentials:write": "credentials:write";
+            "endpoints:read": "endpoints:read";
+            "endpoints:write": "endpoints:write";
+            "forecast:read": "forecast:read";
+            "grants:read": "grants:read";
+            "grants:write": "grants:write";
+            "occurrences:read": "occurrences:read";
+            "occurrences:redeliver": "occurrences:redeliver";
+            "projects:read": "projects:read";
+            "projects:write": "projects:write";
+            "schedules:read": "schedules:read";
+            "schedules:write": "schedules:write";
+            "usage:read": "usage:read";
+        }>>;
+    }, z.core.$strip>>;
+    freshness: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>, z.ZodObject<{
+        asOf: z.ZodString;
+        kind: z.ZodLiteral<"projected">;
+        lagSeconds: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CredentialPage = z.infer<typeof credentialPageSchema>;
+/**
+ * The one-time creation response. `secret` is present here and nowhere else in
+ * the contract; every read shape carries metadata only.
+ */
+export declare const credentialCreatedSchema: z.ZodObject<{
+    createdAt: z.ZodString;
+    displayPrefix: z.ZodString;
+    environmentKind: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    issuedBy: z.ZodOptional<z.ZodString>;
+    lastUsedAt: z.ZodOptional<z.ZodString>;
+    project: z.ZodString;
+    revokedAt: z.ZodOptional<z.ZodString>;
+    supersededBy: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "credentials:administer": "credentials:administer";
+        "credentials:read": "credentials:read";
+        "credentials:write": "credentials:write";
+        "endpoints:read": "endpoints:read";
+        "endpoints:write": "endpoints:write";
+        "forecast:read": "forecast:read";
+        "grants:read": "grants:read";
+        "grants:write": "grants:write";
+        "occurrences:read": "occurrences:read";
+        "occurrences:redeliver": "occurrences:redeliver";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "schedules:read": "schedules:read";
+        "schedules:write": "schedules:write";
+        "usage:read": "usage:read";
+    }>>;
+    secret: z.ZodString;
+    shownOnce: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type CredentialCreated = z.infer<typeof credentialCreatedSchema>;
+/**
+ * What a caller asks for when issuing a credential.
+ *
+ * `project` and `environmentKind` are caller-supplied and then *validated
+ * against the principal's organization* — they select within the caller's own
+ * tenancy rather than widening it, which is the same shape `resolveAuthority`
+ * already has. The organization is never here: that would be selecting a
+ * tenant, which `docs/contracts/v1-conventions.md` forbids outright.
+ */
+export declare const credentialRequestSchema: z.ZodObject<{
+    environmentKind: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    project: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "credentials:administer": "credentials:administer";
+        "credentials:read": "credentials:read";
+        "credentials:write": "credentials:write";
+        "endpoints:read": "endpoints:read";
+        "endpoints:write": "endpoints:write";
+        "forecast:read": "forecast:read";
+        "grants:read": "grants:read";
+        "grants:write": "grants:write";
+        "occurrences:read": "occurrences:read";
+        "occurrences:redeliver": "occurrences:redeliver";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "schedules:read": "schedules:read";
+        "schedules:write": "schedules:write";
+        "usage:read": "usage:read";
+    }>>;
+}, z.core.$strip>;
+export type CredentialRequest = z.infer<typeof credentialRequestSchema>;
+/**
+ * The longest a rotated credential may keep working, and its default.
+ *
+ * The number is a judgement rather than a derivation: long enough that a deploy
+ * can roll a new secret through every consumer, short enough that a leaked old
+ * secret stops being useful within a day. It is stated here rather than left in
+ * a route so that changing it is a contract change somebody reviews.
+ */
+export declare const CREDENTIAL_ROTATION_OVERLAP_SECONDS = 86400;
+/**
+ * What a caller asks for when rotating.
+ *
+ * `overlapSeconds` may only *shorten* the window — the default is also the
+ * maximum. A caller who knows their consumers have already picked up the new
+ * secret can retire the old one immediately; nobody can ask for a longer tail
+ * than the contract allows, because the tail is the part that is dangerous.
+ *
+ * Zero is permitted and means the old credential stops verifying at once, which
+ * is deliberately not the same as revoking it: the audit trail records a
+ * rotation, and the retired credential names its replacement.
+ */
+export declare const credentialRotationRequestSchema: z.ZodObject<{
+    overlapSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CredentialRotationRequest = z.infer<typeof credentialRotationRequestSchema>;
+/**
+ * The rotation response: the replacement, and what became of the original.
+ *
+ * Both halves are here because a caller that only learned the new secret would
+ * have no way to know when the old one stops working, and the deadline is the
+ * whole point of an overlap. `retired` is metadata only — rotation never
+ * reveals a secret it did not just mint.
+ */
+export declare const credentialRotatedSchema: z.ZodObject<{
+    credential: z.ZodObject<{
+        createdAt: z.ZodString;
+        displayPrefix: z.ZodString;
+        environmentKind: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        issuedBy: z.ZodOptional<z.ZodString>;
+        lastUsedAt: z.ZodOptional<z.ZodString>;
+        project: z.ZodString;
+        revokedAt: z.ZodOptional<z.ZodString>;
+        supersededBy: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodArray<z.ZodEnum<{
+            "credentials:administer": "credentials:administer";
+            "credentials:read": "credentials:read";
+            "credentials:write": "credentials:write";
+            "endpoints:read": "endpoints:read";
+            "endpoints:write": "endpoints:write";
+            "forecast:read": "forecast:read";
+            "grants:read": "grants:read";
+            "grants:write": "grants:write";
+            "occurrences:read": "occurrences:read";
+            "occurrences:redeliver": "occurrences:redeliver";
+            "projects:read": "projects:read";
+            "projects:write": "projects:write";
+            "schedules:read": "schedules:read";
+            "schedules:write": "schedules:write";
+            "usage:read": "usage:read";
+        }>>;
+        secret: z.ZodString;
+        shownOnce: z.ZodLiteral<true>;
+    }, z.core.$strip>;
+    retired: z.ZodObject<{
+        createdAt: z.ZodString;
+        displayPrefix: z.ZodString;
+        environmentKind: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        issuedBy: z.ZodOptional<z.ZodString>;
+        lastUsedAt: z.ZodOptional<z.ZodString>;
+        project: z.ZodString;
+        revokedAt: z.ZodOptional<z.ZodString>;
+        supersededBy: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodArray<z.ZodEnum<{
+            "credentials:administer": "credentials:administer";
+            "credentials:read": "credentials:read";
+            "credentials:write": "credentials:write";
+            "endpoints:read": "endpoints:read";
+            "endpoints:write": "endpoints:write";
+            "forecast:read": "forecast:read";
+            "grants:read": "grants:read";
+            "grants:write": "grants:write";
+            "occurrences:read": "occurrences:read";
+            "occurrences:redeliver": "occurrences:redeliver";
+            "projects:read": "projects:read";
+            "projects:write": "projects:write";
+            "schedules:read": "schedules:read";
+            "schedules:write": "schedules:write";
+            "usage:read": "usage:read";
+        }>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CredentialRotated = z.infer<typeof credentialRotatedSchema>;
+/**
+ * The revocation response.
+ *
+ * Metadata rather than an empty body, because the contract has no
+ * representation for one — `successStatusFor` yields 200 or 201 and every
+ * operation must declare a response schema. That constraint turns out to be the
+ * better answer anyway: returning the revoked credential lets a caller confirm
+ * *which* credential stopped working and when, which an empty 204 would make
+ * them ask for separately.
+ */
+export declare const credentialRevokedSchema: z.ZodObject<{
+    credential: z.ZodObject<{
+        createdAt: z.ZodString;
+        displayPrefix: z.ZodString;
+        environmentKind: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        issuedBy: z.ZodOptional<z.ZodString>;
+        lastUsedAt: z.ZodOptional<z.ZodString>;
+        project: z.ZodString;
+        revokedAt: z.ZodOptional<z.ZodString>;
+        supersededBy: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodArray<z.ZodEnum<{
+            "credentials:administer": "credentials:administer";
+            "credentials:read": "credentials:read";
+            "credentials:write": "credentials:write";
+            "endpoints:read": "endpoints:read";
+            "endpoints:write": "endpoints:write";
+            "forecast:read": "forecast:read";
+            "grants:read": "grants:read";
+            "grants:write": "grants:write";
+            "occurrences:read": "occurrences:read";
+            "occurrences:redeliver": "occurrences:redeliver";
+            "projects:read": "projects:read";
+            "projects:write": "projects:write";
+            "schedules:read": "schedules:read";
+            "schedules:write": "schedules:write";
+            "usage:read": "usage:read";
+        }>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CredentialRevokedResponse = z.infer<typeof credentialRevokedSchema>;
+/**
+ * Field-name fragments whose values must never reach a log, metric, or support
+ * index.
+ *
+ * Matched as substrings against a normalized key rather than by exact name.
+ * Exact matching caught `token` and missed `refreshToken`, `access_token`,
+ * `apiKey`, `client_secret` and `password` — which is most of what
+ * architecture section 10 actually requires be kept out of logs. Naming
+ * conventions vary across the codebase and across the libraries we log from,
+ * so the rule has to be insensitive to them.
+ */
+export declare const REDACTED_FIELD_FRAGMENTS: readonly ["authorization", "cookie", "credential", "key", "password", "secret", "signature", "token"];
+/**
+ * Fields redacted wholesale because they are content, not metadata.
+ *
+ * Architecture section 10 names callback bodies and prompts alongside
+ * payloads. Matched exactly rather than as fragments, so derived metadata like
+ * `bodyLength` still reaches a log. Note that a name containing a redacted
+ * fragment is still caught: `promptTokens` is redacted because it contains
+ * "token". Over-redacting a counter is the right side to err on.
+ */
+export declare const REDACTED_FIELDS_EXACT: readonly ["body", "data", "payload", "prompt"];
+/**
+ * Fields that contain "key" but are deliberately non-secret, and which
+ * observability depends on.
+ *
+ * `Callback-Key-Id` names *which* signing key was used and is the one thing
+ * needed to diagnose a rotation failure; `partitionKey` is a customer-facing
+ * forecast dimension; `idempotencyKey` is how a replay is traced. Redacting
+ * these would satisfy the letter of "hide secrets" while breaking the
+ * observability the architecture requires.
+ */
+export declare const NEVER_REDACTED: readonly ["callbackkeyid", "idempotencykey", "keyid", "partitionkey"];
+/**
+ * Redacts by field name, recursively, for structured logging.
+ *
+ * Customer callback payloads are content, not metadata: `data` and `payload`
+ * are redacted wholesale rather than sampled, because a scheduling payload is
+ * exactly the kind of thing that carries a customer's own secrets.
+ */
+export declare function redact(value: unknown): unknown;

package/dist/secrets.js

@@ -0,0 +1,272 @@
+import { z } from "zod";
+import { environmentKindSchema, scopeSchema } from "./authority.js";
+import { apiCredentialIdSchema, projectIdSchema } from "./identifiers.js";
+import { pageSchema } from "./protocol.js";
+import { durationSecondsSchema, timestampSchema } from "./time.js";
+/**
+ * Secret handling and redaction.
+ *
+ * A secret is shown exactly once, at creation. After that only its non-secret
+ * prefix and metadata are readable — by the API, by MCP tools, by the
+ * dashboard, and by support. There is no "reveal" endpoint, because a store
+ * that can reveal a secret is a store that can leak one.
+ */
+/** `pt_` + environment + `_` + public prefix. The secret half is never stored. */
+export const CREDENTIAL_PREFIX_PATTERN = /^pt_(?:live|test)_[0-9a-z]{8}$/u;
+/** How many characters of a credential are the non-secret display prefix. */
+export const CREDENTIAL_PREFIX_LENGTH = 16;
+/** How many characters of high-entropy secret follow the display prefix. */
+export const CREDENTIAL_SECRET_LENGTH = 32;
+/**
+ * A whole credential: the display prefix, followed immediately by the secret
+ * half. `pt_test_a1b2c3d4` is the prefix of `pt_test_a1b2c3d4<32 more>`, which
+ * is what lets a presented credential be looked up by prefix before anything is
+ * compared — a store that had to scan every row to find a candidate would leak
+ * timing, and a separator would be one more thing for a client to get wrong.
+ *
+ * **This pattern is enforced where credentials are issued and verified, and
+ * deliberately not by `credentialCreatedSchema` below.** A response schema is
+ * projected into a committed example, and an example matching this pattern is
+ * indistinguishable from a real credential to `npm run check:secrets`, which
+ * would refuse it — correctly. So the wire schema states the length floor, the
+ * issuer states the format, and the published example is visibly a placeholder.
+ */
+export const CREDENTIAL_SECRET_PATTERN = /^pt_(?:live|test)_[0-9a-z]{40}$/u;
+/**
+ * A credential as any read shape shows it: what it can do, where it can do it,
+ * and enough to recognise which one it is. Never the secret.
+ */
+export const credentialMetadataSchema = z.object({
+    createdAt: timestampSchema,
+    /** The non-secret leading segment, safe to display and log. */
+    displayPrefix: z.string().regex(CREDENTIAL_PREFIX_PATTERN),
+    /** Which environment of that project. Part of the credential's authority. */
+    environmentKind: environmentKindSchema,
+    /**
+     * When this credential stops verifying, present only after it is rotated.
+     *
+     * Distinct from `revokedAt` because the two say different things to whoever
+     * is debugging: an expiry is self-inflicted and scheduled — you rotated, and
+     * this is the deadline you were given — where a revocation is somebody
+     * deciding this credential should stop working now. Collapsing them would
+     * make a missed rotation window look like a security event.
+     */
+    expiresAt: timestampSchema.optional(),
+    id: apiCredentialIdSchema,
+    /**
+     * The member who issued it, when one is recorded.
+     *
+     * **Published because acting on somebody else's credential needs a wider
+     * scope, and a surface that could not say whose a credential is would have to
+     * discover that by being refused.** The value is the identifier the identity
+     * provider uses for that person; it names nobody outside the organization
+     * that already shares the credential's project.
+     *
+     * Absent on a credential issued before the issuer was recorded, and on one
+     * issued by anything that is not a signed-in member. An absent issuer is
+     * *nobody's* — it matches no member, so only a caller holding
+     * `credentials:administer` may rotate or revoke it.
+     */
+    issuedBy: z.string().min(1).optional(),
+    lastUsedAt: timestampSchema.optional(),
+    /** The project this credential is bound to for its whole life. */
+    project: projectIdSchema,
+    revokedAt: timestampSchema.optional(),
+    /**
+     * The credential that replaced this one, present only on a rotated
+     * credential. Read shapes carry it so a holder of the old credential can tell
+     * that a replacement exists without being able to use it — the id is not a
+     * secret, and it is what makes "why did this stop working" answerable.
+     */
+    supersededBy: apiCredentialIdSchema.optional(),
+    /**
+     * Exactly what it may do. Present on the read shape because a credential
+     * nobody can see the scopes of is a credential nobody can audit, and the
+     * scope list is not secret — holding it grants nothing.
+     */
+    scopes: z.array(scopeSchema).min(1),
+});
+/**
+ * A page of credentials.
+ *
+ * Built from `pageSchema` rather than written out, so paging is defined once:
+ * the cursor, the bounded limit and the freshness discriminator on this
+ * collection are the same ones every later collection gets, and a client that
+ * can page one can page all of them.
+ *
+ * The item is `credentialMetadataSchema` — the read shape — so there is no
+ * shape in the contract in which a list could carry a secret. That is a
+ * property of the type rather than of the query behind it.
+ */
+export const credentialPageSchema = pageSchema(credentialMetadataSchema);
+/**
+ * The one-time creation response. `secret` is present here and nowhere else in
+ * the contract; every read shape carries metadata only.
+ */
+export const credentialCreatedSchema = credentialMetadataSchema.extend({
+    secret: z.string().min(CREDENTIAL_PREFIX_LENGTH + CREDENTIAL_SECRET_LENGTH),
+    /** Always true, so a client cannot mistake this for a readable field. */
+    shownOnce: z.literal(true),
+});
+/**
+ * What a caller asks for when issuing a credential.
+ *
+ * `project` and `environmentKind` are caller-supplied and then *validated
+ * against the principal's organization* — they select within the caller's own
+ * tenancy rather than widening it, which is the same shape `resolveAuthority`
+ * already has. The organization is never here: that would be selecting a
+ * tenant, which `docs/contracts/v1-conventions.md` forbids outright.
+ */
+export const credentialRequestSchema = z.object({
+    environmentKind: environmentKindSchema,
+    project: projectIdSchema,
+    /**
+     * Requested scopes. The grant is the intersection of these, the credential
+     * policy, and the issuing member's current role — so asking for more than the
+     * role allows narrows the result rather than refusing it.
+     */
+    scopes: z.array(scopeSchema).min(1),
+});
+/**
+ * The longest a rotated credential may keep working, and its default.
+ *
+ * The number is a judgement rather than a derivation: long enough that a deploy
+ * can roll a new secret through every consumer, short enough that a leaked old
+ * secret stops being useful within a day. It is stated here rather than left in
+ * a route so that changing it is a contract change somebody reviews.
+ */
+export const CREDENTIAL_ROTATION_OVERLAP_SECONDS = 86_400;
+/**
+ * What a caller asks for when rotating.
+ *
+ * `overlapSeconds` may only *shorten* the window — the default is also the
+ * maximum. A caller who knows their consumers have already picked up the new
+ * secret can retire the old one immediately; nobody can ask for a longer tail
+ * than the contract allows, because the tail is the part that is dangerous.
+ *
+ * Zero is permitted and means the old credential stops verifying at once, which
+ * is deliberately not the same as revoking it: the audit trail records a
+ * rotation, and the retired credential names its replacement.
+ */
+export const credentialRotationRequestSchema = z.object({
+    overlapSeconds: durationSecondsSchema
+        .max(CREDENTIAL_ROTATION_OVERLAP_SECONDS, "must not exceed the maximum rotation overlap")
+        .optional(),
+});
+/**
+ * The rotation response: the replacement, and what became of the original.
+ *
+ * Both halves are here because a caller that only learned the new secret would
+ * have no way to know when the old one stops working, and the deadline is the
+ * whole point of an overlap. `retired` is metadata only — rotation never
+ * reveals a secret it did not just mint.
+ */
+export const credentialRotatedSchema = z.object({
+    credential: credentialCreatedSchema,
+    retired: credentialMetadataSchema,
+});
+/**
+ * The revocation response.
+ *
+ * Metadata rather than an empty body, because the contract has no
+ * representation for one — `successStatusFor` yields 200 or 201 and every
+ * operation must declare a response schema. That constraint turns out to be the
+ * better answer anyway: returning the revoked credential lets a caller confirm
+ * *which* credential stopped working and when, which an empty 204 would make
+ * them ask for separately.
+ */
+export const credentialRevokedSchema = z.object({
+    credential: credentialMetadataSchema,
+});
+/**
+ * Field-name fragments whose values must never reach a log, metric, or support
+ * index.
+ *
+ * Matched as substrings against a normalized key rather than by exact name.
+ * Exact matching caught `token` and missed `refreshToken`, `access_token`,
+ * `apiKey`, `client_secret` and `password` — which is most of what
+ * architecture section 10 actually requires be kept out of logs. Naming
+ * conventions vary across the codebase and across the libraries we log from,
+ * so the rule has to be insensitive to them.
+ */
+export const REDACTED_FIELD_FRAGMENTS = [
+    "authorization",
+    "cookie",
+    "credential",
+    "key",
+    "password",
+    "secret",
+    "signature",
+    "token",
+];
+/**
+ * Fields redacted wholesale because they are content, not metadata.
+ *
+ * Architecture section 10 names callback bodies and prompts alongside
+ * payloads. Matched exactly rather than as fragments, so derived metadata like
+ * `bodyLength` still reaches a log. Note that a name containing a redacted
+ * fragment is still caught: `promptTokens` is redacted because it contains
+ * "token". Over-redacting a counter is the right side to err on.
+ */
+export const REDACTED_FIELDS_EXACT = [
+    "body",
+    "data",
+    "payload",
+    "prompt",
+];
+/**
+ * Fields that contain "key" but are deliberately non-secret, and which
+ * observability depends on.
+ *
+ * `Callback-Key-Id` names *which* signing key was used and is the one thing
+ * needed to diagnose a rotation failure; `partitionKey` is a customer-facing
+ * forecast dimension; `idempotencyKey` is how a replay is traced. Redacting
+ * these would satisfy the letter of "hide secrets" while breaking the
+ * observability the architecture requires.
+ */
+export const NEVER_REDACTED = [
+    // The header spelling matters as much as the bare one: a log line carries
+    // `Callback-Key-Id` under its real name, which normalizes to
+    // `callbackkeyid` and would otherwise miss an exact-match allowlist and be
+    // caught by the `key` fragment — leaving rotation diagnosis blind, which is
+    // the exact failure this list exists to prevent.
+    "callbackkeyid",
+    "idempotencykey",
+    "keyid",
+    "partitionkey",
+];
+const REDACTION = "[redacted]";
+/** Lowercased with separators removed, so `access_token` and `accessToken` agree. */
+function normalizeKey(key) {
+    return key.toLowerCase().replace(/[_-]/gu, "");
+}
+function mustRedact(key) {
+    const normalized = normalizeKey(key);
+    // The allowlist wins, so broad fragment matching cannot swallow a field
+    // whose whole purpose is to be readable in a log. Matched whole, not as a
+    // suffix: `apiKeyId` ends with `keyid` and must still be redacted.
+    if (NEVER_REDACTED.some((allowed) => normalized === allowed)) {
+        return false;
+    }
+    return (REDACTED_FIELDS_EXACT.some((exact) => normalized === exact) ||
+        REDACTED_FIELD_FRAGMENTS.some((fragment) => normalized.includes(normalizeKey(fragment))));
+}
+/**
+ * Redacts by field name, recursively, for structured logging.
+ *
+ * Customer callback payloads are content, not metadata: `data` and `payload`
+ * are redacted wholesale rather than sampled, because a scheduling payload is
+ * exactly the kind of thing that carries a customer's own secrets.
+ */
+export function redact(value) {
+    if (Array.isArray(value)) {
+        return value.map(redact);
+    }
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, nested]) => [
+        key,
+        mustRedact(key) ? REDACTION : redact(nested),
+    ]));
+}