@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.300

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

@@ -0,0 +1,314 @@
+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 InteractiveStation } from './attach-interactive.js';
+import type {
+  AttachDriver,
+  AttachOutcome,
+  AttachPrompt,
+  AttachStep,
+  DriverHooks,
+  StartedAttach,
+  StepInput,
+} from './attach-driver.js';
+
+export type StartAttach = (
+  station: InteractiveStation,
+  input: Record<string, unknown>,
+  hooks: DriverHooks,
+  owner: AttachOwner,
+) => 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 {
+  agentId: string;
+  organization?: string;
+  userId?: string;
+  sessionId?: string;
+  authorization?: string;
+}
+
+export interface AttachView {
+  attachId: string;
+  station: string;
+  status: 'pending' | 'done' | 'failed';
+  step: AttachStep | null;
+  prompt: string;
+  qr: string | null;
+  pairingCode: string | null;
+  userCode: string | null;
+  verificationUri: string | null;
+  authorizeUrl: string | null;
+  accountId: string | null;
+  identity: Record<string, string>;
+  activated: boolean;
+  error: string | null;
+  expiresAt: number;
+}
+
+type CompleteAttach = (
+  owner: AttachOwner,
+  station: StationName,
+  config: Record<string, unknown>,
+  active: () => boolean,
+) => Promise<{ accountId: string; activated: boolean }>;
+
+type AuthorizeAttach = (owner: AttachOwner) => Promise<void>;
+
+export interface AttachSessionDeps {
+  authorize: AuthorizeAttach;
+  complete: CompleteAttach;
+  start?: StartAttach;
+}
+
+interface Session {
+  owner: AttachOwner;
+  driver: AttachDriver | null;
+  view: AttachView;
+  finishing?: boolean;
+  committing?: boolean;
+}
+
+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,
+    userCode: null,
+    verificationUri: null,
+    authorizeUrl: 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 === undefined || session.owner.agentId !== owner.agentId || session.owner.organization !== owner.organization || session.owner.userId !== owner.userId || session.owner.sessionId !== owner.sessionId) throw missing();
+    if (session.view.expiresAt <= Date.now()) throw new ApiError('this sign-in expired; start again', 410);
+    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,
+      userCode: null,
+      verificationUri: null,
+      authorizeUrl: 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);
+    const active = (): boolean => session !== undefined && this.sessions.get(attachId) === session && session.view.status === 'pending' && session.view.expiresAt > Date.now();
+    if (!active() || session === undefined || session.finishing === true) return;
+    session.finishing = true;
+    try {
+      await this.deps.authorize(session.owner);
+      if (!active()) return;
+      const landed = await this.deps.complete(
+        session.owner,
+        station,
+        outcome.config,
+        () => {
+          if (!active()) return false;
+          session.committing = true;
+          return true;
+        },
+      );
+      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;
+        session.view.userCode = p.userCode ?? null;
+        session.view.verificationUri = p.verificationUri ?? null;
+        session.view.authorizeUrl = p.authorizeUrl ?? 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),
+        owner,
+      );
+      if (this.sessions.get(attachId) !== session || session.view.expiresAt <= Date.now()) {
+        await started.driver.cancel();
+        throw new ApiError('this sign-in expired or stopped; start again', 410);
+      }
+      session.driver = started.driver;
+      if (started.expiresAt !== undefined) session.view.expiresAt = started.expiresAt;
+      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: StepInput,
+  ): 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 this.deps.authorize(owner);
+    this.own(owner, attachId);
+    await driver.submit(input, owner.authorization);
+    return { ...session.view };
+  }
+
+  async cancel(owner: AttachOwner, attachId: string): Promise<void> {
+    const session = this.own(owner, attachId);
+    if (session.committing === true) throw new ApiError('this sign-in has already been saved', 409);
+    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 || (session.committing === true && session.view.status === 'pending')) 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,110 @@
+import { randomBytes } from 'node:crypto';
+import { stringOf } from '@metro-labs/http/api-http';
+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;
+}
+
+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, smart: true }),
+  ).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(stringOf(reply.error) || UNREACHABLE, privateKey),
+    );
+  const identity = {
+    inboxId: stringOf(reply.inboxId),
+    address: stringOf(reply.address),
+    installationId: stringOf(reply.installationId),
+    dbPath: stringOf(reply.dbPath),
+  };
+  if (identity.inboxId === '' || identity.address === '')
+    throw new XmtpAttachError(UNREACHABLE);
+  return identity;
+}

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

@@ -0,0 +1,248 @@
+import { randomBytes } from 'node:crypto';
+import {
+  DiscordTokenError,
+  verifyDiscordBotToken,
+} from '@metro-labs/discord-bot/verify';
+import {
+  TelegramTokenError,
+  verifyTelegramBotToken,
+} from '@metro-labs/telegram-bot/verify';
+import {
+  parsePrivateKey,
+  ThreemaGatewayError,
+  verifyThreemaGateway,
+} from '@metro-labs/threema/verify';
+import { ApiError } from '@metro-labs/http/api-error';
+import { bodyField } from '@metro-labs/http/api-http';
+import { ensureStationDeps } from './runtime-deps.js';
+import { publicBaseOrDefault } from '../files/attach-serve.js';
+import {
+  discardXmtpDb,
+  newXmtpDbPath,
+  verifyXmtpKeyOutOfProcess,
+  XmtpAttachError,
+  type VerifyXmtpKey,
+} from './attach-xmtp.js';
+
+export const ATTACHABLE_STATIONS = [
+  'discord-bot',
+  'telegram-bot',
+  'threema',
+  'xmtp',
+  'webhook',
+] as const;
+
+export type AttachStation = (typeof ATTACHABLE_STATIONS)[number];
+
+export class StationAttachError extends ApiError {}
+
+export interface AttachInput {
+  station: AttachStation;
+  token?: unknown;
+  gatewayId?: unknown;
+  secret?: unknown;
+  privateKey?: unknown;
+}
+
+export interface OneTimeSecret {
+  label: string;
+  value: string;
+  note: string;
+}
+
+export interface PreparedAccount {
+  config: Record<string, unknown>;
+  identity: Record<string, string>;
+  secret?: OneTimeSecret;
+  discard?: () => void;
+}
+
+const TOKEN_RE = /^[A-Za-z0-9._:-]{8,256}$/;
+
+const SECP256K1_ORDER = BigInt(
+  '0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141',
+);
+
+export function attachInputOf(station: AttachStation, body: unknown): AttachInput {
+  return {
+    station,
+    token: bodyField(body, 'token'),
+    gatewayId: bodyField(body, 'gatewayId'),
+    secret: bodyField(body, 'secret'),
+    privateKey: bodyField(body, 'privateKey'),
+  };
+}
+
+export function isAttachStation(raw: unknown): raw is AttachStation {
+  return (
+    typeof raw === 'string' &&
+    (ATTACHABLE_STATIONS as readonly string[]).includes(raw)
+  );
+}
+
+function requireToken(raw: unknown, label: string): string {
+  const token = typeof raw === 'string' ? raw.trim() : '';
+  if (token === '')
+    throw new StationAttachError(`a ${label} bot token is required`, 400);
+  if (!TOKEN_RE.test(token))
+    throw new StationAttachError(
+      `that does not look like a ${label} bot token`,
+      400,
+    );
+  return token;
+}
+
+function rejected(err: unknown, own: boolean, fallback: string): never {
+  throw new StationAttachError(
+    own && err instanceof Error ? err.message : fallback,
+    400,
+  );
+}
+
+async function prepareDiscord(raw: unknown): Promise<PreparedAccount> {
+  const token = requireToken(raw, 'Discord');
+  try {
+    const bot = await verifyDiscordBotToken(token);
+    if (!bot.messageContent)
+      throw new StationAttachError(
+        'this Discord application does not have the Message Content intent enabled. Turn it on under Bot / Privileged Gateway Intents in the developer portal, then attach it again',
+        400,
+      );
+    return {
+      config: { token },
+      identity: { userId: bot.userId, username: bot.username },
+    };
+  } catch (err) {
+    if (err instanceof StationAttachError) throw err;
+    return rejected(
+      err,
+      err instanceof DiscordTokenError,
+      'Discord rejected that bot token',
+    );
+  }
+}
+
+async function prepareTelegram(raw: unknown): Promise<PreparedAccount> {
+  const token = requireToken(raw, 'Telegram');
+  try {
+    const bot = await verifyTelegramBotToken(token);
+    return {
+      config: { token },
+      identity: { botId: String(bot.botId), username: bot.username },
+    };
+  } catch (err) {
+    return rejected(
+      err,
+      err instanceof TelegramTokenError,
+      'Telegram rejected that bot token',
+    );
+  }
+}
+
+export function newXmtpPrivateKey(): string {
+  for (;;) {
+    const hex = randomBytes(32).toString('hex');
+    const value = BigInt(`0x${hex}`);
+    if (value > 0n && value < SECP256K1_ORDER) return `0x${hex}`;
+  }
+}
+
+async function prepareXmtp(verify: VerifyXmtpKey): Promise<PreparedAccount> {
+  const privateKey = newXmtpPrivateKey();
+  const dbPath = newXmtpDbPath();
+  const identity = await verify(privateKey, dbPath).catch((err: unknown) =>
+    rejected(
+      err,
+      err instanceof XmtpAttachError,
+      'Metro could not open an XMTP inbox with the key it generated, so nothing was attached',
+    ),
+  );
+  return {
+    config: { privateKey, dbPath, smart: true },
+    identity: { inboxId: identity.inboxId, address: identity.address },
+    secret: {
+      label: 'xmtp private key',
+      value: privateKey,
+      note: 'Metro generated this key, opened inbox ' +
+        `${identity.inboxId} with it, and stores it with the account. ` +
+        'It is shown once, here, and is never returned by any API again.',
+    },
+    discard: () => {
+      discardXmtpDb(identity.dbPath);
+    },
+  };
+}
+
+export const hookUrl = (webhookId: string, secret: string): string =>
+  `${publicBaseOrDefault().replace(/\/+$/, '')}/api/webhooks/${webhookId}/${secret}`;
+
+const WEBHOOK_ID_FLOOR = 10n ** 18n;
+
+export function newWebhookId(): string {
+  const raw = BigInt(`0x${randomBytes(8).toString('hex')}`);
+  return String(WEBHOOK_ID_FLOOR + (raw % (9n * WEBHOOK_ID_FLOOR)));
+}
+
+export const threemaCallbackUrl = (callbackId: string, token: string): string =>
+  `${publicBaseOrDefault().replace(/\/+$/, '')}/api/threema/${callbackId}/${token}`;
+
+function requireText(raw: unknown, label: string): string {
+  const text = typeof raw === 'string' ? raw.trim() : '';
+  if (text === '')
+    throw new StationAttachError(`the Threema ${label} is required`, 400);
+  return text;
+}
+
+async function prepareThreema(input: AttachInput): Promise<PreparedAccount> {
+  const gatewayId = requireText(input.gatewayId, 'Gateway ID');
+  const secret = requireText(input.secret, 'API secret');
+  const privateKey = requireText(input.privateKey, 'private key');
+  try {
+    const identity = await verifyThreemaGateway({ gatewayId, secret, privateKey });
+    const callbackId = newWebhookId();
+    const callbackToken = randomBytes(48).toString('base64url');
+    return {
+      config: {
+        gatewayId: identity.gatewayId,
+        secret,
+        privateKey: parsePrivateKey(privateKey) ?? privateKey,
+        callbackId,
+        callbackToken,
+        createdAt: new Date().toISOString(),
+      },
+      identity: {
+        gatewayId: identity.gatewayId,
+        credits: String(identity.credits),
+        callback: threemaCallbackUrl(callbackId, callbackToken),
+      },
+    };
+  } catch (err) {
+    if (err instanceof StationAttachError) throw err;
+    return rejected(
+      err,
+      err instanceof ThreemaGatewayError,
+      'Threema rejected those Gateway credentials',
+    );
+  }
+}
+
+function prepareWebhook(): PreparedAccount {
+  const secret = randomBytes(48).toString('base64url');
+  const webhookId = newWebhookId();
+  return {
+    config: { secret, webhookId, createdAt: new Date().toISOString() },
+    identity: { endpoint: hookUrl(webhookId, secret) },
+  };
+}
+
+export async function prepareAccount(
+  input: AttachInput,
+  verify: VerifyXmtpKey = verifyXmtpKeyOutOfProcess,
+): Promise<PreparedAccount> {
+  ensureStationDeps(input.station);
+  if (input.station === 'discord-bot') return prepareDiscord(input.token);
+  if (input.station === 'telegram-bot') return prepareTelegram(input.token);
+  if (input.station === 'webhook') return prepareWebhook();
+  if (input.station === 'threema') return prepareThreema(input);
+  return prepareXmtp(verify);
+}