@fuzdev/fuz_app 0.1.0

package/dist/server/app_backend.d.ts

@@ -0,0 +1,74 @@
+/**
+ * App backend types and factory — database initialization + auth migrations + deps.
+ *
+ * Provides `AppBackend`, `CreateAppBackendOptions`, and `create_app_backend()`.
+ *
+ * **Vocabulary**:
+ * - `AppDeps` — stateless capabilities: injectable, swappable per environment
+ * - `*Options` — static values set at startup, per-factory configuration
+ * - Runtime state — mutable values (e.g., `bootstrap_status`) — NOT in deps or options
+ *
+ * @module
+ */
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import type { AppDeps } from '../auth/deps.js';
+import type { AuditLogEvent } from '../auth/audit_log_schema.js';
+import type { DbType } from '../db/db.js';
+import type { Keyring } from '../auth/keyring.js';
+import type { PasswordHashDeps } from '../auth/password.js';
+import type { StatResult } from '../runtime/deps.js';
+import { type MigrationResult } from '../db/migrate.js';
+/**
+ * Result of `create_app_backend()` — database metadata + deps bundle.
+ *
+ * This is the initialized backend, not the HTTP server.
+ * Pass it to `create_app_server()` to assemble the Hono app.
+ */
+export interface AppBackend {
+    deps: AppDeps;
+    db_type: DbType;
+    db_name: string;
+    /** Migration results from `create_app_backend` (auth migrations only). */
+    readonly migration_results: ReadonlyArray<MigrationResult>;
+    /** Close the database connection. Bound to the actual driver. */
+    close: () => Promise<void>;
+}
+/**
+ * Input for `create_app_backend()`.
+ *
+ * `keyring` is passed pre-validated — callers handle their own error reporting
+ * (e.g., tx uses `runtime.exit(1)` on invalid keys).
+ */
+export interface CreateAppBackendOptions {
+    /** Get file/directory stats, or null if path doesn't exist. */
+    stat: (path: string) => Promise<StatResult | null>;
+    /** Read a file as text. */
+    read_file: (path: string) => Promise<string>;
+    /** Delete a file. */
+    delete_file: (path: string) => Promise<void>;
+    /** Database connection URL (`postgres://`, `file://`, or `memory://`). */
+    database_url: string;
+    /** Validated cookie signing keyring. */
+    keyring: Keyring;
+    /** Password hashing implementation. Use `argon2_password_deps` in production. */
+    password: PasswordHashDeps;
+    /** Structured logger instance. Omit for default (`new Logger('server')`). */
+    log?: Logger;
+    /**
+     * Called after each audit log INSERT succeeds.
+     * Use to broadcast audit events via SSE. Flows through `AppDeps`
+     * to all route factories automatically. Defaults to a noop.
+     */
+    on_audit_event?: (event: AuditLogEvent) => void;
+}
+/**
+ * Initialize the backend: database + auth migrations + deps.
+ *
+ * Calls `create_db` → `run_migrations` (auth namespace) and bundles
+ * the result with the provided keyring and password deps.
+ *
+ * @param options - keyring, password deps, and optional database URL
+ * @returns app backend with deps, database metadata, and migration results
+ */
+export declare const create_app_backend: (options: CreateAppBackendOptions) => Promise<AppBackend>;
+//# sourceMappingURL=app_backend.d.ts.map

package/dist/server/app_backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAE/C,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAiB,KAAK,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAItE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC3D,iEAAiE;IACjE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+DAA+D;IAC/D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,2BAA2B;IAC3B,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAChD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAU,SAAS,uBAAuB,KAAG,OAAO,CAAC,UAAU,CAa7F,CAAC"}

package/dist/server/app_backend.js

@@ -0,0 +1,39 @@
+/**
+ * App backend types and factory — database initialization + auth migrations + deps.
+ *
+ * Provides `AppBackend`, `CreateAppBackendOptions`, and `create_app_backend()`.
+ *
+ * **Vocabulary**:
+ * - `AppDeps` — stateless capabilities: injectable, swappable per environment
+ * - `*Options` — static values set at startup, per-factory configuration
+ * - Runtime state — mutable values (e.g., `bootstrap_status`) — NOT in deps or options
+ *
+ * @module
+ */
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { run_migrations } from '../db/migrate.js';
+import { AUTH_MIGRATION_NS } from '../auth/migrations.js';
+import { create_db } from '../db/create_db.js';
+/**
+ * Initialize the backend: database + auth migrations + deps.
+ *
+ * Calls `create_db` → `run_migrations` (auth namespace) and bundles
+ * the result with the provided keyring and password deps.
+ *
+ * @param options - keyring, password deps, and optional database URL
+ * @returns app backend with deps, database metadata, and migration results
+ */
+export const create_app_backend = async (options) => {
+    const { database_url, keyring, password, stat, read_file, delete_file } = options;
+    const log = options.log ?? new Logger('server');
+    const on_audit_event = options.on_audit_event ?? (() => { }); // eslint-disable-line @typescript-eslint/no-empty-function
+    const { db, close, db_type, db_name } = await create_db(database_url);
+    const migration_results = await run_migrations(db, [AUTH_MIGRATION_NS]);
+    return {
+        db_type,
+        db_name,
+        migration_results,
+        close,
+        deps: { keyring, password, db, stat, read_file, delete_file, log, on_audit_event },
+    };
+};

package/dist/server/app_server.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Server assembly factory.
+ *
+ * `create_app_server()` eliminates the ~100 lines of duplicated server assembly
+ * shared by tx, visiones, and mageguild. Consumers provide a pre-initialized
+ * `AppBackend` and options (session, origins, routes); the factory handles
+ * middleware, bootstrap status, surface generation, and Hono app assembly.
+ *
+ * @module
+ */
+import { Hono, type Context } from 'hono';
+import { z } from 'zod';
+import { type SessionOptions } from '../auth/session_cookie.js';
+import type { BootstrapAccountSuccess } from '../auth/bootstrap_account.js';
+import type { SseEventSpec } from '../realtime/sse.js';
+import { type AuditLogSse } from '../realtime/sse_auth_guard.js';
+import type { AppSettings } from '../auth/app_settings_schema.js';
+import { type RateLimiter } from '../rate_limiter.js';
+import type { DaemonTokenState } from '../auth/daemon_token.js';
+import { type MigrationNamespace, type MigrationResult } from '../db/migrate.js';
+import type { AppDeps } from '../auth/deps.js';
+import type { AppBackend } from './app_backend.js';
+import '../hono_context.js';
+import { type ServeStaticFactory } from './static.js';
+import { type AppSurfaceSpec } from '../http/surface.js';
+import { type RouteSpec } from '../http/route_spec.js';
+import type { MiddlewareSpec } from '../http/middleware_spec.js';
+import { type BootstrapStatus } from '../auth/bootstrap_routes.js';
+/**
+ * Context passed to `on_effect_error` when a pending effect rejects.
+ */
+export interface EffectErrorContext {
+    /** HTTP method of the request that spawned the effect. */
+    method: string;
+    /** URL path of the request that spawned the effect. */
+    path: string;
+}
+/**
+ * Configuration for `create_app_server()`.
+ *
+ * Requires a pre-initialized `AppBackend` from `create_app_backend()`.
+ * Two explicit steps: init backend then assemble server.
+ */
+export interface AppServerOptions {
+    /** Pre-initialized backend from `create_app_backend()`. */
+    backend: AppBackend;
+    /** Session options for cookie-based auth. */
+    session_options: SessionOptions<string>;
+    /** Parsed allowed origin patterns. */
+    allowed_origins: Array<RegExp>;
+    /** Trusted proxy options. */
+    proxy: {
+        trusted_proxies: Array<string>;
+        get_connection_ip: (c: Context) => string | undefined;
+    };
+    /**
+     * Shared IP rate limiter for login, bootstrap, and bearer auth.
+     * Omit or `undefined` to use a default limiter (5 attempts per 15 minutes).
+     * Pass `null` to explicitly disable rate limiting.
+     * Also available on `AppServerContext` for route factory callbacks.
+     */
+    ip_rate_limiter?: RateLimiter | null;
+    /**
+     * Per-account rate limiter for login attempts.
+     * Omit or `undefined` to use a default limiter (10 attempts per 30 minutes).
+     * Pass `null` to explicitly disable rate limiting.
+     * Also available on `AppServerContext` for route factory callbacks.
+     */
+    login_account_rate_limiter?: RateLimiter | null;
+    /**
+     * Per-account rate limiter for signup attempts, keyed by submitted username.
+     * Omit or `undefined` to use a default limiter (10 attempts per 30 minutes).
+     * Pass `null` to explicitly disable rate limiting.
+     * Also available on `AppServerContext` for route factory callbacks.
+     */
+    signup_account_rate_limiter?: RateLimiter | null;
+    /**
+     * Rate limiter for bearer token auth attempts (per-IP).
+     * Omit or `undefined` to use a default limiter (5 attempts per 15 minutes).
+     * Pass `null` to explicitly disable rate limiting.
+     */
+    bearer_ip_rate_limiter?: RateLimiter | null;
+    /**
+     * Maximum allowed request body size in bytes.
+     * Omit or `undefined` to use the default (1 MiB).
+     * Pass `null` to explicitly disable body size limiting.
+     */
+    max_body_size?: number | null;
+    /** Daemon token state for keeper auth. Omit to disable. */
+    daemon_token_state?: DaemonTokenState;
+    /** Bootstrap options. Omit to skip bootstrap status check and routes. */
+    bootstrap?: {
+        token_path: string | null;
+        /** Route prefix for bootstrap routes. Default `'/api/account'`. */
+        route_prefix?: string;
+        /**
+         * Called after successful bootstrap (account + session created).
+         * Use for app-specific post-bootstrap work like generating API tokens.
+         */
+        on_bootstrap?: (result: BootstrapAccountSuccess, c: Context) => Promise<void>;
+    };
+    /**
+     * Set to `false` to disable the auto-created surface route (`GET /api/surface`).
+     * Default: auto-created (authenticated).
+     */
+    surface_route?: false;
+    /** Consumer migration namespaces — run after auth migrations during init. */
+    migration_namespaces?: Array<MigrationNamespace>;
+    /**
+     * Build route specs from the initialized backend.
+     * Called after all middleware is ready.
+     */
+    create_route_specs: (context: AppServerContext) => Array<RouteSpec>;
+    /** Optional: transform middleware specs before applying. */
+    transform_middleware?: (specs: Array<MiddlewareSpec>) => Array<MiddlewareSpec>;
+    /**
+     * Enable factory-managed audit log SSE.
+     *
+     * When truthy, creates an `AuditLogSse` instance internally, wires `on_audit_event`
+     * on the backend deps (composing with any existing callback), and auto-includes
+     * `AUDIT_LOG_EVENT_SPECS` in the surface. The result is exposed on `AppServerContext`
+     * (for route factories) and `AppServer` (for the caller).
+     *
+     * Pass `true` for defaults (admin role), or `{role: 'custom'}` for a custom role.
+     * Omit to wire audit SSE manually.
+     */
+    audit_log_sse?: true | {
+        role?: string;
+    };
+    /** SSE event specs for surface generation. Defaults to `[]` (no SSE events). */
+    event_specs?: Array<SseEventSpec>;
+    /** Env schema for surface generation. Pass `z.object({})` when there are no env vars beyond `BaseServerEnv`. */
+    env_schema: z.ZodObject;
+    /** Middleware applied after routes, before static serving. Included in surface. */
+    post_route_middleware?: Array<MiddlewareSpec>;
+    /** Static file serving. Omit if not serving static files. */
+    static_serving?: {
+        serve_static: ServeStaticFactory;
+        spa_fallback?: string;
+    };
+    /**
+     * Await all pending fire-and-forget effects before returning the response.
+     * Use in tests so audit log assertions don't need polling.
+     * Default `false` (production: true fire-and-forget).
+     */
+    await_pending_effects?: boolean;
+    /**
+     * Called when a pending effect rejects.
+     * Use for monitoring, metrics, or alerting in production.
+     * Only called when `await_pending_effects` is `false` (production mode).
+     */
+    on_effect_error?: (error: unknown, context: EffectErrorContext) => void;
+    /** Env values for startup summary logging. */
+    env_values?: Record<string, unknown>;
+}
+/** Context passed to `create_route_specs`. */
+export interface AppServerContext {
+    deps: AppDeps;
+    backend: AppBackend;
+    bootstrap_status: BootstrapStatus;
+    session_options: SessionOptions<string>;
+    /** Shared IP rate limiter (from options). `null` when not configured. */
+    ip_rate_limiter: RateLimiter | null;
+    /** Per-account login rate limiter (from options). `null` when not configured. */
+    login_account_rate_limiter: RateLimiter | null;
+    /** Per-account signup rate limiter (from options). `null` when not configured. */
+    signup_account_rate_limiter: RateLimiter | null;
+    /** Global app settings (mutable ref — mutated by settings admin route). */
+    app_settings: AppSettings;
+    /** Factory-managed audit log SSE. `null` when `audit_log_sse` option is not set. */
+    audit_sse: AuditLogSse | null;
+}
+/** Result of `create_app_server()`. */
+export interface AppServer {
+    app: Hono;
+    /** Surface spec — serializable surface + raw specs that produced it. */
+    surface_spec: AppSurfaceSpec;
+    bootstrap_status: BootstrapStatus;
+    /** Global app settings (mutable ref — mutated by settings admin route). */
+    app_settings: AppSettings;
+    /** Combined migration results — auth migrations from `create_app_backend` plus consumer migrations. */
+    migration_results: ReadonlyArray<MigrationResult>;
+    /** Factory-managed audit log SSE. `null` when `audit_log_sse` option is not set. */
+    audit_sse: AuditLogSse | null;
+    /** Close the database connection. Propagated from `AppBackend`. */
+    close: () => Promise<void>;
+}
+/** Default maximum request body size: 1 MiB. */
+export declare const DEFAULT_MAX_BODY_SIZE: number;
+/**
+ * Create a fully assembled Hono app with auth, middleware, and routes.
+ *
+ * Handles the full lifecycle: consumer migrations → proxy middleware →
+ * auth middleware → bootstrap status → route specs → surface generation →
+ * Hono app assembly → static serving.
+ *
+ * @param options - server configuration
+ * @returns assembled Hono app, backend, surface build, and bootstrap status
+ */
+export declare const create_app_server: (options: AppServerOptions) => Promise<AppServer>;
+//# sourceMappingURL=app_server.d.ts.map

package/dist/server/app_server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app_server.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_server.ts"],"names":[],"mappings":"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"}

package/dist/server/app_server.js

@@ -0,0 +1,266 @@
+/**
+ * Server assembly factory.
+ *
+ * `create_app_server()` eliminates the ~100 lines of duplicated server assembly
+ * shared by tx, visiones, and mageguild. Consumers provide a pre-initialized
+ * `AppBackend` and options (session, origins, routes); the factory handles
+ * middleware, bootstrap status, surface generation, and Hono app assembly.
+ *
+ * @module
+ */
+import { Hono } from 'hono';
+import { logger } from 'hono/logger';
+import { bodyLimit } from 'hono/body-limit';
+import { z } from 'zod';
+import { SESSION_COOKIE_OPTIONS, } from '../auth/session_cookie.js';
+import { create_audit_log_sse, AUDIT_LOG_EVENT_SPECS, } from '../realtime/sse_auth_guard.js';
+import { query_app_settings_load } from '../auth/app_settings_queries.js';
+import { create_rate_limiter, DEFAULT_LOGIN_ACCOUNT_RATE_LIMIT, } from '../rate_limiter.js';
+import { run_migrations } from '../db/migrate.js';
+import { AUTH_MIGRATION_NAMESPACE } from '../auth/migrations.js';
+// Side-effect import: augments Hono's ContextVariableMap so consumers
+// that import app_server get type-safe c.get('auth_session_id') etc.
+import '../hono_context.js';
+import { create_proxy_middleware_spec } from '../http/proxy.js';
+import { create_static_middleware } from './static.js';
+import { log_startup_summary } from './startup.js';
+import { create_app_surface_spec, } from '../http/surface.js';
+import { apply_middleware_specs, apply_route_specs, prefix_route_specs, } from '../http/route_spec.js';
+import { check_bootstrap_status, create_bootstrap_route_specs, } from '../auth/bootstrap_routes.js';
+import { create_surface_route_spec } from '../http/common_routes.js';
+import { create_auth_middleware_specs } from '../auth/middleware.js';
+import { fuz_auth_guard_resolver } from '../auth/route_guards.js';
+import { ERROR_PAYLOAD_TOO_LARGE } from '../http/error_schemas.js';
+/** Default maximum request body size: 1 MiB. */
+export const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
+/**
+ * Create a fully assembled Hono app with auth, middleware, and routes.
+ *
+ * Handles the full lifecycle: consumer migrations → proxy middleware →
+ * auth middleware → bootstrap status → route specs → surface generation →
+ * Hono app assembly → static serving.
+ *
+ * @param options - server configuration
+ * @returns assembled Hono app, backend, surface build, and bootstrap status
+ */
+export const create_app_server = async (options) => {
+    const { backend } = options;
+    const { log } = backend.deps;
+    // 1. Consumer migrations
+    let all_migration_results = backend.migration_results;
+    if (options.migration_namespaces?.length) {
+        // guard against namespace collision with fuz_app's internal migrations
+        for (const ns of options.migration_namespaces) {
+            if (ns.namespace === AUTH_MIGRATION_NAMESPACE) {
+                throw new Error(`Migration namespace "${AUTH_MIGRATION_NAMESPACE}" is reserved by fuz_app — choose a different namespace`);
+            }
+        }
+        const consumer_results = await run_migrations(backend.deps.db, options.migration_namespaces);
+        all_migration_results = [...backend.migration_results, ...consumer_results];
+    }
+    // 2. Rate limiter defaults (undefined = default, null = disable)
+    const ip_rate_limiter = options.ip_rate_limiter === undefined ? create_rate_limiter() : options.ip_rate_limiter;
+    const login_account_rate_limiter = options.login_account_rate_limiter === undefined
+        ? create_rate_limiter(DEFAULT_LOGIN_ACCOUNT_RATE_LIMIT)
+        : options.login_account_rate_limiter;
+    const signup_account_rate_limiter = options.signup_account_rate_limiter === undefined
+        ? create_rate_limiter(DEFAULT_LOGIN_ACCOUNT_RATE_LIMIT)
+        : options.signup_account_rate_limiter;
+    const bearer_ip_rate_limiter = options.bearer_ip_rate_limiter === undefined
+        ? create_rate_limiter()
+        : options.bearer_ip_rate_limiter;
+    // 3. Factory-managed audit SSE (shallow copy deps, no mutation of backend.deps)
+    const audit_sse = options.audit_log_sse
+        ? create_audit_log_sse({
+            log,
+            role: typeof options.audit_log_sse === 'object' ? options.audit_log_sse.role : undefined,
+        })
+        : null;
+    const deps = audit_sse
+        ? {
+            ...backend.deps,
+            on_audit_event: (event) => {
+                audit_sse.on_audit_event(event);
+                backend.deps.on_audit_event(event);
+            },
+        }
+        : backend.deps;
+    // 4. Proxy middleware
+    const proxy_spec = create_proxy_middleware_spec({ ...options.proxy, log });
+    // 5. Auth middleware
+    const auth_middleware = await create_auth_middleware_specs(deps, {
+        allowed_origins: options.allowed_origins,
+        session_options: options.session_options,
+        bearer_ip_rate_limiter,
+        daemon_token_state: options.daemon_token_state,
+    });
+    let middleware_specs = [proxy_spec, ...auth_middleware];
+    if (options.transform_middleware) {
+        middleware_specs = options.transform_middleware(middleware_specs);
+    }
+    // 6. Bootstrap status + app settings
+    const bootstrap_status = options.bootstrap
+        ? await check_bootstrap_status(deps, { token_path: options.bootstrap.token_path })
+        : { available: false, token_path: null };
+    const app_settings = await query_app_settings_load({ db: deps.db });
+    // 7. Surface route ref — factory manages the circular ref
+    const surface_ref = {
+        surface: { middleware: [], routes: [], env: [], events: [], diagnostics: [] },
+    };
+    // 8. Route specs (consumer routes + factory-managed routes)
+    const context = {
+        deps,
+        backend,
+        bootstrap_status,
+        session_options: options.session_options,
+        ip_rate_limiter,
+        login_account_rate_limiter,
+        signup_account_rate_limiter,
+        app_settings,
+        audit_sse,
+    };
+    const consumer_routes = options.create_route_specs(context);
+    // Factory-managed routes appended after consumer routes
+    const factory_routes = [];
+    // Bootstrap routes
+    if (options.bootstrap) {
+        const bootstrap_routes = create_bootstrap_route_specs(deps, {
+            session_options: options.session_options,
+            bootstrap_status,
+            on_bootstrap: options.bootstrap.on_bootstrap,
+            ip_rate_limiter,
+        });
+        const prefix = options.bootstrap.route_prefix ?? '/api/account';
+        factory_routes.push(...prefix_route_specs(prefix, bootstrap_routes));
+    }
+    // Surface route (default: enabled)
+    if (options.surface_route !== false) {
+        factory_routes.push(create_surface_route_spec(surface_ref));
+    }
+    const route_specs = [...consumer_routes, ...factory_routes];
+    // 9. Surface + logging
+    const surface_middleware = options.post_route_middleware
+        ? [...middleware_specs, ...options.post_route_middleware]
+        : middleware_specs;
+    const all_event_specs = [
+        ...(options.event_specs ?? []),
+        ...(audit_sse ? AUDIT_LOG_EVENT_SPECS : []),
+    ];
+    const surface_spec = create_app_surface_spec({
+        middleware_specs: surface_middleware,
+        route_specs,
+        env_schema: options.env_schema,
+        event_specs: all_event_specs,
+    });
+    // Config-level diagnostics (concatenated after spec-level from generate_app_surface)
+    const config_diagnostics = [];
+    const cookie_opts = options.session_options.cookie_options;
+    if (cookie_opts) {
+        if (cookie_opts.secure === false) {
+            config_diagnostics.push({
+                level: 'warning',
+                category: 'security',
+                message: 'Session cookie secure=false — cookies sent over HTTP',
+            });
+        }
+        if (cookie_opts.sameSite && cookie_opts.sameSite !== SESSION_COOKIE_OPTIONS.sameSite) {
+            config_diagnostics.push({
+                level: 'warning',
+                category: 'security',
+                message: `Session cookie sameSite='${cookie_opts.sameSite}' — weakened from default '${SESSION_COOKIE_OPTIONS.sameSite}'`,
+            });
+        }
+        if (cookie_opts.httpOnly === false) {
+            config_diagnostics.push({
+                level: 'warning',
+                category: 'security',
+                message: 'Session cookie httpOnly=false — cookie accessible to JavaScript',
+            });
+        }
+    }
+    if (ip_rate_limiter === null) {
+        config_diagnostics.push({
+            level: 'warning',
+            category: 'config',
+            message: 'IP rate limiter explicitly disabled (null)',
+        });
+    }
+    if (bearer_ip_rate_limiter === null) {
+        config_diagnostics.push({
+            level: 'warning',
+            category: 'config',
+            message: 'Bearer IP rate limiter explicitly disabled (null)',
+        });
+    }
+    if (config_diagnostics.length) {
+        surface_spec.surface.diagnostics = [...surface_spec.surface.diagnostics, ...config_diagnostics];
+    }
+    // Backfill the surface ref — factory owns this lifecycle
+    surface_ref.surface = surface_spec.surface;
+    log_startup_summary(surface_spec.surface, log, options.env_values);
+    // 10. Hono app assembly
+    const app = new Hono();
+    // Pending effects — collects fire-and-forget promises (audit logs, usage tracking).
+    // In test mode, effects are awaited before the response returns.
+    // In production, rejected effects are reported via on_effect_error.
+    app.use('*', async (c, next) => {
+        c.set('pending_effects', []);
+        try {
+            await next();
+        }
+        finally {
+            const effects = c.var.pending_effects;
+            if (effects.length) {
+                if (options.await_pending_effects) {
+                    await Promise.allSettled(effects);
+                }
+                else {
+                    const ctx = { method: c.req.method, path: c.req.path };
+                    const callback = options.on_effect_error;
+                    void Promise.allSettled(effects).then((results) => {
+                        for (const result of results) {
+                            if (result.status === 'rejected') {
+                                log.error('Pending effect rejected:', result.reason, ctx);
+                                callback?.(result.reason, ctx);
+                            }
+                        }
+                    });
+                }
+            }
+        }
+    });
+    if (log.level !== 'off') {
+        app.use(logger((msg) => log.info(msg)));
+    }
+    // Body size limit — rejects oversized payloads before auth/validation.
+    // Default 1 MiB; pass null to disable.
+    if (options.max_body_size !== null) {
+        const max_size = options.max_body_size ?? DEFAULT_MAX_BODY_SIZE;
+        app.use(bodyLimit({
+            maxSize: max_size,
+            onError: (c) => c.json({ error: ERROR_PAYLOAD_TOO_LARGE }, 413),
+        }));
+    }
+    apply_middleware_specs(app, middleware_specs);
+    apply_route_specs(app, route_specs, fuz_auth_guard_resolver, log, deps.db);
+    // 11. Post-route middleware (before static serving)
+    if (options.post_route_middleware) {
+        apply_middleware_specs(app, options.post_route_middleware);
+    }
+    // 12. Static file serving
+    if (options.static_serving) {
+        const { serve_static, spa_fallback } = options.static_serving;
+        for (const mw of create_static_middleware(serve_static, { spa_fallback })) {
+            app.use('/*', mw);
+        }
+    }
+    return {
+        app,
+        surface_spec,
+        bootstrap_status,
+        app_settings,
+        migration_results: all_migration_results,
+        audit_sse,
+        close: backend.close,
+    };
+};

package/dist/server/env.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Base server environment schema and validation.
+ *
+ * Provides `BaseServerEnv` — a shared Zod schema for common server env vars
+ * that apps can use directly or extend with app-specific fields.
+ *
+ * Generic env loading lives in `env/load.ts`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { type Keyring } from '../auth/keyring.js';
+/**
+ * Base Zod schema for server environment variables.
+ *
+ * Provides the common fields used by fuz apps:
+ * server config, database, auth, security, public URLs, and SMTP.
+ *
+ * Apps can use directly or extend with app-specific fields via `.extend()`.
+ */
+export declare const BaseServerEnv: z.ZodObject<{
+    NODE_ENV: z.ZodEnum<{
+        development: "development";
+        production: "production";
+    }>;
+    PORT: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    HOST: z.ZodDefault<z.ZodString>;
+    DATABASE_URL: z.ZodString;
+    SECRET_COOKIE_KEYS: z.ZodString;
+    ALLOWED_ORIGINS: z.ZodString;
+    PUBLIC_API_URL: z.ZodDefault<z.ZodString>;
+    PUBLIC_WEBSOCKET_URL: z.ZodOptional<z.ZodString>;
+    PUBLIC_CONTACT_EMAIL: z.ZodOptional<z.ZodUnion<readonly [z.ZodEmail, z.ZodLiteral<"">]>>;
+    BOOTSTRAP_TOKEN_PATH: z.ZodOptional<z.ZodString>;
+    SMTP_HOST: z.ZodOptional<z.ZodString>;
+    SMTP_USER: z.ZodOptional<z.ZodUnion<readonly [z.ZodEmail, z.ZodLiteral<"">]>>;
+    SMTP_PASSWORD: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type BaseServerEnv = z.infer<typeof BaseServerEnv>;
+/**
+ * Validated server env config — the artifacts `create_app_server()` needs.
+ */
+export interface ServerEnvOptions {
+    ok: true;
+    keyring: Keyring;
+    allowed_origins: Array<RegExp>;
+    bootstrap_token_path: string | null;
+}
+/**
+ * Error from `validate_server_env` — keyring or origin validation failed.
+ */
+export interface ServerEnvOptionsError {
+    ok: false;
+    field: 'SECRET_COOKIE_KEYS' | 'ALLOWED_ORIGINS';
+    errors: Array<string>;
+}
+export type ServerEnvOptionsResult = ServerEnvOptions | ServerEnvOptionsError;
+/**
+ * Validate a loaded `BaseServerEnv` and produce the artifacts needed for server init.
+ *
+ * Handles keyring validation, origin parsing, and bootstrap token path extraction.
+ * Returns a Result so callers handle errors their own way (exit, logging, etc).
+ *
+ * @param env - a loaded and Zod-validated `BaseServerEnv`
+ * @returns `{ok: true, keyring, allowed_origins, bootstrap_token_path}` or `{ok: false, field, errors}`
+ */
+export declare const validate_server_env: (env: BaseServerEnv) => ServerEnvOptionsResult;
+//# sourceMappingURL=env.d.ts.map

package/dist/server/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EAA2B,KAAK,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAG1E;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;kBAkCxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,oBAAoB,GAAG,iBAAiB,CAAC;IAChD,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,GAAG,qBAAqB,CAAC;AAE9E;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,aAAa,KAAG,sBA4BxD,CAAC"}