toiljs 0.0.88 → 0.0.90

package/server/globals/auth.ts

@@ -117,8 +117,8 @@ function __fromHex(s: string): Uint8Array {
     return out;
 }
 
-/** The session HMAC secret (UTF-8 of the env value or the DEV fallback). */
-function __resolveSessionSecret(): Uint8Array {
+/** The BASE session HMAC secret (UTF-8 of the env value or the DEV fallback). */
+function __resolveSessionSecretBase(): Uint8Array {
     let s = __sessionSecret;
     if (s != null) return s;
     const v = Environment.getSecure(ENV_SESSION_SECRET);
@@ -126,6 +126,48 @@ function __resolveSessionSecret(): Uint8Array {
     __sessionSecret = s;
     return s;
 }
+
+/** A stable per-TENANT tag: the request Host the edge routes on, lowercased and
+ *  port-stripped (matching the edge's `strip_port`), so it is identical for every
+ *  request to one tenant and distinct across tenants. Used to bind a session to
+ *  its tenant (below). */
+function __sessionTenantTag(): string {
+    const req = Server.currentRequest;
+    if (req == null) return '';
+    const raw = req.header('host');
+    if (raw == null) return '';
+    let h = raw.toLowerCase();
+    if (h.startsWith('[')) {
+        // IPv6 literal `[addr]` optionally + `:port`: keep through the closing
+        // bracket, drop any port after it. A naive lastIndexOf(':') would slice
+        // inside the address (`[::1]` -> `[:`), collapsing distinct IPv6 tenants
+        // to the same tag. Bracket-aware, matching the edge's strip_port.
+        const close = h.indexOf(']');
+        if (close >= 0) h = h.slice(0, close + 1);
+    } else {
+        const colon = h.lastIndexOf(':');
+        if (colon > 0) h = h.slice(0, colon); // drop :port (mirrors edge strip_port)
+    }
+    return h;
+}
+
+/**
+ * The session HMAC key, BOUND TO THE TENANT. We fold the tenant tag into the base
+ * secret so a session sealed for tenant B does NOT verify on tenant A even if both
+ * resolve the SAME base secret (e.g. an unconfigured multi-tenant deployment
+ * sharing the published dev fallback). `mintSession` and `getSessionBytes` both
+ * call this within one request instance, so they derive the same key for the same
+ * tenant; a cross-tenant replay derives a different key and fails to open. This
+ * makes the base secret no longer the SOLE cross-tenant isolator — still set a
+ * distinct `AUTH_SESSION_SECRET` per deployment; this is defense-in-depth.
+ */
+function __resolveSessionSecret(): Uint8Array {
+    const base = __resolveSessionSecretBase();
+    const tag = Uint8Array.wrap(
+        String.UTF8.encode('toil-session-tenant-bind-v1:' + __sessionTenantTag()),
+    );
+    return __hmacSha256(base, tag);
+}
 /** The OPRF master seed, hashed to 32 bytes (RFC 9497 Ns) so any env value works. */
 function __resolveOprfSeed(): Uint8Array {
     let s = __oprfSeed;

package/server/globals/email.ts

@@ -24,6 +24,17 @@
 @external('env', 'email_send')
 declare function __toilEmailSend(reqPtr: usize, reqLen: i32): i32;
 
+// Host import: submit one email FIRE-AND-FORGET and return immediately (does NOT
+// suspend). Same wire blob as `email_send`; the host validates + queues then
+// returns a queue-accept status without parking on the provider round-trip. Used
+// for transactional sends whose delivery result the caller does not need, so the
+// send is constant-time regardless of whether the recipient exists (this closes
+// the auth email-enumeration timing oracle). A tenant that never calls
+// `sendDetached` tree-shakes this import away.
+// @ts-ignore: decorator
+@external('env', 'email_send_detached')
+declare function __toilEmailSendDetached(reqPtr: usize, reqLen: i32): i32;
+
 /**
  * The result of a send. Kept in sync with `EmailStatus` in toil-backend
  * `email.rs` (`#[repr(i32)]`). `Sent` and `Deduped` are success; the rest say
@@ -68,6 +79,48 @@ export namespace EmailService {
         purpose: string = 'tx',
         html: string = '',
     ): EmailStatus {
+        const buf = frameRequest(to, subject, body, purpose, html);
+        return <EmailStatus>__toilEmailSend(buf.dataStart, buf.length);
+    }
+
+    /**
+     * FIRE-AND-FORGET send: frame the SAME wire request as {@link send} but submit
+     * it via the NON-SUSPENDING `email_send_detached` host import, which validates
+     * + queues the message and returns IMMEDIATELY (constant time) without parking
+     * on the provider round-trip. Use it for transactional mail (confirm/reset
+     * links) whose delivery result the caller does not need: because it does not
+     * block on the send, the response time no longer reveals whether the recipient
+     * maps to an account (the auth email-enumeration timing oracle).
+     *
+     * The returned {@link EmailStatus} is a QUEUE-ACCEPT status, not a delivery
+     * result: `Sent` means "accepted/queued" (the final provider outcome is not
+     * awaited); `Disabled` / `BadRecipient` / `TryLater` are the pre-submit
+     * rejects. The host records the true final outcome for `/_admin/email`.
+     */
+    export function sendDetached(
+        to: string,
+        subject: string,
+        body: string,
+        purpose: string = 'tx',
+        html: string = '',
+    ): EmailStatus {
+        const buf = frameRequest(to, subject, body, purpose, html);
+        return <EmailStatus>__toilEmailSendDetached(buf.dataStart, buf.length);
+    }
+
+    /**
+     * Frame one email request blob (the v2 wire format) into a fresh buffer the
+     * caller passes straight to a host import. Shared by {@link send} and
+     * {@link sendDetached} so their wire encoding can never drift; the caller
+     * keeps the returned buffer live across the (synchronous) import call.
+     */
+    function frameRequest(
+        to: string,
+        subject: string,
+        body: string,
+        purpose: string,
+        html: string,
+    ): Uint8Array {
         const toB = Uint8Array.wrap(String.UTF8.encode(to));
         const subjB = Uint8Array.wrap(String.UTF8.encode(subject));
         const purpB = Uint8Array.wrap(String.UTF8.encode(purpose));
@@ -98,7 +151,7 @@ export namespace EmailService {
         off += bodyB.length;
         memory.copy(off, htmlB.dataStart, htmlB.length);
 
-        return <EmailStatus>__toilEmailSend(base, total);
+        return buf;
     }
 }
 

package/src/client/auth.ts

@@ -207,6 +207,7 @@ export interface AuthOptions {
 export async function register(
     username: string,
     password: string,
+    email: string,
     opts: AuthOptions = {},
 ): Promise<void> {
     const baseUrl = opts.baseUrl ?? '/auth';
@@ -247,14 +248,20 @@ export async function register(
     }
     if (publicKey.length !== PUBLIC_KEY_LEN) throw new Error('auth: bad public key length');
 
-    // 3. Submit the public key + proof-of-possession.
+    // 3. Submit the username + email + public key + proof-of-possession.
     const finish = await postBinary(
         baseUrl,
         '/register/finish',
-        new DataWriter().writeString(username).writeBytes(publicKey).writeBytes(regProof).toBytes(),
+        new DataWriter()
+            .writeString(username)
+            .writeString(email)
+            .writeBytes(publicKey)
+            .writeBytes(regProof)
+            .toBytes(),
     );
     const finishStatus = finish.readU8();
     if (finishStatus === 1) throw new Error('auth: username already registered (log in instead)');
+    if (finishStatus === 2) throw new Error('auth: email already in use');
     if (finishStatus !== 0) throw new Error('auth: registration rejected');
 }
 
@@ -338,7 +345,15 @@ export async function login(
         '/login/finish',
         new DataWriter().writeBytes(cid).writeBytes(cipherText).writeBytes(signature).toBytes(),
     );
-    if (res.readU8() !== 0) {
+    const loginStatus = res.readU8();
+    if (loginStatus === 2) {
+        // The credential verified, but the domain requires a confirmed email and
+        // this account is not confirmed yet. Distinguishable so the UI can prompt
+        // "confirm your email" / offer a resend, rather than a generic failure.
+        wipe(sharedSecret);
+        throw new EmailNotConfirmedError();
+    }
+    if (loginStatus !== 0) {
         wipe(sharedSecret);
         throw new Error('auth: login failed');
     }
@@ -364,5 +379,116 @@ export async function login(
     return session; // session token
 }
 
+/** Thrown by {@link login} when the credential is valid but the account's email
+ *  is not confirmed and the domain requires confirmation. Catch it to prompt the
+ *  user to confirm (and offer {@link resendConfirmation}). */
+export class EmailNotConfirmedError extends Error {
+    constructor() {
+        super('auth: email not confirmed');
+        this.name = 'EmailNotConfirmedError';
+    }
+}
+
+/** Confirm an account from the one-time token in the emailed link
+ *  (`/confirm?token=<hex>`). Throws if the token is invalid or expired. */
+export async function confirmEmail(token: string, opts: AuthOptions = {}): Promise<void> {
+    const baseUrl = opts.baseUrl ?? '/auth';
+    const res = await postBinary(
+        baseUrl,
+        '/confirm',
+        new DataWriter().writeBytes(fromHex(token)).toBytes(),
+    );
+    if (res.readU8() !== 0) throw new Error('auth: confirmation link invalid or expired');
+}
+
+/** Ask the server to re-send the confirmation email. Resolves regardless of
+ *  whether the email maps to an unconfirmed account (the server never reveals
+ *  it): treat success as "if that address needs confirming, a link is on its
+ *  way." */
+export async function resendConfirmation(email: string, opts: AuthOptions = {}): Promise<void> {
+    const baseUrl = opts.baseUrl ?? '/auth';
+    await postBinary(baseUrl, '/confirm/resend', new DataWriter().writeString(email).toBytes());
+}
+
+/** Begin a password reset: ask the server to email a reset link. Resolves
+ *  regardless of whether the email exists (anti-enumeration) — always show the
+ *  user "if that email exists, a reset link is on its way." */
+export async function requestPasswordReset(email: string, opts: AuthOptions = {}): Promise<void> {
+    const baseUrl = opts.baseUrl ?? '/auth';
+    await postBinary(baseUrl, '/reset/request', new DataWriter().writeString(email).toBytes());
+}
+
+/**
+ * Complete a password reset from the one-time token in the emailed link
+ * (`/reset?token=<hex>`) and a NEW password. Mirrors registration's crypto: the
+ * new password is blinded through the OPRF, stretched with Argon2id into a fresh
+ * ML-DSA keypair, and only the new public key (+ a proof-of-possession) is sent;
+ * the server overwrites the stored login key. The username is recovered from the
+ * token server-side, so the caller only needs the token + the new password.
+ * Throws (generic) if the token is invalid or expired.
+ */
+export async function resetPassword(
+    token: string,
+    newPassword: string,
+    opts: AuthOptions = {},
+): Promise<void> {
+    const baseUrl = opts.baseUrl ?? '/auth';
+    const rawToken = fromHex(token);
+    const oprf = ristretto255_oprf.oprf;
+    const pw = utf8(newPassword.normalize('NFKC'));
+
+    // 1. Peek the token + OPRF-evaluate the new blinded password. The server
+    //    returns the account's username + KDF params (the token is not consumed
+    //    until finish).
+    const { blind, blinded } = oprf.blind(pw);
+    const start = await postBinary(
+        baseUrl,
+        '/reset/start',
+        new DataWriter().writeBytes(rawToken).writeBytes(blinded).toBytes(),
+    );
+    if (start.readU8() !== 0) throw new Error('auth: reset link invalid or expired');
+    const username = start.readString();
+    const kdf = decodeKdf(start);
+    const evaluated = start.readBytes();
+
+    // 2. OPRF -> keyed salt -> seed -> NEW keypair; keep only the public key + a
+    //    PoP over it. Wipe the secret key and seed immediately.
+    const oprfOutput = oprf.finalize(pw, blind, evaluated);
+    const seed = await deriveSeed(oprfOutput, kdf);
+    let publicKey: Uint8Array;
+    let regProof: Uint8Array;
+    try {
+        const kp = ml_dsa44.keygen(seed);
+        publicKey = kp.publicKey;
+        try {
+            regProof = ml_dsa44.sign(buildRegisterMessage(username, publicKey), kp.secretKey, {
+                context: utf8(REGISTER_CONTEXT),
+            });
+        } finally {
+            wipe(kp.secretKey);
+        }
+    } finally {
+        wipe(seed);
+    }
+    if (publicKey.length !== PUBLIC_KEY_LEN) throw new Error('auth: bad public key length');
+
+    // 3. Consume the token + overwrite the stored login key.
+    const finish = await postBinary(
+        baseUrl,
+        '/reset/finish',
+        new DataWriter().writeBytes(rawToken).writeBytes(publicKey).writeBytes(regProof).toBytes(),
+    );
+    if (finish.readU8() !== 0) throw new Error('auth: password reset rejected');
+}
+
 /** The client auth surface, grouped for `Auth.register` / `Auth.login` use. */
-export const Auth = { register, login, buildLoginMessage, LOGIN_CONTEXT } as const;
+export const Auth = {
+    register,
+    login,
+    confirmEmail,
+    resendConfirmation,
+    requestPasswordReset,
+    resetPassword,
+    buildLoginMessage,
+    LOGIN_CONTEXT,
+} as const;

package/src/devserver/analytics/index.ts

@@ -16,9 +16,11 @@ import type { MemoryRef } from '../runtime/host.js';
 
 /** Frame version + counter count, kept in lockstep with the edge (`analytics.rs` / `metric_id.rs`). */
 const FRAME_VERSION = 2;
-const METRIC_COUNTERS = 43;
-/** MetricId indices we seed with sample data (others default 0). Mirrors the wire contract
- *  (counter ids 0..=42; gauge ids ConnectedStreamsAvg=43, CommittedMemoryAvg=45). */
+const METRIC_COUNTERS = 42;
+/** MetricId indices we seed with sample data (others default 0). Mirrors the AUTHORITATIVE edge wire
+ *  contract EXACTLY (`toil-backend/src/analytics/metric_id.rs`): counter ids 0..=41, gauge ids
+ *  ConnectedStreamsAvg=42, CommittedMemoryAvg=44. There is NO WasmDispatches (removed + reindexed); the
+ *  edge/guest are 42, so this must be 42 with matching indices or the dashboard mislabels every metric. */
 const MID = {
     Requests: 0,
     BytesOutL1: 1,
@@ -26,16 +28,15 @@ const MID = {
     Status2xx: 3,
     Status4xx: 5,
     StaticHits: 7,
-    WasmDispatches: 8,
-    GasUsed: 12,
-    DbOps: 13,
-    DbReads: 14,
-    DbWrites: 15,
-    StreamBytesIn: 25,
-    StreamBytesOut: 26,
-    MemGrownBytes: 39,
-    CacheHits: 41,
-    CacheMisses: 42,
+    GasUsed: 11,
+    DbOps: 12,
+    DbReads: 13,
+    DbWrites: 14,
+    StreamBytesIn: 24,
+    StreamBytesOut: 25,
+    MemGrownBytes: 38,
+    CacheHits: 40,
+    CacheMisses: 41,
 } as const;
 
 interface DevTenantStats {
@@ -46,6 +47,14 @@ interface DevTenantStats {
     reqMinuteCap: number;
     reqDayUsed: number;
     reqDayCap: number;
+    // LIVE per-second rates (f64), appended after the windows. Mirrors the edge `encode_stats`.
+    rps: number;
+    bytesInPerSec: number;
+    bytesOutPerSec: number;
+    streamBytesInPerSec: number;
+    streamBytesOutPerSec: number;
+    dbOpsPerSec: number;
+    gasPerSec: number;
     nowMs: number;
 }
 
@@ -58,7 +67,6 @@ function devStats(): DevTenantStats {
     life[MID.Status2xx] = 40n;
     life[MID.Status4xx] = 2n;
     life[MID.StaticHits] = 8n;
-    life[MID.WasmDispatches] = 34n;
     life[MID.GasUsed] = 1_000_000n;
     life[MID.DbOps] = 17n;
     life[MID.DbReads] = 12n;
@@ -76,39 +84,63 @@ function devStats(): DevTenantStats {
         reqMinuteCap: 100,
         reqDayUsed: 42,
         reqDayCap: 5000,
+        // Plausible non-zero live rates so a dev dashboard shows moving gauges.
+        rps: 0.7,
+        bytesInPerSec: 68.2,
+        bytesOutPerSec: 205.75,
+        streamBytesInPerSec: 34.1,
+        streamBytesOutPerSec: 136.5,
+        dbOpsPerSec: 0.28,
+        gasPerSec: 16_666.67,
         nowMs: 1_700_000_000_000,
     };
 }
 
 /**
  * Encode the v2 snapshot frame BYTE-FOR-BYTE like the edge (`analytics.rs` `encode_stats`), FIXED
- * layout (no strings):
- *   u16 version | u64 now_ms | u32 count | i64 × count | i64 connectedStreams | i64 committedMemory |
- *   i64 reqMinuteUsed | u64 reqMinuteCap | i64 reqDayUsed | u64 reqDayCap
+ * layout (no strings). Counters/levels are u64; the 7 trailing LIVE per-second rates are f64:
+ *   u16 version | u64 now_ms | u32 count | u64 × count | u64 connectedStreams | u64 committedMemory |
+ *   u64 reqMinuteUsed | u64 reqMinuteCap | u64 reqDayUsed | u64 reqDayCap |
+ *   f64 rps | f64 bytesInPerSec | f64 bytesOutPerSec | f64 streamBytesInPerSec |
+ *   f64 streamBytesOutPerSec | f64 dbOpsPerSec | f64 gasPerSec
+ * The rates are APPENDED (version-gated by length): the guest's bounds-checked reader yields 0.0 for a
+ * pre-rates frame, so an older edge stays decodable.
  */
 function encodeStats(s: DevTenantStats): Buffer {
     const head = Buffer.alloc(2 + 8 + 4);
     head.writeUInt16LE(FRAME_VERSION, 0);
     head.writeBigUInt64LE(BigInt(s.nowMs), 2);
     head.writeUInt32LE(s.life.length, 10);
-    const body = Buffer.alloc(s.life.length * 8 + 48);
+    // 6 window u64s (48 bytes) + 7 rate f64s (56 bytes).
+    const body = Buffer.alloc(s.life.length * 8 + 48 + 56);
     let o = 0;
     for (const v of s.life) {
-        body.writeBigInt64LE(v, o);
+        body.writeBigUInt64LE(v, o);
         o += 8;
     }
-    body.writeBigInt64LE(BigInt(s.connectedStreams), o); o += 8;
-    body.writeBigInt64LE(BigInt(s.committedMemory), o); o += 8;
-    body.writeBigInt64LE(BigInt(s.reqMinuteUsed), o); o += 8;
+    body.writeBigUInt64LE(BigInt(s.connectedStreams), o); o += 8;
+    body.writeBigUInt64LE(BigInt(s.committedMemory), o); o += 8;
+    body.writeBigUInt64LE(BigInt(s.reqMinuteUsed), o); o += 8;
     body.writeBigUInt64LE(BigInt(s.reqMinuteCap), o); o += 8;
-    body.writeBigInt64LE(BigInt(s.reqDayUsed), o); o += 8;
-    body.writeBigUInt64LE(BigInt(s.reqDayCap), o);
+    body.writeBigUInt64LE(BigInt(s.reqDayUsed), o); o += 8;
+    body.writeBigUInt64LE(BigInt(s.reqDayCap), o); o += 8;
+    body.writeDoubleLE(s.rps, o); o += 8;
+    body.writeDoubleLE(s.bytesInPerSec, o); o += 8;
+    body.writeDoubleLE(s.bytesOutPerSec, o); o += 8;
+    body.writeDoubleLE(s.streamBytesInPerSec, o); o += 8;
+    body.writeDoubleLE(s.streamBytesOutPerSec, o); o += 8;
+    body.writeDoubleLE(s.dbOpsPerSec, o); o += 8;
+    body.writeDoubleLE(s.gasPerSec, o);
     return Buffer.concat([head, body]);
 }
 
-/** The metric ids carried in the per-minute ring (mirrors the edge `MINUTE_RING_METRICS`). Only these get
- *  minute resolution on the 1h/6h ranges; every other metric falls back to the hour ring there. */
-const MINUTE_RING_METRICS = new Set<number>([0, 2, 1, 25, 26, 12, 13, 39, 43, 45]);
+/** The metric ids carried in the per-minute ring (mirrors the edge `MINUTE_RING_METRICS` in
+ *  `toil-backend/src/analytics/ring.rs` EXACTLY). Only these get minute resolution on the 1h/6h ranges;
+ *  every other metric falls back to the hour ring there. These are the AUTHORITATIVE edge ids
+ *  (Requests=0, BytesInL1=2, BytesOutL1=1, GasUsed=11, DbOps=12, StreamBytesIn=24, StreamBytesOut=25,
+ *  MemGrownBytes=38, ConnectedStreamsAvg=42, CommittedMemoryAvg=44) -- must match the reindexed layout or
+ *  the dev 1h/6h graphs pick the wrong ring for these metrics. */
+const MINUTE_RING_METRICS = new Set<number>([0, 1, 2, 11, 12, 24, 25, 38, 42, 44]);
 
 /**
  * Range id -> (bucketCount, bucketSecs), matching the edge `Range` + minute-ring fallback: 1h/6h are
@@ -126,13 +158,15 @@ function rangeShape(range: number, metricId: number): { count: number; bucketSec
         case 5: return { count: 168, bucketSecs: 3600 };
         case 6: return { count: 336, bucketSecs: 3600 };
         case 7: return { count: 720, bucketSecs: 3600 };
+        case 8: return { count: 60, bucketSecs: 86_400 }; // D60 on the DAY ring
+        case 9: return { count: 90, bucketSecs: 86_400 }; // D90 on the DAY ring
         default: return { count: 24, bucketSecs: 3600 };
     }
 }
 
 /**
- * Encode the v2 series frame BYTE-FOR-BYTE like the edge `encode_series`:
- *   u16 version | u16 metricId | u32 bucketSecs | u64 headMs | u32 count | i64 × count
+ * Encode the v2 series frame BYTE-FOR-BYTE like the edge `encode_series` (points are u64 now):
+ *   u16 version | u16 metricId | u32 bucketSecs | u64 headMs | u32 count | u64 × count
  * A synthetic gentle ramp so a dev dashboard draws a non-flat line.
  */
 function encodeSeries(metricId: number, range: number): Buffer {
@@ -146,9 +180,9 @@ function encodeSeries(metricId: number, range: number): Buffer {
     head.writeUInt32LE(count, 16);
     const body = Buffer.alloc(count * 8);
     for (let i = 0; i < count; i++) {
-        // A smooth ramp with a little variation, deterministic per (metric, index).
+        // A smooth ramp with a little variation, deterministic per (metric, index). Non-negative -> u64.
         const v = BigInt(((i * 7 + metricId) % 50) + i);
-        body.writeBigInt64LE(v, i * 8);
+        body.writeBigUInt64LE(v, i * 8);
     }
     return Buffer.concat([head, body]);
 }
@@ -211,8 +245,9 @@ export function buildAnalyticsImports(
             range: number,
         ): number => {
             if (domainLen > MAX_DOMAIN_LEN) return ABSENT;
-            // Valid metric ids are 0..=46 (counters 0..=42 + the 4 gauge avg/peak series), ranges 0..=7.
-            if (metricId < 0 || metricId > 46 || range < 0 || range > 7) return ABSENT;
+            // Valid metric ids are 0..=45 (counters 0..=41 + the 4 gauge avg/peak series 42..=45), matching
+            // the edge `MetricId::from_u16` (v < N_METRICS=46); ranges 0..=9 (H1..D30 + D60/D90).
+            if (metricId < 0 || metricId > 45 || range < 0 || range > 9) return ABSENT;
             if (domainLen > 0) {
                 if (!ref.memory) throw new Error('analytics_series called before memory was bound');
                 const m = Buffer.from(ref.memory.buffer);

package/src/devserver/config/ratelimit.ts

@@ -36,6 +36,13 @@ interface RouteLimiter {
 /** `(routeId) -> limiter`, created lazily with the route's first-seen params. */
 const registry = new Map<number, RouteLimiter>();
 
+/** Drop all limiter state (tests). Each dev wasm dispatch shares this module-level
+ *  registry, so a test that fires many `@ratelimit`-decorated routes in one file
+ *  would otherwise carry counts across cases; reset between cases for isolation. */
+export function __resetRatelimitForTests(): void {
+    registry.clear();
+}
+
 export interface DevDecision {
     allowed: boolean;
     /** Whole seconds to wait before retrying (>= 1 when denied, 0 when allowed). */

package/src/devserver/email/index.ts

@@ -74,6 +74,50 @@ export class NodeEmailService {
     }
 }
 
+// --- Test-only capture seam ---------------------------------------------------
+
+/**
+ * A message the dev email pipeline decided to send (a real provider send, or the
+ * unconfigured stub), captured for TESTS ONLY. The built-in auth controller
+ * delivers its one-time confirm/reset tokens via email, so an e2e test reads the
+ * token straight out of the emitted link here. This is NOT a production path —
+ * the edge never imports this module, and real sends are unchanged.
+ */
+export interface SentEmail {
+    readonly to: string;
+    readonly subject: string;
+    /** Plain-text body (the confirm/reset link appears here and in `html`). */
+    readonly text: string;
+    readonly html: string;
+    /** Short non-PII tag the guest passed (e.g. `verify`, `reset`). */
+    readonly purpose: string;
+}
+
+/** Bounded ring of the most-recent dev sends (test seam). */
+export const __sentEmails: SentEmail[] = [];
+const SENT_EMAILS_MAX = 256;
+
+/**
+ * Record one dev send into {@link __sentEmails}. Called at the exact point the
+ * dev pipeline decides to send/stub, so it captures precisely the messages the
+ * guest emitted (and nothing it dropped/deduped).
+ */
+export function recordSentEmail(msg: ParsedEmail): void {
+    __sentEmails.push({
+        to: msg.to,
+        subject: msg.subject,
+        text: msg.body,
+        html: msg.html,
+        purpose: msg.purpose,
+    });
+    while (__sentEmails.length > SENT_EMAILS_MAX) __sentEmails.shift();
+}
+
+/** Clear the captured dev-send ring (tests call this between cases). */
+export function __clearSentEmails(): void {
+    __sentEmails.length = 0;
+}
+
 // --- Process-level singleton (one project per dev/self-host process) ----------
 
 let service: NodeEmailService | null = null;