@fuzdev/fuz_app 0.106.1 → 0.107.0

package/dist/testing/cross_backend/token_scope_surface.js

@@ -0,0 +1,170 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-backend parity suite for **token scoping's non-RPC surface rule** —
+ * *a narrowed api token is RPC-only*.
+ *
+ * ## Why this suite exists
+ *
+ * Every existing cross-impl token-scope assertion is the `rpc:<method>` arm
+ * (the `token_scope_cases` batch in the conformance security slate). The
+ * `surface:<name>` arm had **none** — and it is the load-bearing half of the
+ * design. Both spines implement it, at the same named surfaces, returning a
+ * denial body that is an explicit cross-impl contract
+ * (`token_scope_denied_body` ↔ `fuz_auth::token_scope_surface_denied_response`),
+ * and nothing compared the two.
+ *
+ * That gap has the shape this control family keeps finding: the per-method arm
+ * was the one everybody looked at, so it was the one that got a gate. The
+ * surface arm is where a divergence could sit indefinitely — the schema gate
+ * can't see it (no column), the action-manifest gate can't see it (no method),
+ * and the spec-derived suites can't see it (these are REST routes, not the
+ * declared RPC surface).
+ *
+ * ## What it pins
+ *
+ * - **The denial body, byte for byte** — status, `error`, and the exact
+ *   `required_scope` capability string, per surface. A spine that renamed a
+ *   surface, dropped the `surface:` prefix, or emitted the JSON-RPC envelope
+ *   from a REST route fails here.
+ * - **Scope outranks role** — a narrowed token whose account *also* lacks the
+ *   gating role must hear `token_scope_required`, not
+ *   `insufficient_permissions`. This is the observable the TS↔Rust ordering
+ *   divergence produced before both spines converged on running the surface
+ *   gate ahead of the role gate; it was explicitly *invisible* to the
+ *   cross-backend suites, because every scoped-token probe used a token whose
+ *   account happened to hold the role.
+ *
+ * Two non-vacuity controls hold the negatives honest: the narrowed token must
+ * still reach the RPC method it *does* name (otherwise a spine that rejected
+ * the credential outright would pass every denial), and a **full** bearer must
+ * reach the same surface (otherwise a route broken for all bearers would pass
+ * too).
+ *
+ * ## Why the WS upgrade isn't here
+ *
+ * Rule 3's third probeable surface is the WebSocket upgrade, and it is
+ * deliberately omitted: `create_ws_transport` threads cookies, not bearer
+ * headers, and a refused upgrade surfaces as a thrown connection error whose
+ * body — the thing this suite exists to compare — isn't readable. The two HTTP
+ * surfaces are where the denial body is observable, which is what the parity
+ * gate needs. The WS gate keeps its per-spine coverage (fuz_app's surface
+ * census pins the call site; the Rust census pins its own).
+ *
+ * `$lib`-free by contract (relative specifiers only), like the sibling
+ * cross-backend suites.
+ *
+ * @module
+ */
+import { describe, assert } from 'vitest';
+import { account_token_create_action_spec } from '../../auth/account_action_specs.js';
+import { ERROR_TOKEN_SCOPE_REQUIRED } from '../../http/error_schemas.js';
+import { test_if } from './capabilities.js';
+import { cross_rpc_call } from './cell_cross_helpers.js';
+import { SPINE_RPC_PATH } from './spine_surface_constants.js';
+/** Default audit-log SSE path — the `audit_stream` surface. */
+const DEFAULT_SSE_PATH = '/api/admin/audit/stream';
+/**
+ * A well-formed hash that no fact has. The scope gate is a pre-authorization
+ * guard, so it fires before the handler ever looks the hash up — but *params*
+ * validation runs ahead of every auth gate (it is part of addressing the
+ * route), so the value still has to parse.
+ */
+const ABSENT_FACT_HASH = `blake3:${'0'.repeat(64)}`;
+/** The single RPC method the narrowed tokens in this suite admit. */
+const ADMITTED_METHOD = 'account_verify';
+/** The flat denial body both spines must return, for a given surface. */
+const surface_denial_body = (surface) => ({
+    error: ERROR_TOKEN_SCOPE_REQUIRED,
+    required_scope: `surface:${surface}`
+});
+/**
+ * Mint a narrowed bearer token over a session, through the production
+ * `account_token_create` path.
+ *
+ * Deliberately not a fixture-level credential: minting it here means the token
+ * is produced by the same handler a real minter would use, on whichever
+ * account the caller chose — which is what lets the ordering case put a
+ * narrowed token on an account that lacks the gating role.
+ */
+const mint_narrowed_token = async (transport, rpc_path, session_headers) => {
+    const res = await cross_rpc_call(transport, rpc_path, account_token_create_action_spec.method, { scope: { kind: 'methods', methods: [ADMITTED_METHOD] } }, session_headers);
+    assert.ok(res.ok, `minting a narrowed token failed: ${JSON.stringify(res.error)}`);
+    const token = res.result?.token;
+    assert.ok(typeof token === 'string' && token.length > 0, 'mint returned no token');
+    return token;
+};
+/**
+ * Assert a bearer GET is refused with the canonical surface denial.
+ *
+ * `origin: null` so the bearer credential isn't discarded as browser context,
+ * and a fresh jar so no session cookie rides along and answers instead.
+ */
+const assert_surface_denied = async (fresh_transport, path, token, surface) => {
+    const res = await fresh_transport({ origin: null })(path, {
+        headers: { authorization: `Bearer ${token}` }
+    });
+    assert.strictEqual(res.status, 403, `${path} must refuse a narrowed token with 403`);
+    const body = await res.json();
+    assert.deepStrictEqual(body, surface_denial_body(surface), `${path} must return the canonical flat surface denial`);
+};
+export const describe_token_scope_surface_cross_tests = (options) => {
+    const { setup_test, capabilities } = options;
+    const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
+    const sse_path = options.sse_path ?? DEFAULT_SSE_PATH;
+    describe('token scope non-RPC surface parity', () => {
+        /**
+         * The non-vacuity control for every denial below: a narrowed token is
+         * still a working credential. Without this, a spine that rejected the
+         * token outright — or never minted it — would pass all four negatives.
+         */
+        test_if(true, 'a narrowed token still reaches the method it names', async () => {
+            const fixture = await setup_test();
+            const token = await mint_narrowed_token(fixture.transport, rpc_path, fixture.create_session_headers());
+            const res = await cross_rpc_call(fixture.fresh_transport({ origin: null }), rpc_path, ADMITTED_METHOD, undefined, { authorization: `Bearer ${token}` });
+            assert.ok(res.ok, `admitted method must succeed: ${JSON.stringify(res.error)}`);
+        });
+        test_if(capabilities.sse, 'a narrowed token is refused the audit stream (surface:audit_stream)', async () => {
+            const fixture = await setup_test();
+            const token = await mint_narrowed_token(fixture.transport, rpc_path, fixture.create_session_headers());
+            await assert_surface_denied(fixture.fresh_transport, sse_path, token, 'audit_stream');
+        });
+        test_if(capabilities.fact_serving, 'a narrowed token is refused the bare-hash fact read (surface:fact_bare)', async () => {
+            const fixture = await setup_test();
+            const token = await mint_narrowed_token(fixture.transport, rpc_path, fixture.create_session_headers());
+            await assert_surface_denied(fixture.fresh_transport, `/api/facts/${ABSENT_FACT_HASH}`, token, 'fact_bare');
+        });
+        /**
+         * The surface-level non-vacuity control. A **full** bearer on the same
+         * route must get past the scope gate — proving the denial above is the
+         * scope refusing a narrowed token, not the route refusing every bearer.
+         * A 404 (no such fact) is the expected outcome; anything that isn't the
+         * scope denial satisfies the property, so the assertion is on what the
+         * response must *not* be.
+         */
+        test_if(capabilities.fact_serving, 'a full token is not refused by the scope gate on the same route', async () => {
+            const fixture = await setup_test();
+            const res = await fixture.fresh_transport({ origin: null })(`/api/facts/${ABSENT_FACT_HASH}`, { headers: fixture.create_bearer_headers() });
+            const body = (await res.json().catch(() => undefined));
+            assert.notStrictEqual(body?.error, ERROR_TOKEN_SCOPE_REQUIRED, 'a full-authority bearer must not be refused on scope grounds');
+        });
+        /**
+         * **Scope outranks role**, and this is the case that had no cross-impl
+         * pin while the two spines disagreed about it.
+         *
+         * The surfaces are role-gated, so a narrowed token on an account without
+         * the role could be refused by either gate. The scope gate must answer:
+         * it is the coarser fact about a credential that was never going to be
+         * admitted, and `insufficient_permissions` would instead report on the
+         * deployment's role structure to that credential. Every other
+         * scoped-token probe in the slate uses the keeper's token, whose account
+         * *holds* the role — so both orderings look identical there, which is
+         * exactly why this divergence survived as long as it did.
+         */
+        test_if(capabilities.fact_serving, 'scope outranks role — a narrowed token lacking the role hears about its scope', async () => {
+            const fixture = await setup_test();
+            const non_admin = await fixture.create_account({ username: 'scope_before_role' });
+            const token = await mint_narrowed_token(fixture.fresh_transport(), rpc_path, non_admin.create_session_headers());
+            await assert_surface_denied(fixture.fresh_transport, `/api/facts/${ABSENT_FACT_HASH}`, token, 'fact_bare');
+        });
+    });
+};

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

@@ -1 +1 @@
-{"version":3,"file":"integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAsB7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAMhE,OAAO,EAKN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAkB1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAW,KAAK,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAG1D;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC9C;;;;OAIG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;;;;;;;OASG;IACH,cAAc,EAAE,cAAc,CAAC;IAC/B,kEAAkE;IAClE,YAAY,EAAE,mBAAmB,CAAC;IAClC;;;;OAIG;IACH,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,mCAAmC,GAC/C,SAAS,8BAA8B,KACrC,IA66CF,CAAC"}
+{"version":3,"file":"integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAsB7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAMhE,OAAO,EAKN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAkB1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAW,KAAK,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAG1D;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC9C;;;;OAIG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;;;;;;;OASG;IACH,cAAc,EAAE,cAAc,CAAC;IAC/B,kEAAkE;IAClE,YAAY,EAAE,mBAAmB,CAAC;IAClC;;;;OAIG;IACH,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,mCAAmC,GAC/C,SAAS,8BAA8B,KACrC,IA86CF,CAAC"}

package/dist/testing/integration.js

@@ -685,8 +685,9 @@ export const describe_standard_integration_tests = (options) => {
                 // Pick an admin REST route where a clean role-denial 403 is
                 // reachable: account-grain (`actor: 'none'`, so the authorization
                 // phase doesn't first demand an acting actor → `actor_required`)
-                // and input/param/query-free (so input validation doesn't 400
-                // first, per the 401 → 400 → 403 phase order). Admin surfaces are
+                // and input/param/query-free (params and query still validate ahead
+                // of the auth phase — only body validation moved behind the gates,
+                // per the 401 → authz → 403 → 400 order). Admin surfaces are
                 // RPC-first now; a consumer may expose no such REST route (fuz_app
                 // itself, zzz) — then this REST-era check is a no-op and RPC denial
                 // is covered by `describe_rpc_attack_surface_tests`.

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;AA4dD;;;;;;;;;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;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"}

package/dist/testing/rpc_attack_surface.js

@@ -83,8 +83,10 @@ const describe_rpc_auth = (options) => {
                                     const app = apps.by_role.get(wrong_role);
                                     if (!app)
                                         throw new Error(`No test app for role '${wrong_role}'`);
-                                    // Send valid params so we trip the role gate (403), not input
-                                    // validation (400). Dispatcher ordering: 401 → 400 → 403.
+                                    // Send valid params so the probe varies only the role. Dispatcher
+                                    // ordering is 401 → authz → 403 → 400, so the role gate trips
+                                    // ahead of validation regardless; valid params also keep the
+                                    // authorization phase from answering `actor_required` first.
                                     const action = find_rpc_action(rpc_endpoint_specs, endpoint.path, method.name);
                                     const params = action ? generate_valid_body(action.spec.input) : undefined;
                                     const res = await app.request(endpoint.path, create_rpc_post_init(method.name, params));

package/package.json

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