@pithy-sh/core 0.13.0 → 0.15.0

package/src/controlPlane/data/connections.ts

@@ -0,0 +1,231 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { sql } from "kysely";
+import { ConflictError } from "../../error/pithyError";
+import { type ConnectionCredentialKind, ControlPlaneConnection, type RegisteredKey } from "./connection";
+import { activeKeys } from "./keyLifecycle";
+import { activeTrusts, type OidcTrust } from "./oidcTrust";
+import { CONTROL_PLANE_CONNECTIONS_TABLE, type ControlPlaneDatabase } from "./tables";
+
+/**
+ * Every connection in one database, read for a review: which person authorized each, and which still answer.
+ *
+ * `GET {basePath}/connections` and `pithy dashboard connections` both read through {@link listConnections}, so the
+ * Worker's answer and the CLI's cannot list different things.
+ */
+
+/** Which credential kinds a connection holds, live or not. */
+export function connectionCredentialKind(connection: ControlPlaneConnection): ConnectionCredentialKind {
+  const keys = connection.keys.length > 0;
+  const trusts = (connection.trusts ?? []).length > 0;
+  if (keys && trusts) return "both";
+  if (keys) return "key";
+  if (trusts) return "trust";
+  return "none";
+}
+
+/** Whether any key or trust on the connection can verify a call at `now`. */
+export function connectionLive(connection: ControlPlaneConnection, now: Date): boolean {
+  return activeKeys(connection.keys, now).length > 0 || activeTrusts(connection.trusts ?? [], now).length > 0;
+}
+
+/**
+ * When the connection was revoked: the latest revocation among its credentials, once none is live and every one of
+ * them was revoked. Null while anything is live, and for a connection whose keys merely expired.
+ */
+export function connectionRevokedAt(connection: ControlPlaneConnection, now: Date): Date | null {
+  if (connectionLive(connection, now)) return null;
+  const credentials = [...connection.keys, ...(connection.trusts ?? [])];
+  if (credentials.length === 0) return null;
+  let latest: Date | null = null;
+  for (const credential of credentials) {
+    if (credential.revokedAt === null) return null;
+    if (latest === null || credential.revokedAt.getTime() > latest.getTime()) latest = credential.revokedAt;
+  }
+  return latest;
+}
+
+/** What {@link revokeCredentials} changed. */
+export interface RevokedCredentials {
+  /** The connection with every key and trust not yet revoked revoked at `now`. */
+  readonly connection: ControlPlaneConnection;
+  readonly revokedKeyIds: readonly string[];
+  readonly revokedTrustIds: readonly string[];
+}
+
+/**
+ * Revoke every key and trust not yet revoked, whatever its window. One that has not started will verify once its
+ * window opens, and the revoker's clock may run behind the Worker that stamped it, so it is revoked too. A credential
+ * already revoked keeps its instant.
+ */
+export function revokeCredentials(connection: ControlPlaneConnection, now: Date): RevokedCredentials {
+  const keyIds = connection.keys.filter((key) => key.revokedAt === null).map((key) => key.keyId);
+  const trustIds = (connection.trusts ?? []).filter((trust) => trust.revokedAt === null).map((trust) => trust.trustId);
+  return {
+    connection: {
+      ...connection,
+      keys: connection.keys.map((key) => (key.revokedAt === null ? { ...key, revokedAt: now } : key)),
+      trusts: (connection.trusts ?? []).map((trust) =>
+        trust.revokedAt === null ? { ...trust, revokedAt: now } : trust,
+      ),
+      updatedAt: keyIds.length + trustIds.length > 0 ? now : connection.updatedAt,
+    },
+    revokedKeyIds: keyIds,
+    revokedTrustIds: trustIds,
+  };
+}
+
+/** Whether a connection was authorized by `principal`. An email, compared without regard to case. */
+export function authorizedByPrincipal(connection: ControlPlaneConnection, principal: string): boolean {
+  return connection.authorizedBy !== null && connection.authorizedBy.toLowerCase() === principal.toLowerCase();
+}
+
+/** Which connections {@link listConnections} reads. */
+export interface ConnectionFilter {
+  /** Only connections this email authorized. Unattributed connections are listed apart either way. */
+  readonly principal?: string | undefined;
+  /** Only connections bound to this environment. */
+  readonly environment?: string | undefined;
+}
+
+/** The connections a filter selects, with the ones no principal was recorded for kept apart. */
+export interface ConnectionListing {
+  /** Connections with a recorded principal, matching the filter, oldest first. */
+  readonly connections: readonly ControlPlaneConnection[];
+  /** Connections registered before principals were recorded, oldest first. Never matched by a principal. */
+  readonly unattributed: readonly ControlPlaneConnection[];
+}
+
+/** Every connection in the database, attributed ones matching the filter, unattributed ones apart. */
+export async function listConnections(
+  db: ControlPlaneDatabase,
+  filter: ConnectionFilter = {},
+): Promise<ConnectionListing> {
+  let query = db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().orderBy("createdAt").orderBy("id");
+  if (filter.environment !== undefined) query = query.where("environment", "=", filter.environment);
+  const rows = (await query.execute()).map((row) => ControlPlaneConnection.parse(row));
+  const { principal } = filter;
+  return {
+    connections: rows.filter(
+      (row) => row.authorizedBy !== null && (principal === undefined || authorizedByPrincipal(row, principal)),
+    ),
+    unattributed: rows.filter((row) => row.authorizedBy === null),
+  };
+}
+
+/** Read one connection by id, or null. */
+export async function readConnection(db: ControlPlaneDatabase, id: string): Promise<ControlPlaneConnection | null> {
+  const row = await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().where("id", "=", id).executeTakeFirst();
+  return row ? ControlPlaneConnection.parse(row) : null;
+}
+
+/**
+ * A connection read for a write to its credential columns, with those columns exactly as stored. A write made from it
+ * lands only while they are unchanged, so a revocation landing in between is never overwritten.
+ */
+export interface ConnectionForWrite {
+  readonly connection: ControlPlaneConnection;
+  /** The keys column as stored, compared as stored. */
+  readonly storedKeys: unknown;
+  /** The trusts column as stored, compared as stored. */
+  readonly storedTrusts: unknown;
+}
+
+/** Read one connection by id for a write, or null. With `environment`, null for a connection bound to another. */
+export async function readConnectionForWrite(
+  db: ControlPlaneDatabase,
+  id: string,
+  options: { readonly environment?: string | undefined } = {},
+): Promise<ConnectionForWrite | null> {
+  let query = db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().where("id", "=", id);
+  if (options.environment !== undefined) query = query.where("environment", "=", options.environment);
+  const row = await query.executeTakeFirst();
+  if (!row) return null;
+  return { connection: ControlPlaneConnection.parse(row), storedKeys: row.keys, storedTrusts: row.trusts };
+}
+
+/**
+ * Write a connection's keys and stamp `updatedAt`, only while its keys column still holds what `read` saw. False
+ * when it no longer does: another write, a revocation among them, landed in between and nothing was written.
+ */
+export async function writeKeys(
+  db: ControlPlaneDatabase,
+  read: ConnectionForWrite,
+  keys: readonly RegisteredKey[],
+  now: Date,
+): Promise<boolean> {
+  const result = await db
+    .updateTable(CONTROL_PLANE_CONNECTIONS_TABLE)
+    .set({
+      keys: ControlPlaneConnection.shape.keys.encode([...keys]),
+      updatedAt: ControlPlaneConnection.shape.updatedAt.encode(now),
+    })
+    .where("id", "=", read.connection.id)
+    .where(sql<boolean>`${sql.ref("keys")} = ${read.storedKeys}`)
+    .executeTakeFirst();
+  return Number(result.numUpdatedRows) > 0;
+}
+
+/** The credential columns a {@link writeCredentials} call replaces. A column left out is not written. */
+export interface CredentialColumns {
+  readonly keys?: readonly RegisteredKey[] | undefined;
+  readonly trusts?: readonly OidcTrust[] | undefined;
+}
+
+/**
+ * Write the given credential columns and stamp `updatedAt`, only while both the keys and the trusts columns still hold
+ * what `read` saw. False when either changed in between, and nothing was written.
+ */
+export async function writeCredentials(
+  db: ControlPlaneDatabase,
+  read: ConnectionForWrite,
+  columns: CredentialColumns,
+  now: Date,
+): Promise<boolean> {
+  const result = await db
+    .updateTable(CONTROL_PLANE_CONNECTIONS_TABLE)
+    .set({
+      ...(columns.keys === undefined ? {} : { keys: ControlPlaneConnection.shape.keys.encode([...columns.keys]) }),
+      ...(columns.trusts === undefined
+        ? {}
+        : { trusts: ControlPlaneConnection.shape.trusts.encode([...columns.trusts]) }),
+      updatedAt: ControlPlaneConnection.shape.updatedAt.encode(now),
+    })
+    .where("id", "=", read.connection.id)
+    .where(sql<boolean>`${sql.ref("keys")} = ${read.storedKeys}`)
+    .where(sql<boolean>`${sql.ref("trusts")} = ${read.storedTrusts}`)
+    .executeTakeFirst();
+  return Number(result.numUpdatedRows) > 0;
+}
+
+/** How many times {@link revokeConnection} reads again after a write landed between its read and its own. */
+const REVOKE_ATTEMPTS = 5;
+
+/**
+ * Revoke every key and trust of one connection not yet revoked, or answer null when no connection has that id. With
+ * `environment`, a connection bound to another environment answers null too.
+ *
+ * Writes the two credential columns and the stamp and nothing else on the row, and only while both columns still
+ * hold what it read; when another write landed in between, it reads again.
+ */
+export async function revokeConnection(
+  db: ControlPlaneDatabase,
+  id: string,
+  now: Date,
+  options: { readonly environment?: string | undefined } = {},
+): Promise<RevokedCredentials | null> {
+  for (let attempt = 0; attempt < REVOKE_ATTEMPTS; attempt++) {
+    const read = await readConnectionForWrite(db, id, options);
+    if (read === null) return null;
+    const revoked = revokeCredentials(read.connection, now);
+    if (revoked.revokedKeyIds.length + revoked.revokedTrustIds.length === 0) return revoked;
+    const columns = { keys: revoked.connection.keys, trusts: revoked.connection.trusts ?? [] };
+    if (await writeCredentials(db, read, columns, now)) return revoked;
+  }
+  throw new ConflictError({
+    message: "The connection kept changing while it was being revoked.",
+    action: "Revoke it again.",
+    detail: `connection ${id} changed between read and write ${REVOKE_ATTEMPTS} times`,
+  });
+}

package/src/controlPlane/data/hold.ts

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { SQLiteDate } from "../../data/codecs";
+
+/**
+ * **A legal hold: one subject preserved, with the reason it was placed and, once released, why.**
+ *
+ * Placed and released over the control plane, behind `retention:hold`, because a hold is operational and urgent:
+ * counsel says preserve everything about this customer, and the next scheduled purge is tonight. While a hold stands
+ * no purge, prune or inactivity deletion touches its subject. Released holds are kept — the row is the record that
+ * one stood, from when to when, and why it ended — so nothing here is ever deleted.
+ */
+
+/** What a hold preserves: one user, one organization, or one tenant's audit trail. */
+export const HoldSubjectType = z
+  .enum(["user", "organization", "audit"])
+  .describe(
+    "What the hold preserves: `user`, one account and everything its purge would erase; `organization`, one tenant and everything its purge would erase; `audit`, one tenant's audit trail, which the prune then leaves whole.",
+  );
+export type HoldSubjectType = z.infer<typeof HoldSubjectType>;
+
+/** Whether a hold is in force. */
+export const HoldState = z
+  .enum(["active", "released"])
+  .describe("`active` while the hold stands; `released` once it has been lifted, with the reason.");
+export type HoldState = z.infer<typeof HoldState>;
+
+/** One hold, as `pithy_controlplane_holds` stores it. */
+export const LegalHold = z
+  .object({
+    id: z.string().min(1).describe("The hold's id. Text, never a sequence: it is named on a release route."),
+    subjectType: HoldSubjectType,
+    subjectId: z
+      .string()
+      .min(1)
+      .max(255)
+      .nullable()
+      .describe(
+        "The held user's or organization's id, or the tenant whose audit trail is held. Null only for an `audit` hold on the untenanted trail.",
+      ),
+    reason: z.string().min(1).max(500).describe("Why the hold was placed, in whoever placed it's words."),
+    placedBy: z.string().describe("The management client's own user id that placed it — the token's `sub`."),
+    placedAt: SQLiteDate.describe("When the hold was placed. Ms-epoch in SQLite."),
+    state: HoldState,
+    releasedAt: SQLiteDate.nullable().describe("When the hold was released, or null while it stands."),
+    releasedBy: z.string().nullable().describe("Who released it, or null while it stands."),
+    releaseReason: z.string().max(500).nullable().describe("Why it was released, or null while it stands."),
+  })
+  .describe("A legal hold on one user, one organization or one tenant's audit trail.");
+export type LegalHold = z.output<typeof LegalHold>;

package/src/controlPlane/data/oidcTrust.ts

@@ -0,0 +1,249 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { JsonDate } from "../../data/codecs";
+import { ControlPlaneKeyConflictError } from "../error/errors";
+
+/**
+ * An OIDC trust: the second credential kind a connection may hold, beside a registered key
+ * (`docs/AGENT-ACCESS.md` §6.2, #722).
+ *
+ * A key is a bearer: one client holds the private half. A trust is a **policy**: a trusted issuer, the
+ * audience its tokens must name, and a matcher over the claims that say which workload a token was minted
+ * for. Nobody holds a secret. The workload asks its own identity provider for a short-lived token, and the
+ * Worker checks it against the issuer's published keys with the verifier the webhooks already use,
+ * `core/src/http/oidcWebhook.ts`.
+ *
+ * ## The claims become data here, and that is a deliberate departure
+ *
+ * In a webhook the claims check is a predicate the **route** holds, because whoever wrote the route knows
+ * the legitimate sender. A connection's trust is per adopter, decided at registration by the same person who
+ * grants the scopes, so the matcher is stored with the trust and validated on the way in. That is the whole
+ * reason {@link OidcClaimMatch} exists rather than a function.
+ *
+ * ## The claims check is the boundary, not the signature
+ *
+ * An identity provider signs for everybody with the same keys. GitHub signs a token for every repository on
+ * the planet. A trust whose matcher constrains nothing accepts all of them, so {@link OidcClaimMatch} refuses
+ * one at registration — structurally, not as a warning — and refuses the claims that name the token rather
+ * than the workload ({@link RESERVED_OIDC_CLAIMS}), since a matcher made of those constrains nothing either.
+ *
+ * ## Named claims, not the `sub` string
+ *
+ * A `sub` is a concatenation whose composition belongs to the provider and to the adopter's own template.
+ * The claims beneath it — GitHub's `repository_id`, `environment`, `ref`; GitLab's `project_id` — are
+ * published individually and are stable. So the matcher is a map of claim names to values, and `sub` is one
+ * claim among the others rather than a special case.
+ *
+ * ## No rotation, and revocation changes shape
+ *
+ * There is no key to append, prove and expire. A token cannot be revoked; the trust is, and every token
+ * already minted stays live until it expires — {@link TRUST_REVOCATION_LATENCY} is the sentence that says
+ * so at the moment it matters.
+ *
+ * Nothing in this module reads a clock, a binding or D1. `now` is injected wherever time matters.
+ */
+
+/**
+ * Claims that name the token rather than the workload: who minted it, for whom, and when. A matcher built
+ * from these alone would accept every workload the issuer serves, so none of them may be registered.
+ * `iss` and `aud` are checked anyway, by the trust's own issuer and audience.
+ */
+export const RESERVED_OIDC_CLAIMS = ["iss", "aud", "exp", "nbf", "iat", "jti"] as const;
+
+/** The most claims one trust may match on. Far above any real constraint; a bound on a stored row. */
+export const MAX_TRUST_CLAIMS = 16;
+
+/** The most claims a refusal records, so a token carrying a hundred cannot fill the audit trail. */
+export const MAX_OBSERVED_CLAIMS = 32;
+
+/** The longest claim value a matcher stores or a refusal records. */
+export const MAX_CLAIM_VALUE = 256;
+
+/** A claim name: the plain alphabet providers use, plus `.`, `:` and `-` for a customized template. */
+const CLAIM_NAME = /^[A-Za-z0-9_.:-]{1,64}$/;
+
+/** Every C0 and C1 control, the line separators, and the bidi controls: a value is one line of plain text. */
+const UNRENDERABLE = /[\p{Cc}\p{Bidi_Control}\u2028\u2029]/u;
+
+const reserved = new Set<string>(RESERVED_OIDC_CLAIMS);
+
+/**
+ * One claim name in a matcher. A name, not a path: nested claims are not matched, because a matcher that
+ * walks a structure is a matcher with more ways to be wrong on the check the whole trust rests on.
+ */
+export const OidcClaimName = z
+  .string()
+  .regex(CLAIM_NAME, "A claim name is letters, digits, `_`, `.`, `:` or `-`, at most 64.")
+  .refine((name) => !reserved.has(name), {
+    message: `${RESERVED_OIDC_CLAIMS.join(", ")} name the token, not the workload, so they cannot constrain a trust.`,
+  })
+  .describe(
+    "A claim the token must carry, by name — `repository_id`, `environment`, `project_id`, `sub`. Never one of the claims that name the token itself.",
+  );
+export type OidcClaimName = z.infer<typeof OidcClaimName>;
+
+/** One claim value in a matcher: compared as a string against the token's claim of the same name. */
+export const OidcClaimValue = z
+  .string()
+  .min(1, "A claim value cannot be empty.")
+  .max(MAX_CLAIM_VALUE, `A claim value is ${MAX_CLAIM_VALUE} characters at most.`)
+  .refine((value) => !UNRENDERABLE.test(value), "A claim value is one line of plain text.")
+  .describe(
+    "The exact value that claim must have. A numeric or boolean claim is compared by its string form, so `1262274726` matches a `repository_id` whichever way the provider typed it.",
+  );
+export type OidcClaimValue = z.infer<typeof OidcClaimValue>;
+
+/**
+ * Which workloads a trust accepts: every named claim must equal its value.
+ *
+ * **At least one, and that is the refusal the whole credential kind rests on.** An issuer with no claim
+ * constraint accepts every workload it serves.
+ */
+export const OidcClaimMatch = z
+  .record(OidcClaimName, OidcClaimValue)
+  .refine((claims) => Object.keys(claims).length > 0, {
+    message: "A trust needs at least one claim constraint. An issuer alone accepts every workload it serves.",
+  })
+  .refine((claims) => Object.keys(claims).length <= MAX_TRUST_CLAIMS, {
+    message: `A trust matches on ${MAX_TRUST_CLAIMS} claims at most.`,
+  })
+  .describe(
+    "The subject constraint: every named claim must equal its value. At least one, because an issuer alone accepts every workload it serves.",
+  );
+export type OidcClaimMatch = z.infer<typeof OidcClaimMatch>;
+
+/** An https URL. A trust's issuer and key endpoint are fetched from, so plain http is refused. */
+const HttpsUrl = z.url({ protocol: /^https$/ });
+
+/**
+ * One registered OIDC trust, an element of the connection's `trusts` column.
+ *
+ * Stored beside `keys` rather than inside it: the two kinds share nothing but the connection they grant
+ * through, and a union array would make every key reader learn about trusts.
+ */
+export const OidcTrust = z
+  .object({
+    trustId: z
+      .string()
+      .min(1)
+      .max(64)
+      .describe(
+        "The trust's id, named by a call on the `pithy-control-plane-trust` header the way a token's `kid` names a key. Not a secret.",
+      ),
+    issuer: HttpsUrl.describe(
+      "The exact `iss` this trust accepts — `https://token.actions.githubusercontent.com`, `https://gitlab.com`. A token from any other issuer is refused before its claims are read.",
+    ),
+    jwksUrl: HttpsUrl.describe(
+      "Where the issuer publishes the keys that sign its tokens, read from its discovery document at registration. Public, so configuration and not a secret.",
+    ),
+    audience: z
+      .string()
+      .min(1)
+      .max(512)
+      .describe(
+        "The `aud` a token must name. Defaults to this environment's own Worker origin, which is what stops a staging token being replayed against production.",
+      ),
+    claims: OidcClaimMatch,
+    authorizedBy: z
+      .email()
+      .max(254)
+      .describe(
+        "Who sanctioned this trust: the signed-in session's email at registration. Never who may use it — a trust's users are whoever its claims admit.",
+      ),
+    validFrom: JsonDate.describe("When the trust was registered and began to be honored."),
+    revokedAt: JsonDate.nullable().describe(
+      "When the trust was revoked, or null. Takes effect on the next call; a token already minted is refused from then on, but stays in its holder's hands until it expires.",
+    ),
+    firstCallAt: JsonDate.nullable().describe(
+      "When a call first verified under this trust, or null while it is awaiting a first call. Nothing can prove a trust at registration — there is no private key here and no workload present — so this is the only proof there is.",
+    ),
+  })
+  .describe(
+    "One OIDC trust: a trusted issuer, the audience its tokens must name, and the claims that say which workloads it admits.",
+  );
+export type OidcTrust = z.output<typeof OidcTrust>;
+
+/**
+ * What a caller should expect after a trust is revoked, said at the moment it is revoked rather than
+ * discovered afterwards.
+ */
+export const TRUST_REVOCATION_LATENCY =
+  "A token cannot be revoked, only the trust. Every call naming this trust is refused from now on, but a token already minted stays in its holder's hands until it expires — the issuer's own lifetime, typically minutes.";
+
+/** Every trust that may verify a call at `now`: not revoked, and started. */
+export function activeTrusts(trusts: readonly OidcTrust[], now: Date): OidcTrust[] {
+  return trusts.filter((trust) => trust.revokedAt === null && trust.validFrom.getTime() <= now.getTime());
+}
+
+/** The trust a call names, if it is live at `now`, or null. The revocation check lives here so no caller forgets it. */
+export function findVerifyingTrust(trusts: readonly OidcTrust[], trustId: string, now: Date): OidcTrust | null {
+  return activeTrusts(trusts, now).find((trust) => trust.trustId === trustId) ?? null;
+}
+
+/** Register a trust beside the others. A duplicate id is refused: the id is what a call addresses. */
+export function appendTrust(trusts: readonly OidcTrust[], trust: OidcTrust): OidcTrust[] {
+  if (trusts.some((existing) => existing.trustId === trust.trustId)) {
+    throw new ControlPlaneKeyConflictError({
+      message: "That trust id is already registered on this connection.",
+      action: "Register the trust under a new id.",
+      detail: `duplicate trustId ${trust.trustId}`,
+    });
+  }
+  return [...trusts, trust];
+}
+
+/**
+ * Revoke one trust at `now`, or answer null when no trust answers to that id. A trust already revoked keeps
+ * the instant it was first revoked: the window a call was refused under must not move.
+ */
+export function revokeTrust(trusts: readonly OidcTrust[], trustId: string, now: Date): OidcTrust[] | null {
+  if (!trusts.some((trust) => trust.trustId === trustId)) return null;
+  return trusts.map((trust) =>
+    trust.trustId === trustId && trust.revokedAt === null ? { ...trust, revokedAt: now } : trust,
+  );
+}
+
+/** A claim's string form, or undefined for a value that is not a string, number or boolean. */
+function claimString(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (typeof value === "boolean") return String(value);
+  return undefined;
+}
+
+/**
+ * Whether a token's claims satisfy a trust's matcher: every registered claim present and equal.
+ *
+ * An empty matcher matches nothing. Registration refuses one, and this refuses it again rather than letting
+ * a hand-edited row vacuously admit every workload.
+ */
+export function claimsMatch(
+  match: Readonly<Record<string, string>>,
+  claims: Readonly<Record<string, unknown>>,
+): boolean {
+  const entries = Object.entries(match);
+  if (entries.length === 0) return false;
+  return entries.every(([name, expected]) => claimString(claims[name]) === expected);
+}
+
+/**
+ * The claims a refused token carried, as a refusal records them: the workload's claims, as strings, capped.
+ *
+ * This is what makes a custom issuer workable and a profiled one self-correcting — register, let the
+ * workload run once, read what it actually sent. Only ever called once the signature, issuer and audience
+ * have verified, so the caller demonstrably holds a genuine token for this audience and naming its claims
+ * leaks nothing it does not already hold.
+ */
+export function observedClaims(claims: Readonly<Record<string, unknown>>): Record<string, string> {
+  const recorded: Record<string, string> = {};
+  for (const [name, value] of Object.entries(claims)) {
+    if (Object.keys(recorded).length >= MAX_OBSERVED_CLAIMS) break;
+    if (reserved.has(name) || !CLAIM_NAME.test(name)) continue;
+    const text = claimString(value);
+    if (text === undefined) continue;
+    recorded[name] = text.slice(0, MAX_CLAIM_VALUE);
+  }
+  return recorded;
+}

package/src/controlPlane/data/tables.ts

@@ -6,6 +6,7 @@ import type { Kysely } from "kysely";
 import type { z } from "zod";
 import { createDatabase, type DatabaseSchema } from "../../data/db";
 import { ControlPlaneConnection } from "./connection";
+import { LegalHold } from "./hold";
 import { ControlPlaneReplay } from "./replay";
 
 /**
@@ -23,6 +24,9 @@ export const CONTROL_PLANE_CONNECTIONS_TABLE = "pithyControlplaneConnections";
  */
 export const CONTROL_PLANE_REPLAYS_TABLE = "pithyControlplaneReplays";
 
+/** Legal holds, kept after release as the record that one stood. */
+export const CONTROL_PLANE_HOLDS_TABLE = "pithyControlplaneHolds";
+
 /**
  * The control-plane tables map. Both are always present: a Worker that composes the seam and has never
  * been connected still needs somewhere for the answer "nobody is connected" to come from, and the
@@ -32,6 +36,7 @@ export function controlPlaneTables(): Record<string, z.ZodObject> {
   return {
     [CONTROL_PLANE_CONNECTIONS_TABLE]: ControlPlaneConnection,
     [CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay,
+    [CONTROL_PLANE_HOLDS_TABLE]: LegalHold,
   };
 }
 
@@ -39,6 +44,7 @@ export function controlPlaneTables(): Record<string, z.ZodObject> {
 export type ControlPlaneTables = {
   [CONTROL_PLANE_CONNECTIONS_TABLE]: typeof ControlPlaneConnection;
   [CONTROL_PLANE_REPLAYS_TABLE]: typeof ControlPlaneReplay;
+  [CONTROL_PLANE_HOLDS_TABLE]: typeof LegalHold;
 };
 export type ControlPlaneDatabase = Kysely<DatabaseSchema<ControlPlaneTables>>;
 
@@ -47,5 +53,6 @@ export function controlPlaneDatabase(d1: D1Database): ControlPlaneDatabase {
   return createDatabase(d1, {
     [CONTROL_PLANE_CONNECTIONS_TABLE]: ControlPlaneConnection,
     [CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay,
+    [CONTROL_PLANE_HOLDS_TABLE]: LegalHold,
   }) as unknown as ControlPlaneDatabase;
 }

package/src/controlPlane/data/trustFirstCall.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { sql } from "kysely";
+import { CONTROL_PLANE_CONNECTIONS_TABLE, type ControlPlaneDatabase } from "./tables";
+
+/**
+ * Record the first call a trust answered (#722), so a listing stops saying *awaiting a first call*.
+ *
+ * **One statement that touches one field, never a read-modify-write of the column.** The verifier read the row
+ * moments ago, and an operator may have revoked the trust since. Writing back the whole `trusts` array as the
+ * verifier saw it would resurrect that trust — a revocation undone by the very call it was meant to stop. So the
+ * write is `json_set` on the matching element's `firstCallAt` alone, and only while that element is still
+ * unrevoked and still uncalled: a revoked trust is left exactly as revoked, and a second first call changes nothing.
+ *
+ * The instant is written as ISO-8601, the shape `JsonDate` stores inside the column.
+ */
+export async function recordTrustFirstCall(
+  db: ControlPlaneDatabase,
+  connectionId: string,
+  trustId: string,
+  at: Date,
+): Promise<void> {
+  const trusts = sql.ref("trusts");
+  const uncalled = (alias: string) =>
+    sql`json_extract(${sql.ref(`${alias}.value`)}, '$.trustId') = ${trustId}
+      and json_extract(${sql.ref(`${alias}.value`)}, '$.revokedAt') is null
+      and json_extract(${sql.ref(`${alias}.value`)}, '$.firstCallAt') is null`;
+  await db
+    .updateTable(CONTROL_PLANE_CONNECTIONS_TABLE)
+    .set({
+      trusts: sql<string>`json_set(${trusts}, '$[' || (select ${sql.ref("t.key")} from json_each(${trusts}) as t where ${uncalled("t")} limit 1) || '].firstCallAt', ${at.toISOString()})`,
+    })
+    .where("id", "=", connectionId)
+    .where(sql<boolean>`exists (select 1 from json_each(${trusts}) as u where ${uncalled("u")})`)
+    .execute();
+}