@pithy-sh/core 0.12.0 → 0.14.0

package/dist/controlPlane/evidence/pack.js

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { noopEmit } from "../../audit/recorder.js";
+import { MIGRATIONS_READ_SCOPE } from "../scope/scope.js";
+import { ControlPlaneConnection } from "../data/connection.js";
+import { CONTROL_PLANE_CONNECTIONS_TABLE } from "../data/tables.js";
+import { workerVersionMetadata } from "../../worker/identity.js";
+import { readCapabilityHealth } from "../discovery/health.js";
+import { privacyAttestation } from "../../privacy/posture.js";
+import { causeMessage } from "../../error/cause.js";
+import { describedOperations } from "../../openapi/operations.js";
+import { readDatabaseMigrations } from "../migrationState/migrationState.js";
+import { EVIDENCE_CONTROL_IDS, SECRETS_CAPABILITY } from "./mapping.js";
+import { deriveAuditLogging, deriveChangeHistory, deriveCsrf, deriveDataProtection, deriveKeyRotation, deriveManagementAccess, deriveRouteVerification, evidenceEntry } from "./derive.js";
+//#region src/controlPlane/evidence/pack.ts
+/** Every connection registered for this environment, or null where the table could not be read. */
+async function readConnections(c, sources, environment) {
+	try {
+		return (await sources.database(c).selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().where("environment", "=", environment).orderBy("createdAt").execute()).map((row) => {
+			const connection = ControlPlaneConnection.parse(row);
+			return {
+				id: connection.id,
+				authorizedBy: connection.authorizedBy,
+				actorKind: connection.actorKind,
+				purpose: connection.purpose,
+				scopes: connection.scopes,
+				keys: connection.keys.map(({ validFrom, validUntil, revokedAt }) => ({
+					validFrom,
+					validUntil,
+					revokedAt
+				}))
+			};
+		});
+	} catch (cause) {
+		c.var.log.warn("evidence: connections unreadable", { reason: causeMessage(cause) ?? String(cause) });
+		return null;
+	}
+}
+/** The composed audit recorder and whether each binding it writes through is present, or null for none. */
+function auditRecorder(capabilities, env) {
+	const recorder = capabilities.find((capability) => capability.auditRecorder !== void 0);
+	if (!recorder) return null;
+	const bindings = [...new Set(Object.values(recorder.databases ?? {}).map((database) => database.binding))];
+	return {
+		capability: recorder.name,
+		bindings: bindings.map((binding) => ({
+			binding,
+			present: env[binding] != null
+		}))
+	};
+}
+/** Secrets' rotation status for this caller, read exactly as the manifest reads it. */
+async function secretsRotation(c, sources, context) {
+	if (!sources.composition().some((capability) => capability.name === "secrets")) return { state: "not-composed" };
+	const source = sources.composedHealth().get(SECRETS_CAPABILITY);
+	const report = await readCapabilityHealth(source, context.grantedScopes, (found) => found.read(c));
+	return {
+		state: "composed",
+		keys: source?.keys ?? [],
+		report
+	};
+}
+/** The privacy inventory, or null where the walk threw. */
+function inventoryOf(c, sources) {
+	try {
+		return sources.privacyInventory();
+	} catch (cause) {
+		c.var.log.warn("evidence: privacy inventory unreadable", { reason: causeMessage(cause) ?? String(cause) });
+		return null;
+	}
+}
+/** Read everything the pack derives from, and derive it. */
+async function readEvidencePack(c, sources, context) {
+	const env = c.env;
+	const now = sources.now();
+	const groups = sources.routeGroups();
+	const operations = groups === void 0 ? void 0 : describedOperations(groups);
+	const migrationsGranted = context.grantedScopes.includes(MIGRATIONS_READ_SCOPE);
+	const [connections, secrets, retirement, databases] = await Promise.all([
+		readConnections(c, sources, context.environment),
+		secretsRotation(c, sources, context),
+		sources.retirement(env),
+		migrationsGranted ? Promise.all(sources.composedMigrations().map((entry) => readDatabaseMigrations(env, entry, (failed, cause) => c.var.log.warn("evidence: migration ledger unreadable", {
+			database: failed.database,
+			binding: failed.binding,
+			reason: causeMessage(cause) ?? String(cause)
+		})))) : Promise.resolve([])
+	]);
+	const derived = {
+		"audit-logging": deriveAuditLogging({
+			recorder: auditRecorder(sources.composition(), env),
+			emitting: c.var.emit !== noopEmit
+		}),
+		"route-verification": deriveRouteVerification(operations),
+		"management-access": deriveManagementAccess(connections),
+		"key-rotation": deriveKeyRotation({
+			connections,
+			now,
+			secrets,
+			retirement
+		}),
+		"change-history": deriveChangeHistory({
+			granted: migrationsGranted,
+			databases
+		}),
+		"data-protection": deriveDataProtection({
+			inventory: inventoryOf(c, sources),
+			attestation: privacyAttestation(env)
+		}),
+		csrf: deriveCsrf({
+			operations,
+			sameOriginPublished: c.var.sameOrigin !== null
+		})
+	};
+	return {
+		environment: context.environment,
+		generatedAt: now.toISOString(),
+		version: workerVersionMetadata(c.env).id,
+		mappingVersion: 1,
+		controls: EVIDENCE_CONTROL_IDS.map((control) => evidenceEntry(control, derived[control]))
+	};
+}
+//#endregion
+export { readEvidencePack };

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

@@ -0,0 +1,96 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { ConflictError } from "../../error/pithyError";
+import type { ControlPlaneConnection } from "../data/connection";
+import { type ControlPlaneHandlerDeps } from "./handlers";
+import type { ConnectionView } from "./responses";
+import type { ConnectionListQuery, ConnectionParams, RevokeConnectionRequest } from "./schemas";
+/** A connection as the listing shows it at `now`: who, what for, which credentials, never key material. */
+export declare function connectionView(connection: ControlPlaneConnection, now: Date): ConnectionView;
+/**
+ * `GET /control-plane/connections` — every connection bound to this Worker's environment, the caller's own among
+ * them. A database shared with another environment holds that environment's rows too, and they are never listed.
+ * Read-only.
+ */
+export declare function listConnectionsHandler(deps: ControlPlaneHandlerDeps): (c: Context<PithyHonoEnv>, query: ConnectionListQuery) => Promise<Response & import("hono").TypedResponse<{
+    connections: {
+        id: string;
+        environment: string;
+        actorKind: "agent" | "dashboard" | "script" | null;
+        purpose: string | null;
+        authorizedBy: string | null;
+        credentialKind: "both" | "key" | "none" | "trust";
+        scopes: string[];
+        trusts: {
+            trustId: string;
+            issuer: string;
+            claims: {
+                [x: string]: string;
+            };
+            revokedAt: string | null;
+        }[];
+        live: boolean;
+        registeredAt: string;
+        revokedAt: string | null;
+    }[];
+    unattributed: {
+        id: string;
+        environment: string;
+        actorKind: "agent" | "dashboard" | "script" | null;
+        purpose: string | null;
+        authorizedBy: string | null;
+        credentialKind: "both" | "key" | "none" | "trust";
+        scopes: string[];
+        trusts: {
+            trustId: string;
+            issuer: string;
+            claims: {
+                [x: string]: string;
+            };
+            revokedAt: string | null;
+        }[];
+        live: boolean;
+        registeredAt: string;
+        revokedAt: string | null;
+    }[];
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
+/**
+ * The refusal of a connection asking to revoke itself. The action names the environment it is bound to, since
+ * `dashboard disconnect` would otherwise end the connection of the environment its `--env` defaults to.
+ */
+export declare function selfRevokeRefusal(connectionId: string, environment: string): ConflictError;
+/**
+ * `POST /control-plane/connections/:connectionId/revoke` — revoke every key and trust another connection in this
+ * Worker's environment holds that is not yet revoked. A connection bound to another environment is answered as
+ * though it did not exist.
+ *
+ * Refused on the caller's own connection: a client ending its own access does it through `disconnect`, which also
+ * removes what it holds locally.
+ */
+export declare function revokeConnectionHandler(deps: ControlPlaneHandlerDeps): (c: Context<PithyHonoEnv>, params: ConnectionParams, body: RevokeConnectionRequest) => Promise<Response & import("hono").TypedResponse<{
+    connection: {
+        id: string;
+        environment: string;
+        actorKind: "agent" | "dashboard" | "script" | null;
+        purpose: string | null;
+        authorizedBy: string | null;
+        credentialKind: "both" | "key" | "none" | "trust";
+        scopes: string[];
+        trusts: {
+            trustId: string;
+            issuer: string;
+            claims: {
+                [x: string]: string;
+            };
+            revokedAt: string | null;
+        }[];
+        live: boolean;
+        registeredAt: string;
+        revokedAt: string | null;
+    };
+    revokedKeyIds: string[];
+    revokedTrustIds: string[];
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
+//# sourceMappingURL=connections.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/connections.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,EAAE,aAAa,EAAiB,MAAM,wBAAwB,CAAC;AAEtE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAQjE,OAAO,EAAE,KAAK,uBAAuB,EAAU,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAA6D,MAAM,aAAa,CAAC;AAC7G,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEhG,2GAA2G;AAC3G,wBAAgB,cAAc,CAAC,UAAU,EAAE,sBAAsB,EAAE,GAAG,EAAE,IAAI,GAAG,cAAc,CAmB5F;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,uBAAuB,OACjD,OAAO,CAAC,YAAY,CAAC,SAAS,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAYnE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,CAM1F;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,uBAAuB,OAClD,OAAO,CAAC,YAAY,CAAC,UAAU,gBAAgB,QAAQ,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;mEA6ChG"}

package/dist/controlPlane/http/connections.js

@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ConflictError, NotFoundError } from "../../error/pithyError.js";
+import { personDecision } from "../../cli/command.js";
+import { ControlPlaneAuditActions, safeEmit } from "../audit/actions.js";
+import { connectionCredentialKind, connectionLive, connectionRevokedAt, listConnections, revokeConnection } from "../data/connections.js";
+import { caller } from "./handlers.js";
+//#region src/controlPlane/http/connections.ts
+/** A connection as the listing shows it at `now`: who, what for, which credentials, never key material. */
+function connectionView(connection, now) {
+	return {
+		id: connection.id,
+		environment: connection.environment,
+		actorKind: connection.actorKind,
+		purpose: connection.purpose,
+		authorizedBy: connection.authorizedBy,
+		credentialKind: connectionCredentialKind(connection),
+		scopes: [...connection.scopes],
+		trusts: (connection.trusts ?? []).map((trust) => ({
+			trustId: trust.trustId,
+			issuer: trust.issuer,
+			claims: { ...trust.claims },
+			revokedAt: trust.revokedAt?.toISOString() ?? null
+		})),
+		live: connectionLive(connection, now),
+		registeredAt: connection.createdAt.toISOString(),
+		revokedAt: connectionRevokedAt(connection, now)?.toISOString() ?? null
+	};
+}
+/**
+* `GET /control-plane/connections` — every connection bound to this Worker's environment, the caller's own among
+* them. A database shared with another environment holds that environment's rows too, and they are never listed.
+* Read-only.
+*/
+function listConnectionsHandler(deps) {
+	return async (c, query) => {
+		const context = caller(c);
+		const now = deps.now();
+		const listing = await listConnections(deps.database(c), {
+			principal: query.principal,
+			environment: context.environment
+		});
+		return c.json({
+			connections: listing.connections.map((connection) => connectionView(connection, now)),
+			unattributed: listing.unattributed.map((connection) => connectionView(connection, now))
+		});
+	};
+}
+/**
+* The refusal of a connection asking to revoke itself. The action names the environment it is bound to, since
+* `dashboard disconnect` would otherwise end the connection of the environment its `--env` defaults to.
+*/
+function selfRevokeRefusal(connectionId, environment) {
+	return new ConflictError({
+		message: "A connection cannot revoke itself here.",
+		action: `End this connection from the CLI instead. ${personDecision("dashboard disconnect", { flags: { "--env": environment } }, { runtime: true })}`,
+		detail: `connection ${connectionId} asked to revoke itself`
+	});
+}
+/**
+* `POST /control-plane/connections/:connectionId/revoke` — revoke every key and trust another connection in this
+* Worker's environment holds that is not yet revoked. A connection bound to another environment is answered as
+* though it did not exist.
+*
+* Refused on the caller's own connection: a client ending its own access does it through `disconnect`, which also
+* removes what it holds locally.
+*/
+function revokeConnectionHandler(deps) {
+	return async (c, params, body) => {
+		const context = caller(c);
+		if (params.connectionId === context.connectionId) throw selfRevokeRefusal(context.connectionId, context.environment);
+		const db = deps.database(c);
+		const now = deps.now();
+		const revoked = await revokeConnection(db, params.connectionId, now, { environment: context.environment });
+		if (revoked === null) throw new NotFoundError({
+			message: "No connection in this environment has that id.",
+			detail: `connection ${params.connectionId} not found in ${context.environment}`
+		});
+		const target = revoked.connection;
+		await safeEmit(c.var.emit, {
+			action: ControlPlaneAuditActions.connectionRevoked,
+			outcome: "success",
+			severity: "warning",
+			actorType: "control-plane",
+			actorId: context.subject,
+			resourceType: "controlplane_connection",
+			resourceId: target.id,
+			requestId: c.req.header("cf-ray"),
+			ip: c.req.header("cf-connecting-ip"),
+			userAgent: c.req.header("user-agent"),
+			metadata: {
+				callerConnectionId: context.connectionId,
+				connectionId: target.id,
+				connectionEnvironment: target.environment,
+				authorizedBy: target.authorizedBy,
+				reason: body.reason,
+				revokedKeyIds: [...revoked.revokedKeyIds],
+				revokedTrustIds: [...revoked.revokedTrustIds]
+			}
+		}, c.var.log);
+		return c.json({
+			connection: connectionView(target, now),
+			revokedKeyIds: [...revoked.revokedKeyIds],
+			revokedTrustIds: [...revoked.revokedTrustIds]
+		});
+	};
+}
+//#endregion
+export { connectionView, listConnectionsHandler, revokeConnectionHandler, selfRevokeRefusal };

package/dist/controlPlane/http/guard.d.ts

@@ -1,12 +1,13 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import type { MiddlewareHandler } from "hono";
-import type { AuditEmit } from "../../audit/recorder";
+import { type AuditEmit } from "../../audit/recorder";
 import type { PithyHonoEnv } from "../../capability/capability";
 import type { ControlPlaneContext } from "../context";
 import type { ControlPlaneActorKind } from "../data/connection";
 import type { ControlPlaneRequirement } from "../scope/scope";
 import { type ControlPlaneVerifyDeps } from "./verify";
+import { type ControlPlaneTrustVerifyDeps } from "./verifyTrust";
 /**
  * `requireControlPlane(scope)` — the gate every control-plane route wears, including the ones
  * capabilities contribute.
@@ -43,7 +44,12 @@ export type ControlPlaneVerifier = (request: Request, requirement: ControlPlaneR
  * Build the verifier the seam's middleware publishes. Split out from the middleware so the wiring is
  * testable without a Worker, and so `verify.ts` stays free of Hono.
  */
-export declare function createControlPlaneVerifier(deps: ControlPlaneVerifyDeps): ControlPlaneVerifier;
+export declare function createControlPlaneVerifier(deps: ControlPlaneVerifyDeps, 
+/**
+ * The trust path's own dependencies (#722). Absent, a call presenting an OIDC token is refused like any other
+ * credential this Worker cannot verify — the seam fails closed rather than waving an unverifiable token through.
+ */
+trusts?: ControlPlaneTrustVerifyDeps): ControlPlaneVerifier;
 /**
  * What this Worker may say about its own build, as headers — everything the binding handed it, and
  * nothing else.
@@ -78,6 +84,18 @@ export declare const CONTROL_PLANE_GUARD: unique symbol;
 /** Whether a mounted handler is a control-plane gate. */
 export declare function isControlPlaneGuard(handler: unknown): boolean;
 export declare function requireControlPlane(requirement: ControlPlaneRequirement): MiddlewareHandler<PithyHonoEnv>;
+/**
+ * The scope a call needs, resolved from the call itself. Never throws: whatever it cannot read resolves to
+ * a requirement, and `ANY_VERIFIED_CALLER` is the least it may resolve to — never no gate at all.
+ */
+export type ControlPlaneRequirementResolver = (c: Parameters<MiddlewareHandler<PithyHonoEnv>>[0]) => Promise<ControlPlaneRequirement>;
+/**
+ * {@link requireControlPlane} for a route whose scope is named by the request, which is the presence ticket
+ * route's case (#815): the room kind in its body decides the scope. Resolving it **inside the gate, before
+ * verifying**, is what keeps a refused call to the one denial row every other route writes — a handler that
+ * checked the scope after the gate let the call through would leave an allowed row ahead of its denial.
+ */
+export declare function requireControlPlaneFor(resolve: ControlPlaneRequirementResolver): MiddlewareHandler<PithyHonoEnv>;
 /**
  * The recorder a verified call's handlers write through: the request's own, with the connection's actor
  * kind added to every `control-plane` event that does not already carry one.
@@ -85,6 +103,9 @@ export declare function requireControlPlane(requirement: ControlPlaneRequirement
  * Only `control-plane` events, because the kind describes a management client and nothing else — a
  * handler recording what happened to a user is recording a user. An event that states a kind keeps it.
  * A connection with no recorded kind adds nothing, so its rows read exactly as they did before.
+ *
+ * The no-op comes back as itself: there is nothing to stamp, and a wrapper around it would hide that nothing is
+ * recorded from every reader past this gate — the evidence pack's `controlPlaneCallsRecorded` among them (#821).
  */
 export declare function stampActorKind(emit: AuditEmit, actorKind: ControlPlaneActorKind | null): AuditEmit;
 //# sourceMappingURL=guard.d.ts.map

package/dist/controlPlane/http/guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAMhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,EAAE,KAAK,sBAAsB,EAA0B,MAAM,UAAU,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,uBAAuB,KACjC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,sBAAsB,GAAG,oBAAoB,CAgB7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMzE;AAED;;;;;;GAMG;AACH;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,eAAwC,CAAC;AAEzE,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE7D;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,uBAAuB,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAuEzG;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,CAIlG"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,EAAE,KAAK,SAAS,EAAY,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAMhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAMhE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAS9D,OAAO,EAAE,KAAK,sBAAsB,EAA0B,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,KAAK,2BAA2B,EAA+B,MAAM,eAAe,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,uBAAuB,KACjC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,sBAAsB;AAC5B;;;GAGG;AACH,MAAM,CAAC,EAAE,2BAA2B,GACnC,oBAAoB,CAwCtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMzE;AAED;;;;;;GAMG;AACH;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,eAAwC,CAAC;AAEzE,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE7D;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,uBAAuB,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAEzG;AAED;;;GAGG;AACH,MAAM,MAAM,+BAA+B,GAAG,CAC5C,CAAC,EAAE,UAAU,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,KAC9C,OAAO,CAAC,uBAAuB,CAAC,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,+BAA+B,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAwFhH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,CAIlG"}

package/dist/controlPlane/http/guard.js

@@ -1,20 +1,33 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
+import { noopEmit } from "../../audit/recorder.js";
 import { PithyError } from "../../error/pithyError.js";
 import { commandName, remedy } from "../../cli/command.js";
+import { ControlPlaneInsufficientScopeError, ControlPlaneInvalidCredentialError, ControlPlaneNotConnectedError } from "../error/errors.js";
 import { workerVersionMetadata } from "../../worker/identity.js";
 import { compositionEnvironment } from "../../env/ambient.js";
 import { ControlPlaneAuditActions, safeEmit } from "../audit/actions.js";
-import { ControlPlaneNotConnectedError } from "../error/errors.js";
-import { CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER } from "../wire.js";
+import { CONTROL_PLANE_OIDC_HEADER, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER } from "../wire.js";
 import { verifyControlPlaneCall } from "./verify.js";
+import { verifyControlPlaneTrustCall } from "./verifyTrust.js";
 //#region src/controlPlane/http/guard.ts
 /**
 * Build the verifier the seam's middleware publishes. Split out from the middleware so the wiring is
 * testable without a Worker, and so `verify.ts` stays free of Hono.
 */
-function createControlPlaneVerifier(deps) {
+function createControlPlaneVerifier(deps, trusts) {
 	return async (request, requirement) => {
+		const oidc = request.headers.get(CONTROL_PLANE_OIDC_HEADER);
+		if (oidc !== null) {
+			if (request.headers.get("pithy-control-plane") !== null) throw new ControlPlaneInvalidCredentialError({ detail: "a call presented both a signed token and an OIDC token" });
+			if (!trusts) throw new ControlPlaneInvalidCredentialError({ detail: "an OIDC token was presented and this Worker verifies none" });
+			return await verifyControlPlaneTrustCall({
+				token: oidc,
+				trustId: request.headers.get("pithy-control-plane-trust") ?? void 0,
+				scope: request.headers.get("pithy-control-plane-scope") ?? void 0,
+				requirement
+			}, trusts);
+		}
 		const body = new Uint8Array(await request.clone().arrayBuffer());
 		return await verifyControlPlaneCall({
 			token: request.headers.get("pithy-control-plane") ?? void 0,
@@ -65,7 +78,17 @@ function isControlPlaneGuard(handler) {
 	return typeof handler === "function" && handler[CONTROL_PLANE_GUARD] === true;
 }
 function requireControlPlane(requirement) {
+	return requireControlPlaneFor(async () => requirement);
+}
+/**
+* {@link requireControlPlane} for a route whose scope is named by the request, which is the presence ticket
+* route's case (#815): the room kind in its body decides the scope. Resolving it **inside the gate, before
+* verifying**, is what keeps a refused call to the one denial row every other route writes — a handler that
+* checked the scope after the gate let the call through would leave an allowed row ahead of its denial.
+*/
+function requireControlPlaneFor(resolve) {
 	const guard = async (c, next) => {
+		const requirement = await resolve(c);
 		for (const [name, value] of Object.entries(workerVersionHeaders(c.env))) c.header(name, value);
 		const verify = c.var.controlPlaneVerifier;
 		if (!verify) {
@@ -101,11 +124,18 @@ function requireControlPlane(requirement) {
 				connectionEnvironment: context.environment,
 				scope: context.scope,
 				keyId: context.keyId,
+				...context.credentialKind === "trust" ? { credentialKind: "trust" } : {},
 				method: c.req.method,
 				path: c.req.path
 			}
 		}, c.var.log);
-		await next();
+		try {
+			await next();
+		} catch (error) {
+			await auditHandlerDenial(c, requirement, context, error);
+			throw error;
+		}
+		await auditHandlerDenial(c, requirement, context, c.error);
 	};
 	guard[CONTROL_PLANE_GUARD] = true;
 	return guard;
@@ -117,9 +147,12 @@ function requireControlPlane(requirement) {
 * Only `control-plane` events, because the kind describes a management client and nothing else — a
 * handler recording what happened to a user is recording a user. An event that states a kind keeps it.
 * A connection with no recorded kind adds nothing, so its rows read exactly as they did before.
+*
+* The no-op comes back as itself: there is nothing to stamp, and a wrapper around it would hide that nothing is
+* recorded from every reader past this gate — the evidence pack's `controlPlaneCallsRecorded` among them (#821).
 */
 function stampActorKind(emit, actorKind) {
-	if (actorKind === null) return emit;
+	if (actorKind === null || emit === noopEmit) return emit;
 	return (event) => emit(event.actorType === "control-plane" && event.actorKind == null ? {
 		...event,
 		actorKind
@@ -136,23 +169,86 @@ function stampActorKind(emit, actorKind) {
 * the exact verification step, and the audit trail is queryable and long-lived. The step belongs in the
 * log, which is bounded and already carries the whole payload.
 *
+* **Attributed exactly as far as it is proven (#812).** A call that failed verification — no connection, a bad
+* signature, an unknown or expired key — names nobody, because nothing about it is proven. A call whose credential
+* verified and whose scope was not granted is a known connection asking for an operation it lacks, which is what
+* scope probing looks like, so its row carries the subject as `actorId`, the connection as its resource, the key
+* in `metadata.keyId` (and `credentialKind: "trust"` when that key is a trust), and the connection's `actorKind` — the same four the allowed row carries. Only the first presentation of a token is: the verifier
+* spends the jti of a scope refusal and names no caller on a token already spent, because a signature proves who minted
+* a token, not who presented it. Only the row changes; the error thrown is the same.
+*
 * Nothing here can turn a correct denial into a 500 — `safeEmit` swallows, and the caller rethrows the
 * original error regardless.
 */
 async function auditDenial(c, requirement, cause) {
 	const code = cause instanceof PithyError ? cause.payload.code : "core/internal";
+	const proven = cause instanceof ControlPlaneInsufficientScopeError ? cause.caller : null;
+	const refusedTrust = cause instanceof ControlPlaneInvalidCredentialError ? cause.refusedTrust : null;
+	const metadata = {
+		reason: code,
+		required: String(requirement),
+		method: c.req.method,
+		path: c.req.path,
+		...refusedTrust ? {
+			connectionId: refusedTrust.connectionId,
+			trustId: refusedTrust.trustId,
+			observedClaims: { ...refusedTrust.observedClaims }
+		} : {}
+	};
+	await safeEmit(c.var.emit, {
+		action: ControlPlaneAuditActions.callDenied,
+		outcome: "denied",
+		severity: "warning",
+		actorType: "control-plane",
+		...proven?.actorKind ? { actorKind: proven.actorKind } : {},
+		actorId: proven?.subject ?? null,
+		...proven ? {
+			resourceType: "controlplane_connection",
+			resourceId: proven.connectionId
+		} : {},
+		requestId: c.req.header("cf-ray"),
+		ip: c.req.header("cf-connecting-ip"),
+		userAgent: c.req.header("user-agent"),
+		metadata: proven ? {
+			...metadata,
+			keyId: proven.keyId,
+			...proven.credentialKind === "trust" ? { credentialKind: "trust" } : {}
+		} : metadata
+	}, c.var.log);
+}
+/**
+* Record a scope refusal a handler raised after the gate let the call in.
+*
+* Only `controlplane/insufficient_scope`: every other refusal past the gate is the handler's own to
+* record, and a 404 or a validation error is not a credential reaching beyond its grant. The same row as
+* {@link auditDenial}, with two differences that follow from the call having been verified: the actor is
+* the proven subject and its connection, and `refusedBy` says the gate passed it — `required` is the
+* gate's requirement, which this call met; what it lacked is in the log, with the rest of `detail`.
+* `scope`, `keyId` and `credentialKind` name the refused credential exactly as the gate's `call_allowed` row does, so a
+* read of one key's reach (#828) finds its refusals too, even on a request with no `cf-ray` to join by.
+*/
+async function auditHandlerDenial(c, requirement, context, cause) {
+	const code = cause?.payload?.code;
+	if (code !== "controlplane/insufficient_scope") return;
 	await safeEmit(c.var.emit, {
 		action: ControlPlaneAuditActions.callDenied,
 		outcome: "denied",
 		severity: "warning",
 		actorType: "control-plane",
-		actorId: null,
+		actorId: context.subject,
+		resourceType: "controlplane_connection",
+		resourceId: context.connectionId,
 		requestId: c.req.header("cf-ray"),
 		ip: c.req.header("cf-connecting-ip"),
 		userAgent: c.req.header("user-agent"),
 		metadata: {
 			reason: code,
 			required: String(requirement),
+			refusedBy: "handler",
+			connectionId: context.connectionId,
+			scope: context.scope,
+			keyId: context.keyId,
+			...context.credentialKind === "trust" ? { credentialKind: "trust" } : {},
 			method: c.req.method,
 			path: c.req.path
 		}
@@ -167,4 +263,4 @@ function connectStep(env) {
 	return remedy("dashboard connect", { flags: { "--env": env } }, { runtime: true }).say((command) => `run ${command}`);
 }
 //#endregion
-export { CONTROL_PLANE_GUARD, createControlPlaneVerifier, isControlPlaneGuard, requireControlPlane, stampActorKind, workerVersionHeaders };
+export { CONTROL_PLANE_GUARD, createControlPlaneVerifier, isControlPlaneGuard, requireControlPlane, requireControlPlaneFor, stampActorKind, workerVersionHeaders };