toiljs 0.0.105 → 0.0.107

package/docs/llms.txt

@@ -61,6 +61,7 @@ This is the canonical documentation, organized by section. Each link points to a
 - [Authentication](auth/README.md): Toil ships a complete, **post-quantum password login** you turn on with one line.
 - [Configuring auth for production](auth/configuration.md): Built-in auth runs locally with **zero configuration**, it falls back to published, insecure DEV secrets so `toiljs dev` Just Works.
 - [Extending & integrating auth](auth/extending.md): Built-in auth is deliberately opinionated so the common case is one line.
+- [Customizing the auth emails](auth/emails.md): Override the built-in verification, password-reset, and 2FA emails with your own branded React templates by adding reserved emails/auth-*.tsx files (tokens: {link} for confirm/reset, {code} for 2FA); sends stay detached (constant-time).
 - [How Toil auth works](auth/how-it-works.md): Toil auth is a **post-quantum, password-based, mutually-authenticated** login.
 - [Using auth](auth/usage.md): Either the config flag (canonical) or a one-line import, both do the same thing (the build appends the framework's auth controller + user shape to your server as compiled entries, so `/auth/*` self-mounts):
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.105",
+    "version": "0.0.107",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {

package/server/auth/AuthController.ts

@@ -443,6 +443,19 @@ class EmailOwner {
     }
 }
 
+/** Reverse-index key for the STABLE ToilUserId uniqueness guard: (realm host,
+ *  32-byte id). Realm-scoped, so uniqueness is enforced PER TENANT — two sites
+ *  never share an id namespace. */
+@data
+class UserIdKey {
+    host: string = '';
+    id: Uint8Array = new Uint8Array(0);
+    constructor(host: string = '', id: Uint8Array = new Uint8Array(0)) {
+        this.host = host;
+        this.id = id;
+    }
+}
+
 @data
 class TokenId {
     hash: Uint8Array = new Uint8Array(0);
@@ -488,6 +501,9 @@ class AuthAccount {
     // 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;
+    // Append-only: the STABLE ToilUserId, derived once at registration. Reset rotates
+    // publicKey but leaves this, so the id is stable across a reset.
+    toilUserId: Uint8Array = new Uint8Array(0);
 }
 
 @data
@@ -534,6 +550,7 @@ class TwoFaChallenge {
 class AuthDb {
     @collection static accounts: Documents<Username, AuthAccount>;
     @collection static emails: Documents<EmailKey, EmailOwner>; // email -> username (uniqueness index)
+    @collection static userIds: Documents<UserIdKey, EmailOwner>; // toilUserId -> username (per-tenant uniqueness guard)
     @collection static challenges: Documents<ChallengeId, Challenge>;
     @collection static confirmTokens: Documents<TokenId, TokenRec>;
     @collection static resetTokens: Documents<TokenId, TokenRec>;
@@ -633,6 +650,10 @@ class Auth {
         a.memKiB = MEM_KIB;
         a.iterations = ITERS;
         a.parallelism = PAR;
+        // Derive + persist the stable id once, here. Tenant-scoped (framed domain +
+        // realm-keyed reverse index below).
+        const uid = ToilUserId.derive(pk, username, authDomain(ctx)).toBytes();
+        a.toilUserId = uid;
         // create-if-absent: a racing duplicate registration loses here, not above.
         if (!AuthDb.accounts.create(new Username(h, username), a)) {
             return Response.bytes(new DataWriter().writeU8(ST_TAKEN).toBytes());
@@ -645,6 +666,13 @@ class Auth {
             AuthDb.accounts.delete(new Username(h, username));
             return Response.bytes(new DataWriter().writeU8(ST_EMAIL_TAKEN).toBytes());
         }
+        // Per-tenant id-uniqueness guard: atomic create of toilUserId -> username
+        // (race-safe at the key's home). A lost race rolls back email + account.
+        if (!AuthDb.userIds.create(new UserIdKey(h, uid), new EmailOwner(username))) {
+            AuthDb.emails.delete(new EmailKey(h, email));
+            AuthDb.accounts.delete(new Username(h, username));
+            return fail();
+        }
 
         if (mustConfirm) {
             this.issueConfirmation(h, ctx, username, email);
@@ -841,8 +869,7 @@ class Auth {
         //    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
         //    ToilUserId is derived from the login public key + username + tenant domain.
-        const domain = authDomain(ctx);
-        const toilUserId = ToilUserId.derive(acct.publicKey, ch.username, domain).toBytes();
+        const toilUserId = this.stableUserId(ctx, h, ch.username, acct);
         const userData = __toilEncodeAuthUser(toilUserId, ch.username);
         const w = new DataWriter();
         w.writeU8(ST_OK);
@@ -958,6 +985,17 @@ class Auth {
         return Response.bytes(new DataWriter().writeU8(ST_OK).toBytes());
     }
 
+    /** The account's STABLE ToilUserId, persisted at registration (so reset never
+     *  changes it). An empty stored id is derived once, persisted, and indexed. */
+    private stableUserId(ctx: RouteContext, h: string, username: string, acct: AuthAccount): Uint8Array {
+        if (acct.toilUserId.length > 0) return acct.toilUserId;
+        const uid = ToilUserId.derive(acct.publicKey, username, authDomain(ctx)).toBytes();
+        acct.toilUserId = uid;
+        AuthDb.accounts.patch(new Username(h, username), acct);
+        AuthDb.userIds.create(new UserIdKey(h, uid), new EmailOwner(username));
+        return uid;
+    }
+
     /** GET /auth/me  (@auth: 401 without a valid session) -> the typed user
      *  (bytes(toilUserId) str(username)). `AuthService.getUser()` is auto-typed
      *  to the built-in `@user` with no type argument. */
@@ -1037,8 +1075,7 @@ class Auth {
         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 toilUserId = this.stableUserId(ctx, h, ch.username, acct);
         const userData = __toilEncodeAuthUser(toilUserId, ch.username);
         const w = new DataWriter();
         w.writeU8(ST_OK);
@@ -1188,19 +1225,12 @@ class Auth {
         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);
+                // The subject is contextual (login vs setup) so AuthController owns it;
+                // the body/html come from the generated `AuthEmail` — the built-in
+                // default, or an `emails/auth-2fa.tsx` override filling `{code}`. The
+                // send is DETACHED (constant-time, no provider-RTT parking), a property
+                // the override cannot lose (AuthEmail.twofa uses sendDetached).
+                AuthEmail.twofa(email, code, subject);
                 return twoFaCodeHash(host, username, code);
             }
             // >>> case TWOFA_TOTP: { return twoFaSecretBinding(username); } <<<
@@ -1267,19 +1297,11 @@ class Auth {
         // Token in the URL FRAGMENT (see resetRequest): kept out of server/CDN
         // logs and the Referer header; the confirm page reads it from location.hash.
         const link = baseUrl(ctx) + '/confirm#token=' + crypto.toHex(raw);
-        const subject = 'Confirm your account';
-        const text = 'Confirm your account by opening this link:\n' + link + '\n';
-        const html =
-            '<p>Confirm your account by clicking the link below:</p>' +
-            '<p><a href="' +
-            link +
-            '">Confirm my account</a></p>' +
-            '<p>Or paste this into your browser:<br>' +
-            link +
-            '</p>';
-        // DETACHED (non-suspending) send: constant-time, no provider-RTT parking on
-        // the "account exists" path (see the enumeration note on this method).
-        EmailService.sendDetached(email, subject, text, 'verify', html);
+        // The built-in confirm email, or an `emails/auth-confirm.tsx` override filling
+        // `{link}`. DETACHED (non-suspending) send: constant-time, no provider-RTT
+        // parking on the "account exists" path (see the enumeration note on this
+        // method); AuthEmail.confirm uses sendDetached, so an override keeps that.
+        AuthEmail.confirm(email, link);
     }
 
     /** Email a password-reset link. Best-effort (the request path already
@@ -1292,19 +1314,10 @@ class Auth {
      *  (Residual: the reset-token mint on the exists path still does a sub-ms
      *  ToilDB write the miss path skips.) */
     private sendResetEmail(email: string, link: string): void {
-        const subject = 'Reset your password';
-        const text = 'Reset your password by opening this link:\n' + link + '\n';
-        const html =
-            '<p>We received a request to reset your password. Click the link below:</p>' +
-            '<p><a href="' +
-            link +
-            '">Reset my password</a></p>' +
-            '<p>If you did not request this, you can ignore this email.</p>' +
-            '<p>Or paste this into your browser:<br>' +
-            link +
-            '</p>';
-        // DETACHED (non-suspending) send: constant-time, closes the reset-request
-        // email-enumeration timing oracle (see the note above).
-        EmailService.sendDetached(email, subject, text, 'reset', html);
+        // The built-in reset email, or an `emails/auth-reset.tsx` override filling
+        // `{link}`. DETACHED (non-suspending) send: constant-time, closes the
+        // reset-request email-enumeration timing oracle (see the note above);
+        // AuthEmail.reset uses sendDetached, so an override keeps that property.
+        AuthEmail.reset(email, link);
     }
 }

package/server/globals/auth.ts

@@ -228,8 +228,16 @@ function __labelled(label: string, transcriptHash: Uint8Array): Uint8Array {
 function __reqIsSecure(): bool {
     const req = Server.currentRequest;
     if (req == null) return false;
+    // Proxied deployments: trust the terminating proxy's scheme header.
     const proto = req.header('x-forwarded-proto');
-    return proto != null && proto == 'https';
+    if (proto != null) return proto == 'https';
+    // Direct-origin deployments: the edge terminates TLS itself and sends no
+    // x-forwarded-proto, so fall back to the configured public origin. An https
+    // PUBLIC_BASE_URL means the site is served over TLS, so the auth cookies must
+    // be Secure + __Host-/__Secure- prefixed. Without this a direct-origin HTTPS
+    // edge sets bare cookies and the client's getUser() misses the __Secure- name.
+    const base = Environment.get('PUBLIC_BASE_URL');
+    return base != null && base.startsWith('https://');
 }
 
 export namespace AuthService {
@@ -402,7 +410,10 @@ export namespace AuthService {
         let cookie = Cookie.create(USER_BASE, base64UrlEncode(userData))
             .sameSite(SameSite.Lax)
             .maxAge(<i64>ttlSecs);
-        cookie = secure ? cookie.asSecurePrefixed() : cookie.path('/');
+        // Path=/ in BOTH branches: asSecurePrefixed() sets no path, so without this
+        // the cookie is scoped to the /auth request path and getUser() can't read it
+        // on /login or /dashboard.
+        cookie = secure ? cookie.asSecurePrefixed().path('/') : cookie.path('/');
         return cookie;
     }
 
@@ -412,7 +423,10 @@ export namespace AuthService {
         let cookie = Cookie.create(USER_BASE, '')
             .sameSite(SameSite.Lax)
             .maxAge(0);
-        cookie = secure ? cookie.asSecurePrefixed() : cookie.path('/');
+        // Path=/ in BOTH branches: asSecurePrefixed() sets no path, so without this
+        // the cookie is scoped to the /auth request path and getUser() can't read it
+        // on /login or /dashboard.
+        cookie = secure ? cookie.asSecurePrefixed().path('/') : cookie.path('/');
         return cookie;
     }
 

package/server/globals/email.ts

@@ -68,7 +68,7 @@ export namespace EmailService {
      * the off-core mailer reports a result.
      *
      * `body` is the plain-text body; pass a non-empty `html` to send an HTML
-     * message (then `body` is the plain-text alternative — set both for the best
+     * message (then `body` is the plain-text alternative; set both for the best
      * deliverability, or leave `body` empty for HTML-only). `purpose` is a short,
      * non-PII tag used for host-side dedup/abuse keying.
      */
@@ -181,7 +181,7 @@ export class RenderedEmail {
  *   welcome.send('alice@example.com', vars, 'welcome');
  *
  * `{{ key }}` (with surrounding spaces) is accepted; an unknown placeholder
- * renders to the empty string. `html` is optional — omit it for a plain-text
+ * renders to the empty string. `html` is optional: omit it for a plain-text
  * template.
  */
 export class EmailTemplate {
@@ -209,6 +209,19 @@ export class EmailTemplate {
         const r = this.render(vars);
         return EmailService.send(to, r.subject, r.body, purpose, r.html);
     }
+
+    /**
+     * Render and DETACHED-send to `to`: frames the message and returns via the
+     * non-suspending {@link EmailService.sendDetached}, so the call is constant
+     * time regardless of whether the recipient exists. Use for transactional auth
+     * mail (confirm / reset links, 2FA codes) whose delivery result the caller
+     * does not need; this is what keeps the built-in auth flows free of an
+     * email-enumeration timing oracle even when an app overrides the template.
+     */
+    sendDetached(to: string, vars: Map<string, string>, purpose: string = 'tx'): EmailStatus {
+        const r = this.render(vars);
+        return EmailService.sendDetached(to, r.subject, r.body, purpose, r.html);
+    }
 }
 
 /**

package/server/globals/userid.ts

@@ -30,12 +30,18 @@ export class ToilUserId {
      * unambiguous, and `domain` is the trusted tail supplied by the host, not the user.
      */
     static derive(mldsaPublicKey: Uint8Array, identifier: string, domain: string): ToilUserId {
+        // Length-framed, domain-separated preimage: a u32 length prefix on every
+        // field keeps ids collision-free across tenants; the context tag separates
+        // this hash from other sha256 uses.
+        const ctx = Uint8Array.wrap(String.UTF8.encode(USERID_CONTEXT));
         const id = Uint8Array.wrap(String.UTF8.encode(identifier));
         const dom = Uint8Array.wrap(String.UTF8.encode(domain));
-        const buf = new Uint8Array(mldsaPublicKey.length + id.length + dom.length);
-        buf.set(mldsaPublicKey, 0);
-        buf.set(id, mldsaPublicKey.length);
-        buf.set(dom, mldsaPublicKey.length + id.length);
+        const buf = new Uint8Array(16 + ctx.length + mldsaPublicKey.length + id.length + dom.length);
+        let off = 0;
+        off = putField(buf, off, ctx);
+        off = putField(buf, off, mldsaPublicKey);
+        off = putField(buf, off, id);
+        off = putField(buf, off, dom);
         return ToilUserId.fromBytes(crypto.sha256(buf));
     }
 
@@ -105,3 +111,18 @@ export class ToilUserId {
         return !this.equals(other);
     }
 }
+
+/** Domain-separation tag for {@link ToilUserId.derive}; versioned. */
+const USERID_CONTEXT: string = 'toil.userid.v1';
+
+/** Append a u32-LE length prefix + `src` to `buf` at `off`; return the new offset. */
+function putField(buf: Uint8Array, off: i32, src: Uint8Array): i32 {
+    const n = src.length;
+    buf[off] = <u8>(n & 0xff);
+    buf[off + 1] = <u8>((n >> 8) & 0xff);
+    buf[off + 2] = <u8>((n >> 16) & 0xff);
+    buf[off + 3] = <u8>((n >> 24) & 0xff);
+    off += 4;
+    buf.set(src, off);
+    return off + n;
+}

package/src/compiler/auth-emails.ts

@@ -0,0 +1,296 @@
+/**
+ * Built-in auth email templates + their per-app OVERRIDE pipeline.
+ *
+ * The built-in auth controller (`server/auth/AuthController.ts`) sends three
+ * transactional emails: the email-verification link, the password-reset link,
+ * and the 2FA code. Their default subject/text/html live here as the single
+ * source of truth. An app overrides any of them by dropping a reserved-name
+ * React template in `emails/`:
+ *
+ *   emails/auth-confirm.tsx  -> email verification   (interpolates `{link}`)
+ *   emails/auth-reset.tsx    -> password reset        (interpolates `{link}`)
+ *   emails/auth-2fa.tsx      -> 2FA code              (interpolates `{code}`)
+ *
+ * Whenever auth is on, the build (re)writes an ambient `_auth_emails.ts` into the
+ * toiljs `server/globals` LIB dir, exposing `AuthEmail.confirm/reset/twofa` baked
+ * with the app's override when present and the default otherwise. Because it rides
+ * the same `lib` set as `EmailService`/`AuthService`, the node_modules-compiled
+ * `AuthController` calls it with NO import (an exported namespace in a plain app
+ * entry would be module-scoped, not global). Every send goes through
+ * `EmailTemplate.sendDetached`, so overriding a template can never reintroduce the
+ * auth email-enumeration timing oracle the detached send closes.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import pc from 'picocolors';
+import { createServer } from 'vite';
+
+import type { ResolvedToilConfig } from './config.js';
+import { RESERVED_AUTH_EMAIL_NAMES, renderEmailFile, toPascal, type RenderedEmail } from './emails.js';
+import { createViteConfig } from './vite.js';
+
+/**
+ * The APP-LOCAL library directory the auth-email module is generated into,
+ * relative to the project root (posix, for the toilscript `--lib` CLI arg). It is
+ * passed to the compiler via `--lib` (see runToilscriptPass), which "uses exports
+ * of all top-level files at this path as globals". That is what makes the
+ * generated `AuthEmail` namespace resolvable from the node_modules-compiled
+ * `AuthController` with NO import, the same way `EmailService`/`AuthService` are
+ * ambient. Generating HERE (the app's own gitignored `.toil/`) rather than into
+ * `node_modules/toiljs/server/globals` keeps it PER-APP: a pnpm/workspace/linked
+ * install physically shares that package dir, so writing there would let one app
+ * clobber another's templates (or delete the file another app is compiling), and
+ * a read-only store would fail the build. `.toil` is always app-writable.
+ */
+export const AUTH_EMAILS_LIB_SUBDIR = '.toil/authlib';
+
+/** The reserved override names (PascalCase), one per built-in auth email. */
+type AuthName = 'AuthConfirm' | 'AuthReset' | 'Auth2fa';
+
+/** One built-in auth email: its reserved override name, the token it fills, the
+ *  host-side `purpose` tag, and the default subject/text/html (with `{{token}}`). */
+interface AuthEmailSpec {
+    /** The generated `AuthEmail.<fn>` this feeds. */
+    readonly fn: 'confirm' | 'reset' | 'twofa';
+    /** The single runtime value the template interpolates. */
+    readonly token: 'link' | 'code';
+    /** Host dedup/abuse tag; must match what AuthController passed before. */
+    readonly purpose: string;
+    /** Default subject. Empty (and ignored) for `twofa`: AuthController passes login/setup subjects. */
+    readonly defaultSubject: string;
+    readonly defaultText: string;
+    readonly defaultHtml: string;
+    /** Whether the subject is a runtime arg (twofa) rather than a baked default (confirm/reset). */
+    readonly subjectFromArg: boolean;
+}
+
+/** The reserved override name -> its spec. Keys mirror {@link RESERVED_AUTH_EMAIL_NAMES}. */
+const SPECS: Record<AuthName, AuthEmailSpec> = {
+    AuthConfirm: {
+        fn: 'confirm',
+        token: 'link',
+        purpose: 'verify',
+        subjectFromArg: false,
+        defaultSubject: 'Confirm your account',
+        defaultText: 'Confirm your account by opening this link:\n{{link}}\n',
+        defaultHtml:
+            '<p>Confirm your account by clicking the link below:</p>' +
+            '<p><a href="{{link}}">Confirm my account</a></p>' +
+            '<p>Or paste this into your browser:<br>{{link}}</p>',
+    },
+    AuthReset: {
+        fn: 'reset',
+        token: 'link',
+        purpose: 'reset',
+        subjectFromArg: false,
+        defaultSubject: 'Reset your password',
+        defaultText: 'Reset your password by opening this link:\n{{link}}\n',
+        defaultHtml:
+            '<p>We received a request to reset your password. Click the link below:</p>' +
+            '<p><a href="{{link}}">Reset my password</a></p>' +
+            '<p>If you did not request this, you can ignore this email.</p>' +
+            '<p>Or paste this into your browser:<br>{{link}}</p>',
+    },
+    Auth2fa: {
+        fn: 'twofa',
+        token: 'code',
+        purpose: '2fa',
+        subjectFromArg: true,
+        // Subject is supplied by AuthController (login vs setup), so it is not baked.
+        defaultSubject: '',
+        defaultText:
+            'Your verification code is {{code}}.\n' +
+            'It expires in a few minutes. If you did not request it, ignore this email.\n',
+        defaultHtml:
+            '<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>',
+    },
+};
+
+const AUTH_NAMES = Object.keys(SPECS) as AuthName[];
+
+/** The effective (override-or-default) parts for each auth email. */
+type Parts = Record<AuthName, Effective>;
+interface Effective {
+    readonly subject: string;
+    readonly text: string;
+    readonly html: string;
+}
+
+const GENERATED_BASENAME = '_auth_emails.ts';
+
+function warn(msg: string): void {
+    process.stderr.write(`  toil: auth emails ${msg}\n`);
+}
+
+/** A valid AS/JS string literal (double-quoted, fully escaped). */
+function asLit(s: string): string {
+    return JSON.stringify(s);
+}
+
+/** Every reserved auth-override file present in `emails/`, by PascalCase name. */
+function reservedFilesIn(emailsDir: string): Map<AuthName, string> {
+    const out = new Map<AuthName, string>();
+    if (!fs.existsSync(emailsDir)) return out;
+    for (const f of fs.readdirSync(emailsDir).sort()) {
+        if (!/\.(tsx|jsx)$/.test(f)) continue;
+        const name = toPascal(f.replace(/\.(tsx|jsx)$/, ''));
+        if (RESERVED_AUTH_EMAIL_NAMES.has(name) && !out.has(name as AuthName))
+            out.set(name as AuthName, f);
+    }
+    return out;
+}
+
+/**
+ * Fold a rendered override into the effective parts for `name`, warning about
+ * templates that will not interpolate correctly (a missing required token means
+ * the link/code would be absent; an extra token renders empty). A `subject` the
+ * renderer defaulted to the module name is treated as "no custom subject".
+ */
+function effectiveFromOverride(name: AuthName, spec: AuthEmailSpec, r: RenderedEmail): Effective {
+    if (!r.tokens.includes(spec.token))
+        warn(
+            `override emails/${name} never uses the {${spec.token}} prop, so the ` +
+                `${spec.token === 'link' ? 'link' : 'code'} will be missing from the email.`,
+        );
+    for (const t of r.tokens)
+        if (t !== spec.token)
+            warn(
+                `override emails/${name} uses {${t}}, which auth does not provide ` +
+                    `(only {${spec.token}}); it will render empty.`,
+            );
+    // For twofa the subject is a runtime arg; for confirm/reset use the template's
+    // subject unless it defaulted to the component name (no `export const subject`).
+    const subject = spec.subjectFromArg || r.subject === name ? spec.defaultSubject : r.subject;
+    return { subject, text: r.text, html: r.html };
+}
+
+/** Codegen one `AuthEmail.<fn>` function. `twofa` takes its subject as an arg. */
+function emitFn(spec: AuthEmailSpec, eff: Effective): string[] {
+    const subjectExpr = spec.subjectFromArg ? 'subject' : asLit(eff.subject);
+    const sig =
+        spec.fn === 'twofa'
+            ? 'twofa(to: string, code: string, subject: string): void'
+            : `${spec.fn}(to: string, ${spec.token}: string): void`;
+    return [
+        `  export function ${sig} {`,
+        `    const T: string = ${asLit(eff.text)};`,
+        `    const H: string = ${asLit(eff.html)};`,
+        `    const v = new Map<string, string>();`,
+        `    v.set(${asLit(spec.token)}, ${spec.token});`,
+        `    new EmailTemplate(${subjectExpr}, T, H).sendDetached(to, v, ${asLit(spec.purpose)});`,
+        `  }`,
+    ];
+}
+
+/** Codegen the ambient `AuthEmail` AssemblyScript module. */
+function moduleSource(parts: Parts): string {
+    const out: string[] = [
+        '// GENERATED by toiljs from the built-in auth email templates -- DO NOT EDIT.',
+        '// Override any of these by adding emails/auth-confirm.tsx, emails/auth-reset.tsx,',
+        '// or emails/auth-2fa.tsx (see docs/auth/emails.md). `EmailTemplate` is a toiljs',
+        '// global (server/globals/email.ts); the detached send keeps auth constant-time.',
+        '',
+        'export namespace AuthEmail {',
+    ];
+    for (const name of AUTH_NAMES) out.push(...emitFn(SPECS[name], parts[name]));
+    out.push('}');
+    return out.join('\n') + '\n';
+}
+
+/**
+ * Best-effort removal of a stale copy from the pre-0.0.107 location
+ * (`node_modules/toiljs/server/globals/_auth_emails.ts`). Leaving it there would
+ * define a SECOND `AuthEmail` namespace alongside the new app-local one and break
+ * the compile with a duplicate symbol, so a project upgraded in place (without a
+ * fresh `npm i`) is cleaned up here. Never throws (a read-only store just skips).
+ */
+function removeLegacyModule(root: string): void {
+    try {
+        const legacy = path.join(root, 'node_modules', 'toiljs', 'server', 'globals', GENERATED_BASENAME);
+        if (fs.existsSync(legacy)) fs.rmSync(legacy);
+    } catch {
+        // read-only / missing: nothing to clean, not fatal
+    }
+}
+
+/**
+ * (Re)write `_auth_emails.ts` into the app-local `.toil/authlib` LIB dir so the
+ * built-in auth controller has its email senders, baking any reserved
+ * `emails/*.tsx` override over the default. Runs BEFORE the toilscript server
+ * build (like {@link renderEmails}) so the module is compiled in via `--lib`. A
+ * no-op that removes a stale module when auth is off or there is no server. Only
+ * spins up Vite when an override actually exists.
+ */
+export async function renderAuthEmails(cfg: ResolvedToilConfig, authOn: boolean): Promise<void> {
+    const generatedPath = path.join(cfg.root, AUTH_EMAILS_LIB_SUBDIR, GENERATED_BASENAME);
+    removeLegacyModule(cfg.root);
+
+    // No server to compile into, or auth off: ensure no stale module lingers.
+    const hasServer = fs.existsSync(path.join(cfg.root, 'toilconfig.json'));
+    if (!authOn || !hasServer) {
+        if (fs.existsSync(generatedPath)) fs.rmSync(generatedPath);
+        return;
+    }
+
+    const emailsDir = path.join(cfg.root, 'emails');
+    const overrides = reservedFilesIn(emailsDir);
+
+    // Start from every default, then render + fold in whatever the app overrides.
+    const parts = {} as Parts;
+    for (const name of AUTH_NAMES) {
+        const spec = SPECS[name];
+        parts[name] = { subject: spec.defaultSubject, text: spec.defaultText, html: spec.defaultHtml };
+    }
+
+    if (overrides.size > 0) {
+        const { renderToStaticMarkup } = await import('react-dom/server');
+        const server = await createServer({
+            ...(await createViteConfig(cfg)),
+            server: { middlewareMode: true, hmr: false },
+            appType: 'custom',
+            logLevel: 'silent',
+        });
+        try {
+            for (const [name, file] of overrides) {
+                try {
+                    const r = await renderEmailFile(
+                        server,
+                        emailsDir,
+                        file,
+                        renderToStaticMarkup as (el: unknown) => string,
+                    );
+                    if (r) parts[name] = effectiveFromOverride(name, SPECS[name], r);
+                    else warn(`skipped ${file} (no default-exported component)`);
+                } catch (err) {
+                    warn(`skipped ${file} (${err instanceof Error ? err.message : String(err)})`);
+                }
+            }
+        } finally {
+            await server.close();
+        }
+    }
+
+    const next = moduleSource(parts);
+    const prev = fs.existsSync(generatedPath) ? fs.readFileSync(generatedPath, 'utf8') : null;
+    if (prev === next) return; // no change: do not bump mtime (would retrigger the dev watcher)
+    fs.mkdirSync(path.dirname(generatedPath), { recursive: true });
+    fs.writeFileSync(generatedPath, next);
+    if (overrides.size > 0)
+        process.stdout.write(
+            pc.green('  ✓ ') +
+                pc.dim(
+                    `auth emails: overrode ${[...overrides.keys()].map((n) => SPECS[n].fn).join(', ')}`,
+                ) +
+                '\n',
+        );
+}
+
+/** The generated module's basename, so the server watcher can ignore its own output. */
+export const AUTH_EMAILS_GENERATED_BASENAME = GENERATED_BASENAME;
+
+// Exported for unit testing the pure fold/codegen without a Vite server.
+export const __test = { moduleSource, effectiveFromOverride, SPECS };

package/src/compiler/emails.ts

@@ -63,6 +63,15 @@ const REACT_INTERNAL = new Set([
     'then', // so a thenable check never tokenizes
 ]);
 
+/**
+ * Reserved `emails/*.tsx` module names (by PascalCase basename) that OVERRIDE a
+ * built-in auth email instead of becoming a generic `Emails.<Name>.send(...)`
+ * entry. When one is present, the auth pipeline (src/compiler/auth-emails.ts)
+ * bakes it into `_auth_emails.ts` in place of the default; here we just make sure
+ * it does NOT also surface as an app-callable `Emails.*` template.
+ */
+export const RESERVED_AUTH_EMAIL_NAMES = new Set(['AuthConfirm', 'AuthReset', 'Auth2fa']);
+
 const TOKEN_RE = /\{\{\s*([A-Za-z_$][\w$]*)\s*\}\}/g;
 
 function extractTokens(s: string): string[] {
@@ -240,7 +249,7 @@ export function toPascal(base: string): string {
 
 /** Server source dir (where the generated module must live to be compiled): the
  *  dir of the first toilconfig entry, else `<root>/server`. */
-function serverDir(root: string): string {
+export function serverDir(root: string): string {
     try {
         const cfg = JSON.parse(fs.readFileSync(path.join(root, 'toilconfig.json'), 'utf8')) as {
             entries?: unknown;
@@ -316,7 +325,7 @@ function warn(msg: string): void {
  * there is no `emails/` directory. Removes a stale generated module when the
  * directory becomes empty.
  */
-export async function renderEmails(cfg: ResolvedToilConfig): Promise<void> {
+export async function renderEmails(cfg: ResolvedToilConfig, authOn = false): Promise<void> {
     const emailsDir = path.join(cfg.root, 'emails');
     const generatedPath = path.join(serverDir(cfg.root), GENERATED_BASENAME);
 
@@ -344,6 +353,15 @@ export async function renderEmails(cfg: ResolvedToilConfig): Promise<void> {
     const rendered: RenderedEmail[] = [];
     try {
         for (const file of files) {
+            // Reserved auth-override templates (emails/auth-confirm.tsx, …) are
+            // consumed by the auth pipeline, not surfaced as generic `Emails.*`.
+            // Only reserved WHEN AUTH IS ON: a non-auth project keeping an email
+            // by that name still gets its normal `Emails.<Name>.send(...)`.
+            if (
+                authOn &&
+                RESERVED_AUTH_EMAIL_NAMES.has(toPascal(path.basename(file).replace(/\.(tsx|jsx)$/, '')))
+            )
+                continue;
             try {
                 const r = await renderEmailFile(
                     server,