@pithy-sh/core 0.9.0 → 0.11.0

package/src/capability/capability.ts

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: MIT
 
 import type { ExecutionContext, ForwardableEmailMessage } from "@cloudflare/workers-types";
-import type { Hono } from "hono";
+import type { Hono, MiddlewareHandler } from "hono";
 import type { z } from "zod";
+import type { ActingOrganizationResolver } from "../access/acting";
 import type { AuditEmit } from "../audit/recorder";
 import type { ControlPlaneContext } from "../controlPlane/context";
 import type { AdminRoute } from "../controlPlane/discovery/adminRoute";
@@ -14,6 +15,7 @@ import type { DatabaseSpecMap } from "../data/databases";
 import type { EntitlementResolver } from "../entitlement/entitlement";
 import type { AuthContext } from "../http/authContext";
 import type { SameOriginGate } from "../http/sameOrigin";
+import type { SocketChannel } from "../http/socket";
 import type { LocaleCatalogs } from "../i18n/catalog";
 import type { LocaleContext } from "../i18n/locale";
 import type { Translator } from "../i18n/translator";
@@ -30,6 +32,19 @@ import type { CapabilitySettings } from "./settings";
 export interface PithyVars {
   /** The authenticated identity, populated by `@pithy-sh/auth`; `null` until a strategy sets it. */
   auth: AuthContext | null;
+  /**
+   * Which organization this request acts for, and what the caller's role there allows — a resolver,
+   * populated by `@pithy-sh/organization`'s middleware. With no organization capability composed it is
+   * {@link import("../access/acting").noActingOrganization}, which answers `null`: nothing is in force,
+   * every record a request writes carries a null organization, and every rule that admits by organization
+   * admits nobody.
+   *
+   * **A seam beside {@link auth}, never a field on it.** `auth` says who is signed in; this says what they
+   * may do *here*, and a capability that gates on it — media, storage — must not import the capability
+   * that computes it. Lazy, because resolving it is a D1 read most requests never need; read it with
+   * `await c.var.actingOrganization()`, or through `accessCaller` in `access/access.ts`.
+   */
+  actingOrganization: ActingOrganizationResolver;
   /**
    * The resolved request locale, populated by `@pithy-sh/i18n`'s middleware; `null` in a Worker that
    * does not compose it — which is what "nothing was negotiated" looks like, as distinct from "the
@@ -131,6 +146,12 @@ export type PithyHonoEnv = { Bindings: Record<string, unknown>; Variables: Pithy
 
 export type PithyMiddleware = (app: Hono<PithyHonoEnv>) => void;
 
+/**
+ * One readiness guard: a handler that refuses because **this Worker** is in a bad state. See
+ * {@link Capability.readiness} for where it runs and where it does not.
+ */
+export type PithyReadinessGuard = MiddlewareHandler<PithyHonoEnv>;
+
 /**
  * The structural seam for one capability's secret-registry slice — secret name → its declaration.
  * Core carries it on the {@link Capability} contract so a capability can declare which secrets it
@@ -229,29 +250,18 @@ export type SecretBranchSeam = Record<string, readonly string[]>;
 export type InapplicableSecretSeam = Record<string, string>;
 
 /**
- * The structural seam for one capability's token-profile slice — profile name → the scoped CF API
- * token that capability's code needs. Declared next to the code that uses it (alongside
- * {@link Capability.secretRegistry}), so a capability owns its token's least-privilege scope and where
- * the minted value lands. Core carries only the structural axes (never interpreted here); the concrete
- * `TokenProfile`, the permission catalog, `defineTokenProfile`, and the mint engine live in
- * `@pithy-sh/cloudflare`/the CLI. `pithy token` aggregates every capability's slice into one registry.
+ * One route a capability gates on an `AuthContext` scope — see {@link Capability.scopeGates}.
+ *
+ * Descriptive, never behavioral: the gate itself is the capability's own middleware, and this is what a
+ * diagnostic reads to name it. `route` is the method and the mounted path, as the route table writes them.
  */
-export interface TokenProfileSeam {
-  /** The CF permissions the token grants, as short catalog keys (`d1:read`, `secrets:write`). */
-  readonly permissions: readonly string[];
-  /** The resource scope: `"account"` (the whole account, the default) or an explicit CF resource map. */
-  readonly resources?: "account" | Record<string, string>;
-  /** The secret-registry name the minted value is stored under — its backend decides the destination. */
-  readonly secret?: string;
-  /** A built-in destination override (`dev-vars` | `ephemeral` | `secrets-store`) for a tooling profile. */
-  readonly defaultStore?: string;
-  /** Why the profile exists / what consumes it — surfaced in `pithy token` help and docs. */
-  readonly description?: string;
+export interface ScopeGate {
+  /** The scope the gate requires, as the resolved config names it — `leaderboard:submit`. */
+  readonly scope: string;
+  /** The method and mounted path it guards, `POST /leaderboard/:board`. */
+  readonly route: string;
 }
 
-/** A capability's token-profile slice: profile name → {@link TokenProfileSeam}. */
-export type TokenProfileSeamMap = Record<string, TokenProfileSeam>;
-
 /**
  * One thing an **adopter** plugged into a capability — the capability's own name for something the kit
  * did not ship and cannot enumerate. `@pithy-sh/auth` declares one per additional Better Auth plugin
@@ -378,13 +388,6 @@ export interface Capability<
    * whenever it is composed declares nothing, which is the ordinary case.
    */
   inapplicableSecrets?: InapplicableSecretSeam;
-  /**
-   * The scoped CF API tokens this capability's code needs, as a token-profile slice (profile name →
-   * {@link TokenProfileSeam}). Additive and optional, and declared next to {@link Capability.secretRegistry}
-   * — the value of a minted token lands in the secret the profile names. `pithy token` aggregates every
-   * capability's slice with the built-in tooling profiles into one registry.
-   */
-  tokenProfiles?: TokenProfileSeamMap;
   /**
    * Extra CF permissions this capability needs the **CI system token** to hold, as short catalog keys
    * (e.g. `email:routing` for email provisioning, `kv:write` for a module that seeds KV in CI). They
@@ -392,6 +395,20 @@ export interface Capability<
    * extends what CI can do without the adopter hand-editing token scopes. Additive and optional.
    */
   ciPermissions?: readonly string[];
+  /**
+   * The CF permissions this capability's **deployed Workers** call Cloudflare with, as short catalog keys
+   * (`secrets:write`, `images:write`, `analytics:read`). The runtime counterpart of {@link ciPermissions}.
+   *
+   * **A deployed application holds one Cloudflare API token, and this is the only way into it (#728).**
+   * Every composed capability's keys union into the project-level `runtime` profile, minted per
+   * environment into the Secrets Store and read by every Worker of that environment through one binding,
+   * the way every capability's `ciPermissions` union into the one `ci-system` token. A capability cannot
+   * declare a token of its own. A project whose composition declares none mints no runtime token.
+   *
+   * Build it from the resolved config, as `secretRegistry` is built: a capability configured to call
+   * nothing on Cloudflare declares nothing, and adds nothing to the token. Additive and optional.
+   */
+  runtimePermissions?: readonly string[];
   /**
    * The admin routes this capability contributes behind the `control-plane` strategy, described well
    * enough for a management client to call them — full mounted path, required scope, and a one-line
@@ -532,8 +549,36 @@ export interface Capability<
   boot?: (context: CapabilityComposeContext) => void;
   /** Mounts a Hono sub-router. */
   routes?: (app: Hono<PithyHonoEnv>) => void;
-  /** Composable middleware (e.g. turnstile(), requireAuth()). */
+  /**
+   * The WebSockets this capability serves, described for the AsyncAPI contract (`../http/socket.ts`). Built
+   * from the resolved config, like `adminRoutes`: the paths it mounted, and the schemas its frames are
+   * parsed with. A capability with no socket leaves it unset.
+   */
+  sockets?: readonly SocketChannel[];
+  /**
+   * Composable middleware (e.g. turnstile(), requireAuth()). Runs on every request, the control-plane
+   * surface included. A refusal that protects a route — a rate limit, authentication, a CSRF check —
+   * belongs here. A refusal because the Worker itself is broken belongs in {@link Capability.readiness}.
+   */
   middleware?: PithyMiddleware[];
+  /**
+   * Guards that refuse because **this Worker is misconfigured or unprovisioned** — `@pithy-sh/vector`'s
+   * `provisionGuard`, when the deployed index disagrees with config. Not for protecting a route: a rate
+   * limit, authentication and a CSRF check refuse a *caller*, and they belong in
+   * {@link Capability.middleware}.
+   *
+   * `createBackend` mounts every readiness guard after every capability's `middleware` and before any
+   * capability's routes, so the verifier, `emit` and every rate limit are already in place. It skips
+   * each guard on the admin surface — every composed capability's `adminRoutes`, the seam's own
+   * included, the set CORS is derived from. The control plane is the diagnostic surface, so it cannot
+   * sit behind the faults it diagnoses. Every other request meets the guard, `GET /health` aside, which
+   * is registered ahead of all of it.
+   *
+   * A handler rather than a registrar like `middleware`, because core decides where it mounts. A guard
+   * that wanted its own path would be deciding the exemption by path shape, which is the thing this
+   * exists to take away from it.
+   */
+  readiness?: PithyReadinessGuard[];
   /**
    * Whether this capability fills the entitlement seam — replaces `c.var.entitlements` with a real
    * resolver. `@pithy-sh/payments` declares it; nothing else does today.
@@ -545,6 +590,27 @@ export interface Capability<
    * flag and say so, which turns a fleet of production 403s into one line at startup.
    */
   providesEntitlements?: boolean;
+  /**
+   * Whether this capability fills `AuthContext.scopes` — whether anything will ever put a string in the
+   * array the scope gates read. `@pithy-sh/auth` declares it when an adopter supplies `resolveScopes`, and
+   * not otherwise (#560).
+   *
+   * The same reason {@link providesEntitlements} exists, one seam over. Every scope gate fails closed, so a
+   * Worker composing `leaderboard` with no resolver is not broken: it refuses every caller on the gated
+   * routes, forever, and the runtime cannot tell that from a caller who simply is not trusted. `pithy doctor`
+   * compares this flag against {@link scopeGates} and says so.
+   */
+  providesScopes?: boolean;
+  /**
+   * The routes this capability gates on an `AuthContext` scope, built from the resolved config — a gate the
+   * config has switched off is not declared. Omit it when nothing is gated, which is the ordinary case.
+   *
+   * **Declared so the CLI can name what will deny.** With no capability composed that
+   * {@link providesScopes}, every route listed here answers 403 to every caller, and `pithy doctor` names
+   * each one. Each capability's route-contract test holds this list to the `scopes` its `describeRoute`s
+   * carry, so the declaration cannot drift from the routes.
+   */
+  scopeGates?: readonly ScopeGate[];
   /**
    * This capability's client-safe projection — the **only** values of its config that may reach a
    * browser bundle. Resolved at build time against a {@link ClientProjectionContext} (the environment),
@@ -592,6 +658,17 @@ export interface Capability<
    * time, and read by `pithy doctor`.
    */
   extensions?: readonly CapabilityExtension[];
+  /**
+   * The role powers this capability's own routes gate on, through the acting-organization seam —
+   * `media:manage`, `storage:manage`. Omit it when a capability asks no power, which is the normal case.
+   *
+   * **Declared so the catalog requirement can be conditional.** `@pithy-sh/organization` refuses a role
+   * catalog in which no role holds a power a composed capability gates on — a route nobody could ever use
+   * — and a project that composes no media must not be refused for not placing `media:manage`. The
+   * organization capability reads this list at compose, across every composed capability, rather than
+   * importing any of them.
+   */
+  powers?: readonly string[];
   /** Bindings this capability needs in the env (normalized — `optional` is always set). */
   requiredBindings: BindingSpec[];
 }

package/src/capability/composition.ts

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { pithyCommandOf } from "../cli/command";
 import { InternalError } from "../error/pithyError";
 import type { Capability } from "./capability";
 
@@ -90,7 +91,7 @@ export function composedCapability<T extends Capability>(name: string, is: (capa
       // missing-peer check names it: a capability name is a published part of this framework, and a
       // wiring fault that will not say which wire is a fault nobody can act on.
       message: `The "${name}" capability is not composed, so this job could not run.`,
-      action: `Add ${name}(...) to createBackend's capabilities (run \`pithy add ${name}\`).`,
+      action: `Add ${name}(...) to createBackend's capabilities (run \`${pithyCommandOf("add", { args: [name], flags: { "--with-prerequisites": true } }, { runtime: true })}\`).`,
       detail: `no composed capability named "${name}" carrying its seams was found.`,
     });
   }

package/src/capability/settings.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { InternalError } from "../error/pithyError";
 import type { HostEnvReport } from "../workflow/hostEnv";
 import { hostEnvProviderSentence } from "../workflow/hostEnv";
 
@@ -69,6 +70,13 @@ export const SettingsFinding = z
       .describe(
         "What resolves it: the `pithy` command, the `pithy.config.ts` key, or the one-time account action. Never optional — a finding nobody can act on is a complaint.",
       ),
+    fix: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "The `pithy` command that resolves it, whole and runnable as written, when one does. Absent when the remedy is an edit or an account action, and from a capability older than the field — `pithy doctor --json` reports either as `fix: null`.",
+      ),
   })
   .describe("One capability setting that does not work, with the action that resolves it.");
 export type SettingsFinding = z.infer<typeof SettingsFinding>;
@@ -90,8 +98,15 @@ export interface SettingsEnvironment {
 export interface SettingsCheckContext {
   /** The root config's `name` — the leading segment of every resource this project provisions. */
   project: string;
-  /** The Worker whose `pithy.config.ts` composed this capability. */
+  /** The Worker whose `pithy.config.ts` composed this capability, by its `wrangler.jsonc` name. */
   worker: string;
+  /**
+   * That Worker's directory under `apps/` — the value `--worker` takes, and the one a refusal lists (#711).
+   *
+   * Not `worker` under another name. A scaffold deploys `apps/api` as `acme-api`, so a command a finding names
+   * for one Worker is written with this.
+   */
+  workerDirectory: string;
   /** Every environment the project declares, in declaration order. */
   environments: readonly SettingsEnvironment[];
 }
@@ -101,8 +116,8 @@ export interface SettingsCheckContext {
  *
  * Closed for the reason `CapabilityHealth` is: handing a capability a raw Cloudflare client would make
  * every capability a place a network call can be invented, and would put `@pithy-sh/cloudflare` in the
- * dependency list of packages that need none of it. Three questions cover what the first checks ask; a
- * fourth lands here, once, when a capability actually needs it.
+ * dependency list of packages that need none of it. A question lands here once a capability actually needs
+ * it, and not before: six cover what the checks ask.
  *
  * Every method may throw. A throw is the account failing to answer, and the runner reports that
  * capability's account tier as unchecked rather than as a pass.
@@ -127,6 +142,47 @@ export interface SettingsAccountReader {
    * created it with, so the check looks where the value went.
    */
   storeEntry(name: string): Promise<boolean>;
+  /**
+   * The ids of the rows in one of the kit's own tables whose column holds one of `values`, in the app
+   * database a Worker binds as `DB` in one deployed environment (#727).
+   *
+   * Asked by media and storage after a project narrows `visibility.allowed`: narrowing never rewrites a
+   * record, so the records left outside the policy have to be *named*, and only the deployed database
+   * holds them. Closed in its own way — the table must be a `pithy_` one and the column an identifier,
+   * both refused otherwise, and the values are bound, never interpolated — so it reads a fact about a
+   * capability's own rows and cannot become a query language.
+   */
+  appRows(request: AppRowsRequest): Promise<readonly string[]>;
+  /**
+   * Whether that environment's **D1 vault** holds a `json` secret that still carries a top-level `field` —
+   * asked of its manager Worker, which opens the value and answers a bit, never the value (#728). `false`
+   * for a secret that is not stored, since it carries nothing.
+   *
+   * Asked by media of `media-storage-credentials`, which held a supplied Cloudflare token until the runtime
+   * token replaced it: the upgrade is finished only once the bundle has been rewritten without it.
+   */
+  vaultSecretField(request: { name: string; environment: string; field: string }): Promise<boolean>;
+  /**
+   * Whether the account holds a Cloudflare API token of exactly this name (#728). The name is the token's,
+   * composed with the namer that minted it — never a pattern, so a check names one credential it can see.
+   *
+   * Asked by secrets of the manager token the runtime token superseded, which nothing revokes for you.
+   */
+  accountToken(name: string): Promise<boolean>;
+}
+
+/** What {@link SettingsAccountReader.appRows} is asked. */
+export interface AppRowsRequest {
+  /** The deployed environment whose app database is read. `dev` is refused: it has no deployed database. */
+  readonly environment: string;
+  /** The Worker's `apps/` directory — whose `wrangler.jsonc` names the database for that environment. */
+  readonly workerDirectory: string;
+  /** The kit table, as it is named in SQL — `pithy_media_assets`. Must carry the `pithy_` prefix. */
+  readonly table: string;
+  /** The column compared, as it is named in SQL — `visibility`. */
+  readonly column: string;
+  /** The values that make a row worth naming. */
+  readonly values: readonly string[];
 }
 
 /** What the account tier is told: everything the local tier gets, plus the account it may ask. */
@@ -135,6 +191,56 @@ export interface SettingsAccountContext extends SettingsCheckContext {
   account: SettingsAccountReader;
 }
 
+/** One environment an account check could not answer for, and why. */
+export interface UnansweredEnvironment {
+  /** The environment id. */
+  readonly environment: string;
+  /** What the account, or the project, said instead of an answer. */
+  readonly cause: unknown;
+}
+
+/**
+ * An account check that answered for some environments and not for others.
+ *
+ * A check that asks per environment must not let one unanswerable environment cost the others their
+ * findings: staging stood up before prod is the ordinary bring-up, and a check that threw on prod's missing
+ * database would throw away what it had already found in staging. So it collects what it can, and throws
+ * this at the end carrying those findings. The runner reports them as findings and the tier as unchecked,
+ * both — a fault and an unanswered question are two facts, and neither hides the other.
+ */
+export class SettingsAccountIncomplete extends InternalError {
+  /** What the environments that did answer were found to have wrong. */
+  readonly findings: readonly SettingsFinding[];
+  /** The environments that did not answer, in the order they were asked. */
+  readonly unanswered: readonly string[];
+
+  constructor(findings: readonly SettingsFinding[], unanswered: readonly UnansweredEnvironment[]) {
+    const reasons = unanswered.map(({ environment, cause }) => `${environment}: ${describeCause(cause)}`).join("; ");
+    super(
+      {
+        message: `The account check could not answer for ${unanswered.map(({ environment }) => environment).join(", ")}.`,
+        detail: reasons,
+      },
+      { cause: unanswered[0]?.cause },
+    );
+    this.findings = findings;
+    this.unanswered = unanswered.map(({ environment }) => environment);
+  }
+}
+
+/** A cause, as one line. */
+function describeCause(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+/**
+ * The findings an account check reached before it threw — none for an ordinary throw, and what it had
+ * collected for a {@link SettingsAccountIncomplete}.
+ */
+export function settingsFindingsBefore(error: unknown): readonly SettingsFinding[] {
+  return error instanceof SettingsAccountIncomplete ? error.findings : [];
+}
+
 /**
  * A capability's settings check, as it hangs off the capability.
  *
@@ -149,6 +255,58 @@ export interface CapabilitySettings {
   account?(context: SettingsAccountContext): Promise<SettingsFinding[]>;
 }
 
+/**
+ * **Two or more checks on one capability, as the one `settings` it declares (#728).** Media names records a
+ * narrowed visibility no longer admits and a bundle still holding a superseded token: two questions, one
+ * capability, one seam.
+ *
+ * Each tier runs every check's, in declaration order. A check that could not answer for some environments
+ * costs those environments and nothing else: the others' findings are kept, and the run ends in one
+ * {@link SettingsAccountIncomplete} carrying every finding and every unanswered environment. A check that
+ * throws outright is unanswered for every environment the context declares.
+ */
+export function allSettings(...checks: readonly CapabilitySettings[]): CapabilitySettings {
+  const accounts = checks.flatMap((check) => (check.account ? [check.account.bind(check)] : []));
+  return {
+    async local(context) {
+      const findings: SettingsFinding[] = [];
+      for (const check of checks) findings.push(...(await check.local(context)));
+      return findings;
+    },
+    ...(accounts.length === 0
+      ? {}
+      : {
+          async account(context) {
+            const findings: SettingsFinding[] = [];
+            const unanswered: UnansweredEnvironment[] = [];
+            for (const account of accounts) {
+              try {
+                findings.push(...(await account(context)));
+              } catch (cause) {
+                findings.push(...settingsFindingsBefore(cause));
+                if (cause instanceof SettingsAccountIncomplete) {
+                  for (const environment of cause.unanswered) {
+                    if (!unanswered.some((entry) => entry.environment === environment)) {
+                      unanswered.push({ environment, cause: cause.cause ?? cause });
+                    }
+                  }
+                  continue;
+                }
+                // With no environment to name, there is nothing the throw could be reported against.
+                if (context.environments.length === 0) throw cause;
+                for (const { name } of context.environments) {
+                  if (!unanswered.some((entry) => entry.environment === name))
+                    unanswered.push({ environment: name, cause });
+                }
+              }
+            }
+            if (unanswered.length > 0) throw new SettingsAccountIncomplete(findings, unanswered);
+            return findings;
+          },
+        }),
+  };
+}
+
 /**
  * Turn a host env's own parse report into findings — the bridge that makes "one schema, two readers" real.
  *
@@ -156,7 +314,7 @@ export interface CapabilitySettings {
  * import("../workflow/hostEnv").checkHostEnv} against its own declaration, and hands the report here. The
  * problem line is Zod's own message and the action line is {@link hostEnvProviderSentence} — the same
  * words the host writes into its log before it refuses to start. Two readers of one declaration, and no
- * second wording to drift.
+ * second wording to drift. A provider that names a command carries it as `fix` too.
  */
 export function hostEnvFindings(report: HostEnvReport<unknown>, environment: string | null): SettingsFinding[] {
   return report.problems.map((problem) => ({
@@ -164,5 +322,8 @@ export function hostEnvFindings(report: HostEnvReport<unknown>, environment: str
     environment,
     problem: problem.reason,
     action: hostEnvProviderSentence(problem.provider),
+    // The provider's own command, where it names one, as the finding's `fix` (#697): the same words the action
+    // line runs, without the sentence around them.
+    ...(problem.provider.command === undefined ? {} : { fix: problem.provider.command }),
   }));
 }