@decocms/runtime 1.2.5 → 1.2.7

package/README.md

@@ -0,0 +1,770 @@
+# @decocms/runtime
+
+A TypeScript framework for building MCP (Model Context Protocol) servers with first-class support for tools, prompts, resources, OAuth authentication, and event-driven architectures.
+
+## Installation
+
+```bash
+bun add @decocms/runtime
+```
+
+Or with npm:
+
+```bash
+npm install @decocms/runtime
+```
+
+## Quick Start
+
+Create a simple MCP server with tools:
+
+```typescript
+import { withRuntime, createTool } from "@decocms/runtime";
+import { z } from "zod";
+
+// Define a tool
+const greetTool = createTool({
+  id: "greet",
+  description: "Greets a user by name",
+  inputSchema: z.object({
+    name: z.string().describe("Name of the person to greet"),
+  }),
+  outputSchema: z.object({
+    message: z.string(),
+  }),
+  execute: async ({ context }) => {
+    return { message: `Hello, ${context.name}!` };
+  },
+});
+
+// Create the MCP server
+export default withRuntime({
+  tools: [() => greetTool],
+});
+```
+
+The server automatically exposes an MCP endpoint at `/mcp` that handles all MCP protocol requests.
+
+## Core Concepts
+
+### withRuntime
+
+The `withRuntime` function is the main entry point for creating an MCP server. It accepts configuration options and returns a fetch handler compatible with Cloudflare Workers, Bun, and other web standard runtimes.
+
+```typescript
+import { withRuntime } from "@decocms/runtime";
+
+export default withRuntime({
+  // Tools exposed to LLMs
+  tools: [...],
+  
+  // Prompts for guided interactions
+  prompts: [...],
+  
+  // Resources for data access
+  resources: [...],
+  
+  // Optional: Custom fetch handler for non-MCP routes
+  fetch: async (req, env, ctx) => {
+    // Handle custom routes
+    return new Response("Custom response");
+  },
+  
+  // Optional: CORS configuration
+  cors: {
+    origin: "*",
+    credentials: true,
+  },
+  
+  // Optional: OAuth configuration
+  oauth: { ... },
+  
+  // Optional: Configuration state
+  configuration: { ... },
+  
+  // Optional: Event handlers
+  events: { ... },
+  
+  // Optional: Hook before request processing
+  before: async (env) => {
+    // Initialize resources
+  },
+});
+```
+
+## Tools
+
+Tools are functions that LLMs can invoke to perform actions or retrieve data.
+
+### Creating a Tool
+
+```typescript
+import { createTool } from "@decocms/runtime";
+import { z } from "zod";
+
+const calculateTool = createTool({
+  id: "calculate",
+  description: "Performs basic arithmetic operations",
+  inputSchema: z.object({
+    operation: z.enum(["add", "subtract", "multiply", "divide"]),
+    a: z.number(),
+    b: z.number(),
+  }),
+  outputSchema: z.object({
+    result: z.number(),
+  }),
+  execute: async ({ context }) => {
+    const { operation, a, b } = context;
+    let result: number;
+    
+    switch (operation) {
+      case "add": result = a + b; break;
+      case "subtract": result = a - b; break;
+      case "multiply": result = a * b; break;
+      case "divide": result = a / b; break;
+    }
+    
+    return { result };
+  },
+});
+```
+
+### Private Tools (Authentication Required)
+
+Use `createPrivateTool` for tools that require user authentication:
+
+```typescript
+import { createPrivateTool } from "@decocms/runtime";
+
+const getUserDataTool = createPrivateTool({
+  id: "getUserData",
+  description: "Retrieves the current user's data",
+  inputSchema: z.object({}),
+  outputSchema: z.object({
+    userId: z.string(),
+    email: z.string(),
+  }),
+  execute: async ({ runtimeContext }) => {
+    // ensureAuthenticated is called automatically
+    const user = runtimeContext.env.MESH_REQUEST_CONTEXT.ensureAuthenticated();
+    return { userId: user.id, email: user.email };
+  },
+});
+```
+
+### Streamable Tools
+
+For tools that return streaming responses:
+
+```typescript
+import { createStreamableTool } from "@decocms/runtime";
+
+const streamDataTool = createStreamableTool({
+  id: "streamData",
+  description: "Streams data as a response",
+  inputSchema: z.object({
+    query: z.string(),
+  }),
+  streamable: true,
+  execute: async ({ context }) => {
+    // Return a streaming Response
+    const stream = new ReadableStream({
+      async start(controller) {
+        controller.enqueue(new TextEncoder().encode("Chunk 1\n"));
+        controller.enqueue(new TextEncoder().encode("Chunk 2\n"));
+        controller.close();
+      },
+    });
+    
+    return new Response(stream, {
+      headers: { "Content-Type": "text/plain" },
+    });
+  },
+});
+```
+
+### Registering Tools
+
+Tools can be registered in multiple ways:
+
+```typescript
+export default withRuntime({
+  // Option 1: Array of tool factories
+  tools: [
+    () => greetTool,
+    () => calculateTool,
+    (env) => createDynamicTool(env),
+  ],
+  
+  // Option 2: Single function returning array
+  tools: async (env) => {
+    return [greetTool, calculateTool];
+  },
+});
+```
+
+## Prompts
+
+Prompts define guided interactions with predefined templates.
+
+### Creating a Prompt
+
+```typescript
+import { createPrompt, createPublicPrompt } from "@decocms/runtime";
+import { z } from "zod";
+
+const codeReviewPrompt = createPrompt({
+  name: "code-review",
+  title: "Code Review",
+  description: "Provides a structured code review",
+  argsSchema: {
+    code: z.string().describe("The code to review"),
+    language: z.string().optional().describe("Programming language"),
+  },
+  execute: async ({ args }) => {
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Please review this ${args.language ?? "code"}:\n\n${args.code}`,
+          },
+        },
+      ],
+    };
+  },
+});
+
+// Public prompt (no auth required)
+const welcomePrompt = createPublicPrompt({
+  name: "welcome",
+  title: "Welcome Message",
+  description: "Generates a welcome message",
+  execute: async () => {
+    return {
+      messages: [
+        {
+          role: "user",
+          content: { type: "text", text: "Welcome to our MCP server!" },
+        },
+      ],
+    };
+  },
+});
+```
+
+## Resources
+
+Resources expose data that LLMs can read.
+
+### Creating a Resource
+
+```typescript
+import { createResource, createPublicResource } from "@decocms/runtime";
+
+const configResource = createResource({
+  uri: "config://app",
+  name: "App Configuration",
+  description: "Current application configuration",
+  mimeType: "application/json",
+  read: async ({ runtimeContext }) => {
+    const config = await loadConfig();
+    return {
+      uri: "config://app",
+      mimeType: "application/json",
+      text: JSON.stringify(config, null, 2),
+    };
+  },
+});
+
+// URI templates for dynamic resources
+const fileResource = createPublicResource({
+  uri: "file://{path}",
+  name: "File Reader",
+  description: "Reads file contents",
+  read: async ({ uri }) => {
+    const path = uri.pathname;
+    const content = await readFile(path);
+    return {
+      uri: uri.toString(),
+      mimeType: "text/plain",
+      text: content,
+    };
+  },
+});
+```
+
+## OAuth Authentication
+
+Enable OAuth for protected MCP endpoints:
+
+```typescript
+import { withRuntime, type OAuthConfig } from "@decocms/runtime";
+
+const oauthConfig: OAuthConfig = {
+  mode: "PKCE",
+  
+  // External OAuth provider URL
+  authorizationServer: "https://your-oauth-provider.com",
+  
+  // Generate authorization URL
+  authorizationUrl: (callbackUrl) => {
+    const url = new URL("https://your-oauth-provider.com/authorize");
+    url.searchParams.set("client_id", "your-client-id");
+    url.searchParams.set("redirect_uri", callbackUrl);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", "openid profile email");
+    return url.toString();
+  },
+  
+  // Exchange authorization code for tokens
+  exchangeCode: async ({ code, redirect_uri }) => {
+    const response = await fetch("https://your-oauth-provider.com/token", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirect_uri!,
+        client_id: "your-client-id",
+        client_secret: "your-client-secret",
+      }),
+    });
+    return response.json();
+  },
+  
+  // Optional: Refresh token support
+  refreshToken: async (refreshToken) => {
+    const response = await fetch("https://your-oauth-provider.com/token", {
+      method: "POST",
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+      }),
+    });
+    return response.json();
+  },
+};
+
+export default withRuntime({
+  oauth: oauthConfig,
+  tools: [...],
+});
+```
+
+OAuth endpoints are automatically exposed:
+- `/.well-known/oauth-protected-resource` - Resource metadata
+- `/.well-known/oauth-authorization-server` - Server metadata
+- `/authorize` - Authorization endpoint
+- `/oauth/callback` - OAuth callback
+- `/token` - Token endpoint
+- `/register` - Dynamic client registration
+
+## Configuration State
+
+Define typed configuration state that persists across requests:
+
+```typescript
+import { withRuntime, BindingOf } from "@decocms/runtime";
+import { z } from "zod";
+
+// Define your state schema
+const stateSchema = z.object({
+  apiKey: z.string(),
+  maxTokens: z.number().default(1000),
+  // Bindings reference other MCP connections
+  database: BindingOf<MyRegistry, "@deco/database">("@deco/database"),
+});
+
+export default withRuntime({
+  configuration: {
+    state: stateSchema,
+    scopes: ["API_KEY::read", "DATABASE::query"],
+    
+    // Called when configuration changes
+    onChange: async (env, { state, scopes }) => {
+      console.log("Configuration updated:", state);
+    },
+  },
+  
+  tools: [
+    (env) => createTool({
+      id: "query",
+      inputSchema: z.object({ sql: z.string() }),
+      execute: async ({ runtimeContext }) => {
+        // Access resolved bindings from state
+        const { database } = runtimeContext.env.MESH_REQUEST_CONTEXT.state;
+        return database.QUERY({ sql: context.sql });
+      },
+    }),
+  ],
+});
+```
+
+## Event Handlers
+
+Subscribe to events from other MCP connections:
+
+```typescript
+import { withRuntime, SELF } from "@decocms/runtime";
+
+export default withRuntime({
+  configuration: {
+    state: z.object({
+      database: BindingOf<Registry, "@deco/database">("@deco/database"),
+    }),
+  },
+  
+  events: {
+    // Subscribe to events from the database binding
+    database: {
+      // Per-event handlers
+      "record.created": async ({ events }, env) => {
+        for (const event of events) {
+          console.log("New record:", event.data);
+        }
+        return { success: true };
+      },
+      "record.deleted": async ({ events }, env) => {
+        return { success: true };
+      },
+    },
+    
+    // Subscribe to events from self (this connection)
+    SELF: {
+      "order.completed": async ({ events }, env) => {
+        return { success: true };
+      },
+    },
+  },
+});
+
+// Or use batch handlers for multiple event types
+export default withRuntime({
+  events: {
+    handler: async ({ events }, env) => {
+      // Process all events in batch
+      return { success: true };
+    },
+    events: [
+      "SELF::order.created",
+      "database::record.updated",
+    ],
+  },
+});
+```
+
+## Bindings
+
+Bindings define standardized interfaces that MCP servers can implement.
+
+### Using Existing Bindings
+
+```typescript
+import { impl, WellKnownBindings } from "@decocms/runtime/bindings";
+
+// Implement a channel binding
+const channelTools = impl(WellKnownBindings.Channel, [
+  {
+    description: "Join a channel",
+    handler: async ({ workspace, channelId }) => {
+      // Implementation
+      return { success: true, channelId };
+    },
+  },
+  {
+    description: "Leave a channel",
+    handler: async ({ channelId }) => {
+      return { success: true };
+    },
+  },
+]);
+
+export default withRuntime({
+  tools: [() => channelTools].flat(),
+});
+```
+
+### Creating Custom Bindings
+
+```typescript
+import { z } from "zod";
+import type { Binder } from "@decocms/runtime/bindings";
+
+// Define your binding schema
+export const MY_BINDING = [
+  {
+    name: "MY_TOOL_ACTION" as const,
+    inputSchema: z.object({
+      param: z.string(),
+    }),
+    outputSchema: z.object({
+      result: z.string(),
+    }),
+  },
+  {
+    name: "MY_TOOL_QUERY" as const,
+    inputSchema: z.object({}),
+    outputSchema: z.object({
+      items: z.array(z.string()),
+    }),
+    opt: true, // Optional tool
+  },
+] as const satisfies Binder;
+```
+
+## Custom Fetch Handler
+
+Handle non-MCP routes alongside your MCP server:
+
+```typescript
+export default withRuntime({
+  tools: [...],
+  
+  fetch: async (req, env, ctx) => {
+    const url = new URL(req.url);
+    
+    if (url.pathname === "/api/health") {
+      return new Response(JSON.stringify({ status: "ok" }), {
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+    
+    if (url.pathname.startsWith("/api/")) {
+      // Handle API routes
+      return handleApiRoutes(req, env);
+    }
+    
+    return new Response("Not Found", { status: 404 });
+  },
+});
+```
+
+## CORS Configuration
+
+Configure CORS for browser-based MCP clients:
+
+```typescript
+export default withRuntime({
+  cors: {
+    origin: ["https://example.com", "http://localhost:3000"],
+    credentials: true,
+    allowMethods: ["GET", "POST", "OPTIONS"],
+    allowHeaders: ["Content-Type", "Authorization", "mcp-protocol-version"],
+  },
+  
+  // Or disable CORS entirely
+  cors: false,
+});
+```
+
+## Accessing Request Context
+
+Access request context within tools:
+
+```typescript
+const myTool = createTool({
+  id: "contextDemo",
+  inputSchema: z.object({}),
+  execute: async ({ runtimeContext }) => {
+    const { env, req } = runtimeContext;
+    
+    // Access MESH_REQUEST_CONTEXT for auth and bindings
+    const ctx = env.MESH_REQUEST_CONTEXT;
+    
+    // Get authenticated user (throws if not authenticated)
+    const user = ctx.ensureAuthenticated();
+    
+    // Access resolved binding state
+    const state = ctx.state;
+    
+    // Get connection info
+    const { connectionId, organizationId, meshUrl } = ctx;
+    
+    // Access original request
+    const userAgent = req?.headers.get("user-agent");
+    
+    return { userId: user.id };
+  },
+});
+```
+
+## Complete Example
+
+Here's a complete example of an MCP server with tools, prompts, resources, and OAuth:
+
+```typescript
+import { 
+  withRuntime, 
+  createTool, 
+  createPrivateTool,
+  createPrompt,
+  createResource,
+} from "@decocms/runtime";
+import { z } from "zod";
+
+// Public tool - no auth required
+const echoTool = createTool({
+  id: "echo",
+  description: "Echoes the input message",
+  inputSchema: z.object({
+    message: z.string(),
+  }),
+  outputSchema: z.object({
+    echo: z.string(),
+  }),
+  execute: async ({ context }) => {
+    return { echo: context.message };
+  },
+});
+
+// Private tool - requires authentication
+const getProfileTool = createPrivateTool({
+  id: "getProfile",
+  description: "Gets the current user's profile",
+  inputSchema: z.object({}),
+  outputSchema: z.object({
+    id: z.string(),
+    email: z.string(),
+    name: z.string(),
+  }),
+  execute: async ({ runtimeContext }) => {
+    const user = runtimeContext.env.MESH_REQUEST_CONTEXT.ensureAuthenticated();
+    return {
+      id: user.id,
+      email: user.email,
+      name: user.user_metadata.full_name,
+    };
+  },
+});
+
+// Prompt template
+const analyzePrompt = createPrompt({
+  name: "analyze",
+  title: "Analyze Data",
+  description: "Analyzes provided data and returns insights",
+  argsSchema: {
+    data: z.string().describe("JSON data to analyze"),
+  },
+  execute: async ({ args }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `Analyze this data and provide insights:\n\n${args.data}`,
+        },
+      },
+    ],
+  }),
+});
+
+// Resource
+const statusResource = createResource({
+  uri: "status://server",
+  name: "Server Status",
+  description: "Current server status and metrics",
+  mimeType: "application/json",
+  read: async () => ({
+    uri: "status://server",
+    mimeType: "application/json",
+    text: JSON.stringify({
+      status: "healthy",
+      uptime: process.uptime(),
+      timestamp: new Date().toISOString(),
+    }),
+  }),
+});
+
+// Export the MCP server
+export default withRuntime({
+  tools: [
+    () => echoTool,
+    () => getProfileTool,
+  ],
+  prompts: [
+    () => analyzePrompt,
+  ],
+  resources: [
+    () => statusResource,
+  ],
+  cors: {
+    origin: "*",
+    credentials: true,
+  },
+});
+```
+
+## API Reference
+
+### Types
+
+- `Tool<TSchemaIn, TSchemaOut>` - Tool definition with typed input/output
+- `StreamableTool<TSchemaIn>` - Tool that returns streaming Response
+- `Prompt<TArgs>` - Prompt definition with typed arguments
+- `Resource` - Resource definition
+- `OAuthConfig` - OAuth configuration
+- `CreateMCPServerOptions` - Full options for withRuntime
+- `RequestContext` - Request context with auth and bindings
+- `AppContext` - Runtime context passed to execute functions
+
+### Functions
+
+- `withRuntime(options)` - Create an MCP server
+- `createTool(opts)` - Create a public tool
+- `createPrivateTool(opts)` - Create an authenticated tool
+- `createStreamableTool(opts)` - Create a streaming tool
+- `createPrompt(opts)` - Create an authenticated prompt
+- `createPublicPrompt(opts)` - Create a public prompt
+- `createResource(opts)` - Create an authenticated resource
+- `createPublicResource(opts)` - Create a public resource
+- `BindingOf(name)` - Create a binding reference schema
+
+### Exports
+
+```typescript
+// Main entry
+import { withRuntime, createTool, ... } from "@decocms/runtime";
+
+// Bindings utilities
+import { impl, WellKnownBindings, ... } from "@decocms/runtime/bindings";
+
+// MCP client utilities
+import { createMCPFetchStub, MCPClient } from "@decocms/runtime/client";
+
+// Proxy utilities
+import { ... } from "@decocms/runtime/proxy";
+
+// Tool utilities
+import { ... } from "@decocms/runtime/tools";
+```
+
+## Deployment
+
+The server works with any Web Standard runtime:
+
+**Cloudflare Workers:**
+```typescript
+export default withRuntime({ tools: [...] });
+```
+
+**Bun:**
+```typescript
+const server = withRuntime({ tools: [...] });
+Bun.serve({
+  port: 3000,
+  fetch: server.fetch,
+});
+```
+
+**Node.js (with adapter):**
+```typescript
+import { serve } from "@hono/node-server";
+const server = withRuntime({ tools: [...] });
+serve({ fetch: server.fetch, port: 3000 });
+```
+
+## License
+
+See the root LICENSE.md file in the repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/runtime",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",
@@ -8,8 +8,8 @@
   },
   "dependencies": {
     "@cloudflare/workers-types": "^4.20250617.0",
-    "@decocms/bindings": "^1.1.1",
-    "@modelcontextprotocol/sdk": "1.25.2",
+    "@decocms/bindings": "^1.0.7",
+    "@modelcontextprotocol/sdk": "1.25.3",
     "@ai-sdk/provider": "^3.0.0",
     "hono": "^4.10.7",
     "jose": "^6.0.11",
@@ -31,6 +31,11 @@
   "engines": {
     "node": ">=24.0.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/decocms/mesh.git",
+    "directory": "packages/runtime"
+  },
   "publishConfig": {
     "access": "public"
   }

package/scripts/generate-json-schema.ts

@@ -1,11 +1,16 @@
 // heavily inspired by https://github.com/cloudflare/workers-sdk/blob/main/packages/wrangler/scripts/generate-json-schema.ts
 import { writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { createGenerator } from "ts-json-schema-generator";
 import type { Config, Schema } from "ts-json-schema-generator";
 
+// Use standard ESM __dirname pattern for cross-runtime compatibility
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
 const config: Config = {
-  path: join(import.meta.dirname!, "../src/wrangler.ts"),
+  path: join(__dirname, "../src/wrangler.ts"),
+  tsconfig: join(__dirname, "../tsconfig.json"),
   type: "WranglerConfig",
   skipTypeCheck: true,
 };
@@ -19,6 +24,6 @@ const schema = applyFormattingRules(
 );
 
 writeFileSync(
-  join(import.meta.dirname!, "../config-schema.json"),
+  join(__dirname, "../config-schema.json"),
   JSON.stringify(schema, null, 2),
 );

package/src/oauth.ts

@@ -70,6 +70,27 @@ interface CodePayload {
   codeChallengeMethod?: string;
 }
 
+/**
+ * OAuth 2.0/2.1 Token Request Parameters
+ * Per RFC 6749 (OAuth 2.0) and RFC 9207 (OAuth 2.1)
+ * All parameters are strings when properly formatted
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3
+ */
+interface OAuthTokenRequestBody {
+  /** REQUIRED for authorization_code grant - The authorization code from callback */
+  code?: string;
+  /** OPTIONAL - PKCE code verifier (RFC 7636) */
+  code_verifier?: string;
+  /** REQUIRED - Grant type: "authorization_code" or "refresh_token" */
+  grant_type?: string;
+  /** REQUIRED for refresh_token grant - The refresh token */
+  refresh_token?: string;
+  /** OPTIONAL - Redirect URI used in authorization request */
+  redirect_uri?: string;
+  /** Additional provider-specific parameters */
+  [key: string]: unknown;
+}
+
 const forceHttps = (url: URL) => {
   const isLocal = url.hostname === "localhost" || url.hostname === "127.0.0.1";
   if (!isLocal) {
@@ -285,24 +306,41 @@ export function createOAuthHandlers(oauth: OAuthConfig) {
   const handleToken = async (req: Request): Promise<Response> => {
     try {
       const contentType = req.headers.get("content-type") ?? "";
-      let body: Record<string, string>;
+      let body: Record<string, unknown>;
 
       if (contentType.includes("application/x-www-form-urlencoded")) {
         const formData = await req.formData();
-        body = Object.fromEntries(formData.entries()) as Record<string, string>;
+        body = Object.fromEntries(formData.entries());
       } else {
-        body = await req.json();
+        const jsonBody = await req.json();
+        if (
+          typeof jsonBody !== "object" ||
+          jsonBody === null ||
+          Array.isArray(jsonBody)
+        ) {
+          return Response.json(
+            {
+              error: "invalid_request",
+              error_description: "Request body must be a JSON object",
+            },
+            { status: 400 },
+          );
+        }
+        body = jsonBody as Record<string, unknown>;
       }
 
+      // Extract and validate OAuth parameters
+      // Per RFC 6749, all parameters should be strings, but we validate at runtime
       const { code, code_verifier, grant_type, refresh_token } = body;
 
       // Handle refresh_token grant type
       if (grant_type === "refresh_token") {
-        if (!refresh_token) {
+        if (typeof refresh_token !== "string" || !refresh_token) {
           return Response.json(
             {
               error: "invalid_request",
-              error_description: "refresh_token is required",
+              error_description:
+                "refresh_token is required and must be a string",
             },
             { status: 400 },
           );
@@ -356,9 +394,12 @@ export function createOAuthHandlers(oauth: OAuthConfig) {
         );
       }
 
-      if (!code) {
+      if (typeof code !== "string" || !code) {
         return Response.json(
-          { error: "invalid_request", error_description: "code is required" },
+          {
+            error: "invalid_request",
+            error_description: "code is required and must be a string",
+          },
           { status: 400 },
         );
       }
@@ -377,11 +418,11 @@ export function createOAuthHandlers(oauth: OAuthConfig) {
 
       // Verify PKCE if code challenge was provided
       if (payload.codeChallenge) {
-        if (!code_verifier) {
+        if (typeof code_verifier !== "string" || !code_verifier) {
           return Response.json(
             {
               error: "invalid_grant",
-              error_description: "code_verifier required",
+              error_description: "code_verifier required and must be a string",
             },
             { status: 400 },
           );

package/src/tools.ts

@@ -345,39 +345,70 @@ export interface OnChangeCallback<TState> {
   scopes: string[];
 }
 
+/**
+ * OAuth 2.0 Token Exchange Parameters
+ * Parameters passed to exchangeCode() for token retrieval
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3
+ */
 export interface OAuthParams {
+  /** REQUIRED - The authorization code received from the authorization server */
   code: string;
+  /** OPTIONAL - PKCE code verifier (RFC 7636) */
   code_verifier?: string;
+  /** OPTIONAL - Code challenge method: S256 (SHA-256) or plain */
   code_challenge_method?: "S256" | "plain";
   /**
-   * The redirect_uri used in the authorization request (without state/extra params).
-   * This is the clean callback URL that should be used for token exchange.
+   * OPTIONAL - The redirect_uri used in the authorization request
+   * MUST be identical if included in the authorization request
    */
   redirect_uri?: string;
 }
 
+/**
+ * OAuth 2.0 Token Response
+ * Response from the authorization server's token endpoint
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
+ */
 export interface OAuthTokenResponse {
+  /** REQUIRED - The access token issued by the authorization server */
   access_token: string;
+  /** REQUIRED - Type of token (usually "Bearer" per RFC 6750) */
   token_type: string;
+  /** RECOMMENDED - Lifetime in seconds of the access token */
   expires_in?: number;
+  /** OPTIONAL - Used to obtain new access tokens (if applicable) */
   refresh_token?: string;
+  /** OPTIONAL - Scope of the access token (if different from requested) */
   scope?: string;
+  /** Additional provider-specific fields */
   [key: string]: unknown;
 }
 
 /**
- * OAuth client for dynamic client registration (RFC7591)
+ * OAuth 2.0 Client Metadata (Dynamic Client Registration)
+ * @see https://datatracker.ietf.org/doc/html/rfc7591#section-2
+ * @see https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.1
  */
 export interface OAuthClient {
+  /** REQUIRED - OAuth 2.0 client identifier string */
   client_id: string;
+  /** OPTIONAL - OAuth 2.0 client secret string (confidential clients) */
   client_secret?: string;
+  /** OPTIONAL - Human-readable name of the client */
   client_name?: string;
+  /** REQUIRED - Array of redirect URIs for use in redirect-based flows */
   redirect_uris: string[];
+  /** OPTIONAL - Array of OAuth 2.0 grant types (e.g., "authorization_code", "refresh_token") */
   grant_types?: string[];
+  /** OPTIONAL - Array of response types (e.g., "code", "token") */
   response_types?: string[];
+  /** OPTIONAL - Authentication method for the token endpoint (e.g., "client_secret_basic", "none") */
   token_endpoint_auth_method?: string;
+  /** OPTIONAL - Space-separated list of scope values */
   scope?: string;
+  /** OPTIONAL - Time at which the client identifier was issued (Unix timestamp) */
   client_id_issued_at?: number;
+  /** OPTIONAL - Time at which the client secret expires (Unix timestamp, 0 = never) */
   client_secret_expires_at?: number;
 }