@fuzdev/fuz_app 0.54.0 → 0.56.0

package/dist/server/app_server.js

@@ -25,8 +25,10 @@ import { create_app_surface_spec, } from '../http/surface.js';
 import { apply_middleware_specs, apply_route_specs, prefix_route_specs, } from '../http/route_spec.js';
 import { check_bootstrap_status, create_bootstrap_route_specs, } from '../auth/bootstrap_routes.js';
 import { create_surface_route_spec } from '../http/common_routes.js';
+import { flush_pending_effects, flush_post_commit_effects } from '../http/pending_effects.js';
 import { create_auth_middleware_specs } from '../auth/middleware.js';
-import { fuz_auth_guard_resolver } from '../auth/route_guards.js';
+import { fuz_auth_guard_resolver } from '../auth/auth_guard_resolver.js';
+import { create_fuz_authorization_handler } from '../auth/request_context.js';
 import { ERROR_PAYLOAD_TOO_LARGE } from '../http/error_schemas.js';
 import { create_rpc_endpoint } from '../actions/action_rpc.js';
 /** Default maximum request body size: 1 MiB. */
@@ -39,15 +41,15 @@ export const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
  * static serving. Database migrations belong to the backend lifecycle —
  * pass `migration_namespaces` to `create_app_backend`.
  *
- * When `audit_log_sse` is set, shallow-copies `backend.deps` with a composed
- * `on_audit_event` that fans out to the SSE registry and the original
- * callback — `backend.deps` itself is not mutated.
+ * When `audit_log_sse` is set, the SSE registry's listener is appended to
+ * `backend.deps.audit.on_event_chain` — no shallow-copy of `AppDeps`.
  *
  * @returns assembled Hono app, backend, surface build, and bootstrap status
  */
 export const create_app_server = async (options) => {
     const { backend } = options;
-    const { log } = backend.deps;
+    const { deps } = backend;
+    const { log } = deps;
     // Rate limiter defaults (undefined = default, null = disable)
     const ip_rate_limiter = options.ip_rate_limiter === undefined ? create_rate_limiter() : options.ip_rate_limiter;
     const login_account_rate_limiter = options.login_account_rate_limiter === undefined
@@ -65,22 +67,18 @@ export const create_app_server = async (options) => {
     const action_account_rate_limiter = options.action_account_rate_limiter === undefined
         ? create_rate_limiter(DEFAULT_ACTION_ACCOUNT_RATE_LIMIT)
         : options.action_account_rate_limiter;
-    // Factory-managed audit SSE (shallow copy deps, no mutation of backend.deps)
+    // Factory-managed audit SSE — appends a listener to the bound emitter's
+    // chain so SSE fan-out runs alongside the consumer's `on_audit_event`
+    // without rebuilding `AppDeps`.
     const audit_sse = options.audit_log_sse
         ? create_audit_log_sse({
             log,
             role: typeof options.audit_log_sse === 'object' ? options.audit_log_sse.role : undefined,
         })
         : null;
-    const deps = audit_sse
-        ? {
-            ...backend.deps,
-            on_audit_event: (event) => {
-                audit_sse.on_audit_event(event);
-                backend.deps.on_audit_event(event);
-            },
-        }
-        : backend.deps;
+    if (audit_sse) {
+        deps.audit.on_event_chain.push(audit_sse.on_audit_event);
+    }
     // Proxy middleware
     const proxy_spec = create_proxy_middleware_spec({ ...options.proxy, log });
     // Auth middleware
@@ -215,31 +213,37 @@ export const create_app_server = async (options) => {
     log_startup_summary(surface_spec.surface, log, options.env_values);
     // Hono app assembly
     const app = new Hono();
-    // Pending effects — collects fire-and-forget promises (audit logs, usage tracking).
-    // In test mode, effects are awaited before the response returns.
-    // In production, rejected effects are reported via on_effect_error.
+    // Two-queue side-effect flush. `pending_effects` collects eager
+    // fire-and-forget promises (audit emits, session touch, api-token
+    // usage). `post_commit_effects` collects deferred thunks pushed via
+    // `emit_after_commit` (WS notifications, anything that must observe a
+    // committed transaction). Both queues drain here, after the handler
+    // (and any wrapping `db.transaction`) returns. In test mode both are
+    // awaited before the response returns; in production, eager-queue
+    // rejections are reported via `on_effect_error`.
     app.use('*', async (c, next) => {
         c.set('pending_effects', []);
+        c.set('post_commit_effects', []);
         try {
             await next();
         }
         finally {
-            const effects = c.var.pending_effects;
-            if (effects.length) {
+            const eager = c.var.pending_effects;
+            const deferred = c.var.post_commit_effects;
+            if (eager.length || deferred.length) {
                 if (options.await_pending_effects) {
-                    await Promise.allSettled(effects);
+                    await flush_pending_effects(eager, log);
+                    await flush_post_commit_effects(deferred, log);
                 }
                 else {
-                    const ctx = { method: c.req.method, path: c.req.path };
+                    const error_ctx = { method: c.req.method, path: c.req.path };
                     const callback = options.on_effect_error;
-                    void Promise.allSettled(effects).then((results) => {
-                        for (const result of results) {
-                            if (result.status === 'rejected') {
-                                log.error('Pending effect rejected:', result.reason, ctx);
-                                callback?.(result.reason, ctx);
-                            }
-                        }
-                    });
+                    void flush_pending_effects(eager, log, callback ? (reason) => callback(reason, error_ctx) : undefined);
+                    // `flush_post_commit_effects` is non-throwing: per-thunk
+                    // errors are routed through `log.error` inside the helper,
+                    // so production fire-and-forget skips the `on_effect_error`
+                    // fan-out (deferred thunks are wrapped end-to-end already).
+                    void flush_post_commit_effects(deferred, log);
                 }
             }
         }
@@ -257,7 +261,8 @@ export const create_app_server = async (options) => {
         }));
     }
     apply_middleware_specs(app, middleware_specs);
-    apply_route_specs(app, route_specs, fuz_auth_guard_resolver, log, deps.db);
+    const authorize = create_fuz_authorization_handler({ db: deps.db });
+    apply_route_specs(app, route_specs, fuz_auth_guard_resolver, log, deps.db, authorize);
     // Post-route middleware (before static serving)
     if (options.post_route_middleware) {
         apply_middleware_specs(app, options.post_route_middleware);

package/dist/server/validate_nginx.d.ts

@@ -24,7 +24,7 @@ export interface NginxValidationResult {
  *
  * Checks for required security headers, Authorization stripping in `/api`
  * blocks, and the nginx `add_header` inheritance gotcha. Designed for
- * fuz_app consumer deploy configs (tx.ts `NGINX_CONFIG` constants).
+ * fuz_app consumer deploy configs (zap.ts `NGINX_CONFIG` constants).
  *
  * Limitations: string pattern matching, not a real nginx parser. Catches
  * common omissions in fuz_app deploy configs but won't catch all possible

package/dist/server/validate_nginx.js

@@ -92,7 +92,7 @@ const location_matches_api = (block) => {
  *
  * Checks for required security headers, Authorization stripping in `/api`
  * blocks, and the nginx `add_header` inheritance gotcha. Designed for
- * fuz_app consumer deploy configs (tx.ts `NGINX_CONFIG` constants).
+ * fuz_app consumer deploy configs (zap.ts `NGINX_CONFIG` constants).
  *
  * Limitations: string pattern matching, not a real nginx parser. Catches
  * common omissions in fuz_app deploy configs but won't catch all possible

package/dist/testing/CLAUDE.md

@@ -36,8 +36,10 @@ module load.
 | `create_stub_db()`                                    | Returns a real `Db` whose `client.query` yields `{rows: []}` and whose `transaction(fn)` synchronously calls `fn(inner_stub_db)`. Safe for `apply_route_specs`'s declarative transaction wrapper.                                                                                                                                                                                                                                                                                                                                   |
 | `stub_handler()`                                      | Returns a fresh `Response('stub')`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `stub_mw`                                             | Pass-through middleware handler (`async (_c, next) => next()`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `stub_app_deps`                                       | Frozen `AppDeps` — every capability is a throwing stub, `on_audit_event` is a noop.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `create_stub_app_deps()`                              | Factory returning fresh `AppDeps` with no-op FS/keyring/password, a `create_noop_stub` DB, silent `Logger`.                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `stub_app_deps`                                       | Frozen `AppDeps` — every capability is a throwing stub, `audit` is a no-op `AuditEmitter` from `create_test_audit_emitter`.                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `create_stub_app_deps()`                              | Factory returning fresh `AppDeps` with no-op FS/keyring/password, a `create_noop_stub` DB, silent `Logger`, no-op `audit`.                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `create_test_audit_emitter()`                         | No-op `AuditEmitter` for tests that don't assert on audit fan-out. `emit` / `emit_role_grant_target` are no-ops; `emit_pool` resolves immediately; `notify` is a no-op; `on_event_chain` is empty.                                                                                                                                                                                                                                                                                                                                  |
+| `create_stub_audit_sse()`                             | No-op `AuditLogSse` for surface-test wiring without booting real SSE. `subscribe` returns a no-op cleanup; `on_audit_event` is a no-op; the `registry` is a fresh `SubscriberRegistry` (live `.size` / `.close_*` for tests touching registry state, isolated per call). For real SSE plumbing, build via `create_audit_log_sse` against `create_test_app`.                                                                                                                                                                         |
 | `create_stub_api_middleware({include_daemon_token?})` | Stub `MiddlewareSpec[]` matching `create_auth_middleware_specs`'s output (origin/session/request_context/bearer_auth, optional daemon_token) for surface generation without booting real auth. See `../auth/CLAUDE.md` §Middleware for the real stack.                                                                                                                                                                                                                                                                              |
 | `create_stub_app_server_context(session_options)`     | Stub `AppServerContext` — rate limiters null, `bootstrap_status.available: false`, `app_settings.open_signup: false`.                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `create_test_app_surface_spec(options)`               | Builds an `AppSurfaceSpec` that mirrors `create_app_server`'s route assembly: consumer routes + factory-managed bootstrap routes (prefixed via `bootstrap_route_prefix`, default `'/api/account'`) + stub middleware + surface generation. `CreateTestAppSurfaceSpecOptions` accepts `session_options`, `create_route_specs`, `env_schema?`, `event_specs?`, `rpc_endpoints?`, `transform_middleware?`, `bootstrap_route_prefix?`. Single source of truth for attack-surface tests — track `create_app_server` wiring changes here. |
@@ -58,14 +60,14 @@ factories.
 Override types widen branded `Uuid` fields to `string` so tests pass
 literal ids without per-site casts — the factory brands internally.
 Exported as `TestAccountOverrides` / `TestActorOverrides` /
-`TestPermitOverrides` / `TestAuditEventOverrides`.
+`TestRoleGrantOverrides` / `TestAuditEventOverrides`.
 
 | Factory                               | Default id / role                                                                             |
 | ------------------------------------- | --------------------------------------------------------------------------------------------- |
 | `create_test_account(overrides?)`     | `{id: 'acct-test', username: 'test_user', …}`                                                 |
 | `create_test_actor(overrides?)`       | `{id: 'actor-test', account_id: 'acct-test', …}`                                              |
-| `create_test_permit(overrides?)`      | `{id: 'permit-test', actor_id: 'actor-test', role: 'admin', scope_id: null, …}`               |
-| `create_test_context(permits?)`       | `{account, actor, permits}` — pass `[{role: 'keeper'}, {role: 'admin'}]` for multi-role.      |
+| `create_test_role_grant(overrides?)`  | `{id: 'role-grant-test', actor_id: 'actor-test', role: 'admin', scope_id: null, …}`           |
+| `create_test_context(role_grants?)`   | `{account, actor, role_grants}` — pass `[{role: 'keeper'}, {role: 'admin'}]` for multi-role.  |
 | `create_test_audit_event(overrides?)` | `{id: 'evt-test', event_type: 'login', outcome: 'success', …}` — for SSE guard / audit tests. |
 
 ### `mock_fs.ts` — in-memory filesystem
@@ -75,6 +77,17 @@ Missing-path reads throw an `Error` with `.code = 'ENOENT'` so callers
 exercise the same branches as `node:fs`. Use for DI-based filesystem
 tests; never replaces `node:fs` globally.
 
+### `db_entities.ts` — DB-backed entity factories
+
+`create_test_account_with_actor(db, {username, password_hash?})` wraps
+`query_create_account_with_actor` with a default `password_hash` (`'hash'`).
+Returns `{account, actor}`. Replaces the per-file `create_user` /
+`create_test_actor` / `create_test_account` helpers that had accumulated
+across the auth test suite. Use for query-level tests that need real
+DB rows but not a full session/token bundle. For tests that also need
+an API token + session cookie + role_grants, use `bootstrap_test_account`
+from `app_server.ts` instead.
+
 ## Database — `db.ts`
 
 Factory builders for parameterized DB tests. Consumer projects pass their
@@ -88,7 +101,7 @@ factories accept any migration namespace set.
 | `reset_pglite(db)`                               | `DROP SCHEMA public CASCADE` + recreate. Reuses a live PGlite instance.                                                                                                                                                                                                                              |
 | `create_pglite_factory(init_schema)`             | In-memory; no external deps; `skip: false`. See WASM caching below.                                                                                                                                                                                                                                  |
 | `create_pg_factory(init_schema, test_url?)`      | PostgreSQL; `skip: true` when `test_url` is missing; drops `schema_version` before `init_schema` so migrations re-evaluate against actual tables (prevents stale tracker rows from skipping migrations when DDL changes between test sessions); pool is reused + cleaned up across `create()` calls. |
-| `AUTH_TRUNCATE_TABLES`                           | `['invite', 'api_token', 'auth_session', 'permit', 'permit_offer', 'actor', 'account']` in FK-safe order. Excludes `audit_log` — unit DB tests don't need to truncate it.                                                                                                                            |
+| `AUTH_TRUNCATE_TABLES`                           | `['invite', 'api_token', 'auth_session', 'role_grant', 'role_grant_offer', 'actor', 'account']` in FK-safe order. Excludes `audit_log` — unit DB tests don't need to truncate it.                                                                                                                    |
 | `AUTH_INTEGRATION_TRUNCATE_TABLES`               | `AUTH_TRUNCATE_TABLES + ['audit_log']` — for integration suites that exercise the audit path.                                                                                                                                                                                                        |
 | `AUTH_DROP_TABLES`                               | Full set from `AUTH_MIGRATIONS` in drop order; call `drop_auth_schema(db)` at the top of `init_schema` on persistent pg databases that may hold stale DDL from previous fuz_app versions.                                                                                                            |
 | `drop_auth_schema(db)`                           | `DROP TABLE IF EXISTS <table> CASCADE` for every entry in `AUTH_DROP_TABLES` plus `schema_version`. Safe on fresh DBs.                                                                                                                                                                               |
@@ -157,16 +170,20 @@ bind to the server's deps (db, keyring). Hono assembly is cheap
 
 Pre-built Hono apps at each auth level (public / authed / keeper / per-role)
 for attack-surface testing. No middleware stack — a single `/*` middleware
-injects the `REQUEST_CONTEXT_KEY` + `CREDENTIAL_TYPE_KEY` (default
-`'session'`) and hands off to `apply_route_specs` with
-`fuz_auth_guard_resolver`.
+injects `ACCOUNT_ID_KEY` + `REQUEST_CONTEXT_KEY` + `CREDENTIAL_TYPE_KEY`
+(default `'session'`) plus the `TEST_CONTEXT_PRESET_KEY` flag (so the
+dispatcher's authorization phase trusts the pre-baked context and skips
+its DB-backed actor resolution), then hands off to `apply_route_specs`
+with `fuz_auth_guard_resolver` + `create_fuz_authorization_handler`.
+Production middleware never sets `TEST_CONTEXT_PRESET_KEY`, so the escape
+hatch is test-only by construction.
 
 | Helper                                                           | Role                                                                                                                                                                                   |
 | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `create_test_request_context(role?)`                             | Minimal `RequestContext` — one account, one actor, one permit for `role` (or none).                                                                                                    |
+| `create_test_request_context(role?)`                             | Minimal `RequestContext` — one account, one actor, one role_grant for `role` (or none).                                                                                                |
 | `create_test_app_from_specs(specs, auth_ctx?, credential_type?)` | Hono app with pre-set context + `apply_route_specs`. `credential_type` defaults to `'session'` when an auth context is supplied — override for `'daemon_token'` / `'api_token'` tests. |
 | `AuthTestApps`                                                   | `{public, authed, keeper, by_role: Map<string, Hono>}`.                                                                                                                                |
-| `create_auth_test_apps(specs, roles)`                            | Builds one app per auth level. Keeper app uses `credential_type: 'daemon_token'` so `require_keeper` passes.                                                                           |
+| `create_auth_test_apps(specs, roles)`                            | Builds one app per auth level. Keeper app uses `credential_type: 'daemon_token'` so `require_credential_types(['daemon_token'])` passes.                                               |
 | `select_auth_app(apps, auth)`                                    | Map `RouteAuth` → matching Hono app. Throws for missing `role:*` entries.                                                                                                              |
 | `resolve_test_path(path)`                                        | `:foo` → `test_foo` — adequate for routes without format-constrained params.                                                                                                           |
 
@@ -297,20 +314,20 @@ Walks Zod schemas to generate valid values for adversarial/round-trip tests.
 
 ### `integration_helpers.ts` — route lookup + body checks
 
-| Helper                                                             | Role                                                                                                                                                                                                                                                 |
-| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `find_route_spec(specs, method, path)`                             | Exact match then parameterized match (`:foo` matches any segment).                                                                                                                                                                                   |
-| `find_auth_route(specs, suffix, method)`                           | Suffix-ending match for REST auth routes — decouples tests from consumer prefix. `suffix` is typed as `RestAuthRouteSuffix` and throws at runtime on unknown values (post-RPC-migration, only login/logout/password/verify/signup/bootstrap remain). |
-| `assert_response_matches_spec(specs, method, path, response)`      | 2xx → validates against `spec.output`; non-2xx → validates against merged error schemas for that status. Non-JSON responses allowed only when no schema applies.                                                                                     |
-| `create_expired_test_cookie(keyring, session_options)`             | Validly signed cookie with `expires_at` in 1970.                                                                                                                                                                                                     |
-| `check_error_response_fields(body)`                                | Returns the list of fields outside `KNOWN_SAFE_ERROR_FIELDS` (`error`, `issues`, `required_role`, `retry_after`, `credential_type`, `has_references`, `ok`).                                                                                         |
-| `assert_no_error_info_leakage(body, context)`                      | Rejects field-name patterns (`stack`, `trace`, `sql`, …) + value patterns (`node_modules`, stack-like `at …`, `.ts:NN`).                                                                                                                             |
-| `assert_rate_limit_retry_after_header(response, body)`             | `Retry-After` numeric header equals `Math.ceil(body.retry_after)`.                                                                                                                                                                                   |
-| `SENSITIVE_FIELD_BLOCKLIST`                                        | `['password_hash', 'token_hash']` — never in any response body.                                                                                                                                                                                      |
-| `ADMIN_ONLY_FIELD_BLOCKLIST`                                       | `['updated_by', 'created_by']` — never in non-admin response bodies.                                                                                                                                                                                 |
-| `collect_json_keys_recursive(value)`                               | Deep walk; returns `Set<string>` of every key at every nesting depth.                                                                                                                                                                                |
-| `assert_no_sensitive_fields_in_json(body, blocklist, context)`     | Rejects any key in the blocklist at any depth.                                                                                                                                                                                                       |
-| `pick_auth_headers(spec, test_app, authed_account, admin_account)` | `RouteAuth` → appropriate test credentials; role `admin` uses `admin_account`, other roles use bootstrapped keeper, `keeper` uses daemon token.                                                                                                      |
+| Helper                                                             | Role                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `find_route_spec(specs, method, path)`                             | Exact match then parameterized match (`:foo` matches any segment).                                                                                                                                                                       |
+| `find_auth_route(specs, suffix, method)`                           | Suffix-ending match for REST auth routes — decouples tests from consumer prefix. `suffix` is typed as `RestAuthRouteSuffix` and throws at runtime on unknown values (only login/logout/password/verify/signup/bootstrap remain on REST). |
+| `assert_response_matches_spec(specs, method, path, response)`      | 2xx → validates against `spec.output`; non-2xx → validates against merged error schemas for that status. Non-JSON responses allowed only when no schema applies.                                                                         |
+| `create_expired_test_cookie(keyring, session_options)`             | Validly signed cookie with `expires_at` in 1970.                                                                                                                                                                                         |
+| `check_error_response_fields(body)`                                | Returns the list of fields outside `KNOWN_SAFE_ERROR_FIELDS` (`error`, `issues`, `required_roles`, `required_credential_types`, `retry_after`, `has_references`, `ok`).                                                                  |
+| `assert_no_error_info_leakage(body, context)`                      | Rejects field-name patterns (`stack`, `trace`, `sql`, …) + value patterns (`node_modules`, stack-like `at …`, `.ts:NN`).                                                                                                                 |
+| `assert_rate_limit_retry_after_header(response, body)`             | `Retry-After` numeric header equals `Math.ceil(body.retry_after)`.                                                                                                                                                                       |
+| `SENSITIVE_FIELD_BLOCKLIST`                                        | `['password_hash', 'token_hash']` — never in any response body.                                                                                                                                                                          |
+| `ADMIN_ONLY_FIELD_BLOCKLIST`                                       | `['updated_by', 'created_by']` — never in non-admin response bodies.                                                                                                                                                                     |
+| `collect_json_keys_recursive(value)`                               | Deep walk; returns `Set<string>` of every key at every nesting depth.                                                                                                                                                                    |
+| `assert_no_sensitive_fields_in_json(body, blocklist, context)`     | Rejects any key in the blocklist at any depth.                                                                                                                                                                                           |
+| `pick_auth_headers(spec, test_app, authed_account, admin_account)` | `RouteAuth` → appropriate test credentials; role `admin` uses `admin_account`, other roles use bootstrapped keeper, `keeper` uses daemon token.                                                                                          |
 
 ## Attack surface suites
 
@@ -383,28 +400,30 @@ validation. Extra cases append to the standard list.
 ## Middleware stack — `middleware.ts`
 
 Module-level `vi.mock()` for the four query modules bearer auth touches:
-`api_token_queries`, `account_queries`, `permit_queries`. Because
+`api_token_queries`, `account_queries`, `role_grant_queries`. Because
 `vi.mock()` is hoisted, these run before any imports resolve — so any
 test file that imports from `middleware.ts` gets these mocks globally.
 Pair with `vi.restoreAllMocks()` in `afterEach` when mixing into
 `.db.test.ts` files (see DB test caveat below).
 
-| Helper                                                            | Role                                                                                                                                                          |
-| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BearerAuthTestOptions`, `BearerAuthTestCase`                     | Test-case table shape for the bearer auth runner.                                                                                                             |
-| `create_bearer_auth_mocks(tc)`                                    | Configures the module-level mocks per test case; returns spy references.                                                                                      |
-| `TEST_CLIENT_IP = '127.0.0.1'`                                    | IP set by the proxy stub in `create_bearer_auth_test_app`.                                                                                                    |
-| `create_bearer_auth_test_app(tc, ip_rate_limiter?)`               | Hono app with bearer middleware + echo route at `/api/test` returning `{ok, has_context, credential_type, account_id, actor_id, permit_count, api_token_id}`. |
-| `describe_bearer_auth_cases(suite_name, cases, ip_rate_limiter?)` | Table-driven runner — one `test()` per case; asserts status, error, body fields, `api_token_id`, context preservation.                                        |
-| `TEST_MIDDLEWARE_PATH = '/api/test'`                              | Path used by the echo route in the stack factory.                                                                                                             |
-| `create_test_middleware_stack_app(options?)`                      | Real proxy + origin + bearer middleware for integration-shape testing. Echo route returns `{ok, client_ip, has_context}`.                                     |
+| Helper                                                            | Role                                                                                                                                                                                                                                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `BearerAuthTestOptions`, `BearerAuthTestCase`                     | Test-case table shape for the bearer auth runner.                                                                                                                                                                                                                              |
+| `create_bearer_auth_mocks(tc)`                                    | Configures the module-level mocks per test case; returns spy references.                                                                                                                                                                                                       |
+| `TEST_CLIENT_IP = '127.0.0.1'`                                    | IP set by the proxy stub in `create_bearer_auth_test_app`.                                                                                                                                                                                                                     |
+| `create_bearer_auth_test_app(tc, ip_rate_limiter?)`               | Hono app with bearer middleware + echo route at `/api/test` returning `{ok, account_id, credential_type, api_token_id, request_context_set}` — the account-grain identity bearer auth writes, plus a flag for tests that pre-populate `REQUEST_CONTEXT_KEY` via `pre_context`. |
+| `describe_bearer_auth_cases(suite_name, cases, ip_rate_limiter?)` | Table-driven runner — one `test()` per case; asserts status, error, body fields, `api_token_id`, context preservation.                                                                                                                                                         |
+| `TEST_MIDDLEWARE_PATH = '/api/test'`                              | Path used by the echo route in the stack factory.                                                                                                                                                                                                                              |
+| `create_test_middleware_stack_app(options?)`                      | Real proxy + origin + bearer middleware for integration-shape testing. Echo route returns `{ok, client_ip, has_context}`.                                                                                                                                                      |
 
 The echo route under `create_bearer_auth_test_app` deliberately surfaces
-every middleware-written context variable (`REQUEST_CONTEXT_KEY`,
-`CREDENTIAL_TYPE_KEY`, `AUTH_API_TOKEN_ID_KEY`). When public auth surface
-gains a new context variable, header, or field, update this echo
-alongside the assertions in `src/test/auth/*.test.ts` — the two move
-together.
+every middleware-written context variable (`ACCOUNT_ID_KEY`,
+`CREDENTIAL_TYPE_KEY`, `AUTH_API_TOKEN_ID_KEY`) — bearer middleware
+writes account-grain identity only; the dispatcher's authorization phase
+owns `REQUEST_CONTEXT_KEY`. The `request_context_set` flag covers the
+test-only `pre_context` injection path. When public auth surface gains a
+new context variable, header, or field, update this echo alongside the
+assertions in `src/test/auth/*.test.ts` — the two move together.
 
 ## Round-trip suites
 
@@ -464,7 +483,7 @@ Three layers:
 1. **Primitives** — `create_fake_ws()`, `create_fake_hono_context(opts)`,
    `create_stub_upgrade()`, `MinimalActionEnvironment`,
    `dispatch_ws_message(on_message, event, ws)`.
-2. **Harness** — `create_ws_test_harness<TCtx>({actions, extend_context?, transport?, heartbeat?, log?, on_socket_open?, on_socket_close?})` → `WsTestHarness`. `connect(identity?)` is async and resolves after `on_socket_open` completes, so broadcasts sent immediately after `await harness.connect()` reach the client.
+2. **Harness** — `create_ws_test_harness({actions, transport?, heartbeat?, log?, on_socket_open?, on_socket_close?})` → `WsTestHarness`. `connect(identity?)` is async and resolves after `on_socket_open` completes, so broadcasts sent immediately after `await harness.connect()` reach the client. The harness threads its own `create_stub_db()` into the dispatcher's `db` slot so handlers declaring `side_effects: true` execute under the same transaction wrap they would in production (the stub's `transaction(fn)` synchronously calls `fn(stub_db)`); domain deps reach handlers via factory closures, the same way HTTP RPC factories already wire them. Audit fan-out runs through whatever `audit` emitter the consumer supplied to its action factory closure (typically `create_test_audit_emitter()` for unit harnesses).
 3. **Round-trip helpers** — `is_notification(method)`,
    `is_notification_with<P>(method, match)` (type-guard combinator —
    narrows `wait_for` return type), `is_response_for(id)`.
@@ -551,9 +570,9 @@ Options: `{session_options, create_route_specs, app_options?, db_factories?}`.
 
 ### `admin_integration.ts` — `describe_standard_admin_integration_tests`
 
-7 test groups covering admin surface: account listing, permit grant
-lifecycle (via `permit_offer_create` + `permit_revoke` RPC flows —
-**not** REST; see `../auth/CLAUDE.md` for `permit_offer_action_specs.ts` + `permit_offer_actions.ts`), session / token management, audit log reads (RPC),
+7 test groups covering admin surface: account listing, role_grant grant
+lifecycle (via `role_grant_offer_create` + `role_grant_revoke` RPC flows —
+**not** REST; see `../auth/CLAUDE.md` for `role_grant_offer_action_specs.ts` + `role_grant_offer_actions.ts`), session / token management, audit log reads (RPC),
 admin-to-admin isolation, error coverage, response schema validation.
 
 Required options: `{session_options, create_route_specs, roles: RoleSchemaResult, rpc_endpoints: RpcEndpointsSuiteOption, admin_prefix?, app_options?, db_factories?}`.
@@ -571,22 +590,21 @@ once with a stub ctx for path lookup and `create_app_server` invokes it
 again per-test for live dispatch.
 
 **Hard-fails via `require_rpc_endpoint_path`** at setup time when
-`rpc_endpoints` is empty — admin permit grant/revoke plus session/token
-revoke-all plus audit-log list/history are all RPC-only since the
-2026-04-22 migration. A confusing test failure mid-suite is worse than a
-clear setup error.
+`rpc_endpoints` is empty — admin role_grant grant/revoke plus session/token
+revoke-all plus audit-log list/history are RPC-only. A confusing test
+failure mid-suite is worse than a clear setup error.
 
 The suite also exercises `account_token_create` (and
 `account_token_revoke`) for the cross-admin isolation + audit-trail
-scenarios. Wire the account actions alongside admin / permit-offer —
+scenarios. Wire the account actions alongside admin / role-grant-offer —
 the easiest path is `create_standard_rpc_actions`, which bundles all
 three. Consumers that only wire admin will hit `method not found:
 account_token_create` on first run.
 
 Error-coverage scope is narrowed to the REST suffixes still on the
 admin surface (`/audit/stream`); the RPC surface is covered by
-`describe_rpc_round_trip_tests`. Post-RPC-migration that surface is
-0–1 routes — when the scoped count is ≤1, the `afterAll` hook logs
+`describe_rpc_round_trip_tests`. The scoped REST surface is 0–1
+routes — when the scoped count is ≤1, the `afterAll` hook logs
 `[error coverage] skipped admin REST coverage assertion — …` and
 does not fail. The 20% `DEFAULT_INTEGRATION_ERROR_COVERAGE` baseline
 is a REST-era threshold; the RPC surface has its own coverage via
@@ -599,9 +617,9 @@ branch.
 Verifies every auth mutation produces the expected `audit_log` row by
 querying the table after each request. Uses the real middleware stack.
 Same `rpc_endpoints` hard-fail as the admin suite — the mutation-audit
-tests drive permit flow, session/token revoke-all, and invite
-create/delete through `permit_offer_create_action_spec` /
-`permit_revoke_action_spec` / `admin_session_revoke_all_action_spec` /
+tests drive role_grant flow, session/token revoke-all, and invite
+create/delete through `role_grant_offer_create_action_spec` /
+`role_grant_revoke_action_spec` / `admin_session_revoke_all_action_spec` /
 `admin_token_revoke_all_action_spec` / `app_settings_update_action_spec` /
 `invite_create_action_spec` / `invite_delete_action_spec`.
 
@@ -670,7 +688,7 @@ Registry lookups:
    - unauthenticated → `unauthenticated` (code -32001)
    - wrong role → `forbidden` (-32002)
    - authenticated without role → `forbidden`
-   - **keeper rejects non-daemon credentials** — session and api_token credentials are rejected even when the account has the keeper role (only `daemon_token` passes). Mirrors `require_keeper`'s two-part guard (see `../auth/CLAUDE.md` for `require_keeper.ts`).
+   - **keeper rejects non-daemon credentials** — session and api_token credentials are rejected even when the account has the keeper role (only `daemon_token` passes). The credential-type gate fires before the role gate (see `../auth/CLAUDE.md` §`request_context.ts` for `require_credential_types`).
    - correct auth passes (not 401/403)
    - GET unauthenticated for `side_effects: false` reads
 2. **RPC adversarial envelopes** — fixed set exercising dispatcher steps 1–2: non-JSON body, wrong `jsonrpc` version, missing `jsonrpc` / `method` / `id`, batch array, unknown method, GET missing `method`/`id`, GET invalid JSON params, GET non-object params, GET mutation method → `invalid_request`.

package/dist/testing/admin_integration.d.ts

@@ -17,7 +17,7 @@ export interface StandardAdminIntegrationTestOptions {
     /** Role schema result from `create_role_schema()` — used to determine valid/invalid/web-grantable roles. */
     roles: RoleSchemaResult;
     /**
-     * RPC endpoint specs — the source `RpcAction` arrays. Required; permit
+     * RPC endpoint specs — the source `RpcAction` arrays. Required; role_grant
      * grant/revoke are RPC-only and the suite hard-fails without them.
      *
      * Accepts either an array (eager) or a factory
@@ -48,17 +48,16 @@ export interface StandardAdminIntegrationTestOptions {
 /**
  * Standard admin integration test suite for fuz_app admin routes.
  *
- * Exercises account listing, permit grant/revoke (via RPC), session
+ * Exercises account listing, role_grant grant/revoke (via RPC), session
  * management, token management, audit log reads, admin-to-admin
  * isolation, and 401/403 error-coverage on the admin REST surface.
  * Output-schema conformance is not in scope — see the module docstring
  * for the suites that cover it.
  *
  * @throws Error at setup time when `options.rpc_endpoints` is empty — admin
- *   permit grant/revoke, session/token revoke-all, and audit-log reads are
- *   all RPC-only since the 2026-04-22 migration. Hard-fails via
- *   `require_rpc_endpoint_path` so consumers see a clear setup error rather
- *   than `method not found` mid-suite.
+ *   role_grant grant/revoke, session/token revoke-all, and audit-log reads
+ *   are RPC-only. Hard-fails via `require_rpc_endpoint_path` so consumers
+ *   see a clear setup error rather than `method not found` mid-suite.
  */
 export declare const describe_standard_admin_integration_tests: (options: StandardAdminIntegrationTestOptions) => void;
 //# sourceMappingURL=admin_integration.d.ts.map

package/dist/testing/admin_integration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"admin_integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/admin_integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAgC7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAA0B,KAAK,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAEtF,OAAO,EAA6C,KAAK,eAAe,EAAC,MAAM,iBAAiB,CAAC;AACjG,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AASjB,OAAO,EAKN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAqB1B;;GAEG;AACH,MAAM,WAAW,mCAAmC;IACnD,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,4GAA4G;IAC5G,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAChC;AAgCD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,mCAAmC,KAC1C,IAu1BF,CAAC"}
+{"version":3,"file":"admin_integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/admin_integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAgC7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAA0B,KAAK,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAGtF,OAAO,EAA6C,KAAK,eAAe,EAAC,MAAM,iBAAiB,CAAC;AACjG,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AASjB,OAAO,EAKN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAoB1B;;GAEG;AACH,MAAM,WAAW,mCAAmC;IACnD,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,4GAA4G;IAC5G,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAChC;AAmCD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,mCAAmC,KAC1C,IA+1BF,CAAC"}