@fuzdev/fuz_app 0.147.0 → 0.149.0

package/dist/testing/integration_helpers.d.ts

@@ -1,5 +1,6 @@
 import './assert_dev_env.js';
 import type { RouteSpec, RouteMethod } from '../http/route_spec.js';
+import { type RouteAuth } from '../http/auth_shape.js';
 import type { Keyring } from '../auth/keyring.js';
 import { type SessionOptions } from '../auth/session_cookie.js';
 import type { TestAccount } from './app_server.js';
@@ -100,9 +101,36 @@ export interface KeeperHeaderProvider {
     create_daemon_token_headers: (extra?: Record<string, string>) => Record<string, string>;
 }
 /**
- * Pick request headers matching a route spec's auth requirement.
+ * Who a generated request calls as, picked from the declared auth: no
+ * credential for a public route or method, else the keeper's daemon token
+ * (`credential_types` names it), the admin account's session (an
+ * admin-gated one), the keeper's session (another role), or the authed
+ * account's session.
+ */
+export type AuthPrincipal = 'public' | 'daemon_token' | 'admin' | 'keeper' | 'authed';
+/**
+ * Pick the principal a generated request calls as, from its declared auth.
+ * Shared by the REST and RPC round-trips (`pick_auth_headers`,
+ * `pick_rpc_auth`), so both call each auth shape as the same principal.
  *
- * Maps `RouteAuth` onto a test account's credentials:
+ * Every principal but `'public'` carries a live credential of the kind the
+ * auth names, so the backend must authenticate it; a role mismatch (a keeper
+ * session on a role the keeper lacks) still refuses as 403, after
+ * authentication.
+ */
+export declare const pick_auth_principal: (auth: RouteAuth) => AuthPrincipal;
+/**
+ * The request headers carrying a principal's credential.
+ *
+ * @param principal - the principal `pick_auth_principal` chose
+ * @param keeper - the keeper's header builders
+ * @param authed_account - the account the `'authed'` principal calls as
+ * @param admin_account - the account the `'admin'` principal calls as
+ */
+export declare const to_principal_headers: (principal: AuthPrincipal, keeper: KeeperHeaderProvider, authed_account: TestAccount, admin_account: TestAccount) => Record<string, string>;
+/**
+ * Pick request headers matching a route spec's auth requirement
+ * (`pick_auth_principal`, then `to_principal_headers`):
  * - `none` — origin headers only
  * - `authenticated` — the authed account's session cookie
  * - `role: admin` — the admin account's session cookie
@@ -110,4 +138,35 @@ export interface KeeperHeaderProvider {
  * - `keeper` — the keeper provider's daemon token
  */
 export declare const pick_auth_headers: (spec: RouteSpec, keeper: KeeperHeaderProvider, authed_account: TestAccount, admin_account: TestAccount) => Record<string, string>;
+/**
+ * Whether a round-trip sends a request as a fresh account rather than the
+ * shared authed one: a side-effecting request picked for the `'authed'`
+ * principal. Generated input omits optional fields, and an omitted target on
+ * a self-service action is the caller — `account_delete` deletes it,
+ * `account_session_revoke_all`, a logout or a password change end its
+ * session — so any side-effecting call may destroy the credential it was sent
+ * with, and on a shared account every later call would refuse as
+ * unauthenticated. Keyed on the request's own side-effect signal (an action's
+ * `side_effects`, a route's non-`GET` method) rather than a list of known
+ * destroyers, so a consumer's self-targeting action is covered without
+ * registering it. The other principals stay shared: the keeper and its daemon
+ * token are one per fixture, and an admin-gated request with generated nil ids
+ * targets no existing account. A credential they lose still fails the
+ * round-trip on its 401 check (`is_unauthenticated_refusal`).
+ *
+ * @param principal - the principal `pick_auth_principal` chose
+ * @param side_effects - whether the request can change state
+ */
+export declare const round_trip_uses_fresh_account: (principal: AuthPrincipal, side_effects: boolean) => boolean;
+/**
+ * Whether a response says the request carried no valid credential: a 401
+ * whose reason is `authentication_required`, or that names no reason. A 401
+ * naming another reason is a handler's own answer to an authenticated call —
+ * `invalid_credentials` for a wrong current password — and is not this.
+ *
+ * @param status - the HTTP status
+ * @param reason - the refusal's reason: a REST body's `error`, a JSON-RPC
+ *   error's `data.reason`
+ */
+export declare const is_unauthenticated_refusal: (status: number, reason: unknown) => boolean;
 //# sourceMappingURL=integration_helpers.d.ts.map

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

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

package/dist/testing/integration_helpers.js

@@ -7,6 +7,7 @@ import './assert_dev_env.js';
 import { assert } from 'vitest';
 import { is_null_schema, merge_error_schemas } from '../http/schema_helpers.js';
 import { is_public_auth } from '../http/auth_shape.js';
+import { ERROR_AUTHENTICATION_REQUIRED } from '../http/error_schemas.js';
 import { create_session_cookie_value } from '../auth/session_cookie.js';
 import { ROLE_ADMIN } from '../auth/role_schema.js';
 /**
@@ -245,28 +246,84 @@ export const assert_no_sensitive_fields_in_json = (body, blocklist, context) =>
     }
 };
 /**
- * Pick request headers matching a route spec's auth requirement.
+ * Pick the principal a generated request calls as, from its declared auth.
+ * Shared by the REST and RPC round-trips (`pick_auth_headers`,
+ * `pick_rpc_auth`), so both call each auth shape as the same principal.
  *
- * Maps `RouteAuth` onto a test account's credentials:
+ * Every principal but `'public'` carries a live credential of the kind the
+ * auth names, so the backend must authenticate it; a role mismatch (a keeper
+ * session on a role the keeper lacks) still refuses as 403, after
+ * authentication.
+ */
+export const pick_auth_principal = (auth) => {
+    if (is_public_auth(auth))
+        return 'public';
+    if (auth.credential_types?.includes('daemon_token'))
+        return 'daemon_token';
+    if (auth.roles?.length)
+        return auth.roles.includes(ROLE_ADMIN) ? 'admin' : 'keeper';
+    return 'authed';
+};
+/**
+ * The request headers carrying a principal's credential.
+ *
+ * @param principal - the principal `pick_auth_principal` chose
+ * @param keeper - the keeper's header builders
+ * @param authed_account - the account the `'authed'` principal calls as
+ * @param admin_account - the account the `'admin'` principal calls as
+ */
+export const to_principal_headers = (principal, keeper, authed_account, admin_account) => {
+    switch (principal) {
+        case 'public':
+            return { host: 'localhost', origin: 'http://localhost:5173' };
+        case 'daemon_token':
+            return keeper.create_daemon_token_headers();
+        case 'admin':
+            return admin_account.create_session_headers();
+        case 'keeper':
+            return keeper.create_session_headers();
+        case 'authed':
+            return authed_account.create_session_headers();
+    }
+};
+/**
+ * Pick request headers matching a route spec's auth requirement
+ * (`pick_auth_principal`, then `to_principal_headers`):
  * - `none` — origin headers only
  * - `authenticated` — the authed account's session cookie
  * - `role: admin` — the admin account's session cookie
  * - `role: <other>` — the keeper provider's session
  * - `keeper` — the keeper provider's daemon token
  */
-export const pick_auth_headers = (spec, keeper, authed_account, admin_account) => {
-    const { auth } = spec;
-    if (is_public_auth(auth)) {
-        return { host: 'localhost', origin: 'http://localhost:5173' };
-    }
-    if (auth.credential_types?.includes('daemon_token')) {
-        return keeper.create_daemon_token_headers();
-    }
-    if (auth.roles?.length) {
-        if (auth.roles.includes(ROLE_ADMIN)) {
-            return admin_account.create_session_headers();
-        }
-        return keeper.create_session_headers();
-    }
-    return authed_account.create_session_headers();
-};
+export const pick_auth_headers = (spec, keeper, authed_account, admin_account) => to_principal_headers(pick_auth_principal(spec.auth), keeper, authed_account, admin_account);
+/**
+ * Whether a round-trip sends a request as a fresh account rather than the
+ * shared authed one: a side-effecting request picked for the `'authed'`
+ * principal. Generated input omits optional fields, and an omitted target on
+ * a self-service action is the caller — `account_delete` deletes it,
+ * `account_session_revoke_all`, a logout or a password change end its
+ * session — so any side-effecting call may destroy the credential it was sent
+ * with, and on a shared account every later call would refuse as
+ * unauthenticated. Keyed on the request's own side-effect signal (an action's
+ * `side_effects`, a route's non-`GET` method) rather than a list of known
+ * destroyers, so a consumer's self-targeting action is covered without
+ * registering it. The other principals stay shared: the keeper and its daemon
+ * token are one per fixture, and an admin-gated request with generated nil ids
+ * targets no existing account. A credential they lose still fails the
+ * round-trip on its 401 check (`is_unauthenticated_refusal`).
+ *
+ * @param principal - the principal `pick_auth_principal` chose
+ * @param side_effects - whether the request can change state
+ */
+export const round_trip_uses_fresh_account = (principal, side_effects) => principal === 'authed' && side_effects;
+/**
+ * Whether a response says the request carried no valid credential: a 401
+ * whose reason is `authentication_required`, or that names no reason. A 401
+ * naming another reason is a handler's own answer to an authenticated call —
+ * `invalid_credentials` for a wrong current password — and is not this.
+ *
+ * @param status - the HTTP status
+ * @param reason - the refusal's reason: a REST body's `error`, a JSON-RPC
+ *   error's `data.reason`
+ */
+export const is_unauthenticated_refusal = (status, reason) => status === 401 && (reason === undefined || reason === ERROR_AUTHENTICATION_REQUIRED);

package/dist/testing/round_trip.d.ts

@@ -1,4 +1,5 @@
 import './assert_dev_env.js';
+import { type AuthPrincipal } from './integration_helpers.js';
 import type { SetupTest, TestFixture } from './cross_backend/setup.js';
 import type { AppSurfaceSpec } from '../http/surface.js';
 /** Options for `describe_round_trip_validation`. */
@@ -38,6 +39,22 @@ export interface RoundTripTestOptions {
         body?: Record<string, unknown>;
     }>>;
 }
+/**
+ * Guard against a refusal that says the request carried no valid credential
+ * when it carried one (`is_unauthenticated_refusal`), the REST twin of
+ * `assert_rpc_authenticated`. Every non-public route is sent a live
+ * credential its auth admits, so a 401 reading `authentication_required`, or
+ * naming no reason, means the credential stopped working — most often because
+ * an earlier request ended it. A public route may answer 401 (a login with a
+ * wrong password), and so may a handler refusing an authenticated request
+ * with a reason of its own (`invalid_credentials`).
+ *
+ * @param route_key - the route, as `METHOD /path`
+ * @param status - the HTTP status
+ * @param body - the parsed response body, or `undefined` when not JSON
+ * @param principal - the principal the request was sent as
+ */
+export declare const assert_route_authenticated: (route_key: string, status: number, body: unknown, principal: AuthPrincipal) => void;
 /**
  * Run schema-driven round-trip validation tests.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AA+B7B,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,cAAc,EAAE,cAAc,CAAC;IAC/B,kDAAkD;IAClD,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,+EAA+E;IAC/E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,EAAE,GAAG,CACrB,MAAM,EACN,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CACnF,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B,GAAI,SAAS,oBAAoB,KAAG,IAmI9E,CAAC"}
+{"version":3,"file":"round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AA6B7B,OAAO,EAON,KAAK,aAAa,EAClB,MAAM,0BAA0B,CAAC;AAMlC,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,cAAc,EAAE,cAAc,CAAC;IAC/B,kDAAkD;IAClD,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,+EAA+E;IAC/E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,EAAE,GAAG,CACrB,MAAM,EACN,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CACnF,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,GACtC,WAAW,MAAM,EACjB,QAAQ,MAAM,EACd,MAAM,OAAO,EACb,WAAW,aAAa,KACtB,IAUF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B,GAAI,SAAS,oBAAoB,KAAG,IAmJ9E,CAAC"}

package/dist/testing/round_trip.js

@@ -8,19 +8,48 @@ import './assert_dev_env.js';
  * `setup_test` fixture-producing callback.
  *
  * Cadence: per-describe `setup_test()` call. Each test in the suite
- * fires one HTTP request against a shared fixture — no test mutates
- * state in a way that contaminates the next, so the per-test cost of
- * re-bootstrapping isn't justified here. Suites with state-isolation
- * requirements (integration, admin_integration, audit_completeness)
- * call `setup_test()` per test.
+ * fires one HTTP request against a shared fixture, so the per-test cost of
+ * re-bootstrapping isn't paid here. A mutation called as the authed account
+ * runs on a fresh account of its own (`round_trip_uses_fresh_account`) — a
+ * generated logout or self-delete would otherwise end the shared account's
+ * credential — and a 401 to any non-public request fails
+ * (`is_unauthenticated_refusal`), so a credential lost some other way goes
+ * red rather than vacuous. Suites with state-isolation requirements
+ * (integration, admin_integration, audit_completeness) call `setup_test()`
+ * per test.
  *
  * @module
  */
 import { describe, test, beforeAll, assert } from 'vitest';
 import { ROLE_ADMIN } from '../auth/role_schema.js';
-import { is_public_auth, needs_actor, input_schema_declares_acting } from '../http/auth_shape.js';
-import { assert_response_matches_spec, pick_auth_headers } from './integration_helpers.js';
+import { needs_actor, input_schema_declares_acting } from '../http/auth_shape.js';
+import { assert_response_matches_spec, is_unauthenticated_refusal, pick_auth_headers, pick_auth_principal, round_trip_uses_fresh_account, to_principal_headers } from './integration_helpers.js';
 import { resolve_valid_path, generate_valid_body, to_route_content_type } from './schema_generators.js';
+/**
+ * Guard against a refusal that says the request carried no valid credential
+ * when it carried one (`is_unauthenticated_refusal`), the REST twin of
+ * `assert_rpc_authenticated`. Every non-public route is sent a live
+ * credential its auth admits, so a 401 reading `authentication_required`, or
+ * naming no reason, means the credential stopped working — most often because
+ * an earlier request ended it. A public route may answer 401 (a login with a
+ * wrong password), and so may a handler refusing an authenticated request
+ * with a reason of its own (`invalid_credentials`).
+ *
+ * @param route_key - the route, as `METHOD /path`
+ * @param status - the HTTP status
+ * @param body - the parsed response body, or `undefined` when not JSON
+ * @param principal - the principal the request was sent as
+ */
+export const assert_route_authenticated = (route_key, status, body, principal) => {
+    if (principal === 'public')
+        return;
+    const reason = body !== null && typeof body === 'object' ? body.error : undefined;
+    if (!is_unauthenticated_refusal(status, reason))
+        return;
+    assert.fail(`${route_key} answered 401 (${JSON.stringify(reason ?? null)}) to the ${principal}` +
+        ` principal's credential — the request carried a credential its auth admits,` +
+        ` so a 401 here means that credential stopped working`);
+};
 /**
  * Run schema-driven round-trip validation tests.
  *
@@ -51,22 +80,23 @@ export const describe_round_trip_validation = (options) => {
                 roles: [ROLE_ADMIN]
             });
         });
-        // Mirror `pick_auth_headers`' account selection to recover the actor id
-        // of whichever account it authed as — so an `actor: 'required'` route
-        // that declares `acting?: ActingActor` gets the matching actor supplied
-        // explicitly (its sole actor, here), rather than relying on implicit
-        // single-actor resolution. Keeps such routes drivable without a
-        // consumer skip-list entry. Returns `null` for public routes.
-        const pick_acting_actor_id = (spec) => {
-            const { auth } = spec;
-            if (is_public_auth(auth))
-                return null;
-            if (auth.credential_types?.includes('daemon_token'))
-                return fixture.actor.id;
-            if (auth.roles?.length) {
-                return auth.roles.includes(ROLE_ADMIN) ? admin_account.actor.id : fixture.actor.id;
+        // The actor id of whichever account the principal calls as — so an
+        // `actor: 'required'` route that declares `acting?: ActingActor` gets the
+        // matching actor supplied explicitly (its sole actor, here), rather than
+        // relying on implicit single-actor resolution. Keeps such routes drivable
+        // without a consumer skip-list entry. `null` for public routes.
+        const to_acting_actor_id = (principal, authed) => {
+            switch (principal) {
+                case 'public':
+                    return null;
+                case 'admin':
+                    return admin_account.actor.id;
+                case 'authed':
+                    return authed.actor.id;
+                case 'daemon_token':
+                case 'keeper':
+                    return fixture.actor.id;
             }
-            return authed_account.actor.id;
         };
         test.each(describe_time_specs)('$method $path produces schema-valid response', async (spec) => {
             const route_key = `${spec.method} ${spec.path}`;
@@ -81,13 +111,19 @@ export const describe_round_trip_validation = (options) => {
             const url = resolve_valid_path(spec.path, spec.params);
             const override = options.input_overrides?.get(route_key);
             let body = override ?? generate_valid_body(spec.input);
-            const headers = pick_auth_headers(spec, fixture, authed_account, admin_account);
+            // a mutation called as the authed account runs on a fresh one, so a
+            // logout or a self-delete can't end the shared account's credential
+            const principal = pick_auth_principal(spec.auth);
+            const authed = round_trip_uses_fresh_account(principal, spec.method !== 'GET')
+                ? await fixture.create_account({ roles: [] })
+                : authed_account;
+            const headers = to_principal_headers(principal, fixture, authed, admin_account);
             // Auto-supply `acting` for actor-required routes that declare it. The
             // `actor !== 'none' ⟺ acting declared` registry invariant means a
             // route either declares `acting` in `query` (REST GET/body-less) or
             // `input` — supply the picked account's actor in the matching channel.
             let request_url = url;
-            const acting_id = needs_actor(spec.auth) ? pick_acting_actor_id(spec) : null;
+            const acting_id = needs_actor(spec.auth) ? to_acting_actor_id(principal, authed) : null;
             if (acting_id !== null) {
                 if (spec.query && input_schema_declares_acting(spec.query)) {
                     request_url = `${url}${url.includes('?') ? '&' : '?'}acting=${acting_id}`;
@@ -107,6 +143,13 @@ export const describe_round_trip_validation = (options) => {
                 return;
             }
             try {
+                if (res.status === 401) {
+                    const body = await res
+                        .clone()
+                        .json()
+                        .catch(() => undefined);
+                    assert_route_authenticated(route_key, res.status, body, principal);
+                }
                 await assert_response_matches_spec(describe_time_specs, spec.method, url, res);
             }
             catch (e) {

package/dist/testing/rpc_attack_surface.d.ts

@@ -6,6 +6,16 @@ export interface RpcAttackSurfaceOptions {
     build: () => AppSurfaceSpec;
     /** All roles in the app (e.g. `['admin', 'keeper']`). */
     roles: Array<string>;
+    /**
+     * Valid params per method (method name → params) to build its adversarial
+     * params cases from, in place of the generated base — for an input whose
+     * valid shape the generator can't reach. Each must pass the method's input
+     * schema; one that doesn't throws at collection, naming the method. The
+     * cases are sent as a single-actor principal, so an override omits
+     * `acting`. The cross-process twin is
+     * `RpcAdversarialCrossTestOptions.input_overrides`.
+     */
+    input_overrides?: ReadonlyMap<string, Record<string, unknown>>;
 }
 /**
  * Run the standard RPC attack surface test suite.

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

@@ -1 +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,EAGX,cAAc,EACd,MAAM,oBAAoB,CAAC;AA0B5B,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;AA8dD;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,GAAI,SAAS,uBAAuB,KAAG,IAOpF,CAAC"}
+{"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,EAGX,cAAc,EACd,MAAM,oBAAoB,CAAC;AA+B5B,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;IACrB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/D;AA2VD;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,GAAI,SAAS,uBAAuB,KAAG,IAOpF,CAAC"}

package/dist/testing/rpc_attack_surface.js

@@ -16,10 +16,10 @@ import { test, assert, describe } from 'vitest';
 import { is_keeper_auth, is_public_auth, is_role_auth } from '../http/auth_shape.js';
 import { JSONRPC_ERROR_CODES } from '../http/jsonrpc_errors.js';
 import { create_auth_test_apps, create_test_app_from_specs, create_test_request_context, select_auth_app } from './auth_apps.js';
-import { generate_input_test_cases } from './adversarial_input.js';
 import { generate_valid_body } from './schema_generators.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';
+import { assert_rpc_envelope_refusal, create_rpc_envelope_cases, generate_rpc_params_test_cases, to_rpc_envelope_request } from './rpc_envelope_cases.js';
+import { expected_invalid_reason } from './adversarial_input_cases.js';
 // --- Helpers ---
 /** Filter RPC methods that require any form of authentication. */
 const filter_protected_rpc_methods = (endpoint) => endpoint.methods.filter((m) => !is_public_auth(m.auth));
@@ -169,148 +169,27 @@ const describe_rpc_auth = (options) => {
 /**
  * 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).
+ * Runs `create_rpc_envelope_cases` for each endpoint: the dispatcher's
+ * envelope parsing, method lookup, and GET read restriction.
  */
 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 public_apps = create_auth_test_apps(route_specs, []);
     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 (validation) or auth error
-                    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);
+                for (const c of create_rpc_envelope_cases(endpoint)) {
+                    test(c.name, async () => {
+                        const app = c.as === 'anonymous'
+                            ? public_apps.public
+                            : select_auth_app(authed_apps, c.method.auth);
+                        const { url, init } = to_rpc_envelope_request(endpoint.path, c);
+                        const res = await app.request(url, init);
+                        assert_rpc_envelope_refusal(res.status, await res.json(), c);
                     });
                 }
             });
@@ -323,8 +202,10 @@ const describe_rpc_adversarial_envelopes = (options) => {
  *
  * 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 `testing/adversarial_input.ts`.
+ * and wraps them in valid JSON-RPC envelopes, via `generate_rpc_params_test_cases`;
+ * a method's `input_overrides` entry, when given, is the base they're built from.
+ * Each owes 400 `invalid_params` with the broken field's declared
+ * `invalid_reason` as `data.reason`, or no reason (`expected_invalid_reason`).
  */
 const describe_rpc_adversarial_params = (options) => {
     const { build, roles } = options;
@@ -348,10 +229,10 @@ const describe_rpc_adversarial_params = (options) => {
                         });
                         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);
+                    const test_cases = generate_rpc_params_test_cases(action.spec.input, {
+                        base: options.input_overrides?.get(method.name),
+                        label: method.name
+                    });
                     if (test_cases.length === 0)
                         continue;
                     total_cases += test_cases.length;
@@ -363,6 +244,12 @@ const describe_rpc_adversarial_params = (options) => {
                                 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);
+                                // the broken field's declared reason, or none
+                                const data = body.error.data;
+                                const reason = typeof data === 'object' && data !== null
+                                    ? data.reason
+                                    : undefined;
+                                assert.strictEqual(reason, expected_invalid_reason(action.spec.input, tc), `data.reason for ${method.name} [${tc.label}]`);
                             });
                         }
                     });