@fuzdev/fuz_app 0.1.0

package/dist/http/proxy.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Trusted proxy configuration and middleware.
+ *
+ * Resolves the client IP from `X-Forwarded-For` only when the TCP connection
+ * originates from a configured trusted proxy. Without this middleware,
+ * `get_client_ip` returns `'unknown'`.
+ *
+ * @module
+ */
+import type { Context, MiddlewareHandler } from 'hono';
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { MiddlewareSpec } from './middleware_spec.js';
+/**
+ * Normalize an IP address for consistent matching and storage.
+ *
+ * - Strips `::ffff:` prefix from IPv4-mapped IPv6 addresses
+ *   (e.g. `::ffff:127.0.0.1` → `127.0.0.1`)
+ * - Lowercases for case-insensitive IPv6 comparison
+ * - Idempotent: calling twice produces the same result
+ * - Safe on non-IP strings: `normalize_ip('unknown')` returns `'unknown'`
+ *
+ * @param ip - IP address string to normalize
+ */
+export declare const normalize_ip: (ip: string) => string;
+/**
+ * Configuration for trusted proxy resolution.
+ */
+export interface ProxyOptions {
+    /** Trusted proxy IPs or CIDR ranges (e.g. `'127.0.0.1'`, `'10.0.0.0/8'`, `'::1'`). */
+    trusted_proxies: Array<string>;
+    /** Extract the raw TCP connection IP from the Hono context. */
+    get_connection_ip: (c: Context) => string | undefined;
+    /** Optional logger for proxy resolution diagnostics. */
+    log?: Logger;
+}
+/**
+ * A parsed proxy entry — either an exact IP or a CIDR range.
+ */
+export type ParsedProxy = {
+    type: 'ip';
+    address: string;
+} | {
+    type: 'cidr';
+    network: bigint;
+    prefix: number;
+    address_type: 'IPv4' | 'IPv6';
+};
+/**
+ * Parse a trusted proxy entry string into a structured form.
+ *
+ * Accepts plain IPs (`'127.0.0.1'`, `'::1'`) and CIDR notation (`'10.0.0.0/8'`, `'fe80::/10'`).
+ * Plain IPs are normalized (lowercase, IPv4-mapped IPv6 stripped) and validated.
+ * CIDR prefixes are validated against address family bounds.
+ *
+ * @param entry - IP address or CIDR notation
+ * @throws on invalid IP, invalid CIDR network, or NaN/negative/over-range prefix
+ */
+export declare const parse_proxy_entry: (entry: string) => ParsedProxy;
+/**
+ * Check whether `ip` matches any entry in the trusted proxy list.
+ *
+ * Normalizes `ip` before matching (lowercase, IPv4-mapped IPv6 stripped).
+ *
+ * @param ip - the IP address to check
+ * @param proxies - parsed proxy entries
+ */
+export declare const is_trusted_ip: (ip: string, proxies: Array<ParsedProxy>) => boolean;
+/**
+ * Resolve the real client IP from an `X-Forwarded-For` header value.
+ *
+ * Walks right-to-left, skipping trusted proxy entries. The first
+ * non-trusted entry is the client IP. If all entries are trusted,
+ * returns the leftmost entry. All entries are normalized before
+ * matching and in the returned value.
+ *
+ * @param forwarded_for - the `X-Forwarded-For` header value
+ * @param proxies - parsed trusted proxy entries
+ * @returns the normalized client IP, or `undefined` if the header is empty
+ */
+export declare const resolve_client_ip: (forwarded_for: string, proxies: Array<ParsedProxy>) => string | undefined;
+/**
+ * Create a Hono middleware that resolves the client IP from trusted proxies.
+ *
+ * Sets `client_ip` on the Hono context for downstream use by `get_client_ip`.
+ * All client IPs are normalized (lowercase, IPv4-mapped IPv6 stripped).
+ *
+ * Resolution logic:
+ * 1. No `X-Forwarded-For` → use connection IP directly.
+ * 2. `X-Forwarded-For` present but connection is untrusted → ignore header
+ *    (spoofed by a direct attacker), use connection IP.
+ * 3. `X-Forwarded-For` present and connection is trusted → walk header
+ *    right-to-left, strip trusted entries, use first untrusted entry.
+ *
+ * @param options - trusted proxy configuration
+ */
+export declare const create_proxy_middleware: (options: ProxyOptions) => MiddlewareHandler;
+/**
+ * Create a middleware spec for trusted proxy resolution.
+ *
+ * Apply before auth middleware so `client_ip` is available for rate limiting.
+ *
+ * @param options - trusted proxy configuration
+ */
+export declare const create_proxy_middleware_spec: (options: ProxyOptions) => MiddlewareSpec;
+/**
+ * Read the resolved client IP from the Hono context.
+ *
+ * Returns `'unknown'` if the proxy middleware has not run or no IP is available.
+ * Set by `create_proxy_middleware`.
+ */
+export declare const get_client_ip: (c: Context) => string;
+//# sourceMappingURL=proxy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAErD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,KAAG,MAQzC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,sFAAsF;IACtF,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,iBAAiB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACpB;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAC7B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;CAAC,CAAC;AAElF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,WA6CjD,CAAC;AAiBF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,EAAE,SAAS,KAAK,CAAC,WAAW,CAAC,KAAG,OAqBvE,CAAC;AAQF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAC7B,eAAe,MAAM,EACrB,SAAS,KAAK,CAAC,WAAW,CAAC,KACzB,MAAM,GAAG,SAiBX,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,YAAY,KAAG,iBAyC/D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,YAAY,KAAG,cAInE,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,OAAO,KAAG,MAAyC,CAAC"}

package/dist/http/proxy.js

@@ -0,0 +1,240 @@
+/**
+ * Trusted proxy configuration and middleware.
+ *
+ * Resolves the client IP from `X-Forwarded-For` only when the TCP connection
+ * originates from a configured trusted proxy. Without this middleware,
+ * `get_client_ip` returns `'unknown'`.
+ *
+ * @module
+ */
+import { convertIPv4ToBinary, convertIPv6ToBinary, distinctRemoteAddr } from 'hono/utils/ipaddr';
+/**
+ * Normalize an IP address for consistent matching and storage.
+ *
+ * - Strips `::ffff:` prefix from IPv4-mapped IPv6 addresses
+ *   (e.g. `::ffff:127.0.0.1` → `127.0.0.1`)
+ * - Lowercases for case-insensitive IPv6 comparison
+ * - Idempotent: calling twice produces the same result
+ * - Safe on non-IP strings: `normalize_ip('unknown')` returns `'unknown'`
+ *
+ * @param ip - IP address string to normalize
+ */
+export const normalize_ip = (ip) => {
+    const lowered = ip.toLowerCase();
+    // Strip ::ffff: prefix only when remainder contains a dot (IPv4-mapped IPv6).
+    // This distinguishes ::ffff:127.0.0.1 (IPv4-mapped) from ::ffff:1 (pure IPv6).
+    if (lowered.startsWith('::ffff:') && lowered.substring(7).includes('.')) {
+        return lowered.substring(7);
+    }
+    return lowered;
+};
+/**
+ * Parse a trusted proxy entry string into a structured form.
+ *
+ * Accepts plain IPs (`'127.0.0.1'`, `'::1'`) and CIDR notation (`'10.0.0.0/8'`, `'fe80::/10'`).
+ * Plain IPs are normalized (lowercase, IPv4-mapped IPv6 stripped) and validated.
+ * CIDR prefixes are validated against address family bounds.
+ *
+ * @param entry - IP address or CIDR notation
+ * @throws on invalid IP, invalid CIDR network, or NaN/negative/over-range prefix
+ */
+export const parse_proxy_entry = (entry) => {
+    const slash_index = entry.indexOf('/');
+    if (slash_index === -1) {
+        const normalized = normalize_ip(entry);
+        if (!distinctRemoteAddr(normalized)) {
+            throw new Error(`Invalid proxy IP: ${entry}`);
+        }
+        return { type: 'ip', address: normalized };
+    }
+    const network_str = entry.substring(0, slash_index);
+    const prefix_str = entry.substring(slash_index + 1);
+    const prefix = parseInt(prefix_str, 10);
+    if (Number.isNaN(prefix)) {
+        throw new Error(`Invalid CIDR prefix (not a number): ${entry}`);
+    }
+    if (prefix < 0) {
+        throw new Error(`Invalid CIDR prefix (negative): ${entry}`);
+    }
+    if (String(prefix) !== prefix_str) {
+        throw new Error(`Invalid CIDR prefix (not an integer): ${entry}`);
+    }
+    const address_type = distinctRemoteAddr(network_str);
+    if (address_type === 'IPv4') {
+        if (prefix > 32) {
+            throw new Error(`Invalid CIDR prefix for IPv4 (max 32): ${entry}`);
+        }
+        const network = convertIPv4ToBinary(network_str);
+        const host_mask = prefix === 32 ? 0n : (1n << BigInt(32 - prefix)) - 1n;
+        if ((network & host_mask) !== 0n) {
+            throw new Error(`Non-network-aligned CIDR (host bits set): ${entry}`);
+        }
+        return { type: 'cidr', network, prefix, address_type };
+    }
+    if (address_type === 'IPv6') {
+        if (prefix > 128) {
+            throw new Error(`Invalid CIDR prefix for IPv6 (max 128): ${entry}`);
+        }
+        const network = convertIPv6ToBinary(network_str);
+        const host_mask = prefix === 128 ? 0n : (1n << BigInt(128 - prefix)) - 1n;
+        if ((network & host_mask) !== 0n) {
+            throw new Error(`Non-network-aligned CIDR (host bits set): ${entry}`);
+        }
+        return { type: 'cidr', network, prefix, address_type };
+    }
+    throw new Error(`Invalid proxy CIDR: ${entry}`);
+};
+/**
+ * Check whether an IP falls within a CIDR range.
+ *
+ * Compares the top `prefix` bits by right-shifting both values.
+ */
+const cidr_contains = (ip_binary, network, prefix, total_bits) => {
+    const shift = BigInt(total_bits - prefix);
+    return ip_binary >> shift === network >> shift;
+};
+/**
+ * Check whether `ip` matches any entry in the trusted proxy list.
+ *
+ * Normalizes `ip` before matching (lowercase, IPv4-mapped IPv6 stripped).
+ *
+ * @param ip - the IP address to check
+ * @param proxies - parsed proxy entries
+ */
+export const is_trusted_ip = (ip, proxies) => {
+    const normalized = normalize_ip(ip);
+    const address_type = distinctRemoteAddr(normalized);
+    if (!address_type)
+        return false;
+    for (const proxy of proxies) {
+        if (proxy.type === 'ip') {
+            if (proxy.address === normalized)
+                return true;
+            continue;
+        }
+        // CIDR match — skip mismatched address families
+        if (proxy.address_type !== address_type)
+            continue;
+        if (address_type === 'IPv4') {
+            if (cidr_contains(convertIPv4ToBinary(normalized), proxy.network, proxy.prefix, 32))
+                return true;
+        }
+        else {
+            if (cidr_contains(convertIPv6ToBinary(normalized), proxy.network, proxy.prefix, 128))
+                return true;
+        }
+    }
+    return false;
+};
+// NOTE: some non-standard proxies include ports in XFF entries (e.g.
+// 203.0.113.1:8080). The entry fails distinctRemoteAddr and is treated as
+// untrusted (safe default), but rate limiting keys on the port-suffixed
+// string instead of the bare IP. Low risk — nginx and cloud LBs don't
+// include ports.
+/**
+ * Resolve the real client IP from an `X-Forwarded-For` header value.
+ *
+ * Walks right-to-left, skipping trusted proxy entries. The first
+ * non-trusted entry is the client IP. If all entries are trusted,
+ * returns the leftmost entry. All entries are normalized before
+ * matching and in the returned value.
+ *
+ * @param forwarded_for - the `X-Forwarded-For` header value
+ * @param proxies - parsed trusted proxy entries
+ * @returns the normalized client IP, or `undefined` if the header is empty
+ */
+export const resolve_client_ip = (forwarded_for, proxies) => {
+    const entries = [];
+    for (const raw of forwarded_for.split(',')) {
+        const trimmed = raw.trim();
+        if (trimmed)
+            entries.push(normalize_ip(trimmed));
+    }
+    if (entries.length === 0)
+        return undefined;
+    // Walk from right to left, skip trusted proxies
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (!is_trusted_ip(entry, proxies)) {
+            return entry;
+        }
+    }
+    // All entries are trusted — return leftmost (edge case, likely misconfigured)
+    return entries[0];
+};
+/**
+ * Create a Hono middleware that resolves the client IP from trusted proxies.
+ *
+ * Sets `client_ip` on the Hono context for downstream use by `get_client_ip`.
+ * All client IPs are normalized (lowercase, IPv4-mapped IPv6 stripped).
+ *
+ * Resolution logic:
+ * 1. No `X-Forwarded-For` → use connection IP directly.
+ * 2. `X-Forwarded-For` present but connection is untrusted → ignore header
+ *    (spoofed by a direct attacker), use connection IP.
+ * 3. `X-Forwarded-For` present and connection is trusted → walk header
+ *    right-to-left, strip trusted entries, use first untrusted entry.
+ *
+ * @param options - trusted proxy configuration
+ */
+export const create_proxy_middleware = (options) => {
+    const parsed_proxies = options.trusted_proxies.map(parse_proxy_entry);
+    const { log } = options;
+    return async (c, next) => {
+        const connection_ip = options.get_connection_ip(c);
+        const forwarded_for = c.req.header('x-forwarded-for');
+        let client_ip;
+        if (!forwarded_for) {
+            // No proxy header — use connection IP directly
+            client_ip = connection_ip ? normalize_ip(connection_ip) : 'unknown';
+            if (!connection_ip) {
+                log?.warn('Connection IP is undefined — client_ip set to unknown');
+            }
+        }
+        else if (!connection_ip || !is_trusted_ip(connection_ip, parsed_proxies)) {
+            // Header present but connection is untrusted — ignore spoofed header
+            client_ip = connection_ip ? normalize_ip(connection_ip) : 'unknown';
+            if (connection_ip) {
+                log?.debug('XFF ignored — connection from untrusted IP:', connection_ip);
+            }
+            else {
+                log?.warn('Connection IP is undefined with XFF present — client_ip set to unknown');
+            }
+        }
+        else {
+            // Connection from a trusted proxy — resolve from header
+            const resolved = resolve_client_ip(forwarded_for, parsed_proxies);
+            if (!resolved) {
+                client_ip = normalize_ip(connection_ip);
+            }
+            else {
+                client_ip = resolved;
+                // all XFF entries were trusted — likely misconfiguration
+                if (is_trusted_ip(resolved, parsed_proxies)) {
+                    log?.warn('All XFF entries are trusted — possible misconfiguration:', forwarded_for);
+                }
+            }
+        }
+        c.set('client_ip', client_ip);
+        await next();
+    };
+};
+/**
+ * Create a middleware spec for trusted proxy resolution.
+ *
+ * Apply before auth middleware so `client_ip` is available for rate limiting.
+ *
+ * @param options - trusted proxy configuration
+ */
+export const create_proxy_middleware_spec = (options) => ({
+    name: 'trusted_proxy',
+    path: '*',
+    handler: create_proxy_middleware(options),
+});
+/**
+ * Read the resolved client IP from the Hono context.
+ *
+ * Returns `'unknown'` if the proxy middleware has not run or no IP is available.
+ * Set by `create_proxy_middleware`.
+ */
+export const get_client_ip = (c) => c.get('client_ip') || 'unknown';

package/dist/http/route_spec.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Introspectable route spec system for Hono apps.
+ *
+ * Routes are defined as data (method, path, auth, input/output schemas, handler),
+ * then applied to Hono. The attack surface is generated from the specs —
+ * always accurate, always complete.
+ *
+ * Input/output schemas align with SAES `ActionSpec` conventions:
+ * - `input`: Zod schema for the request body (`z.null()` for no body)
+ * - `output`: Zod schema for the success response body
+ * - `z.strictObject()` for inputs (reject unknown keys)
+ *
+ * @module
+ */
+import type { Context, Hono, MiddlewareHandler } from 'hono';
+import type { z } from 'zod';
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { Db } from '../db/db.js';
+import { type RouteErrorSchemas, type RateLimitKey } from './error_schemas.js';
+import type { MiddlewareSpec } from './middleware_spec.js';
+/**
+ * Auth requirement for a route — `none`, `authenticated`, a specific role, or `keeper`.
+ *
+ * `{type: 'none'}` means the route is open to all clients — including non-browser
+ * callers (CLI, API tokens, scripts). No session or auth middleware guards are applied.
+ */
+export type RouteAuth = {
+    type: 'none';
+} | {
+    type: 'authenticated';
+} | {
+    type: 'role';
+    role: string;
+} | {
+    type: 'keeper';
+};
+/**
+ * Resolves a `RouteAuth` to middleware guard handlers.
+ *
+ * Injected into `apply_route_specs` to decouple route registration
+ * from auth-specific middleware. See `fuz_auth_guard_resolver` in
+ * `auth/route_guards.ts` for the standard implementation.
+ */
+export type AuthGuardResolver = (auth: RouteAuth) => Array<MiddlewareHandler>;
+/** HTTP methods supported by route specs. */
+export type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/**
+ * Per-request deps provided by the framework to route handlers.
+ *
+ * `db` is transaction-scoped for mutation routes and pool-level for reads.
+ * `background_db` is always pool-level — use it for fire-and-forget effects
+ * that must outlive the transaction.
+ */
+export interface RouteContext {
+    /** Transaction-scoped for mutations, pool-level for reads. */
+    db: Db;
+    /** Always pool-level — for fire-and-forget effects that outlive the transaction. */
+    background_db: Db;
+    /** Fire-and-forget side effects — push here for post-response flushing. */
+    pending_effects: Array<Promise<void>>;
+}
+/**
+ * Route handler function — receives the Hono context and a `RouteContext`
+ * with per-request deps (db, background_db, pending_effects).
+ *
+ * TypeScript allows fewer params, so handlers that don't need `route`
+ * can use `(c) => ...` without changes.
+ */
+export type RouteHandler = (c: Context, route: RouteContext) => Response | Promise<Response>;
+/**
+ * A single route definition — the unit of the surface map.
+ *
+ * `input` and `output` schemas align with SAES `ActionSpec` naming.
+ * Use `z.null()` for routes with no request body (GET, DELETE without body).
+ */
+export interface RouteSpec {
+    method: RouteMethod;
+    path: string;
+    /**
+     * Auth requirement for this route.
+     *
+     * `{type: 'none'}` means the route is open to all clients including non-browser
+     * callers (CLI, scripts) — no auth guards are applied.
+     */
+    auth: RouteAuth;
+    handler: RouteHandler;
+    description: string;
+    /**
+     * URL path parameter schema. Use `z.strictObject()` with string fields matching `:param` segments.
+     *
+     * TODO @action-system-review `params` is HTTP-specific — SAES encodes everything in
+     * `input`. When saes-rpc lands, this may move to `ActionRouteOptions` only.
+     */
+    params?: z.ZodObject;
+    /** URL query parameter schema. Use `z.strictObject()` with string fields. */
+    query?: z.ZodObject;
+    /** Request body schema. Use `z.null()` for routes with no body. */
+    input: z.ZodType;
+    /** Success response body schema. */
+    output: z.ZodType;
+    /**
+     * Rate limit key type — declares what this route's rate limiter is keyed on.
+     *
+     * When set, 429 (`RateLimitError`) is auto-derived in `derive_error_schemas`.
+     * The actual `RateLimiter` instance is still wired imperatively in the handler —
+     * this field is metadata for surface introspection and policy invariants.
+     */
+    rate_limit?: RateLimitKey;
+    /**
+     * Handler-specific error response schemas keyed by HTTP status code.
+     *
+     * Middleware errors (auth 401/403, validation 400, rate limit 429) are
+     * auto-derived from `auth`, `input`, and `rate_limit`. Declare handler-specific
+     * errors here (e.g., 404 for not-found, 409 for conflicts).
+     *
+     * Explicit entries override auto-derived ones for the same status code.
+     */
+    errors?: RouteErrorSchemas;
+    /**
+     * Whether to wrap the handler in a database transaction.
+     *
+     * When omitted, defaults are derived from the HTTP method:
+     * - `GET` → `false` (read-only, no transaction)
+     * - All others (`POST`, `PUT`, `DELETE`, `PATCH`) → `true`
+     *
+     * Set explicitly to override the default (e.g., `false` for a POST
+     * that manages its own transaction like signup).
+     */
+    transaction?: boolean;
+}
+/**
+ * Get validated input from the Hono context.
+ *
+ * Call this in route handlers after the input validation middleware has run.
+ * The type parameter should match the route's `input` schema.
+ *
+ * @returns the validated request body
+ */
+export declare const get_route_input: <T>(c: Context) => T;
+/**
+ * Get validated URL path params from the Hono context.
+ *
+ * Call this in route handlers after the params validation middleware has run.
+ * The type parameter should match the route's `params` schema.
+ *
+ * TODO @action-system-review Make typesafe — derive `T` from the `params` schema on the
+ * route spec so the type parameter isn't manually specified.
+ *
+ * @returns the validated path parameters
+ */
+export declare const get_route_params: <T>(c: Context) => T;
+/**
+ * Get validated URL query params from the Hono context.
+ *
+ * Call this in route handlers after the query validation middleware has run.
+ * The type parameter should match the route's `query` schema.
+ *
+ * @returns the validated query parameters
+ */
+export declare const get_route_query: <T>(c: Context) => T;
+/**
+ * Apply named middleware specs to a Hono app.
+ *
+ * @param app - the Hono app
+ * @param specs - middleware specs to apply
+ * @mutates `app`
+ */
+export declare const apply_middleware_specs: (app: Hono, specs: Array<MiddlewareSpec>) => void;
+/**
+ * Apply route specs to a Hono app.
+ *
+ * For each spec: resolves auth to guards via the provided resolver,
+ * adds input validation middleware (for routes with non-null input schemas),
+ * wraps handler with DEV-only output and error validation, and registers the route.
+ *
+ * Each handler receives a `RouteContext` with:
+ * - `db`: transaction-scoped (for non-GET) or pool-level (for GET)
+ * - `background_db`: always pool-level
+ * - `pending_effects`: fire-and-forget effect queue
+ *
+ * @param app - the Hono app
+ * @param specs - route specs to apply
+ * @param resolve_auth_guards - maps `RouteAuth` to middleware — use `fuz_auth_guard_resolver` from `auth/route_guards.ts`
+ * @param log - the logger instance
+ * @param db - database instance for transaction wrapping and `RouteContext`
+ * @mutates `app`
+ */
+export declare const apply_route_specs: (app: Hono, specs: Array<RouteSpec>, resolve_auth_guards: AuthGuardResolver, log: Logger, db: Db) => void;
+/**
+ * Prepend a prefix to all route spec paths.
+ *
+ * @param prefix - the path prefix (e.g. `/api/account`)
+ * @param specs - route specs to prefix
+ * @returns new array of specs with prefixed paths
+ */
+export declare const prefix_route_specs: (prefix: string, specs: Array<RouteSpec>) => Array<RouteSpec>;
+//# sourceMappingURL=route_spec.d.ts.map

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

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