@hogsend/engine 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.9.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,11 +40,14 @@
     "svix": "^1.95.1",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.9.0",
-    "@hogsend/db": "^0.9.0",
-    "@hogsend/email": "^0.9.0",
-    "@hogsend/plugin-posthog": "^0.9.0",
-    "@hogsend/plugin-resend": "^0.9.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.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

@@ -9,11 +9,6 @@ import {
   type JournalShape,
 } from "@hogsend/db";
 import type { TemplateRegistry } from "@hogsend/email";
-import {
-  createResendClient,
-  createResendProvider,
-} from "@hogsend/plugin-resend";
-import type { Resend } from "resend";
 import { createBucketAccessor } from "./buckets/bucket-access.js";
 import type { DefinedBucket } from "./buckets/define-bucket.js";
 import {
@@ -33,6 +28,8 @@ import { buildJourneyRegistry } from "./journeys/registry.js";
 import { setAnalytics } from "./lib/analytics-singleton.js";
 import { type Auth, createAuth } from "./lib/auth.js";
 import { setEmailService } from "./lib/email.js";
+import { EmailProviderRegistry } from "./lib/email-provider-registry.js";
+import { emailProvidersFromEnv } from "./lib/email-providers-from-env.js";
 import type {
   EmailService,
   FrequencyCapConfig,
@@ -41,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";
@@ -61,8 +60,19 @@ export interface HogsendClient {
   db: Database;
   dbClient: DatabaseClient;
   auth: Auth;
-  email: Resend;
   emailService: EmailService;
+  /**
+   * The container-held registry of email providers, keyed by `meta.id`. The
+   * `POST /v1/webhooks/email/:providerId` route resolves the verifying provider
+   * out of this. Holds at least the resolved active provider.
+   */
+  emailProviders: EmailProviderRegistry;
+  /**
+   * The single resolved active email provider (the one the mailer sends
+   * through). Resolved from `opts.email.defaultProvider` / `EMAIL_PROVIDER`,
+   * defaulting to the env-built Resend provider for byte-for-byte parity.
+   */
+  emailProvider: EmailProvider;
   /**
    * The app's template registry (key → component + subject + category +
    * optional preview/examples). Same object threaded into the engine mailer;
@@ -121,10 +131,18 @@ export interface HogsendClientOptions {
    * (templates → render → preference checks → tracking → `email_sends` write),
    * and the {@link EmailProvider} is only the swappable wire under it.
    *
-   * - `provider` — the swappable email provider (Resend, Postmark, SES…).
-   *   Defaults to a Resend provider built from env (`RESEND_API_KEY` /
-   *   `RESEND_WEBHOOK_SECRET`). Tracking/rendering/preferences come along for
-   *   free regardless of which provider you supply.
+   * - `provider` — a single swappable email provider (Resend, Postmark, SES…),
+   *   the back-compat one-provider seam. MERGED LAST (after env presets and
+   *   `providers`), so it wins on id collision. Tracking/rendering/preferences
+   *   come along for free regardless of which provider you supply.
+   * - `providers` — register MANY providers into the {@link EmailProviderRegistry}
+   *   (e.g. Resend + Postmark) so the `POST /v1/webhooks/email/:providerId`
+   *   route can verify each one's webhooks. Merged AFTER the env presets and
+   *   BEFORE `provider`.
+   * - `defaultProvider` — the active provider id the mailer sends through.
+   *   Resolves as `defaultProvider ?? EMAIL_PROVIDER ?? "resend"`. If it names a
+   *   provider that isn't registered, the container throws at boot with the list
+   *   of registered ids.
    * - `templates` — the app's template registry (key → component + subject +
    *   category), threaded into the engine mailer and onward to
    *   `getTemplate(..., { registry })`. The engine bakes in no business
@@ -136,6 +154,8 @@ export interface HogsendClientOptions {
    */
   email?: {
     provider?: EmailProvider;
+    providers?: EmailProvider[];
+    defaultProvider?: string;
     templates?: TemplateRegistry;
   };
   /**
@@ -229,28 +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 email = createResendClient({ apiKey: env.RESEND_API_KEY });
-
   const registry = buildJourneyRegistry(
     opts.journeys ?? [],
     opts.enabledJourneys ?? env.ENABLED_JOURNEYS,
@@ -301,12 +299,51 @@ export function createHogsendClient(
     opts.enabledLists ?? env.ENABLED_LISTS,
   );
 
-  const provider =
-    opts.email?.provider ??
-    createResendProvider({
-      apiKey: env.RESEND_API_KEY,
-      webhookSecret: env.RESEND_WEBHOOK_SECRET,
-    });
+  // Build the email provider registry, then resolve the single active provider
+  // the mailer sends through. Merge order is load-bearing (consumer last/wins,
+  // mirroring the destinations merge): env presets FIRST, then
+  // `opts.email.providers`, then the single back-compat `opts.email.provider`
+  // LAST — so a consumer-supplied provider overrides an env preset of the same
+  // id (last-writer-wins on the registry). The registry is what the
+  // `POST /v1/webhooks/email/:providerId` route dispatches by id.
+  const emailProviders = new EmailProviderRegistry([
+    ...emailProvidersFromEnv(env),
+    ...(opts.email?.providers ?? []),
+    ...(opts.email?.provider ? [opts.email.provider] : []),
+  ]);
+
+  // The active provider id the mailer sends through:
+  // `defaultProvider ?? EMAIL_PROVIDER ?? "resend"`. The default Resend provider
+  // is built (when RESEND_API_KEY is set) by `emailProvidersFromEnv` above — the
+  // SINGLE place Resend is constructed from env — so resolution is just a
+  // registry lookup that throws if the active id resolves to nothing. NEVER
+  // silently fall back for a non-resend id.
+  const activeId =
+    opts.email?.defaultProvider ?? env.EMAIL_PROVIDER ?? "resend";
+  const provider = emailProviders.get(activeId);
+
+  if (!provider) {
+    throw new Error(
+      `email provider "${activeId}" is not registered (registered: ${emailProviders
+        .getAll()
+        .map((p) => p.meta?.id ?? "resend")
+        .join(", ")})`,
+    );
+  }
+
+  // Tracking sovereignty: first-party open/click tracking is the single source
+  // of truth. A provider that can't force its OWN tracking off per-send (an
+  // account-level toggle — e.g. Resend) declares `nativeTracking: true`. We
+  // can't reach that toggle, so we WARN at boot. The outbound-echo suppression
+  // in `dispatchWebhook` is the defence: a native open/click webhook only
+  // touches DB status, never re-emits outbound.
+  if (provider.capabilities?.nativeTracking === true) {
+    logger.warn(
+      `provider ${
+        provider.meta?.id ?? "resend"
+      } reports account-level native tracking ON; disable it in the dashboard — first-party tracking is Hogsend's source of truth.`,
+    );
+  }
 
   const defaults: HogsendDefaults = {
     timezone: opts.defaults?.timezone ?? "UTC",
@@ -327,10 +364,9 @@ export function createHogsendClient(
     opts.overrides?.mailer ??
     createTrackedMailer(
       {
-        defaultFrom: env.RESEND_FROM_EMAIL,
+        defaultFrom: env.EMAIL_FROM ?? env.RESEND_FROM_EMAIL,
         templates,
         db,
-        webhookSecret: env.RESEND_WEBHOOK_SECRET,
         bounceThreshold: 3,
         baseUrl: env.API_PUBLIC_URL,
         frequencyCap: defaults.frequencyCap,
@@ -344,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
@@ -404,8 +495,9 @@ export function createHogsendClient(
     db,
     dbClient: created.client,
     auth,
-    email,
     emailService,
+    emailProviders,
+    emailProvider: provider,
     templates,
     analytics,
     registry,

package/src/env.ts

@@ -23,12 +23,46 @@ 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.
     BETTER_AUTH_TRUSTED_ORIGINS: z.string().optional(),
-    RESEND_API_KEY: z.string().min(1),
+    // Optional: a deploy may run a non-Resend provider (Postmark, SES…) and set
+    // no Resend key at all. Read directly ONLY in the lazy-resend default branch
+    // (container.ts) and the future `emailProvidersFromEnv` preset. With this
+    // optional, a Postmark-only deploy boots without a Resend key.
+    RESEND_API_KEY: z.string().min(1).optional(),
     RESEND_FROM_EMAIL: z.string().email().default("noreply@hogsend.com"),
+    // --- Provider-neutral email config (BYO email provider) ---
+    // The active email provider id the container resolves from the
+    // EmailProviderRegistry. Absent → "resend" (today's byte-for-byte default).
+    EMAIL_PROVIDER: z.string().optional(),
+    // Neutral default-from address. The mailer's `defaultFrom` is
+    // `EMAIL_FROM ?? RESEND_FROM_EMAIL`, so an unset EMAIL_FROM keeps today's
+    // Resend-named default.
+    EMAIL_FROM: 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
+    // EMAIL_PROVIDER=postmark to activate it. Postmark has no HMAC, so webhook
+    // 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_MESSAGE_STREAM: z.string().min(1).optional(),
+    POSTMARK_WEBHOOK_USER: z.string().min(1).optional(),
+    POSTMARK_WEBHOOK_PASS: z.string().min(1).optional(),
     // Hatchet connection contract. The @hatchet-dev SDK also reads these straight
     // from process.env via its own config-loader, so this schema is a presence /
     // shape check that keeps the contract in one place — the values still flow to

package/src/index.ts

@@ -3,24 +3,32 @@
 // Content (journeys, webhook sources, workflows) is injected into these
 // factories by client app code; the engine never imports content.
 
-// --- Capability-provider contracts (canonical origin: @hogsend/core) ---
-// Email provider contract + analytics contract, re-exported so consumers can
-// import them from `@hogsend/engine`. (`SendEmailOptions` is intentionally
-// omitted here: the engine's public `SendEmailOptions` is the high-level
-// journey-facing send options from `./lib/email.js`; the provider-contract
-// `SendEmailOptions` remains available via `@hogsend/core`.)
 export type {
   BatchEmailItem,
   CaptureOptions,
+  EmailEvent,
+  EmailEventType,
   EmailProvider,
+  EmailProviderCapabilities,
+  EmailProviderMeta,
+  /** @deprecated Use {@link EmailEvent}. Frozen `event.raw` cast target. */
+  LegacyResendWebhookEvent,
   PostHogService,
   SendResult,
+  /** @deprecated Use {@link EmailEvent}. Kept for one minor. */
   WebhookEvent,
   WebhookHandlerMap,
 } from "@hogsend/core";
 // Core helpers used by content journeys (days/hours/minutes, condition + journey
 // types) so content can import everything from `@hogsend/engine`.
 export * from "@hogsend/core";
+// --- Capability-provider contracts (canonical origin: @hogsend/core) ---
+// Email provider contract + analytics contract, re-exported so consumers can
+// import them from `@hogsend/engine`. (`SendEmailOptions` is intentionally
+// omitted here: the engine's public `SendEmailOptions` is the high-level
+// journey-facing send options from `./lib/email.js`; the provider-contract
+// `SendEmailOptions` remains available via `@hogsend/core`.)
+export { defineEmailProvider, WebhookHandshakeSignal } from "@hogsend/core";
 export {
   BucketRegistry,
   JourneyRegistry,
@@ -120,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,
@@ -135,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 ---
@@ -149,6 +168,8 @@ export {
   sendEmail,
   setEmailService,
 } from "./lib/email.js";
+// --- Email provider registry (container-held, keyed by meta.id) ---
+export { EmailProviderRegistry } from "./lib/email-provider-registry.js";
 // --- Email service (engine-owned tracked mailer) ---
 export type {
   EmailService,
@@ -182,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,
@@ -205,6 +232,11 @@ export {
 export {
   pushTrackingEvent,
   resolveEmailSendContext,
+  resolveEmailSendContextByMessageId,
+  /**
+   * @deprecated Kept for one minor; use
+   * {@link resolveEmailSendContextByMessageId}.
+   */
   resolveEmailSendContextByResendId,
 } from "./lib/tracking-events.js";
 // --- Outbound webhooks: signing core (Section 1.2) ---

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,