theorum 0.1.15 → 1.1.3

package/esm/src/guardrails/types.d.ts

@@ -0,0 +1,291 @@
+/**
+ * Guardrail vocabulary — trust levels, stages, verdicts, and profile policy shape.
+ *
+ * This module is the single source of truth for guardrail types. It must not import
+ * from `src/kernel/`: the kernel type-imports `ProfileGuardrailsSpec` for
+ * `ProfileCommon.guardrails`, and that edge stays one-directional. Implementation
+ * modules under `src/guardrails/` may import kernel types freely.
+ *
+ * @module
+ */
+/**
+ * Origin trust for text entering the model's context.
+ *
+ * - `trusted` — author-time profile text (`identity.system`). Sensitive redaction
+ *   only; injection redaction would mangle the host's own instructions.
+ * - `assembled` — host-built per turn (`req.system`). Interpolates retrieval and
+ *   user data, so it is permeable and takes full detection.
+ * - `untrusted` — user input, tool results, attachments, delegated agents.
+ */
+export declare const TRUST_LEVELS: readonly ["trusted", "assembled", "untrusted"];
+export type TrustLevel = (typeof TRUST_LEVELS)[number];
+/** Boundary a guardrail check runs at. */
+export declare const GUARDRAIL_STAGES: readonly ["input", "history", "system", "attachment", "tool_call", "tool_result", "output_delta", "output_final", "network", "live_inbound", "live_outbound", "trace"];
+export type GuardrailStage = (typeof GUARDRAIL_STAGES)[number];
+/** How serious a hit is. Does not decide what happens next — that is `onBlock`. */
+export declare const SEVERITIES: readonly ["info", "low", "medium", "high"];
+export type Severity = (typeof SEVERITIES)[number];
+/** Egress block handling. */
+export declare const EGRESS_ON_BLOCK: readonly ["reject_to_agent", "refuse_to_user"];
+export type EgressOnBlock = (typeof EGRESS_ON_BLOCK)[number];
+/** One detector match. */
+export interface GuardrailHit {
+    /** Stable rule id, e.g. `injection.instruction-override`. */
+    rule: string;
+    severity: Severity;
+    /** Offsets into the inspected text; absent for whole-payload checks. */
+    span?: {
+        start: number;
+        end: number;
+    };
+    /**
+     * Exact matched substring (capped). Present when detectors had the source text.
+     * Stripped from host/trace unless `observability.include.guardrailMatchPreview`.
+     */
+    match?: string;
+}
+/**
+ * Outcome of one guardrail evaluation.
+ *
+ * A discriminated union so a new variant fails every unhandled `switch` at
+ * compile time rather than falling through at runtime.
+ */
+export type Verdict = {
+    action: 'allow';
+} | {
+    action: 'redact';
+    text: string;
+    hits: GuardrailHit[];
+} | {
+    action: 'flag';
+    hits: GuardrailHit[];
+} | {
+    action: 'block';
+    hits: GuardrailHit[];
+    /** Sent to the model on a repair turn when `onBlock` is `reject_to_agent`. */
+    rejection: string;
+    /** Shown to the user when `onBlock` is `refuse_to_user`. Host-owned copy. */
+    refusal?: string;
+};
+export type GuardrailAction = Verdict['action'];
+/**
+ * Where a tool result came from.
+ *
+ * `local` is host TypeScript the profile registered; `http` and `mcp` are remote
+ * services whose bytes the host does not control. `delegated` is another agent
+ * answering through the tool boundary — its output is model-generated prose that
+ * reads as authoritative, which is why depth is tracked separately.
+ */
+export declare const TOOL_ORIGINS: readonly ["local", "builtin", "http", "mcp", "delegated"];
+export type ToolOrigin = (typeof TOOL_ORIGINS)[number];
+/** Where a piece of content entered the turn from. */
+export interface Provenance {
+    origin: ToolOrigin;
+    /** Registered tool name. */
+    tool: string;
+    /**
+     * Hops from the user's turn. A direct tool call is 1; a tool result produced by
+     * a delegated agent that itself called tools is deeper. Depth matters because a
+     * two-hop delegation can otherwise launder remote content into trusted-looking
+     * output.
+     */
+    depth: number;
+}
+/**
+ * Untrusted content a turn has already taken into its context.
+ *
+ * Once a turn has read attacker-influenceable bytes, a later tool call is a
+ * confused-deputy risk: the content can ask the agent to act, and the agent has
+ * authority the content does not. Sources are kept in order so a policy can reason
+ * about depth as well as presence.
+ */
+export interface TurnTaint {
+    sources: Provenance[];
+    /**
+     * Directive hits found in remote content this turn read.
+     *
+     * Separates "read something remote" from "read something that tried to steer
+     * me". The second is far rarer, so a gate keyed on it refuses far less
+     * legitimate work.
+     */
+    suspicious: GuardrailHit[];
+}
+/**
+ * What a turn may still do after it has ingested untrusted remote content.
+ *
+ * Enforcement is opt-in. Tracking and reporting are on by default — every
+ * remote read is observable — but refusing tool calls changes what working agents
+ * are allowed to do, so a host declares which access levels to gate rather than
+ * having the kernel guess.
+ */
+/**
+ * How strongly the tool-ingress signals fired, derived from the hits themselves.
+ *
+ * Not a probability: there is no calibrated model behind it. `elevated` means one
+ * directive signal alongside an external destination; `high` means the content
+ * named a tool the model can call, or several signals agreed.
+ */
+export declare const ADVISORY_LEVELS: readonly ["none", "elevated", "high"];
+export type AdvisoryLevel = (typeof ADVISORY_LEVELS)[number];
+export declare const TAINT_GATES: readonly ["off", "destructive", "write"];
+export type TaintGate = (typeof TAINT_GATES)[number];
+/**
+ * Only structural facts gate tool calls.
+ *
+ * Content signals from `tool-directives.ts` deliberately have no gate here. They
+ * are pattern matches with no measured precision, and refusing a tool call on an
+ * unpredictable signal makes an agent unreliable rather than safe — the failure is
+ * invisible to the user and looks like the agent being stupid. Those signals
+ * annotate the fence and raise telemetry; the model still gets to decide, and the
+ * host still gets to see.
+ */
+export interface TaintGuardrailSpec {
+    /**
+     * Host copy appended to the fence when tool content looks directive.
+     *
+     * The kernel states what it observed; what the agent should *do* about it —
+     * ask the user, refuse, proceed carefully — is product behaviour and stays
+     * host-owned. Omitted means the observation is stated without guidance.
+     */
+    advisoryGuidance?: string;
+    /**
+     * Least-severe tool capability refused once the turn has read remote content.
+     *
+     * - `off` (default) — report only.
+     * - `destructive` — refuse hard-to-undo calls.
+     * - `write` — refuse those and any state-changing call.
+     *
+     * Stated as a capability threshold rather than a list of tool `access` values so
+     * the guardrail vocabulary stays independent of the tool registry; the kernel
+     * maps a tool's declared access onto it.
+     */
+    afterRemoteRead?: TaintGate;
+}
+/** Facts a check may read. Deliberately excludes the full profile. */
+export interface GuardrailContext {
+    stage: GuardrailStage;
+    trust: TrustLevel;
+    profileId: string;
+    canary?: string;
+    role?: string;
+    slots?: Record<string, string>;
+    /** Set on tool-shaped stages; absent for user and system text. */
+    provenance?: Provenance;
+}
+/**
+ * One guardrail decision, as it reaches the host and the trace.
+ *
+ * Carries rule identity and offsets, never the matched content, so a trace sink
+ * can count and locate hits without becoming a second copy of the secret.
+ */
+export interface GuardrailEvent {
+    stage: GuardrailStage;
+    trust: TrustLevel;
+    action: GuardrailAction;
+    hits: GuardrailHit[];
+    provenance?: Provenance;
+}
+/**
+ * User-visible output projected out of the turn's events.
+ *
+ * Structured output travels alongside text so a profile with `outputs.structured`
+ * is not invisible to its own egress policy.
+ */
+export interface OutboundPayload {
+    /** Concatenated user-visible text for this attempt. */
+    text: string;
+    /** Structured output, when the profile emits it. */
+    structured?: unknown;
+}
+/** Evaluates candidate user-visible output before release. */
+export type EgressEnforcer = (payload: OutboundPayload, context: GuardrailContext) => Verdict | Promise<Verdict>;
+/** Profile egress policy for rejection, retry, or refusal behavior. */
+export interface ProfileEgressSpec {
+    enforce: EgressEnforcer;
+    onBlock?: EgressOnBlock;
+    maxRetries?: number;
+    repairGuidance?: string;
+}
+/** SSRF and network access policy for HTTP and remote MCP tools. */
+export interface NetworkGuardrailSpec {
+    /**
+     * When true, allows connections to localhost / loopback and private subnets
+     * (e.g. for local dev/testing). Default: false.
+     */
+    allowPrivateNetworks?: boolean;
+    /** Hostnames or IP addresses permitted regardless of private subnet status. */
+    allowedHosts?: string[];
+    /**
+     * Allowed URL schemes. Defaults to `['https']`, or `['http', 'https']` when
+     * `allowPrivateNetworks` is set.
+     */
+    allowedSchemes?: string[];
+}
+/** Optional daily turn quota consumed by host HTTP middleware. */
+export interface QuotaGuardrailSpec {
+    perDay: number;
+    /**
+     * Host copy surfaced when the quota trips. The kernel never authors this:
+     * `quotaExhausted` returns structured data (`code`, `perDay`) and includes
+     * this string only when the host set it.
+     */
+    message?: string;
+}
+/**
+ * Per-turn canary switches. `true` / `false` toggles minting with the
+ * registered default bind note; the object form supplies host copy.
+ */
+export interface CanaryGuardrailSpec {
+    /**
+     * Host template appended to the system prompt binding the canary. Must
+     * contain the `{canary}` placeholder; `bindCanary` refuses a note that lost
+     * the token. Omitted means the lexicon default (`canary.bind_note`).
+     */
+    bindNote?: string;
+}
+/** Profile guardrail switches enforced by the kernel. */
+export interface ProfileGuardrailsSpec {
+    /** Optional daily turn quota; omitted means quota enforcement is not configured. */
+    quota?: QuotaGuardrailSpec;
+    canary?: boolean | CanaryGuardrailSpec;
+    sanitizeInput?: boolean;
+    redactSensitive?: boolean;
+    egress?: ProfileEgressSpec;
+    /** SSRF and network access policies for HTTP and MCP tools. */
+    network?: NetworkGuardrailSpec;
+    /** What the turn may still do after reading untrusted remote content. */
+    taint?: TaintGuardrailSpec;
+}
+/** The guardrail field names a `host` profile may set. */
+export declare const HOST_GUARDRAIL_FIELDS: readonly ["sanitizeInput", "redactSensitive", "network", "taint"];
+/**
+ * The guardrail switches a `host` profile may set.
+ *
+ * A host profile runs no model, so only the guards that fire on the `invokeTool`
+ * path exist for it: the detectors applied to model-supplied arguments and to
+ * tool result and failure text (`sanitizeInput`, `redactSensitive`), SSRF
+ * clearance for declarative HTTP and MCP targets (`network`), and the
+ * confused-deputy gate on a tainted turn (`taint`). Everything else in
+ * {@link ProfileGuardrailsSpec} — quota, canary, egress — guards a model turn
+ * and is refused by `defineProfile` on `type: 'host'`.
+ *
+ * This is a view of the one guardrail vocabulary, not a second hierarchy.
+ */
+export type HostGuardrailsSpec = Pick<ProfileGuardrailsSpec, (typeof HOST_GUARDRAIL_FIELDS)[number]>;
+/**
+ * A profile's guardrail switches with defaults applied.
+ *
+ * Every path resolves through `resolveGuardrailPolicy` so turn and Live ingress
+ * cannot drift apart on defaults.
+ */
+export interface ResolvedGuardrailPolicy {
+    sanitizeInput: boolean;
+    redactSensitive: boolean;
+    canary: boolean;
+    /** Host bind-note template from `guardrails.canary.bindNote`, when set. */
+    canaryBindNote?: string;
+    egress?: ProfileEgressSpec;
+    network?: NetworkGuardrailSpec;
+    quota?: QuotaGuardrailSpec;
+    taint?: TaintGuardrailSpec;
+}

package/esm/src/guardrails/types.js

@@ -0,0 +1,72 @@
+/**
+ * Guardrail vocabulary — trust levels, stages, verdicts, and profile policy shape.
+ *
+ * This module is the single source of truth for guardrail types. It must not import
+ * from `src/kernel/`: the kernel type-imports `ProfileGuardrailsSpec` for
+ * `ProfileCommon.guardrails`, and that edge stays one-directional. Implementation
+ * modules under `src/guardrails/` may import kernel types freely.
+ *
+ * @module
+ */
+/**
+ * Origin trust for text entering the model's context.
+ *
+ * - `trusted` — author-time profile text (`identity.system`). Sensitive redaction
+ *   only; injection redaction would mangle the host's own instructions.
+ * - `assembled` — host-built per turn (`req.system`). Interpolates retrieval and
+ *   user data, so it is permeable and takes full detection.
+ * - `untrusted` — user input, tool results, attachments, delegated agents.
+ */
+export const TRUST_LEVELS = ['trusted', 'assembled', 'untrusted'];
+/** Boundary a guardrail check runs at. */
+export const GUARDRAIL_STAGES = [
+    'input',
+    'history',
+    'system',
+    'attachment',
+    'tool_call',
+    'tool_result',
+    'output_delta',
+    'output_final',
+    'network',
+    'live_inbound',
+    'live_outbound',
+    'trace',
+];
+/** How serious a hit is. Does not decide what happens next — that is `onBlock`. */
+export const SEVERITIES = ['info', 'low', 'medium', 'high'];
+/** Egress block handling. */
+export const EGRESS_ON_BLOCK = ['reject_to_agent', 'refuse_to_user'];
+/**
+ * Where a tool result came from.
+ *
+ * `local` is host TypeScript the profile registered; `http` and `mcp` are remote
+ * services whose bytes the host does not control. `delegated` is another agent
+ * answering through the tool boundary — its output is model-generated prose that
+ * reads as authoritative, which is why depth is tracked separately.
+ */
+export const TOOL_ORIGINS = ['local', 'builtin', 'http', 'mcp', 'delegated'];
+/**
+ * What a turn may still do after it has ingested untrusted remote content.
+ *
+ * Enforcement is opt-in. Tracking and reporting are on by default — every
+ * remote read is observable — but refusing tool calls changes what working agents
+ * are allowed to do, so a host declares which access levels to gate rather than
+ * having the kernel guess.
+ */
+/**
+ * How strongly the tool-ingress signals fired, derived from the hits themselves.
+ *
+ * Not a probability: there is no calibrated model behind it. `elevated` means one
+ * directive signal alongside an external destination; `high` means the content
+ * named a tool the model can call, or several signals agreed.
+ */
+export const ADVISORY_LEVELS = ['none', 'elevated', 'high'];
+export const TAINT_GATES = ['off', 'destructive', 'write'];
+/** The guardrail field names a `host` profile may set. */
+export const HOST_GUARDRAIL_FIELDS = [
+    'sanitizeInput',
+    'redactSensitive',
+    'network',
+    'taint',
+];

package/esm/src/host/client-turn.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Strip host-only diagnostics from turn events before client-facing transports.
+ *
+ * @module
+ */
+import type { TurnEvent } from '../kernel/types.js';
+/** Options for {@link forClient} / {@link forClientEvents}. */
+export interface ClientTurnOptions {
+    /**
+     * Keep provider-native step payloads on `evidence` events.
+     * Default `false` — parsed fields (`kind`, `code`, `result`, citations) remain.
+     */
+    includeEvidenceRaw?: boolean;
+}
+/** Return a copy of one turn event safe to forward to browsers or end-user SSE. */
+declare function forClient(event: TurnEvent, options?: ClientTurnOptions): TurnEvent;
+/** Map {@link forClient} over a batch (e.g. Live relay or HTTP stream flush). */
+declare function forClientEvents(events: TurnEvent[], options?: ClientTurnOptions): TurnEvent[];
+export { forClient, forClientEvents };

package/esm/src/host/client-turn.js

@@ -0,0 +1,36 @@
+/**
+ * Strip host-only diagnostics from turn events before client-facing transports.
+ *
+ * @module
+ */
+import { projectGuardrailTurnEvent } from '../guardrails/events.js';
+function stripErrorInternal(event) {
+    if (event.type !== 'error' || !event.errorInternal) {
+        return event;
+    }
+    const { errorInternal: _internal, ...rest } = event;
+    return rest;
+}
+function stripEvidenceRaw(event) {
+    if (event.type !== 'evidence' || !event.evidence?.raw) {
+        return event;
+    }
+    const { raw: _raw, ...evidence } = event.evidence;
+    return { ...event, evidence };
+}
+/** Return a copy of one turn event safe to forward to browsers or end-user SSE. */
+function forClient(event, options) {
+    let out = stripErrorInternal(event);
+    if (!options?.includeEvidenceRaw) {
+        out = stripEvidenceRaw(out);
+    }
+    // Clients never receive matched substrings — even if the host opted into
+    // guardrailMatchPreview for server logs / JSONL.
+    out = projectGuardrailTurnEvent(out, false);
+    return out;
+}
+/** Map {@link forClient} over a batch (e.g. Live relay or HTTP stream flush). */
+function forClientEvents(events, options) {
+    return events.map((event) => forClient(event, options));
+}
+export { forClient, forClientEvents };

package/esm/src/host/mint-trace.d.ts

@@ -6,8 +6,8 @@
  *
  * @module
  */
-import { type TraceSink } from '../observability/trace.js';
 import type { TraceRecord } from '../observability/trace-record.js';
+import type { TraceSink } from '../observability/trace-sink.js';
 interface CutoutTape {
     ok: boolean;
     ms: number;

package/esm/src/host/mod.d.ts

@@ -1,13 +1,15 @@
 /**
  * Optional host-application helpers.
  *
- * These are not part of the turn kernel. They exist for Deno HTTP hosts that
- * want shared reply status mapping and cutout-trace flushing without re-
- * implementing the same glue in every app route.
+ * Not part of the turn kernel. Shared glue for Deno HTTP hosts (reply status,
+ * cutout-trace flush) and live structured-output preview while tokens stream.
  *
  * @module
  */
 import "../../_dnt.polyfills.js";
+export type { ClientTurnOptions } from './client-turn.js';
+export { forClient, forClientEvents } from './client-turn.js';
 export type { CutoutTape } from './mint-trace.js';
 export { flushMintTrace } from './mint-trace.js';
+export { readStreamingJsonStringField } from './readStreamingJsonStringField.js';
 export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json, } from './reply.js';

package/esm/src/host/mod.js

@@ -1,12 +1,13 @@
 /**
  * Optional host-application helpers.
  *
- * These are not part of the turn kernel. They exist for Deno HTTP hosts that
- * want shared reply status mapping and cutout-trace flushing without re-
- * implementing the same glue in every app route.
+ * Not part of the turn kernel. Shared glue for Deno HTTP hosts (reply status,
+ * cutout-trace flush) and live structured-output preview while tokens stream.
  *
  * @module
  */
 import "../../_dnt.polyfills.js";
+export { forClient, forClientEvents } from './client-turn.js';
 export { flushMintTrace } from './mint-trace.js';
+export { readStreamingJsonStringField } from './readStreamingJsonStringField.js';
 export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json, } from './reply.js';

package/esm/src/kernel/auth/crypto.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Web Crypto utilities for OAuth 2.1 PKCE and stateless sealed state envelopes.
+ *
+ * All operations use standard `crypto.subtle` and `crypto.getRandomValues`,
+ * ensuring 100% portability across Node, Deno, Bun, Cloudflare Workers, and browsers.
+ *
+ * @module
+ */
+/** Encode Uint8Array to RFC 4648 base64url string without padding. */
+export declare function toBase64Url(bytes: Uint8Array): string;
+/** Decode RFC 4648 base64url string to Uint8Array. */
+export declare function fromBase64Url(base64url: string): Uint8Array;
+/**
+ * Generate a cryptographically secure PKCE code verifier (RFC 7636 Section 4.1).
+ * Length must be between 43 and 128 characters without modulo bias.
+ */
+export declare function generateCodeVerifier(length?: number): string;
+/**
+ * Compute the PKCE code challenge using S256 (RFC 7636 Section 4.2):
+ * `BASE64URL(SHA256(ASCII(code_verifier)))`
+ */
+export declare function computeCodeChallenge(verifier: string): Promise<string>;
+export interface SealedStatePayload {
+    codeVerifier: string;
+    expectedIssuer: string;
+    resource?: string;
+    redirectUri: string;
+    expiresAt: number;
+    clientId: string;
+    extra?: Record<string, unknown>;
+}
+/**
+ * Create a stateless HMAC-SHA256 signed envelope for OAuth `state`.
+ * This allows a stateless backend to recover the code_verifier and expected issuer
+ * upon receiving the OAuth callback, without any database or session cache.
+ */
+export declare function sealStatePayload(payload: SealedStatePayload, secret: string): Promise<string>;
+/**
+ * Unpack and verify an HMAC-SHA256 signed `state` envelope.
+ * Validates cryptographic signature and expiration timestamp.
+ */
+export declare function unsealStatePayload(sealed: string, secret: string): Promise<SealedStatePayload>;

package/esm/src/kernel/auth/crypto.js

@@ -0,0 +1,106 @@
+/**
+ * Web Crypto utilities for OAuth 2.1 PKCE and stateless sealed state envelopes.
+ *
+ * All operations use standard `crypto.subtle` and `crypto.getRandomValues`,
+ * ensuring 100% portability across Node, Deno, Bun, Cloudflare Workers, and browsers.
+ *
+ * @module
+ */
+/** Encode Uint8Array to RFC 4648 base64url string without padding. */
+export function toBase64Url(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.byteLength; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** Decode RFC 4648 base64url string to Uint8Array. */
+export function fromBase64Url(base64url) {
+    let base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
+    while (base64.length % 4 !== 0) {
+        base64 += '=';
+    }
+    try {
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes;
+    }
+    catch (err) {
+        throw new Error(`Invalid base64url encoding: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Generate a cryptographically secure PKCE code verifier (RFC 7636 Section 4.1).
+ * Length must be between 43 and 128 characters without modulo bias.
+ */
+export function generateCodeVerifier(length = 64) {
+    if (length < 43 || length > 128) {
+        throw new RangeError(`Invalid PKCE code_verifier length: ${length}. RFC 7636 Section 4.1 requires length between 43 and 128 characters.`);
+    }
+    const validChars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
+    const maxValid = 256 - (256 % validChars.length); // 198 (66 * 3) eliminates modulo bias
+    let verifier = '';
+    const buffer = new Uint8Array(length * 2);
+    while (verifier.length < length) {
+        crypto.getRandomValues(buffer);
+        for (let i = 0; i < buffer.length && verifier.length < length; i++) {
+            const val = buffer[i];
+            if (val !== undefined && val < maxValid) {
+                verifier += validChars[val % validChars.length];
+            }
+        }
+    }
+    return verifier;
+}
+/**
+ * Compute the PKCE code challenge using S256 (RFC 7636 Section 4.2):
+ * `BASE64URL(SHA256(ASCII(code_verifier)))`
+ */
+export async function computeCodeChallenge(verifier) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(verifier);
+    const digest = await crypto.subtle.digest('SHA-256', data);
+    return toBase64Url(new Uint8Array(digest));
+}
+/**
+ * Create a stateless HMAC-SHA256 signed envelope for OAuth `state`.
+ * This allows a stateless backend to recover the code_verifier and expected issuer
+ * upon receiving the OAuth callback, without any database or session cache.
+ */
+export async function sealStatePayload(payload, secret) {
+    const encoder = new TextEncoder();
+    const jsonStr = JSON.stringify(payload);
+    const payloadBytes = encoder.encode(jsonStr);
+    const payloadB64 = toBase64Url(payloadBytes);
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(payloadB64));
+    const signatureB64 = toBase64Url(new Uint8Array(signature));
+    return `${payloadB64}.${signatureB64}`;
+}
+/**
+ * Unpack and verify an HMAC-SHA256 signed `state` envelope.
+ * Validates cryptographic signature and expiration timestamp.
+ */
+export async function unsealStatePayload(sealed, secret) {
+    const parts = sealed.split('.');
+    if (parts.length !== 2) {
+        throw new Error('Invalid sealed state format'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const [payloadB64, signatureB64] = parts;
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    const signatureBytes = fromBase64Url(signatureB64);
+    const isValid = await crypto.subtle.verify('HMAC', key, signatureBytes, encoder.encode(payloadB64));
+    if (!isValid) {
+        throw new Error('OAuth state HMAC signature verification failed: state has been tampered with or corrupted');
+    }
+    const payloadJson = new TextDecoder().decode(fromBase64Url(payloadB64));
+    const payload = JSON.parse(payloadJson);
+    if (Date.now() > payload.expiresAt) {
+        throw new Error('OAuth state has expired'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return payload;
+}

package/esm/src/kernel/auth/mod.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Authentication and authorization primitives for Theorum.
+ *
+ * Implements stateless OAuth 2.1 PKCE, RFC 9728 discovery, RFC 8414 AS metadata,
+ * RFC 9207 issuer validation, and RFC 8707 resource indicators.
+ *
+ * @module
+ */
+export * from './crypto.js';
+export * from './oauth.js';
+export * from './types.js';

package/esm/src/kernel/auth/mod.js

@@ -0,0 +1,11 @@
+/**
+ * Authentication and authorization primitives for Theorum.
+ *
+ * Implements stateless OAuth 2.1 PKCE, RFC 9728 discovery, RFC 8414 AS metadata,
+ * RFC 9207 issuer validation, and RFC 8707 resource indicators.
+ *
+ * @module
+ */
+export * from './crypto.js';
+export * from './oauth.js';
+export * from './types.js';