@0xmaxma/claude-gateway 1.8.6 → 1.8.8

package/dist/connectors/mcp-oauth.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Generic OAuth 2.1 + PKCE (+ optional Dynamic Client Registration) support for
+ * "custom" MCP connectors whose only auth option is a real OAuth sign-in (no
+ * static API key) — e.g. Firecrawl's `https://mcp.firecrawl.dev/v2/mcp-oauth`.
+ *
+ * This module never touches Express or the pending-flow store — pure discovery
+ * + token functions, unit-testable with plain HTTP mocks. See
+ * `pending-oauth-store.ts` for the in-flight-flow state and
+ * `api/oauth-connectors-router.ts` for the HTTP endpoints that glue this
+ * together with `connectors/custom.ts`'s existing secret storage.
+ *
+ * Empirically verified against production Firecrawl (2026-09, this repo's own
+ * throwaway PoC — see git history / PR description, not reproduced here):
+ * DCR genuinely works with an arbitrary redirect_uri (no pre-registration
+ * needed), and the RFC 8707 `resource` parameter is REQUIRED on both the
+ * authorize request and the token exchange — omitting it yields a token that
+ * exchanges fine but is rejected by the MCP endpoint itself
+ * ("OAUTH_CONNECTION_INVALID"). Always pass `resource` through this module's
+ * functions; never make it optional.
+ */
+export interface OAuthMetadata {
+    /** The MCP server URL this metadata was discovered for — also the RFC 8707 `resource`. */
+    resource: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    /** Absent when the AS doesn't advertise RFC 7591 Dynamic Client Registration. */
+    registrationEndpoint?: string;
+    /**
+     * Scopes to request for this resource: the protected-resource metadata's list
+     * when it publishes one, else the authorization server's. Empty when neither
+     * does — see `resolveScope` for what gets sent then.
+     */
+    scopesSupported: string[];
+}
+export interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+}
+/**
+ * A token endpoint that answered, and answered with a refusal.
+ *
+ * The distinction this class exists to draw is between "the grant is dead" and
+ * "we couldn't reach the provider just now". The refresh sweep gives up on a
+ * connector after a few consecutive failures and deletes its stored credentials,
+ * which is right for the first case and destructive for the second — a fifteen
+ * minute provider outage is an ordinary event and must not cost the user their
+ * sign-in. Only an explicit OAuth error response can be classified, so only this
+ * error type carries `isPermanent`; anything else the sweep sees (a DNS failure,
+ * a socket timeout, a 502, a discovery step that returned the wrong shape) is
+ * treated as retryable by default.
+ */
+export declare class OAuthTokenError extends Error {
+    readonly status: number;
+    /** RFC 6749 §5.2 `error` code from the response body, when it had one. */
+    readonly errorCode?: string | undefined;
+    constructor(message: string, status: number, 
+    /** RFC 6749 §5.2 `error` code from the response body, when it had one. */
+    errorCode?: string | undefined);
+    /**
+     * True when the authorization server has told us this grant will never work
+     * again. Deliberately a small allowlist rather than "any 4xx": a 400 with no
+     * recognisable `error` code, or a 429, says more about this request than about
+     * the grant, and retrying costs nothing but a backoff.
+     */
+    get isPermanent(): boolean;
+}
+/**
+ * Discover OAuth metadata for an MCP server by probing it unauthenticated
+ * (expects a 401 advertising `resource_metadata`, per RFC 9728), then walking
+ * protected-resource metadata → authorization-server metadata (RFC 8414).
+ * Throws a descriptive error at whichever step fails — callers surface it
+ * to the admin as "can't set up OAuth for this URL", not a generic 500.
+ */
+export declare function discoverOAuthMetadata(mcpUrl: string): Promise<OAuthMetadata>;
+/**
+ * `discoverOAuthMetadata` with a process-local cache, for the background refresh
+ * sweep.
+ *
+ * Discovery costs three round trips — an MCP probe that is *expected* to 401, then
+ * protected-resource metadata, then authorization-server metadata — to obtain a
+ * document that changes about never. Paying that on every refresh is not just waste:
+ * each of those three requests is another way for a refresh to fail, and a failed
+ * refresh is what eventually makes the sweep give up and delete the connector's
+ * credentials. Fewer moving parts on the periodic path means fewer spurious failures.
+ *
+ * Only the sweep uses this. An admin-initiated `oauth/start` still calls
+ * `discoverOAuthMetadata` directly: that is the moment a human is waiting to find out
+ * whether this URL works at all, so it should see today's truth, not a cached answer
+ * from before they fixed their provider's configuration.
+ */
+export declare function discoverOAuthMetadataCached(mcpUrl: string): Promise<OAuthMetadata>;
+/** Drop every cached metadata document. For tests, and for a forced re-discovery. */
+export declare function clearOAuthMetadataCache(): void;
+/**
+ * Register a public (no client_secret) client via RFC 7591 DCR. Throws if the
+ * server rejects it — callers fall back to a per-connector static client_id
+ * (an env var an admin configured by hand) when this isn't available at all,
+ * see `resolveClientId` below.
+ */
+export declare function registerClient(registrationEndpoint: string, redirectUri: string, clientName: string): Promise<string>;
+/**
+ * Resolve a client_id for `metadata`: try DCR first, fall back to a static
+ * `MCP_OAUTH_CLIENT_ID__<connectorId>` env var (an admin-configured client_id
+ * for a provider that advertises no registration_endpoint at all).
+ */
+export declare function resolveClientId(metadata: OAuthMetadata, connectorId: string, redirectUri: string): Promise<string>;
+/**
+ * The `scope` to send with an authorization request for `metadata`.
+ *
+ * An admin-set `MCP_OAUTH_SCOPES__<connectorId>` (space-separated) wins, for the
+ * same reason `MCP_OAUTH_CLIENT_ID__<connectorId>` exists above: discovery is the
+ * provider's story about itself, and when that story is wrong the sign-in fails at
+ * the provider with an `invalid_scope` the operator cannot otherwise do anything
+ * about. Some servers publish a scope the client is not entitled to; some grant a
+ * refresh_token only when `offline_access` is asked for and never advertise it.
+ * Both are one env var away from working, instead of a code change away.
+ *
+ * `offline_access` is the fallback when nothing is discovered or configured: the
+ * refresh sweep needs a refresh_token, and an authorization request carrying no
+ * scope at all gets whatever the provider's default happens to be.
+ */
+export declare function resolveScope(metadata: OAuthMetadata, connectorId: string): string;
+export interface PkcePair {
+    codeVerifier: string;
+    codeChallenge: string;
+}
+export declare function generatePkce(): PkcePair;
+export declare function generateState(): string;
+export declare function buildAuthorizeUrl(opts: {
+    metadata: OAuthMetadata;
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    codeChallenge: string;
+    state: string;
+}): string;
+export declare function exchangeCode(opts: {
+    metadata: OAuthMetadata;
+    clientId: string;
+    redirectUri: string;
+    code: string;
+    codeVerifier: string;
+}): Promise<TokenResponse>;
+export declare function refreshAccessToken(opts: {
+    metadata: OAuthMetadata;
+    clientId: string;
+    refreshToken: string;
+}): Promise<TokenResponse>;
+//# sourceMappingURL=mcp-oauth.d.ts.map

package/dist/connectors/mcp-oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-oauth.d.ts","sourceRoot":"","sources":["../../src/connectors/mcp-oauth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAiIH,MAAM,WAAW,aAAa;IAC5B,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAGtC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM;gBAH3B,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM;IACvB,0EAA0E;IACjE,SAAS,CAAC,EAAE,MAAM,YAAA;IAM7B;;;;;OAKG;IACH,IAAI,WAAW,IAAI,OAAO,CASzB;CACF;AA6BD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAyElF;AA6CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAaxF;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,oBAAoB,EAAE,MAAM,EAC5B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,aAAa,EACvB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAKjF;AAED,MAAM,WAAW,QAAQ;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,wBAAgB,YAAY,IAAI,QAAQ,CAIvC;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAYT;AAsED,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,aAAa,CAAC,CAYzB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,aAAa,CAAC,CAUzB"}