Add Cloudflare OAuth proxy integration for self-hosted Hindsight (#922)
Adds an OAuth 2.1 proxy Worker that connects cloud MCP clients (claude.ai, Claude Code, Codex) to a self-hosted Hindsight instance via Cloudflare Workers and Tunnel. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
404sand808s
GitHub
parent
3fc87e767c
commit
aad07a141b
5 changed files with 382 additions and 0 deletions
3
hindsight-integrations/cloudflare-oauth-proxy/.gitignore
vendored
Normal file
3
hindsight-integrations/cloudflare-oauth-proxy/.gitignore
vendored
Normal file
|
|
@ -0,0 +1,3 @@
|
||||||
|
node_modules/
|
||||||
|
dist/
|
||||||
|
.wrangler/
|
||||||
94
hindsight-integrations/cloudflare-oauth-proxy/README.md
Normal file
94
hindsight-integrations/cloudflare-oauth-proxy/README.md
Normal file
|
|
@ -0,0 +1,94 @@
|
||||||
|
# Cloudflare OAuth Proxy for Self-Hosted Hindsight
|
||||||
|
|
||||||
|
An [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) proxy that connects cloud-based MCP clients (such as [claude.ai](https://claude.ai), [Claude Code](../claude-code/), and [Codex](../codex/)) to a self-hosted [Hindsight](https://vectorize.io/hindsight) instance. Built on [Cloudflare Workers](https://developers.cloudflare.com/workers/) using the [`@cloudflare/workers-oauth-provider`](https://github.com/cloudflare/workers-oauth-provider) library.
|
||||||
|
|
||||||
|
## Why
|
||||||
|
|
||||||
|
Cloud-based MCP clients require an OAuth 2.1 flow to connect to remote MCP servers. Self-hosted Hindsight instances typically sit behind a private network or Cloudflare Tunnel, and don't natively expose an OAuth endpoint. This Worker bridges that gap: it handles the OAuth dance on a public domain, authenticates the user with a simple password gate, and proxies authenticated MCP traffic to your Hindsight origin through a Cloudflare Tunnel.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
Cloud MCP Client (claude.ai, Claude Code, Codex)
|
||||||
|
|
|
||||||
|
| HTTPS + OAuth 2.1
|
||||||
|
v
|
||||||
|
Cloudflare Worker (this proxy)
|
||||||
|
- OAuth 2.1 authorization server
|
||||||
|
- Dynamic client registration (RFC 7591)
|
||||||
|
- PKCE (S256 only)
|
||||||
|
- CORS restricted to allowlisted origins
|
||||||
|
|
|
||||||
|
| HTTPS + Cloudflare Tunnel
|
||||||
|
v
|
||||||
|
Self-hosted Hindsight (Docker)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- A [Cloudflare](https://www.cloudflare.com/) account with a domain
|
||||||
|
- A running self-hosted Hindsight instance (see [self-hosting quickstart](https://vectorize.io/hindsight/quickstart/self-hosting))
|
||||||
|
- A [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) exposing your Hindsight instance
|
||||||
|
- [Node.js](https://nodejs.org/) (v18+)
|
||||||
|
|
||||||
|
## Setup
|
||||||
|
|
||||||
|
### 1. Install dependencies
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd hindsight-integrations/cloudflare-oauth-proxy
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Configure `wrangler.toml`
|
||||||
|
|
||||||
|
Copy the included `wrangler.toml` and update the placeholder values:
|
||||||
|
|
||||||
|
- `HINDSIGHT_ORIGIN`: Your Cloudflare Tunnel origin URL (e.g., `https://hindsight-origin.yourdomain.com`)
|
||||||
|
- `kv_namespaces.id`: Create a KV namespace via `npx wrangler kv namespace create OAUTH_KV` and paste the returned ID
|
||||||
|
- `routes.pattern` / `routes.zone_name`: Your public-facing domain for the proxy
|
||||||
|
|
||||||
|
### 3. Set secrets
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx wrangler secret put SESSION_SECRET # Password for the login page
|
||||||
|
npx wrangler secret put PROXY_SECRET # X-Proxy-Secret header value (must match your origin WAF rule)
|
||||||
|
npx wrangler secret put HINDSIGHT_API_TOKEN # Bearer token for the Hindsight API
|
||||||
|
npx wrangler secret put ALLOWED_EMAIL # Your email (used as the OAuth user identity)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Deploy
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run deploy
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Secure your origin
|
||||||
|
|
||||||
|
Add a WAF rule on your Cloudflare Tunnel origin hostname to block requests that don't carry the correct `X-Proxy-Secret` header. This ensures only the Worker can reach your Hindsight instance.
|
||||||
|
|
||||||
|
## Connecting clients
|
||||||
|
|
||||||
|
Once deployed, add the Worker URL as a remote MCP server in your client:
|
||||||
|
|
||||||
|
- **claude.ai**: Settings > MCP Servers > Add > enter `https://hindsight.yourdomain.com/mcp`
|
||||||
|
- **Claude Code**: `claude mcp add hindsight-remote https://hindsight.yourdomain.com/mcp --transport http`
|
||||||
|
- **Codex**: Configure via the MCP settings with the same URL
|
||||||
|
|
||||||
|
On first connection, you'll be redirected to a login page. Enter the `SESSION_SECRET` password to authorize. This only needs to happen once per OAuth session.
|
||||||
|
|
||||||
|
## Secrets reference
|
||||||
|
|
||||||
|
| Secret | Purpose |
|
||||||
|
|--------|---------|
|
||||||
|
| `SESSION_SECRET` | Password shown on the login page to authorize a session |
|
||||||
|
| `PROXY_SECRET` | Value sent as `X-Proxy-Secret` header to the origin (for WAF validation) |
|
||||||
|
| `HINDSIGHT_API_TOKEN` | Bearer token for authenticating with the Hindsight API |
|
||||||
|
| `ALLOWED_EMAIL` | Your email address, used as the OAuth user identity |
|
||||||
|
|
||||||
|
## Security notes
|
||||||
|
|
||||||
|
- CORS is restricted to `claude.ai` origins by default. To support additional clients (e.g., ChatGPT), add their origins to the `ALLOWED_ORIGINS` set in `src/index.ts`.
|
||||||
|
- PKCE is enforced with S256 only (plain PKCE is not advertised).
|
||||||
|
- OAuth state is stored in Cloudflare KV with a 5-minute TTL.
|
||||||
|
- The proxy strips the client's `Authorization` header and replaces it with the configured `HINDSIGHT_API_TOKEN` before forwarding to the origin.
|
||||||
17
hindsight-integrations/cloudflare-oauth-proxy/package.json
Normal file
17
hindsight-integrations/cloudflare-oauth-proxy/package.json
Normal file
|
|
@ -0,0 +1,17 @@
|
||||||
|
{
|
||||||
|
"name": "hindsight-cloudflare-oauth-proxy",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"private": true,
|
||||||
|
"description": "OAuth 2.1 proxy for connecting cloud MCP clients to self-hosted Hindsight via Cloudflare Workers",
|
||||||
|
"scripts": {
|
||||||
|
"dev": "npx wrangler dev",
|
||||||
|
"deploy": "npx wrangler deploy"
|
||||||
|
},
|
||||||
|
"dependencies": {
|
||||||
|
"@cloudflare/workers-oauth-provider": "^0.0.4"
|
||||||
|
},
|
||||||
|
"devDependencies": {
|
||||||
|
"@cloudflare/workers-types": "^4.20250327.0",
|
||||||
|
"wrangler": "^4.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
247
hindsight-integrations/cloudflare-oauth-proxy/src/index.ts
Normal file
247
hindsight-integrations/cloudflare-oauth-proxy/src/index.ts
Normal file
|
|
@ -0,0 +1,247 @@
|
||||||
|
import { WorkerEntrypoint } from "cloudflare:workers";
|
||||||
|
import OAuthProvider from "@cloudflare/workers-oauth-provider";
|
||||||
|
|
||||||
|
interface Env {
|
||||||
|
OAUTH_KV: KVNamespace;
|
||||||
|
OAUTH_PROVIDER: any;
|
||||||
|
HINDSIGHT_ORIGIN: string;
|
||||||
|
ALLOWED_EMAIL: string;
|
||||||
|
SESSION_SECRET: string;
|
||||||
|
PROXY_SECRET: string; // add as Wrangler secret
|
||||||
|
HINDSIGHT_API_TOKEN: string; // add as Wrangler secret
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- HTML escaping ---
|
||||||
|
function escapeHtml(s: string): string {
|
||||||
|
return s
|
||||||
|
.replace(/&/g, "&")
|
||||||
|
.replace(/"/g, """)
|
||||||
|
.replace(/'/g, "'")
|
||||||
|
.replace(/</g, "<")
|
||||||
|
.replace(/>/g, ">");
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- CORS Allowlist ---
|
||||||
|
const ALLOWED_ORIGINS = new Set([
|
||||||
|
"https://claude.ai",
|
||||||
|
"https://www.claude.ai",
|
||||||
|
]);
|
||||||
|
|
||||||
|
function corsHeaders(origin: string): Record<string, string> {
|
||||||
|
return {
|
||||||
|
"Access-Control-Allow-Origin": origin,
|
||||||
|
"Access-Control-Allow-Methods": "*",
|
||||||
|
"Access-Control-Allow-Headers": "Authorization, Content-Type",
|
||||||
|
"Access-Control-Max-Age": "86400",
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function stripCorsHeaders(response: Response): Response {
|
||||||
|
const cleaned = new Response(response.body, response);
|
||||||
|
cleaned.headers.delete("Access-Control-Allow-Origin");
|
||||||
|
cleaned.headers.delete("Access-Control-Allow-Methods");
|
||||||
|
cleaned.headers.delete("Access-Control-Allow-Headers");
|
||||||
|
cleaned.headers.delete("Access-Control-Max-Age");
|
||||||
|
return cleaned;
|
||||||
|
}
|
||||||
|
|
||||||
|
function applyCors(response: Response, origin: string | null): Response {
|
||||||
|
if (!origin || !ALLOWED_ORIGINS.has(origin)) {
|
||||||
|
// Strip any CORS headers the library may have added
|
||||||
|
if (response.headers.has("Access-Control-Allow-Origin")) {
|
||||||
|
return stripCorsHeaders(response);
|
||||||
|
}
|
||||||
|
return response;
|
||||||
|
}
|
||||||
|
const patched = stripCorsHeaders(response);
|
||||||
|
for (const [k, v] of Object.entries(corsHeaders(origin))) {
|
||||||
|
patched.headers.set(k, v);
|
||||||
|
}
|
||||||
|
return patched;
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- MCP Proxy Handler ---
|
||||||
|
export class HindsightProxy extends WorkerEntrypoint<Env> {
|
||||||
|
async fetch(request: Request): Promise<Response> {
|
||||||
|
const props = (this.ctx as any).props || {};
|
||||||
|
console.log(`MCP request from ${props.email}: ${request.method} ${new URL(request.url).pathname}`);
|
||||||
|
|
||||||
|
const url = new URL(request.url);
|
||||||
|
const originUrl = new URL(this.env.HINDSIGHT_ORIGIN);
|
||||||
|
url.hostname = originUrl.hostname;
|
||||||
|
url.port = originUrl.port;
|
||||||
|
url.protocol = originUrl.protocol;
|
||||||
|
|
||||||
|
const headers = new Headers(request.headers);
|
||||||
|
headers.delete("Authorization");
|
||||||
|
headers.set("X-Proxy-Secret", this.env.PROXY_SECRET);
|
||||||
|
headers.set("Authorization", `Bearer ${this.env.HINDSIGHT_API_TOKEN}`);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const response = await fetch(url.toString(), {
|
||||||
|
method: request.method,
|
||||||
|
headers,
|
||||||
|
body: request.body ?? null,
|
||||||
|
});
|
||||||
|
return new Response(response.body, {
|
||||||
|
status: response.status,
|
||||||
|
statusText: response.statusText,
|
||||||
|
headers: response.headers,
|
||||||
|
});
|
||||||
|
} catch (err) {
|
||||||
|
console.error("Failed to proxy to Hindsight:", err);
|
||||||
|
return new Response(JSON.stringify({ error: "Backend unavailable" }), {
|
||||||
|
status: 502,
|
||||||
|
headers: { "Content-Type": "application/json" },
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function loginPage(stateKey: string, error?: string): string {
|
||||||
|
return '<!DOCTYPE html>' +
|
||||||
|
'<html><head><title>Hindsight MCP</title>' +
|
||||||
|
'<style>' +
|
||||||
|
'body{font-family:system-ui;background:#0a0a0a;color:#e0e0e0;display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0}' +
|
||||||
|
'.card{background:#1a1a1a;border:1px solid #333;border-radius:12px;padding:2rem;width:320px}' +
|
||||||
|
'h2{margin-top:0}' +
|
||||||
|
'input{width:100%;padding:10px;margin:8px 0;border:1px solid #444;border-radius:6px;background:#0a0a0a;color:#e0e0e0;box-sizing:border-box;font-size:16px}' +
|
||||||
|
'button{width:100%;padding:10px;margin-top:12px;border:none;border-radius:6px;background:#3b82f6;color:white;font-size:16px;cursor:pointer}' +
|
||||||
|
'button:hover{background:#2563eb}' +
|
||||||
|
'.error{color:#ef4444;font-size:14px}' +
|
||||||
|
'.info{color:#888;font-size:13px;margin-top:12px}' +
|
||||||
|
'</style></head><body>' +
|
||||||
|
'<div class="card">' +
|
||||||
|
'<h2>Hindsight MCP</h2>' +
|
||||||
|
'<p>Authorize Claude to access your memory.</p>' +
|
||||||
|
(error ? '<p class="error">' + escapeHtml(error) + '</p>' : '') +
|
||||||
|
'<form method="POST" action="/authorize">' +
|
||||||
|
'<input type="hidden" name="stateKey" value="' + escapeHtml(stateKey) + '" />' +
|
||||||
|
'<input type="password" name="password" placeholder="Password" autofocus required />' +
|
||||||
|
'<button type="submit">Authorize</button>' +
|
||||||
|
'</form>' +
|
||||||
|
'<p class="info">You only need to do this once per session.</p>' +
|
||||||
|
'</div></body></html>';
|
||||||
|
}
|
||||||
|
|
||||||
|
const defaultHandler = {
|
||||||
|
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
|
||||||
|
const url = new URL(request.url);
|
||||||
|
|
||||||
|
if (url.pathname === "/health") {
|
||||||
|
return new Response(JSON.stringify({ status: "ok" }), {
|
||||||
|
headers: { "Content-Type": "application/json" },
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
if (url.pathname === "/authorize" && request.method === "GET") {
|
||||||
|
const oauthReqInfo = await env.OAUTH_PROVIDER.parseAuthRequest(request);
|
||||||
|
console.log("GET /authorize - parsed oauthReqInfo, clientId:", oauthReqInfo.clientId);
|
||||||
|
|
||||||
|
const stateKey = crypto.randomUUID();
|
||||||
|
await env.OAUTH_KV.put("auth_state:" + stateKey, JSON.stringify(oauthReqInfo), { expirationTtl: 300 });
|
||||||
|
|
||||||
|
return new Response(loginPage(stateKey), {
|
||||||
|
headers: { "Content-Type": "text/html" },
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
if (url.pathname === "/authorize" && request.method === "POST") {
|
||||||
|
const formData = await request.formData();
|
||||||
|
const password = formData.get("password") as string;
|
||||||
|
const stateKey = formData.get("stateKey") as string;
|
||||||
|
|
||||||
|
if (!password || password !== env.SESSION_SECRET) {
|
||||||
|
return new Response(loginPage(stateKey || "", "Incorrect password."), {
|
||||||
|
status: 401,
|
||||||
|
headers: { "Content-Type": "text/html" },
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!stateKey) {
|
||||||
|
return new Response("Missing state. Please try connecting again from Claude.", { status: 400 });
|
||||||
|
}
|
||||||
|
|
||||||
|
const stored = await env.OAUTH_KV.get("auth_state:" + stateKey);
|
||||||
|
await env.OAUTH_KV.delete("auth_state:" + stateKey);
|
||||||
|
|
||||||
|
if (!stored) {
|
||||||
|
return new Response("Authorization expired. Please try connecting again from Claude.", { status: 400 });
|
||||||
|
}
|
||||||
|
|
||||||
|
const oauthReqInfo = JSON.parse(stored);
|
||||||
|
console.log("POST /authorize - completing authorization for client:", oauthReqInfo.clientId);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const { redirectTo } = await env.OAUTH_PROVIDER.completeAuthorization({
|
||||||
|
request: oauthReqInfo,
|
||||||
|
userId: env.ALLOWED_EMAIL,
|
||||||
|
metadata: { label: env.ALLOWED_EMAIL },
|
||||||
|
scope: oauthReqInfo.scope ? oauthReqInfo.scope : ["mcp:full"],
|
||||||
|
props: {
|
||||||
|
email: env.ALLOWED_EMAIL,
|
||||||
|
authenticatedAt: Date.now(),
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
console.log("Authorization complete, redirecting to Claude");
|
||||||
|
return Response.redirect(redirectTo, 302);
|
||||||
|
} catch (err) {
|
||||||
|
console.error("completeAuthorization error:", err);
|
||||||
|
return new Response("Authorization failed. Please try again.", { status: 500 });
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (url.pathname === "/") {
|
||||||
|
return new Response(JSON.stringify({ service: "Hindsight MCP OAuth Proxy" }), {
|
||||||
|
headers: { "Content-Type": "application/json" },
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
return new Response("Not Found", { status: 404 });
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
// --- Inner provider (not exported directly) ---
|
||||||
|
const provider = new OAuthProvider({
|
||||||
|
apiRoute: "/mcp",
|
||||||
|
apiHandler: HindsightProxy,
|
||||||
|
defaultHandler: defaultHandler,
|
||||||
|
authorizeEndpoint: "/authorize",
|
||||||
|
tokenEndpoint: "/token",
|
||||||
|
clientRegistrationEndpoint: "/register",
|
||||||
|
});
|
||||||
|
|
||||||
|
// --- Wrapped export: restricts CORS + hardens metadata ---
|
||||||
|
export default {
|
||||||
|
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
|
||||||
|
const origin = request.headers.get("Origin");
|
||||||
|
const url = new URL(request.url);
|
||||||
|
|
||||||
|
// Intercept OPTIONS: only allow preflight for allowlisted origins
|
||||||
|
if (request.method === "OPTIONS") {
|
||||||
|
if (origin && ALLOWED_ORIGINS.has(origin)) {
|
||||||
|
return new Response(null, {
|
||||||
|
status: 204,
|
||||||
|
headers: { "Content-Length": "0", ...corsHeaders(origin) },
|
||||||
|
});
|
||||||
|
}
|
||||||
|
return new Response(null, { status: 403 });
|
||||||
|
}
|
||||||
|
|
||||||
|
// Override metadata to advertise S256-only PKCE
|
||||||
|
if (url.pathname === "/.well-known/oauth-authorization-server") {
|
||||||
|
const response = await provider.fetch(request, env, ctx);
|
||||||
|
const metadata = await response.json() as Record<string, unknown>;
|
||||||
|
metadata.code_challenge_methods_supported = ["S256"];
|
||||||
|
const newResponse = new Response(JSON.stringify(metadata), {
|
||||||
|
headers: { "Content-Type": "application/json" },
|
||||||
|
});
|
||||||
|
return applyCors(newResponse, origin);
|
||||||
|
}
|
||||||
|
|
||||||
|
// All other requests: pass to provider, then fix CORS
|
||||||
|
const response = await provider.fetch(request, env, ctx);
|
||||||
|
return applyCors(response, origin);
|
||||||
|
},
|
||||||
|
};
|
||||||
21
hindsight-integrations/cloudflare-oauth-proxy/wrangler.toml
Normal file
21
hindsight-integrations/cloudflare-oauth-proxy/wrangler.toml
Normal file
|
|
@ -0,0 +1,21 @@
|
||||||
|
name = "hindsight-oauth-proxy"
|
||||||
|
main = "src/index.ts"
|
||||||
|
compatibility_date = "2025-03-01"
|
||||||
|
workers_dev = true
|
||||||
|
|
||||||
|
[[kv_namespaces]]
|
||||||
|
binding = "OAUTH_KV"
|
||||||
|
id = "your-kv-namespace-id"
|
||||||
|
|
||||||
|
[vars]
|
||||||
|
HINDSIGHT_ORIGIN = "https://your-hindsight-origin.example.com"
|
||||||
|
|
||||||
|
[[routes]]
|
||||||
|
pattern = "hindsight.yourdomain.com/*"
|
||||||
|
zone_name = "yourdomain.com"
|
||||||
|
|
||||||
|
# Secrets (set via `npx wrangler secret put`):
|
||||||
|
# - SESSION_SECRET (password for the login page)
|
||||||
|
# - PROXY_SECRET (header value for WAF rule on origin)
|
||||||
|
# - HINDSIGHT_API_TOKEN (Bearer token for Hindsight API)
|
||||||
|
# - ALLOWED_EMAIL (your email, used as the OAuth user ID)
|
||||||
Loading…
Reference in a new issue