toiljs 0.0.43 → 0.0.45

package/docs/email.md

@@ -24,72 +24,106 @@ Everything here is an ambient **global** (no import), like `crypto` and
 
 ## Configure email
 
-Email is configured **per host on the edge** (it is a deployment capability, not
-app code), in that host's TOML config — `hosts/<host>.toml`:
-
-```toml
-[email]
-enabled = true
-from = "you@example.com"          # validated; single address, no CRLF
-provider = "resend"               # "resend" | "gmail" | "smtp"
-secret_ref = "resend_key"         # a FILENAME, never the secret itself
-max_per_min = 60                  # per-tenant send budget
-max_per_recipient_per_hour = 5    # anti-abuse cap per recipient
+Email is a **framework-reserved namespace of the tenant's environment** — the
+same out-of-band [Environment](./environment.md) store that backs
+`Environment.get` / `getSecure`, but the `[email]` block is **host-only**: it is
+read and used in Rust (the off-core mailer) and is **never exposed to the
+`.wasm`**. The provider key never lives in the deployed module or in the
+inotify-watched `hosts/<host>.toml`.
+
+On the edge today it lives in the tenant's env secrets file,
+`$TOIL_ENV_DIR/<host>.env.secrets` (default dir `/run/toil/env`), kept `0600` and
+**out of `hosts/`** so the config watcher never sees a credential (the dashboard /
+edge DB replaces this file later). Email config is a set of **reserved
+`TOIL_EMAIL_*` keys** — host-only, stripped from the guest buckets, so a tenant
+can never read them via `Environment.getSecure`:
+
+```bash
+# $TOIL_ENV_DIR/<host>.env.secrets   (mode 0600; NOT under hosts/, NOT in the .wasm)
+
+TOIL_EMAIL_ENABLED=true
+TOIL_EMAIL_FROM=you@example.com       # validated; single address, no CRLF
+TOIL_EMAIL_PROVIDER=resend            # resend | gmail | smtp
+TOIL_EMAIL_API_KEY=re_xxxxxxxxxxxx    # the provider credential
+TOIL_EMAIL_MAX_PER_MIN=60             # per-host send budget: rolling 1-minute cap
+TOIL_EMAIL_MAX_PER_DAY=0              # per-host send budget: rolling 24-hour cap (0 = unlimited)
+TOIL_EMAIL_MAX_PER_RECIPIENT_PER_HOUR=5   # anti-abuse cap per recipient
 ```
 
+The same file also carries the tenant's own secrets (and `<host>.env` their plain
+vars; see [Environment](./environment.md)); the `TOIL_EMAIL_*` keys are just the
+reserved namespace the framework consumes.
+
 When `enabled` is `false` (the default) the host has no email capability and
-`EmailService.send` returns `Disabled`. If `enabled` is `true` but the config is
-invalid or the secret can't be resolved, the **deploy fails** rather than
-shipping a host that can never send.
+`EmailService.send` returns `Disabled`. The env is loaded **lazily** (on the
+first send) and the `api_key` is materialized into a zeroizing secret in host
+memory — never written to logs or `/_admin`. A malformed `[email]` block is
+treated as "no email" (the host returns `Disabled`); validate config on the
+dashboard before deploying.
 
-### Secrets
+### Providers
 
-`secret_ref` is a **bare filename** (no path separators) under the secrets
-directory `$TOIL_SECRETS_DIR` (default `/run/toil/secrets`). The file holds the
-provider API key (Resend) or SMTP password. It is read once at load, zeroized in
-memory, and never written to the config, logs, or `/_admin`.
+**Resend** (`provider = "resend"`) — a JSON API; `api_key` holds the API key.
 
-```
-/run/toil/secrets/resend_key      # contents: re_xxxxxxxxxxxx…
+**Gmail** (`TOIL_EMAIL_PROVIDER=gmail`) — SMTP with Gmail defaults:
+`smtp.gmail.com`, port `587` (STARTTLS), username = `from`. `TOIL_EMAIL_API_KEY`
+holds a Gmail **App Password** (create one at
+<https://myaccount.google.com/apppasswords>; the account needs 2-Step
+Verification). No extra keys needed:
+
+```bash
+TOIL_EMAIL_ENABLED=true
+TOIL_EMAIL_FROM=you@gmail.com
+TOIL_EMAIL_PROVIDER=gmail
+TOIL_EMAIL_API_KEY=abcd efgh ijkl mnop
 ```
 
-### Providers
+**Generic SMTP** (`TOIL_EMAIL_PROVIDER=smtp`) — any submission server (Outlook,
+SendGrid/Mailgun SMTP, your own). Requires `TOIL_EMAIL_SMTP_HOST`; port defaults
+to `587` (STARTTLS), or set `465` for implicit TLS. `TOIL_EMAIL_SMTP_USER`
+defaults to `from`.
+
+```bash
+TOIL_EMAIL_ENABLED=true
+TOIL_EMAIL_FROM=noreply@example.com
+TOIL_EMAIL_PROVIDER=smtp
+TOIL_EMAIL_API_KEY=the-smtp-password
+TOIL_EMAIL_SMTP_HOST=smtp.example.com
+TOIL_EMAIL_SMTP_PORT=587
+TOIL_EMAIL_SMTP_USER=noreply@example.com
+```
 
-**Resend** (`provider = "resend"`) — a JSON API; `secret_ref` holds the API key.
+### In dev
 
-**Gmail** (`provider = "gmail"`) — SMTP with Gmail defaults: `smtp.gmail.com`,
-port `587` (STARTTLS), username = `from`. `secret_ref` holds a Gmail **App
-Password** (create one at <https://myaccount.google.com/apppasswords>; the
-account needs 2-Step Verification). No extra keys needed:
+`toiljs dev` runs the **full email pipeline** in Node — recipient validation,
+dedup, and the per-minute / per-day / per-recipient caps all behave exactly like
+the edge — and **really sends** once you configure a provider. Configure it in
+`toil.config.ts` (non-secret) with the API key in `.env.secrets`:
 
-```toml
-[email]
-enabled = true
-from = "you@gmail.com"
-provider = "gmail"
-secret_ref = "gmail_app_password"
+```ts
+// toil.config.ts
+import { defineConfig } from 'toiljs/compiler';
+export default defineConfig({
+    server: {
+        email: { provider: 'resend', from: 'you@example.com', maxPerMin: 60 },
+    },
+});
 ```
-
-**Generic SMTP** (`provider = "smtp"`) — any submission server (Outlook,
-SendGrid/Mailgun SMTP, your own). Requires `smtp_host`; port defaults to `587`
-(STARTTLS), or set `465` for implicit TLS. `smtp_user` defaults to `from`.
-
-```toml
-[email]
-enabled = true
-from = "noreply@example.com"
-provider = "smtp"
-secret_ref = "smtp_password"
-smtp_host = "smtp.example.com"
-smtp_port = 587
-smtp_user = "noreply@example.com"
+```bash
+# .env.secrets  (gitignored)
+TOIL_EMAIL_API_KEY=re_xxxxxxxxxxxx
 ```
 
-### In dev
+`TOIL_EMAIL_*` env vars override the config file (so the same `.env.secrets` the
+edge uses works in dev too). Supports `resend` and `gmail`/`smtp` (SMTP via
+nodemailer). **Not configured?** `EmailService.send` stays a log-only mock and
+returns `Sent`, so a flow that sends email still works without setup.
 
-`toiljs dev` has no real provider: `EmailService.send` logs `✉ dev email_send ->
-<recipient> (not actually sent)` and returns `Sent`, so your flow proceeds. The
-ABI is identical to the edge, so code that runs in dev runs on the edge.
+> Because the dev server runs the guest **synchronously**, the actual network
+> send is fire-and-forget: validation + caps return their exact status
+> immediately, but a `Sent` is optimistic and the real delivery outcome (or
+> `ProviderError`) is logged, not returned. The ABI is identical to the edge, so
+> code that runs in dev runs on the edge.
 
 ## Sending email
 
@@ -240,7 +274,7 @@ const ok: bool = TwoFactor.verify(challenge.token, 'alice@example.com', userEnte
   recipient that hasn't expired. Constant-time compare.
 - **`TwoFactor.setSecret(secret)`** — the HMAC secret for the tokens. Call once
   at startup in `main.ts`; it must be identical on every edge instance and out of
-  any client bundle. (This is separate from the provider `secret_ref`.)
+  any client bundle. (This is separate from the provider `api_key`.)
 
 **Limitation:** this gives integrity + expiry but **not single-use** — a valid
 code verifies repeatedly within its TTL, because there is no server state to burn
@@ -252,7 +286,10 @@ last-verified-at and reject at or before it.
 All enforced authoritatively in the single mailer (so the counts are exact across
 all workers):
 
-- **Per-tenant budget** — `max_per_min` (a token bucket). Over it → `Budget`.
+- **Per-host budget** — two rolling windows, both enforced: a 1-minute cap
+  (`max_per_min`) and a 24-hour cap (`max_per_day`, `0` = unlimited). Over either
+  one → `Budget`. Each host's caps, in-window sends, and reject counts are visible
+  per host at `GET /_admin/email`.
 - **Per-recipient cap** — `max_per_recipient_per_hour`. Over it →
   `RecipientCapped`.
 - **Dedup** — identical `(host, recipient, purpose)` within ~30s → `Deduped`.

package/docs/environment.md

@@ -0,0 +1,97 @@
+# Environment variables & secrets
+
+`Environment` gives a tenant **per-app environment variables and secrets**, set
+out of band (a dashboard, like GitHub Actions) so the deployed `.wasm` carries
+**no credentials**. It is read-only from app code — there is no `set`; values are
+configured on the deployment side, never from the module.
+
+```ts
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+@rest('cfg')
+class Cfg {
+    @get('/')
+    show(ctx: RouteContext): Response {
+        const base = Environment.get('PUBLIC_API_BASE'); // plain var, or null
+        const key = Environment.getSecure('STRIPE_KEY'); // secret, or null
+        // Use `key` to call a third party; never log it or return it to a client.
+        return Response.text(base != null ? base : 'unset');
+    }
+}
+```
+
+`Environment` is a global — no import needed (like `EmailService` / `AuthService`).
+
+## Two disjoint buckets
+
+Just like GitHub Actions' `vars` vs `secrets`:
+
+- **`Environment.get(key)`** reads **plain vars** — non-sensitive config (a public
+  API base URL, a feature flag, a region). Returns the string, or `null`.
+- **`Environment.getSecure(key)`** reads **secrets** — sensitive values (a
+  third-party API key). Returns the string, or `null`.
+
+The buckets are **disjoint**: a secret is **never** returned by `get()`, and a
+plain var is never returned by `getSecure()`. That keeps a secret from leaking
+through a code path that logs the result of a `get()`. Keys are case-sensitive,
+exact-match.
+
+> Secrets you read with `getSecure` are plaintext in your module at runtime
+> (that's the point — you need them to call out). Don't log them, don't put them
+> in a response, and don't copy them into a client bundle.
+
+## What is NOT here
+
+Framework-reserved namespaces (today: **email** provider config) are **host-only**
+— resolved and used in Rust where the framework needs them, and **never exposed to
+the `.wasm`**. There is no `Environment.email`; you configure email in the
+`[email]` block of the same env file and the platform uses it for you (see
+[Email](./email.md)). The env imports only ever see your own `vars` / `secrets`.
+
+## Where values live
+
+Vars and secrets live in **two separate dotenv (`.env`) files**, so the disjoint
+split is structural and the secrets file can be locked down on its own. On the
+edge they are per host, **out of `hosts/`** (so the config watcher never sees a
+credential) — the dashboard / edge database replaces them later:
+
+```bash
+# $TOIL_ENV_DIR/<host>.env          (default dir /run/toil/env)
+PUBLIC_API_BASE=https://api.example.com   # -> Environment.get("PUBLIC_API_BASE")
+REGION=eu
+
+# $TOIL_ENV_DIR/<host>.env.secrets  (mode 0600)
+STRIPE_KEY=sk_live_xxx                     # -> Environment.getSecure("STRIPE_KEY")
+
+# host-only email config — reserved TOIL_EMAIL_* keys, NEVER exposed to the .wasm
+TOIL_EMAIL_ENABLED=true
+TOIL_EMAIL_PROVIDER=resend
+TOIL_EMAIL_FROM=noreply@example.com
+TOIL_EMAIL_API_KEY=re_xxx
+```
+
+Each file is plain dotenv: `KEY=value` per line, `#` comments, optional `export`,
+optional quotes. Keys with the reserved **`TOIL_`** prefix are framework/host-only
+and are stripped from BOTH guest buckets — a tenant can never read them via
+`get`/`getSecure` (see [Email](./email.md) for `TOIL_EMAIL_*`).
+
+On the edge, env is loaded **lazily** (the first time your code reads it) into a
+**bounded, shared, read-only cache** with idle eviction: the data lives in one
+place and is never copied per request, a host that never reads env costs nothing,
+secrets are wiped when a host goes cold, and a flood of requests to many distinct
+hosts can never grow memory without bound.
+
+## In dev
+
+`toiljs dev` reads `.env` (vars) and `.env.secrets` (secrets) at your project
+root, and overlays `process.env` as plain vars for convenience. Both are
+gitignored by the scaffold. The ABI is identical to the edge, so code that runs
+in dev runs on the edge.
+
+```bash
+# .env  (vars)
+PUBLIC_API_BASE=http://localhost:4000
+
+# .env.secrets  (secrets; 0600; gitignored)
+STRIPE_KEY=sk_test_xxx
+```

package/examples/basic/server/main.ts

@@ -11,6 +11,7 @@ import './routes/Players';
 import './routes/Leaderboard';
 import './routes/Session';
 import './routes/PqDemo';
+import './routes/EnvDemo';
 import './services/Stats';
 import './services/remotes';
 

package/examples/basic/server/routes/EnvDemo.ts

@@ -0,0 +1,42 @@
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+/**
+ * Environment demo: per-tenant config + secrets, read from server code with no
+ * import (`Environment` is a server global).
+ *
+ * Values come from out-of-band dotenv files the edge loads lazily and never
+ * bundles into the `.wasm`: plain vars from `<host>.env`, secrets from
+ * `<host>.env.secrets`. In `toiljs dev` those are `.env` / `.env.secrets` at the
+ * project root — copy `.env.example` / `.env.secrets.example` to see this populate.
+ *
+ *   Environment.get("KEY")        -> a plain var, or null
+ *   Environment.getSecure("KEY")  -> a secret, or null   (a secret is NEVER
+ *                                    returned by get(), the buckets are disjoint)
+ *
+ * Reserved `TOIL_*` keys (e.g. the `TOIL_EMAIL_*` mailer config) are host-only:
+ * the edge reads them, but they are unreachable through get()/getSecure().
+ */
+@rest('env')
+class EnvDemo {
+    /** GET /env/show -> the public vars, plus WHETHER the demo secret is set.
+     *  We return the secret's presence, not its value: getSecure() hands the guest
+     *  the real secret, but a demo must never echo a secret back over the wire. */
+    @get('/show')
+    public show(_ctx: RouteContext): Response {
+        let greeting = '(unset)';
+        const g = Environment.get('PUBLIC_GREETING');
+        if (g != null) greeting = g;
+
+        let region = '(unset)';
+        const r = Environment.get('REGION');
+        if (r != null) region = r;
+
+        const apiKeySet = Environment.getSecure('DEMO_API_KEY') != null;
+
+        const body =
+            'PUBLIC_GREETING=' + greeting + '\n' +
+            'REGION=' + region + '\n' +
+            'DEMO_API_KEY set=' + (apiKeySet ? 'yes' : 'no') + '\n';
+        return Response.text(body, 200);
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.43",
+    "version": "0.0.45",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -116,8 +116,8 @@
         "setup": "npm i && npm run build"
     },
     "dependencies": {
-        "@btc-vision/post-quantum": "^0.5.3",
         "@dacely/hyper-express": "6.17.4",
+        "@dacely/noble-post-quantum": "^0.6.1",
         "@dacely/toilscript-loader": "^0.1.0",
         "@eslint-react/eslint-plugin": "^5.8.8",
         "@eslint/js": "^10.0.1",
@@ -127,6 +127,7 @@
         "eslint-plugin-react-refresh": "^0.5.2",
         "hash-wasm": "^4.12.0",
         "juice": "^12.1.0",
+        "nodemailer": "^9.0.0",
         "picocolors": "^1.1.1",
         "sharp": "^0.35.0",
         "toilscript": "^0.1.25",
@@ -156,6 +157,7 @@
         "@testing-library/dom": "^10.4.1",
         "@testing-library/react": "^16.3.2",
         "@types/node": "^25.9.1",
+        "@types/nodemailer": "^8.0.1",
         "@types/react": "^19.2.15",
         "@types/react-dom": "^19.2.3",
         "@vitest/coverage-v8": "^4.1.7",

package/server/globals/environment.ts

@@ -0,0 +1,82 @@
+// Environment: the per-tenant environment variables + secrets a tenant
+// configures OUT OF BAND (a dashboard today, backed by a file; the edge DB
+// later) so the deployed `.wasm` carries no credentials — the GitHub-Actions
+// model. Available as a no-import global (the toilscript `--lib` mechanism, like
+// `AuthService` / `EmailService`).
+//
+//   const base = Environment.get("PUBLIC_API_BASE");      // plain var, or null
+//   const key  = Environment.getSecure("STRIPE_KEY");     // secret, or null
+//
+// Two DISJOINT buckets (like GitHub `vars.*` vs `secrets.*`): `get` reads ONLY
+// plain vars, `getSecure` reads ONLY secrets, so a secret can never come back
+// through `get()` (and leak into a log of a `get`). READ-ONLY — there is no
+// `set`; a tenant sets values on their dashboard, never from the `.wasm`.
+//
+// Framework-reserved namespaces (e.g. the email provider config) are HOST-ONLY:
+// they are resolved and consumed in Rust where the framework uses them and are
+// NEVER reachable here — these imports only see the tenant's own vars/secrets.
+//
+// Backed by the `env_get` / `env_get_secure` host imports (toil-backend
+// `env_get_import.rs`, reading the lazy + bounded `env_cache`, plus the toiljs
+// dev-server mock). A tenant that never reads env imports neither, so
+// AssemblyScript tree-shakes this away.
+
+// Host imports: copy one value into `outPtr[0..outCap]`. Return the value's byte
+// length (`0` = present but empty), `-1` if `outCap` is too small (retry with a
+// bigger buffer), `-2` if the key is absent. Resolved from the trusted request
+// host, never anything the guest passes.
+// @ts-ignore: decorator
+@external('env', 'env_get')
+declare function __toilEnvGet(keyPtr: usize, keyLen: i32, outPtr: usize, outCap: i32): i32;
+// @ts-ignore: decorator
+@external('env', 'env_get_secure')
+declare function __toilEnvGetSecure(keyPtr: usize, keyLen: i32, outPtr: usize, outCap: i32): i32;
+
+export namespace Environment {
+    /** The key is absent from the bucket. */
+    const ABSENT: i32 = -2;
+    /** The output buffer was too small; retry with a bigger one. */
+    const TOO_SMALL: i32 = -1;
+    /** First attempt buffer; doubles on `TOO_SMALL`. */
+    const INITIAL_CAP: i32 = 256;
+    /** Upper bound on a value, matching the host's per-value cap. */
+    const MAX_CAP: i32 = 64 * 1024;
+
+    /** Shared reader for both buckets; `secure` picks the secret import. */
+    function read(key: string, secure: bool): string | null {
+        const keyB = Uint8Array.wrap(String.UTF8.encode(key));
+        let cap = INITIAL_CAP;
+        while (cap <= MAX_CAP) {
+            const buf = new Uint8Array(cap);
+            const n = secure
+                ? __toilEnvGetSecure(keyB.dataStart, keyB.length, buf.dataStart, cap)
+                : __toilEnvGet(keyB.dataStart, keyB.length, buf.dataStart, cap);
+            if (n == ABSENT) return null;
+            if (n == TOO_SMALL) {
+                cap = cap * 2;
+                continue;
+            }
+            if (n < 0) return null; // unknown negative: fail closed
+            return String.UTF8.decodeUnsafe(buf.dataStart, n);
+        }
+        return null; // value larger than MAX_CAP: treat as absent
+    }
+
+    /**
+     * The plain environment variable `key` (a tenant var, set on the dashboard),
+     * or `null` if it is not set. NEVER returns a secret — use {@link getSecure}
+     * for those.
+     */
+    export function get(key: string): string | null {
+        return read(key, false);
+    }
+
+    /**
+     * The secret `key` (a tenant secret, set on the dashboard), or `null` if it
+     * is not set. Disjoint from {@link get}: a plain var is never returned here.
+     * The value is sensitive — do not log it.
+     */
+    export function getSecure(key: string): string | null {
+        return read(key, true);
+    }
+}

package/src/cli/create.ts

@@ -165,7 +165,7 @@ function scaffold(
         '.prettierignore':
             'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\n',
         '.gitignore':
-            'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\n',
+            'node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\n# Local dev env vars/secrets (never commit)\n.env\n.env.secrets\n',
         // Use the project's pinned TypeScript (node_modules) instead of VS Code's bundled version.
         '.vscode/settings.json':
             JSON.stringify({ 'typescript.tsdk': 'node_modules/typescript/lib' }, null, 4) + '\n',
@@ -304,6 +304,7 @@ declare class RenderedEmail { subject: string; body: string; html: string; const
 declare class EmailTemplate { constructor(subject: string, body: string, html?: string); render(vars: Map<string, string>): RenderedEmail; send(to: string, vars: Map<string, string>, purpose?: string): EmailStatus; }
 declare enum RateLimit { FixedWindow, SlidingWindow, TokenBucket }
 declare namespace RateLimitService { function guard(routeId: i32, strategy: i32, limit: i32, window: i32): import('toiljs/server/runtime/response').Response | null; function guardKeyed(routeId: i32, strategy: i32, limit: i32, window: i32, key: string): import('toiljs/server/runtime/response').Response | null; }
+declare namespace Environment { function get(key: string): string | null; function getSecure(key: string): string | null; }
 declare class TwoFactorIssue { code: string; token: string; constructor(code: string, token: string); }
 declare class TwoFactorChallenge { token: string; status: EmailStatus; constructor(token: string, status: EmailStatus); }
 declare namespace TwoFactor { const DEFAULT_TTL_SECS: u64; const DEFAULT_DIGITS: i32; function setSecret(secret: Uint8Array): void; function issue(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorIssue; function send(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorChallenge; function verify(token: string, recipient: string, code: string): bool; }

package/src/client/auth.ts

@@ -12,7 +12,7 @@
  */
 
 import { argon2id, sha256 } from 'hash-wasm';
-import { ml_dsa44 } from '@btc-vision/post-quantum/ml-dsa.js';
+import { ml_dsa44 } from '@dacely/noble-post-quantum/ml-dsa.js';
 
 import { DataReader, DataWriter } from 'toiljs/io';
 

package/src/compiler/config.ts

@@ -3,10 +3,12 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { type InlineConfig } from 'vite';
+import { type EmailBackendConfig } from 'toiljs/shared';
 
 import { type SeoConfig } from './seo.js';
 
 export type { SeoConfig } from './seo.js';
+export type { EmailBackendConfig, SmtpBackendConfig } from 'toiljs/shared';
 
 /** Built-in AI providers the dev toolbar can proxy to. */
 export enum AiProvider {
@@ -103,6 +105,15 @@ export interface ServerConfig {
     readonly srcDir?: string;
     /** Server build output directory, relative to root. Default `build/server`. */
     readonly outDir?: string;
+    /**
+     * Email backend config (the dev server and the future Node self-host). The
+     * non-secret pieces — provider, `from`, send caps, SMTP host/port/user. The
+     * API key / SMTP password is a SECRET and lives ONLY in `.env.secrets`
+     * (`TOIL_EMAIL_API_KEY`); any `TOIL_EMAIL_*` env var overrides the matching
+     * field here. The production edge ignores this (it reads `TOIL_EMAIL_*` from
+     * the per-tenant env store); this drives `toiljs dev` / self-host.
+     */
+    readonly email?: EmailBackendConfig;
 }
 
 /**
@@ -144,6 +155,8 @@ export interface ResolvedToilConfig {
     readonly devtoolsAi: DevtoolsAiConfig | null;
     /** Build-time SEO config, or `null` when not configured. */
     readonly seo: SeoConfig | null;
+    /** The `server.email` backend config (dev / self-host), or `null` when unset. */
+    readonly email: EmailBackendConfig | null;
     /** Absolute path to the framework client runtime (`toiljs/client`). */
     readonly runtimePath: string;
     readonly vite: InlineConfig;
@@ -215,6 +228,7 @@ export async function loadConfig(
                 ? (client.devtools.ai ?? null)
                 : null,
         seo: client.seo ?? null,
+        email: user.server?.email ?? null,
         runtimePath: resolveRuntimePath(),
         vite: client.vite ?? {},
     };

package/src/compiler/generate.ts

@@ -117,6 +117,7 @@ export const TOIL_SERVER_ENV_DTS =
     `declare class EmailTemplate { constructor(subject: string, body: string, html?: string); render(vars: Map<string, string>): RenderedEmail; send(to: string, vars: Map<string, string>, purpose?: string): EmailStatus; }\n` +
     `declare enum RateLimit { FixedWindow, SlidingWindow, TokenBucket }\n` +
     `declare namespace RateLimitService { function guard(routeId: i32, strategy: i32, limit: i32, window: i32): import('toiljs/server/runtime/response').Response | null; function guardKeyed(routeId: i32, strategy: i32, limit: i32, window: i32, key: string): import('toiljs/server/runtime/response').Response | null; }\n` +
+    `declare namespace Environment { function get(key: string): string | null; function getSecure(key: string): string | null; }\n` +
     `declare class TwoFactorIssue { code: string; token: string; constructor(code: string, token: string); }\n` +
     `declare class TwoFactorChallenge { token: string; status: EmailStatus; constructor(token: string, status: EmailStatus); }\n` +
     `declare namespace TwoFactor { const DEFAULT_TTL_SECS: u64; const DEFAULT_DIGITS: i32; function setSecret(secret: Uint8Array): void; function issue(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorIssue; function send(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorChallenge; function verify(token: string, recipient: string, code: string): bool; }\n` +

package/src/compiler/index.ts

@@ -310,6 +310,7 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
         port: cfg.port,
         wasmFile: serverWasmFile(cfg.root),
         vite: { host: '127.0.0.1', port: vitePort },
+        email: cfg.email ?? undefined,
     });
     server.httpServer?.once('close', () => {
         void front.close();

package/src/devserver/crypto.ts

@@ -17,7 +17,7 @@
 
 import * as nodeCrypto from 'node:crypto';
 
-import { ml_dsa44 } from '@btc-vision/post-quantum/ml-dsa.js';
+import { ml_dsa44 } from '@dacely/noble-post-quantum/ml-dsa.js';
 
 import type { MemoryRef } from './host.js';
 

package/src/devserver/dotenv.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared dotenv loader for the dev server (and the future Node self-host): reads
+ * a project's `.env` (plain vars) + `.env.secrets` (secrets) and splits out the
+ * framework-reserved `TOIL_*` keys (host-only), mirroring the edge's `env_store`.
+ *
+ * Vite/devserver-free on purpose — both the `Environment.get/getSecure` dev
+ * source (`./env.ts`) and the email backend config (`./email/config.ts`) consume
+ * this one loader, and the self-host will too.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Keys with this prefix are framework-reserved/host-only (never a tenant var/secret). */
+export const RESERVED_PREFIX = 'TOIL_';
+
+export interface LoadedEnv {
+    /** Non-reserved `.env` entries + `process.env` overlay → `Environment.get`. */
+    readonly vars: Map<string, string>;
+    /** Non-reserved `.env.secrets` entries → `Environment.getSecure`. */
+    readonly secrets: Map<string, string>;
+    /** Reserved `TOIL_*` entries from either file (+ `process.env`) → host-only config. */
+    readonly reserved: Map<string, string>;
+}
+
+const cache = new Map<string, LoadedEnv>();
+
+/** Parse one dotenv value: take inside matching quotes, else cut an inline ` #`. */
+function parseValue(rest: string): string {
+    const q = rest[0];
+    if (q === '"' || q === "'") {
+        const end = rest.indexOf(q, 1);
+        return end < 0 ? rest.slice(1) : rest.slice(1, end);
+    }
+    const hash = rest.indexOf(' #');
+    return (hash < 0 ? rest : rest.slice(0, hash)).trimEnd();
+}
+
+/**
+ * Parse dotenv text into `plain` (non-reserved) and `reserved` (`TOIL_*`):
+ * `KEY=value`, `#` comments, optional `export`, optional surrounding quotes.
+ */
+function parseDotenv(text: string, plain: Map<string, string>, reserved: Map<string, string>): void {
+    for (const raw of text.split('\n')) {
+        let line = raw.trim();
+        if (line.length === 0 || line.startsWith('#')) continue;
+        if (line.startsWith('export ')) line = line.slice('export '.length);
+        const eq = line.indexOf('=');
+        if (eq < 0) continue;
+        const key = line.slice(0, eq).trim();
+        if (key.length === 0) continue;
+        const val = parseValue(line.slice(eq + 1).trim());
+        (key.startsWith(RESERVED_PREFIX) ? reserved : plain).set(key, val);
+    }
+}
+
+function readFileInto(file: string, plain: Map<string, string>, reserved: Map<string, string>): void {
+    try {
+        parseDotenv(fs.readFileSync(file, 'utf8'), plain, reserved);
+    } catch {
+        /* file absent: skip */
+    }
+}
+
+/**
+ * Load `<root>/.env` + `<root>/.env.secrets`, cached by resolved root. `process.env`
+ * overlays first (non-reserved → vars, `TOIL_*` → reserved), then the files take
+ * precedence. Secrets come only from `.env.secrets`.
+ */
+export function loadEnvFiles(root: string): LoadedEnv {
+    const key = path.resolve(root);
+    const hit = cache.get(key);
+    if (hit) return hit;
+
+    const vars = new Map<string, string>();
+    const secrets = new Map<string, string>();
+    const reserved = new Map<string, string>();
+
+    // process.env overlay: non-reserved as plain vars, TOIL_* as reserved config.
+    for (const [k, v] of Object.entries(process.env)) {
+        if (typeof v !== 'string') continue;
+        (k.startsWith(RESERVED_PREFIX) ? reserved : vars).set(k, v);
+    }
+    readFileInto(path.join(key, '.env'), vars, reserved);
+    readFileInto(path.join(key, '.env.secrets'), secrets, reserved);
+
+    const out: LoadedEnv = { vars, secrets, reserved };
+    cache.set(key, out);
+    return out;
+}
+
+/** Drop the cache (tests). */
+export function clearEnvCache(): void {
+    cache.clear();
+}