toiljs 0.0.44 → 0.0.45

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();
+}

package/src/devserver/email/config.ts

@@ -0,0 +1,123 @@
+/**
+ * Resolve the dev / self-host email config: merge the typed `toil.config.ts`
+ * `email` section (non-secret) with the reserved `TOIL_EMAIL_*` env keys (which
+ * WIN, for edge parity + 12-factor), and pull the API key from
+ * `TOIL_EMAIL_API_KEY` (a secret, only ever in `.env.secrets`/the environment).
+ *
+ * Mirrors the edge's `host/email.rs` (`EmailSection::from_reserved` + `resolve`):
+ * provider parse, `from` validation, Gmail/SMTP defaults. Returns a `null`
+ * config when email is simply not set up (silent), or a `warning` when it is
+ * partially configured but invalid (logged at startup, treated as Disabled).
+ */
+import type { EmailBackendConfig } from 'toiljs/shared';
+
+import { validFrom } from './validate.js';
+
+export type ResolvedProvider = 'resend' | 'smtp';
+
+export interface ResolvedSmtp {
+    readonly host: string;
+    readonly port: number;
+    readonly user: string;
+}
+
+export interface ResolvedEmailConfig {
+    readonly provider: ResolvedProvider;
+    readonly from: string;
+    readonly apiKey: string;
+    readonly maxPerMin: number;
+    readonly maxPerDay: number;
+    readonly maxPerRecipientPerHour: number;
+    /** Present iff `provider === 'smtp'`. */
+    readonly smtp?: ResolvedSmtp;
+}
+
+export interface ResolveResult {
+    /** The resolved config, or `null` when email is unconfigured / invalid. */
+    readonly config: ResolvedEmailConfig | null;
+    /** A reason email is off despite partial config (logged at startup). */
+    readonly warning: string | null;
+}
+
+/** `TOIL_EMAIL_<NAME>` from the reserved map, trimmed; `undefined` if absent/empty. */
+function envOf(reserved: Map<string, string>, name: string): string | undefined {
+    const v = reserved.get(`TOIL_EMAIL_${name}`);
+    const t = v?.trim();
+    return t ? t : undefined;
+}
+
+function parseBool(v: string | undefined): boolean | undefined {
+    if (v === undefined) return undefined;
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+
+function parseInt0(v: string | undefined, fallback: number): number {
+    if (v === undefined) return fallback;
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+export function resolveEmailConfig(
+    cfg: EmailBackendConfig | null | undefined,
+    reserved: Map<string, string>,
+): ResolveResult {
+    const c = cfg ?? {};
+    // Env (TOIL_EMAIL_*) overrides the config file; api key is env-only.
+    const providerId = (envOf(reserved, 'PROVIDER') ?? c.provider ?? 'resend').toLowerCase();
+    const from = envOf(reserved, 'FROM') ?? c.from?.trim();
+    const apiKey = envOf(reserved, 'API_KEY');
+    const enabled = parseBool(envOf(reserved, 'ENABLED'));
+
+    // Unconfigured: explicitly disabled, or no `from` and no key at all -> silent off.
+    if (enabled === false) return { config: null, warning: null };
+    if (from === undefined && apiKey === undefined && cfg == null) {
+        return { config: null, warning: null };
+    }
+
+    if (from === undefined) {
+        return { config: null, warning: 'email config present but `from` is missing' };
+    }
+    if (!validFrom(from)) {
+        return { config: null, warning: 'email `from` is not a valid address (CRLF or no `@`)' };
+    }
+    if (apiKey === undefined) {
+        return {
+            config: null,
+            warning: 'email config present but TOIL_EMAIL_API_KEY is not set (in .env.secrets)',
+        };
+    }
+
+    let provider: ResolvedProvider;
+    let smtp: ResolvedSmtp | undefined;
+    if (providerId === 'resend') {
+        provider = 'resend';
+    } else if (providerId === 'gmail' || providerId === 'smtp') {
+        provider = 'smtp';
+        const isGmail = providerId === 'gmail';
+        const host = envOf(reserved, 'SMTP_HOST') ?? c.smtp?.host?.trim() ?? (isGmail ? 'smtp.gmail.com' : '');
+        if (!host) {
+            return { config: null, warning: 'provider `smtp` requires TOIL_EMAIL_SMTP_HOST' };
+        }
+        const port = parseInt0(envOf(reserved, 'SMTP_PORT'), c.smtp?.port ?? 0) || 587;
+        const user = envOf(reserved, 'SMTP_USER') ?? c.smtp?.user?.trim() ?? from;
+        smtp = { host, port, user };
+    } else {
+        return { config: null, warning: `unknown email provider "${providerId}" (resend|gmail|smtp)` };
+    }
+
+    return {
+        config: {
+            provider,
+            from,
+            apiKey,
+            maxPerMin: parseInt0(envOf(reserved, 'MAX_PER_MIN'), c.maxPerMin ?? 60),
+            maxPerDay: parseInt0(envOf(reserved, 'MAX_PER_DAY'), c.maxPerDay ?? 0),
+            maxPerRecipientPerHour: parseInt0(
+                envOf(reserved, 'MAX_PER_RECIPIENT_PER_HOUR'),
+                c.maxPerRecipientPerHour ?? 5,
+            ),
+            smtp,
+        },
+        warning: null,
+    };
+}

package/src/devserver/email/index.ts

@@ -0,0 +1,111 @@
+/**
+ * The dev / self-host email service — the full edge pipeline in Node, reusable
+ * by the future self-host runtime (this folder has NO Vite/devserver coupling).
+ *
+ * Split for the sync-wasm constraint: `prepare()` is SYNCHRONOUS (parse +
+ * validate + dedup + budget + per-recipient cap) and returns the terminal status
+ * to hand the guest now; `deliver()` is ASYNC (the actual provider send). A
+ * synchronous host (the dev server) fires `deliver()` and returns `Sent`
+ * optimistically; an async-capable host (a future self-host) can `await deliver()`
+ * for the true status.
+ */
+import { loadEnvFiles } from '../dotenv.js';
+import { EmailCaps } from './caps.js';
+import { resolveEmailConfig, type ResolvedEmailConfig } from './config.js';
+import { sendVia, type OutboundMessage } from './providers.js';
+import { EmailStatus } from './status.js';
+import { validRecipient } from './validate.js';
+import { parseEmailBlob, type ParsedEmail } from './wire.js';
+
+import type { EmailBackendConfig } from 'toiljs/shared';
+
+export { EmailStatus } from './status.js';
+export type { ResolvedEmailConfig } from './config.js';
+
+export interface PrepareResult {
+    /** The status to return to the guest now. `Sent` means proceed to `deliver`. */
+    readonly status: EmailStatus;
+    /** The parsed message, present iff `status === Sent` (caller should deliver). */
+    readonly parsed: ParsedEmail | null;
+}
+
+export class NodeEmailService {
+    private readonly caps = new EmailCaps();
+    constructor(private readonly config: ResolvedEmailConfig) {}
+
+    /** The configured provider id (for the startup banner / logs). */
+    get providerLabel(): string {
+        return `${this.config.provider} (${this.config.from})`;
+    }
+
+    /**
+     * Synchronous pre-send: parse the wire blob, validate the recipient, then
+     * dedup + per-minute/day budget + per-recipient cap (all committing). Returns
+     * a terminal status (`BadRecipient` / `Deduped` / `Budget` / `RecipientCapped`),
+     * or `{ status: Sent, parsed }` meaning the caller should `deliver(parsed)`.
+     */
+    prepare(blob: Buffer, now: number = Date.now()): PrepareResult {
+        const parsed = parseEmailBlob(blob);
+        if (parsed === null || !validRecipient(parsed.to)) {
+            return { status: EmailStatus.BadRecipient, parsed: null };
+        }
+        if (this.caps.isDuplicate(parsed.to, parsed.purpose, now)) {
+            return { status: EmailStatus.Deduped, parsed: null };
+        }
+        if (!this.caps.budgetOk(this.config.maxPerMin, this.config.maxPerDay, now)) {
+            return { status: EmailStatus.Budget, parsed: null };
+        }
+        if (!this.caps.recipientOk(parsed.to, this.config.maxPerRecipientPerHour, now)) {
+            return { status: EmailStatus.RecipientCapped, parsed: null };
+        }
+        return { status: EmailStatus.Sent, parsed };
+    }
+
+    /** Actually send via the configured provider; resolves to the real status. */
+    deliver(parsed: ParsedEmail): Promise<EmailStatus> {
+        const msg: OutboundMessage = {
+            from: this.config.from,
+            to: parsed.to,
+            subject: parsed.subject,
+            body: parsed.body,
+            html: parsed.html,
+        };
+        return sendVia(this.config, msg);
+    }
+}
+
+// --- Process-level singleton (one project per dev/self-host process) ----------
+
+let service: NodeEmailService | null = null;
+
+export interface EmailInitResult {
+    /** The service, or `null` when email is unconfigured / invalid. */
+    readonly service: NodeEmailService | null;
+    /** A note for the startup banner: the provider label, or a config warning. */
+    readonly note: string | null;
+}
+
+/**
+ * Build the email service from the `toil.config.ts` `email` section + the
+ * project's `.env.secrets` (`TOIL_EMAIL_*`, holding the API key) and install it
+ * as the process singleton. Call once at startup. Returns a startup note.
+ */
+export function initEmailService(
+    root: string,
+    cfgEmail: EmailBackendConfig | null | undefined,
+): EmailInitResult {
+    const reserved = loadEnvFiles(root).reserved;
+    const { config, warning } = resolveEmailConfig(cfgEmail, reserved);
+    service = config === null ? null : new NodeEmailService(config);
+    return { service, note: service === null ? warning : service.providerLabel };
+}
+
+/** The installed email service, or `null` when email is not configured. */
+export function getEmailService(): NodeEmailService | null {
+    return service;
+}
+
+/** Reset the singleton (tests). */
+export function resetEmailService(): void {
+    service = null;
+}

package/src/devserver/email/providers.ts

@@ -0,0 +1,130 @@
+/**
+ * Provider transports for the dev / self-host mailer, mirroring the edge's
+ * `mailer.rs`: Resend over `fetch` (`send_resend`) and SMTP over nodemailer
+ * (`send_smtp`). Both retry transient failures with capped backoff; a permanent
+ * rejection is terminal (`ProviderError`).
+ *
+ * nodemailer is imported lazily, so a Resend-only project never loads it.
+ */
+import { EmailStatus } from './status.js';
+import type { ResolvedEmailConfig } from './config.js';
+
+const MAX_ATTEMPTS = 3;
+const BACKOFF_BASE_MS = 200;
+const POST_TIMEOUT_MS = 10_000;
+
+/** The concrete parts of one send (already validated + rendered). */
+export interface OutboundMessage {
+    readonly from: string;
+    readonly to: string;
+    readonly subject: string;
+    /** Plain-text body (may be empty when only `html` is set). */
+    readonly body: string;
+    /** Optional HTML body (empty = plain-text send). */
+    readonly html: string;
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Classify an HTTP status (or `null` for a transport failure): 2xx → `Sent`,
+ * 4xx → terminal `ProviderError` (a bad address keeps being bad), else
+ * (5xx / transport) → retry.
+ */
+function classifyHttp(status: number | null): EmailStatus | 'retry' {
+    if (status !== null && status >= 200 && status < 300) return EmailStatus.Sent;
+    if (status !== null && status >= 400 && status < 500) return EmailStatus.ProviderError;
+    return 'retry';
+}
+
+/** Drive one Resend POST with retry. */
+export async function sendResend(
+    cfg: ResolvedEmailConfig,
+    msg: OutboundMessage,
+): Promise<EmailStatus> {
+    const payload: Record<string, unknown> = {
+        from: msg.from,
+        to: [msg.to],
+        subject: msg.subject,
+    };
+    if (msg.body.length > 0) payload.text = msg.body;
+    if (msg.html.length > 0) payload.html = msg.html;
+
+    let backoff = BACKOFF_BASE_MS;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        let status: number | null = null;
+        try {
+            const res = await fetch('https://api.resend.com/emails', {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${cfg.apiKey}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(POST_TIMEOUT_MS),
+            });
+            status = res.status;
+        } catch {
+            status = null; // transport error → retry
+        }
+        const verdict = classifyHttp(status);
+        if (verdict !== 'retry') return verdict;
+        if (attempt === MAX_ATTEMPTS) break;
+        await sleep(backoff);
+        backoff *= 2;
+    }
+    return EmailStatus.ProviderError;
+}
+
+/** Send one email over SMTP (nodemailer) with retry. */
+export async function sendSmtp(
+    cfg: ResolvedEmailConfig,
+    msg: OutboundMessage,
+): Promise<EmailStatus> {
+    const smtp = cfg.smtp;
+    if (smtp === undefined) return EmailStatus.ProviderError; // resolve() guarantees Some for smtp
+
+    let transporter: import('nodemailer').Transporter;
+    try {
+        const nodemailer = await import('nodemailer');
+        transporter = nodemailer.createTransport({
+            host: smtp.host,
+            port: smtp.port,
+            secure: smtp.port === 465, // 465 = implicit TLS; else STARTTLS
+            auth: { user: smtp.user, pass: cfg.apiKey },
+            connectionTimeout: POST_TIMEOUT_MS,
+            greetingTimeout: POST_TIMEOUT_MS,
+        });
+    } catch {
+        // nodemailer not installed: SMTP unavailable.
+        return EmailStatus.ProviderError;
+    }
+
+    let backoff = BACKOFF_BASE_MS;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+            await transporter.sendMail({
+                from: msg.from,
+                to: msg.to,
+                subject: msg.subject,
+                text: msg.body.length > 0 ? msg.body : undefined,
+                html: msg.html.length > 0 ? msg.html : undefined,
+            });
+            return EmailStatus.Sent;
+        } catch (e) {
+            // SMTP 5xx is a PERMANENT failure (bad auth / rejected recipient):
+            // terminal. 4xx / transport errors are transient: retry with backoff.
+            const code = (e as { responseCode?: number }).responseCode;
+            if (typeof code === 'number' && code >= 500) return EmailStatus.ProviderError;
+            if (attempt === MAX_ATTEMPTS) break;
+            await sleep(backoff);
+            backoff *= 2;
+        }
+    }
+    return EmailStatus.ProviderError;
+}
+
+/** Dispatch to the configured provider. */
+export function sendVia(cfg: ResolvedEmailConfig, msg: OutboundMessage): Promise<EmailStatus> {
+    return cfg.provider === 'resend' ? sendResend(cfg, msg) : sendSmtp(cfg, msg);
+}

package/src/devserver/email/status.ts

@@ -0,0 +1,23 @@
+/**
+ * The `i32` status `env::email_send` returns to the guest. Byte-identical to the
+ * edge's `EmailStatus` (toil-backend `host/email.rs`, `#[repr(i32)]`) and the
+ * guest `EmailStatus` enum (`server/globals/email.ts`). `Sent` and `Deduped` are
+ * success; the rest say why it was not delivered and whether a retry could help.
+ */
+export enum EmailStatus {
+    Sent = 0,
+    /** No email config (or not enabled). */
+    Disabled = 1,
+    /** Per-process minute/day budget exhausted. Retriable later. */
+    Budget = 2,
+    /** Per-recipient hourly cap hit. Terminal for this recipient/window. */
+    RecipientCapped = 3,
+    /** An identical recent (recipient, purpose) send was collapsed. Treat as sent. */
+    Deduped = 4,
+    /** Saturated / queue full. Retriable; back off. */
+    TryLater = 5,
+    /** The recipient failed host-side validation (CRLF, multiple addresses, malformed). */
+    BadRecipient = 6,
+    /** The provider rejected the send, or transport failed after retries. Terminal. */
+    ProviderError = 7,
+}

package/src/devserver/email/validate.ts

@@ -0,0 +1,40 @@
+/**
+ * Strict single-recipient check for the guest-supplied `to`, byte-for-byte the
+ * edge's (`host/email.rs::valid_recipient`). Rejects header injection
+ * (CR/LF/NUL), multiple addresses (comma, semicolon, whitespace, angle
+ * brackets, quotes), and the obviously malformed, so a guest can never smuggle a
+ * Bcc or a second envelope recipient into the provider call. Exactly one `@`,
+ * non-empty local part, dotted domain.
+ */
+const FORBIDDEN = new Set(['\r', '\n', '\0', ',', ';', ' ', '\t', '<', '>', '"']);
+
+export function validRecipient(s: string): boolean {
+    if (s.length === 0 || Buffer.byteLength(s, 'utf8') > 320) return false;
+    for (const ch of s) {
+        if (FORBIDDEN.has(ch)) return false;
+    }
+    const parts = s.split('@');
+    if (parts.length !== 2) return false; // not exactly one '@'
+    const [local, domain] = parts;
+    return (
+        local.length > 0 &&
+        domain.includes('.') &&
+        !domain.startsWith('.') &&
+        !domain.endsWith('.')
+    );
+}
+
+/**
+ * Lenient validation of the operator-supplied `from` (`host/email.rs::valid_from`):
+ * trusted config, so the only hard requirement is no header injection; the
+ * provider validates deliverability.
+ */
+export function validFrom(s: string): boolean {
+    return (
+        Buffer.byteLength(s, 'utf8') <= 320 &&
+        s.includes('@') &&
+        !s.includes('\r') &&
+        !s.includes('\n') &&
+        !s.includes('\0')
+    );
+}

package/src/devserver/email/wire.ts

@@ -0,0 +1,55 @@
+/**
+ * Decode the `email_send` request blob the guest writes into wasm memory — the
+ * v2 wire format, byte-for-byte the edge's (`email_send_import.rs::parse_request`
+ * and `server/globals/email.ts`):
+ *
+ *   u16 to_len | u16 subject_len | u16 purpose_len | u32 body_len | u32 html_len
+ *   [to][subject][purpose][body][html]      (14-byte LE header, then UTF-8 payloads)
+ *
+ * `html_len == 0` is a plain-text send. Returns `null` on truncation, a length
+ * that overruns the blob, trailing garbage, or non-UTF-8 — all guest encode bugs
+ * the caller maps to `BadRecipient`.
+ */
+export interface ParsedEmail {
+    readonly to: string;
+    readonly subject: string;
+    readonly purpose: string;
+    readonly body: string;
+    readonly html: string;
+}
+
+const HEADER_LEN = 14;
+
+export function parseEmailBlob(raw: Buffer): ParsedEmail | null {
+    if (raw.length < HEADER_LEN) return null;
+    const toLen = raw.readUInt16LE(0);
+    const subjectLen = raw.readUInt16LE(2);
+    const purposeLen = raw.readUInt16LE(4);
+    const bodyLen = raw.readUInt32LE(6);
+    const htmlLen = raw.readUInt32LE(10);
+
+    const total = toLen + subjectLen + purposeLen + bodyLen + htmlLen;
+    // Exact fit: the five payloads must consume the rest of the blob precisely.
+    if (HEADER_LEN + total !== raw.length) return null;
+
+    let off = HEADER_LEN;
+    const take = (n: number): string | null => {
+        const end = off + n;
+        const slice = raw.subarray(off, end);
+        // Reject invalid UTF-8 (Buffer.toString is lossy, so verify by round-trip).
+        const s = slice.toString('utf8');
+        if (Buffer.byteLength(s, 'utf8') !== n) return null;
+        off = end;
+        return s;
+    };
+
+    const to = take(toLen);
+    const subject = take(subjectLen);
+    const purpose = take(purposeLen);
+    const body = take(bodyLen);
+    const html = take(htmlLen);
+    if (to === null || subject === null || purpose === null || body === null || html === null) {
+        return null;
+    }
+    return { to, subject, purpose, body, html };
+}

package/src/devserver/env.ts

@@ -1,87 +1,30 @@
 /**
  * Dev-only source for `Environment.get` / `getSecure`, mirroring the edge's
- * per-tenant env store. Reads two optional dotenv files at the project root:
+ * per-tenant env store. Reads two optional dotenv files at the project root via
+ * the shared loader (`./dotenv.ts`):
  *
  *   - `.env`          -> plain vars  (`Environment.get`); `process.env` overlays
  *   - `.env.secrets`  -> secrets     (`Environment.getSecure`); keep gitignored
  *
  * DISJOINT like the edge: `get` sees only vars, `getSecure` only secrets, so a
  * secret never comes back through `get`. Framework-reserved `TOIL_*` keys are
- * host-only and stripped from BOTH buckets (a tenant can't read them).
+ * host-only (the email backend config reads them) and never a tenant var/secret.
  *
  * Cached after first read; restart `toiljs dev` to pick up edits. The edge
  * resolves this PER TENANT from `$TOIL_ENV_DIR/<host>.env` + `<host>.env.secrets`
  * (and the edge DB later) through a lazy, bounded cache; dev has a single
  * project, so two files are enough and no eviction is needed.
  */
-import fs from 'node:fs';
-import path from 'node:path';
-
-/** Keys with this prefix are framework-reserved/host-only (never exposed). */
-const RESERVED_PREFIX = 'TOIL_';
-
-interface DevEnv {
-    vars: Map<string, string>;
-    secrets: Map<string, string>;
-}
-
-let cache: DevEnv | null = null;
-
-/** 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();
-}
-
-/** Minimal dotenv parser: `KEY=value`, `#` comments, optional `export`, quotes. */
-function parseDotenv(text: string, into: 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 || key.startsWith(RESERVED_PREFIX)) continue; // reserved/host-only
-        into.set(key, parseValue(line.slice(eq + 1).trim()));
-    }
-}
-
-function readFileInto(file: string, into: Map<string, string>): void {
-    try {
-        parseDotenv(fs.readFileSync(path.join(process.cwd(), file), 'utf8'), into);
-    } catch {
-        /* file absent: skip */
-    }
-}
-
-function load(): DevEnv {
-    if (cache) return cache;
-    const vars = new Map<string, string>();
-    const secrets = new Map<string, string>();
-    // process.env overlays as plain vars (convenient in dev); never as secrets.
-    for (const [k, v] of Object.entries(process.env)) {
-        if (typeof v === 'string' && !k.startsWith(RESERVED_PREFIX)) vars.set(k, v);
-    }
-    readFileInto('.env', vars);
-    readFileInto('.env.secrets', secrets);
-    cache = { vars, secrets };
-    return cache;
-}
+import { loadEnvFiles } from './dotenv.js';
 
 /** A plain var by exact key, or `null`. Reads ONLY the `.env` (vars) bucket. */
 export function devEnvGet(key: string): string | null {
-    const e = load();
-    return e.vars.has(key) ? (e.vars.get(key) as string) : null;
+    const v = loadEnvFiles(process.cwd()).vars.get(key);
+    return v === undefined ? null : v;
 }
 
 /** A secret by exact key, or `null`. Reads ONLY the `.env.secrets` bucket. */
 export function devEnvGetSecure(key: string): string | null {
-    const e = load();
-    return e.secrets.has(key) ? (e.secrets.get(key) as string) : null;
+    const v = loadEnvFiles(process.cwd()).secrets.get(key);
+    return v === undefined ? null : v;
 }