@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

package/runtime/node_modules/@metro-labs/gmail/src/outbound.ts

@@ -0,0 +1,125 @@
+import { checkAddress, filesOf, isAddress, isEmailAddress, mailLine, str, subjectOf, threadOfLine, type OutgoingFile } from '@metro-labs/core/stations/mail';
+import { respond } from '@metro-labs/core/stations/station-runtime';
+import { TrainError } from '@metro-labs/core/train-error';
+import { accountOf, type Account } from './accounts.js';
+import { gmailJson, queryOf, USER } from './api.js';
+import { assertSendable } from './attachments.js';
+import { headerOf, peopleOf, personOf, type GmailMessage } from './message.js';
+import { boundaryOf, buildMime } from './mime.js';
+
+type Args = Record<string, unknown>;
+
+interface Sent {
+  id?: string;
+  threadId?: string;
+}
+
+const REPLY_HEADERS = ['From', 'To', 'Cc', 'Reply-To', 'Subject', 'Message-ID', 'References'];
+
+const metadata = (): [string, string][] => [['format', 'metadata'], ...REPLY_HEADERS.map((h): [string, string] => ['metadataHeaders', h])];
+
+async function sendMime(acct: Account, mime: string, threadId: string | null): Promise<Sent> {
+  const boundary = boundaryOf();
+  const body = [
+    `--${boundary}`,
+    'Content-Type: application/json; charset=UTF-8',
+    '',
+    JSON.stringify(threadId === null ? {} : { threadId }),
+    `--${boundary}`,
+    'Content-Type: message/rfc822',
+    '',
+    mime,
+    `--${boundary}--`,
+    '',
+  ].join('\r\n');
+  return gmailJson<Sent>(acct, `/upload${USER}/messages/send?uploadType=multipart`, {
+    method: 'POST',
+    headers: { 'content-type': `multipart/related; boundary=${boundary}` },
+    body,
+  });
+}
+
+async function latestIn(acct: Account, threadId: string): Promise<GmailMessage> {
+  const thread = await gmailJson<{ messages?: GmailMessage[] }>(acct, `${USER}/threads/${encodeURIComponent(threadId)}?${queryOf(metadata())}`);
+  const latest = (thread.messages ?? []).filter((m) => !(m.labelIds ?? []).includes('DRAFT')).at(-1);
+  if (latest === undefined) throw new TrainError('gmail_empty_conversation', 'Gmail has no message in this thread to answer', { retryable: false });
+  return latest;
+}
+
+const addresses = (m: GmailMessage, name: string): string[] => peopleOf(headerOf(m, name)).map((p) => p.address);
+
+export function recipientsOf(m: GmailMessage, self: string, all: boolean): { to: string[]; cc: string[] } {
+  const others = (list: string[]): string[] => list.filter((a) => a !== self && isEmailAddress(a));
+  const from = personOf(headerOf(m, 'From')).address;
+  const replyTo = others(addresses(m, 'Reply-To'));
+  const sender = from === self ? others(addresses(m, 'To')) : replyTo.length > 0 ? replyTo : others([from]);
+  const to = [...new Set(all ? [...sender, ...others(addresses(m, 'To'))] : sender)];
+  const cc = all ? others(addresses(m, 'Cc')).filter((a) => !to.includes(a)) : [];
+  if (to.length === 0) throw new TrainError('gmail_no_recipient', 'this mail names nobody to answer', { retryable: false });
+  return { to, cc };
+}
+
+export const replySubject = (subject: string): string => (/^re:/i.test(subject.trim()) ? subject.trim() : `Re: ${subject.trim()}`.trim());
+
+interface Outgoing {
+  target: string;
+  acct: Account;
+  files: OutgoingFile[];
+  text: string;
+  replyTo: string;
+}
+
+async function outgoing(args: Args): Promise<Outgoing> {
+  const line = str(args.line);
+  const parsed = threadOfLine('gmail', line);
+  if (parsed === null) throw new TrainError('gmail_bad_line', `not a valid gmail line: ${line}`, { retryable: false });
+  const acct = accountOf(args);
+  if (acct.cfg.sendEnabled === false) throw new TrainError('gmail_read_only', 'This Gmail connection is read-only. Allow sending with Google in channel settings, then choose a Metro write policy.', { retryable: false });
+  const files = filesOf(args.attachments);
+  const text = typeof args.text === 'string' ? args.text : '';
+  if (text.trim() === '' && files.length === 0) throw new TrainError('gmail_text_required', 'give some text or a file to send', { retryable: false });
+  await assertSendable(files);
+  return { target: parsed.threadId, acct, files, text, replyTo: str(args.replyTo) };
+}
+
+async function compose(id: string, out: Outgoing, args: Args): Promise<void> {
+  const to = out.target.toLowerCase();
+  checkAddress('gmail', to);
+  const subject = subjectOf('gmail', str(args.subject), out.text);
+  const { mime, labels } = await buildMime({ from: out.acct.email, to: [to], cc: [], subject, text: out.text, inReplyTo: '', references: '', files: out.files });
+  const sent = await sendMime(out.acct, mime, null);
+  const line = sent.threadId === undefined ? undefined : mailLine('gmail', out.acct.id, sent.threadId);
+  respond(id, { result: { account: out.acct.id, messageId: sent.id, ...(line === undefined ? {} : { line }), ...(labels.length > 0 ? { attachments: labels } : {}) } });
+}
+
+async function answer(id: string, args: Args, all: boolean): Promise<void> {
+  const out = await outgoing(args);
+  if (isAddress(out.target)) {
+    if (!all || out.replyTo !== '')
+      throw new TrainError('gmail_reply_needs_thread', "reply on the thread's own line; an address line starts a new email", { retryable: false });
+    await compose(id, out, args);
+    return;
+  }
+  const m =
+    out.replyTo === ''
+      ? await latestIn(out.acct, out.target)
+      : await gmailJson<GmailMessage>(out.acct, `${USER}/messages/${encodeURIComponent(out.replyTo)}?${queryOf(metadata())}`);
+  const { to, cc } = recipientsOf(m, out.acct.email, all);
+  const messageId = headerOf(m, 'Message-ID');
+  const { mime, labels } = await buildMime({
+    from: out.acct.email,
+    to,
+    cc,
+    subject: replySubject(headerOf(m, 'Subject')),
+    text: out.text,
+    inReplyTo: messageId,
+    references: `${headerOf(m, 'References')} ${messageId}`.trim(),
+    files: out.files,
+  });
+  const sent = await sendMime(out.acct, mime, m.threadId ?? out.target);
+  respond(id, { result: { account: out.acct.id, repliedTo: m.id, messageId: sent.id, ...(labels.length > 0 ? { attachments: labels } : {}) } });
+}
+
+export const reply = (id: string, args: Args): Promise<void> => answer(id, args, false);
+
+export const send = (id: string, args: Args): Promise<void> => answer(id, args, str(args.replyTo) === '');

package/runtime/node_modules/@metro-labs/gmail/src/query.ts

@@ -0,0 +1,101 @@
+import { mailFull, mailSummary, MAX_LIMIT, readQueryOf, str, type MailItem, type ReadQuery } from '@metro-labs/core/stations/mail';
+import { respond } from '@metro-labs/core/stations/station-runtime';
+import { accountOf, type Account } from './accounts.js';
+import { gmailJson, queryOf, USER } from './api.js';
+import { saveFile, withBodies } from './attachments.js';
+import { itemOf, LIST_HEADERS, mailFilesOf, type GmailMessage } from './message.js';
+
+type Args = Record<string, unknown>;
+
+const BATCH = 10;
+
+const listing = (): [string, string][] => [['format', 'metadata'], ...LIST_HEADERS.map((h): [string, string] => ['metadataHeaders', h])];
+
+const messagePath = (messageId: string, params: [string, string][]): string => `${USER}/messages/${encodeURIComponent(messageId)}?${queryOf(params)}`;
+
+const seconds = (iso: string): string => String(Math.floor(Date.parse(iso) / 1000));
+
+const untilOf = (q: ReadQuery, beforeAt: string): string | undefined => [q.until, beforeAt].filter((s) => s !== '').sort()[0];
+
+export function searchOf(q: ReadQuery, beforeAt: string): string {
+  const until = untilOf(q, beforeAt);
+  return [
+    q.query,
+    q.from === '' ? '' : `from:${q.from}`,
+    q.since === '' ? '' : `after:${seconds(q.since)}`,
+    until === undefined ? '' : `before:${seconds(until)}`,
+    q.unreadOnly ? 'is:unread' : '',
+  ]
+    .filter((s) => s !== '')
+    .join(' ');
+}
+
+function matches(q: ReadQuery, m: MailItem, beforeAt: string): boolean {
+  if (q.from !== '' && m.from !== q.from) return false;
+  if (q.unreadOnly && m.isRead) return false;
+  const at = Date.parse(m.date ?? '');
+  if (q.since !== '' && at < Date.parse(q.since)) return false;
+  const until = untilOf(q, beforeAt);
+  return until === undefined || at < Date.parse(until);
+}
+
+async function receivedAt(acct: Account, messageId: string): Promise<string> {
+  if (messageId === '') return '';
+  const m = await gmailJson<GmailMessage>(acct, messagePath(messageId, [['format', 'minimal']]));
+  return itemOf(m).date ?? '';
+}
+
+async function inThread(acct: Account, q: ReadQuery, threadId: string, beforeAt: string): Promise<MailItem[]> {
+  const thread = await gmailJson<{ messages?: GmailMessage[] }>(acct, `${USER}/threads/${encodeURIComponent(threadId)}?${queryOf(listing())}`);
+  return (thread.messages ?? [])
+    .map(itemOf)
+    .filter((m) => matches(q, m, beforeAt))
+    .reverse();
+}
+
+async function searched(acct: Account, q: ReadQuery, beforeAt: string): Promise<MailItem[]> {
+  const search = searchOf(q, beforeAt);
+  const params: [string, string][] = [...(search === '' ? [] : [['q', search] as [string, string]]), ['maxResults', String(q.threadId === null ? q.limit : MAX_LIMIT)]];
+  const found = await gmailJson<{ messages?: { id: string; threadId?: string }[] }>(acct, `${USER}/messages?${queryOf(params)}`);
+  const ids = (found.messages ?? []).filter((m) => q.threadId === null || m.threadId === q.threadId).slice(0, q.limit);
+  const items: MailItem[] = [];
+  for (let i = 0; i < ids.length; i += BATCH) {
+    const batch = ids.slice(i, i + BATCH).map((m) => gmailJson<GmailMessage>(acct, messagePath(m.id, listing())));
+    items.push(...(await Promise.all(batch)).map(itemOf));
+  }
+  return items;
+}
+
+async function list(id: string, acct: Account, q: ReadQuery): Promise<void> {
+  const beforeAt = await receivedAt(acct, q.before);
+  const found = q.threadId !== null && q.query === '' ? await inThread(acct, q, q.threadId, beforeAt) : await searched(acct, q, beforeAt);
+  acct.check();
+  respond(id, {
+    result: {
+      account: acct.id,
+      mode: q.query === '' ? 'filter' : 'search',
+      messages: found.slice(0, q.limit).map((m) => mailSummary('gmail', acct.id, m)),
+    },
+  });
+}
+
+async function one(id: string, acct: Account, messageId: string): Promise<void> {
+  const m = await withBodies(acct, await gmailJson<GmailMessage>(acct, messagePath(messageId, [['format', 'full']])));
+  const attachments = [];
+  for (const [index, file] of mailFilesOf(m).entries()) {
+    const saved = await saveFile(acct, m.id, file, index);
+    attachments.push({ name: file.name, mime: file.mime, kind: file.kind, size: saved.bytes, local_path: saved.path });
+  }
+  acct.check();
+  respond(id, { result: { account: acct.id, message: { ...mailFull('gmail', acct.id, itemOf(m)), attachments } } });
+}
+
+export async function read(id: string, args: Args): Promise<void> {
+  const acct = accountOf(args);
+  const messageId = str(args.messageId);
+  if (messageId !== '') {
+    await one(id, acct, messageId);
+    return;
+  }
+  await list(id, acct, readQueryOf('gmail', args));
+}

package/runtime/node_modules/@metro-labs/gmail/src/state.ts

@@ -0,0 +1,30 @@
+import { readJson, writeSecure } from '@metro-labs/core/secure-fs';
+import { accountFiles } from '@metro-labs/core/stations/account-files';
+import { seenOf } from '@metro-labs/core/stations/mail';
+import { tokenStateOf, type Tokens } from '@metro-labs/core/stations/oauth';
+
+export interface AccountState extends Tokens {
+  refreshGrant?: string;
+  authorizationId?: string;
+  historyId: string | null;
+  seen: string[];
+}
+
+export const stateFiles = accountFiles('GMAIL_STATE_DIR', 'gmail-state-');
+
+export function loadState(accountId: string, seed: Partial<AccountState>): AccountState {
+  const saved = readJson<Record<string, unknown>>(stateFiles.path(accountId), {});
+  const same = saved.authorizationId === seed.authorizationId;
+  const held = same ? saved : {};
+  return {
+    ...tokenStateOf(held, seed),
+    refreshGrant: typeof held.refreshGrant === 'string' ? held.refreshGrant : seed.refreshGrant,
+    authorizationId: seed.authorizationId,
+    historyId: typeof saved.historyId === 'string' && saved.historyId !== '' ? saved.historyId : null,
+    seen: seenOf(saved.seen),
+  };
+}
+
+export function saveState(accountId: string, state: AccountState): void {
+  writeSecure(stateFiles.path(accountId), JSON.stringify(state));
+}

package/runtime/node_modules/@metro-labs/gmail/src/station.ts

@@ -0,0 +1,16 @@
+import type { ReadFilter, Station, Verb } from '@metro-labs/core/stations/types';
+import { stateFiles } from './state.js';
+
+export const gmailStation: Station = {
+  name: 'gmail',
+  hasAccounts: true,
+  hasTrain: true,
+  discoversChannels: true,
+  messageVerbs: new Set<Verb>(['send', 'reply', 'read']),
+  readFilters: new Set<ReadFilter>(['account', 'query', 'from', 'until', 'unread_only', 'message_id']),
+  approvals: false,
+  attachmentMode: 'canonical',
+  forget: stateFiles.forget,
+  forgetExcept: stateFiles.forgetExcept,
+  tools: [],
+};

package/runtime/node_modules/@metro-labs/gmail/src/trust.ts

@@ -0,0 +1,42 @@
+import { automatedByHeaders, automatedBySender, domainOf, firstHeader, type MailHeader, type Screened } from '@metro-labs/core/stations/mail-trust';
+
+const DMARC = /^dmarc=(\w+) header\.from=([a-z0-9.-]+)$/;
+const DKIM_PASS = /^dkim=pass((?: header\.[a-z]+=[^\s"()]+)+)$/;
+const DKIM_DOMAIN = / header\.(?:i=[^@\s]*@|d=)([a-z0-9.-]+)(?= |$)/g;
+
+function withoutComments(text: string): string {
+  let out = text.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+  for (let before = ''; before !== out; ) {
+    before = out;
+    out = out.replace(/\([^()]*\)/g, ' ');
+  }
+  return out;
+}
+
+function clausesOf(result: string): string[] | null {
+  const clauses = withoutComments(result)
+    .split(';')
+    .map((c) => c.replace(/\s+/g, ' ').trim().toLowerCase());
+  return clauses[0] === 'mx.google.com' ? clauses.slice(1) : null;
+}
+
+const dkimAligned = (clauses: string[], fromDomain: string): boolean =>
+  clauses.some((c) => [...(DKIM_PASS.exec(c)?.[1] ?? '').matchAll(DKIM_DOMAIN)].some((m) => m[1] === fromDomain));
+
+function passes(clauses: string[], fromDomain: string): boolean {
+  const dmarc = clauses.map((c) => DMARC.exec(c)).find((m) => m !== null);
+  if (dmarc?.[2] !== undefined && dmarc[2] !== fromDomain) return false;
+  if (dmarc?.[1] === 'pass') return true;
+  return dmarc?.[1] !== 'fail' && dkimAligned(clauses, fromDomain);
+}
+
+export function senderVerified(headers: MailHeader[], fromAddress: string): boolean {
+  const fromDomain = domainOf(fromAddress);
+  const clauses = clausesOf(firstHeader(headers, 'authentication-results') ?? '');
+  return fromDomain !== '' && clauses !== null && passes(clauses, fromDomain);
+}
+
+export function screen(headers: MailHeader[], from: string, keepAutomated: boolean): Screened {
+  const automated = keepAutomated ? null : (automatedBySender(from) ?? automatedByHeaders(headers));
+  return automated === null ? { verified: senderVerified(headers, from) } : { skip: automated };
+}

package/runtime/node_modules/@metro-labs/http/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@metro-labs/http",
+  "version": "0.1.0",
+  "private": true,
+  "description": "How a metro server authenticates and answers a request: CORS, the JSON helpers, ApiError, the signed-identity header, the identity registry, AWS request signing, the signature a box puts on its requests to api.metro.box, and the connector client both use (url checks, the MCP initialize, OAuth discovery, registration and tokens). Shared by the daemon and api.metro.box, never by a station.",
+  "type": "module",
+  "exports": {
+    "./cors": "./src/cors.ts",
+    "./api-http": "./src/api-http.ts",
+    "./api-error": "./src/api-error.ts",
+    "./return-to": "./src/return-to.ts",
+    "./mode-api": "./src/mode-api.ts",
+    "./workos-token": "./src/workos-token.ts",
+    "./sigv4": "./src/sigv4.ts",
+    "./agent-signature": "./src/agent-signature.ts",
+    "./connector-url": "./src/connector-url.ts",
+    "./connector-public-url": "./src/connector-public-url.ts",
+    "./connector-resource": "./src/connector-resource.ts",
+    "./connector-reach": "./src/connector-reach.ts",
+    "./connector-mcp": "./src/connector-mcp.ts",
+    "./connector-tools": "./src/connector-tools.ts",
+    "./connector-discovery": "./src/connector-discovery.ts",
+    "./connector-oauth": "./src/connector-oauth.ts",
+    "./connector-input": "./src/connector-input.ts",
+    "./connector-policy": "./src/connector-policy.ts",
+    "./connector-grant": "./src/connector-grant.ts",
+    "./mcp-server-protocol": "./src/mcp-server-protocol.ts",
+    "./mcp-server-tools": "./src/mcp-server-tools.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit && bun test test/"
+  },
+  "dependencies": {
+    "@metro-labs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@stage-labs/config": "0.1.0-beta.3",
+    "eslint": "^10.3.0",
+    "knip": "^6.15.0",
+    "madge": "^8.0.0",
+    "typescript": "^5"
+  }
+}

package/runtime/node_modules/@metro-labs/http/src/agent-signature.ts

@@ -0,0 +1,95 @@
+import { createHash, createPublicKey, randomBytes, sign, verify, type KeyObject } from 'node:crypto';
+import { strongEd25519 } from './ed25519.js';
+
+export const AGENT_SCHEME = 'MetroAgent';
+export const AGENT_CLOCK_SKEW_MS = 5 * 60_000;
+
+const VERSION = 'metro-agent-request/v1';
+const KEY_ID_RE = /^[A-Za-z0-9_-]{43}$/;
+const NONCE_RE = /^[A-Za-z0-9_-]{22}$/;
+const SIGNATURE_RE = /^[A-Za-z0-9_-]{86}$/;
+const TIME_RE = /^[0-9]{1,15}$/;
+const RAW_KEY_RE = /^[A-Za-z0-9_-]{43}$/;
+
+export interface AgentRequest {
+  method: string;
+  host: string;
+  path: string;
+  body: Uint8Array;
+}
+
+export interface AgentProof {
+  keyId: string;
+  time: number;
+  nonce: string;
+  signature: string;
+}
+
+const digest = (bytes: Uint8Array): string => createHash('sha256').update(bytes).digest('base64url');
+
+export const agentKeyId = (signingKey: string): string => digest(Buffer.from(signingKey, 'base64url'));
+
+function publicKeyOf(raw: string): KeyObject | null {
+  if (!RAW_KEY_RE.test(raw) || Buffer.from(raw, 'base64url').toString('base64url') !== raw) return null;
+  try {
+    const key = createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: raw }, format: 'jwk' });
+    return key.asymmetricKeyType === 'ed25519' ? key : null;
+  } catch {
+    return null;
+  }
+}
+
+export function signingKeyOf(raw: string): KeyObject | null {
+  const key = publicKeyOf(raw);
+  return key !== null && strongEd25519(Buffer.from(raw, 'base64url')) ? key : null;
+}
+
+export function rawPublicKey(key: KeyObject): string {
+  const { x } = key.export({ format: 'jwk' });
+  if (typeof x !== 'string') throw new Error('not an OKP public key');
+  return x;
+}
+
+function signingInput(request: AgentRequest, proof: Omit<AgentProof, 'signature'>): Buffer {
+  return Buffer.from([
+    VERSION,
+    request.method.toUpperCase(),
+    request.host.toLowerCase(),
+    request.path,
+    proof.keyId,
+    String(proof.time),
+    proof.nonce,
+    digest(request.body),
+  ].join('\n'));
+}
+
+export function signAgentRequest(request: AgentRequest, privateKey: KeyObject, keyId: string, time: number): string {
+  const nonce = randomBytes(16).toString('base64url');
+  const signature = sign(null, signingInput(request, { keyId, time, nonce }), privateKey).toString('base64url');
+  return `${AGENT_SCHEME} ${keyId}.${String(time)}.${nonce}.${signature}`;
+}
+
+const PARTS = [KEY_ID_RE, TIME_RE, NONCE_RE, SIGNATURE_RE];
+
+function partsOf(header: string | undefined): string[] | null {
+  if (header === undefined || header.length > 256) return null;
+  const [scheme, value, extra] = header.trim().split(' ');
+  if (scheme !== AGENT_SCHEME || value === undefined || extra !== undefined) return null;
+  const parts = value.split('.');
+  return parts.length === PARTS.length && parts.every((part, i) => PARTS[i]?.test(part) === true) ? parts : null;
+}
+
+export function readAgentProof(header: string | undefined): AgentProof | null {
+  const parts = partsOf(header);
+  if (parts === null) return null;
+  const [keyId = '', time = '', nonce = '', signature = ''] = parts;
+  return { keyId, time: Number(time), nonce, signature };
+}
+
+export const withinSkew = (time: number, now: number): boolean => Math.abs(now - time) <= AGENT_CLOCK_SKEW_MS;
+
+export function agentSignatureValid(request: AgentRequest, proof: AgentProof, signingKey: string): boolean {
+  const key = signingKeyOf(signingKey);
+  if (key === null || agentKeyId(signingKey) !== proof.keyId) return false;
+  return verify(null, signingInput(request, proof), key, Buffer.from(proof.signature, 'base64url'));
+}

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

@@ -0,0 +1,146 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ApiError } from './api-error.js';
+import { errMsg, log } from '@metro-labs/core/log';
+
+const BODY_MAX = 4 * 1024;
+
+export type Role = 'admin' | 'member';
+
+export interface ApiSession {
+  subject: string;
+  userId?: string;
+  sessionId?: string;
+  role: Role;
+}
+
+export type BearerSessions = (req: IncomingMessage) => Promise<ApiSession | null>;
+
+let bearerSessions: BearerSessions | null = null;
+
+export function setBearerSessions(fn: BearerSessions | null): void {
+  bearerSessions = fn;
+}
+
+const PROXY_HEADERS = ['x-forwarded-for', 'x-forwarded-host', 'tailscale-funnel-request'] as const;
+
+export const cameThroughProxy = (req: IncomingMessage): boolean =>
+  PROXY_HEADERS.some((name) => req.headers[name] !== undefined);
+
+export function requireAdmin(session: ApiSession): void {
+  if (session.role !== 'admin') throw new ApiError('this needs the admin role in your organization', 403);
+}
+
+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): Promise<ApiSession | null> {
+  return bearerSessions === null ? Promise.resolve(null) : bearerSessions(req);
+}
+
+export async function readBodyBytes(req: IncomingMessage, max = BODY_MAX): Promise<Buffer> {
+  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 > max) over = true;
+    if (!over) chunks.push(buf);
+    else if (total > 2 * max) break;
+  }
+  if (over) throw new ApiError('request body too large', 413);
+  return Buffer.concat(chunks);
+}
+
+export async function readJsonBody(req: IncomingMessage, max = BODY_MAX): Promise<unknown> {
+  const raw = (await readBodyBytes(req, max)).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 interface SessionRoute {
+  methods: Readonly<Record<string, readonly string[]>>;
+  admin: boolean | readonly string[];
+  label: string;
+}
+
+const needsAdmin = (route: SessionRoute, method: string): boolean =>
+  route.admin === true || (Array.isArray(route.admin) && route.admin.includes(method));
+
+export function sessionRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  route: SessionRoute,
+  handler: (session: ApiSession, path: string) => Promise<unknown>,
+): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  const methods = Object.hasOwn(route.methods, path) ? route.methods[path] : undefined;
+  if (methods === undefined) return false;
+  const method = req.method ?? '';
+  if (method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (!methods.includes(method)) {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  apiSession(req)
+    .then(async (session) => {
+      if (!session) throw new ApiError('unauthorized', 401);
+      if (needsAdmin(route, method)) requireAdmin(session);
+      sendJson(req, res, 200, await handler(session, path));
+    })
+    .catch((err: unknown) => {
+      apiFailure(req, res, err, route.label);
+    });
+  return true;
+}
+
+export function bodyField(body: unknown, key: string): unknown {
+  return typeof body === 'object' && body !== null && !Array.isArray(body)
+    ? (body as Record<string, unknown>)[key]
+    : undefined;
+}
+
+export const stringOf = (value: unknown): string => (typeof value === 'string' ? value : '');