@akira-tl/forgerelay 1.1.0 → 1.1.2

package/dist/mcp/operations/external-mcp/external-mcp-oauth.js

@@ -0,0 +1,387 @@
+import { randomBytes } from "node:crypto";
+import { AuthorizationServerMismatchError, InsufficientScopeError, OAuthError, OAuthErrorCode, SdkHttpError, UnauthorizedError, auth, computeScopeUnion, extractWWWAuthenticateParams, LATEST_PROTOCOL_VERSION, refreshAuthorization, resourceUrlFromServerUrl, } from "@modelcontextprotocol/client";
+export class ExternalMcpOAuthError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ExternalMcpOAuthError";
+    }
+}
+const CLIENT_NAME = "ForgeRelay External MCP";
+const CLIENT_URI = "https://github.com/Akira-TL/forgerelay";
+export function createExternalMcpRuntimeAuth(store, identity, serverUrl) {
+    const record = store.read(identity);
+    if (!record)
+        return { identity, serverUrl, bindingMismatch: false };
+    if (!record.tokens?.access_token
+        && record.reauthorization?.reason === "authorization_required"
+        && sameServerUrl(record.serverUrl, serverUrl)) {
+        return { identity, serverUrl, bindingMismatch: false };
+    }
+    if (!sameServerUrl(record.serverUrl, serverUrl)) {
+        return { identity, serverUrl, bindingMismatch: true };
+    }
+    try {
+        assertStoredBinding(record);
+    }
+    catch (error) {
+        if (error instanceof AuthorizationServerMismatchError) {
+            return { identity, serverUrl, bindingMismatch: true };
+        }
+        throw error;
+    }
+    const state = { revision: record.revision };
+    const authProvider = {
+        token: async () => {
+            const latest = store.read(identity);
+            if (!latest || !sameServerUrl(latest.serverUrl, serverUrl))
+                return undefined;
+            state.revision = latest.revision;
+            return latest.tokens?.access_token;
+        },
+        onUnauthorized: async () => {
+            await store.withIdentityLock(identity, async () => {
+                const latest = store.read(identity);
+                if (!latest)
+                    throw authRequired(identity.server);
+                if (!sameServerUrl(latest.serverUrl, serverUrl)) {
+                    await markReauthorization(store, identity, latest, "binding_changed");
+                    throw reauthorizationRequired(identity.server, "OAuth resource binding changed.");
+                }
+                if (latest.revision !== state.revision) {
+                    state.revision = latest.revision;
+                    return;
+                }
+                if (!latest.tokens?.refresh_token || !latest.clientInformation) {
+                    await markReauthorization(store, identity, latest, "authorization_required");
+                    throw reauthorizationRequired(identity.server, "Stored OAuth credentials cannot be refreshed.");
+                }
+                assertStoredBinding(latest);
+                const authorizationServerUrl = latest.discoveryState?.authorizationServerUrl
+                    ?? latest.authorizationServerUrl;
+                if (!authorizationServerUrl) {
+                    await markReauthorization(store, identity, latest, "binding_changed");
+                    throw reauthorizationRequired(identity.server, "Stored OAuth authorization-server binding is incomplete.");
+                }
+                try {
+                    const refreshed = await refreshAuthorization(authorizationServerUrl, {
+                        metadata: latest.discoveryState?.authorizationServerMetadata,
+                        clientInformation: latest.clientInformation,
+                        refreshToken: latest.tokens.refresh_token,
+                        resource: latest.resourceUrl ? new URL(latest.resourceUrl) : resourceUrlFromServerUrl(serverUrl),
+                    });
+                    const expectedIssuer = storedIssuer(latest, authorizationServerUrl);
+                    const next = await store.replace(identity, serverUrl, {
+                        tokens: { ...refreshed, issuer: expectedIssuer },
+                        clientInformation: latest.clientInformation,
+                        ...(latest.discoveryState ? { discoveryState: latest.discoveryState } : {}),
+                        authorizationServerUrl: expectedIssuer,
+                        ...(latest.resourceUrl ? { resourceUrl: latest.resourceUrl } : {}),
+                    });
+                    state.revision = next.revision;
+                }
+                catch (error) {
+                    if (isCredentialReauthorizationError(error)) {
+                        await markReauthorization(store, identity, latest, "invalid_grant");
+                        throw reauthorizationRequired(identity.server, "Stored OAuth credentials require fresh authorization.");
+                    }
+                    throw error;
+                }
+            });
+        },
+    };
+    return { authProvider, bindingMismatch: false, identity, serverUrl };
+}
+export async function markExternalMcpAuthorizationRequired(store, runtimeAuth) {
+    if (!runtimeAuth)
+        return;
+    await store.withIdentityLock(runtimeAuth.identity, async () => {
+        const latest = store.read(runtimeAuth.identity);
+        if (latest)
+            return;
+        await store.replace(runtimeAuth.identity, runtimeAuth.serverUrl, {
+            reauthorization: {
+                reason: "authorization_required",
+                observedAt: new Date().toISOString(),
+            },
+        });
+    });
+}
+export async function markExternalMcpReauthorization(store, runtimeAuth, reason, details = {}) {
+    if (!runtimeAuth)
+        return;
+    await store.withIdentityLock(runtimeAuth.identity, async () => {
+        const latest = store.read(runtimeAuth.identity);
+        if (!latest)
+            return;
+        if (reason !== "binding_changed" && !sameServerUrl(latest.serverUrl, runtimeAuth.serverUrl))
+            return;
+        await markReauthorization(store, runtimeAuth.identity, latest, reason, details);
+    });
+}
+export function externalMcpAuthError(server, error, runtimeAuth) {
+    if (error instanceof ExternalMcpOAuthError)
+        return error;
+    if (runtimeAuth?.bindingMismatch) {
+        return reauthorizationRequired(server, "OAuth resource binding changed.");
+    }
+    if (error instanceof InsufficientScopeError) {
+        return reauthorizationRequired(server, "External MCP requires additional OAuth scope.");
+    }
+    if (error instanceof AuthorizationServerMismatchError) {
+        return reauthorizationRequired(server, "OAuth authorization-server binding changed.");
+    }
+    if (error instanceof UnauthorizedError || (error instanceof SdkHttpError && error.status === 401)) {
+        return runtimeAuth?.authProvider
+            ? reauthorizationRequired(server, "Stored OAuth credentials were rejected.")
+            : authRequired(server);
+    }
+    if (isCredentialReauthorizationError(error)) {
+        return reauthorizationRequired(server, "Stored OAuth credentials require fresh authorization.");
+    }
+    return undefined;
+}
+export class ExternalMcpInteractiveOAuthProvider {
+    options;
+    redirectUrl;
+    clientMetadataUrl;
+    clientMetadata;
+    stateValue = randomBytes(32).toString("base64url");
+    codeVerifierValue;
+    clientInformationValue;
+    tokensValue;
+    discoveryStateValue;
+    authorizationServerUrlValue;
+    resourceUrlValue;
+    constructor(options) {
+        this.options = options;
+        this.redirectUrl = options.redirectUrl;
+        this.clientMetadataUrl = options.clientMetadataUrl;
+        this.clientMetadata = {
+            client_name: CLIENT_NAME,
+            client_uri: CLIENT_URI,
+            redirect_uris: [this.redirectUrl.toString()],
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+        };
+        if (options.existing && sameServerUrl(options.existing.serverUrl, options.serverUrl)) {
+            this.clientInformationValue = clone(options.existing.clientInformation);
+            this.tokensValue = clone(options.existing.tokens);
+            this.discoveryStateValue = clone(options.existing.discoveryState);
+            this.authorizationServerUrlValue = options.existing.authorizationServerUrl;
+            this.resourceUrlValue = options.existing.resourceUrl;
+        }
+    }
+    state() {
+        return this.stateValue;
+    }
+    clientInformation(_ctx) {
+        return clone(this.clientInformationValue);
+    }
+    saveClientInformation(clientInformation) {
+        this.clientInformationValue = clone(clientInformation);
+    }
+    tokens(_ctx) {
+        return clone(this.tokensValue);
+    }
+    saveTokens(tokens) {
+        this.tokensValue = clone(tokens);
+    }
+    redirectToAuthorization(authorizationUrl) {
+        return this.options.onAuthorizationUrl(new URL(authorizationUrl));
+    }
+    saveCodeVerifier(codeVerifier) {
+        this.codeVerifierValue = codeVerifier;
+    }
+    codeVerifier() {
+        if (!this.codeVerifierValue)
+            throw new Error("OAuth PKCE verifier is not available for this authorization session.");
+        return this.codeVerifierValue;
+    }
+    saveAuthorizationServerUrl(authorizationServerUrl) {
+        this.authorizationServerUrlValue = authorizationServerUrl;
+    }
+    authorizationServerUrl() {
+        return this.authorizationServerUrlValue;
+    }
+    saveResourceUrl(resourceUrl) {
+        this.resourceUrlValue = resourceUrl;
+    }
+    resourceUrl() {
+        return this.resourceUrlValue;
+    }
+    saveDiscoveryState(state) {
+        this.discoveryStateValue = clone(state);
+    }
+    discoveryState() {
+        return clone(this.discoveryStateValue);
+    }
+    invalidateCredentials(scope) {
+        if (scope === "all" || scope === "client")
+            this.clientInformationValue = undefined;
+        if (scope === "all" || scope === "tokens")
+            this.tokensValue = undefined;
+        if (scope === "all" || scope === "verifier")
+            this.codeVerifierValue = undefined;
+        if (scope === "all" || scope === "discovery") {
+            this.discoveryStateValue = undefined;
+            this.authorizationServerUrlValue = undefined;
+            this.resourceUrlValue = undefined;
+        }
+    }
+    validateCallback(callbackUrl) {
+        if (callbackUrl.origin !== this.redirectUrl.origin || callbackUrl.pathname !== this.redirectUrl.pathname) {
+            throw new Error("OAuth callback URL does not match the ForgeRelay redirect URL.");
+        }
+        const state = callbackUrl.searchParams.get("state");
+        if (!state || state !== this.stateValue)
+            throw new Error("OAuth callback state did not match the authorization request.");
+        const error = callbackUrl.searchParams.get("error");
+        if (error)
+            throw new Error(`OAuth authorization failed: ${safeOAuthErrorCode(error)}.`);
+        const code = callbackUrl.searchParams.get("code");
+        if (!code)
+            throw new Error("OAuth callback did not contain an authorization code.");
+        const iss = callbackUrl.searchParams.get("iss") ?? undefined;
+        return { code, ...(iss ? { iss } : {}) };
+    }
+    snapshot() {
+        return {
+            ...(this.tokensValue ? { tokens: clone(this.tokensValue) } : {}),
+            ...(this.clientInformationValue ? { clientInformation: clone(this.clientInformationValue) } : {}),
+            ...(this.discoveryStateValue ? { discoveryState: clone(this.discoveryStateValue) } : {}),
+            ...(this.authorizationServerUrlValue ? { authorizationServerUrl: this.authorizationServerUrlValue } : {}),
+            ...(this.resourceUrlValue ? { resourceUrl: this.resourceUrlValue } : {}),
+        };
+    }
+}
+export async function beginExternalMcpInteractiveOAuth(provider, serverUrl, requestedScope) {
+    // A manual auth command must rediscover the current authorization server instead of
+    // trusting discovery state captured by an older credential for the same MCP URL.
+    provider.invalidateCredentials("discovery");
+    const challenge = await probeExternalMcpOAuthChallenge(serverUrl);
+    const scope = computeScopeUnion(requestedScope, challenge.scope);
+    const result = await auth(provider, {
+        serverUrl,
+        ...(challenge.resourceMetadataUrl ? { resourceMetadataUrl: challenge.resourceMetadataUrl } : {}),
+        ...(scope ? { scope } : {}),
+        forceReauthorization: true,
+    });
+    if (result !== "REDIRECT")
+        throw new Error("External MCP OAuth did not start an interactive authorization redirect.");
+}
+async function probeExternalMcpOAuthChallenge(serverUrl) {
+    const response = await fetch(serverUrl, {
+        method: "POST",
+        redirect: "manual",
+        headers: {
+            accept: "application/json, text/event-stream",
+            "content-type": "application/json",
+            "mcp-protocol-version": LATEST_PROTOCOL_VERSION,
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: "forgerelay-oauth-probe",
+            method: "server/discover",
+            params: {
+                _meta: {
+                    "io.modelcontextprotocol/protocolVersion": LATEST_PROTOCOL_VERSION,
+                    "io.modelcontextprotocol/clientCapabilities": {},
+                    "io.modelcontextprotocol/clientInfo": { name: "forgerelay", version: "1.0.0" },
+                },
+            },
+        }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    try {
+        if (response.status !== 401)
+            return {};
+        const challenge = extractWWWAuthenticateParams(response);
+        return {
+            ...(challenge.resourceMetadataUrl ? { resourceMetadataUrl: challenge.resourceMetadataUrl } : {}),
+            ...(challenge.scope ? { scope: challenge.scope } : {}),
+        };
+    }
+    finally {
+        await response.text().catch(() => "");
+    }
+}
+export async function finishExternalMcpInteractiveOAuth(provider, serverUrl, callbackUrl) {
+    const callback = provider.validateCallback(callbackUrl);
+    const result = await auth(provider, {
+        serverUrl,
+        authorizationCode: callback.code,
+        ...(callback.iss ? { iss: callback.iss } : {}),
+    });
+    if (result !== "AUTHORIZED")
+        throw new Error("External MCP OAuth token exchange did not complete.");
+    const snapshot = provider.snapshot();
+    if (!snapshot.tokens?.access_token || !snapshot.clientInformation) {
+        throw new Error("External MCP OAuth completed without usable credentials.");
+    }
+    return snapshot;
+}
+function assertStoredBinding(record) {
+    const authorizationServerUrl = record.discoveryState?.authorizationServerUrl ?? record.authorizationServerUrl;
+    if (!authorizationServerUrl)
+        return;
+    const expectedIssuer = storedIssuer(record, authorizationServerUrl);
+    for (const candidate of [record.tokens?.issuer, record.clientInformation?.issuer]) {
+        if (candidate && !sameIssuer(candidate, expectedIssuer)) {
+            throw new AuthorizationServerMismatchError(candidate, expectedIssuer);
+        }
+    }
+}
+function storedIssuer(record, authorizationServerUrl) {
+    return record.discoveryState?.authorizationServerMetadata?.issuer
+        ?? record.authorizationServerUrl
+        ?? authorizationServerUrl;
+}
+async function markReauthorization(store, identity, current, reason, details = {}) {
+    await store.replace(identity, current.serverUrl, {
+        ...(current.tokens ? { tokens: current.tokens } : {}),
+        ...(current.clientInformation ? { clientInformation: current.clientInformation } : {}),
+        ...(current.discoveryState ? { discoveryState: current.discoveryState } : {}),
+        ...(current.authorizationServerUrl ? { authorizationServerUrl: current.authorizationServerUrl } : {}),
+        ...(current.resourceUrl ? { resourceUrl: current.resourceUrl } : {}),
+        reauthorization: {
+            reason,
+            observedAt: new Date().toISOString(),
+            ...(details.scope?.trim() ? { scope: details.scope.trim() } : {}),
+        },
+    });
+}
+function isCredentialReauthorizationError(error) {
+    return error instanceof OAuthError && [
+        OAuthErrorCode.InvalidGrant,
+        OAuthErrorCode.InvalidClient,
+        OAuthErrorCode.UnauthorizedClient,
+    ].includes(error.code);
+}
+function authRequired(server) {
+    return new ExternalMcpOAuthError("auth_required", `External MCP ${server} requires OAuth authorization. Run: forgerelay mcp auth ${server}`);
+}
+function reauthorizationRequired(server, reason) {
+    return new ExternalMcpOAuthError("reauthorization_required", `${reason} Run: forgerelay mcp auth ${server}`);
+}
+function sameServerUrl(left, right) {
+    try {
+        return new URL(left).toString() === new URL(right).toString();
+    }
+    catch {
+        return false;
+    }
+}
+function sameIssuer(left, right) {
+    // RFC 9207 issuer validation uses simple string comparison; URL normalization
+    // would incorrectly treat distinct issuer identifiers as equivalent.
+    return left === right;
+}
+function safeOAuthErrorCode(value) {
+    return /^[a-z0-9._-]{1,80}$/i.test(value) ? value : "authorization_error";
+}
+function clone(value) {
+    return value === undefined ? undefined : structuredClone(value);
+}

package/dist/mcp/operations/external-mcp/external-mcp-runtime.js

@@ -1,28 +1,45 @@
+import { ExternalMcpConfigRegistry } from "../../../runtime/config/external-mcp-registry.js";
+import { ExternalMcpCredentialStore } from "../../../runtime/config/external-mcp-auth-store.js";
+import { logEvent } from "../../../runtime/logging/logger.js";
 import { CapabilityError } from "../../server/core/capability-registry.js";
 import { requireCapabilityWorkspaceRoot } from "../../server/core/capability-support.js";
 import { ExternalMcpTransformError, ExternalMcpTransformRunner, } from "../../hooks/external-mcp-transform.js";
 import { ExternalMcpError, ExternalMcpGateway } from "./external-mcp.js";
 export function createExternalMcpCapabilityRuntime(config) {
-    const externalMcp = new ExternalMcpGateway(config.mcpServers, config.mediaMaxBytes);
+    const credentialStore = new ExternalMcpCredentialStore({ configDir: config.configDir });
+    const externalMcp = new ExternalMcpGateway(config.mediaMaxBytes, credentialStore);
+    const registry = new ExternalMcpConfigRegistry({
+        configDir: config.configDir,
+        legacyServers: config.mcpServers,
+        onDiagnostic: (diagnostic) => logEvent(config.logging, "warn", "external_mcp_config_invalid", {
+            source: diagnostic.source,
+            path: diagnostic.path,
+            reason: diagnostic.message,
+        }),
+    });
     const transforms = new ExternalMcpTransformRunner(config.hooks, config.logging, process.env, config.commandShellRuntime, config.mediaMaxBytes);
     return {
-        available: externalMcp.available,
-        unavailableReason: externalMcp.available ? undefined : "No external MCP servers are configured.",
+        available: true,
         run: async (input, context, runOptions) => {
             try {
+                const workspaceRoot = requireCapabilityWorkspaceRoot(context);
+                const snapshot = registry.resolve(workspaceRoot);
                 const transformContext = (server, tool) => ({
                     workspaceId: context.workspaceId,
-                    workspaceRoot: requireCapabilityWorkspaceRoot(context),
+                    workspaceRoot,
                     workspaceMode: context.workspaceMode,
                     server,
                     tool,
                 });
-                const result = await externalMcp.run(input, runOptions.signal, input.operation === "call"
+                const result = await externalMcp.run(snapshot.servers, input, runOptions.signal, input.operation === "call"
                     ? {
                         request: (server, tool, arguments_) => transforms.transformRequest(transformContext(server, tool), arguments_, runOptions.signal),
                         result: (server, tool, externalResult) => transforms.transformResult(transformContext(server, tool), externalResult, runOptions.signal),
                     }
-                    : undefined);
+                    : undefined, {
+                    workspaceRoot,
+                    origins: snapshot.origins,
+                });
                 return {
                     value: result.value,
                     ...(result.content ? { content: result.content } : {}),