@openephemeris/mcp-server 3.17.0 → 3.20.0

package/CHANGELOG.md

@@ -7,6 +7,83 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.20.0] — 2026-07-09
+
+Second wave of the transport/iframe review: legacy transport retirement, resumability, and remaining hardening/quality items.
+
+### Removed
+- **Legacy SSE transport retired.** `GET /sse` + `POST /message` (pre-2025 spec, SDK-deprecated, no cross-machine replay, zero live sessions) now return `410 Gone` pointing at `/mcp`. `scripts/test-sse-client.ts` and the `test:sse` script removed; docs updated.
+
+### Added
+- **`Last-Event-ID` resumability.** Bounded in-memory `EventStore` (200 events/stream, 2h TTL) on the Streamable HTTP transport — a reconnecting SSE stream replays missed events instead of losing them. Per-process is safe because sessions are machine-pinned via fly-replay.
+- **Server-computed natal aspects.** `explore_natal_chart` was discarding the `aspects` array the natal endpoint already returns (with true ephemeris-derived `is_applying`) and re-deriving aspects client-side with an approximate heuristic — `computeAspects` deleted, server aspects mapped through. Bi-wheel cross-aspects stay client-side (two charts, no single endpoint) but the applying/separating heuristic now uses real longitude speeds instead of defaulted guesses.
+- **CSP + keyboard accessibility** on the four iframe apps: inline-only `Content-Security-Policy` meta on each shell; interactive SVG elements (planets, houses, aspects, centers/gates/channels) get `tabindex`/`role`/`aria-label`, Enter/Space activation, and visible focus indicators.
+- **Real-handler test coverage.** `createSseApp()` is now exported and `test/server-sse-real-app.test.ts` drives the actual Express app: 401/WWW-Authenticate contract, expired-JWT refresh signal, session issuance with machine prefix, cross-machine `fly-replay` 307 + loop-guard 404, resume-auth requirement, Host allowlist, and the 410 legacy responses.
+- **`check:plugin` release gate** (`scripts/plugin-audit.ts`): plugin.json version must match the package (it had rotted at 3.1.0) and `openephemeris-plugin.zip` must match the plugin tree by content; `regen:plugin` rebuilds both. Wired into `verify:release`.
+- **CI:** `validate:visual` (Playwright + axe over the app harness) added to the validate workflow; the live canary now sends a **Telegram alert on failure** (needs `TELEGRAM_BOT_TOKEN`/`TELEGRAM_CHAT_ID` secrets; no-ops without them).
+
+### Changed
+- Resume-path auth now runs **before** the session lookup so an unauthenticated probe cannot learn whether a session id exists.
+
+---
+
+## [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

@@ -187,7 +187,7 @@ The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable
 
 - **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
+- **Legacy SSE**: retired in 3.20.0 — use Streamable HTTP at `/mcp`
 
 ### Auth and upgrade behavior in MCP clients
 

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.
@@ -253,14 +270,18 @@ export class BackendClient {
                     `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}`;
@@ -361,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/event-store.d.ts

@@ -0,0 +1,11 @@
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import type { EventStore, EventId, StreamId } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+export declare class InMemoryEventStore implements EventStore {
+    private streams;
+    storeEvent(streamId: StreamId, message: JSONRPCMessage): Promise<EventId>;
+    replayEventsAfter(lastEventId: EventId, { send }: {
+        send: (eventId: EventId, message: JSONRPCMessage) => Promise<void>;
+    }): Promise<StreamId>;
+    /** Drop streams idle past the TTL so abandoned sessions don't leak memory. */
+    private reapStale;
+}

package/dist/event-store.js

@@ -0,0 +1,61 @@
+/**
+ * event-store.ts — bounded in-memory EventStore for Streamable HTTP
+ * resumability (Last-Event-ID).
+ *
+ * Without an event store the transport cannot replay server→client messages
+ * missed across an SSE reconnect — a dropped connection silently loses any
+ * buffered events. This store keeps a small per-session ring of recent events
+ * so a client reconnecting with Last-Event-ID resumes cleanly.
+ *
+ * Deliberately in-memory and per-process: sessions are already machine-pinned
+ * (fly-replay routes a session's requests to its owning machine), so the
+ * events for a session always live on the machine handling its reconnect.
+ */
+import { randomUUID } from "node:crypto";
+const MAX_EVENTS_PER_STREAM = 200;
+const STREAM_TTL_MS = 2 * 60 * 60 * 1000; // matches the session idle TTL
+export class InMemoryEventStore {
+    streams = new Map();
+    async storeEvent(streamId, message) {
+        // Event IDs embed the stream ID so replay can locate the stream without a
+        // secondary index: "<streamId>__<uuid>".
+        const eventId = `${streamId}__${randomUUID()}`;
+        let stream = this.streams.get(streamId);
+        if (!stream) {
+            stream = { events: [], lastTouched: Date.now() };
+            this.streams.set(streamId, stream);
+        }
+        stream.events.push({ eventId, message });
+        stream.lastTouched = Date.now();
+        if (stream.events.length > MAX_EVENTS_PER_STREAM) {
+            stream.events.splice(0, stream.events.length - MAX_EVENTS_PER_STREAM);
+        }
+        this.reapStale();
+        return eventId;
+    }
+    async replayEventsAfter(lastEventId, { send }) {
+        const sep = lastEventId.lastIndexOf("__");
+        const streamId = sep > 0 ? lastEventId.slice(0, sep) : "";
+        const stream = this.streams.get(streamId);
+        if (!stream)
+            return streamId;
+        const idx = stream.events.findIndex((e) => e.eventId === lastEventId);
+        // If the event aged out of the ring, replay nothing rather than
+        // duplicating from an unknown point — the client re-requests as needed.
+        if (idx === -1)
+            return streamId;
+        for (const event of stream.events.slice(idx + 1)) {
+            await send(event.eventId, event.message);
+        }
+        stream.lastTouched = Date.now();
+        return streamId;
+    }
+    /** Drop streams idle past the TTL so abandoned sessions don't leak memory. */
+    reapStale() {
+        const cutoff = Date.now() - STREAM_TTL_MS;
+        for (const [id, stream] of this.streams) {
+            if (stream.lastTouched < cutoff)
+                this.streams.delete(id);
+        }
+    }
+}

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/server-sse.d.ts

@@ -1 +1,7 @@
-export {};
+import express from "express";
+/**
+ * Build the full Express app (auth gate, OAuth routes, /mcp Streamable HTTP,
+ * health, resources). Exported so tests can drive the REAL handlers with
+ * supertest instead of a re-implemented stub. Does not listen.
+ */
+export declare function createSseApp(): Promise<express.Application>;