@hogsend/engine 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -13,6 +13,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./worker": "./src/worker.ts",
+    "./auth": "./src/lib/auth.ts",
+    "./create-admin": "./src/lib/create-admin.ts",
     "./package.json": "./package.json"
   },
   "files": [
@@ -38,14 +40,14 @@
     "svix": "^1.95.1",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.10.0",
-    "@hogsend/db": "^0.10.0",
-    "@hogsend/email": "^0.10.0",
-    "@hogsend/plugin-posthog": "^0.10.0",
-    "@hogsend/plugin-resend": "^0.10.0"
+    "@hogsend/core": "^0.12.0",
+    "@hogsend/db": "^0.12.0",
+    "@hogsend/email": "^0.12.0",
+    "@hogsend/plugin-posthog": "^0.12.0",
+    "@hogsend/plugin-resend": "^0.12.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.10.0"
+    "@hogsend/plugin-postmark": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/app.ts

@@ -12,6 +12,7 @@ import type { Auth } from "./lib/auth.js";
 import { mountStudio } from "./lib/studio.js";
 import type { ApiKeyContext } from "./middleware/api-key.js";
 import { errorHandler } from "./middleware/error-handler.js";
+import { clientIpKey, createRateLimit } from "./middleware/rate-limit.js";
 import { requestLogger } from "./middleware/request-logger.js";
 import { registerRoutes } from "./routes/index.js";
 import type { DefinedWebhookSource } from "./webhook-sources/define-webhook-source.js";
@@ -89,21 +90,26 @@ export function createApp(
     return c.json({ error: "Not Found" }, 404);
   });
 
-  // Closed signup: the first user may register (first-load "create admin");
-  // once any user exists, sign-up is blocked. This is the security control that
-  // lets `requireAdmin` trust any authenticated session in a single-tenant app.
+  // Belt-and-suspenders throttle on the sign-up path. Public sign-up is now
+  // CLOSED at the better-auth layer (`disableSignUp: true` in lib/auth.ts ⇒ the
+  // now-ungated POST /api/auth/sign-up/email returns 400
+  // EMAIL_PASSWORD_SIGN_UP_DISABLED), so there is no token to brute-force here.
+  // We KEEP this IP-keyed sliding window anyway: it cheaply drops a flood at the
+  // edge before it reaches better-auth's handler (defence in depth, and it caps
+  // any future credential-probing on this path). Keyed by client IP because
+  // sign-up is unauthenticated — every request would otherwise collapse onto one
+  // "anonymous" bucket. `disableInTest: false` so the suite can still assert the
+  // 429. Distinct prefix → isolated budget.
+  const signUpRateLimit = createRateLimit({
+    prefix: "ratelimit:signup",
+    windowMs: 60_000,
+    max: 10,
+    keyFn: clientIpKey,
+    disableInTest: false,
+  });
   app.use("/api/auth/sign-up/*", async (c, next) => {
-    if (c.req.method === "POST") {
-      const { db } = c.get("container");
-      const existing = await db.select({ id: user.id }).from(user).limit(1);
-      if (existing.length > 0) {
-        return c.json(
-          { error: "Sign-ups are closed. An admin already exists." },
-          403,
-        );
-      }
-    }
-    return next();
+    if (c.req.method !== "POST") return next();
+    return signUpRateLimit(c, next);
   });
 
   app.on(["POST", "GET"], "/api/auth/*", (c) => {
@@ -112,11 +118,16 @@ export function createApp(
   });
 
   // Public bootstrap probe: tells the Studio whether to show the first-run
-  // "create admin" screen (no users yet) instead of the login screen.
+  // "no admin yet" INFO screen (no users yet) instead of the login screen.
+  // Returns ONLY `{ needsSetup }`. Since public sign-up is closed, the Studio's
+  // zero-user state offers NO network path to create a user — the info screen
+  // points the operator at the CLI / env bootstrap instead.
   app.get("/v1/auth/status", async (c) => {
-    const { db } = c.get("container");
+    const container = c.get("container");
+    const { db } = container;
     const existing = await db.select({ id: user.id }).from(user).limit(1);
-    return c.json({ needsSetup: existing.length === 0 });
+    const needsSetup = existing.length === 0;
+    return c.json({ needsSetup });
   });
 
   // Merge env-enabled presets ahead of the consumer's explicit sources so a

package/src/container.ts

@@ -27,6 +27,10 @@ import type { DefinedJourney } from "./journeys/define-journey.js";
 import { buildJourneyRegistry } from "./journeys/registry.js";
 import { setAnalytics } from "./lib/analytics-singleton.js";
 import { type Auth, createAuth } from "./lib/auth.js";
+import {
+  createDomainStatusService,
+  type DomainStatusService,
+} from "./lib/domain-status.js";
 import { setEmailService } from "./lib/email.js";
 import { EmailProviderRegistry } from "./lib/email-provider-registry.js";
 import { emailProvidersFromEnv } from "./lib/email-providers-from-env.js";
@@ -38,6 +42,8 @@ import { hatchet } from "./lib/hatchet.js";
 import { createLogger, type Logger } from "./lib/logger.js";
 import { createTrackedMailer } from "./lib/mailer.js";
 import { getPostHog } from "./lib/posthog.js";
+import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
+import { sendResetPasswordEmail } from "./lib/reset-email.js";
 import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
 import { prepareTrackedHtml } from "./lib/tracking.js";
 import type { DefinedList } from "./lists/define-list.js";
@@ -71,6 +77,14 @@ export interface HogsendClient {
    * defaulting to the env-built Resend provider for byte-for-byte parity.
    */
   emailProvider: EmailProvider;
+  /**
+   * Cached sending-domain status for the ACTIVE provider. Consumed by the
+   * mailer's test-mode check (F3 — sync `testModeCached()` per send), the
+   * `GET/POST /v1/admin/domain` routes, and (via HTTP) the CLI
+   * (`hogsend domain`) + Studio Setup view. In-memory cache only; the per-send
+   * path never awaits a provider call.
+   */
+  domainStatus: DomainStatusService;
   /**
    * The app's template registry (key → component + subject + category +
    * optional preview/examples). Same object threaded into the engine mailer;
@@ -247,26 +261,6 @@ export function createHogsendClient(
   const created = createDatabase({ url: env.DATABASE_URL });
   const db = opts.overrides?.db ?? created.db;
 
-  const auth =
-    opts.overrides?.auth ??
-    createAuth({
-      db,
-      secret: env.BETTER_AUTH_SECRET,
-      baseURL: env.BETTER_AUTH_URL,
-      // Always trust the public API origin; add any explicitly configured ones
-      // (e.g. a remote Studio origin) on top. baseURL is trusted automatically.
-      trustedOrigins: Array.from(
-        new Set(
-          [
-            env.API_PUBLIC_URL,
-            ...(env.BETTER_AUTH_TRUSTED_ORIGINS?.split(",") ?? []),
-          ]
-            .map((o) => o.trim())
-            .filter(Boolean),
-        ),
-      ),
-    });
-
   const registry = buildJourneyRegistry(
     opts.journeys ?? [],
     opts.enabledJourneys ?? env.ENABLED_JOURNEYS,
@@ -363,6 +357,16 @@ export function createHogsendClient(
     );
   }
 
+  // Cached sending-domain status for the active provider. Constructed right
+  // after provider resolution so it binds the SAME provider the mailer sends
+  // through. One non-blocking warm-up refresh primes the cache at boot —
+  // fire-and-forget, swallowed errors, must never block or fail boot. Skipped
+  // under NODE_ENV=test so test runs stay hermetic (no real provider HTTP).
+  const domainStatus = createDomainStatusService({ provider, env, logger });
+  if (env.NODE_ENV !== "test") {
+    domainStatus.refreshIfStale();
+  }
+
   const defaults: HogsendDefaults = {
     timezone: opts.defaults?.timezone ?? "UTC",
     sendWindow: opts.defaults?.sendWindow,
@@ -393,11 +397,71 @@ export function createHogsendClient(
       {
         provider,
         prepareTrackedHtml,
+        // Test-mode redirect: the mailer reads `domainStatus.testModeCached()`
+        // (sync, cache-only) per send to decide whether to redirect to the safe
+        // inbox. Constructed above (right after provider resolution) so it binds
+        // the SAME active provider the mailer sends through.
+        domainStatus,
       },
     );
 
   setEmailService(emailService);
 
+  // Wire better-auth's secondary storage to the SHARED engine Redis (the same
+  // singleton backing the PostHog cache + worker heartbeat — never a second
+  // pool). Passing `secondaryStorage` flips better-auth's rate-limit store from
+  // the per-instance in-memory default to this shared store, so the sign-in /
+  // request-password-reset limiters are enforced ACROSS Railway replicas and
+  // survive restarts (security finding #2).
+  //
+  // Gate on the RAW `process.env.REDIS_URL`, NOT `env.REDIS_URL`: the latter
+  // carries a `redis://localhost:6379` zod default, so it is never empty and
+  // would wire secondary storage unconditionally. When an operator hasn't set
+  // REDIS_URL we deliberately keep better-auth's in-memory store rather than
+  // pushing SESSIONS into a Redis that may not exist — a wired secondaryStorage
+  // degrades `get` to null on a fault, which for sessions means silent
+  // logouts. `getRedis()` is lazyConnect, so this stays synchronous (no
+  // connection until the first auth command); on a transient Redis fault the
+  // adapter degrades to a no-op rather than failing the auth flow.
+  const authSecondaryStorage = process.env.REDIS_URL
+    ? createRedisSecondaryStorage(getRedis())
+    : undefined;
+
+  // Auth is built AFTER the mailer so we can wire the self-service password-reset
+  // delivery to the just-built `emailService` directly (rather than relying on a
+  // singleton resolved at request time). The injected `sendResetPassword` is what
+  // flips better-auth's reset endpoints from disabled → live; the engine-owned,
+  // self-contained reset email needs no consumer template wiring, so reset works
+  // on a bare instance. NEVER log the url/token (see `sendResetPasswordEmail`).
+  const auth =
+    opts.overrides?.auth ??
+    createAuth({
+      db,
+      secret: env.BETTER_AUTH_SECRET,
+      baseURL: env.BETTER_AUTH_URL,
+      secondaryStorage: authSecondaryStorage,
+      // Always trust the public API origin; add any explicitly configured ones
+      // (e.g. a remote Studio origin) on top. baseURL is trusted automatically.
+      trustedOrigins: Array.from(
+        new Set(
+          [
+            env.API_PUBLIC_URL,
+            ...(env.BETTER_AUTH_TRUSTED_ORIGINS?.split(",") ?? []),
+          ]
+            .map((o) => o.trim())
+            .filter(Boolean),
+        ),
+      ),
+      sendResetPassword: async ({ user, url }) => {
+        await sendResetPasswordEmail({
+          to: user.email,
+          url,
+          emailService,
+          logger,
+        });
+      },
+    });
+
   const analytics = opts.analytics ?? getPostHog();
 
   // Expose the resolved analytics instance to the module-level task-execution
@@ -461,6 +525,7 @@ export function createHogsendClient(
     emailService,
     emailProviders,
     emailProvider: provider,
+    domainStatus,
     templates,
     analytics,
     registry,

package/src/env.ts

@@ -23,6 +23,18 @@ export const env = createEnv({
     REDIS_URL: z.string().min(1).default("redis://localhost:6379"),
     BETTER_AUTH_SECRET: z.string().min(1),
     BETTER_AUTH_URL: z.string().url().default("http://localhost:3002"),
+    // --- First-admin bootstrap (replaces the web setup-token land-grab) ---
+    // Public sign-up is DISABLED (lib/auth.ts `disableSignUp`), so admins are
+    // created ONLY by the CLI (`hogsend studio admin create`) or this boot-time
+    // bootstrap. When STUDIO_ADMIN_EMAIL is set AND the user table is empty, the
+    // API process mints this admin on boot (idempotent — only on 0 users).
+    STUDIO_ADMIN_EMAIL: z.string().email().optional(),
+    // Optional password for the bootstrap admin. When set, it is used verbatim
+    // and NEVER logged. When omitted (but STUDIO_ADMIN_EMAIL is set), the engine
+    // auto-generates a strong password and prints it ONCE to the server log
+    // (the single intended secret-logging exception) — rotate it immediately via
+    // the Studio forgot/reset flow. Min length matches better-auth's policy.
+    STUDIO_ADMIN_PASSWORD: z.string().min(8).optional(),
     // Extra origins allowed to call the auth endpoints (beyond BETTER_AUTH_URL),
     // comma-separated. Needed when the Studio is served from a different origin
     // than the API — e.g. the `hogsend studio` CLI pointing at a remote instance.
@@ -41,6 +53,29 @@ export const env = createEnv({
     // `EMAIL_FROM ?? RESEND_FROM_EMAIL`, so an unset EMAIL_FROM keeps today's
     // Resend-named default.
     EMAIL_FROM: z.string().email().optional(),
+    // The sending domain the domain-status service reports on. OVERRIDES the
+    // default derivation (host part of EMAIL_FROM, falling back to the host of
+    // RESEND_FROM_EMAIL) — set it when you send from a subaddress domain that
+    // differs from the one registered at the provider.
+    EMAIL_DOMAIN: z.string().optional(),
+    // --- Test mode (provider-neutral send redirect) ---
+    // Controls whether the engine redirects every send to a safe inbox while the
+    // sending domain isn't verified yet:
+    //   auto  (default) — test mode iff the active provider supports domains AND
+    //                      an EMAIL_DOMAIN is configured AND it is UNVERIFIED per
+    //                      the cached DomainStatusService. Fail-OPEN: a cache miss
+    //                      or provider outage resolves to LIVE (never silently
+    //                      redirects prod mail). With no domains capability or no
+    //                      EMAIL_DOMAIN, `auto` stays LIVE — existing deploys are
+    //                      unaffected.
+    //   true            — always redirect (reason: "env_flag").
+    //   false           — never redirect, even with an unverified domain.
+    HOGSEND_TEST_MODE: z.enum(["auto", "true", "false"]).default("auto"),
+    // The safe inbox every redirected send is delivered to in test mode. Falls
+    // back to STUDIO_ADMIN_EMAIL when unset; when NEITHER resolves while test
+    // mode is active, the send is BLOCKED (recorded, never delivered to the real
+    // recipient) with a loud, actionable log.
+    HOGSEND_TEST_EMAIL: z.string().email().optional(),
     // --- Postmark (opt-in BYO provider) ---
     // Postmark stays OPT-IN: a preset is built only when POSTMARK_SERVER_TOKEN
     // is present, and it NEVER changes the default active provider — set
@@ -48,6 +83,11 @@ export const env = createEnv({
     // authenticity is HTTP Basic creds in the webhook URL — fail-closed when
     // unset (status updates rejected).
     POSTMARK_SERVER_TOKEN: z.string().min(1).optional(),
+    // Postmark ACCOUNT token (X-Postmark-Account-Token) — unlocks the Domains
+    // API capability on the Postmark provider. Optional: without it the
+    // provider still sends, it just can't manage sending domains
+    // (`supported: false` on /v1/admin/domain).
+    POSTMARK_ACCOUNT_TOKEN: z.string().min(1).optional(),
     POSTMARK_MESSAGE_STREAM: z.string().min(1).optional(),
     POSTMARK_WEBHOOK_USER: z.string().min(1).optional(),
     POSTMARK_WEBHOOK_PASS: z.string().min(1).optional(),

package/src/index.ts

@@ -3,9 +3,18 @@
 // Content (journeys, webhook sources, workflows) is injected into these
 // factories by client app code; the engine never imports content.
 
+// Sending-domain capability contract (presence of `EmailProvider.domains` is
+// the gate). Already covered by the `export * from "@hogsend/core"` above —
+// re-named here for discoverability.
 export type {
   BatchEmailItem,
   CaptureOptions,
+  DnsRecord,
+  DnsRecordPurpose,
+  DnsRecordStatus,
+  DomainStatus,
+  DomainsCapability,
+  DomainVerificationState,
   EmailEvent,
   EmailEventType,
   EmailProvider,
@@ -128,7 +137,11 @@ export {
   setJourneyRegistry,
 } from "./journeys/registry-singleton.js";
 // --- Auth ---
-export { type Auth, createAuth } from "./lib/auth.js";
+export {
+  type Auth,
+  createAuth,
+  type SendResetPasswordFn,
+} from "./lib/auth.js";
 // --- Backfill ---
 export {
   type BatchedBackfillOptions,
@@ -143,13 +156,27 @@ export {
   reportWorkerReady,
   type WorkerReadyInfo,
 } from "./lib/boot.js";
+// --- First-admin creation (CLI + boot bootstrap share this scrypt-correct path)
+export { bootstrapAdminFromEnv } from "./lib/bootstrap-admin.js";
 // --- Bucket transition emission (shared by real-time / cron / fast-expiry) ---
 export {
   type BucketTransitionSource,
   emitBucketTransition,
 } from "./lib/bucket-emit.js";
+export {
+  AdminAlreadyExistsError,
+  type CreatedAdmin,
+  createAdminUser,
+} from "./lib/create-admin.js";
 // --- Infrastructure singletons ---
 export { getDb } from "./lib/db.js";
+// --- Sending-domain status service (cached; container-held) ---
+export {
+  createDomainStatusService,
+  type DomainStatusService,
+  type EngineDomainStatus,
+  type TestModeState,
+} from "./lib/domain-status.js";
 // --- Email ---
 export {
   type SendEmailOptions,
@@ -192,7 +219,13 @@ export {
   type OutboundPayloads,
 } from "./lib/outbound.js";
 export { getPostHog } from "./lib/posthog.js";
-export { getRedisIfConnected } from "./lib/redis.js";
+export {
+  type AuthSecondaryStorage,
+  createRedisSecondaryStorage,
+  getRedisIfConnected,
+} from "./lib/redis.js";
+// --- Self-service password reset (engine-owned, self-contained email) ---
+export { sendResetPasswordEmail } from "./lib/reset-email.js";
 export { type MountStudioResult, mountStudio } from "./lib/studio.js";
 export {
   type ResolveTimezoneInput,

package/src/lib/auth.ts

@@ -3,6 +3,25 @@ import * as schema from "@hogsend/db/schema";
 import { betterAuth } from "better-auth";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
 import { organization } from "better-auth/plugins/organization";
+import type { AuthSecondaryStorage } from "./redis.js";
+
+/**
+ * Delivers the password-reset link. Injected by `createHogsendClient` (wired to
+ * the engine mailer) so the auth-construction layer stays decoupled from the
+ * email pipeline, and so tests can pass a spy and assert the callback fires
+ * without sending. Defaults to a no-op so a bare `createAuth({ db, secret,
+ * baseURL })` (e.g. the CLI's headless instance) doesn't try to send mail.
+ *
+ * Receives better-auth's `{ user, url, token }`: `url` is the
+ * `${baseURL}/api/auth/reset-password/:token?callbackURL=…` link that, when
+ * clicked, redirects the browser to the Studio reset route with `?token=`. NEVER
+ * log `url`/`token`.
+ */
+export type SendResetPasswordFn = (args: {
+  user: { email: string; id: string };
+  url: string;
+  token: string;
+}) => Promise<void>;
 
 export function createAuth(opts: {
   db: Database;
@@ -14,21 +33,79 @@ export function createAuth(opts: {
    * than the API (e.g. the `hogsend studio` CLI against a remote instance).
    */
   trustedOrigins?: string[];
+  /**
+   * Self-service password-reset delivery. When provided, better-auth's
+   * `/request-password-reset` + `/reset-password` endpoints are live (without a
+   * `sendResetPassword` callback better-auth hard-errors `RESET_PASSWORD_DISABLED`).
+   * `createHogsendClient` wires this to the engine mailer; omit it (the default)
+   * for a headless instance that should not send mail (the CLI). The reset token
+   * is single-use, short-TTL (15 min), constant-time compared — all better-auth
+   * internals we inherit; we never re-implement them.
+   */
+  sendResetPassword?: SendResetPasswordFn;
+  /**
+   * Shared cross-replica store for better-auth's session AND rate-limit data.
+   * When provided, better-auth resolves `rateLimit.storage` to "secondary-storage"
+   * instead of the in-memory default — so the sign-in / request-password-reset
+   * limiters are enforced GLOBALLY across Railway replicas and survive restarts,
+   * not per-instance (security finding #2). `createHogsendClient` wires this to
+   * the engine's shared Redis when available; omit it (the default) to keep
+   * better-auth's in-memory store on a bare instance with no Redis.
+   */
+  secondaryStorage?: AuthSecondaryStorage;
 }) {
-  const { db, secret, baseURL, trustedOrigins } = opts;
+  const { db, secret, baseURL, trustedOrigins, sendResetPassword } = opts;
   return betterAuth({
     basePath: "/api/auth",
     secret,
     baseURL,
     ...(trustedOrigins && trustedOrigins.length > 0 ? { trustedOrigins } : {}),
+    // Passing `secondaryStorage` flips better-auth's rate-limit storage from the
+    // per-instance in-memory default to this shared store (see option doc).
+    ...(opts.secondaryStorage
+      ? { secondaryStorage: opts.secondaryStorage }
+      : {}),
+    // Tighten the brute-force budget on the credential paths — better-auth's
+    // global default is a coarse 100 req / 10s per IP. Rate limiting is enabled
+    // in production by default; with `secondaryStorage` above these counters are
+    // shared across replicas rather than per-instance.
+    rateLimit: {
+      customRules: {
+        "/sign-in/email": { window: 60, max: 10 },
+        "/request-password-reset": { window: 60, max: 5 },
+      },
+    },
     database: drizzleAdapter(db, {
       provider: "pg",
       schema,
     }),
     emailAndPassword: {
       enabled: true,
+      // 🔒 Public sign-up is closed: there is NO unauthenticated network path
+      // that creates a user. In better-auth 1.6.11 this guard lives INSIDE the
+      // sign-up endpoint handler, so it blocks BOTH POST /api/auth/sign-up/email
+      // (→ 400 EMAIL_PASSWORD_SIGN_UP_DISABLED) AND the in-process
+      // `auth.api.signUpEmail`. Admins are minted only by the CLI (DB-direct)
+      // and the boot env bootstrap, both via the internal adapter. Login + the
+      // self-service forgot/reset endpoints are untouched (disableSignUp only
+      // gates sign-up).
+      disableSignUp: true,
       minPasswordLength: 8,
       maxPasswordLength: 128,
+      // Self-service reset is enabled ONLY when a sender is injected (otherwise
+      // the endpoints stay disabled rather than 500 on a missing callback).
+      ...(sendResetPassword
+        ? {
+            // Short TTL (overrides better-auth's 3600s default). The token is
+            // also single-use (deleted on consume) and constant-time compared —
+            // better-auth internals we inherit.
+            resetPasswordTokenExpiresIn: 60 * 15,
+            // A reset kills existing sessions, so a recovered account can't be
+            // ridden by a stale/leaked session.
+            revokeSessionsOnPasswordReset: true,
+            sendResetPassword,
+          }
+        : {}),
     },
     session: {
       expiresIn: 60 * 60 * 24 * 7,

package/src/lib/boot.ts

@@ -81,6 +81,12 @@ export function reportApiReady(info: ApiReadyInfo): void {
   const templates = Object.keys(client.templates).length;
   const localUrl = `http://localhost:${port}`;
 
+  // Cache-only, sync, never throws — so reading it here adds no boot latency.
+  // Loud when env-flag-forced (resolves even with a cold cache); the
+  // domain-unverified auto banner is additionally fired as a transition WARN by
+  // the warm-up refresh in the container.
+  const testMode = client.domainStatus.testModeCached();
+
   if (!bannerMode(client)) {
     client.logger.info("Hogsend API ready", {
       engineVersion,
@@ -91,6 +97,14 @@ export function reportApiReady(info: ApiReadyInfo): void {
       buckets,
       templates,
       schema: info.schemaVersion ?? undefined,
+      ...(testMode.active
+        ? {
+            testMode: {
+              redirectTo: testMode.redirectTo,
+              reason: testMode.reason,
+            },
+          }
+        : {}),
     });
     return;
   }
@@ -104,6 +118,13 @@ export function reportApiReady(info: ApiReadyInfo): void {
   ].join(dim(" · "));
   const label = (text: string) => dim(text.padEnd(7));
 
+  const testModeLine = testMode.active
+    ? `  ${color.bgYellow(color.black(" TEST MODE "))} ${color.yellow(
+        `all sends → ${testMode.redirectTo ?? "(no redirect address — sends will fail!)"} ` +
+          dim(`(${testMode.reason ?? "unknown"})`),
+      )}`
+    : null;
+
   writeBanner([
     `${BADGE} ${dim(`engine ${engineVersion} · api ${API_VERSION}`)}`,
     "",
@@ -111,6 +132,7 @@ export function reportApiReady(info: ApiReadyInfo): void {
     info.schemaVersion
       ? `  ${ok} schema in sync ${dim(`(${info.schemaVersion})`)}`
       : null,
+    testModeLine,
     "",
     `  ${label("API")}${color.cyan(localUrl)}`,
     `  ${label("Docs")}${color.cyan(`${localUrl}/docs`)}`,

package/src/lib/bootstrap-admin.ts

@@ -0,0 +1,90 @@
+import { randomBytes } from "node:crypto";
+import { user } from "@hogsend/db";
+import type { HogsendClient } from "../container.js";
+import { AdminAlreadyExistsError, createAdminUser } from "./create-admin.js";
+
+/**
+ * Boot-time first-admin bootstrap. Replaces the old web setup-token land-grab:
+ * with public sign-up disabled (lib/auth.ts `disableSignUp`), admins are minted
+ * ONLY by the CLI (DB-direct) or this in-process boot path — there is NO
+ * unauthenticated network path that creates a user.
+ *
+ * Contract (all conditions must hold to mint):
+ *  - `STUDIO_ADMIN_EMAIL` is set (unset ⇒ no-op; CLI is then the only path).
+ *  - The `user` table has ZERO rows (idempotent: never mints over an existing
+ *    user, never rotates/re-prints anything once an admin exists).
+ *
+ * Password resolution:
+ *  - `STUDIO_ADMIN_PASSWORD` if set (NEVER logged).
+ *  - else an auto-generated strong password (base64url, >=16 chars) PRINTED
+ *    ONCE to the server log — the single intended secret-logging exception,
+ *    clearly labelled "shown once". The operator should rotate it immediately
+ *    via the self-service forgot/reset flow (retained, revokes sessions).
+ *
+ * Concurrency: two API replicas booting on a fresh DB could both pass the
+ * 0-rows check; the `user.email` unique constraint makes the loser's
+ * `createUser` throw — caught here and treated as "already created" (no-op, no
+ * log of the loser's generated password). Invariant preserved: exactly one
+ * admin, no unauthenticated path.
+ *
+ * Never blocks boot beyond a clear fatal when an explicitly-set password is too
+ * weak — that validation lives in env.ts (`STUDIO_ADMIN_PASSWORD.min(8)`), so
+ * by the time we run the password is already known-valid or auto-generated.
+ */
+export async function bootstrapAdminFromEnv(opts: {
+  client: HogsendClient;
+}): Promise<void> {
+  const { db, auth, env, logger } = opts.client;
+
+  const email = env.STUDIO_ADMIN_EMAIL;
+  if (!email) return;
+
+  // Idempotency gate: only mint into a fresh DB (zero users). Reuses the same
+  // zero-check the old /v1/auth/status used.
+  const existing = await db.select({ id: user.id }).from(user).limit(1);
+  if (existing.length > 0) return;
+
+  // Auto-generate when no explicit password: base64url(18 bytes) ⇒ 24 chars,
+  // ~144 bits of entropy. We only log the generated value, never an env one.
+  const explicit = env.STUDIO_ADMIN_PASSWORD;
+  const password = explicit ?? randomBytes(18).toString("base64url");
+
+  try {
+    const admin = await createAdminUser({ auth, email, password });
+
+    if (!explicit) {
+      // The ONE intended secret-logging exception (auto-generated only). Shown
+      // once — never re-printed (we only reach here on a zero-user DB).
+      logger.warn(
+        `[studio] First admin created: ${admin.email}. ` +
+          `Generated password (save this, shown once): ${password}`,
+      );
+      logger.warn(
+        "[studio] Rotate it now via the Studio forgot-password flow " +
+          "(or set STUDIO_ADMIN_PASSWORD).",
+      );
+    } else {
+      logger.info(`[studio] First admin created from env: ${admin.email}.`);
+    }
+  } catch (err) {
+    if (err instanceof AdminAlreadyExistsError) {
+      // A concurrent replica won the race (or the user appeared between the
+      // zero-check and the insert). No-op — never log the generated password.
+      logger.debug(
+        "[studio] First-admin bootstrap skipped: an admin already exists.",
+      );
+      return;
+    }
+    // A unique-violation surfaced by the adapter (not our pre-check) is the same
+    // race; treat any duplicate-key error as "already created". Anything else is
+    // unexpected — surface it without leaking the password.
+    const message = err instanceof Error ? err.message : String(err);
+    if (/duplicate key|unique constraint|already exists/i.test(message)) {
+      logger.debug(
+        "[studio] First-admin bootstrap lost a creation race; skipping.",
+      );
+      return;
+    }
+    logger.error("[studio] First-admin bootstrap failed.", { error: message });
+  }
+}