@hogsend/engine 0.10.0 → 0.12.0

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/lib/test-mode.ts

@@ -0,0 +1,123 @@
+import { normalizeRecipients } from "@hogsend/core";
+import type { TestModeState } from "./domain-status.js";
+import type { Logger } from "./logger.js";
+
+/**
+ * Test-mode redirect helpers — the provider-neutral safety net that protects an
+ * operator from sending real mail before their DNS verifies. The active
+ * {@link TestModeState} is resolved ONCE per send by the mailer (cache-only,
+ * zero provider latency) and threaded here; these helpers are pure transforms.
+ *
+ * Why the redirect lives in the engine (not the provider): any `EmailProvider`
+ * is a dumb HTML wire; test mode must protect Postmark/SES users identically.
+ * Only `fromOverride` is provider-aware (Resend's `onboarding@resend.dev`), and
+ * that knowledge sits in the domain-status resolver, keyed on `providerId`.
+ */
+
+/** The structured WARN event name fired per redirected send. */
+export const TEST_MODE_REDIRECT_EVENT = "email.test_mode_redirect";
+
+/** The actionable error message when test mode is active but unaddressable. */
+export const NO_REDIRECT_MESSAGE =
+  "test mode active but no redirect address — set HOGSEND_TEST_EMAIL " +
+  "(or STUDIO_ADMIN_EMAIL); the send was BLOCKED, not delivered to the real recipient";
+
+/**
+ * Thrown by the no-db raw send paths (`sendRaw`/`sendBatch`) when test mode is
+ * active but no redirect address resolves. The tracked (DB) path does NOT throw
+ * — it records a `failed` row and returns a skipped result, mirroring the
+ * suppression branch — but the raw paths have no row to write, so they fail
+ * loudly rather than silently delivering to the real recipient.
+ */
+export class TestModeNoRedirectError extends Error {
+  constructor() {
+    super(NO_REDIRECT_MESSAGE);
+    this.name = "TestModeNoRedirectError";
+  }
+}
+
+/** The redirected wire fields for a single message. */
+export interface RedirectedFields {
+  /** Always the single redirect inbox (cc/bcc are dropped). */
+  to: string[];
+  /** The single redirect address (`to[0]`), for the `email_sends.toEmail` column. */
+  redirectTo: string;
+  /** Prefixed `[TEST → <originalRecipients>] <subject>`. */
+  subject: string;
+  /** `fromOverride ?? originalFrom` (Resend ⇒ onboarding@resend.dev). */
+  from: string;
+  /** Comma-joined ORIGINAL recipients, for the WARN log + email_sends marker. */
+  originalTo: string;
+  /** The flattened original recipient list (to + cc + bcc). */
+  originalRecipients: string[];
+}
+
+/**
+ * Resolve the active {@link TestModeState} for a send. Returns the cached state
+ * when `active`, else `null` (live send). ALWAYS fires the fire-and-forget
+ * `refreshIfStale()` first — the ONLY cache-refresh trigger on the send path,
+ * never awaited. `domainStatus` is optional so direct mailer construction
+ * (tests) without it keeps today's behavior.
+ */
+export function resolveTestMode(domainStatus?: {
+  testModeCached(): TestModeState;
+  refreshIfStale(): void;
+}): TestModeState | null {
+  if (!domainStatus) return null;
+  domainStatus.refreshIfStale();
+  const state = domainStatus.testModeCached();
+  return state.active ? state : null;
+}
+
+/**
+ * Build the redirected wire fields for one message under an active test mode.
+ * `to`/`cc`/`bcc` flatten into the subject prefix; the wire `to` becomes the
+ * single redirect inbox and cc/bcc are dropped entirely (never leak the test
+ * mail to an original cc/bcc recipient). Caller MUST have checked
+ * `state.redirectTo !== null` first (use {@link isUnaddressable}).
+ */
+export function buildRedirect(opts: {
+  from: string;
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  subject: string;
+  state: TestModeState;
+}): RedirectedFields {
+  const originalRecipients = [
+    ...normalizeRecipients(opts.to),
+    ...normalizeRecipients(opts.cc),
+    ...normalizeRecipients(opts.bcc),
+  ];
+  const originalTo = originalRecipients.join(",");
+  // redirectTo is non-null here — the caller gates on isUnaddressable first.
+  const redirectTo = opts.state.redirectTo as string;
+  return {
+    to: [redirectTo],
+    redirectTo,
+    subject: `[TEST → ${originalTo}] ${opts.subject}`,
+    from: opts.state.fromOverride ?? opts.from,
+    originalTo,
+    originalRecipients,
+  };
+}
+
+/** True when test mode is active but no redirect address resolves. */
+export function isUnaddressable(state: TestModeState): boolean {
+  return state.active && state.redirectTo === null;
+}
+
+/** Fire the per-send structured WARN for a redirected send. */
+export function logRedirect(
+  logger: Logger | undefined,
+  meta: {
+    originalTo: string;
+    redirectTo: string | null;
+    reason: string | null;
+  },
+): void {
+  logger?.warn(TEST_MODE_REDIRECT_EVENT, {
+    event: TEST_MODE_REDIRECT_EVENT,
+    ...meta,
+  });
+}

package/src/lib/tracked.ts

@@ -14,6 +14,7 @@ import {
 } from "@hogsend/email";
 import { eq } from "drizzle-orm";
 import { getListRegistry } from "../lists/registry-singleton.js";
+import type { TestModeState } from "./domain-status.js";
 import {
   type FrequencyCapConfig,
   type SendTrackedEmailOptions,
@@ -24,6 +25,12 @@ import { isFrequencyCapped } from "./frequency-cap.js";
 import { hatchet } from "./hatchet.js";
 import { createLogger, type Logger } from "./logger.js";
 import { emitOutbound } from "./outbound.js";
+import {
+  buildRedirect,
+  isUnaddressable,
+  logRedirect,
+  NO_REDIRECT_MESSAGE,
+} from "./test-mode.js";
 
 // Module-level fallback logger for the outbound emit — the tracked-mailer's
 // `logger` dep is optional, but `emitOutbound` requires one. Mirrors the
@@ -49,6 +56,13 @@ interface TrackedEmailDeps {
   frequencyCap?: FrequencyCapConfig;
   /** Optional structured logger for operational events (e.g. cap skips). */
   logger?: Logger;
+  /**
+   * The active test-mode state, resolved ONCE by the mailer (cache-only) and
+   * threaded in so this module stays domainStatus-unaware. `null` ⇒ live send.
+   * When active, suppression/frequency/unsubscribe still key to the ORIGINAL
+   * recipient (`options.to`); only the wire + `email_sends` row are redirected.
+   */
+  testMode?: TestModeState | null;
 }
 
 export async function sendTrackedEmail<K extends TemplateName>(
@@ -61,9 +75,19 @@ export async function sendTrackedEmail<K extends TemplateName>(
     prepareTrackedHtml,
     frequencyCap,
     logger,
+    testMode,
     options,
   } = opts;
 
+  // Test-mode redirect (resolved by the mailer; null ⇒ live). When active, the
+  // wire `to`/`from`/`subject` + the email_sends row are redirected, but EVERY
+  // preference statement below (suppression, frequency cap, unsubscribe token)
+  // still keys to the ORIGINAL recipient `options.to` — preferences belong to
+  // the real user, never the shared test inbox. Resolved lazily after the
+  // suppression/frequency-cap branch so the original recipient's preferences are
+  // honored first.
+  const redirectActive = Boolean(testMode?.active);
+
   // The idempotency-collision result, built identically whether the prior row is
   // found by the up-front short-circuit select OR the concurrent-insert loser
   // path below: surface the winner's send id, mapping "sent" → sent and anything
@@ -220,17 +244,80 @@ export async function sendTrackedEmail<K extends TemplateName>(
         }).element
       : element;
 
+  // Test-mode redirect — resolved AFTER the original-recipient preference checks
+  // above (suppression/frequency/unsubscribe), so preferences belong to the real
+  // user. Hard-fail branch: active but unaddressable ⇒ write a `failed` row with
+  // the metadata marker (so Studio surfaces the blocked send) and return a
+  // skipped result. The provider is NEVER reached — the real recipient must not
+  // receive mail from an unverified domain just because no test inbox is set.
+  if (redirectActive && testMode && isUnaddressable(testMode)) {
+    (logger ?? emitLogger).error(NO_REDIRECT_MESSAGE, {
+      originalTo: options.to,
+      templateKey: options.templateKey,
+    });
+    const rows = await db
+      .insert(emailSends)
+      .values({
+        templateKey: options.templateKey,
+        fromEmail: options.from,
+        toEmail: options.to,
+        subject: options.subject ?? "",
+        category: effectiveCategory,
+        journeyStateId: options.journeyStateId,
+        userId: options.userId,
+        userEmail: options.userEmail ?? options.to,
+        status: "failed",
+        metadata: { testMode: true, originalTo: options.to },
+      })
+      .returning({ id: emailSends.id });
+    const blockedRow = rows[0];
+    if (!blockedRow) throw new Error("Failed to insert email_sends row");
+    return trackedSendResult({
+      emailSendId: blockedRow.id,
+      messageId: "",
+      status: "skipped",
+      reason: "test_mode_blocked",
+    });
+  }
+
+  // Active + addressable: compute the redirected wire fields ONCE. `email_sends`
+  // records what ACTUALLY went out the wire (redirect inbox, prefixed subject,
+  // effective from) plus the `metadata.originalTo` marker, while preferences
+  // above stayed keyed to `options.to`.
+  const redirect =
+    redirectActive && testMode
+      ? buildRedirect({
+          from: options.from,
+          to: options.to,
+          subject,
+          state: testMode,
+        })
+      : null;
+  if (redirect && testMode) {
+    logRedirect(logger ?? emitLogger, {
+      originalTo: redirect.originalTo,
+      redirectTo: testMode.redirectTo,
+      reason: testMode.reason,
+    });
+  }
+  const wireTo = redirect ? redirect.to : options.to;
+  const wireSubject = redirect ? redirect.subject : subject;
+  const wireFrom = redirect ? redirect.from : options.from;
+
   const baseInsert = db.insert(emailSends).values({
     templateKey: options.templateKey,
-    fromEmail: options.from,
-    toEmail: options.to,
-    subject,
+    fromEmail: wireFrom,
+    toEmail: redirect ? redirect.redirectTo : options.to,
+    subject: wireSubject,
     category: effectiveCategory,
     journeyStateId: options.journeyStateId,
     userId: options.userId,
     userEmail: options.userEmail ?? options.to,
     status: "queued",
     idempotencyKey: options.idempotencyKey,
+    ...(redirect
+      ? { metadata: { testMode: true, originalTo: options.to } }
+      : {}),
   });
 
   // With an idempotency key, swallow a concurrent-insert collision on the unique
@@ -274,9 +361,9 @@ export async function sendTrackedEmail<K extends TemplateName>(
         : rawHtml;
 
     const result = await provider.send({
-      from: options.from,
-      to: options.to,
-      subject,
+      from: wireFrom,
+      to: wireTo,
+      subject: wireSubject,
       html,
       tags: options.tags,
       headers: sendHeaders,

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;