@stage-labs/metro 0.1.0-beta.21 → 0.1.0-beta.211

package/runtime/node_modules/@metro-labs/daemon/src/agents/accounts-api.ts

@@ -0,0 +1,357 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { normalizeAllowlist, normalizeApprovers } from './allowlist.js';
+import { approversForAccount } from './map.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { RecentSender } from './senders.js';
+import { ApiError } from '@metro-labs/http/api-error';
+import { apiFailure, bodyField, readJsonBody, sendJson } from '@metro-labs/http/api-http';
+import { type AccountRef } from './account-attach.js';
+import { type AccountRoute } from './account-routes.js';
+import { handlePolicy, type SetPolicy } from './policy-route.js';
+import { LOOKUPS } from './account-lookups.js';
+import { unconfirmedSenders } from './sender-cards.js';
+import { stationByName } from '../stations/registry.js';
+import type { StationName } from '@metro-labs/core/station-names';
+import {
+  ATTACHABLE_STATIONS,
+  attachInputOf,
+  isAttachStation,
+  type AttachInput,
+  type OneTimeSecret,
+  type PreparedAccount,
+} from '../stations/attach.js';
+import {
+  INTERACTIVE_STATIONS,
+  isInteractiveStation,
+  type InteractiveStation,
+} from '../stations/attach-interactive.js';
+import type { StepInput } from '../stations/attach-driver.js';
+import {
+  type AttachOwner,
+  type AttachView,
+} from '../stations/attach-session.js';
+
+interface AttachSessionApi {
+  start: (
+    owner: AttachOwner,
+    station: InteractiveStation,
+    input: Record<string, unknown>,
+  ) => Promise<AttachView>;
+  view: (owner: AttachOwner, attachId: string) => AttachView;
+  submit: (
+    owner: AttachOwner,
+    attachId: string,
+    input: StepInput,
+  ) => Promise<AttachView>;
+  cancel: (owner: AttachOwner, attachId: string) => Promise<void>;
+}
+
+export interface AccountApiDeps {
+  attachSessions: AttachSessionApi;
+  prepareAccount: (input: AttachInput) => Promise<PreparedAccount>;
+  attachAccount: (
+    agentId: string,
+    station: StationName,
+    config: Record<string, unknown>,
+  ) => Promise<AccountRef>;
+  detachAccount: (
+    agentId: string,
+    station: StationName,
+    accountId: string,
+  ) => Promise<AccountRef>;
+  syncStations: (station: StationName) => Promise<void>;
+  reloadAgents: () => Promise<void>;
+  setAllowlist: (
+    agentId: string,
+    station: StationName,
+    accountId: string,
+    allowlist: string[],
+    approvers?: string[],
+  ) => Promise<string[]>;
+  setPolicy: SetPolicy;
+  recentSenders: (station: StationName, accountId: string) => RecentSender[];
+  resolveSender: (
+    station: StationName,
+    accountId: string,
+    query: string,
+  ) => Promise<unknown>;
+  accountCall: (
+    station: StationName,
+    action: string,
+    args: Record<string, unknown>,
+  ) => Promise<unknown>;
+  setAccountEnabled: (
+    agentId: string,
+    station: StationName,
+    accountId: string,
+    enabled: boolean,
+  ) => Promise<boolean>;
+}
+
+export const ATTACHABLE: string[] = [...ATTACHABLE_STATIONS, ...INTERACTIVE_STATIONS];
+
+async function activate(
+  deps: AccountApiDeps,
+  station: StationName,
+): Promise<boolean> {
+  try {
+    await deps.syncStations(station);
+    return true;
+  } catch (err) {
+    log.warn(
+      { station, err: errMsg(err) },
+      'account-api: station reload failed, the change lands at the next boot',
+    );
+    return false;
+  }
+}
+
+interface AttachPayload {
+  status: 'done';
+  agentId: string;
+  station: string;
+  accountId: string;
+  identity: Record<string, string>;
+  activated: boolean;
+  secret?: OneTimeSecret;
+}
+
+async function storeAccount(
+  deps: AccountApiDeps,
+  agentId: string,
+  station: StationName,
+  prepared: PreparedAccount,
+): Promise<AccountRef> {
+  try {
+    return await deps.attachAccount(
+      agentId,
+      station,
+      prepared.config,
+    );
+  } catch (err) {
+    prepared.discard?.();
+    throw err;
+  }
+}
+
+
+function asInput(body: unknown): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of ['apiId', 'apiHash', 'phone', 'mailbox'])
+    out[key] = bodyField(body, key);
+  return out;
+}
+
+async function handleStart(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const station = bodyField(body, 'station');
+  if (isInteractiveStation(station)) {
+    const view = await deps.attachSessions.start(
+      { agentId },
+      station,
+      asInput(body),
+    );
+    sendJson(req, res, 201, view);
+    return;
+  }
+  if (!isAttachStation(station))
+    throw new ApiError(`station must be one of ${ATTACHABLE.join(', ')}`, 400);
+  const prepared = await deps.prepareAccount(attachInputOf(station, body));
+  const ref = await storeAccount(deps, agentId, station, prepared);
+  log.info(
+    { agentId: ref.agentId, station, account: ref.accountId },
+    'account-api: attached a station account',
+  );
+  const payload: AttachPayload = {
+    status: 'done',
+    agentId: ref.agentId,
+    station,
+    accountId: ref.accountId,
+    identity: prepared.identity,
+    activated: await activate(deps, station),
+  };
+  sendJson(
+    req,
+    res,
+    201,
+    prepared.secret === undefined
+      ? payload
+      : { ...payload, secret: prepared.secret },
+  );
+}
+
+async function handleDetach(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  target: { station: StationName; accountId: string },
+): Promise<void> {
+  const ref = await deps.detachAccount(
+    agentId,
+    target.station,
+    target.accountId,
+  );
+  log.info(
+    { agentId: ref.agentId, station: ref.station, account: ref.accountId },
+    'account-api: detached a station account',
+  );
+  sendJson(req, res, 200, {
+    agentId: ref.agentId,
+    station: ref.station,
+    accountId: ref.accountId,
+    detached: true,
+    activated: await activate(deps, ref.station),
+  });
+  forgetAccount(ref.station, ref.accountId);
+}
+
+function forgetAccount(station: StationName, accountId: string): void {
+  try {
+    stationByName(station)?.forget?.(accountId);
+  } catch (err) {
+    log.warn(
+      { station, account: accountId, err: errMsg(err) },
+      'account-api: could not remove the files of a detached account',
+    );
+  }
+}
+
+async function applied(deps: AccountApiDeps): Promise<boolean> {
+  try {
+    await deps.reloadAgents();
+    return true;
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'account-api: allowlist reload failed, the change lands at the next boot');
+    return false;
+  }
+}
+
+async function handleAllowlist(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  target: { station: StationName; accountId: string },
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const wanted = normalizeAllowlist(bodyField(body, 'allowlist'));
+  const asked = isRecord(body) && 'approvers' in body ? body.approvers : approversForAccount(target.station, target.accountId);
+  const approvers = normalizeApprovers(asked, wanted);
+  const before = new Set(approversForAccount(target.station, target.accountId).map((a) => a.toLowerCase()));
+  const unknown = await unconfirmedSenders(deps, target.station, target.accountId, approvers.filter((a) => !before.has(a.toLowerCase())));
+  if (unknown.length > 0) throw new ApiError(`${target.station} does not know ${unknown.join(', ')}. Check the id, or have them write to the agent once, then try again.`, 400);
+  const allowlist = await deps.setAllowlist(agentId, target.station, target.accountId, wanted, approvers);
+  log.info({ agentId, station: target.station, account: target.accountId, senders: allowlist.length }, 'account-api: allowlist set');
+  sendJson(req, res, 200, {
+    agentId,
+    station: target.station,
+    accountId: target.accountId,
+    allowlist,
+    approvers,
+    activated: await applied(deps),
+  });
+}
+
+async function handleEnabled(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  target: { station: StationName; accountId: string },
+): Promise<void> {
+  const wanted = bodyField(await readJsonBody(req), 'enabled');
+  if (typeof wanted !== 'boolean') throw new ApiError('enabled must be true or false', 400);
+  const enabled = await deps.setAccountEnabled(agentId, target.station, target.accountId, wanted);
+  log.info({ agentId, station: target.station, account: target.accountId, enabled }, 'account-api: account enabled flag set');
+  sendJson(req, res, 200, {
+    agentId,
+    station: target.station,
+    accountId: target.accountId,
+    enabled,
+    activated: await activate(deps, target.station),
+  });
+}
+
+async function handleSession(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  owner: AttachOwner,
+  attachId: string,
+): Promise<void> {
+  if (req.method === 'DELETE') {
+    await deps.attachSessions.cancel(owner, attachId);
+    sendJson(req, res, 200, { attachId, cancelled: true });
+    return;
+  }
+  sendJson(req, res, 200, deps.attachSessions.view(owner, attachId));
+}
+
+async function handleStep(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  owner: AttachOwner,
+  attachId: string,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const field = (key: string): unknown => bodyField(body, key);
+  const view = await deps.attachSessions.submit(owner, attachId, {
+    code: field('code'),
+    password: field('password'),
+    state: field('state'),
+    mode: field('mode'),
+    error: field('error'),
+    errorDescription: field('errorDescription'),
+  });
+  sendJson(req, res, 200, view);
+}
+
+async function dispatchAttach(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  route: Extract<AccountRoute, { kind: 'start' | 'session' | 'step' }>,
+): Promise<void> {
+  if (route.kind === 'start') return handleStart(req, res, deps, agentId);
+  if (route.kind === 'session') return handleSession(req, res, deps, { agentId }, route.attachId);
+  return handleStep(req, res, deps, { agentId }, route.attachId);
+}
+
+async function dispatchRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  route: AccountRoute,
+): Promise<void> {
+  if (route.kind === 'start' || route.kind === 'session' || route.kind === 'step') return dispatchAttach(req, res, deps, agentId, route);
+  if (route.kind === 'allowlist') return handleAllowlist(req, res, deps, agentId, route);
+  if (route.kind === 'enabled') return handleEnabled(req, res, deps, agentId, route);
+  if (route.kind === 'policy') return handlePolicy(req, res, deps, agentId, route);
+  const lookup = LOOKUPS[route.kind];
+  if (lookup !== undefined && 'station' in route) return lookup(req, res, deps, route);
+  return handleDetach(req, res, deps, agentId, route);
+}
+
+export async function handleAccountRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  agentId: string,
+  route: AccountRoute,
+): Promise<void> {
+  try {
+    await dispatchRoute(req, res, deps, agentId, route);
+  } catch (err) {
+    apiFailure(req, res, err);
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/agents/admin.ts

@@ -0,0 +1,30 @@
+import { randomBytes } from 'node:crypto';
+import { ApiError } from '@metro-labs/http/api-error';
+import { AGENT_NAME_RE } from '@metro-labs/core/ids';
+
+export class AgentAdminError extends ApiError {}
+
+export interface AgentSummary {
+  id: string;
+  name: string | null;
+}
+
+export interface CreatedAgent {
+  id: string;
+  name: string | null;
+  key: string;
+}
+
+export function normalizeAgentName(raw: unknown): string {
+  const name = typeof raw === 'string' ? raw.trim() : '';
+  if (!AGENT_NAME_RE.test(name))
+    throw new AgentAdminError(
+      'name must be 2-32 characters of A-Z, a-z, 0-9, - or _, starting with a letter or digit',
+      400,
+    );
+  return name;
+}
+
+export function newApiKey(): string {
+  return `mk_${randomBytes(32).toString('base64url')}`;
+}

package/runtime/node_modules/@metro-labs/daemon/src/agents/allowlist.ts

@@ -0,0 +1,59 @@
+import { ApiError } from '@metro-labs/http/api-error';
+
+const EVERYONE = '*';
+const MAX_ENTRIES = 500;
+const MAX_LENGTH = 200;
+
+function hasControlChar(value: string): boolean {
+  for (const ch of value) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+const DOMAIN_ENTRY_RE = /^@[a-z0-9-]+(\.[a-z0-9-]+)+$/;
+
+function domainEntry(value: string): string {
+  const domain = value.toLowerCase();
+  if (!DOMAIN_ENTRY_RE.test(domain))
+    throw new ApiError(`'${value}' is not a domain; write it as @example.com`, 400);
+  return domain;
+}
+
+function senderId(entry: unknown): string {
+  if (typeof entry !== 'string') throw new ApiError('allowlist must be a list of sender ids', 400);
+  const value = entry.trim();
+  if (value.length > MAX_LENGTH || hasControlChar(value))
+    throw new ApiError(`a sender id is at most ${String(MAX_LENGTH)} plain characters`, 400);
+  return value.startsWith('@') ? domainEntry(value) : value;
+}
+
+export function normalizeApprovers(raw: unknown, allowlist: string[]): string[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) throw new ApiError('approvers must be a list of sender ids', 400);
+  const listed = new Set(allowlist.map((entry) => entry.toLowerCase()));
+  const seen = new Set<string>();
+  return raw.map(senderId).filter((value) => {
+    const key = value.toLowerCase();
+    if (!listed.has(key) || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function normalizeAllowlist(raw: unknown): string[] {
+  if (!Array.isArray(raw)) throw new ApiError('allowlist must be a list of sender ids', 400);
+  if (raw.length > MAX_ENTRIES) throw new ApiError(`allowlist holds at most ${String(MAX_ENTRIES)} senders`, 400);
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const entry of raw) {
+    const value = senderId(entry);
+    if (value === EVERYONE) return [EVERYONE];
+    const key = value.toLowerCase();
+    if (key === '' || seen.has(key)) continue;
+    seen.add(key);
+    out.push(value);
+  }
+  return out.length === 0 ? [EVERYONE] : out;
+}

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

@@ -0,0 +1,131 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { parseId } from '@metro-labs/core/ids';
+import {
+  apiFailure,
+  apiSession,
+  cors,
+  sendJson,
+} from '@metro-labs/http/api-http';
+import { ATTACHABLE, handleAccountRoute, type AccountApiDeps } from './accounts-api.js';
+import {
+  accountRoute,
+  accountRouteAllows,
+  type AccountRoute,
+} from './account-routes.js';
+import type { AgentSummary } from './admin.js';
+
+const PREFIX = '/api/agents';
+
+export interface AgentApiDeps extends AccountApiDeps {
+  listAgents: () => Promise<AgentSummary[]>;
+  gatherAccounts: (allowed: Set<string>) => Promise<{
+    accounts: Record<string, unknown[]>;
+    unavailable: string[];
+  }>;
+  capabilities: () => Record<string, string[]>;
+  toolGroups?: () => Record<string, { name: string; group: string }[]>;
+  attachable?: string[];
+  connectorIds: (agentIds: string[]) => Promise<Map<string, string[]>>;
+}
+
+type Routable =
+  | { kind: 'collection' }
+  | { kind: 'accounts'; id: string; route: AccountRoute };
+
+type Target = Routable | { kind: 'unknown' } | null;
+
+function subTarget(id: string, rest: string[]): Target {
+  if (rest[0] !== 'accounts') return { kind: 'unknown' };
+  const route = accountRoute(rest.slice(1));
+  return route === null ? { kind: 'unknown' } : { kind: 'accounts', id, route };
+}
+
+export function target(path: string): Target {
+  if (path === PREFIX || path === `${PREFIX}/`) return { kind: 'collection' };
+  if (!path.startsWith(`${PREFIX}/`)) return null;
+  const segments = path.slice(PREFIX.length + 1).split('/').filter(Boolean);
+  const head = segments[0];
+  if (head === undefined) return { kind: 'collection' };
+  const id = parseId(head);
+  return id === null ? { kind: 'unknown' } : subTarget(id, segments.slice(1));
+}
+
+function agentPayload(agent: AgentSummary, connectors: Map<string, string[]>): Record<string, unknown> {
+  return { id: agent.id, name: agent.name, connector_ids: connectors.get(agent.id) ?? [] };
+}
+
+function wantsAccounts(req: IncomingMessage): boolean {
+  const query = (req.url ?? '').split('?')[1] ?? '';
+  return new URLSearchParams(query).get('accounts') === '1';
+}
+
+async function handleList(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+): Promise<void> {
+  const list = await deps.listAgents();
+  const connectors = await deps.connectorIds(list.map((a) => a.id));
+  const base = {
+    agents: list.map((a) => agentPayload(a, connectors)),
+    capabilities: deps.capabilities(),
+    attachable: deps.attachable ?? ATTACHABLE,
+    ...(deps.toolGroups === undefined ? {} : { tools: deps.toolGroups() }),
+  };
+  if (!wantsAccounts(req)) {
+    sendJson(req, res, 200, base);
+    return;
+  }
+  const { accounts, unavailable } = await deps.gatherAccounts(
+    new Set(list.map((a) => a.id)),
+  );
+  sendJson(req, res, 200, { ...base, accounts, unavailable });
+}
+
+const ALLOWED_LIST = ['GET'];
+
+function methodAllowed(tgt: Routable, method: string | undefined): boolean {
+  if (tgt.kind === 'accounts') return accountRouteAllows(tgt.route, method);
+  return ALLOWED_LIST.includes(method ?? '');
+}
+
+async function dispatch(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+  tgt: Routable,
+): Promise<void> {
+  const session = await apiSession(req);
+  if (!session) {
+    sendJson(req, res, 401, { error: 'unauthorized' });
+    return;
+  }
+  if (tgt.kind === 'accounts') await handleAccountRoute(req, res, deps, tgt.id, tgt.route);
+  else await handleList(req, res, deps);
+}
+
+export function handleAgentApiRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AgentApiDeps,
+): boolean {
+  const tgt = target((req.url ?? '').split('?')[0] ?? '');
+  if (tgt === null) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (tgt.kind === 'unknown') {
+    sendJson(req, res, 404, { error: 'no such agent' });
+    return true;
+  }
+  if (!methodAllowed(tgt, req.method)) {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  dispatch(req, res, deps, tgt).catch((err: unknown) => {
+    if (res.headersSent) return;
+    apiFailure(req, res, err, 'agent-api');
+  });
+  return true;
+}