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

package/dist/middleware.d.mts

@@ -1,12 +1,12 @@
 import { LunoraError } from '@lunora/errors';
-import { L as LunoraAuth } from "./packem_shared/create-auth.d-Mwhb4gSc.mjs";
+import { L as LunoraAuth } from "./packem_shared/create-auth.d-COcIS_KU.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.
-*/
+ * 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>;