@stage-labs/metro 0.1.0-beta.4 → 0.1.0-beta.41

package/runtime/node_modules/@metro-labs/mcp/src/daemon/api-http.ts

@@ -0,0 +1,153 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ApiError } from './api-error.js';
+import { errMsg, log } from './log.js';
+import {
+  verifyAgentToken,
+  verifyRunToken,
+  verifySession,
+  type AgentClaims,
+  type RunClaims,
+} from './session.js';
+import { extractToken } from '../mcp/request-identity.js';
+
+const BODY_MAX = 4 * 1024;
+const DRAIN_MAX = 2 * BODY_MAX;
+
+export interface ApiSession {
+  subject: string;
+}
+
+export function cors(req: IncomingMessage): Record<string, string> {
+  return {
+    'access-control-allow-origin': req.headers.origin ?? '*',
+    'access-control-allow-methods': 'GET, POST, PUT, DELETE, OPTIONS',
+    'access-control-allow-headers': 'Authorization, Content-Type',
+    'access-control-allow-private-network': 'true',
+    'access-control-max-age': '86400',
+    vary: 'Origin',
+  };
+}
+
+export function sendJson(
+  req: IncomingMessage,
+  res: ServerResponse,
+  status: number,
+  body: unknown,
+): void {
+  res.writeHead(status, {
+    'content-type': 'application/json',
+    'cache-control': 'no-store',
+    ...cors(req),
+  });
+  res.end(JSON.stringify(body));
+}
+
+export function apiSession(req: IncomingMessage): ApiSession | null {
+  const secret = process.env.METRO_SESSION_SECRET?.trim() ?? '';
+  if (secret === '') return null;
+  const token = extractToken(req) ?? '';
+  if (token === '') return null;
+  try {
+    const { subject } = verifySession(token, secret);
+    return { subject: subject.toLowerCase() };
+  } catch {
+    return null;
+  }
+}
+
+export function runIdentity(req: IncomingMessage): RunClaims | null {
+  const secret = process.env.METRO_SESSION_SECRET?.trim() ?? '';
+  if (secret === '') return null;
+  const token = extractToken(req) ?? '';
+  if (token === '') return null;
+  try {
+    const claims = verifyRunToken(token, secret);
+    return { ...claims, subject: claims.subject.toLowerCase() };
+  } catch {
+    return null;
+  }
+}
+
+export interface AgentIdentity extends AgentClaims {
+  runtimeId?: string;
+}
+
+export function agentIdentity(req: IncomingMessage): AgentIdentity | null {
+  const secret = process.env.METRO_SESSION_SECRET?.trim() ?? '';
+  if (secret === '') return null;
+  const token = extractToken(req) ?? '';
+  if (token === '') return null;
+  try {
+    const { subject, agentId } = verifyAgentToken(token, secret);
+    return { subject: subject.toLowerCase(), agentId };
+  } catch {
+    const run = runIdentity(req);
+    if (run === null) return null;
+    return { subject: run.subject, agentId: run.agentId, runtimeId: run.runtimeId };
+  }
+}
+
+export type Fence = (runtimeId: string, agentId: string) => Promise<void>;
+
+const RELEASED = 'this machine no longer holds the agent';
+
+export async function assertLease(
+  who: AgentIdentity,
+  fence: Fence,
+): Promise<void> {
+  if (who.runtimeId === undefined) return;
+  try {
+    await fence(who.runtimeId, who.agentId);
+  } catch (err) {
+    if (err instanceof ApiError) throw new ApiError(RELEASED, 401);
+    throw err;
+  }
+}
+
+export function projectParam(req: IncomingMessage): string | null {
+  const raw = new URL(req.url ?? '/', 'http://localhost').searchParams.get(
+    'project',
+  );
+  return raw === null || raw === '' ? null : raw;
+}
+
+export async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  let over = false;
+  for await (const c of req) {
+    const buf = c as Buffer;
+    total += buf.length;
+    if (total > BODY_MAX) over = true;
+    if (!over) chunks.push(buf);
+    else if (total > DRAIN_MAX) break;
+  }
+  if (over) throw new ApiError('request body too large', 413);
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  if (raw === '') return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new ApiError('body must be JSON', 400);
+  }
+}
+
+export function apiFailure(
+  req: IncomingMessage,
+  res: ServerResponse,
+  err: unknown,
+  label = 'agent-api',
+): void {
+  if (err instanceof ApiError) {
+    sendJson(req, res, err.status, { error: err.message });
+    return;
+  }
+  log.warn({ err: errMsg(err) }, `${label}: request failed`);
+  if (!res.headersSent) sendJson(req, res, 500, { error: `${label} failed` });
+}
+
+export function bodyField(body: unknown, key: string): unknown {
+  return typeof body === 'object' && body !== null && !Array.isArray(body)
+    ? (body as Record<string, unknown>)[key]
+    : undefined;
+}

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

@@ -0,0 +1,99 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { ID_RE } from '../db/ids.js';
+import { readFileSync } from 'node:fs';
+import { resolveCachedAttachment } from '../stations/attachments.js';
+import { writeSecure } from './secure-fs.js';
+
+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,
+  };
+}
+
+export 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/mcp/src/daemon/attach-owner.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { ID_RE } from '../db/ids.js';
+import { resolveCachedAttachment } from '../stations/attachments.js';
+import { writeSecure } from './secure-fs.js';
+
+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/mcp/src/daemon/attach-serve.ts

@@ -0,0 +1,133 @@
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  guessMime,
+  resolveCachedAttachment,
+} from '../stations/attachments.js';
+import {
+  allowedAgents,
+  authConfigFromEnv,
+  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 './log.js';
+import { configuredTunnelHost, currentTunnelUrl, webhookPort } from './tunnel.js';
+import { isLocalMode } from './paths.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, authConfigFromEnv()) ?? undefined).has(
+    owner,
+  );
+}
+
+const DEFAULT_PUBLIC_BASE = 'https://mcp.metro.box';
+
+export function publicBaseUrl(): string | null {
+  const env = process.env.METRO_PUBLIC_URL?.trim();
+  if (env) return env.replace(/\/+$/, '');
+  const live = currentTunnelUrl();
+  if (live !== null) return live;
+  const host = configuredTunnelHost();
+  return host ? `https://${host}` : null;
+}
+
+const servesLocally = (): boolean =>
+  (process.env.METRO_RUN_TOKEN?.trim() ?? '') !== '' || isLocalMode();
+
+const localBase = (): string | null =>
+  servesLocally() ? `http://127.0.0.1:${String(webhookPort())}` : null;
+
+export const publicBaseOrDefault = (): string =>
+  publicBaseUrl() ?? localBase() ?? DEFAULT_PUBLIC_BASE;
+
+export function attachmentUrl(
+  pathOrName: string,
+  agentId: string,
+): string | null {
+  const base = publicBaseUrl() ?? localBase();
+  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;
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/attach-session.ts

@@ -0,0 +1,278 @@
+import { randomBytes } from 'node:crypto';
+import { ApiError } from './api-error.js';
+import { errMsg, log } from './log.js';
+import type { StationName } from '../db/schema.js';
+import {
+  startInteractiveAttach,
+  type AttachDriver,
+  type AttachOutcome,
+  type AttachPrompt,
+  type AttachStep,
+  type DriverHooks,
+  type InteractiveStation,
+  type StartedAttach,
+} from '../stations/attach-interactive.js';
+
+export type StartAttach = (
+  station: InteractiveStation,
+  input: Record<string, unknown>,
+  hooks: DriverHooks,
+) => Promise<StartedAttach>;
+
+export const ATTACH_ID_RE = /^as_[A-Za-z0-9_-]{22}$/;
+
+const PENDING_TTL_MS = 5 * 60_000;
+const SETTLED_TTL_MS = 60_000;
+const SWEEP_MS = 15_000;
+const MAX_PER_AGENT = 2;
+const MAX_TOTAL = 40;
+
+export interface AttachOwner {
+  subject: string;
+  agentId: string;
+}
+
+export interface AttachView {
+  attachId: string;
+  station: string;
+  status: 'pending' | 'done' | 'failed';
+  step: AttachStep | null;
+  prompt: string;
+  qr: string | null;
+  pairingCode: string | null;
+  accountId: string | null;
+  identity: Record<string, string>;
+  activated: boolean;
+  error: string | null;
+  expiresAt: number;
+}
+
+export type CompleteAttach = (
+  owner: AttachOwner,
+  station: StationName,
+  config: Record<string, unknown>,
+) => Promise<{ accountId: string; activated: boolean }>;
+
+export type AuthorizeAttach = (owner: AttachOwner) => Promise<void>;
+
+export interface AttachSessionDeps {
+  authorize: AuthorizeAttach;
+  complete: CompleteAttach;
+  start?: StartAttach;
+}
+
+interface Session {
+  owner: AttachOwner;
+  driver: AttachDriver | null;
+  view: AttachView;
+}
+
+const missing = (): ApiError => new ApiError('no such attach session', 404);
+
+function newAttachId(): string {
+  return `as_${randomBytes(16).toString('base64url')}`;
+}
+
+function blankView(attachId: string, station: string): AttachView {
+  return {
+    attachId,
+    station,
+    status: 'pending',
+    step: null,
+    prompt: '',
+    qr: null,
+    pairingCode: null,
+    accountId: null,
+    identity: {},
+    activated: false,
+    error: null,
+    expiresAt: Date.now() + PENDING_TTL_MS,
+  };
+}
+
+export class AttachSessions {
+  private sessions = new Map<string, Session>();
+  private sweeper: ReturnType<typeof setInterval> | null = null;
+
+  constructor(private deps: AttachSessionDeps) {}
+
+  private ensureSweeper(): void {
+    if (this.sweeper) return;
+    this.sweeper = setInterval(() => {
+      this.sweep().catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'attach-session: sweep failed');
+      });
+    }, SWEEP_MS);
+    this.sweeper.unref();
+  }
+
+  private own(owner: AttachOwner, attachId: string): Session {
+    const session = this.sessions.get(attachId);
+    if (
+      session?.owner.subject !== owner.subject ||
+      session.owner.agentId !== owner.agentId
+    )
+      throw missing();
+    return session;
+  }
+
+  private admit(owner: AttachOwner): void {
+    if (this.sessions.size >= MAX_TOTAL)
+      throw new ApiError(
+        'too many sign-ins are in flight on this daemon, try again shortly',
+        429,
+      );
+    const mine = [...this.sessions.values()].filter(
+      (s) => s.owner.agentId === owner.agentId && s.view.status === 'pending',
+    );
+    if (mine.length >= MAX_PER_AGENT)
+      throw new ApiError(
+        'this agent already has a sign-in in progress, finish or cancel it first',
+        409,
+      );
+  }
+
+  private settle(session: Session, patch: Partial<AttachView>): void {
+    Object.assign(session.view, patch, {
+      qr: null,
+      pairingCode: null,
+      step: null,
+      expiresAt: Date.now() + SETTLED_TTL_MS,
+    });
+    session.driver = null;
+  }
+
+  private async finish(
+    attachId: string,
+    station: StationName,
+    outcome: AttachOutcome,
+  ): Promise<void> {
+    const session = this.sessions.get(attachId);
+    if (session?.view.status !== 'pending') return;
+    try {
+      const landed = await this.deps.complete(
+        session.owner,
+        station,
+        outcome.config,
+      );
+      this.settle(session, {
+        status: 'done',
+        prompt: '',
+        identity: outcome.identity,
+        accountId: landed.accountId,
+        activated: landed.activated,
+      });
+      log.info(
+        { agentId: session.owner.agentId, station, account: landed.accountId },
+        'attach-session: signed in and attached a station account',
+      );
+    } catch (err) {
+      const reason =
+        err instanceof ApiError ? err.message : 'could not store the account';
+      log.warn({ station, err: errMsg(err) }, 'attach-session: store failed');
+      this.settle(session, { status: 'failed', prompt: '', error: reason });
+    }
+  }
+
+  private hooksFor(attachId: string, station: StationName) {
+    return {
+      prompt: (p: AttachPrompt): void => {
+        const session = this.sessions.get(attachId);
+        if (session?.view.status !== 'pending') return;
+        session.view.step = p.step;
+        session.view.prompt = p.prompt;
+        session.view.qr = p.qr ?? null;
+        session.view.pairingCode = p.pairingCode ?? null;
+      },
+      done: (o: AttachOutcome): void => {
+        this.finish(attachId, station, o).catch((err: unknown) => {
+          log.warn(
+            { attachId, station, err: errMsg(err) },
+            'attach-session: completion failed',
+          );
+        });
+      },
+      fail: (message: string): void => {
+        const session = this.sessions.get(attachId);
+        if (session?.view.status !== 'pending') return;
+        this.settle(session, { status: 'failed', prompt: '', error: message });
+      },
+    };
+  }
+
+  async start(
+    owner: AttachOwner,
+    station: InteractiveStation,
+    input: Record<string, unknown>,
+  ): Promise<AttachView> {
+    await this.deps.authorize(owner);
+    this.admit(owner);
+    this.ensureSweeper();
+    const attachId = newAttachId();
+    const session: Session = {
+      owner,
+      driver: null,
+      view: blankView(attachId, station),
+    };
+    this.sessions.set(attachId, session);
+    try {
+      const started = await (this.deps.start ?? startInteractiveAttach)(
+        station,
+        input,
+        this.hooksFor(attachId, station),
+      );
+      session.driver = started.driver;
+      this.hooksFor(attachId, station).prompt(started.prompt);
+    } catch (err) {
+      this.sessions.delete(attachId);
+      throw err;
+    }
+    log.info(
+      { agentId: owner.agentId, station, attachId },
+      'attach-session: started',
+    );
+    return { ...session.view };
+  }
+
+  view(owner: AttachOwner, attachId: string): AttachView {
+    return { ...this.own(owner, attachId).view };
+  }
+
+  async submit(
+    owner: AttachOwner,
+    attachId: string,
+    input: { code?: unknown; password?: unknown },
+  ): Promise<AttachView> {
+    const session = this.own(owner, attachId);
+    const driver = session.driver;
+    if (session.view.status !== 'pending' || !driver)
+      throw new ApiError('this sign-in is already finished', 409);
+    await driver.submit(input);
+    return { ...session.view };
+  }
+
+  async cancel(owner: AttachOwner, attachId: string): Promise<void> {
+    const session = this.own(owner, attachId);
+    this.sessions.delete(attachId);
+    await session.driver?.cancel().catch(() => undefined);
+    log.info({ attachId }, 'attach-session: cancelled');
+  }
+
+  async sweep(now = Date.now()): Promise<void> {
+    for (const [attachId, session] of [...this.sessions]) {
+      if (session.view.expiresAt > now) continue;
+      this.sessions.delete(attachId);
+      const driver = session.driver;
+      session.driver = null;
+      if (!driver) continue;
+      log.info({ attachId }, 'attach-session: expired, credentials discarded');
+      await driver.cancel().catch(() => undefined);
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (this.sweeper) clearInterval(this.sweeper);
+    this.sweeper = null;
+    await this.sweep(Number.MAX_SAFE_INTEGER);
+  }
+}