@nifrajs/better-auth 1.13.0 → 2.1.0

package/README.md

@@ -30,7 +30,7 @@ export const auth = createBetterAuth({
 
 ```ts
 // server.ts
-import { server } from "@nifrajs/core"
+import { server } from "@nifrajs/core/server"
 import { betterAuth } from "@nifrajs/better-auth"
 import { auth } from "./auth"
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type AnyServer, type Server } from "@nifrajs/core/server";
 /**
  * The structural slice of a [better-auth](https://better-auth.com) instance this package needs.
  * Declared structurally rather than imported, so `@nifrajs/better-auth` has **no runtime dependency** on
@@ -49,7 +50,7 @@ export interface BetterAuthOptions {
  * Idempotent (named `"better-auth"` — applying twice mounts once). Read the session with
  * {@link getSession} / {@link requireSession}, which infer your better-auth types.
  */
-export declare function betterAuth(auth: BetterAuthLike, options?: BetterAuthOptions): import("@nifrajs/core").IdentityPlugin;
+export declare function betterAuth(auth: BetterAuthLike, options?: BetterAuthOptions): import("@nifrajs/core/server").IdentityPlugin;
 /**
  * Resolve the better-auth session for a request — a thin, typed wrapper over `auth.api.getSession`.
  * Returns `null` when unauthenticated. Takes the raw `Request` so it works in both server handlers
@@ -78,4 +79,96 @@ export interface RequireSessionOptions {
  * ```
  */
 export declare function requireSession<A extends BetterAuthLike>(auth: A, request: Request, options?: RequireSessionOptions): Promise<SessionOf<A>>;
+/**
+ * The authenticated caller of a request, mapped from a better-auth session. Built by
+ * {@link requirePrincipal} / {@link authed} and threaded onto the handler context as `c.principal`.
+ *
+ * `tenantId` is optional here (`string | undefined`); with `{ requireTenant: true }` it is narrowed to a
+ * non-optional `string` (see {@link authed}), so a tenant-scoped handler never has to null-check it.
+ * nifra owns the session -> principal wiring ONLY; binding the principal to a DB/RLS scope stays in
+ * userland (nifra is storage-agnostic and adds no DB code).
+ */
+export interface Principal<User> {
+    /** The full better-auth user record, typed from the concrete auth instance. */
+    readonly user: User;
+    /** The user's id (`user.id`). */
+    readonly userId: string;
+    /** The session's id (`session.id`). */
+    readonly sessionId: string;
+    /** The resolved tenant/org id, if any. Non-optional `string` under `{ requireTenant: true }`. */
+    readonly tenantId?: string;
+}
+/**
+ * The non-null user type of a concrete better-auth instance `A` (`SessionOf<A>["user"]`). Collapses to
+ * `unknown` only for the erased structural `BetterAuthLike`; a real instance recovers the concrete user.
+ */
+export type SessionUserOf<A extends BetterAuthLike> = SessionOf<A> extends {
+    user: infer U;
+} ? U : unknown;
+/**
+ * Options for {@link requirePrincipal} / {@link authed}.
+ */
+export interface AuthedOptions<User> {
+    /** Require a resolvable tenant. When set and no tenant resolves, fail closed with `403`. */
+    readonly requireTenant?: boolean;
+    /** Browser redirect target (`302`) for a missing session, instead of the default `401` JSON. Same-origin. */
+    readonly redirectTo?: string;
+    /** Resolve the tenant id from the user. Default: `user.tenantId ?? user.orgId` (string-valued only). */
+    readonly tenantOf?: (user: User) => string | undefined;
+}
+/**
+ * The principal type for a given `requireTenant` flag: `tenantId` narrows to a required `string` when
+ * `requireTenant` is `true`, otherwise stays optional (`string | undefined`). The flag is captured as a
+ * literal `const` type parameter at the call sites so `{ requireTenant: true }` selects the narrowed branch.
+ */
+export type PrincipalFor<User, RequireTenant extends boolean> = RequireTenant extends true ? Principal<User> & {
+    readonly tenantId: string;
+} : Principal<User>;
+/** Add `{ principal: P }` to a server's context while preserving its route registry `R` (no collapse to
+ * `any`). This is the type that makes `.use(authed(auth))` thread a NON-NULL `c.principal`. */
+export type WithPrincipal<S extends AnyServer, P> = S extends Server<infer R, infer C> ? Server<R, C & {
+    principal: P;
+}> : never;
+/**
+ * Resolve the better-auth session and map it to a {@link Principal}, or **throw a `Response`** so the
+ * handler never runs unauthenticated:
+ *
+ * - No/invalid session -> `302` to `options.redirectTo` when set, else `401` JSON (`requireSession`).
+ * - `requireTenant: true` and no tenant resolves -> `403` JSON (`{ ok: false, error: "forbidden" }`).
+ *
+ * nifra returns a thrown `Response` as-is (short-circuit), so this is the fail-closed guard used inline
+ * or by {@link authed}. `tenantId` is a non-optional `string` in the return type when `requireTenant`.
+ *
+ * ```ts
+ * const principal = await requirePrincipal(auth, c.req, { requireTenant: true })
+ * // principal.userId / principal.tenantId are typed `string`, no null-check
+ * ```
+ */
+export declare function requirePrincipal<A extends BetterAuthLike, const RequireTenant extends boolean = false>(auth: A, request: Request, options?: AuthedOptions<SessionUserOf<A>> & {
+    readonly requireTenant?: RequireTenant;
+}): Promise<PrincipalFor<SessionUserOf<A>, RequireTenant>>;
+/**
+ * A nifra plugin that derives a fail-closed {@link Principal} onto every downstream handler as
+ * `c.principal`. After `server().use(authed(auth))`, `c.principal.user` / `c.principal.userId` are typed
+ * and **non-null** - a handler CANNOT run without an authenticated caller, so the guard can't be
+ * forgotten. Works in both modes:
+ *
+ * ```ts
+ * // inline
+ * const app = server().use(authed(auth)).get("/me", (c) => ({ id: c.principal.userId }))
+ * // contract-first (the pre-applied derive threads `principal` into the contract's handlers)
+ * const api = implement(contract, handlers, server().use(authed(auth, { requireTenant: true })))
+ * ```
+ *
+ * With `{ requireTenant: true }`, `c.principal.tenantId` is typed `string` (a missing tenant is a `403`).
+ *
+ * DESIGN NOTE: this is an **unnamed** plugin by necessity. A named plugin (for idempotent dedupe) carries
+ * a `& { pluginName }` intersection that defeats the generic inference of `use`'s context-threading
+ * overload and collapses the server - and its typed client - to `any` (see `@nifrajs/core` plugin docs).
+ * Threading a NON-NULL principal is the whole point, so `authed` stays unnamed and generic. Applying it
+ * twice simply derives twice (the second resolve overwrites with the same value); scope it once per app.
+ */
+export declare function authed<A extends BetterAuthLike, const RequireTenant extends boolean = false>(auth: A, options?: AuthedOptions<SessionUserOf<A>> & {
+    readonly requireTenant?: RequireTenant;
+}): <S extends AnyServer>(app: S) => WithPrincipal<S, PrincipalFor<SessionUserOf<A>, RequireTenant>>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpE,QAAQ,CAAC,GAAG,EAAE;QACZ,+FAA+F;QAC/F,QAAQ,CAAC,UAAU,EAAE,CAAC,OAAO,EAAE;YAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;SAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;KAClF,CAAA;IACD;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC5E;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,cAAc,IAAI,WAAW,CAC3D,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAC5C,CAAA;AAED,MAAM,WAAW,iBAAiB;IAChC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,GAAE,iBAAsB,0CAiB/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,cAAc,EACjD,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAI9B;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAeD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,cAAc,EAC3D,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAIvB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,4 +1,4 @@
-import { defineIdentityPlugin } from "@nifrajs/core";
+import { defineIdentityPlugin } from "@nifrajs/core/server";
 // better-auth dispatches only GET (session, OAuth/email callbacks) and POST (sign-in/up/out, etc.).
 const HANDLED_METHODS = ["GET", "POST"];
 /**
@@ -74,4 +74,73 @@ export async function requireSession(auth, request, options = {}) {
         return session;
     throw rejection(options);
 }
+const forbidden = () => Response.json({ ok: false, error: "forbidden" }, { status: 403 });
+/**
+ * Resolve the better-auth session and map it to a {@link Principal}, or **throw a `Response`** so the
+ * handler never runs unauthenticated:
+ *
+ * - No/invalid session -> `302` to `options.redirectTo` when set, else `401` JSON (`requireSession`).
+ * - `requireTenant: true` and no tenant resolves -> `403` JSON (`{ ok: false, error: "forbidden" }`).
+ *
+ * nifra returns a thrown `Response` as-is (short-circuit), so this is the fail-closed guard used inline
+ * or by {@link authed}. `tenantId` is a non-optional `string` in the return type when `requireTenant`.
+ *
+ * ```ts
+ * const principal = await requirePrincipal(auth, c.req, { requireTenant: true })
+ * // principal.userId / principal.tenantId are typed `string`, no null-check
+ * ```
+ */
+export async function requirePrincipal(auth, request, options) {
+    // Reuse requireSession's throw path (302/redirect or 401) verbatim - one owner for the no-session gate.
+    const session = await requireSession(auth, request, options?.redirectTo !== undefined ? { redirectTo: options.redirectTo } : {});
+    // better-auth sessions are `{ user: { id: string, ... }, session: { id: string, ... } }`; view the
+    // fields we map. The concrete user type flows through `SessionUserOf<A>` for `principal.user`.
+    const view = session;
+    const user = view.user;
+    const userId = user.id;
+    const sessionId = view.session.id;
+    const resolveTenant = options?.tenantOf ??
+        ((u) => {
+            const record = u;
+            const value = record.tenantId ?? record.orgId;
+            return typeof value === "string" ? value : undefined;
+        });
+    // A blank tenant is NOT a resolved tenant: a NOT-NULL column defaulted to "" (or a custom `tenantOf`
+    // returning "") must fail closed under `requireTenant`, never bind the principal to an empty tenant.
+    const resolved = resolveTenant(user);
+    const tenantId = resolved === undefined || resolved === "" ? undefined : resolved;
+    if (options?.requireTenant === true && tenantId === undefined)
+        throw forbidden();
+    // Build the principal without ever assigning `tenantId: undefined` (exactOptionalPropertyTypes). The
+    // single cast maps our own constructed object onto the conditional `PrincipalFor` return - the runtime
+    // shape is exactly the mapped session, no untrusted data crosses here.
+    const principal = tenantId === undefined ? { user, userId, sessionId } : { user, userId, sessionId, tenantId };
+    return principal;
+}
+/**
+ * A nifra plugin that derives a fail-closed {@link Principal} onto every downstream handler as
+ * `c.principal`. After `server().use(authed(auth))`, `c.principal.user` / `c.principal.userId` are typed
+ * and **non-null** - a handler CANNOT run without an authenticated caller, so the guard can't be
+ * forgotten. Works in both modes:
+ *
+ * ```ts
+ * // inline
+ * const app = server().use(authed(auth)).get("/me", (c) => ({ id: c.principal.userId }))
+ * // contract-first (the pre-applied derive threads `principal` into the contract's handlers)
+ * const api = implement(contract, handlers, server().use(authed(auth, { requireTenant: true })))
+ * ```
+ *
+ * With `{ requireTenant: true }`, `c.principal.tenantId` is typed `string` (a missing tenant is a `403`).
+ *
+ * DESIGN NOTE: this is an **unnamed** plugin by necessity. A named plugin (for idempotent dedupe) carries
+ * a `& { pluginName }` intersection that defeats the generic inference of `use`'s context-threading
+ * overload and collapses the server - and its typed client - to `any` (see `@nifrajs/core` plugin docs).
+ * Threading a NON-NULL principal is the whole point, so `authed` stays unnamed and generic. Applying it
+ * twice simply derives twice (the second resolve overwrites with the same value); scope it once per app.
+ */
+export function authed(auth, options) {
+    return (app) => app.derive(async (c) => ({
+        principal: await requirePrincipal(auth, c.req, options),
+    }));
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAsCpE,oGAAoG;AACpG,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,CAAU,CAAA;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,UAAU,CAAC,IAAoB,EAAE,UAA6B,EAAE;IAC9E,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,EAAE,QAAQ,IAAI,WAAW,CAAA;IACtE,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAA,CAAC,sDAAsD;IACtG,mGAAmG;IACnG,sGAAsG;IACtG,qGAAqG;IACrG,oGAAoG;IACpG,OAAO,oBAAoB,CAAC,aAAa,EAAE,CAAsB,GAAM,EAAK,EAAE;QAC5E,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,CAAC;YACrC,iGAAiG;YACjG,oGAAoG;YACpG,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAA4B,EAAE,EAAE,CACxE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CACpB,CAAA;QACH,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,IAAO,EACP,OAAgB;IAEhB,iGAAiG;IACjG,gFAAgF;IAChF,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAiC,CAAA;AAC1F,CAAC;AAUD,MAAM,SAAS,GAAG,CAAC,OAA8B,EAAY,EAAE;IAC7D,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAA;IAC7B,IAAI,EAAE,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IACjG,0GAA0G;IAC1G,yGAAyG;IACzG,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,oGAAoG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAC1H,CAAA;IACH,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;AACvE,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAO,EACP,OAAgB,EAChB,UAAiC,EAAE;IAEnC,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IAC/C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,OAAO,CAAA;IACpC,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;AAC1B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/better-auth",
-  "version": "1.13.0",
+  "version": "2.1.0",
   "description": "Mount better-auth into a nifra app — one app.use() wires /api/auth/*, plus typed getSession/requireSession guards. Structural typing: no hard dependency on better-auth.",
   "keywords": [
     "bun",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^1.13.0",
+    "@nifrajs/core": "^2.1.0",
     "better-auth": ">=1.0.0"
   },
   "peerDependenciesMeta": {

package/src/index.ts

@@ -1,4 +1,4 @@
-import { type AnyServer, defineIdentityPlugin } from "@nifrajs/core"
+import { type AnyServer, defineIdentityPlugin, type Server } from "@nifrajs/core/server"
 
 /**
  * The structural slice of a [better-auth](https://better-auth.com) instance this package needs.
@@ -132,3 +132,152 @@ export async function requireSession<A extends BetterAuthLike>(
   if (session !== null) return session
   throw rejection(options)
 }
+
+/**
+ * The authenticated caller of a request, mapped from a better-auth session. Built by
+ * {@link requirePrincipal} / {@link authed} and threaded onto the handler context as `c.principal`.
+ *
+ * `tenantId` is optional here (`string | undefined`); with `{ requireTenant: true }` it is narrowed to a
+ * non-optional `string` (see {@link authed}), so a tenant-scoped handler never has to null-check it.
+ * nifra owns the session -> principal wiring ONLY; binding the principal to a DB/RLS scope stays in
+ * userland (nifra is storage-agnostic and adds no DB code).
+ */
+export interface Principal<User> {
+  /** The full better-auth user record, typed from the concrete auth instance. */
+  readonly user: User
+  /** The user's id (`user.id`). */
+  readonly userId: string
+  /** The session's id (`session.id`). */
+  readonly sessionId: string
+  /** The resolved tenant/org id, if any. Non-optional `string` under `{ requireTenant: true }`. */
+  readonly tenantId?: string
+}
+
+/**
+ * The non-null user type of a concrete better-auth instance `A` (`SessionOf<A>["user"]`). Collapses to
+ * `unknown` only for the erased structural `BetterAuthLike`; a real instance recovers the concrete user.
+ */
+export type SessionUserOf<A extends BetterAuthLike> =
+  SessionOf<A> extends { user: infer U } ? U : unknown
+
+/**
+ * Options for {@link requirePrincipal} / {@link authed}.
+ */
+export interface AuthedOptions<User> {
+  /** Require a resolvable tenant. When set and no tenant resolves, fail closed with `403`. */
+  readonly requireTenant?: boolean
+  /** Browser redirect target (`302`) for a missing session, instead of the default `401` JSON. Same-origin. */
+  readonly redirectTo?: string
+  /** Resolve the tenant id from the user. Default: `user.tenantId ?? user.orgId` (string-valued only). */
+  readonly tenantOf?: (user: User) => string | undefined
+}
+
+/**
+ * The principal type for a given `requireTenant` flag: `tenantId` narrows to a required `string` when
+ * `requireTenant` is `true`, otherwise stays optional (`string | undefined`). The flag is captured as a
+ * literal `const` type parameter at the call sites so `{ requireTenant: true }` selects the narrowed branch.
+ */
+export type PrincipalFor<User, RequireTenant extends boolean> = RequireTenant extends true
+  ? Principal<User> & { readonly tenantId: string }
+  : Principal<User>
+
+/** Add `{ principal: P }` to a server's context while preserving its route registry `R` (no collapse to
+ * `any`). This is the type that makes `.use(authed(auth))` thread a NON-NULL `c.principal`. */
+export type WithPrincipal<S extends AnyServer, P> =
+  S extends Server<infer R, infer C> ? Server<R, C & { principal: P }> : never
+
+const forbidden = (): Response => Response.json({ ok: false, error: "forbidden" }, { status: 403 })
+
+/**
+ * Resolve the better-auth session and map it to a {@link Principal}, or **throw a `Response`** so the
+ * handler never runs unauthenticated:
+ *
+ * - No/invalid session -> `302` to `options.redirectTo` when set, else `401` JSON (`requireSession`).
+ * - `requireTenant: true` and no tenant resolves -> `403` JSON (`{ ok: false, error: "forbidden" }`).
+ *
+ * nifra returns a thrown `Response` as-is (short-circuit), so this is the fail-closed guard used inline
+ * or by {@link authed}. `tenantId` is a non-optional `string` in the return type when `requireTenant`.
+ *
+ * ```ts
+ * const principal = await requirePrincipal(auth, c.req, { requireTenant: true })
+ * // principal.userId / principal.tenantId are typed `string`, no null-check
+ * ```
+ */
+export async function requirePrincipal<
+  A extends BetterAuthLike,
+  const RequireTenant extends boolean = false,
+>(
+  auth: A,
+  request: Request,
+  options?: AuthedOptions<SessionUserOf<A>> & { readonly requireTenant?: RequireTenant },
+): Promise<PrincipalFor<SessionUserOf<A>, RequireTenant>> {
+  // Reuse requireSession's throw path (302/redirect or 401) verbatim - one owner for the no-session gate.
+  const session = await requireSession(
+    auth,
+    request,
+    options?.redirectTo !== undefined ? { redirectTo: options.redirectTo } : {},
+  )
+  // better-auth sessions are `{ user: { id: string, ... }, session: { id: string, ... } }`; view the
+  // fields we map. The concrete user type flows through `SessionUserOf<A>` for `principal.user`.
+  const view = session as unknown as {
+    readonly user: SessionUserOf<A>
+    readonly session: { readonly id: string }
+  }
+  const user = view.user
+  const userId = (user as { readonly id: string }).id
+  const sessionId = view.session.id
+
+  const resolveTenant =
+    options?.tenantOf ??
+    ((u: SessionUserOf<A>): string | undefined => {
+      const record = u as { readonly tenantId?: unknown; readonly orgId?: unknown }
+      const value = record.tenantId ?? record.orgId
+      return typeof value === "string" ? value : undefined
+    })
+  // A blank tenant is NOT a resolved tenant: a NOT-NULL column defaulted to "" (or a custom `tenantOf`
+  // returning "") must fail closed under `requireTenant`, never bind the principal to an empty tenant.
+  const resolved = resolveTenant(user)
+  const tenantId = resolved === undefined || resolved === "" ? undefined : resolved
+
+  if (options?.requireTenant === true && tenantId === undefined) throw forbidden()
+
+  // Build the principal without ever assigning `tenantId: undefined` (exactOptionalPropertyTypes). The
+  // single cast maps our own constructed object onto the conditional `PrincipalFor` return - the runtime
+  // shape is exactly the mapped session, no untrusted data crosses here.
+  const principal: Principal<SessionUserOf<A>> =
+    tenantId === undefined ? { user, userId, sessionId } : { user, userId, sessionId, tenantId }
+  return principal as PrincipalFor<SessionUserOf<A>, RequireTenant>
+}
+
+/**
+ * A nifra plugin that derives a fail-closed {@link Principal} onto every downstream handler as
+ * `c.principal`. After `server().use(authed(auth))`, `c.principal.user` / `c.principal.userId` are typed
+ * and **non-null** - a handler CANNOT run without an authenticated caller, so the guard can't be
+ * forgotten. Works in both modes:
+ *
+ * ```ts
+ * // inline
+ * const app = server().use(authed(auth)).get("/me", (c) => ({ id: c.principal.userId }))
+ * // contract-first (the pre-applied derive threads `principal` into the contract's handlers)
+ * const api = implement(contract, handlers, server().use(authed(auth, { requireTenant: true })))
+ * ```
+ *
+ * With `{ requireTenant: true }`, `c.principal.tenantId` is typed `string` (a missing tenant is a `403`).
+ *
+ * DESIGN NOTE: this is an **unnamed** plugin by necessity. A named plugin (for idempotent dedupe) carries
+ * a `& { pluginName }` intersection that defeats the generic inference of `use`'s context-threading
+ * overload and collapses the server - and its typed client - to `any` (see `@nifrajs/core` plugin docs).
+ * Threading a NON-NULL principal is the whole point, so `authed` stays unnamed and generic. Applying it
+ * twice simply derives twice (the second resolve overwrites with the same value); scope it once per app.
+ */
+export function authed<A extends BetterAuthLike, const RequireTenant extends boolean = false>(
+  auth: A,
+  options?: AuthedOptions<SessionUserOf<A>> & { readonly requireTenant?: RequireTenant },
+): <S extends AnyServer>(
+  app: S,
+) => WithPrincipal<S, PrincipalFor<SessionUserOf<A>, RequireTenant>> {
+  return <S extends AnyServer>(app: S) =>
+    app.derive(async (c: { readonly req: Request }) => ({
+      principal: await requirePrincipal(auth, c.req, options),
+    })) as unknown as WithPrincipal<S, PrincipalFor<SessionUserOf<A>, RequireTenant>>
+}