@decocms/runtime 1.0.0-alpha.22 → 1.0.0-alpha.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/runtime",
-  "version": "1.0.0-alpha.22",
+  "version": "1.0.0-alpha.23",
   "type": "module",
   "dependencies": {
     "@cloudflare/workers-types": "^4.20250617.0",

package/src/index.ts

@@ -3,6 +3,7 @@ import { decodeJwt } from "jose";
 import type { z } from "zod";
 import { createContractBinding, createIntegrationBinding } from "./bindings.ts";
 import { type CORSOptions, handlePreflight, withCORS } from "./cors.ts";
+import { createOAuthHandlers } from "./oauth.ts";
 import { State } from "./state.ts";
 import {
   createMCPServer,
@@ -233,6 +234,8 @@ export const withRuntime = <TEnv, TSchema extends z.ZodTypeAny = never>(
 ) => {
   const server = createMCPServer<TEnv, TSchema>(userFns);
   const corsOptions = userFns.cors;
+  const oauth = userFns.oauth;
+  const oauthHandlers = oauth ? createOAuthHandlers(oauth) : null;
 
   const fetcher = async (
     req: Request,
@@ -240,7 +243,35 @@ export const withRuntime = <TEnv, TSchema extends z.ZodTypeAny = never>(
     ctx: any,
   ) => {
     const url = new URL(req.url);
+
+    // OAuth routes (when configured)
+    if (oauthHandlers) {
+      // Protected resource metadata (RFC9728) - both paths MUST be supported
+      if (
+        url.pathname === "/.well-known/oauth-protected-resource" ||
+        url.pathname === "/mcp/.well-known/oauth-protected-resource"
+      ) {
+        return oauthHandlers.handleProtectedResourceMetadata(req);
+      }
+
+      // OAuth callback - receives code from external OAuth provider
+      if (url.pathname === "/oauth/callback") {
+        return oauthHandlers.handleOAuthCallback(req);
+      }
+
+      // Dynamic client registration (RFC7591)
+      if (url.pathname === "/mcp/register" && req.method === "POST") {
+        return oauthHandlers.handleClientRegistration(req);
+      }
+    }
+
+    // MCP endpoint
     if (url.pathname === "/mcp") {
+      // If OAuth is configured, require authentication
+      if (oauthHandlers && !oauthHandlers.hasAuth(req)) {
+        return oauthHandlers.createUnauthorizedResponse(req);
+      }
+
       return server.fetch(req, env, ctx);
     }
 
@@ -273,7 +304,7 @@ export const withRuntime = <TEnv, TSchema extends z.ZodTypeAny = never>(
   };
 
   return {
-    fetch: async (req: Request, env: TEnv & DefaultEnv<TSchema>, ctx: any) => {
+    fetch: async (req: Request, env: TEnv & DefaultEnv<TSchema>, ctx?: any) => {
       // Handle CORS preflight (OPTIONS) requests
       if (corsOptions !== false && req.method === "OPTIONS") {
         const options = corsOptions ?? {};

package/src/oauth.ts

@@ -0,0 +1,229 @@
+import type { OAuthClient, OAuthConfig, OAuthParams } from "./tools.ts";
+
+/**
+ * Generate a cryptographically secure random token
+ */
+function generateRandomToken(length = 32): string {
+  const chars =
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  const array = new Uint8Array(length);
+  crypto.getRandomValues(array);
+  return Array.from(array, (byte) => chars[byte % chars.length]).join("");
+}
+
+/**
+ * Validate redirect URI format per OAuth 2.1
+ */
+function isValidRedirectUri(uri: string): boolean {
+  try {
+    const url = new URL(uri);
+    return (
+      url.protocol === "https:" ||
+      url.hostname === "localhost" ||
+      url.hostname === "127.0.0.1" ||
+      // Allow custom schemes for native apps (e.g., cursor://, vscode://)
+      !url.protocol.startsWith("http")
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create OAuth endpoint handlers for MCP servers
+ * Per MCP Authorization spec: https://modelcontextprotocol.io/specification/draft/basic/authorization
+ */
+export function createOAuthHandlers(oauth: OAuthConfig) {
+  /**
+   * Build OAuth 2.0 Protected Resource Metadata (RFC9728)
+   * Per MCP spec, this MUST point to the external authorization server
+   */
+  const handleProtectedResourceMetadata = (req: Request): Response => {
+    const url = new URL(req.url);
+    const resourceUrl = `${url.origin}/mcp`;
+
+    return Response.json({
+      resource: resourceUrl,
+      authorization_servers: [oauth.authorizationServer],
+      scopes_supported: ["*"],
+      bearer_methods_supported: ["header"],
+      resource_signing_alg_values_supported: ["RS256", "none"],
+    });
+  };
+
+  /**
+   * Handle OAuth callback - receives code from external OAuth provider
+   */
+  const handleOAuthCallback = async (req: Request): Promise<Response> => {
+    const url = new URL(req.url);
+    const code = url.searchParams.get("code");
+    const codeVerifier = url.searchParams.get("code_verifier") ?? undefined;
+    const codeChallengeMethod = url.searchParams.get("code_challenge_method") as
+      | "S256"
+      | "plain"
+      | undefined;
+
+    if (!code) {
+      return Response.json(
+        {
+          error: "invalid_request",
+          error_description: "Missing code parameter",
+        },
+        { status: 400 },
+      );
+    }
+
+    try {
+      const oauthParams: OAuthParams = {
+        code,
+        code_verifier: codeVerifier,
+        code_challenge_method: codeChallengeMethod,
+      };
+      const tokenResponse = await oauth.exchangeCode(oauthParams);
+
+      return Response.json(tokenResponse, {
+        headers: {
+          "Cache-Control": "no-store",
+          Pragma: "no-cache",
+        },
+      });
+    } catch (error) {
+      console.error("OAuth code exchange error:", error);
+      return Response.json(
+        {
+          error: "invalid_grant",
+          error_description: "Failed to exchange authorization code",
+        },
+        { status: 400 },
+      );
+    }
+  };
+
+  /**
+   * Handle dynamic client registration (RFC7591)
+   */
+  const handleClientRegistration = async (req: Request): Promise<Response> => {
+    try {
+      const body = (await req.json()) as {
+        redirect_uris?: string[];
+        client_name?: string;
+        grant_types?: string[];
+        response_types?: string[];
+        token_endpoint_auth_method?: string;
+        scope?: string;
+      };
+
+      // Validate redirect URIs
+      if (!body.redirect_uris || body.redirect_uris.length === 0) {
+        return Response.json(
+          {
+            error: "invalid_redirect_uri",
+            error_description: "At least one redirect_uri is required",
+          },
+          { status: 400 },
+        );
+      }
+
+      for (const uri of body.redirect_uris) {
+        if (!isValidRedirectUri(uri)) {
+          return Response.json(
+            {
+              error: "invalid_redirect_uri",
+              error_description: `Invalid redirect URI: ${uri}`,
+            },
+            { status: 400 },
+          );
+        }
+      }
+
+      const clientId = generateRandomToken(32);
+      const clientSecret =
+        body.token_endpoint_auth_method !== "none"
+          ? generateRandomToken(32)
+          : undefined;
+      const now = Math.floor(Date.now() / 1000);
+
+      const client: OAuthClient = {
+        client_id: clientId,
+        client_secret: clientSecret,
+        client_name: body.client_name,
+        redirect_uris: body.redirect_uris,
+        grant_types: body.grant_types ?? ["authorization_code"],
+        response_types: body.response_types ?? ["code"],
+        token_endpoint_auth_method:
+          body.token_endpoint_auth_method ?? "client_secret_post",
+        scope: body.scope,
+        client_id_issued_at: now,
+        client_secret_expires_at: 0,
+      };
+
+      // Save client if persistence is provided
+      if (oauth.persistence) {
+        await oauth.persistence.saveClient(client);
+      }
+
+      return new Response(JSON.stringify(client), {
+        status: 201,
+        headers: {
+          "Content-Type": "application/json",
+          "Cache-Control": "no-store",
+          Pragma: "no-cache",
+        },
+      });
+    } catch (error) {
+      console.error("Client registration error:", error);
+      return Response.json(
+        {
+          error: "invalid_client_metadata",
+          error_description: "Invalid client registration request",
+        },
+        { status: 400 },
+      );
+    }
+  };
+
+  /**
+   * Return 401 with WWW-Authenticate header for unauthenticated MCP requests
+   * Per MCP spec: MUST include resource_metadata URL
+   */
+  const createUnauthorizedResponse = (req: Request): Response => {
+    const url = new URL(req.url);
+    const resourceMetadataUrl = `${url.origin}/.well-known/oauth-protected-resource`;
+    const wwwAuthenticateValue = `Bearer resource_metadata="${resourceMetadataUrl}", scope="*"`;
+
+    return Response.json(
+      {
+        jsonrpc: "2.0",
+        error: {
+          code: -32000,
+          message: "Unauthorized: Authentication required",
+        },
+        id: null,
+      },
+      {
+        status: 401,
+        headers: {
+          "WWW-Authenticate": wwwAuthenticateValue,
+          "Access-Control-Expose-Headers": "WWW-Authenticate",
+        },
+      },
+    );
+  };
+
+  /**
+   * Check if request has authentication token
+   */
+  const hasAuth = (req: Request): boolean => {
+    const authHeader = req.headers.get("Authorization");
+    const meshToken = req.headers.get("x-mesh-token");
+    return !!(authHeader || meshToken);
+  };
+
+  return {
+    handleProtectedResourceMetadata,
+    handleOAuthCallback,
+    handleClientRegistration,
+    createUnauthorizedResponse,
+    hasAuth,
+  };
+}

package/src/tools.ts

@@ -149,11 +149,76 @@ export interface OnChangeCallback<TSchema extends z.ZodTypeAny = never> {
   state: z.infer<TSchema>;
   scopes: string[];
 }
+
+export interface OAuthParams {
+  code: string;
+  code_verifier?: string;
+  code_challenge_method?: "S256" | "plain";
+}
+
+export interface OAuthTokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in?: number;
+  refresh_token?: string;
+  scope?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * OAuth client for dynamic client registration (RFC7591)
+ */
+export interface OAuthClient {
+  client_id: string;
+  client_secret?: string;
+  client_name?: string;
+  redirect_uris: string[];
+  grant_types?: string[];
+  response_types?: string[];
+  token_endpoint_auth_method?: string;
+  scope?: string;
+  client_id_issued_at?: number;
+  client_secret_expires_at?: number;
+}
+
+/**
+ * OAuth configuration for MCP servers implementing PKCE flow
+ * Per MCP Authorization spec: https://modelcontextprotocol.io/specification/draft/basic/authorization
+ */
+export interface OAuthConfig {
+  mode: "PKCE";
+  /**
+   * The external authorization server URL (e.g., "https://openrouter.ai")
+   * Used in protected resource metadata to indicate where clients should authenticate
+   */
+  authorizationServer: string;
+  /**
+   * Generates the authorization URL where users should be redirected
+   * @param callbackUrl - The URL the OAuth provider will redirect back to with the code
+   * @returns The full authorization URL to redirect the user to
+   */
+  authorizationUrl: (callbackUrl: string) => string;
+  /**
+   * Exchanges the authorization code for access tokens
+   * Called when the OAuth callback is received with a code
+   */
+  exchangeCode: (oauthParams: OAuthParams) => Promise<OAuthTokenResponse>;
+  /**
+   * Optional: persistence for dynamic client registration (RFC7591)
+   * If not provided, clients are accepted without validation
+   */
+  persistence?: {
+    getClient: (clientId: string) => Promise<OAuthClient | null>;
+    saveClient: (client: OAuthClient) => Promise<void>;
+  };
+}
+
 export interface CreateMCPServerOptions<
   Env = unknown,
   TSchema extends z.ZodTypeAny = never,
 > {
   before?: (env: Env & DefaultEnv<TSchema>) => Promise<void> | void;
+  oauth?: OAuthConfig;
   configuration?: {
     onChange?: (
       env: Env & DefaultEnv<TSchema>,