@openephemeris/mcp-server 3.13.9 → 3.14.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.14.0] — 2026-05-24
+
+### Added
+- **Fullscreen bottom-bar layout** for bodygraph, bi-wheel, and chart-wheel iframes — chart fills the viewport, controls dock to the bottom for a cleaner read on small windows.
+- **Debug highlight click handler** in the bodygraph (`?debugHighlight`) — click any gate to surface its center/channel data via iframe postMessage.
+- **Highlight visualization** — highlighted gates render with CSS glow while non-highlighted gates dim, making activation patterns visually obvious.
+- **Click payload metadata** — bodygraph gate groups now emit `data-center` for richer iframe click events.
+- **OAuth refresh-token persistence** to Supabase, with in-memory expiry enforcement and a 90-day TTL (up from 30 days).
+- **OAuth discovery test suite** with 401-compliance coverage.
+
+### Fixed
+- Auth check now runs before `isInitializeRequest` — resolves the Claude Web `ofid_` initialization error.
+- Light-mode ring tokens wired correctly in bi-wheel (were missing token references).
+- Fullscreen bottom-bar layout polish — edge cases and styling fixes after initial rollout.
+
+### Changed
+- **Server-side SVG is now the only bodygraph render path** — the legacy client-side renderer has been retired. Reduces bundle size and removes a source of cross-environment rendering drift.
+- Claude Web connector docs updated to reflect OAuth (not API key) as the connection method.
+
+### Underlying API improvements (delivered transparently)
+- **LLM-format projection now covers all 7 benchmarked endpoints** (was 4): `/ephemeris/natal-chart`, `/comparative/synastry`, `/comparative/natal-transits`, `/human-design/chart`, `/vedic/chart`, `/chinese/bazi`, `/acg/hits`. Weighted average reduction: 61% (GPT-4o), 60% (Claude). Range: 13%–98% per endpoint.
+- `/acg/hits` newly supports `format=llm` — proximity hits as compact rows. Other `/acg/*` endpoints continue to return precision GeoJSON for map rendering.
+
+---
+
+## [3.13.11] — 2026-05-15
+
+### Added
+- **Bi-Wheel UI Parity** — Unified the Bi-Wheel and Natal Chart Wheel architectures with matching feature sets.
+- **Tally & Dignity Panels** — Integrated element/modality tallies and planetary dignity badges into the Bi-Wheel UI.
+- **House System Controls** — Added dynamic house system selection to the Bi-Wheel aspect panel, triggering live recalculations.
+- **Enhanced Rendering** — Exported dignity/tally logic from core renderer for consistent client-side UI generation.
+
+### Fixed
+- Widened `BiWheelMode` type definitions to prevent TypeScript compilation errors during mode-specific panel rendering.
+- Standardized CSS design tokens and layout containers between natal and comparative chart wheels.
+
+---
+
 ## [3.10.4] — 2026-04-24
 
 ### Changed

package/README.md

@@ -183,7 +183,7 @@ Cursor deeplink payload:
 
 The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable HTTP support (MCP 2025-11-25 spec). Remote-only clients can connect directly — no bridge/proxy required:
 
-- **Claude Web**: Add `https://mcp.openephemeris.com/mcp` as a remote MCP server with `X-API-Key: your-key` header
+- **Claude Web**: Add `https://mcp.openephemeris.com/mcp` as a custom connector URL — leave OAuth Client ID and Secret **blank**. The server uses OAuth 2.1 + PKCE (Dynamic Client Registration), so Claude handles authentication via a browser popup automatically.
 - **Via Smithery**: Use the [Smithery listing](https://smithery.ai/servers/open-ephemeris/openephemeris) for managed connections with any client
 - **Legacy SSE**: `https://mcp.openephemeris.com/sse` remains available for SSE-only clients
 
@@ -355,8 +355,8 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 
 - Allowlisted operations: **28**
 - Methods: `GET=4`, `POST=24`, `PUT=0`, `PATCH=0`, `DELETE=0`
-- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **72**
-- Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bi_wheel`, `explore_human_design`, `explore_natal_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `timezone_resolve`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **79**
+- Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bazi_annual_pillar`, `bazi_chart`, `bazi_compatibility`, `bazi_element_balance`, `bazi_luck_pillars`, `bazi_ten_gods`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bi_wheel`, `explore_human_design`, `explore_moon_phase`, `explore_natal_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `timezone_resolve`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
 - Generic tools: 
 
 ### Allowlist Families

package/config/dev-allowlist.json

@@ -128,8 +128,8 @@
       "path": "/visualization/chart-wheel"
     }
   ],
-  "last_generated_at": "2026-04-25T17:47:00.681Z",
-  "openapi_sha256": "9b2a79811fef658557233fc649b598178488985708b3ad10f252be598567080a",
+  "last_generated_at": "2026-05-14T01:35:40.409Z",
+  "openapi_sha256": "50112cd7017466815265d92e7d73cbc29be6bdc729a87db50989f189d562d201",
   "candidates_get": [
     {
       "method": "GET",
@@ -469,6 +469,14 @@
       ],
       "operationId": "aspects_acg_aspects_post"
     },
+    {
+      "method": "POST",
+      "path": "/acg/ccg/parans",
+      "tags": [
+        "ACG"
+      ],
+      "operationId": "acg_ccg_parans_post"
+    },
     {
       "method": "POST",
       "path": "/acg/ccg",
@@ -541,6 +549,14 @@
       ],
       "operationId": "midpoints_acg_midpoints_post"
     },
+    {
+      "method": "POST",
+      "path": "/acg/parans",
+      "tags": [
+        "ACG"
+      ],
+      "operationId": "acg_parans_post"
+    },
     {
       "method": "POST",
       "path": "/acg/power-lines",
@@ -549,6 +565,14 @@
       ],
       "operationId": "power_lines_acg_power_lines_post"
     },
+    {
+      "method": "POST",
+      "path": "/acg/relational-parans",
+      "tags": [
+        "ACG"
+      ],
+      "operationId": "acg_relational_parans_post"
+    },
     {
       "method": "POST",
       "path": "/chinese/bazi/annual-pillar",
@@ -699,7 +723,7 @@
       "tags": [
         "ephemeris"
       ],
-      "operationId": "calculate_draconic_chart_ephemeris_draconic_post"
+      "operationId": "CalculateDraconicChart"
     },
     {
       "method": "POST",
@@ -779,7 +803,7 @@
       "tags": [
         "ephemeris"
       ],
-      "operationId": "calculate_prenatal_lunation_ephemeris_prenatal_lunation_post"
+      "operationId": "CalculatePrenatalLunation"
     },
     {
       "method": "POST",

package/dist/index.js

@@ -7,9 +7,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry, formatToolResponse, modelVisibleTools } from "./tools/index.js";
 import { listPrompts, getPromptContent } from "./prompts.js";
+// ── MCP App resource imports ────────────────────────────────────────────────
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
 import { BODYGRAPH_RESOURCE_URI, BODYGRAPH_MIME_TYPE, getBodygraphBundle, } from "./tools/apps/bodygraph-app.js";
 import { BI_WHEEL_RESOURCE_URI, BI_WHEEL_MIME_TYPE, getBiWheelBundle, } from "./tools/apps/bi-wheel-app.js";
+import { MOON_PHASE_RESOURCE_URI, MOON_PHASE_MIME_TYPE, getMoonPhaseBundle, } from "./tools/apps/moon-phase-app.js";
+// ─────────────────────────────────────────────────────────────────────────────
 function resolveServerVersion() {
     try {
         const here = path.dirname(fileURLToPath(import.meta.url));
@@ -39,9 +42,6 @@ const server = new Server({
         tools: {},
         prompts: {},
         resources: {},
-        experimental: {
-            "io.modelcontextprotocol/ui": {},
-        },
     },
 });
 // List available tools
@@ -59,10 +59,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 openWorldHint: tool.annotations?.openWorldHint ?? false,
             },
             // Expose MCP Apps UI linkage so Claude Desktop can prefetch the resource
-            // and render the iframe when a tool result arrives.
-            // Include BOTH the modern nested key (_meta.ui.resourceUri) and the
-            // legacy flat key (_meta["ui/resourceUri"]) — the official ext-apps SDK
-            // normalizes both via registerAppTool() for host compatibility.
             ...(tool._meta?.ui?.resourceUri
                 ? {
                     _meta: {
@@ -124,6 +120,14 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
             mimeType: BI_WHEEL_MIME_TYPE,
         });
     }
+    if (getMoonPhaseBundle()) {
+        resources.push({
+            uri: MOON_PHASE_RESOURCE_URI,
+            name: "Moon Phase Explorer",
+            description: "Interactive lunar phase dial showing illumination, sign, and void-of-course status.",
+            mimeType: MOON_PHASE_MIME_TYPE,
+        });
+    }
     return { resources };
 });
 // Read resource
@@ -147,6 +151,12 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             throw new Error("Bi-Wheel UI bundle not found. Run `npm run build:ui` to build it.");
         return { contents: [{ uri: BI_WHEEL_RESOURCE_URI, mimeType: BI_WHEEL_MIME_TYPE, text: bundle }] };
     }
+    if (uri === MOON_PHASE_RESOURCE_URI) {
+        const bundle = getMoonPhaseBundle();
+        if (!bundle)
+            throw new Error("Moon Phase UI bundle not found. Run `npm run build:ui` to build it.");
+        return { contents: [{ uri: MOON_PHASE_RESOURCE_URI, mimeType: MOON_PHASE_MIME_TYPE, text: bundle }] };
+    }
     throw new Error(`Unknown resource: ${uri}`);
 });
 // Handle tool calls
@@ -166,19 +176,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     catch (error) {
         const durationMs = Date.now() - startTime;
         const errorMessage = error instanceof Error ? error.message : String(error);
+        const isRetryable = error.retryable === true || error.status === 401 || error.code === "auth_required";
         console.error(`[MCP] ❌ Failed: ${toolName} (${durationMs}ms) - ${errorMessage}`);
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({
-                        success: false,
-                        error: "TOOL_EXECUTION_ERROR",
-                        message: errorMessage,
-                    }, null, 2),
+                    text: `Tool execution failed:\n\n${errorMessage}\n\nPlease read the error above carefully and assist the user (e.g. by providing them the auth link or explaining the issue).`,
                 },
             ],
-            isError: true,
+            isError: !isRetryable,
         };
     }
 });

package/dist/oauth/dcr.d.ts

@@ -0,0 +1,11 @@
+/**
+ * src/oauth/dcr.ts — Dynamic Client Registration (RFC 7591).
+ *
+ * POST /oauth/register
+ *
+ * Deterministic client_id: SHA-256 of the sorted, joined redirect_uris.
+ * This means the same set of redirect URIs always produces the same client_id,
+ * making registration idempotent.
+ */
+import { type Router } from "express";
+export declare const oauthDcrRouter: Router;

package/dist/oauth/dcr.js

@@ -0,0 +1,49 @@
+/**
+ * src/oauth/dcr.ts — Dynamic Client Registration (RFC 7591).
+ *
+ * POST /oauth/register
+ *
+ * Deterministic client_id: SHA-256 of the sorted, joined redirect_uris.
+ * This means the same set of redirect URIs always produces the same client_id,
+ * making registration idempotent.
+ */
+import express from "express";
+import { createHash } from "node:crypto";
+export const oauthDcrRouter = express.Router();
+oauthDcrRouter.post("/oauth/register", (req, res) => {
+    // Validate Content-Type
+    const contentType = req.headers["content-type"];
+    if (!contentType || !contentType.includes("application/json")) {
+        res.status(400).json({
+            error: "invalid_request",
+            error_description: "Content-Type must be application/json.",
+        });
+        return;
+    }
+    const body = req.body;
+    // Validate redirect_uris
+    if (!body ||
+        !Array.isArray(body.redirect_uris) ||
+        body.redirect_uris.length === 0) {
+        res.status(400).json({
+            error: "invalid_client_metadata",
+            error_description: "redirect_uris must be a non-empty array of strings.",
+        });
+        return;
+    }
+    const redirect_uris = body.redirect_uris;
+    const client_name = body.client_name || "Unknown Client";
+    // Deterministic client_id: SHA-256 of sorted redirect URIs
+    const uriFingerprint = [...redirect_uris].sort().join("\n");
+    const client_id = createHash("sha256")
+        .update(uriFingerprint, "utf8")
+        .digest("hex");
+    res.status(201).json({
+        client_id,
+        client_name,
+        redirect_uris,
+        grant_types: ["authorization_code", "refresh_token"],
+        token_endpoint_auth_method: "none",
+        created_at: new Date().toISOString(),
+    });
+});

package/dist/oauth/discovery.d.ts

@@ -0,0 +1,12 @@
+/**
+ * src/oauth/discovery.ts — OAuth 2.1 Discovery endpoints.
+ *
+ * Implements:
+ *   GET /.well-known/oauth-protected-resource  (RFC 8707)
+ *   GET /.well-known/oauth-authorization-server (RFC 8414)
+ *
+ * All URLs use https:// per the OAuth 2.1 specification.
+ */
+import { type Router } from "express";
+export declare const PROTECTED_RESOURCE_METADATA_URL = "https://mcp.openephemeris.com/.well-known/oauth-protected-resource";
+export declare const oauthDiscoveryRouter: Router;

package/dist/oauth/discovery.js

@@ -0,0 +1,45 @@
+/**
+ * src/oauth/discovery.ts — OAuth 2.1 Discovery endpoints.
+ *
+ * Implements:
+ *   GET /.well-known/oauth-protected-resource  (RFC 8707)
+ *   GET /.well-known/oauth-authorization-server (RFC 8414)
+ *
+ * All URLs use https:// per the OAuth 2.1 specification.
+ */
+import express from "express";
+const MCP_SERVER_ORIGIN = "https://mcp.openephemeris.com";
+const WEB_APP_ORIGIN = "https://openephemeris.com";
+export const PROTECTED_RESOURCE_METADATA_URL = `${MCP_SERVER_ORIGIN}/.well-known/oauth-protected-resource`;
+export const oauthDiscoveryRouter = express.Router();
+// ---------------------------------------------------------------------------
+// GET /.well-known/oauth-protected-resource
+// Also served at the path-scoped /.well-known/oauth-protected-resource/mcp
+// per the latest MCP Authorization spec draft (some clients probe per-resource).
+// ---------------------------------------------------------------------------
+const protectedResourceHandler = (_req, res) => {
+    res.json({
+        resource: `${MCP_SERVER_ORIGIN}/mcp`,
+        authorization_servers: [MCP_SERVER_ORIGIN],
+        bearer_methods_supported: ["header"],
+        scopes_supported: ["openephemeris:read"],
+    });
+};
+oauthDiscoveryRouter.get("/.well-known/oauth-protected-resource", protectedResourceHandler);
+oauthDiscoveryRouter.get("/.well-known/oauth-protected-resource/mcp", protectedResourceHandler);
+// ---------------------------------------------------------------------------
+// GET /.well-known/oauth-authorization-server
+// ---------------------------------------------------------------------------
+oauthDiscoveryRouter.get("/.well-known/oauth-authorization-server", (_req, res) => {
+    res.json({
+        issuer: MCP_SERVER_ORIGIN,
+        authorization_endpoint: `${WEB_APP_ORIGIN}/oauth/authorize`,
+        token_endpoint: `${MCP_SERVER_ORIGIN}/oauth/token`,
+        registration_endpoint: `${MCP_SERVER_ORIGIN}/oauth/register`,
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code", "refresh_token"],
+        code_challenge_methods_supported: ["S256"],
+        token_endpoint_auth_methods_supported: ["none"],
+        scopes_supported: ["openephemeris:read"],
+    });
+});

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,18 @@
+/**
+ * src/oauth/pkce.ts — PKCE (Proof Key for Code Exchange) utilities.
+ *
+ * Implements RFC 7636 S256 challenge verification and cryptographically
+ * random authorization code generation.
+ */
+/**
+ * Verify that `code_challenge === base64url(SHA-256(code_verifier))`.
+ *
+ * Uses crypto.timingSafeEqual for the final comparison to prevent
+ * timing side-channel attacks.
+ */
+export declare function verifyCodeChallenge(code_verifier: string, code_challenge: string): boolean;
+/**
+ * Generate a cryptographically random authorization code.
+ * Returns 64 hex characters (32 random bytes).
+ */
+export declare function generateAuthorizationCode(): string;

package/dist/oauth/pkce.js

@@ -0,0 +1,34 @@
+/**
+ * src/oauth/pkce.ts — PKCE (Proof Key for Code Exchange) utilities.
+ *
+ * Implements RFC 7636 S256 challenge verification and cryptographically
+ * random authorization code generation.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+/**
+ * Verify that `code_challenge === base64url(SHA-256(code_verifier))`.
+ *
+ * Uses crypto.timingSafeEqual for the final comparison to prevent
+ * timing side-channel attacks.
+ */
+export function verifyCodeChallenge(code_verifier, code_challenge) {
+    if (!code_verifier || !code_challenge)
+        return false;
+    // SHA-256 hash the verifier and base64url encode it
+    const computed = createHash("sha256")
+        .update(code_verifier, "ascii")
+        .digest("base64url");
+    // Buffers must be equal length for timingSafeEqual
+    const computedBuf = Buffer.from(computed, "utf8");
+    const challengeBuf = Buffer.from(code_challenge, "utf8");
+    if (computedBuf.length !== challengeBuf.length)
+        return false;
+    return timingSafeEqual(computedBuf, challengeBuf);
+}
+/**
+ * Generate a cryptographically random authorization code.
+ * Returns 64 hex characters (32 random bytes).
+ */
+export function generateAuthorizationCode() {
+    return randomBytes(32).toString("hex");
+}

package/dist/oauth/rate-limit.d.ts

@@ -0,0 +1,20 @@
+/**
+ * src/oauth/rate-limit.ts — Simple per-IP rate limiter for the token endpoint.
+ *
+ * No external dependencies — uses a plain Map + setInterval for cleanup.
+ *
+ * Usage:
+ *   app.use("/oauth/token", createRateLimiter({ windowMs: 60_000, maxRequests: 10 }));
+ */
+import type { Request, Response, NextFunction } from "express";
+export interface RateLimiterOptions {
+    windowMs: number;
+    maxRequests: number;
+    trustProxy?: boolean;
+}
+/**
+ * Creates a rate-limiting Express middleware.
+ *
+ * Returns 429 with Retry-After header when the per-IP limit is exceeded.
+ */
+export declare function createRateLimiter(options: RateLimiterOptions): (req: Request, res: Response, next: NextFunction) => void;

package/dist/oauth/rate-limit.js

@@ -0,0 +1,65 @@
+/**
+ * src/oauth/rate-limit.ts — Simple per-IP rate limiter for the token endpoint.
+ *
+ * No external dependencies — uses a plain Map + setInterval for cleanup.
+ *
+ * Usage:
+ *   app.use("/oauth/token", createRateLimiter({ windowMs: 60_000, maxRequests: 10 }));
+ */
+/**
+ * Creates a rate-limiting Express middleware.
+ *
+ * Returns 429 with Retry-After header when the per-IP limit is exceeded.
+ */
+export function createRateLimiter(options) {
+    const { windowMs, maxRequests, trustProxy = false } = options;
+    const store = new Map();
+    // Cleanup expired entries every windowMs
+    const cleanupTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [ip, entry] of store) {
+            if (entry.resetAt <= now) {
+                store.delete(ip);
+            }
+        }
+    }, windowMs);
+    if (cleanupTimer.unref)
+        cleanupTimer.unref();
+    return (req, res, next) => {
+        // Determine client IP
+        let ip;
+        if (trustProxy) {
+            const forwarded = req.headers["x-forwarded-for"];
+            if (typeof forwarded === "string") {
+                ip = forwarded.split(",")[0].trim();
+            }
+            else if (Array.isArray(forwarded) && forwarded.length > 0) {
+                ip = forwarded[0].split(",")[0].trim();
+            }
+            else {
+                ip = req.ip || req.socket.remoteAddress || "unknown";
+            }
+        }
+        else {
+            ip = req.ip || req.socket.remoteAddress || "unknown";
+        }
+        const now = Date.now();
+        let entry = store.get(ip);
+        // Reset window if expired
+        if (!entry || entry.resetAt <= now) {
+            entry = { count: 0, resetAt: now + windowMs };
+            store.set(ip, entry);
+        }
+        entry.count++;
+        if (entry.count > maxRequests) {
+            const retryAfterSec = Math.ceil((entry.resetAt - now) / 1_000);
+            res.setHeader("Retry-After", String(retryAfterSec));
+            res.status(429).json({
+                error: "rate_limit_exceeded",
+                error_description: "Too many requests. Please try again later.",
+            });
+            return;
+        }
+        next();
+    };
+}

package/dist/oauth/store.d.ts

@@ -0,0 +1,88 @@
+/**
+ * src/oauth/store.ts — OAuth authorization code store.
+ *
+ * Architecture: in-memory is always the source of truth for the MCP server
+ * process. When Supabase env vars are present AND valid, codes are ALSO
+ * persisted async to Supabase for durability and multi-instance lookup.
+ *
+ * This means:
+ *   - Unit tests (no env vars) → pure in-memory, zero network calls ✓
+ *   - Production (Supabase set)  → in-memory for hot-path, Supabase for
+ *     persistence/audit trail ✓
+ *
+ * NOTE: The consent page (/api/oauth/approve) writes directly to Supabase
+ * using the service role key without going through this store.  The store
+ * is used by the MCP server's own /oauth/* endpoints.
+ *
+ * Security:
+ *   - NEVER log the `code` value.  Log only the row `id` (uuid).
+ *   - consumeCodeAsync marks codes consumed atomically in Supabase when
+ *     Supabase is reachable; falls through to in-memory otherwise.
+ */
+export interface IssuedCodeOptions {
+    client_id: string;
+    redirect_uri: string;
+    code_challenge: string;
+    code_challenge_method: "S256";
+    /** Optional user_id — set by consent page; undefined in unit tests */
+    user_id?: string;
+    expiresInMs?: number;
+}
+export declare class OAuthStore {
+    /** In-memory is ALWAYS the hot-path source of truth */
+    private codes;
+    private refreshTokens;
+    private cleanupTimer;
+    constructor();
+    /**
+     * Issue a new authorization code.
+     *
+     * Always writes to in-memory (fast, test-safe).
+     * Also fire-and-forgets a Supabase persist when env vars are set.
+     */
+    issueCode(options: IssuedCodeOptions): string;
+    /**
+     * Consume a code synchronously from in-memory (single-use).
+     * This is the fast-path used by the token endpoint.
+     */
+    consumeCode(code: string): (IssuedCodeOptions & {
+        used: boolean;
+        expires_at: Date;
+    }) | null;
+    /**
+     * Async consume — checks in-memory first, then Supabase.
+     *
+     * Use this from token.ts so production deployments with Supabase
+     * can survive process restarts (code issued before restart lives in DB).
+     */
+    consumeCodeAsync(code: string): Promise<(IssuedCodeOptions & {
+        used: boolean;
+        expires_at: Date;
+    }) | null>;
+    /**
+     * Refresh-token TTL — 90 days, sliding (reset on each rotation).
+     * Matches GitHub's 6-month convention more closely than Supabase's 30d
+     * default. Tradeoff: longer-lived refresh tokens = bigger blast radius
+     * on leak; rotation + Supabase RLS mitigates this. An active user who
+     * touches OE at least once per 90d gets an effectively permanent
+     * connection.
+     */
+    private static REFRESH_TTL_MS;
+    storeRefreshToken(token: string, meta: object): void;
+    /**
+     * Synchronous in-memory consume. Kept for backward compat with any callers
+     * that don't need cross-instance resilience. Token endpoint must use
+     * consumeRefreshTokenAsync.
+     */
+    consumeRefreshToken(token: string): object | null;
+    /**
+     * Async consume — checks in-memory first, then Supabase. This is what the
+     * token endpoint uses so refresh requests survive machine restarts and
+     * load-balancing across multiple Fly instances.
+     */
+    consumeRefreshTokenAsync(token: string): Promise<object | null>;
+    generateRefreshToken(): string;
+    reset(): void;
+    private purgeExpired;
+    destroy(): void;
+}