theokit 0.12.0 → 0.12.1

package/dist/csrf-BBrEZSBW.d.ts

@@ -0,0 +1,107 @@
+import { IncomingMessage } from 'node:http';
+import { A as AuditLogger } from './audit-log-BQWM5YLG.js';
+
+/**
+ * CSRF enforcement mode.
+ *
+ * - `off`     — skip CSRF entirely. Use only when you have another defense
+ *               (e.g. you don't ship session cookies, all auth is bearer).
+ * - `warn`    — log a structured warning when the check would fail, but
+ *               still serve the request. Default for 0.2.0. Migration mode.
+ * - `strict`  — reject failing requests with 403 + code `CSRF_INVALID`.
+ *               Will become the default in 0.3.0.
+ */
+type CsrfMode = 'off' | 'warn' | 'strict';
+/**
+ * Per-request structured logger surface. Only `warn` is used by enforceCsrf;
+ * we don't require a full Logger here so callers can pass a mock or the
+ * console directly.
+ */
+interface CsrfLogger {
+    warn: (payload: CsrfWarnPayload) => void;
+    /** Optional path the request was destined for — used for log correlation. */
+    path?: string;
+}
+/**
+ * T5.1 — Rails-inspired per-route escalation.
+ *
+ * `routes` accepts string (exact match) or RegExp entries. When a request
+ * path matches AND the request would otherwise emit a warning, the
+ * `behavior` field decides what happens:
+ *
+ *   - `'warn'`  → normal warn dispatch (no-op vs default)
+ *   - `'raise'` → escalate to 403 regardless of global `csrf` mode
+ *
+ * `'raise'` never downgrades: when global mode is `'off'`, validation is
+ * skipped entirely and disallowed dispatch never runs.
+ */
+interface DisallowedConfig {
+    routes: (string | RegExp)[];
+    behavior: 'warn' | 'raise';
+}
+/**
+ * Test whether `path` matches any of the supplied patterns. String
+ * patterns are EXACT (trailing slash matters — use RegExp for tolerance).
+ *
+ * EC-5: when a RegExp carries the `/g` flag, `.test()` mutates
+ * `lastIndex` and the next invocation may miss. We reset `lastIndex`
+ * before each test so the matcher is a pure function.
+ */
+declare function matchDisallowed(path: string, patterns: readonly (string | RegExp)[]): boolean;
+/**
+ * T2.2 — Stable cutover identifier shipped with every csrf.warn payload.
+ *
+ * Convention borrowed from Vite's `deprecations.ts:74` — a `code` plus a
+ * `docsUrl` lets users (a) grep their logs for a single stable identifier
+ * to find every csrf.warn line, and (b) click through directly to the
+ * migration guide. Strings are exported constants so the analyzer (T2.3)
+ * and migration guide can reference the same source of truth.
+ */
+declare const CSRF_WARN_CODE: "CSRF_STRICT_CUTOVER";
+declare const CSRF_WARN_DOCS_URL: "https://theokit.dev/upgrade/csrf-strict-cutover";
+interface CsrfWarnPayload {
+    event: 'csrf.warn';
+    method: string;
+    path: string | undefined;
+    reason: string;
+    /**
+     * Stable identifier for the 0.2 → 0.3 CSRF strict cutover. Always
+     * `'CSRF_STRICT_CUTOVER'`. Grep-able from prod logs.
+     */
+    code: string;
+    /**
+     * Link to the section of the migration guide explaining how to clear
+     * this specific warning class.
+     */
+    docsUrl: string;
+}
+declare function validateCsrf(req: IncomingMessage): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * T5a.2 Phase B (slice 1/6) — Web-Standards-shaped CSRF validator.
+ *
+ * Mirror of `validateCsrf(req: IncomingMessage)` for the Web `Request`
+ * shape. Consumes `request.headers.get(name)` (native Web `Headers` API)
+ * instead of `req.headers[name]` (Node `IncomingMessage` indexer). Same
+ * CSRF policy + same return shape — the difference is only the input
+ * extraction.
+ *
+ * Used by `executeWebRequest` (T5a.2 Phase A) to enforce CSRF on the
+ * Web-Standards request handler entry-point.
+ */
+declare function validateCsrfRequest(request: Request): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+declare function enforceCsrf(req: IncomingMessage, mode: CsrfMode, logger?: CsrfLogger, disallowed?: DisallowedConfig, auditLogger?: AuditLogger): {
+    allow: boolean;
+    reason?: string;
+};
+
+export { CSRF_WARN_CODE as C, type DisallowedConfig as D, CSRF_WARN_DOCS_URL as a, type CsrfLogger as b, type CsrfMode as c, type CsrfWarnPayload as d, enforceCsrf as e, validateCsrfRequest as f, matchDisallowed as m, validateCsrf as v };

package/dist/csrf-readiness-store-CjIoub3U.d.ts

@@ -0,0 +1,43 @@
+/**
+ * T2.2 — In-memory bounded counter for CSRF warn events.
+ *
+ * Aggregates `csrf.warn` payloads by `(method, path, reason)` triple.
+ * Used by the `/__theo/csrf-readiness` endpoint to expose a summary the
+ * developer (or devtools tab) can inspect, so users do NOT need to grep
+ * stdout to know which endpoints will break under 0.3.0 strict CSRF.
+ *
+ * Bounded at 1000 distinct keys (EC-22). Eviction is LRU-by-insertion —
+ * when the cap is hit, the oldest key is dropped and a re-record of an
+ * evicted key starts fresh (count: 1).
+ *
+ * Single-threaded by virtue of the JS event loop; Map operations are
+ * atomic. NOT shared across processes — each worker has its own store.
+ */
+interface CsrfWarnRecord {
+    method: string;
+    path: string;
+    reason: string;
+}
+interface CsrfReadinessRouteSummary {
+    method: string;
+    path: string;
+    reason: string;
+    count: number;
+    firstSeen: string;
+    lastSeen: string;
+}
+interface CsrfReadinessSummary {
+    generatedAt: string;
+    totalEvents: number;
+    routes: CsrfReadinessRouteSummary[];
+}
+declare class CsrfReadinessStore {
+    static readonly MAX_ENTRIES = 1000;
+    private readonly entries;
+    private keyFor;
+    record(event: CsrfWarnRecord): void;
+    summary(): CsrfReadinessSummary;
+    reset(): void;
+}
+
+export { CsrfReadinessStore as C, type CsrfReadinessRouteSummary as a, type CsrfReadinessSummary as b, type CsrfWarnRecord as c };

package/dist/define-websocket-CdK94O-D.d.ts

@@ -0,0 +1,64 @@
+import { IncomingMessage } from 'node:http';
+
+interface WebSocketLike {
+    send(data: string | Buffer): void;
+    close(code?: number, reason?: string): void;
+}
+interface WebSocketHandler {
+    onOpen?: (ws: WebSocketLike, req: IncomingMessage) => void;
+    onMessage?: (ws: WebSocketLike, data: string | Buffer) => void;
+    onClose?: (ws: WebSocketLike, code: number, reason: Buffer) => void;
+    onError?: (ws: WebSocketLike, error: Error) => void;
+}
+/**
+ * Define a WebSocket endpoint handler.
+ * Identity function — provides type inference for WebSocket handlers.
+ */
+declare function defineWebSocket(handler: WebSocketHandler): WebSocketHandler;
+/**
+ * T5a.2 Phase F slice 3/3 — Web-Standards WebSocket endpoint handler.
+ *
+ * Mirror of `WebSocketHandler` for the Web `Request` shape. `onOpen`
+ * receives `request: Request` instead of `req: IncomingMessage`. The
+ * rest of the lifecycle (onMessage, onClose, onError) is shape-agnostic
+ * (`WebSocketLike` is already Web-standards-compatible per the existing
+ * design — `send(string | Buffer)` works on both Node `ws` and Web
+ * `WebSocket` instances; CF Workers / Bun / Deno coerce as needed at
+ * the adapter boundary).
+ *
+ * Per `docs/plans/t5a2-incoming-message-to-request-shape-refactor-plan.md`
+ * v1.0 § Phase F (closes Phase F).
+ *
+ * **Architectural note — WebSocket upgrade semantics differ across runtimes:**
+ *   - Node + `ws`: `WebSocketServer.handleUpgrade(req, socket, head, cb)` —
+ *     `req` is `IncomingMessage`. Use `WebSocketHandler`.
+ *   - CF Workers: `new WebSocketPair()` + `request.headers` (the upgrade
+ *     handshake IS a Web Request). Use `WebSocketHandlerWeb`.
+ *   - Bun: `server.upgrade(request, { data })` — same Web Request shape.
+ *   - Deno: `Deno.upgradeWebSocket(request)` — same Web Request shape.
+ *
+ * Cross-runtime WebSocket endpoints ship BOTH `WebSocketHandler` +
+ * `WebSocketHandlerWeb` exports; the runtime adapter picks the matching
+ * one. This is the canonical Hono / Nitric pattern.
+ */
+interface WebSocketHandlerWeb {
+    onOpen?: (ws: WebSocketLike, request: Request) => void;
+    onMessage?: (ws: WebSocketLike, data: string | Uint8Array) => void;
+    onClose?: (ws: WebSocketLike, code: number, reason: string) => void;
+    onError?: (ws: WebSocketLike, error: Error) => void;
+}
+/**
+ * Web-Standards `defineWebSocket` sibling. Identity function — provides
+ * type inference for Web WebSocket handlers.
+ *
+ * **Type difference note vs Node path:**
+ *   - `onMessage` data is `string | Uint8Array` instead of `string | Buffer`
+ *     (Web standards have no `Buffer`; Node's Buffer is a Uint8Array
+ *     subclass so the Node path's Buffer values flow through unchanged
+ *     when adapters wrap them).
+ *   - `onClose` reason is `string` instead of `Buffer` (Web `CloseEvent`
+ *     exposes the reason as a UTF-8 string natively).
+ */
+declare function defineWebSocketWeb(handler: WebSocketHandlerWeb): WebSocketHandlerWeb;
+
+export { type WebSocketHandler as W, type WebSocketHandlerWeb as a, type WebSocketLike as b, defineWebSocketWeb as c, defineWebSocket as d };

package/dist/devtools/entry.d.ts

@@ -0,0 +1,5 @@
+declare global {
+    interface Window {
+        __theoDevtoolsMounted?: boolean;
+    }
+}

package/dist/error-envelope-BsNzzAV5.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Error envelope — canonical cross-layer contract for theokit framework, SDK,
+ * and UI per plan g5-error-envelope-cross-layer v1.0 § Phase 1 / T1.1.
+ *
+ * Blueprint G5 (SHIPPABLE_WITH_CAVEATS 89/100) — Form 4 Hybrid: shared CODE
+ * enum + per-domain extensions + 2-layer SDK boundary translation.
+ *
+ * 3/3 references convergence: code + message + cause base (trpc TRPCError
+ * + hono HTTPException + encore Error). Wasp confirms ecosystem gap.
+ *
+ * Reference anchors (verified file:line):
+ * - referencia: trpc/packages/server/src/unstable-core-do-not-import/error/TRPCError.ts:65-87
+ * - referencia: trpc/packages/server/src/unstable-core-do-not-import/rpc/codes.ts:11-44,76-81
+ * - referencia: hono/src/http-exception.ts:46-78
+ * - referencia: encore/runtimes/go/beta/errs/error.go:38-55 (Go — D4 disclaimer applied)
+ *
+ * Per blueprint ADR D2: retryable + hint are extension slots, NOT base fields
+ * (3/3 references derive retryability from code identity; no reference ships
+ * a `retryable: boolean` on envelope; `hint` is novel).
+ *
+ * Per blueprint ADR D5: server-only `meta` filtered at serializer boundary
+ * (encore `json:"-"` analog).
+ *
+ * Lives in `core/contracts/` per architecture.md v3 — canonical home for
+ * shared client↔server types. Zero intra-monorepo deps; zero runtime deps
+ * (trpc + hono ship envelope with zero runtime deps per blueprint Q5).
+ */
+/**
+ * Canonical TheoKit error code union. HTTP-status flavor + SDK/agent-domain
+ * additions per blueprint Recommendations § concrete shape.
+ *
+ * String-literal union mirrors trpc's TRPC_ERROR_CODE_KEY pattern — enables
+ * exhaustive `switch (env.code)` narrowing in consumer code (UI display
+ * dispatch, retry-policy gates, telemetry classification).
+ */
+type TheoErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'CONFLICT' | 'PRECONDITION_FAILED' | 'PAYLOAD_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'TOO_MANY_REQUESTS' | 'INTERNAL_SERVER_ERROR' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'GATEWAY_TIMEOUT' | 'AGENT_RUN_ERROR' | 'PROVIDER_KEY_MISSING' | 'BUDGET_EXCEEDED' | 'RATE_LIMITED' | 'CREDENTIAL_POOL_EXHAUSTED';
+/**
+ * Base envelope shape — `{ code, message, cause?, meta?, ext? }`.
+ *
+ * `cause` follows TC39 proposal-error-cause (universal pattern, 3/3 references).
+ * `meta` is server-only metadata filtered at serializer boundary per ADR D5
+ * (`stack` is auto-stripped in non-dev builds — see T1.2 `TheoError.toJSON()`).
+ * `ext` carries opt-in per-domain extensions (`ValidationFieldsExt`,
+ * `RetryableExt`, `HintExt`, or arbitrary user-defined types via formatter hook).
+ */
+interface TheoErrorEnvelope<TExt = unknown> {
+    readonly code: TheoErrorCode;
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly meta?: Record<string, unknown>;
+    readonly ext?: TExt;
+}
+/**
+ * `ValidationFieldsExt` — validation-failure extension carrying the dot-notation
+ * field map identical to G3 `ActionInputError.fields`. Empty-string key for
+ * root-level errors (mirrors G3 EC-7). Multiple messages per key are preserved.
+ */
+interface ValidationFieldsExt {
+    readonly fields: Record<string, string[]>;
+}
+
+export type { TheoErrorEnvelope as T, ValidationFieldsExt as V, TheoErrorCode as a };

package/dist/health-route-C0hk64_U.d.ts

@@ -0,0 +1,57 @@
+/**
+ * M7-2 — health/ready reserved routes for the convention/filesystem-route
+ * server. Liveness (`/__theo/health`, always 200) and readiness
+ * (`/__theo/ready`, 200/503 from a probe) are registered on a reserved
+ * namespace BEFORE the user-route catch-all + 404 branch — mirroring nitro's
+ * `/_nitro/*` reserved-namespace pattern (knowledge-base/references/nitro/src/
+ * runtime/internal/routes/dev-tasks.ts). Liveness and readiness are kept
+ * separate by design: liveness says "the process is up", readiness says
+ * "dependencies are up".
+ *
+ * @public
+ */
+/** Reserved path for the liveness endpoint. */
+declare const HEALTH_PATH = "/__theo/health";
+/** Reserved path for the readiness endpoint. */
+declare const READY_PATH = "/__theo/ready";
+/** Config produced by {@link defineHealthRoute}. */
+interface HealthRouteConfig {
+    readonly kind: 'health';
+    /** Returns the liveness body (auto-serialized to JSON). Default: `{ status: 'ok' }`. */
+    readonly handler: () => unknown;
+}
+/** Config produced by {@link defineReadyRoute}. */
+interface ReadyRouteConfig {
+    readonly kind: 'ready';
+    /** Resolves `true` when dependencies are ready. A throw/reject is treated as not-ready (503). */
+    readonly probe: () => boolean | Promise<boolean>;
+}
+/** The reserved-route registry consulted by {@link serveReservedRoute}. */
+interface ReservedRoutes {
+    readonly health?: HealthRouteConfig;
+    readonly ready?: ReadyRouteConfig;
+}
+/** A reserved-route response: an HTTP status + a JSON-serializable body. */
+interface ReservedResponse {
+    readonly status: number;
+    readonly body: unknown;
+}
+/**
+ * Define the liveness route. The default handler returns `{ status: 'ok' }`.
+ * Liveness is always 200 — it asserts the process is up, not that dependencies are.
+ */
+declare function defineHealthRoute(handler?: () => unknown): HealthRouteConfig;
+/**
+ * Define the readiness route. The `probe` decides 200 (ready) vs 503 (not-ready).
+ * A probe that throws/rejects is treated as not-ready (503) — never a 500 crash.
+ */
+declare function defineReadyRoute(probe: () => boolean | Promise<boolean>): ReadyRouteConfig;
+/**
+ * Pure dispatcher: map a request pathname to a reserved-route response, or
+ * `null` when the path is not reserved (so the user catch-all + 404 take over).
+ * Liveness defaults to 200 `{status:'ok'}`; readiness without a probe is
+ * trivially ready (200). Registered BEFORE the user catch-all by the caller.
+ */
+declare function serveReservedRoute(pathname: string, routes?: ReservedRoutes): Promise<ReservedResponse | null>;
+
+export { HEALTH_PATH as H, type ReservedRoutes as R, type HealthRouteConfig as a, READY_PATH as b, type ReadyRouteConfig as c, type ReservedResponse as d, defineHealthRoute as e, defineReadyRoute as f, serveReservedRoute as s };