melchizedek-agents 1.1.0 → 1.3.0

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