@lunora/auth 1.0.0-alpha.21 → 1.0.0-alpha.211

package/dist/index.d.mts

@@ -1,28 +1,36 @@
-export { lunoraAuthAdapter, lunoraD1Adapter } from "./adapter.mjs";
+import { D as DoStorageLike } from "./packem_shared/adapter.d-CaPwF2v3.mjs";
+export { l as lunoraAuthAdapter, a as lunoraD1Adapter, b as lunoraDoAdapter } from "./packem_shared/adapter.d-CaPwF2v3.mjs";
 import { LunoraError } from '@lunora/errors';
-import { L as LunoraAuth, a as LunoraAuthOptions } from "./packem_shared/create-auth.d-Mwhb4gSc.mjs";
-export { c as createAuth, r as resolveAuthOptions } from "./packem_shared/create-auth.d-Mwhb4gSc.mjs";
+import { L as LunoraAuth, a as LunoraAuthOptions } from "./packem_shared/create-auth.d-D1CKOFWc.mjs";
+export { c as createAuth, r as resolveAuthOptions } from "./packem_shared/create-auth.d-D1CKOFWc.mjs";
+import { AppendAuthAuditEntry, AppendAuthAuditOptions, AuthAuditEvent, AuthAuditReader } from "./audit.mjs";
+export { AUTH_AUDIT_TABLE, type AuthAuditEntry, type AuthAuditOutcome, 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 I as InviteOnlyOptions, type a as IssuedSignUpInvitation, type S as SignUpInvitation, c as createSignUpInvitation, l as listSignUpInvitations, p as pruneSignUpInvitations, r as revokeSignUpInvitation } from "./packem_shared/invite-only.d-DKyHHkkQ.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";
 import 'better-auth/adapters';
 import '@lunora/server';
 /**
-* A timestamp as it leaves the admin API: epoch-ms (better-auth stores `Date`s,
-* which we normalize on output) or `null` when the column is unset.
-*/
+ * A timestamp as it leaves the admin API: epoch-ms (better-auth stores `Date`s,
+ * which we normalize on output) or `null` when the column is unset.
+ */
 type AuthTimestamp = null | number;
 /**
-* One user row as the admin API surfaces it. The fixed keys mirror better-auth's
-* core `user` table plus the `admin()` plugin columns (`role`/`banned`/…); the
-* index signature carries any app-defined `user.additionalFields` so callers
-* (the studio) can render them generically. Password material never lives on
-* this row (it's in the `account` table) and is never returned.
-*/
+ * One user row as the admin API surfaces it. The fixed keys mirror better-auth's
+ * core `user` table plus the `admin()` plugin columns (`role`/`banned`/…); the
+ * index signature carries any app-defined `user.additionalFields` so callers
+ * (the studio) can render them generically. Password material never lives on
+ * this row (it's in the `account` table) and is never returned.
+ */
 interface AuthAdminUser {
   [key: string]: unknown;
   banExpires?: AuthTimestamp;
@@ -38,12 +46,12 @@ interface AuthAdminUser {
   updatedAt?: AuthTimestamp;
 }
 /**
-* One session row as the admin API surfaces it. Mirrors better-auth's `session`
-* table; `impersonatedBy` is set when the session was minted by
-* {@link AuthAdmin.impersonateUser}. The signing `token` is stripped — it's a
-* bearer credential, and the only place we hand one back is the explicit
-* impersonation flow.
-*/
+ * One session row as the admin API surfaces it. Mirrors better-auth's `session`
+ * table; `impersonatedBy` is set when the session was minted by
+ * {@link AuthAdmin.impersonateUser}. The signing `token` is stripped — it's a
+ * bearer credential, and the only place we hand one back is the explicit
+ * impersonation flow.
+ */
 interface AuthAdminSession {
   [key: string]: unknown;
   createdAt?: AuthTimestamp;
@@ -91,6 +99,28 @@ interface AuthInvitation {
   role?: null | string;
   status?: null | string;
 }
+/**
+ * One sign-up invitation (from the `inviteOnly` plugin). Distinct from
+ * {@link AuthInvitation}, which invites an existing account into an organization:
+ * this one is what lets an address create an account at all.
+ */
+interface AuthSignUpInvitation {
+  [key: string]: unknown;
+  /** When an account was created for this address; `null` while the invitation is unspent. */
+  acceptedAt?: AuthTimestamp;
+  createdAt?: AuthTimestamp;
+  email?: null | string;
+  expiresAt?: AuthTimestamp;
+  id: string;
+  invitedBy?: null | string;
+  /**
+   * The plaintext invitation token — present **only** on the row
+   * {@link AuthAdmin.createSignUpInvitation} returns, never on a listed one.
+   * The stored `tokenHash` is in {@link SENSITIVE_FIELDS}, so it cannot leave
+   * this plane by accident.
+   */
+  token?: string;
+}
 /** One team row (from the `organization` plugin with `teams.enabled`). */
 interface AuthTeam {
   [key: string]: unknown;
@@ -108,10 +138,10 @@ interface AuthTeamMember {
   userId: string;
 }
 /**
-* One custom organization role (from the organization plugin's dynamic
-* access-control). `permission` is a JSON string of a `resource → actions[]` map
-* as stored; the studio parses it for display/editing.
-*/
+ * One custom organization role (from the organization plugin's dynamic
+ * access-control). `permission` is a JSON string of a `resource → actions[]` map
+ * as stored; the studio parses it for display/editing.
+ */
 interface AuthOrgRole {
   [key: string]: unknown;
   createdAt?: AuthTimestamp;
@@ -135,17 +165,19 @@ interface AuthPage<T> {
   total: number;
 }
 /**
-* Which admin surfaces a given auth instance supports, derived from the enabled
-* better-auth plugins (and any {@link CreateAuthAdminOptions.features} overrides).
-* The studio calls {@link AuthAdmin.capabilities} once and renders only the
-* panels whose capability is `true` — so a deployment that doesn't enable, say,
-* the `organization` plugin never shows an Organizations section.
-*/
+ * Which admin surfaces a given auth instance supports, derived from the enabled
+ * better-auth plugins (and any {@link CreateAuthAdminOptions.features} overrides).
+ * The studio calls {@link AuthAdmin.capabilities} once and renders only the
+ * panels whose capability is `true` — so a deployment that doesn't enable, say,
+ * the `organization` plugin never shows an Organizations section.
+ */
 interface AuthCapabilities {
   /** Linked-account browsing/unlinking — core (the `account` table always exists). */
   accounts: boolean;
   /** The `admin()` plugin: ban/role/impersonate/create/delete/set-password. */
   admin: boolean;
+  /** The `inviteOnly` plugin: sign-up invitations. */
+  inviteOnly: boolean;
   /** The `organization` plugin: orgs, members, invitations. */
   organization: boolean;
   /** The `@better-auth/passkey` plugin: per-user passkeys. */
@@ -154,12 +186,12 @@ interface AuthCapabilities {
   twoFactor: boolean;
 }
 /**
-* One app/plugin-defined field the create-user form should render, derived from
-* the merged better-auth `user` table (core + plugin + `additionalFields`). Only
-* user-settable columns are surfaced — server-managed flags (`input: false`),
-* foreign keys (`references`), and the core columns the form already handles
-* (`email`/`name`/`role`/ban state/…) are filtered out upstream.
-*/
+ * One app/plugin-defined field the create-user form should render, derived from
+ * the merged better-auth `user` table (core + plugin + `additionalFields`). Only
+ * user-settable columns are surfaced — server-managed flags (`input: false`),
+ * foreign keys (`references`), and the core columns the form already handles
+ * (`email`/`name`/`role`/ban state/…) are filtered out upstream.
+ */
 interface AuthUserFieldSpec {
   /** Logical field name (the key passed back in `createUser`'s `data`). */
   name: string;
@@ -171,13 +203,13 @@ interface AuthUserFieldSpec {
   unique: boolean;
 }
 /**
-* A rich, read-only description of the deployment's auth configuration for the
-* studio's config panel and dynamic create-user form. Unlike
-* {@link AuthCapabilities} (five booleans that gate panels), this exposes *what*
-* is configured — enabled plugins, email/password + social sign-in, the
-* user-settable fields, organization sub-features (teams / custom roles), and
-* the session + rate-limit policy — without ever leaking a secret.
-*/
+ * A rich, read-only description of the deployment's auth configuration for the
+ * studio's config panel and dynamic create-user form. Unlike
+ * {@link AuthCapabilities} (five booleans that gate panels), this exposes *what*
+ * is configured — enabled plugins, email/password + social sign-in, the
+ * user-settable fields, organization sub-features (teams / custom roles), and
+ * the session + rate-limit policy — without ever leaking a secret.
+ */
 interface AuthConfigInfo {
   /** The same capability booleans {@link AuthAdmin.capabilities} returns, embedded so a single call drives the whole panel. */
   capabilities: AuthCapabilities;
@@ -185,7 +217,8 @@ interface AuthConfigInfo {
   emailAndPassword: boolean;
   /** Organization plugin sub-features. */
   organization: {
-    enabled: boolean; /** Custom roles / dynamic access control (`organizationRole` table present). */
+    enabled: boolean;
+    /** Custom roles / dynamic access control (`organizationRole` table present). */
     roles: boolean;
     /** Teams (`team` table present). */
     teams: boolean;
@@ -236,14 +269,14 @@ interface ImpersonationResult {
   user: AuthAdminUser;
 }
 /**
-* The full read + write surface the studio's auth dashboard drives, backed by
-* better-auth's tables. Returned by {@link createAuthAdmin}. The runtime accepts
-* a structurally-compatible object as its `authAdmin` option and exposes each
-* method behind an admin-token-gated endpoint. Methods whose backing plugin is
-* absent still exist (they're not conditionally omitted) but the studio gates
-* them on {@link AuthAdmin.capabilities}; calling one for an unconfigured plugin
-* surfaces the underlying adapter error.
-*/
+ * The full read + write surface the studio's auth dashboard drives, backed by
+ * better-auth's tables. Returned by {@link createAuthAdmin}. The runtime accepts
+ * a structurally-compatible object as its `authAdmin` option and exposes each
+ * method behind an admin-token-gated endpoint. Methods whose backing plugin is
+ * absent still exist (they're not conditionally omitted) but the studio gates
+ * them on {@link AuthAdmin.capabilities}; calling one for an unconfigured plugin
+ * surfaces the underlying adapter error.
+ */
 interface AuthAdmin {
   /** Directly add an existing user as an org member (server-side, no invitation/acceptance). */
   addMember: (input: {
@@ -281,6 +314,17 @@ interface AuthAdmin {
     permission: Record<string, string[]>;
     role: string;
   }) => Promise<AuthOrgRole>;
+  /**
+   * Invite an address to sign up, or refresh an existing invitation for it.
+   * Needs the `inviteOnly` plugin — without it the row is written to a table
+   * nothing reads, which is why the studio gates the panel on
+   * {@link AuthCapabilities.inviteOnly}.
+   */
+  createSignUpInvitation: (input: {
+    email: string;
+    expiresInSeconds?: number;
+    invitedBy?: string;
+  }) => Promise<AuthSignUpInvitation>;
   /** Create a team under an organization. */
   createTeam: (input: {
     name: string;
@@ -348,6 +392,16 @@ interface AuthAdmin {
     offset?: number;
     userId?: string;
   }) => Promise<AuthPage<AuthAdminSession>>;
+  /**
+   * Sign-up invitations, newest first. Unfiltered on purpose: "pending" is
+   * `acceptedAt === null && expiresAt > now`, and applying that after a page
+   * would let page 1 come back empty while pending rows sat on page 2. The
+   * caller has both columns and can label each row itself.
+   */
+  listSignUpInvitations: (options: {
+    limit?: number;
+    offset?: number;
+  }) => Promise<AuthPage<AuthSignUpInvitation>>;
   /** List a team's members. */
   listTeamMembers: (options: {
     limit?: number;
@@ -375,6 +429,10 @@ interface AuthAdmin {
   removeUser: (input: {
     userId: string;
   }) => Promise<void>;
+  /** Withdraw a sign-up invitation. Not retroactive — an account already created keeps existing; use {@link AuthAdmin.removeUser} for that. */
+  revokeSignUpInvitation: (input: {
+    email: string;
+  }) => Promise<void>;
   revokeUserSession: (input: {
     sessionId: string;
   }) => Promise<void>;
@@ -427,152 +485,690 @@ interface AuthAdmin {
 /** Options for {@link createAuthAdmin}. */
 interface CreateAuthAdminOptions {
   /**
-  * Force individual {@link AuthCapabilities} on or off regardless of which
-  * plugins are detected — e.g. `{ impersonate: false }`-style opt-outs by
-  * setting `admin: false`, or hiding linked accounts with `accounts: false`.
-  * A capability is reported only when both its plugin is enabled *and* its
-  * override isn't `false`.
-  */
+   * Force individual {@link AuthCapabilities} on or off regardless of which
+   * plugins are detected — e.g. `{ impersonate: false }`-style opt-outs by
+   * setting `admin: false`, or hiding linked accounts with `accounts: false`.
+   * A capability is reported only when both its plugin is enabled *and* its
+   * override isn't `false`.
+   */
   features?: Partial<AuthCapabilities>;
   /**
-  * User id recorded as the impersonator on sessions minted by
-  * {@link AuthAdmin.impersonateUser}. Defaults to the impersonated user's own
-  * id (a self-reference) since the trusted admin plane has no acting user.
-  */
+   * User id recorded as the impersonator on sessions minted by
+   * {@link AuthAdmin.impersonateUser}. Defaults to the impersonated user's own
+   * id (a self-reference) since the trusted admin plane has no acting user.
+   */
   impersonatedBy?: string;
   /**
-  * How long (in seconds) an impersonation session lives. Must be a positive
-  * finite integer. Capped at 24 × {@link DEFAULT_IMPERSONATION_SECONDS}
-  * (86 400 s / 24 h). Defaults to {@link DEFAULT_IMPERSONATION_SECONDS}
-  * (3 600 s / 1 h).
-  */
+   * How long (in seconds) an impersonation session lives. Must be a positive
+   * finite integer. Capped at 24 × {@link DEFAULT_IMPERSONATION_SECONDS}
+   * (86 400 s / 24 h). Defaults to {@link DEFAULT_IMPERSONATION_SECONDS}
+   * (3 600 s / 1 h).
+   */
   impersonationSeconds?: number;
 }
 /**
-* A normalized failure from an admin operation. better-auth throws `APIError`s
-* carrying a `body.code` (e.g. `USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL`); we
-* surface that `code` so the runtime can map it onto an HTTP status and the
-* studio can show a meaningful message instead of a generic 500.
-*/
+ * A normalized failure from an admin operation. better-auth throws `APIError`s
+ * carrying a `body.code` (e.g. `USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL`); we
+ * surface that `code` so the runtime can map it onto an HTTP status and the
+ * studio can show a meaningful message instead of a generic 500.
+ */
 declare class LunoraAuthAdminError extends LunoraError {
   constructor(message: string, code: string);
 }
 /**
-* Build the studio's auth user-management plane on top of better-auth.
-*
-* Pass the result as the runtime's `authAdmin` option; the runtime exposes each
-* method behind an admin-token-gated `/_lunora/admin/auth/*` endpoint. The set
-* of usable surfaces is reported by {@link AuthAdmin.capabilities} — derived
-* from the enabled better-auth plugins, so enabling `admin()`, `organization()`,
-* `twoFactor()`, or the passkey plugin in the auth config is what lights up the
-* matching dashboard panels.
-*
-* **Trust model — important.** These operations talk to better-auth's
-* `internalAdapter` (and `adapter`/password hasher) **directly**, deliberately
-* bypassing the plugins' own endpoints, which require the caller to hold an
-* admin-role session. That session check is the wrong gate here: the runtime
-* already authorizes every call with `LUNORA_ADMIN_TOKEN`, so this helper acts
-* as a trusted server-side operator. It is therefore not an end-user-callable
-* API — never expose it on a path that isn't admin-token gated.
-*
-* `auth.$context` is a promise (better-auth resolves the adapter, password
-* config, etc. lazily); we memoize it so the first call pays the cost once.
-*/
+ * Build the studio's auth user-management plane on top of better-auth.
+ *
+ * Pass the result as the runtime's `authAdmin` option; the runtime exposes each
+ * method behind an admin-token-gated `/_lunora/admin/auth/*` endpoint. The set
+ * of usable surfaces is reported by {@link AuthAdmin.capabilities} — derived
+ * from the enabled better-auth plugins, so enabling `admin()`, `organization()`,
+ * `twoFactor()`, or the passkey plugin in the auth config is what lights up the
+ * matching dashboard panels.
+ *
+ * **Trust model — important.** These operations talk to better-auth's
+ * `internalAdapter` (and `adapter`/password hasher) **directly**, deliberately
+ * bypassing the plugins' own endpoints, which require the caller to hold an
+ * admin-role session. That session check is the wrong gate here: the runtime
+ * already authorizes every call with `LUNORA_ADMIN_TOKEN`, so this helper acts
+ * as a trusted server-side operator. It is therefore not an end-user-callable
+ * API — never expose it on a path that isn't admin-token gated.
+ *
+ * `auth.$context` is a promise (better-auth resolves the adapter, password
+ * 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;
+  /**
+   * When true, `x-forwarded-for` is trusted as a client-IP fallback when
+   * `cf-connecting-ip` is absent — only enable this behind a proxy you control,
+   * or the recorded IP is attacker-chosen. Defaults to `false`: off Cloudflare,
+   * with no trusted proxy configured, the audit record's `ip` is omitted rather
+   * than populated from a spoofable header.
+   */
+  trustProxyHeaders?: boolean;
+}
+/**
+ * Structural view of the fields we read off better-auth's after-hook context —
+ * kept loose to avoid coupling to internal types.
+ *
+ * `body` is the parsed request body better-auth's middleware context exposes
+ * as `ctx.body` — pinned present and populated (e.g. `.email`) in the after-hook
+ * by `__tests__/audit-hooks.behaviour.test.ts` (plan 280 S0).
+ */
+interface AuditHookContext {
+  body?: Record<string, unknown>;
+  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.
+ *
+ * Sign-in is split by what the endpoint actually DOES (plan 280 §4):
+ *
+ * - `/sign-in/social`, `/sign-in/magic-link` and `@better-auth/sso`'s
+ * `/sign-in/sso` only DISPATCH — the first mints a provider redirect URL, the
+ * second sends an email, the third answers `{ url, redirect: true }` pointing
+ * at the identity provider's authorization endpoint. Nobody is authenticated
+ * yet, so these are `sign-in-initiated`, not `sign-in`. Without the `sso`
+ * branch that path fell through to the `/sign-in/` substring below and every
+ * SSO redirect mint was recorded as a completed, successful `sign-in` with no
+ * actor — in exactly the flow where the "who authenticated" trail matters
+ * most.
+ * - `/callback/:id` (social + generic-oauth), `/magic-link/verify`,
+ * `@better-auth/sso`'s `/sso/saml2/sp/acs/:providerId`, and every
+ * `/two-factor/verify-*` (`verify-totp` / `verify-otp` / `verify-backup-code`
+ * — all three complete a challenged sign-in the same way) are where a
+ * session actually gets issued, so they join credential sign-ins
+ * (`/sign-in/email`, `/sign-in/username`, `/sign-in/phone-number`, …) as
+ * plain `sign-in`. They were NOT recorded at all before this change.
+ *
+ * The SAML assertion consumer service needs its own branch because it is the
+ * one completion that carries no `/callback/` segment: `processSAMLResponse`
+ * validates the assertion, resolves the user and calls `setSessionCookie`, all
+ * under `/sso/saml2/sp/acs/:providerId`. Matching neither that substring nor
+ * any other branch, it classified as `undefined` — the endpoint that issues
+ * every SAML session left no audit row at all.
+ *
+ * SAML sign-OUT has the mirror-image problem, and two endpoints rather than
+ * one. Neither ends in `/sign-out`, and both terminate the local session before
+ * redirecting, so both are `sign-out` rather than an initiated event:
+ *
+ * - `/sso/saml2/logout/:providerId` — SP-initiated. Deletes the SAML session
+ * keys, calls `deleteSession` on the current session token and
+ * `deleteSessionCookie`, then redirects to the IdP's logout URL.
+ * - `/sso/saml2/sp/slo/:providerId` — the SP's single-logout receiver, for the
+ * IdP-initiated direction and for the response leg of an SP-initiated one.
+ * Both `handleLogoutRequest` and `handleLogoutResponse` call `deleteSession`
+ * and `deleteSessionCookie` the same way.
+ *
+ * Recording the SAML sign-in while leaving these silent is worse than either
+ * gap alone: the trail would show a session opening and never closing, so a
+ * reader cannot tell "still signed in" from "we stopped watching".
+ *
+ * There is no dedicated `/oauth2/callback/*` branch because the generic
+ * `/callback/` check above already covers it, and covering it is CORRECT: an
+ * OAuth callback is a completed sign-in whatever path prefix it arrives on. The
+ * same substring also catches `@better-auth/sso`'s `/sso/callback/:providerId`,
+ * which is where an SSO sign-in actually completes — `sso` is re-exported from
+ * `@lunora/auth/plugins/enterprise`, so that path is live, not hypothetical.
+ *
+ * Checked against the installed `better-auth` and `@better-auth/*` dist for
+ * 1.7.3: generic-oauth registers NO endpoints of its own (there is no
+ * `/sign-in/oauth2`) — it registers providers used through the core
+ * `/sign-in/social` and `/callback/:id`, and the one dist hit for a literal
+ * `/oauth2/callback/` is inside `better-auth/plugins/oauth-popup`, which
+ * `plugins.ts` does not re-export — so today the branch fires for the core
+ * callback, and stays correct if the other becomes reachable.
+ */
+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.
+ *
+ * Does NOT attempt to distinguish a 2FA-challenged credential sign-in from a
+ * fully successful one (a `sign-in-challenged` event, as an earlier design for
+ * this change proposed) — pinned in `__tests__/audit-hooks.behaviour.test.ts`
+ * (plan 280 S0): better-auth runs the APP's own `hooks.after` BEFORE the
+ * `twoFactor` plugin's own after-hook that rewrites the response to
+ * `{ twoFactorRedirect: true }` and nulls `ctx.context.newSession`. By the time
+ * THIS hook runs, `context.returned`/`context.newSession` still reflect the
+ * pre-interception, fully-successful sign-in — there is nothing here to detect
+ * the challenge from. Distinguishing it would need a different seam (e.g. a
+ * plugin-ordered-after-`twoFactor` hook, or reading `twoFactor`'s own
+ * database state) and is left to a follow-up.
+ */
+declare const buildAuditEntry: (context: AuditHookContext, { now, trustProxyHeaders }?: {
+  now?: number;
+  trustProxyHeaders?: boolean;
+}) => 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 }) },
+ * });
+ * ```
+ *
+ * ## Behaviour change (plan 280) — `onRecord`/SIEM consumers keyed on `event` strings, read this
+ *
+ * | Endpoint                                          | Before              | After                 |
+ * | -------------------------------------------------- | ------------------- | --------------------- |
+ * | `/sign-in/email` (and other credential sign-ins)  | `sign-in`           | `sign-in` (unchanged) |
+ * | `/sign-in/social`                                  | `sign-in`           | `sign-in-initiated`   |
+ * | `/sign-in/magic-link`                              | `sign-in`           | `sign-in-initiated`   |
+ * | `/callback/:id` (social + generic-oauth)          | _(not recorded)_    | `sign-in`             |
+ * | `/magic-link/verify`                               | _(not recorded)_    | `sign-in`             |
+ * | `/two-factor/verify-totp` / `-otp` / `-backup-code`| _(not recorded)_    | `sign-in`             |
+ *
+ * A caller matching on `event === "sign-in"` now sees FEWER events for
+ * `/sign-in/social` and `/sign-in/magic-link` (they never actually authenticated
+ * anyone) and MORE events for the four previously-unrecorded completion
+ * endpoints — the net effect is a more truthful count, not a strictly larger or
+ * smaller one. `sign-in-initiated` is a new event name (open `AuthAuditEvent`
+ * union, so no wire/type break, but SIEM rules enumerating event names should
+ * add it). A failed sign-in now also carries `targetEmail` (the attempted
+ * address/username) when the request body supplied one — see
+ * {@link AppendAuthAuditEntry.targetEmail} — so credential-stuffing attempts can
+ * be grouped by target even though they never produce an `actorEmail`.
+ *
+ * NOT changed: `/sign-in/email` under an active 2FA challenge still records
+ * plain `sign-in` / `success` (not a distinct `sign-in-challenged` event) — see
+ * {@link buildAuditEntry}'s docblock for why that distinction turned out not to
+ * be buildable from this hook.
+ */
+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;
+/**
+ * The Durable Object state slice this class needs — structural so unit tests can
+ * pass a double without depending on the workers runtime.
+ */
+interface AuthDoState {
+  storage: DoStorageLike;
+}
+/** Path the worker calls to resolve a request's identity. Not part of `/api/auth/*`. */
+declare const RESOLVE_SESSION_PATH = "/__lunora/auth/session";
+/**
+ * Path the worker calls to read the audit log. Also not part of `/api/auth/*`.
+ *
+ * The audit table lives in this object like every other auth table, so the worker
+ * cannot query it directly — same constraint as the session route, same shared secret.
+ */
+declare const READ_AUDIT_PATH = "/__lunora/auth/audit";
+/** Header carrying the shared secret that authenticates the calling worker. */
+declare const INTERNAL_SECRET_HEADER = "x-lunora-auth-do-secret";
+/**
+ * Options for the auth DO, beyond the better-auth options themselves.
+ */
+interface AuthDoOptions {
+  /**
+   * Shared secret authenticating the worker on {@link RESOLVE_SESSION_PATH}.
+   *
+   * The DO binding is reachable from any worker bound to the namespace, so the
+   * binding alone is not an authorization boundary — same reasoning as
+   * `SessionDO`'s `SESSION_DO_SECRET`. When this is unset the internal route is
+   * refused outright rather than served unauthenticated: a missing secret is a
+   * misconfiguration, and answering identity questions to anyone is the one
+   * failure mode worth being loud about. `/api/auth/*` is unaffected — those
+   * routes carry their own credentials.
+   */
+  internalSecret?: string;
+}
 /**
-* Default basePath used by better-auth's client + handler. Override via the
-* second argument if you mount the auth routes somewhere else.
-*/
+ * Base class for an app's auth Durable Object. Subclass it (or let codegen emit the
+ * subclass) and register the subclass in `wrangler.jsonc`.
+ *
+ * ```ts
+ * export class AuthDO extends LunoraAuthDO {
+ *     public constructor(state: DurableObjectState, env: Env) {
+ *         super(state, () => ({ secret: env.AUTH_SECRET, plugins: [scim({ … })] }), {
+ *             internalSecret: env.AUTH_DO_SECRET,
+ *         });
+ *     }
+ * }
+ * ```
+ */
+declare class LunoraAuthDO {
+  #private;
+  /**
+   * @param state The Durable Object state — its `storage` becomes better-auth's database.
+   * @param optionsFactory Builds the better-auth options. Called once, lazily, on the first request.
+   * @param options Auth-DO specific options (base path, internal secret).
+   */
+  constructor(state: AuthDoState, optionsFactory: () => LunoraAuthOptions, options?: AuthDoOptions);
+  /**
+   * Serve an auth request. Routes under `/api/auth` go to better-auth, and so do
+   * the OAuth discovery documents its options configure (`./discovery`); the
+   * internal session route is handled here; anything else is a 404.
+   *
+   * The base path is not configurable. The worker half only ever forwards
+   * `/api/auth/*` (`createDoAuthWiring`, which codegen calls with no base path),
+   * so a second knob here could only ever disagree with it.
+   */
+  fetch(request: Request): Promise<Response>;
+}
+/**
+ * The exact `.well-known` paths this auth configuration serves outside its base
+ * path: the protected-resource metadata for each MCP resource, and the
+ * authorization-server metadata for the issuer. Empty unless an
+ * `oauthProvider()` or `mcp()` plugin is configured.
+ * @throws LunoraError `AUTH_MCP_RESOURCE_AMBIGUOUS` — see {@link mcpResourceOf}.
+ */
+declare const authDiscoveryPaths: (options: LunoraAuthOptions) => ReadonlyArray<string>;
+/**
+ * Derive {@link authDiscoveryPaths} for an `.auth()` declaration, memoised on the
+ * declaration object. A framework-hosted worker rebuilds its options on every
+ * request, and calling `options(env)` each time would rebuild every plugin.
+ */
+declare const authDiscoveryPathsFor: <Env>(declaration: {
+  options: (env: Env) => LunoraAuthOptions;
+}, env: Env) => ReadonlyArray<string>;
+/**
+ * Serve an OAuth discovery document from `auth` when `request` asks for one of the
+ * paths {@link authDiscoveryPaths} derives from its options; `undefined` for
+ * anything else, so the caller's own 404 stands. A 404 from better-auth itself is
+ * also passed over as `undefined`.
+ */
+declare const handleAuthDiscoveryRequest: (auth: LunoraAuth, request: Request) => Promise<Response | undefined>;
+/**
+ * The `CREATE TABLE` / `CREATE INDEX` statements for a better-auth config, in
+ * execution order (every table before any index).
+ *
+ * All statements are `IF NOT EXISTS`, so this is safe to run on every cold start —
+ * which is how `LunoraAuthDO` uses it. It creates; it never alters or drops, so a
+ * schema that has already diverged is left alone rather than half-migrated.
+ *
+ * Physical names throughout: `modelName` for tables, `fieldName ?? key` for columns,
+ * and better-auth's own resolved `columns` / `name` for indexes — so an index name
+ * here is the name better-auth's introspection expects to find.
+ * @param options The better-auth options the DO will run — the plugin list decides which tables exist.
+ * @returns SQL statements to execute in order.
+ */
+declare const authDoSchemaStatements: (options: LunoraAuthOptions) => string[];
+/**
+ * `ALTER TABLE … ADD COLUMN` statements for columns the live schema is missing.
+ *
+ * ## Why this is needed at all
+ *
+ * {@link authDoSchemaStatements} is entirely `IF NOT EXISTS`, which makes it safe to
+ * re-run but blind to change: a *new table* appears on the next cold start, a *new
+ * column on an existing table* never does. That is not a hypothetical — enabling the
+ * `admin` plugin after first deploy adds `role` / `banned` / `banExpires` to `user`,
+ * and without this the object would keep serving a `user` table that cannot hold them.
+ *
+ * Additive only. Nothing here drops, renames, or retypes a column: a column that
+ * exists is left exactly as it is, so a schema someone has deliberately diverged is
+ * never "corrected" underneath them.
+ *
+ * ## What SQLite will not let us do
+ *
+ * `ADD COLUMN` cannot introduce a `NOT NULL` column without a default (existing rows
+ * would violate it immediately), and cannot introduce `UNIQUE`. So a required column
+ * with a static default is added with both; a required column *without* one is added
+ * **nullable**, which differs from what a fresh `CREATE TABLE` would produce. That is
+ * the deliberate trade: better-auth writes these fields on every insert, so nullable
+ * is harmless, whereas refusing to add the column at all would leave the object
+ * broken. Uniqueness is unaffected — better-auth expresses it as a separate index, and
+ * those are `IF NOT EXISTS`, so they are created by the statements above.
+ * @param options The better-auth options the DO runs, already resolved.
+ * @param existingColumns Physical column names currently present on a table; empty/absent for a table that does not exist yet (it will be created instead).
+ * @returns SQL statements to execute in order; empty when the live schema is current.
+ */
+declare const authDoColumnAdditions: (options: LunoraAuthOptions, existingColumns: (table: string) => Iterable<string>) => string[];
+/** What one table looked like after a copy call. */
+interface AuthMoveTableReport {
+  /** Rows that collided with a row the pinned object holds on its own, kept as they are (only under `force`). */
+  conflicts: number;
+  /** Rows this call inserted into the target. */
+  copied: number;
+  /** Rows this call deleted from the target because the source deleted them since they were copied. */
+  deleted: number;
+  /** Rows in the source object. */
+  sourceRows: number;
+  table: string;
+  /** Rows in the target object after this call. */
+  targetRows: number;
+  /** Rows this call read that the target already held exactly. */
+  unchanged: number;
+  /** Rows this call updated in the target because the source changed them since they were copied. */
+  updated: number;
+}
+/** The answer to one copy call. */
+interface AuthMoveResult {
+  /** `true` once every table is copied and matches the source's fingerprint; otherwise call again. */
+  done: boolean;
+  tables: AuthMoveTableReport[];
+}
+/** The worker-side move between the un-pinned and the pinned auth object. */
+interface AuthJurisdictionMove {
+  /**
+   * Copy every table from the un-pinned object into the pinned one. Refuses, unless
+   * `force` is set, a pinned object holding users the copy did not write, and a row
+   * that collides with one.
+   */
+  copy: (options?: {
+    force?: boolean;
+  }) => Promise<AuthMoveResult>;
+  /**
+   * Drop every table in the un-pinned object. Refused unless every table was copied
+   * and still matches what was copied.
+   */
+  purge: () => Promise<{
+    dropped: string[];
+  }>;
+}
+/** The slice of a Durable Object namespace this needs — structural, so tests need no runtime. */
+interface AuthNamespaceLike {
+  get(this: void, id: unknown): {
+    fetch: (request: Request) => Promise<Response>;
+  };
+  idFromName(this: void, name: string): unknown;
+  /** Jurisdiction-restricted subnamespace. Optional only so older binding types still fit; {@link createDoAuthWiring} fails closed without it when a jurisdiction is set. */
+  jurisdiction?(this: void, jurisdiction: AuthJurisdiction): AuthNamespaceLike;
+}
+/**
+ * Cloudflare Durable Object data-residency jurisdiction. Widening union —
+ * Cloudflare adds values over time.
+ */
+type AuthJurisdiction = "eu" | "fedramp" | "us";
+/** What {@link createDoAuthWiring} needs, already resolved against `env`. */
+interface DoAuthWiringOptions {
+  /**
+   * The OAuth discovery paths the object serves outside `/api/auth` —
+   * `authDiscoveryPaths(options)` over the same auth options the object builds.
+   * Derived in the worker so a probe of any other path never costs a round-trip
+   * to the object. Empty or absent: nothing is forwarded.
+   */
+  discoveryPaths?: ReadonlyArray<string>;
+  /**
+   * Shared secret presented on the object's internal session route. `undefined`
+   * means identity resolution fails closed — see {@link DoAuthWiring.resolveIdentity}.
+   */
+  internalSecret: string | undefined;
+  /**
+   * Pin the auth object to a data-residency jurisdiction — pass the worker's
+   * `jurisdiction`. The object holds users, sessions, and credentials, so it must
+   * live where the rest of the app's data does. The same name maps to a different
+   * object per jurisdiction, so toggling this on an existing deployment starts a
+   * fresh, empty auth object.
+   */
+  jurisdiction?: AuthJurisdiction;
+  /** The bound namespace, or `undefined` when the binding is absent from `env`. */
+  namespace: AuthNamespaceLike | undefined;
+  /**
+   * Name of the object instance holding the auth tables. Defaults to `"auth"`.
+   *
+   * One object owns the whole auth schema, so this exists to let an app pick the
+   * name (or run separate objects per deployment/tenant) rather than being pinned to
+   * a hardcoded one.
+   */
+  objectName?: string;
+}
+/** The worker options DO-backed auth replaces. */
+interface DoAuthWiring {
+  /**
+   * Reads the audit log out of the object, so the studio's audit feed works in DO
+   * mode. Answers an empty page rather than throwing when the object is unreachable
+   * or no secret is configured — an unavailable feed should read as empty, not 500
+   * the studio.
+   */
+  auditReader: AuthAuditReader;
+  /**
+   * Forwards `/api/auth/*` to the object; `undefined` for anything else.
+   *
+   * The base path is fixed. It was configurable on both halves of DO-backed auth
+   * and settable on neither: codegen's `AuthDeclaration` has no field for it, so
+   * the emitted `createDoAuthWiring(...)` never passed one and an `AuthDO`
+   * subclass that set its own served nothing.
+   */
+  authHandler: (request: Request) => Promise<Response | undefined>;
+  /**
+   * Forwards a `GET`/`HEAD` for one of {@link DoAuthWiringOptions.discoveryPaths}
+   * to the object; `undefined` for anything else, and for the object's 404. The
+   * worker calls it only after the app's own routes missed.
+   */
+  discoveryHandler: (request: Request) => Promise<Response | undefined>;
+  /**
+   * Copy the auth tables from the un-pinned object into the pinned one, and later
+   * purge the un-pinned copy. Present only when a `jurisdiction` is set. Backs the
+   * worker's `copyAuthToJurisdiction` and `purgeUnpinnedAuth` admin ops.
+   */
+  jurisdictionMove?: AuthJurisdictionMove;
+  /**
+   * Resolves a request's identity by asking the object. `null` when anonymous,
+   * unreachable, or ungated.
+   *
+   * `expiresAtMs` (epoch ms) is the session's expiry, which the runtime forwards as
+   * the socket's credential expiry so the DO can drop a subscriber whose session has
+   * lapsed; `role` is better-auth's `admin()` column, which RLS role grants read;
+   * `email` and `name` are the profile claims `ctx.auth.getIdentity()` is documented
+   * to carry. Each is absent when the session does not carry it.
+   */
+  resolveIdentity: (request: Request) => Promise<null | {
+    email?: string;
+    expiresAtMs?: number;
+    name?: string;
+    role?: string;
+    userId: string;
+  }>;
+}
+/**
+ * Build the worker-side wiring for an auth Durable Object.
+ *
+ * Every failure path answers "not authenticated" rather than throwing: this runs on
+ * the request path for every request that touches `ctx.auth`, and a throw there would
+ * turn a misconfiguration into a 500 on traffic that has nothing to do with auth.
+ * The exception is a `jurisdiction` the namespace cannot express, which throws here.
+ * @param options The resolved namespace, secret, and names.
+ * @returns The `authHandler` / `resolveIdentity` pair.
+ */
+declare const createDoAuthWiring: (options: DoAuthWiringOptions) => DoAuthWiring;
+/** 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.
+ */
 declare const DEFAULT_AUTH_BASE_PATH: string;
 /**
-* Route an inbound `Request` to better-auth if the path falls under
-* `basePath`; otherwise return `null` so the caller can continue dispatching.
-*
-* Better-auth handles arbitrarily nested paths (`/api/auth/sign-in/email`,
-* `/api/auth/callback/github`, …), so we use prefix matching instead of the
-* exact-path map `createWorker` consumes for top-level routes.
-*/
+ * Route an inbound `Request` to better-auth if the path falls under
+ * `basePath`; otherwise return `undefined` so the caller can continue dispatching.
+ *
+ * Better-auth handles arbitrarily nested paths (`/api/auth/sign-in/email`,
+ * `/api/auth/callback/github`, …), so we use prefix matching instead of the
+ * exact-path map `createWorker` consumes for top-level routes.
+ */
 declare const handleAuthRequest: (auth: LunoraAuth, request: Request, basePath?: string) => Promise<Response | undefined>;
 /**
-* Apply better-auth's required schema (`user`, `session`, `account`,
-* `verification`) to the configured database. Idempotent — better-auth
-* diffs the existing schema and only runs the missing DDL.
-*
-* Cached per `options` reference so the diff cost (one PRAGMA-style sweep
-* per table) doesn't fire on every request. In Cloudflare Workers the same
-* `env.DB` binding is reused across invocations within a single isolate, so
-* caching against the options object — which captures the binding — is
-* sufficient.
-*
-* For production you should prefer pre-applying the schema at deploy time
-* via `compileMigrationsSql` + `wrangler d1 execute`; this helper exists for
-* dev/playground and small deployments.
-*/
+ * The cleanup statements, in execution order: every blocking index, then the column.
+ *
+ * Exported for the pre-applied-schema path (`compileMigrationsSql` + `wrangler d1 execute`),
+ * which compiles DDL without ever reading the database and so can neither tell whether the
+ * column is present nor discover the index names — SQLite has no `DROP COLUMN IF EXISTS` to
+ * make either unnecessary. Pass the names from
+ * `SELECT name, sql FROM sqlite_master WHERE type = 'index' AND tbl_name = 'account'`, and
+ * run this only against a database that still has the column.
+ * @param accountTable Physical name of the account table (`account` unless renamed via `account.modelName`).
+ * @param indexNames Indexes to drop first, from {@link indexesReferencingIssuer}.
+ * @returns The `DROP INDEX` statements followed by the `DROP COLUMN`.
+ */
+declare const legacyIssuerCleanupStatements: (accountTable?: string, indexNames?: Iterable<string>) => string[];
+/**
+ * Apply better-auth's required schema (`user`, `session`, `account`,
+ * `verification`) to the configured database. Idempotent — better-auth
+ * diffs the existing schema and only runs the missing DDL.
+ *
+ * Cached per `options` reference so the diff cost (one PRAGMA-style sweep
+ * per table) doesn't fire on every request. In Cloudflare Workers the same
+ * `env.DB` binding is reused across invocations within a single isolate, so
+ * caching against the options object — which captures the binding — is
+ * sufficient.
+ *
+ * For production you should prefer pre-applying the schema at deploy time
+ * via `compileMigrationsSql` + `wrangler d1 execute`; this helper exists for
+ * dev/playground and small deployments.
+ */
 declare const ensureMigrated: (auth: LunoraAuth | {
   options: LunoraAuthOptions;
 }) => Promise<void>;
 /**
-* Compile better-auth's migrations to a single SQL string. Useful for
-* `wrangler d1 execute --file -` in CI so the deploy step applies the schema
-* before the first user request.
-*
-* Compiles from the SAME resolved options `createAuth` runs with (via
-* `resolveAuthOptions`), not the raw caller options — so the schema includes the
-* `rateLimit` table the worker's default-on durable limiter writes to. Compiling
-* from the raw options would omit it, and the running worker would then write to
-* a table the migration never created.
-*/
+ * Compile better-auth's migrations to a single SQL string. Useful for
+ * `wrangler d1 execute --file -` in CI so the deploy step applies the schema
+ * before the first user request.
+ *
+ * Compiles from the SAME resolved options `createAuth` runs with (via
+ * `resolveAuthOptions`), not the raw caller options — so the schema includes the
+ * `rateLimit` table the worker's default-on durable limiter writes to. Compiling
+ * from the raw options would omit it, and the running worker would then write to
+ * a table the migration never created.
+ *
+ * **Upgrading a database created by an older `@lunora/auth`.** This compiles DDL without
+ * reading the database, so it cannot know whether the `account.issuer` column better-auth
+ * 1.7.0 required and 1.7.3 reverted is present — and SQLite has no `DROP COLUMN IF EXISTS`
+ * to make that moot. `ensureMigrated` handles it automatically; on this path, run
+ * `legacyIssuerCleanupStatements()` once against a database that still has the column.
+ * Leaving it in place fails every sign-up with `NOT NULL constraint failed: account.issuer`.
+ */
 declare const compileMigrationsSql: (options: LunoraAuthOptions) => Promise<string>;
 /**
-* Lunora-friendly view over better-auth's `session` option.
-*
-* This is a typed alias for better-auth's own `session` shape — Lunora stays a
-* thin wrapper, so we don't reimplement the fields, we just give them a named,
-* documented home so callers get autocomplete without reaching into
-* `BetterAuthOptions`. The most relevant fields for session rotation / richer
-* policies are `expiresIn` (absolute session lifetime, in seconds),
-* `updateAge` (rolling-rotation interval, in seconds — how often an active
-* session's expiry is pushed forward; `0` rotates on every use),
-* `disableSessionRefresh` (turn rolling rotation off entirely so sessions
-* expire at the absolute `expiresIn` regardless of activity), `freshAge`
-* (freshness window, in seconds, for sensitive operations like account
-* deletion; `0` treats every session as fresh — not recommended), and
-* `cookieCache` (opt-in signed-cookie session cache to skip DB reads).
-*
-* See better-auth's `session` option for the full field list.
-*/
+ * Lunora-friendly view over better-auth's `session` option.
+ *
+ * This is a typed alias for better-auth's own `session` shape — Lunora stays a
+ * thin wrapper, so we don't reimplement the fields, we just give them a named,
+ * documented home so callers get autocomplete without reaching into
+ * `BetterAuthOptions`. The most relevant fields for session rotation / richer
+ * policies are `expiresIn` (absolute session lifetime, in seconds),
+ * `updateAge` (rolling-rotation interval, in seconds — how often an active
+ * session's expiry is pushed forward; `0` rotates on every use),
+ * `disableSessionRefresh` (turn rolling rotation off entirely so sessions
+ * expire at the absolute `expiresIn` regardless of activity), `freshAge`
+ * (freshness window, in seconds, for sensitive operations like account
+ * deletion; `0` treats every session as fresh — not recommended), and
+ * `cookieCache` (signed-cookie session cache that skips DB reads —
+ * `createAuth` fills `{ enabled: true, maxAge: 60 }` when you leave it unset, so
+ * a revoked session keeps authenticating for up to that many seconds; pass
+ * `{ enabled: false }` where that window is unacceptable).
+ *
+ * See better-auth's `session` option for the full field list.
+ */
 type SessionPolicy = NonNullable<BetterAuthOptions["session"]>;
 /**
-* Validate a {@link SessionPolicy} and return it unchanged (pass-through).
-*
-* better-auth happily accepts the `session` block verbatim, so the only job
-* here is to catch obviously-broken numeric inputs at construction time —
-* negative or non-finite durations — rather than letting them produce
-* surprising cookie expiries at runtime. Field names mirror better-auth's
-* `session` option exactly so the validated object forwards 1:1.
-*/
+ * Validate a {@link SessionPolicy} and return it unchanged (pass-through).
+ *
+ * better-auth happily accepts the `session` block verbatim, so the only job
+ * here is to catch obviously-broken numeric inputs at construction time —
+ * negative or non-finite durations — rather than letting them produce
+ * surprising cookie expiries at runtime. Field names mirror better-auth's
+ * `session` option exactly so the validated object forwards 1:1.
+ */
 declare const validateSessionPolicy: (policy: SessionPolicy) => SessionPolicy;
 /**
-* Ready-made {@link SessionPolicy} presets covering the common rotation /
-* expiry trade-offs. Spread or override fields as needed:
-*
-* ```ts
-* import { createAuth, sessionPresets } from "@lunora/auth";
-*
-* export const auth = createAuth({
-*     secret: env.AUTH_SECRET,
-*     database: env.DB,
-*     session: { ...sessionPresets.rolling, freshAge: 60 * 5 },
-* });
-* ```
-*
-* - `rolling` — balanced default: 7-day absolute expiry, rotated once per day,
-*   with a 60s signed-cookie session cache so bursts of authenticated calls
-*   skip the per-request DB session read.
-* - `strict` — short, security-sensitive: 1-hour expiry, 15-minute rotation,
-*   cookie cache **off** (fast revocation / short freshness is the whole point).
-* - `longLived` — low-friction consumer apps: 30-day expiry, daily rotation,
-*   with the same 60s cookie cache as `rolling`.
-*/
+ * Ready-made {@link SessionPolicy} presets covering the common rotation /
+ * expiry trade-offs. Spread or override fields as needed:
+ *
+ * ```ts
+ * import { createAuth, sessionPresets } from "@lunora/auth";
+ *
+ * export const auth = createAuth({
+ *     secret: env.AUTH_SECRET,
+ *     database: env.DB,
+ *     session: { ...sessionPresets.rolling, freshAge: 60 * 5 },
+ * });
+ * ```
+ *
+ * - `rolling` — balanced default: 7-day absolute expiry, rotated once per day,
+ *   with a 60s signed-cookie session cache so bursts of authenticated calls
+ *   skip the per-request DB session read.
+ * - `strict` — short, security-sensitive: 1-hour expiry, 15-minute rotation,
+ *   cookie cache **off** (fast revocation / short freshness is the whole point).
+ * - `longLived` — low-friction consumer apps: 30-day expiry, daily rotation,
+ *   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 AuthInvitation, type AuthMember, type AuthOrganization, type AuthPage, type AuthPasskey, type AuthTimestamp, type CreateAuthAdminOptions, DEFAULT_AUTH_BASE_PATH, type ImpersonationResult, type ListUsersOptions, type LunoraAuth, LunoraAuthAdminError, type LunoraAuthOptions, type SessionPolicy, compileMigrationsSql, createAuthAdmin, ensureMigrated, handleAuthRequest, sessionPresets, validateSessionPolicy };
+export { READ_AUDIT_PATH as AUTH_DO_AUDIT_PATH, INTERNAL_SECRET_HEADER as AUTH_DO_SECRET_HEADER, RESOLVE_SESSION_PATH as AUTH_DO_SESSION_PATH, type AppendAuthAuditEntry, type AppendAuthAuditOptions, type AuthAccount, type AuthAdmin, type AuthAdminSession, type AuthAdminUser, type AuthAuditEvent, type AuthAuditHookConfig, type AuthAuditReader, type AuthCapabilities, type AuthConfigInfo, type AuthDoOptions, type AuthDoState, type AuthInvitation, type AuthJurisdiction, type AuthJurisdictionMove, type AuthMember, type AuthMoveResult, type AuthMoveTableReport, type AuthNamespaceLike, type AuthOrgRole, type AuthOrganization, type AuthPage, type AuthPasskey, type AuthSignUpInvitation, type AuthTeam, type AuthTeamMember, type AuthTimestamp, type AuthUserFieldSpec, type CreateAuthAdminOptions, DEFAULT_AUTH_BASE_PATH, type DoAuthWiring, type DoAuthWiringOptions, type EmailClassification, type EmailGateConfig, type EmailGateHookConfig, type ImpersonationResult, type ListUsersOptions, type LunoraAuth, LunoraAuthAdminError, LunoraAuthDO, type LunoraAuthOptions, type SessionPolicy, type SqlExecutor, authAuditHook, authDiscoveryPaths, authDiscoveryPathsFor, authDoColumnAdditions, authDoSchemaStatements, buildAuditEntry, compileMigrationsSql, createAuthAdmin, createDoAuthWiring, emailGateDatabaseHooks, ensureMigrated, eventForPath, handleAuthDiscoveryRequest, handleAuthRequest, legacyIssuerCleanupStatements, sessionPresets, validateSessionPolicy, withAuthAudit, withEmailGate };