@fuzdev/fuz_app 0.146.1 → 0.148.0

package/dist/testing/cross_backend/role_grant_role_grammar.js

@@ -32,7 +32,8 @@ import '../assert_dev_env.js';
 import { assert, describe, test } from 'vitest';
 import { ERROR_ROLE_NOT_WEB_GRANTABLE } from '../../http/error_schemas.js';
 import { JSONRPC_ERROR_CODES } from '../../http/jsonrpc_errors.js';
-import { cross_rpc_call, error_reason } from './cell_cross_helpers.js';
+import { list_audit_events } from './audit_cross_helpers.js';
+import { cross_rpc_call, error_reason } from './cross_rpc.js';
 import { SPINE_RPC_PATH } from './spine_surface_constants.js';
 const NIL_UUID = '00000000-0000-0000-0000-000000000000';
 /**
@@ -63,7 +64,7 @@ const GRANT_EVENT_TYPES = ['role_grant_create', 'role_grant_offer_create'];
 export const describe_role_grant_role_grammar_cross_tests = (options) => {
     const { setup_test } = options;
     const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
-    describe('grant verbs refuse an off-grammar role at validation', { timeout: 30_000 }, () => {
+    describe('grant verbs refuse an off-grammar role at validation', () => {
         for (const method of GRANT_METHODS) {
             test(`${method}: an off-grammar role is invalid_params with no reason`, async () => {
                 const fixture = await setup_test();
@@ -94,14 +95,10 @@ export const describe_role_grant_role_grammar_cross_tests = (options) => {
             // and the length cap is inclusive: a role exactly at it is on the grammar
             const at_length = await cross_rpc_call(t, rpc_path, 'role_grant_assign', { to_account_id: NIL_UUID, role: AT_LENGTH_ROLE }, session);
             assert.strictEqual(error_reason(at_length), ERROR_ROLE_NOT_WEB_GRANTABLE, 'a role at the length cap passes validation');
-            // a barrier before reading the log: both spines write audit rows off
-            // the request path
-            const drained = await cross_rpc_call(fixture.fresh_transport({ origin: null }), rpc_path, '_testing_drain_effects', undefined, fixture.create_daemon_token_headers());
-            assert.ok(drained.ok, `_testing_drain_effects failed: ${JSON.stringify(drained.error)}`);
+            // both spines write audit rows off the request path, so each read is
+            // behind the drain barrier
             for (const event_type of GRANT_EVENT_TYPES) {
-                const listed = await cross_rpc_call(t, rpc_path, 'audit_log_list', { event_type }, session);
-                assert.ok(listed.ok, `audit_log_list failed: ${JSON.stringify(listed.error)}`);
-                const events = listed.result.events;
+                const events = await list_audit_events(fixture, { event_type }, rpc_path);
                 const roles = events.map((event) => event.metadata?.role);
                 for (const role of roles) {
                     assert.ok(typeof role !== 'string' || !OFF_GRAMMAR_ROLES.includes(role), `${event_type}: an audit row records the off-grammar role ${JSON.stringify(role)}`);

package/dist/testing/cross_backend/rpc_adversarial.d.ts

@@ -0,0 +1,38 @@
+import '../assert_dev_env.js';
+import { type AppSurfaceSpec, type RpcEndpointSpec } from '../../http/surface.js';
+import type { RpcPathCrossSuiteOptions } from './setup.js';
+/** Options for `describe_rpc_adversarial_cross_tests`. */
+export interface RpcAdversarialCrossTestOptions extends RpcPathCrossSuiteOptions {
+    /** The declared surface; the endpoint at `rpc_path` supplies the methods and their input schemas. */
+    readonly surface_source: AppSurfaceSpec;
+    /**
+     * The endpoints the backend live-mounts (resolved —
+     * `resolve_rpc_endpoints_for_setup` turns the factory form into this). The
+     * methods the one at `rpc_path` carries beyond the declared surface run
+     * through both groups too. Omitted, only declared methods run.
+     */
+    readonly live_rpc_endpoints?: ReadonlyArray<RpcEndpointSpec>;
+    /** Methods to leave out, beyond the protocol actions always skipped. */
+    readonly skip_methods?: ReadonlyArray<string>;
+    /**
+     * Generated params cases a backend is known to answer otherwise, each run
+     * as its own `xfail_until` test; the method's other cases keep their test.
+     * Pass it only for the backend that diverges.
+     */
+    readonly xfail_params?: ReadonlyArray<RpcParamsXfail>;
+}
+/** Generated params cases of one method marked `xfail_until`, by case label. */
+export interface RpcParamsXfail {
+    readonly method: string;
+    /** `InputTestCase.label`s of `generate_rpc_params_test_cases(method's input)`. */
+    readonly labels: ReadonlyArray<string>;
+    readonly tracking_id: string;
+    readonly reason: string;
+}
+/**
+ * Run the cross-process malformed-envelope and invalid-params suite.
+ *
+ * @param options - the fixture, the declared surface and live mount, the RPC path, and methods to skip
+ */
+export declare const describe_rpc_adversarial_cross_tests: (options: RpcAdversarialCrossTestOptions) => void;
+//# sourceMappingURL=rpc_adversarial.d.ts.map

package/dist/testing/cross_backend/rpc_adversarial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc_adversarial.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/rpc_adversarial.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAyE9B,OAAO,EAGN,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,MAAM,uBAAuB,CAAC;AAoB/B,OAAO,KAAK,EAAE,wBAAwB,EAAe,MAAM,YAAY,CAAC;AAKxE,0DAA0D;AAC1D,MAAM,WAAW,8BAA+B,SAAQ,wBAAwB;IAC/E,qGAAqG;IACrG,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC7D,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACtD;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAmGD;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,GAChD,SAAS,8BAA8B,KACrC,IA8JF,CAAC"}

package/dist/testing/cross_backend/rpc_adversarial.js

@@ -0,0 +1,292 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process malformed-envelope and invalid-params suite for a JSON-RPC
+ * endpoint.
+ *
+ * `describe_rpc_attack_surface_tests` runs its envelope and params groups
+ * in-process against stub apps, so they never reach a spawned backend — and
+ * the Rust spine parses envelopes and params by hand, while the
+ * action-manifest parity gate compares declarations and is blind to param
+ * schemas. This suite sends the same requests over `fixture.transport` to
+ * each backend.
+ *
+ * Two groups:
+ *
+ * - **Envelopes** — `create_rpc_envelope_cases`, the in-process group's set:
+ *   non-JSON body, wrong or missing `jsonrpc`, missing `method` or `id`, a
+ *   batch array, non-object POST params, an unknown method, `GET` missing
+ *   `method` or `id`, `GET` invalid-JSON params, `GET` non-object params on
+ *   every read, and a `GET` of a mutating method.
+ *   Each is sent by the principal its method's auth admits, so the envelope
+ *   check is what refuses, and each pins status, JSON-RPC code, the echoed
+ *   `id`, and `data.reason` (exact where the TS dispatcher sets one, absent
+ *   otherwise). Three ordering cases go without a credential: an anonymous
+ *   `GET` of a mutating method is refused `invalid_request` rather than 401
+ *   (the read restriction runs after the method lookup and before
+ *   authorization), an anonymous batch array is refused `invalid_request`
+ *   with `id: null` (the envelope parse runs before auth, and batches are
+ *   unsupported), and an anonymous `GET` with non-object params is the 401
+ *   (params validation runs after authorization).
+ * - **Params** — for each declared method (and each live-mounted one, below),
+ *   `generate_rpc_params_test_cases`
+ *   (the in-process generator minus its structural cases), each sent as the
+ *   method's authorized principal and owing 400 `invalid_params` with no
+ *   `data.reason`. One test per method, reporting every case that answers
+ *   otherwise; `xfail_params` runs named cases of a method as their own
+ *   `xfail_until` tests, for a known divergence on one backend.
+ *
+ * The authorized principal is the keeper on the first channel the method's
+ * auth admits: its session, else its daemon token or API token over a
+ * no-`Origin` transport (`resolve_conformance_principal`), mirroring the
+ * in-process `select_auth_app`. **Preconditions:** the keeper holds every
+ * role a declared method gates on (`default_cross_process_setup` seeds
+ * `keeper` and `admin`; pass `extra_keeper_roles` for others), and it has a
+ * single actor. No generated body carries a valid `acting` — the generator's
+ * base fills only required and defaulted fields — and a malformed `acting` is
+ * read as omitted ahead of validation on both spines, so a single-actor
+ * keeper resolves its actor and validation is what refuses. A keeper with a
+ * second actor answers `actor_required` first; such a suite lists the
+ * actor-required methods in `skip_methods`.
+ *
+ * **Off the declared surface.** `live_rpc_endpoints` adds the methods the
+ * backend live-mounts at `rpc_path` beyond the declared surface — cell verbs,
+ * opt-in resolvers, the `_testing_*` backdoors. Both groups run over them too:
+ * the envelope cases built from those methods, in a group of their own, and a
+ * params test per method, `_testing_*` included (a daemon-only backdoor is
+ * sent with the keeper's daemon token). A spine that keeps a method family off
+ * its declared surface still owes the twin's answer to bad params there.
+ *
+ * Skipped: `_testing_*` methods on the declared surface (a declared surface
+ * lists them only by accident; the live mount is where they are walked), and
+ * the protocol actions (`PROTOCOL_ACTION_METHODS`, fixed shared specs covered
+ * by the WS suites, which `generate_rpc_auth_conformance_cases` skips too).
+ *
+ * Cross-process only: in-process, `describe_rpc_attack_surface_tests` runs
+ * the same envelope cases and params generator.
+ *
+ * @module
+ */
+import { assert, describe, test } from 'vitest';
+import { generate_app_surface } from '../../http/surface.js';
+import { is_public_auth } from '../../http/auth_shape.js';
+import { JSONRPC_ERROR_CODES } from '../../http/jsonrpc_errors.js';
+import { BUILTIN_CREDENTIAL_TYPES, CREDENTIAL_TYPE_API_TOKEN, CREDENTIAL_TYPE_DAEMON_TOKEN, CREDENTIAL_TYPE_SESSION } from '../../auth/credential_type_schema.js';
+import { PROTOCOL_ACTION_METHODS } from '../../actions/action_codegen.js';
+import { TESTING_METHOD_PREFIX } from '../surface_invariants.js';
+import { create_rpc_post_init } 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 { resolve_conformance_principal } from './conformance_table.js';
+import { SPINE_RPC_PATH } from './spine_surface_constants.js';
+import { xfail_until } from './xfail.js';
+const PROTOCOL_METHODS = new Set(PROTOCOL_ACTION_METHODS);
+/** The keeper principal on each builtin credential channel. */
+const CHANNEL_PRINCIPALS = {
+    [CREDENTIAL_TYPE_SESSION]: 'keeper',
+    [CREDENTIAL_TYPE_DAEMON_TOKEN]: 'daemon',
+    [CREDENTIAL_TYPE_API_TOKEN]: 'token'
+};
+/**
+ * The principal a method's auth admits: the keeper's session where the
+ * method takes one, else the first builtin channel its credential gate
+ * names — the choice the in-process `select_auth_app` makes, minus its throw
+ * on a non-session channel paired with a role other than keeper (the keeper
+ * holds every builtin role, so sending its token there still passes the gate).
+ *
+ * @param auth - the method's declared auth
+ * @returns the principal to send as
+ */
+const to_authorized_principal = (auth) => {
+    if (is_public_auth(auth))
+        return 'anonymous';
+    const credential_types = auth.credential_types;
+    if (!credential_types?.length || credential_types.includes(CREDENTIAL_TYPE_SESSION)) {
+        return 'keeper';
+    }
+    const channel = BUILTIN_CREDENTIAL_TYPES.find((t) => credential_types.includes(t));
+    const principal = channel === undefined ? undefined : CHANNEL_PRINCIPALS[channel];
+    if (!principal) {
+        throw new Error(`rpc_adversarial: no builtin channel admits credential types '${credential_types.join("', '")}'`);
+    }
+    return principal;
+};
+const send_as = async (fixture, auth, as, url, init) => {
+    const principal = as === 'anonymous' ? 'anonymous' : to_authorized_principal(auth);
+    const { transport, headers } = await resolve_conformance_principal(fixture, principal);
+    const res = await transport(url, {
+        ...init,
+        headers: { ...init.headers, ...headers }
+    });
+    const text = await res.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = text;
+    }
+    return { status: res.status, body };
+};
+const reason_of = (body) => {
+    const data = body?.error?.data;
+    return typeof data === 'object' && data !== null
+        ? data.reason
+        : undefined;
+};
+/**
+ * The live-mounted actions at `rpc_path` the declared endpoint lacks, each
+ * method once, in mount order, with their surface form.
+ */
+const to_off_surface = (rpc_path, declared, live_rpc_endpoints) => {
+    const seen = new Set(declared);
+    const actions = [];
+    for (const live of live_rpc_endpoints ?? []) {
+        if (live.path !== rpc_path)
+            continue;
+        for (const action of live.actions) {
+            if (seen.has(action.spec.method))
+                continue;
+            seen.add(action.spec.method);
+            actions.push(action);
+        }
+    }
+    if (actions.length === 0)
+        return null;
+    const surface = generate_app_surface({
+        route_specs: [],
+        middleware_specs: [],
+        rpc_endpoints: [{ path: rpc_path, actions }]
+    });
+    const endpoint = surface.rpc_endpoints[0];
+    if (!endpoint)
+        throw new Error(`rpc_adversarial: no surface for the live mount at '${rpc_path}'`);
+    return { actions, endpoint };
+};
+/**
+ * Run the cross-process malformed-envelope and invalid-params suite.
+ *
+ * @param options - the fixture, the declared surface and live mount, the RPC path, and methods to skip
+ */
+export const describe_rpc_adversarial_cross_tests = (options) => {
+    const { setup_test, surface_source } = options;
+    const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
+    const skip = new Set(options.skip_methods);
+    const endpoint = surface_source.surface.rpc_endpoints.find((e) => e.path === rpc_path);
+    const endpoint_spec = surface_source.rpc_endpoints.find((e) => e.path === rpc_path);
+    const off_surface = endpoint
+        ? to_off_surface(rpc_path, 
+        // a `_testing_*` method listed on the declared surface is skipped there,
+        // so it must stay eligible here, where the live mount walks it
+        new Set(endpoint.methods
+            .map((m) => m.name)
+            .filter((name) => !name.startsWith(TESTING_METHOD_PREFIX))), options.live_rpc_endpoints)
+        : null;
+    describe('RPC adversarial envelopes (cross-process)', () => {
+        if (!endpoint || !endpoint_spec) {
+            test('the RPC endpoint is on the declared surface', () => {
+                assert.fail(`no RPC endpoint at '${rpc_path}' on the declared surface`);
+            });
+            return;
+        }
+        const cases = create_rpc_envelope_cases(endpoint, { skip_methods: options.skip_methods });
+        test('the envelope cases cover the endpoint', () => {
+            // both halves need a read and a mutation to choose; a surface
+            // lacking either loses cases silently otherwise
+            assert.ok(cases.some((c) => !c.method.side_effects), 'no read method to carry the POST and GET envelope cases');
+            assert.ok(cases.some((c) => c.method.side_effects), 'no authenticated mutation to carry the GET read-restriction cases');
+        });
+        for (const c of cases) {
+            test(c.name, async () => {
+                const fixture = await setup_test();
+                const { url, init } = to_rpc_envelope_request(rpc_path, c);
+                const { status, body } = await send_as(fixture, c.method.auth, c.as, url, init);
+                assert_rpc_envelope_refusal(status, body, c);
+            });
+        }
+    });
+    if (off_surface) {
+        describe('RPC adversarial envelopes, live-mounted methods off the declared surface (cross-process)', () => {
+            for (const c of create_rpc_envelope_cases(off_surface.endpoint, {
+                skip_methods: options.skip_methods
+            })) {
+                test(c.name, async () => {
+                    const fixture = await setup_test();
+                    const { url, init } = to_rpc_envelope_request(rpc_path, c);
+                    const { status, body } = await send_as(fixture, c.method.auth, c.as, url, init);
+                    assert_rpc_envelope_refusal(status, body, c);
+                });
+            }
+        });
+    }
+    describe('RPC adversarial params (cross-process)', () => {
+        if (!endpoint || !endpoint_spec)
+            return;
+        let total = 0;
+        const xfails = new Map();
+        for (const x of options.xfail_params ?? []) {
+            for (const label of x.labels)
+                xfails.set(`${x.method}\0${label}`, x);
+        }
+        const matched_xfails = new Set();
+        /** Send one case; a refusal message when it is not the canonical 400. */
+        const check_case = async (fixture, action, tc) => {
+            const { status, body } = await send_as(fixture, action.spec.auth, 'authorized', rpc_path, create_rpc_post_init(action.spec.method, tc.body));
+            const code = body?.error?.code;
+            if (status === 400 &&
+                code === JSONRPC_ERROR_CODES.invalid_params &&
+                reason_of(body) === undefined) {
+                return null;
+            }
+            return `[${tc.label}] params ${JSON.stringify(tc.body)} → ${status} ${JSON.stringify(body)}`;
+        };
+        // the declared methods, then the live-mounted ones the declared surface lacks
+        const declared_actions = endpoint_spec.actions.filter((action) => !action.spec.method.startsWith(TESTING_METHOD_PREFIX) &&
+            endpoint.methods.some((m) => m.name === action.spec.method));
+        for (const action of [...declared_actions, ...(off_surface?.actions ?? [])]) {
+            const { method, input } = action.spec;
+            if (PROTOCOL_METHODS.has(method))
+                continue;
+            if (skip.has(method))
+                continue;
+            const all_cases = generate_rpc_params_test_cases(input);
+            if (all_cases.length === 0)
+                continue;
+            total += all_cases.length;
+            const param_cases = [];
+            for (const tc of all_cases) {
+                const key = `${method}\0${tc.label}`;
+                const xfail = xfails.get(key);
+                if (!xfail) {
+                    param_cases.push(tc);
+                    continue;
+                }
+                matched_xfails.add(key);
+                xfail_until(xfail.tracking_id, xfail.reason, `${method}: [${tc.label}] → 400 invalid_params`, async () => {
+                    const failure = await check_case(await setup_test(), action, tc);
+                    assert.strictEqual(failure, null);
+                });
+            }
+            if (param_cases.length === 0)
+                continue;
+            test(`${method}: every generated invalid params case → 400 invalid_params`, async () => {
+                const fixture = await setup_test();
+                const failures = [];
+                for (const tc of param_cases) {
+                    const failure = await check_case(fixture, action, tc);
+                    if (failure)
+                        failures.push(failure);
+                }
+                assert.deepStrictEqual(failures, [], `${method}: ${failures.length} of ${param_cases.length} cases not refused invalid_params`);
+            });
+        }
+        test('every xfail_params entry names a generated case', () => {
+            // a stale entry would otherwise xfail nothing, silently
+            const unmatched = [...xfails.keys()]
+                .filter((key) => !matched_xfails.has(key))
+                .map((key) => key.replace('\0', ': '));
+            assert.deepStrictEqual(unmatched, []);
+        });
+        test('generated params cases exist', () => {
+            assert.ok(total > 0, 'no params cases generated — schema walking may be broken');
+        });
+    });
+};

package/dist/testing/cross_backend/rpc_success_fixtures.d.ts

@@ -0,0 +1,24 @@
+import '../assert_dev_env.js';
+import type { RpcSuccessFixtures } from '../rpc_round_trip.js';
+/** Options for `create_spine_rpc_success_fixtures`. */
+export interface SpineRpcSuccessFixturesOptions {
+    /** The JSON-RPC endpoint path the standard actions are mounted on. Default `SPINE_RPC_PATH`. */
+    readonly rpc_path?: string;
+}
+/**
+ * Build the success-fixture map for the standard spine methods that need a
+ * real row id: `account_token_revoke`, `account_session_revoke`,
+ * `invite_delete`, `role_grant_revoke`, `role_grant_offer_accept`,
+ * `role_grant_offer_decline`, and `role_grant_offer_retract`.
+ *
+ * Each factory mints fresh accounts — a fresh `ROLE_ADMIN` holder as grantor
+ * where the setup step is admin-gated — and builds its row as a real client
+ * would, then returns the headers of the account that calls: the owner for
+ * token and session revoke, accept, decline, and retract; the fresh admin
+ * for invite delete and role grant revoke.
+ *
+ * @param options - the RPC endpoint path
+ * @returns the method → fixture-factory map
+ */
+export declare const create_spine_rpc_success_fixtures: (options?: SpineRpcSuccessFixturesOptions) => RpcSuccessFixtures;
+//# sourceMappingURL=rpc_success_fixtures.d.ts.map

package/dist/testing/cross_backend/rpc_success_fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc_success_fixtures.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/rpc_success_fixtures.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAqC9B,OAAO,KAAK,EAAqB,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAOlF,uDAAuD;AACvD,MAAM,WAAW,8BAA8B;IAC9C,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iCAAiC,GAC7C,UAAS,8BAAmC,KAC1C,kBAwHF,CAAC"}

package/dist/testing/cross_backend/rpc_success_fixtures.js

@@ -0,0 +1,124 @@
+import '../assert_dev_env.js';
+/**
+ * Success fixtures for the standard spine RPC methods that act on an existing
+ * row — revoke a token or a session, delete an invite, revoke a role grant,
+ * accept, decline, or retract an offer. The generic round-trip sends nil ids,
+ * so on its own it only ever sees these methods refuse with `not_found`; each
+ * fixture here builds the real row through the backend's own RPC surface and
+ * returns the params (and, where the row must belong to the caller, the
+ * caller's headers) that drive a **success** response, which
+ * `describe_rpc_round_trip_tests` then validates against the method's output
+ * schema on every backend.
+ *
+ * Spine-generic: the fixtures use only standard RPC actions and the builtin
+ * `ROLE_ADMIN`, so any consumer mounting `create_standard_rpc_actions` can
+ * pass the map to `describe_standard_cross_process_tests` (as
+ * `rpc_success_fixtures`), `describe_standard_tests`, or
+ * `describe_rpc_round_trip_tests` (as `success_fixtures`). Each fixture mints
+ * its own accounts and calls as one of them, so none touches or calls as the
+ * suite's shared identities.
+ *
+ * @module
+ */
+import { assert } from 'vitest';
+import { account_session_list_action_spec, account_token_create_action_spec } from '../../auth/account_action_specs.js';
+import { invite_create_action_spec } from '../../auth/admin_action_specs.js';
+import { role_grant_assign_action_spec, role_grant_offer_create_action_spec } from '../../auth/role_grant_offer_action_specs.js';
+import { ROLE_ADMIN } from '../../auth/role_schema.js';
+import { rpc_call_typed } from '../rpc_helpers.js';
+import { SPINE_RPC_PATH } from './spine_surface_constants.js';
+/**
+ * Build the success-fixture map for the standard spine methods that need a
+ * real row id: `account_token_revoke`, `account_session_revoke`,
+ * `invite_delete`, `role_grant_revoke`, `role_grant_offer_accept`,
+ * `role_grant_offer_decline`, and `role_grant_offer_retract`.
+ *
+ * Each factory mints fresh accounts — a fresh `ROLE_ADMIN` holder as grantor
+ * where the setup step is admin-gated — and builds its row as a real client
+ * would, then returns the headers of the account that calls: the owner for
+ * token and session revoke, accept, decline, and retract; the fresh admin
+ * for invite delete and role grant revoke.
+ *
+ * @param options - the RPC endpoint path
+ * @returns the method → fixture-factory map
+ */
+export const create_spine_rpc_success_fixtures = (options = {}) => {
+    const { rpc_path = SPINE_RPC_PATH } = options;
+    const call = (fixture, spec, params, headers) => rpc_call_typed({ app: fixture.transport, path: rpc_path, method: spec.method, params, headers }, spec.output);
+    const create_grantor = (fixture) => fixture.create_account({ roles: [ROLE_ADMIN] });
+    const create_pending_offer = async (fixture) => {
+        const grantor = await create_grantor(fixture);
+        const recipient = await fixture.create_account();
+        const { offer } = await call(fixture, role_grant_offer_create_action_spec, { to_account_id: recipient.account.id, role: ROLE_ADMIN }, grantor.create_session_headers());
+        return { grantor, recipient, offer_id: offer.id };
+    };
+    const fixtures = new Map([
+        [
+            'account_token_revoke',
+            async (fixture) => {
+                const owner = await fixture.create_account();
+                const headers = owner.create_session_headers();
+                const token = await call(fixture, account_token_create_action_spec, {
+                    name: 'rpc success fixture',
+                    scope: { kind: 'full' },
+                    lifetime: { kind: 'eternal' }
+                }, headers);
+                return { params: { token_id: token.id }, headers };
+            }
+        ],
+        [
+            'account_session_revoke',
+            async (fixture) => {
+                // a throwaway account revokes its own session, the one it calls with
+                const owner = await fixture.create_account();
+                const headers = owner.create_session_headers();
+                const { sessions } = await call(fixture, account_session_list_action_spec, undefined, headers);
+                const session = sessions[0];
+                assert.ok(session, 'account_session_revoke fixture: the fresh account lists no session');
+                return { params: { session_id: session.id }, headers };
+            }
+        ],
+        [
+            'invite_delete',
+            async (fixture) => {
+                const grantor = await create_grantor(fixture);
+                const { invite } = await call(fixture, invite_create_action_spec, { username: `inv${crypto.randomUUID().replaceAll('-', '').slice(0, 24)}` }, grantor.create_session_headers());
+                return { params: { invite_id: invite.id }, headers: grantor.create_session_headers() };
+            }
+        ],
+        [
+            'role_grant_revoke',
+            async (fixture) => {
+                const grantor = await create_grantor(fixture);
+                const grantee = await fixture.create_account();
+                const { role_grant_id } = await call(fixture, role_grant_assign_action_spec, { to_account_id: grantee.account.id, role: ROLE_ADMIN }, grantor.create_session_headers());
+                return {
+                    params: { actor_id: grantee.actor.id, role_grant_id },
+                    headers: grantor.create_session_headers()
+                };
+            }
+        ],
+        [
+            'role_grant_offer_accept',
+            async (fixture) => {
+                const { recipient, offer_id } = await create_pending_offer(fixture);
+                return { params: { offer_id }, headers: recipient.create_session_headers() };
+            }
+        ],
+        [
+            'role_grant_offer_decline',
+            async (fixture) => {
+                const { recipient, offer_id } = await create_pending_offer(fixture);
+                return { params: { offer_id }, headers: recipient.create_session_headers() };
+            }
+        ],
+        [
+            'role_grant_offer_retract',
+            async (fixture) => {
+                const { grantor, offer_id } = await create_pending_offer(fixture);
+                return { params: { offer_id }, headers: grantor.create_session_headers() };
+            }
+        ]
+    ]);
+    return fixtures;
+};

package/dist/testing/cross_backend/rust_spine_consumer_surface.d.ts

@@ -0,0 +1,101 @@
+import '../assert_dev_env.js';
+/**
+ * The declared surface of a consumer served by the Rust spine, for its cross
+ * suites — `create_rust_spine_consumer_surface_spec`.
+ *
+ * The usual Rust spine consumer server mounts the same spine routes whatever
+ * its domain: `/health`, `fuz_auth::account_router` under `/api/account`
+ * (`ACCOUNT_ROUTER_PATHS`), the bootstrap and signup routers beside it, and
+ * one RPC endpoint carrying the standard admin / role-grant-offer / account
+ * actions plus the consumer's own. This module builds that surface from the
+ * hono-free route shapes and the consumer's action specs, so a consumer
+ * supplies only what is its own. A server that mounts no signup router (a
+ * single-keeper daemon such as mageguild's) is not this shape.
+ *
+ * The route shapes come from `create_account_route_shapes` and friends, never
+ * the live route factories, which statically pull `hono/cookie` and
+ * `hono/streaming`. Handlers are never invoked — the suites read `method`,
+ * `path`, `auth` and the schemas, and live dispatch happens in the spawned
+ * binary — so routes and actions carry no-op handlers.
+ *
+ * @module
+ */
+import type { RpcAction } from '../../actions/action_rpc.js';
+import type { ActionSpecUnion } from '../../actions/action_spec.js';
+import type { RoleSchemaResult } from '../../auth/role_schema.js';
+import type { SessionOptions } from '../../auth/session_cookie.js';
+import type { AppSurfaceSpec, RpcEndpointSpec } from '../../http/surface.js';
+import type { AppServerContext } from '../../server/app_server_context.js';
+/**
+ * The routes `fuz_auth::account_router` mounts, relative to `/api/account`. An
+ * allowlist rather than every account route shape: `/verify` is a TS-only
+ * route the Rust router doesn't serve, so declaring it would have the suites
+ * probe a 404. A shape fuz_app renames or drops fails the surface build; one
+ * it adds stays off the surface until the Rust router mounts it and this list
+ * names it.
+ */
+export declare const ACCOUNT_ROUTER_PATHS: readonly ["/status", "/login", "/logout", "/password"];
+/** Options for `create_rust_spine_consumer_rpc_endpoints`. */
+export interface RustSpineConsumerRpcEndpointsOptions {
+    /**
+     * The consumer's own action specs. The request-response specs that aren't
+     * protocol actions (`heartbeat`, `peer/ping`, …) go on the RPC endpoint, so a
+     * full registry like `all_action_specs` can be passed as it is.
+     */
+    readonly domain_action_specs: ReadonlyArray<ActionSpecUnion>;
+    /**
+     * Actions besides the standard set and the domain specs — opt-in families
+     * the consumer mounts (`create_actor_lookup_actions`,
+     * `create_self_service_role_actions`), built against the stub context.
+     */
+    readonly extra_rpc_actions?: (ctx: AppServerContext) => Array<RpcAction>;
+    /** The consumer's role schema, for the standard admin and role-grant-offer actions. */
+    readonly roles?: RoleSchemaResult;
+    /**
+     * Domain methods kept off the declared surface — ones the spec-derived
+     * suites can't drive (an input whose `.refine()` the generic body generator
+     * can't satisfy). They stay mounted on the backend; this only leaves them
+     * out of what the suites enumerate.
+     */
+    readonly exclude_methods?: ReadonlyArray<string>;
+    /** The RPC endpoint's path. Default `SPINE_RPC_PATH`. */
+    readonly rpc_path?: string;
+}
+/** Options for `create_rust_spine_consumer_surface_spec`. */
+export interface RustSpineConsumerSurfaceSpecOptions extends RustSpineConsumerRpcEndpointsOptions {
+    /** The backend's session config — its cookie name above all. */
+    readonly session_options: SessionOptions<string>;
+    /**
+     * Whether the server turns on the spine's opt-in host gate
+     * (`fuz_http::StackOptions::host_gate`), declared as a `host_validation`
+     * layer at the head of the middleware list.
+     *
+     * @default false
+     */
+    readonly host_gate?: boolean;
+}
+/**
+ * The RPC endpoints a Rust spine consumer mounts: the standard admin /
+ * role-grant-offer / account actions, the extra families, then the domain
+ * specs — what `describe_spine_cross_suites` takes as `rpc_endpoints`.
+ *
+ * @param options - the consumer's action specs, extras and roles
+ * @returns the endpoints, as a factory of the stub context
+ * @throws Error when an `exclude_methods` entry names no domain spec
+ */
+export declare const create_rust_spine_consumer_rpc_endpoints: (options: RustSpineConsumerRpcEndpointsOptions) => ((ctx: AppServerContext) => Array<RpcEndpointSpec>);
+/**
+ * Build the declared surface of a Rust spine consumer for its cross suites,
+ * on `create_test_app_surface_spec`: the spine routes (health, the account
+ * router's paths, signup, and bootstrap as a `surface_only` shape), the RPC
+ * endpoint from `create_rust_spine_consumer_rpc_endpoints`, the daemon-token
+ * layer every consumer test binary wires, and — with `host_gate` — the
+ * `host_validation` layer at the head of the middleware list.
+ *
+ * @param options - the consumer's session config, action specs, extras and roles
+ * @returns the surface spec, for `describe_spine_cross_suites`'s `surface_source`
+ * @throws Error when an account route shape the Rust router mounts is missing,
+ *   or an `exclude_methods` entry names no domain spec
+ */
+export declare const create_rust_spine_consumer_surface_spec: (options: RustSpineConsumerSurfaceSpecOptions) => AppSurfaceSpec;
+//# sourceMappingURL=rust_spine_consumer_surface.d.ts.map

package/dist/testing/cross_backend/rust_spine_consumer_surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rust_spine_consumer_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/rust_spine_consumer_surface.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAA6B,MAAM,8BAA8B,CAAC;AAM/F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAMnE,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAI3E;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,wDAAyD,CAAC;AAU3F,8DAA8D;AAC9D,MAAM,WAAW,oCAAoC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC7D;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IACzE,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACjD,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,6DAA6D;AAC7D,MAAM,WAAW,mCAAoC,SAAQ,oCAAoC;IAChG,gEAAgE;IAChE,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACjD;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,wCAAwC,GACpD,SAAS,oCAAoC,KAC3C,CAAC,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,eAAe,CAAC,CA+BpD,CAAC;AAiCF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uCAAuC,GACnD,SAAS,mCAAmC,KAC1C,cAeA,CAAC"}