theokit 0.12.0 → 0.13.0

package/dist/server/rate-limit/index.d.ts

@@ -0,0 +1,105 @@
+import { R as RateLimitConfig, a as RateLimitResult } from '../../rate-limit-BdNDZ3vt.js';
+export { c as createRateLimiter, b as createRateLimiterWeb } from '../../rate-limit-BdNDZ3vt.js';
+import { R as RateLimitStore } from '../../rate-limit-store-BEJnhWdw.js';
+export { I as InMemoryStore, a as RateLimitState } from '../../rate-limit-store-BEJnhWdw.js';
+import { IncomingMessage } from 'node:http';
+
+/**
+ * T2.2 — Per-route + per-user rate limiting.
+ *
+ * Layered on top of `rate-limit-store.ts`. The route map allows
+ * declarative policies ("strict /api/login, loose everything else")
+ * driven by config, not handler-decorated. `keyBy` selects what
+ * identifier the limiter buckets on.
+ *
+ * ADR D2: per-route via path matching, NOT per-handler decorator.
+ * Operators can tune policies without touching route definitions.
+ */
+type KeyByMode = 'ip' | 'session' | 'user' | ((req: IncomingMessage) => string);
+interface RouteRateLimitConfig {
+    /** Fallback config used when no per-route entry matches. */
+    default?: RateLimitConfig;
+    /** Map of path pattern → config. Exact-string keys (RegExp via API). */
+    routes?: Record<string, RateLimitConfig>;
+    /** Same as `routes` but each entry is a [pattern, config] tuple, RegExp allowed. */
+    routePatterns?: readonly [string | RegExp, RateLimitConfig][];
+    /** Bucket identifier strategy. Default 'ip'. */
+    keyBy?: KeyByMode;
+    /** Cookie name used by keyBy='session'. Defaults to 'theo_session'. */
+    cookieName?: string;
+    /** Optional shared store (for multi-route correlation). Default per-limiter InMemoryStore. */
+    store?: RateLimitStore;
+}
+/**
+ * Test whether `path` matches `pattern`. String patterns are compared
+ * after trailing-slash normalization (EC-5). RegExp uses `.test` after
+ * resetting `lastIndex` (defensive against `/g` flag).
+ */
+declare function matchRoutePattern(path: string, pattern: string | RegExp): boolean;
+/**
+ * Build the rate-limit bucket key for the request based on `keyBy`.
+ *
+ * EC-6: session mode reads the configured `cookieName`. With the wrong
+ * cookie name (e.g., default 'theo_session' but app uses 'app_session'),
+ * we fall back to IP so anonymous users still get rate-limited rather
+ * than sharing an empty bucket.
+ */
+declare function deriveKey(req: IncomingMessage, keyBy: KeyByMode, cookieName: string): Promise<string>;
+/**
+ * Per-route rate limiter factory. Returns a sync checker compatible with
+ * the existing api-middleware shape.
+ *
+ * Backwards-compatibility (ADR D2): a flat `{ windowMs, max }` config is
+ * accepted and treated as `default` (no per-route variants).
+ */
+declare function createRouteRateLimiter(config: RouteRateLimitConfig | RateLimitConfig): (req: IncomingMessage) => Promise<RateLimitResult>;
+/**
+ * T5a.2 Phase D slice 1/3 — Web-Standards rate-limiter inputs context.
+ *
+ * Web `Request` has no equivalent of `req.socket.remoteAddress` (Node
+ * runtime concept) or `req.user` (set by upstream middleware). The
+ * Web-shaped rate-limiter requires the caller to pass these explicitly:
+ *
+ *   - `clientIp` — resolved per-runtime (Node: `socket.remoteAddress`;
+ *     CF Workers: `request.headers.get('cf-connecting-ip')`; Vercel:
+ *     `x-forwarded-for` first hop; Bun/Deno: adapter-specific).
+ *   - `userId` — resolved by auth middleware (Phase D slice 3/3 ships
+ *     the Web-shaped session helper).
+ *
+ * Defaults: `clientIp = 'unknown'`, `userId = undefined` (matches the
+ * IncomingMessage path's fallback semantics).
+ */
+interface DeriveKeyRequestContext {
+    clientIp?: string;
+    userId?: string;
+}
+/**
+ * T5a.2 Phase D slice 1/3 — Web-Standards-shaped key derivation.
+ *
+ * Mirror of `deriveKey(req: IncomingMessage, keyBy, cookieName)` for the
+ * Web `Request` shape. Same `'ip' | 'session' | 'user'` enum cases (the
+ * `function` callback case is IncomingMessage-only because the existing
+ * `KeyByMode` callback type is Node-shaped; Web callers use the enum
+ * cases or call a future `KeyByModeWeb` shape — out of T5a.2 Phase D scope).
+ *
+ * Uses `getCookieFromRequest` (Phase B slice 6/6) for session-mode cookie
+ * lookup. Cookie parsing has the same CR-009 percent-encoding safety.
+ */
+declare function deriveKeyFromRequest(request: Request, keyBy: Exclude<KeyByMode, (req: IncomingMessage) => string>, cookieName: string, ctx?: DeriveKeyRequestContext): Promise<string>;
+/**
+ * T5a.2 Phase D slice 1/3 — Web-Standards rate-limiter factory.
+ *
+ * Mirror of `createRouteRateLimiter(config)` returning a checker that
+ * accepts `(request: Request, ctx?: DeriveKeyRequestContext)` instead of
+ * `(req: IncomingMessage)`. Same `RouteRateLimitConfig` accepted; same
+ * `keyBy` enum cases; same `InMemoryStore` constraint (CR-005 guard).
+ *
+ * Same returned `RateLimitResult` shape (headers + limited boolean).
+ *
+ * Web `Request` has no `req.url` path-only property — uses
+ * `new URL(request.url).pathname + search` to derive the URL the way the
+ * IncomingMessage path's `req.url ?? ''` would.
+ */
+declare function createRouteRateLimiterWeb(config: RouteRateLimitConfig | RateLimitConfig): (request: Request, ctx?: DeriveKeyRequestContext) => Promise<RateLimitResult>;
+
+export { type DeriveKeyRequestContext, type KeyByMode, RateLimitConfig, RateLimitResult, RateLimitStore, type RouteRateLimitConfig, createRouteRateLimiter, createRouteRateLimiterWeb, deriveKey, deriveKeyFromRequest, matchRoutePattern };

package/dist/server/realtime/index.d.ts

@@ -0,0 +1,15 @@
+import { b as WebSocketLike } from '../../define-websocket-CdK94O-D.js';
+import 'node:http';
+
+declare class ChannelManager {
+    private rooms;
+    private wsRooms;
+    subscribe(ws: WebSocketLike, room: string): void;
+    unsubscribe(ws: WebSocketLike, room: string): void;
+    broadcast(room: string, data: unknown, exclude?: WebSocketLike): void;
+    broadcastAll(data: unknown): void;
+    getRoomSize(room: string): number;
+    cleanup(ws: WebSocketLike): void;
+}
+
+export { ChannelManager };

package/dist/server/scan/index.d.ts

@@ -0,0 +1,126 @@
+import { S as ServerRouteNode } from '../../match-CfbEFRG4.js';
+export { L as LoadModule, c as compilePattern, a as createProductionLoader, b as createViteLoader, m as matchRoute } from '../../match-CfbEFRG4.js';
+import 'vite';
+
+interface ActionNode {
+    filePath: string;
+    actionPath: string;
+}
+/**
+ * Enriched manifest entry per plan g3-server-actions-and-useaction v1.2
+ * § Phase 1 / T1.4 + ADR D4. Consumed by virtual module `@theo/actions`
+ * (T3.1) and G4 devtools "Actions" tab (T5.1).
+ */
+interface ActionManifestEntry {
+    name: string;
+    filePath: string;
+    urlPath: string;
+    accept: 'form' | 'json';
+    hasInput: boolean;
+    /**
+     * P#4 plugin-forms shared-schema convention (per plan p4-plugin-forms v1.1 T1.1).
+     * When present, points to an isomorphic schema file at
+     * `<serverDir>/actions/schemas/<basename>.ts` exporting `export const schema = z.object(...)`.
+     * Virtual module emits `import {schema} from '<schemaFilePath>'` + attaches as
+     * `actions.X.__zodSchema` so client-side <TheoForm> can drive zodResolver.
+     * Undefined when convention not followed (graceful degrade — TheoForm still
+     * works via explicit `schema={...}` prop escape hatch).
+     */
+    schemaFilePath?: string;
+}
+/**
+ * EC-2: structured error for scan-time defects (name collision, reserved
+ * identifier, etc.). Throw at scan time to fail loud — silent shadowing is
+ * a security/correctness footgun.
+ */
+declare class ActionScanError extends Error {
+    readonly code: 'NAME_COLLISION' | 'RESERVED_NAME';
+    readonly conflictingPaths: readonly string[];
+    constructor(code: 'NAME_COLLISION' | 'RESERVED_NAME', message: string, conflictingPaths: readonly string[]);
+}
+/**
+ * Backward-compatible: original simple-shape scanner used by existing
+ * consumers. Preserved verbatim; new consumers should call
+ * `scanServerActionsEnriched`.
+ */
+declare function scanServerActions(serverDir: string): ActionNode[];
+/**
+ * Enriched scan: light AST detection of `accept: 'form'|'json'` + `input:`
+ * presence via regex-after-comment-stripping (EC-9). Throws ActionScanError
+ * on file/dir name collision (EC-2) or reserved JS identifier names.
+ *
+ * Output `ActionManifestEntry[]` is sorted by `name` for deterministic
+ * `.theokit/actions-manifest.json` emission.
+ */
+declare function scanServerActionsEnriched(serverDir: string): ActionManifestEntry[];
+
+/**
+ * A discovered agent file. `name` is the client-facing key; `agentPath` is the mounted
+ * SSE route (M0/M1 `UIMessageStream`).
+ */
+interface AgentNode {
+    filePath: string;
+    agentPath: string;
+    name: string;
+}
+
+declare function scanServerRoutes(serverDir: string): ServerRouteNode[];
+
+interface WebSocketRouteNode {
+    filePath: string;
+    wsPath: string;
+}
+declare function scanWebSocketRoutes(serverDir: string): WebSocketRouteNode[];
+
+interface ManifestRoute {
+    filePath: string;
+    routePath: string;
+    paramNames: string[];
+    /** HTTP methods (uppercase) the route file exports. Optional — manifests
+     * generated before G1 omit this; loaders treat absence as "unknown". */
+    methods?: string[];
+}
+interface ManifestAction {
+    filePath: string;
+    actionPath: string;
+}
+interface ManifestWebSocket {
+    filePath: string;
+    wsPath: string;
+}
+/** M2 — a top-level `agents/*.ts` convention entry. `filePath` is relative to the
+ * project root (agents live OUTSIDE `serverDir`), unlike routes/actions/ws. */
+interface ManifestAgent {
+    filePath: string;
+    agentPath: string;
+    name: string;
+}
+interface TheoManifest {
+    version: 1;
+    generatedAt: string;
+    routes: ManifestRoute[];
+    actions: ManifestAction[];
+    websockets: ManifestWebSocket[];
+    /** M2 — optional for backward compat: manifests generated before M2 omit it. */
+    agents?: ManifestAgent[];
+}
+interface LoadedManifest {
+    routes: ServerRouteNode[];
+    actions: ActionNode[];
+    websockets: WebSocketRouteNode[];
+    agents: AgentNode[];
+}
+declare function generateManifest(serverDir: string, projectRoot?: string): TheoManifest;
+declare function writeManifest(manifest: TheoManifest, outputDir: string): void;
+declare function loadManifest(distDir: string, serverDir: string): LoadedManifest;
+
+/**
+ * Scan the server/middleware/ directory for middleware files.
+ * Files are returned sorted alphabetically — use numeric prefixes
+ * (e.g. 01-cors.ts, 02-auth.ts) to control execution order.
+ *
+ * Files starting with '_' or '.' are ignored (helpers, hidden files).
+ */
+declare function scanMiddlewares(serverDir: string): string[];
+
+export { type ActionManifestEntry, type ActionNode, ActionScanError, type LoadedManifest, type ManifestAction, type ManifestAgent, type ManifestRoute, type ManifestWebSocket, ServerRouteNode, type TheoManifest, type WebSocketRouteNode, generateManifest, loadManifest, scanMiddlewares, scanServerActions, scanServerActionsEnriched, scanServerRoutes, scanWebSocketRoutes, writeManifest };

package/dist/server/scan/index.js

@@ -14,7 +14,7 @@ import {
   scanServerRoutes,
   scanWebSocketRoutes,
   writeManifest
-} from "../../chunk-223EFY5X.js";
+} from "../../chunk-2J7XU3PW.js";
 import "../../chunk-WSJKACWB.js";
 import {
   scanMiddlewares

package/dist/server/security/index.d.ts

@@ -0,0 +1,193 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { A as AuditLogger } from '../../audit-log-BQWM5YLG.js';
+export { C as CSRF_WARN_CODE, a as CSRF_WARN_DOCS_URL, b as CsrfLogger, c as CsrfMode, d as CsrfWarnPayload, D as DisallowedConfig, e as enforceCsrf, m as matchDisallowed, v as validateCsrf, f as validateCsrfRequest } from '../../csrf-BBrEZSBW.js';
+import { C as CsrfReadinessStore } from '../../csrf-readiness-store-CjIoub3U.js';
+export { a as CsrfReadinessRouteSummary, b as CsrfReadinessSummary, c as CsrfWarnRecord } from '../../csrf-readiness-store-CjIoub3U.js';
+
+/**
+ * T5.1 — Built-in CSP report endpoint.
+ *
+ * Browsers POST violation reports to `report-uri` (legacy `application/csp-report`)
+ * or `Reporting API` (`application/reports+json`). Framework auto-registers this
+ * endpoint so `cspMode: 'report-only'` is actually useful out of the box.
+ *
+ * Forwards normalized violations to:
+ *   - audit logger (`csp.violation`)
+ *   - devtools dispatcher (dev only, for Errors tab)
+ *   - optional user hook (Sentry, etc.)
+ *
+ * EC-2: browser MAY send `{"csp-report": null}`, empty `{}`, or
+ * reports+json entries lacking `body`. Handler MUST short-circuit to
+ * 204 (valid format, no violation), NEVER crash via null deref.
+ */
+declare const CSP_REPORT_PATH = "/__theo/csp-report";
+interface CspViolation {
+    blockedUrl: string;
+    documentUrl: string;
+    violatedDirective: string;
+    effectiveDirective?: string;
+    originalPolicy?: string;
+    disposition?: 'enforce' | 'report';
+    statusCode?: number;
+    sourceFile?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+}
+interface CspReportHandlerOptions {
+    auditLogger?: AuditLogger;
+    devtoolsDispatcher?: {
+        onCspViolation?: (v: CspViolation) => void;
+    };
+    /** Optional user-provided sink (Sentry, custom log router). Errors here are swallowed. */
+    onViolation?: (v: CspViolation) => void;
+}
+declare function normalizeLegacy(raw: Record<string, unknown>): CspViolation;
+/**
+ * Map a `reports+json` entry to the internal shape. Returns `null` if
+ * the entry lacks a usable `body` object (EC-2).
+ */
+declare function normalizeNew(entry: unknown): CspViolation | null;
+declare function handleCspReport(req: IncomingMessage, res: ServerResponse, opts: CspReportHandlerOptions): Promise<void>;
+declare function handleCspReportRequest(request: Request, opts: CspReportHandlerOptions): Promise<Response>;
+
+/**
+ * T2.2 — `/__theo/csrf-readiness` endpoint.
+ *
+ *   GET  /__theo/csrf-readiness        → 200 + JSON summary
+ *   POST /__theo/csrf-readiness/reset  → 204; clears the store
+ *
+ * The reset endpoint enforces CSRF (own dog food) — requires
+ * `X-Theo-Action: 1` AND a matching Origin header (EC-15). This avoids
+ * the endpoint being weaponizable from a cross-origin page when the
+ * endpoint is opt-in exposed in production.
+ *
+ * Mount opt-in: in dev mode, the host wires this in unconditionally. In
+ * production, only mount when `config.security.csrfTelemetry.exposeReadinessEndpoint === true`.
+ * EC-10 parallel: returns 404 (via boolean false return) when the URL
+ * does not match — the caller continues normal request handling.
+ */
+
+declare const CSRF_READINESS_PATH = "/__theo/csrf-readiness";
+declare const CSRF_READINESS_RESET_PATH = "/__theo/csrf-readiness/reset";
+declare function handleCsrfReadiness(req: IncomingMessage, res: ServerResponse, store: CsrfReadinessStore): Promise<boolean>;
+declare function handleCsrfReadinessRequest(request: Request, store: CsrfReadinessStore): Promise<Response | null>;
+
+/**
+ * Phase 6 — Default Security Headers (D4 / EC-2).
+ *
+ * Per-response security baseline. The framework applies these BEFORE the
+ * route handler runs so a handler can still override via `res.setHeader`.
+ *
+ * EC-2 backward-compatibility: CSP ships in `report-only` mode by default
+ * for 0.2.0. Existing apps with inline scripts or third-party CDN scripts
+ * keep working but consumers see violation reports via their CSP report
+ * collector (or browser DevTools). 0.3.0 will flip the default to
+ * `enforce` after a release of visibility.
+ */
+/**
+ * Default Content-Security-Policy. Conservative-but-not-paralyzing:
+ *
+ *   - default-src 'self'              — every fetch falls back to same-origin
+ *   - script-src 'self'               — T6.1 (0.3.0): `'unsafe-inline'`
+ *                                         dropped. The SSR pipeline issues a
+ *                                         per-request nonce that REPLACES
+ *                                         this directive at runtime
+ *                                         (`'nonce-<token>'`). For static /
+ *                                         non-SSR contexts where no nonce is
+ *                                         available, the policy is strict-
+ *                                         no-inline — user inline scripts
+ *                                         must be migrated to external
+ *                                         `<script src="...">` or threaded
+ *                                         through `ctx.nonce`.
+ *   - style-src 'self' 'unsafe-inline' — Tailwind + TheoUI use style attrs
+ *                                         in animation directives
+ *   - img-src 'self' data: blob:      — supports inline data URIs, blobs
+ *                                         from canvas exports
+ *   - font-src 'self' data:           — Geist fonts inline-base64
+ *   - connect-src 'self' ws: wss:     — WebSocket dev HMR + agent streams
+ *   - frame-ancestors 'none'          — clickjacking defense
+ */
+/**
+ * T5.1 — default CSP includes the built-in report endpoint so violations
+ * are visible without extra config. Apps that ship a custom `csp` string
+ * override the report-uri.
+ */
+declare const DEFAULT_CSP: string;
+/**
+ * T1.1 — Default Permissions-Policy header (default-deny stance).
+ *
+ * Disables sensitive Web APIs that the vast majority of apps don't use.
+ * Apps that DO need any of these opt in by overriding `permissionsPolicy`
+ * in `config.security.headers`.
+ *
+ * The seven features listed are the most-abused for: tracking
+ * (geolocation, accelerometer, gyroscope), spyware (camera, microphone),
+ * fraud (payment), and hardware exfiltration (usb).
+ *
+ * Aligns with Mozilla baseline + OWASP Secure Headers + Lighthouse PWA.
+ */
+declare const DEFAULT_PERMISSIONS_POLICY = "geolocation=(), camera=(), microphone=(), payment=(), usb=(), accelerometer=(), gyroscope=()";
+type CspMode = 'enforce' | 'report-only' | 'off';
+interface SecurityHeadersConfig {
+    /**
+     * Custom CSP policy string. When set, replaces the default verbatim.
+     * Pass `false` to disable CSP entirely (alias for `cspMode: 'off'`).
+     */
+    csp?: string | false;
+    /**
+     * Enforcement mode for CSP. Default `report-only` for 0.2.0 (EC-2).
+     * 0.3.0 will default to `enforce`.
+     */
+    cspMode?: CspMode;
+    /**
+     * Strict-Transport-Security value. Defaults to
+     * `max-age=31536000; includeSubDomains` in production. Pass `false` to
+     * suppress (e.g. internal LANs without TLS).
+     */
+    hsts?: string | false;
+    /** X-Frame-Options. Default DENY. */
+    frameOptions?: 'DENY' | 'SAMEORIGIN';
+    /** X-Content-Type-Options. Default `nosniff`. */
+    contentTypeOptions?: 'nosniff';
+    /** Referrer-Policy. Default `strict-origin-when-cross-origin`. */
+    referrerPolicy?: string;
+    /**
+     * T1.1 — Permissions-Policy directive string. When set, replaces the
+     * default verbatim (no merge — see ADR-EC-12). Pass `false` to disable
+     * the header entirely. Schema-level refinement rejects any string
+     * containing CR/LF (EC-3 — CWE-113 HTTP Response Splitting mitigation).
+     */
+    permissionsPolicy?: string | false;
+}
+interface SecurityEnv {
+    production: boolean;
+}
+/**
+ * T4.1 — Per-request options passed by the SSR pipeline.
+ *
+ * - `nonce`: when set, the framework substitutes the `'unsafe-inline'`
+ *   token in `script-src` with `'nonce-<nonce>'`. EC-3 forces
+ *   `Cache-Control: private, no-store` so a CDN cannot cache the HTML
+ *   (carrying one nonce) and re-serve it with a freshly-generated CSP
+ *   header (carrying a different nonce).
+ * - `prerender`: when true, the nonce is IGNORED. Prerendered HTML is
+ *   generated at build time with no nonce in the script tags; mixing a
+ *   runtime nonce in the header would block every script. EC-4.
+ */
+interface SecurityHeadersOptions {
+    nonce?: string;
+    prerender?: boolean;
+}
+/**
+ * Build the security headers map for a given config + env. Pure function —
+ * returned object can be inspected, logged, or applied to a response.
+ */
+declare function buildSecurityHeaders(config: SecurityHeadersConfig, env: SecurityEnv, options?: SecurityHeadersOptions): Record<string, string>;
+/**
+ * Apply security headers to a Node ServerResponse. Called by the
+ * api-middleware before the route handler runs. The handler can override
+ * any header via `res.setHeader()` — last write wins by Node convention.
+ */
+declare function applySecurityHeaders(res: ServerResponse, config: SecurityHeadersConfig, env: SecurityEnv, options?: SecurityHeadersOptions): void;
+
+export { CSP_REPORT_PATH, CSRF_READINESS_PATH, CSRF_READINESS_RESET_PATH, type CspMode, type CspReportHandlerOptions, type CspViolation, CsrfReadinessStore, DEFAULT_CSP, DEFAULT_PERMISSIONS_POLICY, type SecurityEnv, type SecurityHeadersConfig, type SecurityHeadersOptions, applySecurityHeaders, buildSecurityHeaders, handleCspReport, handleCspReportRequest, handleCsrfReadiness, handleCsrfReadinessRequest, normalizeLegacy, normalizeNew };

package/dist/server/storage/index.d.ts

@@ -0,0 +1,22 @@
+export { P as PostgresFactory, R as RedisFactory, S as StorageManager, g as getStorageManager } from '../../storage-manager-C4jsO0Tp.js';
+export { G as GenericFactory, a as PoolLike, P as PostgresDatabaseConfig, c as RedisLike, R as RedisServerConfig, S as ServerConfig, d as StorageAdapter, b as StorageConfig, T as TlsConfig } from '../../storage-types-DsDTCPbp.js';
+
+interface UnstorageInstance<T> {
+    getItem(key: string): Promise<T | null>;
+    setItem(key: string, value: T): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    keys(prefix?: string): Promise<string[]>;
+    hasItem(key: string): Promise<boolean>;
+    clear(prefix?: string): Promise<void>;
+    dispose?(): Promise<void>;
+}
+declare function useUnstorage<T = unknown>(name: string, driver?: unknown): Promise<UnstorageInstance<T>>;
+
+interface Db0Database {
+    exec: (sql: string) => Promise<unknown>;
+    prepare: (sql: string) => unknown;
+    sql: (strings: TemplateStringsArray, ...args: unknown[]) => Promise<unknown>;
+}
+declare function useDatabase(name: string, connector: unknown): Promise<Db0Database>;
+
+export { type Db0Database, type UnstorageInstance, useDatabase, useUnstorage };

package/dist/server/webhook/index.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Constant-time byte comparison.
+ *
+ * Wraps `node:crypto.timingSafeEqual` when available (Node 6.6+) and falls
+ * back to a constant-time XOR loop for runtimes without `node:crypto`
+ * (Cloudflare Workers, Deno, Bun edge). Required to defeat timing attacks
+ * on webhook signature verification — a naive `===` or `Buffer.equals`
+ * would short-circuit on first mismatch byte and leak signature position
+ * via wall-clock timing.
+ *
+ * Web Crypto's `crypto.subtle.verify` would also work, but requires a
+ * `CryptoKey` object and is asymmetric (verify a signature against a key).
+ * For our case — comparing two pre-computed digests — raw byte equality
+ * is the correct primitive.
+ *
+ * @see https://nodejs.org/api/crypto.html#cryptotimingsafeequala-b
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/verify
+ */
+/**
+ * Returns true iff `a` and `b` have identical bytes. Takes time
+ * proportional to `a.length` regardless of where bytes differ.
+ *
+ * @throws TypeError if either argument is not a Uint8Array.
+ */
+declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+
+/**
+ * Read a Web `Request` body as a raw string EXACTLY ONCE and expose it
+ * alongside the original request (which remains readable by downstream
+ * code). Enforces a configurable `maxBodyBytes` cap to prevent OOM via
+ * pathological POST.
+ *
+ * MUST be called FIRST in the webhook pipeline, before any other code
+ * touches the body (`request.text()`, `request.json()`, parsers). Once
+ * the body is consumed, `Request.clone()` throws and this function fails.
+ *
+ * EC-101: default `maxBodyBytes = 1_000_000` (1 MB) covers Stripe
+ * (256 KB max), Slack (4 MB but compressed), and is well below Node
+ * memory thresholds. GitHub webhooks up to 25 MB MUST opt in
+ * (`maxBodyBytes: 25_000_000`).
+ *
+ * @see https://docs.stripe.com/webhooks/signatures
+ * @see https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks
+ */
+declare const DEFAULT_MAX_BODY_BYTES = 1000000;
+interface ReadRawBodyOptions {
+    /** Maximum bytes to read before throwing `BodyTooLargeError`. Defaults to 1 MB. */
+    maxBodyBytes?: number;
+}
+interface RawBodyResult {
+    /** UTF-8 decoded body (or empty string when no body present). */
+    rawBody: string;
+    /** The ORIGINAL request, still readable by downstream code. */
+    bodyClone: Request;
+}
+/**
+ * Thrown when the request body exceeds `maxBodyBytes`. Carries status
+ * 413 (Payload Too Large) and stable code `BODY_TOO_LARGE` so callers
+ * can map it to an HTTP response without sniffing the message.
+ */
+declare class BodyTooLargeError extends Error {
+    readonly limit: number;
+    readonly actualSeen: number;
+    readonly status = 413;
+    readonly code = "BODY_TOO_LARGE";
+    constructor(limit: number, actualSeen: number);
+}
+declare function readRawBody(request: Request, options?: ReadRawBodyOptions): Promise<RawBodyResult>;
+
+/**
+ * Webhook primitive types (R0.5.10).
+ *
+ * @see docs/adr/0005-webhook-verify-inline-function.md
+ */
+type VerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * A verify function — pure, async-or-sync. Takes the cloned request
+ * (raw body NOT yet consumed by handler), returns ok/notOk + reason.
+ *
+ * Per ADR-0005, helper factories (`stripe`, `github`, `slack`) return
+ * this shape. Users can also write inline `verify: async (req) => ...`
+ * for custom providers.
+ */
+type VerifyFn = (req: Request) => Promise<VerifyResult> | VerifyResult;
+interface WebhookContext {
+    /** The cloned Request (still readable by user code). */
+    readonly request: Request;
+    /** Raw body bytes as UTF-8 string — already-verified at this point. */
+    readonly rawBody: string;
+    /** W3C trace_id propagated from request. */
+    readonly traceId: string;
+    /** Abort signal triggered by client disconnect or server stop. */
+    readonly signal: AbortSignal;
+}
+interface DefineWebhookOptions {
+    verify: VerifyFn;
+    handler: (ctx: WebhookContext) => unknown;
+    /** Override `readRawBody` body size cap (EC-101). Default 1MB. */
+    maxBodyBytes?: number;
+}
+interface WebhookDefinition {
+    readonly verify: VerifyFn;
+    readonly handler: (ctx: WebhookContext) => unknown;
+    readonly maxBodyBytes?: number;
+    /** Discriminator for runtime dispatch. */
+    readonly __theokit_kind: 'webhook';
+}
+
+/**
+ * Declare a webhook handler with first-class signature verification
+ * (R0.5.10, ADR-0005). Pure identity helper — returns the definition
+ * unchanged for downstream dispatch.
+ *
+ * @example
+ * ```ts
+ * // server/webhooks/stripe.ts
+ * import { defineWebhook } from 'theokit/server'
+ * import { stripe } from 'theokit/server/webhook/providers'
+ *
+ * export default defineWebhook({
+ *   verify: stripe({ secret: process.env.STRIPE_WEBHOOK_SECRET! }),
+ *   async handler({ rawBody }) {
+ *     const event = JSON.parse(rawBody)
+ *     // ...
+ *     return new Response('ok')
+ *   },
+ * })
+ * ```
+ */
+declare function defineWebhook(opts: DefineWebhookOptions): WebhookDefinition;
+/**
+ * Dispatch a webhook request through the definition's verify → handler
+ * pipeline. Returns the handler's `Response` (or a wrapped one), or a
+ * 401/413 response when verification or body size guards trip.
+ *
+ * EC-101: enforces `maxBodyBytes` (default 1MB via readRawBody).
+ * EC-103: every throw from `verify` (sync or async) is treated as
+ * `{ok: false, reason: 'verify threw: <message>'}`. Handler NEVER
+ * invoked on verify failure.
+ */
+declare function dispatchWebhook(def: WebhookDefinition, request: Request): Promise<Response>;
+
+export { BodyTooLargeError, DEFAULT_MAX_BODY_BYTES, type DefineWebhookOptions, type RawBodyResult, type ReadRawBodyOptions, type VerifyFn, type VerifyResult, type WebhookContext, type WebhookDefinition, defineWebhook, dispatchWebhook, readRawBody, timingSafeEqual };