@cubis/foundry 0.3.33 → 0.3.35

package/mcp/powers/building-mcp-server-on-cloudflare/steering/oauth-setup.md

@@ -1,338 +0,0 @@
-# Securing MCP Servers
-
-MCP servers require authentication to ensure only trusted users can access them. The MCP specification uses OAuth 2.1 for authentication between clients and servers.
-
-Cloudflare's `workers-oauth-provider` handles token management, client registration, and access token validation automatically.
-
-## Basic Setup
-
-```typescript
-import { OAuthProvider } from "@cloudflare/workers-oauth-provider";
-import { createMcpHandler } from "agents/mcp";
-
-const apiHandler = {
-  async fetch(request: Request, env: unknown, ctx: ExecutionContext) {
-    return createMcpHandler(server)(request, env, ctx);
-  }
-};
-
-export default new OAuthProvider({
-  authorizeEndpoint: "/authorize",
-  tokenEndpoint: "/oauth/token",
-  clientRegistrationEndpoint: "/oauth/register",
-  apiRoute: "/mcp",
-  apiHandler: apiHandler,
-  defaultHandler: AuthHandler
-});
-```
-
-## Proxy Server Pattern
-
-MCP servers often act as OAuth clients too. Your server sits between Claude Desktop and a third-party API like GitHub. To Claude, you're a server. To GitHub, you're a client. This lets users authenticate with their GitHub credentials.
-
-Building a secure proxy server requires careful attention to several security concerns.
-
----
-
-## Security Requirements
-
-### Redirect URI Validation
-
-The `workers-oauth-provider` validates that `redirect_uri` in authorization requests matches registered URIs. This prevents attackers from redirecting authorization codes to malicious endpoints.
-
-### Consent Dialog
-
-When proxying to third-party providers, implement your own consent dialog before forwarding users upstream. This prevents the "confused deputy" problem where attackers exploit cached consent.
-
-Your consent dialog should:
-- Identify the requesting MCP client by name
-- Display the specific scopes being requested
-
----
-
-## CSRF Protection
-
-Prevent attackers from tricking users into approving malicious OAuth clients. Use a random token stored in a secure cookie.
-
-```typescript
-// Generate token when showing consent form
-function generateCSRFProtection(): { token: string; setCookie: string } {
-  const token = crypto.randomUUID();
-  const setCookie = `__Host-CSRF_TOKEN=${token}; HttpOnly; Secure; Path=/; SameSite=Lax; Max-Age=600`;
-  return { token, setCookie };
-}
-
-// Validate token when user approves
-function validateCSRFToken(formData: FormData, request: Request): { clearCookie: string } {
-  const tokenFromForm = formData.get("csrf_token");
-  const cookieHeader = request.headers.get("Cookie") || "";
-  const tokenFromCookie = cookieHeader
-    .split(";")
-    .find((c) => c.trim().startsWith("__Host-CSRF_TOKEN="))
-    ?.split("=")[1];
-
-  if (!tokenFromForm || !tokenFromCookie || tokenFromForm !== tokenFromCookie) {
-    throw new Error("CSRF token mismatch");
-  }
-
-  return {
-    clearCookie: `__Host-CSRF_TOKEN=; HttpOnly; Secure; Path=/; SameSite=Lax; Max-Age=0`
-  };
-}
-```
-
-Include the token as a hidden form field:
-
-```html
-<input type="hidden" name="csrf_token" value="${csrfToken}" />
-```
-
----
-
-## Input Sanitization
-
-Client-controlled content (names, logos, URIs) can execute malicious scripts if not sanitized. Treat all client metadata as untrusted.
-
-```typescript
-function sanitizeText(text: string): string {
-  return text
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&#039;");
-}
-
-function sanitizeUrl(url: string): string {
-  if (!url) return "";
-  try {
-    const parsed = new URL(url);
-    if (!["http:", "https:"].includes(parsed.protocol)) {
-      return "";
-    }
-    return url;
-  } catch {
-    return "";
-  }
-}
-```
-
-**Required protections:**
-- Client names/descriptions: HTML-escape before rendering
-- Logo URLs: Allow only `http:` and `https:` schemes
-- Client URIs: Same as logo URLs
-- Scopes: Treat as text, HTML-escape
-
----
-
-## Content Security Policy
-
-CSP headers block dangerous content and provide defense in depth.
-
-```typescript
-function buildSecurityHeaders(setCookie: string, nonce?: string): HeadersInit {
-  const cspDirectives = [
-    "default-src 'none'",
-    "script-src 'self'" + (nonce ? ` 'nonce-${nonce}'` : ""),
-    "style-src 'self' 'unsafe-inline'",
-    "img-src 'self' https:",
-    "font-src 'self'",
-    "form-action 'self'",
-    "frame-ancestors 'none'",
-    "base-uri 'self'",
-    "connect-src 'self'"
-  ].join("; ");
-
-  return {
-    "Content-Security-Policy": cspDirectives,
-    "X-Frame-Options": "DENY",
-    "X-Content-Type-Options": "nosniff",
-    "Content-Type": "text/html; charset=utf-8",
-    "Set-Cookie": setCookie
-  };
-}
-```
-
----
-
-## State Management
-
-Ensure the same user that hits authorize reaches the callback. Use a random state token stored in KV with short expiration.
-
-```typescript
-// Create state before redirecting to upstream provider
-async function createOAuthState(
-  oauthReqInfo: AuthRequest,
-  kv: KVNamespace
-): Promise<{ stateToken: string }> {
-  const stateToken = crypto.randomUUID();
-  await kv.put(`oauth:state:${stateToken}`, JSON.stringify(oauthReqInfo), {
-    expirationTtl: 600
-  });
-  return { stateToken };
-}
-
-// Bind state to browser session via hashed cookie
-async function bindStateToSession(stateToken: string): Promise<{ setCookie: string }> {
-  const encoder = new TextEncoder();
-  const data = encoder.encode(stateToken);
-  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
-  const hashArray = Array.from(new Uint8Array(hashBuffer));
-  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
-
-  return {
-    setCookie: `__Host-CONSENTED_STATE=${hashHex}; HttpOnly; Secure; Path=/; SameSite=Lax; Max-Age=600`
-  };
-}
-
-// Validate in callback - check both KV and session cookie
-async function validateOAuthState(
-  request: Request,
-  kv: KVNamespace
-): Promise<{ oauthReqInfo: AuthRequest; clearCookie: string }> {
-  const url = new URL(request.url);
-  const stateFromQuery = url.searchParams.get("state");
-
-  if (!stateFromQuery) {
-    throw new Error("Missing state parameter");
-  }
-
-  // Check KV
-  const storedDataJson = await kv.get(`oauth:state:${stateFromQuery}`);
-  if (!storedDataJson) {
-    throw new Error("Invalid or expired state");
-  }
-
-  // Check session cookie matches
-  const cookieHeader = request.headers.get("Cookie") || "";
-  const consentedStateHash = cookieHeader
-    .split(";")
-    .find((c) => c.trim().startsWith("__Host-CONSENTED_STATE="))
-    ?.split("=")[1];
-
-  if (!consentedStateHash) {
-    throw new Error("Missing session binding cookie");
-  }
-
-  // Hash state and compare
-  const encoder = new TextEncoder();
-  const hashBuffer = await crypto.subtle.digest("SHA-256", encoder.encode(stateFromQuery));
-  const stateHash = Array.from(new Uint8Array(hashBuffer))
-    .map((b) => b.toString(16).padStart(2, "0"))
-    .join("");
-
-  if (stateHash !== consentedStateHash) {
-    throw new Error("State token does not match session");
-  }
-
-  await kv.delete(`oauth:state:${stateFromQuery}`);
-
-  return {
-    oauthReqInfo: JSON.parse(storedDataJson),
-    clearCookie: `__Host-CONSENTED_STATE=; HttpOnly; Secure; Path=/; SameSite=Lax; Max-Age=0`
-  };
-}
-```
-
----
-
-## Approved Clients Registry
-
-Maintain a registry of approved client IDs per user. Store in a cryptographically signed cookie with HMAC-SHA256.
-
-```typescript
-export async function addApprovedClient(
-  request: Request,
-  clientId: string,
-  cookieSecret: string
-): Promise<string> {
-  const existingClients = await getApprovedClientsFromCookie(request, cookieSecret) || [];
-  const updatedClients = Array.from(new Set([...existingClients, clientId]));
-
-  const payload = JSON.stringify(updatedClients);
-  const signature = await signData(payload, cookieSecret);
-  const cookieValue = `${signature}.${btoa(payload)}`;
-
-  return `__Host-APPROVED_CLIENTS=${cookieValue}; HttpOnly; Secure; Path=/; SameSite=Lax; Max-Age=2592000`;
-}
-```
-
-When reading the cookie, verify the signature before trusting data. If client isn't approved, show consent dialog.
-
----
-
-## Cookie Security
-
-### Why `__Host-` prefix?
-
-The `__Host-` prefix prevents subdomain attacks on `*.workers.dev` domains. Requirements:
-- Must have `Secure` flag (HTTPS only)
-- Must have `Path=/`
-- Must not have `Domain` attribute
-
-Without this prefix, an attacker on `evil.workers.dev` could set cookies for your `mcp-server.workers.dev` domain.
-
-### Multiple OAuth Providers
-
-If running multiple OAuth flows on the same domain, namespace your cookies:
-- `__Host-CSRF_TOKEN_GITHUB` vs `__Host-CSRF_TOKEN_GOOGLE`
-- `__Host-APPROVED_CLIENTS_GITHUB` vs `__Host-APPROVED_CLIENTS_GOOGLE`
-
----
-
-## Inline JavaScript
-
-If your consent dialog needs inline JavaScript, use data attributes and nonces:
-
-```typescript
-const nonce = crypto.randomUUID();
-
-const html = `
-  <script nonce="${nonce}" data-redirect-url="${sanitizeUrl(redirectUrl)}">
-    setTimeout(() => {
-      const script = document.querySelector('script[data-redirect-url]');
-      window.location.href = script.dataset.redirectUrl;
-    }, 2000);
-  </script>
-`;
-
-return new Response(html, {
-  headers: buildSecurityHeaders(setCookie, nonce)
-});
-```
-
-Data attributes store user-controlled data separately from executable code. Nonces with CSP allow your specific script while blocking injected scripts.
-
----
-
-## Provider-Specific Setup
-
-### GitHub
-
-1. Create OAuth App at github.com/settings/developers
-2. Set callback URL: `https://[worker].workers.dev/callback`
-3. Store secrets:
-   ```bash
-   wrangler secret put GITHUB_CLIENT_ID
-   wrangler secret put GITHUB_CLIENT_SECRET
-   ```
-
-### Google
-
-1. Create OAuth Client at console.cloud.google.com/apis/credentials
-2. Set authorized redirect URI
-3. Scopes: `openid email profile`
-
-### Auth0
-
-1. Create Regular Web Application in Auth0 Dashboard
-2. Set allowed callback URLs
-3. Endpoints: `https://${AUTH0_DOMAIN}/authorize`, `/oauth/token`, `/userinfo`
-
----
-
-## References
-
-- [MCP Authorization Spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
-- [MCP Security Best Practices](https://modelcontextprotocol.io/specification/draft/basic/security_best_practices)
-- [RFC 9700 - OAuth Security](https://www.rfc-editor.org/rfc/rfc9700)

package/mcp/powers/building-mcp-server-on-cloudflare/steering/troubleshooting.md

@@ -1,317 +0,0 @@
-# MCP Server Troubleshooting
-
-Common errors and solutions for MCP servers on Cloudflare.
-
-## Connection Issues
-
-### "Failed to connect to MCP server"
-
-**Symptoms:** Client cannot establish connection to deployed server.
-
-**Causes & Solutions:**
-
-1. **Wrong URL path**
-   ```
-   # Wrong
-   https://my-server.workers.dev/
-
-   # Correct
-   https://my-server.workers.dev/mcp
-   ```
-
-2. **Worker not deployed**
-   ```bash
-   wrangler deployments list
-   # If empty, deploy first:
-   wrangler deploy
-   ```
-
-3. **Worker crashed on startup**
-   ```bash
-   wrangler tail
-   # Check for initialization errors
-   ```
-
-### "WebSocket connection failed"
-
-MCP uses SSE (Server-Sent Events), not WebSockets. Ensure your client is configured for SSE transport:
-
-```json
-{
-  "mcpServers": {
-    "my-server": {
-      "command": "npx",
-      "args": ["mcp-remote", "https://my-server.workers.dev/mcp"]
-    }
-  }
-}
-```
-
-### CORS Errors in Browser
-
-If calling from browser-based client:
-
-```typescript
-// Add CORS headers to your worker
-export default {
-  async fetch(request: Request, env: Env) {
-    // Handle preflight
-    if (request.method === "OPTIONS") {
-      return new Response(null, {
-        headers: {
-          "Access-Control-Allow-Origin": "*",
-          "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-          "Access-Control-Allow-Headers": "Content-Type",
-        },
-      });
-    }
-
-    const response = await handleRequest(request, env);
-
-    // Add CORS headers to response
-    const headers = new Headers(response.headers);
-    headers.set("Access-Control-Allow-Origin", "*");
-
-    return new Response(response.body, {
-      status: response.status,
-      headers,
-    });
-  },
-};
-```
-
-## Tool Errors
-
-### "Tool not found: [tool_name]"
-
-**Causes:**
-
-1. Tool not registered in `init()`
-2. Tool name mismatch (case-sensitive)
-3. `init()` threw an error before registering tool
-
-**Debug:**
-
-```typescript
-async init() {
-  console.log("Registering tools...");
-
-  this.server.tool("my_tool", { ... }, async () => { ... });
-
-  console.log("Tools registered:", this.server.listTools());
-}
-```
-
-Check logs: `wrangler tail`
-
-### "Invalid parameters for tool"
-
-Zod validation failed. Check parameter schema:
-
-```typescript
-// Schema expects number, client sent string
-this.server.tool(
-  "calculate",
-  { value: z.number() },  // Client must send number, not "123"
-  async ({ value }) => { ... }
-);
-
-// Fix: Coerce string to number
-this.server.tool(
-  "calculate",
-  { value: z.coerce.number() },  // "123" → 123
-  async ({ value }) => { ... }
-);
-```
-
-### Tool Timeout
-
-Workers have CPU time limits (10-30ms for free, longer for paid). For long operations:
-
-```typescript
-this.server.tool(
-  "long_operation",
-  { ... },
-  async (params) => {
-    // Break into smaller chunks
-    // Or use Queues/Durable Objects for background work
-
-    // Don't do this:
-    // await sleep(5000);  // Will timeout
-
-    return { content: [{ type: "text", text: "Queued for processing" }] };
-  }
-);
-```
-
-## Authentication Errors
-
-### "401 Unauthorized"
-
-OAuth token missing or expired.
-
-1. **Check client is handling OAuth flow**
-2. **Verify secrets are set:**
-   ```bash
-   wrangler secret list
-   # Should show GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
-   ```
-
-3. **Check KV namespace exists:**
-   ```bash
-   wrangler kv namespace list
-   # Should show OAUTH_KV
-   ```
-
-### "Invalid redirect_uri"
-
-OAuth callback URL doesn't match app configuration.
-
-**Local development:**
-- OAuth app callback: `http://localhost:8788/callback`
-
-**Production:**
-- OAuth app callback: `https://[worker-name].[account].workers.dev/callback`
-
-Must match EXACTLY (including trailing slash or lack thereof).
-
-### "State mismatch" / CSRF Error
-
-State parameter validation failed.
-
-1. **Clear browser cookies and retry**
-2. **Check KV is storing state:**
-   ```typescript
-   // In your auth handler
-   console.log("Storing state:", state);
-   await env.OAUTH_KV.put(`state:${state}`, "1", { expirationTtl: 600 });
-   ```
-
-3. **Verify same domain for all requests**
-
-## Binding Errors
-
-### "Binding not found: [BINDING_NAME]"
-
-Binding not in `wrangler.toml` or not deployed.
-
-```toml
-# wrangler.toml
-[[d1_databases]]
-binding = "DB"           # Must match env.DB in code
-database_name = "mydb"
-database_id = "xxx-xxx"
-```
-
-After adding bindings: `wrangler deploy`
-
-### "D1_ERROR: no such table"
-
-Migrations not applied.
-
-```bash
-# Local
-wrangler d1 migrations apply DB_NAME --local
-
-# Production
-wrangler d1 migrations apply DB_NAME
-```
-
-### Durable Object Not Found
-
-```toml
-# wrangler.toml must have:
-[durable_objects]
-bindings = [{ name = "MCP", class_name = "MyMCP" }]
-
-[[migrations]]
-tag = "v1"
-new_classes = ["MyMCP"]
-```
-
-And class must be exported:
-
-```typescript
-export { MyMCP };  // Don't forget this!
-```
-
-## Deployment Errors
-
-### "Class MyMCP is not exported"
-
-```typescript
-// src/index.ts - Must export the class
-export { MyMCP } from "./mcp";
-
-// OR in same file
-export class MyMCP extends McpAgent { ... }
-```
-
-### "Migration required"
-
-New Durable Object class needs migration:
-
-```toml
-# Add to wrangler.toml
-[[migrations]]
-tag = "v2"  # Increment version
-new_classes = ["NewClassName"]
-# Or for renames:
-# renamed_classes = [{ from = "OldName", to = "NewName" }]
-```
-
-### Build Errors
-
-```bash
-# Clear cache and rebuild
-rm -rf node_modules .wrangler
-npm install
-wrangler deploy
-```
-
-## Debugging Tips
-
-### Enable Verbose Logging
-
-```typescript
-export class MyMCP extends McpAgent {
-  async init() {
-    console.log("MCP Server initializing...");
-    console.log("Environment:", Object.keys(this.env));
-
-    this.server.tool("test", {}, async () => {
-      console.log("Test tool called");
-      return { content: [{ type: "text", text: "OK" }] };
-    });
-
-    console.log("Tools registered");
-  }
-}
-```
-
-View logs:
-```bash
-wrangler tail --format pretty
-```
-
-### Test Locally First
-
-```bash
-npm start
-npx @modelcontextprotocol/inspector@latest
-```
-
-Always verify tools work locally before deploying.
-
-### Check Worker Health
-
-```bash
-# List deployments
-wrangler deployments list
-
-# View recent logs
-wrangler tail
-
-# Check worker status
-curl -I https://your-worker.workers.dev/mcp
-```