@stage-labs/metro 0.1.0-beta.174 → 0.1.0-beta.176

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-outlook.ts

@@ -0,0 +1,62 @@
+import type { OutlookLogin } from '@metro-labs/outlook/login';
+import { StationAttachError } from './attach.js';
+import type { DriverHooks, StartedAttach, StepInput } from './attach-driver.js';
+
+const BROWSER_PROMPT =
+  'Sign in with Microsoft in a new tab, with the mailbox this agent should read. This page updates on its own once you are done.';
+const DEVICE_PROMPT =
+  'Open the Microsoft sign-in page, type this code, and sign in with the mailbox this agent should read.';
+const OTHER_ATTEMPT = 'This sign-in link belongs to another attempt. Start again from the Channels page.';
+const BROWSER_TTL_MS = 15 * 60_000;
+
+const text = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
+
+export async function startOutlook(hooks: DriverHooks): Promise<StartedAttach> {
+  const { OutlookBrowserLogin, OutlookLogin: DeviceLogin, OutlookLoginError, failureOf } = await import('@metro-labs/outlook/login');
+  const said = (err: unknown, fallback: string): string =>
+    err instanceof OutlookLoginError && err.message !== '' ? err.message : fallback;
+  const browser = (() => {
+    try {
+      return new OutlookBrowserLogin();
+    } catch (err) {
+      throw new StationAttachError(said(err, 'Microsoft refused to start the sign-in'), 400);
+    }
+  })();
+  let device: OutlookLogin | null = null;
+
+  const toDevice = async (): Promise<void> => {
+    if (device !== null) return;
+    const login = new DeviceLogin({ onDone: hooks.done, onFailed: hooks.fail });
+    const code = await login.start().catch((err: unknown) => {
+      throw new StationAttachError(said(err, 'Microsoft refused to start the sign-in'), 400);
+    });
+    device = login;
+    hooks.prompt({ step: 'device', prompt: DEVICE_PROMPT, userCode: code.userCode, verificationUri: code.verificationUri });
+  };
+
+  const finish = async (input: StepInput): Promise<void> => {
+    const state = text(input.state);
+    if (state !== browser.state) throw new StationAttachError(OTHER_ATTEMPT, 400);
+    const error = text(input.error);
+    if (error !== '') {
+      hooks.fail(failureOf({ error, error_description: text(input.errorDescription) }));
+      return;
+    }
+    const code = text(input.code);
+    if (code === '') throw new StationAttachError('Microsoft did not send a sign-in code back', 400);
+    try {
+      hooks.done(await browser.finish(code, state));
+    } catch (err) {
+      hooks.fail(said(err, 'Metro could not finish the Microsoft sign-in.'));
+    }
+  };
+
+  return {
+    prompt: { step: 'browser', prompt: BROWSER_PROMPT, authorizeUrl: browser.authorizeUrl },
+    expiresAt: Date.now() + BROWSER_TTL_MS,
+    driver: {
+      cancel: () => device?.cancel() ?? Promise.resolve(),
+      submit: (input) => (input.mode === 'device' ? toDevice() : finish(input)),
+    },
+  };
+}

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-session.ts

@@ -3,16 +3,16 @@ import { ApiError } from '@metro-labs/http/api-error';
 import { errMsg, log } from '@metro-labs/core/log';
 import type { StationName } from '@metro-labs/core/station-names';
 import { ensureStationDeps } from './runtime-deps.js';
-import {
-  startInteractiveAttach,
-  type AttachDriver,
-  type AttachOutcome,
-  type AttachPrompt,
-  type AttachStep,
-  type DriverHooks,
-  type InteractiveStation,
-  type StartedAttach,
-} from './attach-interactive.js';
+import { startInteractiveAttach, type InteractiveStation } from './attach-interactive.js';
+import type {
+  AttachDriver,
+  AttachOutcome,
+  AttachPrompt,
+  AttachStep,
+  DriverHooks,
+  StartedAttach,
+  StepInput,
+} from './attach-driver.js';
 
 export type StartAttach = (
   station: InteractiveStation,
@@ -40,6 +40,9 @@ export interface AttachView {
   prompt: string;
   qr: string | null;
   pairingCode: string | null;
+  userCode: string | null;
+  verificationUri: string | null;
+  authorizeUrl: string | null;
   accountId: string | null;
   identity: Record<string, string>;
   activated: boolean;
@@ -82,6 +85,9 @@ function blankView(attachId: string, station: string): AttachView {
     prompt: '',
     qr: null,
     pairingCode: null,
+    userCode: null,
+    verificationUri: null,
+    authorizeUrl: null,
     accountId: null,
     identity: {},
     activated: false,
@@ -132,6 +138,9 @@ export class AttachSessions {
     Object.assign(session.view, patch, {
       qr: null,
       pairingCode: null,
+      userCode: null,
+      verificationUri: null,
+      authorizeUrl: null,
       step: null,
       expiresAt: Date.now() + SETTLED_TTL_MS,
     });
@@ -179,6 +188,9 @@ export class AttachSessions {
         session.view.prompt = p.prompt;
         session.view.qr = p.qr ?? null;
         session.view.pairingCode = p.pairingCode ?? null;
+        session.view.userCode = p.userCode ?? null;
+        session.view.verificationUri = p.verificationUri ?? null;
+        session.view.authorizeUrl = p.authorizeUrl ?? null;
       },
       done: (o: AttachOutcome): void => {
         this.finish(attachId, station, o).catch((err: unknown) => {
@@ -219,6 +231,7 @@ export class AttachSessions {
         this.hooksFor(attachId, station),
       );
       session.driver = started.driver;
+      if (started.expiresAt !== undefined) session.view.expiresAt = started.expiresAt;
       this.hooksFor(attachId, station).prompt(started.prompt);
     } catch (err) {
       this.sessions.delete(attachId);
@@ -238,7 +251,7 @@ export class AttachSessions {
   async submit(
     owner: AttachOwner,
     attachId: string,
-    input: { code?: unknown; password?: unknown },
+    input: StepInput,
   ): Promise<AttachView> {
     const session = this.own(owner, attachId);
     const driver = session.driver;

package/runtime/node_modules/@metro-labs/daemon/src/stations/materialize.ts

@@ -82,6 +82,11 @@ const STATION_TARGETS: Record<StationName, StationTarget> = {
     fileEnv: 'THREEMA_ACCOUNTS_FILE',
     trainImport: '@metro-labs/threema/train',
   },
+  outlook: {
+    file: 'outlook-accounts.json',
+    fileEnv: 'OUTLOOK_ACCOUNTS_FILE',
+    trainImport: '@metro-labs/outlook/train',
+  },
   webhook: {
     file: 'webhook-accounts.json',
     fileEnv: 'WEBHOOK_ACCOUNTS_FILE',

package/runtime/node_modules/@metro-labs/daemon/src/stations/registry.ts

@@ -6,6 +6,7 @@ import { telegramStation } from '@metro-labs/telegram';
 import { discordBotStation } from '@metro-labs/discord-bot';
 import { whatsappStation } from '@metro-labs/whatsapp';
 import { threemaStation } from '@metro-labs/threema';
+import { outlookStation } from '@metro-labs/outlook';
 import { webhookStation } from '@metro-labs/webhook';
 
 export const STATIONS: readonly Station[] = [
@@ -15,6 +16,7 @@ export const STATIONS: readonly Station[] = [
   discordBotStation,
   whatsappStation,
   threemaStation,
+  outlookStation,
   webhookStation,
 ];
 

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.2",
+    "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,107 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { makeAccountStore, resolveAccountId, type Die } from '@metro-labs/core/stations/account-store';
+import { TrainError } from '@metro-labs/core/train-error';
+import { refreshTokens, type FetchLike } from './auth.js';
+import { conversationOfLine } from './format.js';
+import { loadState, saveState, type AccountState } from './state.js';
+
+const ACCOUNTS_FILE = process.env.OUTLOOK_ACCOUNTS_FILE ?? join(homedir(), '.metro', 'outlook-accounts.json');
+
+const RENEW_BEFORE_MS = 5 * 60_000;
+
+export interface AccountConfig {
+  id: string;
+  accountEmail: string;
+  refreshToken: string;
+  accessToken?: string;
+  expiresAt?: number;
+  tenantId?: string | null;
+  deltaLink?: string | null;
+  includeAutomated?: boolean;
+}
+
+function checkAccount(a: AccountConfig, die: Die): void {
+  if (!a.id) die('account missing id');
+  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',
+  file: ACCOUNTS_FILE,
+  validate(raw, die) {
+    const seen = new Set<string>();
+    for (const a of raw) {
+      checkAccount(a, die);
+      if (seen.has(a.id)) die(`duplicate account id '${a.id}'`);
+      seen.add(a.id);
+    }
+  },
+});
+
+export class Account {
+  readonly email: string;
+  readonly state: AccountState;
+  private refreshing: Promise<string> | null = null;
+
+  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,
+      deltaLink: cfg.deltaLink ?? null,
+    });
+  }
+
+  get id(): string {
+    return this.cfg.id;
+  }
+
+  save(): void {
+    saveState(this.cfg.id, this.state);
+  }
+
+  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> {
+    let tokens;
+    try {
+      tokens = await refreshTokens(this.state.refreshToken, this.fetchImpl);
+    } catch (err) {
+      throw new TrainError('outlook_signed_out', err instanceof Error ? err.message : String(err), { retryable: false });
+    }
+    Object.assign(this.state, tokens);
+    this.save();
+    return tokens.accessToken;
+  }
+
+  fetch(input: string, init?: RequestInit): Promise<Response> {
+    return this.fetchImpl(input, init);
+  }
+}
+
+export const accounts = new Map<string, Account>();
+
+export 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) => conversationOfLine(l)?.accountId));
+}

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

@@ -0,0 +1,20 @@
+import { makeStation, respond } from '@metro-labs/core/stations/station-runtime';
+import type { Normalized } from '@metro-labs/core/stations/messaging-normalize';
+import { accounts } from './accounts.js';
+import { MAILBOX_URL } from './config.js';
+import { reply, send } from './outbound.js';
+import { read } from './query.js';
+
+type Args = Record<string, unknown>;
+
+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 } });
+}
+
+const normalizeOutlook = (action: string, args: Args): Normalized => ({ action, args });
+
+export const handleCall = makeStation({
+  handlers: { accounts: listAccounts, send, reply, read },
+  normalize: normalizeOutlook,
+});

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

@@ -0,0 +1,97 @@
+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 { TrainError } from '@metro-labs/core/train-error';
+import type { Account } from './accounts.js';
+import type { AttachmentMeta } from './format.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 interface OutgoingFile {
+  path: string;
+  mime: string;
+  name: string;
+}
+
+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',
+    }));
+
+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,150 @@
+import { clientId, loginBase, NOT_SET_UP, SCOPES } from './config.js';
+
+export class OutlookAuthError extends Error {}
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface Tokens {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+}
+
+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 = Record<string, unknown>;
+
+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 : '');
+const seconds = (v: unknown, fallback: number): number =>
+  typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : fallback;
+
+export function requireClientId(id = clientId()): string {
+  if (id === '') throw new OutlookAuthError(NOT_SET_UP);
+  return id;
+}
+
+export async function postForm(path: string, fields: Record<string, string>, fetchImpl: FetchLike): Promise<{ status: number; body: Body }> {
+  let res: Response;
+  try {
+    res = await fetchImpl(`${loginBase()}/oauth2/v2.0/${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+      body: new URLSearchParams(fields).toString(),
+    });
+  } catch (err) {
+    throw new OutlookAuthError(`Metro could not reach Microsoft: ${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 Body) : {} };
+}
+
+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 function tokensOf(body: Body, now: number, previous?: string): Tokens {
+  const accessToken = text(body.access_token);
+  const refreshToken = text(body.refresh_token) || (previous ?? '');
+  if (accessToken === '' || refreshToken === '') throw new OutlookAuthError('Microsoft answered without the tokens Metro needs.');
+  return { accessToken, refreshToken, expiresAt: now + seconds(body.expires_in, 3600) * 1000 };
+}
+
+export async function requestDeviceCode(fetchImpl: FetchLike = fetch, now = Date.now()): Promise<DeviceCode> {
+  const { status, body } = await postForm('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 OutlookAuthError(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 postForm(
+    'token',
+    { grant_type: DEVICE_GRANT, client_id: requireClientId(), device_code: code.deviceCode },
+    fetchImpl,
+  );
+  if (status === 200) {
+    const tokens = tokensOf(body, now);
+    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 postForm(
+    'token',
+    { grant_type: 'refresh_token', client_id: requireClientId(), refresh_token: refreshToken, scope: SCOPES },
+    fetchImpl,
+  );
+  if (status !== 200) throw new OutlookAuthError(`Microsoft refused to renew this mailbox's sign-in, so connect Outlook again. ${failureOf(body)}`);
+  return tokensOf(body, now, refreshToken);
+}

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

@@ -0,0 +1,52 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { failureOf, OutlookAuthError, postForm, requireClientId, tenantOf, tokensOf, type FetchLike, type Tokens } from './auth.js';
+import { loginBase, redirectUri, SCOPES } from './config.js';
+
+export interface Pkce {
+  verifier: string;
+  challenge: string;
+}
+
+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 authorizeUrl(challenge: string, state: string): string {
+  const query = new URLSearchParams({
+    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 postForm(
+    'token',
+    {
+      grant_type: 'authorization_code',
+      client_id: requireClientId(),
+      code,
+      code_verifier: verifier,
+      redirect_uri: redirectUri(),
+      scope: SCOPES,
+    },
+    fetchImpl,
+  );
+  if (status !== 200) throw new OutlookAuthError(failureOf(body));
+  const tokens = tokensOf(body, now);
+  return { tokens, tenantId: tenantOf(typeof body.id_token === 'string' ? body.id_token : '', tokens.accessToken) };
+}

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

@@ -0,0 +1,36 @@
+export const OUTLOOK_CLIENT_ID = 'a2fbd978-97ee-4cc9-92bb-9d9567a7bf40';
+
+export const SCOPES = [
+  'https://graph.microsoft.com/Mail.ReadWrite',
+  'https://graph.microsoft.com/Mail.Send',
+  'https://graph.microsoft.com/User.Read',
+  'offline_access',
+  'openid',
+].join(' ');
+
+export const NOT_SET_UP = 'Outlook is not set up on this Metro yet.';
+
+export const MAILBOX_URL = 'https://outlook.office.com/mail/';
+
+const trimmed = (raw: string | undefined): string => (raw ?? '').trim();
+
+export function clientId(): string {
+  const fromEnv = trimmed(process.env.METRO_OUTLOOK_CLIENT_ID);
+  return fromEnv === '' ? OUTLOOK_CLIENT_ID : fromEnv;
+}
+
+const base = (raw: string | undefined, fallback: string): string => {
+  const value = trimmed(raw);
+  return (value === '' ? fallback : value).replace(/\/+$/, '');
+};
+
+export const loginBase = (): string =>
+  base(process.env.METRO_OUTLOOK_LOGIN_URL, 'https://login.microsoftonline.com/common');
+
+export const redirectUri = (): string => {
+  const value = trimmed(process.env.METRO_OUTLOOK_REDIRECT);
+  return value === '' ? 'https://metro.box/' : value;
+};
+
+export const graphBase = (): string =>
+  base(process.env.METRO_OUTLOOK_GRAPH_URL, 'https://graph.microsoft.com/v1.0');