@ultimat3/action 22.10.0 → 22.12.0

package/CLAUDE.md

@@ -52,7 +52,8 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 
 ## Invariants — execution and authz
 
-- Every surface goes through `invoke`: parse input, evaluate policy, handle, parse output. A second
+- Every surface goes through `invoke`: the policy's actor half (`guardBeforeInput`, 403 before the
+  parse), parse input, evaluate policy, handle, parse output. A second
   execution path is the one unforgivable change here.
 - **An explicit `ctx` is INSTALLED, never merely passed** — the ambient context (which
   `@ultimat3/entity`'s tenant guard reads) must be the identity `guard()` decided about.

package/README.md

@@ -211,7 +211,9 @@ export const api = defineApi({
       scopes: MCP_SCOPES,            // scope -> [primitive names]; the map defineAppMcp takes
       resolveToken,                  // the MCP resolver: token -> { actor, scopes } | null
       rateLimit: { limit: 120, windowMs: 60_000 },
-      openapi: 'openapi.v1.json',    // x manifest writes only the cut here; x verify checks it
+      openapi: 'openapi.v1.json',    // x manifest writes only the cut here; x verify checks it —
+                                     // each operation `security: [{ bearer: ['<its scope>'] }]`,
+                                     // the bearer scheme lists every scope (x-ultimate.scopes)
     }],
   },
   // Declaring it (any key) makes openapi.json COMPLETE: info, servers, securitySchemes
@@ -256,8 +258,8 @@ the manifest never carried a tool name and was never wrong about one.
 
 ## One invocation core
 
-`invoke()` is the only execution path: **parse input → evaluate policy → handle →
-parse output**. HTTP, MCP, jobs and direct server calls differ **only** in the
+`invoke()` is the only execution path: **policy's actor half → parse input → evaluate
+policy → handle → parse output**. HTTP, MCP, jobs and direct server calls differ **only** in the
 `surface` they hand to `enforce()` from `@ultimat3/policy`, which selects how a
 denial renders (problem+json / tool error / failed job) — never whether authz runs.
 
@@ -267,11 +269,20 @@ no `.def`. A second authz path cannot be written without deleting that store.
 
 | Stage | Failure |
 |---|---|
+| policy, actor half (`guardBeforeInput`) | `X_UNAUTHENTICATED` / `X_FORBIDDEN` for a caller the policy refuses whatever the input — never a 400 describing the schema of an operation they may not call |
 | parse input | `X_INPUT_INVALID` |
 | evaluate policy | the policy's own code — `X_UNAUTHENTICATED` (401), `X_FORBIDDEN` (403) |
 | handle | whatever the handler throws |
 | parse output | `X_OUTPUT_INVALID` — and fields the schema never declared are dropped |
 
+**Who before what (`As of 2026-09`).** The actor half is the part of the policy that reads no
+input: `can(p)` with no predicate, `allow()`, `deny()`, their combinators, and `can(p, pred)` for
+an actor without `p`. It is decided before the parse — `decideBeforeInput` in `@ultimat3/policy`,
+exact rather than a heuristic — so `can('refund:issue')` answers a customer's `{}` with 403, and a
+staff caller's `{}` with the 400 naming each missing field. A predicate over `input` or `row` still
+runs after the parse, on the parsed value. Same on HTTP, MCP (including the `invalid-args`
+path) and `.as()`/jobs. An audited action's denied attempt still records the parsed input.
+
 `cache: { invalidates }` fans out **after** the handler commits, so it never fails it: a
 fan-out that refuses — an undeclared tag, `X_CACHE_TAG_UNKNOWN` — is one
 `action.invalidate.failed` log line and the entries expire by TTL. A replayed idempotent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "22.10.0",
+  "version": "22.12.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
@@ -34,11 +34,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.10.0",
-    "@ultimat3/core": "22.10.0",
-    "@ultimat3/entity": "22.10.0",
-    "@ultimat3/http": "22.10.0",
-    "@ultimat3/policy": "22.10.0",
-    "@ultimat3/schema": "22.10.0"
+    "@ultimat3/cache": "22.12.0",
+    "@ultimat3/core": "22.12.0",
+    "@ultimat3/entity": "22.12.0",
+    "@ultimat3/http": "22.12.0",
+    "@ultimat3/policy": "22.12.0",
+    "@ultimat3/schema": "22.12.0"
   }
 }

package/src/contract-test.ts

@@ -12,6 +12,7 @@ import { actionName, invoke } from './invoke';
 import { derivePath } from './naming';
 import { buildOpenApi } from './openapi';
 import { describeSampleGap, sampleGaps, sampleInput } from './sample-input';
+import { validateInput } from './validate';
 
 export interface ContractTest {
   readonly name: string;
@@ -47,9 +48,12 @@ export function contractTestsFor(
   return [
     {
       name: `${name}: input schema rejects garbage`,
+      // The action's own parser — the one `invoke` runs — and never `invoke` itself: the policy's
+      // actor half is decided BEFORE the parse, so an anonymous caller of a guarded action is
+      // refused 401 without the schema ever seeing the garbage. The claim is about `input:`.
       run: async () => {
         await expectThrow(
-          () => invoke(target, garbage, { ctx, surface: 'http' }),
+          () => validateInput(target.input, garbage, name),
           'X_INPUT_INVALID',
           `${name} accepted the value this assertion sent as garbage`,
           `tighten \`input:\` in the ${name} definition`,
@@ -146,9 +150,10 @@ async function expectDenied(
     // drift error would hide the line that threw behind a fix that does not apply.
     if (!isUltimateError(error)) throw error;
     if (error instanceof ActionDeniedError) return;
-    // `invoke` runs parse input → row → policy → handle → parse output, and every stage lands
-    // here identically. Only `X_INPUT_INVALID` is attributable: it is what `validateInput`
-    // raises before `guard()` is reached, and `input:` is the knob that answers it. Any other
+    // `invoke` runs the policy's actor half → parse input → row → policy → handle → parse
+    // output, and every stage lands here identically. Only `X_INPUT_INVALID` is attributable: it
+    // is what `validateInput` raises before `guard()` is reached (for a policy whose actor half
+    // could not decide), and `input:` is the knob that answers it. Any other
     // code — `X_TENANCY_UNSCOPED` from a `row:` loader, `X_DB_CONFLICT` from a handler,
     // `X_OUTPUT_INVALID` from the parse after it — keeps its own code and its own fix rather
     // than being retold as an input problem with a fix that changes nothing.
@@ -184,11 +189,6 @@ async function expectThrow(
   } catch (error) {
     if (!isUltimateError(error)) throw error;
     if (error.code === code) return;
-    // `X_AUDIT_SINK_MISSING` is the one refusal `invoke` raises BEFORE the input parse, so
-    // "the schema accepted garbage" is a false statement about it and `input:` is not what
-    // answers it. It keeps its own code and its own runnable fix — the same rule `expectDenied`
-    // follows for every code it cannot attribute to `input:`.
-    if (error.code === 'X_AUDIT_SINK_MISSING') throw error;
     report();
     throw new ContractDriftError(`${cause} (got ${error.code}, expected ${code})`, fix);
   }

package/src/index.ts

@@ -248,6 +248,7 @@ export {
   actorOf,
   admitsAnonymous,
   guard,
+  guardBeforeInput,
   policyCapability,
   policyPermissions,
 } from './policy-gate';

package/src/invoke.ts

@@ -34,8 +34,8 @@ import { bustAfterCommit } from './cache-gate';
 import { ActionForeignError, ActionUnregisteredError } from './errors';
 import { getIdempotencyStore, withIdempotency } from './idempotency';
 import { idempotencyKeyFor } from './idempotency-key';
-import { actorOf, guard } from './policy-gate';
-import { validateInput, validateOutput } from './validate';
+import { actorOf, guard, guardBeforeInput } from './policy-gate';
+import { parsedOrNothing, validateInput, validateOutput } from './validate';
 
 /**
  * Private on purpose. `@ultimat3/action` exports no way to read this back, which
@@ -207,7 +207,7 @@ async function execute(
   });
 }
 
-/** The invocation itself, unwrapped: parse, load the row, guard, run, parse, bust. */
+/** The invocation itself, unwrapped: gate, parse, load the row, guard, run, parse, bust. */
 async function perform(
   def: AnyActionDef,
   name: string,
@@ -216,6 +216,18 @@ async function perform(
   options: InvokeOptions,
   trace: InvokeTrace,
 ): Promise<unknown> {
+  const surface = options.surface ?? 'server';
+  // Who is asking is decided before what they sent is read: a caller the policy refuses whatever
+  // the input is gets 403/401 here, not a 400 whose issues describe this action's input schema.
+  // Only the actor half runs — a predicate over `input` or `row` waits for `guard` below.
+  try {
+    guardBeforeInput(def.policy, { actor: actorOf(ctx), ctx, action: name }, surface);
+  } catch (denial) {
+    // The audit record still names what was attempted — the denial is already decided, so parsing
+    // now tells the CALLER nothing, and an unparseable payload is a record with no input.
+    if (def.audit === true) trace.input = await parsedOrNothing(def.input, raw);
+    throw denial;
+  }
   const input = await validateInput(def.input, raw, name);
   trace.input = input;
   // The one place a row-level rule gets its row. Once per invocation, never per row:
@@ -224,11 +236,7 @@ async function perform(
   // action with no loader hands the rule `null` — unchanged, and never a silent allow,
   // because a rule that reads `row` has to decide what `null` means.
   const row = def.row === undefined ? null : ((await def.row({ input, ctx })) ?? null);
-  guard(
-    def.policy,
-    { actor: actorOf(ctx), input, row, ctx, action: name },
-    options.surface ?? 'server',
-  );
+  guard(def.policy, { actor: actorOf(ctx), input, row, ctx, action: name }, surface);
 
   // Output parsing sits inside `run` so a replayed idempotent response is the parsed value too —
   // one shape on the wire, first call and every retry. No span of its own: `execute` above holds

package/src/openapi-complete.ts

@@ -69,6 +69,11 @@ function routeIndex(routes: readonly Route[]): ReadonlyMap<string, Route> {
 
 interface Refusals {
   readonly scheme: string;
+  /**
+   * The security requirement's list: empty on the cookie document, the ONE scope a mounted
+   * operation needs on a bearer mount's (OpenAPI 3.1 allows role names for a non-OAuth scheme).
+   */
+  readonly scopes: readonly string[];
   /** The mount's own allowance applies to every operation, whatever the route declares. */
   readonly everyOpLimited: boolean;
   readonly unauthorizedHeaders?: Record<string, unknown>;
@@ -105,7 +110,7 @@ function completeOperation(operation: Operation, route: Route | undefined, refus
   return {
     ...operation,
     responses,
-    ...(authenticated ? { security: [{ [refusals.scheme]: [] }] } : {}),
+    ...(authenticated ? { security: [{ [refusals.scheme]: [...refusals.scopes] }] } : {}),
   };
 }
 
@@ -162,6 +167,7 @@ export function completeOpenApi(
   const paths = mapOperations(document.paths, (path, method, operation) =>
     completeOperation(operation, index.get(`${method} ${path}`), {
       scheme: COOKIE_SCHEME,
+      scopes: [],
       everyOpLimited: false,
     }),
   );
@@ -187,7 +193,8 @@ export function completeOpenApi(
 /**
  * A bearer mount's own document: only the operations its `scopes` name, re-keyed to the mounted
  * paths, each `bearer`-secured with 401, 404-when-hidden and 429, and only the schemas those
- * operations reference. `x-ultimate.scope` names the scope a token needs for each.
+ * operations reference. Each operation's `security` is `[{ bearer: ['<scope>'] }]` — the scope a
+ * token needs, also in `x-ultimate.scope` — and the scheme documents the whole scope map.
  */
 export function mountOpenApi(
   document: OpenApiDocument,
@@ -205,6 +212,9 @@ export function mountOpenApi(
   // A `Map`: the key is a route path, and a plain object keyed by one would read `__proto__`.
   const mountedItems = new Map<string, Record<string, unknown>>();
   const tags = new Set<string>();
+  // Scope → the operations in THIS document it unlocks: what the scheme documents, so it can never
+  // name an operation the document does not carry.
+  const unlocks = new Map<string, string[]>();
   const byRoute = [...input.routes].sort((a, b) =>
     `${a.path} ${a.method}` < `${b.path} ${b.method}` ? -1 : 1,
   );
@@ -222,6 +232,7 @@ export function mountOpenApi(
       { ...route, meta: { ...route.meta, auth: 'required' } },
       {
         scheme: BEARER_SCHEME,
+        scopes: [scope],
         everyOpLimited: mount.rateLimit !== undefined,
         unauthorizedHeaders: {
           'WWW-Authenticate': { description: 'Bearer', schema: { type: 'string' } },
@@ -234,6 +245,7 @@ export function mountOpenApi(
     };
     const extensions = (completed['x-ultimate'] as Record<string, unknown> | undefined) ?? {};
     for (const tag of (completed['tags'] as readonly string[] | undefined) ?? []) tags.add(tag);
+    unlocks.set(scope, [...(unlocks.get(scope) ?? []), route.meta.name]);
     const mounted = mountedPath(mount.prefix, route.path);
     mountedItems.set(mounted, {
       ...mountedItems.get(mounted),
@@ -249,12 +261,32 @@ export function mountOpenApi(
     paths,
     components: {
       schemas,
-      securitySchemes: { [BEARER_SCHEME]: BEARER_SECURITY_SCHEME },
+      securitySchemes: { [BEARER_SCHEME]: scopedBearerScheme(unlocks) },
     },
     tags: [...tags].sort().map((name) => ({ name })),
   };
 }
 
+/**
+ * The mount's `bearer` scheme with its scopes stated. An `http` scheme has no `scopes` field (that
+ * is OAuth's `flows`), so they are in the description for a reader and in `x-ultimate.scopes` —
+ * scope → operation names, both sorted — for a generator; each operation's requirement names one.
+ */
+function scopedBearerScheme(unlocks: ReadonlyMap<string, readonly string[]>) {
+  const scopes = [...unlocks.keys()].sort();
+  const table = scopes.map((scope) => [scope, [...(unlocks.get(scope) ?? [])].sort()] as const);
+  const lines = table.map(([scope, names]) => `- \`${scope}\`: ${names.join(', ')}`);
+  return {
+    ...BEARER_SECURITY_SCHEME,
+    description: [
+      BEARER_SECURITY_SCHEME.description,
+      'Each operation lists the one scope a token needs in its security requirement; a token without it is answered 404.',
+      ...(lines.length === 0 ? [] : ['', 'Scopes:', ...lines]),
+    ].join('\n'),
+    'x-ultimate': { scopes: Object.fromEntries(table) },
+  };
+}
+
 /** Every component schema `root` reaches through `$ref`, transitively. */
 function referencedSchemas(
   root: unknown,

package/src/policy-gate.ts

@@ -9,6 +9,7 @@ import { assertNever, isAnonymous } from '@ultimat3/core';
 import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
 import {
   enforce,
+  enforceBeforeInput,
   policyPermissions as flattenedPermissions,
   admitsAnonymous as policyAdmitsAnonymous,
 } from '@ultimat3/policy';
@@ -56,6 +57,25 @@ export function guard(policy: ActionPolicy, subject: PolicySubject, surface: Sur
   if (denial !== undefined) throw new ActionDeniedError(subject.action, denial);
 }
 
+/**
+ * The actor-only half of `guard`, run BEFORE the input is parsed: a caller the policy refuses
+ * whatever they send gets the 403 (or 401) here, and never the 400 whose issue list describes
+ * the input schema of an operation they may not call. Undecided — a predicate that reads the input
+ * or the row — passes, and `guard` decides after the parse exactly as before. Same denial class,
+ * same code, same surface rendering as `guard`'s.
+ */
+export function guardBeforeInput(
+  policy: ActionPolicy,
+  subject: Omit<PolicySubject, 'input' | 'row'>,
+  surface: Surface,
+): void {
+  const denial = enforceBeforeInput(policySurface(surface), policy, {
+    actor: subject.actor,
+    ctx: subject.ctx,
+  });
+  if (denial !== undefined) throw new ActionDeniedError(subject.action, denial);
+}
+
 /** A direct server call is the job surface: no request, no response to shape. */
 function policySurface(surface: Surface): PolicySurface {
   switch (surface) {

package/src/validate.ts

@@ -31,6 +31,16 @@ export async function validateInput<S extends StandardSchemaV1>(
   return result.value;
 }
 
+/**
+ * The parse without the refusal: the value, or `undefined` when it does not parse. Only for a
+ * record of an attempt already refused on other grounds (`invoke`'s audit of a before-input
+ * denial) — never on a path that goes on to run anything.
+ */
+export async function parsedOrNothing(schema: StandardSchemaV1, raw: unknown): Promise<unknown> {
+  const result = await validateAsync(schema, raw);
+  return result.issues === undefined ? result.value : undefined;
+}
+
 /**
  * The handler's return value is data too. Parsing it is what makes the OpenAPI
  * response schema, the typed client and the MCP `outputSchema` true rather than