@pithy-sh/core 0.10.0 → 0.12.0

package/src/cli/commandCatalog.generated.ts

@@ -161,6 +161,41 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "completion": {
+    "positionals": [
+      {
+        "name": "shell",
+        "required": false,
+        "variadic": false
+      }
+    ],
+    "flags": {
+      "--remove": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--status": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": [
+      {
+        "kind": "atMostOne",
+        "flags": [
+          "--remove",
+          "--status"
+        ]
+      }
+    ]
+  },
   "contract": {
     "positionals": [],
     "flags": {
@@ -251,6 +286,16 @@ export const COMMANDS = {
         "type": "string",
         "required": false,
         "repeatable": false
+      },
+      "--purpose": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--kind": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
       }
     },
     "groups": [
@@ -278,13 +323,22 @@ export const COMMANDS = {
         ],
         "any": false
       },
+      {
+        "kind": "requires",
+        "flag": "--kind",
+        "needs": [
+          "--public-key"
+        ],
+        "any": false
+      },
       {
         "kind": "requires",
         "flag": "--update",
         "needs": [
           "--worker-url",
           "--scope",
-          "--public-key"
+          "--public-key",
+          "--purpose"
         ],
         "any": true
       }
@@ -845,6 +899,10 @@ export const COMMANDS = {
           "invite",
           "testerNudge",
           "passwordChanged",
+          "accountSuspended",
+          "accountReinstated",
+          "deletionScheduled",
+          "deletionComplete",
           "operationalNotice",
           "newsletter",
           "leadCapture",
@@ -1042,11 +1100,6 @@ export const COMMANDS = {
         "required": false,
         "repeatable": false
       },
-      "--api-token": {
-        "type": "string",
-        "required": false,
-        "repeatable": false
-      },
       "--r2-access-key-id": {
         "type": "string",
         "required": false,
@@ -1057,11 +1110,6 @@ export const COMMANDS = {
         "required": false,
         "repeatable": false
       },
-      "--r2-api-token": {
-        "type": "string",
-        "required": false,
-        "repeatable": false
-      },
       "--json": {
         "type": "boolean",
         "required": false,
@@ -1186,6 +1234,33 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "privacy enable": {
+    "positionals": [],
+    "flags": {
+      "--class": {
+        "type": "string",
+        "required": false,
+        "repeatable": true
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
+  "privacy scan": {
+    "positionals": [],
+    "flags": {
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "provision": {
     "positionals": [],
     "flags": {
@@ -1389,6 +1464,33 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "secrets retire-version": {
+    "positionals": [
+      {
+        "name": "version",
+        "required": true,
+        "variadic": false
+      }
+    ],
+    "flags": {
+      "--env": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--past-guard": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "secrets rm": {
     "positionals": [
       {
@@ -1447,6 +1549,28 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "secrets tables": {
+    "positionals": [],
+    "flags": {
+      "--env": {
+        "type": "string",
+        "required": false,
+        "repeatable": false,
+        "default": "dev"
+      },
+      "--worker": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "secrets update": {
     "positionals": [
       {
@@ -1547,6 +1671,27 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "setup": {
+    "positionals": [],
+    "flags": {
+      "--skip-install": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--dry-run": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "storage deprovision": {
     "positionals": [],
     "flags": {
@@ -1586,11 +1731,6 @@ export const COMMANDS = {
         "required": false,
         "repeatable": false
       },
-      "--api-token": {
-        "type": "string",
-        "required": false,
-        "repeatable": false
-      },
       "--r2-access-key-id": {
         "type": "string",
         "required": false,
@@ -1986,6 +2126,34 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "token forget": {
+    "positionals": [
+      {
+        "name": "profile",
+        "required": true,
+        "variadic": false
+      }
+    ],
+    "flags": {
+      "--env": {
+        "type": "string",
+        "required": false,
+        "repeatable": false,
+        "default": "dev"
+      },
+      "--force": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "token list": {
     "positionals": [],
     "flags": {
@@ -2046,7 +2214,12 @@ export const COMMANDS = {
           "vectorize:write",
           "ai:read",
           "zone:read",
-          "routes:write"
+          "routes:write",
+          "analytics:read",
+          "images:write",
+          "stream:write",
+          "queues:write",
+          "artifacts:write"
         ]
       },
       "--json": {
@@ -2123,7 +2296,12 @@ export const COMMANDS = {
           "vectorize:write",
           "ai:read",
           "zone:read",
-          "routes:write"
+          "routes:write",
+          "analytics:read",
+          "images:write",
+          "stream:write",
+          "queues:write",
+          "artifacts:write"
         ]
       },
       "--keep-previous": {
@@ -2416,6 +2594,32 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "worker bind": {
+    "positionals": [],
+    "flags": {
+      "--from": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--to": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--binding": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "worker list": {
     "positionals": [],
     "flags": {
@@ -2447,17 +2651,27 @@ export const COMMANDS = {
   "worker rename": {
     "positionals": [
       {
-        "name": "from",
-        "required": true,
+        "name": "old",
+        "required": false,
         "variadic": false
       },
       {
-        "name": "to",
-        "required": true,
+        "name": "new",
+        "required": false,
         "variadic": false
       }
     ],
     "flags": {
+      "--from": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--to": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
       "--force": {
         "type": "boolean",
         "required": false,
@@ -2496,6 +2710,40 @@ export const COMMANDS = {
       }
     },
     "groups": []
+  },
+  "worker unbind": {
+    "positionals": [],
+    "flags": {
+      "--from": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--to": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--binding": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": [
+      {
+        "kind": "exactlyOne",
+        "flags": [
+          "--to",
+          "--binding"
+        ]
+      }
+    ]
   }
 } as const;
 
@@ -2521,6 +2769,7 @@ export const GROUPS = [
   "feature",
   "media",
   "payments",
+  "privacy",
   "secrets",
   "storage",
   "support",

package/src/cli/commandFacts.ts

@@ -62,6 +62,7 @@ export const WORKER_NARROWS = [
   "env",
   "init",
   "migrate",
+  "secrets tables",
   "seed",
   "support deprovision",
   "upgrade",
@@ -104,6 +105,7 @@ export const DESTRUCTIVE_COMMANDS = {
   "media deprovision": "the media Worker, and with --storage its bucket",
   remove: "a capability's wiring",
   "secrets deprovision": "the secrets manager, and with --keys the store's keys",
+  "secrets retire-version": "a field-key version, and every ciphertext still sealed under it",
   "secrets rm": "a stored secret",
   "storage deprovision": "the storage Worker, and with --storage its bucket",
   "support deprovision": "the support Workers, and with --storage its attachments",

package/src/controlPlane/capability.ts

@@ -7,17 +7,26 @@ import type { BindingSpecInput } from "../capability/bindings";
 import { type Capability, defineCapability, type PithyHonoEnv } from "../capability/capability";
 import type { DatabaseSpecMap } from "../data/databases";
 import type { KvNamespaceSpecMap, KvRegistry } from "../kv/namespaces";
+import { readRetirement } from "../privacy/fieldRotation";
+import { lazyPrivacyInventory } from "../privacy/inventory";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "../version.generated";
 import { ENVIRONMENT_VAR } from "../worker/identity";
 import { ControlPlaneConfig, type ControlPlaneConfigInput } from "./config/config";
 import { ControlPlaneConnection } from "./data/connection";
 import { CONTROL_PLANE_CONNECTIONS_TABLE, type ControlPlaneDatabase, controlPlaneTables } from "./data/tables";
 import type { CapabilityDeclaration } from "./discovery/adminRoute";
-import { type CapabilityHealthSource, capabilityHealthSources } from "./discovery/health";
+import { type CapabilityHealthSource, capabilityHealthSources, defineCapabilityHealth } from "./discovery/health";
 import { createControlPlaneVerifier } from "./http/guard";
 import { controlPlaneRouteDescriptors, registerControlPlaneRoutes } from "./http/routes";
+import {
+  type ComposedMigrationDatabase,
+  composeMigrationDatabases,
+  MIGRATION_HEALTH_KEYS,
+  readMigrationHealth,
+} from "./migrationState/migrationState";
 import { controlplane_0001_init } from "./migrations/0001_init";
 import { controlplane_0002_management_origin } from "./migrations/0002_management_origin";
+import { controlplane_0003_connection_principal } from "./migrations/0003_connection_principal";
 import { d1ReplayGuard } from "./replay/d1Guard";
 import type { ReplayGuard } from "./replay/guard";
 import {
@@ -79,6 +88,7 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
   const migrations: Record<string, Migration> = {
     "0001_init": controlplane_0001_init,
     "0002_management_origin": controlplane_0002_management_origin,
+    "0003_connection_principal": controlplane_0003_connection_principal,
   };
   const requiredBindings: BindingSpecInput[] = [
     // The app database — the connections table lives here, beside auth's and audit's. Not the secrets
@@ -132,6 +142,18 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
   // assembly, because an adopter is never offered such a scope and the number could never be granted.
   let health: ReadonlyMap<string, CapabilityHealthSource> = new Map();
 
+  // Every database this Worker binds and what this build declares for it (#729), composed by the same hook
+  // through `collectMigrationSets` — the function `pithy migrate` uses, so the route and `pithy doctor`
+  // compose the same way. The inputs differ on a D1 two Workers share: the CLI merges every co-bound
+  // Worker's sets and this Worker holds only its own, so `pending` and `undeclared` can differ there.
+  let migrationDatabases: readonly ComposedMigrationDatabase[] = [];
+
+  // Every capability this Worker composed, kept so the privacy inventory can walk their storage schemas
+  // (#132) — lazily, on the first control-plane read, and once for the isolate. Capturing the list costs
+  // nothing; walking it is deferred, so a Worker whose control plane is never called never walks.
+  let composedCapabilities: readonly Capability[] = [];
+  const privacy = lazyPrivacyInventory(() => composedCapabilities);
+
   const capability = defineCapability({
     name: "controlplane",
     // `@pithy-sh/core`'s version, stamped by `scripts/stampVersions.ts` — a Worker cannot read its own
@@ -164,6 +186,14 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
     // The seam describes itself too. Built from the same resolved `basePath` the routes mount on, so a
     // moved mount point is reported rather than becoming a lie a client believes.
     adminRoutes: controlPlaneRouteDescriptors(config.basePath),
+    // Two counts on the seam's own manifest entry, so a client sees *this environment is behind* on the read
+    // it already makes and calls the route only to see what. Behind `migrations:read`, which the route above
+    // requires — a connection without it gets no number rather than a zero. A database that cannot be read
+    // fails the producer, and the seam reports the summary unavailable rather than a partial total.
+    health: defineCapabilityHealth({
+      keys: MIGRATION_HEALTH_KEYS,
+      read: (c) => readMigrationHealth(c.env as Record<string, unknown>, migrationDatabases),
+    }),
     compose: ({ capabilities }) => {
       // Every capability, including those exposing nothing. A client rendering a capability it cannot
       // act on is useful; a client that cannot tell "no admin surface" from "not installed" is not.
@@ -186,6 +216,8 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
         config: { ...(cap.manifestConfig?.values ?? {}) },
       }));
       health = capabilityHealthSources(capabilities);
+      migrationDatabases = composeMigrationDatabases(capabilities);
+      composedCapabilities = [...capabilities];
     },
     middleware: [
       (app) => {
@@ -228,6 +260,9 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
         database,
         composedCapabilities: () => composed,
         composedHealth: () => health,
+        composedMigrations: () => migrationDatabases,
+        privacyInventory: privacy,
+        retirement: (env) => readRetirement(env, composedCapabilities),
         now,
       });
     },

package/src/controlPlane/context.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { ControlPlaneActorKind } from "./data/connection";
 import { ControlPlaneScope } from "./scope/scope";
 
 /**
@@ -56,6 +57,9 @@ export const ControlPlaneContext = z
     tokenId: z
       .string()
       .describe("The token's `jti`, already claimed in the replay set. Recorded to tie one audit event to one call."),
+    actorKind: ControlPlaneActorKind.nullable().describe(
+      "What kind of client the connection is for — `agent`, `dashboard` or `script` — read from the adopter's own row, never from the token. The gate stamps it onto every control-plane audit row this call writes. Null for a connection registered before the kind was recorded (#721).",
+    ),
   })
   .describe(
     "The verified control-plane caller for one request. Never an AuthContext: a management client is not a user of the adopter's app.",

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/discovery/adminRoute.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { PrivacyPosture } from "../../privacy/posture";
 import { ControlPlaneScope } from "../scope/scope";
 import { ManifestConfigKey, ManifestConfigValues } from "./configuration";
 import { CapabilityHealthReport, HealthSummary, HealthSummaryKey, healthReport, healthWire } from "./healthSummary";
@@ -246,6 +247,16 @@ export const ControlPlaneManifest = z
       .describe(
         "The Cloudflare version id of the build answering this call, from the `CF_VERSION_METADATA` binding, or null where the binding is absent. Opaque and per-deploy: it identifies which build is running, never which features it has. Null is honest — a Worker scaffolded before the binding was declared genuinely cannot say.",
       ),
+    versionCreatedAt: z.iso
+      .datetime()
+      .nullable()
+      .optional()
+      .describe(
+        "When the version answering this call was uploaded, ISO-8601, from the same `CF_VERSION_METADATA` binding as `version` — or null where the binding is absent. The id alone cannot tell a deploy from a rollback: a rollback reactivates an existing version, so the id returns to one already seen while this moves backwards. Relayed, never interpreted. Absent from a Worker older than #132.",
+      ),
+    privacy: PrivacyPosture.optional().describe(
+      "What this project declares about privacy and what its running code holds: classes and counts, never field names (`GET /control-plane/privacy` has those, behind `privacy:read`). Present on every Worker from #132, `declared` explicitly empty when nothing was declared; absent from an older Worker.",
+    ),
     capabilities: z
       .array(CapabilityDescriptor)
       .describe(