@fuzdev/fuz_app 0.1.0

package/dist/http/surface.js

@@ -0,0 +1,156 @@
+/**
+ * App surface generation — JSON-serializable attack surface from route and middleware specs.
+ *
+ * Pure schema helpers (`is_null_schema`, `schema_to_surface`, `middleware_applies`,
+ * `merge_error_schemas`) live in `schema_helpers.ts`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { schema_to_surface, middleware_applies, merge_error_schemas, is_null_schema, is_strict_object_schema, } from './schema_helpers.js';
+// --- Surface generation ---
+/**
+ * Collect error schemas from all middleware that applies to a route path.
+ *
+ * @param middleware - the middleware specs
+ * @param route_path - the route path to match against
+ * @returns merged middleware error schemas, or `null` if none
+ */
+export const collect_middleware_errors = (middleware, route_path) => {
+    const errors = {};
+    for (const mw of middleware) {
+        if (mw.errors && middleware_applies(mw.path, route_path)) {
+            Object.assign(errors, mw.errors);
+        }
+    }
+    return Object.keys(errors).length > 0 ? errors : null;
+};
+/**
+ * Convert env schema to surface entries using `.meta()` metadata.
+ *
+ * @param schema - Zod object schema with `.meta()` on fields
+ * @returns array of env surface entries
+ */
+export const env_schema_to_surface = (schema) => {
+    const entries = [];
+    for (const [name, field_schema] of Object.entries(schema.shape)) {
+        const field = field_schema;
+        const meta = field.meta();
+        const undef_result = field.safeParse(undefined);
+        entries.push({
+            name,
+            description: meta?.description ?? '',
+            sensitivity: meta?.sensitivity ?? null,
+            has_default: undef_result.success && undef_result.data !== undefined,
+            optional: undef_result.success,
+        });
+    }
+    return entries;
+};
+/**
+ * Convert SSE event specs to surface entries.
+ *
+ * @param event_specs - event specs to convert
+ * @returns array of event surface entries
+ */
+export const events_to_surface = (event_specs) => {
+    return event_specs.map((spec) => ({
+        method: spec.method,
+        description: spec.description,
+        channel: spec.channel ?? null,
+        params_schema: schema_to_surface(spec.params),
+    }));
+};
+/**
+ * Generate a JSON-serializable attack surface from middleware, route specs,
+ * and optional env/event metadata.
+ *
+ * @param options - the surface generation options
+ * @returns the attack surface
+ */
+export const generate_app_surface = (options) => {
+    const { route_specs, middleware_specs, env_schema, event_specs } = options;
+    const diagnostics = [];
+    // Spec-level diagnostics: check for non-strict input schemas
+    for (const r of route_specs) {
+        if (!is_null_schema(r.input) && !is_strict_object_schema(r.input)) {
+            diagnostics.push({
+                level: 'warning',
+                category: 'schema',
+                message: 'Input schema is not z.strictObject() — unknown keys will be silently stripped',
+                source: `${r.method} ${r.path} input`,
+            });
+        }
+    }
+    return {
+        diagnostics,
+        middleware: middleware_specs.map((m) => {
+            let mw_error_schemas = null;
+            if (m.errors) {
+                const schemas = {};
+                for (const [status, schema] of Object.entries(m.errors)) {
+                    const json_schema = schema_to_surface(schema);
+                    if (json_schema !== null) {
+                        schemas[status] = json_schema;
+                    }
+                }
+                if (Object.keys(schemas).length > 0) {
+                    mw_error_schemas = schemas;
+                }
+            }
+            return { name: m.name, path: m.path, error_schemas: mw_error_schemas };
+        }),
+        routes: route_specs.map((r) => {
+            const applicable_middleware = middleware_specs
+                .filter((m) => middleware_applies(m.path, r.path))
+                .map((m) => m.name);
+            // Merge auto-derived + middleware + explicit error schemas
+            const mw_errors = collect_middleware_errors(middleware_specs, r.path);
+            const merged_errors = merge_error_schemas(r, mw_errors);
+            let error_schemas = null;
+            if (merged_errors) {
+                const schemas = {};
+                for (const [status, schema] of Object.entries(merged_errors)) {
+                    const json_schema = schema_to_surface(schema);
+                    if (json_schema !== null) {
+                        schemas[status] = json_schema;
+                    }
+                }
+                if (Object.keys(schemas).length > 0) {
+                    error_schemas = schemas;
+                }
+            }
+            return {
+                method: r.method,
+                path: r.path,
+                auth: r.auth,
+                applicable_middleware,
+                description: r.description,
+                is_mutation: r.method !== 'GET',
+                transaction: r.transaction ?? r.method !== 'GET',
+                rate_limit_key: r.rate_limit ?? null,
+                params_schema: r.params ? schema_to_surface(r.params) : null,
+                query_schema: r.query ? schema_to_surface(r.query) : null,
+                input_schema: schema_to_surface(r.input),
+                output_schema: schema_to_surface(r.output),
+                error_schemas,
+            };
+        }),
+        env: env_schema ? env_schema_to_surface(env_schema) : [],
+        events: event_specs?.length ? events_to_surface(event_specs) : [],
+    };
+};
+/**
+ * Create an `AppSurfaceSpec` — the surface bundled with its source specs.
+ *
+ * @param options - the surface generation options
+ * @returns the surface spec with surface and raw specs
+ */
+export const create_app_surface_spec = (options) => {
+    const surface = generate_app_surface(options);
+    return {
+        surface,
+        route_specs: options.route_specs,
+        middleware_specs: options.middleware_specs,
+    };
+};

package/dist/http/surface_query.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Pure query functions over `AppSurface` data.
+ *
+ * Usable in tests, the adversarial auth runner, and future surface explorer UI.
+ * Replaces duplicated inline `.filter()` patterns.
+ *
+ * TODO @surface-explorer Used by test utilities (test_auth_surface, adversarial_input,
+ * surface_invariants) and SurfaceExplorer.svelte (surface_auth_summary, format_route_key).
+ * Several query functions (filter_authenticated_routes, filter_keeper_routes,
+ * routes_by_auth_type, filter_routes_by_prefix) are pre-built for richer surface
+ * explorer features and consumer test suites — leverage more as the surface UI matures.
+ *
+ * @module
+ */
+import type { AppSurface, AppSurfaceRoute } from './surface.js';
+/** Filter routes that require any form of authentication. */
+export declare const filter_protected_routes: (surface: AppSurface) => Array<AppSurfaceRoute>;
+/** Filter routes that are publicly accessible (no auth). */
+export declare const filter_public_routes: (surface: AppSurface) => Array<AppSurfaceRoute>;
+/** Filter all role-guarded routes (any role). */
+export declare const filter_role_routes: (surface: AppSurface) => Array<AppSurfaceRoute & {
+    auth: {
+        type: "role";
+        role: string;
+    };
+}>;
+/** Filter routes that require basic authentication (no specific role). */
+export declare const filter_authenticated_routes: (surface: AppSurface) => Array<AppSurfaceRoute & {
+    auth: {
+        type: "authenticated";
+    };
+}>;
+/** Filter routes that require keeper credentials. */
+export declare const filter_keeper_routes: (surface: AppSurface) => Array<AppSurfaceRoute & {
+    auth: {
+        type: "keeper";
+    };
+}>;
+/** Filter routes that require a specific named role. */
+export declare const filter_routes_for_role: (surface: AppSurface, role: string) => Array<AppSurfaceRoute & {
+    auth: {
+        type: "role";
+        role: string;
+    };
+}>;
+/**
+ * Group routes by auth type.
+ *
+ * @returns a map from auth type string to route arrays, with role routes keyed as `'role:name'`
+ */
+export declare const routes_by_auth_type: (surface: AppSurface) => Map<string, Array<AppSurfaceRoute>>;
+/** Filter routes whose path starts with `prefix`. */
+export declare const filter_routes_by_prefix: (surface: AppSurface, prefix: string) => Array<AppSurfaceRoute>;
+/** Filter routes that have a non-null input schema. */
+export declare const filter_routes_with_input: (surface: AppSurface) => Array<AppSurfaceRoute>;
+/** Filter routes that have a non-null params schema. */
+export declare const filter_routes_with_params: (surface: AppSurface) => Array<AppSurfaceRoute>;
+/** Filter routes that have a non-null query schema. */
+export declare const filter_routes_with_query: (surface: AppSurface) => Array<AppSurfaceRoute>;
+/** Filter routes that are mutations (POST, PUT, DELETE, PATCH). */
+export declare const filter_mutation_routes: (surface: AppSurface) => Array<AppSurfaceRoute>;
+/** Filter routes that declare rate limiting. */
+export declare const filter_rate_limited_routes: (surface: AppSurface) => Array<AppSurfaceRoute>;
+/** Format a route as `'METHOD /path'` (e.g. `'GET /health'`). */
+export declare const format_route_key: (route: AppSurfaceRoute) => string;
+/**
+ * Summarize route auth distribution across the surface.
+ *
+ * @returns counts by auth type, with role counts broken out by role name
+ */
+export declare const surface_auth_summary: (surface: AppSurface) => {
+    none: number;
+    authenticated: number;
+    role: Map<string, number>;
+    keeper: number;
+};
+//# sourceMappingURL=surface_query.d.ts.map

package/dist/http/surface_query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface_query.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/surface_query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAE,eAAe,EAAC,MAAM,cAAc,CAAC;AAE9D,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAEtD,4DAA4D;AAC5D,eAAO,MAAM,oBAAoB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC3B,CAAC;AAEtD,iDAAiD;AACjD,eAAO,MAAM,kBAAkB,GAC9B,SAAS,UAAU,KACjB,KAAK,CAAC,eAAe,GAAG;IAAC,IAAI,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAA;CAAC,CAG7D,CAAC;AAEH,0EAA0E;AAC1E,eAAO,MAAM,2BAA2B,GACvC,SAAS,UAAU,KACjB,KAAK,CAAC,eAAe,GAAG;IAAC,IAAI,EAAE;QAAC,IAAI,EAAE,eAAe,CAAA;KAAC,CAAA;CAAC,CAGxD,CAAC;AAEH,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,GAChC,SAAS,UAAU,KACjB,KAAK,CAAC,eAAe,GAAG;IAAC,IAAI,EAAE;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAC,CAAA;CAAC,CAGjD,CAAC;AAEH,wDAAwD;AACxD,eAAO,MAAM,sBAAsB,GAClC,SAAS,UAAU,EACnB,MAAM,MAAM,KACV,KAAK,CAAC,eAAe,GAAG;IAAC,IAAI,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAA;CAAC,CAI7D,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,UAAU,KAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAY3F,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,uBAAuB,GACnC,SAAS,UAAU,EACnB,QAAQ,MAAM,KACZ,KAAK,CAAC,eAAe,CAA4D,CAAC;AAErF,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAEvD,wDAAwD;AACxD,eAAO,MAAM,yBAAyB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAExD,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAEvD,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CACtC,CAAC;AAE7C,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,GAAI,SAAS,UAAU,KAAG,KAAK,CAAC,eAAe,CAC9B,CAAC;AAEzD,iEAAiE;AACjE,eAAO,MAAM,gBAAgB,GAAI,OAAO,eAAe,KAAG,MAAyC,CAAC;AAEpG;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,UAAU,KACjB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAwBjF,CAAC"}

package/dist/http/surface_query.js

@@ -0,0 +1,86 @@
+/**
+ * Pure query functions over `AppSurface` data.
+ *
+ * Usable in tests, the adversarial auth runner, and future surface explorer UI.
+ * Replaces duplicated inline `.filter()` patterns.
+ *
+ * TODO @surface-explorer Used by test utilities (test_auth_surface, adversarial_input,
+ * surface_invariants) and SurfaceExplorer.svelte (surface_auth_summary, format_route_key).
+ * Several query functions (filter_authenticated_routes, filter_keeper_routes,
+ * routes_by_auth_type, filter_routes_by_prefix) are pre-built for richer surface
+ * explorer features and consumer test suites — leverage more as the surface UI matures.
+ *
+ * @module
+ */
+/** Filter routes that require any form of authentication. */
+export const filter_protected_routes = (surface) => surface.routes.filter((r) => r.auth.type !== 'none');
+/** Filter routes that are publicly accessible (no auth). */
+export const filter_public_routes = (surface) => surface.routes.filter((r) => r.auth.type === 'none');
+/** Filter all role-guarded routes (any role). */
+export const filter_role_routes = (surface) => surface.routes.filter((r) => r.auth.type === 'role');
+/** Filter routes that require basic authentication (no specific role). */
+export const filter_authenticated_routes = (surface) => surface.routes.filter((r) => r.auth.type === 'authenticated');
+/** Filter routes that require keeper credentials. */
+export const filter_keeper_routes = (surface) => surface.routes.filter((r) => r.auth.type === 'keeper');
+/** Filter routes that require a specific named role. */
+export const filter_routes_for_role = (surface, role) => surface.routes.filter((r) => r.auth.type === 'role' && r.auth.role === role);
+/**
+ * Group routes by auth type.
+ *
+ * @returns a map from auth type string to route arrays, with role routes keyed as `'role:name'`
+ */
+export const routes_by_auth_type = (surface) => {
+    const groups = new Map();
+    for (const r of surface.routes) {
+        const key = r.auth.type === 'role' ? `role:${r.auth.role}` : r.auth.type;
+        let group = groups.get(key);
+        if (!group) {
+            group = [];
+            groups.set(key, group);
+        }
+        group.push(r);
+    }
+    return groups;
+};
+/** Filter routes whose path starts with `prefix`. */
+export const filter_routes_by_prefix = (surface, prefix) => surface.routes.filter((r) => r.path.startsWith(prefix));
+/** Filter routes that have a non-null input schema. */
+export const filter_routes_with_input = (surface) => surface.routes.filter((r) => r.input_schema !== null);
+/** Filter routes that have a non-null params schema. */
+export const filter_routes_with_params = (surface) => surface.routes.filter((r) => r.params_schema !== null);
+/** Filter routes that have a non-null query schema. */
+export const filter_routes_with_query = (surface) => surface.routes.filter((r) => r.query_schema !== null);
+/** Filter routes that are mutations (POST, PUT, DELETE, PATCH). */
+export const filter_mutation_routes = (surface) => surface.routes.filter((r) => r.is_mutation);
+/** Filter routes that declare rate limiting. */
+export const filter_rate_limited_routes = (surface) => surface.routes.filter((r) => r.rate_limit_key !== null);
+/** Format a route as `'METHOD /path'` (e.g. `'GET /health'`). */
+export const format_route_key = (route) => `${route.method} ${route.path}`;
+/**
+ * Summarize route auth distribution across the surface.
+ *
+ * @returns counts by auth type, with role counts broken out by role name
+ */
+export const surface_auth_summary = (surface) => {
+    let none = 0;
+    let authenticated = 0;
+    const role = new Map();
+    let keeper = 0;
+    for (const r of surface.routes) {
+        switch (r.auth.type) {
+            case 'none':
+                none++;
+                break;
+            case 'authenticated':
+                authenticated++;
+                break;
+            case 'role':
+                role.set(r.auth.role, (role.get(r.auth.role) ?? 0) + 1);
+                break;
+            case 'keeper':
+                keeper++;
+                break;
+        }
+    }
+    return { none, authenticated, role, keeper };
+};

package/dist/rate_limiter.d.ts

@@ -0,0 +1,94 @@
+/**
+ * In-memory sliding window rate limiter.
+ *
+ * Tracks failed attempts per key (typically IP address) using a sliding
+ * time window. No external dependencies — state resets on server restart.
+ *
+ * @module
+ */
+import type { Context } from 'hono';
+/**
+ * Configuration for a rate limiter instance.
+ */
+export interface RateLimiterOptions {
+    /** Maximum allowed attempts within the window. */
+    max_attempts: number;
+    /** Sliding window duration in milliseconds. */
+    window_ms: number;
+    /** Interval for pruning stale entries (0 disables the timer). */
+    cleanup_interval_ms: number;
+}
+/** Default options for per-IP login rate limiting: 5 attempts per 15 minutes. */
+export declare const DEFAULT_LOGIN_IP_RATE_LIMIT: RateLimiterOptions;
+/** Default options for per-account login rate limiting: 10 attempts per 30 minutes. */
+export declare const DEFAULT_LOGIN_ACCOUNT_RATE_LIMIT: RateLimiterOptions;
+/**
+ * Result of a rate limit check or record operation.
+ */
+export interface RateLimitResult {
+    /** Whether the request is allowed. */
+    allowed: boolean;
+    /** Remaining attempts before blocking. */
+    remaining: number;
+    /** Seconds until the oldest active attempt expires (0 if allowed). */
+    retry_after: number;
+}
+/**
+ * In-memory sliding window rate limiter.
+ *
+ * Stores an array of timestamps per key. On `check`/`record`, timestamps
+ * outside the window are pruned. `retry_after` reports seconds until the
+ * oldest active timestamp expires.
+ *
+ * Parameters that accept `RateLimiter | null` (e.g. `ip_rate_limiter`,
+ * `login_account_rate_limiter`) silently disable rate limiting when `null`
+ * is passed — no checks are performed and all requests are allowed through.
+ */
+export declare class RateLimiter {
+    #private;
+    readonly options: RateLimiterOptions;
+    constructor(options: RateLimiterOptions);
+    /** Number of tracked keys. */
+    get size(): number;
+    /**
+     * Check whether `key` is allowed without recording an attempt.
+     *
+     * @param key - rate limit key (e.g. IP address)
+     * @param now - current timestamp in ms (defaults to `Date.now()`)
+     */
+    check(key: string, now?: number): RateLimitResult;
+    /**
+     * Record a failed attempt for `key` and return the updated result.
+     *
+     * @param key - rate limit key (e.g. IP address)
+     * @param now - current timestamp in ms (defaults to `Date.now()`)
+     */
+    record(key: string, now?: number): RateLimitResult;
+    /**
+     * Clear all attempts for `key` (e.g. after successful login).
+     */
+    reset(key: string): void;
+    /**
+     * Remove entries whose timestamps are all outside the window.
+     *
+     * @param now - current timestamp in ms (defaults to `Date.now()`)
+     */
+    cleanup(now?: number): void;
+    /** Stop the cleanup timer. Safe to call multiple times. */
+    dispose(): void;
+}
+/**
+ * Create a `RateLimiter` with sensible defaults for per-IP login protection.
+ *
+ * @param options - override individual options; unset fields use `DEFAULT_LOGIN_IP_RATE_LIMIT`
+ */
+export declare const create_rate_limiter: (options?: Partial<RateLimiterOptions>) => RateLimiter;
+/**
+ * Build a 429 rate-limit-exceeded JSON response with `Retry-After` header.
+ *
+ * @param c - Hono context
+ * @param retry_after - seconds until the client should retry
+ * @returns a 429 Response
+ */
+export declare const rate_limit_exceeded_response: (c: Context, retry_after: number) => Response;
+//# sourceMappingURL=rate_limiter.d.ts.map

package/dist/rate_limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate_limiter.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/rate_limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAIlC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,mBAAmB,EAAE,MAAM,CAAC;CAC5B;AAED,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,EAAE,kBAIzC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,gCAAgC,EAAE,kBAI9C,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,WAAW;;IACvB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;gBAOzB,OAAO,EAAE,kBAAkB;IAWvC,8BAA8B;IAC9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA2B7D;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA0B9D;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;OAIG;IACH,OAAO,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI;IAYvC,2DAA2D;IAC3D,OAAO,IAAI,IAAI;CAMf;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,OAAO,CAAC,kBAAkB,CAAC,KAAG,WAE3E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,GAAG,OAAO,EAAE,aAAa,MAAM,KAAG,QAI7E,CAAC"}

package/dist/rate_limiter.js

@@ -0,0 +1,156 @@
+/**
+ * In-memory sliding window rate limiter.
+ *
+ * Tracks failed attempts per key (typically IP address) using a sliding
+ * time window. No external dependencies — state resets on server restart.
+ *
+ * @module
+ */
+import { ERROR_RATE_LIMIT_EXCEEDED } from './http/error_schemas.js';
+/** Default options for per-IP login rate limiting: 5 attempts per 15 minutes. */
+export const DEFAULT_LOGIN_IP_RATE_LIMIT = {
+    max_attempts: 5,
+    window_ms: 15 * 60_000,
+    cleanup_interval_ms: 5 * 60_000,
+};
+/** Default options for per-account login rate limiting: 10 attempts per 30 minutes. */
+export const DEFAULT_LOGIN_ACCOUNT_RATE_LIMIT = {
+    max_attempts: 10,
+    window_ms: 30 * 60_000,
+    cleanup_interval_ms: 5 * 60_000,
+};
+/**
+ * In-memory sliding window rate limiter.
+ *
+ * Stores an array of timestamps per key. On `check`/`record`, timestamps
+ * outside the window are pruned. `retry_after` reports seconds until the
+ * oldest active timestamp expires.
+ *
+ * Parameters that accept `RateLimiter | null` (e.g. `ip_rate_limiter`,
+ * `login_account_rate_limiter`) silently disable rate limiting when `null`
+ * is passed — no checks are performed and all requests are allowed through.
+ */
+export class RateLimiter {
+    options;
+    /** Key → array of attempt timestamps. */
+    #attempts = new Map();
+    #cleanup_timer = null;
+    constructor(options) {
+        this.options = options;
+        if (options.cleanup_interval_ms > 0) {
+            this.#cleanup_timer = setInterval(() => this.cleanup(), options.cleanup_interval_ms);
+            // Allow the process to exit even if the timer is still active.
+            if (typeof this.#cleanup_timer === 'object' && 'unref' in this.#cleanup_timer) {
+                this.#cleanup_timer.unref();
+            }
+        }
+    }
+    /** Number of tracked keys. */
+    get size() {
+        return this.#attempts.size;
+    }
+    /**
+     * Check whether `key` is allowed without recording an attempt.
+     *
+     * @param key - rate limit key (e.g. IP address)
+     * @param now - current timestamp in ms (defaults to `Date.now()`)
+     */
+    check(key, now = Date.now()) {
+        const { max_attempts, window_ms } = this.options;
+        const cutoff = now - window_ms;
+        const timestamps = this.#attempts.get(key);
+        if (!timestamps) {
+            return { allowed: true, remaining: max_attempts, retry_after: 0 };
+        }
+        const active = timestamps.filter((t) => t > cutoff);
+        if (active.length !== timestamps.length) {
+            if (active.length === 0) {
+                this.#attempts.delete(key);
+            }
+            else {
+                this.#attempts.set(key, active);
+            }
+        }
+        if (active.length < max_attempts) {
+            return { allowed: true, remaining: max_attempts - active.length, retry_after: 0 };
+        }
+        const oldest = active[0];
+        const retry_after = Math.ceil((oldest + window_ms - now) / 1000);
+        return { allowed: false, remaining: 0, retry_after };
+    }
+    /**
+     * Record a failed attempt for `key` and return the updated result.
+     *
+     * @param key - rate limit key (e.g. IP address)
+     * @param now - current timestamp in ms (defaults to `Date.now()`)
+     */
+    record(key, now = Date.now()) {
+        const { max_attempts, window_ms } = this.options;
+        const cutoff = now - window_ms;
+        let timestamps = this.#attempts.get(key);
+        if (timestamps) {
+            // Prune expired entries in place.
+            const active = timestamps.filter((t) => t > cutoff);
+            active.push(now);
+            this.#attempts.set(key, active);
+            timestamps = active;
+        }
+        else {
+            timestamps = [now];
+            this.#attempts.set(key, timestamps);
+        }
+        const count = timestamps.length;
+        if (count <= max_attempts) {
+            return { allowed: true, remaining: max_attempts - count, retry_after: 0 };
+        }
+        const oldest = timestamps[0];
+        const retry_after = Math.ceil((oldest + window_ms - now) / 1000);
+        return { allowed: false, remaining: 0, retry_after };
+    }
+    /**
+     * Clear all attempts for `key` (e.g. after successful login).
+     */
+    reset(key) {
+        this.#attempts.delete(key);
+    }
+    /**
+     * Remove entries whose timestamps are all outside the window.
+     *
+     * @param now - current timestamp in ms (defaults to `Date.now()`)
+     */
+    cleanup(now = Date.now()) {
+        const cutoff = now - this.options.window_ms;
+        for (const [key, timestamps] of this.#attempts) {
+            const active = timestamps.filter((t) => t > cutoff);
+            if (active.length === 0) {
+                this.#attempts.delete(key);
+            }
+            else {
+                this.#attempts.set(key, active);
+            }
+        }
+    }
+    /** Stop the cleanup timer. Safe to call multiple times. */
+    dispose() {
+        if (this.#cleanup_timer !== null) {
+            clearInterval(this.#cleanup_timer);
+            this.#cleanup_timer = null;
+        }
+    }
+}
+/**
+ * Create a `RateLimiter` with sensible defaults for per-IP login protection.
+ *
+ * @param options - override individual options; unset fields use `DEFAULT_LOGIN_IP_RATE_LIMIT`
+ */
+export const create_rate_limiter = (options) => {
+    return new RateLimiter({ ...DEFAULT_LOGIN_IP_RATE_LIMIT, ...options });
+};
+/**
+ * Build a 429 rate-limit-exceeded JSON response with `Retry-After` header.
+ *
+ * @param c - Hono context
+ * @param retry_after - seconds until the client should retry
+ * @returns a 429 Response
+ */
+export const rate_limit_exceeded_response = (c, retry_after) => c.json({ error: ERROR_RATE_LIMIT_EXCEEDED, retry_after }, { status: 429, headers: { 'Retry-After': String(Math.ceil(retry_after)) } });

package/dist/realtime/sse.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SSE (Server-Sent Events) streaming utilities for Hono.
+ *
+ * Provides generic helpers for creating SSE response streams
+ * and a notification type aligned with JSON-RPC 2.0.
+ *
+ * @module
+ */
+import type { Context } from 'hono';
+import { z } from 'zod';
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+/**
+ * Generic SSE stream controller interface.
+ *
+ * Transport-agnostic — works with any serializable type.
+ */
+export interface SseStream<T = unknown> {
+    /** Send data to the client as a JSON SSE event. */
+    send: (data: T) => void;
+    /** Send a comment (for keep-alive pings). */
+    comment: (text: string) => void;
+    /** Close the stream. */
+    close: () => void;
+    /** Register a listener called when the stream closes (client disconnect or explicit close). */
+    on_close: (fn: () => void) => void;
+}
+/**
+ * Notification shape aligned with JSON-RPC 2.0.
+ *
+ * Uses `{method, params}` to match the JSON-RPC notification format.
+ */
+export interface SseNotification {
+    /** Notification method name (e.g. 'run_created', 'host_updated'). */
+    method: string;
+    /** Method-specific payload. */
+    params: unknown;
+}
+/**
+ * Create an SSE response for a Hono context.
+ *
+ * Wraps Hono's `streamSSE` to provide a `{response, stream}` API
+ * compatible with `SubscriberRegistry` push-based broadcasting.
+ * The callback suspends via a promise that resolves on client disconnect
+ * or explicit `close()`, keeping the stream alive for external sends.
+ *
+ * Uses `hono_stream.write()` directly (not `writeSSE`) to avoid
+ * Hono's HTML callback resolution — keeps the same `data: JSON\n\n` format.
+ *
+ * @param c - Hono context
+ * @returns object with response and stream controller
+ */
+export declare const create_sse_response: <T = unknown>(c: Context, log: Logger) => {
+    response: Response;
+    stream: SseStream<T>;
+};
+/** SSE comment sent on connect to flush headers through proxies. Exported for test assertions. */
+export declare const SSE_CONNECTED_COMMENT = ": connected\n\n";
+/** Spec for an SSE event — declares params schema, description, and channel. */
+export interface SseEventSpec {
+    method: string;
+    params: z.ZodType;
+    description: string;
+    channel?: string;
+}
+/**
+ * Create a broadcaster that validates events in DEV mode.
+ *
+ * In DEV: warns on unknown methods and invalid params.
+ * In production: passes through with zero overhead.
+ *
+ * @param broadcaster - duck-typed broadcaster (e.g. `SubscriberRegistry`)
+ * @param event_specs - event specs to validate against
+ * @returns validated broadcaster wrapper (passthrough in production)
+ */
+export declare const create_validated_broadcaster: <T extends SseNotification>(broadcaster: {
+    broadcast: (channel: string, data: T) => void;
+}, event_specs: Array<SseEventSpec>, log: Logger) => {
+    broadcast: (channel: string, data: T) => void;
+};
+//# sourceMappingURL=sse.d.ts.map

package/dist/realtime/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAElC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACrC,mDAAmD;IACnD,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IACxB,6CAA6C;IAC7C,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,wBAAwB;IACxB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,+FAA+F;IAC/F,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,GAAG,OAAO,EAC9C,GAAG,OAAO,EACV,KAAK,MAAM,KACT;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CAiD3C,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,SAAS,eAAe,EACrE,aAAa;IAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAAC,EAC5D,aAAa,KAAK,CAAC,YAAY,CAAC,EAChC,KAAK,MAAM,KACT;IAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAmBhD,CAAC"}