@pithy-sh/core 0.12.0 → 0.14.0

package/src/consent/purpose.ts

@@ -0,0 +1,160 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ValidationError } from "../error/pithyError";
+import { PrivacyClassName } from "../privacy/classes";
+
+/**
+ * Consent purposes: what a person is asked to agree to, declared where the processing is.
+ *
+ * ## Declared, never discovered
+ *
+ * A capability that processes under consent says so, the way it states its migrations: `@pithy-sh/email` declares
+ * `email.marketing` and `email.tracking`. The adopter adds their own to `consent({ purposes })`. The consent
+ * capability composes every declaration into one catalog, and `hasConsent` answers only for a purpose in it.
+ *
+ * ## A purpose says what it covers and what it demands
+ *
+ * Beside its notice version, a purpose names the data classes it covers, whether it is **explicit** (GDPR
+ * Article 9), the **minimum method** a grant needs, and whether a withdrawal must be made at least at the grade
+ * of the grant it withdraws, the way a HIPAA revocation must be in writing.
+ *
+ * ## The id is the capability's own
+ *
+ * `<domain>.<name>`, and a capability may declare purposes only under its own `name`, the rule `pithy_<name>_*`
+ * tables and `<name>/…` error codes follow, for the same reason: the domain is what keeps two declarations from
+ * colliding. `defineCapability` refuses anything else, naming the capability.
+ */
+
+/**
+ * How a grant was given, weakest first. The order is the grade: a purpose's `minimumMethod` refuses a grant below
+ * it, and a purpose with `writtenWithdrawal` refuses a withdrawal below the grant it withdraws.
+ */
+export const CONSENT_METHODS = ["click", "typed", "drawn", "provider"] as const;
+
+/** How a consent was given or withdrawn. */
+export const ConsentMethod = z
+  .enum(CONSENT_METHODS)
+  .describe(
+    "How a consent was given or withdrawn, weakest first: `click` (a checkbox or a button), `typed` (the person typed their name), `drawn` (a drawn signature), or `provider` (an e-signature provider's completed envelope). The order is the grade a purpose's minimum is held against.",
+  );
+export type ConsentMethod = z.output<typeof ConsentMethod>;
+
+/** A method's grade: its place in {@link CONSENT_METHODS}, so `click` is 0 and `provider` is 3. */
+export function methodRank(method: ConsentMethod): number {
+  return CONSENT_METHODS.indexOf(method);
+}
+
+/** Whether `method` meets `minimum`: at its grade or above. */
+export function meetsMethod(method: ConsentMethod, minimum: ConsentMethod): boolean {
+  return methodRank(method) >= methodRank(minimum);
+}
+
+/** A purpose id: `<domain>.<name>`, lowercase, the domain being the declaring capability's name. */
+export const ConsentPurposeId = z
+  .string()
+  .regex(
+    /^[a-z][a-z0-9-]*\.[a-z][a-z0-9_.-]*$/,
+    "A consent purpose id is `<domain>.<name>`: lowercase, the domain being the declaring capability's name.",
+  )
+  .max(128)
+  .describe(
+    "A consent purpose id, `<domain>.<name>` — `email.marketing`. The domain is the declaring capability's name, or the adopter's own domain for a purpose declared in `consent({ purposes })`.",
+  );
+export type ConsentPurposeId = z.output<typeof ConsentPurposeId>;
+
+/** One purpose a capability or the adopter processes under consent. */
+export const ConsentPurpose = z
+  .object({
+    id: ConsentPurposeId,
+    summary: z
+      .string()
+      .min(1)
+      .max(500)
+      .describe(
+        "One sentence, written for the person, on what agreeing allows — `Send me news and offers by email.` Shown on the consent settings screen.",
+      ),
+    noticeVersion: z
+      .number()
+      .int()
+      .positive()
+      .describe(
+        "The version of the notice a person agrees to. Bump it when the notice changes: every grant under an older version then needs renewing, and `hasConsent` answers no for it until it is.",
+      ),
+    classes: z
+      .array(PrivacyClassName)
+      .default([])
+      .describe(
+        "The data classes this purpose covers — `pii`, `phi`, or an adopter's own. The processing record reads it to name a classed field with no consent behind it.",
+      ),
+    explicit: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Whether this purpose needs explicit consent (GDPR Article 9), as processing health data does. Recorded so an auditor can see which purposes claim it.",
+      ),
+    minimumMethod: ConsentMethod.default("click").describe(
+      "The weakest method a grant may be given by. A grant below it is refused, and `hasConsent` answers no for one recorded below it before the minimum was raised.",
+    ),
+    writtenWithdrawal: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Whether a withdrawal must be made at least at the grade of the grant it withdraws, as a HIPAA revocation must be in writing. Off, a click withdraws any grant: withdrawing is then never harder than granting.",
+      ),
+  })
+  .describe("One purpose processed under consent: what it allows, its notice version, and what a grant demands.");
+export type ConsentPurpose = z.output<typeof ConsentPurpose>;
+export type ConsentPurposeInput = z.input<typeof ConsentPurpose>;
+
+/** The domain half of a purpose id: `email` for `email.marketing`. */
+export function purposeDomain(id: string): string {
+  const dot = id.indexOf(".");
+  return dot === -1 ? id : id.slice(0, dot);
+}
+
+/**
+ * Parse one declarer's purposes and refuse what no consent capability could answer for: an id that is not a
+ * purpose id, one under a domain that is not the declarer's, or two with one id. `domain` is the declaring
+ * capability's name, or `null` for the adopter's own, which may use any domain but a reserved one.
+ */
+export function parseConsentPurposes(
+  declarer: string,
+  purposes: readonly ConsentPurposeInput[],
+  domain: string | null,
+  reserved: ReadonlySet<string> = new Set(),
+): ConsentPurpose[] {
+  const seen = new Set<string>();
+  return purposes.map((input) => {
+    const parsed = ConsentPurpose.safeParse(input);
+    if (!parsed.success) {
+      throw new ValidationError({
+        message: `${declarer} declares a consent purpose that is not valid: ${parsed.error.issues[0]?.message ?? "invalid"}.`,
+        action: "Give it an id of the form `<domain>.<name>`, a summary, and a positive notice version.",
+      });
+    }
+    const purpose = parsed.data;
+    const own = purposeDomain(purpose.id);
+    if (domain !== null && own !== domain) {
+      throw new ValidationError({
+        message: `The ${declarer} capability declares the consent purpose "${purpose.id}" outside its own domain.`,
+        action: `Name it under ${domain}. — a capability declares purposes only under its own name.`,
+      });
+    }
+    if (domain === null && reserved.has(own)) {
+      throw new ValidationError({
+        message: `The consent purpose "${purpose.id}" is under ${own}., which a composed capability owns.`,
+        action: "Name your own purposes under your own domain, such as your app's name.",
+      });
+    }
+    if (seen.has(purpose.id)) {
+      throw new ValidationError({
+        message: `${declarer} declares the consent purpose "${purpose.id}" twice.`,
+        action: "Declare each purpose once.",
+      });
+    }
+    seen.add(purpose.id);
+    return purpose;
+  });
+}

package/src/consent/reader.ts

@@ -0,0 +1,134 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "../capability/capability";
+import type { ConsentPurpose } from "./purpose";
+
+/**
+ * The consent seam: the one question a capability asks before consent-based processing.
+ *
+ * `@pithy-sh/consent` answers it, and nothing imports that package to ask: a capability finds the composed reader
+ * through {@link composedConsent}, the shape `composedAuditEmit` gives the audit recorder, so `@pithy-sh/email`
+ * gates its tracking without depending on a sibling (principle 4).
+ *
+ * **Absent is not "no".** With no consent capability composed there is no record to consult, so
+ * {@link composedConsent} answers `null`, and a capability gates nothing on it. `pithy doctor`
+ * names that state, because processing that a law may require consent for is running with no record behind it.
+ */
+
+/** The subject a consent is recorded against: an account's user id, or a visitor's anonymous device id. */
+export interface ConsentSubject {
+  /** `account` — a user id from `@pithy-sh/auth`; `visitor` — an anonymous device id held in a first-party cookie. */
+  readonly kind: "account" | "visitor";
+  /** The id in that kind. */
+  readonly id: string;
+}
+
+/** What the consent capability answers. */
+export interface ConsentReader {
+  /**
+   * Whether `subject` holds consent to `purpose` now: a grant under the purpose's current notice version, at or
+   * above its minimum method, not withdrawn since, and not expired. An account's answer includes what the visitors
+   * merged into it granted. A purpose the catalog does not know answers no.
+   */
+  hasConsent(subject: ConsentSubject, purpose: string): Promise<boolean>;
+  /**
+   * Every purpose in the composed catalog, the adopter's included, with how many subjects stand where on it now. What
+   * the processing record cites for a consent-based activity. Optional on the seam: a reader without it leaves the
+   * counts unknown, never zero.
+   */
+  standings?(): Promise<readonly ConsentPurposeStanding[]>;
+  /**
+   * Every purpose in the composed catalog, the adopter's included, read from memory and never from the record. What
+   * the processing record checks a consent basis against when `standings` cannot answer. Optional on the seam: a
+   * reader without it leaves the catalog unknown, and the record then reports no gap that rests on the catalog.
+   */
+  purposes?(): readonly ConsentPurpose[];
+}
+
+/** One purpose in the catalog, and where its subjects stand on it now. */
+export interface ConsentPurposeStanding {
+  /** The purpose as the catalog composed it. */
+  readonly purpose: ConsentPurpose;
+  /** Subjects whose latest choice is a grant, under any notice version, expired or not. */
+  readonly grants: number;
+  /** Subjects whose latest choice is a withdrawal. */
+  readonly withdrawals: number;
+  /**
+   * Subjects `hasConsent` answers yes for now: a grant under the current notice version, at or above the purpose's
+   * minimum method, unexpired, and for a visitor not merged into an account, inside the visitor window.
+   */
+  readonly standing: number;
+}
+
+/** One withdrawal, as a capability that keeps its own state in step with consent is told of it. */
+export interface ConsentWithdrawal {
+  /** Who withdrew. */
+  readonly subject: ConsentSubject;
+  /** What they withdrew from. */
+  readonly purpose: string;
+  /** The Worker's bindings for this request. */
+  readonly env: Record<string, unknown>;
+  /**
+   * The subject's email address, read on demand from the capability that owns accounts, or `null` for a visitor
+   * or an account with none. A function, so a listener that needs no address reads none.
+   */
+  readonly address: () => Promise<string | null>;
+}
+
+/**
+ * Hear of a withdrawal from one of this capability's own purposes. `@pithy-sh/email` suppresses the address for
+ * marketing when `email.marketing` is withdrawn, so the suppression list and the consent record never disagree.
+ * Called after the withdrawal is recorded; a throw is the listener's own failure and never undoes the record.
+ */
+export type ConsentWithdrawnListener = (withdrawal: ConsentWithdrawal) => Promise<void>;
+
+/** One grant that now stands, as a capability that keeps its own state in step with consent is told of it. */
+export type ConsentGrant = ConsentWithdrawal;
+
+/**
+ * Hear of a grant to one of this capability's own purposes, once it stands. The other half of
+ * {@link ConsentWithdrawnListener}: `@pithy-sh/email` lifts the marketing suppression a withdrawal wrote when
+ * `email.marketing` is granted again, and nothing else, so a person who changes their mind back is heard. Called
+ * after the grant is recorded and only when the subject's standing is `granted`; a throw never undoes the record.
+ */
+export type ConsentGrantedListener = (grant: ConsentGrant) => Promise<void>;
+
+/** Every purpose the composed capabilities declare, in composition order. */
+export function composedConsentPurposes(capabilities: readonly Capability[]): ConsentPurpose[] {
+  return capabilities.flatMap((capability) => [...(capability.consentPurposes ?? [])]);
+}
+
+/** The composed consent reader for this env, or `null` when no capability provides one. */
+export function composedConsent(
+  capabilities: readonly Capability[],
+  env: Record<string, unknown>,
+): ConsentReader | null {
+  const provider = capabilities.find((capability) => capability.consentReader !== undefined);
+  return provider?.consentReader ? provider.consentReader(env) : null;
+}
+
+/** Whether any composed capability provides the consent seam. */
+export function providesConsent(capabilities: readonly Capability[]): boolean {
+  return capabilities.some((capability) => capability.consentReader !== undefined);
+}
+
+/**
+ * The account's address, read through the capability that owns accounts (`@pithy-sh/auth`'s `addressOf`), or
+ * `null` where nothing composed can say. Never throws: a listener that cannot learn the address does less, and the
+ * withdrawal it heard of stands.
+ */
+export async function composedAddress(
+  capabilities: readonly Capability[],
+  env: Record<string, unknown>,
+  subject: ConsentSubject,
+): Promise<string | null> {
+  if (subject.kind !== "account") return null;
+  const provider = capabilities.find((capability) => capability.addressOf !== undefined);
+  if (!provider?.addressOf) return null;
+  try {
+    return await provider.addressOf(env, subject.id);
+  } catch {
+    return null;
+  }
+}

package/src/controlPlane/audit/actions.ts

@@ -24,8 +24,8 @@ import type { Logger } from "../../logger/logger";
  * Emission goes through core's `emit` seam (`c.var.emit`), a no-op when the audit capability is
  * absent, so the seam never imports audit at runtime either (principle 4).
  *
- * **Four of these are emitted by a route; three are emitted by the CLI** (#294). The connection
- * lifecycle — registered, updated, removed — is written by `pithy dashboard` opening the adopter's D1
+ * **Most of these are emitted by a route; four are emitted by the CLI, one of them by a route as well.** The
+ * connection lifecycle — registered, updated, removed — is written by `pithy dashboard` opening the adopter's D1
  * directly, because those operations never reach their Worker: a first connect has no key to sign with
  * and the Worker may not be deployed, an update re-points an address the Worker never reads, and a
  * disconnect withdraws trust, which must not depend on a working connection (docs/CONTROL-PLANE.md §15).
@@ -34,8 +34,12 @@ import type { Logger } from "../../logger/logger";
  * `control-plane`, meaning the management client called in and proved it, while a CLI-side event carries
  * the adopter's own operator and no session at all.
  *
- * A declared code that nothing emits is a surface the trail promises and never delivers, which is what
- * these three were until #294. `packages/cli/src/ci/auditActions.test.ts` fails the build on one.
+ * `connectionRevoked` is the one written from both sides: by `POST {basePath}/connections/:connectionId/revoke`,
+ * with `actorType` `control-plane` and the caller's connection, and by `pithy dashboard connections --revoke`, with
+ * the operator as actor and no session.
+ *
+ * A declared code that nothing emits is a surface the trail promises and never delivers.
+ * `packages/cli/src/ci/auditActions.test.ts` fails the build on one.
  */
 export const ControlPlaneAuditActions = {
   /** A verified, in-scope management call was admitted. The trail of what the dashboard actually did. */
@@ -52,6 +56,13 @@ export const ControlPlaneAuditActions = {
   connectionUpdated: "controlplane/connection_updated",
   /** A connection was removed. The seam returns to its shipped state: connected to nothing, denying everything. */
   connectionRemoved: "controlplane/connection_removed",
+  /**
+   * Another connection's keys and trusts were revoked, with a reason: by a management client over the seam, or by the
+   * operator at the CLI.
+   */
+  connectionRevoked: "controlplane/connection_revoked",
+  holdPlaced: "controlplane/hold_placed",
+  holdReleased: "controlplane/hold_released",
 } as const;
 
 /** One of the control-plane audit action codes. */

package/src/controlPlane/capability.ts

@@ -6,14 +6,22 @@ import type { Migration } from "kysely/migration";
 import type { BindingSpecInput } from "../capability/bindings";
 import { type Capability, defineCapability, type PithyHonoEnv } from "../capability/capability";
 import type { DatabaseSpecMap } from "../data/databases";
+import { memoryJwksCache } from "../http/oidcWebhook";
 import type { KvNamespaceSpecMap, KvRegistry } from "../kv/namespaces";
+import { routeGroupsOf } from "../openapi/routeGroups";
+import type { PresenceDeclaration } from "../presence/declaration";
+import { describePresenceRooms } from "../presence/http/routes";
 import { readRetirement } from "../privacy/fieldRotation";
 import { lazyPrivacyInventory } from "../privacy/inventory";
+import { composedRetention } from "../retention/composed";
+import { standingHolds } from "../retention/holds";
+import { holdsUserPurge } from "../retention/holdsPurge";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "../version.generated";
 import { ENVIRONMENT_VAR } from "../worker/identity";
 import { ControlPlaneConfig, type ControlPlaneConfigInput } from "./config/config";
 import { ControlPlaneConnection } from "./data/connection";
 import { CONTROL_PLANE_CONNECTIONS_TABLE, type ControlPlaneDatabase, controlPlaneTables } from "./data/tables";
+import { recordTrustFirstCall } from "./data/trustFirstCall";
 import type { CapabilityDeclaration } from "./discovery/adminRoute";
 import { type CapabilityHealthSource, capabilityHealthSources, defineCapabilityHealth } from "./discovery/health";
 import { createControlPlaneVerifier } from "./http/guard";
@@ -27,6 +35,8 @@ import {
 import { controlplane_0001_init } from "./migrations/0001_init";
 import { controlplane_0002_management_origin } from "./migrations/0002_management_origin";
 import { controlplane_0003_connection_principal } from "./migrations/0003_connection_principal";
+import { controlplane_0004_connection_trusts } from "./migrations/0004_connection_trusts";
+import { controlplane_0005_holds } from "./migrations/0005_holds";
 import { d1ReplayGuard } from "./replay/d1Guard";
 import type { ReplayGuard } from "./replay/guard";
 import {
@@ -35,6 +45,7 @@ import {
   controlPlaneKvNamespaces,
   kvReplayGuard,
 } from "./replay/kvGuard";
+import { RETENTION_READ_SCOPE } from "./scope/scope";
 
 /**
  * Where the control-plane registration sorts in the app database. Composed key:
@@ -50,6 +61,17 @@ export const CONTROLPLANE_MIGRATION_ORDER = 1100;
 
 export type ControlPlaneOptions = ControlPlaneConfigInput;
 
+/** The standing legal holds, on the seam's own manifest entry. Behind the scope the holds listing requires. */
+export 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,
+} as const;
+
 /** The control-plane capability, with its resolved config attached. */
 export interface ControlPlaneCapability extends Capability<DatabaseSpecMap, KvNamespaceSpecMap, "controlplane"> {
   /** The resolved seam config. */
@@ -89,6 +111,8 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
     "0001_init": controlplane_0001_init,
     "0002_management_origin": controlplane_0002_management_origin,
     "0003_connection_principal": controlplane_0003_connection_principal,
+    "0004_connection_trusts": controlplane_0004_connection_trusts,
+    "0005_holds": controlplane_0005_holds,
   };
   const requiredBindings: BindingSpecInput[] = [
     // The app database — the connections table lives here, beside auth's and audit's. Not the secrets
@@ -119,6 +143,12 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
 
   const now = () => new Date();
 
+  // The issuers' key sets for every OIDC trust this Worker honors (#722), held for the life of the isolate and
+  // shared by every call. Built once here, never per request: a call naming a real trust and an invented `kid`
+  // is anonymous traffic, and without a held set and its refresh window each one would buy a round trip to the
+  // issuer — `memoryJwksCache` is what bounds that, and only if it outlives the request.
+  const jwksCache = memoryJwksCache({ now });
+
   /**
    * The replay guard for this request, chosen once by config.
    *
@@ -152,6 +182,10 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
   // (#132) — lazily, on the first control-plane read, and once for the isolate. Capturing the list costs
   // nothing; walking it is deferred, so a Worker whose control plane is never called never walks.
   let composedCapabilities: readonly Capability[] = [];
+
+  // Every presence room kind this Worker composed, with the declaration serving it, filled by the same hook.
+  // The seam's ticket route reaches every capability's rooms through it.
+  let presence: ReadonlyMap<string, PresenceDeclaration> = new Map();
   const privacy = lazyPrivacyInventory(() => composedCapabilities);
 
   const capability = defineCapability({
@@ -186,13 +220,23 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
     // The seam describes itself too. Built from the same resolved `basePath` the routes mount on, so a
     // moved mount point is reported rather than becoming a lie a client believes.
     adminRoutes: controlPlaneRouteDescriptors(config.basePath),
+    // A legal hold names the user it preserves, and outlives the purge it allowed: kept, and exported on request.
+    purge: [holdsUserPurge()],
     // Two counts on the seam's own manifest entry, so a client sees *this environment is behind* on the read
     // it already makes and calls the route only to see what. Behind `migrations:read`, which the route above
     // requires — a connection without it gets no number rather than a zero. A database that cannot be read
     // fails the producer, and the seam reports the summary unavailable rather than a partial total.
+    // And the count of standing legal holds, behind `retention:read`, which the holds listing requires.
     health: defineCapabilityHealth({
-      keys: MIGRATION_HEALTH_KEYS,
-      read: (c) => readMigrationHealth(c.env as Record<string, unknown>, migrationDatabases),
+      keys: [...MIGRATION_HEALTH_KEYS, ACTIVE_HOLDS_HEALTH_KEY],
+      read: async (c) => {
+        const env = c.env as Record<string, unknown>;
+        const [migrations, activeHolds] = await Promise.all([
+          readMigrationHealth(env, migrationDatabases),
+          standingHolds(env),
+        ]);
+        return { ...migrations, activeHolds };
+      },
     }),
     compose: ({ capabilities }) => {
       // Every capability, including those exposing nothing. A client rendering a capability it cannot
@@ -214,7 +258,16 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
         // per-request cost: a fact is resolved config, so there is nothing to ask and nothing to fail.
         configKeys: [...(cap.manifestConfig?.keys ?? [])],
         config: { ...(cap.manifestConfig?.values ?? {}) },
+        // Every room kind, with the paths built from the capability's own resolved base path.
+        presenceRooms: cap.presence ? describePresenceRooms(cap.presence) : [],
       }));
+      presence = new Map(
+        capabilities.flatMap((cap) =>
+          cap.presence
+            ? cap.presence.rooms.map((room) => [room.kind, cap.presence as PresenceDeclaration] as const)
+            : [],
+        ),
+      );
       health = capabilityHealthSources(capabilities);
       migrationDatabases = composeMigrationDatabases(capabilities);
       composedCapabilities = [...capabilities];
@@ -227,28 +280,47 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
         // on a route that has nothing to do with the seam.
         app.use("*", async (c, next) => {
           const db = database(c);
+          const environment = String((c.env as Record<string, unknown>)[ENVIRONMENT_VAR] ?? "");
           c.set(
             "controlPlaneVerifier",
-            createControlPlaneVerifier({
-              loadConnection: async (connectionId) => {
-                const row = await db
-                  .selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE)
-                  .selectAll()
-                  .where("id", "=", connectionId)
-                  .executeTakeFirst();
-                return row ? ControlPlaneConnection.parse(row) : null;
+            createControlPlaneVerifier(
+              {
+                loadConnection: async (connectionId) => {
+                  const row = await db
+                    .selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE)
+                    .selectAll()
+                    .where("id", "=", connectionId)
+                    .executeTakeFirst();
+                  return row ? ControlPlaneConnection.parse(row) : null;
+                },
+                countConnections: async () => {
+                  const rows = await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).select("id").limit(1).execute();
+                  return rows.length;
+                },
+                replay: replay(c),
+                // The environment a credential is bound to. Absent off-platform, where the empty string
+                // matches no stored connection and every call therefore denies — the right failure.
+                environment,
+                config,
+                now,
               },
-              countConnections: async () => {
-                const rows = await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).select("id").limit(1).execute();
-                return rows.length;
+              {
+                // One connection per environment (docs/CONTROL-PLANE.md §15), so a call under a trust names the
+                // trust and the environment names the connection.
+                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),
               },
-              replay: replay(c),
-              // The environment a credential is bound to. Absent off-platform, where the empty string
-              // matches no stored connection and every call therefore denies — the right failure.
-              environment: String((c.env as Record<string, unknown>)[ENVIRONMENT_VAR] ?? ""),
-              config,
-              now,
-            }),
+            ),
           );
           await next();
         });
@@ -263,6 +335,13 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
         composedMigrations: () => migrationDatabases,
         privacyInventory: privacy,
         retirement: (env) => readRetirement(env, composedCapabilities),
+        composedPresence: () => presence,
+        composition: () => composedCapabilities,
+        // The app these routes mount on is the one `createBackend` records its route table against, once every
+        // capability has mounted — so the evidence pack, reading it per call, sees every route (#821).
+        routeGroups: () => routeGroupsOf(app),
+        // The retention block as this Worker resolved it at assembly, for the manifest.
+        retention: composedRetention,
         now,
       });
     },

package/src/controlPlane/context.ts

@@ -52,11 +52,19 @@ export const ControlPlaneContext = z
     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.",
+        "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."),
+      .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).",
     ),

package/src/controlPlane/data/connection.ts

@@ -4,6 +4,7 @@
 import { z } from "zod";
 import { JsonDate, SQLiteDate, sqliteJson } from "../../data/codecs";
 import { ControlPlaneScope } from "../scope/scope";
+import { OidcTrust } from "./oidcTrust";
 
 /**
  * The registration record: who may call this Worker's control-plane routes, from where, with what
@@ -67,7 +68,7 @@ export const RegisteredKey = z
 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
@@ -121,7 +122,7 @@ export 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
@@ -141,6 +142,14 @@ export const ConnectionPurpose = z
   );
 export type ConnectionPurpose = z.output<typeof ConnectionPurpose>;
 
+/** Which credential kinds a connection holds, live or not. */
+export 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`.",
+  );
+export type ConnectionCredentialKind = z.infer<typeof ConnectionCredentialKind>;
+
 /**
  * One management-client connection — the row in `pithy_controlplane_connections`.
  *
@@ -208,6 +217,11 @@ export const ControlPlaneConnection = z
     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.",