@pithy-sh/core 0.13.0 → 0.15.0

package/src/controlPlane/http/routes.ts

@@ -5,17 +5,30 @@ import type { Hono } from "hono";
 import type { PithyHonoEnv } from "../../capability/capability";
 import { describeRoute } from "../../http/routeSpec";
 import { validate } from "../../http/validation";
-import { type AdminRoute, ControlPlaneManifest } from "../discovery/adminRoute";
+import { PresenceTicket } from "../../presence/http/responses";
+import { ControlPlanePresenceTicketRequest } from "../../presence/http/schemas";
+import { type AdminRouteDeclaration, ControlPlaneManifest } from "../discovery/adminRoute";
 import {
   ANY_VERIFIED_CALLER,
+  CONNECTIONS_READ_SCOPE,
+  CONNECTIONS_REVOKE_SCOPE,
+  ERASURE_READ_SCOPE,
+  EVIDENCE_READ_SCOPE,
   KEYS_ROTATE_SCOPE,
   MANIFEST_READ_SCOPE,
   MIGRATIONS_READ_SCOPE,
   PRIVACY_READ_SCOPE,
+  PROCESSING_READ_SCOPE,
+  RETENTION_HOLD_SCOPE,
+  RETENTION_READ_SCOPE,
 } from "../scope/scope";
+import { listConnectionsHandler, revokeConnectionHandler } from "./connections";
 import { requireControlPlane } from "./guard";
 import {
   type ControlPlaneHandlerDeps,
+  erasurePeriodHandler,
+  erasureSubjectHandler,
+  evidenceHandler,
   expireKeyHandler,
   listKeysHandler,
   manifestHandler,
@@ -24,15 +37,39 @@ import {
   privacyHandler,
   registerKeyHandler,
 } from "./handlers";
+import { listHoldsHandler, placeHoldHandler, releaseHoldHandler } from "./holds";
+import { presenceTicketGate, presenceTicketHandler } from "./presence";
+import { processingHandler } from "./processing";
 import {
+  ControlPlaneConnectionsResponse,
+  ControlPlaneErasurePeriodResponse,
+  ControlPlaneErasureSubjectResponse,
+  ControlPlaneEvidenceResponse,
+  ControlPlaneHoldResponse,
+  ControlPlaneHoldsResponse,
   ControlPlaneKeysResponse,
   ControlPlaneMigrationsResponse,
   ControlPlanePingResponse,
   ControlPlanePrivacyResponse,
+  ControlPlaneProcessingResponse,
   ExpireKeyResponse,
   RegisterKeyResponse,
+  RevokeConnectionResponse,
 } from "./responses";
-import { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas";
+import {
+  ConnectionListQuery,
+  ConnectionParams,
+  ErasurePeriodQuery,
+  ErasureSubjectParams,
+  ExpireKeyParams,
+  ExpireKeyRequest,
+  HoldListQuery,
+  HoldParams,
+  PlaceHoldRequest,
+  RegisterKeyRequest,
+  ReleaseHoldRequest,
+  RevokeConnectionRequest,
+} from "./schemas";
 
 /**
  * The seam's own routes, distinct from the admin routes capabilities contribute.
@@ -42,8 +79,18 @@ import { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas
  *   GET  /control-plane/keys                  → the registration state       (keys:rotate)
  *   POST /control-plane/keys                  → register a key               (keys:rotate)
  *   POST /control-plane/keys/:keyId/expire    → retire a superseded key      (keys:rotate)
+ *   GET  /control-plane/connections           → every connection, by principal (connections:read)
+ *   POST /control-plane/connections/:id/revoke → revoke another connection    (connections:revoke)
  *   GET  /control-plane/migrations            → where each database stands   (migrations:read)
  *   GET  /control-plane/privacy               → what each schema holds        (privacy:read)
+ *   GET  /control-plane/evidence              → SOC 2 and ISO 27001 evidence  (evidence:read)
+ *   GET  /control-plane/processing            → the Article 30 record         (processing:read)
+ *   GET  /control-plane/erasure               → every purge in a period       (erasure:read)
+ *   GET  /control-plane/erasure/:type/:id     → one subject's purge, attested (erasure:read)
+ *   GET  /control-plane/holds                 → every legal hold              (retention:read)
+ *   POST /control-plane/holds                 → place a legal hold            (retention:hold)
+ *   POST /control-plane/holds/:id/release     → release one, with a reason    (retention:hold)
+ *   POST /control-plane/presence/tickets      → a ticket into a presence room (the room kind's scope)
  *
  * Every one is `control-plane` and default-denied — with no connection registered they all answer 403,
  * and that is the shipped state of a Worker nobody has connected.
@@ -70,52 +117,155 @@ import { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas
  * `ping` carries a null scope. It requires a verified caller and no authorization, and saying so is
  * how a client knows it can always prove a key — including on a connection granted nothing at all.
  */
-export function controlPlaneRouteDescriptors(basePath: string): AdminRoute[] {
+export function controlPlaneRouteDescriptors(basePath: string): AdminRouteDeclaration[] {
   return [
     {
       method: "GET",
+      operation: "ping",
       path: `${basePath}/ping`,
       scope: null,
       summary: "Prove connectivity and which key answered. Always available to a verified caller.",
     },
     {
       method: "GET",
+      operation: "manifest.read",
       path: `${basePath}/manifest`,
       scope: MANIFEST_READ_SCOPE,
+      kind: "reads",
       summary: "What this Worker composes, and how to call each capability's admin surface.",
     },
     {
       method: "GET",
+      operation: "keys.list",
       path: `${basePath}/keys`,
       scope: KEYS_ROTATE_SCOPE,
+      kind: "credentials",
       summary: "The registered keys, their validity windows, and their ages.",
     },
     {
       method: "POST",
+      operation: "keys.register",
       path: `${basePath}/keys`,
       scope: KEYS_ROTATE_SCOPE,
+      kind: "credentials",
       summary: "Register a successor public key. Signed with the key it replaces; appends only.",
     },
     {
       method: "POST",
+      operation: "keys.expire",
       path: `${basePath}/keys/:keyId/expire`,
       scope: KEYS_ROTATE_SCOPE,
+      kind: "credentials",
       summary: "Retire a superseded key. Must be signed with the successor it names as proven.",
     },
     {
       method: "GET",
+      operation: "connections.list",
+      path: `${basePath}/connections`,
+      scope: CONNECTIONS_READ_SCOPE,
+      kind: "reads",
+      summary:
+        "Every connection bound to this Worker's environment: who authorized it, what kind of client it is for and why, its credentials, grant and trust constraints, and when it was registered or revoked. Filterable by principal. No key material.",
+    },
+    {
+      method: "POST",
+      operation: "connections.revoke",
+      path: `${basePath}/connections/:connectionId/revoke`,
+      scope: CONNECTIONS_REVOKE_SCOPE,
+      kind: "credentials",
+      summary:
+        "Revoke every key and trust another connection in this environment holds, with a reason. Never the calling connection, which ends through disconnect.",
+    },
+    {
+      method: "GET",
+      operation: "migrations.read",
       path: `${basePath}/migrations`,
       scope: MIGRATIONS_READ_SCOPE,
+      kind: "reads",
       summary:
         "What each bound database has applied, what is pending, what is undeclared, and which run put it there. Undeclared is relative to this Worker.",
     },
     {
       method: "GET",
+      operation: "privacy.read",
       path: `${basePath}/privacy`,
       scope: PRIVACY_READ_SCOPE,
+      kind: "reads",
       summary:
         "Every stored schema holding a privacy-marked field, each field's path and class, and where it lives. Derived from the running code.",
     },
+    {
+      method: "GET",
+      operation: "evidence.read",
+      path: `${basePath}/evidence`,
+      scope: EVIDENCE_READ_SCOPE,
+      kind: "reads",
+      summary:
+        "SOC 2 and ISO 27001 evidence derived from what this Worker composes and records: each control's facts, their sources, and what could be said. Evidence for an auditor, never a judgment.",
+    },
+    {
+      method: "GET",
+      operation: "processing.read",
+      path: `${basePath}/processing`,
+      scope: PROCESSING_READ_SCOPE,
+      kind: "reads",
+      summary:
+        "The record of processing activities, GDPR Article 30: each purpose, its data classes, legal basis, recipients, retention and measures, and every gap named.",
+    },
+    {
+      method: "GET",
+      operation: "erasure.list",
+      path: `${basePath}/erasure`,
+      scope: ERASURE_READ_SCOPE,
+      kind: "reads",
+      summary:
+        "Every purge in a period: how many completed, are in progress or failed, and each failed or overdue one with the step it stopped at.",
+    },
+    {
+      method: "GET",
+      operation: "erasure.read",
+      path: `${basePath}/erasure/:subjectType/:subjectId`,
+      scope: ERASURE_READ_SCOPE,
+      kind: "reads",
+      summary:
+        "One user's or organization's erasure: the deletion, every step erased or kept with its reason, the state, and the audit events that record each.",
+    },
+    {
+      method: "GET",
+      operation: "holds.list",
+      path: `${basePath}/holds`,
+      scope: RETENTION_READ_SCOPE,
+      kind: "reads",
+      summary:
+        "Every legal hold, standing first: its subject, who placed it and why, and when and why it was released.",
+    },
+    {
+      method: "POST",
+      operation: "holds.place",
+      path: `${basePath}/holds`,
+      scope: RETENTION_HOLD_SCOPE,
+      kind: "writes",
+      summary:
+        "Place a legal hold on a user, an organization or a tenant's audit trail, with a reason. Every purge, prune and inactivity deletion touching it stops until it is released.",
+    },
+    {
+      method: "POST",
+      operation: "holds.release",
+      path: `${basePath}/holds/:holdId/release`,
+      scope: RETENTION_HOLD_SCOPE,
+      kind: "writes",
+      summary: "Release a legal hold, with a reason. The subject returns to the retention the Worker deploys with.",
+    },
+    {
+      method: "POST",
+      operation: "presence.tickets.mint",
+      path: `${basePath}/presence/tickets`,
+      // Null because no one scope covers it: the call needs the scope of the room kind its body names, which
+      // each kind states in the manifest. Its gate resolves that scope from the body and verifies against it.
+      scope: null,
+      summary:
+        "Mint a single-use ticket into one presence room. Needs the room kind's own scope, which the manifest lists beside each kind.",
+    },
   ];
 }
 
@@ -187,6 +337,37 @@ export function registerControlPlaneRoutes(
     (c) => expireKeyHandler(deps)(c, c.req.valid("param"), c.req.valid("json")),
   );
 
+  app.get(
+    `${basePath}/connections`,
+    describeRoute({
+      summary: "List every connection in this Worker's environment.",
+      description:
+        "Every connection bound to this Worker's environment, the caller's own among them; a database shared with another environment never lists that environment's rows. Each connection's id, environment, actor kind, purpose, authorizing principal, credential kind, granted scopes, every trust's subject constraint, whether it is live, and when it was registered and revoked. `principal` narrows to the connections one email authorized; connections registered before principals were recorded are listed apart in `unattributed` and never match. No key material and no secret. Read-only.",
+      verification: "control-plane",
+      scopes: [CONNECTIONS_READ_SCOPE],
+      responses: { 200: ControlPlaneConnectionsResponse },
+    }),
+    requireControlPlane(CONNECTIONS_READ_SCOPE),
+    validate("query", ConnectionListQuery),
+    (c) => listConnectionsHandler(deps)(c, c.req.valid("query")),
+  );
+
+  app.post(
+    `${basePath}/connections/:connectionId/revoke`,
+    describeRoute({
+      summary: "Revoke another connection.",
+      description:
+        "Revokes every key and trust on the connection not yet revoked, at once, with a reason: a live one, and one whose window has not opened yet. A token already minted under a trust stays usable until it expires. Refused on the calling connection, which ends through `pithy dashboard disconnect`, naming its environment with `--env`. A connection bound to another environment answers 404. `pithy dashboard connect` keeps one connection per environment, replacing the one stored, so this route has a target only where the database holds more than one connection for this environment. Audited as `controlplane/connection_revoked`.",
+      verification: "control-plane",
+      scopes: [CONNECTIONS_REVOKE_SCOPE],
+      responses: { 200: RevokeConnectionResponse },
+    }),
+    requireControlPlane(CONNECTIONS_REVOKE_SCOPE),
+    validate("param", ConnectionParams),
+    validate("json", RevokeConnectionRequest),
+    (c) => revokeConnectionHandler(deps)(c, c.req.valid("param"), c.req.valid("json")),
+  );
+
   app.get(
     `${basePath}/migrations`,
     describeRoute({
@@ -214,4 +395,122 @@ export function registerControlPlaneRoutes(
     requireControlPlane(PRIVACY_READ_SCOPE),
     privacyHandler(deps),
   );
+
+  app.get(
+    `${basePath}/evidence`,
+    describeRoute({
+      summary: "Report the evidence this Worker derives for SOC 2 and ISO 27001.",
+      description:
+        "Seven controls, each with its SOC 2 and ISO/IEC 27001:2022 references, the facts read, the declaration each came from, and `evidenced`, `gap` or `not-derivable` with the reason. Derived from what this Worker composes and records. Evidence for an auditor to weigh, never a judgment. A fact another read keeps behind its own scope stays behind it. Read-only.",
+      verification: "control-plane",
+      scopes: [EVIDENCE_READ_SCOPE],
+      responses: { 200: ControlPlaneEvidenceResponse },
+    }),
+    requireControlPlane(EVIDENCE_READ_SCOPE),
+    evidenceHandler(deps),
+  );
+
+  app.get(
+    `${basePath}/processing`,
+    describeRoute({
+      summary: "Report the record of processing activities.",
+      description:
+        "Every processing activity the composed capabilities and the `processing` block declare: its purpose, the data classes it uses cross-checked against the privacy inventory, its legal basis or a gap, a consent basis's purpose and grant counts, its recipients with what each receives, its effective retention, and the evidence pack's controls. Every gap is named and none is filled in. It describes the processing and changes none of it. Read-only.",
+      verification: "control-plane",
+      scopes: [PROCESSING_READ_SCOPE],
+      responses: { 200: ControlPlaneProcessingResponse },
+    }),
+    requireControlPlane(PROCESSING_READ_SCOPE),
+    processingHandler(deps),
+  );
+
+  app.get(
+    `${basePath}/erasure`,
+    describeRoute({
+      summary: "Report every purge in a period.",
+      description:
+        "Every user and organization purge that came due, ran a step, failed or completed in the window: counts of scheduled, in progress, complete, failed and overdue, and each failed or overdue one named with the step it stopped at. The window defaults to the 90 days before `until`, and is at most 366 days. Read-only.",
+      verification: "control-plane",
+      scopes: [ERASURE_READ_SCOPE],
+      responses: { 200: ControlPlaneErasurePeriodResponse },
+    }),
+    requireControlPlane(ERASURE_READ_SCOPE),
+    validate("query", ErasurePeriodQuery),
+    (c) => erasurePeriodHandler(deps)(c, c.req.valid("query")),
+  );
+
+  app.get(
+    `${basePath}/erasure/:subjectType/:subjectId`,
+    describeRoute({
+      summary: "Attest one subject's erasure.",
+      description:
+        "For one user or organization: when it was deleted, by which kind of actor and why, soft or hard, every purge step with its capability, whether it erased or kept the rows and why, and when it finished, the purge's state, and the audit events that record each step by event id and chain position. Nothing about the subject beyond its id. Read-only.",
+      verification: "control-plane",
+      scopes: [ERASURE_READ_SCOPE],
+      responses: { 200: ControlPlaneErasureSubjectResponse },
+    }),
+    requireControlPlane(ERASURE_READ_SCOPE),
+    validate("param", ErasureSubjectParams),
+    (c) => erasureSubjectHandler(deps)(c, c.req.valid("param")),
+  );
+
+  app.get(
+    `${basePath}/holds`,
+    describeRoute({
+      summary: "List the legal holds.",
+      description:
+        "Every hold, standing first and newest first within each: the subject, who placed it and why, and when, by whom and why it was released. `active` counts the holds standing. Read-only.",
+      verification: "control-plane",
+      scopes: [RETENTION_READ_SCOPE],
+      responses: { 200: ControlPlaneHoldsResponse },
+    }),
+    requireControlPlane(RETENTION_READ_SCOPE),
+    validate("query", HoldListQuery),
+    (c) => listHoldsHandler(deps)(c, c.req.valid("query")),
+  );
+
+  app.post(
+    `${basePath}/holds`,
+    describeRoute({
+      summary: "Place a legal hold.",
+      description:
+        "Holds one user, one organization, or one tenant's audit trail, with a reason. While it stands no purge, prune or inactivity deletion touches the subject, and a purge already running stops at its next step. Audited. A hold can only preserve: nothing here shortens a retention.",
+      verification: "control-plane",
+      scopes: [RETENTION_HOLD_SCOPE],
+      responses: { 201: ControlPlaneHoldResponse },
+    }),
+    requireControlPlane(RETENTION_HOLD_SCOPE),
+    validate("json", PlaceHoldRequest),
+    (c) => placeHoldHandler(deps)(c, c.req.valid("json")),
+  );
+
+  app.post(
+    `${basePath}/holds/:holdId/release`,
+    describeRoute({
+      summary: "Release a legal hold.",
+      description:
+        "Ends one standing hold, with a reason, and keeps it as a record. The subject returns to the Worker's retention; a purge it stopped resumes on the next daily pass. Audited.",
+      verification: "control-plane",
+      scopes: [RETENTION_HOLD_SCOPE],
+      responses: { 200: ControlPlaneHoldResponse },
+    }),
+    requireControlPlane(RETENTION_HOLD_SCOPE),
+    validate("param", HoldParams),
+    validate("json", ReleaseHoldRequest),
+    (c) => releaseHoldHandler(deps)(c, c.req.valid("param"), c.req.valid("json")),
+  );
+
+  app.post(
+    `${basePath}/presence/tickets`,
+    describeRoute({
+      summary: "Mint a presence ticket for a management client.",
+      description:
+        "Admits the participant the body names to one room of any kind this Worker composes. Sign the call with the room kind's own scope, as the manifest lists it; presence adds no scope. Single use, for 60 seconds. Open the socket at `socketPath`, offering `protocol` and `pithy.ticket.<ticket>` in `Sec-WebSocket-Protocol`.",
+      verification: "control-plane",
+      responses: { 201: PresenceTicket },
+    }),
+    presenceTicketGate(deps),
+    validate("json", ControlPlanePresenceTicketRequest),
+    (c) => presenceTicketHandler(deps)(c, c.req.valid("json")),
+  );
 }

package/src/controlPlane/http/schemas.ts

@@ -3,6 +3,7 @@
 
 import { z } from "zod";
 import { Ed25519PublicJwk } from "../data/connection";
+import { HoldState, HoldSubjectType } from "../data/hold";
 
 /**
  * The request contract for the seam's own routes. Every input surface is validated here and read in a
@@ -68,3 +69,128 @@ export const ExpireKeyRequest = z
     "A request to expire one superseded key. The successor must be named and must already be live — append, verify, then expire, never replace.",
   );
 export type ExpireKeyRequest = z.infer<typeof ExpireKeyRequest>;
+
+/** `GET /control-plane/erasure/:subjectType/:subjectId` — which subject. */
+export const ErasureSubjectParams = z
+  .object({
+    subjectType: z.enum(["user", "organization"]).describe("The kind of subject: `user` or `organization`."),
+    subjectId: z.string().min(1).max(255).describe("The subject's id."),
+  })
+  .describe("The subject whose erasure to attest.");
+export type ErasureSubjectParams = z.infer<typeof ErasureSubjectParams>;
+
+/** `GET /control-plane/erasure?since&until` — the period. */
+export const ErasurePeriodQuery = z
+  .object({
+    since: z.iso
+      .datetime({ offset: true })
+      .optional()
+      .describe("The window's inclusive start, ISO-8601. Defaults to 90 days before `until`."),
+    until: z.iso
+      .datetime({ offset: true })
+      .optional()
+      .describe("The window's inclusive end, ISO-8601. Defaults to now."),
+  })
+  .describe("The period to attest: at most 366 days.");
+export type ErasurePeriodQuery = z.infer<typeof ErasurePeriodQuery>;
+
+/**
+ * Place a legal hold. The subject and a reason, and nothing else: no field shortens a retention, because a hold
+ * can only preserve.
+ */
+export const PlaceHoldRequest = z
+  .object({
+    subjectType: HoldSubjectType,
+    subjectId: z
+      .string()
+      .min(1)
+      .max(255)
+      .nullable()
+      .describe(
+        "The user's or organization's id, or the tenant whose audit trail to hold. Null only for `audit`, which then holds the untenanted trail.",
+      ),
+    reason: z
+      .string()
+      .trim()
+      .min(1)
+      .max(500)
+      .describe(
+        "Why the hold is placed, in one or two sentences. Required, and recorded with the hold and its audit event.",
+      ),
+  })
+  .strict()
+  .refine((body) => body.subjectId !== null || body.subjectType === "audit", {
+    message: "Only an audit hold may name no subject: a user or organization hold names its id.",
+    path: ["subjectId"],
+  })
+  .describe("A legal hold to place: the subject, and why.");
+export type PlaceHoldRequest = z.infer<typeof PlaceHoldRequest>;
+
+/** The path parameter of the release route. */
+export const HoldParams = z
+  .object({ holdId: z.string().min(1).max(64).describe("The hold's id, as placing it returned.") })
+  .describe("The hold to release.");
+export type HoldParams = z.infer<typeof HoldParams>;
+
+/** Release a legal hold, with a reason. */
+export const ReleaseHoldRequest = z
+  .object({
+    reason: z
+      .string()
+      .trim()
+      .min(1)
+      .max(500)
+      .describe("Why the hold is released. Required, and recorded with the release and its audit event."),
+  })
+  .strict()
+  .describe("A legal hold's release: why it ends.");
+export type ReleaseHoldRequest = z.infer<typeof ReleaseHoldRequest>;
+
+/** Which holds to list. */
+export const HoldListQuery = z
+  .object({
+    state: HoldState.optional().describe("Only holds in this state. Absent lists both, standing first."),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(500)
+      .optional()
+      .describe("How many holds to list, at most 500. Defaults to 100."),
+  })
+  .describe("Which legal holds to list.");
+export type HoldListQuery = z.infer<typeof HoldListQuery>;
+
+/** Which connections to list. */
+export const ConnectionListQuery = z
+  .object({
+    principal: z
+      .email()
+      .max(254)
+      .optional()
+      .describe(
+        "Only connections this email authorized, compared without regard to case. Connections with no recorded principal are listed apart either way and never match.",
+      ),
+  })
+  .describe("Which connections to list.");
+export type ConnectionListQuery = z.infer<typeof ConnectionListQuery>;
+
+/** The path parameter of the revoke route. */
+export const ConnectionParams = z
+  .object({ connectionId: z.uuid().describe("The connection's id, as the listing reports it.") })
+  .describe("The connection to revoke.");
+export type ConnectionParams = z.infer<typeof ConnectionParams>;
+
+/** Revoke a connection, with a reason. */
+export const RevokeConnectionRequest = z
+  .object({
+    reason: z
+      .string()
+      .trim()
+      .min(1)
+      .max(500)
+      .describe("Why the connection is revoked. Required, and recorded on the revocation's audit event."),
+  })
+  .strict()
+  .describe("A connection's revocation: why it ends.");
+export type RevokeConnectionRequest = z.infer<typeof RevokeConnectionRequest>;

package/src/controlPlane/http/verify.ts

@@ -158,13 +158,30 @@ export async function verifyControlPlaneCall(
   await verifyBodyDigest(call.body, claims.bodySha256);
 
   // 11. Scope. Both sides must agree: what the adopter granted, and what this one token was minted for.
+  //     A signature proves who minted the token, not who presented it, and a token binds no path: one captured
+  //     token can be presented at every route it does not cover. So the refusal spends the jti, and names the
+  //     caller only when this presentation was the first (#812). A replay gets the same refusal and names nobody.
+  //     Spending costs the caller nothing — the call is refused either way — and it still happens only after
+  //     step 7, so a forgery cannot burn a jti it merely observed.
   if (!scopeCovers(call.requirement, claims.scope, connection.scopes)) {
+    const firstPresentation = await deps.replay.claim(claims.jti, connection.id);
+    const spent = firstPresentation ? "" : `; jti ${claims.jti} was already spent`;
     throw new ControlPlaneInsufficientScopeError({
-      detail: `required ${String(call.requirement)}; token carried ${claims.scope}; connection grants [${connection.scopes.join(", ")}]`,
+      detail: `required ${String(call.requirement)}; token carried ${claims.scope}; connection grants [${connection.scopes.join(", ")}]${spent}`,
+      ...(firstPresentation
+        ? {
+            caller: {
+              connectionId: connection.id,
+              subject: claims.sub,
+              keyId: key.keyId,
+              actorKind: connection.actorKind,
+            },
+          }
+        : {}),
     });
   }
 
-  // 12. Spend the token. Last, because it is the only step that writes anything.
+  // 12. Spend the token. Last, because it is the only step that writes anything a granted call depends on.
   if (!(await deps.replay.claim(claims.jti, connection.id))) {
     deny(`jti ${claims.jti} was already spent`);
   }