@elfa-ai/mcp 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 4.2.0
+
+### Added
+
+- **OAuth sign-in for hosted deployments** (`ELFA_MCP_AUTH=oauth`, HTTP transport only). Clients such as ChatGPT, Claude and Codex can connect with a browser sign-in instead of an API key. The server acts as an OAuth resource server under the MCP authorization spec:
+  - It serves RFC 9728 protected-resource metadata at `/.well-known/oauth-protected-resource/mcp` (and at the root path).
+  - A request with no credential gets `401` with a `WWW-Authenticate: Bearer resource_metadata=…` challenge.
+  - Each bearer token is checked against the authorization server's introspection endpoint, which returns the Elfa API key the request runs as. The token itself is never forwarded to the Elfa API.
+  - The token must be issued for this server: its audience has to match `ELFA_MCP_RESOURCE_URL`.
+  - Valid answers are cached for up to 60 seconds.
+  - An unreachable authorization server returns `503`, not `401`, so clients don't restart sign-in because of an outage.
+- An `x-elfa-api-key` header still works in OAuth mode, so API-key users of the same deployment are unaffected.
+
+### Changed
+
+- `getMarketEvents-v2` is no longer listed as unexposed. The Elfa API dropped it from the published spec, so there is nothing left to account for.
+- In OAuth mode `ELFA_API_KEY` is ignored. Every request brings its own credential, and an environment key would otherwise be handed to any caller that sends none. API-key mode keeps its environment fallback.
+
 ## 4.1.0
 
 ### Security

package/README.md

@@ -79,7 +79,6 @@ Some MCP clients apply their own timeout, often around 60 seconds. `narratives`
 
 Not exposed as tools:
 
-- `getMarketEvents-v2` — Available only to select Enterprise customers, and the published operation takes no parameters. Contact sales@elfa.ai for access.
 - `chat-stream-v2` — A tool call returns one result, so streaming adds nothing. market_chat covers the same analysis.
 - `auto-stream-queries-v2` — Long lived streams have no tool equivalent. Poll with auto_query.
 - `auto-stream-query-v2` — Long lived streams have no tool equivalent. Poll with auto_query.
@@ -123,7 +122,7 @@ The same server runs over Streamable HTTP for hosted deployments:
 ELFA_MCP_TRANSPORT=http ELFA_MCP_PORT=3000 npx -y @elfa-ai/mcp
 ```
 
-It is stateless — no sessions, one server instance per request, safe behind a load balancer. Credentials come from the `x-elfa-api-key` request header, falling back to the environment.
+It is stateless — no sessions, one server instance per request, safe behind a load balancer. Credentials come from the `x-elfa-api-key` request header, falling back to the environment, or from an OAuth sign-in (see below).
 
 DNS rebinding protection is on by default. The server accepts only the loopback names it binds — `localhost:PORT` and `127.0.0.1:PORT` — which covers the local run above and nothing else. Any deployment that answers on a different `Host` must list the values it serves:
 
@@ -143,6 +142,42 @@ That includes a public domain, a reverse proxy, and a container that maps the po
 
 Set `ELFA_MCP_ALLOWED_ORIGINS` as well when browsers call the server directly. It complements the host allowlist rather than replacing it: a rebound request is same origin, so it carries no `Origin` header for that list to check, and the `Host` header is the only one still naming the attacker's domain.
 
+### OAuth sign-in
+
+A hosted server can let clients sign in through a browser instead of sending an API key. Set `ELFA_MCP_AUTH=oauth` and the server becomes an OAuth resource server under the MCP authorization spec:
+
+1. A request with no credential gets `401` and a `WWW-Authenticate` challenge.
+2. The challenge points the client to the protected-resource metadata at `/.well-known/oauth-protected-resource/mcp`.
+3. That metadata names the authorization server, where the user signs in.
+4. The client then sends `Authorization: Bearer <token>`.
+5. The server checks the token against the authorization server's introspection endpoint. The endpoint answers with the Elfa API key the request runs as, so the token never reaches the Elfa API.
+
+```bash
+ELFA_MCP_TRANSPORT=http \
+ELFA_MCP_AUTH=oauth \
+ELFA_MCP_RESOURCE_URL=https://mcp.example.com/mcp \
+ELFA_OAUTH_ISSUER=https://auth.example.com \
+ELFA_OAUTH_INTROSPECTION_URL=https://auth.example.com/introspect \
+ELFA_OAUTH_INTROSPECTION_TOKEN=... \
+ELFA_MCP_ALLOWED_HOSTS=mcp.example.com \
+npx -y @elfa-ai/mcp
+```
+
+| Variable | Required in OAuth mode | Purpose |
+| --- | --- | --- |
+| `ELFA_MCP_AUTH` | yes | `oauth` to enable, default `apikey` |
+| `ELFA_MCP_RESOURCE_URL` | yes | Canonical URL of this endpoint. Tokens must be issued for exactly this value |
+| `ELFA_OAUTH_ISSUER` | yes | Authorization server listed in the metadata |
+| `ELFA_OAUTH_INTROSPECTION_URL` | yes | Where tokens are checked |
+| `ELFA_OAUTH_INTROSPECTION_TOKEN` | yes | Bearer sent to the introspection endpoint |
+| `ELFA_OAUTH_SCOPES` | no | Comma separated scopes to advertise, default `elfa` |
+
+Notes:
+
+- An `x-elfa-api-key` header still works in OAuth mode.
+- `ELFA_API_KEY` is ignored in OAuth mode, so a caller with no credential never runs as the server's own key.
+- Valid tokens are cached for up to a minute, which bounds how long a revoked token keeps working.
+
 ## Safety
 
 `api_status` is the fastest way to tell an auth problem from a credit problem.

package/dist/index.js

@@ -112,15 +112,44 @@ function list(value) {
   if (!value) return [];
   return value.split(",").map((entry) => entry.trim()).filter(Boolean);
 }
+var ConfigError = class extends Error {
+};
+function oauthConfig(env) {
+  const required = {
+    ELFA_MCP_RESOURCE_URL: env.ELFA_MCP_RESOURCE_URL,
+    ELFA_OAUTH_ISSUER: env.ELFA_OAUTH_ISSUER,
+    ELFA_OAUTH_INTROSPECTION_URL: env.ELFA_OAUTH_INTROSPECTION_URL,
+    ELFA_OAUTH_INTROSPECTION_TOKEN: env.ELFA_OAUTH_INTROSPECTION_TOKEN
+  };
+  const missing = Object.entries(required).filter(([, value]) => !value).map(([name]) => name);
+  if (missing.length > 0) {
+    throw new ConfigError(
+      `ELFA_MCP_AUTH=oauth requires ${missing.join(", ")}.`
+    );
+  }
+  return {
+    resource: required.ELFA_MCP_RESOURCE_URL,
+    issuer: required.ELFA_OAUTH_ISSUER,
+    introspectionUrl: required.ELFA_OAUTH_INTROSPECTION_URL,
+    introspectionToken: required.ELFA_OAUTH_INTROSPECTION_TOKEN,
+    scopes: list(env.ELFA_OAUTH_SCOPES).length > 0 ? list(env.ELFA_OAUTH_SCOPES) : ["elfa"]
+  };
+}
 function loadConfig(env = process.env) {
   const transport = env.ELFA_MCP_TRANSPORT === "http" ? "http" : "stdio";
+  const auth = env.ELFA_MCP_AUTH === "oauth" ? "oauth" : "apikey";
+  if (auth === "oauth" && transport !== "http") {
+    throw new ConfigError("ELFA_MCP_AUTH=oauth needs ELFA_MCP_TRANSPORT=http.");
+  }
   return {
     transport,
     port: num(env.ELFA_MCP_PORT, DEFAULT_PORT),
     host: env.ELFA_MCP_HOST || DEFAULT_HOST,
     allowedOrigins: list(env.ELFA_MCP_ALLOWED_ORIGINS),
     allowedHosts: list(env.ELFA_MCP_ALLOWED_HOSTS),
-    apiKey: env.ELFA_API_KEY || void 0,
+    // In oauth mode every request brings its own credential. An environment
+    // key would be handed to any caller that sends none, so it is ignored.
+    apiKey: auth === "oauth" ? void 0 : env.ELFA_API_KEY || void 0,
     baseUrl: env.ELFA_BASE_URL || void 0,
     extraHeaders: headers(env.ELFA_EXTRA_HEADERS),
     timeout: num(env.ELFA_TIMEOUT, DEFAULT_TIMEOUT),
@@ -128,7 +157,9 @@ function loadConfig(env = process.env) {
     maxResponseChars: num(
       env.ELFA_MCP_MAX_RESPONSE_CHARS,
       DEFAULT_MAX_RESPONSE_CHARS
-    )
+    ),
+    auth,
+    oauth: auth === "oauth" ? oauthConfig(env) : void 0
   };
 }
 
@@ -142,7 +173,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 // package.json
 var package_default = {
   name: "@elfa-ai/mcp",
-  version: "4.1.0",
+  version: "4.2.0",
   description: "Model Context Protocol server for the Elfa API - crypto social intelligence and the Auto condition engine",
   license: "MIT",
   author: "Elfa AI",
@@ -1230,6 +1261,111 @@ function createServer(deps) {
   return server;
 }
 
+// src/oauth.ts
+import { createHash } from "crypto";
+var CACHE_TTL_MS = 6e4;
+var CACHE_MAX_ENTRIES = 1e4;
+var INTROSPECTION_TIMEOUT_MS = 5e3;
+var IntrospectionUnavailableError = class extends Error {
+};
+function protectedResourceMetadataPath(resource) {
+  const { pathname } = new URL(resource);
+  const suffix = pathname === "/" ? "" : pathname.replace(/\/+$/, "");
+  return `/.well-known/oauth-protected-resource${suffix}`;
+}
+function protectedResourceMetadataUrl(resource) {
+  const url = new URL(resource);
+  return `${url.origin}${protectedResourceMetadataPath(resource)}`;
+}
+function protectedResourceMetadata(config) {
+  return {
+    resource: config.resource,
+    authorization_servers: [config.issuer],
+    scopes_supported: config.scopes,
+    bearer_methods_supported: ["header"],
+    resource_name: "Elfa",
+    resource_documentation: "https://docs.elfa.ai/mcp"
+  };
+}
+function bearerChallenge(config, error) {
+  const parts = [
+    `resource_metadata="${protectedResourceMetadataUrl(config.resource)}"`,
+    `scope="${config.scopes.join(" ")}"`
+  ];
+  if (error) {
+    parts.unshift(`error="${error.code}"`);
+    parts.push(`error_description="${error.description.replace(/"/g, "'")}"`);
+  }
+  return `Bearer ${parts.join(", ")}`;
+}
+function bearerToken(authorization) {
+  if (!authorization) return void 0;
+  const match = /^Bearer\s+(\S+)\s*$/i.exec(authorization);
+  return match?.[1];
+}
+var TokenVerifier = class {
+  constructor(config, fetchImpl = fetch, now = Date.now) {
+    this.config = config;
+    this.fetchImpl = fetchImpl;
+    this.now = now;
+  }
+  config;
+  fetchImpl;
+  now;
+  cache = /* @__PURE__ */ new Map();
+  /** The API key for a valid token, or undefined when the token is not valid. */
+  async verify(token) {
+    const cacheKey = createHash("sha256").update(token).digest("hex");
+    const cached = this.cache.get(cacheKey);
+    if (cached && cached.expiresAtMs > this.now()) return cached;
+    if (cached) this.cache.delete(cacheKey);
+    const body = await this.introspect(token);
+    if (!body.active || typeof body.elfa_api_key !== "string") return void 0;
+    const audiences = Array.isArray(body.aud) ? body.aud : [body.aud];
+    if (!audiences.includes(this.config.resource)) return void 0;
+    const tokenExpiryMs = typeof body.exp === "number" ? body.exp * 1e3 : this.now() + CACHE_TTL_MS;
+    if (tokenExpiryMs <= this.now()) return void 0;
+    const verified = {
+      apiKey: body.elfa_api_key,
+      expiresAtMs: Math.min(tokenExpiryMs, this.now() + CACHE_TTL_MS)
+    };
+    if (this.cache.size >= CACHE_MAX_ENTRIES) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== void 0) this.cache.delete(oldest);
+    }
+    this.cache.set(cacheKey, verified);
+    return verified;
+  }
+  async introspect(token) {
+    let response;
+    try {
+      response = await this.fetchImpl(this.config.introspectionUrl, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${this.config.introspectionToken}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({ token }),
+        signal: AbortSignal.timeout(INTROSPECTION_TIMEOUT_MS)
+      });
+    } catch (error) {
+      throw new IntrospectionUnavailableError(
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+    if (!response.ok) {
+      throw new IntrospectionUnavailableError(
+        `introspection returned HTTP ${response.status}`
+      );
+    }
+    try {
+      return await response.json();
+    } catch {
+      throw new IntrospectionUnavailableError("introspection returned invalid JSON");
+    }
+  }
+};
+
 // src/http.ts
 var MCP_PATH = "/mcp";
 function header(req, name) {
@@ -1251,8 +1387,10 @@ function defaultAllowedHosts(config) {
   }
   return [...hosts];
 }
-function createHttpApp(config) {
+function createHttpApp(config, options = {}) {
   const app = express();
+  const oauth = config.oauth;
+  const verifier = options.verifier ?? (oauth ? new TokenVerifier(oauth) : void 0);
   app.disable("x-powered-by");
   app.use(express.json({ limit: "4mb" }));
   app.use(
@@ -1267,6 +1405,47 @@ function createHttpApp(config) {
   app.get("/healthz", (_req, res) => {
     res.json({ ok: true });
   });
+  if (oauth) {
+    const sendMetadata = (_req, res) => {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Cache-Control", "public, max-age=300");
+      res.json(protectedResourceMetadata(oauth));
+    };
+    const metadataPath = protectedResourceMetadataPath(oauth.resource);
+    app.get(metadataPath, sendMetadata);
+    if (metadataPath !== "/.well-known/oauth-protected-resource") {
+      app.get("/.well-known/oauth-protected-resource", sendMetadata);
+    }
+  }
+  async function resolveApiKey(req, res) {
+    const headerKey = header(req, "x-elfa-api-key");
+    if (headerKey || !oauth || !verifier) return headerKey ?? null;
+    const token = bearerToken(header(req, "authorization"));
+    if (!token) {
+      res.setHeader("WWW-Authenticate", bearerChallenge(oauth));
+      jsonRpcError(res, 401, "Authorization required. Sign in to Elfa to use this server.");
+      return void 0;
+    }
+    try {
+      const verified = await verifier.verify(token);
+      if (verified) return verified.apiKey;
+    } catch (error) {
+      if (error instanceof IntrospectionUnavailableError) {
+        jsonRpcError(res, 503, "Authorization service unavailable, try again shortly.");
+        return void 0;
+      }
+      throw error;
+    }
+    res.setHeader(
+      "WWW-Authenticate",
+      bearerChallenge(oauth, {
+        code: "invalid_token",
+        description: "The access token is invalid or expired"
+      })
+    );
+    jsonRpcError(res, 401, "Invalid or expired access token.");
+    return void 0;
+  }
   app.post(MCP_PATH, async (req, res) => {
     const origin = header(req, "origin");
     if (origin && config.allowedOrigins.length > 0 && !config.allowedOrigins.includes(origin)) {
@@ -1276,9 +1455,9 @@ function createHttpApp(config) {
     let server;
     let transport;
     try {
-      const deps = buildDeps(config, {
-        apiKey: header(req, "x-elfa-api-key")
-      });
+      const apiKey = await resolveApiKey(req, res);
+      if (apiKey === void 0) return;
+      const deps = buildDeps(config, { apiKey: apiKey ?? void 0 });
       server = createServer(deps);
       transport = new StreamableHTTPServerTransport({
         enableDnsRebindingProtection: true,

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "server": {
     "name": "elfa",
-    "version": "4.1.0",
+    "version": "4.2.0",
     "docs": "https://docs.elfa.ai",
     "spec": "https://docs.elfa.ai/swagger/swagger.json",
     "specScope": "/v2"
@@ -193,11 +193,6 @@
     }
   ],
   "unexposed": [
-    {
-      "operationId": "getMarketEvents-v2",
-      "reason": "restricted",
-      "note": "Available only to select Enterprise customers, and the published operation takes no parameters. Contact sales@elfa.ai for access."
-    },
     {
       "operationId": "chat-stream-v2",
       "reason": "sse",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elfa-ai/mcp",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Model Context Protocol server for the Elfa API - crypto social intelligence and the Auto condition engine",
   "license": "MIT",
   "author": "Elfa AI",