@pithy-sh/core 0.12.0 → 0.14.0

package/dist/controlPlane/data/oidcTrust.d.ts

@@ -0,0 +1,122 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * 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 declare const RESERVED_OIDC_CLAIMS: readonly ["iss", "aud", "exp", "nbf", "iat", "jti"];
+/** The most claims one trust may match on. Far above any real constraint; a bound on a stored row. */
+export declare const MAX_TRUST_CLAIMS = 16;
+/** The most claims a refusal records, so a token carrying a hundred cannot fill the audit trail. */
+export declare const MAX_OBSERVED_CLAIMS = 32;
+/** The longest claim value a matcher stores or a refusal records. */
+export declare const MAX_CLAIM_VALUE = 256;
+/**
+ * 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 declare const OidcClaimName: z.ZodString;
+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 declare const OidcClaimValue: z.ZodString;
+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 declare const OidcClaimMatch: z.ZodRecord<z.ZodString, z.ZodString>;
+export type OidcClaimMatch = z.infer<typeof OidcClaimMatch>;
+/**
+ * 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 declare const OidcTrust: z.ZodObject<{
+    trustId: z.ZodString;
+    issuer: z.ZodURL;
+    jwksUrl: z.ZodURL;
+    audience: z.ZodString;
+    claims: z.ZodRecord<z.ZodString, z.ZodString>;
+    authorizedBy: z.ZodEmail;
+    validFrom: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    revokedAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>;
+    firstCallAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>;
+}, z.core.$strip>;
+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 declare 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 \u2014 the issuer's own lifetime, typically minutes.";
+/** Every trust that may verify a call at `now`: not revoked, and started. */
+export declare function activeTrusts(trusts: readonly OidcTrust[], now: Date): OidcTrust[];
+/** The trust a call names, if it is live at `now`, or null. The revocation check lives here so no caller forgets it. */
+export declare function findVerifyingTrust(trusts: readonly OidcTrust[], trustId: string, now: Date): OidcTrust | null;
+/** Register a trust beside the others. A duplicate id is refused: the id is what a call addresses. */
+export declare function appendTrust(trusts: readonly OidcTrust[], trust: OidcTrust): OidcTrust[];
+/**
+ * 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 declare function revokeTrust(trusts: readonly OidcTrust[], trustId: string, now: Date): OidcTrust[] | null;
+/**
+ * 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 declare function claimsMatch(match: Readonly<Record<string, string>>, claims: Readonly<Record<string, unknown>>): boolean;
+/**
+ * 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 declare function observedClaims(claims: Readonly<Record<string, unknown>>): Record<string, string>;
+//# sourceMappingURL=oidcTrust.d.ts.map

package/dist/controlPlane/data/oidcTrust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidcTrust.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/oidcTrust.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,YAAI,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAU,CAAC;AAExF,sGAAsG;AACtG,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,qEAAqE;AACrE,eAAO,MAAM,eAAe,MAAM,CAAC;AAUnC;;;GAGG;AACH,eAAO,MAAM,aAAa,aAQvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,qGAAqG;AACrG,eAAO,MAAM,cAAc,aAOxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,cAAc,uCAUxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAK5D;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;iBAuCnB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,iOACsL,CAAC;AAE5N,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,SAAS,EAAE,CAEjF;AAED,wHAAwH;AACxH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,SAAS,GAAG,IAAI,CAE7G;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,CASvF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,SAAS,EAAE,GAAG,IAAI,CAKxG;AAUD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACvC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,OAAO,CAIT;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUhG"}

package/dist/controlPlane/data/oidcTrust.js

@@ -0,0 +1,173 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ControlPlaneKeyConflictError } from "../error/errors.js";
+import { JsonDate } from "../../data/codecs.js";
+import { z } from "zod";
+//#region src/controlPlane/data/oidcTrust.ts
+/**
+* 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.
+*/
+const RESERVED_OIDC_CLAIMS = [
+	"iss",
+	"aud",
+	"exp",
+	"nbf",
+	"iat",
+	"jti"
+];
+/** The most claims one trust may match on. Far above any real constraint; a bound on a stored row. */
+const MAX_TRUST_CLAIMS = 16;
+/** The most claims a refusal records, so a token carrying a hundred cannot fill the audit trail. */
+const MAX_OBSERVED_CLAIMS = 32;
+/** The longest claim value a matcher stores or a refusal records. */
+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(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.
+*/
+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.");
+/** One claim value in a matcher: compared as a string against the token's claim of the same name. */
+const OidcClaimValue = z.string().min(1, "A claim value cannot be empty.").max(256, `A claim value is 256 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.");
+/**
+* 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.
+*/
+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 <= 16, { message: `A trust matches on 16 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.");
+/** 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.
+*/
+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.");
+/**
+* What a caller should expect after a trust is revoked, said at the moment it is revoked rather than
+* discovered afterwards.
+*/
+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. */
+function activeTrusts(trusts, now) {
+	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. */
+function findVerifyingTrust(trusts, trustId, now) {
+	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. */
+function appendTrust(trusts, trust) {
+	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.
+*/
+function revokeTrust(trusts, trustId, now) {
+	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) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	if (typeof value === "boolean") return String(value);
+}
+/**
+* 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.
+*/
+function claimsMatch(match, claims) {
+	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.
+*/
+function observedClaims(claims) {
+	const recorded = {};
+	for (const [name, value] of Object.entries(claims)) {
+		if (Object.keys(recorded).length >= 32) break;
+		if (reserved.has(name) || !CLAIM_NAME.test(name)) continue;
+		const text = claimString(value);
+		if (text === void 0) continue;
+		recorded[name] = text.slice(0, 256);
+	}
+	return recorded;
+}
+//#endregion
+export { MAX_CLAIM_VALUE, MAX_OBSERVED_CLAIMS, MAX_TRUST_CLAIMS, OidcClaimMatch, OidcClaimName, OidcClaimValue, OidcTrust, RESERVED_OIDC_CLAIMS, TRUST_REVOCATION_LATENCY, activeTrusts, appendTrust, claimsMatch, findVerifyingTrust, observedClaims, revokeTrust };

package/dist/controlPlane/data/tables.d.ts

@@ -5,6 +5,7 @@ import type { Kysely } from "kysely";
 import type { z } from "zod";
 import { type DatabaseSchema } from "../../data/db";
 import { ControlPlaneConnection } from "./connection";
+import { LegalHold } from "./hold";
 import { ControlPlaneReplay } from "./replay";
 /**
  * The connections table. `CamelCasePlugin` snake-cases it to `pithy_controlplane_connections` — the
@@ -19,6 +20,8 @@ export declare const CONTROL_PLANE_CONNECTIONS_TABLE = "pithyControlplaneConnect
  * makes the claim a primary-key insert and therefore strongly consistent. See `../replay/guard.ts`.
  */
 export declare const CONTROL_PLANE_REPLAYS_TABLE = "pithyControlplaneReplays";
+/** Legal holds, kept after release as the record that one stood. */
+export declare 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
@@ -29,6 +32,7 @@ export declare 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>>;
 /** Build the control-plane database from the `DB` binding (CamelCasePlugin installed). */

package/dist/controlPlane/data/tables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,iCAAiC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAKhE;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,CAAC,+BAA+B,CAAC,EAAE,OAAO,sBAAsB,CAAC;IACjE,CAAC,2BAA2B,CAAC,EAAE,OAAO,kBAAkB,CAAC;CAC1D,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,cAAc,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAE9E,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,GAAG,oBAAoB,CAKzE"}
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,iCAAiC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE,oEAAoE;AACpE,eAAO,MAAM,yBAAyB,2BAA2B,CAAC;AAElE;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAMhE;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,CAAC,+BAA+B,CAAC,EAAE,OAAO,sBAAsB,CAAC;IACjE,CAAC,2BAA2B,CAAC,EAAE,OAAO,kBAAkB,CAAC;IACzD,CAAC,yBAAyB,CAAC,EAAE,OAAO,SAAS,CAAC;CAC/C,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,cAAc,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAE9E,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,GAAG,oBAAoB,CAMzE"}

package/dist/controlPlane/data/tables.js

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { ControlPlaneConnection } from "./connection.js";
+import { LegalHold } from "./hold.js";
 import { createDatabase } from "../../data/db.js";
+import { ControlPlaneConnection } from "./connection.js";
 import { ControlPlaneReplay } from "./replay.js";
 //#region src/controlPlane/data/tables.ts
 /**
@@ -17,6 +18,8 @@ const CONTROL_PLANE_CONNECTIONS_TABLE = "pithyControlplaneConnections";
 * makes the claim a primary-key insert and therefore strongly consistent. See `../replay/guard.ts`.
 */
 const CONTROL_PLANE_REPLAYS_TABLE = "pithyControlplaneReplays";
+/** Legal holds, kept after release as the record that one stood. */
+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
@@ -25,15 +28,17 @@ const CONTROL_PLANE_REPLAYS_TABLE = "pithyControlplaneReplays";
 function controlPlaneTables() {
 	return {
 		[CONTROL_PLANE_CONNECTIONS_TABLE]: ControlPlaneConnection,
-		[CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay
+		[CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay,
+		[CONTROL_PLANE_HOLDS_TABLE]: LegalHold
 	};
 }
 /** Build the control-plane database from the `DB` binding (CamelCasePlugin installed). */
 function controlPlaneDatabase(d1) {
 	return createDatabase(d1, {
 		[CONTROL_PLANE_CONNECTIONS_TABLE]: ControlPlaneConnection,
-		[CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay
+		[CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay,
+		[CONTROL_PLANE_HOLDS_TABLE]: LegalHold
 	});
 }
 //#endregion
-export { CONTROL_PLANE_CONNECTIONS_TABLE, CONTROL_PLANE_REPLAYS_TABLE, controlPlaneDatabase, controlPlaneTables };
+export { CONTROL_PLANE_CONNECTIONS_TABLE, CONTROL_PLANE_HOLDS_TABLE, CONTROL_PLANE_REPLAYS_TABLE, controlPlaneDatabase, controlPlaneTables };

package/dist/controlPlane/data/trustFirstCall.d.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { 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 declare function recordTrustFirstCall(db: ControlPlaneDatabase, connectionId: string, trustId: string, at: Date): Promise<void>;
+//# sourceMappingURL=trustFirstCall.d.ts.map

package/dist/controlPlane/data/trustFirstCall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trustFirstCall.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/trustFirstCall.ts"],"names":[],"mappings":"AAIA,OAAO,EAAmC,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAEtF;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,oBAAoB,EACxB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,IAAI,GACP,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/controlPlane/data/trustFirstCall.js

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CONTROL_PLANE_CONNECTIONS_TABLE } from "./tables.js";
+import { sql } from "kysely";
+//#region src/controlPlane/data/trustFirstCall.ts
+/**
+* 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.
+*/
+async function recordTrustFirstCall(db, connectionId, trustId, at) {
+	const trusts = sql.ref("trusts");
+	const uncalled = (alias) => 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`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`exists (select 1 from json_each(${trusts}) as u where ${uncalled("u")})`).execute();
+}
+//#endregion
+export { recordTrustFirstCall };