theokit 0.12.0 → 0.13.0

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

@@ -0,0 +1,229 @@
+import { a as AgentErrorEvent, A as AgentEvent } from '../../agent-events-DosDXkSV.js';
+export { b as AgentMessageEvent, f as AgentRunErrorCode, c as AgentThinkingEvent, d as AgentToolCallEvent, e as AgentToolResultEvent } from '../../agent-events-DosDXkSV.js';
+
+/**
+ * Item #4 — `streamAgentRun`
+ *
+ * Adapter that consumes the `@theokit/sdk` `Run.stream()` async generator
+ * (SDKMessage variants) and yields TheoKit `AgentEvent`s suitable for SSE
+ * via `defineAgentEndpoint`. One line at the consumer side:
+ *
+ *   ```ts
+ *   const run = await agent.send(message)
+ *   yield* streamAgentRun(run)
+ *   ```
+ *
+ * Mapping table (SDK → AgentEvent):
+ *
+ * | SDK message                          | AgentEvent yielded                     |
+ * |---|---|
+ * | assistant.content[].type==='text'    | { type: 'message', content }           |
+ * | assistant.content[].type==='tool_use'| (none — covered by tool_call below)    |
+ * | tool_call(status='running')          | { type: 'tool_call', name, args, id }  |
+ * | tool_call(status='completed')        | { type: 'tool_result', name, data, id }|
+ * | tool_call(status='error')            | { type: 'error', message, id }         |
+ * | run.wait() status==='error'          | { type: 'error', message }             |
+ * | run.wait() status==='cancelled'      | (none — cancel ≠ error)                |
+ * | system / user / thinking / status /  | (none — internal SDK telemetry)        |
+ * |   task / request / object_delta      |                                        |
+ *
+ * Abort semantics: when the consumer calls `generator.return()` on the
+ * outer `defineAgentEndpoint` generator, `streamAgentRun` exits the
+ * `for await` loop and does NOT call `run.wait()`. Cleanup of in-flight
+ * SDK resources is the SDK consumer's responsibility (`run.cancel()`).
+ */
+/**
+ * Local mirror of the SDK's `Run` interface — only the surfaces we consume.
+ * The message contract is minimal (just `{ type: string }`) so the SDK's
+ * `SDKMessage` discriminated union IS structurally assignable without any
+ * cast at the consumer site (covariant — TS accepts the SDK's typed message
+ * as the wider `{ type: string }`). Property access inside `streamAgentRun`
+ * narrows via runtime type guards.
+ *
+ * `import type` from `@theokit/sdk` would couple TheoKit to the SDK at type-
+ * resolution time even for consumers who never use the agent surface.
+ */
+interface AgentRunLike {
+    stream: () => AsyncIterable<{
+        type: string;
+    }>;
+    wait: () => Promise<AgentRunResult>;
+}
+/**
+ * Re-exported as a convenience for test fixtures. Production code typically
+ * passes an SDK `Run` directly (structural match via `{ type: string }`).
+ */
+type AgentRunStreamMessage = {
+    type: 'assistant';
+    message: {
+        role: 'assistant';
+        content: {
+            type: string;
+            text?: string;
+        }[];
+    };
+} | {
+    type: 'tool_call';
+    name: string;
+    status: 'running' | 'completed' | 'error';
+    args?: unknown;
+    result?: unknown;
+    call_id: string;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+/** Subset of the SDK `RunResult` we consume. */
+interface AgentRunResult {
+    status: 'finished' | 'error' | 'cancelled';
+    error?: {
+        message: string;
+        code?: string;
+        cause?: unknown;
+    };
+}
+/**
+ * Map an SDK error to the AgentErrorEvent shape. Pure function — easy to test.
+ *
+ * Backward compat (D4): non-AgentRunError throws yield only `message` field
+ * (legacy shape); discriminated fields stay `undefined`.
+ *
+ * Return type is the specific `AgentErrorEvent` (not the union) for ergonomic
+ * call-site access — `errorToEvent(err).code` works without narrowing.
+ */
+declare function errorToEvent(err: unknown, id?: string): AgentErrorEvent;
+declare function streamAgentRun(run: AgentRunLike): AsyncGenerator<AgentEvent, void, unknown>;
+
+/**
+ * Item #5 — `createConversationHistory`
+ *
+ * Orchestrator that resolves a stable `agentId` from (explicit → session →
+ * cookie → fresh UUID), then returns an `@theokit/sdk` `Agent` via
+ * `Agent.getOrCreate(agentId, options)`. Conversation turns auto-persist in
+ * `<cwd>/.theokit/agents/<agentId>/messages.jsonl` — SDK owns the storage
+ * (ADR D1). `MemorySettings` (facts recall layer) is opt-in passthrough via
+ * `options.memory` (ADR D2).
+ *
+ * Security: agentId from cookie/explicit is attacker-controlled. The SDK
+ * uses it as a filesystem path component AND we serialize it into Set-Cookie.
+ * EC-1 enforces a strict regex `^[a-zA-Z0-9_-]{1,128}$` at every entry point;
+ * invalid values fall through (treated as "missing") rather than throw.
+ */
+/**
+ * Minimum surface of an SDK Agent that consumers care about post-creation.
+ * Structural match — any object with `send` + `dispose` of compatible
+ * shape works. `send` returns a `SdkRunLike` (a Run-shaped object) that
+ * `streamAgentRun` can consume. Permissive `unknown` for now; consumers
+ * who want stricter types can cast to the SDK's own types.
+ *
+ * **T5.2 (architecture-cleanup) — DP-7 decision: KEEP (Opt B).** The 5 duck-typed
+ * mirrors below were flagged as "over-engineered" by the 2026-05-27 architecture
+ * review. Decision: KEEP them because `@theokit/sdk` is `devDependency` (not
+ * required at runtime for consumers that don't use agent features). Removing
+ * the mirrors would force a hard runtime dep on the SDK, breaking consumers
+ * who build TheoKit apps without the agent layer.
+ *
+ * @kept Defensive duck-type. Do NOT replace with direct SDK type imports unless
+ *   `@theokit/sdk` is promoted from devDependency to dependency. If promoting,
+ *   ALSO drop the mirrors (Opt A from the architecture-cleanup plan T5.2).
+ */
+interface SdkRunLike {
+    stream: () => AsyncIterable<{
+        type: string;
+    }>;
+    wait: () => Promise<{
+        status: 'finished' | 'error' | 'cancelled';
+        error?: {
+            message: string;
+        };
+    }>;
+}
+interface SdkAgent {
+    send: (message: string, options?: unknown) => Promise<SdkRunLike>;
+    dispose: () => Promise<void>;
+}
+/**
+ * Phase 2 — structural duck-type of `@theokit/sdk`'s `ConversationStorageAdapter`.
+ *
+ * D2 (decoupling): we mirror the SDK's shape locally rather than hard-import
+ * the SDK type. This lets consumers pass any object matching the structural
+ * contract (own implementation, SDK's `FileSystemConversationStorage`,
+ * `InMemoryConversationStorage`, or a Postgres/Redis recipe).
+ *
+ * EC-5 (SHOULD TEST — sync drift detection): the SDK type MUST be assignable
+ * to this interface AND vice-versa. A contract test asserts both directions.
+ *
+ * `unknown` for the message payload avoids coupling to the SDK's `SDKMessage`
+ * shape. Real consumers cast at the call site if they need stricter types.
+ */
+interface ConversationStorageLike {
+    getMessages(conversationId: string): Promise<readonly unknown[]>;
+    appendMessage(conversationId: string, message: unknown): Promise<void>;
+    deleteConversation(conversationId: string): Promise<void>;
+    listConversationIds?(opts?: {
+        limit?: number;
+    }): Promise<readonly string[] | undefined>;
+    dispose?(): Promise<void>;
+}
+/**
+ * Minimum surface of `AgentOptions` accepted by `Agent.getOrCreate`. Forward-
+ * compatible: callers pass whatever the SDK supports (memory, tools, etc.).
+ *
+ * Phase 2 adds typed `conversationStorage` slot. The index signature still
+ * passes everything else opaquely.
+ */
+interface SdkAgentOptions {
+    apiKey?: string;
+    model?: {
+        id: string;
+    };
+    tools?: readonly unknown[];
+    memory?: Record<string, unknown>;
+    /**
+     * Phase 2 (Production-Readiness #1) — pluggable conversation persistence.
+     * Default (when omitted): SDK falls back to `FileSystemConversationStorage`.
+     * Required for serverless / multi-host deploys.
+     */
+    conversationStorage?: ConversationStorageLike;
+    [key: string]: unknown;
+}
+interface ConversationHistoryArgs {
+    /** Request — for reading the conversation cookie. */
+    request: Request | {
+        headers?: {
+            cookie?: string;
+        } | Headers;
+    };
+    /**
+     * Response-like surface that accepts a `Set-Cookie` header. The primitive
+     * appends a Set-Cookie line when issuing a new conversation id. If absent,
+     * the primitive still reads the existing cookie but cannot issue a new
+     * one — useful for read-only contexts.
+     */
+    response?: {
+        headers: Headers;
+    };
+    /** Explicit override — wins over session/cookie/uuid (ADR D3 step 1). */
+    agentId?: string;
+    /** Auth session containing a `conversationId` field — ADR D3 step 2. */
+    session?: {
+        conversationId?: string;
+    } | null;
+    /** SDK AgentOptions forwarded to Agent.getOrCreate. apiKey + model required. */
+    options: SdkAgentOptions;
+    /** Cookie name override. Default: 'theo_conversation'. */
+    cookieName?: string;
+    /** Cookie max-age in seconds. Default + min: 30 days. Non-positive coerced to default (EC-4). */
+    cookieMaxAge?: number;
+}
+interface ConversationHistoryResult {
+    /** The SDK Agent, ready to receive `agent.send(message)`. */
+    agent: SdkAgent;
+    /** The resolved conversation id (useful for logging / debugging). */
+    conversationId: string;
+    /** True when the id was newly generated (no prior cookie / session). */
+    isNew: boolean;
+}
+declare function createConversationHistory(args: ConversationHistoryArgs): Promise<ConversationHistoryResult>;
+
+export { AgentErrorEvent, AgentEvent, type AgentRunLike, type AgentRunResult, type AgentRunStreamMessage, type ConversationHistoryArgs, type ConversationHistoryResult, type ConversationStorageLike, type SdkAgent, type SdkAgentOptions, type SdkRunLike, createConversationHistory, errorToEvent, streamAgentRun };

package/dist/server/agent/index.js

@@ -4,7 +4,8 @@ import {
   createConversationHistory,
   errorToEvent,
   streamAgentRun
-} from "../../chunk-RESN62GB.js";
+} from "../../chunk-2KZQPDYR.js";
+import "../../chunk-EXP56GFQ.js";
 import "../../chunk-DGUM43GV.js";
 export {
   __resetSdkForTests,

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

@@ -0,0 +1,419 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { R as RateLimitStore } from '../../rate-limit-store-BEJnhWdw.js';
+
+/**
+ * T4.1 — Per-request CSP nonce generation.
+ *
+ * Returns a 22–24 character base64-encoded string carrying 16 bytes of
+ * cryptographic entropy. Used by the SSR pipeline to nonce the inline
+ * hydration data script so the default CSP can drop `'unsafe-inline'`
+ * from `script-src` in 0.3.0.
+ *
+ * Runtime portability: prefers Web Crypto (`globalThis.crypto`) because
+ * it is available on every target runtime (Node 19+, Bun, Deno, Vercel
+ * Edge, Cloudflare Workers). Falls back to `node:crypto` for older Node
+ * builds where `globalThis.crypto` is absent.
+ *
+ * NOT a security primitive in the cryptographic sense — the nonce is a
+ * one-shot, single-request value that defeats trivial XSS injection by
+ * making the attacker guess a 128-bit string per request. It is NOT
+ * suitable for signing or session tokens.
+ */
+declare function generateNonce(): string;
+
+declare class AuthRequiredError extends Error {
+    code: "AUTH_REQUIRED";
+    status: number;
+    constructor(message?: string);
+}
+declare function requireAuth<T>(session: T | null | undefined): asserts session is T;
+
+interface SessionConfig {
+    /**
+     * Session secret. Either a single string (legacy) or an array of strings
+     * where index 0 is the newest. The array form enables dual-key rotation
+     * (T3.1 / ADR D5): encrypt always uses `secrets[0]`, decrypt walks the
+     * array, transparent re-encrypt on legacy hits (T3.2).
+     *
+     * EC-1: array length capped at 5 — enforced via throw at construction.
+     */
+    secret: string | string[];
+    cookieName?: string;
+    maxAge?: number;
+}
+interface SessionMeta {
+    /** Index of the secret that decrypted the session. 0 = newest; > 0 = legacy. */
+    secretIndex: number;
+    /** True when the decrypt used a legacy secret and the cookie should be re-encrypted. */
+    needsReencrypt: boolean;
+}
+interface SessionManager<TSession> {
+    getSession(req: IncomingMessage): Promise<TSession | null>;
+    /**
+     * T3.2 — Variant of `getSession` that surfaces decrypt metadata.
+     * Used by `api-middleware.ts` to wire transparent re-encrypt BEFORE
+     * the handler runs (so streaming SSR routes don't miss the Set-Cookie
+     * window — EC-4).
+     */
+    getSessionWithMeta(req: IncomingMessage): Promise<{
+        data: TSession | null;
+        meta: SessionMeta;
+    }>;
+    createSession(res: ServerResponse, data: TSession): Promise<void>;
+    destroySession(res: ServerResponse): void;
+    /**
+     * T3.3 — OWASP A07:2021 session fixation mitigation. Re-encrypts the
+     * current session with a fresh IV and refreshed expiry. No-op when no
+     * session is present.
+     */
+    rotateSession(req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
+}
+declare function createSessionManager<TSession>(config: SessionConfig): SessionManager<TSession>;
+/**
+ * T5a.2 Phase D slice 3/3 — Web-Standards session manager.
+ *
+ * Mirror of `SessionManager<TSession>` for the Web `Request` + `Headers`
+ * shape. Same `SessionConfig`, same encryption (`encrypt`/`decrypt` from
+ * `./crypto.js`), same dual-key rotation logic (CR-002 constant-time
+ * decrypt fallback walk + transparent re-encrypt), same OWASP A07
+ * `rotateSession` invariant.
+ *
+ * **Signature differences vs `SessionManager`:**
+ *   - Read methods take `Request` (instead of `IncomingMessage`).
+ *   - Write methods take a `Headers` instance to mutate (instead of
+ *     `ServerResponse`) — caller passes the headers they're building
+ *     for their `Response` constructor.
+ *
+ * Uses `getCookieFromRequest` / `appendCookieToHeaders` /
+ * `appendDeleteCookieToHeaders` from Phase B slice 6/6.
+ */
+interface SessionManagerWeb<TSession> {
+    getSession(request: Request): Promise<TSession | null>;
+    getSessionWithMeta(request: Request): Promise<{
+        data: TSession | null;
+        meta: SessionMeta;
+    }>;
+    createSession(target: Headers, data: TSession): Promise<void>;
+    destroySession(target: Headers): void;
+    rotateSession(request: Request, target: Headers): Promise<TSession | null>;
+}
+declare function createSessionManagerWeb<TSession>(config: SessionConfig): SessionManagerWeb<TSession>;
+/**
+ * T5a.2 Phase D slice 3/3 — Web-Standards transparent re-encrypt helper.
+ *
+ * Mirror of `rotateIfNeeded(sm, req, res)` for the Web Request + Headers
+ * shape. Reads session via `getSessionWithMeta`; if the cookie was
+ * decrypted with a legacy secret (index > 0), re-issues the cookie with
+ * the newest secret via `createSession(target, data)`.
+ *
+ * **EC-4 honest framing:** unlike the IncomingMessage path where the
+ * timing constraint is "before `res.writeHead` fires", the Web Request
+ * path's constraint is "before the `Response` object is constructed and
+ * returned to the runtime". Caller MUST invoke `rotateIfNeededWeb`
+ * BEFORE building the final `Response(body, { headers: target })` so the
+ * re-encrypted Set-Cookie lands on the wire.
+ */
+declare function rotateIfNeededWeb<TSession>(sm: SessionManagerWeb<TSession>, request: Request, target: Headers): Promise<TSession | null>;
+/**
+ * T3.2 — Transparent re-encrypt helper (EC-4 timing-safe wrapper).
+ *
+ * Call this in your `createContext` (before any rendering / streaming
+ * starts). It:
+ *   1. Reads the session via `getSessionWithMeta`.
+ *   2. If the cookie was decrypted with a legacy secret (index > 0), it
+ *      immediately re-issues the cookie with `secrets[0]` so the next
+ *      request lands on the newest key.
+ *   3. Returns the session data (or null) for use downstream.
+ *
+ * EC-4: this MUST run before `renderToPipeableStream` / `res.writeHead`
+ * fires. Calling it inside an SSR component or handler body that has
+ * already streamed bytes makes the re-encrypt a silent no-op (Set-Cookie
+ * is locked once headers commit), trapping users on the legacy secret
+ * forever once it's removed from the array.
+ */
+declare function rotateIfNeeded<TSession>(sm: SessionManager<TSession>, req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
+declare function assertProductionSecret(secret: string | string[]): void;
+
+declare function encrypt<T>(data: T, secret: string): Promise<string>;
+declare function decrypt<T>(token: string, secret: string): Promise<T | null>;
+/**
+ * Reset the derived-key cache. Test helper — never call from production code.
+ * Used by Vitest to guarantee isolation between tests that use distinct
+ * secrets and want to confirm the derivation path runs.
+ */
+declare function _resetKeyCacheForTests(): void;
+
+/**
+ * T6.2 — RFC 6238 TOTP primitive.
+ *
+ * Reference: https://datatracker.ietf.org/doc/html/rfc6238
+ * HMAC-based one-time password (HOTP) base: https://datatracker.ietf.org/doc/html/rfc4226
+ *
+ * Pure-function, dependency-free implementation via Web Crypto. Secrets
+ * may be passed as Uint8Array (preferred) or base32 string.
+ *
+ * SECURITY NOTES (documented per EC-13):
+ *   - TOTP secrets are equivalent to passwords. Encrypt at rest using a
+ *     separate KMS key from the session secret. If your DB leaks, ALL
+ *     2FA codes are compromised — rotate by forcing all users to re-enroll.
+ *   - Use `verifyTotp` constant-time (we use crypto.timingSafeEqual internally).
+ */
+/** Supported HMAC algorithms per RFC 6238 §1.2. Default SHA-1. */
+type TotpAlgorithm = 'SHA-1' | 'SHA-256' | 'SHA-512';
+interface TotpOptions {
+    /** Shared secret — bytes (preferred) OR base32 string. */
+    secret: Uint8Array | string;
+    /** Time step in seconds. Default 30 (RFC 6238 §5.2 recommended). */
+    step?: number;
+    /** Code length: 6, 7, or 8 digits. Default 6. */
+    digits?: 6 | 7 | 8;
+    /** HMAC algorithm. Default SHA-1 (RFC default). */
+    algorithm?: TotpAlgorithm;
+    /** Time in ms since epoch. Default Date.now(). */
+    time?: number;
+}
+interface VerifyTotpOptions extends TotpOptions {
+    /**
+     * Drift tolerance in number of steps on each side. Default 1
+     * (RFC 6238 §5.2 recommends ±1 step = 90s total window).
+     */
+    window?: number;
+}
+/** Generate a TOTP code for a given time. */
+declare function generateTotp(opts: TotpOptions): Promise<string>;
+/**
+ * Verify a TOTP code against the current window ± `window` steps.
+ *
+ * Returns `false` for malformed tokens (non-digit, wrong length) without
+ * throwing — defensive against accidental user-input passthrough.
+ */
+declare function verifyTotp(token: string, opts: VerifyTotpOptions): Promise<boolean>;
+/** Generate a cryptographically random TOTP secret. Default 20 bytes (RFC minimum). */
+declare function generateTotpSecret(bytes?: number): Uint8Array;
+/**
+ * Build an `otpauth://` URI for QR code enrollment. Format follows the
+ * de facto Google Authenticator spec adopted by every major TOTP app.
+ *   otpauth://totp/<issuer>:<account>?secret=<base32>&issuer=<issuer>&algorithm=<alg>&digits=<n>&period=<sec>
+ */
+interface TotpUriOptions {
+    secret: Uint8Array;
+    issuer: string;
+    account: string;
+    algorithm?: TotpAlgorithm;
+    digits?: 6 | 7 | 8;
+    step?: number;
+}
+declare function totpUri(opts: TotpUriOptions): string;
+
+/**
+ * T6.3 — Backup codes for 2FA recovery.
+ *
+ * generateBackupCodes returns N plaintexts (display once to user) + hashes
+ * (store in DB). verifyBackupCode constant-time-walks all hashes and
+ * returns the matchedHash so caller can delete the used code from storage
+ * — replay protection lives at the caller (we can't see their database).
+ *
+ * SECURITY NOTES:
+ *   - Codes have ~40 bits entropy (8 chars × 5 bits per char from a
+ *     32-char alphabet excluding I/L/O/0/1). Single-use → argon2id
+ *     overhead is unnecessary; SHA-256 of the normalized code suffices.
+ *   - The caller MUST atomically delete the matched hash on successful
+ *     verify. Without that, the code is replayable. We surface
+ *     matchedHash explicitly so this step is conspicuous.
+ *   - Pair this with throttleLoginAttempts (T6.1) on the verify endpoint
+ *     to prevent online brute-force against the 40-bit space.
+ */
+interface BackupCodeOptions {
+    /** How many codes to generate. Default 10. */
+    count?: number;
+    /** Length in chars (excluding separator). Default 8. */
+    length?: number;
+    /** Separator inserted at the midpoint. Default '-'; pass null to omit. */
+    separator?: '-' | null;
+    /** Custom alphabet. Default excludes ambiguous chars (I, L, O, 0, 1). */
+    alphabet?: string;
+}
+interface BackupCode {
+    plaintext: string;
+    hash: string;
+}
+/**
+ * Generate cryptographically random backup codes + their SHA-256 hashes.
+ *
+ * Plaintext is uppercase alphanumeric (default alphabet excludes ambiguous
+ * chars). Separator inserted at the midpoint (default `-`).
+ */
+declare function generateBackupCodes(opts?: BackupCodeOptions): Promise<BackupCode[]>;
+/**
+ * Verify a code against a list of stored hashes. Walks all hashes
+ * constant-time (no early exit). Returns `valid:true` + matchedHash on
+ * hit; `valid:false` otherwise.
+ *
+ * `matchedHash` is the EXACT string the caller stored, ready to be passed
+ * to a `DELETE FROM backup_codes WHERE hash = ?` query.
+ */
+declare function verifyBackupCode(code: string, hashes: readonly string[]): Promise<{
+    valid: boolean;
+    matchedHash?: string;
+}>;
+
+/**
+ * T6.1 — Login throttling primitive.
+ *
+ * Per-credential failure counter backed by any `RateLimitStore`. After
+ * `maxAttempts` failures within `windowMs`, the identifier is locked
+ * for `lockoutMs`. Successful login resets the counter.
+ *
+ * Usage in a login handler:
+ *
+ *   const state = await checkThrottle({ store, identifier: hash(email) })
+ *   if (!state.allowed) return 429
+ *   const valid = await verifyPassword(creds)
+ *   await recordAttempt({ store, identifier: hash(email) }, valid)
+ *   if (!valid) return 401
+ *
+ * SECURITY:
+ *   - NEVER pass raw email/username as `identifier`. Hash or normalize
+ *     first (e.g. SHA-256 of the lowercased email). This prevents PII
+ *     from landing in the rate-limit store or audit logs.
+ *   - Combine with the per-route IP rate limit (T2.2) for layered defense:
+ *     IP-level limits stop scripted floods; credential-level limits stop
+ *     distributed brute force.
+ */
+interface ThrottleOptions {
+    store: RateLimitStore;
+    /**
+     * Stable identifier per credential. Hash raw emails/usernames before
+     * passing in — never leak PII to the rate-limit key space.
+     */
+    identifier: string;
+    /** Failures before lockout. Default 5. */
+    maxAttempts?: number;
+    /** Sliding window for counting failures. Default 15 minutes. */
+    windowMs?: number;
+    /** Lockout duration after maxAttempts hit. Default 1 hour. */
+    lockoutMs?: number;
+}
+interface ThrottleState {
+    allowed: boolean;
+    remainingAttempts: number;
+    /** Set when `allowed === false`. Absolute timestamp when the lockout expires. */
+    lockedUntil?: Date;
+}
+/**
+ * Read the current throttle state for an identifier WITHOUT modifying
+ * the counter. Call before validating credentials so locked attempts
+ * are rejected fast.
+ */
+declare function checkThrottle(opts: ThrottleOptions): Promise<ThrottleState>;
+/**
+ * Record an attempt outcome. On success → reset the counter. On failure
+ * → increment within the sliding window. Returns the new throttle state.
+ *
+ * Storage model: the store entry's TTL is `lockoutMs` (which doubles as
+ * the failure-accumulation window). When `lockoutMs` is short — common
+ * in tests or for soft lockouts — the entry auto-expires and the next
+ * attempt starts fresh.
+ */
+declare function recordAttempt(opts: ThrottleOptions, success: boolean): Promise<ThrottleState>;
+
+/**
+ * T7.3 — RFC 7636 PKCE primitive.
+ *
+ * Reference: https://datatracker.ietf.org/doc/html/rfc7636
+ *
+ * Pure-function, dependency-free implementation using Web Crypto.
+ *
+ * Usage in an OAuth authorization-code flow:
+ *
+ *   const { codeVerifier, codeChallenge, codeChallengeMethod } = await generatePkceChallenge()
+ *   // Store codeVerifier in the user's session
+ *   // Send codeChallenge + codeChallengeMethod in the /authorize redirect
+ *   // ... user authenticates with provider ...
+ *   // On /callback, send codeVerifier with the code → token exchange
+ */
+interface PkceChallenge {
+    codeVerifier: string;
+    codeChallenge: string;
+    codeChallengeMethod: 'S256';
+}
+/**
+ * Compute the code_challenge from a code_verifier per RFC 7636 §4.2.
+ * Exported separately to enable RFC 7636 Appendix B vector testing.
+ */
+declare function pkceChallengeFromVerifier(verifier: string): Promise<string>;
+/**
+ * Generate a fresh PKCE challenge pair.
+ *
+ * Verifier: 32 cryptographically random bytes → 43-char base64url string.
+ * RFC 7636 §4.1 allows 43–128 chars; we ship the minimum-safe default.
+ *
+ * Method: 'S256' only — no 'plain' fallback. RFC 7636 §7.2 strongly
+ * discourages plain and modern providers reject it.
+ */
+declare function generatePkceChallenge(): Promise<PkceChallenge>;
+
+/**
+ * T7.4 — OAuth `state` parameter helpers (RFC 6749 §10.12).
+ *
+ * `state` is a cryptographically random anti-CSRF token. The client
+ * stores it (in session/cookie/db) before redirecting to the
+ * authorization endpoint and verifies it on the callback. Without it,
+ * an attacker can authorize on the user's account using a captured code.
+ */
+/**
+ * Generate a cryptographically random state token. Default 32 bytes
+ * (~43 base64url chars). Increase for higher entropy if your provider
+ * supports it.
+ */
+declare function generateOAuthState(opts?: {
+    bytes?: number;
+}): string;
+/**
+ * Verify a state token. Constant-time compare. Empty inputs always fail
+ * (defensive — never accept empty as "they match").
+ *
+ * CR-012 fix: `constantTimeEquals` does not early-exit on length mismatch,
+ * so the comparison time is independent of how the input was forged.
+ */
+declare function verifyOAuthState(provided: string, stored: string): boolean;
+
+/**
+ * T7.4 — OpenID Connect Discovery 1.0 metadata fetcher.
+ *
+ * Reference: https://openid.net/specs/openid-connect-discovery-1_0.html
+ *
+ * Caches metadata in module scope. Cache key is the exact issuer string
+ * (trailing-slash sensitive per RFC 8414 §3). Failures are NOT cached —
+ * subsequent calls retry the fetch.
+ *
+ * EC-7 — HTTPS enforced. RFC 8414 §3 requires HTTPS for OIDC issuers.
+ * Localhost (loopback) is allowed for development.
+ */
+interface OidcMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    jwks_uri?: string;
+    userinfo_endpoint?: string;
+    end_session_endpoint?: string;
+    scopes_supported?: string[];
+    response_types_supported?: string[];
+    grant_types_supported?: string[];
+    id_token_signing_alg_values_supported?: string[];
+    [key: string]: unknown;
+}
+/** Clear the discovery cache. Used by tests. */
+declare function clearOidcCache(): void;
+/**
+ * Fetch (or return cached) OIDC provider metadata.
+ *
+ * Throws when:
+ *   - Issuer URL is malformed
+ *   - Issuer is HTTP and not a loopback host (EC-7)
+ *   - HTTP response is non-OK
+ *   - Metadata lacks `authorization_endpoint` (sanity check)
+ */
+declare function discoverOidcProvider(issuer: string | URL): Promise<OidcMetadata>;
+
+export { AuthRequiredError, type BackupCode, type BackupCodeOptions, type OidcMetadata, type PkceChallenge, type SessionConfig, type SessionManager, type SessionManagerWeb, type SessionMeta, type ThrottleOptions, type ThrottleState, type TotpAlgorithm, type TotpOptions, type TotpUriOptions, type VerifyTotpOptions, _resetKeyCacheForTests, assertProductionSecret, checkThrottle, clearOidcCache, createSessionManager, createSessionManagerWeb, decrypt, discoverOidcProvider, encrypt, generateBackupCodes, generateNonce, generateOAuthState, generatePkceChallenge, generateTotp, generateTotpSecret, pkceChallengeFromVerifier, recordAttempt, requireAuth, rotateIfNeeded, rotateIfNeededWeb, totpUri, verifyBackupCode, verifyOAuthState, verifyTotp };