@pithy-sh/core 0.11.0 → 0.12.0

package/src/controlPlane/scope/scope.ts

@@ -85,13 +85,24 @@ export const KEYS_ROTATE_SCOPE: ControlPlaneScope = "keys:rotate";
  */
 export const MIGRATIONS_READ_SCOPE: ControlPlaneScope = "migrations:read";
 
+/**
+ * Read this Worker's full privacy inventory: every storage schema holding a marked field, each marked field's
+ * path, its class, and where it is stored (#132). Read-only — the one route behind it is a `GET`.
+ *
+ * **Its own scope rather than `manifest:read`**, because field names are the kind of thing an adopter may
+ * reasonably withhold from a client that has no business seeing them. The manifest's privacy block carries
+ * classes and counts only, so a connection without this one still sees the posture headline.
+ */
+export const PRIVACY_READ_SCOPE: ControlPlaneScope = "privacy:read";
+
 /**
  * The seam's base grant — what `pithy dashboard connect` grants whatever the Worker composes. Ping is absent
  * because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
  *
- * **{@link MIGRATIONS_READ_SCOPE} is absent on purpose.** It is a read — every route requiring it is a `GET`
- * — so `connect` derives it from the seam's `adminRoutes` the way it derives every capability's reads. The
- * base exists for `keys:rotate`, which is not a read and would otherwise drop out.
+ * **{@link MIGRATIONS_READ_SCOPE} and {@link PRIVACY_READ_SCOPE} are absent on purpose.** Each is a read —
+ * every route requiring it is a `GET` — so `connect` derives it from the seam's `adminRoutes` the way it
+ * derives every capability's reads. The base exists for `keys:rotate`, which is not a read and would
+ * otherwise drop out.
  */
 export const SEAM_SCOPES: readonly ControlPlaneScope[] = [MANIFEST_READ_SCOPE, KEYS_ROTATE_SCOPE];
 

package/src/controlPlane/token/base64url.ts

@@ -27,7 +27,7 @@ const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*$/;
 export function base64UrlEncode(bytes: Uint8Array): string {
   // Built one character at a time. `String.fromCharCode(...bytes)` overflows the argument stack on
   // inputs this seam genuinely sees — a request body digest, an exported key — so the loop is the
-  // implementation, not a style choice. (Same reason as `secrets/src/crypto/envelope.ts`.)
+  // implementation, not a style choice. (Same reason as `core/src/crypto/envelope.ts`.)
   let binary = "";
   for (const byte of bytes) binary += String.fromCharCode(byte);
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");

package/src/createBackend.ts

@@ -32,6 +32,7 @@ import type { Logger } from "./logger/logger";
 import { bindRequestContext, createWorkerLogger } from "./logger/worker";
 import type { RouteGroup } from "./openapi/document";
 import { recordRouteGroups } from "./openapi/routeGroups";
+import { refuseEncryptedKvStores } from "./privacy/encryptedColumns";
 import { HEALTH_PATH } from "./worker/health";
 import { workerVersion } from "./worker/identity";
 import { registeredWorkflowBinding } from "./workflow/bindings";
@@ -178,6 +179,9 @@ export function createBackend<
   // `@pithy-sh/i18n`'s middleware replaces it per request; nothing else ever does.
   const defaultTranslator = bakedTranslator(catalogFor(messages, DEFAULT_LOCALE));
   const namespaces = composeKv(all);
+  // An encrypted field in a KV store is refused here, at boot (#390): a KV envelope cannot be found by key version,
+  // so it could never be rotated. The refusal names the store, the field and D1.
+  refuseEncryptedKvStores(all);
   const workflows = composeWorkflows(all);
 
   // Each named database implies its D1 binding; each KV namespace implies its KV binding; each

package/src/crypto/envelope.ts

@@ -0,0 +1,196 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { InternalError } from "../error/pithyError";
+
+/**
+ * **The AES-256-GCM envelope: one primitive, two callers** (#390).
+ *
+ * It was `@pithy-sh/secrets`' own, ported from the CMS `secretsCrypto`, and it sealed that capability's rows and
+ * nothing else. Field encryption needs the same primitive inside an adopter's own Workers, and a capability may not
+ * depend on another's internals (principle 4), so it lives in core now and both callers import it from here. The
+ * format did not change: a row secrets sealed before the move opens after it, byte for byte.
+ *
+ * ## Two version axes
+ *
+ * `currentVersion` says which key seals new writes, and the `keyVersion` persisted on every envelope says which key
+ * opens it. A rotation adds a version, moves the pointer and keeps the old key until nothing is sealed under it, so
+ * a row opens under whichever version sealed it, for as long as that version is in the set. This is the
+ * *encryption-key* version. A secret's *value* version is a separate concern (`secrets/src/crypto/versionedValue.ts`).
+ *
+ * The config is the uniform `{ currentVersion, versions }` shape every versioned value uses, plus `lastRotatedAt`
+ * beside it as rotation metadata. Version keys are stringified integers, so reading the keys is a full-set read:
+ * every still-valid version, never the current one alone.
+ *
+ * ## The bound context is the caller's, and it is authenticated
+ *
+ * Every seal binds a **context** string as AES-GCM additional authenticated data. It is not encrypted; it is bound.
+ * Without it a ciphertext is valid under the key alone, so one lifted from one row and written into another opens
+ * cleanly, and every decision about which value a caller gets lives in the query above. With it, a moved ciphertext
+ * fails inside the primitive, however that query is later rewritten.
+ *
+ * The primitive takes the context whole, because what to bind is the caller's fact, not this module's:
+ *
+ * - `@pithy-sh/secrets` binds `pithy.secrets.v1:<stored name>` — exactly what it always bound.
+ * - A field marked `encrypted()` binds `pithy/enc/1:<declared name>:<field path>:<primary key>` (`../privacy/sealed`).
+ *
+ * Each prefix is versioned, so a later change to what is bound is a deliberate, visible break, and the two prefixes
+ * are distinct, so a secret's ciphertext never opens as a field and a field's never opens as a secret. **What is bound
+ * must be stable for the life of the ciphertext**: each caller states why its own context is.
+ *
+ * An empty context is refused on both halves. It binds nothing, and it would fail open rather than loudly.
+ */
+
+/** The key set a seal draws from: which version is current, every still-valid key, and when it last rotated. */
+export const EncryptionConfig = z
+  .object({
+    currentVersion: z
+      .string()
+      .meta({ multiline: false })
+      .describe("The version key (a stringified integer) whose key seals new writes — the active key."),
+    versions: z
+      // Every string leaf of a `json` secret says whether it fits on a terminal line, and a base64 key
+      // does. See `cli/promptPlan.ts`; held repo-wide by `packages/cli/src/ci/secretFieldLines.test.ts`.
+      .record(z.string(), z.string().meta({ multiline: false }))
+      .describe(
+        "Every still-valid key: version key (stringified integer) → base64-encoded AES-256 key. Holds the current key plus any prior versions still needed to open values not yet re-sealed.",
+      ),
+    lastRotatedAt: z.iso
+      .datetime()
+      .meta({ multiline: false })
+      .describe(
+        "ISO-8601 timestamp of the last rotation; the rotation cron compares against it to decide when to rotate.",
+      ),
+  })
+  .describe(
+    "A versioned AES-256 key set: the uniform versioned-value shape (currentVersion + versions) plus rotation metadata. Secrets' master key (`SECRETS_ENCRYPTION_KEYS`) and the field key (`PITHY_FIELD_KEYS`) both take it.",
+  );
+export type EncryptionConfig = z.output<typeof EncryptionConfig>;
+
+/**
+ * One AES-256-GCM envelope: base64 ciphertext, base64 IV, and the key version that sealed it.
+ *
+ * The bound context is deliberately not in here. It is supplied by the caller on the way back in, from the row's own
+ * identity, so a row that has been moved cannot carry its old context with it.
+ */
+export const EncryptedEnvelope = z
+  .object({
+    encryptedValue: z.string().min(1).describe("The AES-256-GCM ciphertext and tag, base64."),
+    iv: z.string().min(1).describe("The 12-byte initialization vector, base64. Fresh for every seal."),
+    keyVersion: z
+      .number()
+      .int()
+      .describe("The version of the key that sealed this value: the key set entry that opens it."),
+  })
+  .describe("An AES-256-GCM envelope: the ciphertext, its IV, and the key version that sealed it.");
+export type EncryptedEnvelope = z.output<typeof EncryptedEnvelope>;
+
+/** What the refusals name the key set by — its binding, so an operator knows which entry to inspect. */
+export interface EnvelopeOptions {
+  /** The binding the key set was read from, e.g. `SECRETS_ENCRYPTION_KEYS`. Defaults to `the key set`. */
+  keys?: string;
+}
+
+/** Base64-encode raw bytes without spreading into `fromCharCode` (stack-safe, lint-clean). */
+export function toBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** Decode base64 to raw bytes. */
+export function fromBase64(b64: string): Uint8Array<ArrayBuffer> {
+  return Uint8Array.from(atob(b64), (char) => char.charCodeAt(0));
+}
+
+/** The authenticated data for one seal. An empty context is refused: it would bind nothing. */
+function additionalData(context: string): Uint8Array<ArrayBuffer> {
+  if (context.length === 0) {
+    throw new InternalError({ detail: "the envelope needs a context to bind; an empty context binds nothing" });
+  }
+  // Copied through `from` so the view is backed by an `ArrayBuffer` rather than an `ArrayBufferLike`:
+  // workers-types types `encode` as the wider one, which no longer satisfies `BufferSource`.
+  return Uint8Array.from(new TextEncoder().encode(context));
+}
+
+/** The raw key bytes for `version`, or a refusal naming the key set. Never the key itself. */
+export function keyBytes(
+  config: EncryptionConfig,
+  version: number,
+  options: EnvelopeOptions = {},
+): Uint8Array<ArrayBuffer> {
+  const b64 = config.versions[String(version)];
+  if (!b64) {
+    throw new InternalError({
+      detail: `encryption key version ${version} not present in ${options.keys ?? "the key set"}`,
+    });
+  }
+  return fromBase64(b64);
+}
+
+/** Import the AES-GCM key for `version` from the config, or throw if that version is absent. */
+async function importKey(
+  config: EncryptionConfig,
+  version: number,
+  usage: ("encrypt" | "decrypt")[],
+  options: EnvelopeOptions,
+): Promise<CryptoKey> {
+  return crypto.subtle.importKey("raw", keyBytes(config, version, options), "AES-GCM", false, usage);
+}
+
+/**
+ * Seal `plaintext` under the config's current key version, binding `context`. The IV is 12 fresh random bytes, so
+ * two seals of one value never share a ciphertext.
+ */
+export async function encryptValue(
+  config: EncryptionConfig,
+  context: string,
+  plaintext: string,
+  options: EnvelopeOptions = {},
+): Promise<EncryptedEnvelope> {
+  const aad = additionalData(context);
+  const keyVersion = Number(config.currentVersion);
+  const key = await importKey(config, keyVersion, ["encrypt"], options);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: aad },
+    key,
+    new TextEncoder().encode(plaintext),
+  );
+  return { encryptedValue: toBase64(new Uint8Array(ciphertext)), iv: toBase64(iv), keyVersion };
+}
+
+/**
+ * Open an envelope sealed under `context`. The key version may differ from `currentVersion` during a rotation window;
+ * the matching key must still be in the config.
+ *
+ * A missing key version, a tampered ciphertext, the wrong key, or a ciphertext sealed under another context all throw
+ * — never the plaintext or key material. GCM cannot tell those apart, and separating them for the caller would be an
+ * oracle: the `detail` names the context the open was *attempted under*, which is what an operator needs. Each caller
+ * binds a context composed from validated identifiers, so it is safe in a log; neither binds a value.
+ */
+export async function decryptValue(
+  config: EncryptionConfig,
+  context: string,
+  envelope: EncryptedEnvelope,
+  options: EnvelopeOptions = {},
+): Promise<string> {
+  const aad = additionalData(context);
+  const key = await importKey(config, envelope.keyVersion, ["decrypt"], options);
+  try {
+    const plaintext = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: fromBase64(envelope.iv), additionalData: aad },
+      key,
+      fromBase64(envelope.encryptedValue),
+    );
+    return new TextDecoder().decode(plaintext);
+  } catch (cause) {
+    throw new InternalError(
+      {
+        detail: `AES-GCM decrypt failed for '${context}' under key version ${envelope.keyVersion}: wrong key, tampered ciphertext, or a ciphertext sealed under a different context`,
+      },
+      { cause },
+    );
+  }
+}

package/src/crypto/fieldKeys.ts

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { remedy } from "../cli/command";
+import { InternalError } from "../error/pithyError";
+import { EncryptionConfig } from "./envelope";
+
+/**
+ * **The field key: what an app Worker seals its encrypted fields with** (#390).
+ *
+ * `PITHY_FIELD_KEYS` is an {@link EncryptionConfig}, the same versioned shape as secrets' master key, and it is a
+ * **different key on purpose**. Field encryption seals and opens inside the adopter's own Workers, so every Worker that
+ * holds an encrypted field must hold the key it uses. Were that the master key `SECRETS_ENCRYPTION_KEYS`, every such
+ * Worker would hold the key to the whole secrets vault, and one compromised would open it. A key of its own limits
+ * that to the fields: a Worker that holds an encrypted field and composes no `secrets` is bound this key and never
+ * the master key.
+ *
+ * It is not a second mechanism: `pithy secrets provision` mints it beside the master key, in the same format, binds
+ * it to every Worker that holds an encrypted field, and the manager's at-rest cron rotates it every
+ * {@link FIELD_KEY_ROTATION_DAYS} days.
+ */
+
+/** The binding an app Worker reads its field key through. Fixed across environments; only the store entry is scoped. */
+export const FIELD_KEYS_BINDING = "PITHY_FIELD_KEYS";
+
+/** How often the manager rotates the field key, in days. */
+export const FIELD_KEY_ROTATION_DAYS = 30;
+
+/** A Secrets Store binding: `.get()` resolves the plaintext inside the Worker. */
+export interface FieldKeyBinding {
+  get(): Promise<string>;
+}
+
+/**
+ * Where a field key comes from: the Worker's `env.PITHY_FIELD_KEYS` binding (a Secrets Store binding deployed, a JSON
+ * string from `.dev.vars` locally), or a config a caller already resolved.
+ */
+export type FieldKeys = FieldKeyBinding | string | EncryptionConfig;
+
+/**
+ * Resolve a field key to its config. A missing binding, text that is not JSON, and JSON that is not a key set are each
+ * refused, and **nothing read is ever echoed**: what failed to parse is the key set.
+ */
+export async function resolveFieldKeys(keys: FieldKeys | undefined): Promise<EncryptionConfig> {
+  let raw: unknown = keys;
+  if (keys === undefined || keys === null) {
+    throw new InternalError({
+      message: "This Worker holds an encrypted field and no field key.",
+      action: `Bind ${FIELD_KEYS_BINDING}. ${remedy("secrets provision").say((command) => `${command} binds it to every Worker with an encrypted field.`)}`,
+      detail: `${FIELD_KEYS_BINDING} binding is not configured`,
+    });
+  }
+  if (typeof keys === "object" && "get" in keys && typeof keys.get === "function") raw = await keys.get();
+  if (typeof raw === "string") {
+    try {
+      raw = JSON.parse(raw);
+    } catch {
+      throw new InternalError({ detail: `${FIELD_KEYS_BINDING} is not valid JSON` });
+    }
+  }
+  const parsed = EncryptionConfig.safeParse(raw);
+  if (!parsed.success) throw new InternalError({ detail: `${FIELD_KEYS_BINDING} is not a valid EncryptionConfig` });
+  return parsed.data;
+}
+
+/**
+ * Every live version in a key set, newest first, as numbers. A version key that is not an integer is refused rather
+ * than sorted as text, where `"10"` sorts before `"9"`.
+ */
+export function liveVersions(config: EncryptionConfig): number[] {
+  const versions = Object.keys(config.versions).map(Number);
+  if (!versions.every((version) => Number.isInteger(version))) {
+    throw new InternalError({ detail: `${FIELD_KEYS_BINDING}: a version key is not a stringified integer` });
+  }
+  return versions.sort((left, right) => right - left);
+}

package/src/data/codecs.ts

@@ -85,46 +85,78 @@ export const JsonDate = z.codec(z.union([z.string(), z.number(), z.date()]), z.d
 });
 
 /**
- * sqliteJson: T ↔ JSON string, validated by `schema` on both sides. Decode
- * accepts a JSON string or an already-parsed value; the result is validated
- * against `schema` before it reaches the app.
+ * sqliteJson's decode: a JSON string is parsed, an already-parsed value passes through. One function for every
+ * column, so `isSqliteJson` can tell the kit's codec from any other by its decode.
  *
- * **Both `JSON` functions throw**, and both were reachable. `JSON.parse` throws a
- * `SyntaxError` on any string that is not a JSON document — which a column holding
- * text an older writer put there, or a payload a customer's Worker returned, can be.
- * `JSON.stringify` throws a `TypeError` on a `BigInt` and on a cycle, either of
- * which a `schema` can legitimately admit. Both become an issue (#358).
+ * **`JSON.parse` throws**, and it was reachable: a column holding text an older writer put there, or a payload a
+ * customer's Worker returned, need not be a JSON document. That becomes an issue (#358).
  */
-export function sqliteJson<T extends z.ZodType>(schema: T) {
-  return z.codec(z.union([z.string(), schema]), schema, {
-    decode: (value, payload): z.input<T> => {
-      if (typeof value !== "string") return value as z.input<T>;
-      try {
-        return JSON.parse(value) as z.input<T>;
-      } catch {
-        payload.issues.push({ code: "invalid_format", format: "json", input: value, message: "Not valid JSON." });
-        return z.NEVER;
-      }
-    },
-    encode: (value, payload): string => {
-      // The offending value is deliberately not carried onto the issue: it is the thing JSON could not
-      // hold, so a reporter that renders an issue would be the second place to trip over it.
-      try {
-        const json = JSON.stringify(value);
-        if (typeof json === "string") return json;
-      } catch {
-        // Falls through to the one push below. A `BigInt`, a cycle and an `undefined` result are the
-        // same answer — this value does not survive the round trip — and they deserve the same issue.
-      }
-      payload.issues.push({
-        code: "invalid_format",
-        format: "json",
-        input: undefined,
-        message: "Not serializable as JSON.",
-      });
-      return z.NEVER;
-    },
+function decodeJson(value: unknown, payload: Payload<unknown>): unknown {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    payload.issues.push({ code: "invalid_format", format: "json", input: value, message: "Not valid JSON." });
+    return z.NEVER;
+  }
+}
+
+/**
+ * sqliteJson's encode. **`JSON.stringify` throws** on a `BigInt` and on a cycle, either of which a schema can
+ * legitimately admit, so that becomes an issue too (#358).
+ */
+function encodeJson(value: unknown, payload: Payload<unknown>): string {
+  // The offending value is deliberately not carried onto the issue: it is the thing JSON could not hold, so a
+  // reporter that renders an issue would be the second place to trip over it.
+  try {
+    const json = JSON.stringify(value);
+    if (typeof json === "string") return json;
+  } catch {
+    // Falls through to the one push below. A `BigInt`, a cycle and an `undefined` result are the same answer —
+    // this value does not survive the round trip — and they deserve the same issue.
+  }
+  payload.issues.push({
+    code: "invalid_format",
+    format: "json",
+    input: undefined,
+    message: "Not serializable as JSON.",
   });
+  return z.NEVER;
+}
+
+/**
+ * sqliteJson: T ↔ JSON string, validated by `schema` on both sides. Decode accepts a JSON string or an
+ * already-parsed value; the result is validated against `schema` before it reaches the app.
+ */
+export function sqliteJson<T extends z.ZodType>(schema: T): SqliteJson<T> {
+  return z.codec(z.union([z.string(), schema]), schema, {
+    decode: decodeJson as (value: string | z.output<T>, payload: Payload<string | z.output<T>>) => z.input<T>,
+    encode: encodeJson as (value: z.input<T>, payload: Payload<z.input<T>>) => string,
+  }) as SqliteJson<T>;
+}
+
+/**
+ * Names the type `sqliteJson` returns, and nothing else. A type only: no value carries it. `Redacted<T>` reads a JSON
+ * column's fields through it, as `redact` reads them through {@link isSqliteJson}, so an adopter's codec of the same
+ * shape is opaque to both.
+ */
+declare const kitJsonColumn: unique symbol;
+
+/** What `sqliteJson(schema)` returns: the kit's JSON column over `schema`. Clones keep it, as they return `this`. */
+export type SqliteJson<T extends z.ZodType> = z.ZodCodec<z.ZodUnion<[z.ZodString, T]>, T> & {
+  readonly [kitJsonColumn]: T;
+};
+
+/** The schema a kit JSON column decodes to, or `never` for any other node. */
+export type SqliteJsonSchema<S> = S extends { readonly [kitJsonColumn]: infer T } ? T : never;
+
+/**
+ * Whether a schema is a JSON column `sqliteJson` built, or a clone of one (`.describe()`, `.meta()`), read by its
+ * decode. `redact` walks such a column's fields one by one, and treats every other codec as opaque.
+ */
+export function isSqliteJson(schema: z.ZodType): boolean {
+  const def = schema._zod.def as { type: string; transform?: unknown };
+  return def.type === "pipe" && def.transform === decodeJson;
 }
 
 export const MAX_TIMEZONE_LENGTH = 64;

package/src/error/extend.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import type { MessageParams } from "../i18n/catalog";
+import type { UnmarkedString } from "../privacy/types";
 import type { ErrorPayload, KitErrorDomain } from "./payload";
 import { ExtendedErrorPayload } from "./payload";
 import { InternalError } from "./pithyError";
@@ -95,11 +96,11 @@ export function defineErrorPayload<const Code extends `${string}/${string}`>(
     /** The HTTP status this code maps to. A 4xx or a 5xx — an error is not a success. */
     status: number;
     /** Public, safe-to-expose summary. Sent to clients and shown in the terminal. */
-    message: string;
-    /** Operator remediation hint. Becomes the CLI action line. Never sent to a client. */
-    action?: string;
-    /** Internal context for logs + audit. NEVER serialized to clients — the HTTP codec strips it. */
-    detail?: string;
+    message: UnmarkedString;
+    /** Operator remediation hint. Becomes the CLI action line. Never sent to a client. Never a marked value (#132). */
+    action?: UnmarkedString;
+    /** Internal context for logs + audit. NEVER serialized to clients — the HTTP codec strips it. Never a marked value (#132). */
+    detail?: UnmarkedString;
     /**
      * Values a translating client interpolates into its own wording for this code. Client-facing:
      * these cross the boundary with `message`, unlike `action` and `detail`.

package/src/error/payload.ts

@@ -181,6 +181,38 @@ const AuthSessionNotFreshPublic = z
   })
   .describe("The session is authentic but the holder authenticated too long ago to attach a provider (403).");
 
+const AuthAccountSuspendedPublic = z
+  .object({
+    code: z
+      .literal("auth/account_suspended")
+      .describe(
+        "The account this credential belongs to is suspended, so the request is refused whatever it carries. An operator suspended it on purpose, with a reason, and the reason is the `message`. When the suspension has an end, `params.suspendedUntil` names it as ISO-8601; a suspension past its end is no longer one, and nothing has to clear it. A separate code from `auth/forbidden` so a client can render the screen that says what happened rather than a generic refusal.",
+      ),
+    status: z
+      .literal(403)
+      .describe(
+        "Forbidden — the credential is genuine and the account behind it may not act. Not 401: signing in again cannot help, and a client that read it as an expired token would loop.",
+      ),
+    ...publicFields,
+  })
+  .describe("The account is suspended (403).");
+
+const AuthAccountDeletedPublic = z
+  .object({
+    code: z
+      .literal("auth/account_deleted")
+      .describe(
+        "The account this credential belongs to is deleted and inside its purge window: it cannot sign in or act, and it can still be restored until the window closes. After the purge there is no account, and the credential is simply invalid.",
+      ),
+    status: z
+      .literal(403)
+      .describe(
+        "Forbidden — the account exists and may not act. Not 404, because until the purge runs it can come back, and not 401, because signing in again cannot help.",
+      ),
+    ...publicFields,
+  })
+  .describe("The account is deleted and awaiting its purge (403).");
+
 const NotFoundPublic = z
   .object({
     code: z.literal("core/not_found").describe("The requested resource does not exist."),
@@ -1758,6 +1790,8 @@ export const KitPublicErrorPayload = z
     ForbiddenPublic,
     AuthProviderUnavailablePublic,
     AuthSessionNotFreshPublic,
+    AuthAccountSuspendedPublic,
+    AuthAccountDeletedPublic,
     NotFoundPublic,
     ConflictPublic,
     RateLimitPublic,
@@ -1914,6 +1948,12 @@ const AuthProviderUnavailable = AuthProviderUnavailablePublic.extend(internalFie
 const AuthSessionNotFresh = AuthSessionNotFreshPublic.extend(internalFields).describe(
   AuthSessionNotFreshPublic.description ?? "",
 );
+const AuthAccountSuspended = AuthAccountSuspendedPublic.extend(internalFields).describe(
+  AuthAccountSuspendedPublic.description ?? "",
+);
+const AuthAccountDeleted = AuthAccountDeletedPublic.extend(internalFields).describe(
+  AuthAccountDeletedPublic.description ?? "",
+);
 const NotFound = NotFoundPublic.extend(internalFields).describe(NotFoundPublic.description ?? "");
 const Conflict = ConflictPublic.extend(internalFields).describe(ConflictPublic.description ?? "");
 const RateLimit = RateLimitPublic.extend(internalFields).describe(RateLimitPublic.description ?? "");
@@ -2311,6 +2351,8 @@ export const KitErrorPayload = z
     Forbidden,
     AuthProviderUnavailable,
     AuthSessionNotFresh,
+    AuthAccountSuspended,
+    AuthAccountDeleted,
     NotFound,
     Conflict,
     RateLimit,

package/src/error/pithyError.ts

@@ -3,6 +3,7 @@
 
 import type { z } from "zod";
 import type { MessageParams } from "../i18n/catalog";
+import type { UnmarkedString } from "../privacy/types";
 import type { ValidationIssue } from "./payload";
 import { ErrorPayload } from "./payload";
 
@@ -18,7 +19,20 @@ import { ErrorPayload } from "./payload";
 export class PithyError extends Error {
   readonly payload: ErrorPayload;
 
-  constructor(payload: ErrorPayload, options?: { cause?: unknown }) {
+  /**
+   * `message`, `action` and `detail` are each an {@link UnmarkedString} here and on every subclass's arguments
+   * (#132): a value marked with a privacy class is refused at compile time, because all three ride into every log
+   * line and audit row that carries this error. A template literal is a plain `string`, so interpolation is not caught — see
+   * `privacy/types.ts` for exactly what is.
+   */
+  constructor(
+    payload: ErrorPayload & {
+      message: UnmarkedString;
+      action?: UnmarkedString | undefined;
+      detail?: UnmarkedString | undefined;
+    },
+    options?: { cause?: unknown },
+  ) {
     const parsed = ErrorPayload.parse(payload);
     super(parsed.message, options);
     this.payload = parsed;
@@ -28,12 +42,12 @@ export class PithyError extends Error {
 
 /** Variable parts every subclass accepts; the `code`/`status` are fixed by the subclass. */
 interface ErrorArgs {
-  /** Override the public, safe-to-expose message. Defaults to a per-code summary. */
-  message?: string;
-  /** A remediation hint (CLI action line). */
-  action?: string;
-  /** Internal context for logs + audit. Never serialized to clients. */
-  detail?: string;
+  /** Override the public, safe-to-expose message. Defaults to a per-code summary. Never a privacy-marked value. */
+  message?: UnmarkedString;
+  /** A remediation hint (CLI action line). Never a privacy-marked value. */
+  action?: UnmarkedString;
+  /** Internal context for logs + audit. Never serialized to clients, and never a privacy-marked value (#132). */
+  detail?: UnmarkedString;
   /**
    * Values a translating client interpolates into its own wording for this code. Client-facing, so —
    * unlike `action` and `detail` — these cross the boundary with `message`. The `code` is the catalog

package/src/index.ts

@@ -102,6 +102,7 @@ export {
   KEYS_ROTATE_SCOPE,
   MANIFEST_READ_SCOPE,
   MIGRATIONS_READ_SCOPE,
+  PRIVACY_READ_SCOPE,
   SEAM_SCOPES,
 } from "./controlPlane/scope/scope";
 export { exportPublicJwk, type MintControlPlaneToken, mintControlPlaneToken } from "./controlPlane/token/mint";

package/src/logger/logger.ts

@@ -3,6 +3,7 @@
 
 import type { ErrorPayload } from "../error/payload";
 import { PithyError } from "../error/pithyError";
+import type { Loggable, UnmarkedString } from "../privacy/types";
 import { LOG_LEVEL_ORDER, type LogFields, type LogLevel, type LogRecord } from "./record";
 
 /**
@@ -15,22 +16,28 @@ import { LOG_LEVEL_ORDER, type LogFields, type LogLevel, type LogRecord } from "
  * The reserved `error` field on any call may carry a `PithyError` or `ErrorPayload` — the engine lifts
  * it into the record's `error`, `detail` and all. A log is internal; this is the inverse of the HTTP
  * codec, which strips `detail`. The logger must never be wired to a client-facing surface.
+ *
+ * **A value marked with a privacy class does not compile here** (#132). Every method takes `F & Loggable<F>`,
+ * so a field holding a `pii()`/`phi()`/`secret()`/`pci()` value — the value itself, or one inside an object or
+ * an array, to the depth `privacy/types.ts` states — is refused at that key, and `redact(Schema, value)` is the
+ * way through. The message and a child's name take `UnmarkedString`, so `log.info(user.email)` is refused too. `LogFields` the schema stays permissive: a record that reaches a sink at runtime still parses,
+ * because a brand is a type and a parsed log line has none.
  */
 export interface Logger {
   /** Dev-time diagnostics. Dropped unless the logger's level is `debug`. */
-  debug(msg: string, fields?: LogFields): void;
+  debug<F extends LogFields = LogFields>(msg: UnmarkedString, fields?: F & Loggable<F>): void;
   /** Normal operational events. */
-  info(msg: string, fields?: LogFields): void;
+  info<F extends LogFields = LogFields>(msg: UnmarkedString, fields?: F & Loggable<F>): void;
   /** A recoverable problem worth attention. */
-  warn(msg: string, fields?: LogFields): void;
+  warn<F extends LogFields = LogFields>(msg: UnmarkedString, fields?: F & Loggable<F>): void;
   /** A failure that was observed. Pass `{ error }` (a PithyError) to carry its full payload. */
-  error(msg: string, fields?: LogFields): void;
+  error<F extends LogFields = LogFields>(msg: UnmarkedString, fields?: F & Loggable<F>): void;
   /**
    * A namespaced sub-logger. `name` composes as `parent:child`; bound `fields` merge into every record
    * the child emits. Omit `name` (pass `undefined`) to bind fields only — how request-correlation
    * attaches `request`/`method`/`path` without renaming the logger.
    */
-  child(name?: string, fields?: LogFields): Logger;
+  child<F extends LogFields = LogFields>(name?: UnmarkedString, fields?: F & Loggable<F>): Logger;
 }
 
 /** A sink receives a finished {@link LogRecord}. Adapters supply one; the engine builds records and calls it. */