toiljs 0.0.90 → 0.0.92

package/src/client/auth.ts

@@ -39,6 +39,13 @@ function fromHex(hex: string): Uint8Array {
     return out;
 }
 
+/** bytes -> lowercase-hex. */
+function toHex(bytes: Uint8Array): string {
+    let s = '';
+    for (let i = 0; i < bytes.length; i++) s += bytes[i].toString(16).padStart(2, '0');
+    return s;
+}
+
 /**
  * The server's PINNED static ML-KEM-768 public key. The client encapsulates to
  * it; only the genuine server (holder of the matching secret key) can
@@ -353,17 +360,23 @@ export async function login(
         wipe(sharedSecret);
         throw new EmailNotConfirmedError();
     }
-    if (loginStatus !== 0) {
+    // status 3 = 2FA required: the credential verified but the account has a second
+    // factor. The server ALSO returns its serverConfirm tag (so we still complete
+    // mutual auth below) but mints NO session/cookie. Both the success (0) and the
+    // 2FA (3) responses are `bytes(first) bytes(serverConfirm)` -- `first` is the
+    // session token on 0 and the twoFaId on 3.
+    if (loginStatus !== 0 && loginStatus !== 3) {
         wipe(sharedSecret);
         throw new Error('auth: login failed');
     }
-    const session = res.readBytes();
+    const first = res.readBytes();
     const serverConfirm = res.readBytes();
 
     // 5. Mutual auth: derive the session key K = HMAC(sharedSecret, label || H(M)),
     //    then check the server's tag = HMAC(K, label || H(M)). Only a server that
     //    decapsulated correctly derives the same K, so a valid tag proves its
-    //    identity. Verify before returning the session.
+    //    identity. Runs for BOTH statuses, so a 2FA prompt only ever appears AFTER
+    //    the server has authenticated itself.
     const transcriptHash = await sha256Bytes(message);
     const sessionKey = await hmacSha256(
         sharedSecret,
@@ -376,7 +389,14 @@ export async function login(
     );
     if (!bytesEqual(expected, serverConfirm)) throw new Error('auth: server authentication failed');
 
-    return session; // session token
+    if (loginStatus === 3) {
+        // The server authenticated itself, but a second factor is required. Surface
+        // the twoFaId (hex) so the caller can collect a code and call
+        // verifyTwoFactor. NO session exists yet.
+        throw new TwoFactorRequiredError(toHex(first));
+    }
+
+    return first; // session token
 }
 
 /** Thrown by {@link login} when the credential is valid but the account's email
@@ -389,6 +409,91 @@ export class EmailNotConfirmedError extends Error {
     }
 }
 
+/** Thrown by {@link login} when the password verified AND the server authenticated
+ *  itself (mutual auth passed) but the account requires a SECOND FACTOR. No session
+ *  exists yet. Catch it, collect the delivered code, and call
+ *  {@link verifyTwoFactor} with `err.twoFaId`. */
+export class TwoFactorRequiredError extends Error {
+    /** The opaque login-challenge id (hex) to echo to {@link verifyTwoFactor}. */
+    readonly twoFaId: string;
+    constructor(twoFaId: string) {
+        super('auth: two-factor authentication required');
+        this.name = 'TwoFactorRequiredError';
+        this.twoFaId = twoFaId;
+    }
+}
+
+/** The 2FA method values, mirroring the server enum (append-only). */
+export const TwoFactorMethod = { None: 0, Email: 1 } as const;
+
+/**
+ * Complete a 2FA login: submit the delivered `code` for the challenge `twoFaId`
+ * (from {@link TwoFactorRequiredError}). On success the server mints the session
+ * (sets the cookies) and returns the opaque session token. Throws one generic
+ * error ("code invalid or expired") on any failure -- the code is single-use and
+ * attempt-limited server-side.
+ */
+export async function verifyTwoFactor(
+    twoFaId: string,
+    code: string,
+    opts: AuthOptions = {},
+): Promise<Uint8Array> {
+    const baseUrl = opts.baseUrl ?? '/auth';
+    const res = await postBinary(
+        baseUrl,
+        '/2fa/verify',
+        new DataWriter().writeBytes(fromHex(twoFaId)).writeString(code).toBytes(),
+    );
+    if (res.readU8() !== 0) throw new Error('auth: two-factor code invalid or expired');
+    return res.readBytes(); // opaque session token
+}
+
+/**
+ * Begin enabling or disabling 2FA for the CURRENT session user. Pass a
+ * {@link TwoFactorMethod} value (`Email` to enable email 2FA, `None` to disable).
+ * The server delivers a proof code (to the new method when enabling, or the
+ * CURRENT method when disabling - anti-hijack); confirm it with
+ * {@link confirmTwoFactorSetup}. Requires a valid session.
+ */
+export async function setupTwoFactor(method: number, opts: AuthOptions = {}): Promise<void> {
+    const baseUrl = opts.baseUrl ?? '/auth';
+    const res = await postBinary(
+        baseUrl,
+        '/2fa/setup',
+        new DataWriter().writeU8(method).toBytes(),
+    );
+    if (res.readU8() !== 0) throw new Error('auth: two-factor setup failed');
+}
+
+/**
+ * Confirm a pending {@link setupTwoFactor} by submitting the delivered `code`.
+ * On success the account's 2FA method is switched (enabled or disabled). Requires
+ * a valid session. Throws (generic) if the code is wrong or expired.
+ */
+export async function confirmTwoFactorSetup(code: string, opts: AuthOptions = {}): Promise<void> {
+    const baseUrl = opts.baseUrl ?? '/auth';
+    const res = await postBinary(
+        baseUrl,
+        '/2fa/setup/verify',
+        new DataWriter().writeString(code).toBytes(),
+    );
+    if (res.readU8() !== 0) throw new Error('auth: two-factor setup confirmation failed');
+}
+
+/**
+ * The current session user's 2FA method (a {@link TwoFactorMethod} value; `0` =
+ * off). Requires a valid session. For the UI to reflect enabled/disabled state.
+ */
+export async function twoFactorStatus(opts: AuthOptions = {}): Promise<number> {
+    const baseUrl = opts.baseUrl ?? '/auth';
+    const res = await fetch(baseUrl + '/2fa/status', {
+        method: 'GET',
+        credentials: 'same-origin',
+    });
+    if (!res.ok) throw new Error('auth: request failed');
+    return new DataReader(new Uint8Array(await res.arrayBuffer())).readU8();
+}
+
 /** 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> {
@@ -489,6 +594,11 @@ export const Auth = {
     resendConfirmation,
     requestPasswordReset,
     resetPassword,
+    verifyTwoFactor,
+    setupTwoFactor,
+    confirmTwoFactorSetup,
+    twoFactorStatus,
+    TwoFactorMethod,
     buildLoginMessage,
     LOGIN_CONTEXT,
 } as const;

package/test/pqauth-email.test.ts

@@ -24,7 +24,7 @@ import { __resetDbForTests } from '../src/devserver/db/index.js';
 import { __resetRatelimitForTests } from '../src/devserver/config/ratelimit.js';
 import { clearEnvCache } from '../src/devserver/config/dotenv.js';
 import { __sentEmails, __clearSentEmails } from '../src/devserver/email/index.js';
-import { Auth, EmailNotConfirmedError } from '../src/client/auth.js';
+import { Auth, EmailNotConfirmedError, TwoFactorRequiredError } from '../src/client/auth.js';
 import { DataReader, DataWriter } from '../src/io/codec.js';
 
 const EXAMPLE_WASM = path.resolve(
@@ -40,17 +40,20 @@ function loadModule(): WasmServerModule {
     return m;
 }
 
-/** Route the client's `fetch(path, {body})` into the dev wasm dispatcher (with a cookie jar). */
+/** Route the client's `fetch(path, {body})` into the dev wasm dispatcher (with a cookie jar).
+ *  The Host header the client's requests carry is settable (`setHost`) so a test can drive
+ *  the same client against DIFFERENT tenant domains and prove per-host auth isolation. */
 function installFetchShim(m: WasmServerModule): () => void {
     const original = globalThis.fetch;
     const jar = new Map<string, string>();
+    let host = 'localhost:3000';
     globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
         const url = typeof input === 'string' ? input : input.toString();
         const pathname = new URL(url, 'http://localhost').pathname;
         const bodyBytes =
             init?.body == null ? new Uint8Array(0) : new Uint8Array(init.body as ArrayBuffer);
         const headers: [string, string][] = [
-            ['host', 'localhost:3000'],
+            ['host', host],
             ['content-type', 'application/octet-stream'],
         ];
         if (jar.size > 0)
@@ -80,6 +83,9 @@ function installFetchShim(m: WasmServerModule): () => void {
             globalThis.fetch = original;
         },
         jar,
+        setHost: (h: string) => {
+            host = h;
+        },
     };
 }
 
@@ -117,10 +123,26 @@ function tokenFromEmail(kind: 'confirm' | 'reset', to: string): string {
     );
 }
 
+/** Pull the 6-digit code out of the most-recent captured 2FA email (purpose `2fa`) to `to`. */
+function codeFromEmail(to: string): string {
+    for (let i = __sentEmails.length - 1; i >= 0; i--) {
+        const msg = __sentEmails[i];
+        if (msg.to !== to || msg.purpose !== '2fa') continue;
+        const hit = /\b(\d{6})\b/.exec(msg.text) ?? /\b(\d{6})\b/.exec(msg.html);
+        if (hit) return hit[1];
+    }
+    throw new Error(
+        `no 2fa code emailed to ${to}; captured=${JSON.stringify(
+            __sentEmails.map((e) => ({ to: e.to, purpose: e.purpose })),
+        )}`,
+    );
+}
+
 describe.skipIf(!haveWasm)('built-in auth: email verification + password reset (client <-> example wasm)', () => {
     let restoreFetch: () => void;
     let mod: WasmServerModule;
     let jar: Map<string, string>;
+    let setHost: (h: string) => void;
 
     beforeEach(() => {
         __resetDbForTests();
@@ -133,6 +155,7 @@ describe.skipIf(!haveWasm)('built-in auth: email verification + password reset (
         const shim = installFetchShim(mod);
         restoreFetch = shim.restore;
         jar = shim.jar;
+        setHost = shim.setHost;
     });
     afterEach(() => {
         restoreFetch();
@@ -164,10 +187,13 @@ describe.skipIf(!haveWasm)('built-in auth: email verification + password reset (
     it(
         'reset link is NOT poisonable via a crafted Host header (#6 host-header reset-poisoning)',
         async () => {
+            // grace lives on the victim tenant (realm = normalized Host "victim.com").
+            setHost('victim.com');
             await Auth.register('grace', 'pw-grace-correct', 'grace@x.com');
             __clearSentEmails();
             // Attacker triggers reset/request with a Host that routes to the victim
-            // (the edge strip_port -> "victim.com") but, dropped raw into a link,
+            // (the edge strip_port -> "victim.com", which is grace's realm, so the
+            // request DOES resolve her account) but, dropped raw into a link,
             // reparents the URL authority to attacker.com.
             const body = new DataWriter().writeString('grace@x.com').toBytes();
             const r = mod.dispatch({
@@ -330,4 +356,364 @@ describe.skipIf(!haveWasm)('built-in auth: email verification + password reset (
         },
         60_000,
     );
+
+    // ---- multi-method 2FA (email) ----
+
+    it(
+        '(a) full email-2FA login round-trip: enable, login requires a code, verify mints the session',
+        async () => {
+            await Auth.register('dave', 'dave-pw-strong', 'dave@x.com');
+            await Auth.login('dave', 'dave-pw-strong'); // 2FA off -> session
+
+            // Enable email 2FA: setup delivers a code, confirm switches the method on.
+            await Auth.setupTwoFactor(Auth.TwoFactorMethod.Email);
+            await Auth.confirmTwoFactorSetup(codeFromEmail('dave@x.com'));
+            expect(await Auth.twoFactorStatus()).toBe(Auth.TwoFactorMethod.Email);
+
+            __clearSentEmails();
+            jar.clear(); // drop the existing session so login is a clean 2FA challenge
+
+            // Login now demands a second factor: mutual auth still passes (login()
+            // verifies serverConfirm before throwing), but NO session is minted.
+            let err: unknown;
+            try {
+                await Auth.login('dave', 'dave-pw-strong');
+            } catch (e) {
+                err = e;
+            }
+            expect(err).toBeInstanceOf(TwoFactorRequiredError);
+            const twoFaId = (err as TwoFactorRequiredError).twoFaId;
+            expect(twoFaId.length).toBeGreaterThan(0);
+            expect(jar.get('toil_sess')).toBeUndefined(); // no session at login/finish
+
+            // Read the login code out of the captured email and verify -> session.
+            const session = await Auth.verifyTwoFactor(twoFaId, codeFromEmail('dave@x.com'));
+            expect(session.length).toBeGreaterThan(0);
+
+            // /auth/me now returns the user.
+            const meRes = await fetch('/auth/me');
+            expect(meRes.status).toBe(200);
+            const me = new DataReader(new Uint8Array(await meRes.arrayBuffer()));
+            expect(me.readBytes().length).toBeGreaterThan(0); // toilUserId
+            expect(me.readString()).toBe('dave');
+        },
+        90_000,
+    );
+
+    it(
+        '(b) 2FA code security: wrong code rejected + attempt-limited to death, correct code single-use',
+        async () => {
+            await Auth.register('eve', 'eve-pw-strong', 'eve@x.com');
+            await Auth.login('eve', 'eve-pw-strong');
+            await Auth.setupTwoFactor(Auth.TwoFactorMethod.Email);
+            await Auth.confirmTwoFactorSetup(codeFromEmail('eve@x.com'));
+
+            // ---- wrong code is rejected, and after TWOFA_MAX_ATTEMPTS the challenge dies ----
+            __clearSentEmails();
+            jar.clear();
+            let err: unknown;
+            try {
+                await Auth.login('eve', 'eve-pw-strong');
+            } catch (e) {
+                err = e;
+            }
+            const twoFaId = (err as TwoFactorRequiredError).twoFaId;
+            const code = codeFromEmail('eve@x.com');
+            const wrong = code === '000000' ? '111111' : '000000';
+
+            // 5 (TWOFA_MAX_ATTEMPTS) wrong guesses. Reset the per-IP limiter between
+            // each so this exercises the CHALLENGE's own attempt cap, not @ratelimit.
+            for (let i = 0; i < 5; i++) {
+                __resetRatelimitForTests();
+                await expect(Auth.verifyTwoFactor(twoFaId, wrong)).rejects.toThrow();
+            }
+            // The challenge is now destroyed: even the CORRECT code fails.
+            __resetRatelimitForTests();
+            await expect(Auth.verifyTwoFactor(twoFaId, code)).rejects.toThrow();
+
+            // ---- a correct code is single-use: replay fails ----
+            __clearSentEmails();
+            jar.clear();
+            __resetRatelimitForTests();
+            let err2: unknown;
+            try {
+                await Auth.login('eve', 'eve-pw-strong');
+            } catch (e) {
+                err2 = e;
+            }
+            const twoFaId2 = (err2 as TwoFactorRequiredError).twoFaId;
+            const code2 = codeFromEmail('eve@x.com');
+            const session = await Auth.verifyTwoFactor(twoFaId2, code2); // consumes
+            expect(session.length).toBeGreaterThan(0);
+            __resetRatelimitForTests();
+            await expect(Auth.verifyTwoFactor(twoFaId2, code2)).rejects.toThrow(); // replay dead
+        },
+        120_000,
+    );
+
+    it(
+        '(c) cross-flow: reset tokens and 2FA codes are NOT interchangeable (namespace separation)',
+        async () => {
+            await Auth.register('frank', 'frank-pw-strong', 'frank@x.com');
+
+            // ---- direction 1: a LIVE reset token is useless at /auth/2fa/verify ----
+            await Auth.requestPasswordReset('frank@x.com');
+            const resetToken = tokenFromEmail('reset', 'frank@x.com'); // live resetTokens entry
+            __resetRatelimitForTests();
+            // Present the reset token as BOTH the twoFaId AND the code: /2fa/verify
+            // looks in `twoFaLogins` (a different collection) -> nothing -> rejected.
+            await expect(Auth.verifyTwoFactor(resetToken, resetToken)).rejects.toThrow();
+
+            // ---- direction 2: a LIVE 2FA login challenge id is useless at /auth/reset/finish ----
+            await Auth.login('frank', 'frank-pw-strong'); // session (2FA still off here)
+            __clearSentEmails();
+            await Auth.setupTwoFactor(Auth.TwoFactorMethod.Email);
+            await Auth.confirmTwoFactorSetup(codeFromEmail('frank@x.com'));
+            __clearSentEmails();
+            jar.clear();
+            __resetRatelimitForTests();
+            let err: unknown;
+            try {
+                await Auth.login('frank', 'frank-pw-strong');
+            } catch (e) {
+                err = e;
+            }
+            const twoFaId = (err as TwoFactorRequiredError).twoFaId; // live twoFaLogins key
+            const loginCode = codeFromEmail('frank@x.com');
+
+            // Submit the live 2FA challenge id AND the live 2FA code to
+            // /auth/reset/finish as the reset token: reset/finish looks in
+            // `resetTokens` -> nothing -> non-200. A live 2FA challenge is NOT a
+            // reset token.
+            const probes: Uint8Array[] = [hexToBytes(twoFaId), new TextEncoder().encode(loginCode)];
+            for (const raw of probes) {
+                __resetRatelimitForTests();
+                const body = new DataWriter()
+                    .writeBytes(raw)
+                    .writeBytes(new Uint8Array(1312)) // valid-length pk (reach the consume step)
+                    .writeBytes(new Uint8Array(2420)) // valid-length proof
+                    .toBytes();
+                const r = mod.dispatch({
+                    method: 'POST',
+                    path: '/auth/reset/finish',
+                    headers: [
+                        ['host', 'localhost:3000'],
+                        ['content-type', 'application/octet-stream'],
+                    ],
+                    body,
+                });
+                expect(r.status).not.toBe(200);
+            }
+
+            // The cross-flow probes touched NOTHING: the real 2FA login still
+            // completes with its real (twoFaId, code).
+            __resetRatelimitForTests();
+            const session = await Auth.verifyTwoFactor(twoFaId, loginCode);
+            expect(session.length).toBeGreaterThan(0);
+        },
+        120_000,
+    );
+
+    it(
+        '(d) NO session cookie is set on the ST_TWOFA_REQUIRED login response',
+        async () => {
+            await Auth.register('gwen', 'gwen-pw-strong', 'gwen@x.com');
+            await Auth.login('gwen', 'gwen-pw-strong');
+            await Auth.setupTwoFactor(Auth.TwoFactorMethod.Email);
+            await Auth.confirmTwoFactorSetup(codeFromEmail('gwen@x.com'));
+
+            jar.clear(); // drop every cookie
+            __clearSentEmails();
+            __resetRatelimitForTests();
+
+            let err: unknown;
+            try {
+                await Auth.login('gwen', 'gwen-pw-strong');
+            } catch (e) {
+                err = e;
+            }
+            expect(err).toBeInstanceOf(TwoFactorRequiredError);
+            // The shim folds any Set-Cookie into the jar; login/finish set NONE.
+            expect(jar.get('toil_sess')).toBeUndefined();
+            expect(jar.get('toil_user')).toBeUndefined();
+            // With no session cookie, the @auth-gated /auth/me is 401.
+            const meRes = await fetch('/auth/me');
+            expect(meRes.status).toBe(401);
+        },
+        60_000,
+    );
+
+    it(
+        '(e) login<->setup 2FA challenges are separate: a setup code cannot mint a login session, and setup/verify never silently disables 2FA',
+        async () => {
+            await Auth.register('ivy', 'ivy-pw-strong', 'ivy@x.com');
+            await Auth.login('ivy', 'ivy-pw-strong'); // session; 2FA still off
+
+            // Begin a 2FA SETUP: writes a challenge into `twoFaSetup` (keyed by
+            // username), NOT a login challenge into `twoFaLogins`.
+            __clearSentEmails();
+            __resetRatelimitForTests();
+            await Auth.setupTwoFactor(Auth.TwoFactorMethod.Email);
+            const setupCode = codeFromEmail('ivy@x.com');
+
+            // Present the LIVE setup code at /auth/2fa/verify with a fabricated
+            // twoFaId: /2fa/verify consults ONLY `twoFaLogins`, so the id misses and
+            // a setup code can never mint a login session.
+            __resetRatelimitForTests();
+            const fakeId = 'ab'.repeat(16); // 16-byte hex, not a real twoFaLogins key
+            await expect(Auth.verifyTwoFactor(fakeId, setupCode)).rejects.toThrow();
+
+            // The probe consumed NOTHING: the real setup still completes with the code.
+            __resetRatelimitForTests();
+            await Auth.confirmTwoFactorSetup(setupCode);
+            expect(await Auth.twoFactorStatus()).toBe(Auth.TwoFactorMethod.Email);
+
+            // With 2FA now ON but NO pending setup challenge, /auth/2fa/setup/verify is
+            // a no-op: a stray code cannot flip (disable) the method. A login challenge
+            // (targetMethod=NONE) has no wire path here and can never be routed in to
+            // silently disable 2FA.
+            __resetRatelimitForTests();
+            await expect(Auth.confirmTwoFactorSetup('000000')).rejects.toThrow();
+            expect(await Auth.twoFactorStatus()).toBe(Auth.TwoFactorMethod.Email);
+        },
+        120_000,
+    );
+
+    it(
+        '(f) cross-flow: confirm tokens and 2FA codes are NOT interchangeable (namespace separation)',
+        async () => {
+            setConfirmation(true);
+            await Auth.register('jade', 'jade-pw-strong', 'jade@x.com'); // unconfirmed -> confirm token emailed
+            const confirmToken = tokenFromEmail('confirm', 'jade@x.com'); // live confirmTokens entry
+
+            // ---- direction 1: a LIVE confirm token is useless at /auth/2fa/verify ----
+            __resetRatelimitForTests();
+            // Present the confirm token as BOTH the twoFaId AND the code: /2fa/verify
+            // reads `twoFaLogins` (a different collection) -> nothing -> rejected.
+            await expect(Auth.verifyTwoFactor(confirmToken, confirmToken)).rejects.toThrow();
+
+            // The probe consumed NOTHING: the confirm token still confirms the account,
+            // and login then succeeds (email now confirmed).
+            __resetRatelimitForTests();
+            await Auth.confirmEmail(confirmToken);
+            __resetRatelimitForTests();
+            expect((await Auth.login('jade', 'jade-pw-strong')).length).toBeGreaterThan(0);
+
+            // ---- direction 2: a LIVE 2FA login id/code is useless at /auth/confirm ----
+            // Enable 2FA (jade is confirmed + has a session from the login above).
+            __clearSentEmails();
+            __resetRatelimitForTests();
+            await Auth.setupTwoFactor(Auth.TwoFactorMethod.Email);
+            await Auth.confirmTwoFactorSetup(codeFromEmail('jade@x.com'));
+
+            // Fresh login -> a live `twoFaLogins` challenge (id + emailed code).
+            __clearSentEmails();
+            jar.clear();
+            __resetRatelimitForTests();
+            let err: unknown;
+            try {
+                await Auth.login('jade', 'jade-pw-strong');
+            } catch (e) {
+                err = e;
+            }
+            const twoFaId = (err as TwoFactorRequiredError).twoFaId;
+            const loginCode = codeFromEmail('jade@x.com');
+
+            // Submit the live 2FA id AND the live code to /auth/confirm as the confirm
+            // token: /auth/confirm consumes from `confirmTokens` (sha256(raw)) -> nothing
+            // -> non-200. A 2FA credential is NOT a confirm token.
+            const probes: Uint8Array[] = [hexToBytes(twoFaId), new TextEncoder().encode(loginCode)];
+            for (const raw of probes) {
+                __resetRatelimitForTests();
+                const body = new DataWriter().writeBytes(raw).toBytes();
+                const r = mod.dispatch({
+                    method: 'POST',
+                    path: '/auth/confirm',
+                    headers: [
+                        ['host', 'localhost:3000'],
+                        ['content-type', 'application/octet-stream'],
+                    ],
+                    body,
+                });
+                expect(r.status).not.toBe(200);
+            }
+
+            // The probes touched NOTHING: the real 2FA login still completes.
+            __resetRatelimitForTests();
+            const session = await Auth.verifyTwoFactor(twoFaId, loginCode);
+            expect(session.length).toBeGreaterThan(0);
+        },
+        120_000,
+    );
+
+    it(
+        '(g) per-domain isolation: a confirm/reset/2FA code minted on domain A is USELESS on domain B',
+        async () => {
+            const A = 'a.example.com';
+            const B = 'b.example.com';
+
+            // ---- confirm token: minted on A, unredeemable on B ----
+            setConfirmation(true);
+            setHost(A);
+            await Auth.register('mia', 'mia-pw-strong', 'mia@x.com'); // realm A + confirm token emailed
+            const confirmTok = tokenFromEmail('confirm', 'mia@x.com');
+
+            setHost(B);
+            __resetRatelimitForTests();
+            // Same raw token, different realm -> tokenId(B, raw) is a different key -> miss.
+            await expect(Auth.confirmEmail(confirmTok)).rejects.toThrow();
+
+            setHost(A);
+            __resetRatelimitForTests();
+            await Auth.confirmEmail(confirmTok); // realm A -> confirms
+            setConfirmation(false);
+
+            // ---- reset token: minted on A, unredeemable on B ----
+            setHost(A);
+            __clearSentEmails();
+            __resetRatelimitForTests();
+            await Auth.requestPasswordReset('mia@x.com');
+            const resetTok = tokenFromEmail('reset', 'mia@x.com');
+
+            setHost(B);
+            __resetRatelimitForTests();
+            await expect(Auth.resetPassword(resetTok, 'mia-pw-new')).rejects.toThrow(); // realm B miss
+
+            setHost(A);
+            __resetRatelimitForTests();
+            await Auth.resetPassword(resetTok, 'mia-pw-new'); // realm A -> resets
+
+            // ---- 2FA login code: minted on A, unusable on B ----
+            setHost(A);
+            __resetRatelimitForTests();
+            await Auth.login('mia', 'mia-pw-new'); // session on A (2FA still off)
+            __clearSentEmails();
+            await Auth.setupTwoFactor(Auth.TwoFactorMethod.Email);
+            await Auth.confirmTwoFactorSetup(codeFromEmail('mia@x.com')); // 2FA enabled on A
+
+            __clearSentEmails();
+            jar.clear();
+            __resetRatelimitForTests();
+            let err: unknown;
+            try {
+                await Auth.login('mia', 'mia-pw-new'); // -> 2FA challenge (twoFaId + code, realm A)
+            } catch (e) {
+                err = e;
+            }
+            const twoFaId = (err as TwoFactorRequiredError).twoFaId;
+            const loginCode = codeFromEmail('mia@x.com');
+
+            setHost(B);
+            __resetRatelimitForTests();
+            // The twoFaId lives in twoFaLogins under realm A; on B its key (and the
+            // realm-bound codeHash) miss -> a code from A cannot mint a session on B.
+            await expect(Auth.verifyTwoFactor(twoFaId, loginCode)).rejects.toThrow();
+
+            setHost(A);
+            __resetRatelimitForTests();
+            const session = await Auth.verifyTwoFactor(twoFaId, loginCode); // realm A -> mints
+            expect(session.length).toBeGreaterThan(0);
+        },
+        180_000,
+    );
 });