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

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

@@ -0,0 +1,125 @@
+import { kindOf } from '@metro-labs/core/stations/attachments';
+import type { AttachmentMeta, MailItem } from '@metro-labs/core/stations/mail';
+import { decodeEntities, htmlToText, tidy } from '@metro-labs/core/stations/mail-text';
+import { firstHeader, type MailHeader } from '@metro-labs/core/stations/mail-trust';
+
+export interface GmailPart {
+  mimeType?: string;
+  filename?: string;
+  headers?: MailHeader[];
+  body?: { attachmentId?: string; size?: number; data?: string };
+  parts?: GmailPart[];
+}
+
+export interface GmailMessage {
+  id: string;
+  threadId?: string;
+  labelIds?: string[];
+  snippet?: string;
+  internalDate?: string;
+  payload?: GmailPart;
+}
+
+export interface MailFile extends AttachmentMeta {
+  attachmentId: string | null;
+  data: string | null;
+}
+
+export interface Person {
+  address: string;
+  name: string;
+}
+
+export const LIST_HEADERS = ['From', 'To', 'Cc', 'Subject', 'Message-ID'];
+
+export const headersOf = (m: GmailMessage): MailHeader[] => m.payload?.headers ?? [];
+
+export const headerOf = (m: GmailMessage, name: string): string => firstHeader(headersOf(m), name.toLowerCase()) ?? '';
+
+const splitList = (value: string): string[] =>
+  (value.match(/(?:"(?:[^"\\]|\\.)*"|<[^>]*>|[^,"<])+/g) ?? []).map((s) => s.trim()).filter((s) => s !== '');
+
+export function personOf(raw: string): Person {
+  const angle = /<([^<>]*)>\s*$/.exec(raw);
+  if (angle === null) return { address: raw.replace(/\([^()]*\)/g, '').trim().toLowerCase(), name: '' };
+  const name = raw.slice(0, angle.index).trim().replace(/^"(.*)"$/, '$1').replace(/\\(.)/g, '$1');
+  return { address: (angle[1] ?? '').trim().toLowerCase(), name };
+}
+
+export const peopleOf = (value: string): Person[] => splitList(value).map(personOf).filter((p) => p.address.includes('@'));
+
+const addressesOf = (value: string): string[] => peopleOf(value).map((p) => p.address);
+
+function flatten(part: GmailPart | undefined): GmailPart[] {
+  return part === undefined ? [] : [part, ...(part.parts ?? []).flatMap(flatten)];
+}
+
+const isFile = (p: GmailPart): boolean => (p.filename ?? '') !== '';
+
+function charsetOf(part: GmailPart): string {
+  const type = firstHeader(part.headers ?? [], 'content-type') ?? '';
+  return /charset="?([^";\s]+)/i.exec(type)?.[1] ?? 'utf-8';
+}
+
+function decoded(part: GmailPart): string {
+  const bytes = Buffer.from(part.body?.data ?? '', 'base64url');
+  try {
+    return new TextDecoder(charsetOf(part)).decode(bytes);
+  } catch {
+    return bytes.toString('utf8');
+  }
+}
+
+export const unloadedBodies = (m: GmailMessage): GmailPart[] =>
+  flatten(m.payload).filter((p) => !isFile(p) && (p.mimeType ?? '').startsWith('text/') && (p.body?.data ?? '') === '' && (p.body?.attachmentId ?? '') !== '');
+
+export function textOf(m: GmailMessage): string {
+  const parts = flatten(m.payload).filter((p) => !isFile(p) && (p.body?.data ?? '') !== '');
+  const plain = parts.find((p) => p.mimeType === 'text/plain');
+  if (plain !== undefined) return tidy(decoded(plain));
+  const html = parts.find((p) => p.mimeType === 'text/html');
+  return html === undefined ? '' : htmlToText(decoded(html));
+}
+
+export const mailFilesOf = (m: GmailMessage): MailFile[] =>
+  flatten(m.payload)
+    .filter(isFile)
+    .map((p) => {
+      const name = p.filename ?? 'attachment';
+      const mime = p.mimeType ?? 'application/octet-stream';
+      return {
+        attachmentId: p.body?.attachmentId ?? null,
+        data: p.body?.data ?? null,
+        name,
+        mime,
+        kind: kindOf(mime, name),
+        ...(typeof p.body?.size === 'number' ? { size: p.body.size } : {}),
+      };
+    });
+
+export const metaOf = (f: MailFile): AttachmentMeta => ({
+  kind: f.kind,
+  name: f.name,
+  mime: f.mime,
+  ...(f.size === undefined ? {} : { size: f.size }),
+});
+
+export function itemOf(m: GmailMessage): MailItem {
+  const from = personOf(headerOf(m, 'From'));
+  const at = Number(m.internalDate);
+  return {
+    id: m.id,
+    threadId: m.threadId ?? m.id,
+    subject: headerOf(m, 'Subject').trim(),
+    from: from.address,
+    fromName: from.name,
+    to: addressesOf(headerOf(m, 'To')),
+    cc: addressesOf(headerOf(m, 'Cc')),
+    date: Number.isFinite(at) && at > 0 ? new Date(at).toISOString() : null,
+    preview: decodeEntities(m.snippet ?? '').trim(),
+    text: textOf(m),
+    hasAttachments: mailFilesOf(m).length > 0 || m.payload?.mimeType === 'multipart/mixed',
+    isRead: !(m.labelIds ?? []).includes('UNREAD'),
+    internetMessageId: headerOf(m, 'Message-ID') || null,
+  };
+}

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

@@ -0,0 +1,70 @@
+import { randomBytes } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { kindOf } from '@metro-labs/core/stations/attachments';
+import type { OutgoingFile } from '@metro-labs/core/stations/mail';
+
+export interface Draft {
+  from: string;
+  to: string[];
+  cc: string[];
+  subject: string;
+  text: string;
+  inReplyTo: string;
+  references: string;
+  files: OutgoingFile[];
+}
+
+const CRLF = '\r\n';
+
+const oneLine = (v: string): string => v.replace(/[\r\n]+/g, ' ').trim();
+const isAscii = (v: string): boolean => /^[\x20-\x7e]*$/.test(v);
+const WORD_BYTES = 45;
+const FOLD = `${CRLF} `;
+
+function utf8Chunks(v: string): string[] {
+  const chunks = [''];
+  for (const ch of v) {
+    const last = chunks.length - 1;
+    if (Buffer.byteLength((chunks[last] ?? '') + ch) > WORD_BYTES) chunks.push(ch);
+    else chunks[last] = (chunks[last] ?? '') + ch;
+  }
+  return chunks;
+}
+
+const encodedWord = (v: string): string =>
+  isAscii(v) ? v : utf8Chunks(v).map((c) => `=?UTF-8?B?${Buffer.from(c, 'utf8').toString('base64')}?=`).join(FOLD);
+const quoted = (v: string): string => `"${v.replace(/["\\]/g, '\\$&')}"`;
+const base64Lines = (data: Buffer): string => data.toString('base64').replace(/.{1,76}/g, `$&${CRLF}`);
+export const boundaryOf = (): string => `metro_${randomBytes(12).toString('hex')}`;
+
+function fileHeaders(file: OutgoingFile): string[] {
+  const name = oneLine(file.name);
+  const typeName = isAscii(name) ? quoted(name) : quoted(encodedWord(name));
+  const disposition = isAscii(name) ? `filename=${quoted(name)}` : `filename*=UTF-8''${encodeURIComponent(name)}`;
+  return [`Content-Type: ${oneLine(file.mime)}; name=${typeName}`, `Content-Disposition: attachment; ${disposition}`, 'Content-Transfer-Encoding: base64'];
+}
+
+const part = (headers: string[], body: Buffer): string => [...headers, '', base64Lines(body)].join(CRLF);
+
+export async function buildMime(d: Draft): Promise<{ mime: string; labels: string[] }> {
+  const head = [
+    `From: ${d.from}`,
+    `To: ${d.to.join(`,${FOLD}`)}`,
+    ...(d.cc.length > 0 ? [`Cc: ${d.cc.join(`,${FOLD}`)}`] : []),
+    `Subject: ${encodedWord(oneLine(d.subject))}`,
+    ...(d.inReplyTo === '' ? [] : [`In-Reply-To: ${oneLine(d.inReplyTo)}`]),
+    ...(d.references === '' ? [] : [`References: ${oneLine(d.references).split(/\s+/).join(FOLD)}`]),
+    'MIME-Version: 1.0',
+  ];
+  const text = part(['Content-Type: text/plain; charset="UTF-8"', 'Content-Transfer-Encoding: base64'], Buffer.from(d.text, 'utf8'));
+  if (d.files.length === 0) return { mime: [...head, text].join(CRLF), labels: [] };
+  const boundary = boundaryOf();
+  const parts = [text];
+  const labels: string[] = [];
+  for (const file of d.files) {
+    parts.push(part(fileHeaders(file), await readFile(file.path)));
+    labels.push(kindOf(file.mime, file.path));
+  }
+  const body = [...parts.map((p) => `--${boundary}${CRLF}${p}`), `--${boundary}--`, ''];
+  return { mime: [...head, `Content-Type: multipart/mixed; boundary="${boundary}"`, '', ...body].join(CRLF), labels };
+}

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,43 @@
+{
+  "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-delivery": "./src/connector-delivery.ts",
+    "./connector-migration": "./src/connector-migration.ts",
+    "./connector-grant": "./src/connector-grant.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,110 @@
+import { createHash, createPublicKey, diffieHellman, generateKeyPairSync, 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;
+}
+
+type Curve = 'Ed25519' | 'X25519';
+
+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, curve: Curve): 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: curve, x: raw }, format: 'jwk' });
+    return key.asymmetricKeyType === curve.toLowerCase() ? key : null;
+  } catch {
+    return null;
+  }
+}
+
+export function signingKeyOf(raw: string): KeyObject | null {
+  const key = publicKeyOf(raw, 'Ed25519');
+  return key !== null && strongEd25519(Buffer.from(raw, 'base64url')) ? key : null;
+}
+
+function contributes(key: KeyObject): boolean {
+  try {
+    return diffieHellman({ privateKey: generateKeyPairSync('x25519').privateKey, publicKey: key }).some((byte) => byte !== 0);
+  } catch {
+    return false;
+  }
+}
+
+export function sealingKeyOf(raw: string): KeyObject | null {
+  const key = publicKeyOf(raw, 'X25519');
+  return key !== null && contributes(key) ? 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'));
+}