@fuzdev/fuz_app 0.55.0 → 0.56.0

package/dist/http/route_spec.js

@@ -15,38 +15,17 @@
 import { DEV } from 'esm-env';
 import { ERROR_INVALID_JSON_BODY, ERROR_INVALID_REQUEST_BODY, ERROR_INVALID_ROUTE_PARAMS, ERROR_INVALID_QUERY_PARAMS, } from './error_schemas.js';
 import { ThrownJsonrpcError, jsonrpc_error_code_to_http_status, jsonrpc_error_code_to_name, } from './jsonrpc_errors.js';
-import { CACHED_REQUEST_BODY_KEY } from '../hono_context.js';
 import { is_null_schema, merge_error_schemas } from './schema_helpers.js';
-/**
- * Get validated input from the Hono context.
- *
- * Call after the input validation middleware has run. The type parameter
- * should match the route's `input` schema.
- */
-export const get_route_input = (c) => {
+import { assert_route_auth_acting_biconditional } from './auth_shape.js';
+export function get_route_input(c, _schema) {
     return c.get('validated_input');
-};
-/**
- * Get validated URL path params from the Hono context.
- *
- * Call after the params validation middleware has run. The type parameter
- * should match the route's `params` schema.
- *
- * TODO derive `T` from the route spec so the type parameter isn't manually
- * specified — same applies to `get_route_input` / `get_route_query`.
- */
-export const get_route_params = (c) => {
+}
+export function get_route_params(c, _schema) {
     return c.get('validated_params');
-};
-/**
- * Get validated URL query params from the Hono context.
- *
- * Call after the query validation middleware has run. The type parameter
- * should match the route's `query` schema.
- */
-export const get_route_query = (c) => {
+}
+export function get_route_query(c, _schema) {
     return c.get('validated_query');
-};
+}
 /**
  * Create input validation middleware for a route spec.
  *
@@ -54,7 +33,10 @@ export const get_route_query = (c) => {
  * validated elsewhere, e.g. from `?params=` query string in RPC handlers)
  * and for null-input routes (no body expected). For other routes with input
  * schemas, returns a middleware that parses and validates the JSON body,
- * storing the result on the context as `validated_input`.
+ * storing the result on the context as `validated_input`. Input validation
+ * runs before the authorization phase, so the authorization phase reads
+ * `c.var.validated_input.acting` directly — no separate body pre-parse /
+ * cache machinery is needed.
  *
  * @mutates `c.var.validated_input` - set to the parsed and validated body on success
  */
@@ -64,30 +46,12 @@ const create_input_validation = (input_schema, method) => {
     if (is_null_schema(input_schema))
         return [];
     const validate = async (c, next) => {
-        // Prefer the cached parse result written by `read_raw_acting`
-        // (the dispatcher's `acting` extractor). The cache decouples
-        // us from Hono's internal `bodyCache` — Hono keeps the body
-        // text alive across multiple `c.req.json()` calls but still
-        // re-runs `JSON.parse` each time, so caching the parsed value
-        // saves work and pins behavior to fuz_app code rather than to
-        // undocumented Hono internals.
-        // Hono's `c.get()` types this as the variable-map entry, but at
-        // runtime it returns `undefined` when no setter has run for this
-        // request. Narrow defensively.
-        const cached = c.get(CACHED_REQUEST_BODY_KEY);
         let body;
-        if (cached !== undefined) {
-            if (!cached.ok)
-                return c.json({ error: ERROR_INVALID_JSON_BODY }, 400);
-            body = cached.body;
+        try {
+            body = await c.req.json();
         }
-        else {
-            try {
-                body = await c.req.json();
-            }
-            catch {
-                return c.json({ error: ERROR_INVALID_JSON_BODY }, 400);
-            }
+        catch {
+            return c.json({ error: ERROR_INVALID_JSON_BODY }, 400);
         }
         if (typeof body !== 'object' || body === null || Array.isArray(body)) {
             return c.json({ error: ERROR_INVALID_JSON_BODY }, 400);
@@ -299,29 +263,38 @@ const build_rest_error_body = (err) => {
  * and generic errors), and registers the route.
  *
  * Per-route middleware order: params → query → pre-validation auth
- * guards (401) → authorization phase → post-authorization auth guards
- * (403) → input validation → handler. The 401 check runs before any
- * body parsing so unauthenticated callers never see route-shape
- * information from parse failures. The authorization phase runs before
- * input validation (matches the RPC dispatcher's order) so role /
- * keeper denials surface 403 before 400 invalid_params; it extracts
- * `acting` from raw query (GET) or pre-parsed JSON body (POST/PUT/...)
- * — Hono caches the parsed body internally so the subsequent input-
- * validation step does not re-parse. The role / keeper guards consume
- * the `RequestContext` populated by the authorization phase.
+ * guards (401) → input validation (400) → authorization phase →
+ * post-authorization auth guards (403) → handler. The 401 check runs
+ * before any body parsing so unauthenticated callers never see
+ * route-shape information from parse failures. Input validation runs
+ * before the authorization phase (validate first, authorize after) so
+ * the authorization phase reads `c.var.validated_input.acting` as a
+ * typed Zod field instead of pre-parsing the raw body. Role /
+ * credential-type denials still surface 403 last; trade-off is that
+ * authenticated-but-unauthorized callers can distinguish 400
+ * (validation) from 403 (authorization), a defense-in-depth concession
+ * deemed acceptable because the route surface is public via
+ * spec/codegen JSON.
  *
  * Each handler receives a `RouteContext` with:
- * - `db`: transaction-scoped (for non-GET) or pool-level (for GET)
- * - `background_db`: always pool-level
- * - `pending_effects`: fire-and-forget effect queue
+ * - `db`: transaction-scoped when `RouteSpec.transaction` is true; pool-level otherwise
+ * - `pending_effects`: eager fire-and-forget pool-write queue
+ * - `post_commit_effects`: deferred-thunk queue (push via `emit_after_commit`)
+ *
+ * Also enforces registry-time invariant 2 from the auth-shape design:
+ * `auth.actor !== 'none' ⟺ input or query declares acting?: ActingActor`.
+ * REST is bi-located (GETs declare `acting` on `query`, mutations on
+ * `input`), so the check passes both slots; the action-dispatcher
+ * registries (`compile_action_registry`) share the same helper with
+ * `input` only — `ActionSpec` has no `query` shape.
  *
- * @param resolve_auth_guards - maps `RouteAuth` to middleware — use `fuz_auth_guard_resolver` from `auth/route_guards.ts`
- * @param authorize - optional authorization phase; runs between guards and input validation
+ * @param resolve_auth_guards - maps `RouteAuth` to middleware — use `fuz_auth_guard_resolver` from `auth/auth_guard_resolver.ts`
+ * @param authorize - optional authorization phase; runs after input validation
  * @param db - used for transaction wrapping and `RouteContext`
  * @mutates `app`
- * @throws Error if two specs share the same `method` + `path` (each combination must be unique)
+ * @throws Error if two specs share the same `method` + `path` (each combination must be unique), or if any spec violates the actor-acting biconditional
  */
-export const apply_route_specs = (app, specs, resolve_auth_guards, log, db, authorize, is_acting_aware) => {
+export const apply_route_specs = (app, specs, resolve_auth_guards, log, db, authorize) => {
     const registered = new Set();
     for (const spec of specs) {
         const route_key = `${spec.method} ${spec.path}`;
@@ -329,11 +302,12 @@ export const apply_route_specs = (app, specs, resolve_auth_guards, log, db, auth
             throw new Error(`Duplicate route: ${route_key} — each method+path combination must be unique`);
         }
         registered.add(route_key);
+        assert_route_auth_acting_biconditional(spec.auth, { input: spec.input, query: spec.query }, `Route "${route_key}"`);
         const { pre_validation: pre_validation_guards, post_authorization: post_authorization_guards } = resolve_auth_guards(spec.auth);
         const params_validation = create_params_validation(spec.params);
         const query_validation = create_query_validation(spec.query);
         const input_validation = create_input_validation(spec.input, spec.method);
-        const merged_errors = merge_error_schemas(spec, null, is_acting_aware?.(spec) ?? false);
+        const merged_errors = merge_error_schemas(spec, null);
         const authorization = authorize
             ? [
                 async (c, next) => {
@@ -348,13 +322,21 @@ export const apply_route_specs = (app, specs, resolve_auth_guards, log, db, auth
         const use_transaction = spec.transaction ?? spec.method !== 'GET';
         const inner = spec.handler;
         let handler = use_transaction
-            ? (c) => db.transaction(async (tx) => inner(c, { db: tx, background_db: db, pending_effects: c.var.pending_effects }))
-            : (c) => inner(c, { db, background_db: db, pending_effects: c.var.pending_effects });
+            ? (c) => db.transaction(async (tx) => inner(c, {
+                db: tx,
+                pending_effects: c.var.pending_effects,
+                post_commit_effects: c.var.post_commit_effects,
+            }))
+            : (c) => inner(c, {
+                db,
+                pending_effects: c.var.pending_effects,
+                post_commit_effects: c.var.post_commit_effects,
+            });
         // Step 2: output validation
         handler = wrap_output_validation(handler, spec.output, merged_errors, log);
         // Step 3: error catch layer
         handler = wrap_error_catch(handler, log);
-        app.on(spec.method, [spec.path], ...params_validation, ...query_validation, ...pre_validation_guards, ...authorization, ...post_authorization_guards, ...input_validation, handler);
+        app.on(spec.method, [spec.path], ...params_validation, ...query_validation, ...pre_validation_guards, ...input_validation, ...authorization, ...post_authorization_guards, handler);
     }
 };
 /**

package/dist/http/schema_helpers.d.ts

@@ -8,7 +8,7 @@
  * @module
  */
 import { z } from 'zod';
-import type { RouteAuth } from './route_spec.js';
+import type { RouteAuth } from './auth_shape.js';
 import { type RateLimitKey, type RouteErrorSchemas } from './error_schemas.js';
 /**
  * Check if a schema is exactly `z.null()`.
@@ -45,7 +45,7 @@ export declare const schema_to_surface: (schema: z.ZodType) => unknown;
  *
  * Supports Hono-style patterns:
  * - `/api/*` matches `/api/anything`
- * - `/api/tx/*` matches `/api/tx/runs` but not `/api/account/login`
+ * - `/api/zap/*` matches `/api/zap/runs` but not `/api/account/login`
  * - Exact match: `/health` matches `/health`
  */
 export declare const middleware_applies: (mw_path: string, route_path: string) => boolean;
@@ -55,19 +55,8 @@ export declare const middleware_applies: (mw_path: string, route_path: string) =
  * Merge order: derived -> middleware -> explicit route errors.
  * Later layers override earlier ones for the same status code.
  *
- * `acting_aware` flows through to `derive_error_schemas` so routes whose
- * input declares `acting?: ActingActor` (or whose auth requires permits)
- * pick up the actor-failure error shapes the dispatcher's authorization
- * phase may emit. The flag is computed at the call site rather than here
- * because the `acting`-detection helper lives in `auth/` (it depends on
- * the canonical `ActingActor` schema for reference equality, and `http/`
- * stays auth-agnostic). See `http/CLAUDE.md` § Three-layer error-schema
- * merge.
- *
  * @param spec - the route spec (needs `auth`, `input`, `params`, `rate_limit`, `errors`)
  * @param middleware_errors - errors contributed by middleware whose path matches the route
- * @param acting_aware - whether the dispatcher's authorization phase may emit
- *   actor-failure errors on this route
  * @returns merged error schemas, or `null` if empty
  */
 export declare const merge_error_schemas: (spec: {
@@ -77,5 +66,5 @@ export declare const merge_error_schemas: (spec: {
     query?: z.ZodObject;
     rate_limit?: RateLimitKey;
     errors?: RouteErrorSchemas;
-}, middleware_errors?: RouteErrorSchemas | null, acting_aware?: boolean) => RouteErrorSchemas | null;
+}, middleware_errors?: RouteErrorSchemas | null) => RouteErrorSchemas | null;
 //# sourceMappingURL=schema_helpers.d.ts.map

package/dist/http/schema_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/schema_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAuB,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAAsC,CAAC;AAE1F;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAAsC,CAAC;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OACe,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAQrD,CAAC;AAoBF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,EAAE,YAAY,MAAM,KAAG,OAQxE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM;IACL,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B,EACD,oBAAoB,iBAAiB,GAAG,IAAI,EAC5C,sBAAoB,KAClB,iBAAiB,GAAG,IAWtB,CAAC"}
+{"version":3,"file":"schema_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/schema_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAuB,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAAsC,CAAC;AAE1F;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAAsC,CAAC;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OACe,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAQrD,CAAC;AAoBF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,EAAE,YAAY,MAAM,KAAG,OAQxE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM;IACL,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B,EACD,oBAAoB,iBAAiB,GAAG,IAAI,KAC1C,iBAAiB,GAAG,IAUtB,CAAC"}

package/dist/http/schema_helpers.js

@@ -74,7 +74,7 @@ const strip_json_schema_noise = (value) => {
  *
  * Supports Hono-style patterns:
  * - `/api/*` matches `/api/anything`
- * - `/api/tx/*` matches `/api/tx/runs` but not `/api/account/login`
+ * - `/api/zap/*` matches `/api/zap/runs` but not `/api/account/login`
  * - Exact match: `/health` matches `/health`
  */
 export const middleware_applies = (mw_path, route_path) => {
@@ -94,29 +94,17 @@ export const middleware_applies = (mw_path, route_path) => {
  * Merge order: derived -> middleware -> explicit route errors.
  * Later layers override earlier ones for the same status code.
  *
- * `acting_aware` flows through to `derive_error_schemas` so routes whose
- * input declares `acting?: ActingActor` (or whose auth requires permits)
- * pick up the actor-failure error shapes the dispatcher's authorization
- * phase may emit. The flag is computed at the call site rather than here
- * because the `acting`-detection helper lives in `auth/` (it depends on
- * the canonical `ActingActor` schema for reference equality, and `http/`
- * stays auth-agnostic). See `http/CLAUDE.md` § Three-layer error-schema
- * merge.
- *
  * @param spec - the route spec (needs `auth`, `input`, `params`, `rate_limit`, `errors`)
  * @param middleware_errors - errors contributed by middleware whose path matches the route
- * @param acting_aware - whether the dispatcher's authorization phase may emit
- *   actor-failure errors on this route
  * @returns merged error schemas, or `null` if empty
  */
-export const merge_error_schemas = (spec, middleware_errors, acting_aware = false) => {
+export const merge_error_schemas = (spec, middleware_errors) => {
     const derived = derive_error_schemas({
         auth: spec.auth,
         has_input: !is_null_schema(spec.input),
         has_params: !!spec.params,
         has_query: !!spec.query,
         rate_limit: spec.rate_limit,
-        acting_aware,
     });
     const merged = { ...derived, ...middleware_errors, ...spec.errors };
     return Object.keys(merged).length > 0 ? merged : null;

package/dist/http/surface.d.ts

@@ -9,7 +9,8 @@
 import { z } from 'zod';
 import type { EventSpec } from '../realtime/sse.js';
 import type { MiddlewareSpec } from './middleware_spec.js';
-import type { IsActingAware, RouteAuth, RouteSpec } from './route_spec.js';
+import type { RouteSpec } from './route_spec.js';
+import type { RouteAuth } from './auth_shape.js';
 import type { RateLimitKey, RouteErrorSchemas } from './error_schemas.js';
 import type { RpcAction } from '../actions/action_rpc.js';
 import type { Sensitivity } from '../sensitivity.js';
@@ -118,15 +119,6 @@ export interface GenerateAppSurfaceOptions {
     env_schema?: z.ZodObject;
     event_specs?: Array<EventSpec>;
     rpc_endpoints?: Array<RpcEndpointSpec>;
-    /**
-     * Per-route predicate that decides whether the dispatcher's authorization
-     * phase may emit `actor_required` / `actor_not_on_account` (400) or
-     * `no_actors_on_account` / `account_vanished` (500) on this spec. Mirrors
-     * the parameter on `apply_route_specs` so the surface exposes the same
-     * error shapes the live framework would emit. See `http/CLAUDE.md` §
-     * Three-layer error-schema merge.
-     */
-    is_acting_aware?: IsActingAware;
 }
 /**
  * Collect error schemas from all middleware that applies to a route path.

package/dist/http/surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAC,aAAa,EAAE,SAAS,EAAE,SAAS,EAAC,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAC,YAAY,EAAE,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,0BAA0B,CAAC;AASxD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAKnD,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,qBAAqB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,WAAW,EAAE,OAAO,CAAC;IACrB,oFAAoF;IACpF,cAAc,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,uFAAuF;IACvF,aAAa,EAAE,OAAO,CAAC;IACvB,8FAA8F;IAC9F,YAAY,EAAE,OAAO,CAAC;IACtB,wFAAwF;IACxF,YAAY,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,aAAa,EAAE,OAAO,CAAC;IACvB,mGAAmG;IACnG,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,mGAAmG;IACnG,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;CACvB;AAED,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,qFAAqF;IACrF,YAAY,EAAE,OAAO,CAAC;IACtB,uDAAuD;IACvD,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,cAAc,EAAE,YAAY,GAAG,IAAI,CAAC;CACpC;AAED,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;CACpC;AAED,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IAC1B,UAAU,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACxC,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAC/B,aAAa,EAAE,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC5C,GAAG,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC1B,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAC/B,WAAW,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;CACzC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,UAAU,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9B,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IACxC,aAAa,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CACtC;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9B,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACzB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/B,aAAa,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACvC;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC;CAChC;AAID;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GACrC,YAAY,KAAK,CAAC,cAAc,CAAC,EACjC,YAAY,MAAM,KAChB,iBAAiB,GAAG,IAQtB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,aAAa,CAe9E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,aAAa,KAAK,CAAC,SAAS,CAAC,KAAG,KAAK,CAAC,eAAe,CAOtF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,yBAAyB,KAAG,UA0FzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,yBAAyB,KAAG,cAQ5E,CAAC"}
+{"version":3,"file":"surface.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/surface.ts"],"names":[],"mappings":"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"}

package/dist/http/surface.js

@@ -7,7 +7,6 @@
  * @module
  */
 import { z } from 'zod';
-import { map_action_auth } from '../actions/action_bridge.js';
 import { schema_to_surface, middleware_applies, merge_error_schemas, is_null_schema, is_strict_object_schema, } from './schema_helpers.js';
 // --- Surface generation ---
 /**
@@ -61,7 +60,7 @@ export const events_to_surface = (event_specs) => {
  * and optional env/event metadata.
  */
 export const generate_app_surface = (options) => {
-    const { route_specs, middleware_specs, env_schema, event_specs, rpc_endpoints, is_acting_aware } = options;
+    const { route_specs, middleware_specs, env_schema, event_specs, rpc_endpoints } = options;
     const diagnostics = [];
     // Spec-level diagnostics: check for non-strict input schemas
     for (const r of route_specs) {
@@ -98,7 +97,7 @@ export const generate_app_surface = (options) => {
                 .map((m) => m.name);
             // Merge auto-derived + middleware + explicit error schemas
             const mw_errors = collect_middleware_errors(middleware_specs, r.path);
-            const merged_errors = merge_error_schemas(r, mw_errors, is_acting_aware?.(r) ?? false);
+            const merged_errors = merge_error_schemas(r, mw_errors);
             let error_schemas = null;
             if (merged_errors) {
                 const schemas = {};
@@ -133,7 +132,7 @@ export const generate_app_surface = (options) => {
                 path: ep.path,
                 methods: ep.actions.map((a) => ({
                     name: a.spec.method,
-                    auth: map_action_auth(a.spec.auth),
+                    auth: a.spec.auth,
                     input_schema: schema_to_surface(a.spec.input),
                     output_schema: schema_to_surface(a.spec.output),
                     side_effects: a.spec.side_effects,

package/dist/http/surface_query.d.ts

@@ -4,49 +4,48 @@
  * Usable in tests, the adversarial auth runner, and future surface explorer UI.
  * Replaces duplicated inline `.filter()` patterns.
  *
- * TODO @surface-explorer Used by test utilities (test_auth_surface, adversarial_input,
- * surface_invariants) and SurfaceExplorer.svelte (surface_auth_summary, format_route_key).
- * Several query functions (filter_authenticated_routes, filter_keeper_routes,
- * routes_by_auth_type, filter_routes_by_prefix) are pre-built for richer surface
- * explorer features and consumer test suites — leverage more as the surface UI matures.
+ * Categorical filters (`filter_authenticated_routes`, `filter_role_routes`,
+ * `filter_keeper_routes`) group the new flat-record `RouteAuth` shape into
+ * the legacy categorical buckets (`'authenticated'`, `'role'`, `'keeper'`)
+ * for adversarial test runners and the surface explorer. The buckets are
+ * derived views over the four axes (`account`, `actor`, `roles`,
+ * `credential_types`) — see `http/auth_shape.ts` for the canonical shape.
  *
  * @module
  */
 import type { AppSurface, AppSurfaceRoute } from './surface.js';
 /** Filter routes that require any form of authentication. */
 export declare const filter_protected_routes: (surface: AppSurface) => Array<AppSurfaceRoute>;
-/** Filter routes that are publicly accessible (no auth). */
+/** Filter routes that are publicly accessible (no auth surface at all). */
 export declare const filter_public_routes: (surface: AppSurface) => Array<AppSurfaceRoute>;
-/** Filter all role-guarded routes (any role). */
-export declare const filter_role_routes: (surface: AppSurface) => Array<AppSurfaceRoute & {
-    auth: {
-        type: "role";
-        role: string;
-    };
-}>;
-/** Filter routes that require basic authentication (no specific role). */
-export declare const filter_authenticated_routes: (surface: AppSurface) => Array<AppSurfaceRoute & {
-    auth: {
-        type: "authenticated";
-    };
-}>;
-/** Filter routes that require keeper credentials. */
-export declare const filter_keeper_routes: (surface: AppSurface) => Array<AppSurfaceRoute & {
-    auth: {
-        type: "keeper";
-    };
-}>;
-/** Filter routes that require a specific named role. */
-export declare const filter_routes_for_role: (surface: AppSurface, role: string) => Array<AppSurfaceRoute & {
-    auth: {
-        type: "role";
-        role: string;
-    };
-}>;
+/** Filter all role-guarded routes (any role declared on `auth.roles`). */
+export declare const filter_role_routes: (surface: AppSurface) => Array<AppSurfaceRoute>;
 /**
- * Group routes by auth type.
+ * Filter routes that require basic authentication only — `account === 'required'`
+ * with no role / credential gate.
+ */
+export declare const filter_authenticated_routes: (surface: AppSurface) => Array<AppSurfaceRoute>;
+/** Filter routes that require keeper credentials (`daemon_token`). */
+export declare const filter_keeper_routes: (surface: AppSurface) => Array<AppSurfaceRoute>;
+/** Filter routes whose `auth.roles` includes the named role. */
+export declare const filter_routes_for_role: (surface: AppSurface, role: string) => Array<AppSurfaceRoute>;
+/**
+ * Categorize a `RouteAuth` into one of the legacy auth buckets.
  *
- * @returns a map from auth type string to route arrays, with role routes keyed as `'role:name'`
+ * Returns:
+ * - `'none'` for fully public routes (account === 'none' && actor === 'none')
+ * - `'keeper'` when `credential_types` includes `'daemon_token'`
+ * - `'role:<name>'` for each role declared on `auth.roles` (multi-role specs
+ *   are emitted multiple times; callers that need single-bucket grouping
+ *   should pre-collapse)
+ * - `'authenticated'` for `account === 'required'` without role / credential gate
+ * - `'optional'` when either axis is `'optional'` and no other bucket fits
+ * - `'other'` as a last-resort bucket for shapes that don't match above
+ */
+export type RouteAuthCategory = 'none' | 'authenticated' | 'optional' | 'keeper' | `role:${string}` | 'other';
+/**
+ * Group routes by auth category (see `RouteAuthCategory`). Multi-role specs
+ * appear under each of their role buckets.
  */
 export declare const routes_by_auth_type: (surface: AppSurface) => Map<string, Array<AppSurfaceRoute>>;
 /** Filter routes whose path starts with `prefix`. */
@@ -66,12 +65,17 @@ export declare const format_route_key: (route: AppSurfaceRoute) => string;
 /**
  * Summarize route auth distribution across the surface.
  *
- * @returns counts by auth type, with role counts broken out by role name
+ * Categorical view over the four-axis flat record. Multi-role specs
+ * contribute one count per role they admit.
+ *
+ * @returns counts by auth category, with role counts broken out by role name
  */
 export declare const surface_auth_summary: (surface: AppSurface) => {
     none: number;
     authenticated: number;
+    optional: number;
     role: Map<string, number>;
     keeper: number;
+    other: number;
 };
 //# sourceMappingURL=surface_query.d.ts.map

package/dist/http/surface_query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface_query.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/surface_query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAE,eAAe,EAAC,MAAM,cAAc,CAAC;AAE9D,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAEtD,4DAA4D;AAC5D,eAAO,MAAM,oBAAoB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC3B,CAAC;AAEtD,iDAAiD;AACjD,eAAO,MAAM,kBAAkB,GAC9B,SAAS,UAAU,KACjB,KAAK,CAAC,eAAe,GAAG;IAAC,IAAI,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAA;CAAC,CAG7D,CAAC;AAEH,0EAA0E;AAC1E,eAAO,MAAM,2BAA2B,GACvC,SAAS,UAAU,KACjB,KAAK,CAAC,eAAe,GAAG;IAAC,IAAI,EAAE;QAAC,IAAI,EAAE,eAAe,CAAA;KAAC,CAAA;CAAC,CAGxD,CAAC;AAEH,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,GAChC,SAAS,UAAU,KACjB,KAAK,CAAC,eAAe,GAAG;IAAC,IAAI,EAAE;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAC,CAAA;CAAC,CAGjD,CAAC;AAEH,wDAAwD;AACxD,eAAO,MAAM,sBAAsB,GAClC,SAAS,UAAU,EACnB,MAAM,MAAM,KACV,KAAK,CAAC,eAAe,GAAG;IAAC,IAAI,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAA;CAAC,CAI7D,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,UAAU,KAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAY3F,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,uBAAuB,GACnC,SAAS,UAAU,EACnB,QAAQ,MAAM,KACZ,KAAK,CAAC,eAAe,CAA4D,CAAC;AAErF,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAEvD,wDAAwD;AACxD,eAAO,MAAM,yBAAyB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAExD,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAEvD,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CACtC,CAAC;AAE7C,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAEzD,iEAAiE;AACjE,eAAO,MAAM,gBAAgB,GAAI,OAAO,eAAe,KAAG,MAAyC,CAAC;AAEpG;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,UAAU,KACjB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAwBjF,CAAC"}
+{"version":3,"file":"surface_query.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/surface_query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAE,eAAe,EAAC,MAAM,cAAc,CAAC;AAQ9D,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC7B,CAAC;AAEvD,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC3B,CAAC;AAEtD,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC3B,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,2BAA2B,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CACrB,CAAC;AAEnE,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC3B,CAAC;AAEtD,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,GAAI,SAAS,UAAU,EAAE,MAAM,MAAM,KAAG,KAAK,CAAC,eAAe,CAC5B,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAC1B,MAAM,GACN,eAAe,GACf,UAAU,GACV,QAAQ,GACR,QAAQ,MAAM,EAAE,GAChB,OAAO,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,UAAU,KAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAmC3F,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,uBAAuB,GACnC,SAAS,UAAU,EACnB,QAAQ,MAAM,KACZ,KAAK,CAAC,eAAe,CAA4D,CAAC;AAErF,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAEvD,wDAAwD;AACxD,eAAO,MAAM,yBAAyB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAExD,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAEvD,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CACtC,CAAC;AAE7C,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAEzD,iEAAiE;AACjE,eAAO,MAAM,gBAAgB,GAAI,OAAO,eAAe,KAAG,MAAyC,CAAC;AAEpG;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,UAAU,KACjB;IACF,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CAqCd,CAAC"}

package/dist/http/surface_query.js

@@ -4,41 +4,69 @@
  * Usable in tests, the adversarial auth runner, and future surface explorer UI.
  * Replaces duplicated inline `.filter()` patterns.
  *
- * TODO @surface-explorer Used by test utilities (test_auth_surface, adversarial_input,
- * surface_invariants) and SurfaceExplorer.svelte (surface_auth_summary, format_route_key).
- * Several query functions (filter_authenticated_routes, filter_keeper_routes,
- * routes_by_auth_type, filter_routes_by_prefix) are pre-built for richer surface
- * explorer features and consumer test suites — leverage more as the surface UI matures.
+ * Categorical filters (`filter_authenticated_routes`, `filter_role_routes`,
+ * `filter_keeper_routes`) group the new flat-record `RouteAuth` shape into
+ * the legacy categorical buckets (`'authenticated'`, `'role'`, `'keeper'`)
+ * for adversarial test runners and the surface explorer. The buckets are
+ * derived views over the four axes (`account`, `actor`, `roles`,
+ * `credential_types`) — see `http/auth_shape.ts` for the canonical shape.
  *
  * @module
  */
+import { is_keeper_auth, is_plain_authenticated_auth, is_public_auth, is_role_auth, } from './auth_shape.js';
 /** Filter routes that require any form of authentication. */
-export const filter_protected_routes = (surface) => surface.routes.filter((r) => r.auth.type !== 'none');
-/** Filter routes that are publicly accessible (no auth). */
-export const filter_public_routes = (surface) => surface.routes.filter((r) => r.auth.type === 'none');
-/** Filter all role-guarded routes (any role). */
-export const filter_role_routes = (surface) => surface.routes.filter((r) => r.auth.type === 'role');
-/** Filter routes that require basic authentication (no specific role). */
-export const filter_authenticated_routes = (surface) => surface.routes.filter((r) => r.auth.type === 'authenticated');
-/** Filter routes that require keeper credentials. */
-export const filter_keeper_routes = (surface) => surface.routes.filter((r) => r.auth.type === 'keeper');
-/** Filter routes that require a specific named role. */
-export const filter_routes_for_role = (surface, role) => surface.routes.filter((r) => r.auth.type === 'role' && r.auth.role === role);
+export const filter_protected_routes = (surface) => surface.routes.filter((r) => !is_public_auth(r.auth));
+/** Filter routes that are publicly accessible (no auth surface at all). */
+export const filter_public_routes = (surface) => surface.routes.filter((r) => is_public_auth(r.auth));
+/** Filter all role-guarded routes (any role declared on `auth.roles`). */
+export const filter_role_routes = (surface) => surface.routes.filter((r) => is_role_auth(r.auth));
 /**
- * Group routes by auth type.
- *
- * @returns a map from auth type string to route arrays, with role routes keyed as `'role:name'`
+ * Filter routes that require basic authentication only — `account === 'required'`
+ * with no role / credential gate.
+ */
+export const filter_authenticated_routes = (surface) => surface.routes.filter((r) => is_plain_authenticated_auth(r.auth));
+/** Filter routes that require keeper credentials (`daemon_token`). */
+export const filter_keeper_routes = (surface) => surface.routes.filter((r) => is_keeper_auth(r.auth));
+/** Filter routes whose `auth.roles` includes the named role. */
+export const filter_routes_for_role = (surface, role) => surface.routes.filter((r) => r.auth.roles?.includes(role) ?? false);
+/**
+ * Group routes by auth category (see `RouteAuthCategory`). Multi-role specs
+ * appear under each of their role buckets.
  */
 export const routes_by_auth_type = (surface) => {
     const groups = new Map();
-    for (const r of surface.routes) {
-        const key = r.auth.type === 'role' ? `role:${r.auth.role}` : r.auth.type;
+    const push = (key, r) => {
         let group = groups.get(key);
         if (!group) {
             group = [];
             groups.set(key, group);
         }
         group.push(r);
+    };
+    for (const r of surface.routes) {
+        const auth = r.auth;
+        if (is_public_auth(auth)) {
+            push('none', r);
+            continue;
+        }
+        if (is_keeper_auth(auth)) {
+            push('keeper', r);
+            continue;
+        }
+        if (is_role_auth(auth)) {
+            for (const role of auth.roles)
+                push(`role:${role}`, r);
+            continue;
+        }
+        if (is_plain_authenticated_auth(auth)) {
+            push('authenticated', r);
+            continue;
+        }
+        if (auth.account === 'optional' || auth.actor === 'optional') {
+            push('optional', r);
+            continue;
+        }
+        push('other', r);
     }
     return groups;
 };
@@ -59,28 +87,43 @@ export const format_route_key = (route) => `${route.method} ${route.path}`;
 /**
  * Summarize route auth distribution across the surface.
  *
- * @returns counts by auth type, with role counts broken out by role name
+ * Categorical view over the four-axis flat record. Multi-role specs
+ * contribute one count per role they admit.
+ *
+ * @returns counts by auth category, with role counts broken out by role name
  */
 export const surface_auth_summary = (surface) => {
     let none = 0;
     let authenticated = 0;
+    let optional = 0;
     const role = new Map();
     let keeper = 0;
+    let other = 0;
     for (const r of surface.routes) {
-        switch (r.auth.type) {
-            case 'none':
-                none++;
-                break;
-            case 'authenticated':
-                authenticated++;
-                break;
-            case 'role':
-                role.set(r.auth.role, (role.get(r.auth.role) ?? 0) + 1);
-                break;
-            case 'keeper':
-                keeper++;
-                break;
+        const auth = r.auth;
+        if (is_public_auth(auth)) {
+            none++;
+            continue;
+        }
+        if (is_keeper_auth(auth)) {
+            keeper++;
+            continue;
+        }
+        if (is_role_auth(auth)) {
+            for (const r_name of auth.roles) {
+                role.set(r_name, (role.get(r_name) ?? 0) + 1);
+            }
+            continue;
+        }
+        if (is_plain_authenticated_auth(auth)) {
+            authenticated++;
+            continue;
+        }
+        if (auth.account === 'optional' || auth.actor === 'optional') {
+            optional++;
+            continue;
         }
+        other++;
     }
-    return { none, authenticated, role, keeper };
+    return { none, authenticated, optional, role, keeper, other };
 };