@pithy-sh/core 0.13.0 → 0.14.0

package/src/controlPlane/http/handlers.ts

@@ -2,24 +2,36 @@
 // SPDX-License-Identifier: MIT
 
 import type { Context } from "hono";
-import type { PithyHonoEnv } from "../../capability/capability";
+import type { Capability, PithyHonoEnv } from "../../capability/capability";
+import { commandName } from "../../cli/command";
 import { causeMessage } from "../../error/cause";
+import type { RouteGroup } from "../../openapi/document";
+import type { PresenceDeclaration } from "../../presence/declaration";
 import { privacyAttestation, privacyPosture } from "../../privacy/posture";
 import type { PrivacyInventory } from "../../privacy/report";
 import type { RetirementVerdict } from "../../privacy/retirement";
+import type { EffectiveRetention } from "../../retention/policy";
 import { workerVersionMetadata } from "../../worker/identity";
 import { ControlPlaneAuditActions, safeEmit } from "../audit/actions";
 import type { ControlPlaneConfig } from "../config/config";
 import type { ControlPlaneContext } from "../context";
-import { ControlPlaneConnection, type RegisteredKey } from "../data/connection";
+import type { RegisteredKey } from "../data/connection";
+import { type ConnectionForWrite, readConnectionForWrite, writeKeys } from "../data/connections";
 import { appendKey, expireKey, pruneKeys } from "../data/keyLifecycle";
-import { CONTROL_PLANE_CONNECTIONS_TABLE, type ControlPlaneDatabase } from "../data/tables";
+import type { OidcTrust } from "../data/oidcTrust";
+import type { ControlPlaneDatabase } from "../data/tables";
 import type { CapabilityDeclaration, ControlPlaneManifestWire } from "../discovery/adminRoute";
 import { type CapabilityHealthSource, readCapabilityHealth } from "../discovery/health";
 import { healthWire } from "../discovery/healthSummary";
+import { routeInputs, withRouteInputs } from "../discovery/routeInput";
+import { readErasurePeriod, readErasureSubject } from "../erasure/read";
 import { ControlPlaneInvalidCredentialError, ControlPlaneKeyConflictError } from "../error/errors";
+import { readEvidencePack } from "../evidence/pack";
 import { type ComposedMigrationDatabase, readDatabaseMigrations } from "../migrationState/migrationState";
 import type {
+  ControlPlaneErasurePeriodResponse,
+  ControlPlaneErasureSubjectResponse,
+  ControlPlaneEvidenceResponse,
   ControlPlaneKeysResponse,
   ControlPlaneMigrationsResponse,
   ControlPlanePingResponse,
@@ -27,8 +39,15 @@ import type {
   ExpireKeyResponse,
   PublicKeyView,
   RegisterKeyResponse,
+  TrustView,
 } from "./responses";
-import type { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas";
+import type {
+  ErasurePeriodQuery,
+  ErasureSubjectParams,
+  ExpireKeyParams,
+  ExpireKeyRequest,
+  RegisterKeyRequest,
+} from "./schemas";
 
 /**
  * The seam's own route handlers.
@@ -77,25 +96,45 @@ export interface ControlPlaneHandlerDeps {
   composedHealth: () => ReadonlyMap<string, CapabilityHealthSource>;
   /**
    * Every database this Worker binds, with the provider this build composes for it — captured by the same
-   * `compose` hook through `collectMigrationSets`, the function `pithy migrate` composes with (#729).
+   * `compose` hook through `collectMigrationSets`, the function `pithy migrate` composes with.
    */
   composedMigrations: () => readonly ComposedMigrationDatabase[];
   /**
-   * The privacy inventory of every storage schema this Worker composed (#132), walked on the first call and
+   * The privacy inventory of every storage schema this Worker composed, walked on the first call and
    * cached for the isolate. A thunk, so a Worker whose control plane is never called never walks.
    */
   privacyInventory: () => PrivacyInventory;
   /**
-   * The field key's retirement verdict (#390): the guard over this Worker's encrypted columns, read through its own
+   * The field key's retirement verdict: the guard over this Worker's encrypted columns, read through its own
    * bindings. Never throws: whatever it cannot read is incomplete coverage.
    */
   retirement: (env: Record<string, unknown>) => Promise<RetirementVerdict>;
+  /**
+   * Every presence room kind this Worker composed, by kind, with the declaration that serves it — captured
+   * by the same `compose` hook. A thunk for the same reason as {@link composedCapabilities}.
+   */
+  composedPresence: () => ReadonlyMap<string, PresenceDeclaration>;
+  /**
+   * Every capability this Worker composed, as the objects themselves — the evidence pack reads which one records
+   * audit events and the bindings it writes through. A thunk for the same reason as the rest.
+   */
+  composition: () => readonly Capability[];
+  /**
+   * The route table `createBackend` recorded for the app these routes mounted on, or `undefined` for an app it did
+   * not assemble. Read per call, after every capability's routes have mounted, so the evidence pack sees them all.
+   */
+  routeGroups: () => readonly RouteGroup[] | undefined;
+  /**
+   * The retention block as this Worker resolved it at assembly, or null when no backend recorded one. The
+   * manifest reports it.
+   */
+  retention?: () => EffectiveRetention | null;
   /** The clock, injected so a test can stand at any instant. */
   now: () => Date;
 }
 
 /** The verified caller. Never null here — `requireControlPlane` ran first, or this code is unreachable. */
-function caller(c: Context<PithyHonoEnv>): ControlPlaneContext {
+export function caller(c: Context<PithyHonoEnv>): ControlPlaneContext {
   const context = c.var.controlPlane;
   if (!context) {
     // Defense in depth against a route line assembled without the gate. It cannot happen through
@@ -106,37 +145,33 @@ function caller(c: Context<PithyHonoEnv>): ControlPlaneContext {
   return context;
 }
 
-/** Load the connection this call authenticated against. It verified moments ago, so it exists. */
-async function loadConnection(
-  db: ControlPlaneDatabase,
-  connectionId: string,
-): Promise<{ connection: ControlPlaneConnection }> {
-  const row = await db
-    .selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE)
-    .selectAll()
-    .where("id", "=", connectionId)
-    .executeTakeFirst();
-  if (!row) {
+/** Load the connection this call authenticated against, as stored, for a key write. It verified moments ago. */
+async function loadConnection(db: ControlPlaneDatabase, connectionId: string): Promise<ConnectionForWrite> {
+  const loaded = await readConnectionForWrite(db, connectionId);
+  if (loaded === null) {
     // The row was deleted between verification and here — a revocation landing mid-request. Denying is
     // the correct answer: revocation is meant to be immediate.
     throw new ControlPlaneInvalidCredentialError({ detail: `connection ${connectionId} disappeared mid-request` });
   }
-  return { connection: ControlPlaneConnection.parse(row) };
+  return loaded;
 }
 
-/** Write a connection's key array back, stamping `updatedAt`. One UPDATE — a rotation cannot half-apply. */
+/**
+ * Write a connection's key array back, stamping `updatedAt`. One UPDATE, so a rotation cannot half-apply, and only
+ * while the keys are still what `loaded` read: a revocation landing between the read and this write is never undone.
+ */
 async function saveKeys(
   db: ControlPlaneDatabase,
-  connectionId: string,
+  loaded: ConnectionForWrite,
   keys: readonly RegisteredKey[],
   now: Date,
 ): Promise<void> {
-  const encoded = ControlPlaneConnection.shape.keys.encode([...keys]);
-  await db
-    .updateTable(CONTROL_PLANE_CONNECTIONS_TABLE)
-    .set({ keys: encoded, updatedAt: ControlPlaneConnection.shape.updatedAt.encode(now) })
-    .where("id", "=", connectionId)
-    .execute();
+  if (await writeKeys(db, loaded, keys, now)) return;
+  throw new ControlPlaneKeyConflictError({
+    message: "The connection's keys changed while this call ran.",
+    action: "Make the call again.",
+    detail: `connection ${loaded.connection.id} had its keys written between this call's read and its write`,
+  });
 }
 
 /**
@@ -156,6 +191,37 @@ function publicKeyView(key: RegisteredKey): PublicKeyView {
   };
 }
 
+/** The public view of one OIDC trust: its issuer, audience and claims — the population it admits. */
+function trustView(trust: OidcTrust): TrustView {
+  return {
+    trustId: trust.trustId,
+    issuer: trust.issuer,
+    audience: trust.audience,
+    claims: { ...trust.claims },
+    authorizedBy: trust.authorizedBy,
+    validFrom: trust.validFrom.toISOString(),
+    revokedAt: trust.revokedAt?.toISOString() ?? null,
+    firstCallAt: trust.firstCallAt?.toISOString() ?? null,
+  };
+}
+
+/**
+ * Refuse a key write to a caller that verified under an OIDC trust.
+ *
+ * A trust exists so that no key is held on the workload's host. Letting a trust's caller register a key would
+ * turn a short-lived identity into a standing credential at the first call — an exchange by another name, and
+ * the custody the trust was registered to avoid. Granting `keys:rotate` to a connection is a statement about
+ * its keys, never a license for a workload to mint one.
+ */
+function refuseTrustCaller(context: ControlPlaneContext, what: string): void {
+  if (context.credentialKind !== "trust") return;
+  throw new ControlPlaneKeyConflictError({
+    message: "A call under a workload trust cannot change this connection's keys.",
+    action: `Register or expire a key from a client that holds one, or with ${commandName("dashboard connect")}.`,
+    detail: `${what} refused: trust ${context.keyId} verified this call`,
+  });
+}
+
 /**
  * `GET /control-plane/ping` — connectivity and key proof.
  *
@@ -186,11 +252,11 @@ export function pingHandler(deps: ControlPlaneHandlerDeps) {
  * Discovery over configuration. A client builds its navigation from this rather than from settings
  * someone maintains, so a Worker with no payments capability has no purchases pane as a matter of fact.
  *
- * **And the numbers a client would otherwise pay a second round trip for** (#317). Each capability's
+ * **And the numbers a client would otherwise pay a second round trip for**. Each capability's
  * bounded summary is resolved here, behind the scope that capability's own read is behind: a connection
  * without it gets no number rather than a zero, and never costs the adopter's Worker the query.
  *
- * **One capability's failure costs one capability's number** (#350). A producer that throws, or that
+ * **One capability's failure costs one capability's number**. A producer that throws, or that
  * reports something its declaration cannot name, lands on `unavailable` for that entry alone —
  * `readCapabilityHealth` catches it, so nothing rejects, so `Promise.all` still resolves and every
  * sibling still reports. This route is what the whole management surface is built from; a manifest that
@@ -198,13 +264,21 @@ export function pingHandler(deps: ControlPlaneHandlerDeps) {
  * name.
  */
 export function manifestHandler(deps: ControlPlaneHandlerDeps) {
+  // Each admin route's input, converted once per route table rather than once per read. Keyed on the
+  // table itself, so an app whose groups were recorded late is converted when it first has them.
+  let converted: { groups: readonly RouteGroup[]; inputs: ReturnType<typeof routeInputs> } | undefined;
+  const inputsFor = (groups: readonly RouteGroup[] | undefined) => {
+    if (groups === undefined) return undefined;
+    if (converted?.groups !== groups) converted = { groups, inputs: routeInputs(groups) };
+    return converted.inputs;
+  };
   return async (c: Context<PithyHonoEnv>) => {
     const context = caller(c);
     const sources = deps.composedHealth();
     // In parallel: each producer is bounded by its own declaration, and a Worker composing several has
     // no reason to serialize numbers that do not depend on each other.
     const capabilities = await Promise.all(
-      deps.composedCapabilities().map(async (declaration) => ({
+      withRouteInputs(deps.composedCapabilities(), inputsFor(deps.routeGroups())).map(async (declaration) => ({
         ...declaration,
         // Spread, so the values and the failure flag are written together or not at all. A handler that
         // set one and forgot the other is the shape of defect the four-state value exists to prevent.
@@ -220,24 +294,32 @@ export function manifestHandler(deps: ControlPlaneHandlerDeps) {
       environment: context.environment,
       connectionId: context.connectionId,
       version: build.id,
-      // Beside the id, because the id alone cannot tell a deploy from a rollback (#132): a rollback
+      // Beside the id, because the id alone cannot tell a deploy from a rollback: a rollback
       // reactivates a version already seen, and this is the one field that moves backwards when it does.
       versionCreatedAt: build.createdAt,
       // Classes and counts, never field names — those are `GET /privacy`'s, behind their own scope. A project
       // that declared nothing walks nothing; otherwise the walk is the isolate's cached one.
-      // The retirement verdict beside it (#390), so a dashboard reads the guard rather than inferring it.
+      // The retirement verdict beside it, so a dashboard reads the guard rather than inferring it.
       privacy: {
         ...privacyPosture(privacyAttestation(c.env), deps.privacyInventory),
         retirement: await deps.retirement(c.env as Record<string, unknown>),
       },
       capabilities,
       grantedScopes: [...context.grantedScopes],
+      // How long this Worker keeps what it holds, as it takes effect: policy, not data, so on every manifest.
+      ...retentionOf(deps),
     } satisfies ControlPlaneManifestWire);
   };
 }
 
+/** The resolved retention for the manifest, or nothing where this Worker recorded none. */
+function retentionOf(deps: ControlPlaneHandlerDeps): { retention?: EffectiveRetention } {
+  const retention = deps.retention?.() ?? null;
+  return retention === null ? {} : { retention };
+}
+
 /**
- * `GET /control-plane/migrations` — where each database this Worker binds stands (#729).
+ * `GET /control-plane/migrations` — where each database this Worker binds stands.
  *
  * Read-only: it reports, and nothing over the seam runs, reverses or resets a migration.
  *
@@ -274,10 +356,11 @@ export function listKeysHandler(deps: ControlPlaneHandlerDeps) {
       environment: connection.environment,
       keys: connection.keys.map(publicKeyView),
       // The review a credential listing exists for needs these, and it is the adopter's to perform —
-      // on their own side, from their own row (#721).
+      // on their own side, from their own row.
       authorizedBy: connection.authorizedBy,
       actorKind: connection.actorKind,
       purpose: connection.purpose,
+      trusts: (connection.trusts ?? []).map(trustView),
     } satisfies ControlPlaneKeysResponse);
   };
 }
@@ -295,9 +378,11 @@ export function listKeysHandler(deps: ControlPlaneHandlerDeps) {
 export function registerKeyHandler(deps: ControlPlaneHandlerDeps) {
   return async (c: Context<PithyHonoEnv>, body: RegisterKeyRequest) => {
     const context = caller(c);
+    refuseTrustCaller(context, "key registration");
     const db = deps.database(c);
     const now = deps.now();
-    const { connection } = await loadConnection(db, context.connectionId);
+    const loaded = await loadConnection(db, context.connectionId);
+    const { connection } = loaded;
 
     const appended = appendKey(
       connection.keys,
@@ -309,7 +394,7 @@ export function registerKeyHandler(deps: ControlPlaneHandlerDeps) {
       retentionMs: deps.config.keyRetentionDays * MS_PER_DAY,
       maxKeys: deps.config.maxKeys,
     });
-    await saveKeys(db, connection.id, pruned, now);
+    await saveKeys(db, loaded, pruned, now);
 
     await safeEmit(
       c.var.emit,
@@ -365,9 +450,11 @@ export function registerKeyHandler(deps: ControlPlaneHandlerDeps) {
 export function expireKeyHandler(deps: ControlPlaneHandlerDeps) {
   return async (c: Context<PithyHonoEnv>, params: ExpireKeyParams, body: ExpireKeyRequest) => {
     const context = caller(c);
+    refuseTrustCaller(context, "key expiry");
     const db = deps.database(c);
     const now = deps.now();
-    const { connection } = await loadConnection(db, context.connectionId);
+    const loaded = await loadConnection(db, context.connectionId);
+    const { connection } = loaded;
 
     if (body.provenKeyId !== context.keyId) {
       throw new ControlPlaneKeyConflictError({
@@ -378,7 +465,7 @@ export function expireKeyHandler(deps: ControlPlaneHandlerDeps) {
     }
 
     const expired = expireKey(connection.keys, params.keyId, { provenKeyId: body.provenKeyId, now });
-    await saveKeys(db, connection.id, expired, now);
+    await saveKeys(db, loaded, expired, now);
 
     await safeEmit(
       c.var.emit,
@@ -412,7 +499,7 @@ export function expireKeyHandler(deps: ControlPlaneHandlerDeps) {
 }
 
 /**
- * `GET /control-plane/privacy` — the full privacy inventory (#132).
+ * `GET /control-plane/privacy` — the full privacy inventory.
  *
  * Every storage schema this Worker composed that holds a marked field, each field's path and class, and where it
  * is stored — derived from the running code, so unmarking a field removes it on the next deploy with nothing in
@@ -438,3 +525,48 @@ export function privacyHandler(deps: ControlPlaneHandlerDeps) {
     } satisfies ControlPlanePrivacyResponse);
   };
 }
+
+/**
+ * `GET /control-plane/evidence` — the evidence pack.
+ *
+ * SOC 2 and ISO 27001 evidence derived from what this Worker composes, records and declares: each control's
+ * references, the facts read and their sources, and `evidenced`, `gap` or `not-derivable` with the reason. It
+ * proves controls present and performs nothing. Behind `evidence:read`, and it never widens another scope: what
+ * a capability keeps behind its own read stays there. Read-only.
+ */
+export function evidenceHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>) => {
+    const context = caller(c);
+    return c.json((await readEvidencePack(c, deps, context)) satisfies ControlPlaneEvidenceResponse);
+  };
+}
+
+/**
+ * `GET /control-plane/erasure/:subjectType/:subjectId` — one subject's erasure, attested.
+ *
+ * Read from the purge's own lifecycle rows, through the capability that owns the subject, and cited in the audit
+ * chain through the composed audit. A subject with no deletion in force is a 404. Read-only.
+ */
+export function erasureSubjectHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>, params: ErasureSubjectParams) => {
+    caller(c);
+    const env = (c.env ?? {}) as Record<string, unknown>;
+    return c.json(
+      (await readErasureSubject(
+        env,
+        deps,
+        params.subjectType,
+        params.subjectId,
+      )) satisfies ControlPlaneErasureSubjectResponse,
+    );
+  };
+}
+
+/** `GET /control-plane/erasure?since&until` — every purge in a period, counted. Read-only. */
+export function erasurePeriodHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>, query: ErasurePeriodQuery) => {
+    caller(c);
+    const env = (c.env ?? {}) as Record<string, unknown>;
+    return c.json((await readErasurePeriod(env, deps, query)) satisfies ControlPlaneErasurePeriodResponse);
+  };
+}

package/src/controlPlane/http/holds.ts

@@ -0,0 +1,108 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { countActiveHolds, listHolds, placeHold, releaseHold } from "../../retention/holds";
+import { ControlPlaneAuditActions, safeEmit } from "../audit/actions";
+import type { LegalHold } from "../data/hold";
+import { type ControlPlaneHandlerDeps, caller } from "./handlers";
+import type { ControlPlaneHoldResponse, ControlPlaneHoldsResponse, LegalHoldView } from "./responses";
+import type { HoldListQuery, HoldParams, PlaceHoldRequest, ReleaseHoldRequest } from "./schemas";
+
+/**
+ * The legal-hold routes: place, release, list.
+ *
+ * Placing and releasing are each audited under `controlplane/*`, which the retention floor keeps at least a year,
+ * with the subject, the hold and the reason. A hold suspends every purge, prune and inactivity deletion touching its
+ * subject; the capabilities that erase read it through `retention/holds.ts`. **Nothing here shortens a retention**:
+ * a hold can only preserve, and its release returns the subject to the policy the Worker was deployed with.
+ */
+
+/** The default page of `GET /control-plane/holds`. */
+const DEFAULT_HOLD_LIMIT = 100;
+
+/** A hold, as the routes answer it. */
+export function holdView(hold: LegalHold): LegalHoldView {
+  return {
+    id: hold.id,
+    subjectType: hold.subjectType,
+    subjectId: hold.subjectId,
+    reason: hold.reason,
+    placedBy: hold.placedBy,
+    placedAt: hold.placedAt.toISOString(),
+    state: hold.state,
+    releasedAt: hold.releasedAt?.toISOString() ?? null,
+    releasedBy: hold.releasedBy,
+    releaseReason: hold.releaseReason,
+  };
+}
+
+/** The audit event for a placement or a release: the subject as the resource, the hold and the reason beside it. */
+async function auditHold(c: Context<PithyHonoEnv>, action: string, hold: LegalHold, reason: string): Promise<void> {
+  const context = caller(c);
+  await safeEmit(
+    c.var.emit,
+    {
+      action,
+      outcome: "success",
+      severity: "warning",
+      actorType: "control-plane",
+      actorId: context.subject,
+      resourceType: hold.subjectType === "audit" ? "audit_trail" : hold.subjectType,
+      resourceId: hold.subjectId,
+      requestId: c.req.header("cf-ray"),
+      ip: c.req.header("cf-connecting-ip"),
+      userAgent: c.req.header("user-agent"),
+      metadata: { holdId: hold.id, subjectType: hold.subjectType, reason },
+    },
+    c.var.log,
+  );
+}
+
+/** `POST /control-plane/holds` — place a hold. */
+export function placeHoldHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>, body: PlaceHoldRequest) => {
+    const context = caller(c);
+    const hold = await placeHold(deps.database(c), {
+      subjectType: body.subjectType,
+      subjectId: body.subjectId,
+      reason: body.reason,
+      actor: { subject: context.subject },
+      at: deps.now(),
+    });
+    await auditHold(c, ControlPlaneAuditActions.holdPlaced, hold, body.reason);
+    return c.json({ hold: holdView(hold) } satisfies ControlPlaneHoldResponse, 201);
+  };
+}
+
+/** `POST /control-plane/holds/:holdId/release` — release a hold, with a reason. */
+export function releaseHoldHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>, params: HoldParams, body: ReleaseHoldRequest) => {
+    const context = caller(c);
+    const hold = await releaseHold(deps.database(c), {
+      id: params.holdId,
+      reason: body.reason,
+      actor: { subject: context.subject },
+      at: deps.now(),
+    });
+    await auditHold(c, ControlPlaneAuditActions.holdReleased, hold, body.reason);
+    return c.json({ hold: holdView(hold) } satisfies ControlPlaneHoldResponse);
+  };
+}
+
+/** `GET /control-plane/holds` — every hold, standing first. Read-only. */
+export function listHoldsHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>, query: HoldListQuery) => {
+    caller(c);
+    const db = deps.database(c);
+    const holds = await listHolds(db, {
+      ...(query.state ? { state: query.state } : {}),
+      limit: query.limit ?? DEFAULT_HOLD_LIMIT,
+    });
+    return c.json({
+      active: await countActiveHolds(db),
+      holds: holds.map(holdView),
+    } satisfies ControlPlaneHoldsResponse);
+  };
+}

package/src/controlPlane/http/presence.ts

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context, MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { NotFoundError } from "../../error/pithyError";
+import type { PresenceTicket } from "../../presence/http/responses";
+import { issuePresenceTicket, roomKind } from "../../presence/http/routes";
+import type { ControlPlanePresenceTicketRequest } from "../../presence/http/schemas";
+import { ANY_VERIFIED_CALLER, type ControlPlaneRequirement } from "../scope/scope";
+import { type ControlPlaneRequirementResolver, requireControlPlaneFor } from "./guard";
+import type { ControlPlaneHandlerDeps } from "./handlers";
+
+/**
+ * `POST /control-plane/presence/tickets` — a ticket into any room this Worker composes, for a management
+ * client.
+ *
+ * **The scope is the room kind's, and the gate checks it.** Which scope a call needs is named in its body, so
+ * {@link presenceTicketRequirement} reads the kind from a copy of the body before the gate verifies, and the
+ * gate then verifies against that kind's scope exactly as it would against a route's own: one allowed row
+ * when it covers, one denial row naming the kind's scope when it does not, never both. Presence adds no scope
+ * of its own: a connection that may read a record may see who else has it open.
+ *
+ * A body that names no declared kind needs only a verified caller, so an unverified one is refused before any
+ * kind is looked at, and a verified one then gets the handler's 404 — the manifest lists every kind, so its
+ * existence is no secret.
+ */
+export function presenceTicketRequirement(deps: ControlPlaneHandlerDeps): ControlPlaneRequirementResolver {
+  return async (c) => {
+    const kind = await bodyKind(c.req.raw);
+    const presence = kind === undefined ? undefined : deps.composedPresence().get(kind);
+    if (kind === undefined || !presence) return ANY_VERIFIED_CALLER;
+    return roomKind(presence, kind).scope as ControlPlaneRequirement;
+  };
+}
+
+/** The gate the route wears: {@link requireControlPlaneFor} over the room kind's scope. */
+export function presenceTicketGate(deps: ControlPlaneHandlerDeps): MiddlewareHandler<PithyHonoEnv> {
+  return requireControlPlaneFor(presenceTicketRequirement(deps));
+}
+
+/**
+ * The body's `kind`, read from a copy so the route's validator still reads the original. Only to choose a
+ * scope: the validator is what parses the body, and anything unreadable here is simply no kind.
+ */
+async function bodyKind(request: Request): Promise<string | undefined> {
+  try {
+    const body: unknown = await request.clone().json();
+    const kind = typeof body === "object" && body !== null ? (body as { kind?: unknown }).kind : undefined;
+    return typeof kind === "string" ? kind : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The handler, behind {@link presenceTicketGate}: the kind's scope is already verified, so it mints. */
+export function presenceTicketHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>, body: ControlPlanePresenceTicketRequest): Promise<Response> => {
+    const presence = deps.composedPresence().get(body.kind);
+    if (!presence) throw new NotFoundError({ message: "That room kind does not exist.", params: { kind: body.kind } });
+    const room = roomKind(presence, body.kind);
+    const ticket = await issuePresenceTicket(c, presence, {
+      kind: room.kind,
+      recordId: body.recordId,
+      ref: body.participant.ref,
+      name: body.participant.name,
+      origin: "control-plane",
+    });
+    return c.json(ticket satisfies PresenceTicket, 201);
+  };
+}

package/src/controlPlane/http/processing.ts

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { readProcessingRecord } from "../processing/read";
+import { type ControlPlaneHandlerDeps, caller } from "./handlers";
+import type { ControlPlaneProcessingResponse } from "./responses";
+
+/**
+ * `GET /control-plane/processing` — the record of processing activities, GDPR Article 30. Each activity's purpose,
+ * classes, legal basis, recipients, retention and measures, and every gap named. Read-only.
+ */
+export function processingHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>) => {
+    const context = caller(c);
+    return c.json((await readProcessingRecord(c, deps, context)) satisfies ControlPlaneProcessingResponse);
+  };
+}