alpha-gate 0.1.0

package/src/deploy/ui-preview.ts

@@ -0,0 +1,112 @@
+import { selectPalette, shouldColor } from "./core/colors";
+import type { ApplyStep, Finding, InspectStep, PreflightItem } from "./core/types";
+import {
+  renderApply,
+  renderFindings,
+  renderHeader,
+  renderInspect,
+  renderManualStep,
+  renderPreflight,
+} from "./core/ui";
+
+// Dev preview of the deploy CLI's UI — `npm run ui:preview` (add FORCE_COLOR=1 to see colors when
+// piped). Renders the scenarios that matter: fresh install, idempotent re-run, and a manual step.
+
+const RES = "alpha-gate-myalpha";
+const palette = selectPalette(shouldColor(process.env, process.stdout.isTTY === true));
+
+const PREFLIGHT: PreflightItem[] = [
+  { name: "node", ok: true, detail: "node 20.11" },
+  { name: "wrangler", ok: true, detail: "wrangler 4.100" },
+  { name: "auth", ok: true, detail: "login jane@acme" },
+];
+
+const INSPECT: InspectStep[] = [
+  { why: "account & login", command: "wrangler whoami" },
+  { why: "database exists?", command: "wrangler d1 list --json" },
+  { why: "bucket exists?", command: `wrangler r2 bucket info ${RES}` },
+  { why: "Access wired?", command: "wrangler secret list -c admin.toml --format json" },
+];
+
+function show(title: string, findings: Finding[], apply: ApplyStep[]): void {
+  console.log(
+    [
+      `\n\n══════════  ${title}  ══════════\n`,
+      renderHeader("myalpha", palette),
+      "",
+      renderPreflight(PREFLIGHT, palette),
+      "",
+      renderInspect(INSPECT, palette),
+      "  ↳ run these 4 read-only checks?  [Y/n]",
+      "",
+      renderFindings(findings, palette),
+      "",
+      renderApply(apply, palette),
+      "  ↳ apply changes?  [y/N]",
+    ].join("\n"),
+  );
+}
+
+show(
+  "FRESH INSTALL",
+  [
+    { label: "database", value: "not found" },
+    { label: "bucket", value: "not found" },
+    { label: "Access", value: "not configured" },
+  ],
+  [
+    { kind: "create", what: "database", why: "", command: `wrangler d1 create ${RES}` },
+    { kind: "create", what: "bucket", why: "", command: `wrangler r2 bucket create ${RES}` },
+    {
+      kind: "create",
+      what: "migrations",
+      why: "",
+      command: "wrangler d1 migrations apply --remote",
+    },
+    {
+      kind: "create",
+      what: "seed config",
+      why: "",
+      command: "wrangler d1 execute (app_name, scheme)",
+    },
+    { kind: "create", what: "deploy app", why: "", command: "wrangler deploy -c app.toml" },
+    { kind: "create", what: "deploy admin", why: "", command: "wrangler deploy -c admin.toml" },
+  ],
+);
+
+show(
+  "RE-RUN (idempotent)",
+  [
+    { label: "database", value: "exists (a1b2…)" },
+    { label: "bucket", value: "exists" },
+    { label: "Access", value: "configured" },
+  ],
+  [
+    { kind: "skip", what: "database", why: "exists — skipping", command: "" },
+    { kind: "skip", what: "bucket", why: "exists — skipping", command: "" },
+    {
+      kind: "update",
+      what: "migrations",
+      why: "",
+      command: "wrangler d1 migrations apply --remote",
+    },
+    { kind: "skip", what: "seed config", why: "not a first init — skipping", command: "" },
+    { kind: "update", what: "deploy app", why: "", command: "wrangler deploy -c app.toml" },
+    { kind: "update", what: "deploy admin", why: "", command: "wrangler deploy -c admin.toml" },
+  ],
+);
+
+console.log(`\n\n══════════  MANUAL STEP (CLI waits for you)  ══════════\n`);
+console.log(
+  renderManualStep(
+    "Enable Cloudflare Access on the admin Worker, then come back:",
+    [
+      "Zero Trust → Access → Applications → Add (Self-hosted)",
+      `Hostname: ${RES}-admin.workers.dev`,
+      "Add a policy allowing your email (one-time PIN)",
+      "Copy the Application Audience (AUD) tag",
+    ],
+    palette,
+  ),
+);
+console.log("  ↳ Press Enter once that's done and you have the AUD …");

package/src/deps.ts

@@ -0,0 +1,41 @@
+import {
+  type AccessVerifier,
+  createAccessVerifier,
+  createCachedJwksFetcher,
+} from "./auth/access-jwt";
+import type { Env } from "./env";
+import { type Clock, emailDate, nowSeconds, systemClock } from "./lib/clock";
+import { type EmailSender, selectEmailSender } from "./services/email";
+
+// The dependency-injection container (the Deps DI rule; see CONTRIBUTING.md). Handlers and services
+// receive `Deps` and never import bindings or seams directly, so tests swap each seam.
+
+// decision 0006 — ONE JWKS cache for the whole isolate (module scope, not per-request), so Access
+// verification reuses fetched keys across requests and only re-fetches on TTL expiry or an unknown kid.
+const cachedFetchJwks = createCachedJwksFetcher({ now: nowSeconds });
+
+export interface Deps {
+  db: D1Database;
+  r2: R2Bucket;
+  clock: Clock;
+  access: AccessVerifier;
+  email: EmailSender;
+  fetch: typeof fetch; // outbound HTTP for the self-update manifest (§22); mocked in tests
+}
+
+/** Production wiring, built once at the worker entry from the runtime env. */
+export function buildDeps(env: Env): Deps {
+  return {
+    db: env.DB,
+    r2: env.BUILDS,
+    clock: systemClock,
+    access: createAccessVerifier({
+      teamDomain: env.ACCESS_TEAM_DOMAIN,
+      aud: env.ACCESS_AUD,
+      fetchJwks: cachedFetchJwks,
+      now: nowSeconds,
+    }),
+    email: selectEmailSender(env, emailDate),
+    fetch: globalThis.fetch,
+  };
+}

package/src/dev/admin-entry.ts

@@ -0,0 +1,104 @@
+import { createAccessVerifier, type Jwk } from "../auth/access-jwt";
+import { buildDeps } from "../deps";
+import type { Env } from "../env";
+import { nowSeconds } from "../lib/clock";
+import { createAdminApp } from "../routes/admin";
+
+// LOCAL-DEV ONLY (§23). A throwaway Worker entrypoint that lets the gated Admin Worker be opened in a
+// browser on localhost WITHOUT Cloudflare Access in front of it. It runs the REAL admin app and the
+// REAL Access verifier (decision 0006) — only the trust anchor is swapped: a throwaway RSA keypair is
+// minted in-process, and a dev-signed assertion is auto-injected on requests that lack the header
+// (a browser cannot send Cf-Access-Jwt-Assertion; the Cloudflare edge normally adds it).
+//
+// SAFETY: this file is NEVER imported by src/worker.ts and NEVER referenced by the deploy template
+// (deploy.sh fixes main=../src/worker.ts), so a normal deploy cannot ship it. As belt-and-suspenders it
+// also refuses to serve unless env.DEV_ADMIN === "1", which only deploy/dev.sh sets. Effect while
+// running: anyone who can reach the local port is admin "dev@local" — localhost only. Never deploy.
+
+const DEV_TEAM_DOMAIN = "dev.localhost.cloudflareaccess.test";
+const DEV_AUD = "alpha-gate-local-dev";
+const DEV_EMAIL = "dev@local";
+const ONE_YEAR_SECONDS = 365 * 24 * 60 * 60;
+
+function b64url(input: string): string {
+  return btoa(input).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function b64urlBytes(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return b64url(binary);
+}
+
+// Mint the dev keypair + a long-lived assertion once per isolate, and build the admin app against a
+// verifier pointed at that key. Memoized so the keygen cost is paid once, not per request.
+let initPromise: Promise<{ app: ReturnType<typeof createAdminApp>; token: string }> | null = null;
+
+function init(): Promise<{ app: ReturnType<typeof createAdminApp>; token: string }> {
+  if (initPromise === null) {
+    initPromise = (async () => {
+      const pair = (await crypto.subtle.generateKey(
+        {
+          name: "RSASSA-PKCS1-v1_5",
+          modulusLength: 2048,
+          publicExponent: new Uint8Array([1, 0, 1]),
+          hash: "SHA-256",
+        },
+        true,
+        ["sign", "verify"],
+      )) as CryptoKeyPair;
+      const jwk = (await crypto.subtle.exportKey("jwk", pair.publicKey)) as Jwk;
+      jwk.kid = "dev-kid";
+      jwk.alg = "RS256";
+      jwk.use = "sig";
+
+      const now = nowSeconds();
+      const header = b64url(JSON.stringify({ alg: "RS256", kid: "dev-kid", typ: "JWT" }));
+      const payload = b64url(
+        JSON.stringify({
+          iss: `https://${DEV_TEAM_DOMAIN}`,
+          aud: DEV_AUD,
+          email: DEV_EMAIL,
+          iat: now,
+          nbf: now - 5,
+          exp: now + ONE_YEAR_SECONDS,
+        }),
+      );
+      const signature = await crypto.subtle.sign(
+        "RSASSA-PKCS1-v1_5",
+        pair.privateKey,
+        new TextEncoder().encode(`${header}.${payload}`),
+      );
+      const token = `${header}.${payload}.${b64urlBytes(new Uint8Array(signature))}`;
+
+      const verifier = createAccessVerifier({
+        teamDomain: DEV_TEAM_DOMAIN,
+        aud: DEV_AUD,
+        fetchJwks: async () => [jwk],
+        now: nowSeconds,
+      });
+      const app = createAdminApp((env) => ({ ...buildDeps(env), access: verifier }));
+      return { app, token };
+    })();
+  }
+  return initPromise;
+}
+
+export default {
+  async fetch(
+    request: Request,
+    env: Env & { DEV_ADMIN?: string },
+    ctx: ExecutionContext,
+  ): Promise<Response> {
+    if (env.DEV_ADMIN !== "1") {
+      return new Response(
+        "Refused: src/dev/admin-entry.ts is a local-dev-only entrypoint (DEV_ADMIN!=1). Never deploy it.",
+        { status: 500 },
+      );
+    }
+    const { app, token } = await init();
+    const headers = new Headers(request.headers);
+    if (!headers.has("Cf-Access-Jwt-Assertion")) headers.set("Cf-Access-Jwt-Assertion", token);
+    return app.fetch(new Request(request, { headers }), env, ctx);
+  },
+};

package/src/env.ts

@@ -0,0 +1,47 @@
+// The typed contract for the §18 wrangler `[vars]` and bindings. Both Workers (app + admin) share
+// this shape, switched at runtime by `ROLE`. Declared on the global `Cloudflare.Env` so the
+// `cloudflare:test` runtime `env` is typed identically to production.
+//
+// `readEnv()` below is the defensive guard: it fails fast on a misconfigured `ROLE`.
+
+export type Role = "app" | "admin";
+export type EmailProvider = "none" | "cloudflare";
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      // Bindings (§18)
+      DB: D1Database;
+      BUILDS: R2Bucket;
+
+      // Vars (§18)
+      INSTANCE: string;
+      ROLE: Role;
+      EMAIL_PROVIDER: EmailProvider;
+      EMAIL_FROM: string;
+      TOOL_VERSION: string;
+      UPDATE_MANIFEST_URL: string;
+
+      // Admin-only, set after Cloudflare Access is enabled (§19). Absent on the app Worker.
+      ACCESS_TEAM_DOMAIN?: string;
+      ACCESS_AUD?: string;
+
+      // Cloudflare Email Service binding (§24). Rendered onto the admin Worker only, and only when
+      // EMAIL_PROVIDER="cloudflare"; absent otherwise (delivery falls back to copy-paste).
+      EMAIL?: SendEmail;
+    }
+  }
+}
+
+export type Env = Cloudflare.Env;
+
+/**
+ * Defensive read of the runtime env: fails fast on a misconfigured Worker (e.g. a ROLE that isn't
+ * "app"/"admin") rather than mis-routing silently. Returns the same object, narrowed.
+ */
+export function readEnv(env: Env): Env {
+  if (env.ROLE !== "app" && env.ROLE !== "admin") {
+    throw new Error(`Invalid ROLE: ${String(env.ROLE)} (expected "app" or "admin")`);
+  }
+  return env;
+}

package/src/lib/clock.ts

@@ -0,0 +1,17 @@
+// The single sanctioned source of wall-clock time. Everything that records or compares time takes a
+// Clock so tests can seed it; no other module may call `new Date()` / `Date.now()` (Biome enforces
+// this — see biome.json). D1's own `datetime('now')` defaults are fine for columns no test asserts on.
+
+export type Clock = () => string; // ISO-8601 UTC, e.g. "2026-06-13T12:00:00.000Z"
+
+export const systemClock: Clock = () => new Date().toISOString();
+
+/** Current Unix time in whole seconds — for JWT exp/nbf checks. The only other sanctioned Date use. */
+export const nowSeconds = (): number => Math.floor(Date.now() / 1000);
+
+/** ISO-8601 UTC for `days` ago — the §16 log-prune cutoff. */
+export const isoDaysAgo = (days: number): string =>
+  new Date(Date.now() - days * 86_400_000).toISOString();
+
+/** RFC 5322 / IMF date for an email `Date:` header (e.g. "Fri, 13 Jun 2026 12:00:00 GMT"). */
+export const emailDate = (): string => new Date().toUTCString();

package/src/lib/hosts.ts

@@ -0,0 +1,27 @@
+// Derive the public App Worker origin from the admin Worker's own URL. deploy.sh names the pair
+// `alpha-gate-<inst>` (app) and `alpha-gate-<inst>-admin` (admin), both on *.workers.dev — so the app
+// origin is the admin origin with the `-admin` name suffix dropped. Returns null when it can't know
+// (a custom admin domain), so callers show a placeholder rather than a wrong URL.
+
+export function adminToAppOrigin(adminUrl: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(adminUrl);
+  } catch {
+    return null;
+  }
+  if (!url.hostname.endsWith(".workers.dev")) return null;
+  const labels = url.hostname.split(".");
+  const first = labels[0];
+  if (first === undefined || !first.endsWith("-admin")) return null;
+  labels[0] = first.slice(0, -"-admin".length);
+  return `${url.protocol}//${labels.join(".")}`;
+}
+
+// The public `/get?token=` invite link a user follows. It must resolve on the *App* host — `/get` only
+// exists there — so derive it from the admin URL. When the app host can't be known (custom domain, local
+// dev), fall back to the admin request origin: no worse than before, and the only option without it.
+export function inviteUrl(adminUrl: string, token: string): string {
+  const origin = adminToAppOrigin(adminUrl) ?? new URL(adminUrl).origin;
+  return `${origin}/get?token=${encodeURIComponent(token)}`;
+}

package/src/lib/text.ts

@@ -0,0 +1,6 @@
+// Small format helpers shared across layers (no bindings, no I/O).
+
+/** Conservative email shape check: a single @, non-empty whitespace-free parts, a dotted domain. */
+export function isEmail(value: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}

package/src/r2/builds-bucket.ts

@@ -0,0 +1,50 @@
+import { archiveKey } from "./keys";
+
+// The single seam over R2 (decision §16): build archives, branding assets, and audit anchors all flow
+// through here. It NEVER produces a presigned URL — everything is read back through the Worker so the
+// /download token gate, logging, and instant revocation always hold.
+
+type PutBody = ReadableStream | ArrayBuffer | ArrayBufferView | string;
+
+/** Stores a build archive and returns the key it was written under. */
+export async function putArchive(
+  r2: R2Bucket,
+  buildNumber: number,
+  filename: string,
+  body: PutBody,
+): Promise<string> {
+  const key = archiveKey(buildNumber, filename);
+  await r2.put(key, body);
+  return key;
+}
+
+/** Reads an object's body for streaming through /download or /assets. */
+export function getObject(r2: R2Bucket, key: string): Promise<R2ObjectBody | null> {
+  return r2.get(key);
+}
+
+/** Delete every object under a build's prefix (the zip and any DMG) — the archive-purge action. */
+export async function deleteArchivePrefix(r2: R2Bucket, prefix: string): Promise<number> {
+  const listed = await r2.list({ prefix });
+  const keys = listed.objects.map((o) => o.key);
+  if (keys.length > 0) await r2.delete(keys);
+  return keys.length;
+}
+
+/** Metadata-only existence/size check (the §20 register path asserts size == declared). */
+export function headObject(r2: R2Bucket, key: string): Promise<R2Object | null> {
+  return r2.head(key);
+}
+
+export async function putBranding(
+  r2: R2Bucket,
+  key: string,
+  body: PutBody,
+  contentType: string,
+): Promise<void> {
+  await r2.put(key, body, { httpMetadata: { contentType } });
+}
+
+export async function putAuditAnchor(r2: R2Bucket, key: string, json: string): Promise<void> {
+  await r2.put(key, json, { httpMetadata: { contentType: "application/json" } });
+}

package/src/r2/keys.ts

@@ -0,0 +1,27 @@
+// The ONLY place R2 object keys are constructed (decision 0003), so the layout is single-sourced and
+// testable. Build archives are append-only (build_number is UNIQUE); DMG + zip for one build coexist
+// under one prefix; branding lives at fixed keys; audit anchors are append-only head objects (§16).
+
+/** Reduce a user-supplied filename to one safe key segment (strips any path, restricts the charset). */
+export function sanitizeFilename(filename: string): string {
+  const base = filename.replace(/^.*[/\\]/, "");
+  const safe = base.replace(/[^A-Za-z0-9._-]/g, "_");
+  return safe.length > 0 ? safe : "artifact";
+}
+
+export function archiveKey(buildNumber: number, filename: string): string {
+  return `build/${buildNumber}/${sanitizeFilename(filename)}`;
+}
+
+/** The prefix holding a build's archive object(s) — the unit the purge action deletes. */
+export function buildPrefix(buildNumber: number): string {
+  return `build/${buildNumber}/`;
+}
+
+export const BRANDING_ICON_KEY = "branding/icon";
+export const BRANDING_HEADER_KEY = "branding/header";
+
+/** One append-only head object per anchoring run (§16). */
+export function auditAnchorKey(iso: string): string {
+  return `audit/anchor/${iso}.json`;
+}

package/src/routes/admin/admin-context.ts

@@ -0,0 +1,9 @@
+import type { Context } from "hono";
+import type { AccessIdentity } from "../../auth/access-jwt";
+import type { Deps } from "../../deps";
+import type { Env } from "../../env";
+
+// The admin-side context: Deps plus the verified actor (set by the auth middleware). Handlers read
+// the actor for authorization decisions and audit attribution — never from a raw header.
+export type AdminEnv = { Bindings: Env; Variables: { deps: Deps; actor: AccessIdentity } };
+export type AdminContext = Context<AdminEnv>;

package/src/routes/admin/audit-fields.ts

@@ -0,0 +1,22 @@
+import type { AuditFields } from "../../core/audit-chain";
+import type { AdminContext } from "./admin-context";
+
+// Builds the audited content of a mutation from the verified actor (never a raw header) plus request
+// metadata. The route layer owns this (it knows the Hono context); services/audit stays Hono-free.
+export function auditFields(
+  c: AdminContext,
+  action: string,
+  target: string | null = null,
+  detail: string | null = null,
+): AuditFields {
+  const actor = c.get("actor");
+  return {
+    actorEmail: actor.kind === "user" ? actor.email : actor.commonName,
+    action,
+    target,
+    detail,
+    ip: c.req.header("cf-connecting-ip") ?? null,
+    rayId: c.req.header("cf-ray") ?? null,
+    createdAt: c.get("deps").clock(),
+  };
+}

package/src/routes/admin/branding.tsx

@@ -0,0 +1,161 @@
+import { isValidAccent } from "../../core/invite-template";
+import * as meta from "../../db/meta";
+import type { Deps } from "../../deps";
+import { putBranding } from "../../r2/builds-bucket";
+import { BRANDING_HEADER_KEY, BRANDING_ICON_KEY } from "../../r2/keys";
+import { recordAudit } from "../../services/audit";
+import { emailStatus } from "../../services/email";
+import { ResultPage } from "../../views/admin/manage-pages";
+import { renderPage } from "../../views/layout";
+import type { AdminContext } from "./admin-context";
+import { auditFields } from "./audit-fields";
+import { doneRedirect } from "./flash";
+import { field, isEmail } from "./form";
+import { requireUser } from "./middleware";
+
+// §13 — download-page branding + invite template. Human-only. Text config goes to `meta`; images go
+// to R2 under the fixed branding keys after a content-type + size check (branding attack surface).
+
+const TEXT_FIELDS = [
+  "app_name",
+  "blurb",
+  "accent",
+  "activate_scheme",
+  "sparkle_public_key",
+  "invite_subject",
+  "invite_body",
+  "notice_title",
+  "notice_message",
+] as const;
+// Raster only — SVG served from the app origin is a stored-XSS vector (scriptable when opened
+// directly at /assets/icon), so it is intentionally excluded.
+const ALLOWED_IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/webp"]);
+const MAX_IMAGE_BYTES = 512 * 1024;
+
+type Body = Record<string, unknown>;
+
+async function saveImage(
+  deps: Deps,
+  body: Body,
+  fileField: string,
+  key: string,
+  metaFlag: string,
+): Promise<string | null> {
+  const file = body[fileField];
+  if (!(file instanceof File)) return null;
+  if (!ALLOWED_IMAGE_TYPES.has(file.type)) return "unsupported image type";
+  if (file.size > MAX_IMAGE_BYTES) return "image too large";
+  await putBranding(deps.r2, key, await file.arrayBuffer(), file.type);
+  await meta.set(deps.db, metaFlag, "1");
+  return null;
+}
+
+export async function saveBranding(c: AdminContext): Promise<Response> {
+  if (requireUser(c) === null) return c.text("Forbidden", 403);
+  const deps = c.get("deps");
+  const body = await c.req.parseBody();
+
+  // accent is interpolated raw into a public <style> — reject anything that isn't a hex colour so it
+  // can never break out of the style block (loadBranding also coerces stored values defensively).
+  const accent = field(body, "accent");
+  if (accent !== null && accent.trim() !== "" && !isValidAccent(accent)) {
+    return c.text("Accent colour must be a hex value like #0A84FF", 400);
+  }
+
+  for (const name of TEXT_FIELDS) {
+    const value = field(body, name);
+    if (value !== null) await meta.set(deps.db, name, value);
+  }
+
+  for (const [fileField, key, flag] of [
+    ["icon", BRANDING_ICON_KEY, "icon"],
+    ["header", BRANDING_HEADER_KEY, "header"],
+  ] as const) {
+    const error = await saveImage(deps, body, fileField, key, flag);
+    if (error !== null) return c.text(error, 400);
+  }
+
+  await recordAudit(deps, auditFields(c, "branding.update"));
+  // Close the feedback loop: land back on Settings with the "Settings saved." flash.
+  return doneRedirect(c, body, "/admin/settings", "settings.saved");
+}
+
+const back = { href: "/admin/settings", label: "← Settings" } as const;
+
+// Send a one-off test email so the admin can debug delivery without creating users. Sends to a given
+// address (defaults to the admin's own), reuses the real send path, and reports the exact outcome —
+// success, or the provider's error (also logged for `wrangler tail`). Reproduces the create-user failure.
+export async function sendTestEmail(c: AdminContext): Promise<Response> {
+  const actor = requireUser(c);
+  if (actor === null) return c.text("Forbidden", 403);
+  const deps = c.get("deps");
+
+  const status = emailStatus(c.env);
+  if (status.mode !== "active") {
+    return c.html(
+      renderPage(
+        <ResultPage title="Email not configured" intent="error" back={back}>
+          <p>
+            Email delivery isn't active ({status.mode}); there's nothing to test. Turn it on first —
+            see <a href="/admin/settings">Settings</a>.
+          </p>
+        </ResultPage>,
+      ),
+      400,
+    );
+  }
+
+  const requested = field(await c.req.parseBody(), "to");
+  const to = requested && requested.trim().length > 0 ? requested.trim() : actor.email;
+  if (!isEmail(to)) {
+    return c.html(
+      renderPage(
+        <ResultPage title="Test email failed" intent="error" back={back}>
+          <p>
+            <code>{to}</code> isn't a valid email address.
+          </p>
+        </ResultPage>,
+      ),
+      400,
+    );
+  }
+
+  try {
+    await deps.email.send({
+      to,
+      subject: "Alpha Gate — test email",
+      body: `This is a test from your Alpha Gate admin (${status.from}). If you received it, invite delivery works.`,
+    });
+    await recordAudit(deps, auditFields(c, "email.test", to));
+    return c.html(
+      renderPage(
+        <ResultPage title="Test email sent" back={back}>
+          <p>
+            Handed to Cloudflare for delivery to <strong>{to}</strong>. Check the inbox (and spam).
+            If it never arrives, the provider accepted it but couldn't deliver — verify the
+            recipient and sending domain in Cloudflare Email Routing.
+          </p>
+        </ResultPage>,
+      ),
+    );
+  } catch (e) {
+    const detail = e instanceof Error ? e.message : String(e);
+    console.error("[email.test] send to", to, "failed:", e); // full error → `wrangler tail`
+    return c.html(
+      renderPage(
+        <ResultPage title="Test email failed" intent="error" back={back}>
+          <p>
+            Sending to <strong>{to}</strong> failed: <code>{detail}</code>
+          </p>
+          <p class="muted">
+            For the full error, run <code>wrangler tail alpha-gate-&lt;instance&gt;-admin</code> and
+            resend. Common causes: the sending domain (<code>{status.from}</code>) isn't fully
+            onboarded for sending in Cloudflare Email Routing (SPF/DKIM/DMARC), or the recipient
+            isn't allowed.
+          </p>
+        </ResultPage>,
+      ),
+      502,
+    );
+  }
+}