@hogsend/engine 0.9.0 → 0.11.0

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/email-provider-registry.ts

@@ -0,0 +1,45 @@
+import type { EmailProvider } from "@hogsend/core";
+
+/**
+ * Container-held registry of email providers, keyed by `provider.meta.id`. The
+ * webhook route (`POST /v1/webhooks/email/:providerId`) resolves the verifying
+ * provider out of this registry via `c.get("container")`, and the container
+ * also picks ONE `active` provider out of it for the mailer.
+ *
+ * Deliberately NOT a process singleton: unlike the `DestinationRegistry`
+ * singleton — which exists only because the self-booting `deliverWebhookTask`
+ * has no container — both readers of this registry (the mailer the container
+ * constructs, and the webhook route which has the container) have a container
+ * reference, so the singleton + lazy-preset fallback would be dead weight.
+ *
+ * Keyed by `meta.id` with last-writer-wins, so a consumer-supplied provider of
+ * the same id overrides an env preset of that id.
+ */
+export class EmailProviderRegistry {
+  private byId = new Map<string, EmailProvider>();
+
+  constructor(providers: EmailProvider[] = []) {
+    for (const provider of providers) this.register(provider);
+  }
+
+  /**
+   * Register (or replace) a provider. Falls back to `"resend"` for a provider
+   * built before `meta` existed (the contract keeps `meta` optional for
+   * back-compat). Last-writer-wins.
+   */
+  register(provider: EmailProvider): void {
+    this.byId.set(provider.meta?.id ?? "resend", provider);
+  }
+
+  get(id: string): EmailProvider | undefined {
+    return this.byId.get(id);
+  }
+
+  getAll(): EmailProvider[] {
+    return [...this.byId.values()];
+  }
+
+  count(): number {
+    return this.byId.size;
+  }
+}

package/src/lib/email-providers-from-env.ts

@@ -0,0 +1,94 @@
+import type { EmailProvider } from "@hogsend/core";
+import { createResendProvider } from "@hogsend/plugin-resend";
+import type { env as envSchema } from "../env.js";
+
+/**
+ * `@hogsend/plugin-postmark` is an OPT-IN, deferred-publish package: it is an
+ * engine `optionalDependency`, NOT a hard one, and it is not on the npm registry
+ * yet. So we MUST NOT statically import it — a static `import` would make the
+ * package mandatory at engine load, and `npm install @hogsend/engine` would fail
+ * with E404 on plugin-postmark for every consumer that doesn't have it.
+ *
+ * Instead we load it lazily, ONCE, behind a top-level guarded dynamic import:
+ * the `import()` only fires when `POSTMARK_SERVER_TOKEN` is present (the same
+ * gate the preset below uses), so a deploy that never sets that var never
+ * touches the package and degrades gracefully when it isn't installed. ESM
+ * top-level await keeps `emailProvidersFromEnv` itself synchronous (it reads the
+ * already-resolved factory), so `createHogsendClient` stays synchronous.
+ *
+ * The specifier is assembled at runtime (not a string literal) ON PURPOSE: a
+ * literal `import("@hogsend/plugin-postmark")` makes `tsc` resolve the module's
+ * types, which fails with TS2307 for any consumer that doesn't have the opt-in
+ * package installed (e.g. a fresh `create-hogsend` app). A computed specifier is
+ * opaque to the type-checker — resolved only at runtime — so the engine
+ * type-checks identically with or without the package present.
+ */
+type CreatePostmarkProvider = (cfg: {
+  serverToken: string;
+  messageStream?: string;
+  webhookBasicAuth?: { user: string; pass: string };
+}) => EmailProvider;
+
+const POSTMARK_PACKAGE = ["@hogsend", "plugin-postmark"].join("/");
+
+let createPostmarkProvider: CreatePostmarkProvider | null = null;
+if (process.env.POSTMARK_SERVER_TOKEN) {
+  try {
+    ({ createPostmarkProvider } = (await import(POSTMARK_PACKAGE)) as {
+      createPostmarkProvider: CreatePostmarkProvider;
+    });
+  } catch {
+    // The token is set but the opt-in package isn't installed. Leave the factory
+    // null — `emailProvidersFromEnv` skips the preset, and if Postmark was the
+    // resolved active provider the container throws a clear "not registered"
+    // error directing the operator to install `@hogsend/plugin-postmark`.
+    createPostmarkProvider = null;
+  }
+}
+
+/**
+ * Build the env-enabled email-provider presets. Mirrors `destinationsFromEnv`:
+ * a preset is constructed ONLY when its credential is present, so a
+ * Postmark-only deploy (no `RESEND_API_KEY`) contributes no Resend provider.
+ *
+ * These presets come FIRST in the container's merge — a consumer-supplied
+ * provider of the same id wins (last-writer-wins on the registry).
+ */
+export function emailProvidersFromEnv(env: typeof envSchema): EmailProvider[] {
+  const providers: EmailProvider[] = [];
+
+  if (env.RESEND_API_KEY) {
+    providers.push(
+      createResendProvider({
+        apiKey: env.RESEND_API_KEY,
+        webhookSecret: env.RESEND_WEBHOOK_SECRET,
+      }),
+    );
+  }
+
+  // Postmark is OPT-IN: built only when its token is present AND the opt-in
+  // package resolved (see the guarded dynamic import above), and it never
+  // changes the default active provider — set EMAIL_PROVIDER=postmark to
+  // activate it. Postmark has no HMAC, so webhook auth is HTTP Basic creds (the
+  // provider fails closed when they're unset).
+  if (env.POSTMARK_SERVER_TOKEN && createPostmarkProvider) {
+    providers.push(
+      createPostmarkProvider({
+        serverToken: env.POSTMARK_SERVER_TOKEN,
+        ...(env.POSTMARK_MESSAGE_STREAM
+          ? { messageStream: env.POSTMARK_MESSAGE_STREAM }
+          : {}),
+        ...(env.POSTMARK_WEBHOOK_USER && env.POSTMARK_WEBHOOK_PASS
+          ? {
+              webhookBasicAuth: {
+                user: env.POSTMARK_WEBHOOK_USER,
+                pass: env.POSTMARK_WEBHOOK_PASS,
+              },
+            }
+          : {}),
+      }),
+    );
+  }
+
+  return providers;
+}

package/src/lib/email-service-types.ts

@@ -1,9 +1,10 @@
 import type {
   BatchEmailItem,
   DurationObject,
+  EmailEvent,
+  EmailEventType,
   SendEmailOptions,
   SendResult,
-  WebhookEventType,
   WebhookHandlerMap,
 } from "@hogsend/core";
 import type {
@@ -63,12 +64,36 @@ export interface SendTrackedEmailOptions<
 
 export interface TrackedSendResult {
   emailSendId: string;
+  /** The provider's neutral message id (Resend email_id / Postmark MessageID). */
+  messageId: string;
+  /**
+   * @deprecated Renamed to {@link TrackedSendResult.messageId}. This read-alias
+   * always mirrors `messageId`; kept for one minor and removed the following
+   * minor. Build results via {@link trackedSendResult} so the alias stays live.
+   */
   resendId: string;
   status: "sent" | "suppressed" | "unsubscribed" | "skipped";
   /** Present only when `status === "skipped"` by the frequency cap. */
   reason?: "frequency_capped";
 }
 
+/**
+ * Build a {@link TrackedSendResult}, attaching a live `@deprecated` `resendId`
+ * read-alias getter that mirrors `messageId`. Lets every send path return a
+ * single canonical `messageId` while public consumers reading the old `resendId`
+ * field keep working for one minor.
+ */
+export function trackedSendResult(
+  result: Omit<TrackedSendResult, "resendId">,
+): TrackedSendResult {
+  return Object.defineProperty({ ...result }, "resendId", {
+    get(this: { messageId: string }) {
+      return this.messageId;
+    },
+    enumerable: true,
+  }) as TrackedSendResult;
+}
+
 // ---------------------------------------------------------------------------
 // Frequency capping (client default config)
 // ---------------------------------------------------------------------------
@@ -102,7 +127,6 @@ export interface EmailServiceConfig {
    */
   templates: TemplateRegistry;
   db?: unknown;
-  webhookSecret?: string;
   webhookHandlers?: WebhookHandlerMap;
   retryOptions?: RetryOptions;
   bounceThreshold?: number;
@@ -138,13 +162,18 @@ export interface EmailServiceSendOptions<
   idempotencyKey?: string;
 }
 
+/**
+ * @deprecated The route now verifies the provider webhook and hands
+ * {@link EmailService.handleWebhook} an already-parsed {@link EmailEvent}. This
+ * raw `{ payload, headers }` shape is no longer the handler input.
+ */
 export interface EmailServiceWebhookOptions {
   payload: string;
   headers: Record<string, string>;
 }
 
 export interface EmailServiceWebhookResult {
-  type: WebhookEventType;
+  type: EmailEventType;
   handled: boolean;
 }
 
@@ -163,7 +192,14 @@ export interface EmailService {
     options: EmailServiceRenderOptions<K>,
   ): Promise<EmailServiceRenderResult>;
 
+  /**
+   * Dispatch an already-verified, provider-neutral {@link EmailEvent} into the
+   * status/suppression/outbound pipeline. The webhook route owns provider
+   * resolution + signature verification and passes the parsed event + the
+   * resolving `providerId` (the latter is informational for now).
+   */
   handleWebhook(
-    options: EmailServiceWebhookOptions,
+    event: EmailEvent,
+    providerId?: string,
   ): Promise<EmailServiceWebhookResult>;
 }

package/src/lib/headers.ts

@@ -0,0 +1,13 @@
+/**
+ * Flatten a `Headers` instance into a plain lowercased `Record<string, string>`.
+ * Webhook routes verify signatures over the EXACT received bytes, so they need a
+ * case-insensitive header lookup — this is the single place that lowercasing
+ * lives. Pass `c.req.raw.headers`.
+ */
+export function headersToRecord(headers: Headers): Record<string, string> {
+  const record: Record<string, string> = {};
+  for (const [key, value] of headers.entries()) {
+    record[key.toLowerCase()] = value;
+  }
+  return record;
+}