@lunora/auth 1.0.0-alpha.8 → 1.0.0-alpha.80

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,146 @@
+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-in-initiated" | "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;
+  /**
+   * The identifier (email or username) a sign-in-family request ATTEMPTED,
+   * read from the request body. Present for both successful and failed
+   * attempts — unlike `actorEmail` (which requires an authenticated
+   * session), this is what lets a FAILED credential-stuffing attempt be
+   * grouped by target. Same redaction exemption as `actorEmail`: a
+   * top-level column, not a `detail` key, because `AUDIT_REDACT_RULES`
+   * scrubs email-shaped values inside `detail` regardless of key name —
+   * putting it there would erase exactly this datum. Length-capped to 320
+   * chars (RFC 5321) since it carries attacker-controlled request-body text.
+   */
+  targetEmail?: string;
+  /** 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;
+  /** See {@link AuthAuditEntry.targetEmail}. */
+  targetEmail?: string;
+  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.
+ *
+ * `target_email` is added via a guarded `ALTER TABLE` rather than baked only
+ * into the `CREATE`, mirroring `@lunora/observability`'s
+ * `ensureRequestLogTable`/`ensureFunctionMetricsTables` — `CREATE TABLE IF NOT
+ * EXISTS` only helps a table that doesn't exist yet, so a database whose audit
+ * table predates this column needs the `ALTER` to gain it. SQLite has no `ADD
+ * COLUMN IF NOT EXISTS`; the duplicate-column error from a re-run (or from the
+ * column already existing on the freshly-created schema above) is swallowed —
+ * anything else re-throws, so a genuinely broken executor is not silently
+ * papered over.
+ */
+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.
+ *
+ * `limit` is NaN-safe: a non-finite/non-number value (e.g. a caller passing
+ * `Number.NaN`, or an upstream boundary that failed to reject one) falls back
+ * to {@link DEFAULT_READ_LIMIT} rather than reaching `Math.min`/`Math.max`,
+ * which both propagate `NaN` and would otherwise bind it as the SQL `LIMIT`
+ * parameter. This is the library-level fix; `#readAudit` (`./auth-do`) also
+ * rejects a non-numeric `limit` at the boundary with a 400 — this clamp is the
+ * safety net for every OTHER caller of this function too.
+ */
+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,146 @@
+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-in-initiated" | "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;
+  /**
+   * The identifier (email or username) a sign-in-family request ATTEMPTED,
+   * read from the request body. Present for both successful and failed
+   * attempts — unlike `actorEmail` (which requires an authenticated
+   * session), this is what lets a FAILED credential-stuffing attempt be
+   * grouped by target. Same redaction exemption as `actorEmail`: a
+   * top-level column, not a `detail` key, because `AUDIT_REDACT_RULES`
+   * scrubs email-shaped values inside `detail` regardless of key name —
+   * putting it there would erase exactly this datum. Length-capped to 320
+   * chars (RFC 5321) since it carries attacker-controlled request-body text.
+   */
+  targetEmail?: string;
+  /** 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;
+  /** See {@link AuthAuditEntry.targetEmail}. */
+  targetEmail?: string;
+  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.
+ *
+ * `target_email` is added via a guarded `ALTER TABLE` rather than baked only
+ * into the `CREATE`, mirroring `@lunora/observability`'s
+ * `ensureRequestLogTable`/`ensureFunctionMetricsTables` — `CREATE TABLE IF NOT
+ * EXISTS` only helps a table that doesn't exist yet, so a database whose audit
+ * table predates this column needs the `ALTER` to gain it. SQLite has no `ADD
+ * COLUMN IF NOT EXISTS`; the duplicate-column error from a re-run (or from the
+ * column already existing on the freshly-created schema above) is swallowed —
+ * anything else re-throws, so a genuinely broken executor is not silently
+ * papered over.
+ */
+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.
+ *
+ * `limit` is NaN-safe: a non-finite/non-number value (e.g. a caller passing
+ * `Number.NaN`, or an upstream boundary that failed to reject one) falls back
+ * to {@link DEFAULT_READ_LIMIT} rather than reaching `Math.min`/`Math.max`,
+ * which both propagate `NaN` and would otherwise bind it as the SQL `LIMIT`
+ * parameter. This is the library-level fix; `#readAudit` (`./auth-do`) also
+ * rejects a non-numeric `limit` at the boundary with a 400 — this clamp is the
+ * safety net for every OTHER caller of this function too.
+ */
+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,12 @@
+import{redact as p,standardRules as A,piiRules as g}from"@visulima/redact";const n="__lunora_auth_audit__",L=[...A,...g],N=1e3,R=1e4,o=null,E=t=>{if(typeof t=="string")return t;if(typeof t=="number"||typeof t=="bigint"||typeof t=="boolean")return String(t)},d=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,
+            target_email TEXT,
+            ip TEXT,
+            user_agent TEXT,
+            detail TEXT
+        )`,[]);try{await t.run(`ALTER TABLE "${n}" ADD COLUMN target_email TEXT`,[])}catch(e){if(!(e instanceof Error?e.message.toLowerCase():String(e).toLowerCase()).includes("duplicate column"))throw e}},I=async(t,e,i={})=>{await d(t);let a;return e.detail!==void 0&&(a=i.redactDetail===!1?e.detail:p(e.detail,L)),await t.run(`INSERT INTO "${n}" (ts, event, outcome, actor_id, actor_email, target_email, ip, user_agent, detail) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,[e.ts,e.event,e.outcome,e.actorId??o,e.actorEmail??o,e.targetEmail??o,e.ip??o,e.userAgent??o,a===void 0?o:JSON.stringify(a)]),typeof i.retention=="number"&&i.retention>0&&await t.run(`DELETE FROM "${n}" WHERE seq <= (SELECT MAX(seq) - ? FROM "${n}")`,[i.retention]),{...e,detail:a}},f=async(t,e={})=>{await d(t);const i=Number.isFinite(e.limit)?Math.max(1,Math.min(e.limit,R)):N,a=["seq > ?"],s=[e.sinceSeq??0];return e.actorId!==void 0&&(a.push("actor_id = ?"),s.push(e.actorId)),e.event!==void 0&&(a.push("event = ?"),s.push(e.event)),s.push(i),(await t.all(`SELECT seq, ts, event, outcome, actor_id, actor_email, target_email, ip, user_agent, detail FROM "${n}" WHERE ${a.join(" AND ")} ORDER BY seq DESC LIMIT ?`,s)).map(r=>{const u={event:E(r.event)??"",outcome:r.outcome==="failure"?"failure":"success",seq:Number(r.seq),ts:Number(r.ts)},T=[["actorId","actor_id"],["actorEmail","actor_email"],["targetEmail","target_email"],["ip","ip"],["userAgent","user_agent"]];for(const[m,_]of T){const l=E(r[_]);l!==void 0&&(u[m]=l)}const c=E(r.detail);return c!==void 0&&(u.detail=JSON.parse(c)),u})},h=t=>({read:e=>f(t,e)});export{n as AUTH_AUDIT_TABLE,I as appendAuthAuditEntry,h as createAuthAuditReader,d as ensureAuthAuditTable,f as readAuthAuditLog};