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

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

@@ -0,0 +1,90 @@
+const enc = new TextEncoder();
+
+const hex = (bytes: Uint8Array): string =>
+  [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+
+export async function sha256Hex(data: string | Uint8Array<ArrayBuffer>): Promise<string> {
+  const bytes = typeof data === 'string' ? enc.encode(data) : data;
+  return hex(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)));
+}
+
+async function hmac(key: Uint8Array<ArrayBuffer>, data: string): Promise<Uint8Array<ArrayBuffer>> {
+  const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  return new Uint8Array(await crypto.subtle.sign('HMAC', cryptoKey, enc.encode(data)));
+}
+
+const encodeRfc3986 = (value: string): string =>
+  encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+
+const byPair = (a: [string, string], b: [string, string]): number =>
+  a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0;
+
+function canonicalQuery(url: URL): string {
+  const pairs: [string, string][] = [];
+  url.searchParams.forEach((value, key) => {
+    pairs.push([encodeRfc3986(key), encodeRfc3986(value)]);
+  });
+  return pairs.sort(byPair).map(([k, v]) => `${k}=${v}`).join('&');
+}
+
+export const amzDate = (date: Date): string =>
+  date.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+
+export interface SignInput {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+  region: string;
+  service: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  date?: Date;
+}
+
+export interface Signed {
+  headers: Record<string, string>;
+  canonicalRequest: string;
+  stringToSign: string;
+  signature: string;
+}
+
+function canonicalHeaders(input: SignInput, url: URL, date: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(input.headers)) out[key.toLowerCase()] = value.trim().replace(/\s+/g, ' ');
+  out.host = url.host;
+  out['x-amz-date'] = date;
+  if (input.sessionToken !== undefined) out['x-amz-security-token'] = input.sessionToken;
+  return out;
+}
+
+async function signingKey(input: SignInput, day: string): Promise<Uint8Array<ArrayBuffer>> {
+  const kDate = await hmac(enc.encode(`AWS4${input.secretAccessKey}`), day);
+  const kRegion = await hmac(kDate, input.region);
+  const kService = await hmac(kRegion, input.service);
+  return hmac(kService, 'aws4_request');
+}
+
+export async function signV4(input: SignInput): Promise<Signed> {
+  const url = new URL(input.url);
+  const date = amzDate(input.date ?? new Date());
+  const day = date.slice(0, 8);
+  const headers = canonicalHeaders(input, url, date);
+  const names = Object.keys(headers).sort();
+  const signedHeaders = names.join(';');
+  const canonicalRequest = [
+    input.method.toUpperCase(),
+    url.pathname === '' ? '/' : url.pathname,
+    canonicalQuery(url),
+    names.map((name) => `${name}:${headers[name] ?? ''}\n`).join(''),
+    signedHeaders,
+    await sha256Hex(input.body),
+  ].join('\n');
+  const scope = `${day}/${input.region}/${input.service}/aws4_request`;
+  const stringToSign = ['AWS4-HMAC-SHA256', date, scope, await sha256Hex(canonicalRequest)].join('\n');
+  const signature = hex(await hmac(await signingKey(input, day), stringToSign));
+  const authorization = `AWS4-HMAC-SHA256 Credential=${input.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+  const sendable = Object.fromEntries(Object.entries(headers).filter(([name]) => name !== 'host'));
+  return { headers: { ...sendable, authorization }, canonicalRequest, stringToSign, signature };
+}

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

@@ -0,0 +1,149 @@
+import type { IncomingMessage } from 'node:http';
+import { createPublicKey, verify, type JsonWebKey, type KeyObject } from 'node:crypto';
+
+const WORKOS_API = 'https://api.workos.com';
+const ORG_RE = /^org_[A-Za-z0-9]{10,64}$/;
+export const isOrganizationId = (value: string): boolean => ORG_RE.test(value);
+export const DEFAULT_CLIENT_ID = 'client_01M2TJJJ6RM9CT081QB4XZK3G2';
+const SKEW_S = 60;
+const REFETCH_COOLDOWN_MS = 60_000;
+const FETCH_MS = 10_000;
+
+export interface Session {
+  userId: string;
+  sessionId: string;
+  organization: string | null;
+  role: string | null;
+  expiresAt: number;
+}
+
+export interface KeyStore {
+  read: () => string | null;
+  write: (text: string) => void;
+}
+
+export const filled = (value: string | undefined): string | null => {
+  const text = value?.trim() ?? '';
+  return text === '' ? null : text;
+};
+
+export const clientId = (env: NodeJS.ProcessEnv = process.env): string => filled(env.WORKOS_CLIENT_ID) ?? DEFAULT_CLIENT_ID;
+export const workosBase = (env: NodeJS.ProcessEnv = process.env): string => filled(env.WORKOS_API_BASE) ?? WORKOS_API;
+export const jwksUrl = (id: string, base = WORKOS_API): string => `${base}/sso/jwks/${id}`;
+
+function jwksKeys(text: string): Map<string, KeyObject> {
+  const keys = new Map<string, KeyObject>();
+  const parsed: unknown = JSON.parse(text);
+  const list = typeof parsed === 'object' && parsed !== null ? (parsed as { keys?: unknown }).keys : undefined;
+  if (!Array.isArray(list)) return keys;
+  for (const jwk of list) {
+    if (typeof jwk !== 'object' || jwk === null) continue;
+    const { kid, kty } = jwk as { kid?: unknown; kty?: unknown };
+    if (typeof kid !== 'string' || kty !== 'RSA') continue;
+    try {
+      keys.set(kid, createPublicKey({ key: jwk as JsonWebKey, format: 'jwk' }));
+    } catch {
+      continue;
+    }
+  }
+  return keys;
+}
+
+export class SigningKeys {
+  private keys = new Map<string, KeyObject>();
+  private lastMiss = 0;
+  private loaded = false;
+
+  constructor(
+    private readonly url: string,
+    private readonly store?: KeyStore,
+  ) {}
+
+  private load(): void {
+    if (this.loaded) return;
+    this.loaded = true;
+    const cached = this.store?.read() ?? null;
+    if (cached !== null) this.keys = jwksKeys(cached);
+  }
+
+  private async refresh(now: number): Promise<void> {
+    if (now - this.lastMiss < REFETCH_COOLDOWN_MS) return;
+    const res = await fetch(this.url, { signal: AbortSignal.timeout(FETCH_MS) });
+    if (!res.ok) throw new Error(`the signing keys answered ${String(res.status)}`);
+    const text = await res.text();
+    const keys = jwksKeys(text);
+    if (keys.size === 0) throw new Error('the signing keys answered no RSA key');
+    this.keys = keys;
+    this.store?.write(text);
+  }
+
+  async keyFor(kid: string, now = Date.now()): Promise<KeyObject | null> {
+    this.load();
+    const held = this.keys.get(kid);
+    if (held !== undefined) return held;
+    await this.refresh(now);
+    const fetched = this.keys.get(kid);
+    if (fetched === undefined) this.lastMiss = now;
+    return fetched ?? null;
+  }
+}
+
+const b64url = (text: string): Buffer => Buffer.from(text.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+
+function jsonPart(text: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(b64url(text).toString('utf8'));
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+const str = (value: unknown): string | null => (typeof value === 'string' && value !== '' ? value : null);
+
+const issuedBy = (iss: unknown, issuer: string): boolean => typeof iss === 'string' && (iss === issuer || iss.startsWith(`${issuer}/`));
+
+function sessionOf(claims: Record<string, unknown>, issuer: string, now: number): Session | null {
+  const exp = typeof claims.exp === 'number' ? claims.exp : null;
+  const userId = str(claims.sub);
+  const sessionId = str(claims.sid);
+  if (!issuedBy(claims.iss, issuer) || exp === null || userId === null || sessionId === null) return null;
+  if (exp * 1000 < now - SKEW_S * 1000) return null;
+  return { userId, sessionId, organization: str(claims.org_id), role: str(claims.role), expiresAt: exp * 1000 };
+}
+
+interface Parts {
+  signed: string;
+  body: string;
+  signature: Buffer;
+  kid: string;
+}
+
+function parseToken(token: string): Parts | null {
+  const [head, body, sig] = token.split('.');
+  if (head === undefined || body === undefined || sig === undefined) return null;
+  const header = jsonPart(head);
+  const kid = str(header?.kid);
+  if (header?.alg !== 'RS256' || kid === null) return null;
+  return { signed: `${head}.${body}`, body, signature: b64url(sig), kid };
+}
+
+export async function verifyToken(token: string, keys: SigningKeys, issuer = WORKOS_API, now = Date.now()): Promise<Session | null> {
+  const parts = parseToken(token);
+  if (parts === null) return null;
+  const key = await keys.keyFor(parts.kid, now).catch(() => null);
+  if (key === null || !verify('sha256', Buffer.from(parts.signed), key, parts.signature)) return null;
+  const claims = jsonPart(parts.body);
+  return claims === null ? null : sessionOf(claims, issuer, now);
+}
+
+export function bearerToken(req: IncomingMessage): string | null {
+  const header = req.headers.authorization ?? '';
+  const [scheme, token] = header.trim().split(/\s+/);
+  return scheme?.toLowerCase() === 'bearer' && token?.includes('.') === true ? token : null;
+}
+
+export async function bearerSession(req: IncomingMessage, keys: SigningKeys, issuer = WORKOS_API): Promise<Session | null> {
+  const token = bearerToken(req);
+  return token === null ? null : verifyToken(token, keys, issuer);
+}

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

@@ -0,0 +1,25 @@
+{
+  "name": "@metro-labs/outlook",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/station.ts",
+    "./train": "./src/index.ts",
+    "./login": "./src/login.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/outlook/src/accounts.ts

@@ -0,0 +1,78 @@
+import { makeAccountStore, resolveAccountId, type Die } from '@metro-labs/core/stations/account-store';
+import { threadOfLine } from '@metro-labs/core/stations/mail';
+import { TokenKeeper, type FetchLike } from '@metro-labs/core/stations/oauth';
+import { TrainError } from '@metro-labs/core/train-error';
+import { refreshTokens } from './auth.js';
+import { loadState, saveState, type AccountState } from './state.js';
+
+export interface AccountConfig {
+  id: string;
+  accountEmail: string;
+  refreshToken: string;
+  accessToken?: string;
+  expiresAt?: number;
+  includeAutomated?: boolean;
+}
+
+function checkAccount(a: AccountConfig, die: Die): void {
+  if (typeof a.accountEmail !== 'string' || !a.accountEmail.includes('@')) die(`account '${a.id}' has no mailbox address`);
+  if (typeof a.refreshToken !== 'string' || a.refreshToken === '') die(`account '${a.id}' has no refresh token`);
+}
+
+export const { loadAccounts } = makeAccountStore<AccountConfig>({
+  prefix: 'outlook',
+  validate(raw, die) {
+    for (const a of raw) checkAccount(a, die);
+  },
+});
+
+const signedOut = (err: unknown): never => {
+  throw new TrainError('outlook_signed_out', err instanceof Error ? err.message : String(err), { retryable: false });
+};
+
+export class Account {
+  readonly email: string;
+  readonly state: AccountState;
+  private readonly keeper: TokenKeeper;
+
+  constructor(
+    readonly cfg: AccountConfig,
+    private readonly fetchImpl: FetchLike = (input, init) => fetch(input, init),
+  ) {
+    this.email = cfg.accountEmail.toLowerCase();
+    this.state = loadState(cfg.id, { refreshToken: cfg.refreshToken, accessToken: cfg.accessToken ?? '', expiresAt: cfg.expiresAt ?? 0 });
+    this.keeper = new TokenKeeper(this.state, (refreshToken) => refreshTokens(refreshToken, this.fetchImpl).catch(signedOut), () => {
+      this.save();
+    });
+  }
+
+  get id(): string {
+    return this.cfg.id;
+  }
+
+  save(): void {
+    saveState(this.cfg.id, this.state);
+  }
+
+  token(force = false): Promise<string> {
+    return this.keeper.token(force);
+  }
+
+  fetch(input: string, init?: RequestInit): Promise<Response> {
+    return this.fetchImpl(input, init);
+  }
+}
+
+export const accounts = new Map<string, Account>();
+
+function accountFor(id: string): Account {
+  const acct = accounts.get(id);
+  if (!acct) throw new Error(`unknown account '${id}' (have: ${[...accounts.keys()].join(', ')})`);
+  return acct;
+}
+
+export function accountOf(args: { account?: unknown; line?: unknown }): Account {
+  const line = typeof args.line === 'string' && args.line !== '' ? args.line : undefined;
+  const account = typeof args.account === 'string' && args.account !== '' ? args.account : undefined;
+  return accountFor(resolveAccountId(accounts, { account, line }, (l) => threadOfLine('outlook', l)?.accountId));
+}

package/runtime/node_modules/@metro-labs/outlook/src/actions.ts

@@ -0,0 +1,15 @@
+import { makeStation, respond } from '@metro-labs/core/stations/station-runtime';
+import { accounts } from './accounts.js';
+import { listChannels } from './channels.js';
+import { MAILBOX_URL } from './config.js';
+import { reply, send } from './outbound.js';
+import { read } from './query.js';
+
+function listAccounts(id: string): void {
+  const list = [...accounts.values()].map((a) => ({ id: a.id, handle: a.email, url: MAILBOX_URL, email: a.email }));
+  respond(id, { result: { accounts: list } });
+}
+
+export const handleCall = makeStation({
+  handlers: { accounts: listAccounts, listChannels, send, reply, read },
+});

package/runtime/node_modules/@metro-labs/outlook/src/attachments.ts

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { assertAttachmentSize, kindOf, saveBufferToCache, type SavedAttachment } from '@metro-labs/core/stations/attachments';
+import type { AttachmentMeta, OutgoingFile } from '@metro-labs/core/stations/mail';
+import { TrainError } from '@metro-labs/core/train-error';
+import type { Account } from './accounts.js';
+import { graph, graphJson, messagePath } from './graph.js';
+
+export const MAX_FILE_BYTES = 3 * 1024 * 1024;
+
+const FILE_TYPE = '#microsoft.graph.fileAttachment';
+
+export interface GraphAttachment {
+  id: string;
+  name?: string;
+  contentType?: string;
+  size?: number;
+  isInline?: boolean;
+  '@odata.type'?: string;
+}
+
+export interface MailFile extends AttachmentMeta {
+  id: string;
+}
+
+export const metaOf = (f: MailFile): AttachmentMeta => ({
+  kind: f.kind,
+  name: f.name,
+  mime: f.mime,
+  ...(f.size === undefined ? {} : { size: f.size }),
+});
+
+export async function listFiles(acct: Account, messageId: string): Promise<MailFile[]> {
+  const body = await graphJson<{ value?: GraphAttachment[] }>(
+    acct,
+    `${messagePath(messageId)}/attachments?$select=id,name,contentType,size,isInline`,
+  );
+  return (body.value ?? [])
+    .filter((a) => a['@odata.type'] === undefined || a['@odata.type'] === FILE_TYPE)
+    .map((a) => {
+      const name = a.name ?? 'attachment';
+      const mime = a.contentType ?? 'application/octet-stream';
+      return { id: a.id, name, mime, kind: kindOf(mime, name), ...(typeof a.size === 'number' ? { size: a.size } : {}) };
+    });
+}
+
+const cacheKey = (messageId: string): string => createHash('sha256').update(messageId).digest('hex').slice(0, 16);
+
+export async function saveFile(acct: Account, messageId: string, file: MailFile, index: number): Promise<SavedAttachment> {
+  if (file.size !== undefined) assertAttachmentSize(file.size);
+  const res = await graph(acct, `${messagePath(messageId)}/attachments/${encodeURIComponent(file.id)}/$value`);
+  const data = new Uint8Array(await res.arrayBuffer());
+  return saveBufferToCache(data, cacheKey(messageId), index, { mime: file.mime, name: file.name });
+}
+
+export async function assertSendable(files: OutgoingFile[]): Promise<void> {
+  for (const file of files) {
+    const { size } = await stat(file.path);
+    if (size > MAX_FILE_BYTES)
+      throw new TrainError(
+        'outlook_file_too_big',
+        `Metro sends Outlook files up to 3 MB for now; ${file.name} is ${(size / 1024 / 1024).toFixed(1)} MB, so share a link to it instead`,
+        { retryable: false },
+      );
+  }
+}
+
+export async function attachFile(acct: Account, draftId: string, file: OutgoingFile): Promise<string> {
+  const data = await readFile(file.path);
+  await graph(acct, `${messagePath(draftId)}/attachments`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      '@odata.type': FILE_TYPE,
+      name: file.name,
+      contentType: file.mime,
+      contentBytes: data.toString('base64'),
+    }),
+  });
+  return kindOf(file.mime, file.path);
+}

package/runtime/node_modules/@metro-labs/outlook/src/auth.ts

@@ -0,0 +1,120 @@
+import { postForm, seconds, SignInError, tokensOf, type FetchLike, type OAuthBody, type Tokens } from '@metro-labs/core/stations/oauth';
+import { clientId, loginBase, NOT_SET_UP, SCOPES } from './config.js';
+
+export interface DeviceCode {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  message: string;
+  expiresAt: number;
+  intervalMs: number;
+}
+
+export type Poll =
+  | { kind: 'pending' }
+  | { kind: 'slow_down' }
+  | { kind: 'done'; tokens: Tokens; tenantId: string | null }
+  | { kind: 'failed'; message: string };
+
+type Body = OAuthBody;
+
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const CONSENT_CODES = new Set([65001, 90094, 90095]);
+const POLICY_CODES = new Set([530035, 53003]);
+
+const text = (v: unknown): string => (typeof v === 'string' ? v : '');
+
+export function requireClientId(id = clientId()): string {
+  if (id === '') throw new SignInError(NOT_SET_UP);
+  return id;
+}
+
+export const postLogin = (path: string, fields: Record<string, string>, fetchImpl: FetchLike): Promise<{ status: number; body: Body }> =>
+  postForm(`${loginBase()}/oauth2/v2.0/${path}`, fields, fetchImpl, 'Microsoft');
+
+function codesOf(body: Body): number[] {
+  const listed = Array.isArray(body.error_codes) ? body.error_codes.filter((c): c is number => typeof c === 'number') : [];
+  const named = [...text(body.error_description).matchAll(/AADSTS(\d+)/g)].map((m) => Number(m[1]));
+  return [...listed, ...named];
+}
+
+const needsConsent = (error: string, codes: number[]): boolean =>
+  error === 'consent_required' || codes.some((c) => CONSENT_CODES.has(c));
+
+function knownFailure(error: string, codes: number[], id: string): string | null {
+  if (needsConsent(error, codes))
+    return `An administrator of this Microsoft 365 organization must approve Metro once before it can read this mailbox. They can do it at https://login.microsoftonline.com/organizations/adminconsent?client_id=${id} and then you can start again.`;
+  if (codes.some((c) => POLICY_CODES.has(c)))
+    return 'Your company blocks this kind of sign-in. Ask your Microsoft 365 administrator, or use the Microsoft sign-in page instead of a code.';
+  if (error === 'expired_token' || codes.includes(70020)) return 'The sign-in code expired before it was used. Start again.';
+  if (error === 'access_denied' || codes.includes(65004)) return 'The sign-in was declined, so nothing was connected.';
+  return null;
+}
+
+export function failureOf(body: Body, id = clientId()): string {
+  const error = text(body.error);
+  const known = knownFailure(error, codesOf(body), id);
+  if (known !== null) return known;
+  const detail = text(body.error_description).split(/\r?\n/)[0] ?? '';
+  return detail === '' ? `Microsoft refused the sign-in (${error === '' ? 'no reason given' : error}).` : `Microsoft refused the sign-in: ${detail}`;
+}
+
+function decodeClaims(jwt: string): Body | null {
+  const part = jwt.split('.')[1];
+  if (part === undefined) return null;
+  try {
+    const raw: unknown = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+    return typeof raw === 'object' && raw !== null ? (raw as Body) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function tenantOf(...jwts: string[]): string | null {
+  for (const jwt of jwts) {
+    const tid = decodeClaims(jwt)?.tid;
+    if (typeof tid === 'string' && tid !== '') return tid;
+  }
+  return null;
+}
+
+export async function requestDeviceCode(fetchImpl: FetchLike = fetch, now = Date.now()): Promise<DeviceCode> {
+  const { status, body } = await postLogin('devicecode', { client_id: requireClientId(), scope: SCOPES }, fetchImpl);
+  const userCode = text(body.user_code);
+  const deviceCode = text(body.device_code);
+  if (status !== 200 || userCode === '' || deviceCode === '') throw new SignInError(failureOf(body));
+  return {
+    deviceCode,
+    userCode,
+    verificationUri: text(body.verification_uri) || 'https://microsoft.com/devicelogin',
+    message: text(body.message),
+    expiresAt: now + seconds(body.expires_in, 900) * 1000,
+    intervalMs: seconds(body.interval, 5) * 1000,
+  };
+}
+
+export async function pollDeviceCode(code: DeviceCode, fetchImpl: FetchLike = fetch, now = Date.now()): Promise<Poll> {
+  const { status, body } = await postLogin(
+    'token',
+    { grant_type: DEVICE_GRANT, client_id: requireClientId(), device_code: code.deviceCode },
+    fetchImpl,
+  );
+  if (status === 200) {
+    const tokens = tokensOf(body, now, 'Microsoft');
+    return { kind: 'done', tokens, tenantId: tenantOf(text(body.id_token), tokens.accessToken) };
+  }
+  const error = text(body.error);
+  if (error === 'authorization_pending') return { kind: 'pending' };
+  if (error === 'slow_down') return { kind: 'slow_down' };
+  return { kind: 'failed', message: failureOf(body) };
+}
+
+export async function refreshTokens(refreshToken: string, fetchImpl: FetchLike = fetch, now = Date.now()): Promise<Tokens> {
+  const { status, body } = await postLogin(
+    'token',
+    { grant_type: 'refresh_token', client_id: requireClientId(), refresh_token: refreshToken, scope: SCOPES },
+    fetchImpl,
+  );
+  if (status !== 200) throw new SignInError(`Microsoft refused to renew this mailbox's sign-in, so connect Outlook again. ${failureOf(body)}`);
+  return tokensOf(body, now, 'Microsoft', refreshToken);
+}

package/runtime/node_modules/@metro-labs/outlook/src/browser.ts

@@ -0,0 +1,42 @@
+import { SignInError, tokensOf, type FetchLike, type Tokens } from '@metro-labs/core/stations/oauth';
+import { failureOf, postLogin, requireClientId, tenantOf } from './auth.js';
+import { loginBase, redirectUri, SCOPES } from './config.js';
+
+export function authorizeUrl(challenge: string, state: string, loginHint: string | null = null): string {
+  const query = new URLSearchParams({
+    ...(loginHint === null ? {} : { login_hint: loginHint }),
+    client_id: requireClientId(),
+    response_type: 'code',
+    redirect_uri: redirectUri(),
+    response_mode: 'query',
+    scope: SCOPES,
+    state,
+    code_challenge: challenge,
+    code_challenge_method: 'S256',
+    prompt: 'select_account',
+  });
+  return `${loginBase()}/oauth2/v2.0/authorize?${query.toString()}`;
+}
+
+export interface Redeemed {
+  tokens: Tokens;
+  tenantId: string | null;
+}
+
+export async function redeemCode(code: string, verifier: string, fetchImpl: FetchLike, now = Date.now()): Promise<Redeemed> {
+  const { status, body } = await postLogin(
+    'token',
+    {
+      grant_type: 'authorization_code',
+      client_id: requireClientId(),
+      code,
+      code_verifier: verifier,
+      redirect_uri: redirectUri(),
+      scope: SCOPES,
+    },
+    fetchImpl,
+  );
+  if (status !== 200) throw new SignInError(failureOf(body));
+  const tokens = tokensOf(body, now, 'Microsoft');
+  return { tokens, tenantId: tenantOf(typeof body.id_token === 'string' ? body.id_token : '', tokens.accessToken) };
+}

package/runtime/node_modules/@metro-labs/outlook/src/channels.ts

@@ -0,0 +1,60 @@
+import { ChannelPages, type ChannelPage } from '@metro-labs/core/stations/channel-pages';
+import { mailLine } 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 { graphBase } from './config.js';
+import { graphJson } from './graph.js';
+
+const FIELDS = 'conversationId,subject';
+const ORDER = 'receivedDateTime desc';
+const PARAMS = new Set(['$select', '$orderby', '$top', '$skip', '$skiptoken']);
+const SCOPE = 'Matches thread ids, lines and the newest encountered subject across up to 5000 Outlook message records, newest first; repeated conversations are returned once.';
+const directories = new WeakMap<Account, ChannelPages>();
+
+interface MessagePage {
+  value?: { conversationId?: string; subject?: string | null }[];
+  '@odata.nextLink'?: string;
+}
+
+const refused = (): never => { throw new TrainError('outlook_channel_page', 'Outlook returned an unsafe metadata page link.'); };
+
+function checkParams(params: URLSearchParams): void {
+  for (const key of params.keys()) {
+    if (!PARAMS.has(key) || params.getAll(key).length !== 1) refused();
+  }
+  const select = params.get('$select');
+  const order = params.get('$orderby');
+  if ((select !== null && select !== FIELDS) || (order !== null && order !== ORDER)) refused();
+}
+
+function pageUrl(next: string | undefined, limit: number): string {
+  const base = new URL(`${graphBase()}/me/messages`);
+  const url = next === undefined ? base : new URL(next);
+  if (url.origin !== base.origin || url.pathname !== base.pathname || url.username || url.password || url.hash) refused();
+  checkParams(url.searchParams);
+  url.searchParams.set('$select', FIELDS);
+  url.searchParams.set('$orderby', ORDER);
+  url.searchParams.set('$top', String(limit));
+  return url.toString();
+}
+
+async function loadPage(account: Account, next: string | undefined, limit: number): Promise<ChannelPage> {
+  const page = await graphJson<MessagePage>(account, pageUrl(next, limit), { redirect: 'error', signal: AbortSignal.timeout(45_000) });
+  const rows = page.value ?? [];
+  const channels = rows.map((row) => {
+    if (!row.conversationId || row.conversationId.length > 1024) throw new TrainError('outlook_channel_page', 'Outlook returned invalid conversation metadata.');
+    return { id: row.conversationId, line: mailLine('outlook', account.id, row.conversationId), kind: 'thread' as const, ...(row.subject ? { name: row.subject } : {}) };
+  });
+  const token = page['@odata.nextLink'];
+  return { channels, scanned: rows.length, ...(token ? { next: pageUrl(token, limit) } : {}) };
+}
+
+export async function listChannels(id: string, args: Record<string, unknown>): Promise<void> {
+  if (typeof args.account !== 'string' || !args.account.trim()) throw new TrainError('bad_request', 'account is required to list channels.');
+  const account = accountOf({ account: args.account });
+  const directory = directories.get(account) ?? new ChannelPages();
+  directories.set(account, directory);
+  const result = await directory.list(account.id, args, (token, limit) => loadPage(account, token, limit), SCOPE);
+  respond(id, { result });
+}