theorum 1.0.0 → 1.1.3

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.js

@@ -3,6 +3,7 @@
  *
  * @module
  */
+import { projectGuardrailTurnEvent } from '../guardrails/events.js';
 function stripErrorInternal(event) {
     if (event.type !== 'error' || !event.errorInternal) {
         return event;
@@ -23,6 +24,9 @@ function forClient(event, options) {
     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). */

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/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';

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

@@ -0,0 +1,47 @@
+/**
+ * RFC-compliant OAuth 2.1 discovery and flow orchestration.
+ *
+ * Implements:
+ * - RFC 9728: OAuth 2.0 Protected Resource Metadata
+ * - RFC 8414 & OpenID Connect: Authorization Server Metadata
+ * - RFC 9207: Authorization Server Issuer Identification
+ * - RFC 8707: Resource Indicators
+ * - RFC 7636: PKCE (S256)
+ *
+ * @module
+ */
+import type { AuthorizationServerMetadata, CreatePkceFlowOptions, ExchangePkceCodeOptions, ExchangePkceCodeResult, OAuth2Credential, OAuthTokens, PkceFlowResult, ProtectedResourceMetadata, RefreshOAuthTokenOptions } from './types.js';
+/**
+ * Discover Protected Resource Metadata (RFC 9728 Section 3).
+ * Fetches `/.well-known/oauth-protected-resource`.
+ */
+export declare function discoverResourceMetadata(resourceUrl: string, fetchFn?: typeof fetch): Promise<ProtectedResourceMetadata>;
+export declare function discoverAuthServerMetadata(authServerUrl: string, fetchFn?: typeof fetch): Promise<AuthorizationServerMetadata>;
+/**
+ * Initiate an OAuth 2.1 PKCE authorization flow statelesssly.
+ *
+ * Discovers resource & AS metadata (or uses preResolved), generates PKCE code_verifier/code_challenge,
+ * and packs the verifier, expected issuer, and resource into an HMAC-signed state token.
+ */
+export declare function createOAuthPkceFlow(options: CreatePkceFlowOptions): Promise<PkceFlowResult>;
+/**
+ * Validates the authorization response `iss` parameter per RFC 9207 Section 2.4.
+ *
+ * "The client MUST validate that the 'iss' parameter in the authorization response matches
+ * the issuer identifier of the authorization server... using simple string comparison (RFC 3986 Section 6.2.1)."
+ */
+export declare function validateIssuer(expectedIssuer: string, receivedIss?: string): void;
+/**
+ * Exchange authorization code for access and refresh tokens.
+ *
+ * Verifies state HMAC, performs RFC 9207 `iss` validation, and posts
+ * code_verifier and resource to the token_endpoint.
+ */
+export declare function exchangeOAuthPkce(options: ExchangePkceCodeOptions): Promise<ExchangePkceCodeResult>;
+/**
+ * Refresh an expired OAuth 2.1 access token.
+ */
+export declare function refreshOAuthToken(options: RefreshOAuthTokenOptions): Promise<{
+    tokens: OAuthTokens;
+    credential: OAuth2Credential;
+}>;

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

@@ -0,0 +1,278 @@
+/**
+ * RFC-compliant OAuth 2.1 discovery and flow orchestration.
+ *
+ * Implements:
+ * - RFC 9728: OAuth 2.0 Protected Resource Metadata
+ * - RFC 8414 & OpenID Connect: Authorization Server Metadata
+ * - RFC 9207: Authorization Server Issuer Identification
+ * - RFC 8707: Resource Indicators
+ * - RFC 7636: PKCE (S256)
+ *
+ * @module
+ */
+import { computeCodeChallenge, generateCodeVerifier, sealStatePayload, unsealStatePayload, } from './crypto.js';
+/**
+ * Discover Protected Resource Metadata (RFC 9728 Section 3).
+ * Fetches `/.well-known/oauth-protected-resource`.
+ */
+export async function discoverResourceMetadata(resourceUrl, fetchFn = fetch) {
+    const origin = new URL(resourceUrl).origin;
+    const metadataUrl = `${origin}/.well-known/oauth-protected-resource`;
+    const response = await fetchFn(metadataUrl, {
+        headers: { Accept: 'application/json' },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to discover protected resource metadata at ${metadataUrl} (HTTP ${response.status})`);
+    }
+    const data = (await response.json());
+    const authServers = Array.isArray(data.authorization_servers)
+        ? data.authorization_servers
+        : [];
+    if (authServers.length === 0) {
+        throw new Error(`Protected resource metadata at ${metadataUrl} did not declare any authorization_servers`);
+    }
+    return {
+        resource: typeof data.resource === 'string' ? data.resource : resourceUrl,
+        authorization_servers: authServers,
+        scopes_supported: Array.isArray(data.scopes_supported)
+            ? data.scopes_supported
+            : undefined,
+        bearer_methods_supported: Array.isArray(data.bearer_methods_supported)
+            ? data.bearer_methods_supported
+            : undefined,
+    };
+}
+/**
+ * Discover Authorization Server Metadata (RFC 8414 Section 3 & OpenID Connect Discovery 1.0).
+ * Queries `/.well-known/oauth-authorization-server` then `/.well-known/openid-configuration`.
+ */
+function parseAuthServerMetadata(data, fallbackIssuer) {
+    if (typeof data.authorization_endpoint !== 'string' || typeof data.token_endpoint !== 'string') {
+        return undefined;
+    }
+    return {
+        issuer: typeof data.issuer === 'string' ? data.issuer : fallbackIssuer,
+        authorization_endpoint: data.authorization_endpoint,
+        token_endpoint: data.token_endpoint,
+        registration_endpoint: typeof data.registration_endpoint === 'string' ? data.registration_endpoint : undefined,
+        scopes_supported: Array.isArray(data.scopes_supported)
+            ? data.scopes_supported
+            : undefined,
+        response_types_supported: Array.isArray(data.response_types_supported)
+            ? data.response_types_supported
+            : undefined,
+        grant_types_supported: Array.isArray(data.grant_types_supported)
+            ? data.grant_types_supported
+            : undefined,
+        code_challenge_methods_supported: Array.isArray(data.code_challenge_methods_supported)
+            ? data.code_challenge_methods_supported
+            : undefined,
+        authorization_response_iss_parameter_supported: data.authorization_response_iss_parameter_supported === true,
+        client_id_metadata_document_supported: data.client_id_metadata_document_supported === true,
+    };
+}
+export async function discoverAuthServerMetadata(authServerUrl, fetchFn = fetch) {
+    const base = authServerUrl.replace(/\/$/, '');
+    const paths = ['/.well-known/oauth-authorization-server', '/.well-known/openid-configuration'];
+    for (const path of paths) {
+        try {
+            const response = await fetchFn(`${base}${path}`, {
+                headers: { Accept: 'application/json' },
+            });
+            if (!response.ok)
+                continue;
+            const data = (await response.json());
+            const parsed = parseAuthServerMetadata(data, authServerUrl);
+            if (parsed)
+                return parsed;
+        }
+        catch {
+            // Try next discovery endpoint
+        }
+    }
+    throw new Error(`Failed to discover authorization server metadata for "${authServerUrl}"`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+}
+/**
+ * Initiate an OAuth 2.1 PKCE authorization flow statelesssly.
+ *
+ * Discovers resource & AS metadata (or uses preResolved), generates PKCE code_verifier/code_challenge,
+ * and packs the verifier, expected issuer, and resource into an HMAC-signed state token.
+ */
+export async function createOAuthPkceFlow(options) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const pre = options.preResolved;
+    let issuer = pre?.issuer;
+    let authEndpoint = pre?.authorizationEndpoint;
+    let resource = pre?.resource;
+    if (!authEndpoint || !issuer) {
+        let asUrl = options.resourceServerUrl;
+        try {
+            // 1. Try RFC 9728 discovery on resource server
+            const resourceMeta = await discoverResourceMetadata(options.resourceServerUrl, fetchFn);
+            resource = resourceMeta.resource;
+            asUrl = resourceMeta.authorization_servers[0];
+        }
+        catch {
+            // If resource discovery fails, treat resourceServerUrl as direct AS URL
+            resource = options.resourceServerUrl;
+        }
+        // 2. Discover AS metadata
+        const asMeta = await discoverAuthServerMetadata(asUrl, fetchFn);
+        issuer = asMeta.issuer;
+        authEndpoint = asMeta.authorization_endpoint;
+    }
+    // 3. Generate PKCE verifier and S256 challenge
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = await computeCodeChallenge(codeVerifier);
+    // 4. Seal stateless state envelope
+    const ttl = options.stateTtlMs ?? 10 * 60 * 1000; // 10 mins
+    const state = await sealStatePayload({
+        codeVerifier,
+        expectedIssuer: issuer,
+        resource,
+        redirectUri: options.redirectUri,
+        expiresAt: Date.now() + ttl,
+        clientId: options.clientId,
+    }, options.signingSecret);
+    // 5. Construct authorization URL
+    const authUrl = new URL(authEndpoint);
+    authUrl.searchParams.set('response_type', 'code');
+    authUrl.searchParams.set('client_id', options.clientId);
+    authUrl.searchParams.set('redirect_uri', options.redirectUri);
+    authUrl.searchParams.set('code_challenge', codeChallenge);
+    authUrl.searchParams.set('code_challenge_method', 'S256');
+    authUrl.searchParams.set('state', state);
+    if (resource) {
+        authUrl.searchParams.set('resource', resource);
+    }
+    if (options.scopes && options.scopes.length > 0) {
+        authUrl.searchParams.set('scope', options.scopes.join(' '));
+    }
+    return {
+        authorizationUrl: authUrl.toString(),
+        state,
+        codeVerifier,
+        codeChallenge,
+        issuer,
+        resource,
+    };
+}
+/**
+ * Validates the authorization response `iss` parameter per RFC 9207 Section 2.4.
+ *
+ * "The client MUST validate that the 'iss' parameter in the authorization response matches
+ * the issuer identifier of the authorization server... using simple string comparison (RFC 3986 Section 6.2.1)."
+ */
+export function validateIssuer(expectedIssuer, receivedIss) {
+    if (!receivedIss) {
+        // If not provided, allowed only if AS did not support it, but if provided, must match exactly
+        return;
+    }
+    // Simple byte-exact string comparison (no URL normalization per 2026-07-28 spec)
+    if (expectedIssuer !== receivedIss) {
+        throw new Error(`RFC 9207 Issuer mismatch detected (potential mix-up attack): expected "${expectedIssuer}", received "${receivedIss}"`);
+    }
+}
+/**
+ * POST a form-encoded token request and parse the response.
+ *
+ * The authorization-code exchange and the refresh flow differ only in the body
+ * they send and the label on a failure, so the transport, the error shape, and
+ * the expiry computation live here once.
+ */
+async function postTokenRequest(fetchFn, tokenEndpoint, body, failureLabel) {
+    const response = await fetchFn(tokenEndpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'application/json',
+        },
+        body: body.toString(),
+    });
+    if (!response.ok) {
+        const errText = await response.text();
+        throw new Error(`${failureLabel} at ${tokenEndpoint} (HTTP ${response.status}): ${errText}`);
+    }
+    const tokens = (await response.json());
+    const expiresAt = tokens.expires_in !== undefined ? Date.now() + tokens.expires_in * 1000 : undefined;
+    return { tokens, expiresAt };
+}
+/**
+ * Exchange authorization code for access and refresh tokens.
+ *
+ * Verifies state HMAC, performs RFC 9207 `iss` validation, and posts
+ * code_verifier and resource to the token_endpoint.
+ */
+export async function exchangeOAuthPkce(options) {
+    const fetchFn = options.fetchFn ?? fetch;
+    // 1. Unseal state envelope and verify HMAC + expiration
+    const statePayload = await unsealStatePayload(options.state, options.signingSecret);
+    // Validate redirect_uri matches authorization request per RFC 6749 Section 4.1.3
+    const effectiveRedirectUri = options.redirectUri || statePayload.redirectUri;
+    if (options.redirectUri &&
+        statePayload.redirectUri &&
+        options.redirectUri !== statePayload.redirectUri) {
+        throw new Error(`Redirect URI mismatch: expected "${statePayload.redirectUri}", received "${options.redirectUri}"`);
+    }
+    // 2. Validate RFC 9207 issuer
+    validateIssuer(statePayload.expectedIssuer, options.iss);
+    // 3. Resolve token endpoint
+    let tokenEndpoint = options.tokenEndpoint;
+    if (!tokenEndpoint) {
+        const asMeta = await discoverAuthServerMetadata(statePayload.expectedIssuer, fetchFn);
+        tokenEndpoint = asMeta.token_endpoint;
+    }
+    // 4. POST to token endpoint
+    const body = new URLSearchParams();
+    body.set('grant_type', 'authorization_code');
+    body.set('code', options.code);
+    body.set('redirect_uri', effectiveRedirectUri);
+    body.set('client_id', statePayload.clientId);
+    body.set('code_verifier', statePayload.codeVerifier);
+    if (statePayload.resource) {
+        body.set('resource', statePayload.resource);
+    }
+    const { tokens, expiresAt } = await postTokenRequest(fetchFn, tokenEndpoint, body, 'Token exchange failed');
+    const credential = {
+        type: 'oauth2',
+        issuer: statePayload.expectedIssuer,
+        resource: statePayload.resource,
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresAt,
+        tokenEndpoint,
+        clientId: statePayload.clientId,
+        scope: tokens.scope,
+    };
+    return { tokens, credential };
+}
+/**
+ * Refresh an expired OAuth 2.1 access token.
+ */
+export async function refreshOAuthToken(options) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const body = new URLSearchParams();
+    body.set('grant_type', 'refresh_token');
+    body.set('refresh_token', options.refreshToken);
+    body.set('client_id', options.clientId);
+    if (options.resource) {
+        body.set('resource', options.resource);
+    }
+    if (options.scope) {
+        body.set('scope', options.scope);
+    }
+    const { tokens, expiresAt } = await postTokenRequest(fetchFn, options.tokenEndpoint, body, 'Token refresh failed');
+    const credential = {
+        type: 'oauth2',
+        issuer: options.issuer,
+        resource: options.resource,
+        accessToken: tokens.access_token,
+        // Preserve existing refresh token if new one is not issued
+        refreshToken: tokens.refresh_token ?? options.refreshToken,
+        expiresAt,
+        tokenEndpoint: options.tokenEndpoint,
+        clientId: options.clientId,
+        scope: tokens.scope ?? options.scope,
+    };
+    return { tokens, credential };
+}