@pithy-sh/core 0.12.0 → 0.14.0

package/src/controlPlane/evidence/pack.ts

@@ -0,0 +1,190 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import { noopEmit } from "../../audit/recorder";
+import type { Capability, PithyHonoEnv } from "../../capability/capability";
+import { causeMessage } from "../../error/cause";
+import type { RouteGroup } from "../../openapi/document";
+import { describedOperations } from "../../openapi/operations";
+import { privacyAttestation } from "../../privacy/posture";
+import type { PrivacyInventory } from "../../privacy/report";
+import type { RetirementVerdict } from "../../privacy/retirement";
+import { workerVersionMetadata } from "../../worker/identity";
+import type { ControlPlaneContext } from "../context";
+import { ControlPlaneConnection } from "../data/connection";
+import { CONTROL_PLANE_CONNECTIONS_TABLE, type ControlPlaneDatabase } from "../data/tables";
+import { type CapabilityHealthSource, readCapabilityHealth } from "../discovery/health";
+import type { ControlPlaneEvidenceResponse } from "../http/responses";
+import { type ComposedMigrationDatabase, readDatabaseMigrations } from "../migrationState/migrationState";
+import { MIGRATIONS_READ_SCOPE } from "../scope/scope";
+import {
+  type ConnectionRecord,
+  type Derived,
+  deriveAuditLogging,
+  deriveChangeHistory,
+  deriveCsrf,
+  deriveDataProtection,
+  deriveKeyRotation,
+  deriveManagementAccess,
+  deriveRouteVerification,
+  evidenceEntry,
+  type SecretsRotationInput,
+} from "./derive";
+import { EVIDENCE_CONTROL_IDS, EVIDENCE_MAPPING_VERSION, type EvidenceControlId, SECRETS_CAPABILITY } from "./mapping";
+
+/**
+ * The reads behind the evidence pack (#821): what the Worker composes, records and declares, gathered once per
+ * call and handed to the pure derivations in `./derive.ts`.
+ *
+ * **Every read reports what it found or that it could not look, and never throws past here.** One unreadable
+ * table costs the controls that read it their answer — `not-derivable`, with the reason — and the pack still
+ * answers. A cause goes to the Worker's log, for the operator, and never into the pack: a D1 error can name a
+ * table or a query.
+ *
+ * **The pack never widens a scope.** Migration state is read only when the connection holds `migrations:read`,
+ * and a capability's health only for the keys this connection is granted, exactly as the manifest reads them.
+ */
+
+/** What the pack reads from the composed seam. Thunks, because the `compose` hook fills them after routes mount. */
+export interface EvidenceSources {
+  /** Every capability this Worker composed. */
+  composition: () => readonly Capability[];
+  /** Every capability's health contribution, by name. */
+  composedHealth: () => ReadonlyMap<string, CapabilityHealthSource>;
+  /** Every database this Worker binds, with what this build declares for it. */
+  composedMigrations: () => readonly ComposedMigrationDatabase[];
+  /** The privacy inventory, walked once per isolate. */
+  privacyInventory: () => PrivacyInventory;
+  /** The field key's retirement guard. Never throws. */
+  retirement: (env: Record<string, unknown>) => Promise<RetirementVerdict>;
+  /** The route table `createBackend` recorded, or `undefined` for an app it did not assemble. */
+  routeGroups: () => readonly RouteGroup[] | undefined;
+  /** The app database for this request. */
+  database: (c: Context<PithyHonoEnv>) => ControlPlaneDatabase;
+  /** The clock. */
+  now: () => Date;
+}
+
+/** Every connection registered for this environment, or null where the table could not be read. */
+async function readConnections(
+  c: Context<PithyHonoEnv>,
+  sources: EvidenceSources,
+  environment: string,
+): Promise<ConnectionRecord[] | null> {
+  try {
+    const rows = await sources
+      .database(c)
+      .selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE)
+      .selectAll()
+      .where("environment", "=", environment)
+      .orderBy("createdAt")
+      .execute();
+    return rows.map((row) => {
+      // Only the fields the pack reports and the key windows it ages. The public halves stay in the 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: readonly Capability[], env: Record<string, unknown>) {
+  const recorder = capabilities.find((capability) => capability.auditRecorder !== undefined);
+  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: Context<PithyHonoEnv>,
+  sources: EvidenceSources,
+  context: ControlPlaneContext,
+): Promise<SecretsRotationInput> {
+  if (!sources.composition().some((capability) => capability.name === SECRETS_CAPABILITY)) {
+    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: Context<PithyHonoEnv>, sources: EvidenceSources): PrivacyInventory | null {
+  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. */
+export async function readEvidencePack(
+  c: Context<PithyHonoEnv>,
+  sources: EvidenceSources,
+  context: ControlPlaneContext,
+): Promise<ControlPlaneEvidenceResponse> {
+  const env = c.env as Record<string, unknown>;
+  const now = sources.now();
+  const groups = sources.routeGroups();
+  const operations = groups === undefined ? undefined : 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: Record<EvidenceControlId, 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: EVIDENCE_MAPPING_VERSION,
+    controls: EVIDENCE_CONTROL_IDS.map((control) => evidenceEntry(control, derived[control])),
+  };
+}

package/src/controlPlane/http/connections.ts

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { personDecision } from "../../cli/command";
+import { ConflictError, NotFoundError } from "../../error/pithyError";
+import { ControlPlaneAuditActions, safeEmit } from "../audit/actions";
+import type { ControlPlaneConnection } from "../data/connection";
+import {
+  connectionCredentialKind,
+  connectionLive,
+  connectionRevokedAt,
+  listConnections,
+  revokeConnection,
+} from "../data/connections";
+import { type ControlPlaneHandlerDeps, caller } from "./handlers";
+import type { ConnectionView, ControlPlaneConnectionsResponse, RevokeConnectionResponse } 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 function connectionView(connection: ControlPlaneConnection, now: Date): ConnectionView {
+  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.
+ */
+export function listConnectionsHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>, query: ConnectionListQuery) => {
+    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)),
+    } satisfies ControlPlaneConnectionsResponse);
+  };
+}
+
+/**
+ * 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 function selfRevokeRefusal(connectionId: string, environment: string): ConflictError {
+  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.
+ */
+export function revokeConnectionHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>, params: ConnectionParams, body: RevokeConnectionRequest) => {
+    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],
+    } satisfies RevokeConnectionResponse);
+  };
+}

package/src/controlPlane/http/guard.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import type { MiddlewareHandler } from "hono";
-import type { AuditEmit } from "../../audit/recorder";
+import { type AuditEmit, noopEmit } from "../../audit/recorder";
 import type { PithyHonoEnv } from "../../capability/capability";
 import { commandName, remedy } from "../../cli/command";
 import { type AmbientEnv, compositionEnvironment } from "../../env/ambient";
@@ -11,10 +11,22 @@ import { workerVersionMetadata } from "../../worker/identity";
 import { ControlPlaneAuditActions, safeEmit } from "../audit/actions";
 import type { ControlPlaneContext } from "../context";
 import type { ControlPlaneActorKind } from "../data/connection";
-import { ControlPlaneNotConnectedError } from "../error/errors";
+import {
+  ControlPlaneInsufficientScopeError,
+  ControlPlaneInvalidCredentialError,
+  ControlPlaneNotConnectedError,
+} from "../error/errors";
 import type { ControlPlaneRequirement } from "../scope/scope";
-import { CONTROL_PLANE_HEADER, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER } from "../wire";
+import {
+  CONTROL_PLANE_HEADER,
+  CONTROL_PLANE_OIDC_HEADER,
+  CONTROL_PLANE_SCOPE_HEADER,
+  CONTROL_PLANE_TRUST_HEADER,
+  CONTROL_PLANE_VERSION_CREATED_HEADER,
+  CONTROL_PLANE_VERSION_HEADER,
+} from "../wire";
 import { type ControlPlaneVerifyDeps, verifyControlPlaneCall } from "./verify";
+import { type ControlPlaneTrustVerifyDeps, verifyControlPlaneTrustCall } from "./verifyTrust";
 
 /**
  * `requireControlPlane(scope)` — the gate every control-plane route wears, including the ones
@@ -57,8 +69,39 @@ export type ControlPlaneVerifier = (
  * 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 function createControlPlaneVerifier(deps: ControlPlaneVerifyDeps): ControlPlaneVerifier {
+export 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 {
   return async (request, requirement) => {
+    // A call presents one credential. The OIDC header selects the trust path; both at once is refused rather
+    // than resolved, because "which of these did the caller mean" is not a question a verifier should answer.
+    const oidc = request.headers.get(CONTROL_PLANE_OIDC_HEADER);
+    if (oidc !== null) {
+      if (request.headers.get(CONTROL_PLANE_HEADER) !== 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(CONTROL_PLANE_TRUST_HEADER) ?? undefined,
+          scope: request.headers.get(CONTROL_PLANE_SCOPE_HEADER) ?? undefined,
+          requirement,
+        },
+        trusts,
+      );
+    }
     // Clone before reading. The handler still has to parse this body through `validate`, and a stream
     // consumed here would reach it empty — the digest check would pass and the request would then fail
     // validation for no visible reason.
@@ -120,7 +163,26 @@ export function isControlPlaneGuard(handler: unknown): boolean {
 }
 
 export function requireControlPlane(requirement: ControlPlaneRequirement): MiddlewareHandler<PithyHonoEnv> {
+  return requireControlPlaneFor(async () => requirement);
+}
+
+/**
+ * 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 function requireControlPlaneFor(resolve: ControlPlaneRequirementResolver): MiddlewareHandler<PithyHonoEnv> {
   const guard: MiddlewareHandler<PithyHonoEnv> = async (c, next) => {
+    const requirement = await resolve(c);
     // Every control-plane response carries the build that produced it, allowed or denied.
     //
     // **On the guard, not on the seam's own routes**, because the guard is the one thing every
@@ -180,13 +242,29 @@ export function requireControlPlane(requirement: ControlPlaneRequirement): Middl
           connectionEnvironment: context.environment,
           scope: context.scope,
           keyId: context.keyId,
+          // Said only for a trust, so a row written by a key reads exactly as it did before trusts existed.
+          ...(context.credentialKind === "trust" ? { credentialKind: "trust" } : {}),
           method: c.req.method,
           path: c.req.path,
         },
       },
       c.var.log,
     );
-    await next();
+    // A handler can refuse a call the gate's requirement let through — an operator roster write that
+    // would move the owning role is refused `controlplane/insufficient_scope`, naming the ownership route,
+    // even on a connection granted `organization:ownership:transfer`, because a token exercises the one
+    // scope it was minted for — and it refuses it itself, past this gate. That refusal is still a blocked attempt, and the trail must
+    // say so: `call_allowed` alone would hide a credential probing for the grant it lacks.
+    //
+    // Both paths, as the organization routes' refusal recorder reads them: a throw that reaches here, and
+    // `c.error`, which is where Hono's `compose` leaves a downstream throw it rendered through `onError`.
+    try {
+      await next();
+    } catch (error) {
+      await auditHandlerDenial(c, requirement, context, error);
+      throw error;
+    }
+    await auditHandlerDenial(c, requirement, context, c.error);
   };
   (guard as unknown as Record<symbol, unknown>)[CONTROL_PLANE_GUARD] = true;
   return guard;
@@ -199,9 +277,12 @@ export function requireControlPlane(requirement: ControlPlaneRequirement): Middl
  * 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 function stampActorKind(emit: AuditEmit, actorKind: ControlPlaneActorKind | null): AuditEmit {
-  if (actorKind === null) return emit;
+  if (actorKind === null || emit === noopEmit) return emit;
   return (event) =>
     emit(event.actorType === "control-plane" && event.actorKind == null ? { ...event, actorKind } : event);
 }
@@ -217,6 +298,14 @@ export function stampActorKind(emit: AuditEmit, actorKind: ControlPlaneActorKind
  * 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.
  */
@@ -226,6 +315,24 @@ async function auditDenial(
   cause: unknown,
 ): Promise<void> {
   const code = cause instanceof PithyError ? cause.payload.code : "core/internal";
+  const proven = cause instanceof ControlPlaneInsufficientScopeError ? cause.caller : null;
+  // A claim mismatch on an OIDC token whose signature, issuer and audience verified (#722): the claims it carried
+  // are recorded, which is how an operator picks a matcher for a custom issuer. Nobody is named as the actor — the
+  // token is genuine, but not for any workload this Worker trusts.
+  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,
     {
@@ -233,13 +340,74 @@ async function auditDenial(
       outcome: "denied",
       severity: "warning",
       actorType: "control-plane",
-      // Null, deliberately. The `sub` claim of a call that failed verification is unproven, and writing
-      // an unverified identity into the trail as the actor is how a forged token gets to name someone.
-      actorId: null,
+      // The connection's own kind, as `stampActorKind` adds it to the allowed row, so a trail filtered on kind holds a
+      // client's refusals beside its calls. Absent when unproven, and absent for a connection with no recorded kind.
+      ...(proven?.actorKind ? { actorKind: proven.actorKind } : {}),
+      // Null unless proven. The `sub` claim of a call that failed verification is unproven, and writing an
+      // unverified identity into the trail as the actor is how a forged token gets to name someone. A scope refusal
+      // came after the signature verified, so its subject is the token's real one.
+      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: { reason: code, required: String(requirement), method: c.req.method, path: c.req.path },
+      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: Parameters<MiddlewareHandler<PithyHonoEnv>>[0],
+  requirement: ControlPlaneRequirement,
+  context: ControlPlaneContext,
+  cause: unknown,
+): Promise<void> {
+  // Read by its code, not `instanceof`: a capability that throws it may hold its own copy of this module,
+  // and a refusal that slipped past a class check would be exactly the unaudited attempt this exists for.
+  const code = (cause as { payload?: { code?: unknown } } | null)?.payload?.code;
+  if (code !== "controlplane/insufficient_scope") return;
+  await safeEmit(
+    c.var.emit,
+    {
+      action: ControlPlaneAuditActions.callDenied,
+      outcome: "denied",
+      severity: "warning",
+      actorType: "control-plane",
+      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,
+      },
     },
     c.var.log,
   );