melchizedek-agents 1.2.0 → 1.3.0

package/dist/lib/tools/oauthConsent.js

@@ -85,7 +85,9 @@ export class ConsentError extends Error {
                                 ? `The authorization at ${p} could not be completed.`
                                 : code === 'store_failed'
                                     ? `The authorization at ${p} could not be saved.`
-                                    : `No OAuth client is configured for ${p}.`);
+                                    : code === 'registration_failed'
+                                        ? `The authorization at ${p} could not be set up.`
+                                        : `No OAuth client is configured for ${p}.`);
         this.name = 'ConsentError';
         this.code = code;
         if (provider !== undefined)
@@ -120,7 +122,21 @@ function checkEndpoint(value, what) {
         throw new Error(`${what} must not carry credentials.`);
     return url;
 }
-const RESERVED_PARAMS = new Set(['state', 'redirect_uri', 'code_challenge', 'code_challenge_method', 'client_id', 'response_type', 'scope']);
+const RESERVED_PARAMS = new Set(['state', 'redirect_uri', 'code_challenge', 'code_challenge_method', 'client_id', 'response_type', 'scope', 'resource']);
+/** A client's configuration, checked: the endpoints, the client id, the parameters. Throws, naming the provider. */
+function checkClient(name, client) {
+    checkEndpoint(client.authorizationUrl, `${name}: authorizationUrl`);
+    checkEndpoint(client.tokenUrl, `${name}: tokenUrl`);
+    if (typeof client.clientId !== 'string' || !client.clientId)
+        throw new Error(`${name}: clientId is required.`);
+    for (const key of Object.keys(client.authorizationParams ?? {})) {
+        if (RESERVED_PARAMS.has(key))
+            throw new Error(`${name}: authorizationParams may not set "${key}".`);
+    }
+    if (client.resource !== undefined)
+        checkEndpoint(client.resource, `${name}: resource`);
+    return { ...client, scopes: [...(client.scopes ?? [])] };
+}
 /** The consent manager over a credential store. Validates the configuration at once: a bad URL throws here, at boot. */
 export function oauthConsent(options) {
     const redirect = checkEndpoint(options.redirectUri, 'The OAuth redirect URI');
@@ -130,16 +146,23 @@ export function oauthConsent(options) {
     for (const [name, client] of Object.entries(options.providers)) {
         if (!PROVIDER_NAME.test(name))
             throw new Error(`OAuth provider "${name.slice(0, 64)}" must match ${PROVIDER_NAME}.`);
-        checkEndpoint(client.authorizationUrl, `${name}: authorizationUrl`);
-        checkEndpoint(client.tokenUrl, `${name}: tokenUrl`);
-        if (typeof client.clientId !== 'string' || !client.clientId)
-            throw new Error(`${name}: clientId is required.`);
-        for (const key of Object.keys(client.authorizationParams ?? {})) {
-            if (RESERVED_PARAMS.has(key))
-                throw new Error(`${name}: authorizationParams may not set "${key}".`);
-        }
-        providers.set(name, { ...client, scopes: [...(client.scopes ?? [])] });
+        // A source is checked each time it answers; a configured client here, at boot.
+        providers.set(name, typeof client === 'function' ? client : checkClient(name, client));
     }
+    /** The provider's client now, or undefined; a source that fails is a ConsentError('registration_failed'). */
+    const clientOf = async (name) => {
+        const entry = providers.get(name);
+        if (typeof entry !== 'function')
+            return entry;
+        try {
+            return checkClient(name, await entry());
+        }
+        catch (err) {
+            // A discovery refusal names roles and hosts, never a value (lib/tools/oauthDiscovery.ts); anything else is named by kind only.
+            console.warn(`[OAuth] ${name}: the client could not be set up: ${err instanceof Error && err.name === 'OAuthDiscoveryError' ? err.message : err instanceof Error ? err.name : 'unknown error'}`);
+            throw new ConsentError('registration_failed', name);
+        }
+    };
     const states = options.states ?? memoryConsentStates({ ...(options.now ? { now: options.now } : {}) });
     const ttlMs = options.ttlMs ?? 10 * 60_000;
     const now = options.now ?? Date.now;
@@ -193,6 +216,8 @@ export function oauthConsent(options) {
             client_id: client.clientId,
             code_verifier: flow.codeVerifier,
         });
+        if (client.resource)
+            body.set('resource', client.resource);
         if (client.clientSecret) {
             // The secret goes only to a host the operator binds its variable to (ADR 0122), checked now:
             // the allowlist can change after boot. Refused, nothing is sent.
@@ -238,9 +263,9 @@ export function oauthConsent(options) {
         redirectUri: options.redirectUri,
         has: (provider) => typeof provider === 'string' && providers.has(provider),
         async begin(binding) {
-            const client = providers.get(binding.provider);
-            if (!client)
+            if (!providers.has(binding.provider))
                 throw new ConsentError('unknown_provider', PROVIDER_NAME.test(binding.provider) ? binding.provider : undefined);
+            const client = (await clientOf(binding.provider));
             for (const field of ['appName', 'userId', 'sessionId', 'functionCallId']) {
                 if (typeof binding[field] !== 'string' || !binding[field])
                     throw new Error(`A consent flow needs the paused call's ${field}.`);
@@ -269,6 +294,8 @@ export function oauthConsent(options) {
             url.searchParams.set('state', state);
             url.searchParams.set('code_challenge', s256Challenge(codeVerifier));
             url.searchParams.set('code_challenge_method', 'S256');
+            if (client.resource)
+                url.searchParams.set('resource', client.resource);
             const authUri = url.toString();
             const authConfig = {
                 credentialKey: binding.provider,
@@ -314,7 +341,15 @@ export function oauthConsent(options) {
             const code = input.code;
             if (typeof code !== 'string' || !CODE_FORMAT.test(code))
                 fail('invalid_request');
-            const client = providers.get(flow.provider);
+            if (!providers.has(flow.provider))
+                fail('unknown_provider');
+            let client;
+            try {
+                client = await clientOf(flow.provider);
+            }
+            catch {
+                return fail('registration_failed');
+            }
             if (!client)
                 fail('unknown_provider');
             let tokens;

package/dist/lib/tools/oauthDiscovery.d.ts

@@ -0,0 +1,202 @@
+/**
+ * lib/tools/oauthDiscovery.ts — an MCP server's authorization server,
+ * discovered, and this deployment registered at it as an OAuth client
+ * (ADR 0124).
+ *
+ * WHY this file exists:
+ *   The official remote MCP servers (an issue tracker's, a wiki's, a code
+ *   host's) take each user's own OAuth token, and most issue no client id in
+ *   advance: the MCP authorization spec has a client find the authorization
+ *   server from the MCP server (protected-resource metadata, RFC 9728; then
+ *   authorization-server metadata, RFC 8414 or OpenID discovery) and register
+ *   itself (dynamic client registration, RFC 7591). A YAML says so with
+ *   `client_registration: dynamic` on the server's `oauth2` grant; this module
+ *   does the discovery and the registration, and keeps the registered client.
+ *
+ * WHAT IT GUARANTEES:
+ *   - The MCP server is asked first, as the MCP authorization spec has a
+ *     client do: an unauthenticated initialize request, and on a 401 the
+ *     Bearer challenge's `resource_metadata` (and `scope`) parameters in its
+ *     WWW-Authenticate header (RFC 9728 5.1). The URL it names is read first;
+ *     the well-known URLs are the fallback. The header is read by a linear,
+ *     length-bounded tokenizer (no regular expression), and never logged.
+ *   - Discovery never widens the operator's OAuth host allowlist (ADR 0114):
+ *     every URL it fetches (the MCP server's challenge, the metadata
+ *     documents, including one the header names, the registration
+ *     endpoint) and every endpoint it returns (authorization, token) must be
+ *     a host the allowlist binds to the provider, checked before the request
+ *     and again whenever the client is used. A discovered host outside it is
+ *     refused by name, not skipped.
+ *   - Every request passes the transport rule (https, or http to a loopback
+ *     host) and the SSRF guard (lib/net/addressGuard.ts) unless private hosts
+ *     are allowed (ALLOW_PRIVATE_MCP), follows no redirect, has a time limit,
+ *     and reads a bounded JSON body.
+ *   - The authorization server must advertise PKCE S256; one that does not is
+ *     refused (MCP authorization spec). The client registers as a public
+ *     client (`token_endpoint_auth_method: none`) for the one configured
+ *     redirect URI, with the authorization_code and refresh_token grants.
+ *   - The registered client is kept per provider, MCP server and redirect URI
+ *     in the credential store's rows, sealed by its cipher
+ *     (MELCHIZEDEK_CREDENTIAL_KEY), under an app name no run can have (it
+ *     carries `:`, which a memory namespace cannot), so no tool call can read
+ *     it as a token. A row this key cannot open, an expired client secret, or
+ *     endpoints that moved are registered again.
+ *   - No client secret, metadata body or server error text reaches a log
+ *     line, an error message or a result: refusals name roles and hosts.
+ */
+import type { CredentialKey } from './auth.ts';
+import type { CredentialCipher } from './credentialCipher.ts';
+import type { CredentialRows } from './credentialStore.ts';
+import type { OAuthHostAllowlist } from './oauthHosts.ts';
+import type { OAuthClientSource } from './oauthConsent.ts';
+/** A discovery or registration that cannot proceed. The message names roles and hosts, never a value. */
+export declare class OAuthDiscoveryError extends Error {
+    readonly provider: string;
+    constructor(provider: string, message: string);
+}
+/** What discovery found: the MCP server as a resource, and its authorization server's endpoints. */
+export interface DiscoveredAuthorization {
+    /** The MCP server's canonical URI, sent as the RFC 8707 `resource` parameter. */
+    resource: string;
+    /** The authorization server's issuer identifier. */
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint: string;
+    /**
+     * The scopes the MCP server's 401 challenge named (its `scope` parameter),
+     * when it named any: the MCP spec's first choice when the grant names none.
+     */
+    challengeScopes?: string[];
+}
+export interface DiscoveryOptions {
+    /** The provider the grant names: the allowlist is read for it. */
+    provider: string;
+    /** Private and loopback hosts pass the SSRF guard (ALLOW_PRIVATE_MCP). The allowlist still applies. */
+    allowPrivate?: boolean;
+    /** The allowlist; default the one in force (`null`: none configured, which refuses). */
+    allowlist?: OAuthHostAllowlist | null;
+    /** Each request's time limit, ms. Default 10 s. */
+    timeoutMs?: number;
+    /** For tests. */
+    fetch?: typeof fetch;
+}
+/** The MCP server's canonical URI (RFC 8707, MCP authorization spec): no fragment, no trailing slash on a path. */
+export declare function canonicalResource(serverUrl: string): string;
+/** A WWW-Authenticate header longer than this is ignored whole. */
+export declare const MAX_CHALLENGE_HEADER: number;
+/** What a Bearer challenge tells a client that has no token yet. */
+export interface BearerChallenge {
+    /** The `resource_metadata` parameter: the protected-resource metadata URL (RFC 9728 5.1), unparsed. */
+    resourceMetadata?: string;
+    /** The `scope` parameter, split, each a valid scope token (RFC 6750 3). */
+    scopes?: string[];
+}
+/**
+ * The first Bearer challenge's parameters in a WWW-Authenticate header, or
+ * undefined (no Bearer challenge, or a header that is too long or malformed:
+ * either is ignored whole, and discovery falls back to the well-known URLs).
+ * One pass over the header, each step advancing: linear in its length, with
+ * no regular expression. Several challenges in one header, quoted-string
+ * values with escapes, case-insensitive scheme and parameter names, and a
+ * token68 credential on another scheme are understood. A parameter given
+ * twice in the Bearer challenge makes it ambiguous, and malformed.
+ */
+export declare function parseBearerChallenge(header: string | null | undefined): BearerChallenge | undefined;
+/** RFC 9728 3.1: the protected-resource metadata URLs for a server, path-specific first. */
+export declare function protectedResourceMetadataUrls(serverUrl: string): URL[];
+/** RFC 8414 3.1 and OpenID discovery, in the order the MCP authorization spec gives. */
+export declare function authorizationServerMetadataUrls(issuer: string): URL[];
+/**
+ * The MCP server's authorization server, as the MCP authorization spec finds
+ * it: the protected-resource metadata URL named by the server's 401 challenge
+ * (WWW-Authenticate, RFC 9728 5.1), then the well-known URLs (RFC 9728 3.1);
+ * the metadata names the authorization server (a server with none is its
+ * own, as the 2025-03-26 revision had it), and its own metadata (RFC 8414, or
+ * OpenID discovery) names the endpoints. Every host involved, the one the
+ * header names included, passes the provider's allowlist before any request;
+ * PKCE S256 and a registration endpoint are required. Throws
+ * OAuthDiscoveryError.
+ */
+export declare function discoverAuthorization(serverUrl: string, options: DiscoveryOptions): Promise<DiscoveredAuthorization>;
+/** A client this deployment registered at an authorization server. */
+export interface RegisteredClient {
+    clientId: string;
+    /** A confidential client's secret, when the server issued one anyway. */
+    clientSecret?: string;
+    /** Epoch ms after which the secret stops working; absent when it does not expire. */
+    secretExpiresAt?: number;
+}
+export interface RegistrationOptions extends DiscoveryOptions {
+    /** The consent callback, exactly as every authorization will send it. */
+    redirectUri: string;
+    /** Shown to the person on the provider's consent screen. Default "Melchizedek agents". */
+    clientName?: string;
+    scopes?: string[];
+}
+/**
+ * Registers this deployment at the authorization server (RFC 7591) as a
+ * public PKCE client for the one redirect URI. Throws OAuthDiscoveryError,
+ * never the server's text.
+ */
+export declare function registerOAuthClient(discovered: DiscoveredAuthorization, options: RegistrationOptions): Promise<RegisteredClient>;
+/**
+ * The app name registered clients are filed under. It carries `:`, which a
+ * memory namespace (the app a run pins, `[A-Za-z0-9._-]`) cannot, so no
+ * run's credential key ever reaches one of these rows.
+ */
+export declare const REGISTERED_CLIENTS_APP = "oauth-client:dcr";
+/** The row a provider's registered client is kept in: one per MCP server (resource) and redirect URI. */
+export declare function registeredClientKey(provider: string, resource: string, redirectUri: string): CredentialKey;
+/** What a sealed registration holds. */
+interface StoredRegistration {
+    v: 1;
+    clientId: string;
+    clientSecret?: string;
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    resource: string;
+    redirectUri: string;
+}
+export interface OAuthClientRegistry {
+    /** The registration kept for this key, or undefined (none, unreadable under this key, or its secret expired). */
+    get(key: CredentialKey): Promise<(StoredRegistration & {
+        secretExpiresAt?: number;
+    }) | undefined>;
+    put(key: CredentialKey, registration: Omit<StoredRegistration, 'v'>, secretExpiresAt?: number): Promise<void>;
+}
+/** Registered clients over the credential store's rows, sealed by its cipher (the same key as every user's tokens). */
+export declare function oauthClientRegistry(options: {
+    rows: CredentialRows;
+    cipher: CredentialCipher;
+    now?: () => number;
+}): OAuthClientRegistry;
+/** A dynamic grant as a served YAML declares it (lib/tools/oauthTools.ts dynamicOAuthGrantsFor). */
+export interface DynamicOAuthGrant {
+    provider: string;
+    /** The MCP server the grant is for. */
+    server: string;
+    scopes: string[];
+    authorizationParams?: Record<string, string>;
+}
+export interface DynamicClientOptions {
+    /** The consent callback, as configured (OAUTH_REDIRECT_URI). */
+    redirectUri: string;
+    /** Where registrations are kept; without one, each process registers once in memory. */
+    registry?: OAuthClientRegistry;
+    allowPrivate?: boolean;
+    clientName?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+    /** For tests. */
+    allowlist?: OAuthHostAllowlist | null;
+}
+/**
+ * The consent step's client for a dynamic grant (oauthConsent and
+ * oauthRefreshProviders take it in place of a fixed config): discovered and
+ * registered on first use, kept, and re-checked against the allowlist in
+ * force on every use. A failure is not cached; the next use tries again.
+ */
+export declare function dynamicOAuthClient(grant: DynamicOAuthGrant, options: DynamicClientOptions): OAuthClientSource;
+export {};