@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,439 @@
+import { fetchGuarded } from '../../guardrails/network.js';
+import { isRecord } from '../util/record.js';
+import { computeCodeChallenge, generateCodeVerifier, sealStatePayload, toBase64Url, unsealStatePayload, } from './crypto.js';
+const HTTP_NOT_FOUND = 404;
+/** Never follows a redirect: it would carry codes and refresh tokens somewhere nobody vetted. */
+function oauthFetch(url, init, transport) {
+    return fetchGuarded(url, init, {
+        policy: transport.network,
+        followRedirects: false,
+        resolveHost: transport.resolveHost,
+        ...(transport.fetchFn ? { fetchFn: transport.fetchFn } : {}),
+    });
+}
+/** RFC 8414 §2, RFC 9728 §1.2, OAuth 2.1 §1.5: an absolute `https` URL without a fragment. */
+function httpsUrl(value, what) {
+    if (typeof value !== 'string') {
+        throw new Error(`OAuth ${what} is missing`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`OAuth ${what} "${value}" is not a URL`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (url.protocol !== 'https:' || url.hash) {
+        throw new Error(`OAuth ${what} "${value}" must be an https URL without a fragment`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return url;
+}
+/** RFC 8252 §7.3: the loopback hosts an `http` redirect may name. */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '[::1]', 'localhost']);
+/**
+ * RFC 6749 §3.1.2: no fragment; `https`, `http` on loopback (RFC 8252 §7.3), or a
+ * reverse-domain private-use scheme for a native app (RFC 8252 §7.1).
+ */
+function assertRedirectUri(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`OAuth redirect_uri "${value}" is not an absolute URI`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const scheme = url.protocol.slice(0, -1);
+    const allowed = scheme === 'https' ||
+        (scheme === 'http' && LOOPBACK_HOSTS.has(url.hostname)) ||
+        (scheme !== 'http' && scheme.includes('.'));
+    if (!allowed || value.includes('#')) {
+        throw new Error(`OAuth redirect_uri "${value}" must be https, http on loopback, or a reverse-domain app scheme, without a fragment`);
+    }
+}
+/** RFC 6749 §3.3: a scope token is one or more printable ASCII characters other than space, `"`, and `\`. */
+const SCOPE_TOKEN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
+function assertScopeTokens(scopes) {
+    for (const scope of scopes) {
+        if (!SCOPE_TOKEN.test(scope)) {
+            throw new Error(`OAuth scope "${scope}" is not a single RFC 6749 scope token`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    }
+}
+/** Names the flow sets itself; a provider's own parameters may not replace them. */
+const FLOW_PARAMS = new Set([
+    'response_type',
+    'client_id',
+    'redirect_uri',
+    'code_challenge',
+    'code_challenge_method',
+    'state',
+    'resource',
+    'scope',
+]);
+function assertAuthorizationParams(params) {
+    for (const name of Object.keys(params)) {
+        if (FLOW_PARAMS.has(name)) {
+            throw new Error(`OAuth authorization parameter "${name}" is set by the flow and cannot be passed`);
+        }
+    }
+}
+/** A client id that is a URL is a Client ID Metadata Document, which is served over https. */
+function assertClientId(clientId) {
+    if (clientId.length === 0) {
+        throw new Error('OAuth client_id is missing'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (/^https?:/i.test(clientId))
+        httpsUrl(clientId, 'client_id');
+}
+/** RFC 8414 §3.1, RFC 9728 §3.1: `/.well-known/<suffix>` goes between the host and the path. */
+function wellKnownUrl(identifier, suffix) {
+    const path = identifier.pathname.replace(/\/$/, '');
+    return `${identifier.origin}/.well-known/${suffix}${path}${identifier.search}`;
+}
+function stringList(data, field) {
+    const value = data[field];
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string')) {
+        throw new Error(`OAuth metadata "${field}" must be a list of strings`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return value;
+}
+async function metadataObject(response, url) {
+    const data = await response.json();
+    if (!isRecord(data)) {
+        throw new Error(`OAuth metadata at ${url} is not a JSON object`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return data;
+}
+/** `undefined` on HTTP 404. RFC 9728 §3.3: a `resource` not identical to `resourceUrl` is refused. */
+export async function discoverResourceMetadata(resourceUrl, transport = {}) {
+    const metadataUrl = wellKnownUrl(httpsUrl(resourceUrl, 'resource'), 'oauth-protected-resource');
+    const response = await oauthFetch(metadataUrl, { headers: { Accept: 'application/json' } }, transport);
+    if (response.status === HTTP_NOT_FOUND) {
+        await response.body?.cancel();
+        return undefined;
+    }
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error(`Failed to discover protected resource metadata at ${metadataUrl} (HTTP ${response.status})`);
+    }
+    const data = await metadataObject(response, metadataUrl);
+    if (data.resource !== resourceUrl) {
+        throw new Error(`Protected resource metadata at ${metadataUrl} is for "${String(data.resource)}", not "${resourceUrl}"`);
+    }
+    const authServers = stringList(data, 'authorization_servers') ?? [];
+    if (authServers.length === 0) {
+        throw new Error(`Protected resource metadata at ${metadataUrl} did not declare any authorization_servers`);
+    }
+    for (const server of authServers)
+        httpsUrl(server, 'authorization server');
+    return {
+        resource: resourceUrl,
+        authorization_servers: authServers,
+        scopes_supported: stringList(data, 'scopes_supported'),
+        bearer_methods_supported: stringList(data, 'bearer_methods_supported'),
+    };
+}
+/** RFC 8414 §3.3: the `issuer` must be identical to the one it was fetched for. */
+function parseAuthServerMetadata(data, issuer, url) {
+    if (data.issuer !== issuer) {
+        throw new Error(`Authorization server metadata at ${url} names issuer "${String(data.issuer)}", not "${issuer}"`);
+    }
+    const authorizationEndpoint = httpsUrl(data.authorization_endpoint, 'authorization_endpoint');
+    const tokenEndpoint = httpsUrl(data.token_endpoint, 'token_endpoint');
+    const registrationEndpoint = data.registration_endpoint === undefined
+        ? undefined
+        : httpsUrl(data.registration_endpoint, 'registration_endpoint');
+    return {
+        issuer,
+        authorization_endpoint: authorizationEndpoint.href,
+        token_endpoint: tokenEndpoint.href,
+        registration_endpoint: registrationEndpoint?.href,
+        scopes_supported: stringList(data, 'scopes_supported'),
+        response_types_supported: stringList(data, 'response_types_supported'),
+        grant_types_supported: stringList(data, 'grant_types_supported'),
+        code_challenge_methods_supported: stringList(data, 'code_challenge_methods_supported'),
+        authorization_response_iss_parameter_supported: data.authorization_response_iss_parameter_supported === true,
+        client_id_metadata_document_supported: data.client_id_metadata_document_supported === true,
+    };
+}
+/** In order: RFC 8414, then OIDC Discovery with the well-known inserted, then appended for a path. */
+function authServerMetadataUrls(issuer) {
+    const urls = [
+        wellKnownUrl(issuer, 'oauth-authorization-server'),
+        wellKnownUrl(issuer, 'openid-configuration'),
+    ];
+    const path = issuer.pathname.replace(/\/$/, '');
+    if (path)
+        urls.push(`${issuer.origin}${path}/.well-known/openid-configuration`);
+    return urls;
+}
+/** A non-OK URL moves on to the next; metadata that answers but fails validation is refused outright. */
+export async function discoverAuthServerMetadata(issuer, transport = {}) {
+    const issuerUrl = httpsUrl(issuer, 'issuer');
+    if (issuerUrl.search) {
+        throw new Error(`OAuth issuer "${issuer}" must not have a query`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    for (const url of authServerMetadataUrls(issuerUrl)) {
+        const response = await oauthFetch(url, { headers: { Accept: 'application/json' } }, transport);
+        if (!response.ok) {
+            await response.body?.cancel();
+            continue;
+        }
+        return parseAuthServerMetadata(await metadataObject(response, url), issuer, url);
+    }
+    throw new Error(`Failed to discover authorization server metadata for "${issuer}"`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+}
+/** A resource that publishes no metadata is its own authorization server. */
+async function discoverEndpoints(resourceServerUrl, transport) {
+    const resourceMeta = await discoverResourceMetadata(resourceServerUrl, transport);
+    const issuer = resourceMeta?.authorization_servers[0] ?? resourceServerUrl;
+    const asMeta = await discoverAuthServerMetadata(issuer, transport);
+    if (!asMeta.code_challenge_methods_supported?.includes('S256')) {
+        throw new Error(`Authorization server "${issuer}" does not advertise S256 PKCE (code_challenge_methods_supported)`);
+    }
+    return {
+        issuer: asMeta.issuer,
+        authorizationEndpoint: asMeta.authorization_endpoint,
+        tokenEndpoint: asMeta.token_endpoint,
+        issParameterSupported: asMeta.authorization_response_iss_parameter_supported === true,
+    };
+}
+/** Stateless: the verifier, expected issuer, token endpoint, and resource are sealed into `state`. */
+export async function createOAuthPkceFlow(options) {
+    const endpoints = options.preResolved ?? (await discoverEndpoints(options.resourceServerUrl, options));
+    httpsUrl(endpoints.issuer, 'issuer');
+    const authUrl = httpsUrl(endpoints.authorizationEndpoint, 'authorization_endpoint');
+    const tokenEndpoint = httpsUrl(endpoints.tokenEndpoint, 'token_endpoint').href;
+    const { issuer } = endpoints;
+    // why: RFC 8707 audience: always the resource the flow is for; discovery required its metadata to match.
+    httpsUrl(options.resourceServerUrl, 'resource');
+    const resource = options.resourceServerUrl;
+    assertClientId(options.clientId);
+    assertRedirectUri(options.redirectUri);
+    if (options.scopes)
+        assertScopeTokens(options.scopes);
+    if (options.authorizationParams)
+        assertAuthorizationParams(options.authorizationParams);
+    const ttl = options.stateTtlMs ?? 10 * 60 * 1000;
+    if (!Number.isFinite(ttl) || ttl <= 0) {
+        throw new RangeError(`OAuth stateTtlMs must be a positive number of milliseconds; got ${ttl}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const sessionBinding = await sessionBindingDigest(options.sessionBinding);
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = await computeCodeChallenge(codeVerifier);
+    const state = await sealStatePayload({
+        codeVerifier,
+        expectedIssuer: issuer,
+        issRequired: endpoints.issParameterSupported === true,
+        tokenEndpoint,
+        resource,
+        redirectUri: options.redirectUri,
+        expiresAt: Date.now() + ttl,
+        clientId: options.clientId,
+        sessionBinding,
+        scopes: options.scopes ? [...options.scopes] : [],
+    }, options.signingSecret);
+    for (const [name, value] of Object.entries(options.authorizationParams ?? {})) {
+        authUrl.searchParams.set(name, value);
+    }
+    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);
+    authUrl.searchParams.set('resource', resource);
+    if (options.scopes && options.scopes.length > 0) {
+        authUrl.searchParams.set('scope', options.scopes.join(' '));
+    }
+    return {
+        authorizationUrl: authUrl.toString(),
+        state,
+        codeChallenge,
+        issuer,
+        resource,
+    };
+}
+/** SHA-256 of the host's session binding, so the raw value never enters the state. */
+async function sessionBindingDigest(binding) {
+    if (binding.length === 0) {
+        throw new Error('OAuth sessionBinding must be a non-empty value tied to the user session'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(binding));
+    return toBase64Url(new Uint8Array(digest));
+}
+/** Compare two digests without an early exit, so timing says nothing about where they differ. */
+function sameDigest(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** RFC 9207 §2.4: `iss` is required when the server advertises it, and byte-exact (no URL normalization). */
+export function validateIssuer(expectedIssuer, receivedIss, issRequired) {
+    if (receivedIss === undefined) {
+        if (issRequired) {
+            throw new Error(`RFC 9207: authorization server "${expectedIssuer}" sends "iss", but the response has none (potential mix-up attack)`);
+        }
+        return;
+    }
+    if (expectedIssuer !== receivedIss) {
+        throw new Error(`RFC 9207 Issuer mismatch detected (potential mix-up attack): expected "${expectedIssuer}", received "${receivedIss}"`);
+    }
+}
+/** RFC 6749 §5.2: `error_description` is printable ASCII without `"` or `\`. */
+const ERROR_DESCRIPTION = /^[\x20\x21\x23-\x5B\x5D-\x7E]*$/;
+/** RFC 6749 §5.2 shape only; any other body is not repeated into the error. */
+async function tokenErrorText(response) {
+    let data;
+    try {
+        data = await response.json();
+    }
+    catch {
+        return '';
+    }
+    if (!isRecord(data))
+        return '';
+    const { error, error_description: description } = data;
+    if (typeof error !== 'string' || !ERROR_DESCRIPTION.test(error))
+        return '';
+    const told = typeof description === 'string' && ERROR_DESCRIPTION.test(description);
+    return told ? `: ${error} (${description})` : `: ${error}`;
+}
+function parseTokenResponse(data, tokenEndpoint) {
+    const fail = (why) => {
+        throw new Error(`Token response from ${tokenEndpoint} ${why}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    };
+    if (!isRecord(data)) {
+        return fail('is not a JSON object'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const tokens = data;
+    if (typeof tokens.access_token !== 'string' || tokens.access_token.length === 0) {
+        fail('has no access_token'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (typeof tokens.token_type !== 'string' || tokens.token_type.toLowerCase() !== 'bearer') {
+        fail(`has token_type "${String(tokens.token_type)}", not Bearer`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const expiresIn = tokens.expires_in;
+    if (expiresIn !== undefined &&
+        (typeof expiresIn !== 'number' || !Number.isFinite(expiresIn) || expiresIn < 0)) {
+        fail('has an expires_in that is not a number of seconds'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    for (const field of ['refresh_token', 'scope']) {
+        if (tokens[field] !== undefined && typeof tokens[field] !== 'string') {
+            fail(`has a ${field} that is not a string`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    }
+    return tokens;
+}
+/** RFC 6749 §3.3: a scope is a list of space-delimited tokens. */
+function scopeTokens(scope) {
+    return scope === undefined ? [] : scope.split(' ').filter((token) => token.length > 0);
+}
+/**
+ * The scopes asked for are the most a grant may hold: a token carrying any other is refused
+ * before it is stored. An empty request asked for the server's default, so it sets no ceiling;
+ * a response without `scope` granted exactly what was asked (RFC 6749 §5.1).
+ */
+function assertGrantWithin(granted, requested, tokenEndpoint) {
+    if (requested.length === 0)
+        return;
+    const beyond = scopeTokens(granted).filter((scope) => !requested.includes(scope));
+    if (beyond.length > 0) {
+        throw new Error(`Token response from ${tokenEndpoint} grants scopes that were not asked for: ${beyond.join(', ')}`);
+    }
+}
+/**
+ * `requested` is the ceiling the grant is held to. A refresh passes `previous`, whose refresh
+ * token and scope stay when the server sends no new ones.
+ */
+async function requestToken(transport, grant, params, requested, previous) {
+    const { clientSecret, ...issued } = grant;
+    const body = new URLSearchParams({
+        ...params,
+        client_id: grant.clientId,
+        ...(clientSecret === undefined ? {} : { client_secret: clientSecret }),
+        resource: grant.resource,
+    });
+    const response = await oauthFetch(grant.tokenEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+        body: body.toString(),
+    }, transport);
+    if (!response.ok) {
+        const failed = previous ? 'Token refresh failed' : 'Token exchange failed'; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`${failed} at ${grant.tokenEndpoint} (HTTP ${response.status})${await tokenErrorText(response)}`);
+    }
+    const tokens = parseTokenResponse(await response.json(), grant.tokenEndpoint);
+    assertGrantWithin(tokens.scope, requested, grant.tokenEndpoint);
+    const credential = {
+        type: 'oauth2',
+        ...issued,
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token ?? previous?.refreshToken,
+        expiresAt: tokens.expires_in === undefined ? undefined : Date.now() + tokens.expires_in * 1000,
+        scope: tokens.scope ?? previous?.scope ?? (requested.length > 0 ? requested.join(' ') : undefined),
+    };
+    return { tokens, credential };
+}
+/**
+ * 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 async function exchangeOAuthPkce(options) {
+    const state = await unsealStatePayload(options.state, options.signingSecret);
+    const presented = await sessionBindingDigest(options.sessionBinding);
+    if (!sameDigest(presented, state.sessionBinding)) {
+        throw new Error('OAuth state belongs to another session: the callback did not come from the session that began the flow');
+    }
+    if (options.redirectUri !== state.redirectUri) {
+        throw new Error(`Redirect URI mismatch: expected "${state.redirectUri}", received "${options.redirectUri}"`);
+    }
+    validateIssuer(state.expectedIssuer, options.iss, state.issRequired);
+    return requestToken(options, {
+        issuer: state.expectedIssuer,
+        resource: state.resource,
+        tokenEndpoint: state.tokenEndpoint,
+        clientId: state.clientId,
+        ...(options.clientSecret === undefined ? {} : { clientSecret: options.clientSecret }),
+    }, {
+        grant_type: 'authorization_code',
+        code: options.code,
+        redirect_uri: state.redirectUri,
+        code_verifier: state.codeVerifier,
+    }, state.scopes);
+}
+/** Exchanges a refresh token for new tokens at the token endpoint; both the endpoint and the resource must be https URLs. */
+export function refreshOAuthToken(options) {
+    httpsUrl(options.tokenEndpoint, 'token_endpoint');
+    httpsUrl(options.resource, 'resource');
+    return requestToken(options, {
+        issuer: options.issuer,
+        resource: options.resource,
+        tokenEndpoint: options.tokenEndpoint,
+        clientId: options.clientId,
+        ...(options.clientSecret === undefined ? {} : { clientSecret: options.clientSecret }),
+    }, {
+        grant_type: 'refresh_token',
+        refresh_token: options.refreshToken,
+        ...(options.scope ? { scope: options.scope } : {}),
+    }, scopeTokens(options.scope), { refreshToken: options.refreshToken, scope: options.scope });
+}
+/** RFC 8707: the same origin, and the resource's path or below it. */
+export function tokenAudienceCovers(resource, url) {
+    let audience;
+    try {
+        audience = new URL(resource);
+    }
+    catch {
+        return false;
+    }
+    if (audience.origin !== url.origin)
+        return false;
+    const base = audience.pathname.replace(/\/$/, '');
+    return url.pathname === base || url.pathname.startsWith(`${base}/`) || base === '';
+}

package/esm/src/kernel/auth/scope-refusal.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/** What a refusal outside the declared scopes streams as `progress`, for the host and the trace. */
+export declare const authScopeRefusedSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"auth_scope_refused">;
+    slot: z.ZodString;
+    requested: z.ZodArray<z.ZodString>;
+    declared: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type AuthScopeRefused = z.infer<typeof authScopeRefusedSchema>;

package/esm/src/kernel/auth/scope-refusal.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/** What a refusal outside the declared scopes streams as `progress`, for the host and the trace. */
+export const authScopeRefusedSchema = z.object({
+    kind: z.literal('auth_scope_refused'),
+    slot: z.string(),
+    requested: z.array(z.string()),
+    declared: z.array(z.string()),
+});

package/esm/src/kernel/auth/typed-secret.d.ts

@@ -0,0 +1,13 @@
+import type { ToolAuthType } from '../schema.js';
+import type { ToolGateAuth } from '../tools/gate-answer.js';
+import type { ApiKeyCredential, BearerCredential } from './types.js';
+/**
+ * The server builds the credential, so the browser cannot pick its kind or header. An OAuth
+ * gate takes no typed secret: its token comes from the host's callback route.
+ */
+export declare function credentialFromTypedSecret(authType: ToolAuthType, secret: unknown): BearerCredential | ApiKeyCredential;
+/** `auth` is absent on any gate other than sign-in, which takes no key. */
+export declare function credentialForSignInGate(auth: Pick<ToolGateAuth, 'slot' | 'authType'> | undefined, secret: unknown): {
+    slot: string;
+    credential: BearerCredential | ApiKeyCredential;
+};

package/esm/src/kernel/auth/typed-secret.js

@@ -0,0 +1,23 @@
+import { TheoremError } from '../../guardrails/error.js';
+/**
+ * The server builds the credential, so the browser cannot pick its kind or header. An OAuth
+ * gate takes no typed secret: its token comes from the host's callback route.
+ */
+export function credentialFromTypedSecret(authType, secret) {
+    const value = typeof secret === 'string' ? secret.trim() : '';
+    if (!value) {
+        throw new TheoremError('request', 'A typed credential must be a non-empty string'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (authType === 'bearer')
+        return { type: 'bearer', token: value };
+    if (authType === 'api_key')
+        return { type: 'api_key', key: value };
+    throw new TheoremError('request', `A '${authType}' sign-in takes no typed credential; the host's callback saves it`);
+}
+/** `auth` is absent on any gate other than sign-in, which takes no key. */
+export function credentialForSignInGate(auth, secret) {
+    if (!auth) {
+        throw new TheoremError('request', 'a typed credential answers only a sign-in gate'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return { slot: auth.slot, credential: credentialFromTypedSecret(auth.authType, secret) };
+}

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

@@ -0,0 +1,152 @@
+import type { ResolveHost } from '../../guardrails/network.js';
+import type { NetworkGuardrailSpec } from '../../guardrails/types.js';
+/** RFC 9728. */
+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. */
+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;
+}
+/** The tokens an OAuth server returns. */
+export interface OAuthTokens {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+    [key: string]: unknown;
+}
+/** An OAuth sign-in a tool authenticates with. */
+export interface OAuth2Credential {
+    type: 'oauth2';
+    issuer: string;
+    /** RFC 8707: the token is sent nowhere else. */
+    resource: string;
+    accessToken: string;
+    refreshToken?: string;
+    /** Epoch milliseconds. */
+    expiresAt?: number;
+    tokenEndpoint: string;
+    clientId: string;
+    scope?: string;
+}
+/** A bearer token a tool authenticates with. */
+export interface BearerCredential {
+    type: 'bearer';
+    token: string;
+}
+/** An API key a tool authenticates with. */
+export interface ApiKeyCredential {
+    type: 'api_key';
+    key: string;
+    /** The header the key goes in; a tool whose `auth.queryParam` puts it in the URL ignores it. */
+    headerName?: string;
+    /** Text put before the key in the header; ignored as `headerName` is. */
+    headerPrefix?: string;
+}
+/** Any credential a tool can authenticate with. */
+export type ToolCredential = OAuth2Credential | BearerCredential | ApiKeyCredential;
+/** Every discovery and token request clears the network policy and never follows a redirect. */
+export interface OAuthTransportOptions {
+    /** Default: https to public hosts. */
+    network?: NetworkGuardrailSpec;
+    /** A host that resolves to a private address is refused. */
+    resolveHost?: ResolveHost;
+    fetchFn?: typeof fetch;
+}
+/** The endpoints of an OAuth authorization server. */
+export interface OAuthEndpoints {
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    /** RFC 9207: authorization responses without `iss` are then refused. */
+    issParameterSupported?: boolean;
+}
+/** Options for starting a PKCE authorization. */
+export interface CreatePkceFlowOptions extends OAuthTransportOptions {
+    /**
+     * An https URL (e.g. the MCP server) and the token's audience (RFC 8707). Without
+     * RFC 9728 metadata of its own it is its own authorization server.
+     */
+    resourceServerUrl: string;
+    /** Or the https URL of its Client ID Metadata Document. */
+    clientId: string;
+    /** No fragment: https, http on loopback (RFC 8252 §7.3), or a reverse-domain app scheme (§7.1). */
+    redirectUri: string;
+    /** Each a single RFC 6749 §3.3 scope token. */
+    scopes?: string[];
+    /**
+     * Encrypts the state envelope: at least 32 bytes and 256 bits of entropy (32 CSPRNG bytes,
+     * base64-encoded), so a quantum search still faces 128-bit work.
+     */
+    signingSecret: string;
+    /**
+     * Bound to the user's session and neither knowable nor settable by an attacker (a session id,
+     * an HttpOnly cookie value). The callback must present it (RFC 6749 §10.12); only its SHA-256 is sealed.
+     */
+    sessionBinding: string;
+    /** Milliseconds; default 10 minutes. */
+    stateTtlMs?: number;
+    /** Skips discovery. */
+    preResolved?: OAuthEndpoints;
+    /**
+     * Parameters a provider reads beyond the standard ones (e.g. Google's
+     * `access_type: 'offline'`, without which it issues no refresh token). A name the
+     * flow sets itself is refused.
+     */
+    authorizationParams?: Readonly<Record<string, string>>;
+}
+/** A started PKCE authorization: the URL to send the user to and the values to keep. */
+export interface PkceFlowResult {
+    authorizationUrl: string;
+    state: string;
+    codeChallenge: string;
+    issuer: string;
+    resource: string;
+}
+/** Options for trading an authorization code for tokens. */
+export interface ExchangePkceCodeOptions extends OAuthTransportOptions {
+    code: string;
+    state: string;
+    /** From the authorization response query (RFC 9207). */
+    iss?: string;
+    /** Must match the authorization request. */
+    redirectUri: string;
+    signingSecret: string;
+    /** Read from the session handling the callback. */
+    sessionBinding: string;
+    /** A confidential client's secret, sent in the token request body (RFC 6749 §2.3.1); never stored. */
+    clientSecret?: string;
+}
+/** The tokens and credential a PKCE exchange yields. */
+export interface ExchangePkceCodeResult {
+    tokens: OAuthTokens;
+    credential: OAuth2Credential;
+}
+/** Options for refreshing an OAuth access token. */
+export interface RefreshOAuthTokenOptions extends OAuthTransportOptions {
+    refreshToken: string;
+    tokenEndpoint: string;
+    clientId: string;
+    resource: string;
+    scope?: string;
+    issuer: string;
+    /** A confidential client's secret, sent in the token request body (RFC 6749 §2.3.1); never stored. */
+    clientSecret?: string;
+}

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

@@ -0,0 +1 @@
+export {};