@adcp/sdk 5.23.0

package/dist/lib/auth/oauth/MCPOAuthProvider.js

@@ -0,0 +1,255 @@
+"use strict";
+/**
+ * MCP OAuth Provider
+ *
+ * Implements the MCP SDK's OAuthClientProvider interface
+ * using AgentConfig for token storage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPOAuthProvider = void 0;
+const types_1 = require("./types");
+const crypto_1 = require("crypto");
+/**
+ * MCP OAuth Client Provider
+ *
+ * This provider stores OAuth tokens directly in the AgentConfig,
+ * using the same structure as static auth tokens.
+ *
+ * @example
+ * ```typescript
+ * const agent: AgentConfig = {
+ *   id: 'my-agent',
+ *   name: 'My Agent',
+ *   agent_uri: 'https://agent.example.com/mcp',
+ *   protocol: 'mcp',
+ *   // OAuth tokens stored here after auth flow
+ *   oauth_tokens: { access_token: '...', refresh_token: '...' }
+ * };
+ *
+ * const provider = new MCPOAuthProvider({
+ *   agent,
+ *   flowHandler: new CLIFlowHandler(),
+ *   storage: myConfigStorage  // Optional: persists tokens
+ * });
+ *
+ * const transport = new StreamableHTTPClientTransport(url, {
+ *   authProvider: provider
+ * });
+ * ```
+ */
+class MCPOAuthProvider {
+    agent;
+    storage;
+    flowHandler;
+    _clientMetadata;
+    constructor(config) {
+        this.agent = config.agent;
+        this.storage = config.storage;
+        this.flowHandler = config.flowHandler;
+        this._clientMetadata = config.clientMetadata;
+    }
+    /**
+     * Create a provider for CLI usage
+     */
+    static forCLI(agent, flowHandler, storage, clientMetadataOverrides) {
+        // Build complete client metadata with required fields
+        const clientMetadata = {
+            ...types_1.DEFAULT_CLIENT_METADATA,
+            redirect_uris: [flowHandler.getRedirectUrl().toString()],
+            ...clientMetadataOverrides,
+        };
+        return new MCPOAuthProvider({
+            agent,
+            flowHandler,
+            storage,
+            clientMetadata,
+        });
+    }
+    // ========================================
+    // OAuthClientProvider interface
+    // ========================================
+    get redirectUrl() {
+        return this.flowHandler.getRedirectUrl();
+    }
+    get clientMetadata() {
+        return this._clientMetadata;
+    }
+    /**
+     * Validate the protected resource URL from server metadata (RFC 9728).
+     *
+     * Servers behind reverse proxies or DNS aliases may advertise a canonical
+     * resource URL (RFC 8707) that differs from the URL the client connected to.
+     * We allow cross-origin resource URLs because agent configs are pre-configured
+     * by the user, not discovered from untrusted sources. The authorization server
+     * remains the final gatekeeper for token audience validation.
+     */
+    async validateResourceURL(serverUrl, resource) {
+        if (!resource) {
+            return undefined;
+        }
+        const resourceURL = new URL(resource);
+        if (resourceURL.protocol !== 'https:') {
+            throw new Error(`Server at ${serverUrl} advertised non-HTTPS resource URL: ${resource}`);
+        }
+        return resourceURL;
+    }
+    /**
+     * Generate OAuth state parameter
+     */
+    async state() {
+        return (0, crypto_1.randomBytes)(32).toString('base64url');
+    }
+    /**
+     * Load client information from agent config
+     */
+    async clientInformation() {
+        if (this.agent.oauth_client) {
+            return (0, types_1.toMCPClientInfo)(this.agent.oauth_client);
+        }
+        return undefined;
+    }
+    /**
+     * Save client information after dynamic registration
+     */
+    async saveClientInformation(clientInfo) {
+        this.agent.oauth_client = (0, types_1.fromMCPClientInfo)(clientInfo);
+        await this.persistAgent();
+    }
+    /**
+     * Load existing tokens from agent config
+     */
+    async tokens() {
+        if (this.agent.oauth_tokens) {
+            return (0, types_1.toMCPTokens)(this.agent.oauth_tokens);
+        }
+        return undefined;
+    }
+    /**
+     * Save tokens after authorization
+     * Also cleans up the temporary code verifier
+     */
+    async saveTokens(tokens) {
+        this.agent.oauth_tokens = (0, types_1.fromMCPTokens)(tokens);
+        // Clean up temporary code verifier after successful token exchange
+        delete this.agent.oauth_code_verifier;
+        await this.persistAgent();
+    }
+    /**
+     * Redirect user to authorization URL
+     */
+    async redirectToAuthorization(authorizationUrl) {
+        await this.flowHandler.redirectToAuthorization(authorizationUrl);
+    }
+    /**
+     * Save PKCE code verifier
+     */
+    async saveCodeVerifier(codeVerifier) {
+        this.agent.oauth_code_verifier = codeVerifier;
+        await this.persistAgent();
+    }
+    /**
+     * Load PKCE code verifier
+     * The MCP SDK calls saveCodeVerifier() before authorization and
+     * retrieves it here during token exchange.
+     */
+    async codeVerifier() {
+        if (!this.agent.oauth_code_verifier) {
+            throw new Error('No PKCE code verifier found. The OAuth flow may have been interrupted or ' +
+                'the agent config was modified. Please try authenticating again.');
+        }
+        return this.agent.oauth_code_verifier;
+    }
+    /**
+     * Invalidate credentials when server indicates they're invalid
+     */
+    async invalidateCredentials(scope) {
+        switch (scope) {
+            case 'all':
+                delete this.agent.oauth_tokens;
+                delete this.agent.oauth_client;
+                delete this.agent.oauth_code_verifier;
+                break;
+            case 'tokens':
+                delete this.agent.oauth_tokens;
+                break;
+            case 'client':
+                delete this.agent.oauth_client;
+                break;
+            case 'verifier':
+                delete this.agent.oauth_code_verifier;
+                break;
+        }
+        await this.persistAgent();
+    }
+    // ========================================
+    // Additional methods
+    // ========================================
+    /**
+     * Persist agent config to storage if configured
+     */
+    async persistAgent() {
+        if (this.storage) {
+            await this.storage.saveAgent(this.agent);
+        }
+    }
+    /**
+     * Wait for the OAuth callback
+     * Call this after UnauthorizedError is thrown
+     */
+    async waitForCallback() {
+        return this.flowHandler.waitForCallback();
+    }
+    /**
+     * Clean up resources
+     */
+    async cleanup() {
+        await this.flowHandler.cleanup();
+    }
+    /**
+     * Check if we have valid, non-expired OAuth tokens
+     * @returns true if access_token exists and hasn't expired (with 5 minute buffer)
+     */
+    hasValidTokens() {
+        const tokens = this.agent.oauth_tokens;
+        if (!tokens?.access_token)
+            return false;
+        // Check expiration if available
+        if (tokens.expires_at) {
+            const expiresAt = new Date(tokens.expires_at);
+            // Consider expired if within 5 minutes of expiration
+            if (expiresAt.getTime() - Date.now() < 5 * 60 * 1000) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Check if we have a refresh token available for token refresh
+     * @returns true if refresh_token is present
+     */
+    hasRefreshToken() {
+        return !!this.agent.oauth_tokens?.refresh_token;
+    }
+    /**
+     * Clear all OAuth data for this agent
+     */
+    async clearAuth() {
+        await this.invalidateCredentials('all');
+    }
+    /**
+     * Get the agent config this provider manages
+     * @returns The AgentConfig with OAuth tokens populated after successful auth
+     */
+    getAgent() {
+        return this.agent;
+    }
+    /**
+     * Get the agent identifier
+     * @returns The agent's unique ID
+     */
+    getAgentId() {
+        return this.agent.id;
+    }
+}
+exports.MCPOAuthProvider = MCPOAuthProvider;
+//# sourceMappingURL=MCPOAuthProvider.js.map

package/dist/lib/auth/oauth/MCPOAuthProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MCPOAuthProvider.js","sourceRoot":"","sources":["../../../../src/lib/auth/oauth/MCPOAuthProvider.ts"],"names":[],"mappings":"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"}

package/dist/lib/auth/oauth/NonInteractiveFlowHandler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Non-interactive OAuth flow handler for background / headless contexts
+ * (storyboard runs, scheduled compliance jobs, CI).
+ *
+ * Use with {@link MCPOAuthProvider} when you want to **use and refresh**
+ * previously-saved OAuth tokens, but do not want to initiate a new
+ * authorization flow (which would require a browser). Any attempt to
+ * redirect to authorization throws with an actionable error message.
+ *
+ * The MCP SDK will still call this handler's lifecycle — `getRedirectUrl`,
+ * `redirectToAuthorization`, `waitForCallback`, `cleanup` — but only the
+ * first is expected to succeed in practice. The others throw if reached.
+ */
+import type { OAuthFlowHandler } from './types';
+export interface NonInteractiveFlowHandlerConfig {
+    /**
+     * Redirect URL reported back to the MCP SDK. Should match the
+     * `redirect_uris` of the saved client registration (usually
+     * `http://localhost:8766/callback`). Defaults to that value.
+     */
+    redirectUrl?: string | URL;
+    /**
+     * Optional hint shown in the error message when a browser flow is
+     * attempted — e.g., the alias name to pass to `adcp --save-auth`.
+     */
+    agentHint?: string;
+}
+export declare class NonInteractiveFlowHandler implements OAuthFlowHandler {
+    private readonly _redirectUrl;
+    private readonly agentHint?;
+    constructor(config?: NonInteractiveFlowHandlerConfig);
+    getRedirectUrl(): URL;
+    redirectToAuthorization(): Promise<void>;
+    waitForCallback(): Promise<string>;
+    cleanup(): Promise<void>;
+}
+//# sourceMappingURL=NonInteractiveFlowHandler.d.ts.map

package/dist/lib/auth/oauth/NonInteractiveFlowHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NonInteractiveFlowHandler.d.ts","sourceRoot":"","sources":["../../../../src/lib/auth/oauth/NonInteractiveFlowHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGhD,MAAM,WAAW,+BAA+B;IAC9C;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,yBAA0B,YAAW,gBAAgB;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAM;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;gBAExB,MAAM,GAAE,+BAAoC;IAKxD,cAAc,IAAI,GAAG;IAIf,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC;IAWxC,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAIlC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

package/dist/lib/auth/oauth/NonInteractiveFlowHandler.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NonInteractiveFlowHandler = void 0;
+const types_1 = require("./types");
+class NonInteractiveFlowHandler {
+    _redirectUrl;
+    agentHint;
+    constructor(config = {}) {
+        this._redirectUrl = new URL((config.redirectUrl ?? 'http://localhost:8766/callback').toString());
+        this.agentHint = config.agentHint;
+    }
+    getRedirectUrl() {
+        return this._redirectUrl;
+    }
+    async redirectToAuthorization() {
+        const target = this.agentHint
+            ? `adcp --save-auth ${this.agentHint} --oauth`
+            : 'adcp --save-auth <alias> <url> --oauth';
+        throw new types_1.OAuthError(`OAuth authorization required but this context is non-interactive. ` +
+            `Run \`${target}\` from a terminal with a browser, then retry.`, 'interactive_required');
+    }
+    async waitForCallback() {
+        throw new types_1.OAuthError('waitForCallback() is not supported in non-interactive mode.', 'interactive_required');
+    }
+    async cleanup() {
+        // Nothing to clean up — no server was started, no resources allocated.
+    }
+}
+exports.NonInteractiveFlowHandler = NonInteractiveFlowHandler;
+//# sourceMappingURL=NonInteractiveFlowHandler.js.map

package/dist/lib/auth/oauth/NonInteractiveFlowHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NonInteractiveFlowHandler.js","sourceRoot":"","sources":["../../../../src/lib/auth/oauth/NonInteractiveFlowHandler.ts"],"names":[],"mappings":";;;AAcA,mCAAqC;AAiBrC,MAAa,yBAAyB;IACnB,YAAY,CAAM;IAClB,SAAS,CAAU;IAEpC,YAAY,SAA0C,EAAE;QACtD,IAAI,CAAC,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,gCAAgC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjG,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACpC,CAAC;IAED,cAAc;QACZ,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,uBAAuB;QAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS;YAC3B,CAAC,CAAC,oBAAoB,IAAI,CAAC,SAAS,UAAU;YAC9C,CAAC,CAAC,wCAAwC,CAAC;QAC7C,MAAM,IAAI,kBAAU,CAClB,oEAAoE;YAClE,SAAS,MAAM,gDAAgD,EACjE,sBAAsB,CACvB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,MAAM,IAAI,kBAAU,CAAC,6DAA6D,EAAE,sBAAsB,CAAC,CAAC;IAC9G,CAAC;IAED,KAAK,CAAC,OAAO;QACX,uEAAuE;IACzE,CAAC;CACF;AA/BD,8DA+BC"}

package/dist/lib/auth/oauth/authorization-required.d.ts

@@ -0,0 +1,112 @@
+import { AuthenticationRequiredError } from '../../errors';
+import { type WWWAuthenticateChallenge } from './diagnostics';
+/**
+ * Structured description of what an agent's authorization server requires
+ * before it will accept a `tools/call`. Produced by
+ * {@link discoverAuthorizationRequirements}.
+ */
+export interface AuthorizationRequirements {
+    /** The agent URL we probed. */
+    agentUrl: string;
+    /** Resource URL the agent advertises in its `WWW-Authenticate` / PRM (RFC 9728). */
+    resource?: string;
+    /** URL of the protected-resource-metadata document (from `WWW-Authenticate: resource_metadata=…`). */
+    resourceMetadataUrl?: string;
+    /** First `authorization_servers[0]` from the protected-resource metadata. */
+    authorizationServer?: string;
+    /**
+     * All `authorization_servers` advertised by the PRM, in declaration order.
+     * The walker only probes `[0]` (PRM preference order — see RFC 9728 §3.3);
+     * the full list is exposed so callers can surface multi-issuer deployments
+     * in diagnostics. A length > 1 is uncommon and worth flagging to the
+     * operator — typically a federation partner or a staged migration.
+     */
+    authorizationServers?: string[];
+    /** `authorization_endpoint` from the authorization-server metadata (RFC 8414). */
+    authorizationEndpoint?: string;
+    /** `token_endpoint` from the authorization-server metadata. */
+    tokenEndpoint?: string;
+    /** `registration_endpoint` if the AS supports RFC 7591 dynamic client registration. */
+    registrationEndpoint?: string;
+    /** Scopes advertised by the AS (RFC 8414 `scopes_supported`). */
+    scopesSupported?: string[];
+    /**
+     * `grant_types_supported` advertised by the AS (RFC 8414). `undefined` when
+     * the AS didn't publish the field — per RFC 8414 that defaults to
+     * `["authorization_code", "implicit"]`. Clients should treat absence as
+     * "unknown, try your grant and see," not as proof the grant is unsupported.
+     */
+    grantTypesSupported?: string[];
+    /** True when the AS metadata came from the OIDC fallback URL rather than RFC 8414. */
+    metadataSource?: 'rfc-8414' | 'openid-configuration';
+    /** Scope hinted in the `WWW-Authenticate` challenge's `scope` auth-param. */
+    challengeScope?: string;
+    /** Raw parsed challenge the agent returned on the 401. */
+    challenge: WWWAuthenticateChallenge;
+}
+/**
+ * Error raised when an agent returns a 401 and we do not have credentials
+ * to satisfy it. Carries everything needed to run an interactive OAuth flow
+ * or show the operator an actionable prompt.
+ *
+ * Extends {@link AuthenticationRequiredError} so existing callers that catch
+ * `AuthenticationRequiredError` automatically receive the richer variant —
+ * they can downcast with `instanceof NeedsAuthorizationError` when they
+ * want walked discovery metadata.
+ *
+ * Note on `code` vs `subCode`:
+ *   The parent class declares `readonly code = 'AUTHENTICATION_REQUIRED'` as
+ *   a class field that re-initializes on every construction, so a child-side
+ *   override attempt is silently overwritten under `useDefineForClassFields`.
+ *   The narrow discriminator is exposed as `subCode` — prefer
+ *   `instanceof NeedsAuthorizationError` for type-narrowing and use `subCode`
+ *   only for structured-log keying.
+ *
+ * Note on `hasOAuth`:
+ *   The inherited getter returns `true` only when both `authorization_endpoint`
+ *   and `token_endpoint` were walked successfully. A partially-walked
+ *   requirements record (PRM reachable but AS metadata missing) still yields
+ *   `hasOAuth === false` even though `requirements.authorizationServer` is set.
+ *   Treat it as "we have enough to start a flow," not "server wants OAuth."
+ */
+export declare class NeedsAuthorizationError extends AuthenticationRequiredError {
+    /** Narrow discriminator for consumers that already know about this class. */
+    readonly subCode: "needs_authorization";
+    readonly requirements: AuthorizationRequirements;
+    constructor(requirements: AuthorizationRequirements, message?: string);
+}
+/**
+ * Options for {@link discoverAuthorizationRequirements}.
+ */
+export interface DiscoverAuthorizationOptions {
+    /** Allow http:// and private-IP probe targets. Default false. */
+    allowPrivateIp?: boolean;
+    /** Override per-probe HTTP timeout (ms). Default inherits from ssrfSafeFetch (10s). */
+    timeoutMs?: number;
+    /**
+     * If provided, use this `WWW-Authenticate` header verbatim instead of
+     * re-probing the agent. Use this when you already have a 401 response in
+     * hand and want to avoid a second round-trip.
+     */
+    wwwAuthenticate?: string;
+}
+/**
+ * Walk the OAuth discovery chain starting from an agent URL. Returns
+ * `AuthorizationRequirements` when the agent demands OAuth, or `null` when a
+ * `tools/list` call succeeds without credentials.
+ *
+ * Strategy:
+ *   1. POST `tools/list` to the agent with no `Authorization` header.
+ *   2. If 401 + `WWW-Authenticate: Bearer`: parse the challenge.
+ *   3. If the challenge carries `resource_metadata=…`: GET it and read
+ *      `resource` + `authorization_servers`.
+ *   4. For the first `authorization_servers[0]`: GET `/.well-known/oauth-authorization-server`
+ *      and read `authorization_endpoint`, `token_endpoint`, `registration_endpoint`,
+ *      `scopes_supported`.
+ *   5. Return a structured record.
+ *
+ * Anything missing from the chain surfaces as `undefined` on the result —
+ * callers can still present a partial picture without re-probing.
+ */
+export declare function discoverAuthorizationRequirements(agentUrl: string, options?: DiscoverAuthorizationOptions): Promise<AuthorizationRequirements | null>;
+//# sourceMappingURL=authorization-required.d.ts.map

package/dist/lib/auth/oauth/authorization-required.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization-required.d.ts","sourceRoot":"","sources":["../../../../src/lib/auth/oauth/authorization-required.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,2BAA2B,EAA0B,MAAM,cAAc,CAAC;AACnF,OAAO,EAAwB,KAAK,wBAAwB,EAAE,MAAM,eAAe,CAAC;AA8DpF;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,kFAAkF;IAClF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,sFAAsF;IACtF,cAAc,CAAC,EAAE,UAAU,GAAG,sBAAsB,CAAC;IACrD,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,SAAS,EAAE,wBAAwB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,uBAAwB,SAAQ,2BAA2B;IACtE,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAG,qBAAqB,CAAU;IAClD,QAAQ,CAAC,YAAY,EAAE,yBAAyB,CAAC;gBAErC,YAAY,EAAE,yBAAyB,EAAE,OAAO,CAAC,EAAE,MAAM;CAStE;AA+BD;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,iEAAiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iCAAiC,CACrD,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAgH3C"}