@fuzdev/fuz_app 0.1.0

package/dist/server/env.js

@@ -0,0 +1,95 @@
+/**
+ * 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 { create_validated_keyring } from '../auth/keyring.js';
+import { parse_allowed_origins } from '../http/origin.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 const BaseServerEnv = z.strictObject({
+    NODE_ENV: z.enum(['development', 'production']).meta({ description: 'Runtime environment mode' }),
+    PORT: z.coerce.number().default(4040).meta({ description: 'HTTP server port' }),
+    HOST: z.string().default('localhost').meta({ description: 'HTTP server bind address' }),
+    DATABASE_URL: z.string().min(1).meta({
+        description: 'Database URL (postgres://, file://, or memory://)',
+        sensitivity: 'secret',
+    }),
+    SECRET_COOKIE_KEYS: z.string().min(32).meta({
+        description: 'Cookie signing keys, separated by __ for rotation',
+        sensitivity: 'secret',
+    }),
+    ALLOWED_ORIGINS: z.string().min(1, 'ALLOWED_ORIGINS is required').meta({
+        description: 'Comma-separated origin patterns for API verification',
+    }),
+    PUBLIC_API_URL: z.string().default('/api').meta({ description: 'Public API base URL' }),
+    PUBLIC_WEBSOCKET_URL: z.string().optional().meta({ description: 'Public WebSocket URL' }),
+    PUBLIC_CONTACT_EMAIL: z
+        .union([z.email(), z.literal('')])
+        .optional()
+        .meta({ description: 'Public contact email address' }),
+    BOOTSTRAP_TOKEN_PATH: z
+        .string()
+        .optional()
+        .meta({ description: 'Path to one-shot admin bootstrap token', sensitivity: 'secret' }),
+    SMTP_HOST: z.string().optional().meta({ description: 'SMTP server hostname' }),
+    SMTP_USER: z
+        .union([z.email(), z.literal('')])
+        .optional()
+        .meta({ description: 'SMTP authentication username' }),
+    SMTP_PASSWORD: z
+        .string()
+        .optional()
+        .meta({ description: 'SMTP authentication password', sensitivity: 'secret' }),
+});
+/**
+ * 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 const validate_server_env = (env) => {
+    const keyring_result = create_validated_keyring(env.SECRET_COOKIE_KEYS);
+    if (!keyring_result.ok) {
+        return { ok: false, field: 'SECRET_COOKIE_KEYS', errors: keyring_result.errors };
+    }
+    let allowed_origins;
+    try {
+        allowed_origins = parse_allowed_origins(env.ALLOWED_ORIGINS);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            field: 'ALLOWED_ORIGINS',
+            errors: [err instanceof Error ? err.message : 'Invalid ALLOWED_ORIGINS'],
+        };
+    }
+    if (allowed_origins.length === 0) {
+        return {
+            ok: false,
+            field: 'ALLOWED_ORIGINS',
+            errors: ['ALLOWED_ORIGINS contains no valid patterns'],
+        };
+    }
+    return {
+        ok: true,
+        keyring: keyring_result.keyring,
+        allowed_origins,
+        bootstrap_token_path: env.BOOTSTRAP_TOKEN_PATH ?? null,
+    };
+};

package/dist/server/startup.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Composable startup summary helpers.
+ *
+ * Logs a human-readable summary from an `AppSurface`.
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { AppSurface } from '../http/surface.js';
+/**
+ * Log a startup summary from an `AppSurface`.
+ *
+ * Logs route count, middleware count, env breakdown (when non-empty),
+ * and event/channel counts (when non-empty). When `env_values` is provided,
+ * non-secret values are logged and secrets are masked with `***`.
+ *
+ * @param surface - the app surface to summarize
+ * @param log - the logger instance
+ * @param env_values - optional env values to log (secrets are masked)
+ */
+export declare const log_startup_summary: (surface: AppSurface, log: Logger, env_values?: Record<string, unknown>) => void;
+//# sourceMappingURL=startup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"startup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/startup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAC/B,SAAS,UAAU,EACnB,KAAK,MAAM,EACX,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAClC,IAqCF,CAAC"}

package/dist/server/startup.js

@@ -0,0 +1,48 @@
+/**
+ * Composable startup summary helpers.
+ *
+ * Logs a human-readable summary from an `AppSurface`.
+ *
+ * @module
+ */
+import { format_env_display_value } from '../env/mask.js';
+/**
+ * Log a startup summary from an `AppSurface`.
+ *
+ * Logs route count, middleware count, env breakdown (when non-empty),
+ * and event/channel counts (when non-empty). When `env_values` is provided,
+ * non-secret values are logged and secrets are masked with `***`.
+ *
+ * @param surface - the app surface to summarize
+ * @param log - the logger instance
+ * @param env_values - optional env values to log (secrets are masked)
+ */
+export const log_startup_summary = (surface, log, env_values) => {
+    log.info(`Surface: ${surface.routes.length} routes, ${surface.middleware.length} middleware layers`);
+    if (surface.env.length) {
+        const required = surface.env.filter((e) => !e.optional);
+        const secret = surface.env.filter((e) => e.sensitivity === 'secret');
+        log.info(`Env: ${surface.env.length} vars (${required.length} required, ${secret.length} secret)`);
+        if (env_values) {
+            for (const entry of surface.env) {
+                const value = env_values[entry.name];
+                if (value === undefined)
+                    continue;
+                log.info(`  ${entry.name}=${format_env_display_value(value, entry.sensitivity === 'secret')}`);
+            }
+        }
+    }
+    if (surface.events.length) {
+        const channels = new Set(surface.events.map((e) => e.channel).filter(Boolean));
+        log.info(`Events: ${surface.events.length} types, ${channels.size} channels`);
+    }
+    if (surface.diagnostics.length) {
+        const warnings = surface.diagnostics.filter((d) => d.level === 'warning');
+        if (warnings.length) {
+            log.warn(`Diagnostics: ${warnings.length} warning(s)`);
+            for (const d of warnings) {
+                log.warn(`  [${d.category}] ${d.message}${d.source ? ` (${d.source})` : ''}`);
+            }
+        }
+    }
+};

package/dist/server/static.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Static file serving middleware for SvelteKit static builds.
+ *
+ * Provides multi-phase static serving:
+ * - Phase 1: Exact path match (handles /, assets, images)
+ * - Phase 2: `.html` fallback for clean URLs (`/about` → `/about.html`)
+ * - Phase 3 (optional): SPA fallback for client-side routes
+ *
+ * @module
+ */
+import type { MiddlewareHandler } from 'hono';
+/**
+ * Options for `serve_static` factory functions (matches Hono's `serveStatic` signature).
+ */
+export interface ServeStaticOptions {
+    root: string;
+    rewriteRequestPath?: (path: string) => string;
+    mimes?: Record<string, string>;
+}
+/**
+ * Factory function that creates a static file serving middleware.
+ *
+ * Matches the signature of `serveStatic` from `hono/deno` and `@hono/node-server/serve-static`.
+ */
+export type ServeStaticFactory = (options: ServeStaticOptions) => MiddlewareHandler;
+/**
+ * Create static file serving middleware for SvelteKit static builds.
+ *
+ * Returns an array of middleware handlers to register on `'/*'`.
+ *
+ * @param serve_static - runtime-specific `serveStatic` factory
+ * @param options - optional root directory and SPA fallback path
+ * @returns array of middleware handlers to apply in order
+ */
+export declare const create_static_middleware: (serve_static: ServeStaticFactory, options?: {
+    root?: string;
+    spa_fallback?: string;
+}) => Array<MiddlewareHandler>;
+//# sourceMappingURL=static.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"static.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/static.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,kBAAkB,KAAK,iBAAiB,CAAC;AAEpF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GACpC,cAAc,kBAAkB,EAChC,UAAU;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAC,KAC9C,KAAK,CAAC,iBAAiB,CAqBzB,CAAC"}

package/dist/server/static.js

@@ -0,0 +1,38 @@
+/**
+ * Static file serving middleware for SvelteKit static builds.
+ *
+ * Provides multi-phase static serving:
+ * - Phase 1: Exact path match (handles /, assets, images)
+ * - Phase 2: `.html` fallback for clean URLs (`/about` → `/about.html`)
+ * - Phase 3 (optional): SPA fallback for client-side routes
+ *
+ * @module
+ */
+/**
+ * Create static file serving middleware for SvelteKit static builds.
+ *
+ * Returns an array of middleware handlers to register on `'/*'`.
+ *
+ * @param serve_static - runtime-specific `serveStatic` factory
+ * @param options - optional root directory and SPA fallback path
+ * @returns array of middleware handlers to apply in order
+ */
+export const create_static_middleware = (serve_static, options) => {
+    const root = options?.root ?? './build';
+    const handlers = [];
+    // Phase 1: exact path match
+    handlers.push(serve_static({ root }));
+    // Phase 2: .html fallback for clean URLs (/about → /about.html)
+    handlers.push(async (c, next) => {
+        const path = c.req.path;
+        if (path === '/' || path.includes('.'))
+            return next();
+        return serve_static({ root, rewriteRequestPath: () => `${path}.html` })(c, next);
+    });
+    // Phase 3: optional SPA fallback for client-side routes
+    if (options?.spa_fallback) {
+        const fallback = options.spa_fallback;
+        handlers.push(serve_static({ root, rewriteRequestPath: () => fallback }));
+    }
+    return handlers;
+};

package/dist/server/validate_nginx.d.ts

@@ -0,0 +1,34 @@
+/**
+ * String-based nginx config validator for fuz_app deploy configs.
+ *
+ * Checks consumer `NGINX_CONFIG` template strings for required security
+ * properties. This is pattern matching on template strings, not a real
+ * nginx parser — it catches common security omissions but won't catch
+ * all possible misconfigurations.
+ *
+ * @module
+ */
+/**
+ * Result of validating an nginx config template string.
+ */
+export interface NginxValidationResult {
+    ok: boolean;
+    warnings: Array<string>;
+    errors: Array<string>;
+}
+/**
+ * Validate an nginx config template string for security properties.
+ *
+ * Checks for required security headers, Authorization stripping in `/api`
+ * blocks, and the nginx `add_header` inheritance gotcha. Designed for
+ * fuz_app consumer deploy configs (tx.ts `NGINX_CONFIG` constants).
+ *
+ * Limitations: string pattern matching, not a real nginx parser. Catches
+ * common omissions in fuz_app deploy configs but won't catch all possible
+ * misconfigurations.
+ *
+ * @param config - nginx config template string
+ * @returns validation result with ok status, warnings, and errors
+ */
+export declare const validate_nginx_config: (config: string) => NginxValidationResult;
+//# sourceMappingURL=validate_nginx.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate_nginx.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/validate_nginx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAgCD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,KAAG,qBA2FtD,CAAC"}

package/dist/server/validate_nginx.js

@@ -0,0 +1,118 @@
+/**
+ * String-based nginx config validator for fuz_app deploy configs.
+ *
+ * Checks consumer `NGINX_CONFIG` template strings for required security
+ * properties. This is pattern matching on template strings, not a real
+ * nginx parser — it catches common security omissions but won't catch
+ * all possible misconfigurations.
+ *
+ * @module
+ */
+/**
+ * Extract location blocks from an nginx config string.
+ *
+ * Finds `location [= ] <path> {` directives and extracts the full block
+ * content including nested braces. Returns the path and full block text.
+ */
+const extract_location_blocks = (config) => {
+    const blocks = [];
+    const location_regex = /location\s+(?:=\s+)?(\S+)\s*\{/g;
+    let match;
+    while ((match = location_regex.exec(config)) !== null) {
+        const path = match[1];
+        const open_brace_index = match.index + match[0].length - 1;
+        let depth = 1;
+        let block_end = open_brace_index + 1;
+        for (let i = open_brace_index + 1; i < config.length; i++) {
+            if (config[i] === '{')
+                depth++;
+            else if (config[i] === '}') {
+                depth--;
+                if (depth === 0) {
+                    block_end = i + 1;
+                    break;
+                }
+            }
+        }
+        blocks.push({ path, content: config.slice(match.index, block_end) });
+    }
+    return blocks;
+};
+/**
+ * Validate an nginx config template string for security properties.
+ *
+ * Checks for required security headers, Authorization stripping in `/api`
+ * blocks, and the nginx `add_header` inheritance gotcha. Designed for
+ * fuz_app consumer deploy configs (tx.ts `NGINX_CONFIG` constants).
+ *
+ * Limitations: string pattern matching, not a real nginx parser. Catches
+ * common omissions in fuz_app deploy configs but won't catch all possible
+ * misconfigurations.
+ *
+ * @param config - nginx config template string
+ * @returns validation result with ok status, warnings, and errors
+ */
+export const validate_nginx_config = (config) => {
+    const errors = [];
+    const warnings = [];
+    const all_blocks = extract_location_blocks(config);
+    // 1. proxy_set_header Authorization "" in /api location blocks
+    const api_blocks = all_blocks.filter((b) => b.path === '/api' || b.path.startsWith('/api/') || b.path.startsWith('/api{'));
+    if (api_blocks.length > 0) {
+        const has_auth_strip = api_blocks.some((block) => block.content.includes('proxy_set_header Authorization ""') ||
+            block.content.includes("proxy_set_header Authorization ''"));
+        if (!has_auth_strip) {
+            errors.push('Missing `proxy_set_header Authorization ""` in /api location block — ' +
+                'required for v1 cookie-only external auth posture');
+        }
+    }
+    // 2. Strict-Transport-Security (error if missing)
+    if (!config.includes('Strict-Transport-Security')) {
+        errors.push('Missing Strict-Transport-Security header');
+    }
+    // 3. X-Content-Type-Options "nosniff" (warning if missing)
+    if (!config.includes('X-Content-Type-Options')) {
+        warnings.push('Missing X-Content-Type-Options "nosniff" header');
+    }
+    // 4. X-Frame-Options (warning if missing)
+    if (!config.includes('X-Frame-Options')) {
+        warnings.push('Missing X-Frame-Options header');
+    }
+    // 5. Referrer-Policy (warning if missing)
+    if (!config.includes('Referrer-Policy')) {
+        warnings.push('Missing Referrer-Policy header');
+    }
+    // 6. server_tokens off (warning if missing)
+    if (!config.includes('server_tokens off')) {
+        warnings.push('Missing server_tokens off — nginx version may be disclosed');
+    }
+    // 7. limit_req (warning if missing — may be in a separate rate_limit.conf)
+    if (!config.includes('limit_req')) {
+        warnings.push('Missing limit_req — may be in a separate rate_limit.conf. ' +
+            'Consider adding nginx-level rate limiting');
+    }
+    // 8. X-Forwarded-For: prefer $remote_addr over $proxy_add_x_forwarded_for
+    if (config.includes('$proxy_add_x_forwarded_for')) {
+        warnings.push('Using $proxy_add_x_forwarded_for — prefer $remote_addr for single-proxy setups ' +
+            'to avoid client-injected XFF headers');
+    }
+    // 9. Child location blocks with add_header must repeat security headers
+    for (const block of all_blocks) {
+        if (block.content.includes('add_header') &&
+            !block.content.includes('Strict-Transport-Security')) {
+            // Only flag child locations that add their own response headers
+            // (Cache-Control, Content-Disposition, etc.) — these override
+            // inherited headers from the parent server block
+            if (block.content.includes('Cache-Control') ||
+                block.content.includes('Content-Disposition')) {
+                warnings.push(`Location ${block.path} has add_header but is missing Strict-Transport-Security — ` +
+                    'nginx add_header in child blocks replaces (not extends) inherited headers');
+            }
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        warnings,
+        errors,
+    };
+};

package/dist/testing/CLAUDE.md

@@ -0,0 +1,3 @@
+# testing/
+
+Every module in this directory starts with `import './assert_dev_env.js';` as its first line. This side-effect import throws at runtime if `DEV` (from `esm-env`) is false, preventing accidental inclusion in production bundles. Always add this import as the first line when creating new testing modules.

package/dist/testing/admin_integration.d.ts

@@ -0,0 +1,45 @@
+import './assert_dev_env.js';
+import type { SessionOptions } from '../auth/session_cookie.js';
+import type { AppServerContext, AppServerOptions } from '../server/app_server.js';
+import type { RouteSpec } from '../http/route_spec.js';
+import { type RoleSchemaResult } from '../auth/role_schema.js';
+import { type DbFactory } from './db.js';
+/**
+ * Configuration for `describe_standard_admin_integration_tests`.
+ */
+export interface StandardAdminIntegrationTestOptions {
+    /** Session config for cookie-based auth. */
+    session_options: SessionOptions<string>;
+    /** Route spec factory — same one used in production. */
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    /** Role schema result from `create_role_schema()` — used to determine valid/invalid/web-grantable roles. */
+    roles: RoleSchemaResult;
+    /**
+     * Path prefix where admin routes are mounted (e.g., `'/api/admin'`).
+     * Used by the schema validation test to scope to fuz_app admin routes only,
+     * avoiding app-specific admin-gated routes that may use stub deps.
+     * Default `'/api/admin'`.
+     */
+    admin_prefix?: string;
+    /** Optional overrides for `AppServerOptions`. */
+    app_options?: Partial<Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'>>;
+    /**
+     * Database factories to run tests against. Default: pglite only.
+     * Pass consumer factories (e.g. `[pglite_factory, pg_factory]`) to also test against PostgreSQL.
+     */
+    db_factories?: Array<DbFactory>;
+}
+/**
+ * Standard admin integration test suite for fuz_app admin routes.
+ *
+ * Exercises account listing, permit grant/revoke, session management, token
+ * management, audit log routes, admin-to-admin isolation, and response
+ * schema validation.
+ *
+ * Each test group asserts that required routes exist, failing with a descriptive
+ * message if the consumer's route specs are misconfigured.
+ *
+ * @param options - session config, route factory, and role schema
+ */
+export declare const describe_standard_admin_integration_tests: (options: StandardAdminIntegrationTestOptions) => void;
+//# sourceMappingURL=admin_integration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"admin_integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/admin_integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAiB7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAA0B,KAAK,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAGtF,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AAUjB;;GAEG;AACH,MAAM,WAAW,mCAAmC;IACnD,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,4GAA4G;IAC5G,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CACpB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,iBAAiB,GAAG,oBAAoB,CAAC,CAC5E,CAAC;IACF;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAChC;AAgDD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,mCAAmC,KAC1C,IAomCF,CAAC"}