@lunora/auth 1.0.0-alpha.34 → 1.0.0-alpha.36

package/README.md

@@ -88,6 +88,61 @@ better-auth's plugin factories are re-exported from `@lunora/auth/plugins` (so y
 
 For Cloudflare Turnstile on the **auth flow**, use the `captcha` plugin (`captcha({ provider: "cloudflare-turnstile", secretKey: env.TURNSTILE_SECRET_KEY })`); it reads the token from the `x-captcha-response` header. For **non-auth** procedures, the package root also exports standalone helpers — `verifyTurnstile` (pure `siteverify`) and `verifyTurnstileMiddleware` (a `.use()` middleware that takes the token from the function args).
 
+### Disposable / free-email gating
+
+Reject throwaway/disposable signups (and branch on free-vs-business email) by reusing the visulima email lists — pure-data and **edge-safe on the default path** (no DNS). Wire it into better-auth's native signup with `withEmailGate` (or `emailGateDatabaseHooks`):
+
+```ts
+import { createAuth, withEmailGate, lunoraD1Adapter } from "@lunora/auth";
+
+const auth = createAuth(
+    withEmailGate(
+        { secret: env.AUTH_SECRET, database: lunoraD1Adapter(env.DB), emailAndPassword: { enabled: true } },
+        {
+            blockDisposable: true, // default — reject disposable domains with `EMAIL_DOMAIN_BLOCKED`
+            allowDomains: ["your-company.com"], // never blocked; always classified `business`
+            denyDomains: [], // extra domains to treat as disposable
+            // mx: true,       // OPT-IN deliverability check — needs DNS (node:dns), so keep it OFF on the edge path
+            onClassify: (c, user) => console.log(`signup ${user.email as string}: ${c.emailClass}`),
+        },
+    ),
+);
+```
+
+A blocked signup fails with the coded error `EMAIL_DOMAIN_BLOCKED` (HTTP 400); a business/free email passes and its `emailClass` (`disposable | free | business`) is surfaced via `onClassify`. Everything is config-gated and defaults sensibly.
+
+- **Programmatic / non-auth use:** `classifyEmail(email, config)` (sync, pure-data) and `assertEmailAllowed(email, config)` (async; throws the coded error) come from `@lunora/auth/email-guard`, plus `emailGateMiddleware({ email: (ctx) => ctx.args.email })` for a `.use()` gate on your own signup mutations.
+- **Edge-safety:** on workerd, `await loadEmailDomainLists()` once at worker init (the gate helpers do this for you). The optional `mx: true` deliverability check is loaded via a dynamic import so `node:dns` never enters the default bundle — enable it only with `nodejs_compat` (or a DNS-over-HTTPS shim).
+
+### Security / audit trail
+
+Record authentication & security events (sign-in, sign-up, password change, MFA enable/disable, token refresh, session revoke, …) to a durable, queryable audit trail. Install the better-auth `hooks.after` recorder with `authAuditHook` (or compose via `withAuthAudit`), backed by the same D1 database as the auth tables:
+
+```ts
+import { authAuditHook, createAuth, d1Executor, lunoraD1Adapter, readAuthAuditLog } from "@lunora/auth";
+
+const executor = d1Executor(env.DB);
+
+const auth = createAuth({
+    secret: env.AUTH_SECRET,
+    database: lunoraD1Adapter(env.DB),
+    hooks: {
+        after: authAuditHook({
+            executor,
+            // retention is CONFIGURABLE and NOT capped — omit it for an unbounded, compliance-grade trail
+            retention: 100_000,
+            // optional export tap for SIEM forwarding (receives each redacted entry)
+            onRecord: (entry) => forwardToSiem(entry),
+        }),
+    },
+});
+
+// Query the trail (RLS/admin-gate this in your own read):
+const recent = await readAuthAuditLog(executor, { event: "sign-in", limit: 100 });
+```
+
+The free-form `detail` payload is scrubbed with `@visulima/redact` before it is persisted, so a token/password that leaks into an event's context never reaches the durable table. Retention defaults to unbounded (set `retention` to bound it). The store lives in the reserved `__lunora_auth_audit__` table (auto-hidden from the data browser).
+
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/packages/auth)**.
 
 ## Related

package/dist/audit.d.mts

@@ -0,0 +1,114 @@
+import { SqlExecutor } from "./sql-store.mjs";
+import "./store.mjs";
+import 'better-auth/adapters';
+/** Reserved append-only table backing the Studio "Security / audit" page. Auto-hidden from the data browser by the `__lunora` prefix. */
+declare const AUTH_AUDIT_TABLE = "__lunora_auth_audit__";
+/**
+ * Well-known auth/security event types. A plain `string` is also accepted so
+ * plugins can record their own events without a union change — the union just
+ * gives autocomplete for the common ones.
+ */
+type AuthAuditEvent = "account-link" | "account-unlink" | "email-verification" | "mfa-disable" | "mfa-enable" | "password-change" | "password-reset" | "session-revoke" | "sign-in" | "sign-out" | "sign-up" | "token-refresh" | (string & {});
+/** Whether the recorded operation succeeded or failed (e.g. a rejected sign-in). */
+type AuthAuditOutcome = "failure" | "success";
+/** One recorded auth/security event, in monotonic `seq` order. */
+interface AuthAuditEntry {
+  /** Redaction is applied to `detail`, not this — the actor's email is intentional forensic data. Absent for anonymous/pre-auth events. */
+  actorEmail?: string;
+  /** The acting user's id, when known. */
+  actorId?: string;
+  /** JSON-decoded extra context, with secrets/PII redacted at write time; absent when none was recorded. */
+  detail?: Record<string, unknown>;
+  /** Auth event type, e.g. `sign-in` / `password-change`. */
+  event: string;
+  /** Client IP the event originated from, when resolvable. */
+  ip?: string;
+  /** Whether the operation succeeded or failed. */
+  outcome: AuthAuditOutcome;
+  /** Monotonic per-database cursor — strictly increasing, never reused. */
+  seq: number;
+  /** Wall-clock millis when the event was recorded. */
+  ts: number;
+  /** Client User-Agent, when present on the request. */
+  userAgent?: string;
+}
+/** Fields accepted when appending one event; `seq` is assigned by the table. */
+interface AppendAuthAuditEntry {
+  actorEmail?: string;
+  actorId?: string;
+  detail?: Record<string, unknown>;
+  event: string;
+  ip?: string;
+  outcome: AuthAuditOutcome;
+  ts: number;
+  userAgent?: string;
+}
+/** Options for {@link appendAuthAuditEntry}. */
+interface AppendAuthAuditOptions {
+  /**
+   * Redact secrets/PII in the `detail` payload before persisting. Defaults to
+   * `true`. Set `false` only for a trusted, pre-scrubbed payload.
+   */
+  redactDetail?: boolean;
+  /**
+   * Keep only the most recent `retention` rows (trimmed after each append),
+   * mirroring the admin audit log's bounded retention. Omit for an unbounded
+   * trail (the compliance default) — deliberately NOT capped at 1000.
+   */
+  retention?: number;
+}
+/** Options for {@link readAuthAuditLog}. */
+interface ReadAuthAuditOptions {
+  /** Return only events for this actor id. */
+  actorId?: string;
+  /** Return only events of this type. */
+  event?: string;
+  /** Max rows to return, clamped to [1, 10000]. Defaults to 1000. */
+  limit?: number;
+  /** Return only events with `seq` strictly greater than this (forward paging). */
+  sinceSeq?: number;
+}
+/**
+ * Create the `__lunora_auth_audit__` table. `seq` is an `AUTOINCREMENT` primary
+ * key giving the database a monotonic cursor the Security page pages through.
+ * Idempotent, so read and write paths can call it defensively.
+ */
+declare const ensureAuthAuditTable: (executor: SqlExecutor) => Promise<void>;
+/**
+ * Append one auth event, redacting its `detail` payload (unless disabled) and —
+ * when `retention` is set — trimming the log back to the most recent rows.
+ * Creates the table first so callers needn't. Returns the redacted, persisted
+ * entry (sans `seq`) so an export tap can forward exactly what was stored.
+ */
+declare const appendAuthAuditEntry: (executor: SqlExecutor, entry: AppendAuthAuditEntry, options?: AppendAuthAuditOptions) => Promise<AppendAuthAuditEntry>;
+/**
+ * Read audit events newest-first, optionally filtered by `actorId` / `event` and
+ * paged past `sinceSeq`, up to `limit` (clamped to [1, 10000]). Parses each row's
+ * `detail` JSON back into an object. Creates the table first so reads on a
+ * never-audited database return `[]` instead of throwing.
+ */
+declare const readAuthAuditLog: (executor: SqlExecutor, options?: ReadAuthAuditOptions) => Promise<AuthAuditEntry[]>;
+/**
+ * The auth/security audit read plane the runtime's `authAuditReader` option
+ * accepts — a structurally-compatible `{ read }` object the worker calls behind
+ * its admin gate to back the studio's "Security / audit" page
+ * (`__lunora_admin__:getAuthAuditLog`).
+ */
+interface AuthAuditReader {
+  read: (options: ReadAuthAuditOptions) => Promise<AuthAuditEntry[]>;
+}
+/**
+ * Build the reader the runtime's `authAuditReader` option accepts, closing over
+ * the auth D1 `executor` (`d1Executor(env.DB)`) so an admin caller reads the same
+ * `__lunora_auth_audit__` table the hook writes. Filters/paging pass straight
+ * through to {@link readAuthAuditLog} (which clamps `limit`).
+ *
+ * ```ts
+ * export default createWorker({
+ *     authAuditReader: createAuthAuditReader(d1Executor(env.DB)),
+ *     // …
+ * });
+ * ```
+ */
+declare const createAuthAuditReader: (executor: SqlExecutor) => AuthAuditReader;
+export { AUTH_AUDIT_TABLE, type AppendAuthAuditEntry, type AppendAuthAuditOptions, type AuthAuditEntry, type AuthAuditEvent, type AuthAuditOutcome, type AuthAuditReader, type ReadAuthAuditOptions, appendAuthAuditEntry, createAuthAuditReader, ensureAuthAuditTable, readAuthAuditLog };

package/dist/audit.d.ts

@@ -0,0 +1,114 @@
+import { SqlExecutor } from "./sql-store.js";
+import "./store.js";
+import 'better-auth/adapters';
+/** Reserved append-only table backing the Studio "Security / audit" page. Auto-hidden from the data browser by the `__lunora` prefix. */
+declare const AUTH_AUDIT_TABLE = "__lunora_auth_audit__";
+/**
+ * Well-known auth/security event types. A plain `string` is also accepted so
+ * plugins can record their own events without a union change — the union just
+ * gives autocomplete for the common ones.
+ */
+type AuthAuditEvent = "account-link" | "account-unlink" | "email-verification" | "mfa-disable" | "mfa-enable" | "password-change" | "password-reset" | "session-revoke" | "sign-in" | "sign-out" | "sign-up" | "token-refresh" | (string & {});
+/** Whether the recorded operation succeeded or failed (e.g. a rejected sign-in). */
+type AuthAuditOutcome = "failure" | "success";
+/** One recorded auth/security event, in monotonic `seq` order. */
+interface AuthAuditEntry {
+  /** Redaction is applied to `detail`, not this — the actor's email is intentional forensic data. Absent for anonymous/pre-auth events. */
+  actorEmail?: string;
+  /** The acting user's id, when known. */
+  actorId?: string;
+  /** JSON-decoded extra context, with secrets/PII redacted at write time; absent when none was recorded. */
+  detail?: Record<string, unknown>;
+  /** Auth event type, e.g. `sign-in` / `password-change`. */
+  event: string;
+  /** Client IP the event originated from, when resolvable. */
+  ip?: string;
+  /** Whether the operation succeeded or failed. */
+  outcome: AuthAuditOutcome;
+  /** Monotonic per-database cursor — strictly increasing, never reused. */
+  seq: number;
+  /** Wall-clock millis when the event was recorded. */
+  ts: number;
+  /** Client User-Agent, when present on the request. */
+  userAgent?: string;
+}
+/** Fields accepted when appending one event; `seq` is assigned by the table. */
+interface AppendAuthAuditEntry {
+  actorEmail?: string;
+  actorId?: string;
+  detail?: Record<string, unknown>;
+  event: string;
+  ip?: string;
+  outcome: AuthAuditOutcome;
+  ts: number;
+  userAgent?: string;
+}
+/** Options for {@link appendAuthAuditEntry}. */
+interface AppendAuthAuditOptions {
+  /**
+   * Redact secrets/PII in the `detail` payload before persisting. Defaults to
+   * `true`. Set `false` only for a trusted, pre-scrubbed payload.
+   */
+  redactDetail?: boolean;
+  /**
+   * Keep only the most recent `retention` rows (trimmed after each append),
+   * mirroring the admin audit log's bounded retention. Omit for an unbounded
+   * trail (the compliance default) — deliberately NOT capped at 1000.
+   */
+  retention?: number;
+}
+/** Options for {@link readAuthAuditLog}. */
+interface ReadAuthAuditOptions {
+  /** Return only events for this actor id. */
+  actorId?: string;
+  /** Return only events of this type. */
+  event?: string;
+  /** Max rows to return, clamped to [1, 10000]. Defaults to 1000. */
+  limit?: number;
+  /** Return only events with `seq` strictly greater than this (forward paging). */
+  sinceSeq?: number;
+}
+/**
+ * Create the `__lunora_auth_audit__` table. `seq` is an `AUTOINCREMENT` primary
+ * key giving the database a monotonic cursor the Security page pages through.
+ * Idempotent, so read and write paths can call it defensively.
+ */
+declare const ensureAuthAuditTable: (executor: SqlExecutor) => Promise<void>;
+/**
+ * Append one auth event, redacting its `detail` payload (unless disabled) and —
+ * when `retention` is set — trimming the log back to the most recent rows.
+ * Creates the table first so callers needn't. Returns the redacted, persisted
+ * entry (sans `seq`) so an export tap can forward exactly what was stored.
+ */
+declare const appendAuthAuditEntry: (executor: SqlExecutor, entry: AppendAuthAuditEntry, options?: AppendAuthAuditOptions) => Promise<AppendAuthAuditEntry>;
+/**
+ * Read audit events newest-first, optionally filtered by `actorId` / `event` and
+ * paged past `sinceSeq`, up to `limit` (clamped to [1, 10000]). Parses each row's
+ * `detail` JSON back into an object. Creates the table first so reads on a
+ * never-audited database return `[]` instead of throwing.
+ */
+declare const readAuthAuditLog: (executor: SqlExecutor, options?: ReadAuthAuditOptions) => Promise<AuthAuditEntry[]>;
+/**
+ * The auth/security audit read plane the runtime's `authAuditReader` option
+ * accepts — a structurally-compatible `{ read }` object the worker calls behind
+ * its admin gate to back the studio's "Security / audit" page
+ * (`__lunora_admin__:getAuthAuditLog`).
+ */
+interface AuthAuditReader {
+  read: (options: ReadAuthAuditOptions) => Promise<AuthAuditEntry[]>;
+}
+/**
+ * Build the reader the runtime's `authAuditReader` option accepts, closing over
+ * the auth D1 `executor` (`d1Executor(env.DB)`) so an admin caller reads the same
+ * `__lunora_auth_audit__` table the hook writes. Filters/paging pass straight
+ * through to {@link readAuthAuditLog} (which clamps `limit`).
+ *
+ * ```ts
+ * export default createWorker({
+ *     authAuditReader: createAuthAuditReader(d1Executor(env.DB)),
+ *     // …
+ * });
+ * ```
+ */
+declare const createAuthAuditReader: (executor: SqlExecutor) => AuthAuditReader;
+export { AUTH_AUDIT_TABLE, type AppendAuthAuditEntry, type AppendAuthAuditOptions, type AuthAuditEntry, type AuthAuditEvent, type AuthAuditOutcome, type AuthAuditReader, type ReadAuthAuditOptions, appendAuthAuditEntry, createAuthAuditReader, ensureAuthAuditTable, readAuthAuditLog };

package/dist/audit.mjs

@@ -0,0 +1,111 @@
+import { redact, standardRules, piiRules } from '@visulima/redact';
+
+const AUTH_AUDIT_TABLE = "__lunora_auth_audit__";
+const AUDIT_REDACT_RULES = [...standardRules, ...piiRules];
+const DEFAULT_READ_LIMIT = 1e3;
+const MAX_READ_LIMIT = 1e4;
+const SQL_NULL = null;
+const text = (value) => {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
+    return String(value);
+  }
+  return void 0;
+};
+const ensureAuthAuditTable = async (executor) => {
+  await executor.run(
+    `CREATE TABLE IF NOT EXISTS "${AUTH_AUDIT_TABLE}" (
+            seq INTEGER PRIMARY KEY AUTOINCREMENT,
+            ts REAL NOT NULL,
+            event TEXT NOT NULL,
+            outcome TEXT NOT NULL,
+            actor_id TEXT,
+            actor_email TEXT,
+            ip TEXT,
+            user_agent TEXT,
+            detail TEXT
+        )`,
+    []
+  );
+};
+const appendAuthAuditEntry = async (executor, entry, options = {}) => {
+  await ensureAuthAuditTable(executor);
+  let detail;
+  if (entry.detail !== void 0) {
+    detail = options.redactDetail === false ? entry.detail : redact(entry.detail, AUDIT_REDACT_RULES);
+  }
+  await executor.run(
+    `INSERT INTO "${AUTH_AUDIT_TABLE}" (ts, event, outcome, actor_id, actor_email, ip, user_agent, detail) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      entry.ts,
+      entry.event,
+      entry.outcome,
+      entry.actorId ?? SQL_NULL,
+      entry.actorEmail ?? SQL_NULL,
+      entry.ip ?? SQL_NULL,
+      entry.userAgent ?? SQL_NULL,
+      detail === void 0 ? SQL_NULL : JSON.stringify(detail)
+    ]
+  );
+  if (typeof options.retention === "number" && options.retention > 0) {
+    await executor.run(`DELETE FROM "${AUTH_AUDIT_TABLE}" WHERE seq <= (SELECT MAX(seq) - ? FROM "${AUTH_AUDIT_TABLE}")`, [options.retention]);
+  }
+  return { ...entry, detail };
+};
+const readAuthAuditLog = async (executor, options = {}) => {
+  await ensureAuthAuditTable(executor);
+  const limit = Math.max(1, Math.min(options.limit ?? DEFAULT_READ_LIMIT, MAX_READ_LIMIT));
+  const clauses = ["seq > ?"];
+  const parameters = [options.sinceSeq ?? 0];
+  if (options.actorId !== void 0) {
+    clauses.push("actor_id = ?");
+    parameters.push(options.actorId);
+  }
+  if (options.event !== void 0) {
+    clauses.push("event = ?");
+    parameters.push(options.event);
+  }
+  parameters.push(limit);
+  const rows = await executor.all(
+    `SELECT seq, ts, event, outcome, actor_id, actor_email, ip, user_agent, detail FROM "${AUTH_AUDIT_TABLE}" WHERE ${clauses.join(" AND ")} ORDER BY seq DESC LIMIT ?`,
+    parameters
+  );
+  return rows.map((row) => {
+    const base = {
+      event: text(row["event"]) ?? "",
+      outcome: row["outcome"] === "failure" ? "failure" : "success",
+      seq: Number(row["seq"]),
+      ts: Number(row["ts"])
+    };
+    const actorId = text(row["actor_id"]);
+    const actorEmail = text(row["actor_email"]);
+    const ip = text(row["ip"]);
+    const userAgent = text(row["user_agent"]);
+    const detail = text(row["detail"]);
+    if (actorId !== void 0) {
+      base.actorId = actorId;
+    }
+    if (actorEmail !== void 0) {
+      base.actorEmail = actorEmail;
+    }
+    if (ip !== void 0) {
+      base.ip = ip;
+    }
+    if (userAgent !== void 0) {
+      base.userAgent = userAgent;
+    }
+    if (detail !== void 0) {
+      base.detail = JSON.parse(detail);
+    }
+    return base;
+  });
+};
+const createAuthAuditReader = (executor) => {
+  return {
+    read: (options) => readAuthAuditLog(executor, options)
+  };
+};
+
+export { AUTH_AUDIT_TABLE, appendAuthAuditEntry, createAuthAuditReader, ensureAuthAuditTable, readAuthAuditLog };

package/dist/email-guard.d.mts

@@ -0,0 +1,122 @@
+import { Middleware } from '@lunora/server';
+/**
+ * The resolved trust class of an email address' domain: `disposable` (a
+ * throwaway/temporary provider, or a caller `denyDomains` hit), `free` (a free
+ * consumer provider like Gmail — deliverable but not B2B), or `business`
+ * (anything else — a custom/company domain, or an `allowDomains` hit).
+ */
+type EmailClass = "business" | "disposable" | "free";
+/** Result of {@link classifyEmail} — the resolved class plus the normalized domain. */
+interface EmailClassification {
+  /** The normalized (lowercased, trimmed) domain, or `undefined` for a structurally invalid address. */
+  domain: string | undefined;
+  /** The resolved trust class. A structurally invalid address resolves to `business` with `domain: undefined`. */
+  emailClass: EmailClass;
+}
+/** Configuration for {@link classifyEmail} / {@link assertEmailAllowed} / {@link emailGateMiddleware}. */
+interface EmailGateConfig {
+  /**
+   * Domains that are always allowed and always classified `business`, even if
+   * they appear on the disposable or free lists. Wildcard/subdomain aware
+   * (`example.com` also allows `mail.example.com`). Your own hosted domains go
+   * here.
+   */
+  allowDomains?: ReadonlyArray<string>;
+  /**
+   * Reject disposable/throwaway signups. Defaults to `true` — the whole point
+   * of the gate. Set `false` to classify-only (surface `emailClass` without
+   * blocking).
+   */
+  blockDisposable?: boolean;
+  /**
+   * Extra domains to treat as disposable (blocked when `blockDisposable`), on
+   * top of the built-in list. Wildcard/subdomain aware.
+   */
+  denyDomains?: ReadonlyArray<string>;
+  /**
+   * Reserved for callers that branch on free-vs-business (e.g. gate a feature
+   * behind a business email). Purely advisory — {@link EmailClassification}'s
+   * `emailClass` already reports `free`, so this flag exists for symmetry/intent
+   * and never blocks. Defaults to `false`.
+   */
+  flagFreeEmail?: boolean;
+  /**
+   * Opt-in MX deliverability verification. Off by default because it needs DNS
+   * (`@visulima/email-verifier/checks/mx` → `node:dns`), which is not available
+   * on the default workerd path. When `true`, {@link assertEmailAllowed} rejects
+   * an address whose domain publishes no MX (or fallback A/AAAA) records with
+   * `EMAIL_UNDELIVERABLE`. The check is loaded via a dynamic import, so leaving
+   * this off keeps the DNS module out of the bundle entirely.
+   */
+  mx?: boolean;
+  /**
+   * Reject structurally invalid addresses up front (via
+   * `@visulima/email-verifier/checks/syntax`, pure-data/edge-safe). Defaults to
+   * `true`. When `false`, an unparseable address classifies as `business` with
+   * `domain: undefined` and is not rejected on syntax alone.
+   */
+  requireValidSyntax?: boolean;
+}
+/** Options for {@link emailGateMiddleware}: the base gate config plus how to read the email from `ctx`. */
+interface EmailGateMiddlewareOptions<Context> extends EmailGateConfig {
+  /**
+   * Selector that pulls the signup email from `ctx`. The procedure context
+   * carries only the resolved identity, not the raw request body, so route the
+   * email through the function `args` and read it out here (mirrors
+   * `verifyTurnstileMiddleware`'s `token` selector).
+   */
+  email: (context: Context) => string | undefined;
+  /**
+   * Called with the resolved classification once the gate passes, so app policy
+   * can branch on `free` vs `business` (e.g. gate a plan behind a business
+   * email). Never fires when the gate rejects.
+   */
+  onClassify?: (classification: EmailClassification, context: Context) => void;
+}
+/**
+ * Inject the built-in disposable + free domain lists into the lookup packages,
+ * once. Call this at worker init on workerd (where the packages' `node:fs`
+ * loader is unavailable) so {@link classifyEmail} has data to match against;
+ * {@link assertEmailAllowed} / {@link emailGateMiddleware} await it for you, so
+ * the gating path is always edge-safe. Idempotent — repeat calls share one load.
+ */
+declare const loadEmailDomainLists: () => Promise<void>;
+/**
+ * Classify an email address' domain as `disposable` / `free` / `business`,
+ * pure-data and edge-safe (no DNS, no filesystem). A structurally invalid
+ * address resolves to `{ domain: undefined, emailClass: "business" }` — use
+ * {@link assertEmailAllowed} (which can reject on syntax) for the gating path.
+ * `allowDomains` wins over both lists; `denyDomains` adds to the disposable list.
+ *
+ * The lookup relies on the built-in domain lists being loaded. On Node they
+ * auto-load from disk; on workerd, `await loadEmailDomainLists()` first (or use
+ * {@link assertEmailAllowed} / {@link emailGateMiddleware}, which await it).
+ */
+declare const classifyEmail: (email: string, config?: EmailGateConfig) => EmailClassification;
+/**
+ * Classify `email` and enforce the gate, throwing a coded {@link LunoraError}
+ * when it fails: `VALIDATION_ERROR` (structurally invalid, only when
+ * `requireValidSyntax`, the default), `EMAIL_DOMAIN_BLOCKED` (disposable or
+ * deny-listed, only when `blockDisposable`, the default), or `EMAIL_UNDELIVERABLE`
+ * (no MX records, only when `mx: true`).
+ *
+ * Returns the {@link EmailClassification} on success so callers can branch on
+ * `free` vs `business`. Async only because of the opt-in MX step; with `mx` off
+ * it resolves without any network I/O.
+ */
+declare const assertEmailAllowed: (email: string, config?: EmailGateConfig) => Promise<EmailClassification>;
+/**
+ * Lunora procedure middleware that gates a non-auth, signup-shaped
+ * `mutation`/`action` on the email-domain policy. Attach it with `.use()`; it
+ * reads the email from `ctx` via the `email` selector (route it through `args`)
+ * and runs {@link assertEmailAllowed}, which throws a coded {@link LunoraError}
+ * (`EMAIL_DOMAIN_BLOCKED` / `EMAIL_UNDELIVERABLE` / `VALIDATION_ERROR`) the
+ * runtime maps to the matching status.
+ *
+ * To gate better-auth's native `/sign-up/email` endpoint instead, use
+ * `emailGateDatabaseHooks` / `withEmailGate` from `@lunora/auth` — those hook
+ * better-auth's own user-create path. The `Middleware` import is type-only, so
+ * this stays free of any runtime `@lunora/server` dependency.
+ */
+declare const emailGateMiddleware: <Context>(options: EmailGateMiddlewareOptions<Context>) => Middleware<Context, Context>;
+export { type EmailClass, type EmailClassification, type EmailGateConfig, type EmailGateMiddlewareOptions, assertEmailAllowed, classifyEmail, emailGateMiddleware, loadEmailDomainLists };

package/dist/email-guard.d.ts

@@ -0,0 +1,122 @@
+import { Middleware } from '@lunora/server';
+/**
+ * The resolved trust class of an email address' domain: `disposable` (a
+ * throwaway/temporary provider, or a caller `denyDomains` hit), `free` (a free
+ * consumer provider like Gmail — deliverable but not B2B), or `business`
+ * (anything else — a custom/company domain, or an `allowDomains` hit).
+ */
+type EmailClass = "business" | "disposable" | "free";
+/** Result of {@link classifyEmail} — the resolved class plus the normalized domain. */
+interface EmailClassification {
+  /** The normalized (lowercased, trimmed) domain, or `undefined` for a structurally invalid address. */
+  domain: string | undefined;
+  /** The resolved trust class. A structurally invalid address resolves to `business` with `domain: undefined`. */
+  emailClass: EmailClass;
+}
+/** Configuration for {@link classifyEmail} / {@link assertEmailAllowed} / {@link emailGateMiddleware}. */
+interface EmailGateConfig {
+  /**
+   * Domains that are always allowed and always classified `business`, even if
+   * they appear on the disposable or free lists. Wildcard/subdomain aware
+   * (`example.com` also allows `mail.example.com`). Your own hosted domains go
+   * here.
+   */
+  allowDomains?: ReadonlyArray<string>;
+  /**
+   * Reject disposable/throwaway signups. Defaults to `true` — the whole point
+   * of the gate. Set `false` to classify-only (surface `emailClass` without
+   * blocking).
+   */
+  blockDisposable?: boolean;
+  /**
+   * Extra domains to treat as disposable (blocked when `blockDisposable`), on
+   * top of the built-in list. Wildcard/subdomain aware.
+   */
+  denyDomains?: ReadonlyArray<string>;
+  /**
+   * Reserved for callers that branch on free-vs-business (e.g. gate a feature
+   * behind a business email). Purely advisory — {@link EmailClassification}'s
+   * `emailClass` already reports `free`, so this flag exists for symmetry/intent
+   * and never blocks. Defaults to `false`.
+   */
+  flagFreeEmail?: boolean;
+  /**
+   * Opt-in MX deliverability verification. Off by default because it needs DNS
+   * (`@visulima/email-verifier/checks/mx` → `node:dns`), which is not available
+   * on the default workerd path. When `true`, {@link assertEmailAllowed} rejects
+   * an address whose domain publishes no MX (or fallback A/AAAA) records with
+   * `EMAIL_UNDELIVERABLE`. The check is loaded via a dynamic import, so leaving
+   * this off keeps the DNS module out of the bundle entirely.
+   */
+  mx?: boolean;
+  /**
+   * Reject structurally invalid addresses up front (via
+   * `@visulima/email-verifier/checks/syntax`, pure-data/edge-safe). Defaults to
+   * `true`. When `false`, an unparseable address classifies as `business` with
+   * `domain: undefined` and is not rejected on syntax alone.
+   */
+  requireValidSyntax?: boolean;
+}
+/** Options for {@link emailGateMiddleware}: the base gate config plus how to read the email from `ctx`. */
+interface EmailGateMiddlewareOptions<Context> extends EmailGateConfig {
+  /**
+   * Selector that pulls the signup email from `ctx`. The procedure context
+   * carries only the resolved identity, not the raw request body, so route the
+   * email through the function `args` and read it out here (mirrors
+   * `verifyTurnstileMiddleware`'s `token` selector).
+   */
+  email: (context: Context) => string | undefined;
+  /**
+   * Called with the resolved classification once the gate passes, so app policy
+   * can branch on `free` vs `business` (e.g. gate a plan behind a business
+   * email). Never fires when the gate rejects.
+   */
+  onClassify?: (classification: EmailClassification, context: Context) => void;
+}
+/**
+ * Inject the built-in disposable + free domain lists into the lookup packages,
+ * once. Call this at worker init on workerd (where the packages' `node:fs`
+ * loader is unavailable) so {@link classifyEmail} has data to match against;
+ * {@link assertEmailAllowed} / {@link emailGateMiddleware} await it for you, so
+ * the gating path is always edge-safe. Idempotent — repeat calls share one load.
+ */
+declare const loadEmailDomainLists: () => Promise<void>;
+/**
+ * Classify an email address' domain as `disposable` / `free` / `business`,
+ * pure-data and edge-safe (no DNS, no filesystem). A structurally invalid
+ * address resolves to `{ domain: undefined, emailClass: "business" }` — use
+ * {@link assertEmailAllowed} (which can reject on syntax) for the gating path.
+ * `allowDomains` wins over both lists; `denyDomains` adds to the disposable list.
+ *
+ * The lookup relies on the built-in domain lists being loaded. On Node they
+ * auto-load from disk; on workerd, `await loadEmailDomainLists()` first (or use
+ * {@link assertEmailAllowed} / {@link emailGateMiddleware}, which await it).
+ */
+declare const classifyEmail: (email: string, config?: EmailGateConfig) => EmailClassification;
+/**
+ * Classify `email` and enforce the gate, throwing a coded {@link LunoraError}
+ * when it fails: `VALIDATION_ERROR` (structurally invalid, only when
+ * `requireValidSyntax`, the default), `EMAIL_DOMAIN_BLOCKED` (disposable or
+ * deny-listed, only when `blockDisposable`, the default), or `EMAIL_UNDELIVERABLE`
+ * (no MX records, only when `mx: true`).
+ *
+ * Returns the {@link EmailClassification} on success so callers can branch on
+ * `free` vs `business`. Async only because of the opt-in MX step; with `mx` off
+ * it resolves without any network I/O.
+ */
+declare const assertEmailAllowed: (email: string, config?: EmailGateConfig) => Promise<EmailClassification>;
+/**
+ * Lunora procedure middleware that gates a non-auth, signup-shaped
+ * `mutation`/`action` on the email-domain policy. Attach it with `.use()`; it
+ * reads the email from `ctx` via the `email` selector (route it through `args`)
+ * and runs {@link assertEmailAllowed}, which throws a coded {@link LunoraError}
+ * (`EMAIL_DOMAIN_BLOCKED` / `EMAIL_UNDELIVERABLE` / `VALIDATION_ERROR`) the
+ * runtime maps to the matching status.
+ *
+ * To gate better-auth's native `/sign-up/email` endpoint instead, use
+ * `emailGateDatabaseHooks` / `withEmailGate` from `@lunora/auth` — those hook
+ * better-auth's own user-create path. The `Middleware` import is type-only, so
+ * this stays free of any runtime `@lunora/server` dependency.
+ */
+declare const emailGateMiddleware: <Context>(options: EmailGateMiddlewareOptions<Context>) => Middleware<Context, Context>;
+export { type EmailClass, type EmailClassification, type EmailGateConfig, type EmailGateMiddlewareOptions, assertEmailAllowed, classifyEmail, emailGateMiddleware, loadEmailDomainLists };

package/dist/email-guard.mjs

@@ -0,0 +1,71 @@
+import { LunoraError } from '@lunora/errors';
+import { isDisposableDomain, setDomains } from '@visulima/disposable-email-domains';
+import { extractDomain, isFreeDomain, setDomains as setDomains$1 } from '@visulima/free-email-domains';
+
+const listFromModule = (module) => {
+  const value = module.default ?? module;
+  return Array.isArray(value) ? value : [];
+};
+let listsPromise;
+const loadEmailDomainLists = async () => {
+  listsPromise ??= (async () => {
+    const [disposable, free] = await Promise.all([import('@visulima/disposable-email-domains/domains'), import('@visulima/free-email-domains/domains')]);
+    setDomains(listFromModule(disposable));
+    setDomains$1(listFromModule(free));
+  })();
+  return listsPromise;
+};
+const toDomainSet = (domains) => domains && domains.length > 0 ? new Set(domains.map((domain) => domain.toLowerCase())) : void 0;
+const classifyEmail = (email, config = {}) => {
+  const domain = extractDomain(email);
+  if (domain === void 0) {
+    return { domain: void 0, emailClass: "business" };
+  }
+  const allowDomains = toDomainSet(config.allowDomains);
+  if (isDisposableDomain(domain, { allowDomains, customDomains: toDomainSet(config.denyDomains) })) {
+    return { domain, emailClass: "disposable" };
+  }
+  if (isFreeDomain(domain, { allowDomains })) {
+    return { domain, emailClass: "free" };
+  }
+  return { domain, emailClass: "business" };
+};
+const verifyMx = async (domain) => {
+  const { checkMxRecords } = await import('@visulima/email-verifier/checks/mx');
+  const result = await checkMxRecords(domain);
+  return result.valid;
+};
+const assertEmailAllowed = async (email, config = {}) => {
+  if (config.requireValidSyntax !== false) {
+    const { validateSyntax } = await import('@visulima/email-verifier/checks/syntax');
+    if (!validateSyntax(email)) {
+      throw new LunoraError("VALIDATION_ERROR", `@lunora/auth: "${email}" is not a valid email address.`);
+    }
+  }
+  await loadEmailDomainLists();
+  const classification = classifyEmail(email, config);
+  if (classification.emailClass === "disposable" && config.blockDisposable !== false) {
+    throw new LunoraError(
+      "EMAIL_DOMAIN_BLOCKED",
+      `@lunora/auth: signups from the disposable/throwaway domain "${classification.domain ?? email}" are not allowed.`
+    );
+  }
+  if (config.mx === true && classification.domain !== void 0 && !await verifyMx(classification.domain)) {
+    throw new LunoraError(
+      "EMAIL_UNDELIVERABLE",
+      `@lunora/auth: the domain "${classification.domain}" publishes no MX records, so mail to it cannot be delivered.`
+    );
+  }
+  return classification;
+};
+const emailGateMiddleware = (options) => async ({ ctx, next }) => {
+  const email = options.email(ctx);
+  if (email === void 0 || email === "") {
+    throw new LunoraError("VALIDATION_ERROR", "@lunora/auth: emailGateMiddleware received no email to check.");
+  }
+  const classification = await assertEmailAllowed(email, options);
+  options.onClassify?.(classification, ctx);
+  return next();
+};
+
+export { assertEmailAllowed, classifyEmail, emailGateMiddleware, loadEmailDomainLists };

package/dist/index.d.mts

@@ -2,10 +2,16 @@ export { lunoraAuthAdapter, lunoraD1Adapter } from "./adapter.mjs";
 import { LunoraError } from '@lunora/errors';
 import { L as LunoraAuth, a as LunoraAuthOptions } from "./packem_shared/create-auth.d-COcIS_KU.mjs";
 export { c as createAuth, r as resolveAuthOptions } from "./packem_shared/create-auth.d-COcIS_KU.mjs";
+import { AppendAuthAuditEntry, AppendAuthAuditOptions, AuthAuditEvent } from "./audit.mjs";
+export { AUTH_AUDIT_TABLE, type AuthAuditEntry, type AuthAuditOutcome, type AuthAuditReader, type ReadAuthAuditOptions, appendAuthAuditEntry, createAuthAuditReader, ensureAuthAuditTable, readAuthAuditLog } from "./audit.mjs";
+import { createAuthMiddleware } from 'better-auth/api';
+import { SqlExecutor } from "./sql-store.mjs";
+export { createSqlAuthStore, d1Executor } from "./sql-store.mjs";
+import { BetterAuthOptions } from 'better-auth';
+import { EmailClassification, EmailGateConfig } from "./email-guard.mjs";
+export { type EmailClass, type EmailGateMiddlewareOptions, assertEmailAllowed, classifyEmail, emailGateMiddleware, loadEmailDomainLists } from "./email-guard.mjs";
 export { type LunoraAuthApiContext, LunoraAuthHeadersError, type WithAuthPluginsMiddleware, type WithAuthPluginsOptions, withAuthPlugins } from "./middleware.mjs";
 export { default as authTables } from "./schema.mjs";
-import { BetterAuthOptions } from 'better-auth';
-export { type SqlExecutor, createSqlAuthStore, d1Executor } from "./sql-store.mjs";
 export { type AuthQuery, type AuthRow, type AuthStore, type AuthWhereClause, createMemoryAuthStore, matchesWhere } from "./store.mjs";
 export { type FetchLike, TURNSTILE_VERIFY_ENDPOINT, type TurnstileVerifyResult, type VerifyTurnstileOptions, verifyTurnstile } from "./turnstile.mjs";
 export { type VerifyTurnstileMiddlewareOptions, verifyTurnstileMiddleware } from "./turnstile-middleware.mjs";
@@ -480,6 +486,121 @@ declare class LunoraAuthAdminError extends LunoraError {
  * config, etc. lazily); we memoize it so the first call pays the cost once.
  */
 declare const createAuthAdmin: (auth: LunoraAuth, options?: CreateAuthAdminOptions) => AuthAdmin;
+/** Configuration for {@link authAuditHook}. */
+interface AuthAuditHookConfig extends AppendAuthAuditOptions {
+  /**
+   * Where to persist the trail — the same {@link SqlExecutor} seam better-auth's
+   * store rides (`d1Executor(env.DB)`), so events land in the auth D1 database.
+   */
+  executor: SqlExecutor;
+  /**
+   * Optional export tap (pairs with SIEM forwarding): called with each redacted
+   * entry right after it is persisted, so a deployment can fan events out to an
+   * external sink. Rejections/throws are swallowed so forwarding can't break an
+   * auth request.
+   */
+  onRecord?: (entry: AppendAuthAuditEntry) => Promise<void> | void;
+}
+/** Structural view of the fields we read off better-auth's after-hook context — kept loose to avoid coupling to internal types. */
+interface AuditHookContext {
+  context?: {
+    newSession?: {
+      session?: {
+        userId?: string;
+      };
+      user?: {
+        email?: string;
+        id?: string;
+      };
+    } | null;
+    returned?: unknown;
+    session?: {
+      session?: {
+        userId?: string;
+      };
+      user?: {
+        email?: string;
+        id?: string;
+      };
+    } | null;
+  };
+  headers?: Headers;
+  path?: string;
+  request?: Request;
+}
+/**
+ * Map a better-auth endpoint path to the security event it represents, or
+ * `undefined` for endpoints not worth auditing (session reads, config, …). Match
+ * is by suffix so a caller `basePath` prefix (`/api/auth`) never affects it.
+ */
+declare const eventForPath: (path: string) => AuthAuditEvent | undefined;
+/**
+ * Build the entry a given after-hook context should record, or `undefined` when
+ * the path is not an audited security event. Exported for direct unit testing of
+ * the classification/extraction without spinning up better-auth.
+ */
+declare const buildAuditEntry: (context: AuditHookContext, now?: number) => AppendAuthAuditEntry | undefined;
+/**
+ * Create the better-auth `hooks.after` middleware that records the auth/security
+ * audit trail. Assign it to `hooks.after` (or compose via {@link withAuthAudit}).
+ *
+ * ```ts
+ * const auth = createAuth({
+ *     secret: env.AUTH_SECRET,
+ *     database: lunoraD1Adapter(env.DB),
+ *     hooks: { after: authAuditHook({ executor: d1Executor(env.DB), retention: 100_000 }) },
+ * });
+ * ```
+ */
+declare const authAuditHook: (config: AuthAuditHookConfig) => ReturnType<typeof createAuthMiddleware>;
+/**
+ * Merge the audit `hooks.after` middleware into a better-auth options object,
+ * composing with any `hooks.after` the caller already set (theirs runs first,
+ * then the audit record). Returns a new options object.
+ */
+declare const withAuthAudit: <Options extends {
+  hooks?: {
+    after?: unknown;
+  };
+}>(options: Options, config: AuthAuditHookConfig) => Options;
+/** better-auth's `databaseHooks` shape, derived so a rename upstream fails to compile rather than silently mis-hooking. */
+type DatabaseHooks = NonNullable<BetterAuthOptions["databaseHooks"]>;
+/** Config for the signup gate hooks: the base {@link EmailGateConfig} plus an optional classification tap. */
+interface EmailGateHookConfig extends EmailGateConfig {
+  /**
+   * Called with the resolved classification once the gate passes, so app policy
+   * can react to `free` vs `business` at signup (e.g. tag the account). Never
+   * fires when the gate rejects. `context` is better-auth's endpoint context
+   * (`null` outside a request, e.g. an internal create).
+   */
+  onClassify?: (classification: EmailClassification, user: Record<string, unknown>, context: unknown) => void;
+}
+/**
+ * Produce a `databaseHooks` fragment that gates better-auth's native signup on
+ * the email-domain policy. Spread it into `createAuth({ databaseHooks: … })`, or
+ * use {@link withEmailGate} to merge it (composing with any existing
+ * `user.create.before`).
+ *
+ * ```ts
+ * const auth = createAuth({
+ *     secret: env.AUTH_SECRET,
+ *     database: lunoraD1Adapter(env.DB),
+ *     databaseHooks: emailGateDatabaseHooks({ blockDisposable: true }),
+ * });
+ * ```
+ */
+declare const emailGateDatabaseHooks: (config?: EmailGateHookConfig) => DatabaseHooks;
+/**
+ * Merge the email-domain signup gate into an existing better-auth options object,
+ * preserving any `databaseHooks` the caller already set. If they already declared
+ * a `user.create.before`, the gate runs first (rejecting disposable signups
+ * before their hook sees them), then theirs runs on the (possibly rewritten) user.
+ *
+ * ```ts
+ * const auth = createAuth(withEmailGate({ secret, database }, { blockDisposable: true }));
+ * ```
+ */
+declare const withEmailGate: (options: BetterAuthOptions, config?: EmailGateHookConfig) => BetterAuthOptions;
 /**
  * Default basePath used by better-auth's client + handler. Override via the
  * second argument if you mount the auth routes somewhere else.
@@ -576,4 +697,4 @@ declare const validateSessionPolicy: (policy: SessionPolicy) => SessionPolicy;
  *   with the same 60s cookie cache as `rolling`.
  */
 declare const sessionPresets: Record<"longLived" | "rolling" | "strict", SessionPolicy>;
-export { type AuthAccount, type AuthAdmin, type AuthAdminSession, type AuthAdminUser, type AuthCapabilities, type AuthConfigInfo, type AuthInvitation, type AuthMember, type AuthOrgRole, type AuthOrganization, type AuthPage, type AuthPasskey, type AuthTeam, type AuthTeamMember, type AuthTimestamp, type AuthUserFieldSpec, type CreateAuthAdminOptions, DEFAULT_AUTH_BASE_PATH, type ImpersonationResult, type ListUsersOptions, type LunoraAuth, LunoraAuthAdminError, type LunoraAuthOptions, type SessionPolicy, compileMigrationsSql, createAuthAdmin, ensureMigrated, handleAuthRequest, sessionPresets, validateSessionPolicy };
+export { type AppendAuthAuditEntry, type AppendAuthAuditOptions, type AuthAccount, type AuthAdmin, type AuthAdminSession, type AuthAdminUser, type AuthAuditEvent, type AuthAuditHookConfig, type AuthCapabilities, type AuthConfigInfo, type AuthInvitation, type AuthMember, type AuthOrgRole, type AuthOrganization, type AuthPage, type AuthPasskey, type AuthTeam, type AuthTeamMember, type AuthTimestamp, type AuthUserFieldSpec, type CreateAuthAdminOptions, DEFAULT_AUTH_BASE_PATH, type EmailClassification, type EmailGateConfig, type EmailGateHookConfig, type ImpersonationResult, type ListUsersOptions, type LunoraAuth, LunoraAuthAdminError, type LunoraAuthOptions, type SessionPolicy, type SqlExecutor, authAuditHook, buildAuditEntry, compileMigrationsSql, createAuthAdmin, emailGateDatabaseHooks, ensureMigrated, eventForPath, handleAuthRequest, sessionPresets, validateSessionPolicy, withAuthAudit, withEmailGate };

package/dist/index.d.ts

@@ -2,10 +2,16 @@ export { lunoraAuthAdapter, lunoraD1Adapter } from "./adapter.js";
 import { LunoraError } from '@lunora/errors';
 import { L as LunoraAuth, a as LunoraAuthOptions } from "./packem_shared/create-auth.d-COcIS_KU.js";
 export { c as createAuth, r as resolveAuthOptions } from "./packem_shared/create-auth.d-COcIS_KU.js";
+import { AppendAuthAuditEntry, AppendAuthAuditOptions, AuthAuditEvent } from "./audit.js";
+export { AUTH_AUDIT_TABLE, type AuthAuditEntry, type AuthAuditOutcome, type AuthAuditReader, type ReadAuthAuditOptions, appendAuthAuditEntry, createAuthAuditReader, ensureAuthAuditTable, readAuthAuditLog } from "./audit.js";
+import { createAuthMiddleware } from 'better-auth/api';
+import { SqlExecutor } from "./sql-store.js";
+export { createSqlAuthStore, d1Executor } from "./sql-store.js";
+import { BetterAuthOptions } from 'better-auth';
+import { EmailClassification, EmailGateConfig } from "./email-guard.js";
+export { type EmailClass, type EmailGateMiddlewareOptions, assertEmailAllowed, classifyEmail, emailGateMiddleware, loadEmailDomainLists } from "./email-guard.js";
 export { type LunoraAuthApiContext, LunoraAuthHeadersError, type WithAuthPluginsMiddleware, type WithAuthPluginsOptions, withAuthPlugins } from "./middleware.js";
 export { default as authTables } from "./schema.js";
-import { BetterAuthOptions } from 'better-auth';
-export { type SqlExecutor, createSqlAuthStore, d1Executor } from "./sql-store.js";
 export { type AuthQuery, type AuthRow, type AuthStore, type AuthWhereClause, createMemoryAuthStore, matchesWhere } from "./store.js";
 export { type FetchLike, TURNSTILE_VERIFY_ENDPOINT, type TurnstileVerifyResult, type VerifyTurnstileOptions, verifyTurnstile } from "./turnstile.js";
 export { type VerifyTurnstileMiddlewareOptions, verifyTurnstileMiddleware } from "./turnstile-middleware.js";
@@ -480,6 +486,121 @@ declare class LunoraAuthAdminError extends LunoraError {
  * config, etc. lazily); we memoize it so the first call pays the cost once.
  */
 declare const createAuthAdmin: (auth: LunoraAuth, options?: CreateAuthAdminOptions) => AuthAdmin;
+/** Configuration for {@link authAuditHook}. */
+interface AuthAuditHookConfig extends AppendAuthAuditOptions {
+  /**
+   * Where to persist the trail — the same {@link SqlExecutor} seam better-auth's
+   * store rides (`d1Executor(env.DB)`), so events land in the auth D1 database.
+   */
+  executor: SqlExecutor;
+  /**
+   * Optional export tap (pairs with SIEM forwarding): called with each redacted
+   * entry right after it is persisted, so a deployment can fan events out to an
+   * external sink. Rejections/throws are swallowed so forwarding can't break an
+   * auth request.
+   */
+  onRecord?: (entry: AppendAuthAuditEntry) => Promise<void> | void;
+}
+/** Structural view of the fields we read off better-auth's after-hook context — kept loose to avoid coupling to internal types. */
+interface AuditHookContext {
+  context?: {
+    newSession?: {
+      session?: {
+        userId?: string;
+      };
+      user?: {
+        email?: string;
+        id?: string;
+      };
+    } | null;
+    returned?: unknown;
+    session?: {
+      session?: {
+        userId?: string;
+      };
+      user?: {
+        email?: string;
+        id?: string;
+      };
+    } | null;
+  };
+  headers?: Headers;
+  path?: string;
+  request?: Request;
+}
+/**
+ * Map a better-auth endpoint path to the security event it represents, or
+ * `undefined` for endpoints not worth auditing (session reads, config, …). Match
+ * is by suffix so a caller `basePath` prefix (`/api/auth`) never affects it.
+ */
+declare const eventForPath: (path: string) => AuthAuditEvent | undefined;
+/**
+ * Build the entry a given after-hook context should record, or `undefined` when
+ * the path is not an audited security event. Exported for direct unit testing of
+ * the classification/extraction without spinning up better-auth.
+ */
+declare const buildAuditEntry: (context: AuditHookContext, now?: number) => AppendAuthAuditEntry | undefined;
+/**
+ * Create the better-auth `hooks.after` middleware that records the auth/security
+ * audit trail. Assign it to `hooks.after` (or compose via {@link withAuthAudit}).
+ *
+ * ```ts
+ * const auth = createAuth({
+ *     secret: env.AUTH_SECRET,
+ *     database: lunoraD1Adapter(env.DB),
+ *     hooks: { after: authAuditHook({ executor: d1Executor(env.DB), retention: 100_000 }) },
+ * });
+ * ```
+ */
+declare const authAuditHook: (config: AuthAuditHookConfig) => ReturnType<typeof createAuthMiddleware>;
+/**
+ * Merge the audit `hooks.after` middleware into a better-auth options object,
+ * composing with any `hooks.after` the caller already set (theirs runs first,
+ * then the audit record). Returns a new options object.
+ */
+declare const withAuthAudit: <Options extends {
+  hooks?: {
+    after?: unknown;
+  };
+}>(options: Options, config: AuthAuditHookConfig) => Options;
+/** better-auth's `databaseHooks` shape, derived so a rename upstream fails to compile rather than silently mis-hooking. */
+type DatabaseHooks = NonNullable<BetterAuthOptions["databaseHooks"]>;
+/** Config for the signup gate hooks: the base {@link EmailGateConfig} plus an optional classification tap. */
+interface EmailGateHookConfig extends EmailGateConfig {
+  /**
+   * Called with the resolved classification once the gate passes, so app policy
+   * can react to `free` vs `business` at signup (e.g. tag the account). Never
+   * fires when the gate rejects. `context` is better-auth's endpoint context
+   * (`null` outside a request, e.g. an internal create).
+   */
+  onClassify?: (classification: EmailClassification, user: Record<string, unknown>, context: unknown) => void;
+}
+/**
+ * Produce a `databaseHooks` fragment that gates better-auth's native signup on
+ * the email-domain policy. Spread it into `createAuth({ databaseHooks: … })`, or
+ * use {@link withEmailGate} to merge it (composing with any existing
+ * `user.create.before`).
+ *
+ * ```ts
+ * const auth = createAuth({
+ *     secret: env.AUTH_SECRET,
+ *     database: lunoraD1Adapter(env.DB),
+ *     databaseHooks: emailGateDatabaseHooks({ blockDisposable: true }),
+ * });
+ * ```
+ */
+declare const emailGateDatabaseHooks: (config?: EmailGateHookConfig) => DatabaseHooks;
+/**
+ * Merge the email-domain signup gate into an existing better-auth options object,
+ * preserving any `databaseHooks` the caller already set. If they already declared
+ * a `user.create.before`, the gate runs first (rejecting disposable signups
+ * before their hook sees them), then theirs runs on the (possibly rewritten) user.
+ *
+ * ```ts
+ * const auth = createAuth(withEmailGate({ secret, database }, { blockDisposable: true }));
+ * ```
+ */
+declare const withEmailGate: (options: BetterAuthOptions, config?: EmailGateHookConfig) => BetterAuthOptions;
 /**
  * Default basePath used by better-auth's client + handler. Override via the
  * second argument if you mount the auth routes somewhere else.
@@ -576,4 +697,4 @@ declare const validateSessionPolicy: (policy: SessionPolicy) => SessionPolicy;
  *   with the same 60s cookie cache as `rolling`.
  */
 declare const sessionPresets: Record<"longLived" | "rolling" | "strict", SessionPolicy>;
-export { type AuthAccount, type AuthAdmin, type AuthAdminSession, type AuthAdminUser, type AuthCapabilities, type AuthConfigInfo, type AuthInvitation, type AuthMember, type AuthOrgRole, type AuthOrganization, type AuthPage, type AuthPasskey, type AuthTeam, type AuthTeamMember, type AuthTimestamp, type AuthUserFieldSpec, type CreateAuthAdminOptions, DEFAULT_AUTH_BASE_PATH, type ImpersonationResult, type ListUsersOptions, type LunoraAuth, LunoraAuthAdminError, type LunoraAuthOptions, type SessionPolicy, compileMigrationsSql, createAuthAdmin, ensureMigrated, handleAuthRequest, sessionPresets, validateSessionPolicy };
+export { type AppendAuthAuditEntry, type AppendAuthAuditOptions, type AuthAccount, type AuthAdmin, type AuthAdminSession, type AuthAdminUser, type AuthAuditEvent, type AuthAuditHookConfig, type AuthCapabilities, type AuthConfigInfo, type AuthInvitation, type AuthMember, type AuthOrgRole, type AuthOrganization, type AuthPage, type AuthPasskey, type AuthTeam, type AuthTeamMember, type AuthTimestamp, type AuthUserFieldSpec, type CreateAuthAdminOptions, DEFAULT_AUTH_BASE_PATH, type EmailClassification, type EmailGateConfig, type EmailGateHookConfig, type ImpersonationResult, type ListUsersOptions, type LunoraAuth, LunoraAuthAdminError, type LunoraAuthOptions, type SessionPolicy, type SqlExecutor, authAuditHook, buildAuditEntry, compileMigrationsSql, createAuthAdmin, emailGateDatabaseHooks, ensureMigrated, eventForPath, handleAuthRequest, sessionPresets, validateSessionPolicy, withAuthAudit, withEmailGate };

package/dist/index.mjs

@@ -1,6 +1,10 @@
 export { lunoraAuthAdapter, lunoraD1Adapter } from './adapter.mjs';
 export { LunoraAuthAdminError, createAuthAdmin } from './packem_shared/LunoraAuthAdminError-CReJPMkx.mjs';
+export { AUTH_AUDIT_TABLE, appendAuthAuditEntry, createAuthAuditReader, ensureAuthAuditTable, readAuthAuditLog } from './audit.mjs';
+export { authAuditHook, buildAuditEntry, eventForPath, withAuthAudit } from './packem_shared/authAuditHook-3OJKhpQV.mjs';
 export { createAuth, resolveAuthOptions } from './packem_shared/createAuth-s4i7WhAh.mjs';
+export { emailGateDatabaseHooks, withEmailGate } from './packem_shared/emailGateDatabaseHooks-BGS4uJM9.mjs';
+export { assertEmailAllowed, classifyEmail, emailGateMiddleware, loadEmailDomainLists } from './email-guard.mjs';
 export { DEFAULT_AUTH_BASE_PATH, handleAuthRequest } from './packem_shared/DEFAULT_AUTH_BASE_PATH-DjcUWEQl.mjs';
 export { LunoraAuthHeadersError, withAuthPlugins } from './middleware.mjs';
 export { compileMigrationsSql, ensureMigrated } from './packem_shared/compileMigrationsSql-Dl5N8z5q.mjs';

package/dist/packem_shared/authAuditHook-3OJKhpQV.mjs

@@ -0,0 +1,119 @@
+import { createAuthMiddleware } from 'better-auth/api';
+import { appendAuthAuditEntry } from '../audit.mjs';
+
+const eventForPath = (path) => {
+  const normalized = path.toLowerCase();
+  const ends = (suffix) => normalized === suffix || normalized.endsWith(suffix);
+  if (ends("/sign-up/email") || ends("/sign-up")) {
+    return "sign-up";
+  }
+  if (normalized.includes("/sign-in/")) {
+    return "sign-in";
+  }
+  if (ends("/sign-out")) {
+    return "sign-out";
+  }
+  if (ends("/change-password") || ends("/set-password")) {
+    return "password-change";
+  }
+  if (ends("/reset-password") || ends("/request-password-reset") || ends("/forget-password")) {
+    return "password-reset";
+  }
+  if (ends("/verify-email")) {
+    return "email-verification";
+  }
+  if (normalized.includes("/two-factor/enable") || normalized.includes("/totp/enable")) {
+    return "mfa-enable";
+  }
+  if (normalized.includes("/two-factor/disable") || normalized.includes("/totp/disable")) {
+    return "mfa-disable";
+  }
+  if (ends("/refresh-token") || ends("/token")) {
+    return "token-refresh";
+  }
+  if (ends("/revoke-session") || ends("/revoke-sessions") || ends("/revoke-other-sessions")) {
+    return "session-revoke";
+  }
+  if (ends("/link-social")) {
+    return "account-link";
+  }
+  if (ends("/unlink-account")) {
+    return "account-unlink";
+  }
+  return void 0;
+};
+const header = (context, name) => {
+  const value = context.headers?.get(name) ?? context.request?.headers.get(name);
+  return value ?? void 0;
+};
+const resolveIp = (context) => {
+  const forwarded = header(context, "x-forwarded-for");
+  return header(context, "cf-connecting-ip") ?? (forwarded === void 0 ? void 0 : forwarded.split(",")[0]?.trim()) ?? header(context, "x-real-ip");
+};
+const resolveActor = (context) => {
+  const source = context.context?.newSession ?? context.context?.session;
+  const actorId = source?.user?.id ?? source?.session?.userId;
+  const actorEmail = source?.user?.email;
+  return {
+    ...actorId === void 0 ? {} : { actorId },
+    ...actorEmail === void 0 ? {} : { actorEmail }
+  };
+};
+const resolveOutcome = (context) => {
+  const returned = context.context?.returned;
+  if (returned instanceof Error) {
+    return "failure";
+  }
+  if (typeof returned === "object" && returned !== null && "status" in returned) {
+    const status = Number(returned.status);
+    if (Number.isFinite(status) && status >= 400) {
+      return "failure";
+    }
+  }
+  return "success";
+};
+const buildAuditEntry = (context, now = Date.now()) => {
+  const event = context.path === void 0 ? void 0 : eventForPath(context.path);
+  if (event === void 0) {
+    return void 0;
+  }
+  const ip = resolveIp(context);
+  const userAgent = header(context, "user-agent");
+  return {
+    ...resolveActor(context),
+    event,
+    outcome: resolveOutcome(context),
+    ts: now,
+    ...ip === void 0 ? {} : { ip },
+    ...userAgent === void 0 ? {} : { userAgent },
+    detail: { path: context.path }
+  };
+};
+const authAuditHook = (config) => createAuthMiddleware(async (context) => {
+  try {
+    const entry = buildAuditEntry(context);
+    if (entry !== void 0) {
+      const persisted = await appendAuthAuditEntry(config.executor, entry, {
+        redactDetail: config.redactDetail,
+        retention: config.retention
+      });
+      if (config.onRecord !== void 0) {
+        await config.onRecord(persisted);
+      }
+    }
+  } catch (error) {
+    console.error("@lunora/auth: audit hook failed to record event", error);
+  }
+  return {};
+});
+const withAuthAudit = (options, config) => {
+  const audit = authAuditHook(config);
+  const existing = options.hooks?.after;
+  const after = existing ? async (context) => {
+    await existing(context);
+    return audit(context);
+  } : audit;
+  return { ...options, hooks: { ...options.hooks, after } };
+};
+
+export { authAuditHook, buildAuditEntry, eventForPath, withAuthAudit };

package/dist/packem_shared/emailGateDatabaseHooks-BGS4uJM9.mjs

@@ -0,0 +1,64 @@
+import { LunoraError } from '@lunora/errors';
+import { APIError } from 'better-auth/api';
+import { assertEmailAllowed } from '../email-guard.mjs';
+
+const statusString = (status) => {
+  switch (status) {
+    case 400: {
+      return "BAD_REQUEST";
+    }
+    case 422: {
+      return "UNPROCESSABLE_ENTITY";
+    }
+    case 429: {
+      return "TOO_MANY_REQUESTS";
+    }
+    default: {
+      return "INTERNAL_SERVER_ERROR";
+    }
+  }
+};
+const buildBeforeHook = (config) => async (user, context) => {
+  const email = typeof user.email === "string" ? user.email : void 0;
+  if (email === void 0 || email === "") {
+    return;
+  }
+  let classification;
+  try {
+    classification = await assertEmailAllowed(email, config);
+  } catch (error) {
+    if (error instanceof LunoraError) {
+      throw new APIError(statusString(error.status), { code: error.code, message: error.message });
+    }
+    throw error;
+  }
+  config.onClassify?.(classification, user, context);
+};
+const emailGateDatabaseHooks = (config = {}) => {
+  return {
+    user: { create: { before: buildBeforeHook(config) } }
+  };
+};
+const withEmailGate = (options, config = {}) => {
+  const gate = buildBeforeHook(config);
+  const existing = options.databaseHooks?.user?.create?.before;
+  const before = existing ? async (user, context) => {
+    await gate(user, context);
+    return existing(user, context);
+  } : gate;
+  return {
+    ...options,
+    databaseHooks: {
+      ...options.databaseHooks,
+      user: {
+        ...options.databaseHooks?.user,
+        create: {
+          ...options.databaseHooks?.user?.create,
+          before
+        }
+      }
+    }
+  };
+};
+
+export { emailGateDatabaseHooks, withEmailGate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/auth",
-  "version": "1.0.0-alpha.34",
+  "version": "1.0.0-alpha.36",
   "description": "Auth for Lunora — a thin better-auth wrapper: email/password, OAuth, plugins, D1-backed",
   "keywords": [
     "auth",
@@ -52,6 +52,14 @@
       "types": "./dist/middleware.d.ts",
       "import": "./dist/middleware.mjs"
     },
+    "./audit": {
+      "types": "./dist/audit.d.ts",
+      "import": "./dist/audit.mjs"
+    },
+    "./email-guard": {
+      "types": "./dist/email-guard.d.ts",
+      "import": "./dist/email-guard.mjs"
+    },
     "./turnstile": {
       "types": "./dist/turnstile.d.ts",
       "import": "./dist/turnstile.mjs"
@@ -83,9 +91,13 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.6.23",
-    "@lunora/errors": "1.0.0-alpha.6",
-    "@lunora/server": "1.0.0-alpha.28",
-    "@lunora/values": "1.0.0-alpha.9",
+    "@lunora/errors": "1.0.0-alpha.7",
+    "@lunora/server": "1.0.0-alpha.30",
+    "@lunora/values": "1.0.0-alpha.10",
+    "@visulima/disposable-email-domains": "1.0.1",
+    "@visulima/email-verifier": "1.0.1",
+    "@visulima/free-email-domains": "1.0.0",
+    "@visulima/redact": "3.0.0",
     "better-auth": "^1.6.23"
   },
   "engines": {