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

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/channel-pages.ts

@@ -0,0 +1,129 @@
+import { ticketStore } from '../tickets.js';
+import { TrainError } from '../train-error.js';
+import { channelEntry, channelMatches, channelOptions, DIRECTORY_LIMIT, type ChannelEntry, type ChannelList } from './channel-directory.js';
+
+const TTL = 5 * 60 * 1000;
+const MAX_BYTES = 2 * 1024 * 1024;
+const CAP_REASON = 'Stopped after 5000 metadata records or pages; search does not cover the whole mailbox.';
+const SIZE_REASON = 'Directory metadata exceeded the local size or entry limit; search is partial.';
+
+export interface ChannelPage {
+  channels: ChannelEntry[];
+  scanned: number;
+  next?: string;
+}
+
+export type ChannelPageLoader = (token: string | undefined, limit: number, seen: ReadonlySet<string>) => Promise<ChannelPage>;
+
+interface Scan {
+  next?: string;
+  channels: ChannelEntry[];
+  seen: Set<string>;
+  visited: Set<string>;
+  scanned: number;
+  bytes: number;
+  complete: boolean;
+  stopped?: string;
+}
+
+interface Cursor {
+  account: string;
+  query: string;
+  scope: string;
+  expiresAt: number;
+  scan: Scan;
+  loaded?: Promise<Scan>;
+}
+
+function addEntries(scan: Scan, rows: ChannelEntry[], account: string, query: string): void {
+  for (const raw of rows) {
+    const entry = channelEntry(raw, account);
+    if (!entry) {
+      scan.stopped = SIZE_REASON;
+      continue;
+    }
+    if (scan.seen.has(entry.id)) continue;
+    const size = Buffer.byteLength(JSON.stringify(entry)) + Buffer.byteLength(JSON.stringify(entry.id));
+    if (scan.bytes + size > MAX_BYTES) {
+      scan.stopped = SIZE_REASON;
+      break;
+    }
+    scan.bytes += size;
+    scan.seen.add(entry.id);
+    if (channelMatches(raw, query)) scan.channels.push(entry);
+  }
+}
+
+function project(cursor: Cursor, page: ChannelPage): Scan {
+  const scan: Scan = {
+    next: page.next, channels: [], seen: new Set(cursor.scan.seen),
+    visited: new Set(cursor.scan.visited).add(cursor.scan.next ?? ''),
+    scanned: cursor.scan.scanned + page.scanned,
+    bytes: cursor.scan.bytes + Buffer.byteLength(page.next ?? ''), complete: !page.next,
+  };
+  if (page.next && scan.visited.has(page.next)) throw new TrainError('channel_page', 'The mailbox repeated a channel page token.');
+  addEntries(scan, page.channels, cursor.account, cursor.query);
+  if (scan.bytes > MAX_BYTES) scan.stopped = SIZE_REASON;
+  if (page.next && Math.max(scan.scanned, scan.visited.size) >= DIRECTORY_LIMIT) scan.stopped ??= CAP_REASON;
+  if (scan.stopped) {
+    scan.next = undefined;
+    scan.complete = false;
+  }
+  return scan;
+}
+
+export class ChannelPages {
+  private readonly cursors = ticketStore<Cursor>(TTL, 32);
+
+  async list(account: string, args: Record<string, unknown>, load: ChannelPageLoader, scope: string): Promise<ChannelList> {
+    const { query, limit, cursor: ticket } = channelOptions(args);
+    const cursor: Cursor = ticket === undefined
+      ? {
+        account, query, scope, expiresAt: Date.now() + TTL,
+        scan: { channels: [], seen: new Set(), visited: new Set(), scanned: 0, bytes: Buffer.byteLength(account + query + scope), complete: false },
+      }
+      : this.resume(ticket, account, query);
+    const scan = await this.load(cursor, load);
+    if (cursor.expiresAt <= Date.now()) throw new TrainError('channel_cursor', 'Channel listing expired; start a new listing.');
+    const channels = scan.channels.slice(0, limit);
+    const remaining = scan.channels.slice(channels.length);
+    const more = remaining.length > 0 || (!scan.complete && !scan.stopped);
+    const next = more ? this.cursors.mint({ ...cursor, scan: { ...scan, channels: remaining }, loaded: undefined }).ticket : undefined;
+    return {
+      channels: channels.map((entry) => ({ ...entry })),
+      capability: {
+        supported: true, complete: scan.complete && !more, source: 'remote',
+        reason: [cursor.scope, scan.stopped, more ? 'More metadata remains; follow next_cursor, even after an empty page.' : ''].filter(Boolean).join(' '),
+      },
+      ...(next === undefined ? {} : { next_cursor: next }),
+    };
+  }
+
+  private resume(ticket: string, account: string, query: string): Cursor {
+    const cursor = this.cursors.peek(ticket);
+    if (!cursor || cursor.account !== account || cursor.query !== query || cursor.expiresAt <= Date.now())
+      throw new TrainError('channel_cursor', 'Invalid or expired channel cursor; start a new listing for this account and query.');
+    return cursor;
+  }
+
+  private async load(cursor: Cursor, load: ChannelPageLoader): Promise<Scan> {
+    if (cursor.scan.channels.length || cursor.scan.complete || cursor.scan.stopped) return cursor.scan;
+    cursor.loaded ??= this.fetch(cursor, load);
+    try {
+      return await cursor.loaded;
+    } catch (err) {
+      cursor.loaded = undefined;
+      throw err;
+    }
+  }
+
+  private async fetch(cursor: Cursor, load: ChannelPageLoader): Promise<Scan> {
+    const count = Math.min(100, DIRECTORY_LIMIT - cursor.scan.scanned);
+    const page = await load(cursor.scan.next, count, new Set(cursor.scan.seen));
+    if (!Number.isInteger(page.scanned) || page.scanned < 0 || page.scanned > count || page.channels.length > page.scanned)
+      throw new TrainError('channel_page', 'The mailbox returned more channel metadata than requested.');
+    if (page.next !== undefined && (typeof page.next !== 'string' || !page.next || page.next.length > 16384))
+      throw new TrainError('channel_page', 'The mailbox returned an invalid channel page token.');
+    return project(cursor, page);
+  }
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/mail-text.ts

@@ -0,0 +1,72 @@
+export const MAX_TEXT_CHARS = 20_000;
+
+const ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  ndash: '-',
+  mdash: '-',
+  hellip: '...',
+  rsquo: "'",
+  lsquo: "'",
+  rdquo: '"',
+  ldquo: '"',
+};
+
+function codePoint(n: number): string {
+  return Number.isInteger(n) && n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '';
+}
+
+export function decodeEntities(text: string): string {
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, name: string) => {
+    if (name.startsWith('#x') || name.startsWith('#X')) return codePoint(parseInt(name.slice(2), 16));
+    if (name.startsWith('#')) return codePoint(Number(name.slice(1)));
+    return ENTITIES[name.toLowerCase()] ?? whole;
+  });
+}
+
+export function htmlToText(html: string): string {
+  const text = html
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(head|style|script|title)\b[\s\S]*?<\/\1\s*>/gi, '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<li\b[^>]*>/gi, '\n- ')
+    .replace(/<\/(p|div|tr|h[1-6]|blockquote|table|ul|ol)\s*>/gi, '\n')
+    .replace(/<(p|div|tr|h[1-6]|blockquote|table)\b[^>]*>/gi, '\n')
+    .replace(/<\/t[dh]\s*>/gi, ' ')
+    .replace(/<[^>]*>/g, '');
+  return tidy(decodeEntities(text));
+}
+
+export function tidy(text: string): string {
+  return text
+    .replace(/\r\n?/g, '\n')
+    .replace(/[ \t ]+/g, ' ')
+    .split('\n')
+    .map((l) => l.trim())
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+export function capText(text: string, max = MAX_TEXT_CHARS): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n[... ${String(text.length - max)} more characters]`;
+}
+
+export function bodyText(body: { contentType?: unknown; content?: unknown } | undefined): string {
+  const content = typeof body?.content === 'string' ? body.content : '';
+  return String(body?.contentType).toLowerCase() === 'html' ? htmlToText(content) : tidy(content);
+}
+
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/\r?\n/g, '<br>');
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/mail-trust.ts

@@ -0,0 +1,29 @@
+export interface MailHeader {
+  name?: string;
+  value?: string;
+}
+
+export type Screened = { skip: string } | { verified: boolean };
+
+const AUTOMATED_LOCAL = /^(no-?reply|do-?not-?reply|donotreply|mailer-daemon|notifications?)([+._-].*)?$/i;
+const BULK = new Set(['bulk', 'list', 'junk']);
+
+export const headerValues = (headers: MailHeader[], name: string): string[] =>
+  headers.filter((h) => (h.name ?? '').toLowerCase() === name).map((h) => (h.value ?? '').trim());
+
+export const firstHeader = (headers: MailHeader[], name: string): string | undefined => headerValues(headers, name)[0];
+
+export function automatedBySender(address: string): string | null {
+  const local = address.split('@')[0] ?? '';
+  return AUTOMATED_LOCAL.test(local) ? `sender ${address}` : null;
+}
+
+export function automatedByHeaders(headers: MailHeader[]): string | null {
+  if (firstHeader(headers, 'list-unsubscribe') !== undefined) return 'List-Unsubscribe';
+  const auto = firstHeader(headers, 'auto-submitted');
+  if (auto !== undefined && auto.toLowerCase() !== 'no') return `Auto-Submitted: ${auto}`;
+  const precedence = (firstHeader(headers, 'precedence') ?? '').toLowerCase();
+  return BULK.has(precedence) ? `Precedence: ${precedence}` : null;
+}
+
+export const domainOf = (address: string): string => (address.split('@')[1] ?? '').toLowerCase();

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/mail.ts

@@ -0,0 +1,212 @@
+import { mintId } from '../ids.js';
+import { Line } from '../lines.js';
+import { TrainError } from '../train-error.js';
+import { capText } from './mail-text.js';
+
+export type MailStation = 'outlook' | 'gmail';
+
+type Args = Record<string, unknown>;
+
+export interface MailItem {
+  id: string;
+  threadId: string;
+  subject: string;
+  from: string;
+  fromName: string;
+  to: string[];
+  cc: string[];
+  date: string | null;
+  preview: string;
+  text: string;
+  hasAttachments: boolean;
+  isRead: boolean;
+  internetMessageId: string | null;
+}
+
+export interface AttachmentMeta {
+  kind: string;
+  name: string;
+  mime: string;
+  size?: number;
+}
+
+export interface OutgoingFile {
+  path: string;
+  mime: string;
+  name: string;
+}
+
+export interface ReadQuery {
+  threadId: string | null;
+  query: string;
+  from: string;
+  since: string;
+  until: string;
+  before: string;
+  unreadOnly: boolean;
+  limit: number;
+}
+
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 50;
+const SEEN_MAX = 500;
+const SUBJECT_MAX = 255;
+const ADDRESS_RE = /^[^@\s/]+@[^@\s/]+\.[^@\s/]+$/;
+
+export interface MailService {
+  station: MailStation;
+  company: string;
+  product: string;
+  api: string;
+  apiCode: string;
+}
+
+export function refusalOf(s: MailService, status: number, detail: string): TrainError {
+  const refuse = (code: string, text: string, retryable = false): TrainError => new TrainError(`${s.station}_${code}`, text, { retryable });
+  if (status === 401) return refuse('signed_out', `${s.company} refused this mailbox's sign-in (${detail}); connect ${s.product} again from the page`);
+  if (status === 403) return refuse('forbidden', `${s.company} does not let Metro do that on this mailbox (${detail})`);
+  if (status === 404) return refuse('not_found', `${s.product} has no such message or conversation (${detail})`);
+  if (status === 413) return refuse('too_large', `${s.product} refused the size of that request (${detail})`);
+  if (status === 429) return refuse('throttled', `${s.company} asked Metro to slow down (${detail}); try again in a minute`, true);
+  return refuse(s.apiCode, `${s.api} answered ${String(status)} (${detail})`, status >= 500);
+}
+
+export const str = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
+
+const encodeResource = (id: string): string => id.replace(/%/g, '%25').replace(/\//g, '%2F').replace(/\+/g, '%2B');
+
+export const mailLine = (station: MailStation, accountId: string, threadId: string): string =>
+  `metro://${station}/${accountId}/${encodeResource(threadId)}`;
+
+const mailUser = (station: MailStation, accountId: string, address: string): string =>
+  `metro://${station}/${accountId}/user/${address.toLowerCase()}`;
+
+export function threadOfLine(station: MailStation, line: string): { accountId: string; threadId: string } | null {
+  const parsed = Line.parseMail(line, station);
+  if (parsed === null) return null;
+  try {
+    return { accountId: parsed.accountId, threadId: decodeURIComponent(parsed.resource) };
+  } catch {
+    return null;
+  }
+}
+
+const isPrivateTo = (m: MailItem, self: string): boolean => m.to.length === 1 && m.to[0] === self && m.cc.length === 0;
+
+export function mailEnvelope(station: MailStation, accountId: string, self: string, m: MailItem, attachments: AttachmentMeta[], verified: boolean): Record<string, unknown> {
+  const body = capText(m.text);
+  return {
+    id: mintId(),
+    ts: m.date ?? new Date().toISOString(),
+    station,
+    line: mailLine(station, accountId, m.threadId),
+    line_name: m.subject === '' ? '(no subject)' : m.subject,
+    from: mailUser(station, accountId, m.from === '' ? 'unknown' : m.from),
+    from_name: m.fromName || m.from,
+    from_display_name: m.fromName || undefined,
+    message_id: m.id,
+    text: m.subject === '' ? body : `Subject: ${m.subject}\n\n${body}`,
+    is_private: isPrivateTo(m, self),
+    sender_verified: verified,
+    payload: {
+      from: m.from,
+      to: m.to,
+      cc: m.cc,
+      subject: m.subject,
+      internetMessageId: m.internetMessageId,
+      ...(attachments.length === 0 ? {} : { attachments }),
+    },
+  };
+}
+
+const heading = (station: MailStation, accountId: string, m: MailItem): Record<string, unknown> => ({
+  message_id: m.id,
+  line: mailLine(station, accountId, m.threadId),
+  from: m.from,
+  from_name: m.fromName,
+  date: m.date,
+  title: m.subject,
+});
+
+export const mailSummary = (station: MailStation, accountId: string, m: MailItem): Record<string, unknown> => ({
+  ...heading(station, accountId, m),
+  text_preview: m.preview,
+  has_attachments: m.hasAttachments,
+  is_read: m.isRead,
+});
+
+export const mailFull = (station: MailStation, accountId: string, m: MailItem): Record<string, unknown> => ({
+  ...heading(station, accountId, m),
+  has_attachments: m.hasAttachments,
+  is_read: m.isRead,
+  to: m.to,
+  cc: m.cc,
+  text: capText(m.text),
+});
+
+export const isAddress = (target: string): boolean => target.includes('@');
+
+export const isEmailAddress = (value: string): boolean => ADDRESS_RE.test(value);
+
+export function checkAddress(station: MailStation, to: string): void {
+  if (!isEmailAddress(to)) throw new TrainError(`${station}_bad_address`, `not an email address: ${to}`, { retryable: false });
+}
+
+export function subjectOf(station: MailStation, subject: string, text: string): string {
+  const chosen = subject !== '' ? subject : (text.split('\n').find((l) => l.trim() !== '') ?? '').trim();
+  if (chosen === '') throw new TrainError(`${station}_subject_required`, 'a new email needs a subject or some text', { retryable: false });
+  return chosen.length > SUBJECT_MAX ? `${chosen.slice(0, SUBJECT_MAX - 3)}...` : chosen;
+}
+
+export const filesOf = (raw: unknown): OutgoingFile[] =>
+  (Array.isArray(raw) ? raw : [])
+    .map((a) => (a ?? {}) as Record<string, unknown>)
+    .filter((a) => typeof a.path === 'string' && a.path !== '')
+    .map((a) => ({
+      path: String(a.path),
+      mime: typeof a.mime === 'string' && a.mime !== '' ? a.mime : 'application/octet-stream',
+      name: typeof a.name === 'string' && a.name !== '' ? a.name : 'file',
+    }));
+
+function isoOf(station: MailStation, raw: string, field: string): string {
+  if (raw === '') return '';
+  const at = Date.parse(raw);
+  if (Number.isNaN(at)) throw new TrainError(`${station}_bad_date`, `${field} must be a date, for example 2026-09-24 or 2026-09-24T10:00:00Z`, { retryable: false });
+  return new Date(at).toISOString();
+}
+
+export function readQueryOf(station: MailStation, args: Args): ReadQuery {
+  const line = str(args.line);
+  const thread = line === '' ? null : threadOfLine(station, line);
+  if (line !== '' && thread === null) throw new TrainError(`${station}_bad_line`, `not a valid ${station} line: ${line}`, { retryable: false });
+  return {
+    threadId: thread?.threadId ?? null,
+    query: str(args.query),
+    from: str(args.from).toLowerCase(),
+    since: isoOf(station, str(args.since), 'since'),
+    until: isoOf(station, str(args.until), 'until'),
+    before: str(args.before),
+    unreadOnly: args.unreadOnly === true,
+    limit: typeof args.limit === 'number' && args.limit > 0 ? Math.min(Math.floor(args.limit), MAX_LIMIT) : DEFAULT_LIMIT,
+  };
+}
+
+export const seenOf = (raw: unknown): string[] => (Array.isArray(raw) ? raw.filter((s): s is string => typeof s === 'string') : []);
+
+export function noteSeen(seen: string[], messageId: string): void {
+  seen.push(messageId);
+  if (seen.length > SEEN_MAX) seen.splice(0, seen.length - SEEN_MAX);
+}
+
+export function pollForever(tag: string, once: () => Promise<unknown>, intervalMs: number): void {
+  const tick = (): void => {
+    once()
+      .catch((err: unknown) => {
+        process.stderr.write(`${tag} mail check failed: ${err instanceof Error ? err.message : String(err)}\n`);
+      })
+      .finally(() => {
+        setTimeout(tick, intervalMs);
+      });
+  };
+  tick();
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/messaging-normalize.ts

@@ -0,0 +1,16 @@
+type Args = Record<string, unknown>;
+
+export interface Normalized {
+  action: string;
+  args: Args;
+}
+
+export type Normalize = (action: string, args: Args) => Normalized;
+
+export const messagingAliases =
+  (removal: Args = { emoji: '' }): Normalize =>
+  (action, args) => {
+    if (action === 'reply') return { action: 'send', args };
+    if (action === 'unreact') return { action: 'react', args: { ...args, ...removal } };
+    return { action, args };
+  };

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/oauth.ts

@@ -0,0 +1,126 @@
+import { createHash, randomBytes } from 'node:crypto';
+
+export class SignInError extends Error {}
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export type OAuthBody = Record<string, unknown>;
+
+export interface Tokens {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+}
+
+export interface Pkce {
+  verifier: string;
+  challenge: string;
+}
+
+const RENEW_BEFORE_MS = 5 * 60_000;
+const MAILBOX_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+const text = (v: unknown): string => (typeof v === 'string' ? v : '');
+
+export const seconds = (v: unknown, fallback: number): number =>
+  typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : fallback;
+
+export function envValue(name: string, fallback: string): string {
+  const value = (process.env[name] ?? '').trim();
+  return value === '' ? fallback : value;
+}
+
+export const envUrl = (name: string, fallback: string): string => envValue(name, fallback).replace(/\/+$/, '');
+
+export function pkcePair(verifier = randomBytes(32).toString('base64url')): Pkce {
+  return { verifier, challenge: createHash('sha256').update(verifier).digest('base64url') };
+}
+
+export const newState = (): string => randomBytes(24).toString('base64url');
+
+export function parseMailbox(value: unknown): string | null {
+  const mailbox = (typeof value === 'string' ? value.trim() : '').toLowerCase();
+  if (mailbox === '') return null;
+  if (!MAILBOX_RE.test(mailbox))
+    throw new SignInError('Type the whole address of the mailbox, like andy@company.com, or leave it blank.');
+  return mailbox;
+}
+
+export async function postForm(url: string, fields: Record<string, string>, fetchImpl: FetchLike, provider: string): Promise<{ status: number; body: OAuthBody }> {
+  let res: Response;
+  try {
+    res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+      body: new URLSearchParams(fields).toString(),
+    });
+  } catch (err) {
+    throw new SignInError(`Metro could not reach ${provider}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const raw: unknown = await res.json().catch(() => ({}));
+  return { status: res.status, body: typeof raw === 'object' && raw !== null ? (raw as OAuthBody) : {} };
+}
+
+export function tokensOf(body: OAuthBody, now: number, provider: string, previous?: string): Tokens {
+  const accessToken = text(body.access_token);
+  const refreshToken = text(body.refresh_token) || (previous ?? '');
+  if (accessToken === '' || refreshToken === '') throw new SignInError(`${provider} answered without the tokens Metro needs.`);
+  return { accessToken, refreshToken, expiresAt: now + seconds(body.expires_in, 3600) * 1000 };
+}
+
+export function tokenStateOf(saved: OAuthBody, seed: Partial<Tokens>): Tokens {
+  const fromFile = text(saved.refreshToken) !== '';
+  return {
+    refreshToken: fromFile ? text(saved.refreshToken) : text(seed.refreshToken),
+    accessToken: fromFile ? text(saved.accessToken) : text(seed.accessToken),
+    expiresAt: fromFile ? Number(saved.expiresAt) || 0 : Number(seed.expiresAt) || 0,
+  };
+}
+
+export class TokenKeeper {
+  private refreshing: Promise<string> | null = null;
+
+  constructor(
+    private readonly state: Tokens,
+    private readonly renewWith: (refreshToken: string) => Promise<Tokens>,
+    private readonly renewed: () => void,
+  ) {}
+
+  token(force = false): Promise<string> {
+    const fresh = this.state.accessToken !== '' && this.state.expiresAt - RENEW_BEFORE_MS > Date.now();
+    if (fresh && !force) return Promise.resolve(this.state.accessToken);
+    this.refreshing ??= this.renew().finally(() => {
+      this.refreshing = null;
+    });
+    return this.refreshing;
+  }
+
+  private async renew(): Promise<string> {
+    Object.assign(this.state, await this.renewWith(this.state.refreshToken));
+    this.renewed();
+    return this.state.accessToken;
+  }
+}
+
+export interface BrowserFlow<R> {
+  authorize: (challenge: string, state: string) => string;
+  redeem: (code: string, verifier: string) => Promise<R>;
+}
+
+export class BrowserSignIn<R> {
+  readonly state = newState();
+  readonly authorizeUrl: string;
+  private readonly pkce = pkcePair();
+  private used = false;
+
+  constructor(private readonly flow: BrowserFlow<R>) {
+    this.authorizeUrl = flow.authorize(this.pkce.challenge, this.state);
+  }
+
+  async finish(code: string, state: string): Promise<R> {
+    if (state !== this.state) throw new SignInError('This sign-in link belongs to another attempt. Start again from the Channels page.');
+    if (this.used) throw new SignInError('This sign-in was already used. Start again from the Channels page.');
+    this.used = true;
+    return this.flow.redeem(code, this.pkce.verifier);
+  }
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/profile.ts

@@ -0,0 +1,58 @@
+import { TrainError } from '../train-error.js';
+
+export const PROFILE_FIELDS = ['name', 'bio', 'avatar'] as const;
+export type ProfileField = (typeof PROFILE_FIELDS)[number];
+
+export const NAME_MAX = 64;
+export const BIO_MAX = 512;
+
+export interface ProfileAvatar {
+  path: string;
+  mime: string;
+  name: string;
+}
+
+export interface ProfileChange {
+  name?: string;
+  bio?: string;
+  avatar?: ProfileAvatar;
+}
+
+export interface ProfileApplied {
+  account: string;
+  applied: ProfileField[];
+}
+
+const text = (value: unknown, field: string, max: number): string | undefined => {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string') throw new TrainError('bad_request', `${field} must be a string`);
+  const trimmed = value.trim();
+  if (trimmed === '') throw new TrainError('bad_request', `${field} cannot be empty`);
+  if (trimmed.length > max) throw new TrainError('bad_request', `${field} is over ${String(max)} characters`);
+  return trimmed;
+};
+
+function avatarOf(value: unknown): ProfileAvatar | undefined {
+  if (value === undefined) return undefined;
+  const raw = (value ?? {}) as Record<string, unknown>;
+  if (typeof raw.path !== 'string' || raw.path === '') throw new TrainError('bad_request', 'avatar needs a local file');
+  return { path: raw.path, mime: typeof raw.mime === 'string' ? raw.mime : 'application/octet-stream', name: typeof raw.name === 'string' ? raw.name : 'avatar' };
+}
+
+export function parseProfileChange(args: Record<string, unknown>): ProfileChange {
+  const change: ProfileChange = {};
+  const name = text(args.name, 'name', NAME_MAX);
+  const bio = text(args.bio, 'bio', BIO_MAX);
+  const avatar = avatarOf(args.avatar);
+  if (name !== undefined) change.name = name;
+  if (bio !== undefined) change.bio = bio;
+  if (avatar !== undefined) change.avatar = avatar;
+  if (Object.keys(change).length === 0) throw new TrainError('bad_request', 'set_profile needs at least one of name, bio, avatar');
+  return change;
+}
+
+export const fieldsOf = (change: ProfileChange): ProfileField[] => PROFILE_FIELDS.filter((f) => change[f] !== undefined);
+
+export const assertImage = (avatar: ProfileAvatar): void => {
+  if (!avatar.mime.startsWith('image/')) throw new TrainError('bad_request', `avatar must be an image, not ${avatar.mime}`);
+};