@hogsend/engine 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.10.0",
+  "version": "0.11.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.11.0",
+    "@hogsend/db": "^0.11.0",
+    "@hogsend/email": "^0.11.0",
+    "@hogsend/plugin-posthog": "^0.11.0",
+    "@hogsend/plugin-resend": "^0.11.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.10.0"
+    "@hogsend/plugin-postmark": "^0.11.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

@@ -38,6 +38,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";
@@ -247,26 +249,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,
@@ -398,6 +380,61 @@ export function createHogsendClient(
 
   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

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.

package/src/index.ts

@@ -128,7 +128,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,11 +147,18 @@ 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";
 // --- Email ---
@@ -192,7 +203,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/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 });
+  }
+}

package/src/lib/create-admin.ts

@@ -0,0 +1,104 @@
+import type { Auth } from "./auth.js";
+
+/**
+ * Shared admin-minting primitive used by BOTH the CLI's `admin create` and the
+ * engine's env bootstrap. Mints a credential admin via better-auth's
+ * INTERNAL ADAPTER (scrypt-identical to the running app) rather than the public
+ * sign-up endpoint — which is now blocked by `disableSignUp` (see lib/auth.ts).
+ *
+ * Why the internal adapter (not `auth.api.signUpEmail`): in better-auth 1.6.11
+ * the `disableSignUp` check lives INSIDE the sign-up endpoint handler, and
+ * `auth.api.signUpEmail` dispatches through that SAME handler — so with sign-up
+ * disabled it throws `EMAIL_PASSWORD_SIGN_UP_DISABLED` for the in-process API
+ * too. The internal adapter is NOT subject to that guard. This mirrors exactly
+ * what admin-recovery's `reset()` already does for its no-credential branch
+ * (`ctx.password.hash` + `ctx.internalAdapter.createAccount({ providerId:
+ * "credential" })`).
+ *
+ * Security invariants (acceptance gates, not preferences):
+ *  - The password is hashed via `ctx.password.hash` (scrypt, identical to the
+ *    app). There is NO raw SQL password write.
+ *  - The password is never logged and never returned in any result object.
+ *  - `emailVerified: true` because this is an operator-minted admin (CLI or
+ *    boot env), not a self-service signup.
+ *
+ * Lives in `lib/` (reachable via the `@hogsend/engine/create-admin` subpath)
+ * with a module graph that touches ONLY better-auth — it never pulls `env.ts`,
+ * Hatchet, or Resend — so the CLI can import it the same way it imports
+ * `createAuth` from `@hogsend/engine/auth`.
+ */
+
+/** A single admin row, no secrets. Shared with the CLI's `AdminSummary`. */
+export interface CreatedAdmin {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: string;
+}
+
+/** Thrown when an admin with the given email already exists. */
+export class AdminAlreadyExistsError extends Error {
+  constructor(public readonly email: string) {
+    super(
+      `An admin with email "${email}" already exists. ` +
+        "Use `hogsend studio admin reset` to set a new password.",
+    );
+    this.name = "AdminAlreadyExistsError";
+  }
+}
+
+/**
+ * Create a credential admin user against a built better-auth instance. Throws
+ * {@link AdminAlreadyExistsError} if the email already exists (so callers can
+ * point the operator at `reset`). The unique constraint on `user.email` is the
+ * backstop: a concurrent racer that slips past the pre-check throws on
+ * `createUser` — callers that need idempotency should catch that.
+ */
+export async function createAdminUser(opts: {
+  auth: Auth;
+  email: string;
+  name?: string;
+  password: string;
+}): Promise<CreatedAdmin> {
+  const { auth, email, password } = opts;
+  const displayName = opts.name ?? email.split("@")[0] ?? email;
+
+  const ctx = await auth.$context;
+
+  // Pre-check for a clear error (better-auth lowercases on lookup + create).
+  const existing = await ctx.internalAdapter.findUserByEmail(email);
+  if (existing) {
+    throw new AdminAlreadyExistsError(email);
+  }
+
+  // scrypt hash — identical to the running app (admin-recovery.reset uses the
+  // same call). NO raw SQL password write.
+  const hashed = await ctx.password.hash(password);
+
+  // `createUser` returns the bare user row (createWithHooks → the created user),
+  // NOT `{ user }` — verified against better-auth@1.6.11 internal-adapter.mjs:75.
+  const created = await ctx.internalAdapter.createUser({
+    email,
+    name: displayName,
+    emailVerified: true,
+  });
+
+  await ctx.internalAdapter.createAccount({
+    userId: created.id,
+    providerId: "credential",
+    accountId: created.id,
+    password: hashed,
+  });
+
+  const createdAt =
+    created.createdAt instanceof Date
+      ? created.createdAt.toISOString()
+      : String(created.createdAt ?? new Date().toISOString());
+
+  return {
+    id: created.id,
+    email: created.email,
+    name: created.name,
+    createdAt,
+  };
+}

package/src/lib/redis.ts

@@ -28,3 +28,71 @@ export function getRedis(): Redis {
 export function getRedisIfConnected(): Redis | undefined {
   return _redis;
 }
+
+/**
+ * Namespace for better-auth's secondary-storage keys so they never collide with
+ * the PostHog person-property cache or the worker heartbeat sharing this Redis.
+ */
+const AUTH_STORAGE_PREFIX = "hogsend:auth:";
+
+/**
+ * The minimal shape better-auth's `secondaryStorage` option expects. Mirrors
+ * `@better-auth/core`'s `SecondaryStorage` so we don't pull a type out of a deep
+ * subpath: `get` returns the raw stored string (better-auth `JSON.parse`s it),
+ * `set` takes an optional TTL in SECONDS, `delete` removes the key.
+ */
+export interface AuthSecondaryStorage {
+  get: (key: string) => Promise<string | null>;
+  set: (key: string, value: string, ttl?: number) => Promise<void>;
+  delete: (key: string) => Promise<void>;
+}
+
+/**
+ * Adapt an ioredis client to better-auth's `secondaryStorage` contract so all
+ * better-auth session AND rate-limit counters live in Redis — shared across
+ * Railway replicas and surviving restarts. Without this, better-auth defaults
+ * `rateLimit.storage` to in-memory (per-instance, reset on redeploy), so the
+ * sign-in / request-password-reset limits are materially weaker than they look
+ * on a multi-replica deploy (security finding #2).
+ *
+ * Reuses the SHARED engine Redis singleton ({@link getRedis}) — it never opens a
+ * second pool. better-auth gives `set` a TTL in SECONDS, which we honour with
+ * `EX`; entries with no TTL persist (matching better-auth's own behaviour).
+ *
+ * Every operation is wrapped so a Redis blip degrades gracefully instead of
+ * crashing the auth flow: `get` returns `null` (better-auth treats it as a
+ * miss), `set`/`delete` no-op. We never want a transient cache fault to take
+ * down sign-in.
+ */
+export function createRedisSecondaryStorage(
+  redis: Redis,
+): AuthSecondaryStorage {
+  const k = (key: string) => `${AUTH_STORAGE_PREFIX}${key}`;
+  return {
+    async get(key) {
+      try {
+        return await redis.get(k(key));
+      } catch {
+        return null;
+      }
+    },
+    async set(key, value, ttl) {
+      try {
+        if (typeof ttl === "number" && ttl > 0) {
+          await redis.set(k(key), value, "EX", ttl);
+        } else {
+          await redis.set(k(key), value);
+        }
+      } catch {
+        // Degrade to no-op — never fail the auth flow on a cache write.
+      }
+    },
+    async delete(key) {
+      try {
+        await redis.del(k(key));
+      } catch {
+        // Degrade to no-op.
+      }
+    },
+  };
+}

package/src/lib/reset-email.ts

@@ -0,0 +1,139 @@
+import { getEmailService } from "./email.js";
+import type { EmailService } from "./email-service-types.js";
+import { createLogger, type Logger } from "./logger.js";
+
+// Fallback logger for the no-provider warning — callers may not pass one. Mirrors
+// the engine-lib singleton pattern (mailer, define-journey, tracked).
+const fallbackLogger = createLogger(process.env.LOG_LEVEL);
+
+/**
+ * The TTL the reset link advertises in its copy. Mirrors the
+ * `resetPasswordTokenExpiresIn` we configure in `createAuth` (15 minutes) so the
+ * email never claims a window that doesn't match the server's enforcement.
+ */
+const RESET_TTL_MINUTES = 15;
+
+/**
+ * The engine-owned, self-contained password-reset email. The engine ships NO
+ * business templates (those live in the consumer's `src/emails/`), so a reset
+ * email that required a consumer template would break the "works out of the box"
+ * guarantee. This builds a tiny inline HTML + plaintext body — no React Email
+ * dependency, no template-registry lookup — and sends it through the resolved
+ * provider via the mailer's RAW path.
+ *
+ * `sendRaw` is correct here (not `send`): a password reset is strictly
+ * transactional and must bypass template resolution AND the
+ * preference/suppression check — a recovering operator must always receive it,
+ * marketing opt-out or not. There is no tracking pixel and no unsubscribe footer
+ * for the same reason.
+ *
+ * Security:
+ * - NEVER logs the `url` or the token. On a delivery failure we log a generic
+ *   warning (pointing the operator at the CLI) and RESOLVE without throwing, so
+ *   better-auth's neutral "if this email exists…" response is preserved (no user
+ *   enumeration, no leak of whether the address was real).
+ * - The `from` resolves from `EMAIL_FROM ?? RESEND_FROM_EMAIL` — but we don't
+ *   pass it explicitly: the mailer's `sendRaw` defaults `from` to its configured
+ *   `defaultFrom`, which is exactly that pair.
+ */
+export async function sendResetPasswordEmail(opts: {
+  to: string;
+  url: string;
+  /**
+   * The mailer to send through. Optional: defaults to the container-installed
+   * singleton (`getEmailService()`). Injectable so tests can pass a spy and
+   * assert the send fires without touching a real provider.
+   */
+  emailService?: EmailService;
+  /** Optional structured logger; defaults to a stdout logger. */
+  logger?: Logger;
+}): Promise<void> {
+  const { to, url } = opts;
+  const log = opts.logger ?? fallbackLogger;
+
+  let service: EmailService;
+  try {
+    service = opts.emailService ?? getEmailService();
+  } catch {
+    // The mailer singleton hasn't been installed (container never booted). Steer
+    // the operator to the guaranteed recovery path; never throw (preserves the
+    // neutral response). Do NOT log the url/token.
+    log.warn(
+      "password reset requested but no email service is configured — use `hogsend studio admin reset`",
+    );
+    return;
+  }
+
+  const subject = "Reset your Hogsend Studio password";
+  const html = buildResetHtml(url);
+  const text = buildResetText(url);
+
+  try {
+    await service.sendRaw({ to, subject, html, text });
+  } catch (error) {
+    // A provider error (missing/invalid key, network) must not surface to the
+    // caller — better-auth's neutral response stays intact. Log a generic
+    // warning that points at the CLI fallback. NEVER include the url/token.
+    log.warn(
+      "password reset email failed to send (no usable email provider?) — use `hogsend studio admin reset`",
+      { error: error instanceof Error ? error.message : String(error) },
+    );
+  }
+}
+
+/** Minimal, dependency-free HTML body. The URL appears as a button and a raw
+ * link (so it works even when buttons are stripped). No tracking, no footer. */
+function buildResetHtml(url: string): string {
+  const safeUrl = escapeHtmlAttr(url);
+  const safeText = escapeHtml(url);
+  return `<!doctype html>
+<html lang="en">
+  <body style="margin:0;padding:24px;background:#f4f4f5;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#18181b;">
+    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:480px;margin:0 auto;background:#ffffff;border-radius:8px;padding:32px;">
+      <tr><td>
+        <h1 style="margin:0 0 16px;font-size:20px;font-weight:600;">Reset your password</h1>
+        <p style="margin:0 0 24px;font-size:14px;line-height:1.6;color:#3f3f46;">
+          We received a request to reset your Hogsend Studio password. Click the
+          button below to choose a new one.
+        </p>
+        <p style="margin:0 0 24px;">
+          <a href="${safeUrl}" style="display:inline-block;background:#18181b;color:#ffffff;text-decoration:none;font-size:14px;font-weight:600;padding:12px 20px;border-radius:6px;">Reset password</a>
+        </p>
+        <p style="margin:0 0 16px;font-size:13px;line-height:1.6;color:#71717a;">
+          Or paste this link into your browser:<br />
+          <a href="${safeUrl}" style="color:#2563eb;word-break:break-all;">${safeText}</a>
+        </p>
+        <p style="margin:0;font-size:12px;line-height:1.6;color:#a1a1aa;">
+          This link expires in ${RESET_TTL_MINUTES} minutes and can be used once.
+          If you didn't request a password reset, you can safely ignore this email.
+        </p>
+      </td></tr>
+    </table>
+  </body>
+</html>`;
+}
+
+/** Plain-text alternative (same content, no markup). */
+function buildResetText(url: string): string {
+  return [
+    "Reset your password",
+    "",
+    "We received a request to reset your Hogsend Studio password.",
+    "Open this link to choose a new one:",
+    "",
+    url,
+    "",
+    `This link expires in ${RESET_TTL_MINUTES} minutes and can be used once.`,
+    "If you didn't request a password reset, you can safely ignore this email.",
+  ].join("\n");
+}
+
+/** Escape for an HTML text node. */
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Escape for a double-quoted HTML attribute (e.g. an `href`). */
+function escapeHtmlAttr(s: string): string {
+  return escapeHtml(s).replace(/"/g, "&quot;");
+}

package/src/middleware/rate-limit.ts

@@ -1,3 +1,4 @@
+import type { Context } from "hono";
 import { createMiddleware } from "hono/factory";
 import type { AppEnv } from "../app.js";
 import { getRedis } from "../lib/redis.js";
@@ -11,6 +12,38 @@ export interface RateLimitOptions {
   windowMs?: number;
   max?: number;
   prefix?: string;
+  /**
+   * Derive the per-request bucket key. Default keys on the resolved api-key /
+   * user id (falling back to "anonymous") — correct for the authenticated data
+   * plane. Pass `clientIpKey` for UNAUTHENTICATED surfaces (e.g. the first-admin
+   * sign-up gate) where every request would otherwise collapse onto the single
+   * "anonymous" bucket and let one attacker exhaust the budget for everyone.
+   */
+  keyFn?: (c: Context<AppEnv>) => string;
+  /**
+   * The middleware no-ops under `NODE_ENV=test` by default so the suite isn't
+   * throttled. Set `false` to keep it ACTIVE in tests — required to assert the
+   * unauthenticated sign-up limiter actually returns 429 past the threshold.
+   */
+  disableInTest?: boolean;
+}
+
+/**
+ * Best-effort client IP from the proxy headers Railway/Cloudflare set (same
+ * source as `audit.ts` / tracking). Falls back to "unknown" so a request with
+ * no forwarded IP still shares a single bounded bucket rather than bypassing.
+ */
+function clientIp(c: Context<AppEnv>): string {
+  return (
+    c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ||
+    c.req.header("x-real-ip") ||
+    "unknown"
+  );
+}
+
+/** Bucket key for unauthenticated, IP-scoped surfaces (e.g. sign-up). */
+export function clientIpKey(c: Context<AppEnv>): string {
+  return `ip:${clientIp(c)}`;
 }
 
 /**
@@ -25,6 +58,7 @@ export function createRateLimit(opts: RateLimitOptions = {}) {
   const windowMs = opts.windowMs ?? DEFAULT_WINDOW_MS;
   const max = opts.max ?? DEFAULT_MAX_REQUESTS;
   const prefix = opts.prefix ?? DEFAULT_PREFIX;
+  const disableInTest = opts.disableInTest ?? true;
 
   // Per-instance memory store so prefixes stay budget-isolated in the
   // Redis-less fallback path too.
@@ -32,10 +66,11 @@ export function createRateLimit(opts: RateLimitOptions = {}) {
   let cleanupCounter = 0;
 
   return createMiddleware<AppEnv>(async (c, next) => {
-    if (process.env.NODE_ENV === "test") return next();
+    if (disableInTest && process.env.NODE_ENV === "test") return next();
 
-    const apiKey = c.get("apiKey");
-    const keyId = apiKey?.id ?? c.get("user")?.id ?? "anonymous";
+    const keyId = opts.keyFn
+      ? opts.keyFn(c)
+      : (c.get("apiKey")?.id ?? c.get("user")?.id ?? "anonymous");
     const now = Date.now();
 
     let count: number;