@fuzdev/fuz_app 0.65.0 → 0.67.0

package/dist/testing/cross_backend/default_backend_configs.js

@@ -0,0 +1,111 @@
+import '../assert_dev_env.js';
+import { build_test_backend_paths } from './build_test_backend_paths.js';
+import { default_test_bootstrap_token, default_test_cookie_keys, default_test_keeper_password, default_test_keeper_username, } from './default_secrets.js';
+/**
+ * Capabilities shared by TS-family backends — same canonical
+ * implementation, same feature set. No trusted-proxy phase (the test
+ * binary doesn't enable proxy parsing) and no per-account login rate
+ * limit (the TS canonical path leaves the limiter null in test mode).
+ */
+export const ts_default_capabilities = Object.freeze({
+    bearer_auth: true,
+    trusted_proxy: false,
+    login_rate_limit: false,
+    ws: true,
+    sse: false,
+    in_process_only: false,
+});
+/**
+ * Capabilities for the Rust family. Adds `trusted_proxy: true` (the
+ * Rust spine's client-IP middleware is always wired; the env-gate just
+ * controls whether XFF is consulted vs the TCP peer IP) and
+ * `login_rate_limit: true` (env-gated bucket on `/login` + `/password`).
+ */
+export const rust_default_capabilities = Object.freeze({
+    bearer_auth: true,
+    trusted_proxy: true,
+    login_rate_limit: true,
+    ws: true,
+    sse: false,
+    in_process_only: false,
+});
+/** Bootstrap block built from the default secrets + supplied paths. */
+const build_default_bootstrap = (paths, overrides) => ({
+    token_path: paths.bootstrap_token_path,
+    token: default_test_bootstrap_token,
+    username: default_test_keeper_username,
+    password: default_test_keeper_password,
+    daemon_token_path: paths.daemon_token_path,
+    ...overrides,
+});
+/**
+ * Shared builder for TS-family backends (Deno + Node). Owns the common
+ * env baseline (NODE_ENV, HOST, PORT, in-memory PGlite, cookie keys,
+ * bootstrap token path) so per-backend factories only declare what
+ * genuinely differs.
+ */
+export const make_default_ts_backend_config = (opts) => {
+    const { name, port, start_command, database_url = 'memory://', extra_env, capabilities = ts_default_capabilities, paths = build_test_backend_paths(name), bootstrap_overrides, port_env_var = 'PORT', } = opts;
+    return {
+        name,
+        start_command,
+        base_url: `http://localhost:${port}`,
+        rpc_path: '/api/rpc',
+        ws_path: '/api/ws',
+        health_path: '/health',
+        bootstrap_path: '/api/account/bootstrap',
+        cookie_name: 'fuz_session',
+        startup_timeout_ms: 30_000,
+        env: {
+            NODE_ENV: 'development',
+            HOST: 'localhost',
+            [port_env_var]: String(port),
+            DATABASE_URL: database_url,
+            SECRET_FUZ_COOKIE_KEYS: default_test_cookie_keys,
+            FUZ_ALLOWED_ORIGINS: 'http://localhost:*',
+            FUZ_BOOTSTRAP_TOKEN_PATH: paths.bootstrap_token_path,
+            ...extra_env,
+        },
+        bootstrap: build_default_bootstrap(paths, bootstrap_overrides),
+        capabilities,
+    };
+};
+/**
+ * Shared builder for Rust-family backends. Owns the common env baseline
+ * (RUST_LOG, HOST, port, real Postgres, cookie keys, bootstrap token
+ * path, the `FUZ_TESTING_RESET_DB_ON_STARTUP=true` self-wipe gate) plus
+ * the 120s startup window for cargo's first-run build cost.
+ */
+export const make_default_rust_backend_config = (opts) => {
+    const { name, port, start_command, database_url, extra_env, capabilities = rust_default_capabilities, paths = build_test_backend_paths(name), bootstrap_overrides, port_env_var = 'PORT', rust_log = 'info', } = opts;
+    return {
+        name,
+        start_command,
+        base_url: `http://localhost:${port}`,
+        rpc_path: '/api/rpc',
+        ws_path: '/api/ws',
+        health_path: '/health',
+        bootstrap_path: '/api/account/bootstrap',
+        cookie_name: 'fuz_session',
+        startup_timeout_ms: 120_000,
+        env: {
+            RUST_LOG: rust_log,
+            HOST: 'localhost',
+            [port_env_var]: String(port),
+            DATABASE_URL: database_url,
+            SECRET_FUZ_COOKIE_KEYS: default_test_cookie_keys,
+            FUZ_ALLOWED_ORIGINS: 'http://localhost:*',
+            FUZ_BOOTSTRAP_TOKEN_PATH: paths.bootstrap_token_path,
+            // Self-wipe the auth-namespace schema before migrations on every
+            // boot. Read by `fuz_testing::reset_db_on_startup_if_env_set`,
+            // which the consumer's test binary invokes from its
+            // `pre_migration_hook` between pool creation and
+            // `fuz_db::run_migrations`. The `_testing_reset` RPC action
+            // (per-test reset) is orthogonal.
+            FUZ_TESTING_RESET_DB_ON_STARTUP: 'true',
+            ...extra_env,
+        },
+        bootstrap: build_default_bootstrap(paths, bootstrap_overrides),
+        capabilities,
+    };
+};

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

@@ -0,0 +1,40 @@
+import '../assert_dev_env.js';
+/**
+ * Default test secrets for cross-process backend bootstrap.
+ *
+ * Every cross-backend consumer needs the same shape: a bootstrap token
+ * the harness writes to disk before spawn, a keeper username/password
+ * the harness POSTs to `/api/account/bootstrap`, and cookie keys the
+ * binary uses to construct its `Keyring`. The literals here are dev-only
+ * and protected by `assert_dev_env`; the binaries themselves throw on
+ * production load.
+ *
+ * Each constant is exported individually so consumers can override one
+ * without re-deriving the rest. Builders in `default_backend_configs.ts`
+ * thread these defaults into the `BackendConfig.bootstrap` block and the
+ * `SECRET_FUZ_COOKIE_KEYS` env entry; callers compose the
+ * `bootstrap_overrides` knob when they need a non-default keeper.
+ *
+ * @module
+ */
+/**
+ * Fixed bootstrap token written to each backend's `token_path` before
+ * spawn. The test binary reads + consumes this via its
+ * `*_BOOTSTRAP_TOKEN_PATH` env var; the harness POSTs the same token to
+ * `/api/account/bootstrap` to mint the keeper account. Any 32+ char
+ * string works — the binary just compares bytes, no entropy required
+ * for tests.
+ */
+export declare const default_test_bootstrap_token = "test_bootstrap_token_for_cross_be";
+/** Keeper username used by every cross-process test fixture. */
+export declare const default_test_keeper_username = "keeper";
+/** Keeper password used by every cross-process test fixture. */
+export declare const default_test_keeper_password = "password_test_keeper";
+/**
+ * Dev-only cookie keys (64+ chars). The test binary needs
+ * `SECRET_FUZ_COOKIE_KEYS` to construct its `Keyring`. Never used in
+ * production — the test binaries themselves throw on production load
+ * via `assert_dev_env`.
+ */
+export declare const default_test_cookie_keys = "dev_only_cookie_keys_for_cross_backend_tests_not_for_prod_use_xx";
+//# sourceMappingURL=default_secrets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"default_secrets.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_secrets.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,sCAAsC,CAAC;AAEhF,gEAAgE;AAChE,eAAO,MAAM,4BAA4B,WAAW,CAAC;AAErD,gEAAgE;AAChE,eAAO,MAAM,4BAA4B,yBAAyB,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,qEAC8B,CAAC"}

package/dist/testing/cross_backend/default_secrets.js

@@ -0,0 +1,39 @@
+import '../assert_dev_env.js';
+/**
+ * Default test secrets for cross-process backend bootstrap.
+ *
+ * Every cross-backend consumer needs the same shape: a bootstrap token
+ * the harness writes to disk before spawn, a keeper username/password
+ * the harness POSTs to `/api/account/bootstrap`, and cookie keys the
+ * binary uses to construct its `Keyring`. The literals here are dev-only
+ * and protected by `assert_dev_env`; the binaries themselves throw on
+ * production load.
+ *
+ * Each constant is exported individually so consumers can override one
+ * without re-deriving the rest. Builders in `default_backend_configs.ts`
+ * thread these defaults into the `BackendConfig.bootstrap` block and the
+ * `SECRET_FUZ_COOKIE_KEYS` env entry; callers compose the
+ * `bootstrap_overrides` knob when they need a non-default keeper.
+ *
+ * @module
+ */
+/**
+ * Fixed bootstrap token written to each backend's `token_path` before
+ * spawn. The test binary reads + consumes this via its
+ * `*_BOOTSTRAP_TOKEN_PATH` env var; the harness POSTs the same token to
+ * `/api/account/bootstrap` to mint the keeper account. Any 32+ char
+ * string works — the binary just compares bytes, no entropy required
+ * for tests.
+ */
+export const default_test_bootstrap_token = 'test_bootstrap_token_for_cross_be';
+/** Keeper username used by every cross-process test fixture. */
+export const default_test_keeper_username = 'keeper';
+/** Keeper password used by every cross-process test fixture. */
+export const default_test_keeper_password = 'password_test_keeper';
+/**
+ * Dev-only cookie keys (64+ chars). The test binary needs
+ * `SECRET_FUZ_COOKIE_KEYS` to construct its `Keyring`. Never used in
+ * production — the test binaries themselves throw on production load
+ * via `assert_dev_env`.
+ */
+export const default_test_cookie_keys = 'dev_only_cookie_keys_for_cross_backend_tests_not_for_prod_use_xx';

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

@@ -0,0 +1,64 @@
+import '../assert_dev_env.js';
+import { type RoleSchemaResult } from '../../auth/role_schema.js';
+import { type SessionOptions } from '../../auth/session_cookie.js';
+import { type RouteSpec } from '../../http/route_spec.js';
+import type { AppSurfaceSpec, RpcEndpointSpec } from '../../http/surface.js';
+import type { AppServerContext } from '../../server/app_server.js';
+/**
+ * Session config — cookie name matches the binary's issued session cookie
+ * (`fuz_session`) so cookie-attribute assertions + jar extraction line up.
+ */
+export declare const spine_session_options: SessionOptions<string>;
+/**
+ * Built-in roles only — the standard spine registers no app-defined role
+ * specs. When the spine grows additional grantable roles, thread their
+ * registry through `create_role_schema` here so the admin suite picks up
+ * grant-path coverage.
+ */
+export declare const spine_roles: RoleSchemaResult;
+/** RPC endpoint mount path — matches the binary's `/api/rpc`. */
+export declare const SPINE_RPC_PATH = "/api/rpc";
+/**
+ * Audit-log SSE stream path — `/api/admin` prefix + the
+ * `create_audit_log_route_specs` `/audit/stream` route. Matches the default
+ * `BackendConfig.sse_path` and the cross-process SSE suite's default. Only
+ * mounted by the TS spine binary (which wires `audit_log_sse`); the shared
+ * surface stub leaves `ctx.audit_sse` null so the snapshot stays SSE-free.
+ */
+export declare const SPINE_SSE_PATH = "/api/admin/audit/stream";
+/**
+ * Factory-form RPC endpoints so the `app_settings_update` handler closes
+ * over the per-test `ctx.app_settings`. `create_app_server` (in the binary)
+ * owns live dispatch; the surface builder invokes the factory once with a
+ * stub ctx for setup-time path/method lookup, so the handler closures are
+ * never called across the process boundary.
+ *
+ * Test binaries append their own `_testing_reset` action to this endpoint's
+ * `actions` (see `testing_reset_actions.ts`); it is intentionally excluded
+ * here so it stays off the declared surface (the harness calls it directly
+ * over the daemon-token channel).
+ */
+export declare const spine_rpc_endpoints: (ctx: AppServerContext) => Array<RpcEndpointSpec>;
+/**
+ * Account REST + signup route specs under `/api/account` (bootstrap
+ * auto-mounted by the surface builder / `create_app_server`), plus the
+ * audit-log SSE stream under `/api/admin` **only when `ctx.audit_sse` is
+ * set** (the TS spine binary passes `audit_log_sse: true`).
+ *
+ * The shared `create_spine_surface_spec()` builds its ctx with
+ * `audit_sse: null`, so the declared surface snapshot stays SSE-free and the
+ * Rust `spine_stub` cross test is unaffected — only the live TS binary mounts
+ * the stream at `SPINE_SSE_PATH`.
+ */
+export declare const create_spine_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+/**
+ * The `AppSurfaceSpec` for the standard spine surface — the wire-shape
+ * source the cross-process round-trip + RPC-round-trip suites validate
+ * against. `bootstrap: {mode: 'surface_only'}` mounts
+ * `POST /api/account/bootstrap`'s shape to match the binary (which wires
+ * bootstrap for real); the harness's `globalSetup` already consumed the
+ * live bootstrap, so the cross-process round-trip validates the binary's
+ * 409 against the route's declared error schema.
+ */
+export declare const create_spine_surface_spec: () => AppSurfaceSpec;
+//# sourceMappingURL=default_spine_surface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"default_spine_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_spine_surface.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA6B9B,OAAO,EAAqB,KAAK,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAwB,KAAK,cAAc,EAAC,MAAM,8BAA8B,CAAC;AAGxF,OAAO,EAAqB,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAC,cAAc,EAAE,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,4BAA4B,CAAC;AAGjE;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,MAAM,CAAwC,CAAC;AAElG;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,gBAAyC,CAAC;AAEpE,iEAAiE;AACjE,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,4BAA4B,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,gBAAgB,KAAG,KAAK,CAAC,eAAe,CAQhF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,KAAK,gBAAgB,KAAG,KAAK,CAAC,SAAS,CAkB/E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAO,cAM1C,CAAC"}

package/dist/testing/cross_backend/default_spine_surface.js

@@ -0,0 +1,121 @@
+import '../assert_dev_env.js';
+/**
+ * Canonical no-domain spine surface — the standard fuz_app
+ * auth/account/admin/audit surface with no consumer domain layer on top.
+ *
+ * This is the single source of truth for "the standard spine surface",
+ * shared by:
+ *
+ * - the Rust `testing_spine_stub` cross-process self-tests (which build the
+ *   `AppSurfaceSpec` via `create_spine_surface_spec` and drive the binary's
+ *   wire shape),
+ * - the TS `testing_spine_server` cross-process binary (which feeds
+ *   `create_spine_route_specs` + `spine_rpc_endpoints` into a live
+ *   `create_app_server`), and
+ * - the `cross_backend_ts_*` self-test projects.
+ *
+ * **`$lib`-free by contract.** This module and everything it imports use
+ * relative specifiers (no `$lib` SvelteKit alias) so the spawned TS test
+ * binary — run under Gro's loader, which resolves `.js`→`.ts` and package
+ * imports but **not** the `$lib` alias — can import it transitively. Keep
+ * it that way: a `$lib` import anywhere in this graph breaks the binary
+ * spawn while still typechecking under vitest.
+ *
+ * @module
+ */
+import { create_account_route_specs } from '../../auth/account_routes.js';
+import { create_audit_log_route_specs } from '../../auth/audit_log_routes.js';
+import { create_role_schema } from '../../auth/role_schema.js';
+import { create_session_config } from '../../auth/session_cookie.js';
+import { create_signup_route_specs } from '../../auth/signup_routes.js';
+import { create_standard_rpc_actions } from '../../auth/standard_rpc_actions.js';
+import { prefix_route_specs } from '../../http/route_spec.js';
+import { create_test_app_surface_spec } from '../stubs.js';
+/**
+ * Session config — cookie name matches the binary's issued session cookie
+ * (`fuz_session`) so cookie-attribute assertions + jar extraction line up.
+ */
+export const spine_session_options = create_session_config('fuz_session');
+/**
+ * Built-in roles only — the standard spine registers no app-defined role
+ * specs. When the spine grows additional grantable roles, thread their
+ * registry through `create_role_schema` here so the admin suite picks up
+ * grant-path coverage.
+ */
+export const spine_roles = create_role_schema([]);
+/** RPC endpoint mount path — matches the binary's `/api/rpc`. */
+export const SPINE_RPC_PATH = '/api/rpc';
+/**
+ * Audit-log SSE stream path — `/api/admin` prefix + the
+ * `create_audit_log_route_specs` `/audit/stream` route. Matches the default
+ * `BackendConfig.sse_path` and the cross-process SSE suite's default. Only
+ * mounted by the TS spine binary (which wires `audit_log_sse`); the shared
+ * surface stub leaves `ctx.audit_sse` null so the snapshot stays SSE-free.
+ */
+export const SPINE_SSE_PATH = '/api/admin/audit/stream';
+/**
+ * Factory-form RPC endpoints so the `app_settings_update` handler closes
+ * over the per-test `ctx.app_settings`. `create_app_server` (in the binary)
+ * owns live dispatch; the surface builder invokes the factory once with a
+ * stub ctx for setup-time path/method lookup, so the handler closures are
+ * never called across the process boundary.
+ *
+ * Test binaries append their own `_testing_reset` action to this endpoint's
+ * `actions` (see `testing_reset_actions.ts`); it is intentionally excluded
+ * here so it stays off the declared surface (the harness calls it directly
+ * over the daemon-token channel).
+ */
+export const spine_rpc_endpoints = (ctx) => [
+    {
+        path: SPINE_RPC_PATH,
+        actions: create_standard_rpc_actions(ctx.deps, {
+            app_settings: ctx.app_settings,
+            roles: spine_roles,
+        }),
+    },
+];
+/**
+ * Account REST + signup route specs under `/api/account` (bootstrap
+ * auto-mounted by the surface builder / `create_app_server`), plus the
+ * audit-log SSE stream under `/api/admin` **only when `ctx.audit_sse` is
+ * set** (the TS spine binary passes `audit_log_sse: true`).
+ *
+ * The shared `create_spine_surface_spec()` builds its ctx with
+ * `audit_sse: null`, so the declared surface snapshot stays SSE-free and the
+ * Rust `spine_stub` cross test is unaffected — only the live TS binary mounts
+ * the stream at `SPINE_SSE_PATH`.
+ */
+export const create_spine_route_specs = (ctx) => [
+    ...prefix_route_specs('/api/account', [
+        ...create_account_route_specs(ctx.deps, {
+            session_options: spine_session_options,
+            ip_rate_limiter: null,
+            login_account_rate_limiter: null,
+            login_fail_floor_ms: 0,
+        }),
+        ...create_signup_route_specs(ctx.deps, {
+            session_options: spine_session_options,
+            ip_rate_limiter: null,
+            signup_account_rate_limiter: null,
+            app_settings: ctx.app_settings,
+        }),
+    ]),
+    ...(ctx.audit_sse
+        ? prefix_route_specs('/api/admin', create_audit_log_route_specs({ stream: ctx.audit_sse }))
+        : []),
+];
+/**
+ * The `AppSurfaceSpec` for the standard spine surface — the wire-shape
+ * source the cross-process round-trip + RPC-round-trip suites validate
+ * against. `bootstrap: {mode: 'surface_only'}` mounts
+ * `POST /api/account/bootstrap`'s shape to match the binary (which wires
+ * bootstrap for real); the harness's `globalSetup` already consumed the
+ * live bootstrap, so the cross-process round-trip validates the binary's
+ * 409 against the route's declared error schema.
+ */
+export const create_spine_surface_spec = () => create_test_app_surface_spec({
+    session_options: spine_session_options,
+    create_route_specs: create_spine_route_specs,
+    rpc_endpoints: spine_rpc_endpoints,
+    bootstrap: { mode: 'surface_only' },
+});