@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,213 @@
+import type { LexiconOverrides } from '../guardrails/lexicon.js';
+import type { SensitiveGroups } from '../guardrails/sensitive.js';
+import type { ResolvedGuardrailPolicy } from '../guardrails/types.js';
+import type { LiveProfileToolsSpec, ProfileToolsSpec, ToolCallEdit, ToolPhaseEvent } from '../kernel/tools/types.js';
+import type { AttachmentValidationIssue, CompactionSpec, GroundingEvent, ImageProfile, LiveProfile, ModelBinding, ModelId, ProfileOutputsSpec, ProviderEvidence, Source, SpeechProfile, TextProfile, TurnStop, TurnTokens } from '../kernel/types.js';
+import type { ResolvedObservabilityPolicy } from '../observability/types.js';
+/** A URL check as it runs; `false` when off. */
+export type UrlCheckView = false | {
+    hosts: string[];
+    fromTools: boolean;
+};
+/** The bundled egress checks a profile's reply runs through. */
+export interface EgressChecksView {
+    sensitive: SensitiveGroups;
+    boundary: boolean;
+    injection: boolean;
+    images: UrlCheckView;
+    links: UrlCheckView;
+}
+/** Guardrails visible to UI — egress enforcer functions are omitted. */
+export type ProfileGuardrailsView = Pick<ResolvedGuardrailPolicy, 'quota' | 'canary' | 'sanitizeInput' | 'redactSensitive'> & {
+    hasEgress: boolean;
+    /** `null` with no egress check, or a host `enforce` whose checks are its own. */
+    egressChecks: EgressChecksView | null;
+};
+/** Observability visible to UI — TraceSink / onWriteError functions are omitted. */
+export type ProfileObservabilityView = Pick<ResolvedObservabilityPolicy, 'record' | 'sampleRate' | 'include' | 'scrub' | 'resource' | 'retainForDays' | 'rotateAfterMiB'> & {
+    /** false | registered id | 'custom' when writeTo is an inline TraceSink; absent when unset. */
+    writeTo?: false | string;
+    hasOnWriteError: boolean;
+};
+/** Resolved `inputs` — `ProfileInputsSpec` plus `acceptAttr` for file pickers. */
+export interface ProfileInputsInterface {
+    text: boolean;
+    attachments: {
+        accept: string[];
+        acceptAttr: string;
+    } | null;
+    voice: {
+        accept: string[];
+    } | null;
+    maxFiles?: number;
+    maxBytes?: number;
+    maxTurnBytes?: number;
+    limitsByMime?: Record<string, number>;
+    slots?: Record<string, string[]>;
+}
+/** A tool's definition (handler, schemas, endpoint, headers) stays on the host; `t1Policy` too. */
+export type ProfileToolsView = Pick<ProfileToolsSpec, 'allow' | 't2Loader'>;
+/** A model binding as the interface carries it: a compaction `trigger` is a host function. */
+export type ModelBindingView = Omit<ModelBinding, 'compaction'> & {
+    compaction?: Omit<CompactionSpec, 'trigger'>;
+};
+/** `profile.outputs` as the interface carries it: validators are host functions. */
+export type ProfileOutputsView = Omit<ProfileOutputsSpec, 'validation'>;
+/** What the text, image and speech interfaces carry in place of their profile's own fields. */
+export type ComposerInterfaceFields = {
+    models: Record<ModelId, ModelBindingView>;
+    outputs?: ProfileOutputsView;
+    /** Client keys' overrides (`CLIENT_LEXICON_KEYS`), resolved on the host; pass to `lexiconText`. */
+    lexicon: LexiconOverrides;
+    inputs: ProfileInputsInterface;
+    guardrails?: ProfileGuardrailsView;
+    observability?: ProfileObservabilityView;
+    /** Always true — composer turns cancel via `TurnRequest.signal`. */
+    canStop: true;
+};
+export type TextProfileInterface = Omit<TextProfile, 'inputs' | 'tools' | 'guardrails' | 'observability' | 'lexicon' | 'models' | 'outputs'> & ComposerInterfaceFields & {
+    tools: ProfileToolsView;
+    /** From `turnBehaviour.allowSteering` (default true on text). */
+    allowSteering: boolean;
+};
+export type ImageProfileInterface = Omit<ImageProfile, 'inputs' | 'tools' | 'guardrails' | 'observability' | 'lexicon' | 'models' | 'outputs'> & ComposerInterfaceFields & {
+    tools: ProfileToolsView;
+};
+export type SpeechProfileInterface = Omit<SpeechProfile, 'guardrails' | 'observability' | 'lexicon' | 'models' | 'outputs'> & ComposerInterfaceFields;
+export type LiveProfileInterface = Omit<LiveProfile, 'tools' | 'guardrails' | 'observability' | 'lexicon' | 'models'> & {
+    models: Record<ModelId, ModelBindingView>;
+    /** Client keys' overrides (`CLIENT_LEXICON_KEYS`), resolved on the host; pass to `lexiconText`. */
+    lexicon: LexiconOverrides;
+    tools: LiveProfileToolsSpec;
+    guardrails?: ProfileGuardrailsView;
+    observability?: ProfileObservabilityView;
+};
+export type ProfileInterface = TextProfileInterface | ImageProfileInterface | SpeechProfileInterface | LiveProfileInterface;
+/** Turn/chat composer profiles — excludes live (realtime streams, no turn inputs block). */
+export type ComposerProfileInterface = Exclude<ProfileInterface, LiveProfileInterface>;
+export type TranscriptBlockKind = 'user-text' | 'user-attachment' | 'user-voice' | 'thought' | 'text' | 'tool' | 'structured' | 'media' | 'grounding' | 'citation' | 'evidence' | 'error' | 'turn-done';
+export interface TranscriptBlockBase {
+    id: string;
+    kind: TranscriptBlockKind;
+}
+export interface UserTextBlock extends TranscriptBlockBase {
+    kind: 'user-text';
+    text: string;
+}
+export interface UserAttachmentBlock extends TranscriptBlockBase {
+    kind: 'user-attachment' | 'user-voice';
+    name: string;
+    mimeType: string;
+    sizeBytes: number;
+    /** Optional base64 payload for inline image/audio preview in the host UI. */
+    data?: string;
+}
+export interface ThoughtBlock extends TranscriptBlockBase {
+    kind: 'thought';
+    text: string;
+}
+export interface TextBlock extends TranscriptBlockBase {
+    kind: 'text';
+    text: string;
+}
+/** Where a call stands: the latest phase that changes its status. */
+export type ToolCallState = Extract<ToolPhaseEvent, {
+    phase: 'running' | 'gate' | 'complete' | 'error' | 'cancel';
+}>;
+/** One tool call: the model's raw call joined with its phase events by `callId` (`toolCallsOf`). */
+export interface ToolCall {
+    name: string;
+    callId: string;
+    /** What the model proposed. */
+    arguments: Record<string, unknown>;
+    /** The call's `ToolCallRequest.thoughtSignature`: history replays the call with it. */
+    thoughtSignature?: string;
+    /** The call's `ToolCallRequest.stepId`: calls sharing it replay as one assistant message. */
+    stepId?: string;
+    /** The user's edit on approval; `to` is what ran. */
+    edited?: ToolCallEdit;
+    /** What the call is doing, in the tool's words, from its last `running` phase. */
+    activity?: string;
+    /** What the call did, from its `complete` phase. */
+    activityPast?: string;
+    /** Absent while the call has only been made. */
+    state?: ToolCallState;
+    /** When it last started running (epoch ms). */
+    startedAt?: number;
+    /** When it last settled: complete, failed, cancelled or gated (epoch ms). */
+    endedAt?: number;
+    artifacts: unknown[];
+}
+export interface ToolBlock extends TranscriptBlockBase {
+    kind: 'tool';
+    tool: ToolCall;
+}
+export interface StructuredBlock extends TranscriptBlockBase {
+    kind: 'structured';
+    value: unknown;
+}
+export interface MediaBlock extends TranscriptBlockBase {
+    kind: 'media';
+    mimeType: string;
+    /** Base64 for model-generated or attached media. Absent when `url` is set. */
+    data?: string;
+    /** Remote http(s) URL promoted from completed tool output. Absent when `data` is set. */
+    url?: string;
+    /** A smaller copy of `url` for previews, when the tool output offered one. */
+    previewUrl?: string;
+}
+export interface GroundingBlock extends TranscriptBlockBase {
+    kind: 'grounding';
+    grounding: GroundingEvent;
+}
+/** Sources a provider or a tool cited; `callId` names the tool call when a tool did. */
+export interface CitationBlock extends TranscriptBlockBase {
+    kind: 'citation';
+    sources: Source[];
+    callId?: string;
+}
+export interface EvidenceBlock extends TranscriptBlockBase {
+    kind: 'evidence';
+    evidence: ProviderEvidence;
+}
+export interface ErrorBlock extends TranscriptBlockBase {
+    kind: 'error';
+    message: string;
+}
+export interface TurnDoneBlock extends TranscriptBlockBase {
+    kind: 'turn-done';
+    stop?: TurnStop;
+    tokens?: TurnTokens;
+    interactionId?: string;
+    compaction?: boolean;
+    /**
+     * How long the reply has worked so far (ms), approval waits excluded. The host
+     * client stamps it when a run ends, so the time travels with the transcript.
+     */
+    workedMs?: number;
+    /** When the reply last stopped (epoch ms), stamped with `workedMs`. */
+    endedAt?: number;
+}
+export type TranscriptBlock = UserTextBlock | UserAttachmentBlock | ThoughtBlock | TextBlock | ToolBlock | StructuredBlock | MediaBlock | GroundingBlock | CitationBlock | EvidenceBlock | ErrorBlock | TurnDoneBlock;
+export interface PendingAttachment {
+    name: string;
+    mimeType: string;
+    sizeBytes: number;
+    /** Optional base64 payload copied onto the transcript block for UI preview. */
+    data?: string;
+}
+export interface AttachmentValidationResult {
+    ok: boolean;
+    issues: AttachmentValidationIssue[];
+}
+export interface UserTurnDraft {
+    text?: string;
+    attachments?: PendingAttachment[];
+    voice?: PendingAttachment[];
+}
+export interface FoldTurnEventsOptions {
+    showThoughts?: boolean;
+    idPrefix?: string;
+}
+declare function streamThoughtsEnabled(outputs?: ProfileOutputsSpec): boolean;
+export { streamThoughtsEnabled };

package/esm/src/interface/types.js

@@ -0,0 +1,4 @@
+function streamThoughtsEnabled(outputs) {
+    return outputs?.streaming?.streamThoughts !== false;
+}
+export { streamThoughtsEnabled };

package/esm/src/kernel/auth/credential-source.d.ts

@@ -0,0 +1,23 @@
+import type { ToolCredential } from './types.js';
+/**
+ * Where a call's tool credentials come from. The kernel reads a slot only when a
+ * tool that signs in runs, so a turn opens no credential it does not use.
+ */
+export interface ToolCredentialSource {
+    /** The slot's credential, or `undefined` when the person has not signed in. */
+    get(slot: string): Promise<ToolCredential | undefined>;
+    /**
+     * A new credential for the slot: a refreshed OAuth token, or a key typed at a
+     * sign-in gate. The call goes on only once it resolves, so persist it here; a
+     * rotated refresh token lost to a closed stream cannot be recovered.
+     */
+    set(slot: string, credential: ToolCredential): Promise<void>;
+    /**
+     * The secret of a confidential OAuth client, read when the kernel refreshes a token
+     * issued to `clientId`. Omit it for public clients. The secret is the host's, not
+     * the person's, so it never lives on a stored credential.
+     */
+    clientSecret?(clientId: string): Promise<string | undefined>;
+}
+/** A source held in memory, seeded from `initial` (copied, never written back). */
+export declare function memoryCredentialSource(initial?: Readonly<Record<string, ToolCredential>>): ToolCredentialSource;

package/esm/src/kernel/auth/credential-source.js

@@ -0,0 +1,11 @@
+/** A source held in memory, seeded from `initial` (copied, never written back). */
+export function memoryCredentialSource(initial = {}) {
+    const slots = new Map(Object.entries(initial));
+    return {
+        get: (slot) => Promise.resolve(slots.get(slot)),
+        set: (slot, credential) => {
+            slots.set(slot, credential);
+            return Promise.resolve();
+        },
+    };
+}

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

@@ -0,0 +1,51 @@
+/** RFC 4648 base64url, without padding. */
+export declare function toBase64Url(bytes: Uint8Array): string;
+export declare function fromBase64Url(base64url: string): Uint8Array<ArrayBuffer>;
+/** RFC 7636 §4.1: 43 to 128 characters, drawn without modulo bias. */
+export declare function generateCodeVerifier(length?: number): string;
+/** RFC 7636 §4.2 S256. */
+export declare function computeCodeChallenge(verifier: string): Promise<string>;
+export interface SealedStatePayload {
+    codeVerifier: string;
+    expectedIssuer: string;
+    /** RFC 9207: a response without `iss` is refused. */
+    issRequired: boolean;
+    /** Fixed when the flow began. */
+    tokenEndpoint: string;
+    resource: string;
+    redirectUri: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+    clientId: string;
+    /** SHA-256 of the host's session binding. */
+    sessionBinding: string;
+    /** The scopes the flow asked for; a grant may hold none beyond them. Empty asks for the server's default. */
+    scopes: string[];
+}
+/** Encrypted, not only signed: the state crosses the browser and the server, and the PKCE verifier must stay secret. */
+export declare function sealStatePayload(payload: SealedStatePayload, secret: string): Promise<string>;
+export declare function unsealStatePayload(sealed: string, secret: string): Promise<SealedStatePayload>;
+export interface SealSecretInput {
+    plaintext: string;
+    /** The host's sealing key: at least 32 bytes, kept apart from where sealed values are stored. */
+    key: string;
+    /** What the sealed value belongs to, such as owner, slot and row. Opening needs the same list. */
+    binding: readonly string[];
+    /** Names `key`, so a rotated key still opens what an older one sealed. */
+    keyVersion: number;
+}
+/**
+ * Seals a stored credential. AES-256-GCM under a key derived per seal; the key
+ * version and binding are authenticated, so a value copied to another owner,
+ * slot or row does not open.
+ */
+export declare function sealSecret(input: SealSecretInput): Promise<string>;
+export interface OpenSecretInput {
+    sealed: string;
+    /** Every key still in use, by version. */
+    keys: Readonly<Record<number, string>>;
+    /** The binding the value was sealed with. */
+    binding: readonly string[];
+}
+/** Opens what `sealSecret` sealed; throws when the envelope, key version or binding does not match. */
+export declare function openSecret(input: OpenSecretInput): Promise<string>;

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

@@ -0,0 +1,161 @@
+import { base64ToBytes, bytesToBase64 } from '../util/base64.js';
+/** RFC 4648 base64url, without padding. */
+export function toBase64Url(bytes) {
+    return bytesToBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+export function fromBase64Url(base64url) {
+    let base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
+    while (base64.length % 4 !== 0) {
+        base64 += '=';
+    }
+    try {
+        return base64ToBytes(base64);
+    }
+    catch (err) {
+        throw new Error(`Invalid base64url encoding: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** RFC 7636 §4.1: 43 to 128 characters, drawn 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): rejecting above it removes 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;
+}
+/** RFC 7636 §4.2 S256. */
+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));
+}
+/** A secret shorter than 256 bits would be the weak link. */
+const MIN_SECRET_BYTES = 32;
+/** Public domain-separation labels, not secrets: each use of a host secret derives a key no other use shares. */
+const STATE_CONTEXT = 'theorem/oauth-state/v1';
+const SEAL_CONTEXT = 'theorem/sealed-secret/v1';
+const IV_BYTES = 12;
+/** A fresh salt per seal gives every seal its own key, so no key sees enough random nonces for one to repeat. */
+const SALT_BYTES = 32;
+/** Authenticated with the ciphertext, so a later scheme can be told apart and an old one is never guessed at. */
+const ENVELOPE_VERSION = 'v1';
+async function sealKey(secret, salt, info, label) {
+    const encoder = new TextEncoder();
+    const secretBytes = encoder.encode(secret);
+    if (secretBytes.length < MIN_SECRET_BYTES) {
+        throw new RangeError(`${label} must be at least ${MIN_SECRET_BYTES} bytes; got ${secretBytes.length}`);
+    }
+    const base = await crypto.subtle.importKey('raw', secretBytes, 'HKDF', false, ['deriveKey']);
+    return crypto.subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt: salt, info: encoder.encode(info) }, base, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+/** `salt.iv.ciphertext`, base64url: AES-256-GCM under a key derived per seal. */
+async function sealBytes(plaintext, secret, scheme) {
+    const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+    const key = await sealKey(secret, salt, scheme.info, scheme.label);
+    const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+    const ciphertext = await crypto.subtle.encrypt({
+        name: 'AES-GCM',
+        iv: iv,
+        additionalData: new TextEncoder().encode(scheme.associatedData),
+    }, key, new TextEncoder().encode(plaintext));
+    return [toBase64Url(salt), toBase64Url(iv), toBase64Url(new Uint8Array(ciphertext))].join('.');
+}
+/** The plaintext `sealBytes` sealed, or null when the envelope does not open under this secret and data. */
+async function openBytes(parts, secret, scheme) {
+    const [saltB64, ivB64, ciphertextB64] = parts;
+    if (saltB64 === undefined || ivB64 === undefined || ciphertextB64 === undefined)
+        return null;
+    const key = await sealKey(secret, fromBase64Url(saltB64), scheme.info, scheme.label);
+    try {
+        const plaintext = await crypto.subtle.decrypt({
+            name: 'AES-GCM',
+            iv: fromBase64Url(ivB64),
+            additionalData: new TextEncoder().encode(scheme.associatedData),
+        }, key, fromBase64Url(ciphertextB64));
+        return new TextDecoder().decode(plaintext);
+    }
+    catch {
+        return null;
+    }
+}
+const STATE_SCHEME = {
+    info: STATE_CONTEXT,
+    label: 'OAuth state secret', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    associatedData: ENVELOPE_VERSION,
+};
+/** Encrypted, not only signed: the state crosses the browser and the server, and the PKCE verifier must stay secret. */
+export async function sealStatePayload(payload, secret) {
+    const envelope = await sealBytes(JSON.stringify(payload), secret, STATE_SCHEME);
+    return [ENVELOPE_VERSION, envelope].join('.');
+}
+export async function unsealStatePayload(sealed, secret) {
+    const [version, ...parts] = sealed.split('.');
+    if (version !== ENVELOPE_VERSION || parts.length !== 3) {
+        throw new Error('Invalid sealed state format'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const plaintext = await openBytes(parts, secret, STATE_SCHEME);
+    if (plaintext === null) {
+        throw new Error('OAuth state could not be opened: it was tampered with, corrupted, or sealed with another secret');
+    }
+    const payload = JSON.parse(plaintext);
+    if (!Array.isArray(payload.scopes)) {
+        throw new Error('Invalid sealed state format'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    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;
+}
+function secretScheme(keyVersion, binding) {
+    return {
+        info: SEAL_CONTEXT,
+        label: 'Secret sealing key', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        associatedData: JSON.stringify([ENVELOPE_VERSION, keyVersion, binding]),
+    };
+}
+function assertKeyVersion(keyVersion) {
+    if (!Number.isSafeInteger(keyVersion) || keyVersion < 0) {
+        throw new RangeError(`Key version must be a non-negative integer; got ${keyVersion}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+/**
+ * Seals a stored credential. AES-256-GCM under a key derived per seal; the key
+ * version and binding are authenticated, so a value copied to another owner,
+ * slot or row does not open.
+ */
+export async function sealSecret(input) {
+    assertKeyVersion(input.keyVersion);
+    const scheme = secretScheme(input.keyVersion, input.binding);
+    const envelope = await sealBytes(input.plaintext, input.key, scheme);
+    return [ENVELOPE_VERSION, String(input.keyVersion), envelope].join('.');
+}
+/** Opens what `sealSecret` sealed; throws when the envelope, key version or binding does not match. */
+export async function openSecret(input) {
+    const [version, keyVersionText, ...parts] = input.sealed.split('.');
+    const keyVersion = Number(keyVersionText);
+    if (version !== ENVELOPE_VERSION || parts.length !== 3 || !/^\d+$/.test(keyVersionText ?? '')) {
+        throw new Error('Invalid sealed secret format'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const key = input.keys[keyVersion];
+    if (key === undefined) {
+        throw new Error(`No key for sealed secret key version ${keyVersion}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const plaintext = await openBytes(parts, key, secretScheme(keyVersion, input.binding));
+    if (plaintext === null) {
+        throw new Error('Sealed secret could not be opened: it was tampered with, bound to something else, or sealed with another key');
+    }
+    return plaintext;
+}

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

@@ -0,0 +1,5 @@
+export * from './credential-source.js';
+export * from './crypto.js';
+export * from './oauth.js';
+export * from './typed-secret.js';
+export * from './types.js';

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

@@ -0,0 +1,5 @@
+export * from './credential-source.js';
+export * from './crypto.js';
+export * from './oauth.js';
+export * from './typed-secret.js';
+export * from './types.js';

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

@@ -0,0 +1,17 @@
+import type { AuthorizationServerMetadata, CreatePkceFlowOptions, ExchangePkceCodeOptions, ExchangePkceCodeResult, OAuthTransportOptions, PkceFlowResult, ProtectedResourceMetadata, RefreshOAuthTokenOptions } from './types.js';
+/** `undefined` on HTTP 404. RFC 9728 §3.3: a `resource` not identical to `resourceUrl` is refused. */
+export declare function discoverResourceMetadata(resourceUrl: string, transport?: OAuthTransportOptions): Promise<ProtectedResourceMetadata | undefined>;
+/** A non-OK URL moves on to the next; metadata that answers but fails validation is refused outright. */
+export declare function discoverAuthServerMetadata(issuer: string, transport?: OAuthTransportOptions): Promise<AuthorizationServerMetadata>;
+/** Stateless: the verifier, expected issuer, token endpoint and resource are sealed into `state`. */
+export declare function createOAuthPkceFlow(options: CreatePkceFlowOptions): Promise<PkceFlowResult>;
+/** RFC 9207 §2.4: `iss` is required when the server advertises it, and byte-exact (no URL normalization). */
+export declare function validateIssuer(expectedIssuer: string, receivedIss: string | undefined, issRequired: boolean): void;
+/**
+ * Requires the session that began the flow (RFC 6749 §10.12), the same `redirect_uri` (§4.1.3)
+ * and a valid `iss` (RFC 9207); posts to the token endpoint sealed in `state`, never a caller's.
+ */
+export declare function exchangeOAuthPkce(options: ExchangePkceCodeOptions): Promise<ExchangePkceCodeResult>;
+export declare function refreshOAuthToken(options: RefreshOAuthTokenOptions): Promise<ExchangePkceCodeResult>;
+/** RFC 8707: the same origin, and the resource's path or below it. */
+export declare function tokenAudienceCovers(resource: string, url: URL): boolean;