@fuzdev/fuz_app 0.140.0 → 0.141.0

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

@@ -0,0 +1,152 @@
+import '../assert_dev_env.js';
+import { z } from 'zod';
+import type { RpcPathCrossSuiteOptions } from './setup.js';
+import { TestingOriginCheckOutput, type TestingOriginCheckInput } from './testing_reset_actions.js';
+/** One expected refusal of a parse row. */
+export declare const OriginConformanceError: z.ZodObject<{
+    index: z.ZodOptional<z.ZodNumber>;
+    kind: z.ZodEnum<{
+        empty_entry: "empty_entry";
+        not_printable_ascii: "not_printable_ascii";
+        missing_scheme: "missing_scheme";
+        unsupported_scheme: "unsupported_scheme";
+        has_path: "has_path";
+        has_userinfo: "has_userinfo";
+        missing_host: "missing_host";
+        invalid_host_char: "invalid_host_char";
+        unbracketed_ipv6: "unbracketed_ipv6";
+        partial_wildcard: "partial_wildcard";
+        non_canonical_ipv4: "non_canonical_ipv4";
+        unclosed_ipv6: "unclosed_ipv6";
+        invalid_ipv6: "invalid_ipv6";
+        invalid_after_ipv6: "invalid_after_ipv6";
+        invalid_port: "invalid_port";
+        default_port: "default_port";
+        no_origins: "no_origins";
+    }>;
+}, z.core.$strict>;
+export type OriginConformanceError = z.infer<typeof OriginConformanceError>;
+/** A parse row: the value parses (`ok: true`), or is refused with `errors`. */
+export declare const OriginConformanceParseRow: z.ZodUnion<readonly [z.ZodObject<{
+    raw: z.ZodString;
+    ok: z.ZodLiteral<true>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    raw: z.ZodString;
+    errors: z.ZodArray<z.ZodObject<{
+        index: z.ZodOptional<z.ZodNumber>;
+        kind: z.ZodEnum<{
+            empty_entry: "empty_entry";
+            not_printable_ascii: "not_printable_ascii";
+            missing_scheme: "missing_scheme";
+            unsupported_scheme: "unsupported_scheme";
+            has_path: "has_path";
+            has_userinfo: "has_userinfo";
+            missing_host: "missing_host";
+            invalid_host_char: "invalid_host_char";
+            unbracketed_ipv6: "unbracketed_ipv6";
+            partial_wildcard: "partial_wildcard";
+            non_canonical_ipv4: "non_canonical_ipv4";
+            unclosed_ipv6: "unclosed_ipv6";
+            invalid_ipv6: "invalid_ipv6";
+            invalid_after_ipv6: "invalid_after_ipv6";
+            invalid_port: "invalid_port";
+            default_port: "default_port";
+            no_origins: "no_origins";
+        }>;
+    }, z.core.$strict>>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
+export type OriginConformanceParseRow = z.infer<typeof OriginConformanceParseRow>;
+/** A match row: a valid allowlist, one `Origin` value or `null`, and the answer. */
+export declare const OriginConformanceMatchRow: z.ZodObject<{
+    patterns: z.ZodString;
+    origin: z.ZodNullable<z.ZodString>;
+    allowed: z.ZodBoolean;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type OriginConformanceMatchRow = z.infer<typeof OriginConformanceMatchRow>;
+/** The conformance table. */
+export declare const OriginConformance: z.ZodObject<{
+    parse: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        raw: z.ZodString;
+        ok: z.ZodLiteral<true>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        raw: z.ZodString;
+        errors: z.ZodArray<z.ZodObject<{
+            index: z.ZodOptional<z.ZodNumber>;
+            kind: z.ZodEnum<{
+                empty_entry: "empty_entry";
+                not_printable_ascii: "not_printable_ascii";
+                missing_scheme: "missing_scheme";
+                unsupported_scheme: "unsupported_scheme";
+                has_path: "has_path";
+                has_userinfo: "has_userinfo";
+                missing_host: "missing_host";
+                invalid_host_char: "invalid_host_char";
+                unbracketed_ipv6: "unbracketed_ipv6";
+                partial_wildcard: "partial_wildcard";
+                non_canonical_ipv4: "non_canonical_ipv4";
+                unclosed_ipv6: "unclosed_ipv6";
+                invalid_ipv6: "invalid_ipv6";
+                invalid_after_ipv6: "invalid_after_ipv6";
+                invalid_port: "invalid_port";
+                default_port: "default_port";
+                no_origins: "no_origins";
+            }>;
+        }, z.core.$strict>>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>;
+    match: z.ZodArray<z.ZodObject<{
+        patterns: z.ZodString;
+        origin: z.ZodNullable<z.ZodString>;
+        allowed: z.ZodBoolean;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type OriginConformance = z.infer<typeof OriginConformance>;
+/** The committed table, resolved relative to this module. */
+export declare const ORIGIN_CONFORMANCE_URL: URL;
+/**
+ * Read and validate the committed conformance table.
+ *
+ * @returns the parsed table
+ * @throws Error when the file doesn't match `OriginConformance`
+ */
+export declare const load_origin_conformance: () => OriginConformance;
+/** One table row as the action input that checks it. */
+export interface OriginConformanceCheck {
+    /** A short label naming the row, for a failure message. */
+    readonly label: string;
+    readonly input: TestingOriginCheckInput;
+    readonly expected: TestingOriginCheckOutput;
+}
+/**
+ * Flatten the table into action inputs and the answers they must get. A parse
+ * row sends a `null` origin, so a value that parses answers
+ * `{ok: true, allowed: true}`.
+ *
+ * @param table - the conformance table
+ * @returns one check per row, parse rows first
+ */
+export declare const to_origin_conformance_checks: (table: OriginConformance) => Array<OriginConformanceCheck>;
+/**
+ * Compare each check's answer with its expectation and fail once, listing
+ * every row that disagrees.
+ *
+ * @param checks - the table's checks
+ * @param answer - the answer each check got, in order
+ * @param backend - the name the failure message gives the answerer
+ */
+export declare const assert_origin_conformance: (checks: ReadonlyArray<OriginConformanceCheck>, answer: ReadonlyArray<unknown>, backend: string) => void;
+/** Options for `describe_origin_conformance_cross_tests`. */
+export type OriginConformanceCrossTestOptions = RpcPathCrossSuiteOptions;
+/**
+ * Register the origin conformance suite: every row of the committed table,
+ * sent to the backend's `_testing_origin_check` action over the keeper's
+ * daemon-token channel, must get the answer the table names. The action is on
+ * every spine test binary, so the suite is ungated.
+ */
+export declare const describe_origin_conformance_cross_tests: (options: OriginConformanceCrossTestOptions) => void;
+//# sourceMappingURL=origin_conformance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"origin_conformance.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/origin_conformance.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA0B9B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D,OAAO,EACN,wBAAwB,EAExB,KAAK,uBAAuB,EAC5B,MAAM,4BAA4B,CAAC;AAEpC,2CAA2C;AAC3C,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;kBAGjC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAOpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,oFAAoF;AACpF,eAAO,MAAM,yBAAyB;;;;;kBAKpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF,6BAA6B;AAC7B,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAG5B,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,EAAE,GAA2D,CAAC;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAAO,iBACuC,CAAC;AAEnF,wDAAwD;AACxD,MAAM,WAAW,sBAAsB;IACtC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,uBAAuB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;CAC5C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,GACxC,OAAO,iBAAiB,KACtB,KAAK,CAAC,sBAAsB,CAc9B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,GACrC,QAAQ,aAAa,CAAC,sBAAsB,CAAC,EAC7C,QAAQ,aAAa,CAAC,OAAO,CAAC,EAC9B,SAAS,MAAM,KACb,IAiBF,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,iCAAiC,GAAG,wBAAwB,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,uCAAuC,GACnD,SAAS,iCAAiC,KACxC,IA4BF,CAAC"}

package/dist/testing/cross_backend/origin_conformance.js

@@ -0,0 +1,136 @@
+import '../assert_dev_env.js';
+/**
+ * The origin allowlist conformance table, and the cross-backend suite that
+ * runs it against each backend over the wire.
+ *
+ * `origin_conformance.json` (beside this module) is the one statement of the
+ * allowlist grammar and matcher both spines implement. It holds two tables:
+ *
+ * - **parse** rows — `{raw, ok: true}` or `{raw, errors: [{index?, kind}]}`:
+ *   an allowlist value (as `FUZ_ALLOWED_ORIGINS` would carry it) and whether
+ *   it parses, or every refusal with its 1-based entry position (absent for a
+ *   list-level refusal) and its `AllowedOriginsErrorKind`.
+ * - **match** rows — `{patterns, origin, allowed}`: a valid allowlist, one
+ *   `Origin` value (`null` for none), and the request-level answer.
+ *
+ * A row may carry a `note` for the reader. The TS unit test reads the table
+ * directly; `describe_origin_conformance_cross_tests` sends every row to a
+ * backend's `_testing_origin_check` action and compares the answer, so the
+ * Rust spine is held to the same rows without reading this file.
+ *
+ * @module
+ */
+import { readFileSync } from 'node:fs';
+import { assert, describe, test } from 'vitest';
+import { z } from 'zod';
+import { AllowedOriginsErrorKind } from '../../http/origin.js';
+import { cross_rpc_call } from './cell_cross_helpers.js';
+import { SPINE_RPC_PATH } from './spine_surface_constants.js';
+import { TestingOriginCheckOutput, testing_origin_check_action_spec } from './testing_reset_actions.js';
+/** One expected refusal of a parse row. */
+export const OriginConformanceError = z.strictObject({
+    index: z.number().int().min(1).optional(),
+    kind: AllowedOriginsErrorKind
+});
+/** A parse row: the value parses (`ok: true`), or is refused with `errors`. */
+export const OriginConformanceParseRow = z.union([
+    z.strictObject({ raw: z.string(), ok: z.literal(true), note: z.string().optional() }),
+    z.strictObject({
+        raw: z.string(),
+        errors: z.array(OriginConformanceError).min(1),
+        note: z.string().optional()
+    })
+]);
+/** A match row: a valid allowlist, one `Origin` value or `null`, and the answer. */
+export const OriginConformanceMatchRow = z.strictObject({
+    patterns: z.string(),
+    origin: z.string().nullable(),
+    allowed: z.boolean(),
+    note: z.string().optional()
+});
+/** The conformance table. */
+export const OriginConformance = z.strictObject({
+    parse: z.array(OriginConformanceParseRow).min(1),
+    match: z.array(OriginConformanceMatchRow).min(1)
+});
+/** The committed table, resolved relative to this module. */
+export const ORIGIN_CONFORMANCE_URL = new URL('./origin_conformance.json', import.meta.url);
+/**
+ * Read and validate the committed conformance table.
+ *
+ * @returns the parsed table
+ * @throws Error when the file doesn't match `OriginConformance`
+ */
+export const load_origin_conformance = () => OriginConformance.parse(JSON.parse(readFileSync(ORIGIN_CONFORMANCE_URL, 'utf8')));
+/**
+ * Flatten the table into action inputs and the answers they must get. A parse
+ * row sends a `null` origin, so a value that parses answers
+ * `{ok: true, allowed: true}`.
+ *
+ * @param table - the conformance table
+ * @returns one check per row, parse rows first
+ */
+export const to_origin_conformance_checks = (table) => [
+    ...table.parse.map((row) => ({
+        label: `parse ${JSON.stringify(row.raw)}`,
+        input: { patterns: row.raw, origin: null },
+        expected: 'errors' in row
+            ? { ok: false, errors: row.errors.map((e) => ({ ...e })) }
+            : { ok: true, allowed: true }
+    })),
+    ...table.match.map((row) => ({
+        label: `match ${JSON.stringify(row.patterns)} × ${JSON.stringify(row.origin)}`,
+        input: { patterns: row.patterns, origin: row.origin },
+        expected: { ok: true, allowed: row.allowed }
+    }))
+];
+/**
+ * Compare each check's answer with its expectation and fail once, listing
+ * every row that disagrees.
+ *
+ * @param checks - the table's checks
+ * @param answer - the answer each check got, in order
+ * @param backend - the name the failure message gives the answerer
+ */
+export const assert_origin_conformance = (checks, answer, backend) => {
+    const failures = [];
+    checks.forEach((check, i) => {
+        const got = answer[i];
+        try {
+            assert.deepStrictEqual(got, check.expected);
+        }
+        catch {
+            failures.push(`${check.label}: expected ${JSON.stringify(check.expected)}, got ${JSON.stringify(got)}`);
+        }
+    });
+    assert.ok(failures.length === 0, `${backend}: ${failures.length} of ${checks.length} origin conformance rows disagree:\n` +
+        failures.join('\n'));
+};
+/**
+ * Register the origin conformance suite: every row of the committed table,
+ * sent to the backend's `_testing_origin_check` action over the keeper's
+ * daemon-token channel, must get the answer the table names. The action is on
+ * every spine test binary, so the suite is ungated.
+ */
+export const describe_origin_conformance_cross_tests = (options) => {
+    const { setup_test } = options;
+    const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
+    const checks = to_origin_conformance_checks(load_origin_conformance());
+    describe('origin allowlist conformance', () => {
+        test('every table row gets the answer it names', async () => {
+            const fixture = await setup_test();
+            // Origin-free: the daemon-token middleware discards the credential in a
+            // browser context, and the cross-process transport adds an `Origin`
+            const transport = fixture.fresh_transport({ origin: null });
+            const headers = fixture.create_daemon_token_headers();
+            const answers = [];
+            for (const check of checks) {
+                const res = await cross_rpc_call(transport, rpc_path, testing_origin_check_action_spec.method, check.input, headers);
+                assert.ok(res.ok, `${check.label}: RPC failed: ${JSON.stringify(res.error)}`);
+                const parsed = TestingOriginCheckOutput.safeParse(res.result);
+                answers.push(parsed.success ? parsed.data : res.result);
+            }
+            assert_origin_conformance(checks, answers, 'backend');
+        });
+    });
+};