toiljs 0.0.104 → 0.0.106

package/docs/auth/emails.md

@@ -0,0 +1,91 @@
+# Customizing the auth emails
+
+Built-in auth sends three transactional emails: the email-verification link, the password-reset link, and the two-factor code. Each ships with a plain, working default. You can replace any of them with your own branded template, and you never touch the auth code to do it.
+
+## The three emails
+
+| Email | When it sends | The value it gives your template |
+| --- | --- | --- |
+| Email verification | On register, when email confirmation is on | `link` (the confirm URL) |
+| Password reset | On `POST /auth/reset/request` | `link` (the reset URL) |
+| Two-factor code | On login or 2FA setup, for the email method | `code` (the numeric code) |
+
+The defaults are intentionally minimal so a fresh project sends real, correct mail with no setup. To match your brand, override them.
+
+## How to override
+
+Drop a React template in your project's `emails/` folder with the reserved name for that email. If the file exists, the build uses it; if not, the default stands. This is the same `emails/*.tsx` system you use for your own mail (see [Email](../services/email.md)), so you get full markup and inline CSS.
+
+| Reserved file | Overrides | Prop it must read |
+| --- | --- | --- |
+| `emails/auth-confirm.tsx` | Email verification | `link` |
+| `emails/auth-reset.tsx` | Password reset | `link` |
+| `emails/auth-2fa.tsx` | Two-factor code | `code` |
+
+Each template is a default-exported React component. Read the one prop it is given, and it becomes a `{{token}}` hole the edge fills per send. Reading any other prop renders empty, so the build warns you.
+
+```tsx
+// emails/auth-confirm.tsx  ->  overrides the email-verification message.
+export const subject = 'Verify your Acme account';
+
+export default function AuthConfirm({ link }: { link: string }) {
+    return (
+        <div style={{ fontFamily: 'system-ui', padding: 24 }}>
+            <h1 style={{ color: '#cb9820' }}>Welcome to Acme</h1>
+            <p>Tap below to verify your email and finish signing up.</p>
+            <p>
+                <a
+                    href={link}
+                    style={{ background: '#cb9820', color: '#fff', padding: '10px 18px', borderRadius: 8, textDecoration: 'none' }}
+                >
+                    Verify my email
+                </a>
+            </p>
+            <p style={{ color: '#666', fontSize: 13 }}>Or paste this link: {link}</p>
+        </div>
+    );
+}
+```
+
+The reset template works the same way with the `link` prop.
+
+## The subject line
+
+For verification and reset, set the subject with `export const subject = '...'`. Leave it out and the default subject is used (`Confirm your account`, `Reset your password`).
+
+The two-factor email is different: its subject is set by the framework because it changes with context (a login code versus a setup code). Your `emails/auth-2fa.tsx` override controls the body and HTML around the `code`, and the subject stays contextual. A `subject` export in that file is ignored.
+
+```tsx
+// emails/auth-2fa.tsx  ->  overrides the 2FA code message (subject is contextual).
+export default function Auth2fa({ code }: { code: string }) {
+    return (
+        <div style={{ fontFamily: 'system-ui', padding: 24, textAlign: 'center' }}>
+            <p>Your Acme verification code:</p>
+            <p style={{ fontSize: 32, fontWeight: 700, letterSpacing: 6 }}>{code}</p>
+            <p style={{ color: '#666' }}>It expires in a few minutes.</p>
+        </div>
+    );
+}
+```
+
+## What you can and cannot put in
+
+Each template is rendered once, at build time, into a static string of HTML with your styles inlined, and the prop becomes a fill hole. So a fixed layout and inline styles work, but per-send logic does not: a `{items.map(...)}` or a conditional runs at build, not per email. For these three messages that is all you need, one link or one code.
+
+The only value auth hands each template is the one in the table above (`link` or `code`). There is no user name, no app name, no expiry value. Write those into the template text directly.
+
+Styling rules are the same as any toiljs email: write inline `style={{ ... }}`, or import a stylesheet and its rules are inlined for you. A bare CSS import with no inlining has no effect in an email client. See [Email](../services/email.md) for the details.
+
+## Delivery stays safe
+
+You cannot weaken the security of these flows by overriding a template. Every auth email is sent detached (fire-and-forget), so the response time never reveals whether an address maps to an account. That holds whether the message is the default or your override. Overriding only changes what the email looks like, never how it is sent.
+
+## Where the templates go
+
+There is nothing to import and nothing to register. The build reads `emails/auth-*.tsx`, bakes the effective templates into the compiled server, and the auth controller sends them. Changing a template and rebuilding (or saving under `toiljs dev`) is all it takes.
+
+## Related
+
+- [Email](../services/email.md): the full `emails/*.tsx` system, `EmailService`, and `EmailTemplate`.
+- [Configuration](./configuration.md): the auth secrets and the email provider a deployment must set.
+- [Usage](./usage.md): enabling auth, the client API, and guarding routes.

package/docs/introduction/README.md

@@ -18,20 +18,29 @@ Types tie the three together. Change a field on the server and the client stops
 
 ## The problem it solves
 
-Most apps read fast and write slow. Pages load from caches everywhere, but a write, say a comment or an order, has to reach one database in one region. A user in Tokyo writing to Virginia waits for the trip there and back. That single region is also a single point of failure.
+A good web app should be fast everywhere, secure by default, and able to grow without a rewrite. Getting there is the hard part, and most of it has nothing to do with your actual product.
 
-toil closes the gap in two moves. Your code runs at the edge instead of one origin. And ToilDB is built to distribute the writes, not just the reads: every key has a home region that orders its writes, while the data copies outward so reads stay local and quick.
+You assemble it from rented parts: a host, serverless functions, a database, an auth provider, email, a cache, a queue, analytics, a realtime service. Each is its own account, bill, and SDK, and you keep them all in sync. Under that sits a decade of legacy tooling and a node_modules folder heavier than your app. Worse, the fast and secure version is never the default. A CDN, careful caching, region tuning, hardened auth, current crypto: all of it is extra work, so most apps ship slower and less safe than they should.
 
-Spreading reads is easy, and everyone does it. Spreading writes is the hard part, and it is why most "global" apps are only global for reading.
+toil deletes that assembly. One framework runs your frontend, backend, and database at the edge, next to users. Auth, email, realtime, and background jobs are built in and owned. Login is post-quantum out of the box. There is nothing to wire up and no infrastructure to reason about. The good version is the only version.
+
+Distributing writes worldwide is one of the hard problems it handles under the hood. Most stacks spread reads everywhere but pin every write to one region, so a user far from it waits for a round trip and that region is a single point of failure. ToilDB is built to distribute the writes too: every key has a home region that orders its writes while the data copies outward for fast local reads. You never set any of it up.
 
 ```mermaid
 flowchart TB
-    subgraph Ordinary["The ordinary web"]
-        U1["User in Tokyo"] -->|fast| E1["Edge (pages)"]
-        E1 -->|slow, one region| DB1[("Database in Virginia")]
+    subgraph Assemble["The usual way: rent and wire the parts yourself"]
+        direction TB
+        A["Your app"] --> H["host"]
+        A --> F["functions"]
+        A --> D["database"]
+        A --> Au["auth"]
+        A --> Em["email"]
+        A --> Rt["realtime"]
+        A --> J["jobs"]
     end
-    subgraph Toil["toil"]
-        U2["User in Tokyo"] -->|fast| E2["Edge near Tokyo<br/>frontend + backend + data"]
+    subgraph Toil["toil: one framework, at the edge, by default"]
+        direction TB
+        A2["Your app"] --> T["frontend + backend + database + auth +<br/>email + realtime + jobs, built in and near users"]
     end
 ```
 
@@ -43,7 +52,7 @@ Read these in order. Each one builds on the last.
 2. **[What comes built in](./modern-stack.md)** The full list of what toil owns and runs for you, and what it does not.
 3. **[How toil works](./how-it-works.md)** The whole path, from a React click through WebAssembly to ToilDB and back.
 4. **[Why it scales cheaply](./hyperscale.md)** How one small program can serve the whole planet without a per-app server bill.
-5. **[How toil distributes writes](./distributed.md)** The hardest problem in web infrastructure, and how ToilDB is built to solve it.
+5. **[How toil distributes writes](./distributed.md)** One of the hardest problems in web infrastructure, and how ToilDB is built to solve it.
 6. **[toil next to other stacks](./vs-other-frameworks.md)** A fair comparison with Next.js, Rails, serverless, and the rest, wins and losses both.
 7. **[The bar toil holds itself to](./design-principles.md)** The RSG rubric, and its one rule: your grade is your weakest part.
 
@@ -51,7 +60,7 @@ Read these in order. Each one builds on the last.
 
 - **Who it is for:** anyone shipping a real product who wants global speed without a platform team or ten stitched-together services.
 - **Why it is fast:** the code runs next to the user, with no trip to a distant origin.
-- **Why it is different:** it distributes writes, not only reads.
+- **Why it is different:** the whole stack is built in and owned, so there is nothing to assemble, and it distributes writes worldwide, not only reads.
 - **Why it is safe:** the backend is sandboxed, passwords never reach the server in a usable form, secrets never ship in the code, and the browser checks every file it loads.
 
 Ready to build? Jump to [Getting started](../getting-started/README.md).

package/docs/introduction/hyperscale.md

@@ -1,6 +1,6 @@
 # What makes toil hyper-scalable
 
-Hyper-scale means serving very large worldwide traffic at low latency without rebuilding your app as it grows. The test is simple. Traffic climbs from a thousand users to a hundred million across every continent. Do you rewrite the system, or just run more of it?
+Hyper-scale means serving very large worldwide traffic at low latency without rebuilding your app as it grows. Picture traffic climbing from a thousand users to a hundred million across every continent. Do you rewrite the system, or just run more of it?
 
 Any stack can reach that scale if you spend enough: dedicated infrastructure per app, a rented vendor for each moving part, and an ops team to keep the seams from tearing. toil reaches the same scale from the other direction, cheaply. The whole design aims to make worldwide reach a default, not a budget line. This page is about cost.
 

package/docs/introduction/vs-other-frameworks.md

@@ -2,7 +2,7 @@
 
 This page compares toil to the stacks you already use, axis by axis. Every tool below is good at what it was built for. The aim is to be concrete about what you gain and what you give up. toil is younger than all of them, and that shows in a few rows.
 
-toil trades a large, mature ecosystem for one owned framework. That framework distributes writes and ships fast, safe defaults for free. Whether the trade fits your project is the question this page answers.
+toil trades a large, mature ecosystem for one owned framework where the fast, secure, global version is the default. You give up SQL, the Node package universe, and a big integration catalog. You gain a stack that is built in and yours, runs near users, ships post-quantum auth and end-to-end types with no setup, and distributes writes worldwide instead of pinning them to one region. Whether that trade fits your project is what this page answers.
 
 ## The comparison table
 
@@ -24,13 +24,13 @@ The top rows lean toil's way. The bottom rows lean the incumbents' way. toil win
 
 ## How toil compares to each stack
 
-**Next.js / Vercel.** Superb React DX and global edge reads. The ceiling is the write path. Pages cache worldwide, but a write still resolves against one primary region. A comment, an order, a flash-sale click all crawl back to that box. Serverless cold starts add latency and per-invocation cost right when a spike hits. toil keeps a React-first client and moves the write to a home region near the data.
+**Next.js / Vercel.** Superb React DX and global edge reads. The backend, though, is still yours to assemble: a database, auth, email, a queue, and a realtime service, each rented and wired up on its own. Serverless cold starts add latency and per-invocation cost right when a spike hits, and writes still resolve against one primary region. toil keeps a React-first client but ships the whole backend built in, running near the data with no cold start.
 
 **Rails / Django.** Mature, productive, and batteries included, with a deep hiring pool. If one region suits you, this is a great and boring choice. The default shape is a single-region monolith with one primary that every write must reach. You can add replicas and standbys to scale, but distributed writes are not in the model.
 
 **Serverless functions (Lambda, Cloud Functions).** Elastic, stateless compute that scales to zero. It still sits in front of a central database, so a write burst bottlenecks on that store. Each cold invocation bills and lags on its own.
 
-**Edge runtimes (Workers, Deno Deploy).** The closest in spirit to toil's compute model: your code runs near users. The catch is the database you attach. It is usually single-region, so edge compute becomes a faster front door to the same central write bottleneck.
+**Edge runtimes (Workers, Deno Deploy).** The closest in spirit to toil's compute model: your code runs near users. The catch is everything you bolt on around it. The database you attach is usually single-region, and auth, email, realtime, and typed client calls are still yours to assemble. toil ships those built in, on a database designed to distribute writes.
 
 Cloudflare Durable Objects and D1 are the closest mainstream analog to toil's idea, and credit is due. A Durable Object gives one object a single-writer home that orders its writes, the same shape as ToilDB's per-key home. The difference is packaging. With the edge-runtime approach you assemble the pieces yourself: runtime, object or database product, auth, email, and realtime. toil ships distributed writes, the seven database families, auth, email, streaming, and background jobs as one owned stack. Which you prefer is a real trade-off.
 

package/docs/introduction/why-toil.md

@@ -2,7 +2,7 @@
 
 toil is a full-stack framework. You write a React frontend and a TypeScript backend in one project, and toil runs both, plus a database, close to every user worldwide.
 
-The thesis is simple. toil is the modern full-stack tooling a developer actually wants: AAA-grade from the first line, and built to scale to the whole planet. Even a simple pizza site gets top-tier infrastructure with zero setup. Distributed writes are one pillar of that. The stack that just works is the core.
+Shipping a fast, secure, global app normally takes a pile of rented services and a team that understands infrastructure. toil gives you that as the default: one framework, zero config, quantum-proof login, built on modern tech, running near your users from day one. The same setup serves a pizza site and a planet-scale app. Distributing writes worldwide is one of the hard things it handles for you, not the reason it exists.
 
 ## The problem with modern stacks
 
@@ -22,9 +22,7 @@ A solo builder and a funded startup hit the same wall. Top-tier infrastructure m
 
 ## What toil delivers
 
-Every design decision in toil serves one goal: AAA-grade infrastructure by default, not something you assemble by hand. One framework instead of ten rented vendors. Zero configuration. No distributed-systems or networking expertise required. It works out of the box, quantum-proof login included.
-
-Four pillars carry it.
+toil was built to reach real scale cheaply, and every design choice serves that. You get top-tier infrastructure by default: one framework instead of ten vendors, zero configuration, and no networking knowledge required. Quantum-proof login is on from the start. Four things make it work.
 
 ### AAA-grade infrastructure by default
 

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.104",
+    "version": "0.0.106",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {

package/server/auth/AuthController.ts

@@ -1188,19 +1188,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 +1260,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 +1277,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/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/src/compiler/auth-emails.ts

@@ -0,0 +1,279 @@
+/**
+ * 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 { fileURLToPath } from 'node:url';
+
+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 toiljs package's `server/globals` LIB directory: the ambient, no-import
+ * surface (`EmailService`, `AuthService`, …) the toilconfig `lib` array points
+ * at. The auth-email module is generated HERE, not in the app's `server/` dir,
+ * because that is what makes `AuthEmail` resolvable from the node_modules-compiled
+ * `AuthController` with NO import (an exported namespace in a plain app entry is
+ * module-scoped, not global). Prefers the app's install so a symlinked/linked
+ * toiljs is followed; falls back to the running package (hoisted install).
+ */
+function globalsDir(root: string): string {
+    const inApp = path.join(root, 'node_modules', 'toiljs', 'server', 'globals');
+    if (fs.existsSync(inApp)) return inApp;
+    const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+    return path.join(pkgDir, 'server', 'globals');
+}
+
+/** 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';
+}
+
+/**
+ * (Re)write `_auth_emails.ts` in the toiljs lib globals 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. A no-op that removes a stale
+ * module when `authOn` is false. Only spins up Vite when an override actually
+ * exists.
+ */
+export async function renderAuthEmails(cfg: ResolvedToilConfig, authOn: boolean): Promise<void> {
+    const generatedPath = path.join(globalsDir(cfg.root), GENERATED_BASENAME);
+
+    if (!authOn) {
+        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 };