@stage-labs/metro 0.1.0-beta.9 → 0.1.0-beta.91

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

@@ -0,0 +1,368 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { normalizeAllowlist } from './allowlist.js';
+import type { RecentSender } from './senders.js';
+import { ApiError } from '@metro-labs/http/api-error';
+import {
+  apiFailure,
+  bodyField,
+  readJsonBody,
+  sendJson,
+  type ApiSession,
+} from '@metro-labs/http/api-http';
+import {
+  isStationName,
+  parseAccountId,
+  type AccountRef,
+} from './account-attach.js';
+import type { StationName } from '@metro-labs/core/station-names';
+import {
+  ATTACHABLE_STATIONS,
+  isAttachStation,
+  type AttachInput,
+  type OneTimeSecret,
+  type PreparedAccount,
+} from '../stations/attach.js';
+import {
+  INTERACTIVE_STATIONS,
+  isInteractiveStation,
+  type InteractiveStation,
+} from '../stations/attach-interactive.js';
+import {
+  ATTACH_ID_RE,
+  type AttachOwner,
+  type AttachView,
+} from '../stations/attach-session.js';
+
+export 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: { code?: unknown; password?: unknown },
+  ) => Promise<AttachView>;
+  cancel: (owner: AttachOwner, attachId: string) => Promise<void>;
+}
+
+export interface AccountApiDeps {
+  attachSessions: AttachSessionApi;
+  prepareAccount: (input: AttachInput) => Promise<PreparedAccount>;
+  attachAccount: (
+    subject: string,
+    agentId: string,
+    station: StationName,
+    config: Record<string, unknown>,
+  ) => Promise<AccountRef>;
+  detachAccount: (
+    subject: string,
+    agentId: string,
+    station: StationName,
+    accountId: string,
+  ) => Promise<AccountRef>;
+  syncStations: (station: StationName) => Promise<void>;
+  reloadAgents: () => Promise<void>;
+  setAllowlist: (
+    subject: string,
+    agentId: string,
+    station: StationName,
+    accountId: string,
+    allowlist: string[],
+  ) => Promise<string[]>;
+  recentSenders: (station: StationName, accountId: string) => RecentSender[];
+}
+
+export type AccountRoute =
+  | { kind: 'start' }
+  | { kind: 'session'; attachId: string }
+  | { kind: 'step'; attachId: string }
+  | { kind: 'account'; station: StationName; accountId: string }
+  | { kind: 'allowlist'; station: StationName; accountId: string }
+  | { kind: 'senders'; station: StationName; accountId: string };
+
+export const ATTACHABLE: string[] = [
+  ...ATTACHABLE_STATIONS,
+  ...INTERACTIVE_STATIONS,
+];
+
+const ROUTE_METHODS: Record<AccountRoute['kind'], string[]> = {
+  start: ['POST'],
+  session: ['GET', 'DELETE'],
+  step: ['POST'],
+  account: ['DELETE'],
+  allowlist: ['PUT'],
+  senders: ['GET'],
+};
+
+function twoSegmentRoute(head: string, tail: string): AccountRoute | null {
+  if (ATTACH_ID_RE.test(head))
+    return tail === 'step' ? { kind: 'step', attachId: head } : null;
+  if (!isStationName(head)) return null;
+  const accountId = parseAccountId(tail);
+  return accountId === null ? null : { kind: 'account', station: head, accountId };
+}
+
+export function accountRoute(rest: string[]): AccountRoute | null {
+  const [head, tail] = rest;
+  if (head === undefined) return null;
+  if (rest.length === 1)
+    return head === 'start'
+      ? { kind: 'start' }
+      : ATTACH_ID_RE.test(head)
+        ? { kind: 'session', attachId: head }
+        : null;
+  if (rest.length === 3 && tail !== undefined) return accountSubRoute(head, tail, rest[2]);
+  if (rest.length !== 2 || tail === undefined) return null;
+  return twoSegmentRoute(head, tail);
+}
+
+function accountSubRoute(head: string, tail: string, sub: string | undefined): AccountRoute | null {
+  if (!isStationName(head) || (sub !== 'allowlist' && sub !== 'senders')) return null;
+  const accountId = parseAccountId(tail);
+  return accountId === null ? null : { kind: sub, station: head, accountId };
+}
+
+export function accountRouteAllows(
+  route: AccountRoute,
+  method: string | undefined,
+): boolean {
+  return ROUTE_METHODS[route.kind].includes(method ?? '');
+}
+
+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,
+  session: ApiSession,
+  agentId: string,
+  station: StationName,
+  prepared: PreparedAccount,
+): Promise<AccountRef> {
+  try {
+    return await deps.attachAccount(
+      session.subject,
+      agentId,
+      station,
+      prepared.config,
+    );
+  } catch (err) {
+    prepared.discard?.();
+    throw err;
+  }
+}
+
+function ownerOf(session: ApiSession, agentId: string): AttachOwner {
+  return { subject: session.subject, agentId };
+}
+
+function asInput(body: unknown): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of ['apiId', 'apiHash', 'phone'])
+    out[key] = bodyField(body, key);
+  return out;
+}
+
+async function handleStart(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const station = bodyField(body, 'station');
+  if (isInteractiveStation(station)) {
+    const view = await deps.attachSessions.start(
+      ownerOf(session, 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({
+    station,
+    token: bodyField(body, 'token'),
+  });
+  const ref = await storeAccount(deps, session, 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,
+  session: ApiSession,
+  agentId: string,
+  target: { station: StationName; accountId: string },
+): Promise<void> {
+  const ref = await deps.detachAccount(
+    session.subject,
+    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),
+  });
+}
+
+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,
+  session: ApiSession,
+  agentId: string,
+  target: { station: StationName; accountId: string },
+): Promise<void> {
+  const wanted = normalizeAllowlist(bodyField(await readJsonBody(req), 'allowlist'));
+  const allowlist = await deps.setAllowlist(session.subject, agentId, target.station, target.accountId, wanted);
+  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,
+    activated: await applied(deps),
+  });
+}
+
+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 view = await deps.attachSessions.submit(owner, attachId, {
+    code: bodyField(body, 'code'),
+    password: bodyField(body, 'password'),
+  });
+  sendJson(req, res, 200, view);
+}
+
+async function dispatchRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+  route: AccountRoute,
+): Promise<void> {
+  if (route.kind === 'start')
+    return handleStart(req, res, deps, session, agentId);
+  if (route.kind === 'session')
+    return handleSession(
+      req,
+      res,
+      deps,
+      ownerOf(session, agentId),
+      route.attachId,
+    );
+  if (route.kind === 'step')
+    return handleStep(req, res, deps, ownerOf(session, agentId), route.attachId);
+  if (route.kind === 'allowlist') return handleAllowlist(req, res, deps, session, agentId, route);
+  if (route.kind === 'senders') {
+    sendJson(req, res, 200, { senders: deps.recentSenders(route.station, route.accountId) });
+    return;
+  }
+  return handleDetach(req, res, deps, session, agentId, route);
+}
+
+export async function handleAccountRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+  route: AccountRoute,
+): Promise<void> {
+  try {
+    await dispatchRoute(req, res, deps, session, agentId, route);
+  } catch (err) {
+    apiFailure(req, res, err);
+  }
+}

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

@@ -0,0 +1,43 @@
+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;
+  owned: boolean;
+  key: string | null;
+}
+
+export interface CreatedAgent {
+  id: string;
+  name: string;
+  key: string;
+}
+
+export interface OwnedAgent {
+  id: string;
+  name: string;
+}
+
+export type DeletedAgent = OwnedAgent;
+
+export interface ResetAgentKey extends OwnedAgent {
+  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,37 @@
+import { ApiError } from '@metro-labs/http/api-error';
+
+export 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;
+}
+
+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;
+}
+
+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;
+}