@pithy-sh/core 0.10.0 → 0.11.0

package/src/controlPlane/data/connection.ts

@@ -66,6 +66,81 @@ export const RegisteredKey = z
   .describe("One registered public key with its validity window. Two live at once during a rotation overlap.");
 export type RegisteredKey = z.output<typeof RegisteredKey>;
 
+/**
+ * What kind of client a connection is for (#721): `agent`, `dashboard` or `script`.
+ *
+ * The audit trail's `actorType: "control-plane"` names all three identically, and the questions asked
+ * after an incident are exactly the ones that tell them apart — was it a person at the dashboard, a
+ * script somebody wrote, or an agent running unattended. So the kind is recorded on the connection when
+ * it is registered and stamped from there onto every row its calls write.
+ *
+ * It follows the path, never a guess: the device-code flow is a dashboard, always, and a key the
+ * operator registered themselves is whichever of the other two they say, out loud, with `--kind`.
+ */
+export const ControlPlaneActorKind = z
+  .enum(["agent", "dashboard", "script"])
+  .describe(
+    "What kind of client a connection is for: `agent` (an automated client acting on its own judgment, often unattended), `dashboard` (a management dashboard a person drives, registered through the device-code flow), or `script` (an operator's own automation, doing one fixed thing).",
+  );
+export type ControlPlaneActorKind = z.output<typeof ControlPlaneActorKind>;
+
+/**
+ * Who sanctioned a connection: the email address of the signed-in Cloudflare session that registered it.
+ *
+ * **A plain string, deliberately not a reference.** An adopter's `pithy_auth_users` are their customers,
+ * and the operator who registers a connection is their staff, so a join into the organization model would
+ * be empty for most of them. A string is readable by anybody, and matchable against a directory where the
+ * operator is in one.
+ *
+ * **Derived, never asserted.** No flag supplies it; the CLI reads it from `GET /user` under the session.
+ */
+export const ConnectionPrincipal = z
+  .email()
+  .max(254)
+  .describe(
+    "The email address of the person who sanctioned this connection, read from their signed-in Cloudflare session at registration. Never typed, so never asserted.",
+  );
+export type ConnectionPrincipal = z.output<typeof ConnectionPrincipal>;
+
+/** The longest purpose a connection may carry. One line on a review screen, with room to say what it does. */
+export const MAX_CONNECTION_PURPOSE = 200;
+
+/**
+ * Characters a purpose may not carry: every C0 and C1 control (so no terminal escape, no newline and no
+ * carriage return), the Unicode line and paragraph separators, every `Bidi_Control` character — the
+ * embeddings, overrides and isolates, and the LRM, RLM and ALM marks — that lets text render in a
+ * different order from the one it is stored in, and the invisible zero-width space, word joiner and
+ * byte-order mark that split a word without showing it. The zero-width joiner and non-joiner stay: Persian
+ * and the Indic scripts cannot be written without them.
+ *
+ * Each of those is a way for a sentence to look like something else once it reaches a renderer: a line
+ * in `pithy dashboard status` forged beneath the real one, a screen cleared, a scope name read backwards.
+ * Escaping them at every renderer is a promise each renderer has to keep. Refusing them at the boundary
+ * is one promise, kept here.
+ */
+const UNRENDERABLE = /[\p{Cc}\p{Bidi_Control}\u2028\u2029\u200B\u2060\uFEFF]/u;
+
+/**
+ * What a connection is for, in the words of whoever registered it (#721).
+ *
+ * **Required at registration, and refused when absent**, because a review listing credentials by key id
+ * cannot support the decision it exists for. **Untrusted input**: a customer writes it and something else
+ * renders it, so it is validated on the way in, and again on every read of the row.
+ */
+export const ConnectionPurpose = z
+  .string()
+  .trim()
+  .min(1, "Say what this client is for.")
+  .max(MAX_CONNECTION_PURPOSE, `A purpose is ${MAX_CONNECTION_PURPOSE} characters at most.`)
+  .refine(
+    (purpose) => !UNRENDERABLE.test(purpose),
+    "A purpose is one line of plain text: no control, bidi or invisible characters.",
+  )
+  .describe(
+    `What this connection's client is for, in the registering operator's words — one line of plain text, ${MAX_CONNECTION_PURPOSE} characters at most, with no control, bidi or invisible characters. Written by a customer and rendered elsewhere, so validated at the boundary.`,
+  );
+export type ConnectionPurpose = z.output<typeof ConnectionPurpose>;
+
 /**
  * One management-client connection — the row in `pithy_controlplane_connections`.
  *
@@ -112,6 +187,21 @@ export const ControlPlaneConnection = z
       .describe(
         "Where the management client that registered this connection answers — the origin the CLI calls for a verify, a rotation or a disconnect. Stored because it is not derivable: `issuer` is what that client *signs as*, and nothing says a dashboard's API answers at its own `iss`. Null for a connection registered before this column, which reads as the issuer rather than as the hosted dashboard — an older row is still a row about somebody's own deployment. Nothing on the Worker's side reads it; verification cares about `issuer` alone.",
       ),
+    authorizedBy: ConnectionPrincipal.nullable()
+      .default(null)
+      .describe(
+        "Who sanctioned this connection: the email of the signed-in Cloudflare session that registered it, never a flag. Null for a connection registered before principals were recorded (#721), which keeps working and reads as exactly that; registering again is the only way to set it.",
+      ),
+    actorKind: ControlPlaneActorKind.nullable()
+      .default(null)
+      .describe(
+        "What kind of client this connection is for — `agent`, `dashboard` or `script` — stamped onto every audit row its calls write so the trail can tell them apart. Null for a connection registered before it was recorded.",
+      ),
+    purpose: ConnectionPurpose.nullable()
+      .default(null)
+      .describe(
+        "What this connection's client is for, in the registering operator's words. Required at registration and editable with `pithy dashboard connect --update --purpose`; null only for a connection registered before it was recorded.",
+      ),
     scopes: sqliteJson(z.array(ControlPlaneScope)).describe(
       "The operations this connection was granted, stored and enforced on the adopter's side. Enforced only by the caller, a scope would not be a limit at all.",
     ),

package/src/controlPlane/http/cors.ts

@@ -217,10 +217,10 @@ export function corsMiddleware(
 /**
  * Mount one `app.use(path, …)` per entry.
  *
- * **Called from the capability's `middleware` hook, never its `routes` hook, and that is load-bearing.**
- * `createBackend` runs every capability's `middleware` hook before **any** capability's `routes` hook
- * (`createBackend.ts:262-267`), which is what makes this independent of the order an adopter happens to
- * list their capabilities in.
+ * **Called from `createBackend` ahead of every capability's `middleware`, never from a `routes` hook,
+ * and that is load-bearing.** Registered there, it is independent of the order an adopter happens to
+ * list their capabilities in, and it can put a header on whatever a capability's middleware or a
+ * readiness guard short-circuits.
  *
  * From `routes` it looks like it works and does not. The preflight still answers — an `OPTIONS` has no
  * route handler to lose to, so this `use` is the only thing that matches it — but a capability composed

package/src/controlPlane/http/guard.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import type { MiddlewareHandler } from "hono";
+import type { AuditEmit } from "../../audit/recorder";
 import type { PithyHonoEnv } from "../../capability/capability";
 import { commandName, remedy } from "../../cli/command";
 import { type AmbientEnv, compositionEnvironment } from "../../env/ambient";
@@ -9,6 +10,7 @@ import { PithyError } from "../../error/pithyError";
 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 type { ControlPlaneRequirement } from "../scope/scope";
 import { CONTROL_PLANE_HEADER, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER } from "../wire";
@@ -156,6 +158,11 @@ export function requireControlPlane(requirement: ControlPlaneRequirement): Middl
     }
 
     c.set("controlPlane", context);
+    // Every control-plane row this call writes says which kind of client wrote it (#721). Stamped here,
+    // once, rather than at each of the dozens of emit sites across the capabilities, because a rule kept
+    // at the call sites regrows the moment someone adds one — and `actorType` alone names an agent, the
+    // dashboard and a script identically.
+    c.set("emit", stampActorKind(c.var.emit, context.actorKind));
     await safeEmit(
       c.var.emit,
       {
@@ -185,6 +192,20 @@ export function requireControlPlane(requirement: ControlPlaneRequirement): Middl
   return guard;
 }
 
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function stampActorKind(emit: AuditEmit, actorKind: ControlPlaneActorKind | null): AuditEmit {
+  if (actorKind === null) return emit;
+  return (event) =>
+    emit(event.actorType === "control-plane" && event.actorKind == null ? { ...event, actorKind } : event);
+}
+
 /**
  * Record a refused call.
  *

package/src/controlPlane/http/handlers.ts

@@ -3,6 +3,7 @@
 
 import type { Context } from "hono";
 import type { PithyHonoEnv } from "../../capability/capability";
+import { causeMessage } from "../../error/cause";
 import { workerVersion } from "../../worker/identity";
 import { ControlPlaneAuditActions, safeEmit } from "../audit/actions";
 import type { ControlPlaneConfig } from "../config/config";
@@ -14,8 +15,10 @@ import type { CapabilityDeclaration, ControlPlaneManifestWire } from "../discove
 import { type CapabilityHealthSource, readCapabilityHealth } from "../discovery/health";
 import { healthWire } from "../discovery/healthSummary";
 import { ControlPlaneInvalidCredentialError, ControlPlaneKeyConflictError } from "../error/errors";
+import { type ComposedMigrationDatabase, readDatabaseMigrations } from "../migrationState/migrationState";
 import type {
   ControlPlaneKeysResponse,
+  ControlPlaneMigrationsResponse,
   ControlPlanePingResponse,
   ExpireKeyResponse,
   PublicKeyView,
@@ -68,6 +71,11 @@ export interface ControlPlaneHandlerDeps {
    * value is not: the numbers are resolved per request, behind the scope each one is declared under.
    */
   composedHealth: () => ReadonlyMap<string, CapabilityHealthSource>;
+  /**
+   * Every database this Worker binds, with the provider this build composes for it — captured by the same
+   * `compose` hook through `collectMigrationSets`, the function `pithy migrate` composes with (#729).
+   */
+  composedMigrations: () => readonly ComposedMigrationDatabase[];
   /** The clock, injected so a test can stand at any instant. */
   now: () => Date;
 }
@@ -203,6 +211,34 @@ export function manifestHandler(deps: ControlPlaneHandlerDeps) {
   };
 }
 
+/**
+ * `GET /control-plane/migrations` — where each database this Worker binds stands (#729).
+ *
+ * Read-only: it reports, and nothing over the seam runs, reverses or resets a migration.
+ *
+ * **One unreadable ledger costs one database its answer.** Each read catches its own failure and lands on
+ * `unreadable`, so `Promise.all` still resolves and the route answers 200 with what it has. The cause is
+ * logged here, for the operator, and never projected: a D1 error can name a table or a query.
+ */
+export function migrationsHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>) => {
+    const context = caller(c);
+    const env = c.env as Record<string, unknown>;
+    const databases = await Promise.all(
+      deps.composedMigrations().map((entry) =>
+        readDatabaseMigrations(env, entry, (failed, cause) =>
+          c.var.log.warn("migration ledger unreadable", {
+            database: failed.database,
+            binding: failed.binding,
+            reason: causeMessage(cause) ?? String(cause),
+          }),
+        ),
+      ),
+    );
+    return c.json({ environment: context.environment, databases } satisfies ControlPlaneMigrationsResponse);
+  };
+}
+
 /** `GET /control-plane/keys` — the registration state, so a client can surface a stale key. */
 export function listKeysHandler(deps: ControlPlaneHandlerDeps) {
   return async (c: Context<PithyHonoEnv>) => {
@@ -212,6 +248,11 @@ export function listKeysHandler(deps: ControlPlaneHandlerDeps) {
       connectionId: connection.id,
       environment: connection.environment,
       keys: connection.keys.map(publicKeyView),
+      // The review a credential listing exists for needs these, and it is the adopter's to perform —
+      // on their own side, from their own row (#721).
+      authorizedBy: connection.authorizedBy,
+      actorKind: connection.actorKind,
+      purpose: connection.purpose,
     } satisfies ControlPlaneKeysResponse);
   };
 }

package/src/controlPlane/http/readiness.ts

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Hono } from "hono";
+import type { PithyHonoEnv, PithyReadinessGuard } from "../../capability/capability";
+
+/**
+ * Mount every capability's readiness guard, exempting the admin surface.
+ *
+ * **The control plane answers whatever else is wrong with the Worker.** It is the diagnostic surface: a
+ * management client reads the manifest, migration state and drift through it. A guard that refuses every
+ * request because an index drifted would take that surface down on exactly the fault it exists to report,
+ * and the client could not tell drift from a Worker that is simply down.
+ *
+ * **The exemption is the guard, not the middleware.** The seam itself runs on capability middleware —
+ * `controlplane()` publishes the verifier and `audit()` publishes `emit` — so skipping middleware on a
+ * seam request would trade a 500 for a seam that denies everything, or one that stops auditing without a
+ * word. Readiness guards are the only middleware that refuses because the Worker is broken, so they are
+ * the only thing skipped.
+ *
+ * **Hono decides what is on the surface, not a matcher written here.** One `app.use` per admin path marks
+ * the request, so a `:segment` matches exactly as it does for the route and the CORS layer, and a literal
+ * path never matches what is beneath it. The surface is the one `corsSurface(all)` computes, which
+ * `routeContract.test.ts` already holds to the registered routes, so there is no second list to drift.
+ *
+ * The mark is a `WeakSet` over the raw `Request`, closed over here. A context variable would put an
+ * internal flag on `PithyVars`, where every capability could read it and one could set it.
+ *
+ * Call after every capability's `middleware` and before any capability's `routes`. Before the routes,
+ * because a terminal handler never calls `next()` and a guard mounted after it never runs.
+ */
+export function registerReadinessGuards(
+  app: Hono<PithyHonoEnv>,
+  surface: readonly { path: string }[],
+  guards: readonly PithyReadinessGuard[],
+): void {
+  if (guards.length === 0) return;
+
+  const onSurface = new WeakSet<Request>();
+  for (const path of new Set(surface.map((entry) => entry.path))) {
+    app.use(path, async (c, next) => {
+      onSurface.add(c.req.raw);
+      await next();
+    });
+  }
+
+  for (const guard of guards) {
+    app.use("*", (c, next) => (onSurface.has(c.req.raw) ? next() : guard(c, next)));
+  }
+}

package/src/controlPlane/http/responses.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
-import { Ed25519PublicJwk } from "../data/connection";
+import { ConnectionPrincipal, ConnectionPurpose, ControlPlaneActorKind, Ed25519PublicJwk } from "../data/connection";
 
 /**
  * What the seam's own routes return, as Zod objects a management client can validate against.
@@ -65,8 +65,25 @@ export const ControlPlaneKeysResponse = z
     connectionId: z.string().describe("The connection these keys belong to."),
     environment: z.string().describe("The environment that connection is bound to."),
     keys: z.array(PublicKeyView).describe("Every registered key, expired and revoked ones included."),
+    // Added (#721), so `.optional()` as well as `.nullable()`: a client validating against a Worker that
+    // predates the three columns receives none of them, and must still parse the answer.
+    authorizedBy: ConnectionPrincipal.nullable()
+      .optional()
+      .describe(
+        "Who sanctioned this connection — the signed-in session's email at registration. Null for a connection registered before principals were recorded; absent from a Worker older than the field.",
+      ),
+    actorKind: ControlPlaneActorKind.nullable()
+      .optional()
+      .describe(
+        "What kind of client this connection is for: `agent`, `dashboard` or `script`. Null for a connection registered before it was recorded; absent from an older Worker.",
+      ),
+    purpose: ConnectionPurpose.nullable()
+      .optional()
+      .describe(
+        "What the client is for, in the registering operator's words. Untrusted text: render it escaped. Null for a connection registered before it was recorded; absent from an older Worker.",
+      ),
   })
-  .describe("Every key registered against this connection, with its window.");
+  .describe("Every key registered against this connection, with its window, and who authorized it for what.");
 export type ControlPlaneKeysResponse = z.output<typeof ControlPlaneKeysResponse>;
 
 /** `POST /control-plane/keys` — the appended key, and the set as it now stands. */
@@ -90,3 +107,124 @@ export const ExpireKeyResponse = z
   })
   .describe("The expired key, and the set it left behind.");
 export type ExpireKeyResponse = z.output<typeof ExpireKeyResponse>;
+
+/**
+ * One migration as `GET {basePath}/migrations` reports it: its composed name, and whose it is.
+ *
+ * The namespace is a capability's name, which the manifest already reports in `capabilities[]`. So a
+ * client tells an adopter's own migrations from a composed capability's by comparing the two — no
+ * convention, and no list kept anywhere.
+ */
+export const MigrationView = z
+  .object({
+    name: z.string().describe("The composed migration name, exactly as the ledger records it: `0250_audit_0001_init`."),
+    namespace: z
+      .string()
+      .nullable()
+      .describe(
+        "The capability this migration belongs to — its name, as `capabilities[]` in the manifest reports it. Null only for an undeclared migration whose name no Pithy registry could have composed.",
+      ),
+  })
+  .describe("One migration, and the capability namespace it belongs to.");
+export type MigrationView = z.output<typeof MigrationView>;
+
+/** Whether the last group is still reversible by name, or what is in its way. */
+export const MigrationGroupPositionView = z
+  .discriminatedUnion("state", [
+    z
+      .object({
+        state: z
+          .literal("top")
+          .describe(
+            "The group's migrations are the contiguous tip of this database's chain. Not a promise that `pithy migrate --rollback --group <value>` runs: the CLI also refuses an undeclared migration in the ledger, and keeps back or refuses a database another environment binds.",
+          ),
+      })
+      .describe("A group nothing on this database's ledger sits over."),
+    z
+      .object({
+        state: z
+          .literal("buried")
+          .describe("Something sits over the group or inside it, so reversing it by name is refused."),
+        above: z.array(z.string()).describe("The groups in the way, newest first."),
+        ungrouped: z
+          .array(MigrationView)
+          .describe(
+            "The migrations in the way that no group claims, newest first. Nothing can be reversed by group while one of them is at the tip.",
+          ),
+      })
+      .describe("A group with something in its way, and what that is."),
+  ])
+  .describe("Where the last group sits in this database's chain: the top, or buried under named things.");
+export type MigrationGroupPositionView = z.output<typeof MigrationGroupPositionView>;
+
+/** The run that last moved a database, and whether it can still be taken back. */
+export const MigrationGroupView = z
+  .object({
+    group: z
+      .string()
+      .describe("The group's value: the `--group` the run was given, or the ISO-8601 timestamp it generated."),
+    appliedAt: z.iso.datetime().describe("When this group last applied something here, ISO-8601."),
+    migrations: z
+      .array(MigrationView)
+      .describe("What this group applied in this database and is still applied, in application order."),
+    position: MigrationGroupPositionView.describe("Whether the group is the top of the chain, or what is in its way."),
+  })
+  .describe("The newest group with anything still applied in this database.");
+export type MigrationGroupView = z.output<typeof MigrationGroupView>;
+
+/**
+ * One database this Worker binds, read or not.
+ *
+ * **An unreadable database carries no list at all**, never empty ones. `pending: []` reads as up to date,
+ * and a database nobody read is not that. The state is on the value, so a client reaches a list only by
+ * narrowing.
+ */
+export const MigrationDatabaseView = z
+  .discriminatedUnion("state", [
+    z
+      .object({
+        state: z.literal("readable").describe("This database's ledger was read."),
+        database: z.string().describe("The database name, as capabilities declare it in `databases`."),
+        binding: z.string().describe("The D1 binding it is read through, as `wrangler.jsonc` declares it."),
+        applied: z.array(MigrationView).describe("Every applied migration, in the order the ledger applied them."),
+        pending: z
+          .array(MigrationView)
+          .describe("Declared by this build and not applied here, in the order they would run."),
+        undeclared: z
+          .array(MigrationView)
+          .describe(
+            "Applied here and not declared by this Worker, sorted. Relative to this Worker: a database shared with another Worker lists that Worker's migrations here. Otherwise Kysely reads one as a corrupted chain and applies nothing.",
+          ),
+        lastGroup: MigrationGroupView.nullable().describe(
+          "The newest group with anything applied here, or null when nothing applied here was ever grouped.",
+        ),
+      })
+      .describe("A database whose ledger was read."),
+    z
+      .object({
+        state: z.literal("unreadable").describe("This database's ledger could not be read on this call."),
+        database: z.string().describe("The database name, as capabilities declare it in `databases`."),
+        binding: z.string().describe("The D1 binding it would be read through."),
+      })
+      .describe(
+        "A database that could not be read. No lists, so nothing about it reads as zero. The other databases still answer.",
+      ),
+  ])
+  .describe("One database this Worker binds: its migration state, or the fact that it could not be read.");
+export type MigrationDatabaseView = z.output<typeof MigrationDatabaseView>;
+
+/**
+ * `GET /control-plane/migrations` — where every database this Worker binds stands.
+ *
+ * Asked of the Worker because the Worker *is* the deployed build. `pithy doctor` reads the project on disk,
+ * which is what the operator has and not necessarily what is deployed.
+ */
+export const ControlPlaneMigrationsResponse = z
+  .object({
+    environment: z.string().describe("The environment this Worker answers for."),
+    databases: z
+      .array(MigrationDatabaseView)
+      .describe("One entry per database this Worker binds, sorted by database name. One unreadable costs only itself."),
+  })
+  .describe("What is applied, pending and undeclared in each bound database, and which run put it there.");
+export type ControlPlaneMigrationsResponse = z.output<typeof ControlPlaneMigrationsResponse>;

package/src/controlPlane/http/routes.ts

@@ -6,18 +6,20 @@ import type { PithyHonoEnv } from "../../capability/capability";
 import { describeRoute } from "../../http/routeSpec";
 import { validate } from "../../http/validation";
 import { type AdminRoute, ControlPlaneManifest } from "../discovery/adminRoute";
-import { ANY_VERIFIED_CALLER, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE } from "../scope/scope";
+import { ANY_VERIFIED_CALLER, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, MIGRATIONS_READ_SCOPE } from "../scope/scope";
 import { requireControlPlane } from "./guard";
 import {
   type ControlPlaneHandlerDeps,
   expireKeyHandler,
   listKeysHandler,
   manifestHandler,
+  migrationsHandler,
   pingHandler,
   registerKeyHandler,
 } from "./handlers";
 import {
   ControlPlaneKeysResponse,
+  ControlPlaneMigrationsResponse,
   ControlPlanePingResponse,
   ExpireKeyResponse,
   RegisterKeyResponse,
@@ -32,6 +34,7 @@ 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/migrations            → where each database stands   (migrations:read)
  *
  * 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.
@@ -90,6 +93,13 @@ export function controlPlaneRouteDescriptors(basePath: string): AdminRoute[] {
       scope: KEYS_ROTATE_SCOPE,
       summary: "Retire a superseded key. Must be signed with the successor it names as proven.",
     },
+    {
+      method: "GET",
+      path: `${basePath}/migrations`,
+      scope: MIGRATIONS_READ_SCOPE,
+      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.",
+    },
   ];
 }
 
@@ -160,4 +170,18 @@ export function registerControlPlaneRoutes(
     validate("json", ExpireKeyRequest),
     (c) => expireKeyHandler(deps)(c, c.req.valid("param"), c.req.valid("json")),
   );
+
+  app.get(
+    `${basePath}/migrations`,
+    describeRoute({
+      summary: "Report where each database this Worker binds stands.",
+      description:
+        "Applied, pending and undeclared migrations per database, each naming its namespace, and the last group with whether it is still reversible. Undeclared is relative to this Worker: a database shared with another Worker lists that Worker's migrations there. Read-only.",
+      verification: "control-plane",
+      scopes: [MIGRATIONS_READ_SCOPE],
+      responses: { 200: ControlPlaneMigrationsResponse },
+    }),
+    requireControlPlane(MIGRATIONS_READ_SCOPE),
+    migrationsHandler(deps),
+  );
 }

package/src/controlPlane/http/verify.ts

@@ -178,6 +178,8 @@ export async function verifyControlPlaneCall(
     grantedScopes: connection.scopes,
     keyId: key.keyId,
     tokenId: claims.jti,
+    // From the adopter's row, never the token: a client does not get to say what kind of client it is.
+    actorKind: connection.actorKind,
   });
 }