@spfn/core 0.2.0-beta.9 → 0.3.0-beta.10

package/dist/middleware/index.d.ts

@@ -1,10 +1,6 @@
-import { Context, Next } from 'hono';
-
-/**
- * Error Handler Middleware
- *
- * Handles SerializableError with automatic serialization and standard errors
- */
+import { Context, Next, MiddlewareHandler } from 'hono';
+import { N as NamedMiddlewareFactory, a as NamedMiddleware } from '../define-middleware-CVKgqo8S.js';
+import { Redis, Cluster } from 'ioredis';
 
 /**
  * Options for ErrorHandler middleware
@@ -26,6 +22,43 @@ interface ErrorHandlerOptions {
      * @default true
      */
     enableLogging?: boolean;
+    /**
+     * Attach the `error` envelope to every error response
+     *
+     * The envelope is `{ code, message, requestId }` sitting next to the
+     * existing `__type` and `message` fields, never replacing them: a web
+     * client restores its error class from `__type` while a generated client
+     * in another language classifies by `code` alone and cannot read a
+     * discriminator it has no registry for.
+     *
+     * Turn it off only to keep error bodies byte-identical to an older
+     * release. A route reached by a generated client needs it.
+     *
+     * @default true
+     */
+    errorEnvelope?: boolean;
+    /**
+     * Callback invoked when an error occurs
+     *
+     * Called asynchronously without blocking the response.
+     * Useful for external error notifications (Slack, PagerDuty, etc.)
+     */
+    onError?: (err: Error, context: OnErrorContext) => Promise<void> | void;
+}
+/**
+ * Context passed to onError callback
+ */
+interface OnErrorContext {
+    statusCode: number;
+    path: string;
+    method: string;
+    requestId?: string;
+    timestamp: string;
+    userId?: string;
+    request: {
+        headers: Record<string, string>;
+        query: Record<string, string>;
+    };
 }
 /**
  * Error handler middleware for Hono
@@ -34,6 +67,10 @@ interface ErrorHandlerOptions {
  * SerializableError instances are serialized using their toJSON() method,
  * preserving custom fields like `resource`, `fields`, etc.
  *
+ * Every response also carries an `error` envelope — `{ code, message,
+ * requestId }` — for clients that classify by a single documented field
+ * instead of restoring an error class from `__type`.
+ *
  * @param options - Configuration options
  * @returns Error handler function for Hono's onError hook
  *
@@ -53,7 +90,8 @@ interface ErrorHandlerOptions {
  * // Throw SerializableError in routes
  * app.get('/users/:id', (c) => {
  *     throw new NotFoundError({ message: 'User not found', resource: 'User' });
- *     // Response: { __type: 'NotFoundError', message: 'User not found', resource: 'User' }
+ *     // Response: { __type: 'NotFoundError', message: 'User not found', resource: 'User',
+ *     //             error: { code: 'NotFoundError', message: 'User not found', requestId: '…' } }
  * });
  * ```
  */
@@ -68,7 +106,11 @@ interface RequestLoggerOptions {
      *
      * Supports exact match and prefix match (e.g., '/health' excludes '/health/db').
      *
-     * @default ['/health', '/ping', '/favicon.ico']
+     * `/_core/health` is where the built-in health endpoint always answers, so a
+     * readiness probe usually points there rather than at `/health`. Leaving it
+     * out of the default fills the log with one line per probe interval.
+     *
+     * @default ['/_core/health', '/health', '/ping', '/favicon.ico']
      *
      * @example
      * ```typescript
@@ -139,4 +181,304 @@ declare function maskSensitiveData(obj: any, sensitiveFields: string[], seen?: W
  */
 declare function RequestLogger(options?: RequestLoggerOptions): (c: Context, next: Next) => Promise<void>;
 
-export { ErrorHandler, type ErrorHandlerOptions, RequestLogger, type RequestLoggerConfig, type RequestLoggerOptions, maskSensitiveData };
+/**
+ * Proxy-guard middleware
+ *
+ * Verifies that an inbound request came through a trusted Next.js RPC proxy
+ * (HMAC signature) and/or from an allowed browser origin, then tags the request
+ * with a `clientType`. Lets the backend reject direct-to-backend calls that
+ * bypass the proxy.
+ *
+ * This does NOT replace user authentication (JWT) — it answers "what kind of
+ * client is this?", not "who is the user?". It also cannot stop a client from
+ * calling the proxy itself; that is the web's inherent limit (see
+ * PROXY-BACKEND-AUTH-SPEC.md). Mobile clients call the backend directly and are
+ * handled by a future attestation path, OR'd into this same check.
+ *
+ * @module middleware/proxy-guard
+ */
+
+/**
+ * How the request reached the backend.
+ * - `web`: verified via a trusted proxy signature
+ * - `untrusted`: could not be verified (only reached handlers in `tag` mode)
+ * - future: `ios` | `android` once attestation lands
+ */
+type ClientType = 'web' | 'untrusted' | (string & {});
+/**
+ * Enforcement mode.
+ * - `off`: middleware is a no-op (default — keeps existing apps working).
+ * - `tag`: verify and set `clientType`, but never reject (observe first).
+ * - `strict`: reject requests that fail verification.
+ */
+type ProxyGuardMode = 'off' | 'tag' | 'strict';
+/**
+ * Optional replay store. Returns `true` when the nonce is fresh (and records it),
+ * `false` when it has been seen before. Backed by Redis in multi-instance setups.
+ */
+interface NonceStore {
+    checkAndSet(nonce: string, ttlMs: number): Promise<boolean>;
+}
+interface ProxyGuardConfig {
+    /**
+     * Active shared HMAC secret, as `<keyId>:<secret>` (or a bare secret).
+     * Defaults to `env.SPFN_PROXY_SECRET`. Without it (and no previous keys),
+     * signatures cannot be verified and every request is tagged `untrusted`.
+     */
+    secret?: string;
+    /**
+     * Previous (grace) keys still accepted for verification during rotation, as a
+     * comma-separated list of `<keyId>:<secret>`. The proxy never signs with
+     * these — they exist only so in-flight requests signed with the prior key
+     * keep verifying until the rollout settles. Defaults to
+     * `env.SPFN_PROXY_SECRET_PREVIOUS`. Backend-only, so it can live in
+     * `.env.server` (never exposed to the Next.js process).
+     */
+    previousSecrets?: string;
+    /** Enforcement mode. @default 'off' */
+    mode?: ProxyGuardMode;
+    /** Allowed clock skew / replay window in ms. @default 30000 */
+    windowMs?: number;
+    /**
+     * Browser origin allowlist. When set, a request carrying an `Origin` header
+     * not in this list is rejected (strict) / tagged (tag). Requests without an
+     * `Origin` (server-to-server, mobile) skip this check and fall back to the
+     * signature.
+     */
+    allowedOrigins?: string[];
+    /** Optional nonce store for hard replay rejection. Redis (multi-instance) or in-memory (single). */
+    nonceStore?: NonceStore;
+    /**
+     * When the nonce store throws (e.g. Redis down), reject the request instead of
+     * falling back to the timestamp window. Trades availability for strictness.
+     * @default false (fall back to the timestamp window)
+     */
+    nonceFailClosed?: boolean;
+    /** Paths to skip entirely (e.g. health checks). */
+    skipPaths?: string[];
+    /**
+     * Reject (413) once the streamed body exceeds this many bytes. Measured AS IT
+     * STREAMS — Content-Length is NOT trusted, so a missing/chunked/under-reported
+     * length can't bypass it. Bounds the per-request memory the guard buffers.
+     * Undefined = no cap (default). Multipart is exempt (unsigned).
+     */
+    maxBodyBytes?: number;
+}
+declare module 'hono' {
+    interface ContextVariableMap {
+        clientType?: ClientType;
+    }
+}
+/**
+ * Create the proxy-guard middleware.
+ *
+ * @example
+ * ```typescript
+ * export default defineServerConfig()
+ *     .proxyGuard({ mode: 'strict', allowedOrigins: ['https://app.example.com'] })
+ *     .routes(appRouter)
+ *     .build();
+ * ```
+ */
+declare function createProxyGuard(config?: ProxyGuardConfig): MiddlewareHandler;
+/** Minimal cache client (compatible with ioredis Redis | Cluster). */
+type CacheClient = {
+    set(key: string, value: string, ...args: any[]): Promise<any>;
+};
+/**
+ * Build a Redis-backed nonce store for hard replay rejection.
+ *
+ * Uses `SET key 1 PX ttl NX` — an atomic "set if absent". A fresh nonce returns
+ * 'OK'; a replayed one returns null. TTL keeps the key set bounded (only nonces
+ * within the replay window matter).
+ */
+declare function createCacheNonceStore(cache: CacheClient, prefix?: string): NonceStore;
+/**
+ * In-process nonce store for hard replay rejection without Redis.
+ *
+ * Good enough for a single instance — each process only knows its own nonces, so
+ * across multiple instances a replay routed to a different pod isn't caught. Use a
+ * cache-backed store (createCacheNonceStore) for multi-instance hard rejection.
+ * Entries self-expire after their TTL; the map is swept opportunistically so it
+ * stays bounded by the request rate within the replay window.
+ */
+declare function createInMemoryNonceStore(): NonceStore;
+
+/** Test seam: forget every process-local window. */
+declare function resetMemoryRateLimitStore(): void;
+/**
+ * One identity dimension to limit on. A bare string uses the top-level `limit`;
+ * an object can carry its own `limit` so dimensions can differ (e.g. a loose
+ * per-IP cap alongside a tight per-account cap).
+ */
+type RateLimitDimension = string | {
+    key: string;
+    limit?: number;
+};
+interface RateLimitOptions {
+    /** Max requests allowed per window, applied to each dimension without its own `limit`. */
+    limit: number;
+    /** Window length in milliseconds. */
+    windowMs: number;
+    /**
+     * Namespace for the counter keys. Defaults to `${method} ${routePath}` so
+     * each route is limited independently.
+     */
+    scope?: string;
+    /**
+     * Identity dimensions to limit on. Each non-empty value is counted
+     * separately and the strictest wins (e.g. by IP and by account). A dimension
+     * may override the top-level `limit` via `{ key, limit }`. Defaults to the
+     * client IP only.
+     */
+    by?: (c: Context) => (RateLimitDimension | null | undefined)[] | Promise<(RateLimitDimension | null | undefined)[]>;
+    /**
+     * Refuse with 429 when the shared cache is unavailable, instead of counting
+     * in this process. For a surface where a per-process count is not an
+     * acceptable substitute for a shared one.
+     */
+    failClosed?: boolean;
+    /** Message for the 429 response. */
+    message?: string;
+}
+/**
+ * Best-effort client IP for rate-limit keying.
+ *
+ * Prefers the proxy-forwarded real client IP, but ONLY when proxy-guard verified
+ * the request came through our proxy (`clientType` set and not 'untrusted') — on a
+ * verified request the proxy is the sole hop, so the value is the true client and
+ * isn't client-spoofable. Otherwise (no proxy-guard, or unverified/direct request)
+ * the forwarded header is attacker-settable, so fall back to the raw chain — whose
+ * leftmost hop is itself spoofable, so still pair with an account/target dimension
+ * for anything security-sensitive.
+ *
+ * Last resort before giving up is the TCP peer address from the Node adapter
+ * socket. Without it, a deployment that sets no forwarding header would collapse
+ * every client onto a single `'unknown'` bucket.
+ */
+declare function getClientIp(c: Context): string;
+/**
+ * Fixed-window rate limiter — counters in the shared cache when there is one,
+ * in this process otherwise.
+ *
+ * @example
+ * ```typescript
+ * route.post('/_auth/login')
+ *     .use([rateLimit({ limit: 10, windowMs: 60_000 })])
+ *     .handler(...);
+ * ```
+ */
+declare const rateLimit: NamedMiddlewareFactory<"rateLimit", [options: RateLimitOptions]>;
+/** Set the fail-closed default for named policies. Called by the server at boot. */
+declare function setRateLimitFailClosedDefault(failClosed: boolean): void;
+/**
+ * Replace the named-policy registry. Called by the server at boot; passing
+ * undefined clears it (so a restart without policies doesn't keep stale ones).
+ */
+declare function setRateLimitPolicies(policies?: Record<string, RateLimitOptions>): void;
+/** Look up a configured policy by name — undefined when the app didn't set it. */
+declare function getRateLimitPolicy(name: string): RateLimitOptions | undefined;
+/**
+ * Rate-limit a route under a named policy.
+ *
+ * A package author tags a sensitive route with a policy name plus a safe
+ * fallback; the consuming app tunes the numbers centrally via
+ * `defineServerConfig().rateLimit({ policies: { [name]: {...} } })`. When the
+ * app configures the policy, its fields override the fallback (shallow merge);
+ * otherwise the fallback applies, so the route is protected out of the box.
+ *
+ * LAYERS on top of the global default limiter rather than replacing it: the tag
+ * has a distinct name (`rateLimit:<name>`) and does not skip the global, so a
+ * route gets both the global per-IP floor (when enabled) and this policy's own
+ * bucket — whichever is stricter trips first. Opt out of the global floor on a
+ * route with `.skip(['rateLimit'])`.
+ *
+ * The counter scope defaults to the policy name, so (a) every route sharing a
+ * policy shares one bucket, and (b) the key never collides with the global
+ * default's per-route `${method} ${path}` scope.
+ *
+ * @example
+ * ```typescript
+ * route.post('/_auth/login')
+ *     .use([rateLimitPolicy('auth-login', { limit: 5, windowMs: 60_000 })])
+ *     .handler(...);
+ * ```
+ */
+declare function rateLimitPolicy(name: string, fallback: RateLimitOptions): NamedMiddleware<string>;
+
+/**
+ * The rate limiter's fixed-window counter as a pluggable store — the same
+ * pattern the clientProofV1 replay ledger and the SSE token manager already
+ * use: an in-memory default, a Redis/Valkey store on top of `getCache()`, and
+ * the cache's presence deciding which one a request gets.
+ *
+ * Why the memory default exists: without it, "no cache configured" and "cache
+ * down" both meant the limiter had nowhere to count, so the only choices were
+ * letting every request through or refusing every request. Neither is what a
+ * limiter is for. Counting in the process is worse than counting in Redis and
+ * far better than not counting.
+ *
+ * What the memory store cannot do is span processes. Behind N instances each
+ * keeps its own counters, so the effective limit is N times the configured one.
+ * That is the cost of the fallback and the reason a real deployment still
+ * points `CACHE_URL` at Redis.
+ *
+ * @module middleware/rate-limit-store
+ */
+
+/** One window's state for a key: how many hits, and how long the window has left. */
+interface RateLimitHit {
+    count: number;
+    /** Milliseconds until the window resets. */
+    pttl: number;
+}
+/** What the limiter needs from wherever the counters live. */
+interface RateLimitStore {
+    /** Records one hit against `key` and answers the window's state after it. */
+    hit(key: string, windowMs: number): Promise<RateLimitHit>;
+}
+/**
+ * Counters in Redis — shared by every instance, so the configured limit is the
+ * limit no matter how many processes serve the traffic.
+ */
+declare class CacheRateLimitStore implements RateLimitStore {
+    private readonly cache;
+    constructor(cache: Redis | Cluster);
+    hit(key: string, windowMs: number): Promise<RateLimitHit>;
+}
+/**
+ * Counters in this process.
+ *
+ * Entries are pruned lazily — a key past its window resets on its next hit, so
+ * the common path stays O(1). Keys nobody touches again would otherwise sit
+ * there forever, so a full sweep runs once the map crosses `maxKeys`; that
+ * bound is what keeps a limiter keyed by client IP from growing without end.
+ */
+declare class MemoryRateLimitStore implements RateLimitStore {
+    private readonly maxKeys;
+    private readonly windows;
+    /** How many live windows were dropped to stay under `maxKeys`. */
+    private evicted;
+    constructor(maxKeys?: number);
+    hit(key: string, windowMs: number): Promise<RateLimitHit>;
+    /** Drops every window that has already reset. */
+    prune(nowMillis: number): void;
+    /**
+     * Frees a slot for a new key.
+     *
+     * Expired windows go first. If every window is still live the oldest one is
+     * dropped, because a hard bound is the only thing standing between a
+     * per-IP limiter and unbounded memory. A dropped window loses its count,
+     * so a caller who can mint `maxKeys` distinct identities can push another
+     * one out — which is why `evictionCount` is worth watching: it says this
+     * process is past what an in-memory limiter should be asked to hold, and
+     * the deployment wants a real cache.
+     */
+    private makeRoom;
+    get size(): number;
+    /** Live windows dropped for capacity — nonzero means the bound is binding. */
+    get evictionCount(): number;
+    clear(): void;
+}
+
+export { CacheRateLimitStore, type ClientType, ErrorHandler, type ErrorHandlerOptions, MemoryRateLimitStore, type NonceStore, type OnErrorContext, type ProxyGuardConfig, type ProxyGuardMode, type RateLimitDimension, type RateLimitHit, type RateLimitOptions, type RateLimitStore, RequestLogger, type RequestLoggerConfig, type RequestLoggerOptions, createCacheNonceStore, createInMemoryNonceStore, createProxyGuard, getClientIp, getRateLimitPolicy, maskSensitiveData, rateLimit, rateLimitPolicy, resetMemoryRateLimitStore, setRateLimitFailClosedDefault, setRateLimitPolicies };