@fuzdev/fuz_app 0.6.0 → 0.7.0

package/dist/testing/app_server.d.ts

@@ -19,7 +19,7 @@ import type { PasswordHashDeps } from '../auth/password.js';
 import { type SessionOptions } from '../auth/session_cookie.js';
 import type { AppBackend } from '../server/app_backend.js';
 import { type AppServerOptions, type AppServerContext } from '../server/app_server.js';
-import type { AppSurface } from '../http/surface.js';
+import type { AppSurface, AppSurfaceSpec } from '../http/surface.js';
 import type { RouteSpec } from '../http/route_spec.js';
 /**
  * Fast password stub for tests that don't exercise login/password flows.
@@ -137,6 +137,7 @@ export interface TestAccount {
 export interface TestApp {
     app: Hono;
     backend: TestAppServer;
+    surface_spec: AppSurfaceSpec;
     surface: AppSurface;
     route_specs: Array<RouteSpec>;
     /** Build request headers with the bootstrapped session cookie. */

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

@@ -230,6 +230,7 @@ export const create_test_app = async (options) => {
     return {
         app,
         backend: test_server,
+        surface_spec,
         surface: surface_spec.surface,
         route_specs: surface_spec.route_specs,
         create_session_headers,

package/dist/testing/rpc_attack_surface.d.ts

@@ -0,0 +1,23 @@
+import './assert_dev_env.js';
+import type { AppSurfaceSpec } from '../http/surface.js';
+/** Options for `describe_rpc_attack_surface_tests`. */
+export interface RpcAttackSurfaceOptions {
+    /** Build the app surface bundle (surface + route specs + middleware specs + rpc_endpoints). */
+    build: () => AppSurfaceSpec;
+    /** All roles in the app (e.g. `['admin', 'keeper']`). */
+    roles: Array<string>;
+}
+/**
+ * Run the standard RPC attack surface test suite.
+ *
+ * Generates 3 test groups:
+ * 1. Auth enforcement — per-method auth checks via JSON-RPC envelopes
+ * 2. Adversarial envelopes — malformed JSON-RPC requests
+ * 3. Adversarial params — schema-invalid params per method
+ *
+ * Skips silently when `surface.rpc_endpoints` is empty.
+ *
+ * @param options - the test configuration
+ */
+export declare const describe_rpc_attack_surface_tests: (options: RpcAttackSurfaceOptions) => void;
+//# sourceMappingURL=rpc_attack_surface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rpc_attack_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/rpc_attack_surface.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAkB7B,OAAO,KAAK,EAA6C,cAAc,EAAC,MAAM,oBAAoB,CAAC;AAenG,uDAAuD;AACvD,MAAM,WAAW,uBAAuB;IACvC,+FAA+F;IAC/F,KAAK,EAAE,MAAM,cAAc,CAAC;IAC5B,yDAAyD;IACzD,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACrB;AAkaD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAAI,SAAS,uBAAuB,KAAG,IAOpF,CAAC"}

package/dist/testing/rpc_attack_surface.js

@@ -0,0 +1,376 @@
+import './assert_dev_env.js';
+/**
+ * Composable RPC attack surface test suite.
+ *
+ * Three test groups for JSON-RPC 2.0 endpoints:
+ * 1. **Auth enforcement** — per-method auth inside the dispatcher
+ * 2. **Adversarial envelopes** — malformed JSON-RPC requests
+ * 3. **Adversarial params** — schema-invalid params per method
+ *
+ * Uses the same `{build, roles}` config as `describe_adversarial_auth`
+ * and `describe_adversarial_input`. No DB needed — uses stub deps.
+ *
+ * @module
+ */
+import { test, assert, describe } from 'vitest';
+import { JSONRPC_ERROR_CODES } from '../http/jsonrpc_errors.js';
+import { create_auth_test_apps, select_auth_app } from './auth_apps.js';
+import { generate_input_test_cases } from './adversarial_input.js';
+import { ERROR_INVALID_JSON_BODY } from '../http/error_schemas.js';
+import { create_rpc_post_init, create_rpc_get_url, assert_jsonrpc_error_response, } from './rpc_helpers.js';
+// --- Helpers ---
+/** Filter RPC methods that require any form of authentication. */
+const filter_protected_rpc_methods = (endpoint) => endpoint.methods.filter((m) => m.auth.type !== 'none');
+/** Filter RPC methods that require a specific role. */
+const filter_role_rpc_methods = (endpoint) => endpoint.methods.filter((m) => m.auth.type === 'role');
+/** Find the `RpcAction` source spec for a surface method. */
+const find_rpc_action = (rpc_endpoint_specs, endpoint_path, method_name) => {
+    const ep = rpc_endpoint_specs.find((e) => e.path === endpoint_path);
+    return ep?.actions.find((a) => a.spec.method === method_name);
+};
+// --- Auth enforcement ---
+/**
+ * Generate adversarial auth enforcement tests for RPC endpoints.
+ *
+ * For each endpoint, iterates methods with auth requirements and fires
+ * JSON-RPC envelopes with wrong/missing credentials. Auth errors are
+ * JSON-RPC format: `{jsonrpc, id, error: {code, message}}`.
+ *
+ * Describe blocks:
+ * - unauthenticated → error code -32001 — every protected method
+ * - wrong role → error code -32002 — every role method with non-matching roles
+ * - authenticated without role → -32002 — every role method, no-role context
+ * - keeper routes reject session credential → -32002
+ * - correct auth passes — every protected method, assert not 401/403
+ */
+const describe_rpc_auth = (options) => {
+    const { build, roles } = options;
+    const { surface, route_specs } = build();
+    if (surface.rpc_endpoints.length === 0)
+        return;
+    const apps = create_auth_test_apps(route_specs, roles);
+    describe('RPC auth enforcement', () => {
+        for (const endpoint of surface.rpc_endpoints) {
+            const protected_methods = filter_protected_rpc_methods(endpoint);
+            if (protected_methods.length === 0)
+                continue;
+            const role_methods = filter_role_rpc_methods(endpoint);
+            describe(endpoint.path, () => {
+                describe('unauthenticated → JSON-RPC error', () => {
+                    for (const method of protected_methods) {
+                        test(`${method.name} (${format_auth(method.auth)})`, async () => {
+                            const res = await apps.public.request(endpoint.path, create_rpc_post_init(method.name));
+                            assert.strictEqual(res.status, 401, `${method.name} should return 401`);
+                            const body = await res.json();
+                            assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.unauthenticated);
+                        });
+                    }
+                });
+                if (role_methods.length > 0) {
+                    describe('wrong role → forbidden', () => {
+                        for (const method of role_methods) {
+                            const wrong_roles = roles.filter((r) => r !== method.auth.role);
+                            for (const wrong_role of wrong_roles) {
+                                test(`${method.name} (${wrong_role} instead of ${method.auth.role})`, async () => {
+                                    const app = apps.by_role.get(wrong_role);
+                                    if (!app)
+                                        throw new Error(`No test app for role '${wrong_role}'`);
+                                    const res = await app.request(endpoint.path, create_rpc_post_init(method.name));
+                                    assert.strictEqual(res.status, 403, `${method.name} should return 403`);
+                                    const body = await res.json();
+                                    assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.forbidden);
+                                });
+                            }
+                        }
+                    });
+                    describe('authenticated without role → forbidden', () => {
+                        for (const method of role_methods) {
+                            test(`${method.name} (${method.auth.role})`, async () => {
+                                const res = await apps.authed.request(endpoint.path, create_rpc_post_init(method.name));
+                                assert.strictEqual(res.status, 403, `${method.name} should return 403`);
+                                const body = await res.json();
+                                assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.forbidden);
+                            });
+                        }
+                    });
+                }
+                // NOTE: no "keeper rejects session credential" test for RPC — the RPC
+                // dispatcher's check_action_auth only checks role, not credential type.
+                // Credential type enforcement is a REST middleware concern (require_keeper).
+                describe('correct auth passes', () => {
+                    for (const method of protected_methods) {
+                        test(method.name, async () => {
+                            const app = select_auth_app(apps, method.auth);
+                            const res = await app.request(endpoint.path, create_rpc_post_init(method.name));
+                            // handler may error (500, 404 from stub deps) — that's fine
+                            assert.notStrictEqual(res.status, 401, 'should not be 401');
+                            assert.notStrictEqual(res.status, 403, 'should not be 403');
+                        });
+                    }
+                });
+                // also test GET for read methods with auth
+                const protected_reads = protected_methods.filter((m) => !m.side_effects);
+                if (protected_reads.length > 0) {
+                    describe('GET unauthenticated → JSON-RPC error', () => {
+                        for (const method of protected_reads) {
+                            test(`${method.name} (GET)`, async () => {
+                                const url = create_rpc_get_url(endpoint.path, method.name);
+                                const res = await apps.public.request(url);
+                                assert.strictEqual(res.status, 401, `GET ${method.name} should return 401`);
+                                const body = await res.json();
+                                assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.unauthenticated);
+                            });
+                        }
+                    });
+                }
+            });
+        }
+    });
+};
+// --- Adversarial envelopes ---
+/**
+ * Generate adversarial envelope tests for RPC endpoints.
+ *
+ * Fixed set of malformation cases that exercise the dispatcher's
+ * envelope parsing (step 1) and method lookup (step 2).
+ */
+const describe_rpc_adversarial_envelopes = (options) => {
+    const { build, roles } = options;
+    const { surface, route_specs } = build();
+    if (surface.rpc_endpoints.length === 0)
+        return;
+    // public app for envelope errors (happen before auth checks)
+    const apps = create_auth_test_apps(route_specs, []);
+    // authed apps for the GET mutation test (needs correct auth to reach the side_effects check)
+    const authed_apps = create_auth_test_apps(route_specs, roles);
+    describe('RPC adversarial envelopes', () => {
+        for (const endpoint of surface.rpc_endpoints) {
+            // find a mutation method for GET-restriction testing
+            const mutation_method = endpoint.methods.find((m) => m.side_effects);
+            describe(endpoint.path, () => {
+                // --- POST envelope malformation ---
+                test('non-JSON body → parse_error', async () => {
+                    const res = await apps.public.request(endpoint.path, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: 'not-json',
+                    });
+                    assert.strictEqual(res.status, 400);
+                    const body = await res.json();
+                    assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.parse_error);
+                });
+                test('wrong jsonrpc version → invalid_request', async () => {
+                    const res = await apps.public.request(endpoint.path, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({
+                            jsonrpc: '1.0',
+                            id: 'test',
+                            method: endpoint.methods[0]?.name ?? 'any',
+                        }),
+                    });
+                    assert.strictEqual(res.status, 400);
+                    const body = await res.json();
+                    assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.invalid_request);
+                });
+                test('missing jsonrpc field → invalid_request', async () => {
+                    const res = await apps.public.request(endpoint.path, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({
+                            id: 'test',
+                            method: endpoint.methods[0]?.name ?? 'any',
+                        }),
+                    });
+                    assert.strictEqual(res.status, 400);
+                    const body = await res.json();
+                    assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.invalid_request);
+                });
+                test('missing method field → invalid_request', async () => {
+                    const res = await apps.public.request(endpoint.path, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({ jsonrpc: '2.0', id: 'test' }),
+                    });
+                    assert.strictEqual(res.status, 400);
+                    const body = await res.json();
+                    assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.invalid_request);
+                });
+                test('missing id field → invalid_request', async () => {
+                    const res = await apps.public.request(endpoint.path, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({
+                            jsonrpc: '2.0',
+                            method: endpoint.methods[0]?.name ?? 'any',
+                        }),
+                    });
+                    assert.strictEqual(res.status, 400);
+                    const body = await res.json();
+                    assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.invalid_request);
+                });
+                test('batch (array) body → invalid_request', async () => {
+                    const res = await apps.public.request(endpoint.path, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify([
+                            { jsonrpc: '2.0', id: '1', method: endpoint.methods[0]?.name ?? 'any' },
+                        ]),
+                    });
+                    assert.strictEqual(res.status, 400);
+                    const body = await res.json();
+                    assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.invalid_request);
+                    assert.strictEqual(body.id, null, 'batch has no extractable id');
+                });
+                test('unknown method name → method_not_found', async () => {
+                    const res = await apps.public.request(endpoint.path, create_rpc_post_init('__nonexistent_method__'));
+                    assert.strictEqual(res.status, 404);
+                    const body = await res.json();
+                    assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.method_not_found);
+                });
+                // --- GET envelope malformation ---
+                test('GET missing method → invalid_request', async () => {
+                    const res = await apps.public.request(`${endpoint.path}?id=test`);
+                    assert.strictEqual(res.status, 400);
+                    const body = await res.json();
+                    assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.invalid_request);
+                });
+                test('GET missing id → invalid_request', async () => {
+                    const first_method = endpoint.methods[0]?.name ?? 'any';
+                    const res = await apps.public.request(`${endpoint.path}?method=${first_method}`);
+                    assert.strictEqual(res.status, 400);
+                    const body = await res.json();
+                    assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.invalid_request);
+                });
+                test('GET invalid JSON params → invalid_params', async () => {
+                    const read_method = endpoint.methods.find((m) => !m.side_effects);
+                    // skip if no read methods exist
+                    if (!read_method)
+                        return;
+                    const res = await apps.public.request(`${endpoint.path}?method=${read_method.name}&id=test&params=not-json`);
+                    assert.strictEqual(res.status, 400);
+                    const body = await res.json();
+                    assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.invalid_params);
+                });
+                test('GET non-object params → error', async () => {
+                    const read_method = endpoint.methods.find((m) => !m.side_effects);
+                    // skip if no read methods exist
+                    if (!read_method)
+                        return;
+                    // valid JSON but not an object — hits dispatcher's params validation
+                    const res = await apps.public.request(`${endpoint.path}?method=${read_method.name}&id=test&params=42`);
+                    // should reject: either invalid_params (step 4) or auth error (step 3)
+                    assert.ok(res.status >= 400, `expected error status for non-object params, got ${res.status}`);
+                    const body = await res.json();
+                    assert_jsonrpc_error_response(body);
+                });
+                if (mutation_method) {
+                    test('GET mutation method → invalid_request (side effects)', async () => {
+                        const url = create_rpc_get_url(endpoint.path, mutation_method.name);
+                        // need correct auth to reach the side_effects check
+                        const app = select_auth_app(authed_apps, mutation_method.auth);
+                        const res = await app.request(url);
+                        assert.strictEqual(res.status, 400);
+                        const body = await res.json();
+                        assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.invalid_request);
+                    });
+                }
+            });
+        }
+    });
+};
+// --- Adversarial params ---
+/**
+ * Generate adversarial params validation tests for RPC endpoints.
+ *
+ * For each method with a non-null input schema, generates test cases
+ * from the schema (wrong types, missing fields, format violations)
+ * and wraps them in valid JSON-RPC envelopes. Reuses
+ * `generate_input_test_cases` from `adversarial_input.ts`.
+ */
+const describe_rpc_adversarial_params = (options) => {
+    const { build, roles } = options;
+    const { surface, route_specs, rpc_endpoints: rpc_endpoint_specs } = build();
+    if (surface.rpc_endpoints.length === 0)
+        return;
+    const apps = create_auth_test_apps(route_specs, roles);
+    let total_cases = 0;
+    describe('RPC adversarial params', () => {
+        for (const endpoint of surface.rpc_endpoints) {
+            const methods_with_input = endpoint.methods.filter((m) => m.input_schema !== null);
+            if (methods_with_input.length === 0)
+                continue;
+            describe(endpoint.path, () => {
+                for (const method of methods_with_input) {
+                    // look up the source RpcAction for the Zod schema
+                    const action = find_rpc_action(rpc_endpoint_specs, endpoint.path, method.name);
+                    if (!action) {
+                        test(`${method.name} — missing RpcAction source spec`, () => {
+                            assert.fail(`surface has method '${method.name}' but no matching RpcAction in rpc_endpoints`);
+                        });
+                        continue;
+                    }
+                    // filter out structural cases (non-object body) — those fail at
+                    // envelope validation (invalid_request) not params validation (invalid_params).
+                    // Envelope-level structural errors are covered by adversarial envelopes.
+                    const test_cases = generate_input_test_cases(action.spec.input).filter((tc) => tc.expected_error !== ERROR_INVALID_JSON_BODY);
+                    if (test_cases.length === 0)
+                        continue;
+                    total_cases += test_cases.length;
+                    const app = select_auth_app(apps, method.auth);
+                    describe(method.name, () => {
+                        for (const tc of test_cases) {
+                            test(tc.label, async () => {
+                                const res = await app.request(endpoint.path, create_rpc_post_init(method.name, tc.body));
+                                assert.strictEqual(res.status, 400, `Expected 400 for ${method.name} [${tc.label}], got ${res.status}`);
+                                const body = await res.json();
+                                assert_jsonrpc_error_response(body, JSONRPC_ERROR_CODES.invalid_params);
+                            });
+                        }
+                    });
+                }
+            });
+        }
+        test('generated RPC params test cases', () => {
+            // soft check — methods with only null-input schemas produce 0 cases
+            if (surface.rpc_endpoints.some((ep) => ep.methods.some((m) => m.input_schema !== null))) {
+                assert.ok(total_cases > 0, 'No RPC params test cases generated — schema walking may be broken');
+            }
+        });
+    });
+};
+// --- Helpers (formatting) ---
+/** Format a `RouteAuth` as a human-readable label. */
+const format_auth = (auth) => {
+    switch (auth.type) {
+        case 'none':
+            return 'public';
+        case 'authenticated':
+            return 'authenticated';
+        case 'role':
+            return `role: ${auth.role}`;
+        case 'keeper':
+            return 'keeper';
+    }
+};
+// --- Public API ---
+/**
+ * Run the standard RPC attack surface test suite.
+ *
+ * Generates 3 test groups:
+ * 1. Auth enforcement — per-method auth checks via JSON-RPC envelopes
+ * 2. Adversarial envelopes — malformed JSON-RPC requests
+ * 3. Adversarial params — schema-invalid params per method
+ *
+ * Skips silently when `surface.rpc_endpoints` is empty.
+ *
+ * @param options - the test configuration
+ */
+export const describe_rpc_attack_surface_tests = (options) => {
+    const { surface } = options.build();
+    if (surface.rpc_endpoints.length === 0)
+        return;
+    describe_rpc_auth(options);
+    describe_rpc_adversarial_envelopes(options);
+    describe_rpc_adversarial_params(options);
+};

package/dist/testing/rpc_helpers.d.ts

@@ -0,0 +1,44 @@
+import './assert_dev_env.js';
+import { z } from 'zod';
+import type { JsonrpcErrorCode } from '../http/jsonrpc_errors.js';
+/**
+ * Create a `RequestInit` for a JSON-RPC POST request.
+ *
+ * @param method - JSON-RPC method name
+ * @param params - params object (omit for null-input methods)
+ * @param id - request id (default `'test'`)
+ * @returns a `RequestInit` with the JSON-RPC envelope as body
+ */
+export declare const create_rpc_post_init: (method: string, params?: unknown, id?: string | number) => RequestInit;
+/**
+ * Build a GET URL with JSON-RPC query parameters.
+ *
+ * @param endpoint_path - the RPC endpoint path (e.g., `/api/rpc`)
+ * @param method - JSON-RPC method name
+ * @param params - params object (omit for null-input methods)
+ * @param id - request id (default `'test'`)
+ * @returns the full URL with query string
+ */
+export declare const create_rpc_get_url: (endpoint_path: string, method: string, params?: unknown, id?: string | number) => string;
+/**
+ * Assert that a response body is a valid JSON-RPC error response.
+ *
+ * Validates the structure matches `JsonrpcErrorResponse` and optionally
+ * checks the error code.
+ *
+ * @param body - parsed response body
+ * @param expected_code - optional error code to assert
+ */
+export declare const assert_jsonrpc_error_response: (body: unknown, expected_code?: JsonrpcErrorCode) => void;
+/**
+ * Assert that a response body is a valid JSON-RPC success response.
+ *
+ * Validates the structure matches `JsonrpcResponse`. When `output_schema`
+ * is provided, also validates the `result` field against the declared
+ * output schema — matching the REST round-trip's `assert_response_matches_spec`.
+ *
+ * @param body - parsed response body
+ * @param output_schema - optional Zod schema to validate the `result` field against
+ */
+export declare const assert_jsonrpc_success_response: (body: unknown, output_schema?: z.ZodType) => void;
+//# sourceMappingURL=rpc_helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rpc_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/rpc_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAW7B,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAChC,QAAQ,MAAM,EACd,SAAS,OAAO,EAChB,KAAI,MAAM,GAAG,MAAe,KAC1B,WAID,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC9B,eAAe,MAAM,EACrB,QAAQ,MAAM,EACd,SAAS,OAAO,EAChB,KAAI,MAAM,GAAG,MAAe,KAC1B,MAMF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,OAAO,EACb,gBAAgB,gBAAgB,KAC9B,IAUF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,GAAI,MAAM,OAAO,EAAE,gBAAgB,CAAC,CAAC,OAAO,KAAG,IAU1F,CAAC"}

package/dist/testing/rpc_helpers.js

@@ -0,0 +1,74 @@
+import './assert_dev_env.js';
+/**
+ * JSON-RPC request construction and response assertion helpers.
+ *
+ * Shared by `rpc_attack_surface.ts` and `rpc_round_trip.ts`.
+ *
+ * @module
+ */
+import { assert } from 'vitest';
+import { z } from 'zod';
+import { JSONRPC_VERSION, JsonrpcErrorResponse, JsonrpcResponse } from '../http/jsonrpc.js';
+/**
+ * Create a `RequestInit` for a JSON-RPC POST request.
+ *
+ * @param method - JSON-RPC method name
+ * @param params - params object (omit for null-input methods)
+ * @param id - request id (default `'test'`)
+ * @returns a `RequestInit` with the JSON-RPC envelope as body
+ */
+export const create_rpc_post_init = (method, params, id = 'test') => ({
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ jsonrpc: JSONRPC_VERSION, method, params, id }),
+});
+/**
+ * Build a GET URL with JSON-RPC query parameters.
+ *
+ * @param endpoint_path - the RPC endpoint path (e.g., `/api/rpc`)
+ * @param method - JSON-RPC method name
+ * @param params - params object (omit for null-input methods)
+ * @param id - request id (default `'test'`)
+ * @returns the full URL with query string
+ */
+export const create_rpc_get_url = (endpoint_path, method, params, id = 'test') => {
+    const search = new URLSearchParams({ method, id: String(id) });
+    if (params !== undefined && params !== null) {
+        search.set('params', JSON.stringify(params));
+    }
+    return `${endpoint_path}?${search.toString()}`;
+};
+/**
+ * Assert that a response body is a valid JSON-RPC error response.
+ *
+ * Validates the structure matches `JsonrpcErrorResponse` and optionally
+ * checks the error code.
+ *
+ * @param body - parsed response body
+ * @param expected_code - optional error code to assert
+ */
+export const assert_jsonrpc_error_response = (body, expected_code) => {
+    const result = JsonrpcErrorResponse.safeParse(body);
+    assert.ok(result.success, `not a valid JSON-RPC error response: ${JSON.stringify(body)}`);
+    if (expected_code !== undefined) {
+        assert.strictEqual(result.data.error.code, expected_code, `expected error code ${expected_code}, got ${result.data.error.code}`);
+    }
+};
+/**
+ * Assert that a response body is a valid JSON-RPC success response.
+ *
+ * Validates the structure matches `JsonrpcResponse`. When `output_schema`
+ * is provided, also validates the `result` field against the declared
+ * output schema — matching the REST round-trip's `assert_response_matches_spec`.
+ *
+ * @param body - parsed response body
+ * @param output_schema - optional Zod schema to validate the `result` field against
+ */
+export const assert_jsonrpc_success_response = (body, output_schema) => {
+    const result = JsonrpcResponse.safeParse(body);
+    assert.ok(result.success, `not a valid JSON-RPC success response: ${JSON.stringify(body)}`);
+    if (output_schema) {
+        const output_result = output_schema.safeParse(result.data.result);
+        assert.ok(output_result.success, `JSON-RPC result does not match output schema: ${JSON.stringify(output_result.error?.issues)}`);
+    }
+};

package/dist/testing/rpc_round_trip.d.ts

@@ -0,0 +1,41 @@
+import './assert_dev_env.js';
+import type { RouteSpec } from '../http/route_spec.js';
+import type { AppServerContext, AppServerOptions } from '../server/app_server.js';
+import type { SessionOptions } from '../auth/session_cookie.js';
+import { type DbFactory } from './db.js';
+import type { RpcEndpointSpec } from '../http/surface.js';
+/** Options for `describe_rpc_round_trip_tests`. */
+export interface RpcRoundTripTestOptions {
+    /** Session config for cookie-based auth. */
+    session_options: SessionOptions<string>;
+    /** Route spec factory — same one used in production. */
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    /** RPC endpoint specs — the source `RpcAction` arrays for params generation. */
+    rpc_endpoints: Array<RpcEndpointSpec>;
+    /** Optional overrides for `AppServerOptions`. */
+    app_options?: Partial<Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'>>;
+    /** Database factories to run tests against. Default: pglite only. */
+    db_factories?: Array<DbFactory>;
+    /** Methods to skip, by name (e.g., `'tx_plan'`). */
+    skip_methods?: Array<string>;
+    /** Override generated params for specific methods (method name → params). */
+    input_overrides?: Map<string, Record<string, unknown>>;
+}
+/**
+ * Run schema-driven round-trip validation for RPC endpoints.
+ *
+ * For each method:
+ * 1. Generate valid params from the action's input schema
+ * 2. Fire a POST request with JSON-RPC envelope
+ * 3. For `side_effects: false` methods, also fire a GET request
+ * 4. Validate response is well-formed JSON-RPC; successful responses are
+ *    also validated against the method's declared output schema
+ *
+ * Error responses (from missing DB state, etc.) are expected and validated
+ * as well-formed JSON-RPC errors. Successful responses are validated against
+ * `action.spec.output`.
+ *
+ * @param options - round-trip test configuration
+ */
+export declare const describe_rpc_round_trip_tests: (options: RpcRoundTripTestOptions) => void;
+//# sourceMappingURL=rpc_round_trip.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rpc_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/rpc_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAe7B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAG9D,OAAO,EAAwB,KAAK,SAAS,EAAC,MAAM,SAAS,CAAC;AAK9D,OAAO,KAAK,EAAC,eAAe,EAAsB,MAAM,oBAAoB,CAAC;AAQ7E,mDAAmD;AACnD,MAAM,WAAW,uBAAuB;IACvC,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,gFAAgF;IAChF,aAAa,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACtC,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CACpB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,iBAAiB,GAAG,oBAAoB,CAAC,CAC5E,CAAC;IACF,qEAAqE;IACrE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC,oDAAoD;IACpD,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,6EAA6E;IAC7E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AA2BD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,6BAA6B,GAAI,SAAS,uBAAuB,KAAG,IAsIhF,CAAC"}

package/dist/testing/rpc_round_trip.js

@@ -0,0 +1,163 @@
+import './assert_dev_env.js';
+/**
+ * Schema-driven round-trip validation for RPC endpoints.
+ *
+ * For every RPC method, generates valid params and fires JSON-RPC requests
+ * (POST for all methods, GET for reads), validating that responses are
+ * well-formed JSON-RPC. Successful responses are validated against the
+ * method's declared output schema. DB-backed via `create_test_app`.
+ *
+ * @module
+ */
+import { describe, test, beforeAll, afterAll } from 'vitest';
+import { ROLE_ADMIN } from '../auth/role_schema.js';
+import { create_test_app } from './app_server.js';
+import { create_pglite_factory } from './db.js';
+import { generate_valid_body } from './schema_generators.js';
+import { run_migrations } from '../db/migrate.js';
+import { AUTH_MIGRATION_NS } from '../auth/migrations.js';
+import { create_rpc_post_init, create_rpc_get_url, assert_jsonrpc_error_response, assert_jsonrpc_success_response, } from './rpc_helpers.js';
+/**
+ * Pick auth headers matching an RPC method's auth requirement.
+ */
+const pick_rpc_auth_headers = (method, test_app, authed_account, admin_account) => {
+    switch (method.auth.type) {
+        case 'none':
+            return { host: 'localhost', origin: 'http://localhost:5173' };
+        case 'authenticated':
+            return authed_account.create_session_headers();
+        case 'role':
+            if (method.auth.role === ROLE_ADMIN) {
+                return admin_account.create_session_headers();
+            }
+            // keeper role uses the bootstrapped account
+            return test_app.create_session_headers();
+        case 'keeper':
+            return test_app.create_bearer_headers();
+    }
+};
+/**
+ * Run schema-driven round-trip validation for RPC endpoints.
+ *
+ * For each method:
+ * 1. Generate valid params from the action's input schema
+ * 2. Fire a POST request with JSON-RPC envelope
+ * 3. For `side_effects: false` methods, also fire a GET request
+ * 4. Validate response is well-formed JSON-RPC; successful responses are
+ *    also validated against the method's declared output schema
+ *
+ * Error responses (from missing DB state, etc.) are expected and validated
+ * as well-formed JSON-RPC errors. Successful responses are validated against
+ * `action.spec.output`.
+ *
+ * @param options - round-trip test configuration
+ */
+export const describe_rpc_round_trip_tests = (options) => {
+    const skip_set = new Set(options.skip_methods);
+    const init_schema = async (db) => {
+        await run_migrations(db, [AUTH_MIGRATION_NS]);
+    };
+    const factories = options.db_factories ?? [create_pglite_factory(init_schema)];
+    for (const factory of factories) {
+        describe(`RPC round-trip validation (${factory.name})`, () => {
+            if (factory.skip)
+                return;
+            let test_app;
+            let authed_account;
+            let admin_account;
+            let db;
+            beforeAll(async () => {
+                db = await factory.create();
+                test_app = await create_test_app({
+                    session_options: options.session_options,
+                    create_route_specs: options.create_route_specs,
+                    db,
+                    app_options: {
+                        rpc_endpoints: options.rpc_endpoints,
+                        ...options.app_options,
+                    },
+                });
+                authed_account = await test_app.create_account({
+                    username: 'rpc_round_trip_authed',
+                    roles: [],
+                });
+                admin_account = await test_app.create_account({
+                    username: 'rpc_round_trip_admin',
+                    roles: [ROLE_ADMIN],
+                });
+            });
+            afterAll(async () => {
+                await test_app.cleanup();
+                await factory.close(db);
+            });
+            test('all RPC methods produce valid JSON-RPC responses (POST)', async () => {
+                for (const ep_spec of options.rpc_endpoints) {
+                    const surface_ep = test_app.surface_spec.surface.rpc_endpoints.find((e) => e.path === ep_spec.path);
+                    if (!surface_ep)
+                        continue;
+                    for (const action of ep_spec.actions) {
+                        if (skip_set.has(action.spec.method))
+                            continue;
+                        const surface_method = surface_ep.methods.find((m) => m.name === action.spec.method);
+                        if (!surface_method)
+                            continue;
+                        // generate or override params
+                        const override = options.input_overrides?.get(action.spec.method);
+                        const params = override ?? generate_valid_body(action.spec.input) ?? null;
+                        // pick auth
+                        const headers = pick_rpc_auth_headers(surface_method, test_app, authed_account, admin_account);
+                        const init = create_rpc_post_init(action.spec.method, params);
+                        // merge auth headers into init
+                        Object.assign(init.headers, headers);
+                        const res = await test_app.app.request(ep_spec.path, init); // eslint-disable-line no-await-in-loop
+                        const body = await res.json(); // eslint-disable-line no-await-in-loop
+                        // validate well-formed JSON-RPC; successful responses also checked against output schema
+                        try {
+                            if (res.ok) {
+                                assert_jsonrpc_success_response(body, action.spec.output);
+                            }
+                            else {
+                                assert_jsonrpc_error_response(body);
+                            }
+                        }
+                        catch (e) {
+                            throw new Error(`RPC round-trip POST failed for ${action.spec.method} (status ${res.status}): ${e.message}`);
+                        }
+                    }
+                }
+            });
+            test('all read RPC methods produce valid JSON-RPC responses (GET)', async () => {
+                for (const ep_spec of options.rpc_endpoints) {
+                    const surface_ep = test_app.surface_spec.surface.rpc_endpoints.find((e) => e.path === ep_spec.path);
+                    if (!surface_ep)
+                        continue;
+                    const read_actions = ep_spec.actions.filter((a) => !a.spec.side_effects);
+                    for (const action of read_actions) {
+                        if (skip_set.has(action.spec.method))
+                            continue;
+                        const surface_method = surface_ep.methods.find((m) => m.name === action.spec.method);
+                        if (!surface_method)
+                            continue;
+                        const override = options.input_overrides?.get(action.spec.method);
+                        const params = override ?? generate_valid_body(action.spec.input) ?? undefined;
+                        const headers = pick_rpc_auth_headers(surface_method, test_app, authed_account, admin_account);
+                        const url = create_rpc_get_url(ep_spec.path, action.spec.method, params);
+                        const res = await test_app.app.request(url, { headers }); // eslint-disable-line no-await-in-loop
+                        const body = await res.json(); // eslint-disable-line no-await-in-loop
+                        try {
+                            if (res.ok) {
+                                assert_jsonrpc_success_response(body, action.spec.output);
+                            }
+                            else {
+                                assert_jsonrpc_error_response(body);
+                            }
+                        }
+                        catch (e) {
+                            throw new Error(`RPC round-trip GET failed for ${action.spec.method} (status ${res.status}): ${e.message}`);
+                        }
+                    }
+                }
+            });
+        });
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",