@roarkanalytics/sdk-mcp 4.12.0 → 4.12.2

package/src/code-tool.ts

@@ -205,14 +205,71 @@ const remoteStainlessHandler = async ({
 const DENO_WORKER_SOCKET_SUFFIX = '-deno-http.sock';
 
 /**
- * Adds the worker's Unix socket to the existing `--allow-net` allowlist.
+ * Whether this Deno wants the worker's Unix socket named in `--allow-net`.
  *
- * deno-http-worker generates the socket path itself and passes it to the Deno
- * process, so it can only be read off the spawn arguments. Throws rather than
- * falling back to an unrestricted `--allow-net`, so a change in how the socket is
- * passed fails closed instead of silently widening what the sandbox can reach.
+ * Deno changed its mind about this, and the two behaviors are mutually exclusive:
+ *
+ *   Deno 2.7 and earlier  a Unix socket is a file. Listening on it is covered by
+ *                         --allow-read/--allow-write on its path, and --allow-net
+ *                         parses every entry as `host[:port]`, so a `unix:` entry
+ *                         is a hard parse error: "invalid port in 'unix:/tmp/...'".
+ *   Deno 2.9 and later    listening additionally requires --allow-net=unix:<path>,
+ *                         and without it the worker dies with NotCapable.
+ *
+ * There is therefore no single flag string that works on both, and this package is
+ * published for users to run against whatever Deno they have. So ask the binary
+ * instead of guessing from a version string: run a no-op script with the flag and
+ * see whether it is accepted. The probe binds nothing (the script is `0`), and the
+ * result is cached per executable because the answer cannot change under us.
+ */
+const unixAllowNetSupport = new Map<string, boolean>();
+
+export const denoAcceptsUnixAllowNet = (
+  denoPath: string,
+  probe: (command: string, args: string[]) => { status: number | null },
+): boolean => {
+  const cached = unixAllowNetSupport.get(denoPath);
+  if (cached !== undefined) return cached;
+
+  // A path that is never created: --allow-net is parsed before the script runs, which
+  // is the only thing being tested here.
+  const { status } = probe(denoPath, [
+    'run',
+    '--allow-net=unix:/nonexistent-roark-deno-capability-probe.sock',
+    'data:text/javascript,0',
+  ]);
+
+  // A null status means the probe never ran at all - the binary could not be spawned,
+  // or it was killed by the timeout or a signal - as opposed to running and rejecting
+  // the flag, which is an exit code. Answer conservatively for this call but do NOT
+  // cache it: a single transient failure would otherwise pin the answer to
+  // "unsupported" for the life of the process, and on Deno 2.9+ that means every
+  // later execute call dies with NotCapable.
+  if (status === null) return false;
+
+  const accepted = status === 0;
+  unixAllowNetSupport.set(denoPath, accepted);
+  return accepted;
+};
+
+/**
+ * Grants the Deno worker its own Unix socket, and nothing else.
+ *
+ * deno-http-worker generates the socket path while it builds the spawn arguments, so
+ * this is the first point at which it can be read at all. Two things happen here:
+ *
+ * - The socket is added to `--allow-net` only on the Deno versions that require it
+ *   (see denoAcceptsUnixAllowNet). Adding it unconditionally is what broke the
+ *   published image, whose Deno rejected the syntax and exited before serving
+ *   anything, surfacing only as the far vaguer "Deno exited before being ready".
+ * - The grant deno-http-worker makes itself, `--allow-read`/`--allow-write` on the
+ *   socket, is asserted rather than assumed, so a future version that stops making
+ *   it fails here instead of at runtime.
+ *
+ * Throws rather than falling back to an unrestricted `--allow-net`, so anything
+ * unexpected fails closed instead of silently widening what the sandbox can reach.
  */
-export const scopeAllowNetToWorkerSocket = (spawnArgs: string[]): string[] => {
+export const scopeAllowNetToWorkerSocket = (spawnArgs: string[], addSocketToAllowNet: boolean): string[] => {
   // Skip flags: deno-http-worker also appends the socket to `--allow-read`/`--allow-write`,
   // so match only the bare path it passes through to the bootstrap script.
   const socketPath = spawnArgs.find((arg) => !arg.startsWith('-') && arg.endsWith(DENO_WORKER_SOCKET_SUFFIX));
@@ -221,6 +278,19 @@ export const scopeAllowNetToWorkerSocket = (spawnArgs: string[]): string[] => {
       'Could not find the Deno worker socket path in its spawn arguments, so network access could not be scoped to it.',
     );
   }
+
+  const grants = (flag: string) =>
+    spawnArgs.some((arg) => arg.startsWith(flag) && arg.slice(flag.length).split(',').includes(socketPath));
+
+  const missing = ['--allow-read=', '--allow-write='].filter((flag) => !grants(flag));
+  if (missing.length > 0) {
+    throw new Error(
+      `deno-http-worker did not grant the worker socket ${socketPath} on ${missing.join(' or ')}, ` +
+        'so the Deno sandbox would not be able to serve requests.',
+    );
+  }
+
+  if (!addSocketToAllowNet) return spawnArgs;
   return spawnArgs.map((arg) => (arg.startsWith('--allow-net=') ? `${arg},unix:${socketPath}` : arg));
 };
 
@@ -248,7 +318,7 @@ const localDenoHandler = async ({
   const packageNodeModulesPath = path.resolve(packageRoot, 'node_modules');
 
   // Check if deno is in PATH
-  const { execSync, spawn } = await import('node:child_process');
+  const { execSync, spawn, spawnSync } = await import('node:child_process');
   try {
     execSync('command -v deno', { stdio: 'ignore' });
     denoPath = 'deno';
@@ -286,24 +356,36 @@ const localDenoHandler = async ({
 
   const allowRead = allowReadPaths.join(',');
 
+  const addSocketToAllowNet = denoAcceptsUnixAllowNet(denoPath, (command, probeArgs) =>
+    spawnSync(command, probeArgs, {
+      stdio: 'ignore',
+      // spawnSync blocks, so an unbounded probe would hang the server rather than
+      // fail one call. Deno's first run can populate its cache directory, hence
+      // seconds rather than milliseconds, and DENO_NO_UPDATE_CHECK keeps a version
+      // check off that path.
+      timeout: 10_000,
+      env: { ...process.env, DENO_NO_UPDATE_CHECK: '1' },
+    }),
+  );
+
   const worker = await newDenoHTTPWorker(url.pathToFileURL(workerPath), {
     denoExecutable: denoPath,
     runFlags: [
       `--node-modules-dir=manual`,
       `--allow-read=${allowRead}`,
       // Only the Roark API is reachable from the sandbox. The worker's Unix socket
-      // is added to this same allowlist by scopeAllowNetToWorkerSocket below.
+      // is added to this same allowlist by scopeAllowNetToWorkerSocket below, on the
+      // Deno versions that require it.
       `--allow-net=${baseURLHostname}`,
       // Allow environment variables because instantiating the client will try to read from them,
       // even though they are not set.
       '--allow-env',
     ],
     // deno-http-worker picks the worker's Unix socket path while it builds the spawn
-    // arguments, so it is not known when runFlags are constructed above. Deno gates
-    // listening on a Unix socket behind --allow-net, so intercept the spawn to grant
-    // that one socket rather than opening up network access to every host.
+    // arguments, so it is not known when runFlags are constructed above. Intercept the
+    // spawn to grant that one socket rather than opening up network access to every host.
     spawnFunc: (command, spawnArgs, spawnOptions) =>
-      spawn(command, scopeAllowNetToWorkerSocket(spawnArgs), spawnOptions),
+      spawn(command, scopeAllowNetToWorkerSocket(spawnArgs, addSocketToAllowNet), spawnOptions),
     printOutput: true,
     spawnOptions: {
       cwd: path.dirname(workerPath),

package/src/http.ts

@@ -15,6 +15,8 @@ import {
   ORIGIN_CONNECTOR,
   protectedResourceMetadata,
   requireBearer,
+  requireLiveBearer,
+  resolveApiBaseUrl,
   UnauthorizedError,
 } from './oauth';
 import { initMcpServer, newMcpServer } from './server';
@@ -52,7 +54,20 @@ const newServer = async ({
   // not be able to make us do that.
   let authOptions: Partial<ClientOptions>;
   if (mcpOptions.oauth) {
-    authOptions = requireBearer(req, mcpOptions.oauth, connectorFrom(req));
+    const connector = connectorFrom(req);
+    const authorized = requireBearer(req, mcpOptions.oauth, connector);
+    // Presence is not validity. Ask customer-api whether the token is still live, so a revoked or
+    // expired one is answered with 401 + WWW-Authenticate here - the signal a client needs to
+    // re-run the OAuth flow - rather than completing the handshake and failing later inside a
+    // tool result, where nothing is listening for it.
+    //
+    // The base URL is resolved the way the SDK resolves it, NOT defaulted to prod: this server is
+    // launched without `clientOptions`, so on any stage but prod a prod default would check the
+    // token against a server that never issued it and refuse every request.
+    await requireLiveBearer(authorized.bearerToken, mcpOptions.oauth, connector, {
+      baseURL: resolveApiBaseUrl(clientOptions),
+    });
+    authOptions = authorized;
   } else {
     authOptions = parseClientAuthHeaders(req, false);
   }

package/src/oauth.ts

@@ -9,8 +9,10 @@
 // rotated by the client's refresh token), so it is forwarded to customer-api as
 // the SDK bearer unchanged: customer-api validates it on every call.
 
+import { createHash } from 'node:crypto';
 import { IncomingMessage } from 'node:http';
 import { ClientOptions } from '@roarkanalytics/sdk';
+import { readEnv } from './util';
 
 export type OAuthConfig = {
   /** Authorization server issuer, e.g. https://mcp-oauth.api.roark.ai */
@@ -121,7 +123,7 @@ export const requireBearer = (
   req: IncomingMessage,
   config: OAuthConfig,
   connector: Connector = ORIGIN_CONNECTOR,
-): Partial<ClientOptions> => {
+): Partial<ClientOptions> & { bearerToken: string } => {
   const token = extractBearer(req);
   if (!token) {
     throw new UnauthorizedError('Missing bearer token', bearerChallenge(config, connector));
@@ -129,9 +131,176 @@ export const requireBearer = (
   // Assigned rather than conditionally spread: a spread of `cond && { project }` is not checked
   // against `ClientOptions`, so on an SDK without the option the pin would compile and then
   // silently vanish. This way the dependency is enforced by the build.
-  const options: Partial<ClientOptions> = { bearerToken: token };
+  const options: Partial<ClientOptions> & { bearerToken: string } = { bearerToken: token };
   if (connector.kind === 'project') {
     options.project = connector.projectId;
   }
   return options;
 };
+
+/**
+ * What customer-api says about a bearer: `unknown` means it could not be asked, not that the
+ * token is fine.
+ */
+export type BearerVerdict = 'valid' | 'invalid' | 'unknown';
+
+/** The SDK's own default, for when neither an option nor the environment names one. */
+export const DEFAULT_API_BASE_URL = 'https://api.roark.ai';
+
+/**
+ * The base URL the SDK will actually call, resolved exactly the way the SDK resolves it:
+ * explicit option, then `ROARK_BASE_URL`, then the default.
+ *
+ * This has to agree with the SDK or the liveness check asks the wrong host. `launchStreamableHTTPServer`
+ * passes no `clientOptions` at all, so for the deployed server the answer always comes from the
+ * environment: a hardcoded prod default would send every check to prod while data calls went to
+ * whatever `ROARK_BASE_URL` names. On any stage but prod that turns a valid token into a 401 from
+ * a server it was never issued for, and this file would then refuse every request - a dead
+ * connector, which is strictly worse than the bug it is here to fix.
+ */
+export const resolveApiBaseUrl = (clientOptions: Pick<ClientOptions, 'baseURL'> = {}): string =>
+  clientOptions.baseURL ?? readEnv('ROARK_BASE_URL') ?? DEFAULT_API_BASE_URL;
+
+/**
+ * How long a verdict is reused. `newServer` runs per POST, not per session, so an uncached check
+ * would add a round trip to every single MCP request. The window is what a revoked token buys:
+ * it can still complete a handshake and read the tool list for up to this long. It cannot read
+ * anything, because every data path carries the same token to customer-api and is refused there
+ * immediately.
+ */
+const BEARER_CACHE_TTL_MS = 60_000;
+
+/**
+ * An unreachable customer-api is handled by the catch below, but a customer-api that accepts the
+ * connection and then never answers is not: without a deadline every MCP request would hang on
+ * it, which is worse than the failure this check exists to report. A hang becomes `unknown` like
+ * any other transport failure.
+ */
+const BEARER_CHECK_TIMEOUT_MS = 3_000;
+
+/**
+ * Bounded so that spraying invented tokens cannot grow the process's memory. Keys are hashes,
+ * not the tokens themselves: these are live credentials and there is no reason to keep a second
+ * copy of them in a long-lived map.
+ */
+const BEARER_CACHE_MAX = 1_000;
+
+const bearerVerdicts = new Map<string, { verdict: 'valid' | 'invalid'; expiresAt: number }>();
+
+/**
+ * Checks already in flight, so concurrent requests bearing the same uncached token make one call
+ * rather than one each. That is the common shape right after a verdict expires, and whenever a
+ * client opens several requests at once.
+ */
+const inFlightChecks = new Map<string, Promise<BearerVerdict>>();
+
+/** Test seam. */
+export const clearBearerVerdictCache = (): void => {
+  bearerVerdicts.clear();
+  inFlightChecks.clear();
+};
+
+const hashToken = (token: string): string => createHash('sha256').update(token).digest('hex');
+
+const rememberVerdict = (key: string, verdict: 'valid' | 'invalid', expiresAt: number): void => {
+  // Evict the oldest entry rather than clearing the map. A `clear()` would let anyone spraying
+  // invented tokens flush every valid verdict too, making legitimate callers pay a round trip
+  // each and handing customer-api the extra work. Map iterates in insertion order, so the first
+  // key is the oldest.
+  if (bearerVerdicts.size >= BEARER_CACHE_MAX) {
+    const oldest = bearerVerdicts.keys().next();
+    if (!oldest.done) bearerVerdicts.delete(oldest.value);
+  }
+  bearerVerdicts.set(key, { verdict, expiresAt });
+};
+
+export interface VerifyBearerDeps {
+  /** customer-api base URL. Use {@link resolveApiBaseUrl} rather than passing a literal. */
+  baseURL: string;
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+  ttlMs?: number;
+  timeoutMs?: number;
+}
+
+/**
+ * Asks customer-api whether a bearer is still live, via the `/v1/me` endpoint it already exposes
+ * for exactly this ("who is this credential"), and caches the answer briefly.
+ *
+ * Only a 401 counts as invalid. A 403 means the token authenticated and then failed a permission
+ * check, which is a live token; treating it as invalid would tell a client to re-authorize when
+ * re-authorizing cannot help. Anything else - a 5xx, a timeout, a DNS failure - is `unknown`.
+ */
+export const verifyBearer = async (token: string, deps: VerifyBearerDeps): Promise<BearerVerdict> => {
+  const {
+    baseURL,
+    fetchImpl = fetch,
+    now = Date.now,
+    ttlMs = BEARER_CACHE_TTL_MS,
+    timeoutMs = BEARER_CHECK_TIMEOUT_MS,
+  } = deps;
+  const key = hashToken(token);
+
+  const cached = bearerVerdicts.get(key);
+  if (cached && cached.expiresAt > now()) return cached.verdict;
+
+  const alreadyRunning = inFlightChecks.get(key);
+  if (alreadyRunning) return alreadyRunning;
+
+  const check = (async (): Promise<BearerVerdict> => {
+    let response: Response;
+    try {
+      response = await fetchImpl(`${stripSlash(baseURL)}/v1/me`, {
+        method: 'GET',
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch {
+      return 'unknown';
+    }
+
+    const verdict: BearerVerdict =
+      response.status === 401 ? 'invalid'
+      : response.ok ? 'valid'
+      : 'unknown';
+    // An `unknown` is never cached: a blip would otherwise pin the answer for the whole TTL.
+    if (verdict !== 'unknown') rememberVerdict(key, verdict, now() + ttlMs);
+    return verdict;
+  })();
+
+  inFlightChecks.set(key, check);
+  try {
+    return await check;
+  } finally {
+    inFlightChecks.delete(key);
+  }
+};
+
+/**
+ * Rejects a bearer customer-api has already disowned, with the 401 + WWW-Authenticate that tells
+ * an MCP client to re-run the OAuth flow.
+ *
+ * Without this the resource server only checked that a token was PRESENT. A revoked, expired or
+ * entirely invented token completed `initialize` and `tools/list`, and the caller learned nothing
+ * until a tool call failed with an opaque 401 in its result text. No data was reachable - every
+ * data path revalidates at customer-api - but a client that never sees a 401 from the resource
+ * server has no reason to refresh, which for a 24h token means a connector that looks connected
+ * and silently cannot work.
+ *
+ * `unknown` is allowed through deliberately. Failing closed would turn a customer-api blip into a
+ * dead connector for everyone, and it would buy no confidentiality: the token still has to pass
+ * customer-api on the very next call that touches data.
+ */
+export const requireLiveBearer = async (
+  token: string,
+  config: OAuthConfig,
+  connector: Connector,
+  deps: VerifyBearerDeps,
+): Promise<void> => {
+  const verdict = await verifyBearer(token, deps);
+  if (verdict !== 'invalid') return;
+  throw new UnauthorizedError(
+    'The access token is expired or has been revoked',
+    bearerChallenge(config, connector, 'invalid_token', 'The access token is expired or has been revoked'),
+  );
+};

package/src/server.ts

@@ -28,7 +28,7 @@ export const newMcpServer = async ({
   new McpServer(
     {
       name: 'roarkanalytics_sdk_api',
-      version: '4.12.0', // x-release-please-version
+      version: '4.12.2', // x-release-please-version
     },
     {
       instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }),