@fuzdev/fuz_app 0.54.0 → 0.56.0

package/dist/actions/action_rpc.js

@@ -15,14 +15,15 @@ import { z } from 'zod';
 import { DEV } from 'esm-env';
 import {} from '../http/route_spec.js';
 import { get_client_ip } from '../http/proxy.js';
-import { get_request_context, has_role } from '../auth/request_context.js';
-import { CREDENTIAL_TYPE_KEY } from '../hono_context.js';
-import { is_null_schema, is_void_schema } from '../http/schema_helpers.js';
+import { get_request_context, } from '../auth/request_context.js';
+import { ACCOUNT_ID_KEY, CREDENTIAL_TYPE_KEY, TEST_CONTEXT_PRESET_KEY } from '../hono_context.js';
+import { compile_action_registry } from './compile_action_registry.js';
 import { JSONRPC_VERSION, JsonrpcRequest, } from '../http/jsonrpc.js';
 import { jsonrpc_error_messages, jsonrpc_error_code_to_http_status, JSONRPC_ERROR_CODES, } from '../http/jsonrpc_errors.js';
-import { ERROR_INSUFFICIENT_PERMISSIONS, ERROR_KEEPER_REQUIRES_DAEMON_TOKEN, } from '../http/error_schemas.js';
+import { perform_action, perform_action_result_to_envelope } from './perform_action.js';
 /**
- * Pair a spec with a handler while preserving per-method input/output types.
+ * Pair a spec with a handler while preserving per-method input/output types
+ * and selecting the narrowest `ctx.auth` shape the spec literal admits.
  *
  * Constructing `{spec, handler}` literals widens `handler` to
  * `ActionHandler<any, any>`, so spec/handler drift (renamed Zod schema,
@@ -31,60 +32,57 @@ import { ERROR_INSUFFICIENT_PERMISSIONS, ERROR_KEEPER_REQUIRES_DAEMON_TOKEN, } f
  * `(input: z.infer<spec.input>, ctx) => z.infer<spec.output>` via the
  * generic spec parameter — drift surfaces at the call site.
  *
+ * The `ctx.auth` narrowing follows the spec's `auth.account` /
+ * `auth.actor` literals (see `HandlerForSpec`): an actor-implying spec
+ * gets `ctx.auth: RequestActorContext`; an account-grain spec gets
+ * `ctx.auth: RequestContext`; everything else stays `ctx.auth:
+ * RequestContext | null`. Handlers can rely on the dispatcher's
+ * runtime guarantee without a manual narrowing call.
+ *
  * Fits fuz_app's factory-closure pattern (handlers close over
  * `grantable_roles`, `app_settings` ref, `notification_sender`, etc.).
  * zzz uses a different shape — a codegen-keyed `Record<Method, Handler>`
  * map typed via generated `ActionInputs`/`ActionOutputs` — which works when
  * handlers are pure (no closure state) and specs are codegen-enumerated.
- * fuz_app's admin + permit-offer actions have neither, so per-pair typing
+ * fuz_app's admin + role-grant-offer actions have neither, so per-pair typing
  * at the registration site is the right fit.
+ *
+ * Spec-literal preservation is load-bearing: declare specs with
+ * `satisfies RequestResponseActionSpec` (canonical) so `auth.actor`
+ * keeps its `'required'` / `'none'` literal type. A spec typed
+ * directly as `RequestResponseActionSpec` widens the axes to
+ * `AuthAxisState` and the handler defaults to the loosest tier — sound,
+ * but loses the ergonomic narrowing.
+ *
+ * @example
+ * ```ts
+ * // actor-implying spec → ctx.auth: RequestActorContext
+ * rpc_action(role_grant_revoke_action_spec, async (input, ctx) => {
+ *   const revoker_id = ctx.auth.actor.id; // no narrowing needed
+ * });
+ *
+ * // account-grain spec → ctx.auth: RequestContext (actor: null)
+ * rpc_action(account_verify_action_spec, (_input, ctx) => {
+ *   return to_session_account(ctx.auth.account); // no narrowing needed
+ * });
+ * ```
  */
 export const rpc_action = (spec, handler) => ({
     spec,
     handler: handler,
 });
-const jsonrpc_error_response = (id, error) => ({
+/**
+ * Build a JSON-RPC error envelope for transport-shape errors (envelope
+ * parse failures, method-not-found, GET-on-mutation rejections). The
+ * dispatch core in `perform_action` returns a `PerformActionResult`
+ * directly; this helper covers only the wire-shape errors the HTTP shim
+ * emits before / after the core runs.
+ */
+const jsonrpc_error_envelope = (id, error) => ({
     jsonrpc: JSONRPC_VERSION,
     id,
     error,
 });
-/**
- * Check auth for an action spec against the request context.
- *
- * @returns a JSON-RPC error object if auth fails, or `null` if authorized
- */
-const check_action_auth = (auth, request_context, credential_type) => {
-    if (auth === 'public')
-        return null;
-    if (!request_context)
-        return jsonrpc_error_messages.unauthenticated();
-    if (auth === 'authenticated')
-        return null;
-    if (auth === 'keeper') {
-        // keeper requires daemon_token credential type AND the keeper role.
-        // API tokens and session cookies cannot access keeper actions even
-        // if the account has the keeper permit. Attach the credential type
-        // under `data` so clients can distinguish "wrong credential shape"
-        // from "missing keeper role" — mirrors REST 403 semantics.
-        if (credential_type !== 'daemon_token' || !has_role(request_context, 'keeper')) {
-            return jsonrpc_error_messages.forbidden('forbidden', {
-                reason: ERROR_KEEPER_REQUIRES_DAEMON_TOKEN,
-                credential_type,
-            });
-        }
-        return null;
-    }
-    // role check — attach `required_role` under `data.required_role` so
-    // clients can render targeted copy (matches the former REST `PermissionError`
-    // shape that exposed `required_role` as a top-level field).
-    if (!has_role(request_context, auth.role)) {
-        return jsonrpc_error_messages.forbidden(`requires role: ${auth.role}`, {
-            reason: ERROR_INSUFFICIENT_PERMISSIONS,
-            required_role: auth.role,
-        });
-    }
-    return null;
-};
 /**
  * Single JSON-RPC 2.0 endpoint — the canonical RPC transport binding.
  *
@@ -94,9 +92,18 @@ const check_action_auth = (auth, request_context, credential_type) => {
  * 1. **Parse envelope** — POST: JSON body as `JsonrpcRequest`. GET: `method`
  *    and `params` from query string.
  * 2. **Lookup method** — find the `RpcAction` by method name.
- * 3. **Auth check** — verify identity against the action's `auth` requirement.
- * 4. **Validate params** — parse input against the action's `input` schema.
- * 5. **Dispatch** — acquire DB handle (transaction for mutations, pool for reads),
+ * 3. **Pre-validation auth** — short-circuit `unauthenticated` when no
+ *    account is on the request, before input validation runs.
+ * 4. **Authorization phase** — resolve the acting actor (when the action's
+ *    auth requires role_grants or its input declares `acting?: ActingActor`)
+ *    and build the request context. Runs before input validation so
+ *    role-grant-grain auth checks return 403 before 400 invalid_params;
+ *    `acting` is read from raw params via a string typeguard.
+ * 5. **Post-authorization auth** — enforce role / keeper requirements
+ *    against the request context.
+ * 6. **Validate params** — parse input against the action's `input` schema.
+ * 7. **Rate limit** — per-action IP / account throttling.
+ * 8. **Dispatch** — acquire DB handle (transaction for mutations, pool for reads),
  *    construct `ActionContext`, call handler, return JSON-RPC response.
  *
  * GET is restricted to `side_effects: false` actions (cacheable reads).
@@ -115,156 +122,68 @@ const check_action_auth = (auth, request_context, credential_type) => {
  */
 export const create_rpc_endpoint = (options) => {
     const { path: endpoint_path, actions, log, action_ip_rate_limiter = null, action_account_rate_limiter = null, } = options;
-    // build action lookup map
-    const action_map = new Map();
-    for (const action of actions) {
-        if (action_map.has(action.spec.method)) {
-            throw new Error(`Duplicate RPC action method: ${action.spec.method}`);
-        }
-        if (is_null_schema(action.spec.input)) {
-            throw new Error(`RPC action "${action.spec.method}" uses z.null() for input — JSON-RPC 2.0 §4.2 forbids "params": null on the wire (must be omitted or be a Structured value). Use z.void() for parameterless methods.`);
-        }
-        // Reject account-keyed rate limiting on public actions — there's no
-        // actor post-auth, so the account bucket has no key to consume.
-        if ((action.spec.rate_limit === 'account' || action.spec.rate_limit === 'both') &&
-            action.spec.auth === 'public') {
-            throw new Error(`RPC action "${action.spec.method}" declares rate_limit: '${action.spec.rate_limit}' but auth: 'public' — no actor available for account-keyed limiting. Use 'ip' or change auth.`);
-        }
-        action_map.set(action.spec.method, action);
-    }
+    const { action_map } = compile_action_registry(actions, 'RPC action');
     /**
-     * Core dispatcher — shared by GET and POST handlers.
+     * HTTP-shape dispatch shim — the GET/POST entry points share this:
+     *
+     * 1. Resolve the action by method name (HTTP-shape `method_not_found` envelope).
+     * 2. Reject GET requests for `side_effects: true` actions (HTTP-only constraint).
+     * 3. Hand off to `perform_action` for the post-parse pipeline.
+     * 4. Bind the result to `c.json` — `'ok'` returns the result envelope,
+     *    `'error'` returns the error envelope at the `result.status` HTTP code.
      *
      * @param restrict_to_reads - `true` for GET (rejects `side_effects: true` actions)
      */
     const dispatch = async (c, route, method_name, raw_params, id, restrict_to_reads) => {
-        // step 2: lookup method
         const action = action_map.get(method_name);
         if (!action) {
-            const error = jsonrpc_error_response(id, jsonrpc_error_messages.method_not_found(method_name));
-            return c.json(error, jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.method_not_found));
+            return c.json(jsonrpc_error_envelope(id, jsonrpc_error_messages.method_not_found(method_name)), jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.method_not_found));
         }
-        // GET restriction: only side_effects:false actions
         if (restrict_to_reads && action.spec.side_effects) {
-            const error = jsonrpc_error_response(id, jsonrpc_error_messages.invalid_request({
+            return c.json(jsonrpc_error_envelope(id, jsonrpc_error_messages.invalid_request({
                 reason: `method '${method_name}' has side effects and must use POST`,
-            }));
-            return c.json(error, jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.invalid_request));
-        }
-        // step 3: auth check
-        const request_context = get_request_context(c);
-        const credential_type = c.get(CREDENTIAL_TYPE_KEY) ?? null;
-        const auth_error = check_action_auth(action.spec.auth, request_context, credential_type);
-        if (auth_error) {
-            const error = jsonrpc_error_response(id, auth_error);
-            return c.json(error, jsonrpc_error_code_to_http_status(auth_error.code));
+            })), jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.invalid_request));
         }
-        // step 3.5: rate limit — throttle-requests semantics (record on every
-        // invocation, no success-reset). Suits admin mutation oracles where
-        // the *successful* call is the threat. Different from REST login's
-        // throttle-failures pattern that resets on success. Silent partial
-        // enforcement: a key is checked iff its bucket's limiter is wired —
-        // `rate_limit: 'both'` with only one limiter set runs only that side.
-        const rate_limit = action.spec.rate_limit;
-        const client_ip = get_client_ip(c);
-        if (rate_limit) {
-            const ip_check = action_ip_rate_limiter && (rate_limit === 'ip' || rate_limit === 'both');
-            const account_check = action_account_rate_limiter &&
-                request_context &&
-                (rate_limit === 'account' || rate_limit === 'both');
-            const reject = (retry_after) => {
-                const error = jsonrpc_error_response(id, jsonrpc_error_messages.rate_limited('rate limited', { retry_after }));
-                return c.json(error, jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.rate_limited));
-            };
-            if (ip_check) {
-                const result = action_ip_rate_limiter.check(client_ip);
-                if (!result.allowed)
-                    return reject(result.retry_after);
-            }
-            if (account_check) {
-                const result = action_account_rate_limiter.check(request_context.actor.id);
-                if (!result.allowed)
-                    return reject(result.retry_after);
-            }
-            if (ip_check)
-                action_ip_rate_limiter.record(client_ip);
-            if (account_check)
-                action_account_rate_limiter.record(request_context.actor.id);
-        }
-        // step 4: validate params
-        // Missing `params` on the envelope maps to `undefined` for `z.void()`
-        // input schemas and `{}` for object inputs (matches HTTP's "empty
-        // body = empty object" convention so callers of all-optional-object
-        // RPC methods can omit `params` on the wire). JSON-RPC 2.0 §4.2
-        // forbids `params: null`, so `z.void()` is the spec-correct schema
-        // for parameterless methods — registration above rejects `z.null()`
-        // inputs to keep this branch from having to consider that legacy
-        // shape. When `raw_params` is present it flows through unchanged so
-        // contract-violating shapes still fail validation.
-        const params = is_void_schema(action.spec.input) ? raw_params : (raw_params ?? {});
-        const parse_result = action.spec.input.safeParse(params);
-        if (!parse_result.success) {
-            const error = jsonrpc_error_response(id, jsonrpc_error_messages.invalid_params('invalid params', {
-                issues: parse_result.error.issues,
-            }));
-            return c.json(error, jsonrpc_error_code_to_http_status(JSONRPC_ERROR_CODES.invalid_params));
-        }
-        // step 5: dispatch — transaction for mutations, pool for reads
-        const use_transaction = action.spec.side_effects;
+        // HTTP RPC has no streaming channel; `ctx.notify` warn-and-drops in DEV.
         const notify = (notify_method, _notify_params) => {
             if (DEV) {
                 log.warn(`ctx.notify('${notify_method}') called on non-streaming transport; notification dropped (method=${method_name})`);
             }
         };
-        const signal = c.req.raw.signal;
-        const execute = async (db) => {
-            const action_context = {
-                auth: request_context,
-                request_id: id,
-                db,
-                background_db: route.background_db,
-                pending_effects: route.pending_effects,
-                client_ip,
-                log,
-                notify,
-                signal,
-            };
-            const output = await action.handler(parse_result.data, action_context);
-            // DEV-only output validation — logs an error on mismatch, does not throw.
-            if (DEV) {
-                const output_result = action.spec.output.safeParse(output);
-                if (!output_result.success) {
-                    log.error(`RPC output schema mismatch: ${method_name}`, output_result.error.issues);
-                }
-            }
-            return c.json({ jsonrpc: JSONRPC_VERSION, id, result: output });
-        };
-        // error handling wraps the transaction boundary so handler throws
-        // cause rollback before the error is formatted as a JSON-RPC response
-        try {
-            if (use_transaction) {
-                return await route.db.transaction((tx) => execute(tx));
-            }
-            return await execute(route.db);
-        }
-        catch (err) {
-            // Duck-type check: Error with numeric `code` signals a JSON-RPC error.
-            // Avoids instanceof which fails when consumers throw their own ThrownJsonrpcError
-            // (structurally identical but different class identity, e.g. zzz's copy).
-            if (err instanceof Error && typeof err.code === 'number') {
-                const code = err.code;
-                const data = err.data;
-                const status = jsonrpc_error_code_to_http_status(code);
-                const error_json = { code, message: err.message };
-                if (data !== undefined)
-                    error_json.data = data;
-                return c.json(jsonrpc_error_response(id, error_json), status);
-            }
-            // generic error
-            log.error(`Unhandled RPC handler error: ${method_name}`, err);
-            const message = DEV && err instanceof Error ? err.message : 'internal server error';
-            return c.json(jsonrpc_error_response(id, jsonrpc_error_messages.internal_error(message)), 500);
+        // Test escape hatch: harnesses pre-populate `REQUEST_CONTEXT_KEY` and
+        // flag `TEST_CONTEXT_PRESET_KEY = true`. Production middleware never
+        // sets the flag; the shim honors it and `perform_action` trusts the
+        // pre-baked context instead of running the live authorization phase.
+        const preset = c.get(TEST_CONTEXT_PRESET_KEY)
+            ? { request_context: get_request_context(c) }
+            : undefined;
+        const result = await perform_action({
+            action,
+            raw_params,
+            request_id: id,
+            account_id: c.get(ACCOUNT_ID_KEY) ?? null,
+            credential_type: c.get(CREDENTIAL_TYPE_KEY) ?? null,
+            client_ip: get_client_ip(c),
+            signal: c.req.raw.signal,
+            notify,
+            preset,
+        }, {
+            db: route.db,
+            pending_effects: route.pending_effects,
+            post_commit_effects: route.post_commit_effects,
+            log,
+            action_ip_rate_limiter,
+            action_account_rate_limiter,
+        });
+        const envelope = perform_action_result_to_envelope(id, result);
+        if (result.kind === 'error') {
+            // `result.status` is one of the JSON-RPC → HTTP status codes the
+            // dispatcher emits; Hono types `c.json`'s second arg as
+            // `ContentfulStatusCode`, which the cast bridges (the value space
+            // is verified by `jsonrpc_error_code_to_http_status`).
+            return c.json(envelope, result.status);
         }
+        return c.json(envelope);
     };
     // POST handler — parse JSON-RPC envelope from body
     const post_handler = async (c, route) => {
@@ -274,7 +193,7 @@ export const create_rpc_endpoint = (options) => {
             body = await c.req.json();
         }
         catch {
-            const error = jsonrpc_error_response(null, jsonrpc_error_messages.parse_error());
+            const error = jsonrpc_error_envelope(null, jsonrpc_error_messages.parse_error());
             return c.json(error, 400);
         }
         const envelope = JsonrpcRequest.safeParse(body);
@@ -284,7 +203,7 @@ export const create_rpc_endpoint = (options) => {
                 ? body.id
                 : null;
             const id = typeof raw_id === 'string' || typeof raw_id === 'number' ? raw_id : null;
-            const error = jsonrpc_error_response(id, jsonrpc_error_messages.invalid_request({ issues: envelope.error.issues }));
+            const error = jsonrpc_error_envelope(id, jsonrpc_error_messages.invalid_request({ issues: envelope.error.issues }));
             return c.json(error, 400);
         }
         return dispatch(c, route, envelope.data.method, envelope.data.params, envelope.data.id, false);
@@ -294,12 +213,12 @@ export const create_rpc_endpoint = (options) => {
         // step 1: parse from query string
         const method_name = c.req.query('method');
         if (!method_name) {
-            const error = jsonrpc_error_response(null, jsonrpc_error_messages.invalid_request({ reason: 'missing method query parameter' }));
+            const error = jsonrpc_error_envelope(null, jsonrpc_error_messages.invalid_request({ reason: 'missing method query parameter' }));
             return c.json(error, 400);
         }
         const id_raw = c.req.query('id');
         if (!id_raw) {
-            const error = jsonrpc_error_response(null, jsonrpc_error_messages.invalid_request({ reason: 'missing id query parameter' }));
+            const error = jsonrpc_error_envelope(null, jsonrpc_error_messages.invalid_request({ reason: 'missing id query parameter' }));
             return c.json(error, 400);
         }
         // parse integer ids so GET ?id=42 matches POST {id: 42} behavior
@@ -314,7 +233,7 @@ export const create_rpc_endpoint = (options) => {
                 params = JSON.parse(params_raw);
             }
             catch {
-                const error = jsonrpc_error_response(id, jsonrpc_error_messages.invalid_params('params query parameter is not valid JSON'));
+                const error = jsonrpc_error_envelope(id, jsonrpc_error_messages.invalid_params('params query parameter is not valid JSON'));
                 return c.json(error, 400);
             }
         }
@@ -324,7 +243,7 @@ export const create_rpc_endpoint = (options) => {
         {
             method: 'POST',
             path: endpoint_path,
-            auth: { type: 'none' }, // per-action auth inside dispatcher
+            auth: { account: 'none', actor: 'none' }, // per-action auth inside dispatcher
             handler: post_handler,
             description: `JSON-RPC 2.0 endpoint — ${actions.length} method${actions.length === 1 ? '' : 's'}`,
             input: z.null(), // dispatcher owns body parsing; rpc_endpoints surface has the real schemas
@@ -334,7 +253,7 @@ export const create_rpc_endpoint = (options) => {
         {
             method: 'GET',
             path: endpoint_path,
-            auth: { type: 'none' }, // per-action auth inside dispatcher
+            auth: { account: 'none', actor: 'none' }, // per-action auth inside dispatcher
             handler: get_handler,
             description: `JSON-RPC 2.0 endpoint (cacheable reads) — ${actions.length} method${actions.length === 1 ? '' : 's'}`,
             input: z.null(), // params from query string, validated by dispatcher

package/dist/actions/action_spec.d.ts

@@ -23,10 +23,6 @@ export declare const ActionInitiator: z.ZodEnum<{
     backend: "backend";
 }>;
 export type ActionInitiator = z.infer<typeof ActionInitiator>;
-export declare const ActionAuth: z.ZodUnion<readonly [z.ZodLiteral<"public">, z.ZodLiteral<"authenticated">, z.ZodLiteral<"keeper">, z.ZodObject<{
-    role: z.ZodString;
-}, z.core.$strict>]>;
-export type ActionAuth = z.infer<typeof ActionAuth>;
 export declare const ActionSideEffects: z.ZodBoolean;
 export type ActionSideEffects = z.infer<typeof ActionSideEffects>;
 export declare const ActionSpec: z.ZodObject<{
@@ -41,9 +37,29 @@ export declare const ActionSpec: z.ZodObject<{
         frontend: "frontend";
         backend: "backend";
     }>;
-    auth: z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<"public">, z.ZodLiteral<"authenticated">, z.ZodLiteral<"keeper">, z.ZodObject<{
-        role: z.ZodString;
-    }, z.core.$strict>]>>;
+    /**
+     * The four-axis auth shape (canonical schema in `http/auth_shape.ts`).
+     * `null` for `remote_notification` and `local_call` — those don't
+     * dispatch through the request/response auth gate.
+     *
+     * See `../http/auth_shape.ts` for the design rationale (orthogonal
+     * authentication / account-resolution / actor-resolution / role-and-
+     * credential authorization axes).
+     */
+    auth: z.ZodNullable<z.ZodObject<{
+        account: z.ZodEnum<{
+            optional: "optional";
+            none: "none";
+            required: "required";
+        }>;
+        actor: z.ZodEnum<{
+            optional: "optional";
+            none: "none";
+            required: "required";
+        }>;
+        roles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        credential_types: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>>;
     side_effects: z.ZodBoolean;
     input: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     output: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
@@ -62,7 +78,7 @@ export declare const ActionSpec: z.ZodObject<{
      * failure. Declarative metadata mirroring the `streams` precedent —
      * codegen, UI form-state matching, and docs read it off the spec instead
      * of scanning handler implementations. Reuses the same `as const` string
-     * constants the handler throws (e.g. `ERROR_OFFER_*`) so call sites can
+     * constants the handler throws (e.g. `ERROR_ROLE_GRANT_OFFER_*`) so call sites can
      * import either side. Optional — actions that surface only standard
      * transport errors leave it unset.
      */
@@ -72,8 +88,9 @@ export declare const ActionSpec: z.ZodObject<{
      * actions without it skip the rate-limit hook entirely.
      *
      * - `'ip'` — keyed on the resolved client IP (`get_client_ip(c)`).
-     * - `'account'` — keyed on the post-auth actor id (`request_context.actor.id`).
-     *   Registration-time error if paired with `auth: 'public'` (no actor).
+     * - `'account'` — keyed on the post-auth account id (`request_context.account.id`).
+     *   Registration-time error if paired with `auth.account !== 'required'`
+     *   (no account to key on).
      * - `'both'` — both checks run; either can block.
      *
      * Throttle-requests semantics — every invocation records, regardless of
@@ -112,9 +129,20 @@ export declare const RequestResponseActionSpec: z.ZodObject<{
         both: "both";
     }>>;
     kind: z.ZodDefault<z.ZodLiteral<"request_response">>;
-    auth: z.ZodUnion<readonly [z.ZodLiteral<"public">, z.ZodLiteral<"authenticated">, z.ZodLiteral<"keeper">, z.ZodObject<{
-        role: z.ZodString;
-    }, z.core.$strict>]>;
+    auth: z.ZodObject<{
+        account: z.ZodEnum<{
+            optional: "optional";
+            none: "none";
+            required: "required";
+        }>;
+        actor: z.ZodEnum<{
+            optional: "optional";
+            none: "none";
+            required: "required";
+        }>;
+        roles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        credential_types: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>;
     async: z.ZodDefault<z.ZodLiteral<true>>;
 }, z.core.$strict>;
 export type RequestResponseActionSpec = z.infer<typeof RequestResponseActionSpec>;
@@ -187,9 +215,20 @@ export declare const ActionSpecUnion: z.ZodUnion<readonly [z.ZodObject<{
         both: "both";
     }>>;
     kind: z.ZodDefault<z.ZodLiteral<"request_response">>;
-    auth: z.ZodUnion<readonly [z.ZodLiteral<"public">, z.ZodLiteral<"authenticated">, z.ZodLiteral<"keeper">, z.ZodObject<{
-        role: z.ZodString;
-    }, z.core.$strict>]>;
+    auth: z.ZodObject<{
+        account: z.ZodEnum<{
+            optional: "optional";
+            none: "none";
+            required: "required";
+        }>;
+        actor: z.ZodEnum<{
+            optional: "optional";
+            none: "none";
+            required: "required";
+        }>;
+        roles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        credential_types: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>;
     async: z.ZodDefault<z.ZodLiteral<true>>;
 }, z.core.$strict>, z.ZodObject<{
     method: z.ZodString;

package/dist/actions/action_spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAItB,eAAO,MAAM,UAAU;;;;EAAoE,CAAC;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;;;EAA0C,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,UAAU;;oBAKrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;IAUtB;;;;;;OAMG;;IAEH;;;;;;;;OAQG;;IAEH;;;;;;;;;;;;;;;;;;OAkBG;;;;;;kBAEF,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;kBAIpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;kBAMvC,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,gHAAgH;AAChH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKoB,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;;;;;;;EAU3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"action_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAKtB,eAAO,MAAM,UAAU;;;;EAAoE,CAAC;AAC5F,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;;;EAA0C,CAAC;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAC7C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,UAAU;;;;;;;;;;;;IAItB;;;;;;;;OAQG;;;;;;;;;;;;;;;;;;;;IAOH;;;;;;OAMG;;IAEH;;;;;;;;OAQG;;IAEH;;;;;;;;;;;;;;;;;;;OAmBG;;;;;;kBAEF,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAIpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;kBAMvC,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAExF;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;kBAG9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAI1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,gHAAgH;AAChH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAKoB,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;;;;;;;EAU3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/actions/action_spec.js

@@ -12,20 +12,24 @@
  */
 import { z } from 'zod';
 import { RateLimitKey } from '../http/error_schemas.js';
+import { RouteAuth } from '../http/auth_shape.js';
 export const ActionKind = z.enum(['request_response', 'remote_notification', 'local_call']);
 export const ActionInitiator = z.enum(['frontend', 'backend', 'both']);
-export const ActionAuth = z.union([
-    z.literal('public'),
-    z.literal('authenticated'),
-    z.literal('keeper'),
-    z.strictObject({ role: z.string() }),
-]);
 export const ActionSideEffects = z.boolean();
 export const ActionSpec = z.strictObject({
     method: z.string(),
     kind: ActionKind,
     initiator: ActionInitiator,
-    auth: ActionAuth.nullable(),
+    /**
+     * The four-axis auth shape (canonical schema in `http/auth_shape.ts`).
+     * `null` for `remote_notification` and `local_call` — those don't
+     * dispatch through the request/response auth gate.
+     *
+     * See `../http/auth_shape.ts` for the design rationale (orthogonal
+     * authentication / account-resolution / actor-resolution / role-and-
+     * credential authorization axes).
+     */
+    auth: RouteAuth.nullable(),
     side_effects: ActionSideEffects,
     input: z.custom((v) => v instanceof z.ZodType),
     output: z.custom((v) => v instanceof z.ZodType),
@@ -44,7 +48,7 @@ export const ActionSpec = z.strictObject({
      * failure. Declarative metadata mirroring the `streams` precedent —
      * codegen, UI form-state matching, and docs read it off the spec instead
      * of scanning handler implementations. Reuses the same `as const` string
-     * constants the handler throws (e.g. `ERROR_OFFER_*`) so call sites can
+     * constants the handler throws (e.g. `ERROR_ROLE_GRANT_OFFER_*`) so call sites can
      * import either side. Optional — actions that surface only standard
      * transport errors leave it unset.
      */
@@ -54,8 +58,9 @@ export const ActionSpec = z.strictObject({
      * actions without it skip the rate-limit hook entirely.
      *
      * - `'ip'` — keyed on the resolved client IP (`get_client_ip(c)`).
-     * - `'account'` — keyed on the post-auth actor id (`request_context.actor.id`).
-     *   Registration-time error if paired with `auth: 'public'` (no actor).
+     * - `'account'` — keyed on the post-auth account id (`request_context.account.id`).
+     *   Registration-time error if paired with `auth.account !== 'required'`
+     *   (no account to key on).
      * - `'both'` — both checks run; either can block.
      *
      * Throttle-requests semantics — every invocation records, regardless of
@@ -72,7 +77,7 @@ export const ActionSpec = z.strictObject({
 });
 export const RequestResponseActionSpec = ActionSpec.extend({
     kind: z.literal('request_response').default('request_response'),
-    auth: ActionAuth,
+    auth: RouteAuth,
     async: z.literal(true).default(true),
 });
 export const RemoteNotificationActionSpec = ActionSpec.extend({