@stage-labs/metro 0.1.0-beta.15 → 0.1.0-beta.151

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-resolve.ts

@@ -0,0 +1,202 @@
+import {
+  assertAttachmentSize,
+  assertContentLength,
+  guessMime,
+  saveBufferToCache,
+} from '@metro-labs/core/stations/attachments';
+import {
+  assertInlineTotal,
+  decodeInline,
+  removeInlineTemp,
+  splitInlineData,
+  writeInlineTemp,
+} from './attach-inline.js';
+import { realpathSync } from 'node:fs';
+import { log } from '@metro-labs/core/log';
+import { readUpload, UPLOAD_TTL_MS } from '../files/upload-store.js';
+import type { CanonicalAttachment } from '@metro-labs/core/stations/types';
+
+export interface ResolvedAttachment {
+  path: string;
+  mime: string;
+  name: string;
+  bytes: number;
+  temp?: string;
+}
+
+export interface ResolveOptions {
+  allowed?: Set<string>;
+}
+
+interface InlineBudget {
+  used: number;
+}
+
+const FETCH_TIMEOUT_MS = 60_000;
+
+const basenameOf = (src: string): string =>
+  src.split('?')[0]?.split('#')[0]?.split('/').filter(Boolean).pop() ?? '';
+
+const isHttpUrl = (src: string): boolean => /^https?:\/\//i.test(src);
+
+const mintId = (): string => Math.random().toString(36).slice(2, 12);
+
+const HIDDEN_SEGMENT = /(^|\/)\.[^/]/;
+
+function assertReadablePath(path: string): void {
+  let real: string;
+  try {
+    real = realpathSync(path);
+  } catch {
+    return;
+  }
+  if (HIDDEN_SEGMENT.test(real))
+    throw new Error(
+      `attachment path '${path}' resolves into a hidden directory ` +
+        `('${real}') and will not be read. \`path\` is read on the daemon ` +
+        'machine; put the file somewhere non-hidden or pass `upload` instead.',
+    );
+}
+
+async function fromPath(
+  a: CanonicalAttachment,
+  path: string,
+): Promise<ResolvedAttachment> {
+  assertReadablePath(path);
+  const file = Bun.file(path);
+  if (!(await file.exists()))
+    throw new Error(
+      `attachment path '${path}' does not exist on the metro host. ` +
+        '`path` is read on the daemon machine, not on the caller\'s machine; ' +
+        'pass `url` instead if the file is not already on the daemon.',
+    );
+  assertAttachmentSize(file.size);
+  return {
+    path,
+    mime: a.mime ?? guessMime(path),
+    name: a.name ?? basenameOf(path) ?? 'attachment',
+    bytes: file.size,
+  };
+}
+
+async function fromUrl(
+  a: CanonicalAttachment,
+  url: string,
+): Promise<ResolvedAttachment> {
+  if (!isHttpUrl(url))
+    throw new Error(
+      `attachment url '${url}' is not an http(s) url; use \`path\` for a local file`,
+    );
+  const res = await fetch(url, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!res.ok)
+    throw new Error(`attachment fetch failed ${res.status} for '${url}'`);
+  assertContentLength(res.headers.get('content-length'));
+  const data = new Uint8Array(await res.arrayBuffer());
+  const mime =
+    a.mime ?? res.headers.get('content-type')?.split(';')[0] ?? guessMime(url);
+  const name = a.name ?? basenameOf(url) ?? 'attachment';
+  const saved = await saveBufferToCache(data, `out${mintId()}`, 0, {
+    mime,
+    name,
+  });
+  return { path: saved.path, mime, name, bytes: data.length };
+}
+
+async function fromData(
+  a: CanonicalAttachment,
+  data: string,
+  budget: InlineBudget,
+): Promise<ResolvedAttachment> {
+  const name = a.name ?? 'attachment';
+  const source = splitInlineData(data);
+  const bytes = decodeInline(source.data, `'${name}'`);
+  budget.used += bytes.length;
+  assertInlineTotal(budget.used);
+  const { dir, path } = await writeInlineTemp(bytes, a.name);
+  return {
+    path,
+    mime: a.mime ?? source.mime ?? guessMime(name),
+    name,
+    bytes: bytes.length,
+    temp: dir,
+  };
+}
+
+const uploadMissing = (id: string): Error =>
+  new Error(
+    `upload '${id}' is not a live upload of yours. Either it was never created, or its ` +
+      'bytes were never pushed to `POST /api/uploads`, or it belongs to another agent, or ' +
+      `it expired (an upload lives ${Math.round(UPLOAD_TTL_MS / 60_000)} minutes). ` +
+      'Create a new one with `create_upload` and push the file again.',
+  );
+
+function fromUpload(
+  a: CanonicalAttachment,
+  id: string,
+  allowed: Set<string> | undefined,
+): ResolvedAttachment {
+  const rec = allowed === undefined ? undefined : readUpload(id);
+  if (rec === undefined || !(allowed?.has(rec.agentId) ?? false))
+    throw uploadMissing(id);
+  const name = a.name ?? rec.name;
+  return { path: rec.path, mime: a.mime ?? rec.mime, name, bytes: rec.bytes };
+}
+
+export const SOURCE_KEYS = ['path', 'url', 'data', 'upload'] as const;
+
+const sourcesOf = (a: CanonicalAttachment): string[] =>
+  SOURCE_KEYS.filter((k) => {
+    const v = a[k];
+    return typeof v === 'string' && v.length > 0;
+  });
+
+async function resolveAttachment(
+  a: CanonicalAttachment,
+  budget: InlineBudget = { used: 0 },
+  opts: ResolveOptions = {},
+): Promise<ResolvedAttachment> {
+  const sources = sourcesOf(a);
+  if (sources.length === 0)
+    throw new Error(
+      'attachment requires exactly one of `upload`, `data`, `url` or `path`',
+    );
+  if (sources.length > 1)
+    throw new Error(
+      `attachment names ${sources.length} sources (${sources
+        .map((s) => `\`${s}\``)
+        .join(', ')}); pass exactly one of \`upload\`, \`data\`, \`url\` or \`path\``,
+    );
+  log.info({ source: sources[0] }, 'send: attachment source');
+  if (a.upload) return fromUpload(a, a.upload, opts.allowed);
+  if (a.data) return fromData(a, a.data, budget);
+  if (a.path) return fromPath(a, a.path);
+  return fromUrl(a, a.url ?? '');
+}
+
+export async function cleanupAttachments(
+  atts: ResolvedAttachment[],
+): Promise<void> {
+  for (const a of atts) if (a.temp) await removeInlineTemp(a.temp);
+}
+
+export async function resolveAttachments(
+  atts: CanonicalAttachment[],
+  opts: ResolveOptions = {},
+): Promise<ResolvedAttachment[]> {
+  const out: ResolvedAttachment[] = [];
+  const budget: InlineBudget = { used: 0 };
+  for (let i = 0; i < atts.length; i++) {
+    const a = atts[i];
+    if (!a) continue;
+    try {
+      out.push(await resolveAttachment(a, budget, opts));
+    } catch (e) {
+      await cleanupAttachments(out);
+      const why = e instanceof Error ? e.message : String(e);
+      throw new Error(`attachment ${i + 1} of ${atts.length}: ${why}`);
+    }
+  }
+  return out;
+}

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

@@ -0,0 +1,280 @@
+import { randomBytes } from 'node:crypto';
+import { ApiError } from '@metro-labs/http/api-error';
+import { errMsg, log } from '@metro-labs/core/log';
+import type { StationName } from '@metro-labs/core/station-names';
+import { ensureStationDeps } from './runtime-deps.js';
+import {
+  startInteractiveAttach,
+  type AttachDriver,
+  type AttachOutcome,
+  type AttachPrompt,
+  type AttachStep,
+  type DriverHooks,
+  type InteractiveStation,
+  type StartedAttach,
+} from './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 {
+      ensureStationDeps(station);
+      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);
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-xmtp.ts

@@ -0,0 +1,111 @@
+import { randomBytes } from 'node:crypto';
+import { rmSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { errMsg, log } from '@metro-labs/core/log';
+
+export class XmtpAttachError extends Error {}
+
+export interface XmtpIdentity {
+  inboxId: string;
+  address: string;
+  installationId: string;
+  dbPath: string;
+}
+
+export type VerifyXmtpKey = (
+  privateKey: string,
+  dbPath: string,
+) => Promise<XmtpIdentity>;
+
+const VERIFY_TIMEOUT_MS = 90_000;
+const UNREACHABLE =
+  'Metro could not open an XMTP inbox with the key it generated, so nothing was attached';
+
+export function newXmtpDbPath(): string {
+  return `~/.metro/xmtp-production-${randomBytes(8).toString('hex')}.db3`;
+}
+
+export function discardXmtpDb(dbPath: string): void {
+  for (const suffix of ['', '-wal', '-shm'])
+    rmSync(`${dbPath}${suffix}`, { force: true });
+}
+
+export function withoutKey(message: string, privateKey: string): string {
+  return message.split(privateKey).join('[redacted]');
+}
+
+interface VerifyReply {
+  ok?: unknown;
+  inboxId?: unknown;
+  address?: unknown;
+  installationId?: unknown;
+  dbPath?: unknown;
+  error?: unknown;
+}
+
+const str = (value: unknown): string => (typeof value === 'string' ? value : '');
+
+function readReply(raw: string): VerifyReply {
+  const line = raw.trim().split('\n').at(-1) ?? '';
+  try {
+    const parsed: unknown = JSON.parse(line);
+    return typeof parsed === 'object' && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+async function runVerifier(payload: string): Promise<string> {
+  const script = fileURLToPath(import.meta.resolve('@metro-labs/xmtp/verify'));
+  const proc = Bun.spawn(['bun', 'run', script], {
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  await proc.stdin.write(payload);
+  await proc.stdin.end();
+  const timer = setTimeout(() => {
+    proc.kill();
+  }, VERIFY_TIMEOUT_MS);
+  try {
+    const [out, err, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    if (code !== 0)
+      log.warn(
+        { code, stderr: err.trim().slice(-500) },
+        'attach-xmtp: the inbox check exited badly',
+      );
+    return out;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function verifyXmtpKeyOutOfProcess(
+  privateKey: string,
+  dbPath: string,
+): Promise<XmtpIdentity> {
+  const raw = await runVerifier(
+    JSON.stringify({ privateKey, dbPath }),
+  ).catch((err: unknown) => {
+    log.warn({ err: errMsg(err) }, 'attach-xmtp: could not run the inbox check');
+    throw new XmtpAttachError(UNREACHABLE);
+  });
+  const reply = readReply(raw);
+  if (reply.ok !== true)
+    throw new XmtpAttachError(
+      withoutKey(str(reply.error) || UNREACHABLE, privateKey),
+    );
+  const identity = {
+    inboxId: str(reply.inboxId),
+    address: str(reply.address),
+    installationId: str(reply.installationId),
+    dbPath: str(reply.dbPath),
+  };
+  if (identity.inboxId === '' || identity.address === '')
+    throw new XmtpAttachError(UNREACHABLE);
+  return identity;
+}