@lunora/auth 0.0.0 → 1.0.0-alpha.2

package/dist/index.d.ts

@@ -0,0 +1,386 @@
+export { lunoraAuthAdapter, lunoraD1Adapter } from "./adapter.js";
+import { L as LunoraAuth, a as LunoraAuthOptions } from "./packem_shared/create-auth.d-M36jwG_Y.js";
+export { c as createAuth } from "./packem_shared/create-auth.d-M36jwG_Y.js";
+export { type LunoraAuthApiContext, LunoraAuthHeadersError, type WithAuthPluginsMiddleware, type WithAuthPluginsOptions, withAuthPlugins } from "./middleware.js";
+export { default as authTables } from "./schema.js";
+import { BetterAuthOptions } from 'better-auth';
+export { type SqlExecutor, createSqlAuthStore, d1Executor } from "./sql-store.js";
+export { type AuthQuery, type AuthRow, type AuthStore, type AuthWhereClause, createMemoryAuthStore, matchesWhere } from "./store.js";
+export { type FetchLike, TURNSTILE_VERIFY_ENDPOINT, type TurnstileVerifyResult, type VerifyTurnstileOptions, verifyTurnstile } from "./turnstile.js";
+export { type VerifyTurnstileMiddlewareOptions, verifyTurnstileMiddleware } from "./turnstile-middleware.js";
+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.
+*/
+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.
+*/
+interface AuthAdminUser {
+  [key: string]: unknown;
+  banExpires?: AuthTimestamp;
+  banned?: boolean | null;
+  banReason?: null | string;
+  createdAt?: AuthTimestamp;
+  email?: null | string;
+  emailVerified?: boolean | null;
+  id: string;
+  image?: null | string;
+  name?: null | string;
+  role?: null | string;
+  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.
+*/
+interface AuthAdminSession {
+  [key: string]: unknown;
+  createdAt?: AuthTimestamp;
+  expiresAt?: AuthTimestamp;
+  id: string;
+  impersonatedBy?: null | string;
+  ipAddress?: null | string;
+  userAgent?: null | string;
+  userId: string;
+}
+/** One linked account (a credential or OAuth provider). All token material is stripped. */
+interface AuthAccount {
+  [key: string]: unknown;
+  accountId?: null | string;
+  createdAt?: AuthTimestamp;
+  id: string;
+  providerId?: null | string;
+  scope?: null | string;
+  userId: string;
+}
+/** One organization row (from the `organization` plugin). */
+interface AuthOrganization {
+  [key: string]: unknown;
+  createdAt?: AuthTimestamp;
+  id: string;
+  name?: null | string;
+  slug?: null | string;
+}
+/** One organization membership row. */
+interface AuthMember {
+  [key: string]: unknown;
+  createdAt?: AuthTimestamp;
+  id: string;
+  organizationId: string;
+  role?: null | string;
+  userId: string;
+}
+/** One pending organization invitation. */
+interface AuthInvitation {
+  [key: string]: unknown;
+  email?: null | string;
+  expiresAt?: AuthTimestamp;
+  id: string;
+  organizationId: string;
+  role?: null | string;
+  status?: null | string;
+}
+/** One registered passkey. Credential secrets (`publicKey`) are stripped. */
+interface AuthPasskey {
+  [key: string]: unknown;
+  createdAt?: AuthTimestamp;
+  deviceType?: null | string;
+  id: string;
+  name?: null | string;
+  userId: string;
+}
+/** A page of rows plus the unpaginated total. */
+interface AuthPage<T> {
+  rows: 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.
+*/
+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 `organization` plugin: orgs, members, invitations. */
+  organization: boolean;
+  /** The `@better-auth/passkey` plugin: per-user passkeys. */
+  passkey: boolean;
+  /** The `two-factor` plugin: per-user 2FA status / disable. */
+  twoFactor: boolean;
+}
+/** A scalar value usable in an adapter `where` clause / filter. */
+type WhereValue = boolean | number | string;
+/** Filtering / paging options for {@link AuthAdmin.listUsers}. */
+interface ListUsersOptions {
+  /** Column to filter on with `=` (defaults to `email` when `filterValue` is set). */
+  filterField?: string;
+  /** Exact-match filter value. */
+  filterValue?: WhereValue;
+  limit?: number;
+  offset?: number;
+  /** Substring search value (matched with `contains`). */
+  search?: string;
+  /** Column the `search` substring matches against (default `email`). */
+  searchField?: string;
+  /** Column to order by (default `createdAt`). */
+  sortBy?: string;
+  sortDirection?: "asc" | "desc";
+}
+/** The result of {@link AuthAdmin.impersonateUser}: a fresh session token to act as the target user. */
+interface ImpersonationResult {
+  expiresAt: AuthTimestamp;
+  /** Bearer session token for the impersonated user. The caller is responsible for using it (e.g. setting the cookie). */
+  token: string;
+  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.
+*/
+interface AuthAdmin {
+  banUser: (input: {
+    expiresInSeconds?: number;
+    reason?: string;
+    userId: string;
+  }) => Promise<AuthAdminUser>;
+  cancelInvitation: (input: {
+    invitationId: string;
+  }) => Promise<void>;
+  capabilities: () => Promise<AuthCapabilities>;
+  createUser: (input: {
+    data?: Record<string, unknown>;
+    email: string;
+    name: string;
+    password?: string;
+    role?: string | string[];
+  }) => Promise<AuthAdminUser>;
+  deletePasskey: (input: {
+    passkeyId: string;
+  }) => Promise<void>;
+  disableTwoFactor: (input: {
+    userId: string;
+  }) => Promise<void>;
+  impersonateUser: (input: {
+    userId: string;
+  }) => Promise<ImpersonationResult>;
+  listAccounts: (input: {
+    userId: string;
+  }) => Promise<AuthAccount[]>;
+  listInvitations: (options: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }) => Promise<AuthPage<AuthInvitation>>;
+  listMembers: (options: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }) => Promise<AuthPage<AuthMember>>;
+  listOrganizations: (options: {
+    limit?: number;
+    offset?: number;
+  }) => Promise<AuthPage<AuthOrganization>>;
+  listPasskeys: (input: {
+    userId: string;
+  }) => Promise<AuthPasskey[]>;
+  listSessions: (options: {
+    limit?: number;
+    offset?: number;
+    userId?: string;
+  }) => Promise<AuthPage<AuthAdminSession>>;
+  listUsers: (options: ListUsersOptions) => Promise<AuthPage<AuthAdminUser>>;
+  removeMember: (input: {
+    memberId: string;
+  }) => Promise<void>;
+  removeUser: (input: {
+    userId: string;
+  }) => Promise<void>;
+  revokeUserSession: (input: {
+    sessionId: string;
+  }) => Promise<void>;
+  revokeUserSessions: (input: {
+    userId: string;
+  }) => Promise<void>;
+  setRole: (input: {
+    role: string | string[];
+    userId: string;
+  }) => Promise<AuthAdminUser>;
+  setUserPassword: (input: {
+    newPassword: string;
+    userId: string;
+  }) => Promise<void>;
+  unbanUser: (input: {
+    userId: string;
+  }) => Promise<AuthAdminUser>;
+  unlinkAccount: (input: {
+    accountId: string;
+    userId: string;
+  }) => Promise<void>;
+  updateUser: (input: {
+    data: Record<string, unknown>;
+    userId: string;
+  }) => Promise<AuthAdminUser>;
+}
+/** 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`.
+  */
+  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.
+  */
+  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).
+  */
+  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.
+*/
+declare class LunoraAuthAdminError extends Error {
+  readonly code: string;
+  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.
+*/
+declare const createAuthAdmin: (auth: LunoraAuth, options?: CreateAuthAdminOptions) => AuthAdmin;
+/**
+* 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.
+*/
+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.
+*/
+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.
+*/
+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.
+*/
+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.
+*/
+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.
+* - `strict` — short, security-sensitive: 1-hour expiry, 15-minute rotation.
+* - `longLived` — low-friction consumer apps: 30-day expiry, daily rotation.
+*/
+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 };

package/dist/index.mjs

@@ -0,0 +1,12 @@
+export { lunoraAuthAdapter, lunoraD1Adapter } from './adapter.mjs';
+export { LunoraAuthAdminError, createAuthAdmin } from './packem_shared/LunoraAuthAdminError-BxrfEeA_.mjs';
+export { createAuth } from './packem_shared/createAuth-B-tvsvQU.mjs';
+export { DEFAULT_AUTH_BASE_PATH, handleAuthRequest } from './packem_shared/DEFAULT_AUTH_BASE_PATH-DjcUWEQl.mjs';
+export { LunoraAuthHeadersError, withAuthPlugins } from './middleware.mjs';
+export { compileMigrationsSql, ensureMigrated } from './packem_shared/compileMigrationsSql-wZH3oXDu.mjs';
+export { default as authTables } from './schema.mjs';
+export { sessionPresets, validateSessionPolicy } from './packem_shared/sessionPresets-B95rXrd8.mjs';
+export { createSqlAuthStore, d1Executor } from './sql-store.mjs';
+export { createMemoryAuthStore, matchesWhere } from './store.mjs';
+export { TURNSTILE_VERIFY_ENDPOINT, verifyTurnstile } from './turnstile.mjs';
+export { verifyTurnstileMiddleware } from './turnstile-middleware.mjs';

package/dist/middleware.d.mts

@@ -0,0 +1,189 @@
+import { L as LunoraAuth } from "./packem_shared/create-auth.d-M36jwG_Y.mjs";
+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.
+*/
+interface MiddlewareNext<ContextIn> {
+  (): Promise<ContextIn>;
+  <Extension extends Record<string, unknown>>(options: {
+    ctx: Extension;
+  }): 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.
+*/
+declare class LunoraAuthHeadersError extends Error {
+  /** The `ctx.authApi.&lt;method>` that was called without `headers`. */
+  readonly method: string;
+  constructor(method: string);
+}
+/**
+* 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.
+  */
+  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.
+*/
+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.
+  */
+  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.
+    */
+    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.
+*/
+/**
+* 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>;
+}) => Promise<ContextIn & LunoraAuthApiContext<Auth>>;
+declare const withAuthPlugins: <Auth extends LunoraAuth>(auth: Auth, options?: WithAuthPluginsOptions) => WithAuthPluginsMiddleware<Auth>;
+export { LunoraAuthApiContext, LunoraAuthHeadersError, WithAuthPluginsMiddleware, WithAuthPluginsOptions, withAuthPlugins };