@fuzdev/fuz_app 0.1.0

package/dist/testing/adversarial_404.d.ts

@@ -0,0 +1,15 @@
+import './assert_dev_env.js';
+import type { AdversarialTestOptions } from './attack_surface.js';
+/**
+ * Generate adversarial 404 response validation tests.
+ *
+ * For each route with `params` + 404 in `error_schemas`:
+ * 1. Creates a stub handler returning 404 with the declared error code
+ * 2. Fires a request with valid-format params (nil UUIDs for UUID params)
+ * 3. Validates response status is 404
+ * 4. Validates response body matches the declared 404 Zod schema
+ *
+ * @param options - the test configuration
+ */
+export declare const describe_adversarial_404: (options: AdversarialTestOptions) => void;
+//# sourceMappingURL=adversarial_404.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adversarial_404.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_404.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAoB7B,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,qBAAqB,CAAC;AAyBhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,sBAAsB,KAAG,IA2E1E,CAAC"}

package/dist/testing/adversarial_404.js

@@ -0,0 +1,118 @@
+import './assert_dev_env.js';
+/**
+ * Adversarial 404 testing for routes with params and declared 404 error schemas.
+ *
+ * Creates stub handlers that return 404 with the declared error code,
+ * fires requests with valid-format-but-nonexistent params (nil UUIDs),
+ * and validates response bodies against the declared 404 Zod schemas.
+ *
+ * No DB needed — tests schema conformance of 404 responses, not real handlers.
+ *
+ * @module
+ */
+import { test, assert, describe } from 'vitest';
+import { z } from 'zod';
+import { is_null_schema } from '../http/schema_helpers.js';
+import { create_auth_test_apps, select_auth_app } from './auth_apps.js';
+import { resolve_valid_path, generate_valid_body } from './schema_generators.js';
+/**
+ * Extract the error code from a 404 Zod schema for use in the stub handler.
+ *
+ * Supports `z.literal()` (`{const: '...'}`) and `z.enum()` (`{enum: [...]}`, uses first value).
+ */
+const extract_404_error_code = (schema) => {
+    try {
+        const json = z.toJSONSchema(schema);
+        if (json.type !== 'object' || !json.properties || typeof json.properties !== 'object')
+            return null;
+        const props = json.properties;
+        if (!props.error || typeof props.error !== 'object')
+            return null;
+        const error_schema = props.error;
+        if (typeof error_schema.const === 'string')
+            return error_schema.const;
+        if (Array.isArray(error_schema.enum) && typeof error_schema.enum[0] === 'string')
+            return error_schema.enum[0];
+    }
+    catch {
+        // schema can't be converted
+    }
+    return null;
+};
+/**
+ * Generate adversarial 404 response validation tests.
+ *
+ * For each route with `params` + 404 in `error_schemas`:
+ * 1. Creates a stub handler returning 404 with the declared error code
+ * 2. Fires a request with valid-format params (nil UUIDs for UUID params)
+ * 3. Validates response status is 404
+ * 4. Validates response body matches the declared 404 Zod schema
+ *
+ * @param options - the test configuration
+ */
+export const describe_adversarial_404 = (options) => {
+    const { build, roles } = options;
+    const { surface, route_specs } = build();
+    // Build spec lookup for Zod schema access
+    const spec_lookup = new Map();
+    for (const spec of route_specs) {
+        spec_lookup.set(`${spec.method} ${spec.path}`, spec);
+    }
+    // Find testable routes: params + 404 + extractable error code
+    const testable = [];
+    for (const route of surface.routes) {
+        if (route.params_schema === null)
+            continue;
+        if (!route.error_schemas || !('404' in route.error_schemas))
+            continue;
+        const key = `${route.method} ${route.path}`;
+        const spec = spec_lookup.get(key);
+        if (!spec?.params || !spec.errors?.[404])
+            continue;
+        const error_code = extract_404_error_code(spec.errors[404]);
+        if (!error_code)
+            continue;
+        testable.push({ key, error_code, spec });
+    }
+    if (testable.length === 0)
+        return;
+    describe('adversarial 404 response validation', () => {
+        // Create stub specs: replace handlers for testable routes with 404 stubs
+        const error_code_by_key = new Map();
+        for (const entry of testable) {
+            error_code_by_key.set(entry.key, entry.error_code);
+        }
+        const stub_specs = route_specs.map((spec) => {
+            const error_code = error_code_by_key.get(`${spec.method} ${spec.path}`);
+            if (!error_code)
+                return spec;
+            return {
+                ...spec,
+                handler: (c) => c.json({ error: error_code }, 404),
+            };
+        });
+        const apps = create_auth_test_apps(stub_specs, roles);
+        for (const { key, error_code, spec } of testable) {
+            test(key, async () => {
+                const route = surface.routes.find((r) => `${r.method} ${r.path}` === key);
+                const app = select_auth_app(apps, route.auth);
+                const url = resolve_valid_path(route.path, spec.params);
+                const request_init = { method: route.method };
+                // Send valid body for routes with input
+                if (!is_null_schema(spec.input)) {
+                    const body = generate_valid_body(spec.input);
+                    if (body !== undefined) {
+                        request_init.headers = { 'Content-Type': 'application/json' };
+                        request_init.body = JSON.stringify(body);
+                    }
+                }
+                const res = await app.request(url, request_init);
+                assert.strictEqual(res.status, 404, `Expected 404 for ${key}, got ${res.status}`);
+                const body = await res.json();
+                assert.strictEqual(body.error, error_code, `Expected error '${error_code}' for ${key}, got: ${body.error}`);
+                // Validate against declared 404 Zod schema
+                spec.errors[404].parse(body);
+            });
+        }
+    });
+};

package/dist/testing/adversarial_headers.d.ts

@@ -0,0 +1,36 @@
+import './assert_dev_env.js';
+import type { z } from 'zod';
+import { type TestMiddlewareStackOptions } from './middleware.js';
+/** A header-level attack case for middleware stack testing. */
+export interface AdversarialHeaderCase {
+    name: string;
+    headers: Record<string, string>;
+    expected_status: number;
+    expected_error?: string;
+    /** Zod schema to validate error response body against. Defaults to `ApiError` when `expected_error` is set. */
+    expected_error_schema?: z.ZodType;
+    /** Whether the request should reach token validation or be short-circuited by earlier middleware. */
+    validate_expectation: 'called' | 'not_called';
+}
+/**
+ * 7 standard adversarial header cases applicable to any middleware stack.
+ *
+ * @param allowed_origin - an origin that passes the origin check
+ * @returns the standard adversarial header cases
+ */
+export declare const create_standard_adversarial_cases: (allowed_origin: string) => Array<AdversarialHeaderCase>;
+/**
+ * Create a middleware stack app with standard adversarial header tests.
+ *
+ * Convenience wrapper combining `create_test_middleware_stack_app`
+ * and `create_standard_adversarial_cases`.
+ * Asserts body content for both error and success cases, and checks
+ * `mock_validate` call status via per-case declarative flags.
+ *
+ * @param suite_name - the describe block name
+ * @param options - middleware stack configuration
+ * @param allowed_origin - an origin that passes the origin check (used for standard cases)
+ * @param extra_cases - additional cases appended after the 7 standard ones
+ */
+export declare const describe_standard_adversarial_headers: (suite_name: string, options: TestMiddlewareStackOptions, allowed_origin: string, extra_cases?: Array<AdversarialHeaderCase>) => void;
+//# sourceMappingURL=adversarial_headers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adversarial_headers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_headers.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAY7B,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAS3B,OAAO,EAGN,KAAK,0BAA0B,EAC/B,MAAM,iBAAiB,CAAC;AAIzB,+DAA+D;AAC/D,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+GAA+G;IAC/G,qBAAqB,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IAClC,qGAAqG;IACrG,oBAAoB,EAAE,QAAQ,GAAG,YAAY,CAAC;CAC9C;AAID;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,GAC7C,gBAAgB,MAAM,KACpB,KAAK,CAAC,qBAAqB,CAkE7B,CAAC;AAIF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qCAAqC,GACjD,YAAY,MAAM,EAClB,SAAS,0BAA0B,EACnC,gBAAgB,MAAM,EACtB,cAAc,KAAK,CAAC,qBAAqB,CAAC,KACxC,IAkCF,CAAC"}

package/dist/testing/adversarial_headers.js

@@ -0,0 +1,128 @@
+import './assert_dev_env.js';
+/**
+ * Adversarial header attack test suite.
+ *
+ * Provides standard header injection test cases and a convenience wrapper
+ * for exercising middleware stacks with adversarial headers.
+ *
+ * @module
+ */
+import { test, assert, describe } from 'vitest';
+import { ApiError, ERROR_FORBIDDEN_ORIGIN, ERROR_FORBIDDEN_REFERER, ERROR_BEARER_REJECTED_BROWSER, ERROR_INVALID_TOKEN, } from '../http/error_schemas.js';
+import { create_test_middleware_stack_app, TEST_MIDDLEWARE_PATH, } from './middleware.js';
+// --- Standard adversarial header cases ---
+/**
+ * 7 standard adversarial header cases applicable to any middleware stack.
+ *
+ * @param allowed_origin - an origin that passes the origin check
+ * @returns the standard adversarial header cases
+ */
+export const create_standard_adversarial_cases = (allowed_origin) => [
+    {
+        name: 'bearer token with Origin header is rejected before token validation',
+        headers: {
+            Authorization: 'Bearer secret_fuz_token_test',
+            Origin: 'https://attacker.com',
+        },
+        expected_status: 403,
+        expected_error: ERROR_FORBIDDEN_ORIGIN,
+        validate_expectation: 'not_called',
+    },
+    {
+        name: 'bearer token with allowed Origin is rejected as browser context',
+        headers: {
+            Authorization: 'Bearer secret_fuz_token_test',
+            Origin: allowed_origin,
+        },
+        expected_status: 403,
+        expected_error: ERROR_BEARER_REJECTED_BROWSER,
+        validate_expectation: 'not_called',
+    },
+    {
+        name: 'request with no auth headers passes through all middleware',
+        headers: {},
+        expected_status: 200,
+        validate_expectation: 'not_called',
+    },
+    {
+        name: 'empty Origin header is rejected by origin middleware before bearer auth (defense-in-depth)',
+        headers: {
+            Authorization: 'Bearer secret_fuz_token_test',
+            Origin: '',
+        },
+        expected_status: 403,
+        expected_error: ERROR_FORBIDDEN_ORIGIN,
+        validate_expectation: 'not_called',
+    },
+    {
+        name: 'lowercase bearer scheme is recognized (case-insensitive per RFC 7235)',
+        headers: {
+            Authorization: 'bearer secret_fuz_token_test',
+        },
+        expected_status: 401,
+        expected_error: ERROR_INVALID_TOKEN,
+        validate_expectation: 'called',
+    },
+    {
+        name: 'bearer token with Referer from untrusted source is rejected',
+        headers: {
+            Authorization: 'Bearer secret_fuz_token_test',
+            Referer: 'https://attacker.com/page',
+        },
+        expected_status: 403,
+        expected_error: ERROR_FORBIDDEN_REFERER,
+        validate_expectation: 'not_called',
+    },
+    {
+        name: 'bearer token with Referer from allowed origin is rejected as browser context (defense-in-depth)',
+        headers: {
+            Authorization: 'Bearer secret_fuz_token_test',
+            Referer: `${allowed_origin}/page`,
+        },
+        expected_status: 403,
+        expected_error: ERROR_BEARER_REJECTED_BROWSER,
+        validate_expectation: 'not_called',
+    },
+];
+// --- Convenience wrapper ---
+/**
+ * Create a middleware stack app with standard adversarial header tests.
+ *
+ * Convenience wrapper combining `create_test_middleware_stack_app`
+ * and `create_standard_adversarial_cases`.
+ * Asserts body content for both error and success cases, and checks
+ * `mock_validate` call status via per-case declarative flags.
+ *
+ * @param suite_name - the describe block name
+ * @param options - middleware stack configuration
+ * @param allowed_origin - an origin that passes the origin check (used for standard cases)
+ * @param extra_cases - additional cases appended after the 7 standard ones
+ */
+export const describe_standard_adversarial_headers = (suite_name, options, allowed_origin, extra_cases) => {
+    const cases = [...create_standard_adversarial_cases(allowed_origin), ...(extra_cases ?? [])];
+    describe(suite_name, () => {
+        for (const tc of cases) {
+            test(tc.name, async () => {
+                const { app, mock_validate } = create_test_middleware_stack_app(options);
+                const res = await app.request(TEST_MIDDLEWARE_PATH, { headers: tc.headers });
+                assert.strictEqual(res.status, tc.expected_status);
+                const body = await res.json();
+                if (tc.expected_error) {
+                    assert.strictEqual(body.error, tc.expected_error);
+                    const error_schema = tc.expected_error_schema ?? ApiError;
+                    error_schema.parse(body);
+                }
+                if (tc.expected_status === 200) {
+                    assert.strictEqual(body.ok, true, 'expected ok to be true for 200 response');
+                    assert.strictEqual(body.has_context, false, 'expected has_context to be false (no auth)');
+                }
+                if (tc.validate_expectation === 'not_called') {
+                    assert.strictEqual(mock_validate.mock.calls.length, 0, 'validate should not have been called — middleware should short-circuit');
+                }
+                else {
+                    assert.ok(mock_validate.mock.calls.length > 0, 'validate should have been called — request reached token validation');
+                }
+            });
+        }
+    });
+};

package/dist/testing/adversarial_input.d.ts

@@ -0,0 +1,56 @@
+import './assert_dev_env.js';
+import { z } from 'zod';
+import { ERROR_INVALID_REQUEST_BODY, ERROR_INVALID_JSON_BODY } from '../http/error_schemas.js';
+import type { AdversarialTestOptions } from './attack_surface.js';
+interface InputTestCase {
+    label: string;
+    body: unknown;
+    expected_error: typeof ERROR_INVALID_REQUEST_BODY | typeof ERROR_INVALID_JSON_BODY;
+}
+interface ParamsTestCase {
+    label: string;
+    params: Record<string, string>;
+}
+interface QueryTestCase {
+    label: string;
+    query: Record<string, string>;
+}
+/**
+ * Generate adversarial test cases for a route's input schema.
+ *
+ * Produces focused, non-redundant cases:
+ * - Whole-body: send array instead of object, extra unknown key
+ * - Missing required fields (without defaults)
+ * - One wrong-type value per field
+ * - Null for required non-nullable fields
+ * - One format violation per constrained field
+ */
+export declare const generate_input_test_cases: (input_schema: z.ZodType) => Array<InputTestCase>;
+/**
+ * Generate adversarial test cases for a route's params schema.
+ *
+ * Params are always strings from URL segments. Only generates cases for
+ * format-constrained fields (uuid, pattern) since unconstrained string
+ * params accept any string value.
+ */
+export declare const generate_params_test_cases: (params_schema: z.ZodObject) => Array<ParamsTestCase>;
+/**
+ * Generate adversarial test cases for a route's query schema.
+ *
+ * Query params are always strings from the URL. Generates cases for:
+ * - Missing required fields
+ * - Format violations on constrained fields (uuid, pattern)
+ */
+export declare const generate_query_test_cases: (query_schema: z.ZodObject) => Array<QueryTestCase>;
+/**
+ * Generate adversarial input validation test suites.
+ *
+ * Tests input body validation and params validation for all routes.
+ * Uses correct auth credentials so auth guards pass and validation
+ * middleware is actually exercised.
+ *
+ * @param options - the test configuration
+ */
+export declare const describe_adversarial_input: (options: AdversarialTestOptions) => void;
+export {};
+//# sourceMappingURL=adversarial_input.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adversarial_input.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_input.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAiB7B,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAUtB,OAAO,EAEN,0BAA0B,EAC1B,uBAAuB,EAGvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,qBAAqB,CAAC;AA8ChE,UAAU,aAAa;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,EAAE,OAAO,0BAA0B,GAAG,OAAO,uBAAuB,CAAC;CACnF;AAED,UAAU,cAAc;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,UAAU,aAAa;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GAAI,cAAc,CAAC,CAAC,OAAO,KAAG,KAAK,CAAC,aAAa,CAyLtF,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,eAAe,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,cAAc,CA+B3F,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,cAAc,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,aAAa,CA4CxF,CAAC;AAqBF;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GAAI,SAAS,sBAAsB,KAAG,IA6L5E,CAAC"}