@oimlsmart/platform-server 0.1.0

package/src/github.ts

@@ -0,0 +1,284 @@
+// ═══════════════════════════════════════════════════════════════════
+// GitHub OAuth — the deployment's authorized sign-in
+// (docs/deployment/identity.md, "GitHub OAuth"). TWO concerns live here:
+//
+//  1. THE STATELESS OAUTH STATE. The old flow kept a per-process
+//     `Map` jar, which a sibling Worker isolate never sees — the
+//     callback then failed the state check intermittently. The state
+//     parameter is now SELF-PROVING: `<nonce>.<issuedAt>.<hmac>` where
+//     the hmac is HMAC-SHA256 over `nonce:issuedAt` keyed by the
+//     GITHUB_CLIENT_SECRET (already a deployed secret — no new secret,
+//     no D1 round trip), compared in constant time, with a 10-minute
+//     TTL. It verifies identically on node and on the Worker, so the
+//     in-memory path is GONE — this is the only path.
+//
+//  2. THE AUTHORIZED-USERS DECLARATION. Which GitHub accounts may sign
+//     in, and with which initial role, is instance policy declared in
+//     the ENV (the same env seam the OIDC config uses — hono/adapter
+//     reads process.env on node, the Worker bindings on Cloudflare):
+//
+//       GITHUB_ADMIN_LOGINS   comma-separated logins (case-insensitive)
+//                             → role `admin`.
+//       GITHUB_ALLOWED_LOGINS comma-separated logins → the default
+//                             allowed role (`cs_admin`).
+//       GITHUB_ROLE_MAP       `login:role,login2:role2` — fine-grained
+//                             initial roles. Roles validate against the
+//                             platform vocabulary (src/auth/roles.ts);
+//                             an unknown role FAILS CLOSED: the entry is
+//                             dropped, the resolution logs the problem
+//                             once, and the login falls through to the
+//                             other rules — a role is never invented.
+//       GITHUB_ALLOWED_ORG    one org slug → the sign-in checks LIVE
+//                             membership (GET /user/memberships/orgs/
+//                             {org} with the user's own token; state
+//                             `active` counts, `pending` does not) and
+//                             members get the default allowed role. The
+//                             authorization request adds the `read:org`
+//                             scope when this is set (private membership
+//                             is invisible without it).
+//
+//     Precedence is the declaration order above: admin list → role map
+//     → allowed list → org membership → denied. With NO allowlist env
+//     declared the instance is OPEN ENROLLMENT: any GitHub account signs
+//     in with role `user` (the historical behavior) and the resolution
+//     logs a boot warning — fine for a personal evaluation, unsuitable
+//     for a shared deployment.
+//
+//     The allowlist is ADMISSION CONTROL + the INITIAL role. An
+//     existing account keeps its locally assigned role and org (the
+//     admin refines them in the users section, TODO.federation/12) —
+//     but a login struck off every list is refused at the gate,
+//     whatever account it holds. Org binding is NOT derived from
+//     GitHub: every GitHub sign-in provisions with org NULL (item 3 of
+//     the work order — binding happens through the admin's user
+//     management afterwards).
+//
+//  GitHub Enterprise Server: GITHUB_OAUTH_BASE_URL /
+//  GITHUB_API_BASE_URL override the github.com endpoints (also the
+//  in-process test seam — the stub fixture rides them).
+//
+//  WORKER-SAFE: WebCrypto only (crypto.subtle / getRandomValues), no
+//  node built-ins — the Worker bundle carries this module.
+// ═══════════════════════════════════════════════════════════════════
+
+import { APP_ROLES } from './vocab/roles'
+
+type EnvLike = Record<string, string | undefined>
+
+// ── the stateless OAuth state ───────────────────────────────────────
+
+/** The state parameter's lifetime (both OAuth flows share the value). */
+export const OAUTH_STATE_TTL_MS = 10 * 60 * 1000
+
+/** Tolerance for a future-dated `issuedAt` (clock skew between the
+ *  sign-in and the callback — the signature covers the timestamp, so
+ *  only the secret holder could mint one; a wildly future state is
+ *  still refused honestly). */
+const STATE_CLOCK_SKEW_MS = 60_000
+
+function base64url(bytes: Uint8Array): string {
+  let bin = ''
+  for (const b of bytes) bin += String.fromCharCode(b)
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+async function hmacSha256(key: string, message: string): Promise<string> {
+  const cryptoKey = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(key),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  )
+  const sig = await crypto.subtle.sign('HMAC', cryptoKey, new TextEncoder().encode(message))
+  return base64url(new Uint8Array(sig))
+}
+
+/** Constant-time string equality (Workers have no
+ *  crypto.timingSafeEqual — the length check leaks only what the
+ *  attacker already knows, their own input's length). */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  return diff === 0
+}
+
+/** Mint the state parameter: a random nonce + issue time, self-proving
+ *  under HMAC. `now` is injectable for the expiry tests. */
+export async function signOAuthState(secret: string, now: number = Date.now()): Promise<string> {
+  const nonce = base64url(crypto.getRandomValues(new Uint8Array(24)))
+  const sig = await hmacSha256(secret, `${nonce}:${now}`)
+  return `${nonce}.${now}.${sig}`
+}
+
+/** Verify a presented state parameter: well-formed, inside the TTL
+ *  (± skew), and carrying the signature of `nonce:issuedAt` under the
+ *  secret — all three, constant-time on the signature. */
+export async function verifyOAuthState(
+  secret: string,
+  presented: string,
+  opts?: { now?: number; ttlMs?: number },
+): Promise<boolean> {
+  const parts = presented.split('.')
+  if (parts.length !== 3) return false
+  const [nonce, issuedAtRaw, sig] = parts as [string, string, string]
+  if (!nonce || !sig) return false
+  const issuedAt = Number(issuedAtRaw)
+  if (!Number.isFinite(issuedAt)) return false
+  const now = opts?.now ?? Date.now()
+  const ttl = opts?.ttlMs ?? OAUTH_STATE_TTL_MS
+  if (now - issuedAt > ttl) return false
+  if (issuedAt - now > STATE_CLOCK_SKEW_MS) return false
+  // The signature recomputes over the PRESENTED strings (never the
+  // re-parsed number) so no canonicalization gap opens.
+  const expected = await hmacSha256(secret, `${nonce}:${issuedAtRaw}`)
+  return timingSafeEqual(expected, sig)
+}
+
+// ── the authorized-users declaration ────────────────────────────────
+
+/** The initial role for GITHUB_ALLOWED_LOGINS members and
+ *  GITHUB_ALLOWED_ORG members (the role map refines it per login). */
+export const GITHUB_DEFAULT_ALLOWED_ROLE = 'cs_admin'
+
+export interface GitHubAuthorizationConfig {
+  /** Lowercased logins → `admin`. */
+  admins: ReadonlySet<string>
+  /** Lowercased login → validated platform role. */
+  roleMap: ReadonlyMap<string, string>
+  /** Lowercased logins → the default allowed role. */
+  allowed: ReadonlySet<string>
+  /** The org slug whose active members may sign in (null = no org check). */
+  org: string | null
+  /** TRUE when no allowlist env is declared at all: any GitHub account
+   *  signs in with role `user` (the historical posture — the resolution
+   *  logs the open-enrollment warning once). */
+  openEnrollment: boolean
+  /** The declaration's validation problems (unknown roles, malformed
+   *  pairs) — every problem means an entry was DROPPED (fail closed),
+   *  never guessed. The route logs them once per process/isolate. */
+  problems: string[]
+}
+
+function parseLoginList(raw: string | undefined): string[] {
+  return (raw ?? '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean)
+}
+
+/** Resolve + validate the allowlist declaration from the env. Pure. */
+export function resolveGitHubAuthorizationConfig(env: EnvLike): GitHubAuthorizationConfig {
+  const problems: string[] = []
+  const admins = new Set(parseLoginList(env.GITHUB_ADMIN_LOGINS))
+  const allowed = new Set(parseLoginList(env.GITHUB_ALLOWED_LOGINS))
+  const roleMap = new Map<string, string>()
+
+  const rawMap = env.GITHUB_ROLE_MAP?.trim()
+  if (rawMap) {
+    for (const pair of rawMap.split(',')) {
+      const entry = pair.trim()
+      if (!entry) continue
+      const idx = entry.indexOf(':')
+      const login = idx > 0 ? entry.slice(0, idx).trim().toLowerCase() : ''
+      const role = idx > 0 ? entry.slice(idx + 1).trim() : ''
+      if (!login || !role) {
+        problems.push(`GITHUB_ROLE_MAP entry ${JSON.stringify(entry)} is not a 'login:role' pair — the entry is ignored`)
+        continue
+      }
+      if (!(APP_ROLES as readonly string[]).includes(role)) {
+        problems.push(
+          `GITHUB_ROLE_MAP entry for ${JSON.stringify(login)} names the unknown role ${JSON.stringify(role)} — `
+          + `the entry is ignored (fail closed; the platform roles are ${APP_ROLES.join(', ')})`,
+        )
+        continue
+      }
+      roleMap.set(login, role)
+    }
+  }
+
+  const org = env.GITHUB_ALLOWED_ORG?.trim() || null
+  // Open enrollment keys on the DECLARATION, not the post-validation
+  // set: a deployment that declares only a broken role map fails
+  // CLOSED (every login denied), never silently open.
+  const declared = !!(
+    env.GITHUB_ADMIN_LOGINS?.trim()
+    || env.GITHUB_ALLOWED_LOGINS?.trim()
+    || rawMap
+    || org
+  )
+  return { admins, allowed, roleMap, org, openEnrollment: !declared, problems }
+}
+
+/** Where a login stands BEFORE the live org-membership check. */
+export type GitHubListResolution =
+  | { kind: 'listed'; role: string; via: 'admin_logins' | 'role_map' | 'allowed_logins' }
+  /** Not in any list, but GITHUB_ALLOWED_ORG is declared — the live
+   *  membership check decides. */
+  | { kind: 'org_check' }
+  /** Open enrollment: any GitHub account, role `user`. */
+  | { kind: 'open' }
+  | { kind: 'denied' }
+
+/** The pure per-login resolution: admin list → role map → allowed list
+ *  → org check → denied (open enrollment short-circuits to 'open').
+ *  Logins compare case-insensitively (GitHub treats them so). */
+export function resolveGitHubLogin(config: GitHubAuthorizationConfig, login: string): GitHubListResolution {
+  const l = login.trim().toLowerCase()
+  if (config.admins.has(l)) return { kind: 'listed', role: 'admin', via: 'admin_logins' }
+  const mapped = config.roleMap.get(l)
+  if (mapped) return { kind: 'listed', role: mapped, via: 'role_map' }
+  if (config.allowed.has(l)) return { kind: 'listed', role: GITHUB_DEFAULT_ALLOWED_ROLE, via: 'allowed_logins' }
+  if (config.org) return { kind: 'org_check' }
+  if (config.openEnrollment) return { kind: 'open' }
+  return { kind: 'denied' }
+}
+
+// ── the GitHub endpoints (github.com, or GHES / the test stub) ──────
+
+export interface GitHubEndpoints {
+  /** The OAuth web flow base (https://github.com). */
+  oauthBase: string
+  /** The REST API base (https://api.github.com). */
+  apiBase: string
+}
+
+/** The endpoints this instance talks to — github.com by default, the
+ *  GITHUB_*_BASE_URL overrides for GitHub Enterprise Server (and the
+ *  in-process tests' stub). */
+export function gitHubEndpoints(env: EnvLike): GitHubEndpoints {
+  const trim = (v: string | undefined) => v?.trim().replace(/\/+$/, '') || ''
+  return {
+    oauthBase: trim(env.GITHUB_OAUTH_BASE_URL) || 'https://github.com',
+    apiBase: trim(env.GITHUB_API_BASE_URL) || 'https://api.github.com',
+  }
+}
+
+/** The OAuth scope request: the base identity scopes, plus `read:org`
+ *  when an org gate is declared (a private membership is invisible
+ *  without it — the check would fail closed against real members). */
+export function gitHubScopes(env: EnvLike): string {
+  const base = 'read:user user:email'
+  return env.GITHUB_ALLOWED_ORG?.trim() ? `${base} read:org` : base
+}
+
+/** The LIVE org-membership check: the user's own membership record in
+ *  the declared org. `active` counts; `pending` (an invitation not yet
+ *  accepted) does not. Any non-200 — not a member, an org that does not
+ *  exist, a token that cannot see the membership — is NOT a member:
+ *  fail closed. */
+export async function checkGitHubOrgMembership(
+  apiBase: string,
+  org: string,
+  accessToken: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<boolean> {
+  try {
+    const res = await fetchImpl(`${apiBase}/user/memberships/orgs/${encodeURIComponent(org)}`, {
+      headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/vnd.github+json' },
+    })
+    if (!res.ok) return false
+    const body = await res.json() as { state?: string }
+    return body.state === 'active'
+  } catch {
+    return false
+  }
+}

package/src/mailer.ts

@@ -0,0 +1,309 @@
+// ═══════════════════════════════════════════════════════════════════
+// The transactional mailer (TODO.identity/09) — ONE send interface with
+// three postures, resolved from the environment, best first:
+//
+//   1. send_email — the Cloudflare Email Service (public beta): the
+//      Worker's `send_email` binding (env.EMAIL) + EMAIL_FROM. The
+//      binding's builder form carries { from, to, subject, text, html }
+//      — no raw MIME to compose. Domain authentication (SPF/DKIM/DMARC
+//      on oimlsmart.org) is the operator act documented in
+//      docs/deployment/cloudflare.md; without it the binding sends
+//      nothing deliverable, which is why it ships commented-out in
+//      wrangler.toml.
+//   2. https — a small HTTPS mail provider (Resend is the documented
+//      choice: a simple JSON POST API, a free tier, the key a Worker
+//      secret). MAIL_PROVIDER_URL + MAIL_PROVIDER_KEY + EMAIL_FROM; the
+//      request shape is Resend's POST /emails ({ from, to, subject,
+//      text, html } with a Bearer key), so any provider speaking that
+//      shape plugs in by URL alone.
+//   3. console — the honest no-op when no provider is configured: the
+//      message is LOGGED in full (the setup link lands in the deploy
+//      log, the OP_ACCOUNT_SEED posture) and the result says not-sent,
+//      so the triggering flow keeps SHOWING the link (the invite card's
+//      copy path). NEVER a silent drop.
+//
+// Every send — sent, failed, logged, rate-limited — writes an audit
+// event (entity_type 'email': recipient, template, posture, result).
+// Sends are RATE-LIMITED per recipient (a token bucket, in-memory per
+// process/isolate — the federation limiter's documented posture; a
+// global limit needs a durable counter, deliberately out of scope):
+//
+//   MAIL_RATE_LIMIT_CAPACITY    messages per window per recipient
+//                               (default 5; 0 disables the limiter,
+//                               honestly)
+//   MAIL_RATE_LIMIT_WINDOW_MS   the window (default 3_600_000 — 1 h)
+//
+// The mailer NEVER throws from send(): a transport failure is a result
+// ({ ok: false, error }), never an exception into the triggering flow.
+//
+// WORKER-SAFE: fetch + the store seam only, no node built-ins.
+// ═══════════════════════════════════════════════════════════════════
+
+import { getStore } from './store'
+
+/** The env as the mailer reads it: strings on node, plus the Worker's
+ *  object bindings on Cloudflare (the EMAIL send_email binding). */
+export type MailEnv = Record<string, unknown>
+
+export interface MailMessage {
+  to: string
+  subject: string
+  text: string
+  html?: string
+}
+
+export type MailPosture = 'send_email' | 'https' | 'console'
+
+export interface MailSendResult {
+  ok: boolean
+  posture: MailPosture
+  /** Named when ok is false (the provider's answer, bounded; the
+   *  no-provider posture's 'not configured'; the rate-limit refusal). */
+  error?: string
+  rateLimited?: boolean
+}
+
+/** The minimal shape of the Cloudflare Email Service binding (the
+ *  workers-types `SendEmail`'s builder form), declared structurally so
+ *  this module never imports the worker types. */
+export interface SendEmailBinding {
+  send(message: {
+    from: string
+    to: string
+    subject: string
+    text?: string
+    html?: string
+  }): Promise<unknown>
+}
+
+export interface MailerConfig {
+  posture: MailPosture
+  /** The From address (EMAIL_FROM) — required by both real postures. */
+  from: string | null
+  binding: SendEmailBinding | null
+  providerUrl: string | null
+  providerKey: string | null
+  rateLimit: { capacity: number; windowMs: number }
+  /** Every configuration problem, named (logged once per config change —
+   *  a misdeclared mailer must never silently degrade). */
+  problems: string[]
+}
+
+export const MAIL_RATE_LIMIT_DEFAULTS = { capacity: 5, windowMs: 3_600_000 }
+
+/** The provider call's ceiling — a hung provider must never hold the
+ *  triggering request. */
+export const MAIL_TIMEOUT_MS = 10_000
+
+/** Read the env into the effective configuration. PURE (the tests drive
+ *  every posture through it). */
+export function resolveMailerConfig(env: MailEnv): MailerConfig {
+  const problems: string[] = []
+  const str = (name: string): string | null => {
+    const v = env[name]
+    return typeof v === 'string' && v.trim() ? v.trim() : null
+  }
+  const bindingCandidate = env.EMAIL as SendEmailBinding | undefined
+  const binding = bindingCandidate && typeof bindingCandidate.send === 'function' ? bindingCandidate : null
+  const from = str('EMAIL_FROM')
+  const providerUrl = str('MAIL_PROVIDER_URL')
+  const providerKey = str('MAIL_PROVIDER_KEY')
+
+  if (binding && !from) problems.push('the EMAIL send_email binding is present but EMAIL_FROM is unset — the binding posture is skipped')
+  if ((providerUrl || providerKey) && !(providerUrl && providerKey)) {
+    problems.push('MAIL_PROVIDER_URL and MAIL_PROVIDER_KEY must be set together — the HTTPS provider posture is skipped')
+  } else if (providerUrl && providerKey && !from) {
+    problems.push('MAIL_PROVIDER_URL is set but EMAIL_FROM is unset — the HTTPS provider posture is skipped')
+  }
+  if (!binding && !(providerUrl && providerKey && from)) {
+    problems.push('no mail provider is configured (no EMAIL binding, no MAIL_PROVIDER_URL+MAIL_PROVIDER_KEY) — messages are logged, never delivered; the flows keep showing their links')
+  }
+
+  let capacity = MAIL_RATE_LIMIT_DEFAULTS.capacity
+  const rawCapacity = str('MAIL_RATE_LIMIT_CAPACITY')
+  if (rawCapacity !== null) {
+    const parsed = Number(rawCapacity)
+    if (!Number.isInteger(parsed) || parsed < 0) {
+      problems.push(`MAIL_RATE_LIMIT_CAPACITY is not a non-negative integer: ${JSON.stringify(rawCapacity)} — the default ${MAIL_RATE_LIMIT_DEFAULTS.capacity} applies`)
+    } else {
+      capacity = parsed
+    }
+  }
+  let windowMs = MAIL_RATE_LIMIT_DEFAULTS.windowMs
+  const rawWindow = str('MAIL_RATE_LIMIT_WINDOW_MS')
+  if (rawWindow !== null) {
+    const parsed = Number(rawWindow)
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+      problems.push(`MAIL_RATE_LIMIT_WINDOW_MS is not a positive integer: ${JSON.stringify(rawWindow)} — the default ${MAIL_RATE_LIMIT_DEFAULTS.windowMs} applies`)
+    } else {
+      windowMs = parsed
+    }
+  }
+
+  const posture: MailPosture = binding && from ? 'send_email' : providerUrl && providerKey && from ? 'https' : 'console'
+  return { posture, from, binding, providerUrl, providerKey, rateLimit: { capacity, windowMs }, problems }
+}
+
+export interface Mailer {
+  readonly config: MailerConfig
+  send(message: MailMessage, meta?: { template?: string }): Promise<MailSendResult>
+}
+
+/** The audit trail on every send outcome (the spec's invariant) —
+ *  logged, never thrown (the audit never blocks the path). */
+async function auditSend(
+  action: 'email.sent' | 'email.failed' | 'email.logged' | 'email.rate_limited',
+  message: MailMessage,
+  meta: { template?: string; posture: MailPosture; error?: string },
+): Promise<void> {
+  try {
+    const id = crypto.randomUUID()
+    await getStore().putEntity('auditEvents', id, null, JSON.stringify({
+      id,
+      timestamp: new Date().toISOString(),
+      standard_id: '',
+      entity_type: 'email',
+      entity_id: message.to,
+      action,
+      metadata: {
+        subject: message.subject,
+        template: meta.template ?? null,
+        posture: meta.posture,
+        error: meta.error ?? null,
+      },
+    }))
+  } catch (err) {
+    console.error('[mail] the send audit failed to persist:', (err as Error).message)
+  }
+}
+
+interface Bucket {
+  tokens: number
+  resetAt: number
+}
+
+/** Build the mailer over a resolved configuration. `now`/`fetcher` are
+ *  the tests' seams (the clock, the stubbed provider). */
+export function createMailer(config: MailerConfig, deps?: { now?: () => number; fetcher?: typeof fetch }): Mailer {
+  const now = deps?.now ?? (() => Date.now())
+  const fetcher = deps?.fetcher ?? fetch
+  const buckets = new Map<string, Bucket>()
+
+  async function transport(message: MailMessage): Promise<MailSendResult> {
+    if (config.posture === 'send_email') {
+      await config.binding!.send({
+        from: config.from!,
+        to: message.to,
+        subject: message.subject,
+        text: message.text,
+        ...(message.html ? { html: message.html } : {}),
+      })
+      return { ok: true, posture: 'send_email' }
+    }
+    if (config.posture === 'https') {
+      const res = await fetcher(config.providerUrl!, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          authorization: `Bearer ${config.providerKey}`,
+        },
+        body: JSON.stringify({
+          from: config.from,
+          to: message.to,
+          subject: message.subject,
+          text: message.text,
+          ...(message.html ? { html: message.html } : {}),
+        }),
+        signal: AbortSignal.timeout(MAIL_TIMEOUT_MS),
+      })
+      if (!res.ok) {
+        const body = (await res.text().catch(() => '')).slice(0, 300)
+        return { ok: false, posture: 'https', error: `the mail provider answered ${res.status}${body ? `: ${body}` : ''}` }
+      }
+      return { ok: true, posture: 'https' }
+    }
+    // The console posture: the honest no-op. The message is logged in
+    // full (the link survives in the deploy log) and the result says
+    // not-sent, so the triggering flow keeps showing its own link.
+    console.warn(
+      `[mail] no provider configured — the message for ${message.to} is NOT delivered (the flow shows its link instead).\n`
+      + `  subject: ${message.subject}\n`
+      + message.text.split('\n').map(l => `  ${l}`).join('\n'),
+    )
+    return { ok: false, posture: 'console', error: 'no mail provider is configured on this deployment' }
+  }
+
+  return {
+    config,
+    async send(message, meta) {
+      const recipient = message.to.trim().toLowerCase()
+      const { capacity, windowMs } = config.rateLimit
+      if (capacity > 0) {
+        const at = now()
+        let bucket = buckets.get(recipient)
+        if (!bucket || at >= bucket.resetAt) {
+          bucket = { tokens: capacity, resetAt: at + windowMs }
+          buckets.set(recipient, bucket)
+        }
+        if (bucket.tokens <= 0) {
+          const error = `rate limited — this recipient already received ${capacity} message(s) within the window`
+          await auditSend('email.rate_limited', message, { template: meta?.template, posture: config.posture, error })
+          return { ok: false, posture: config.posture, error, rateLimited: true }
+        }
+        bucket.tokens -= 1
+      }
+
+      let result: MailSendResult
+      try {
+        result = await transport(message)
+      } catch (err) {
+        result = { ok: false, posture: config.posture, error: (err as Error).message }
+      }
+      await auditSend(
+        result.ok ? 'email.sent' : config.posture === 'console' ? 'email.logged' : 'email.failed',
+        message,
+        { template: meta?.template, posture: result.posture, error: result.error },
+      )
+      return result
+    },
+  }
+}
+
+// ── the per-process mailer slot ──────────────────────────────────────
+// The rate-limit buckets must survive across requests (a mailer rebuilt
+// per request would reset them), so the composition roots resolve
+// through this slot: ONE mailer per effective configuration, rebuilt
+// when the env's mail surface changes (a test mutating process.env, an
+// isolate booting with the binding). Per-ISOLATE on the Worker — the
+// rate limiter's documented posture, same as the federation one.
+
+let cached: { fingerprint: string; mailer: Mailer } | null = null
+
+function fingerprintOf(config: MailerConfig): string {
+  return JSON.stringify([
+    config.posture,
+    config.from,
+    config.providerUrl,
+    config.providerKey ? 'key-set' : null, // never the key itself
+    !!config.binding,
+    config.rateLimit.capacity,
+    config.rateLimit.windowMs,
+  ])
+}
+
+/** The process's mailer for this env (built once per configuration;
+ *  the configuration problems log once per build, not per request). */
+export function mailerFor(env: MailEnv): Mailer {
+  const config = resolveMailerConfig(env)
+  const fingerprint = fingerprintOf(config)
+  if (!cached || cached.fingerprint !== fingerprint) {
+    for (const problem of config.problems) console.warn(`[mail] ${problem}`)
+    cached = { fingerprint, mailer: createMailer(config) }
+  }
+  return cached.mailer
+}
+
+/** Test seam: drop the cached mailer (the next mailerFor re-resolves). */
+export function resetMailerForTest(): void {
+  cached = null
+}