@fuzdev/fuz_app 0.51.0 → 0.53.0

package/dist/testing/admin_integration.js

@@ -72,7 +72,11 @@ const build_admin_test_app_options = (options, db, roles) => ({
  * Output-schema conformance is not in scope — see the module docstring
  * for the suites that cover it.
  *
- * @param options - session config, route factory, role schema, RPC endpoints
+ * @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.
  */
 export const describe_standard_admin_integration_tests = (options) => {
     // Hard-fail early so consumers see a clear setup error instead of a
@@ -99,16 +103,14 @@ export const describe_standard_admin_integration_tests = (options) => {
                 // RPC migration: account listing, session/token revoke-all,
                 // audit-log reads, and invite CRUD are RPC-only. The only
                 // admin REST route remaining is the optional
-                // `GET /audit-log/stream` SSE, plus the shared RPC endpoint
+                // `GET /audit/stream` SSE, plus the shared RPC endpoint
                 // path itself (admin methods live behind spec-level role auth).
-                // The `/audit-log/stream` suffix tracks the hardcoded path in
+                // The `/audit/stream` suffix tracks the hardcoded path in
                 // `auth/audit_log_routes.ts` — if consumers ever need to mount
                 // the audit SSE at a different suffix, promote this to an
                 // `audit_log_path_suffix` option on
                 // `StandardAdminIntegrationTestOptions`.
-                const admin_routes = captured_route_specs.filter((s) => s.path.endsWith('/audit-log/stream') &&
-                    s.auth.type === 'role' &&
-                    s.auth.role === 'admin');
+                const admin_routes = captured_route_specs.filter((s) => s.path.endsWith('/audit/stream') && s.auth.type === 'role' && s.auth.role === 'admin');
                 // Adaptive threshold: when the scoped admin REST surface is
                 // effectively empty (0–1 routes, typical post-RPC-migration),
                 // the 20% baseline is meaningless — a single SSE route that

package/dist/testing/adversarial_404.d.ts

@@ -8,8 +8,6 @@ import type { AdversarialTestOptions } from './attack_surface.js';
  * 2. Fires a request with valid-format params (nil UUIDs for UUID params)
  * 3. Validates response status is 404
  * 4. Validates response body matches the declared 404 Zod schema
- *
- * @param options - the test configuration
  */
 export declare const describe_adversarial_404: (options: AdversarialTestOptions) => void;
 //# sourceMappingURL=adversarial_404.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"adversarial_404.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_404.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAoB7B,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,qBAAqB,CAAC;AAyBhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,sBAAsB,KAAG,IA2E1E,CAAC"}
+{"version":3,"file":"adversarial_404.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_404.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAoB7B,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,qBAAqB,CAAC;AAyBhE;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,sBAAsB,KAAG,IA2E1E,CAAC"}

package/dist/testing/adversarial_404.js

@@ -47,8 +47,6 @@ const extract_404_error_code = (schema) => {
  * 2. Fires a request with valid-format params (nil UUIDs for UUID params)
  * 3. Validates response status is 404
  * 4. Validates response body matches the declared 404 Zod schema
- *
- * @param options - the test configuration
  */
 export const describe_adversarial_404 = (options) => {
     const { build, roles } = options;

package/dist/testing/adversarial_headers.d.ts

@@ -16,16 +16,17 @@ export interface AdversarialHeaderCase {
  * 7 standard adversarial header cases applicable to any middleware stack.
  *
  * @param allowed_origin - an origin that passes the origin check
- * @returns the standard adversarial header cases
  */
 export declare const create_standard_adversarial_cases: (allowed_origin: string) => Array<AdversarialHeaderCase>;
 /**
  * Create a middleware stack app with standard adversarial header tests.
  *
  * Convenience wrapper combining `create_test_middleware_stack_app`
- * and `create_standard_adversarial_cases`.
- * Asserts body content for both error and success cases, and checks
- * `mock_validate` call status via per-case declarative flags.
+ * and `create_standard_adversarial_cases`. Generates one `test()` per case
+ * inside a `describe()` block — asserts body content for both error and
+ * success cases, and verifies that `mock_validate` was (or was not) reached
+ * per the case's `validate_expectation` flag, ensuring earlier middleware
+ * actually short-circuits before token validation in the rejection cases.
  *
  * @param suite_name - the describe block name
  * @param options - middleware stack configuration

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

@@ -1 +1 @@
-{"version":3,"file":"adversarial_headers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_headers.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAY7B,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAG3B,OAAO,EAGN,KAAK,0BAA0B,EAC/B,MAAM,iBAAiB,CAAC;AAIzB,+DAA+D;AAC/D,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+GAA+G;IAC/G,qBAAqB,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IAClC,qGAAqG;IACrG,oBAAoB,EAAE,QAAQ,GAAG,YAAY,CAAC;CAC9C;AAID;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,GAC7C,gBAAgB,MAAM,KACpB,KAAK,CAAC,qBAAqB,CA+D7B,CAAC;AAIF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qCAAqC,GACjD,YAAY,MAAM,EAClB,SAAS,0BAA0B,EACnC,gBAAgB,MAAM,EACtB,cAAc,KAAK,CAAC,qBAAqB,CAAC,KACxC,IAkCF,CAAC"}
+{"version":3,"file":"adversarial_headers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_headers.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAY7B,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAG3B,OAAO,EAGN,KAAK,0BAA0B,EAC/B,MAAM,iBAAiB,CAAC;AAIzB,+DAA+D;AAC/D,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+GAA+G;IAC/G,qBAAqB,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IAClC,qGAAqG;IACrG,oBAAoB,EAAE,QAAQ,GAAG,YAAY,CAAC;CAC9C;AAID;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,GAC7C,gBAAgB,MAAM,KACpB,KAAK,CAAC,qBAAqB,CA+D7B,CAAC;AAIF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qCAAqC,GACjD,YAAY,MAAM,EAClB,SAAS,0BAA0B,EACnC,gBAAgB,MAAM,EACtB,cAAc,KAAK,CAAC,qBAAqB,CAAC,KACxC,IAkCF,CAAC"}

package/dist/testing/adversarial_headers.js

@@ -15,7 +15,6 @@ import { create_test_middleware_stack_app, TEST_MIDDLEWARE_PATH, } from './middl
  * 7 standard adversarial header cases applicable to any middleware stack.
  *
  * @param allowed_origin - an origin that passes the origin check
- * @returns the standard adversarial header cases
  */
 export const create_standard_adversarial_cases = (allowed_origin) => [
     {
@@ -86,9 +85,11 @@ export const create_standard_adversarial_cases = (allowed_origin) => [
  * Create a middleware stack app with standard adversarial header tests.
  *
  * Convenience wrapper combining `create_test_middleware_stack_app`
- * and `create_standard_adversarial_cases`.
- * Asserts body content for both error and success cases, and checks
- * `mock_validate` call status via per-case declarative flags.
+ * and `create_standard_adversarial_cases`. Generates one `test()` per case
+ * inside a `describe()` block — asserts body content for both error and
+ * success cases, and verifies that `mock_validate` was (or was not) reached
+ * per the case's `validate_expectation` flag, ensuring earlier middleware
+ * actually short-circuits before token validation in the rejection cases.
  *
  * @param suite_name - the describe block name
  * @param options - middleware stack configuration

package/dist/testing/adversarial_input.d.ts

@@ -24,6 +24,10 @@ interface QueryTestCase {
  * - One wrong-type value per field
  * - Null for required non-nullable fields
  * - One format violation per constrained field
+ *
+ * @throws Error if the seed body built by `generate_valid_value` fails
+ *   `input_schema.safeParse` — surfaces broken generation logic with the
+ *   Zod issues path rather than producing nonsense adversarial cases.
  */
 export declare const generate_input_test_cases: (input_schema: z.ZodType) => Array<InputTestCase>;
 /**
@@ -48,8 +52,6 @@ export declare const generate_query_test_cases: (query_schema: z.ZodObject) => A
  * Tests input body validation and params validation for all routes.
  * Uses correct auth credentials so auth guards pass and validation
  * middleware is actually exercised.
- *
- * @param options - the test configuration
  */
 export declare const describe_adversarial_input: (options: AdversarialTestOptions) => void;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"adversarial_input.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_input.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAiB7B,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAUtB,OAAO,EAEN,0BAA0B,EAC1B,uBAAuB,EAGvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,qBAAqB,CAAC;AA8ChE,UAAU,aAAa;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,EAAE,OAAO,0BAA0B,GAAG,OAAO,uBAAuB,CAAC;CACnF;AAED,UAAU,cAAc;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,UAAU,aAAa;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GAAI,cAAc,CAAC,CAAC,OAAO,KAAG,KAAK,CAAC,aAAa,CAyLtF,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,eAAe,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,cAAc,CA+B3F,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,cAAc,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,aAAa,CA4CxF,CAAC;AAqBF;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GAAI,SAAS,sBAAsB,KAAG,IA4M5E,CAAC"}
+{"version":3,"file":"adversarial_input.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_input.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAiB7B,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAUtB,OAAO,EAEN,0BAA0B,EAC1B,uBAAuB,EAGvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,qBAAqB,CAAC;AA8ChE,UAAU,aAAa;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,EAAE,OAAO,0BAA0B,GAAG,OAAO,uBAAuB,CAAC;CACnF;AAED,UAAU,cAAc;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,UAAU,aAAa;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAID;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,GAAI,cAAc,CAAC,CAAC,OAAO,KAAG,KAAK,CAAC,aAAa,CAyLtF,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,eAAe,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,cAAc,CA+B3F,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,cAAc,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,aAAa,CA4CxF,CAAC;AAqBF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,SAAS,sBAAsB,KAAG,IA4M5E,CAAC"}

package/dist/testing/adversarial_input.js

@@ -68,6 +68,10 @@ const format_violation = (format) => {
  * - One wrong-type value per field
  * - Null for required non-nullable fields
  * - One format violation per constrained field
+ *
+ * @throws Error if the seed body built by `generate_valid_value` fails
+ *   `input_schema.safeParse` — surfaces broken generation logic with the
+ *   Zod issues path rather than producing nonsense adversarial cases.
  */
 export const generate_input_test_cases = (input_schema) => {
     if (is_null_schema(input_schema))
@@ -351,8 +355,6 @@ const build_query_url = (path, query) => {
  * Tests input body validation and params validation for all routes.
  * Uses correct auth credentials so auth guards pass and validation
  * middleware is actually exercised.
- *
- * @param options - the test configuration
  */
 export const describe_adversarial_input = (options) => {
     const { build, roles } = options;

package/dist/testing/app_server.d.ts

@@ -51,6 +51,9 @@ export interface BootstrapTestAccountOptions {
  * Creates an account with actor, grants roles, creates an API token,
  * creates a session, and signs a session cookie. Shared by
  * `create_test_app_server` and `TestApp.create_account`.
+ *
+ * @mutates the underlying `options.db` — inserts rows into `account`, `actor`,
+ *   `permit` (one per role), `api_token`, and `auth_session`.
  */
 export declare const bootstrap_test_account: (options: BootstrapTestAccountOptions) => Promise<{
     account: {
@@ -123,6 +126,28 @@ export interface TestAppServerOptions {
      */
     audit_log_config?: AuditLogConfig;
 }
+/**
+ * Create an app server with a bootstrapped account for testing.
+ *
+ * Sets up:
+ * - Auth tables (via cached PGlite factory, or reuses existing `db`)
+ * - A keeper account with hashed password
+ * - Role permits for each role in `options.roles`
+ * - An API token for Bearer auth
+ * - A session with a signed cookie value
+ *
+ * Uses `stub_password_deps` by default — deterministic hashing that works
+ * correctly for login/logout tests without Argon2 overhead.
+ *
+ * @param options - session options and optional overrides
+ * @returns a `TestAppServer` ready for HTTP testing
+ * @mutates the underlying database — when `db` is supplied, resets singleton
+ *   state (`bootstrap_lock.bootstrapped`, `app_settings.open_signup`) before
+ *   bootstrapping; in either branch inserts an account, actor, role permits,
+ *   API token, and session row. When `audit_log_config` is provided, also
+ *   sets `backend.deps.audit_log_config` so `create_app_server`'s shallow
+ *   spread picks it up.
+ */
 export declare const create_test_app_server: (options: TestAppServerOptions) => Promise<TestAppServer>;
 /**
  * Configuration for `create_test_app`.

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

@@ -1 +1 @@
-{"version":3,"file":"app_server.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/app_server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app_server.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/app_server.ts"],"names":[],"mappings":"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"}

package/dist/testing/app_server.js

@@ -40,6 +40,9 @@ const fallback_pglite_factory = create_pglite_factory(async (db) => {
  * Creates an account with actor, grants roles, creates an API token,
  * creates a session, and signs a session cookie. Shared by
  * `create_test_app_server` and `TestApp.create_account`.
+ *
+ * @mutates the underlying `options.db` — inserts rows into `account`, `actor`,
+ *   `permit` (one per role), `api_token`, and `auth_session`.
  */
 export const bootstrap_test_account = async (options) => {
     const { db, keyring, session_options, password, username = 'keeper', password_value = 'test-password-123', roles = [], } = options;
@@ -69,6 +72,8 @@ export const bootstrap_test_account = async (options) => {
         session_cookie,
     };
 };
+/** Silent logger for tests — suppresses all output. */
+const test_log = new Logger('test', { level: 'off' });
 /**
  * Create an app server with a bootstrapped account for testing.
  *
@@ -84,9 +89,13 @@ export const bootstrap_test_account = async (options) => {
  *
  * @param options - session options and optional overrides
  * @returns a `TestAppServer` ready for HTTP testing
+ * @mutates the underlying database — when `db` is supplied, resets singleton
+ *   state (`bootstrap_lock.bootstrapped`, `app_settings.open_signup`) before
+ *   bootstrapping; in either branch inserts an account, actor, role permits,
+ *   API token, and session row. When `audit_log_config` is provided, also
+ *   sets `backend.deps.audit_log_config` so `create_app_server`'s shallow
+ *   spread picks it up.
  */
-/** Silent logger for tests — suppresses all output. */
-const test_log = new Logger('test', { level: 'off' });
 export const create_test_app_server = async (options) => {
     const { session_options, db: existing_db, db_type = 'pglite-memory', password = stub_password_deps, username = 'keeper', password_value = 'test-password-123', roles = [ROLE_KEEPER], on_audit_event = () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
     audit_log_config, } = options;

package/dist/testing/assertions.d.ts

@@ -5,22 +5,25 @@ import type { RouteErrorSchemas } from '../http/error_schemas.js';
 /**
  * Resolve an absolute path relative to the caller's module.
  *
- * @param filename - the filename to resolve
  * @param import_meta_url - the caller's `import.meta.url`
- * @returns absolute path
  */
 export declare const resolve_fixture_path: (filename: string, import_meta_url: string) => string;
 /**
  * Compare live surface against a committed snapshot JSON file.
  *
+ * Failure message instructs the developer to run `gro gen` to update the
+ * snapshot — every fuz_app consumer wires the snapshot through a `*.gen.ts`
+ * file so regeneration goes through the same pipeline as the rest of the
+ * generated artifacts.
+ *
  * @param surface - the live surface to check
  * @param snapshot_path - absolute path to the committed JSON snapshot
+ * @throws AssertionError if the live surface does not deep-equal the snapshot,
+ *   or `Error` if the snapshot file is unreadable / malformed JSON.
  */
 export declare const assert_surface_matches_snapshot: (surface: AppSurface, snapshot_path: string) => void;
 /**
  * Verify surface generation is deterministic (build twice, compare).
- *
- * @param build_surface - function that builds the surface
  */
 export declare const assert_surface_deterministic: (build_surface: () => AppSurface) => void;
 /**
@@ -28,21 +31,19 @@ export declare const assert_surface_deterministic: (build_surface: () => AppSurf
  *
  * @param surface - the app surface to check
  * @param expected_public - format: `['GET /health', 'POST /api/account/login']`
+ * @throws AssertionError if the live surface has public routes not in
+ *   `expected_public`, or if any entry in `expected_public` is missing from
+ *   the live surface.
  */
 export declare const assert_only_expected_public_routes: (surface: AppSurface, expected_public: Array<string>) => void;
-/**
- * Verify every route under a path prefix has the exact expected middleware stack.
- *
- * @param surface - the app surface to check
- * @param path_prefix - prefix to filter routes (e.g. `'/api/'`)
- * @param expected_middleware - the exact middleware names in order
- */
 /**
  * Look up the merged error schema for a route+status from a pre-built schema lookup.
  *
  * @param lookup - map from `"METHOD /path"` to merged error schemas
  * @param route - the surface route to look up
  * @param status - HTTP status code
+ * @returns the Zod schema for that route+status, or `undefined` when no error
+ *   schema is declared for the status code
  */
 export declare const get_route_error_schema: (lookup: Map<string, RouteErrorSchemas>, route: AppSurfaceRoute, status: number) => z.ZodType | undefined;
 /**
@@ -55,7 +56,18 @@ export declare const get_route_error_schema: (lookup: Map<string, RouteErrorSche
  * @param route - the surface route to validate against
  * @param status - expected HTTP status code
  * @param body - the parsed response body to validate
+ * @throws AssertionError if no schema is declared for the route+status pair.
+ * @throws ZodError if the body does not satisfy the declared schema.
  */
 export declare const assert_error_schema_valid: (lookup: Map<string, RouteErrorSchemas>, route: AppSurfaceRoute, status: number, body: unknown) => void;
+/**
+ * Verify every route under a path prefix has the exact expected middleware stack.
+ *
+ * @param surface - the app surface to check
+ * @param path_prefix - prefix to filter routes (e.g. `'/api/'`)
+ * @param expected_middleware - the exact middleware names in order
+ * @throws AssertionError if no routes match `path_prefix`, or if any matching
+ *   route's `applicable_middleware` does not deep-equal `expected_middleware`.
+ */
 export declare const assert_full_middleware_stack: (surface: AppSurface, path_prefix: string, expected_middleware: Array<string>) => void;
 //# sourceMappingURL=assertions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"assertions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/assertions.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAe7B,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,UAAU,EAAE,eAAe,EAAC,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,0BAA0B,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAU,MAAM,EAAE,iBAAiB,MAAM,KAAG,MACtB,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,GAC3C,SAAS,UAAU,EACnB,eAAe,MAAM,KACnB,IAOF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,GAAI,eAAe,MAAM,UAAU,KAAG,IAE9E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,GAC9C,SAAS,UAAU,EACnB,iBAAiB,KAAK,CAAC,MAAM,CAAC,KAC5B,IAWF,CAAC;AAEF;;;;;;GAMG;AACH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAClC,QAAQ,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACtC,OAAO,eAAe,EACtB,QAAQ,MAAM,KACZ,CAAC,CAAC,OAAO,GAAG,SAGd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GACrC,QAAQ,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACtC,OAAO,eAAe,EACtB,QAAQ,MAAM,EACd,MAAM,OAAO,KACX,IAIF,CAAC;AAEF,eAAO,MAAM,4BAA4B,GACxC,SAAS,UAAU,EACnB,aAAa,MAAM,EACnB,qBAAqB,KAAK,CAAC,MAAM,CAAC,KAChC,IAUF,CAAC"}
+{"version":3,"file":"assertions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/assertions.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAe7B,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,UAAU,EAAE,eAAe,EAAC,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,0BAA0B,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAU,MAAM,EAAE,iBAAiB,MAAM,KAAG,MACtB,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,+BAA+B,GAC3C,SAAS,UAAU,EACnB,eAAe,MAAM,KACnB,IAOF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,4BAA4B,GAAI,eAAe,MAAM,UAAU,KAAG,IAE9E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kCAAkC,GAC9C,SAAS,UAAU,EACnB,iBAAiB,KAAK,CAAC,MAAM,CAAC,KAC5B,IAWF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAClC,QAAQ,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACtC,OAAO,eAAe,EACtB,QAAQ,MAAM,KACZ,CAAC,CAAC,OAAO,GAAG,SAGd,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,GACrC,QAAQ,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACtC,OAAO,eAAe,EACtB,QAAQ,MAAM,EACd,MAAM,OAAO,KACX,IAIF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,UAAU,EACnB,aAAa,MAAM,EACnB,qBAAqB,KAAK,CAAC,MAAM,CAAC,KAChC,IAUF,CAAC"}

package/dist/testing/assertions.js

@@ -14,16 +14,21 @@ import { assert } from 'vitest';
 /**
  * Resolve an absolute path relative to the caller's module.
  *
- * @param filename - the filename to resolve
  * @param import_meta_url - the caller's `import.meta.url`
- * @returns absolute path
  */
 export const resolve_fixture_path = (filename, import_meta_url) => resolve(dirname(fileURLToPath(import_meta_url)), filename);
 /**
  * Compare live surface against a committed snapshot JSON file.
  *
+ * Failure message instructs the developer to run `gro gen` to update the
+ * snapshot — every fuz_app consumer wires the snapshot through a `*.gen.ts`
+ * file so regeneration goes through the same pipeline as the rest of the
+ * generated artifacts.
+ *
  * @param surface - the live surface to check
  * @param snapshot_path - absolute path to the committed JSON snapshot
+ * @throws AssertionError if the live surface does not deep-equal the snapshot,
+ *   or `Error` if the snapshot file is unreadable / malformed JSON.
  */
 export const assert_surface_matches_snapshot = (surface, snapshot_path) => {
     const committed = JSON.parse(readFileSync(snapshot_path, 'utf-8'));
@@ -31,8 +36,6 @@ export const assert_surface_matches_snapshot = (surface, snapshot_path) => {
 };
 /**
  * Verify surface generation is deterministic (build twice, compare).
- *
- * @param build_surface - function that builds the surface
  */
 export const assert_surface_deterministic = (build_surface) => {
     assert.deepStrictEqual(build_surface(), build_surface());
@@ -42,6 +45,9 @@ export const assert_surface_deterministic = (build_surface) => {
  *
  * @param surface - the app surface to check
  * @param expected_public - format: `['GET /health', 'POST /api/account/login']`
+ * @throws AssertionError if the live surface has public routes not in
+ *   `expected_public`, or if any entry in `expected_public` is missing from
+ *   the live surface.
  */
 export const assert_only_expected_public_routes = (surface, expected_public) => {
     const expected = new Set(expected_public);
@@ -53,19 +59,14 @@ export const assert_only_expected_public_routes = (surface, expected_public) =>
     assert.strictEqual(unexpected.length, 0, `Unexpected public routes: ${unexpected.join(', ')}`);
     assert.strictEqual(missing.length, 0, `Expected public routes missing: ${missing.join(', ')}`);
 };
-/**
- * Verify every route under a path prefix has the exact expected middleware stack.
- *
- * @param surface - the app surface to check
- * @param path_prefix - prefix to filter routes (e.g. `'/api/'`)
- * @param expected_middleware - the exact middleware names in order
- */
 /**
  * Look up the merged error schema for a route+status from a pre-built schema lookup.
  *
  * @param lookup - map from `"METHOD /path"` to merged error schemas
  * @param route - the surface route to look up
  * @param status - HTTP status code
+ * @returns the Zod schema for that route+status, or `undefined` when no error
+ *   schema is declared for the status code
  */
 export const get_route_error_schema = (lookup, route, status) => {
     const key = `${route.method} ${route.path}`;
@@ -81,12 +82,23 @@ export const get_route_error_schema = (lookup, route, status) => {
  * @param route - the surface route to validate against
  * @param status - expected HTTP status code
  * @param body - the parsed response body to validate
+ * @throws AssertionError if no schema is declared for the route+status pair.
+ * @throws ZodError if the body does not satisfy the declared schema.
  */
 export const assert_error_schema_valid = (lookup, route, status, body) => {
     const schema = get_route_error_schema(lookup, route, status);
     assert.ok(schema, `missing error schema for ${status} on ${route.method} ${route.path}`);
     schema.parse(body);
 };
+/**
+ * Verify every route under a path prefix has the exact expected middleware stack.
+ *
+ * @param surface - the app surface to check
+ * @param path_prefix - prefix to filter routes (e.g. `'/api/'`)
+ * @param expected_middleware - the exact middleware names in order
+ * @throws AssertionError if no routes match `path_prefix`, or if any matching
+ *   route's `applicable_middleware` does not deep-equal `expected_middleware`.
+ */
 export const assert_full_middleware_stack = (surface, path_prefix, expected_middleware) => {
     const routes = surface.routes.filter((r) => r.path.startsWith(path_prefix));
     assert.ok(routes.length > 0, `No routes found under ${path_prefix}`);

package/dist/testing/attack_surface.d.ts

@@ -16,8 +16,6 @@ export interface AdversarialTestOptions {
  * - wrong role → 403 — every role route, tested with all non-matching roles
  * - authenticated without role → 403 — every role route, no-role context
  * - correct auth passes guard — every protected route, assert not 401/403
- *
- * @param options - the test configuration
  */
 export declare const describe_adversarial_auth: (options: AdversarialTestOptions) => void;
 /**
@@ -83,8 +81,6 @@ export interface StandardAttackSurfaceOptions {
  *
  * Consumer test files call this with project-specific options, then add
  * any project-specific assertions in additional `describe` blocks.
- *
- * @param options - the test configuration
  */
 export declare const describe_standard_attack_surface_tests: (options: StandardAttackSurfaceOptions) => void;
 //# sourceMappingURL=attack_surface.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"attack_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/attack_surface.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAoB7B,OAAO,EAON,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,MAAM,yBAAyB,CAAC;AAoBjC,OAAO,EAA4B,KAAK,cAAc,EAAC,MAAM,oBAAoB,CAAC;AAsClF,oFAAoF;AACpF,MAAM,WAAW,sBAAsB;IACtC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,cAAc,CAAC;IAC5B,yDAAyD;IACzD,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,sBAAsB,KAAG,IAkH3E,CAAC;AAIF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uCAAuC,GACnD,UAAU,2BAA2B,GAAG,IAAI,GAAG,SAAS,KACtD,2BAA2B,GAAG,IAWhC,CAAC;AAEF,0DAA0D;AAC1D,MAAM,WAAW,4BAA4B;IAC5C,+EAA+E;IAC/E,KAAK,EAAE,MAAM,cAAc,CAAC;IAC5B,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,sBAAsB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACtC,gHAAgH;IAChH,uBAAuB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACvC,yDAAyD;IACzD,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,eAAe,CAAC,EAAE,4BAA4B,CAAC;IAC/C;;;;;;;;;;;OAWG;IACH,sBAAsB,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sCAAsC,GAClD,SAAS,4BAA4B,KACnC,IAuEF,CAAC"}
+{"version":3,"file":"attack_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/attack_surface.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAoB7B,OAAO,EAON,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,MAAM,yBAAyB,CAAC;AAoBjC,OAAO,EAA4B,KAAK,cAAc,EAAC,MAAM,oBAAoB,CAAC;AAsClF,oFAAoF;AACpF,MAAM,WAAW,sBAAsB;IACtC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,cAAc,CAAC;IAC5B,yDAAyD;IACzD,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,sBAAsB,KAAG,IAkH3E,CAAC;AAIF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uCAAuC,GACnD,UAAU,2BAA2B,GAAG,IAAI,GAAG,SAAS,KACtD,2BAA2B,GAAG,IAWhC,CAAC;AAEF,0DAA0D;AAC1D,MAAM,WAAW,4BAA4B;IAC5C,+EAA+E;IAC/E,KAAK,EAAE,MAAM,cAAc,CAAC;IAC5B,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,sBAAsB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACtC,gHAAgH;IAChH,uBAAuB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACvC,yDAAyD;IACzD,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,eAAe,CAAC,EAAE,4BAA4B,CAAC;IAC/C;;;;;;;;;;;OAWG;IACH,sBAAsB,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,sCAAsC,GAClD,SAAS,4BAA4B,KACnC,IAuEF,CAAC"}

package/dist/testing/attack_surface.js

@@ -53,8 +53,6 @@ const build_error_schema_lookup = (route_specs, middleware_specs) => {
  * - wrong role → 403 — every role route, tested with all non-matching roles
  * - authenticated without role → 403 — every role route, no-role context
  * - correct auth passes guard — every protected route, assert not 401/403
- *
- * @param options - the test configuration
  */
 export const describe_adversarial_auth = (options) => {
     const { build, roles } = options;
@@ -203,8 +201,6 @@ export const resolve_standard_error_schema_tightness = (consumer) => {
  *
  * Consumer test files call this with project-specific options, then add
  * any project-specific assertions in additional `describe` blocks.
- *
- * @param options - the test configuration
  */
 export const describe_standard_attack_surface_tests = (options) => {
     const { build, snapshot_path, expected_public_routes, expected_api_middleware, roles, api_path_prefix = '/api/', security_policy, } = options;

package/dist/testing/audit_completeness.d.ts

@@ -38,7 +38,10 @@ export interface AuditCompletenessTestOptions {
  * event type. Exercises routes via HTTP requests against a real PGlite
  * database, then queries the `audit_log` table to verify events.
  *
- * @param options - session config, route factory, and optional overrides
+ * @throws Error at setup time when `options.rpc_endpoints` is empty — the
+ *   mutation-audit tests drive permit flow, session/token revoke-all, and
+ *   invite create/delete through their RPC action specs. Hard-fails via
+ *   `require_rpc_endpoint_path`.
  */
 export declare const describe_audit_completeness_tests: (options: AuditCompletenessTestOptions) => void;
 //# sourceMappingURL=audit_completeness.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"audit_completeness.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/audit_completeness.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAkB7B,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;AAIrD,OAAO,EAGN,KAAK,eAAe,EAEpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AAKjB,OAAO,EAIN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAsB1B;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC5C,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;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,qEAAqE;IACrE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAChC;AAoDD;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,GAAI,SAAS,4BAA4B,KAAG,IAyezF,CAAC"}
+{"version":3,"file":"audit_completeness.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/audit_completeness.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAkB7B,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;AAIrD,OAAO,EAGN,KAAK,eAAe,EAEpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AAKjB,OAAO,EAIN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAsB1B;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC5C,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;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,qEAAqE;IACrE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAChC;AAoDD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAAI,SAAS,4BAA4B,KAAG,IAyezF,CAAC"}

package/dist/testing/audit_completeness.js

@@ -63,7 +63,10 @@ const json_session_headers = (test_app, extra) => test_app.create_session_header
  * event type. Exercises routes via HTTP requests against a real PGlite
  * database, then queries the `audit_log` table to verify events.
  *
- * @param options - session config, route factory, and optional overrides
+ * @throws Error at setup time when `options.rpc_endpoints` is empty — the
+ *   mutation-audit tests drive permit flow, session/token revoke-all, and
+ *   invite create/delete through their RPC action specs. Hard-fails via
+ *   `require_rpc_endpoint_path`.
  */
 export const describe_audit_completeness_tests = (options) => {
     // Hard-fail early so consumers see a clear setup error instead of a

package/dist/testing/auth_apps.d.ts

@@ -12,10 +12,7 @@ import { type RouteSpec, type RouteAuth } from '../http/route_spec.js';
 import { type RequestContext } from '../auth/request_context.js';
 import { type CredentialType } from '../hono_context.js';
 /**
- * Create a mock request context with optional role permit.
- *
- * @param role - optional role to grant
- * @returns a valid `RequestContext`
+ * Create a mock `RequestContext` with optional role permit.
  */
 export declare const create_test_request_context: (role?: string) => RequestContext;
 /**
@@ -23,8 +20,7 @@ export declare const create_test_request_context: (role?: string) => RequestCont
  *
  * @param route_specs - the route specs to register
  * @param auth_ctx - optional request context to inject via middleware
- * @param credential_type - optional credential type (default: `'session'` when auth_ctx provided)
- * @returns a configured Hono app
+ * @param credential_type - optional credential type (default: `'session'` when `auth_ctx` provided)
  */
 export declare const create_test_app_from_specs: (route_specs: Array<RouteSpec>, auth_ctx?: RequestContext, credential_type?: CredentialType) => Hono;
 /** Pre-built Hono apps for each auth level, shared across adversarial test suites. */
@@ -39,15 +35,14 @@ export interface AuthTestApps {
  *
  * @param route_specs - the route specs to register
  * @param roles - all roles in the app
- * @returns apps keyed by auth level
  */
 export declare const create_auth_test_apps: (route_specs: Array<RouteSpec>, roles: Array<string>) => AuthTestApps;
 /**
  * Select the Hono test app with correct auth for a route.
  *
- * @param apps - the pre-built auth test apps
- * @param auth - the route's auth options
- * @returns the correctly-authenticated Hono app
+ * @throws Error if `auth.type === 'role'` and `auth.role` is not present in
+ *   `apps.by_role` — surfaces a missing entry in the `roles` array passed to
+ *   `create_auth_test_apps`.
  */
 export declare const select_auth_app: (apps: AuthTestApps, auth: RouteAuth) => Hono;
 /** Replace Hono route params (`:foo`) with dummy values for HTTP testing. */

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

@@ -1 +1 @@
-{"version":3,"file":"auth_apps.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/auth_apps.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;GAOG;AAEH,OAAO,EAAC,IAAI,EAAC,MAAM,MAAM,CAAC;AAG1B,OAAO,EAAoB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAExF,OAAO,EAAsB,KAAK,cAAc,EAAC,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAAsB,KAAK,cAAc,EAAC,MAAM,oBAAoB,CAAC;AAI5E;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GAAI,OAAO,MAAM,KAAG,cAI1D,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GACtC,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,WAAW,cAAc,EACzB,kBAAkB,cAAc,KAC9B,IAkBF,CAAC;AAEF,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GACjC,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,OAAO,KAAK,CAAC,MAAM,CAAC,KAClB,YAeF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,YAAY,EAAE,MAAM,SAAS,KAAG,IAcrE,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MAA4C,CAAC"}
+{"version":3,"file":"auth_apps.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/auth_apps.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;GAOG;AAEH,OAAO,EAAC,IAAI,EAAC,MAAM,MAAM,CAAC;AAG1B,OAAO,EAAoB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAExF,OAAO,EAAsB,KAAK,cAAc,EAAC,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAAsB,KAAK,cAAc,EAAC,MAAM,oBAAoB,CAAC;AAI5E;;GAEG;AACH,eAAO,MAAM,2BAA2B,GAAI,OAAO,MAAM,KAAG,cAI1D,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GACtC,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,WAAW,cAAc,EACzB,kBAAkB,cAAc,KAC9B,IAkBF,CAAC;AAEF,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GACjC,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,OAAO,KAAK,CAAC,MAAM,CAAC,KAClB,YAeF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,YAAY,EAAE,MAAM,SAAS,KAAG,IAcrE,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MAA4C,CAAC"}

package/dist/testing/auth_apps.js

@@ -16,10 +16,7 @@ import { CREDENTIAL_TYPE_KEY } from '../hono_context.js';
 import { create_stub_db } from './stubs.js';
 import { create_test_account, create_test_actor, create_test_permit } from './entities.js';
 /**
- * Create a mock request context with optional role permit.
- *
- * @param role - optional role to grant
- * @returns a valid `RequestContext`
+ * Create a mock `RequestContext` with optional role permit.
  */
 export const create_test_request_context = (role) => ({
     account: create_test_account({ id: 'acc_1', username: 'testuser' }),
@@ -31,8 +28,7 @@ export const create_test_request_context = (role) => ({
  *
  * @param route_specs - the route specs to register
  * @param auth_ctx - optional request context to inject via middleware
- * @param credential_type - optional credential type (default: `'session'` when auth_ctx provided)
- * @returns a configured Hono app
+ * @param credential_type - optional credential type (default: `'session'` when `auth_ctx` provided)
  */
 export const create_test_app_from_specs = (route_specs, auth_ctx, credential_type) => {
     const app = new Hono();
@@ -52,7 +48,6 @@ export const create_test_app_from_specs = (route_specs, auth_ctx, credential_typ
  *
  * @param route_specs - the route specs to register
  * @param roles - all roles in the app
- * @returns apps keyed by auth level
  */
 export const create_auth_test_apps = (route_specs, roles) => {
     const by_role = new Map();
@@ -69,9 +64,9 @@ export const create_auth_test_apps = (route_specs, roles) => {
 /**
  * Select the Hono test app with correct auth for a route.
  *
- * @param apps - the pre-built auth test apps
- * @param auth - the route's auth options
- * @returns the correctly-authenticated Hono app
+ * @throws Error if `auth.type === 'role'` and `auth.role` is not present in
+ *   `apps.by_role` — surfaces a missing entry in the `roles` array passed to
+ *   `create_auth_test_apps`.
  */
 export const select_auth_app = (apps, auth) => {
     switch (auth.type) {