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

package/dist/middleware.d.ts

@@ -1,12 +1,12 @@
 import { LunoraError } from '@lunora/errors';
-import { L as LunoraAuth } from "./packem_shared/create-auth.d-Mwhb4gSc.js";
+import { L as LunoraAuth } from "./packem_shared/create-auth.d-COcIS_KU.js";
 import 'better-auth';
 /**
-* Structural mirror of `@lunora/server`'s `MiddlewareNext` — the continuation
-* callback handed to a middleware. Repeated here so this package does not take
-* a runtime dependency on `@lunora/server`; the types are assignable from the
-* fully-typed builder.
-*/
+ * Structural mirror of `@lunora/server`'s `MiddlewareNext` — the continuation
+ * callback handed to a middleware. Repeated here so this package does not take
+ * a runtime dependency on `@lunora/server`; the types are assignable from the
+ * fully-typed builder.
+ */
 interface MiddlewareNext<ContextIn> {
   (): Promise<ContextIn>;
   <Extension extends Record<string, unknown>>(options: {
@@ -14,174 +14,174 @@ interface MiddlewareNext<ContextIn> {
   }): Promise<ContextIn & Extension>;
 }
 /**
-* Thrown by the runtime header guard when a privileged `ctx.authApi.*` endpoint
-* is invoked without a `headers` property on its argument object. Carries the
-* offending `method` name so callers can pinpoint the bad call site, and points
-* at the explicit escape hatches.
-*
-* This is the runtime sibling of the static `auth_api_call_without_headers`
-* advisor lint — both treat a header-less `ctx.authApi.*` call as an
-* authorization bypass, so a call that trips the lint also trips this guard.
-*/
+ * Thrown by the runtime header guard when a privileged `ctx.authApi.*` endpoint
+ * is invoked without a `headers` property on its argument object. Carries the
+ * offending `method` name so callers can pinpoint the bad call site, and points
+ * at the explicit escape hatches.
+ *
+ * This is the runtime sibling of the static `auth_api_call_without_headers`
+ * advisor lint — both treat a header-less `ctx.authApi.*` call as an
+ * authorization bypass, so a call that trips the lint also trips this guard.
+ */
 declare class LunoraAuthHeadersError extends LunoraError {
   /** The `ctx.authApi.&lt;method>` that was called without `headers`. */
   readonly method: string;
   constructor(method: string);
 }
 /**
-* Options for {@link withAuthPlugins}.
-*/
+ * Options for {@link withAuthPlugins}.
+ */
 interface WithAuthPluginsOptions {
   /**
-  * Whether to install the runtime header guard around `ctx.authApi`.
-  *
-  * **Defaults to `true` — the safe default.** When enabled, every
-  * `ctx.authApi.&lt;method>(…)` call that omits `headers` throws
-  * {@link LunoraAuthHeadersError} instead of silently running with full
-  * server-to-server privileges. For a deliberate, per-call unauthenticated
-  * invocation, use the explicit `ctx.authApi.withoutHeaders()` escape hatch
-  * rather than disabling the guard wholesale.
-  *
-  * Set to `false` only when you have audited every `ctx.authApi.*` call site
-  * and accept responsibility for passing headers yourself. This is the loud,
-  * all-or-nothing opt-out; prefer `withoutHeaders()` for one-offs.
-  */
+   * Whether to install the runtime header guard around `ctx.authApi`.
+   *
+   * **Defaults to `true` — the safe default.** When enabled, every
+   * `ctx.authApi.&lt;method>(…)` call that omits `headers` throws
+   * {@link LunoraAuthHeadersError} instead of silently running with full
+   * server-to-server privileges. For a deliberate, per-call unauthenticated
+   * invocation, use the explicit `ctx.authApi.withoutHeaders()` escape hatch
+   * rather than disabling the guard wholesale.
+   *
+   * Set to `false` only when you have audited every `ctx.authApi.*` call site
+   * and accept responsibility for passing headers yourself. This is the loud,
+   * all-or-nothing opt-out; prefer `withoutHeaders()` for one-offs.
+   */
   enforceHeaders?: boolean;
 }
 /**
-* The Lunora context extension this middleware installs. It does *not* replace
-* `ctx.auth` (the identity-only surface populated by the runtime — `userId` and
-* `getIdentity()`); instead it adds a sibling `ctx.authApi` that points at the
-* full better-auth plugin API surface.
-*
-* The shape of `authApi` is the shape of the better-auth instance's `api` —
-* a flat record of endpoint functions like `createOrganization`, `banUser`,
-* `listMembers`, … contributed by whichever plugins are configured on the auth
-* instance. Because the type is `Auth["api"]` and `LunoraAuth` is generic over
-* the auth instance, callers get end-to-end inference: the endpoints they see
-* are exactly the ones their auth instance loaded.
-*/
+ * The Lunora context extension this middleware installs. It does *not* replace
+ * `ctx.auth` (the identity-only surface populated by the runtime — `userId` and
+ * `getIdentity()`); instead it adds a sibling `ctx.authApi` that points at the
+ * full better-auth plugin API surface.
+ *
+ * The shape of `authApi` is the shape of the better-auth instance's `api` —
+ * a flat record of endpoint functions like `createOrganization`, `banUser`,
+ * `listMembers`, … contributed by whichever plugins are configured on the auth
+ * instance. Because the type is `Auth["api"]` and `LunoraAuth` is generic over
+ * the auth instance, callers get end-to-end inference: the endpoints they see
+ * are exactly the ones their auth instance loaded.
+ */
 interface LunoraAuthApiContext<Auth extends LunoraAuth> {
   /**
-  * The better-auth endpoint surface — every endpoint contributed by every
-  * plugin configured on the auth instance, ready to call directly:
-  *
-  * ```ts
-  * await ctx.authApi.createOrganization({ body: { name: "Acme" }, headers });
-  * await ctx.authApi.banUser({ body: { userId: "u_1" }, headers });
-  * ```
-  *
-  * # ⚠️ SECURITY: privileged surface — you MUST pass `headers`
-  *
-  * This is the **full, privileged** better-auth API (`auth.api`) — it
-  * includes admin/management endpoints such as `banUser`, `setRole`,
-  * impersonation, `createOrganization`, `removeMember`, … better-auth
-  * authorizes these calls from the caller's session in the `headers` you
-  * pass. Invoked **without** `headers`, better-auth treats the call as a
-  * trusted server-side invocation and **bypasses session authorization
-  * entirely** — any procedure that can reach `ctx.authApi` could then ban a
-  * user, escalate a role, or read another tenant's data.
-  *
-  * To stop that bypass at runtime, `withAuthPlugins` installs a guard around
-  * `ctx.authApi` by default: a header-less call to any endpoint throws
-  * {@link LunoraAuthHeadersError} rather than running with full privileges.
-  * The same `auth_api_call_without_headers` advisor lint catches it
-  * statically; the guard is the runtime backstop for the cases the lint
-  * can't see (dynamic method names, indirected calls). For the rare,
-  * deliberate unauthenticated server-to-server call, opt out explicitly with
-  * `ctx.authApi.withoutHeaders().&lt;method>(…)`.
-  *
-  * Lunora's procedure context carries only the resolved identity, not the
-  * raw inbound `Headers`, so this middleware CANNOT pre-bind them for you.
-  * Therefore: **thread the inbound `Headers` into every `ctx.authApi.*`
-  * call** (typically from an HTTP action — see {@link withAuthPlugins}). A
-  * header-less call is an authorization bypass, not a convenience.
-  */
+   * The better-auth endpoint surface — every endpoint contributed by every
+   * plugin configured on the auth instance, ready to call directly:
+   *
+   * ```ts
+   * await ctx.authApi.createOrganization({ body: { name: "Acme" }, headers });
+   * await ctx.authApi.banUser({ body: { userId: "u_1" }, headers });
+   * ```
+   *
+   * # ⚠️ SECURITY: privileged surface — you MUST pass `headers`
+   *
+   * This is the **full, privileged** better-auth API (`auth.api`) — it
+   * includes admin/management endpoints such as `banUser`, `setRole`,
+   * impersonation, `createOrganization`, `removeMember`, … better-auth
+   * authorizes these calls from the caller's session in the `headers` you
+   * pass. Invoked **without** `headers`, better-auth treats the call as a
+   * trusted server-side invocation and **bypasses session authorization
+   * entirely** — any procedure that can reach `ctx.authApi` could then ban a
+   * user, escalate a role, or read another tenant's data.
+   *
+   * To stop that bypass at runtime, `withAuthPlugins` installs a guard around
+   * `ctx.authApi` by default: a header-less call to any endpoint throws
+   * {@link LunoraAuthHeadersError} rather than running with full privileges.
+   * The same `auth_api_call_without_headers` advisor lint catches it
+   * statically; the guard is the runtime backstop for the cases the lint
+   * can't see (dynamic method names, indirected calls). For the rare,
+   * deliberate unauthenticated server-to-server call, opt out explicitly with
+   * `ctx.authApi.withoutHeaders().&lt;method>(…)`.
+   *
+   * Lunora's procedure context carries only the resolved identity, not the
+   * raw inbound `Headers`, so this middleware CANNOT pre-bind them for you.
+   * Therefore: **thread the inbound `Headers` into every `ctx.authApi.*`
+   * call** (typically from an HTTP action — see {@link withAuthPlugins}). A
+   * header-less call is an authorization bypass, not a convenience.
+   */
   readonly authApi: {
     /**
-    * Explicit, loud escape hatch from the runtime header guard. Returns
-    * the raw, **unguarded** `auth.api` surface — every endpoint reached
-    * through it runs as a trusted server-to-server call with session
-    * authorization skipped.
-    *
-    * ```ts
-    * // A scheduled job with no inbound request that must create the
-    * // system org. Audited and intentional:
-    * await ctx.authApi.withoutHeaders().createOrganization({ body: { name } });
-    * ```
-    *
-    * Use only for deliberate, audited unauthenticated calls. For ordinary
-    * request-driven calls, pass `headers` so authorization is enforced.
-    */
+     * Explicit, loud escape hatch from the runtime header guard. Returns
+     * the raw, **unguarded** `auth.api` surface — every endpoint reached
+     * through it runs as a trusted server-to-server call with session
+     * authorization skipped.
+     *
+     * ```ts
+     * // A scheduled job with no inbound request that must create the
+     * // system org. Audited and intentional:
+     * await ctx.authApi.withoutHeaders().createOrganization({ body: { name } });
+     * ```
+     *
+     * Use only for deliberate, audited unauthenticated calls. For ordinary
+     * request-driven calls, pass `headers` so authorization is enforced.
+     */
     withoutHeaders: () => Auth["api"];
   } & Auth["api"];
 }
 /**
-* Build a Lunora middleware that mounts a better-auth instance's plugin API
-* onto `ctx.authApi`. Compose it with `.use(...)` once per builder and every
-* downstream handler gets typed access to the plugin endpoints — no more
-* importing the auth instance directly from every query/mutation file.
-*
-* # ⚠️ SECURITY: headers are load-bearing for authorization
-*
-* `ctx.authApi` is the **full privileged** better-auth surface (`auth.api`):
-* `banUser`, `setRole`, impersonation, `createOrganization`, `removeMember`,
-* and so on. better-auth authorizes these from the caller's session carried in
-* the `headers` you pass. **Called without `headers`, better-auth treats the
-* invocation as a trusted server-side call and skips session authorization
-* altogether** — so a header-less `ctx.authApi.banUser(...)` from any procedure
-* runs with full privileges regardless of who the caller is. This is an
-* authorization bypass, not just a missing convenience.
-*
-* To make that bypass fail loudly instead of silently, this middleware wraps
-* `ctx.authApi` in a **runtime header guard by default**: any endpoint called
-* without a `headers` property throws {@link LunoraAuthHeadersError}. The guard
-* mirrors the static `auth_api_call_without_headers` advisor lint exactly, so
-* the two agree on what counts as a header-bearing call.
-*
-* - **Default (safe):** `withAuthPlugins(auth)` — header-less calls throw.
-* - **Per-call opt-out (preferred):** `ctx.authApi.withoutHeaders().banUser(…)`
-* for a deliberate, audited unauthenticated server-to-server call.
-* - **Whole-middleware opt-out (loud):** `withAuthPlugins(auth, { enforceHeaders: false })`
-* disables the guard entirely; only do this once every call site is audited.
-*
-* Lunora's procedure context does not currently carry the raw request headers
-* (only the resolved identity — see `AuthState` in `@lunora/server`), so
-* this middleware **cannot** pre-bind headers for you and does **not** do so.
-* You MUST pass the inbound `Headers` explicitly into **every** `ctx.authApi.*`
-* call, from a transport that has them — typically an HTTP action:
-*
-* ```ts
-* // lunora/orgs.ts
-* import { httpAction } from "@lunora/server";
-* import { withAuthPlugins } from "@lunora/auth/middleware";
-* import { auth } from "./auth.js";
-*
-* export const createOrg = httpAction(async (ctx, request) => {
-*     const { name } = await request.json();
-*
-*     // ctx.authApi is installed by withAuthPlugins(auth) on the builder.
-*     const org = await ctx.authApi.createOrganization({
-*         body: { name },
-*         headers: request.headers,
-*     });
-*
-*     return Response.json(org);
-* });
-* ```
-*
-* For internal server-to-server calls where there is no inbound request
-* (e.g. a scheduled job that creates the system org), opt out explicitly with
-* `ctx.authApi.withoutHeaders()` and authenticate with whatever bearer token
-* your auth instance is configured to honour.
-*/
+ * Build a Lunora middleware that mounts a better-auth instance's plugin API
+ * onto `ctx.authApi`. Compose it with `.use(...)` once per builder and every
+ * downstream handler gets typed access to the plugin endpoints — no more
+ * importing the auth instance directly from every query/mutation file.
+ *
+ * # ⚠️ SECURITY: headers are load-bearing for authorization
+ *
+ * `ctx.authApi` is the **full privileged** better-auth surface (`auth.api`):
+ * `banUser`, `setRole`, impersonation, `createOrganization`, `removeMember`,
+ * and so on. better-auth authorizes these from the caller's session carried in
+ * the `headers` you pass. **Called without `headers`, better-auth treats the
+ * invocation as a trusted server-side call and skips session authorization
+ * altogether** — so a header-less `ctx.authApi.banUser(...)` from any procedure
+ * runs with full privileges regardless of who the caller is. This is an
+ * authorization bypass, not just a missing convenience.
+ *
+ * To make that bypass fail loudly instead of silently, this middleware wraps
+ * `ctx.authApi` in a **runtime header guard by default**: any endpoint called
+ * without a `headers` property throws {@link LunoraAuthHeadersError}. The guard
+ * mirrors the static `auth_api_call_without_headers` advisor lint exactly, so
+ * the two agree on what counts as a header-bearing call.
+ *
+ * - **Default (safe):** `withAuthPlugins(auth)` — header-less calls throw.
+ * - **Per-call opt-out (preferred):** `ctx.authApi.withoutHeaders().banUser(…)`
+ * for a deliberate, audited unauthenticated server-to-server call.
+ * - **Whole-middleware opt-out (loud):** `withAuthPlugins(auth, { enforceHeaders: false })`
+ * disables the guard entirely; only do this once every call site is audited.
+ *
+ * Lunora's procedure context does not currently carry the raw request headers
+ * (only the resolved identity — see `AuthState` in `@lunora/server`), so
+ * this middleware **cannot** pre-bind headers for you and does **not** do so.
+ * You MUST pass the inbound `Headers` explicitly into **every** `ctx.authApi.*`
+ * call, from a transport that has them — typically an HTTP action:
+ *
+ * ```ts
+ * // lunora/orgs.ts
+ * import { httpAction } from "@lunora/server";
+ * import { withAuthPlugins } from "@lunora/auth/middleware";
+ * import { auth } from "./auth.js";
+ *
+ * export const createOrg = httpAction(async (ctx, request) => {
+ *     const { name } = await request.json();
+ *
+ *     // ctx.authApi is installed by withAuthPlugins(auth) on the builder.
+ *     const org = await ctx.authApi.createOrganization({
+ *         body: { name },
+ *         headers: request.headers,
+ *     });
+ *
+ *     return Response.json(org);
+ * });
+ * ```
+ *
+ * For internal server-to-server calls where there is no inbound request
+ * (e.g. a scheduled job that creates the system org), opt out explicitly with
+ * `ctx.authApi.withoutHeaders()` and authenticate with whatever bearer token
+ * your auth instance is configured to honour.
+ */
 /**
-* Shape of the middleware {@link withAuthPlugins} returns: a callable generic
-* over the incoming ctx so chaining `.use(...)` preserves whatever ctx fields
-* the upstream middleware already installed. Lives as its own interface
-* because TypeScript doesn't allow declaring `const fn: &lt;CtxIn>() => ...` —
-* the generic must live on a callable type alias or interface.
-*/
+ * Shape of the middleware {@link withAuthPlugins} returns: a callable generic
+ * over the incoming ctx so chaining `.use(...)` preserves whatever ctx fields
+ * the upstream middleware already installed. Lives as its own interface
+ * because TypeScript doesn't allow declaring `const fn: &lt;CtxIn>() => ...` —
+ * the generic must live on a callable type alias or interface.
+ */
 type WithAuthPluginsMiddleware<Auth extends LunoraAuth> = <ContextIn>(options: {
   ctx: ContextIn;
   next: MiddlewareNext<ContextIn>;

package/dist/packem_shared/create-auth.d-COcIS_KU.d.mts

@@ -0,0 +1,128 @@
+import { betterAuth, BetterAuthOptions } from 'better-auth';
+/**
+ * Lunora's options pass straight through to better-auth — the only thing we add
+ * is requiring `secret` up front so a misconfigured deployment fails loudly
+ * instead of at the first sign-in.
+ *
+ * For `database`, prefer `lunoraD1Adapter` (`database: lunoraD1Adapter(env.DB)`)
+ * over passing the raw `env.DB`. better-auth *does* accept a D1Database directly,
+ * but it then resolves its Kysely adapter via a runtime `await import(...)` inside
+ * `auth.$context` — and that import never settles under `@cloudflare/vite-plugin`'s
+ * worker runner, hanging every auth request in `pnpm dev`. The explicit adapter
+ * skips it, so dev and prod behave the same. (Raw `env.DB` is still correct for
+ * the migration-only instance — see `lunoraD1Adapter`'s note.)
+ *
+ * Session rotation / richer session policies are configured via the `session`
+ * field (a `SessionPolicy`); Lunora validates it for obviously-broken
+ * durations and forwards it verbatim to better-auth. See `sessionPresets`
+ * for ready-made rotation/expiry trade-offs.
+ *
+ * ## Serverless background tasks (Cloudflare Workers)
+ *
+ * better-auth runs some work *after* sending the response — most importantly the
+ * password-reset email, whose background send is what keeps reset responses
+ * constant-time (a timing-attack defence: the response doesn't reveal whether
+ * the account exists). On Cloudflare Workers a promise that isn't handed to
+ * `ctx.waitUntil` can be cancelled the moment the response returns, dropping
+ * that send and weakening the guarantee. Wire your request's `ctx.waitUntil`
+ * into better-auth's background handler so the work survives:
+ *
+ * ```ts
+ * // in your worker fetch handler, where `ctx: ExecutionContext` is in scope
+ * const auth = createAuth({
+ *     secret: env.AUTH_SECRET,
+ *     database: lunoraD1Adapter(env.DB),
+ *     advanced: {
+ *         backgroundTasks: { handler: (promise) => ctx.waitUntil(promise) },
+ *     },
+ * });
+ * ```
+ *
+ * (Lunora can't set this for you — `ctx.waitUntil` is per-request, but
+ * `createAuth` runs once at worker setup.)
+ */
+type LunoraAuthOptions = BetterAuthOptions;
+/**
+ * The full better-auth instance: `auth.handler` accepts a `Request` and
+ * returns a `Response` (used by `handleAuthRequest`); `auth.api`
+ * exposes the typed endpoint surface for server-side calls (e.g.
+ * `auth.api.getSession({ headers })` inside a query/mutation).
+ */
+type LunoraAuth = ReturnType<typeof betterAuth>;
+/**
+ * Resolve the caller's options into the exact shape `createAuth` hands to
+ * `betterAuth` — the hardened, default-filled options the running worker uses.
+ * Exported (and pure) so the migration path can compile the schema from the
+ * same resolved options: `compileMigrationsSql` routes through here, so the
+ * `rateLimit` table the worker's durable limiter writes to is included in the
+ * migration rather than silently omitted (it would be, if migrations saw the
+ * raw options while the worker ran the resolved ones).
+ *
+ * ## What it fills (each gated independently on caller silence)
+ *
+ * Secure-by-default cookies + secret-strength warning via {@link hardenAuthOptions},
+ * applied first so all hardening composes onto one options object.
+ *
+ * Rate limiting is ON by default for `/api/auth/*`.
+ *
+ * better-auth's own default is `rateLimit.enabled ?? isProduction`, and its
+ * `isProduction` is `"development" === "production"` resolved at
+ * module-load time. On Cloudflare Workers that check is unreliable: the
+ * runtime has no Node `process.env` (absent entirely without
+ * `nodejs_compat`, and even with it `NODE_ENV` is rarely `"production"` at
+ * request time). So better-auth would silently leave auth endpoints
+ * _unthrottled_ on a real deployment — the surprise we refuse to ship.
+ *
+ * We therefore default `enabled: true` whenever the caller hasn't made an
+ * explicit choice. We only fill the `enabled` flag and otherwise forward
+ * the caller's `rateLimit` verbatim, so better-auth's `window` (10s) / `max`
+ * (100) defaults and any custom rules still apply. Callers who genuinely
+ * want it off can pass `rateLimit: { enabled: false }` (e.g. when fronting
+ * auth with their own limiter), and any explicit `enabled` value wins.
+ *
+ * We also default `storage: "database"` — but only when rate limiting is not
+ * explicitly disabled (`enabled !== false`). Filling storage under a disabled
+ * limiter is harmless at runtime but makes `getAuthTables` emit an unused
+ * `rateLimit` table, so we skip it there.
+ *
+ * better-auth's own default is `storage: "memory"` — a per-isolate,
+ * non-durable counter. On Cloudflare Workers that means each isolate keeps
+ * its own tally, counters vanish on isolate recycle, and traffic spread
+ * across isolates never sums to the configured `max` — a limiter that
+ * reports "enabled" while never enforcing a global limit (the exact
+ * brute-force / credential-stuffing protection on `/sign-in`, OTP, and
+ * password-reset it is meant to buy). `storage: "database"` rides the counter
+ * through the configured `database` adapter — Lunora's store over the D1 auth
+ * tables — so the limit is durable *and* atomic (the store's native
+ * `incrementOne` gives a one-winner guarantee across isolates). Callers with
+ * their own durable store can pass an explicit `rateLimit: { storage: … }`
+ * (or `customStorage`), and any explicit value wins.
+ *
+ * Session cookie cache is ON by default too.
+ *
+ * Every authenticated call resolves identity through better-auth's
+ * `getSession`, which — without a cache — is a DB (D1) read on the hot path
+ * of every query/mutation/action that reads `ctx.auth` and of the WebSocket
+ * upgrade. better-auth's `session.cookieCache` carries the session payload in
+ * a short-lived signed cookie so `getSession` can answer without hitting the
+ * database until the cache window elapses. We default it on with a
+ * deliberately short 60s `maxAge` (better-auth's own default is 300s): long
+ * enough to erase the per-request read for a burst of calls, short enough
+ * that a revoked or role-changed session self-corrects within a minute.
+ * The one tradeoff — a revoked session stays valid until the cache expires —
+ * is bounded by that TTL; callers who need immediate revocation opt out with
+ * `session: { cookieCache: { enabled: false } }` (or the `strict` preset).
+ *
+ * Every explicit caller value is forwarded verbatim. The two `rateLimit` fills
+ * merge into a single `rateLimit` object so neither clobbers the other.
+ */
+declare const resolveAuthOptions: (options: LunoraAuthOptions) => LunoraAuthOptions;
+/**
+ * Create the auth instance. Thin wrapper around `betterAuth` that enforces
+ * the `secret` requirement at construction time so misconfigured deployments
+ * fail loudly at the first fetch rather than the first sign-in attempt, then
+ * hands {@link resolveAuthOptions}'s hardened, default-filled options to
+ * better-auth.
+ */
+declare const createAuth: (options: LunoraAuthOptions) => LunoraAuth;
+export { LunoraAuth as L, LunoraAuthOptions as a, createAuth as c, resolveAuthOptions as r };

package/dist/packem_shared/create-auth.d-COcIS_KU.d.ts

@@ -0,0 +1,128 @@
+import { betterAuth, BetterAuthOptions } from 'better-auth';
+/**
+ * Lunora's options pass straight through to better-auth — the only thing we add
+ * is requiring `secret` up front so a misconfigured deployment fails loudly
+ * instead of at the first sign-in.
+ *
+ * For `database`, prefer `lunoraD1Adapter` (`database: lunoraD1Adapter(env.DB)`)
+ * over passing the raw `env.DB`. better-auth *does* accept a D1Database directly,
+ * but it then resolves its Kysely adapter via a runtime `await import(...)` inside
+ * `auth.$context` — and that import never settles under `@cloudflare/vite-plugin`'s
+ * worker runner, hanging every auth request in `pnpm dev`. The explicit adapter
+ * skips it, so dev and prod behave the same. (Raw `env.DB` is still correct for
+ * the migration-only instance — see `lunoraD1Adapter`'s note.)
+ *
+ * Session rotation / richer session policies are configured via the `session`
+ * field (a `SessionPolicy`); Lunora validates it for obviously-broken
+ * durations and forwards it verbatim to better-auth. See `sessionPresets`
+ * for ready-made rotation/expiry trade-offs.
+ *
+ * ## Serverless background tasks (Cloudflare Workers)
+ *
+ * better-auth runs some work *after* sending the response — most importantly the
+ * password-reset email, whose background send is what keeps reset responses
+ * constant-time (a timing-attack defence: the response doesn't reveal whether
+ * the account exists). On Cloudflare Workers a promise that isn't handed to
+ * `ctx.waitUntil` can be cancelled the moment the response returns, dropping
+ * that send and weakening the guarantee. Wire your request's `ctx.waitUntil`
+ * into better-auth's background handler so the work survives:
+ *
+ * ```ts
+ * // in your worker fetch handler, where `ctx: ExecutionContext` is in scope
+ * const auth = createAuth({
+ *     secret: env.AUTH_SECRET,
+ *     database: lunoraD1Adapter(env.DB),
+ *     advanced: {
+ *         backgroundTasks: { handler: (promise) => ctx.waitUntil(promise) },
+ *     },
+ * });
+ * ```
+ *
+ * (Lunora can't set this for you — `ctx.waitUntil` is per-request, but
+ * `createAuth` runs once at worker setup.)
+ */
+type LunoraAuthOptions = BetterAuthOptions;
+/**
+ * The full better-auth instance: `auth.handler` accepts a `Request` and
+ * returns a `Response` (used by `handleAuthRequest`); `auth.api`
+ * exposes the typed endpoint surface for server-side calls (e.g.
+ * `auth.api.getSession({ headers })` inside a query/mutation).
+ */
+type LunoraAuth = ReturnType<typeof betterAuth>;
+/**
+ * Resolve the caller's options into the exact shape `createAuth` hands to
+ * `betterAuth` — the hardened, default-filled options the running worker uses.
+ * Exported (and pure) so the migration path can compile the schema from the
+ * same resolved options: `compileMigrationsSql` routes through here, so the
+ * `rateLimit` table the worker's durable limiter writes to is included in the
+ * migration rather than silently omitted (it would be, if migrations saw the
+ * raw options while the worker ran the resolved ones).
+ *
+ * ## What it fills (each gated independently on caller silence)
+ *
+ * Secure-by-default cookies + secret-strength warning via {@link hardenAuthOptions},
+ * applied first so all hardening composes onto one options object.
+ *
+ * Rate limiting is ON by default for `/api/auth/*`.
+ *
+ * better-auth's own default is `rateLimit.enabled ?? isProduction`, and its
+ * `isProduction` is `"development" === "production"` resolved at
+ * module-load time. On Cloudflare Workers that check is unreliable: the
+ * runtime has no Node `process.env` (absent entirely without
+ * `nodejs_compat`, and even with it `NODE_ENV` is rarely `"production"` at
+ * request time). So better-auth would silently leave auth endpoints
+ * _unthrottled_ on a real deployment — the surprise we refuse to ship.
+ *
+ * We therefore default `enabled: true` whenever the caller hasn't made an
+ * explicit choice. We only fill the `enabled` flag and otherwise forward
+ * the caller's `rateLimit` verbatim, so better-auth's `window` (10s) / `max`
+ * (100) defaults and any custom rules still apply. Callers who genuinely
+ * want it off can pass `rateLimit: { enabled: false }` (e.g. when fronting
+ * auth with their own limiter), and any explicit `enabled` value wins.
+ *
+ * We also default `storage: "database"` — but only when rate limiting is not
+ * explicitly disabled (`enabled !== false`). Filling storage under a disabled
+ * limiter is harmless at runtime but makes `getAuthTables` emit an unused
+ * `rateLimit` table, so we skip it there.
+ *
+ * better-auth's own default is `storage: "memory"` — a per-isolate,
+ * non-durable counter. On Cloudflare Workers that means each isolate keeps
+ * its own tally, counters vanish on isolate recycle, and traffic spread
+ * across isolates never sums to the configured `max` — a limiter that
+ * reports "enabled" while never enforcing a global limit (the exact
+ * brute-force / credential-stuffing protection on `/sign-in`, OTP, and
+ * password-reset it is meant to buy). `storage: "database"` rides the counter
+ * through the configured `database` adapter — Lunora's store over the D1 auth
+ * tables — so the limit is durable *and* atomic (the store's native
+ * `incrementOne` gives a one-winner guarantee across isolates). Callers with
+ * their own durable store can pass an explicit `rateLimit: { storage: … }`
+ * (or `customStorage`), and any explicit value wins.
+ *
+ * Session cookie cache is ON by default too.
+ *
+ * Every authenticated call resolves identity through better-auth's
+ * `getSession`, which — without a cache — is a DB (D1) read on the hot path
+ * of every query/mutation/action that reads `ctx.auth` and of the WebSocket
+ * upgrade. better-auth's `session.cookieCache` carries the session payload in
+ * a short-lived signed cookie so `getSession` can answer without hitting the
+ * database until the cache window elapses. We default it on with a
+ * deliberately short 60s `maxAge` (better-auth's own default is 300s): long
+ * enough to erase the per-request read for a burst of calls, short enough
+ * that a revoked or role-changed session self-corrects within a minute.
+ * The one tradeoff — a revoked session stays valid until the cache expires —
+ * is bounded by that TTL; callers who need immediate revocation opt out with
+ * `session: { cookieCache: { enabled: false } }` (or the `strict` preset).
+ *
+ * Every explicit caller value is forwarded verbatim. The two `rateLimit` fills
+ * merge into a single `rateLimit` object so neither clobbers the other.
+ */
+declare const resolveAuthOptions: (options: LunoraAuthOptions) => LunoraAuthOptions;
+/**
+ * Create the auth instance. Thin wrapper around `betterAuth` that enforces
+ * the `secret` requirement at construction time so misconfigured deployments
+ * fail loudly at the first fetch rather than the first sign-in attempt, then
+ * hands {@link resolveAuthOptions}'s hardened, default-filled options to
+ * better-auth.
+ */
+declare const createAuth: (options: LunoraAuthOptions) => LunoraAuth;
+export { LunoraAuth as L, LunoraAuthOptions as a, createAuth as c, resolveAuthOptions as r };