@lunora/auth 1.0.0-alpha.6 → 1.0.0-alpha.61

package/LICENSE.md

@@ -103,3 +103,41 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+
+# Licenses of bundled types
+The published @lunora/auth artifact additionally contains code with the following licenses:
+MIT
+
+# Bundled types:
+## @better-auth/sso
+License: MIT
+By: Bereket Engida
+Repository: git+https://github.com/better-auth/better-auth.git
+
+> The MIT License (MIT)
+> Copyright (c) 2024 - present, Bereket Engida
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy of
+> this software and associated documentation files (the “Software”), to deal in
+> the Software without restriction, including without limitation the rights to
+> use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+> the Software, and to permit persons to whom the Software is furnished to do so,
+> subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+> FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+> IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+> DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+> ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+> DEALINGS IN THE SOFTWARE.
+
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -84,10 +84,65 @@ The runtime resolves the inbound session and stamps `ctx.auth` on every `query`
 
 ### Plugins & CAPTCHA
 
-better-auth's plugin factories are re-exported from `@lunora/auth/plugins` (so you don't need better-auth's deep import paths): `admin`, `anonymous`, `bearer`, `captcha`, `createAccessControl`, `customSession`, `deviceAuthorization`, `emailOTP`, `genericOAuth`, `haveIBeenPwned`, `jwt`, `magicLink`, `mcp`, `multiSession`, `oAuthProxy`, `oidcProvider`, `oneTimeToken`, `organization`, `passkey`, `phoneNumber`, `siwe`, `twoFactor`, `username`, and `withMcpAuth`.
+better-auth's plugin factories are re-exported from `@lunora/auth/plugins` (so you don't need better-auth's deep import paths): `admin`, `anonymous`, `bearer`, `captcha`, `createAccessControl`, `customSession`, `deviceAuthorization`, `emailOTP`, `genericOAuth`, `haveIBeenPwned`, `jwt`, `magicLink`, `mcp`, `mcpHandler`, `multiSession`, `oAuthProxy`, `oauthProvider`, `oneTimeToken`, `organization`, `passkey`, `phoneNumber`, `requireMcpAuth`, `scim`, `siwe`, `twoFactor`, and `username`. Enterprise SSO ships separately as `sso` from `@lunora/auth/plugins/enterprise` (an optional peer — see the docs).
 
 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/adapter.d.mts

@@ -1,43 +1,4 @@
-import { createAdapterFactory } from 'better-auth/adapters';
-import { d1Executor } from "./sql-store.mjs";
-import { AuthStore } from "./store.mjs";
-/**
-* A better-auth database adapter backed by an {@link AuthStore} — the bridge
-* that routes better-auth's reads and writes through Lunora's data layer
-* instead of better-auth's built-in D1/Kysely adapter. Pass the result as
-* `createAuth({ database: lunoraAuthAdapter(store) })`; better-auth's
-* `createAdapterFactory` handles id generation, default values, field-name
-* mapping and output shaping, so this only translates the cleaned CRUD calls
-* onto the store.
-*
-* ```ts
-* const auth = createAuth({
-*     secret: env.AUTH_SECRET,
-*     emailAndPassword: { enabled: true },
-*     database: lunoraAuthAdapter(lunoraStore), // lunoraStore writes via ctx.db
-* });
-* ```
-*
-* Scope: the {@link AuthStore} interface is single-table CRUD. better-auth's
-* relational `join` reads (an advanced opt-in) are not handled — pair the
-* adapter with `disableJoins` or let better-auth fall back to per-table reads.
-*/
-declare const lunoraAuthAdapter: (store: AuthStore) => ReturnType<typeof createAdapterFactory>;
-/**
-* One-liner for the common case: a better-auth `database` backed by a Cloudflare
-* D1 binding, via Lunora's SQL store — equivalent to
-* `lunoraAuthAdapter(createSqlAuthStore(d1Executor(d1)))`.
-*
-* Prefer this over passing the raw `env.DB` as `database`. With raw D1,
-* better-auth resolves its Kysely adapter through a runtime `await import(...)`
-* inside `auth.$context`, and that dynamic import never settles under
-* `@cloudflare/vite-plugin`'s worker runner — so it hangs *every* auth request
-* in `pnpm dev` (a standalone `wrangler dev` or a deployed worker bundle it
-* up-front, so they're unaffected — which makes the hang baffling to debug).
-* This explicit adapter skips that import entirely, so dev and prod behave the
-* same. The migration instance is the one exception — it wants raw `env.DB` so
-* `ensureMigrated`'s Kysely migrator can create the tables (its `$context` is
-* never resolved, so the hang doesn't apply there).
-*/
-declare const lunoraD1Adapter: (d1: Parameters<typeof d1Executor>[0]) => ReturnType<typeof lunoraAuthAdapter>;
-export { lunoraAuthAdapter, lunoraD1Adapter };
+import 'better-auth/adapters';
+export { l as lunoraAuthAdapter, a as lunoraD1Adapter, b as lunoraDoAdapter } from "./packem_shared/adapter.d-DrD3bb1u.mjs";
+import "./sql-store.mjs";
+import "./store.mjs";

package/dist/adapter.d.ts

@@ -1,43 +1,4 @@
-import { createAdapterFactory } from 'better-auth/adapters';
-import { d1Executor } from "./sql-store.js";
-import { AuthStore } from "./store.js";
-/**
-* A better-auth database adapter backed by an {@link AuthStore} — the bridge
-* that routes better-auth's reads and writes through Lunora's data layer
-* instead of better-auth's built-in D1/Kysely adapter. Pass the result as
-* `createAuth({ database: lunoraAuthAdapter(store) })`; better-auth's
-* `createAdapterFactory` handles id generation, default values, field-name
-* mapping and output shaping, so this only translates the cleaned CRUD calls
-* onto the store.
-*
-* ```ts
-* const auth = createAuth({
-*     secret: env.AUTH_SECRET,
-*     emailAndPassword: { enabled: true },
-*     database: lunoraAuthAdapter(lunoraStore), // lunoraStore writes via ctx.db
-* });
-* ```
-*
-* Scope: the {@link AuthStore} interface is single-table CRUD. better-auth's
-* relational `join` reads (an advanced opt-in) are not handled — pair the
-* adapter with `disableJoins` or let better-auth fall back to per-table reads.
-*/
-declare const lunoraAuthAdapter: (store: AuthStore) => ReturnType<typeof createAdapterFactory>;
-/**
-* One-liner for the common case: a better-auth `database` backed by a Cloudflare
-* D1 binding, via Lunora's SQL store — equivalent to
-* `lunoraAuthAdapter(createSqlAuthStore(d1Executor(d1)))`.
-*
-* Prefer this over passing the raw `env.DB` as `database`. With raw D1,
-* better-auth resolves its Kysely adapter through a runtime `await import(...)`
-* inside `auth.$context`, and that dynamic import never settles under
-* `@cloudflare/vite-plugin`'s worker runner — so it hangs *every* auth request
-* in `pnpm dev` (a standalone `wrangler dev` or a deployed worker bundle it
-* up-front, so they're unaffected — which makes the hang baffling to debug).
-* This explicit adapter skips that import entirely, so dev and prod behave the
-* same. The migration instance is the one exception — it wants raw `env.DB` so
-* `ensureMigrated`'s Kysely migrator can create the tables (its `$context` is
-* never resolved, so the hang doesn't apply there).
-*/
-declare const lunoraD1Adapter: (d1: Parameters<typeof d1Executor>[0]) => ReturnType<typeof lunoraAuthAdapter>;
-export { lunoraAuthAdapter, lunoraD1Adapter };
+import 'better-auth/adapters';
+export { l as lunoraAuthAdapter, a as lunoraD1Adapter, b as lunoraDoAdapter } from "./packem_shared/adapter.d-2a61HAY2.js";
+import "./sql-store.js";
+import "./store.js";

package/dist/adapter.mjs

@@ -1,47 +1 @@
-import { createAdapterFactory } from 'better-auth/adapters';
-import { createSqlAuthStore, d1Executor } from './sql-store.mjs';
-
-const asRow = (row) => row;
-const asRowOrNull = (row) => row ?? null;
-const asRows = (rows) => rows;
-const lunoraAuthAdapter = (store) => createAdapterFactory({
-  adapter: () => {
-    return {
-      consumeOne: async ({ model, where }) => asRowOrNull(await store.consumeOne(model, where)),
-      count: async ({ model, where }) => store.count(model, where ?? []),
-      create: async ({ data, model }) => asRow(await store.create(model, data)),
-      delete: async ({ model, where }) => {
-        await store.remove(model, where);
-      },
-      deleteMany: async ({ model, where }) => store.remove(model, where),
-      findMany: async ({ limit, model, offset, sortBy, where }) => asRows(await store.read(model, { limit, offset, sortBy, where: where ?? [] })),
-      findOne: async ({ model, where }) => {
-        const [row] = await store.read(model, { limit: 1, where });
-        return asRowOrNull(row);
-      },
-      update: async ({ model, update, where }) => {
-        const [row] = await store.update(model, where, update);
-        return asRowOrNull(row);
-      },
-      updateMany: async ({ model, update, where }) => {
-        const updated = await store.update(model, where, update);
-        return updated.length;
-      }
-    };
-  },
-  config: {
-    adapterId: "lunora",
-    adapterName: "Lunora Adapter",
-    // Conservative flags so the adapter is store-agnostic: better-auth
-    // serializes dates/booleans/json to primitives (string/number) before a
-    // write and parses them back after a read, so a store — in-memory or
-    // SQL — only ever handles primitives, never schema-aware codecs.
-    supportsBooleans: false,
-    supportsDates: false,
-    supportsJSON: false,
-    supportsNumericIds: false
-  }
-});
-const lunoraD1Adapter = (d1) => lunoraAuthAdapter(createSqlAuthStore(d1Executor(d1)));
-
-export { lunoraAuthAdapter, lunoraD1Adapter };
+import"better-auth/adapters";import{s as p,l as e,w as l}from"./packem_shared/adapter-RvDcm0Zy.mjs";import"./sql-store.mjs";export{p as lunoraAuthAdapter,e as lunoraD1Adapter,l as lunoraDoAdapter};

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,11 @@
+import{redact as A,standardRules as _,piiRules as v}from"@visulima/redact";const n="__lunora_auth_audit__",R=[..._,...v],N=1e3,L=1e4,u=null,s=t=>{if(typeof t=="string")return t;if(typeof t=="number"||typeof t=="bigint"||typeof t=="boolean")return String(t)},m=async t=>{await t.run(`CREATE TABLE IF NOT EXISTS "${n}" (
+            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
+        )`,[])},O=async(t,e,r={})=>{await m(t);let i;return e.detail!==void 0&&(i=r.redactDetail===!1?e.detail:A(e.detail,R)),await t.run(`INSERT INTO "${n}" (ts, event, outcome, actor_id, actor_email, ip, user_agent, detail) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,[e.ts,e.event,e.outcome,e.actorId??u,e.actorEmail??u,e.ip??u,e.userAgent??u,i===void 0?u:JSON.stringify(i)]),typeof r.retention=="number"&&r.retention>0&&await t.run(`DELETE FROM "${n}" WHERE seq <= (SELECT MAX(seq) - ? FROM "${n}")`,[r.retention]),{...e,detail:i}},I=async(t,e={})=>{await m(t);const r=Math.max(1,Math.min(e.limit??N,L)),i=["seq > ?"],d=[e.sinceSeq??0];return e.actorId!==void 0&&(i.push("actor_id = ?"),d.push(e.actorId)),e.event!==void 0&&(i.push("event = ?"),d.push(e.event)),d.push(r),(await t.all(`SELECT seq, ts, event, outcome, actor_id, actor_email, ip, user_agent, detail FROM "${n}" WHERE ${i.join(" AND ")} ORDER BY seq DESC LIMIT ?`,d)).map(a=>{const o={event:s(a.event)??"",outcome:a.outcome==="failure"?"failure":"success",seq:Number(a.seq),ts:Number(a.ts)},E=s(a.actor_id),c=s(a.actor_email),T=s(a.ip),l=s(a.user_agent),p=s(a.detail);return E!==void 0&&(o.actorId=E),c!==void 0&&(o.actorEmail=c),T!==void 0&&(o.ip=T),l!==void 0&&(o.userAgent=l),p!==void 0&&(o.detail=JSON.parse(p)),o})},h=t=>({read:e=>I(t,e)});export{n as AUTH_AUDIT_TABLE,O as appendAuthAuditEntry,h as createAuthAuditReader,m as ensureAuthAuditTable,I as 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 };