theorum 0.1.15 → 1.1.3

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 };
+}

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

@@ -0,0 +1,133 @@
+/**
+ * OAuth 2.1 and Model Context Protocol authorization types.
+ *
+ * Implements current July 28, 2026 MCP specification requirements:
+ * - RFC 9728: Protected Resource Metadata
+ * - RFC 8414 & OpenID Connect: Authorization Server Metadata
+ * - RFC 9207: Authorization Server Issuer Identification (`iss` validation)
+ * - RFC 8707: Resource Indicators
+ * - RFC 7636: PKCE with S256
+ *
+ * @module
+ */
+/** RFC 9728 Protected Resource Metadata */
+export interface ProtectedResourceMetadata {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported?: string[];
+    bearer_methods_supported?: string[];
+    resource_documentation?: string;
+    [key: string]: unknown;
+}
+/** RFC 8414 / OpenID Connect Discovery Metadata */
+export interface AuthorizationServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+    scopes_supported?: string[];
+    response_types_supported?: string[];
+    grant_types_supported?: string[];
+    code_challenge_methods_supported?: string[];
+    authorization_response_iss_parameter_supported?: boolean;
+    client_id_metadata_document_supported?: boolean;
+    [key: string]: unknown;
+}
+/** Standard OAuth 2.1 token response */
+export interface OAuthTokens {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+    /** Custom extra parameters returned by AS */
+    [key: string]: unknown;
+}
+/** Normalized OAuth credential for storage / pass-through in TurnRequest */
+export interface OAuth2Credential {
+    type: 'oauth2';
+    issuer: string;
+    resource?: string;
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    tokenEndpoint: string;
+    clientId: string;
+    scope?: string;
+}
+/** Bearer token credential */
+export interface BearerCredential {
+    type: 'bearer';
+    token: string;
+}
+/** API key credential */
+export interface ApiKeyCredential {
+    type: 'api_key';
+    key: string;
+    headerName?: string;
+    headerPrefix?: string;
+}
+/** Universal union of supported tool credentials */
+export type ToolCredential = OAuth2Credential | BearerCredential | ApiKeyCredential;
+/** Options for creating an OAuth 2.1 PKCE authorization flow */
+export interface CreatePkceFlowOptions {
+    /** Target resource server URL (e.g. MCP server URL) or direct AS URL */
+    resourceServerUrl: string;
+    /** The OAuth client id or Client ID Metadata Document HTTPS URL */
+    clientId: string;
+    /** Redirect URI registered with the OAuth client */
+    redirectUri: string;
+    /** Desired scopes */
+    scopes?: string[];
+    /** Secret string used to HMAC-sign the stateless state envelope */
+    signingSecret: string;
+    /** State envelope TTL in milliseconds (default: 10 minutes) */
+    stateTtlMs?: number;
+    /** Optional pre-resolved discovery metadata to bypass runtime fetch */
+    preResolved?: {
+        issuer?: string;
+        authorizationEndpoint?: string;
+        tokenEndpoint?: string;
+        resource?: string;
+    };
+    /** Optional fetch function for testing or proxying */
+    fetchFn?: typeof fetch;
+}
+/** Result of initiating a PKCE flow */
+export interface PkceFlowResult {
+    authorizationUrl: string;
+    state: string;
+    codeVerifier: string;
+    codeChallenge: string;
+    issuer: string;
+    resource?: string;
+}
+/** Options for exchanging an authorization code */
+export interface ExchangePkceCodeOptions {
+    code: string;
+    state: string;
+    /** `iss` parameter returned in the authorization response query (RFC 9207) */
+    iss?: string;
+    /** Redirect URI matching the authorization request */
+    redirectUri: string;
+    /** Secret used to sign the state envelope */
+    signingSecret: string;
+    /** Optional token endpoint override (defaults to discovered AS token_endpoint) */
+    tokenEndpoint?: string;
+    fetchFn?: typeof fetch;
+}
+/** Result of token exchange */
+export interface ExchangePkceCodeResult {
+    tokens: OAuthTokens;
+    credential: OAuth2Credential;
+}
+/** Options for refreshing an expired OAuth token */
+export interface RefreshOAuthTokenOptions {
+    refreshToken: string;
+    tokenEndpoint: string;
+    clientId: string;
+    resource?: string;
+    scope?: string;
+    issuer: string;
+    fetchFn?: typeof fetch;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * OAuth 2.1 and Model Context Protocol authorization types.
+ *
+ * Implements current July 28, 2026 MCP specification requirements:
+ * - RFC 9728: Protected Resource Metadata
+ * - RFC 8414 & OpenID Connect: Authorization Server Metadata
+ * - RFC 9207: Authorization Server Issuer Identification (`iss` validation)
+ * - RFC 8707: Resource Indicators
+ * - RFC 7636: PKCE with S256
+ *
+ * @module
+ */
+export {};

package/esm/src/kernel/engine/delta.d.ts

@@ -1,8 +1,30 @@
 import type { TurnEvent, TurnTokens } from '../types.js';
+declare function isCodeExecutionType(type: string): boolean;
+declare function isGoogleBuiltinStepType(type: string): boolean;
+declare function googleBuiltinEvidence(raw: Record<string, unknown>): TurnEvent;
+/** Merge a later code-exec delta/step onto an earlier snapshot (partial code/stdout). */
+declare function mergeCodeExecutionPayload(existing: Record<string, unknown> | undefined, incoming: Record<string, unknown>): Record<string, unknown>;
+/** Normalize a Google `code_execution_*` step/delta into an `evidence` event. */
+declare function codeExecutionEvidence(raw: Record<string, unknown>): TurnEvent;
+/** Stable key so streamed deltas and batched `steps[]` do not double-emit. */
+declare function codeExecutionStepKey(raw: Record<string, unknown>, index?: number): string;
 declare function eventsFromDelta(deltaValue: unknown): TurnEvent[];
+/**
+ * Replay a completed Interactions `steps[]` array (non-SSE or stream tail).
+ * Emits typed code-execution evidence plus model_output text/media.
+ */
+declare function eventsFromInteractionSteps(steps: unknown[], alreadyText: boolean): TurnEvent[];
 declare function groundingFromEvent(event: Record<string, unknown>): TurnEvent | undefined;
 declare function extractUsageTokens(raw: unknown): TurnTokens | undefined;
 declare function extractTokenEvent(event: Record<string, unknown>, interaction?: Record<string, unknown>): TurnEvent | undefined;
 declare function eventsFromComplete(event: Record<string, unknown>, alreadyText: boolean): TurnEvent[];
-declare function tryStructured(text: string): TurnEvent | undefined;
-export { eventsFromComplete, eventsFromDelta, extractTokenEvent, extractUsageTokens, groundingFromEvent, tryStructured, };
+export type ParsedStructuredOutput = {
+    ok: true;
+    structured: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/** Parse model text as structured JSON. Invalid JSON is a hard failure — never silent skip. */
+declare function parseStructuredOutput(text: string): ParsedStructuredOutput;
+export { codeExecutionEvidence, codeExecutionStepKey, eventsFromComplete, eventsFromDelta, eventsFromInteractionSteps, extractTokenEvent, extractUsageTokens, googleBuiltinEvidence, groundingFromEvent, isCodeExecutionType, isGoogleBuiltinStepType, mergeCodeExecutionPayload, parseStructuredOutput, };