toiljs 0.0.90 → 0.0.92

package/server/auth/AuthController.ts

@@ -70,6 +70,44 @@ const ST_OK: u8 = 0;
 const ST_TAKEN: u8 = 1; // username already registered
 const ST_EMAIL_TAKEN: u8 = 2; // email already in use (register)
 const ST_UNCONFIRMED: u8 = 2; // email not confirmed (login) — distinct endpoint, reuses the value
+// login/finish 2FA status: the credential verified but a SECOND factor is
+// required; no session is minted (see loginFinish). Distinct from ST_OK(0) /
+// ST_UNCONFIRMED(2) so the client can branch.
+const ST_TWOFA_REQUIRED: u8 = 3;
+
+// Two-factor METHOD enum (append-only; the value is stored in AuthAccount and in
+// every challenge, so NEVER renumber). 0 = 2FA off. Adding a method is one new
+// value here plus a deliver arm + a verify arm (see the `switch (method)` sites);
+// the challenge lifecycle and the login wiring do NOT change.
+const TWOFA_NONE: u8 = 0;
+const TWOFA_EMAIL: u8 = 1;
+// Future (reserved, not yet implemented): TWOFA_TOTP: u8 = 2; TWOFA_SMS: u8 = 3;
+
+// 2FA challenge tuning. The code is single-use, TTL'd, and attempt-limited (all
+// enforced against the stored challenge, independent of the per-IP @ratelimit).
+const TWOFA_TTL_SECS: u64 = 300; // a login/setup code is valid 5 minutes
+const TWOFA_MAX_ATTEMPTS: u32 = 5; // wrong-code guesses before the challenge dies
+const TWOFA_DIGITS: i32 = 6; // digits in an emailed numeric code
+
+// RACE-FREE per-challenge attempt cap. The `ch.attempts` counter below is a
+// non-atomic get+patch across two host calls, so on the edge (a fresh wasm
+// instance per request across 14 workers) N concurrent verifies for ONE
+// challenge can each read attempts=0 and all guess before any patch lands -- a
+// lost-update TOCTOU that lifts the intended 5-guess cap to the attacker's
+// in-flight concurrency. The per-IP @ratelimit does NOT backstop a many-IP
+// attacker. So we ALSO count each verify against a host-side EXACT limiter keyed
+// on the CHALLENGE itself (twoFaId / setup username), never the peer IP: the
+// count is atomic and shared across all workers, so total guesses per challenge
+// are hard-capped regardless of source IP or request concurrency. `ch.attempts`
+// stays as the primary (UX-friendly, burns-the-row) sequential path; this is the
+// concurrency backstop. The routeIds sit just under i32::MAX so they can never
+// collide with the `@ratelimit` decorator's monotonic-from-0 routeIds.
+const TWOFA_VERIFY_RL_ROUTE: i32 = 2147483001;
+const TWOFA_SETUP_RL_ROUTE: i32 = 2147483002;
+// The host strategy tag for SlidingWindow (matches `RateLimit.SlidingWindow` and
+// what the @ratelimit decorator lowers to). Used as a raw int because `RateLimit`
+// is a type-only ambient enum with no runtime backing in a handler body.
+const TWOFA_RL_STRATEGY: i32 = 1;
 
 // Resolved-and-cached per instance; the audience id (server config, never
 // client-echoed). Read lazily (not at module top level) so the env host import
@@ -99,6 +137,38 @@ function authDomain(ctx: RouteContext): string {
     return 'localhost';
 }
 
+/**
+ * The per-request TENANT REALM that EVERY AuthDb key and one-time code/token is
+ * scoped to: the routed, NORMALIZED Host (lowercased, port-stripped, IPv6-bracket
+ * aware). DERIVED IDENTICALLY to the session cookie's tenant tag
+ * (`server/globals/auth.ts` `__sessionTenantTag`) so the DB data and the session
+ * agree on "which domain" a request belongs to.
+ *
+ * This is the HARD cross-domain boundary. The realm is folded into every physical
+ * key (`Username`/`EmailKey`/`TwoFaId`/`ChallengeId`) and every one-time verifier
+ * (`tokenId`/`twoFaCodeHash`/`deriveSalt`), so a confirm/reset/2FA artifact minted
+ * under domain A addresses a DIFFERENT row AND hashes to a DIFFERENT verifier under
+ * domain B: a single toildb tenant that fronts multiple domains can NOT let an auth
+ * code from one be redeemed on another. Mint-realm and redeem-realm must match, and
+ * both are this normalized Host, so a code is bound to the domain it was issued on.
+ */
+function realm(ctx: RouteContext): string {
+    const raw = ctx.request.header('host');
+    if (raw == null) return '';
+    let h = raw.toLowerCase();
+    if (h.startsWith('[')) {
+        // IPv6 literal `[addr]`(:port): keep through the closing bracket, drop the
+        // port. Bracket-aware so `[::1]` is not sliced to `[:` (which would collapse
+        // distinct IPv6 tenants). Mirrors the edge strip_port + the session tag.
+        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
+    }
+    return h;
+}
+
 /**
  * Whether this domain requires a confirmed email before login. A plain
  * (tenant-readable) env var so an app can opt in itself; the edge ALSO force-sets
@@ -227,15 +297,22 @@ function ackOk(): Response {
  * unknown user yields the SAME stable salt as a known one would -- no
  * enumeration oracle.
  */
-function deriveSalt(username: string): Uint8Array {
-    return crypto.sha256Text('toil-auth-salt-v1:' + username).slice(0, 16);
+function deriveSalt(host: string, username: string): Uint8Array {
+    return crypto.sha256Text('toil-auth-salt-v1:' + host + '\x00' + username).slice(0, 16);
 }
 
-/** The one-time-token lookup key: SHA-256 of the raw token bytes. Storing only
- *  the hash means a leak of the token store yields nothing usable — the raw
- *  token lives only in the emailed link. */
-function tokenId(raw: Uint8Array): TokenId {
-    return new TokenId(crypto.sha256(raw));
+/** The one-time-token lookup key: SHA-256 of `host || 0x00 || rawToken`. Storing
+ *  only the hash means a leak of the token store yields nothing usable (the raw
+ *  token lives only in the emailed link); folding the tenant realm IN means the
+ *  same raw token addresses a DIFFERENT row per host, so a confirm/reset token
+ *  minted on domain A can never be redeemed on domain B (its `tokenId` under B's
+ *  realm is a different key that misses). */
+function tokenId(host: string, raw: Uint8Array): TokenId {
+    const prefix = Uint8Array.wrap(String.UTF8.encode(host + '\x00'));
+    const buf = new Uint8Array(prefix.length + raw.length);
+    buf.set(prefix, 0);
+    buf.set(raw, prefix.length);
+    return new TokenId(crypto.sha256(buf));
 }
 
 /** Mint a fresh 32-byte token; returns the raw bytes (for the link) — the store
@@ -244,18 +321,72 @@ function mintToken(): Uint8Array {
     return randomBytes(32);
 }
 
+/**
+ * A CSPRNG numeric code of `digits` decimal digits (leading zeros kept), using
+ * REJECTION SAMPLING so there is NO modulo bias: a byte in [250,256) is rejected
+ * (250 = the largest multiple of 10 that is <= 256), so every accepted byte maps
+ * uniformly onto 0-9. Each digit is drawn independently until accepted.
+ */
+function randomCode(digits: i32): string {
+    const buf = new Uint8Array(1);
+    let s = '';
+    for (let i = 0; i < digits; i++) {
+        let b: i32 = 255;
+        do {
+            crypto.getRandomValues(buf);
+            b = <i32>buf[0];
+        } while (b >= 250); // reject the biased tail
+        s += (b % 10).toString();
+    }
+    return s;
+}
+
+/** The stored 2FA verifier: SHA-256 of `host || 0x00 || username || 0x00 || code`.
+ *  The tenant realm AND the username are bound INTO the hash (null separators,
+ *  unambiguous), so a code is only ever valid for the account it was issued to AND
+ *  the domain it was issued on -- a code from domain A can never satisfy the same
+ *  user's challenge on domain B, even if the row were reachable. The plaintext code
+ *  is NEVER stored. */
+function twoFaCodeHash(host: string, username: string, code: string): Uint8Array {
+    return crypto.sha256Text(host + '\x00' + username + '\x00' + code);
+}
+
+/** Constant-time equality of two fixed 32-byte SHA-256 hashes (XOR-accumulate,
+ *  no early exit on the first differing byte). Mirrors the client `bytesEqual`. */
+function ctEqual(a: Uint8Array, b: Uint8Array): bool {
+    if (a.length != b.length) return false;
+    let diff: i32 = 0;
+    for (let i = 0; i < a.length; i++) diff |= (<i32>a[i]) ^ (<i32>b[i]);
+    return diff == 0;
+}
+
+/** Whether `m` is a 2FA method this build understands (TWOFA_NONE or a supported
+ *  method). ADD A METHOD: also accept its enum value here. */
+function isKnownTwoFaMethod(m: u8): bool {
+    return m == TWOFA_NONE || m == TWOFA_EMAIL;
+    // >>> e.g. `|| m == TWOFA_TOTP || m == TWOFA_SMS` <<<
+}
+
+// Every lookup KEY carries the tenant `host` (realm) as its FIRST field, so the
+// physical key includes the domain and the SAME logical name/email/id addresses a
+// DIFFERENT row per host (cross-domain isolation, on top of toildb's per-tenant
+// scoping). `host` is populated from `realm(ctx)` at every call site.
 @data
 class Username {
+    host: string = '';
     name: string = '';
-    constructor(name: string = '') {
+    constructor(host: string = '', name: string = '') {
+        this.host = host;
         this.name = name;
     }
 }
 
 @data
 class EmailKey {
+    host: string = '';
     email: string = '';
-    constructor(email: string = '') {
+    constructor(host: string = '', email: string = '') {
+        this.host = host;
         this.email = email;
     }
 }
@@ -286,8 +417,10 @@ class TokenRec {
 
 @data
 class ChallengeId {
+    host: string = '';
     cid: Uint8Array = new Uint8Array(0);
-    constructor(cid: Uint8Array = new Uint8Array(0)) {
+    constructor(host: string = '', cid: Uint8Array = new Uint8Array(0)) {
+        this.host = host;
         this.cid = cid;
     }
 }
@@ -306,6 +439,11 @@ class AuthAccount {
     parallelism: u32 = 0;
     email: string = '';
     emailConfirmed: bool = false;
+    // APPENDED (append-only, forward-compatible like `email` above): the account's
+    // second-factor method (see the TWOFA_* enum). An old row decodes as 0 =
+    // TWOFA_NONE (2FA off), the safe default, so existing accounts stay logged in
+    // by password alone until they opt in via /auth/2fa/setup.
+    twoFactorMethod: u8 = 0;
 }
 
 @data
@@ -317,6 +455,37 @@ class Challenge {
     exp: u64 = 0;
 }
 
+/** The lookup key for a login 2FA challenge: 16 random bytes minted per login.
+ *  Lives in its OWN collection (twoFaLogins), a SEPARATE NAMESPACE from
+ *  confirm/reset TokenId, so a confirm/reset token can never resolve here. */
+@data
+class TwoFaId {
+    host: string = '';
+    id: Uint8Array = new Uint8Array(0);
+    constructor(host: string = '', id: Uint8Array = new Uint8Array(0)) {
+        this.host = host;
+        this.id = id;
+    }
+}
+
+/**
+ * A pending second-factor challenge (login OR setup). METHOD-AGNOSTIC lifecycle
+ * fields (username / exp / attempts) plus the per-method `codeHash`; `method` is
+ * which factor was delivered and `targetMethod` is used ONLY by the setup flow
+ * (what to set `account.twoFactorMethod` to on success). Login challenges leave
+ * `targetMethod` at 0. `codeHash = SHA-256(username || 0x00 || code)`; the
+ * plaintext code is never stored.
+ */
+@data
+class TwoFaChallenge {
+    username: string = '';
+    method: u8 = 0;
+    codeHash: Uint8Array = new Uint8Array(0);
+    exp: u64 = 0;
+    attempts: u32 = 0;
+    targetMethod: u8 = 0;
+}
+
 @database
 class AuthDb {
     @collection static accounts: Documents<Username, AuthAccount>;
@@ -329,6 +498,14 @@ class AuthDb {
     // user per kind (O(users)), not one per request (unbounded storage-griefing).
     @collection static confirmTokenOf: Documents<Username, TokenId>;
     @collection static resetTokenOf: Documents<Username, TokenId>;
+    // SECOND-FACTOR challenges live in their OWN collections, a namespace fully
+    // disjoint from confirm/reset tokens (above). A reset/confirm token looked up
+    // here finds nothing (wrong collection); a 2FA code/id looked up in the token
+    // collections finds nothing. The separation is STRUCTURAL, not a purpose
+    // string. `twoFaLogins` is keyed by a random per-login id; `twoFaSetup` is
+    // keyed by username = one outstanding setup challenge per user.
+    @collection static twoFaLogins: Documents<TwoFaId, TwoFaChallenge>;
+    @collection static twoFaSetup: Documents<Username, TwoFaChallenge>;
 }
 
 @rest('auth')
@@ -347,12 +524,13 @@ class Auth {
         const evaluated = AuthService.oprfEvaluate(username, blinded);
         if (evaluated.length != AuthService.OPRF_ELEMENT_LEN) return fail();
 
+        const h = realm(ctx);
         const w = new DataWriter();
         w.writeU8(ST_OK);
         w.writeU32(MEM_KIB);
         w.writeU32(ITERS);
         w.writeU32(PAR);
-        w.writeBytes(deriveSalt(username));
+        w.writeBytes(deriveSalt(h, username));
         w.writeBytes(evaluated);
         return Response.bytes(w.toBytes());
     }
@@ -383,13 +561,17 @@ class Auth {
         const regMsg = AuthService.buildRegisterMessage(username, pk);
         if (!AuthService.verifyRegister(pk, regMsg, proof)) return fail();
 
+        // Every key below is scoped to this request's tenant realm: `bob` / an email
+        // on domain A is a DIFFERENT account + index entry from the same on domain B.
+        const h = realm(ctx);
+
         // Distinguishable statuses (not the generic 401) so the UI can say
         // "username taken" / "email in use". Signup intentionally leaks existence
         // (a product choice, now gated behind the PoP above); reset never does.
-        if (AuthDb.accounts.exists(new Username(username))) {
+        if (AuthDb.accounts.exists(new Username(h, username))) {
             return Response.bytes(new DataWriter().writeU8(ST_TAKEN).toBytes());
         }
-        if (AuthDb.emails.exists(new EmailKey(email))) {
+        if (AuthDb.emails.exists(new EmailKey(h, email))) {
             return Response.bytes(new DataWriter().writeU8(ST_EMAIL_TAKEN).toBytes());
         }
 
@@ -398,26 +580,26 @@ class Auth {
         a.username = username;
         a.email = email;
         a.emailConfirmed = !mustConfirm; // auto-confirm when confirmation is off
-        a.salt = deriveSalt(username);
+        a.salt = deriveSalt(h, username);
         a.publicKey = pk;
         a.memKiB = MEM_KIB;
         a.iterations = ITERS;
         a.parallelism = PAR;
         // create-if-absent: a racing duplicate registration loses here, not above.
-        if (!AuthDb.accounts.create(new Username(username), a)) {
+        if (!AuthDb.accounts.create(new Username(h, username), a)) {
             return Response.bytes(new DataWriter().writeU8(ST_TAKEN).toBytes());
         }
-        // Reserve the email -> username index (uniqueness for reset-by-email). A
-        // racing duplicate email loses here: roll back the account we just created
-        // so a lost email race can't orphan a username whose email index points at
-        // someone else (which would also break reset-by-email for it).
-        if (!AuthDb.emails.create(new EmailKey(email), new EmailOwner(username))) {
-            AuthDb.accounts.delete(new Username(username));
+        // Reserve the email -> username index (uniqueness for reset-by-email, scoped
+        // per host). A racing duplicate email loses here: roll back the account we
+        // just created so a lost email race can't orphan a username whose email index
+        // points at someone else (which would also break reset-by-email for it).
+        if (!AuthDb.emails.create(new EmailKey(h, email), new EmailOwner(username))) {
+            AuthDb.accounts.delete(new Username(h, username));
             return Response.bytes(new DataWriter().writeU8(ST_EMAIL_TAKEN).toBytes());
         }
 
         if (mustConfirm) {
-            this.issueConfirmation(ctx, username, email);
+            this.issueConfirmation(h, ctx, username, email);
         }
         return Response.bytes(new DataWriter().writeU8(ST_OK).toBytes());
     }
@@ -432,15 +614,17 @@ class Auth {
         const r = new DataReader(ctx.request.body);
         const raw = r.readBytes();
         if (!r.ok || raw.length == 0) return fail();
-        // Consume FIRST (a replayed/expired token still burns), then validate.
-        const rec = AuthDb.confirmTokens.getDelete(tokenId(raw));
+        const h = realm(ctx);
+        // Consume FIRST (a replayed/expired token still burns), then validate. The
+        // token id folds in `h`, so a confirm token minted on another domain misses.
+        const rec = AuthDb.confirmTokens.getDelete(tokenId(h, raw));
         if (rec == null) return fail();
         if (nowSecs() >= rec.exp) return fail();
-        const acct = AuthDb.accounts.get(new Username(rec.username));
+        const acct = AuthDb.accounts.get(new Username(h, rec.username));
         if (acct == null) return fail();
         if (!acct.emailConfirmed) {
             acct.emailConfirmed = true;
-            AuthDb.accounts.patch(new Username(rec.username), acct);
+            AuthDb.accounts.patch(new Username(h, rec.username), acct);
         }
         return Response.bytes(new DataWriter().writeU8(ST_OK).toBytes());
     }
@@ -454,11 +638,12 @@ class Auth {
         const r = new DataReader(ctx.request.body);
         const email = r.readString();
         if (!r.ok) return fail();
-        const owner = AuthDb.emails.get(new EmailKey(email));
+        const h = realm(ctx);
+        const owner = AuthDb.emails.get(new EmailKey(h, email));
         if (owner != null) {
-            const acct = AuthDb.accounts.get(new Username(owner.username));
+            const acct = AuthDb.accounts.get(new Username(h, owner.username));
             if (acct != null && !acct.emailConfirmed) {
-                this.issueConfirmation(ctx, owner.username, email);
+                this.issueConfirmation(h, ctx, owner.username, email);
             }
         }
         return ackOk();
@@ -480,14 +665,16 @@ class Auth {
         const evaluated = AuthService.oprfEvaluate(username, blinded);
         if (evaluated.length != AuthService.OPRF_ELEMENT_LEN) return fail();
 
-        const known = AuthDb.accounts.exists(new Username(username));
+        const h = realm(ctx);
+        const known = AuthDb.accounts.exists(new Username(h, username));
         const cid = randomBytes(16);
         const nonce = randomBytes(32);
         const iat = nowSecs();
         const exp = iat + CHALLENGE_TTL_SECS;
 
         // Persist only for a real account; the response is identical either way,
-        // and login/finish for an unknown user fails generically at consume.
+        // and login/finish for an unknown user fails generically at consume. The
+        // challenge key folds in `h`, so a challenge is bound to the login domain.
         if (known) {
             const c = new Challenge();
             c.cid = cid;
@@ -495,7 +682,7 @@ class Auth {
             c.nonce = nonce;
             c.iat = iat;
             c.exp = exp;
-            AuthDb.challenges.create(new ChallengeId(cid), c);
+            AuthDb.challenges.create(new ChallengeId(h, cid), c);
         }
 
         const w = new DataWriter();
@@ -504,7 +691,7 @@ class Auth {
         w.writeU32(MEM_KIB);
         w.writeU32(ITERS);
         w.writeU32(PAR);
-        w.writeBytes(deriveSalt(username));
+        w.writeBytes(deriveSalt(h, username));
         w.writeBytes(nonce);
         w.writeU64(iat);
         w.writeU64(exp);
@@ -523,15 +710,17 @@ class Auth {
         const ct = r.readBytes();
         const sig = r.readBytes();
         if (!r.ok) return fail();
+        const h = realm(ctx);
 
         // 1. CONSUME FIRST: atomic fetch-and-delete. Unknown/used/expired => fail.
-        const ch = AuthDb.challenges.getDelete(new ChallengeId(cid));
+        //    The challenge is realm-keyed, so one minted on another domain misses.
+        const ch = AuthDb.challenges.getDelete(new ChallengeId(h, cid));
         if (ch == null) return fail();
         if (nowSecs() >= ch.exp) return fail();
 
         // 2. Rebuild the message from OUR stored values + the client's ct (and
         //    the bound params + server key id), load the account key, verify.
-        const acct = AuthDb.accounts.get(new Username(ch.username));
+        const acct = AuthDb.accounts.get(new Username(h, ch.username));
         if (acct == null) return fail();
         const message = AuthService.buildLoginMessage(
             ch.username,
@@ -565,6 +754,41 @@ class Auth {
         const sessionKey = AuthService.deriveSessionKey(sharedSecret, transcriptHash);
         const confirm = AuthService.serverConfirmTag(sessionKey, transcriptHash);
 
+        // 3c. SECOND-FACTOR GATE. If this account has 2FA enabled, DO NOT mint a
+        //     session here. Mint a login 2FA challenge (method-agnostic lifecycle)
+        //     and deliver the code (per-method), then return ST_TWOFA_REQUIRED
+        //     WITH the serverConfirm tag (so the client still completes mutual auth
+        //     and knows the server is genuine BEFORE it prompts for a code) and NO
+        //     cookie. The challenge is stored in `twoFaLogins` (its own namespace,
+        //     never resetTokens/confirmTokens). This runs AFTER the signature
+        //     verify above, so it is not an oracle, and the login `Challenge` was
+        //     already consumed (getDelete) at the top of this handler.
+        if (acct.twoFactorMethod != TWOFA_NONE) {
+            const raw = randomBytes(16); // the twoFaId the client echoes to /2fa/verify
+            const codeHash = this.twoFaDeliver(
+                h,
+                acct.twoFactorMethod,
+                ch.username,
+                acct.email,
+                'Your login code',
+            );
+            if (codeHash.length == 0) return fail(); // unsupported/misconfigured method
+            const c2 = new TwoFaChallenge();
+            c2.username = ch.username;
+            c2.method = acct.twoFactorMethod;
+            c2.codeHash = codeHash;
+            c2.exp = nowSecs() + TWOFA_TTL_SECS;
+            c2.attempts = 0;
+            c2.targetMethod = TWOFA_NONE; // a LOGIN challenge changes no method on success
+            AuthDb.twoFaLogins.create(new TwoFaId(h, raw), c2);
+
+            const w2 = new DataWriter();
+            w2.writeU8(ST_TWOFA_REQUIRED);
+            w2.writeBytes(raw);
+            w2.writeBytes(confirm); // mutual-auth tag: the client verifies the server first
+            return Response.bytes(w2.toBytes()); // NO Set-Cookie: no session until 2FA verifies
+        }
+
         // 4. Success: mint the session for whatever `@user` this program has (built-in or the app's own
         //    extended one). `__toilEncodeAuthUser` is injected by `--authUser`: it constructs the `@user`
         //    (app fields at their defaults), sets the reserved identity, and encodes it. The stable
@@ -593,20 +817,21 @@ class Auth {
         const r = new DataReader(ctx.request.body);
         const email = r.readString();
         if (!r.ok) return fail();
-        const owner = AuthDb.emails.get(new EmailKey(email));
-        if (owner != null && AuthDb.accounts.exists(new Username(owner.username))) {
+        const h = realm(ctx);
+        const owner = AuthDb.emails.get(new EmailKey(h, email));
+        if (owner != null && AuthDb.accounts.exists(new Username(h, owner.username))) {
             // Invalidate this user's previous reset token (bound to one outstanding).
-            const prev = AuthDb.resetTokenOf.getDelete(new Username(owner.username));
+            const prev = AuthDb.resetTokenOf.getDelete(new Username(h, owner.username));
             if (prev != null) AuthDb.resetTokens.delete(prev);
             const raw = mintToken();
-            const tid = tokenId(raw);
+            const tid = tokenId(h, raw); // realm-bound: unredeemable on another domain
             const rec = new TokenRec();
             rec.username = owner.username;
             rec.exp = nowSecs() + RESET_TTL_SECS;
             AuthDb.resetTokens.create(tid, rec);
             // If a concurrent reset request won the pointer index, roll back the
             // token we just minted so exactly one stays outstanding (no orphan).
-            if (!AuthDb.resetTokenOf.create(new Username(owner.username), tid)) {
+            if (!AuthDb.resetTokenOf.create(new Username(h, owner.username), tid)) {
                 AuthDb.resetTokens.delete(tid);
             }
             // Token in the URL FRAGMENT, not the query string: a fragment is never
@@ -632,7 +857,8 @@ class Auth {
         const raw = r.readBytes();
         const blinded = r.readBytes();
         if (!r.ok || raw.length == 0) return fail();
-        const rec = AuthDb.resetTokens.get(tokenId(raw));
+        const h = realm(ctx);
+        const rec = AuthDb.resetTokens.get(tokenId(h, raw));
         if (rec == null) return fail();
         if (nowSecs() >= rec.exp) return fail();
         const evaluated = AuthService.oprfEvaluate(rec.username, blinded);
@@ -644,7 +870,7 @@ class Auth {
         w.writeU32(MEM_KIB);
         w.writeU32(ITERS);
         w.writeU32(PAR);
-        w.writeBytes(deriveSalt(rec.username));
+        w.writeBytes(deriveSalt(h, rec.username));
         w.writeBytes(evaluated);
         return Response.bytes(w.toBytes());
     }
@@ -663,11 +889,13 @@ class Auth {
         const proof = r.readBytes();
         if (!r.ok || raw.length == 0) return fail();
         if (pk.length != AuthService.PUBLIC_KEY_LEN) return fail();
-        // Consume FIRST (single use), then validate.
-        const rec = AuthDb.resetTokens.getDelete(tokenId(raw));
+        const h = realm(ctx);
+        // Consume FIRST (single use), then validate. Realm-bound token id: a reset
+        // token from another domain hashes to a different key and misses here.
+        const rec = AuthDb.resetTokens.getDelete(tokenId(h, raw));
         if (rec == null) return fail();
         if (nowSecs() >= rec.exp) return fail();
-        const acct = AuthDb.accounts.get(new Username(rec.username));
+        const acct = AuthDb.accounts.get(new Username(h, rec.username));
         if (acct == null) return fail();
 
         const regMsg = AuthService.buildRegisterMessage(rec.username, pk);
@@ -678,7 +906,7 @@ class Auth {
         // so confirm the account while we are here.
         acct.publicKey = pk;
         acct.emailConfirmed = true;
-        AuthDb.accounts.patch(new Username(rec.username), acct);
+        AuthDb.accounts.patch(new Username(h, rec.username), acct);
         return Response.bytes(new DataWriter().writeU8(ST_OK).toBytes());
     }
 
@@ -707,6 +935,256 @@ class Auth {
         return resp;
     }
 
+    /** POST /auth/2fa/verify  body: bytes(twoFaId) str(code)
+     *  resp: u8(status) [+ bytes(userData)] + Set-Cookie on success.
+     *  The SECOND factor of a 2FA login: consumes the login challenge minted by
+     *  login/finish and, on success, mints the session (the FIRST point a cookie
+     *  is set for a 2FA account). NOT @auth (there is no session yet). The
+     *  challenge is looked up in `twoFaLogins` ONLY, so a reset/confirm token can
+     *  never be presented here. Single-use, attempt-limited, TTL'd, rate-limited. */
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/2fa/verify')
+    public twoFaVerify(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const id = r.readBytes();
+        const code = r.readString();
+        if (!r.ok || id.length == 0) return fail();
+        const h = realm(ctx);
+
+        // RACE-FREE attempt cap: count this guess against a host-side EXACT
+        // limiter keyed on THIS challenge (the twoFaId), not the peer IP. Unlike
+        // the `ch.attempts` get+patch below, this is atomic across all workers,
+        // so a concurrent many-IP attacker cannot exceed TWOFA_MAX_ATTEMPTS
+        // guesses against one code. Denied -> 429 (Retry-After); the challenge is
+        // left for its TTL to reap. Key = realm + twoFaId hex (the edge limiter is
+        // already per-host; the prefix keeps dev parity + isolates per domain).
+        const rl = RateLimitService.guardKeyed(
+            TWOFA_VERIFY_RL_ROUTE,
+            TWOFA_RL_STRATEGY,
+            TWOFA_MAX_ATTEMPTS as i32,
+            TWOFA_TTL_SECS as i32,
+            h + '\x00' + crypto.toHex(id),
+        );
+        if (rl != null) return rl;
+
+        const key = new TwoFaId(h, id);
+        // PEEK (not consume): a wrong guess must NOT burn the challenge (a typo
+        // would otherwise lock the user out) until the attempt cap is reached.
+        const ch = AuthDb.twoFaLogins.get(key);
+        if (ch == null) return fail();
+        if (nowSecs() >= ch.exp || ch.attempts >= TWOFA_MAX_ATTEMPTS) {
+            AuthDb.twoFaLogins.delete(key); // burn an expired / exhausted challenge
+            return fail();
+        }
+        if (!this.twoFaVerifyCode(h, ch.username, code, ch)) {
+            // Wrong code: count the attempt; delete the challenge once the cap is
+            // hit so a burned-out challenge cannot be ground further.
+            ch.attempts = ch.attempts + 1;
+            if (ch.attempts >= TWOFA_MAX_ATTEMPTS) AuthDb.twoFaLogins.delete(key);
+            else AuthDb.twoFaLogins.patch(key, ch);
+            return fail();
+        }
+
+        // SUCCESS: consume-once, then mint the session EXACTLY like login/finish.
+        AuthDb.twoFaLogins.getDelete(key);
+        const acct = AuthDb.accounts.get(new Username(h, ch.username));
+        if (acct == null) return fail();
+        const domain = authDomain(ctx);
+        const toilUserId = ToilUserId.derive(acct.publicKey, ch.username, domain).toBytes();
+        const userData = __toilEncodeAuthUser(toilUserId, ch.username);
+        const w = new DataWriter();
+        w.writeU8(ST_OK);
+        w.writeBytes(userData);
+        const resp = Response.bytes(w.toBytes());
+        resp.setCookie(AuthService.mintSession(userData, SESSION_TTL_SECS));
+        resp.setCookie(AuthService.userCookie(userData, SESSION_TTL_SECS));
+        return resp;
+    }
+
+    /** POST /auth/2fa/setup  (@auth)  body: u8(targetMethod)  resp: u8(ST_OK)
+     *  Begin enabling or disabling 2FA for the SESSION user. Delivers a proof code
+     *  and stores a setup challenge in `twoFaSetup` (keyed by username = one
+     *  outstanding per user); /auth/2fa/setup/verify confirms it. ENABLE proves
+     *  control of the NEW method (deliver via targetMethod). DISABLE proves control
+     *  of the CURRENT method (deliver via account.twoFactorMethod) before the
+     *  factor is removed - anti-hijack. Always a generic ST_OK. */
+    @auth
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/2fa/setup')
+    public twoFaSetup(_ctx: RouteContext): Response {
+        const r = new DataReader(_ctx.request.body);
+        const targetMethod = r.readU8();
+        if (!r.ok) return fail();
+        if (!isKnownTwoFaMethod(targetMethod)) return fail();
+        const u = AuthService.getUser();
+        if (u == null) return fail();
+        const h = realm(_ctx);
+        const acct = AuthDb.accounts.get(new Username(h, u.username));
+        if (acct == null) return fail();
+
+        // Disabling when 2FA is already off: nothing to prove; generic ST_OK.
+        if (targetMethod == TWOFA_NONE && acct.twoFactorMethod == TWOFA_NONE) {
+            return Response.bytes(new DataWriter().writeU8(ST_OK).toBytes());
+        }
+
+        // Which method delivers the PROOF code:
+        //   ENABLE  (targetMethod != NONE): the NEW method (prove you control it).
+        //   DISABLE (targetMethod == NONE): the CURRENT method (prove you still
+        //     hold the existing factor before it is removed).
+        const deliverMethod: u8 = targetMethod != TWOFA_NONE ? targetMethod : acct.twoFactorMethod;
+        const codeHash = this.twoFaDeliver(
+            h,
+            deliverMethod,
+            u.username,
+            acct.email,
+            'Your verification code',
+        );
+        if (codeHash.length == 0) return fail(); // unsupported deliver method
+
+        const c = new TwoFaChallenge();
+        c.username = u.username;
+        c.method = deliverMethod;
+        c.codeHash = codeHash;
+        c.exp = nowSecs() + TWOFA_TTL_SECS;
+        c.attempts = 0;
+        c.targetMethod = targetMethod; // what to set account.twoFactorMethod to on success
+        // One outstanding setup challenge per user: overwrite any prior.
+        AuthDb.twoFaSetup.delete(new Username(h, u.username));
+        AuthDb.twoFaSetup.create(new Username(h, u.username), c);
+        return Response.bytes(new DataWriter().writeU8(ST_OK).toBytes());
+    }
+
+    /** POST /auth/2fa/setup/verify  (@auth)  body: str(code)  resp: u8(ST_OK)
+     *  Confirms a pending /auth/2fa/setup challenge for the SESSION user: on a
+     *  correct code, sets account.twoFactorMethod = challenge.targetMethod (enable
+     *  OR disable) and consumes the challenge. Same single-use + attempt-limit +
+     *  TTL as /auth/2fa/verify. */
+    @auth
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/2fa/setup/verify')
+    public twoFaSetupVerify(_ctx: RouteContext): Response {
+        const r = new DataReader(_ctx.request.body);
+        const code = r.readString();
+        if (!r.ok) return fail();
+        const u = AuthService.getUser();
+        if (u == null) return fail();
+        const h = realm(_ctx);
+
+        // RACE-FREE attempt cap for the setup challenge (same rationale as
+        // /2fa/verify): an atomic host-side limiter keyed on the session user, so
+        // the `ch.attempts` get+patch below cannot be out-raced by concurrent
+        // submissions. @auth-gated, so lower risk than login, but fixed alike.
+        const srl = RateLimitService.guardKeyed(
+            TWOFA_SETUP_RL_ROUTE,
+            TWOFA_RL_STRATEGY,
+            TWOFA_MAX_ATTEMPTS as i32,
+            TWOFA_TTL_SECS as i32,
+            h + '\x00' + u.username,
+        );
+        if (srl != null) return srl;
+
+        const key = new Username(h, u.username);
+        const ch = AuthDb.twoFaSetup.get(key);
+        if (ch == null) return fail();
+        if (nowSecs() >= ch.exp || ch.attempts >= TWOFA_MAX_ATTEMPTS) {
+            AuthDb.twoFaSetup.delete(key);
+            return fail();
+        }
+        if (!this.twoFaVerifyCode(h, ch.username, code, ch)) {
+            ch.attempts = ch.attempts + 1;
+            if (ch.attempts >= TWOFA_MAX_ATTEMPTS) AuthDb.twoFaSetup.delete(key);
+            else AuthDb.twoFaSetup.patch(key, ch);
+            return fail();
+        }
+
+        // SUCCESS: consume-once + apply the method change.
+        AuthDb.twoFaSetup.getDelete(key);
+        const acct = AuthDb.accounts.get(key);
+        if (acct == null) return fail();
+        acct.twoFactorMethod = ch.targetMethod;
+        AuthDb.accounts.patch(key, acct);
+        return Response.bytes(new DataWriter().writeU8(ST_OK).toBytes());
+    }
+
+    /** GET /auth/2fa/status  (@auth)  resp: u8(method)  (0 = off, 1 = email, ...)
+     *  The session user's current 2FA method, so the UI can show state. */
+    @auth
+    @get('/2fa/status')
+    public twoFaStatus(_ctx: RouteContext): Response {
+        const u = AuthService.getUser();
+        if (u == null) return fail();
+        const h = realm(_ctx);
+        const acct = AuthDb.accounts.get(new Username(h, u.username));
+        if (acct == null) return fail();
+        return Response.bytes(new DataWriter().writeU8(acct.twoFactorMethod).toBytes());
+    }
+
+    /**
+     * PER-METHOD 2FA DELIVERY. Generates and delivers a fresh code for `method`
+     * and returns the codeHash to persist for the later verify; returns an EMPTY
+     * array for an unsupported method (the caller fails closed). The plaintext
+     * code never leaves this method.
+     *
+     * >>> ADD A METHOD HERE: a new `case TWOFA_TOTP:` returns the codeHash/secret
+     *     binding WITHOUT emailing (the code is the authenticator's own output),
+     *     and pairs with a `case TWOFA_TOTP` in {@link twoFaVerifyCode}. The
+     *     lifecycle and the login/setup wiring do NOT change. <<<
+     */
+    private twoFaDeliver(
+        host: string,
+        method: u8,
+        username: string,
+        email: string,
+        subject: string,
+    ): Uint8Array {
+        switch (method) {
+            case TWOFA_EMAIL: {
+                const code = randomCode(TWOFA_DIGITS);
+                const text =
+                    'Your verification code is ' +
+                    code +
+                    '.\nIt expires in a few minutes. If you did not request it, ignore this email.\n';
+                const html =
+                    '<p>Your verification code is:</p>' +
+                    '<p style="font-size:28px;font-weight:bold;letter-spacing:4px">' +
+                    code +
+                    '</p>' +
+                    '<p>It expires in a few minutes. If you did not request it, ignore this email.</p>';
+                // DETACHED (non-suspending) send: constant-time, no provider-RTT
+                // parking (matches the confirm/reset anti-enumeration posture).
+                EmailService.sendDetached(email, subject, text, '2fa', html);
+                return twoFaCodeHash(host, username, code);
+            }
+            // >>> case TWOFA_TOTP: { return twoFaSecretBinding(username); } <<<
+            default:
+                return new Uint8Array(0);
+        }
+    }
+
+    /**
+     * PER-METHOD 2FA VERIFICATION: `true` iff `code` satisfies `challenge` for its
+     * method. The method-agnostic lifecycle (peek / attempt-limit / TTL / consume)
+     * lives in the endpoints; only the CODE CHECK is per-method here.
+     *
+     * >>> ADD A METHOD HERE: a new `case TWOFA_TOTP:` runs a TOTP check against the
+     *     stored secret binding. <<<
+     */
+    private twoFaVerifyCode(
+        host: string,
+        username: string,
+        code: string,
+        challenge: TwoFaChallenge,
+    ): bool {
+        switch (challenge.method) {
+            case TWOFA_EMAIL:
+                // Constant-time compare of the two 32-byte SHA-256 hashes.
+                return ctEqual(twoFaCodeHash(host, username, code), challenge.codeHash);
+            // >>> case TWOFA_TOTP: return totpVerify(challenge.codeHash, code); <<<
+            default:
+                return false;
+        }
+    }
+
     /** Mint a confirm token for `username`/`email` and email the confirm link.
      *  Best-effort: a failed send is not fatal (the user can resend).
      *
@@ -718,19 +1196,24 @@ class Auth {
      *  constant time, equalizing both paths. (Residual: on the exists path the
      *  token mint above still does a sub-ms ToilDB write the miss path skips; a
      *  fully constant-time guarantee would also equalize that DB work.) */
-    private issueConfirmation(ctx: RouteContext, username: string, email: string): void {
+    private issueConfirmation(
+        host: string,
+        ctx: RouteContext,
+        username: string,
+        email: string,
+    ): void {
         // Invalidate this user's previous confirm token (bound to one outstanding).
-        const prev = AuthDb.confirmTokenOf.getDelete(new Username(username));
+        const prev = AuthDb.confirmTokenOf.getDelete(new Username(host, username));
         if (prev != null) AuthDb.confirmTokens.delete(prev);
         const raw = mintToken();
-        const tid = tokenId(raw);
+        const tid = tokenId(host, raw); // realm-bound token id (see tokenId)
         const rec = new TokenRec();
         rec.username = username;
         rec.exp = nowSecs() + CONFIRM_TTL_SECS;
         AuthDb.confirmTokens.create(tid, rec);
         // If a concurrent request won the pointer index, roll back the token we
         // just minted so exactly one stays outstanding (no orphan).
-        if (!AuthDb.confirmTokenOf.create(new Username(username), tid)) {
+        if (!AuthDb.confirmTokenOf.create(new Username(host, username), tid)) {
             AuthDb.confirmTokens.delete(tid);
         }
         // Token in the URL FRAGMENT (see resetRequest): kept out of server/CDN