@stage-labs/metro 0.1.0-beta.13 → 0.1.0-beta.131

package/runtime/node_modules/@metro-labs/daemon/src/connectors/verify.ts

@@ -0,0 +1,332 @@
+import { errMsg, log } from '@metro-labs/core/log';
+import { whyUnreachable } from './reach.js';
+import {
+  ConnectorNotMcp,
+  ConnectorUnauthorized,
+  refused,
+  safeIconSrc,
+} from './url.js';
+import { toToolList, type ToolInfo } from './tools.js';
+
+export {
+  ConnectorUnauthorized,
+  ConnectorVerifyError,
+  connectorUrlText,
+  parseConnectorUrl,
+} from './url.js';
+import { isRecord } from '@metro-labs/core/is-record';
+
+export interface OAuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+}
+
+export interface OAuthAuth extends OAuthTokens {
+  kind: 'oauth';
+  issuer: string;
+  tokenEndpoint: string;
+  clientId: string;
+  clientSecret?: string;
+  scope?: string;
+}
+
+export type ConnectorAuth =
+  | { kind: 'none' }
+  | { kind: 'header'; name: string; value: string }
+  | OAuthAuth;
+
+export interface VerifiedServer {
+  server: string;
+  version: string;
+  protocol: string;
+  icon: string;
+  tools: number;
+  catalog: ToolInfo[];
+}
+
+export interface VerifiedRecord extends VerifiedServer {
+  at: string;
+}
+
+const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18'] as const;
+const MAX_TOOL_PAGES = 10;
+
+function notMcp(url: URL): ConnectorNotMcp {
+  return new ConnectorNotMcp(
+    `${url.hostname} answered, but it does not speak MCP.`,
+    400,
+  );
+}
+const PROBE_TIMEOUT_MS = 10_000;
+const ACCEPT = 'application/json, text/event-stream';
+
+async function discard(res: Response): Promise<void> {
+  await res.body?.cancel().catch((err: unknown) => {
+    log.debug(
+      { err: errMsg(err) },
+      'connector-verify: could not discard a response body',
+    );
+  });
+}
+
+function authHeaders(auth: ConnectorAuth): Record<string, string> {
+  if (auth.kind === 'header') return { [auth.name]: auth.value };
+  if (auth.kind === 'oauth')
+    return { authorization: `Bearer ${auth.accessToken}` };
+  return {};
+}
+
+async function frame(
+  url: URL,
+  auth: ConnectorAuth,
+  extra: Record<string, string>,
+  body: unknown,
+  signal: AbortSignal,
+): Promise<Response> {
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      redirect: 'manual',
+      signal,
+      headers: {
+        'content-type': 'application/json',
+        accept: ACCEPT,
+        ...authHeaders(auth),
+        ...extra,
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    throw refused(`Metro could not reach ${url.hostname}: ${whyUnreachable(err)}`);
+  }
+  if (res.status >= 300 && res.status < 400) {
+    await discard(res);
+    throw refused('that url redirects — use the url it redirects to');
+  }
+  return res;
+}
+
+function sseData(body: string): string {
+  for (const line of body.replace(/\r\n/g, '\n').split('\n'))
+    if (line.startsWith('data:')) return line.slice(5).trim();
+  return '';
+}
+
+async function payloadOf(res: Response): Promise<string> {
+  const contentType = res.headers.get('content-type') ?? '';
+  const text = await res.text().catch(() => '');
+  return contentType.includes('text/event-stream') ? sseData(text) : text;
+}
+
+async function resultOrNull(
+  res: Response,
+): Promise<Record<string, unknown> | null> {
+  const payload = await payloadOf(res);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed) || !isRecord(parsed.result)) return null;
+  return parsed.result;
+}
+
+function initializeBody(version: string): unknown {
+  return {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: version,
+      capabilities: {},
+      clientInfo: { name: 'metro', version: '0.1.0' },
+    },
+  };
+}
+
+function iconOf(info: Record<string, unknown>): string {
+  const icons = info.icons;
+  if (!Array.isArray(icons)) return '';
+  for (const entry of icons) {
+    if (!isRecord(entry)) continue;
+    const src = safeIconSrc(entry.src);
+    if (src !== '') return src;
+  }
+  return '';
+}
+
+function serverFrom(url: URL, result: Record<string, unknown>): VerifiedServer {
+  const protocol = result.protocolVersion;
+  if (typeof protocol !== 'string') throw notMcp(url);
+  const info = isRecord(result.serverInfo) ? result.serverInfo : {};
+  const title = typeof info.title === 'string' ? info.title : '';
+  return {
+    server:
+      title !== ''
+        ? title
+        : typeof info.name === 'string'
+          ? info.name
+          : url.hostname,
+    version: typeof info.version === 'string' ? info.version : '',
+    protocol,
+    icon: iconOf(info),
+    tools: 0,
+    catalog: [],
+  };
+}
+
+async function initialize(
+  url: URL,
+  auth: ConnectorAuth,
+  signal: AbortSignal,
+  version: string,
+): Promise<{ session: string | null; server: VerifiedServer }> {
+  const res = await frame(url, auth, {}, initializeBody(version), signal);
+  if (res.status === 401 || res.status === 403) {
+    await discard(res);
+    throw new ConnectorUnauthorized(
+      auth.kind === 'none'
+        ? `${url.hostname} requires authorization.`
+        : `${url.hostname} rejected that credential.`,
+      400,
+    );
+  }
+  if (res.status === 404 || res.status === 405) {
+    await discard(res);
+    throw refused(
+      `${url.hostname} did not accept an MCP initialize over HTTP POST. ` +
+        'If it is a legacy SSE server, Metro cannot verify it yet.',
+    );
+  }
+  if (!res.ok) {
+    await discard(res);
+    throw notMcp(url);
+  }
+  const result = await resultOrNull(res);
+  if (result === null) throw notMcp(url);
+  return {
+    session: res.headers.get('mcp-session-id'),
+    server: serverFrom(url, result),
+  };
+}
+
+function sessionHeaders(
+  session: string | null,
+  version: string,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    'mcp-protocol-version': version,
+  };
+  if (session !== null && session !== '') headers['mcp-session-id'] = session;
+  return headers;
+}
+
+async function announce(
+  url: URL,
+  auth: ConnectorAuth,
+  headers: Record<string, string>,
+  signal: AbortSignal,
+): Promise<void> {
+  const res = await frame(
+    url,
+    auth,
+    headers,
+    { jsonrpc: '2.0', method: 'notifications/initialized' },
+    signal,
+  );
+  await discard(res);
+}
+
+async function toolPage(
+  url: URL,
+  auth: ConnectorAuth,
+  headers: Record<string, string>,
+  signal: AbortSignal,
+  cursor: string,
+): Promise<Record<string, unknown> | null> {
+  const params = cursor === '' ? {} : { cursor };
+  const res = await frame(
+    url,
+    auth,
+    headers,
+    { jsonrpc: '2.0', id: 2, method: 'tools/list', params },
+    signal,
+  );
+  if (!res.ok) {
+    await discard(res);
+    return null;
+  }
+  return resultOrNull(res);
+}
+
+async function listTools(
+  url: URL,
+  auth: ConnectorAuth,
+  headers: Record<string, string>,
+  signal: AbortSignal,
+): Promise<ToolInfo[]> {
+  const tools: ToolInfo[] = [];
+  let cursor = '';
+  for (let page = 0; page < MAX_TOOL_PAGES; page += 1) {
+    const result = await toolPage(url, auth, headers, signal, cursor);
+    if (result === null) break;
+    tools.push(...toToolList(result.tools));
+    const next = result.nextCursor;
+    if (typeof next !== 'string' || next === '' || next === cursor) break;
+    cursor = next;
+  }
+  return tools;
+}
+
+async function terminate(
+  url: URL,
+  auth: ConnectorAuth,
+  headers: Record<string, string>,
+  signal: AbortSignal,
+): Promise<void> {
+  const res = await fetch(url, {
+    method: 'DELETE',
+    redirect: 'manual',
+    signal,
+    headers: { ...authHeaders(auth), ...headers },
+  });
+  await discard(res);
+}
+
+async function probeWith(
+  url: URL,
+  auth: ConnectorAuth,
+  version: string,
+): Promise<VerifiedServer> {
+  const signal = AbortSignal.timeout(PROBE_TIMEOUT_MS);
+  const { session, server } = await initialize(url, auth, signal, version);
+  const headers = sessionHeaders(session, server.protocol);
+  await announce(url, auth, headers, signal);
+  const catalog = await listTools(url, auth, headers, signal);
+  await terminate(url, auth, headers, signal).catch((err: unknown) => {
+    log.debug(
+      { host: url.hostname, err: errMsg(err) },
+      'connector-verify: the remote declined to end the session',
+    );
+  });
+  return { ...server, tools: catalog.length, catalog };
+}
+
+export async function verifyRemoteMcp(
+  url: URL,
+  auth: ConnectorAuth,
+): Promise<VerifiedServer> {
+  let last: unknown;
+  for (const version of PROTOCOL_VERSIONS) {
+    try {
+      return await probeWith(url, auth, version);
+    } catch (err) {
+      if (!(err instanceof ConnectorNotMcp)) throw err;
+      last = err;
+    }
+  }
+  throw last;
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/watch.ts

@@ -0,0 +1,54 @@
+import { watch, type FSWatcher } from 'node:fs';
+import { errMsg, log } from '@metro-labs/core/log';
+
+const DEBOUNCE_MS = 300;
+const FILE = 'connectors.json';
+
+export class ConnectorWatch {
+  private watcher: FSWatcher | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private readonly dir: string,
+    private readonly onChange: () => void,
+  ) {}
+
+  start(): void {
+    try {
+      this.watcher = watch(this.dir, (_event, file) => {
+        if (file === null || file === FILE) this.schedule();
+      });
+      this.watcher.on('error', (err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'connectors: watcher failed; the plugin list refreshes at the next start');
+      });
+      this.watcher.unref();
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'connectors: could not watch the agents dir');
+    }
+    this.fire();
+  }
+
+  stop(): void {
+    this.watcher?.close();
+    this.watcher = null;
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = null;
+  }
+
+  private schedule(): void {
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.fire();
+    }, DEBOUNCE_MS);
+    this.timer.unref();
+  }
+
+  private fire(): void {
+    try {
+      this.onChange();
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'connectors: change handler failed');
+    }
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/files/attach-grant.ts

@@ -0,0 +1,99 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { ID_RE } from '@metro-labs/core/ids';
+import { readFileSync } from 'node:fs';
+import { resolveCachedAttachment } from '@metro-labs/core/stations/attachments';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+
+const GRANT_SUFFIX = '.grant';
+
+export interface AttachmentGrant {
+  token: string;
+  agentId: string;
+  mintedAt: number;
+}
+
+function newAttachmentToken(prefix = 'at'): string {
+  return `${prefix}_${randomBytes(32).toString('base64url')}`;
+}
+
+function parseGrant(raw: string): AttachmentGrant | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== 'object' || parsed === null) return undefined;
+  const { token, agentId, mintedAt } = parsed as Record<string, unknown>;
+  if (typeof token !== 'string' || token === '') return undefined;
+  if (typeof agentId !== 'string' || !ID_RE.test(agentId)) return undefined;
+  return {
+    token,
+    agentId,
+    mintedAt: typeof mintedAt === 'number' ? mintedAt : 0,
+  };
+}
+
+function readGrant(path: string): AttachmentGrant | undefined {
+  try {
+    return parseGrant(readFileSync(`${path}${GRANT_SUFFIX}`, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+export function issueGrant(
+  path: string,
+  agentId: string,
+  prefix?: string,
+): string {
+  const existing = readGrant(path);
+  if (existing?.agentId === agentId) return existing.token;
+  const grant: AttachmentGrant = {
+    token: newAttachmentToken(prefix),
+    agentId,
+    mintedAt: Date.now(),
+  };
+  writeSecure(`${path}${GRANT_SUFFIX}`, `${JSON.stringify(grant)}\n`);
+  return grant.token;
+}
+
+function sameToken(presented: string, stored: string): boolean {
+  const a = Buffer.from(presented, 'utf8');
+  const b = Buffer.from(stored, 'utf8');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+export function grantAllowsPath(
+  path: string,
+  owner: string,
+  presented: string,
+): boolean {
+  if (presented === '') return false;
+  const grant = readGrant(path);
+  if (grant === undefined) return false;
+  if (grant.agentId !== owner) return false;
+  return sameToken(presented, grant.token);
+}
+
+export function readAttachmentGrant(name: string): AttachmentGrant | undefined {
+  const path = resolveCachedAttachment(name);
+  return path === null ? undefined : readGrant(path);
+}
+
+export function issueAttachmentGrant(
+  name: string,
+  agentId: string,
+): string | undefined {
+  const path = resolveCachedAttachment(name);
+  return path === null ? undefined : issueGrant(path, agentId);
+}
+
+export function grantAllows(
+  name: string,
+  owner: string,
+  presented: string,
+): boolean {
+  const path = resolveCachedAttachment(name);
+  return path === null ? false : grantAllowsPath(path, owner, presented);
+}

package/runtime/node_modules/@metro-labs/daemon/src/files/attach-owner.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { ID_RE } from '@metro-labs/core/ids';
+import { resolveCachedAttachment } from '@metro-labs/core/stations/attachments';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+
+const OWNER_SUFFIX = '.owner';
+
+export function recordOwner(path: string, agentId: string): void {
+  writeSecure(`${path}${OWNER_SUFFIX}`, `${agentId}\n`);
+}
+
+export function ownerOf(path: string): string | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(`${path}${OWNER_SUFFIX}`, 'utf8');
+  } catch {
+    return undefined;
+  }
+  const agentId = raw.trim();
+  return ID_RE.test(agentId) ? agentId : undefined;
+}
+
+export function recordAttachmentOwner(name: string, agentId: string): void {
+  const path = resolveCachedAttachment(name);
+  if (path === null) return;
+  recordOwner(path, agentId);
+}
+
+export function attachmentOwner(name: string): string | undefined {
+  const path = resolveCachedAttachment(name);
+  return path === null ? undefined : ownerOf(path);
+}

package/runtime/node_modules/@metro-labs/daemon/src/files/attach-serve.ts

@@ -0,0 +1,121 @@
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  guessMime,
+  resolveCachedAttachment,
+} from '@metro-labs/core/stations/attachments';
+import {
+  allowedAgents,
+  authenticate,
+  extractToken,
+} from '../mcp/request-identity.js';
+import { attachmentOwner, recordAttachmentOwner } from './attach-owner.js';
+import { grantAllows, issueAttachmentGrant } from './attach-grant.js';
+import { errMsg, log } from '@metro-labs/core/log';
+import { currentTunnelUrl, webhookPort } from '../net/tunnel.js';
+
+function authorized(req: IncomingMessage, name: string): boolean {
+  const owner = attachmentOwner(name);
+  if (owner === undefined) return false;
+  if (grantAllows(name, owner, extractToken(req) ?? '')) return true;
+  return allowedAgents(authenticate(req) ?? undefined).has(
+    owner,
+  );
+}
+
+export function publicBaseUrl(): string | null {
+  const env = process.env.METRO_PUBLIC_URL?.trim();
+  if (env) return env.replace(/\/+$/, '');
+  return currentTunnelUrl();
+}
+
+export const loopbackBase = (): string => `http://127.0.0.1:${String(webhookPort())}`;
+
+export const publicBaseOrDefault = (): string => publicBaseUrl() ?? loopbackBase();
+
+export function attachmentUrl(
+  pathOrName: string,
+  agentId: string,
+): string | null {
+  const base = publicBaseUrl() ?? loopbackBase();
+  if (!base) return null;
+  const name = pathOrName.split('/').pop();
+  if (!name || !resolveCachedAttachment(name)) return null;
+  recordAttachmentOwner(name, agentId);
+  const token = issueAttachmentGrant(name, agentId);
+  if (token === undefined) return null;
+  return `${base}/attach/${encodeURIComponent(name)}?token=${encodeURIComponent(token)}`;
+}
+
+export function attachmentEventUrl(
+  payload: Record<string, unknown>,
+  agentId: string,
+): string | null {
+  if (payload.contentType !== 'attachmentSaved') return null;
+  if (typeof payload.url === 'string' && payload.url.length > 0) return null;
+  const p = payload.attachmentPath ?? payload.localPath;
+  return typeof p === 'string' ? attachmentUrl(p, agentId) : null;
+}
+
+async function serveFile(
+  res: ServerResponse,
+  method: string,
+  name: string,
+): Promise<void> {
+  const path = resolveCachedAttachment(name);
+  if (!path) {
+    res.writeHead(404).end();
+    return;
+  }
+  let size: number;
+  try {
+    size = (await stat(path)).size;
+  } catch {
+    res.writeHead(404).end();
+    return;
+  }
+  res.writeHead(200, {
+    'content-type': guessMime(path),
+    'content-length': String(size),
+    'cache-control': 'private, max-age=86400',
+  });
+  if (method === 'HEAD') {
+    res.end();
+    return;
+  }
+  const stream = createReadStream(path);
+  stream.on('error', (err) => {
+    log.warn({ err: errMsg(err) }, 'attach: read stream error');
+    res.end();
+  });
+  stream.pipe(res);
+}
+
+export function handleAttachRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+): boolean {
+  const [rawPath] = (req.url ?? '').split('?', 2);
+  const m = /^\/attach\/([^/]+)$/.exec(rawPath ?? '');
+  if (!m) return false;
+  const method = req.method ?? 'GET';
+  if (method !== 'GET' && method !== 'HEAD') {
+    res.writeHead(405).end();
+    return true;
+  }
+  const name = decodeURIComponent(m[1] ?? '');
+  if (resolveCachedAttachment(name) === null) {
+    res.writeHead(404).end();
+    return true;
+  }
+  if (!authorized(req, name)) {
+    res.writeHead(401).end();
+    return true;
+  }
+  serveFile(res, method, name).catch((err: unknown) => {
+    log.warn({ err: errMsg(err) }, 'attach: serve error');
+    if (!res.headersSent) res.writeHead(500).end();
+  });
+  return true;
+}