@pithy-sh/core 0.12.0 → 0.14.0

package/dist/controlPlane/capability.js

@@ -1,13 +1,21 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
+import { RETENTION_READ_SCOPE } from "./scope/scope.js";
 import { defineCapability } from "../capability/capability.js";
+import { memoryJwksCache } from "../http/oidcWebhook.js";
+import { routeGroupsOf } from "../openapi/routeGroups.js";
+import { describePresenceRooms } from "../presence/http/routes.js";
 import { readRetirement } from "../privacy/fieldRotation.js";
 import { lazyPrivacyInventory } from "../privacy/inventory.js";
+import { composedRetention } from "../retention/composed.js";
+import { ControlPlaneConnection } from "./data/connection.js";
+import { CONTROL_PLANE_CONNECTIONS_TABLE, controlPlaneTables } from "./data/tables.js";
+import { standingHolds } from "../retention/holds.js";
+import { holdsUserPurge } from "../retention/holdsPurge.js";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "../version.generated.js";
 import "../worker/identity.js";
 import { ControlPlaneConfig } from "./config/config.js";
-import { ControlPlaneConnection } from "./data/connection.js";
-import { CONTROL_PLANE_CONNECTIONS_TABLE, controlPlaneTables } from "./data/tables.js";
+import { recordTrustFirstCall } from "./data/trustFirstCall.js";
 import { capabilityHealthSources, defineCapabilityHealth } from "./discovery/health.js";
 import { createControlPlaneVerifier } from "./http/guard.js";
 import { MIGRATION_HEALTH_KEYS, composeMigrationDatabases, readMigrationHealth } from "./migrationState/migrationState.js";
@@ -15,6 +23,8 @@ import { controlPlaneRouteDescriptors, registerControlPlaneRoutes } from "./http
 import { controlplane_0001_init } from "./migrations/0001_init.js";
 import { controlplane_0002_management_origin } from "./migrations/0002_management_origin.js";
 import { controlplane_0003_connection_principal } from "./migrations/0003_connection_principal.js";
+import { controlplane_0004_connection_trusts } from "./migrations/0004_connection_trusts.js";
+import { controlplane_0005_holds } from "./migrations/0005_holds.js";
 import { d1ReplayGuard } from "./replay/d1Guard.js";
 import { CONTROL_PLANE_KV_BINDING, controlPlaneKvNamespaces, kvReplayGuard } from "./replay/kvGuard.js";
 //#region src/controlPlane/capability.ts
@@ -29,6 +39,16 @@ import { CONTROL_PLANE_KV_BINDING, controlPlaneKvNamespaces, kvReplayGuard } fro
 * composed key and make Kysely re-run an applied migration.
 */
 const CONTROLPLANE_MIGRATION_ORDER = 1100;
+/** The standing legal holds, on the seam's own manifest entry. Behind the scope the holds listing requires. */
+const ACTIVE_HOLDS_HEALTH_KEY = {
+	key: "activeHolds",
+	kind: "count",
+	states: null,
+	scope: RETENTION_READ_SCOPE,
+	cost: "indexed",
+	summary: "Legal holds standing. While one stands, no purge, prune or inactivity deletion touches its subject.",
+	nominal: null
+};
 /** Narrow a composed capability to this one — the CLI and tests use it to find the seam's config. */
 function isControlPlaneCapability(capability) {
 	return capability.name === "controlplane";
@@ -57,7 +77,9 @@ function controlplane(options = {}) {
 	const migrations = {
 		"0001_init": controlplane_0001_init,
 		"0002_management_origin": controlplane_0002_management_origin,
-		"0003_connection_principal": controlplane_0003_connection_principal
+		"0003_connection_principal": controlplane_0003_connection_principal,
+		"0004_connection_trusts": controlplane_0004_connection_trusts,
+		"0005_holds": controlplane_0005_holds
 	};
 	const requiredBindings = [{
 		type: "d1",
@@ -75,6 +97,7 @@ function controlplane(options = {}) {
 	*/
 	const database = (c) => c.var.db.app;
 	const now = () => /* @__PURE__ */ new Date();
+	const jwksCache = memoryJwksCache({ now });
 	/**
 	* The replay guard for this request, chosen once by config.
 	*
@@ -90,6 +113,7 @@ function controlplane(options = {}) {
 	let health = /* @__PURE__ */ new Map();
 	let migrationDatabases = [];
 	let composedCapabilities = [];
+	let presence = /* @__PURE__ */ new Map();
 	const privacy = lazyPrivacyInventory(() => composedCapabilities);
 	return {
 		...defineCapability({
@@ -106,9 +130,17 @@ function controlplane(options = {}) {
 			} },
 			kvNamespaces: usesKvReplay ? controlPlaneKvNamespaces(config.jtiTtlSeconds) : {},
 			adminRoutes: controlPlaneRouteDescriptors(config.basePath),
+			purge: [holdsUserPurge()],
 			health: defineCapabilityHealth({
-				keys: MIGRATION_HEALTH_KEYS,
-				read: (c) => readMigrationHealth(c.env, migrationDatabases)
+				keys: [...MIGRATION_HEALTH_KEYS, ACTIVE_HOLDS_HEALTH_KEY],
+				read: async (c) => {
+					const env = c.env;
+					const [migrations, activeHolds] = await Promise.all([readMigrationHealth(env, migrationDatabases), standingHolds(env)]);
+					return {
+						...migrations,
+						activeHolds
+					};
+				}
 			}),
 			compose: ({ capabilities }) => {
 				composed = capabilities.map((cap) => ({
@@ -118,8 +150,10 @@ function controlplane(options = {}) {
 					adminRoutes: [...cap.adminRoutes ?? []],
 					healthKeys: [...cap.health?.keys ?? []],
 					configKeys: [...cap.manifestConfig?.keys ?? []],
-					config: { ...cap.manifestConfig?.values ?? {} }
+					config: { ...cap.manifestConfig?.values ?? {} },
+					presenceRooms: cap.presence ? describePresenceRooms(cap.presence) : []
 				}));
+				presence = new Map(capabilities.flatMap((cap) => cap.presence ? cap.presence.rooms.map((room) => [room.kind, cap.presence]) : []));
 				health = capabilityHealthSources(capabilities);
 				migrationDatabases = composeMigrationDatabases(capabilities);
 				composedCapabilities = [...capabilities];
@@ -127,6 +161,7 @@ function controlplane(options = {}) {
 			middleware: [(app) => {
 				app.use("*", async (c, next) => {
 					const db = database(c);
+					const environment = String(c.env["ENVIRONMENT"] ?? "");
 					c.set("controlPlaneVerifier", createControlPlaneVerifier({
 						loadConnection: async (connectionId) => {
 							const row = await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().where("id", "=", connectionId).executeTakeFirst();
@@ -136,9 +171,18 @@ function controlplane(options = {}) {
 							return (await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).select("id").limit(1).execute()).length;
 						},
 						replay: replay(c),
-						environment: String(c.env["ENVIRONMENT"] ?? ""),
+						environment,
 						config,
 						now
+					}, {
+						loadEnvironmentConnection: async () => {
+							const row = await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().where("environment", "=", environment).executeTakeFirst();
+							return row ? ControlPlaneConnection.parse(row) : null;
+						},
+						environment,
+						now,
+						jwksCache,
+						recordFirstCall: (connectionId, trustId, at) => recordTrustFirstCall(db, connectionId, trustId, at)
 					}));
 					await next();
 				});
@@ -152,6 +196,10 @@ function controlplane(options = {}) {
 					composedMigrations: () => migrationDatabases,
 					privacyInventory: privacy,
 					retirement: (env) => readRetirement(env, composedCapabilities),
+					composedPresence: () => presence,
+					composition: () => composedCapabilities,
+					routeGroups: () => routeGroupsOf(app),
+					retention: composedRetention,
 					now
 				});
 			}
@@ -160,4 +208,4 @@ function controlplane(options = {}) {
 	};
 }
 //#endregion
-export { CONTROLPLANE_MIGRATION_ORDER, CONTROL_PLANE_KV_BINDING, controlplane, isControlPlaneCapability };
+export { ACTIVE_HOLDS_HEALTH_KEY, CONTROLPLANE_MIGRATION_ORDER, CONTROL_PLANE_KV_BINDING, controlplane, isControlPlaneCapability };

package/dist/controlPlane/context.d.ts

@@ -24,6 +24,10 @@ export declare const ControlPlaneContext: z.ZodObject<{
     grantedScopes: z.ZodArray<z.ZodString>;
     keyId: z.ZodString;
     tokenId: z.ZodString;
+    credentialKind: z.ZodOptional<z.ZodEnum<{
+        key: "key";
+        trust: "trust";
+    }>>;
     actorKind: z.ZodNullable<z.ZodEnum<{
         agent: "agent";
         dashboard: "dashboard";

package/dist/controlPlane/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/controlPlane/context.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;iBA4C7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/controlPlane/context.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;iBAoD7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/controlPlane/context.js

@@ -25,8 +25,9 @@ const ControlPlaneContext = z.object({
 	subject: z.string().describe("The management client's own user id from the token's `sub` — who, on their side, is acting. Recorded as the audit `actorId` so the trail answers 'which person at the dashboard did this', not just 'the dashboard'."),
 	scope: ControlPlaneScope.describe("The single scope this token was minted for. One call, one operation — a token carrying the whole grant would make every call as dangerous as the most dangerous one."),
 	grantedScopes: z.array(ControlPlaneScope).describe("Every scope the adopter granted this connection, read from their own row. The authority: a scope absent here is denied however the token is written."),
-	keyId: z.string().describe("Which registered key verified this call. Recorded so a rotation can be traced through the trail, and so a key still in use is visible before it is expired."),
-	tokenId: z.string().describe("The token's `jti`, already claimed in the replay set. Recorded to tie one audit event to one call."),
+	keyId: z.string().describe("Which registered key verified this call — or, for a call under an OIDC trust, which trust. Recorded so a rotation can be traced through the trail, and so a credential still in use is visible before it is retired."),
+	tokenId: z.string().describe("The token's `jti`, already claimed in the replay set. Recorded to tie one audit event to one call. For a call under an OIDC trust, the provider token's own `jti` when it carries one, else empty: such a token is verified per call and never spent."),
+	credentialKind: z.enum(["key", "trust"]).optional().describe("Which kind of credential verified this call: a registered `key`, or an OIDC `trust` (#722), in which case `keyId` names the trust. Absent reads as a key, which is every call made before trusts existed."),
 	actorKind: ControlPlaneActorKind.nullable().describe("What kind of client the connection is for — `agent`, `dashboard` or `script` — read from the adopter's own row, never from the token. The gate stamps it onto every control-plane audit row this call writes. Null for a connection registered before the kind was recorded (#721).")
 }).describe("The verified control-plane caller for one request. Never an AuthContext: a management client is not a user of the adopter's app.");
 //#endregion

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

@@ -38,7 +38,7 @@ export declare const RegisteredKey: z.ZodObject<{
 }, z.core.$strip>;
 export type RegisteredKey = z.output<typeof RegisteredKey>;
 /**
- * What kind of client a connection is for (#721): `agent`, `dashboard` or `script`.
+ * What kind of client a connection is for: `agent`, `dashboard` or `script`.
  *
  * The audit trail's `actorType: "control-plane"` names all three identically, and the questions asked
  * after an incident are exactly the ones that tell them apart — was it a person at the dashboard, a
@@ -69,7 +69,7 @@ export type ConnectionPrincipal = z.output<typeof ConnectionPrincipal>;
 /** The longest purpose a connection may carry. One line on a review screen, with room to say what it does. */
 export declare const MAX_CONNECTION_PURPOSE = 200;
 /**
- * What a connection is for, in the words of whoever registered it (#721).
+ * What a connection is for, in the words of whoever registered it.
  *
  * **Required at registration, and refused when absent**, because a review listing credentials by key id
  * cannot support the decision it exists for. **Untrusted input**: a customer writes it and something else
@@ -77,6 +77,14 @@ export declare const MAX_CONNECTION_PURPOSE = 200;
  */
 export declare const ConnectionPurpose: z.ZodString;
 export type ConnectionPurpose = z.output<typeof ConnectionPurpose>;
+/** Which credential kinds a connection holds, live or not. */
+export declare const ConnectionCredentialKind: z.ZodEnum<{
+    both: "both";
+    key: "key";
+    none: "none";
+    trust: "trust";
+}>;
+export type ConnectionCredentialKind = z.infer<typeof ConnectionCredentialKind>;
 /**
  * One management-client connection — the row in `pithy_controlplane_connections`.
  *
@@ -111,6 +119,17 @@ export declare const ControlPlaneConnection: z.ZodObject<{
         validUntil: z.ZodNullable<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>>;
     }, z.core.$strip>>>;
+    trusts: z.ZodOptional<import("../../data/codecs").SqliteJson<z.ZodArray<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>>>>;
     createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
     updatedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
 }, z.core.$strip>;

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

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/connection.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;GASG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB;;;;iBAgBoF,CAAC;AAClH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;iBAoBoF,CAAC;AAC/G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;EAI/B,CAAC;AACJ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,YAK7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,8GAA8G;AAC9G,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAiB1C;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,aAW3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkEhC,CAAC;AACJ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC7E,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/connection.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;GASG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB;;;;iBAgBoF,CAAC;AAClH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;iBAoBoF,CAAC;AAC/G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;EAI/B,CAAC;AACJ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,YAK7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,8GAA8G;AAC9G,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAiB1C;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,aAW3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE,8DAA8D;AAC9D,eAAO,MAAM,wBAAwB;;;;;EAIlC,CAAC;AACJ,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuEhC,CAAC;AACJ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC7E,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/controlPlane/data/connection.js

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { JsonDate, SQLiteDate, sqliteJson } from "../../data/codecs.js";
 import { ControlPlaneScope } from "../scope/scope.js";
+import { JsonDate, SQLiteDate, sqliteJson } from "../../data/codecs.js";
+import { OidcTrust } from "./oidcTrust.js";
 import { z } from "zod";
 //#region src/controlPlane/data/connection.ts
 /**
@@ -35,7 +36,7 @@ const RegisteredKey = z.object({
 	revokedAt: JsonDate.nullable().describe("When this key was revoked outright, or null. Revocation ignores `validUntil` and takes effect immediately — it is the adopter's unilateral control, and it must not wait for a window to close.")
 }).describe("One registered public key with its validity window. Two live at once during a rotation overlap.");
 /**
-* What kind of client a connection is for (#721): `agent`, `dashboard` or `script`.
+* What kind of client a connection is for: `agent`, `dashboard` or `script`.
 *
 * The audit trail's `actorType: "control-plane"` names all three identically, and the questions asked
 * after an incident are exactly the ones that tell them apart — was it a person at the dashboard, a
@@ -78,13 +79,20 @@ const MAX_CONNECTION_PURPOSE = 200;
 */
 const UNRENDERABLE = /[\p{Cc}\p{Bidi_Control}\u2028\u2029\u200B\u2060\uFEFF]/u;
 /**
-* What a connection is for, in the words of whoever registered it (#721).
+* What a connection is for, in the words of whoever registered it.
 *
 * **Required at registration, and refused when absent**, because a review listing credentials by key id
 * cannot support the decision it exists for. **Untrusted input**: a customer writes it and something else
 * renders it, so it is validated on the way in, and again on every read of the row.
 */
 const ConnectionPurpose = z.string().trim().min(1, "Say what this client is for.").max(200, `A purpose is 200 characters at most.`).refine((purpose) => !UNRENDERABLE.test(purpose), "A purpose is one line of plain text: no control, bidi or invisible characters.").describe(`What this connection's client is for, in the registering operator's words — one line of plain text, 200 characters at most, with no control, bidi or invisible characters. Written by a customer and rendered elsewhere, so validated at the boundary.`);
+/** Which credential kinds a connection holds, live or not. */
+const ConnectionCredentialKind = z.enum([
+	"key",
+	"trust",
+	"both",
+	"none"
+]).describe("Which credential kinds the connection holds, live or not: `key` (registered Ed25519 keys), `trust` (OIDC trusts), `both`, or `none`.");
 /**
 * One management-client connection — the row in `pithy_controlplane_connections`.
 *
@@ -105,8 +113,9 @@ const ControlPlaneConnection = z.object({
 	purpose: ConnectionPurpose.nullable().default(null).describe("What this connection's client is for, in the registering operator's words. Required at registration and editable with `pithy dashboard connect --update --purpose`; null only for a connection registered before it was recorded."),
 	scopes: sqliteJson(z.array(ControlPlaneScope)).describe("The operations this connection was granted, stored and enforced on the adopter's side. Enforced only by the caller, a scope would not be a limit at all."),
 	keys: sqliteJson(z.array(RegisteredKey)).describe("Every key this connection may sign with, current and superseded. One JSON column rather than a child table, so a rotation is one atomic UPDATE and verification is one read."),
+	trusts: sqliteJson(z.array(OidcTrust)).optional().describe("Every OIDC trust this connection honors, live and revoked (#722) — the second credential kind beside `keys`, so a connection may hold a trust, a key, or both. Optional on the type, and absent reads as none: a connection value built before trusts existed still describes a connection, and the column itself defaults to an empty list."),
 	createdAt: SQLiteDate.describe("When the connection was registered. Ms-epoch in SQLite, a Date in TypeScript."),
 	updatedAt: SQLiteDate.describe("When the row last changed — a key registered or expired, or the Worker URL re-pointed.")
 }).describe("One management-client connection: its identity, the environment and URL it is bound to, the operations it was granted, and its versioned public keys.");
 //#endregion
-export { ConnectionPrincipal, ConnectionPurpose, ControlPlaneActorKind, ControlPlaneConnection, Ed25519PublicJwk, MAX_CONNECTION_PURPOSE, RegisteredKey };
+export { ConnectionCredentialKind, ConnectionPrincipal, ConnectionPurpose, ControlPlaneActorKind, ControlPlaneConnection, Ed25519PublicJwk, MAX_CONNECTION_PURPOSE, RegisteredKey };

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

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type ConnectionCredentialKind, ControlPlaneConnection, type RegisteredKey } from "./connection";
+import { type OidcTrust } from "./oidcTrust";
+import { 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 declare function connectionCredentialKind(connection: ControlPlaneConnection): ConnectionCredentialKind;
+/** Whether any key or trust on the connection can verify a call at `now`. */
+export declare function connectionLive(connection: ControlPlaneConnection, now: Date): boolean;
+/**
+ * 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 declare function connectionRevokedAt(connection: ControlPlaneConnection, now: Date): Date | null;
+/** 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 declare function revokeCredentials(connection: ControlPlaneConnection, now: Date): RevokedCredentials;
+/** Whether a connection was authorized by `principal`. An email, compared without regard to case. */
+export declare function authorizedByPrincipal(connection: ControlPlaneConnection, principal: string): boolean;
+/** 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 declare function listConnections(db: ControlPlaneDatabase, filter?: ConnectionFilter): Promise<ConnectionListing>;
+/** Read one connection by id, or null. */
+export declare function readConnection(db: ControlPlaneDatabase, id: string): Promise<ControlPlaneConnection | 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 declare function readConnectionForWrite(db: ControlPlaneDatabase, id: string, options?: {
+    readonly environment?: string | undefined;
+}): Promise<ConnectionForWrite | null>;
+/**
+ * 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 declare function writeKeys(db: ControlPlaneDatabase, read: ConnectionForWrite, keys: readonly RegisteredKey[], now: Date): Promise<boolean>;
+/** 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 declare function writeCredentials(db: ControlPlaneDatabase, read: ConnectionForWrite, columns: CredentialColumns, now: Date): Promise<boolean>;
+/**
+ * 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 declare function revokeConnection(db: ControlPlaneDatabase, id: string, now: Date, options?: {
+    readonly environment?: string | undefined;
+}): Promise<RevokedCredentials | null>;
+//# sourceMappingURL=connections.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/connections.ts"],"names":[],"mappings":"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"}

package/dist/controlPlane/data/connections.js

@@ -0,0 +1,151 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ConflictError } from "../../error/pithyError.js";
+import { activeTrusts } from "./oidcTrust.js";
+import { ControlPlaneConnection } from "./connection.js";
+import { CONTROL_PLANE_CONNECTIONS_TABLE } from "./tables.js";
+import { activeKeys } from "./keyLifecycle.js";
+import { sql } from "kysely";
+//#region src/controlPlane/data/connections.ts
+/**
+* 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. */
+function connectionCredentialKind(connection) {
+	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`. */
+function connectionLive(connection, now) {
+	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.
+*/
+function connectionRevokedAt(connection, now) {
+	if (connectionLive(connection, now)) return null;
+	const credentials = [...connection.keys, ...connection.trusts ?? []];
+	if (credentials.length === 0) return null;
+	let latest = 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;
+}
+/**
+* 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.
+*/
+function revokeCredentials(connection, now) {
+	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. */
+function authorizedByPrincipal(connection, principal) {
+	return connection.authorizedBy !== null && connection.authorizedBy.toLowerCase() === principal.toLowerCase();
+}
+/** Every connection in the database, attributed ones matching the filter, unattributed ones apart. */
+async function listConnections(db, filter = {}) {
+	let query = db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().orderBy("createdAt").orderBy("id");
+	if (filter.environment !== void 0) 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 === void 0 || authorizedByPrincipal(row, principal))),
+		unattributed: rows.filter((row) => row.authorizedBy === null)
+	};
+}
+/** Read one connection by id, or null. */
+async function readConnection(db, id) {
+	const row = await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().where("id", "=", id).executeTakeFirst();
+	return row ? ControlPlaneConnection.parse(row) : null;
+}
+/** Read one connection by id for a write, or null. With `environment`, null for a connection bound to another. */
+async function readConnectionForWrite(db, id, options = {}) {
+	let query = db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().where("id", "=", id);
+	if (options.environment !== void 0) 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.
+*/
+async function writeKeys(db, read, keys, now) {
+	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`${sql.ref("keys")} = ${read.storedKeys}`).executeTakeFirst();
+	return Number(result.numUpdatedRows) > 0;
+}
+/**
+* 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.
+*/
+async function writeCredentials(db, read, columns, now) {
+	const result = await db.updateTable(CONTROL_PLANE_CONNECTIONS_TABLE).set({
+		...columns.keys === void 0 ? {} : { keys: ControlPlaneConnection.shape.keys.encode([...columns.keys]) },
+		...columns.trusts === void 0 ? {} : { trusts: ControlPlaneConnection.shape.trusts.encode([...columns.trusts]) },
+		updatedAt: ControlPlaneConnection.shape.updatedAt.encode(now)
+	}).where("id", "=", read.connection.id).where(sql`${sql.ref("keys")} = ${read.storedKeys}`).where(sql`${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.
+*/
+async function revokeConnection(db, id, now, options = {}) {
+	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;
+		if (await writeCredentials(db, read, {
+			keys: revoked.connection.keys,
+			trusts: revoked.connection.trusts ?? []
+		}, 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`
+	});
+}
+//#endregion
+export { authorizedByPrincipal, connectionCredentialKind, connectionLive, connectionRevokedAt, listConnections, readConnection, readConnectionForWrite, revokeConnection, revokeCredentials, writeCredentials, writeKeys };

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

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * **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 declare const HoldSubjectType: z.ZodEnum<{
+    audit: "audit";
+    organization: "organization";
+    user: "user";
+}>;
+export type HoldSubjectType = z.infer<typeof HoldSubjectType>;
+/** Whether a hold is in force. */
+export declare const HoldState: z.ZodEnum<{
+    active: "active";
+    released: "released";
+}>;
+export type HoldState = z.infer<typeof HoldState>;
+/** One hold, as `pithy_controlplane_holds` stores it. */
+export declare const LegalHold: z.ZodObject<{
+    id: z.ZodString;
+    subjectType: z.ZodEnum<{
+        audit: "audit";
+        organization: "organization";
+        user: "user";
+    }>;
+    subjectId: z.ZodNullable<z.ZodString>;
+    reason: z.ZodString;
+    placedBy: z.ZodString;
+    placedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    state: z.ZodEnum<{
+        active: "active";
+        released: "released";
+    }>;
+    releasedAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>;
+    releasedBy: z.ZodNullable<z.ZodString>;
+    releaseReason: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type LegalHold = z.output<typeof LegalHold>;
+//# sourceMappingURL=hold.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hold.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/hold.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;GAOG;AAEH,sFAAsF;AACtF,eAAO,MAAM,eAAe;;;;EAIzB,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,kCAAkC;AAClC,eAAO,MAAM,SAAS;;;EAE6E,CAAC;AACpG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,yDAAyD;AACzD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;iBAoBgE,CAAC;AACvF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC"}

package/dist/controlPlane/data/hold.js

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SQLiteDate } from "../../data/codecs.js";
+import { z } from "zod";
+//#region src/controlPlane/data/hold.ts
+/**
+* **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. */
+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.");
+/** Whether a hold is in force. */
+const HoldState = z.enum(["active", "released"]).describe("`active` while the hold stands; `released` once it has been lifted, with the reason.");
+/** One hold, as `pithy_controlplane_holds` stores it. */
+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.");
+//#endregion
+export { HoldState, HoldSubjectType, LegalHold };