@pithy-sh/core 0.13.0 → 0.15.0

package/src/controlPlane/processing/read.ts

@@ -0,0 +1,102 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import type { ConsentPurpose } from "../../consent/purpose";
+import { type ConsentReader, composedConsent, composedConsentPurposes } from "../../consent/reader";
+import { causeMessage } from "../../error/cause";
+import type { PrivacyInventory } from "../../privacy/report";
+import { composedProcessing, effectiveProcessing } from "../../processing/composed";
+import { workerVersionMetadata } from "../../worker/identity";
+import type { ControlPlaneContext } from "../context";
+import type { EvidenceControlId, EvidenceState } from "../evidence/mapping";
+import { readEvidencePack } from "../evidence/pack";
+import type { ControlPlaneHandlerDeps } from "../http/handlers";
+import type { ControlPlaneProcessingResponse } from "../http/responses";
+import { EVIDENCE_READ_SCOPE, PRIVACY_READ_SCOPE } from "../scope/scope";
+import { type ConsentInput, deriveProcessingRecord, workersAiRecipients } from "./derive";
+
+/**
+ * The reads behind the processing record: what the Worker composes, declares and records, gathered once per call.
+ * Each read that fails costs the record what it would have said, named in `notDerivable`, and the record still
+ * answers. A cause goes to the Worker's log and never into the record.
+ *
+ * **It never widens a scope.** The measures carry the evidence pack's states only when the connection also holds
+ * `evidence:read`; without it they are cited by control and their state is null. A gap names a stored table or field
+ * only when the connection also holds `privacy:read`; without it, the capability and the class.
+ */
+
+/** The privacy inventory, or null where the walk threw. */
+function inventoryOf(c: Context<PithyHonoEnv>, deps: ControlPlaneHandlerDeps): PrivacyInventory | null {
+  try {
+    return deps.privacyInventory();
+  } catch (cause) {
+    c.var.log.warn("processing: privacy inventory unreadable", { reason: causeMessage(cause) ?? String(cause) });
+    return null;
+  }
+}
+
+/** What the composed consent capability says, or that none is composed. */
+async function consentOf(c: Context<PithyHonoEnv>, deps: ControlPlaneHandlerDeps): Promise<ConsentInput> {
+  const composition = deps.composition();
+  const declared = composedConsentPurposes(composition);
+  const reader = composedConsent(composition, c.env as Record<string, unknown>);
+  if (reader === null) return { state: "not-composed", declared };
+  if (reader.standings !== undefined) {
+    try {
+      return { state: "read", standings: await reader.standings() };
+    } catch (cause) {
+      c.var.log.warn("processing: consent record unreadable", { reason: causeMessage(cause) ?? String(cause) });
+    }
+  }
+  return { state: "unreadable", catalog: catalogOf(c, reader) };
+}
+
+/** The reader's whole catalog from memory, or null where it cannot list one. */
+function catalogOf(c: Context<PithyHonoEnv>, reader: ConsentReader): readonly ConsentPurpose[] | null {
+  if (reader.purposes === undefined) return null;
+  try {
+    return reader.purposes();
+  } catch (cause) {
+    c.var.log.warn("processing: consent catalog unreadable", { reason: causeMessage(cause) ?? String(cause) });
+    return null;
+  }
+}
+
+/** Each control's state, read through the evidence pack, or null without `evidence:read`. */
+async function measuresOf(
+  c: Context<PithyHonoEnv>,
+  deps: ControlPlaneHandlerDeps,
+  context: ControlPlaneContext,
+): Promise<Partial<Record<EvidenceControlId, EvidenceState>> | null> {
+  if (!context.grantedScopes.includes(EVIDENCE_READ_SCOPE)) return null;
+  const pack = await readEvidencePack(c, deps, context);
+  return Object.fromEntries(pack.controls.map((entry) => [entry.control, entry.state]));
+}
+
+/** Read everything the record derives from, and derive it. */
+export async function readProcessingRecord(
+  c: Context<PithyHonoEnv>,
+  deps: ControlPlaneHandlerDeps,
+  context: ControlPlaneContext,
+): Promise<ControlPlaneProcessingResponse> {
+  const env = c.env as Record<string, unknown>;
+  const composition = deps.composition();
+  const [consent, measures] = await Promise.all([consentOf(c, deps), measuresOf(c, deps, context)]);
+  const record = deriveProcessingRecord({
+    activities: composedProcessing() ?? effectiveProcessing(undefined, composition),
+    inventory: inventoryOf(c, deps),
+    retention: deps.retention?.() ?? null,
+    consent,
+    bindingRecipients: workersAiRecipients(composition, env),
+    measures,
+    fieldNames: context.grantedScopes.includes(PRIVACY_READ_SCOPE),
+  });
+  return {
+    environment: context.environment,
+    generatedAt: deps.now().toISOString(),
+    version: workerVersionMetadata(c.env).id,
+    ...record,
+  };
+}

package/src/controlPlane/scope/kind.ts

@@ -0,0 +1,63 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * What kind of operation a control-plane scope grants, declared by the capability that owns the scope.
+ *
+ * Scopes are federated and open, so a management client cannot tell from the string whether `auth:users:suspend`
+ * reads, writes or does something worse. The kind is the closed vocabulary it maps its own roles onto instead: the
+ * app tools' effects, with `reads` beneath them and `credentials` (mints, rotates or revokes a credential) above.
+ * Ordered from least to most restrictive. Written out rather than spread from `TOOL_EFFECTS`, so a scope declaration
+ * stays importable from a browser program without the route machinery; `kind.test.ts` holds the two together.
+ */
+export const SCOPE_KINDS = ["reads", "writes", "sends", "charges", "deletes", "credentials"] as const;
+
+export const ScopeKind = z
+  .enum(SCOPE_KINDS)
+  .describe(
+    "What kind of operation a scope grants: `reads`, `writes`, `sends` (mail or a message leaves the system), `charges` (money or an entitlement moves), `deletes`, or `credentials` (a credential is minted, rotated or revoked).",
+  );
+export type ScopeKind = z.infer<typeof ScopeKind>;
+
+/** The kind a client assumes for a scoped route that states none: a Worker too old to say. */
+export const MOST_RESTRICTIVE_SCOPE_KIND: ScopeKind = "credentials";
+
+/** The part of an admin route a kind is read from. */
+export interface ScopedRoute {
+  readonly scope: string | null;
+  readonly kind?: ScopeKind | undefined;
+}
+
+/**
+ * The kind of a route as a client reads it: its declared kind, {@link MOST_RESTRICTIVE_SCOPE_KIND} for a scoped
+ * route that declares none, and null for a route with no scope, which grants nothing to classify.
+ */
+export function scopeKindOf(route: ScopedRoute): ScopeKind | null {
+  if (route.scope === null) return null;
+  return route.kind ?? MOST_RESTRICTIVE_SCOPE_KIND;
+}
+
+/** One scope whose routes declare more than one kind. */
+export interface ScopeKindConflict {
+  readonly scope: string;
+  /** Every kind declared for it, in the order first seen. */
+  readonly kinds: readonly ScopeKind[];
+}
+
+/**
+ * Every scope whose routes disagree about its kind. Holding a scope confers every route that requires it, so a
+ * scope has exactly one kind, and two routes declaring different ones is a declaration to fix.
+ */
+export function scopeKindConflicts(routes: Iterable<ScopedRoute>): ScopeKindConflict[] {
+  const kinds = new Map<string, ScopeKind[]>();
+  for (const route of routes) {
+    const kind = scopeKindOf(route);
+    if (route.scope === null || kind === null) continue;
+    const seen = kinds.get(route.scope) ?? [];
+    if (!seen.includes(kind)) seen.push(kind);
+    kinds.set(route.scope, seen);
+  }
+  return [...kinds].filter(([, seen]) => seen.length > 1).map(([scope, seen]) => ({ scope, kinds: seen }));
+}

package/src/controlPlane/scope/scope.ts

@@ -79,7 +79,7 @@ export const KEYS_ROTATE_SCOPE: ControlPlaneScope = "keys:rotate";
 
 /**
  * Read where each database this Worker binds stands: what is applied, what is pending, what is undeclared,
- * and which run put it there (#729). Read-only by construction — every route behind it is a `GET`, and
+ * and which run put it there. Read-only by construction — every route behind it is a `GET`, and
  * nothing over the seam runs, reverses or resets a migration. The two migration health keys on the seam's
  * manifest entry sit behind it too, so a connection without it gets no number rather than a zero.
  */
@@ -87,7 +87,7 @@ export const MIGRATIONS_READ_SCOPE: ControlPlaneScope = "migrations:read";
 
 /**
  * Read this Worker's full privacy inventory: every storage schema holding a marked field, each marked field's
- * path, its class, and where it is stored (#132). Read-only — the one route behind it is a `GET`.
+ * path, its class, and where it is stored. Read-only — the one route behind it is a `GET`.
  *
  * **Its own scope rather than `manifest:read`**, because field names are the kind of thing an adopter may
  * reasonably withhold from a client that has no business seeing them. The manifest's privacy block carries
@@ -95,11 +95,73 @@ export const MIGRATIONS_READ_SCOPE: ControlPlaneScope = "migrations:read";
  */
 export const PRIVACY_READ_SCOPE: ControlPlaneScope = "privacy:read";
 
+/**
+ * Read this Worker's evidence pack: the SOC 2 and ISO 27001 evidence it derives from its own declarations.
+ * Read-only — the one route behind it is a `GET`, and it performs nothing it reports on.
+ *
+ * **Its own scope**, because the pack reads across the seam: every connection's principal, kind, purpose and
+ * grant, and every route's verification. It never widens another scope. A fact a capability keeps behind its own
+ * read — migration counts behind {@link MIGRATIONS_READ_SCOPE}, a capability's health behind that capability's
+ * scope — stays behind it, and a connection without that scope gets `not-derivable` naming it.
+ */
+export const EVIDENCE_READ_SCOPE: ControlPlaneScope = "evidence:read";
+
+/**
+ * Read the erasure attestation: one subject's purge, or every purge in a period, with the audit events that
+ * record each step. Read-only — both routes behind it are `GET`s — and kind `reads`.
+ *
+ * **Its own scope**, because it answers across subjects: which accounts and organizations were deleted, by which
+ * kind of actor and why. It carries nothing about a person beyond the id the lifecycle trail already keeps, and it
+ * never widens `audit:events:read`: it cites an event by id and chain position, never its contents.
+ */
+export const ERASURE_READ_SCOPE: ControlPlaneScope = "erasure:read";
+
+/**
+ * Read the record of processing activities, GDPR Article 30: each activity's purpose, data classes, legal basis,
+ * recipients, retention and measures, and every gap. Read-only — the one route behind it is a `GET` — and kind
+ * `reads`.
+ *
+ * **Its own scope**, because it reads across the Worker: every activity, the consent counts behind each consent
+ * basis, and where each stored class sits. It never widens another: the measures carry the evidence pack's states
+ * only for a connection that also holds {@link EVIDENCE_READ_SCOPE}, and a gap names a stored table or field only for
+ * one that also holds {@link PRIVACY_READ_SCOPE}. Without it, a gap names the capability and the class.
+ */
+export const PROCESSING_READ_SCOPE: ControlPlaneScope = "processing:read";
+
+/**
+ * Place and release a legal hold on a user, an organization or a tenant's audit trail. A write — both routes
+ * behind it are `POST`s — and kind `writes`, so `pithy dashboard connect` offers it and never grants it by default.
+ *
+ * **It can only preserve.** A hold suspends purges, prunes and inactivity deletions; releasing one returns the subject
+ * to the policy the Worker deploys with. No route behind it, or anywhere, shortens a retention.
+ */
+export const RETENTION_HOLD_SCOPE: ControlPlaneScope = "retention:hold";
+
+/**
+ * Read the legal holds: every hold, standing or released, with who placed it and why. Read-only — the one
+ * route behind it is a `GET` — and kind `reads`. The manifest's count of standing holds sits behind it too:
+ * `activeHolds`, in the health of the `controlplane` entry.
+ */
+export const RETENTION_READ_SCOPE: ControlPlaneScope = "retention:read";
+
+/**
+ * List every connection bound to this Worker's environment: who authorized it, what kind of client it is for, its purpose, its
+ * credential kinds, its grant and when it was registered or revoked. Kind `reads`. Never key material.
+ */
+export const CONNECTIONS_READ_SCOPE: ControlPlaneScope = "connections:read";
+
+/**
+ * Revoke every key and trust another connection in this Worker's environment holds, with a reason. Kind
+ * `credentials`. Refused on the caller's own connection, which ends through `disconnect`.
+ */
+export const CONNECTIONS_REVOKE_SCOPE: ControlPlaneScope = "connections:revoke";
+
 /**
  * The seam's base grant — what `pithy dashboard connect` grants whatever the Worker composes. Ping is absent
  * because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
  *
- * **{@link MIGRATIONS_READ_SCOPE} and {@link PRIVACY_READ_SCOPE} are absent on purpose.** Each is a read —
+ * **The seam's reads are absent on purpose** — {@link MIGRATIONS_READ_SCOPE}, {@link PRIVACY_READ_SCOPE},
+ * {@link EVIDENCE_READ_SCOPE}, {@link ERASURE_READ_SCOPE}, {@link PROCESSING_READ_SCOPE}. Each is a read —
  * every route requiring it is a `GET` — so `connect` derives it from the seam's `adminRoutes` the way it
  * derives every capability's reads. The base exists for `keys:rotate`, which is not a read and would
  * otherwise drop out.

package/src/controlPlane/wire.ts

@@ -33,6 +33,32 @@
  */
 export const CONTROL_PLANE_HEADER = "pithy-control-plane";
 
+/**
+ * The header a workload presents its OIDC token on, when it calls under a trust rather than a key (#722,
+ * `docs/AGENT-ACCESS.md` §6.2).
+ *
+ * Not `Authorization`, for the same reason as {@link CONTROL_PLANE_HEADER}, and not that header either: a call
+ * presents exactly one credential, and two names make "which one is this" a question the verifier never has
+ * to guess at. The token is the provider's own, verified per call; nothing is exchanged for it.
+ */
+export const CONTROL_PLANE_OIDC_HEADER = "pithy-control-plane-oidc";
+
+/**
+ * The header naming which of this environment's trusts an OIDC call claims, by its id — the way a token's
+ * `kid` names a key. Read before the token is verified, so it selects and grants nothing: the trust's issuer,
+ * audience and claims are what the token is then held to.
+ */
+export const CONTROL_PLANE_TRUST_HEADER = "pithy-control-plane-trust";
+
+/**
+ * The header naming the one scope an OIDC call exercises.
+ *
+ * A signed control-plane token names its scope inside the signature. A provider's identity token cannot — it
+ * proves **who**, never **what** — so the call names it out loud, and the seam checks it against the
+ * connection's grant exactly as it checks a token's. A call that names none is refused.
+ */
+export const CONTROL_PLANE_SCOPE_HEADER = "pithy-control-plane-scope";
+
 /**
  * The response header carrying the build that answered a control-plane call.
  *

package/src/createBackend.ts

@@ -30,9 +30,13 @@ import { buildKvRegistry, composeKv, type KvRegistry } from "./kv/namespaces";
 import { loggingErrorHandler } from "./logger/errorHandler";
 import type { Logger } from "./logger/logger";
 import { bindRequestContext, createWorkerLogger } from "./logger/worker";
+import { assertToolDeclarations } from "./mcp/tools";
 import type { RouteGroup } from "./openapi/document";
 import { recordRouteGroups } from "./openapi/routeGroups";
+import { registerPresenceRoutes } from "./presence/http/routes";
 import { refuseEncryptedKvStores } from "./privacy/encryptedColumns";
+import { effectiveProcessing, recordProcessing } from "./processing/composed";
+import { effectiveRetention, recordRetention } from "./retention/composed";
 import { HEALTH_PATH } from "./worker/health";
 import { workerVersion } from "./worker/identity";
 import { registeredWorkflowBinding } from "./workflow/bindings";
@@ -62,6 +66,19 @@ export interface CreateBackendOptions<Caps extends readonly Capability[], App ex
    * absent — e.g. a non-provisioned local run. Falls through to `unknown` when neither is present.
    */
   env?: string;
+  /**
+   * How long this Worker keeps deleted accounts, the audit trail and each class of personal data — the
+   * `retention` block of the Worker's `pithy.config.ts`, which `createEntrypoint(config)` hands through. Parsed and
+   * resolved here, at assembly, so a block that does not parse, or keeps a floored audit action under the floor,
+   * refuses to deploy. See `retention/policy.ts`.
+   */
+  retention?: unknown;
+  /**
+   * The adopter's own processing activities, and the legal bases they state for a capability's — the `processing`
+   * block of the Worker's `pithy.config.ts`. Resolved here over what this Worker composes, so a block that does not
+   * parse, or overrides an activity nothing declares, refuses to deploy. See `processing/activity.ts`.
+   */
+  processing?: unknown;
 }
 
 /** The Hono env `createBackend` returns — `db`/`kv`/`workflows` typed precisely from the merged capabilities. */
@@ -168,8 +185,12 @@ export function createBackend<
 
   // Recorded after the hooks, so a capability found later is one whose own wiring is complete. This is
   // the only way back to a composed seam from a Workflow step, which the runtime constructs with `env`
-  // and nothing else — see `capability/composition.ts` (pithy-sh/pithy#356).
+  // and nothing else — see `capability/composition.ts`.
   recordComposition(all);
+  // The retention block, resolved over what this Worker composes and recorded beside it, so a purge, a prune and
+  // the inactivity pass read the policy the routes report. A block under the audit floor throws here.
+  recordRetention(effectiveRetention(options.retention, all));
+  recordProcessing(effectiveProcessing(options.processing, all));
 
   const databases = composeDatabases(all);
   // Every composed capability's English, merged under the domain rule. Built once at assembly rather
@@ -179,7 +200,7 @@ export function createBackend<
   // `@pithy-sh/i18n`'s middleware replaces it per request; nothing else ever does.
   const defaultTranslator = bakedTranslator(catalogFor(messages, DEFAULT_LOCALE));
   const namespaces = composeKv(all);
-  // An encrypted field in a KV store is refused here, at boot (#390): a KV envelope cannot be found by key version,
+  // An encrypted field in a KV store is refused here, at boot: a KV envelope cannot be found by key version,
   // so it could never be rotated. The refusal names the store, the field and D1.
   refuseEncryptedKvStores(all);
   const workflows = composeWorkflows(all);
@@ -203,8 +224,7 @@ export function createBackend<
   // registries); the precise types ride on the return below.
   const app = new Hono<PithyHonoEnv>();
   // The logging handler, not the bare encoder: a fault's `action` names the var or command an operator
-  // must fix, `clientError` strips it on the way to the wire (correctly), and without this the remedy
-  // reached no surface at all in a deployed Worker — one access log line reading `status: 500` (#521).
+  // must fix, and `clientError` strips it on the way to the wire, so the log is the one surface it reaches.
   app.onError(loggingErrorHandler);
 
   // Set once at assembly (the per-request `env` constraint holds: correlation binds per request below,
@@ -296,7 +316,7 @@ export function createBackend<
    * The path is `worker/health.ts`'s, not a literal here. Three other sites need the same string — the
    * CLI's route allowlist, `pithy deploy`'s post-deploy probe, and the bare home screen a no-auth
    * scaffold seeds — and that last one is in somebody else's repository, rendering nothing but this
-   * request's answer (#400).
+   * request's answer.
    *
    * The version is what turns `pithy deploy`'s post-deploy check from a liveness probe into an
    * assertion. `status: "ok"` at the declared domain proves *a* Worker is there; it does not prove it is
@@ -332,7 +352,7 @@ export function createBackend<
   // Readiness guards after every capability's middleware, so the verifier, `emit` and every rate limit
   // are in place, and before any capability's routes, so a terminal handler cannot outrun them. Each is
   // skipped on the admin surface: the control plane answers whatever else is wrong with the Worker,
-  // because it is how a management client finds out what that is (#763).
+  // because it is how a management client finds out what that is.
   registerReadinessGuards(
     app,
     adminSurface,
@@ -343,9 +363,14 @@ export function createBackend<
   for (const cap of all) {
     const start = app.routes.length;
     cap.routes?.(app);
+    // A capability's presence routes are its own, tagged with it, under the base path it declared.
+    if (cap.presence && cap.presence.rooms.length > 0) registerPresenceRoutes(app, cap.presence);
     groups.push({ tag: cap.name, routes: app.routes.slice(start) });
   }
   recordRouteGroups(app, groups);
+  // A route that opts in as an MCP tool says so on `describeRoute`, which cannot see its method — so a non-GET
+  // claiming to be a read, or two routes sharing an operation, is refused here, at boot (`mcp/tools.ts`).
+  assertToolDeclarations(groups);
 
   return app as unknown as Hono<BackendEnv<readonly [...Caps, App]>>;
 }

package/src/createEntrypoint.ts

@@ -4,6 +4,8 @@
 import type { ExecutionContext, ForwardableEmailMessage } from "@cloudflare/workers-types";
 import type { Capability, CapabilityEmailHandler } from "./capability/capability";
 import { type CreateBackendOptions, createBackend } from "./createBackend";
+import { createWorkerLogger } from "./logger/worker";
+import { type CapabilityQueueHandler, dispatchQueueBatch, type QueueBatch } from "./queue/consumer";
 import { withLocalServices } from "./worker/serviceLoopback";
 import { triggerWorkflow } from "./workflow/dispatch";
 import { composeWorkflows, scheduledWorkflows } from "./workflow/register";
@@ -54,6 +56,12 @@ export interface PithyEntrypoint {
    * tested in staging.
    */
   scheduled?: (controller: unknown, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
+  /**
+   * The Worker `queue` handler — hands each composed capability the messages of a batch that name it (#824).
+   * **Present only when at least one capability consumes a queue**, for `email`'s reason: an inert handler would
+   * acknowledge every message delivered to it and drop it.
+   */
+  queue?: (batch: QueueBatch, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
 }
 
 /** The cron expression a `scheduled` event fired for, or `undefined` when the event names none. */
@@ -131,6 +139,15 @@ export function createEntrypoint<
     };
   }
 
+  // One `queue` export for every capability that consumes, routed by the capability each message body names.
+  const consumers = new Map<string, CapabilityQueueHandler>(
+    all.flatMap((cap) => (cap.queue ? [[cap.name, cap.queue] as const] : [])),
+  );
+  if (consumers.size > 0) {
+    entrypoint.queue = (batch, env, ctx) =>
+      dispatchQueueBatch(batch, consumers, withLocalServices(env), ctx, createWorkerLogger({ name: "queue" }));
+  }
+
   // Only expose an `email` handler when something actually handles inbound mail — an inert one would
   // silently drop any message Email Routing delivered to this Worker.
   if (handlers.length > 0) {