@openephemeris/mcp-server 3.16.0 → 3.19.0

package/CHANGELOG.md

@@ -7,6 +7,63 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.19.0] — 2026-07-09
+
+Transport hardening + E2E release verification, from a full review of the streaming HTTP transport and iframe app capability.
+
+### Fixed
+- **stdio missing the MCP Apps capability flag.** The stdio entry (`src/index.ts`) never advertised `experimental["io.modelcontextprotocol/ui"]` (the SSE server did), so hosts gating iframe rendering on that capability would not render apps from a local install. Now declared on both transports.
+- **Rotted integration scripts.** `scripts/test-client.ts` and `scripts/smoke-dev-profile.ts` still asserted pre-rename dotted tool names (`auth.login`, `dev.call`) and could never pass. Fixed and wired into CI so they can't rot silently again.
+
+### Added
+- **SSE keepalive.** Long-lived streams (`GET /mcp` leg and legacy `/sse`) now emit an SSE comment frame every 25s and disable the per-socket idle timeout, preventing silent drops through Fly's proxy on idle sessions.
+- **Idle session reaper.** In-memory HTTP sessions abandoned without a DELETE are reaped after 2h idle (they previously leaked until process restart); a reaped session 404s and the client re-initializes per spec.
+- **Tool-call timeout** (120s) so a hung backend request can't pin a session forever.
+- **Resume-path auth.** A session id alone is no longer sufficient to resume a Streamable HTTP session — every request must still carry a valid API key / non-expired JWT (expired JWTs get the standard 401 `invalid_token` refresh signal).
+- **Host-header allowlist** on `/mcp`, `/sse`, `/message` as DNS-rebinding defense (Origin was already validated; Host was not). Extend via `MCP_ALLOWED_HOSTS`.
+- **Fly HTTP health check** on `/health` (previously TCP-only, so a hung process stayed in rotation).
+- **E2E release verification:** `test:published` installs the packed/published tarball into a clean dir and drives `dist/index.js` over stdio (initialize → tools/list → UI resource read → tool call); `test:mcp-http` drives the live Streamable HTTP endpoint end to end including an MCP Apps `resources/read`. Wired into the validate workflow, as a post-publish gate in the npm workflow, and as a 6-hourly production canary.
+- **Tool-count regression test** (84) keeping the marketing SSOT honest.
+
+### Removed
+- **Dormant UI apps deleted** (transit-timeline, bazi, vedic-chart): never imported/registered, two never functional; their trees, tool files, per-app lockfiles, and `build:ui` steps are gone. BaZi/Vedic data still ships via the typed `bazi_*`/`vedic_chart` tools.
+- Leftover one-off codemods (`fix.cjs`, `fix.mjs`, `fix2.mjs`) and the empty `dev_card.json`.
+- 7 byte-identical copies of `singlefile-plugin.ts` (now shared from `src/ui/shared/`); debug `console.log` noise stripped from the chart-wheel bundle.
+
+### Changed
+- Runtime Docker image now prunes dev dependencies before the final stage.
+
+---
+
+## [3.18.0] — 2026-07-06
+
+Launch-reliability hardening for the remote SSE/HTTP server (`oe-mcp-live`).
+
+### Fixed
+- **Stale-JWT dead session.** Self-signed Supabase JWTs expire after 1h. A session's `BackendClient` captured the JWT once at init and the resume path never re-read it, so after the host refreshed the token every tool call kept sending the frozen expired JWT and 401'd forever (users were told to disconnect/reconnect). `BackendClient.setJwt()` now lets the resume branch push the freshly-rotated Bearer token into the session client. Additionally, the `/mcp` auth gate now decodes the JWT `exp` claim (no signature verification — the Go API is the trust boundary) and returns `401 invalid_token` + `WWW-Authenticate` for an already-expired token, triggering the host's OAuth refresh instead of a confusing downstream tool error.
+- **POST retry double-charge.** The axios retry loop retried every method — including POST — on transient failures, and every expensive compute endpoint is POST (e.g. `acg_hits` = 15 credits) metered at reservation time, so one dropped response could be billed up to 4×. Only idempotent GETs are auto-retried now; POST/PUT/PATCH/DELETE are never retried. `429` is no longer retried at all — the rate-limit message surfaces immediately instead of hammering the limiter.
+- **`isError` correctness.** Both CallTool handlers previously set `isError: !isRetryable`, so 429/5xx/network/auth failures arrived as `isError: false` "successes." All failures now report `isError: true` so hosts recover (retry / OAuth refresh), with the one exception of the stdio device-auth-pending case (whose message carries a verification link the model must relay). Extracted into a shared, unit-tested `formatToolError` helper.
+- **Cross-machine session 404s.** `min_machines_running = 2` but the session store is a per-process Map, so a resume request landing on the other machine 404'd. Streamable-HTTP session IDs now embed `FLY_MACHINE_ID`; a request whose session ID targets a different machine is re-routed via the `fly-replay` header (with a `fly-replay-src` loop guard that falls through to 404 so the client re-initializes). No-op locally when `FLY_MACHINE_ID` is unset.
+- **API-key validation no longer costs a credit.** Session-init key validation probed `/ephemeris/moon/phase`, which meters at 1 credit — so merely connecting charged the user. Switched to `/catalogs/bodies` (auth-gated but metered at 0 credits).
+- **ACG / progressed datetime descriptions** now require a UTC offset (e.g. `1990-05-15T14:30:00-05:00`); a naive datetime was silently interpreted as UTC and mislocated ACG lines / shifted progressions.
+- **`dev_read_api` reference text** corrected: `/location/autocomplete` takes `query=`, not `q=`.
+
+### Changed
+- Added a `process.on('unhandledRejection')` log-and-continue handler so a single rejected request can't take down every live session.
+- 402 credit-exhausted message annotated with a pointer to the pricing SSOT (`apps/web/config/billing-plans.ts`).
+- `fly.toml` VM memory raised 512MB → 1024MB for the launch window.
+
+---
+
+## [3.17.0] — 2026-07-06
+
+Docs-only release (this is the version live on npm while 3.18.0 awaited publish).
+
+### Changed
+- README: embedded the hero demo GIF and refreshed the quick-start copy for the launch window (PR #258). No runtime changes.
+
+---
+
 ## [3.16.0] — 2026-07-05
 
 ### Added

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025-2026 Open Ephemeris
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025-2026 Open Ephemeris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,7 +4,9 @@
 [![npm version](https://img.shields.io/npm/v/@openephemeris/mcp-server)](https://www.npmjs.com/package/@openephemeris/mcp-server)
 [![System Status](https://img.shields.io/badge/Status-Operational-brightgreen)](https://status.openephemeris.com/)
 
-Model Context Protocol server for OpenEphemeris — 52 typed astrology tools powered by the NASA JPL DE440 ephemeris. Zero hallucination on planetary positions, dates, and degrees. Covers 1,100 years of astronomical data.
+![OpenEphemeris in Claude — ask in plain language, get a real computed chart](https://raw.githubusercontent.com/openephemeris/openephemeris/main/docs/internal/PH-ASSETS/hero-demo.gif)
+
+Model Context Protocol server for OpenEphemeris — typed astrology tools powered by the NASA JPL DE440 ephemeris. Zero hallucination on planetary positions, dates, and degrees. Covers 1,100 years of astronomical data.
 
 **Hosted endpoint:** `https://mcp.openephemeris.com/mcp` (Streamable HTTP, MCP 2025-11-25 spec)
 
@@ -337,7 +339,7 @@ When you update the MCP server logic (handlers, bug fixes, hardening), you shoul
               ┌────▼────────────────────┐
               │  openephemeris-mcp      │
               │  Node.js MCP Server     │
-              │  52 typed tools         │
+              │  typed tools            │
               │  auth: Key > JWT        │
               └────────────┬────────────┘
                            │ HTTPS
@@ -357,8 +359,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`): **82**
-- 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_list_allowed`, `dev_read_api`, `dev_write_api`, `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_human_design_connection`, `explore_human_design_transit`, `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`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **84**
+- 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_list_allowed`, `dev_read_api`, `dev_write_api`, `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_human_design_connection`, `explore_human_design_transit`, `explore_moon_phase`, `explore_natal_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_connection_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_transit_channel_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/dist/backend/client.d.ts

@@ -44,6 +44,15 @@ export declare class BackendClient {
      * metered against the correct user account.
      */
     setApiKey(key: string): void;
+    /**
+     * Override the stored JWT at runtime. Used by the SSE/HTTP server to refresh
+     * a session's Bearer token when the host (e.g. claude.ai) rotates it via
+     * /oauth/token. Self-signed Supabase JWTs expire after 1h, so without this a
+     * long-lived session would keep sending the frozen expired token and 401 on
+     * every tool call. Only takes effect when no API key / service key is set
+     * (JWT is the lowest-priority credential in the interceptor).
+     */
+    setJwt(jwt: string): void;
     /**
      * Start the device auth flow in the background if not already running.
      * Called automatically when no credentials are found in the interceptor.

package/dist/backend/client.js

@@ -4,7 +4,13 @@ import { CredentialManager } from "../auth/credentials.js";
 import { DeviceAuthFlow } from "../auth/device-auth.js";
 const DEFAULT_TIMEOUT_MS = 45_000;
 const RETRY_DELAYS_MS = [1_000, 2_000, 4_000]; // Three retries with backoff
-const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+// NOTE: 429 is intentionally NOT retryable. Every expensive compute endpoint is
+// POST and the Go API meters at reservation time, so retrying a rate-limited or
+// dropped POST double-charges the user (e.g. acg_hits = 15 credits × retries).
+// We only auto-retry idempotent GETs on transient transport/5xx failures; the
+// 429 message is surfaced immediately so the caller backs off instead of
+// hammering the limiter. See request() for the GET-only guard.
+const RETRYABLE_STATUSES = new Set([502, 503, 504]);
 const RETRYABLE_CODES = new Set(["ECONNRESET", "ETIMEDOUT", "ENOTFOUND", "EAI_AGAIN"]);
 const BINARY_ENDPOINT_PREFIXES = [
     "/visualization/bi-wheel",
@@ -118,6 +124,17 @@ export class BackendClient {
         this.serviceKey = undefined;
         this.jwt = undefined;
     }
+    /**
+     * Override the stored JWT at runtime. Used by the SSE/HTTP server to refresh
+     * a session's Bearer token when the host (e.g. claude.ai) rotates it via
+     * /oauth/token. Self-signed Supabase JWTs expire after 1h, so without this a
+     * long-lived session would keep sending the frozen expired token and 401 on
+     * every tool call. Only takes effect when no API key / service key is set
+     * (JWT is the lowest-priority credential in the interceptor).
+     */
+    setJwt(jwt) {
+        this.jwt = jwt;
+    }
     /**
      * Start the device auth flow in the background if not already running.
      * Called automatically when no credentials are found in the interceptor.
@@ -248,17 +265,23 @@ export class BackendClient {
                         `If you don't have an account, you can create one at the link above (free tier, no credit card needed).`, 401, "auth_required", true, authInfo.verification_uri_complete);
                 }
                 return new BackendError(`Authentication required: ${msg}. Run auth.login to connect your account, ` +
-                    `or set OPENEPHEMERIS_API_KEY in your MCP server config.`, 401, "auth_required", false, LOGIN_SIGNUP_URL);
+                    `or set OPENEPHEMERIS_API_KEY in your MCP server config. If you connected ` +
+                    `through Claude's connector settings, disconnect and reconnect the ` +
+                    `OpenEphemeris connector to re-authorize.`, 401, "auth_required", false, LOGIN_SIGNUP_URL);
             }
             if (status === 402) {
+                // PRICING SSOT: apps/web/config/billing-plans.ts — Explorer grant
+                // (EXPLORER.creditsNumeric = 150, one-time), Pro/`developer`
+                // (monthlyPrice = 29, credits = 75,000), and CREDIT_TOPUPS
+                // ($5→150, $10→350, $20→900). Keep every number below in sync with
+                // that file; do NOT hand-edit these figures independently.
                 const dataObj = data && typeof data === "object" ? data : {};
                 const walletUrl = dataObj.upgrade?.wallets_url || "https://openephemeris.com/wallet";
                 const currentTier = dataObj.upgrade?.current_tier || dataObj.tier || "explorer";
-                const isPro = currentTier === "developer" || currentTier === "pro" || currentTier === "startup" || currentTier === "scale";
                 let upsellMsg = "";
                 if (currentTier === 'explorer') {
                     upsellMsg =
-                        `Let the user know warmly: Their 150 free discovery credits are used up. ` +
+                        `Let the user know warmly: Their 150 free credits (one-time grant) are used up. ` +
                             `They can top up their wallet starting at $5 for 150 credits at ` +
                             `${walletUrl} — or upgrade to Pro ($29/mo) ` +
                             `for 75,000 credits/month at ${UPGRADE_URL}`;
@@ -359,8 +382,14 @@ export class BackendClient {
             }
             catch (err) {
                 if (err instanceof AxiosError) {
-                    const isRetryable = (err.response && RETRYABLE_STATUSES.has(err.response.status)) ||
-                        (!err.response && err.code && RETRYABLE_CODES.has(err.code));
+                    // Only idempotent GETs may be auto-retried. POST/PUT/PATCH/DELETE are
+                    // never retried: expensive compute endpoints are POST and the Go API
+                    // meters credits at reservation time, so a retried POST double-charges
+                    // even when the original response was merely lost in transit.
+                    const isIdempotent = method === "GET";
+                    const isRetryable = isIdempotent &&
+                        ((err.response && RETRYABLE_STATUSES.has(err.response.status)) ||
+                            (!err.response && !!err.code && RETRYABLE_CODES.has(err.code)));
                     if (isRetryable && attempt < RETRY_DELAYS_MS.length) {
                         const jitter = Math.random() * 500;
                         await sleep(RETRY_DELAYS_MS[attempt] + jitter);

package/dist/index.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 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 { initTools, toolRegistry, formatToolResponse, formatToolError, 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";
@@ -42,6 +42,14 @@ const server = new Server({
         tools: {},
         prompts: {},
         resources: {},
+        experimental: {
+            // Declare MCP Apps extension (spec: io.modelcontextprotocol/ui, 2026-01-26).
+            // Must match the SSE server's capability block so stdio hosts (Claude
+            // Desktop) also know this server returns renderable HTML resources.
+            "io.modelcontextprotocol/ui": {
+                mimeTypes: ["text/html;profile=mcp-app"],
+            },
+        },
     },
 });
 // List available tools
@@ -176,17 +184,10 @@ 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: `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: !isRetryable,
-        };
+        // isError: true for every failure so the host recovers, EXCEPT the stdio
+        // device-auth-pending case (model must relay the verification link).
+        return formatToolError(error);
     }
 });
 // Start server

package/dist/oauth/session-utils.d.ts

@@ -0,0 +1,59 @@
+/**
+ * src/oauth/session-utils.ts — Pure helpers for session reliability.
+ *
+ * Two concerns live here so they can be unit-tested without spinning up the
+ * full SSE server:
+ *
+ *   1. JWT expiry decoding — read the `exp` claim WITHOUT signature
+ *      verification. The signature is validated downstream by the Go API's
+ *      ValidateSupabaseJWT; here we only need to know whether a token is
+ *      already expired so the /mcp gate can trigger the host's OAuth refresh
+ *      (401 invalid_token) instead of letting it die as a confusing tool error.
+ *
+ *   2. Machine-scoped session IDs — Fly runs min_machines_running >= 2, but the
+ *      HTTP/SSE session store is a per-process Map. A resume request can land on
+ *      a different machine and 404. We embed the FLY_MACHINE_ID into generated
+ *      session IDs so an incoming request can be re-routed to the owning machine
+ *      via the `fly-replay` header. Local/dev (no FLY_MACHINE_ID) is a no-op.
+ */
+/**
+ * Decode a JWT's payload without verifying the signature and return its `exp`
+ * claim (seconds since epoch), or null if the token is malformed / has no exp.
+ *
+ * Signature verification is intentionally skipped — the Go API is the trust
+ * boundary. This is only used to decide whether to prompt the host to refresh.
+ */
+export declare function decodeJwtExp(token: string): number | null;
+/**
+ * Returns true when the JWT is expired (or expires within `skewSeconds`).
+ * A token we cannot decode (or that carries no exp) is treated as NOT expired
+ * so we never block a token the Go API might still accept — the downstream
+ * validator remains the source of truth.
+ */
+export declare function isJwtExpired(token: string, skewSeconds?: number, nowMs?: number): boolean;
+/** The current Fly machine id, or "" when running locally / outside Fly. */
+export declare function currentMachineId(): string;
+/**
+ * Wrap a raw session ID with the current machine id when running on Fly.
+ * Local/dev (no FLY_MACHINE_ID) returns the raw id unchanged so behavior and
+ * existing session-id shapes are preserved off-platform.
+ */
+export declare function encodeSessionId(rawId: string, machineId?: string): string;
+/**
+ * Extract the machine id embedded in a session ID, or "" if none is present
+ * (locally-minted id, or a legacy id from before this scheme).
+ */
+export declare function machineIdFromSessionId(sessionId: string): string;
+/**
+ * Decide whether an incoming request for `sessionId` should be replayed to a
+ * different Fly machine.
+ *
+ * Returns the target machine id to replay to, or null to handle locally.
+ * Guards against replay loops: if the request was already replayed
+ * (fly-replay-src header present) we never replay again — the caller falls
+ * through to its normal 404 so the client re-initializes per the MCP spec.
+ */
+export declare function replayTargetMachine(sessionId: string, opts: {
+    selfMachineId?: string;
+    alreadyReplayed: boolean;
+}): string | null;

package/dist/oauth/session-utils.js

@@ -0,0 +1,110 @@
+/**
+ * src/oauth/session-utils.ts — Pure helpers for session reliability.
+ *
+ * Two concerns live here so they can be unit-tested without spinning up the
+ * full SSE server:
+ *
+ *   1. JWT expiry decoding — read the `exp` claim WITHOUT signature
+ *      verification. The signature is validated downstream by the Go API's
+ *      ValidateSupabaseJWT; here we only need to know whether a token is
+ *      already expired so the /mcp gate can trigger the host's OAuth refresh
+ *      (401 invalid_token) instead of letting it die as a confusing tool error.
+ *
+ *   2. Machine-scoped session IDs — Fly runs min_machines_running >= 2, but the
+ *      HTTP/SSE session store is a per-process Map. A resume request can land on
+ *      a different machine and 404. We embed the FLY_MACHINE_ID into generated
+ *      session IDs so an incoming request can be re-routed to the owning machine
+ *      via the `fly-replay` header. Local/dev (no FLY_MACHINE_ID) is a no-op.
+ */
+/**
+ * Decode a JWT's payload without verifying the signature and return its `exp`
+ * claim (seconds since epoch), or null if the token is malformed / has no exp.
+ *
+ * Signature verification is intentionally skipped — the Go API is the trust
+ * boundary. This is only used to decide whether to prompt the host to refresh.
+ */
+export function decodeJwtExp(token) {
+    if (typeof token !== "string" || !token)
+        return null;
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const payloadJson = Buffer.from(parts[1], "base64url").toString("utf8");
+        const payload = JSON.parse(payloadJson);
+        if (typeof payload.exp === "number" && Number.isFinite(payload.exp)) {
+            return payload.exp;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns true when the JWT is expired (or expires within `skewSeconds`).
+ * A token we cannot decode (or that carries no exp) is treated as NOT expired
+ * so we never block a token the Go API might still accept — the downstream
+ * validator remains the source of truth.
+ */
+export function isJwtExpired(token, skewSeconds = 0, nowMs = Date.now()) {
+    const exp = decodeJwtExp(token);
+    if (exp === null)
+        return false;
+    const nowSec = Math.floor(nowMs / 1000);
+    return exp <= nowSec + skewSeconds;
+}
+// ---------------------------------------------------------------------------
+// Machine-scoped session IDs (Fly request replay)
+// ---------------------------------------------------------------------------
+const MACHINE_PREFIX_SEP = "."; // "<machineId>.<rawSessionId>"
+/** The current Fly machine id, or "" when running locally / outside Fly. */
+export function currentMachineId() {
+    return process.env.FLY_MACHINE_ID || "";
+}
+/**
+ * Wrap a raw session ID with the current machine id when running on Fly.
+ * Local/dev (no FLY_MACHINE_ID) returns the raw id unchanged so behavior and
+ * existing session-id shapes are preserved off-platform.
+ */
+export function encodeSessionId(rawId, machineId = currentMachineId()) {
+    if (!machineId)
+        return rawId;
+    return `${machineId}${MACHINE_PREFIX_SEP}${rawId}`;
+}
+/**
+ * Extract the machine id embedded in a session ID, or "" if none is present
+ * (locally-minted id, or a legacy id from before this scheme).
+ */
+export function machineIdFromSessionId(sessionId) {
+    if (typeof sessionId !== "string")
+        return "";
+    const idx = sessionId.indexOf(MACHINE_PREFIX_SEP);
+    if (idx <= 0)
+        return "";
+    return sessionId.slice(0, idx);
+}
+/**
+ * Decide whether an incoming request for `sessionId` should be replayed to a
+ * different Fly machine.
+ *
+ * Returns the target machine id to replay to, or null to handle locally.
+ * Guards against replay loops: if the request was already replayed
+ * (fly-replay-src header present) we never replay again — the caller falls
+ * through to its normal 404 so the client re-initializes per the MCP spec.
+ */
+export function replayTargetMachine(sessionId, opts) {
+    const selfMachineId = opts.selfMachineId ?? currentMachineId();
+    // Off-Fly (no machine identity) → never replay.
+    if (!selfMachineId)
+        return null;
+    // Already bounced once → don't loop; let the caller 404.
+    if (opts.alreadyReplayed)
+        return null;
+    const target = machineIdFromSessionId(sessionId);
+    if (!target)
+        return null; // legacy / local id — can't route
+    if (target === selfMachineId)
+        return null; // we own it
+    return target;
+}

package/dist/oauth/token.js

@@ -21,6 +21,20 @@ import { timingSafeEqual } from "node:crypto";
 import { verifyCodeChallenge } from "./pkce.js";
 import { issueSupabaseJWT, refreshSupabaseSession } from "./supabase-jwt.js";
 // ---------------------------------------------------------------------------
+// Supabase config check (mirrors store.ts / supabase-jwt.ts)
+// ---------------------------------------------------------------------------
+/**
+ * True when Supabase env vars are configured, meaning callers expect a real
+ * JWT. In that case a JWT-issuance failure must be reported as an OAuth
+ * error rather than silently degrading to a placeholder token — a
+ * placeholder access_token is classified as an API key downstream
+ * (server-sse.ts extractAuth) and will 401 on every subsequent request,
+ * leaving the connector stuck in a "connected but broken" state.
+ */
+function isSupabaseConfigured() {
+    return Boolean(process.env["SUPABASE_URL"] && process.env["SUPABASE_SERVICE_ROLE_KEY"]);
+}
+// ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 /**
@@ -113,8 +127,10 @@ async function handleAuthorizationCode(req, res, store) {
             store.storeRefreshToken(oauthRefreshToken, {
                 client_id: stored.client_id,
                 user_id: stored.user_id,
-                // Keep the Supabase refresh token for downstream refresh
-                supabase_refresh_token: supabaseTokens.refresh_token,
+                // Real Supabase refresh tokens aren't available for self-signed JWTs
+                // (see supabase-jwt.ts) — storing null avoids a doomed Supabase
+                // refresh round-trip on the next /oauth/token refresh_token grant.
+                supabase_refresh_token: null,
             });
             console.info(`[token] Supabase JWT issued for user ${stored.user_id}`);
             res.json({
@@ -125,10 +141,23 @@ async function handleAuthorizationCode(req, res, store) {
             });
             return;
         }
-        // Supabase JWT issuance failed — log a warning but continue to placeholder
+        // Supabase JWT issuance failed. If Supabase is configured, the caller
+        // expects a real JWT — returning a placeholder here would leave the
+        // connector "connected" while every subsequent API call 401s (a
+        // placeholder access_token is classified as an API key, not a JWT, by
+        // server-sse.ts's extractAuth). Report a proper OAuth error instead so
+        // the client can retry or surface the failure.
+        if (isSupabaseConfigured()) {
+            console.error(`[token] Supabase JWT issuance failed for user ${stored.user_id}; returning server_error`);
+            res.status(500).json({
+                error: "server_error",
+                error_description: "Failed to issue an access token. Please try again.",
+            });
+            return;
+        }
         console.warn(`[token] Supabase JWT issuance failed for user ${stored.user_id}, falling back to placeholder`);
     }
-    // Fallback: local placeholder tokens (test/dev path)
+    // Fallback: local placeholder tokens (test/dev path — Supabase not configured)
     const refreshToken = store.generateRefreshToken();
     store.storeRefreshToken(refreshToken, { client_id: stored.client_id });
     res.json({
@@ -166,7 +195,10 @@ async function handleRefreshToken(req, res, store) {
     // ---------------------------------------------------------------------------
     const userId = storedMeta.user_id;
     const supabaseRefresh = storedMeta.supabase_refresh_token;
-    // Try Supabase refresh first
+    // Try Supabase refresh first — only meaningful if we ever obtained a real
+    // Supabase refresh token. Self-signed JWTs (see supabase-jwt.ts) never do,
+    // so supabase_refresh_token is stored as null and this is skipped in favor
+    // of going straight to the working issueSupabaseJWT(userId) fallback below.
     if (supabaseRefresh) {
         const refreshed = await refreshSupabaseSession(supabaseRefresh);
         if (refreshed) {
@@ -192,7 +224,9 @@ async function handleRefreshToken(req, res, store) {
             const newRefreshToken = store.generateRefreshToken();
             store.storeRefreshToken(newRefreshToken, {
                 ...storedMeta,
-                supabase_refresh_token: freshTokens.refresh_token,
+                // See note above — self-signed JWTs have no real Supabase refresh
+                // token, so store null rather than the JWT's own (also fake) one.
+                supabase_refresh_token: null,
             });
             res.json({
                 access_token: freshTokens.access_token,
@@ -202,8 +236,21 @@ async function handleRefreshToken(req, res, store) {
             });
             return;
         }
+        // We have a user_id (Supabase-issued grant) but JWT issuance failed.
+        // Same reasoning as the authorization_code path: a placeholder token
+        // here would falsely appear "refreshed" while every subsequent request
+        // 401s. Report a proper OAuth error so the client can retry/reauth.
+        if (isSupabaseConfigured()) {
+            console.error(`[token] Refresh: Supabase JWT re-issuance failed for user ${userId}; returning server_error`);
+            res.status(500).json({
+                error: "server_error",
+                error_description: "Failed to refresh the access token. Please try again.",
+            });
+            return;
+        }
     }
-    // Fallback: placeholder tokens
+    // Fallback: placeholder tokens (test/dev path — Supabase not configured,
+    // or this refresh token predates any user_id/Supabase association)
     const newRefreshToken = store.generateRefreshToken();
     store.storeRefreshToken(newRefreshToken, storedMeta);
     res.json({