@nifrajs/better-auth 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nifra Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @nifrajs/better-auth
+
+Mount [better-auth](https://better-auth.com) into a [nifra](https://github.com/nifra) app: one
+`app.use(betterAuth(auth))` wires every better-auth endpoint (sign-in/up/out, OAuth callbacks,
+session, 2FA, magic links, …) under `/api/auth/*`, plus typed `getSession` / `requireSession` guards
+for reading and protecting routes.
+
+This package has **no runtime dependency on better-auth** — it consumes your `auth` object
+structurally, so your better-auth types flow through by inference and your tests need no DB.
+
+## Install
+
+```sh
+bun add @nifrajs/better-auth better-auth
+```
+
+## Setup
+
+Configure better-auth as usual (database, providers, …), then mount it:
+
+```ts
+// auth.ts
+import { betterAuth as createBetterAuth } from "better-auth"
+export const auth = createBetterAuth({
+  database: /* your adapter */,
+  emailAndPassword: { enabled: true },
+  // basePath defaults to "/api/auth"
+})
+```
+
+```ts
+// server.ts
+import { server } from "@nifrajs/core"
+import { betterAuth } from "@nifrajs/better-auth"
+import { auth } from "./auth"
+
+export const app = server()
+  .use(betterAuth(auth)) // serves GET + POST /api/auth/*
+  .get("/", () => ({ ok: true }))
+```
+
+`betterAuth(auth, { basePath })` overrides the mount path; otherwise it uses `auth.options.basePath`,
+then `/api/auth`. The plugin is **idempotent** (named `"better-auth"`): applying it twice mounts once.
+
+## Read the session
+
+`getSession(auth, request)` is a typed wrapper over `auth.api.getSession`. Pass the raw `Request` so it
+works in both core handlers (`c.req`) and `@nifrajs/web` loaders/actions (`request`):
+
+```ts
+import { getSession } from "@nifrajs/better-auth"
+
+app.get("/me", async (c) => {
+  const session = await getSession(auth, c.req) // { user, session } | null — fully typed
+  return session ? { email: session.user.email } : { email: null }
+})
+```
+
+## Protect a route
+
+`requireSession(auth, request, options?)` returns the non-null session or **throws a `Response`** —
+nifra returns a thrown `Response` as-is, short-circuiting the handler:
+
+```ts
+import { requireSession } from "@nifrajs/better-auth"
+
+// 401 JSON { ok: false, error: "unauthorized" } when signed out:
+app.get("/account", async (c) => {
+  const { user } = await requireSession(auth, c.req)
+  return { id: user.id }
+})
+
+// 302 to a login page instead (same-origin path required):
+export const loader = async ({ request }) => {
+  const { user } = await requireSession(auth, request, { redirectTo: "/login" })
+  return { user }
+}
+```
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `betterAuth(auth, options?)` | Plugin that mounts better-auth's handler at `${basePath}/*` for GET + POST. |
+| `getSession(auth, request)` | `Promise<SessionOf<A> \| null>` — typed wrapper over `auth.api.getSession`. |
+| `requireSession(auth, request, options?)` | Returns the session or throws a `Response` (302 `redirectTo` / 401). |
+| `SessionOf<A>` | The non-null session payload type inferred from your `auth`. |
+| `BetterAuthLike` | The structural contract a better-auth instance satisfies. |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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
+ * better-auth: you pass your own `auth` object and its concrete types flow through
+ * {@link getSession} / {@link requireSession} via inference.
+ */
+export interface BetterAuthLike {
+    /** better-auth's catch-all handler — serves every request under `basePath`. */
+    readonly handler: (request: Request) => Response | Promise<Response>;
+    readonly api: {
+        /** Resolve the session from request headers (cookie or bearer). Returns a nullable payload. */
+        readonly getSession: (context: {
+            readonly headers: Headers;
+        }) => Promise<unknown>;
+    };
+    /** better-auth's resolved options; `basePath` (when set) defaults the mount path. */
+    readonly options?: {
+        readonly basePath?: string;
+    };
+}
+/**
+ * The non-null session payload of a concrete better-auth instance `A`, inferred from its
+ * `api.getSession` return type (typically `{ user: User; session: Session }`).
+ */
+export type SessionOf<A extends BetterAuthLike> = NonNullable<Awaited<ReturnType<A["api"]["getSession"]>>>;
+export interface BetterAuthOptions {
+    /** Mount path for better-auth's routes. Defaults to `auth.options.basePath`, then `"/api/auth"`. */
+    readonly basePath?: string;
+}
+/**
+ * Mount a better-auth instance into a nifra app: registers its handler at `${basePath}/*`
+ * (default `/api/auth/*`) for `GET` + `POST`, so every better-auth endpoint — sign-in/up/out, OAuth
+ * callbacks, session, 2FA, magic links, … — is served by your nifra server.
+ *
+ * ```ts
+ * import { betterAuth, requireSession } from "@nifrajs/better-auth"
+ * import { auth } from "./auth"           // your configured better-auth instance
+ *
+ * const app = server().use(betterAuth(auth))            // wires /api/auth/*
+ *   .get("/me", async (c) => (await requireSession(auth, c.req)).user)
+ * ```
+ *
+ * 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;
+/**
+ * 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
+ * (`c.req`) and web loaders/actions (`request`).
+ *
+ * ```ts
+ * const session = await getSession(auth, c.req) // typed: { user, session } | null
+ * if (session) c.set.headers["x-user"] = session.user.id
+ * ```
+ */
+export declare function getSession<A extends BetterAuthLike>(auth: A, request: Request): Promise<SessionOf<A> | null>;
+/**
+ * What {@link requireSession} does on a missing session: `302` to `redirectTo` (a same-origin path),
+ * or — when omitted — a `401` JSON (`{ ok: false, error: "unauthorized" }`). Mirrors `@nifrajs/auth` guards.
+ */
+export interface RequireSessionOptions {
+    readonly redirectTo?: string;
+}
+/**
+ * Require an authenticated better-auth session at the top of a protected handler/loader/action.
+ * Returns the (non-null) session when present; otherwise **throws a `Response`** (302/401) — nifra
+ * returns a thrown `Response` as-is, short-circuiting the rest of the handler.
+ *
+ * ```ts
+ * const { user } = await requireSession(auth, c.req, { redirectTo: "/login" })
+ * ```
+ */
+export declare function requireSession<A extends BetterAuthLike>(auth: A, request: Request, options?: RequireSessionOptions): Promise<SessionOf<A>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAClD;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"}

package/dist/index.js

@@ -0,0 +1,77 @@
+import { defineIdentityPlugin } from "@nifrajs/core";
+// better-auth dispatches only GET (session, OAuth/email callbacks) and POST (sign-in/up/out, etc.).
+const HANDLED_METHODS = ["GET", "POST"];
+/**
+ * Mount a better-auth instance into a nifra app: registers its handler at `${basePath}/*`
+ * (default `/api/auth/*`) for `GET` + `POST`, so every better-auth endpoint — sign-in/up/out, OAuth
+ * callbacks, session, 2FA, magic links, … — is served by your nifra server.
+ *
+ * ```ts
+ * import { betterAuth, requireSession } from "@nifrajs/better-auth"
+ * import { auth } from "./auth"           // your configured better-auth instance
+ *
+ * const app = server().use(betterAuth(auth))            // wires /api/auth/*
+ *   .get("/me", async (c) => (await requireSession(auth, c.req)).user)
+ * ```
+ *
+ * Idempotent (named `"better-auth"` — applying twice mounts once). Read the session with
+ * {@link getSession} / {@link requireSession}, which infer your better-auth types.
+ */
+export function betterAuth(auth, options = {}) {
+    const base = options.basePath ?? auth.options?.basePath ?? "/api/auth";
+    const pattern = `${base.replace(/\/+$/, "")}/*`; // strip trailing slash(es), then wildcard the subtree
+    // A type-IDENTITY plugin (see defineIdentityPlugin): mounting the auth handler must NOT change the
+    // route registry's type. A plain `definePlugin((app) => app)` would infer `app: Server<any, any>`, so
+    // `use`'s result — and the entire typed client derived from it — collapsed to `any`. This was the #1
+    // reported anti-drift bug: routes declared after `.use(betterAuth(...))` silently lost their types.
+    return defineIdentityPlugin("better-auth", (app) => {
+        for (const method of HANDLED_METHODS) {
+            // `register`'s handler is typed `(context: never) => unknown`; the framework invokes it with the
+            // real Context, so reading `c.req` is sound. Returning better-auth's Response passes through as-is.
+            app.register(method, pattern, undefined, (c) => auth.handler(c.req));
+        }
+        return app;
+    });
+}
+/**
+ * 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
+ * (`c.req`) and web loaders/actions (`request`).
+ *
+ * ```ts
+ * const session = await getSession(auth, c.req) // typed: { user, session } | null
+ * if (session) c.set.headers["x-user"] = session.user.id
+ * ```
+ */
+export function getSession(auth, request) {
+    // `auth` is the concrete `A`, so `getSession`'s real return type is recovered by `SessionOf<A>`;
+    // the cast bridges the erased `Promise<unknown>` view inside this generic body.
+    return auth.api.getSession({ headers: request.headers });
+}
+const rejection = (options) => {
+    const to = options.redirectTo;
+    if (to === undefined)
+        return Response.json({ ok: false, error: "unauthorized" }, { status: 401 });
+    // Same-origin guard (mirrors @nifrajs/web `redirect` + @nifrajs/auth guards): a single leading "/", never
+    // "//host" or an absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug — fail loud.
+    if (!to.startsWith("/") || to.startsWith("//")) {
+        throw new Error(`[nifra/better-auth] requireSession redirectTo must be a same-origin path beginning with "/" (got ${JSON.stringify(to)})`);
+    }
+    return new Response(null, { status: 302, headers: { location: to } });
+};
+/**
+ * Require an authenticated better-auth session at the top of a protected handler/loader/action.
+ * Returns the (non-null) session when present; otherwise **throws a `Response`** (302/401) — nifra
+ * returns a thrown `Response` as-is, short-circuiting the rest of the handler.
+ *
+ * ```ts
+ * const { user } = await requireSession(auth, c.req, { redirectTo: "/login" })
+ * ```
+ */
+export async function requireSession(auth, request, options = {}) {
+    const session = await getSession(auth, request);
+    if (session !== null)
+        return session;
+    throw rejection(options);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAgCpE,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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@nifrajs/better-auth",
+  "version": "0.1.0-alpha.1",
+  "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",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr",
+    "auth",
+    "authentication",
+    "sessions",
+    "oauth",
+    "better-auth"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@nifrajs/core": "workspace:*",
+    "better-auth": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "better-auth": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nifrajs/client": "workspace:*",
+    "@nifrajs/core": "workspace:*",
+    "@nifrajs/test-utils": "workspace:*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/better-auth"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/index.ts

@@ -0,0 +1,128 @@
+import { type AnyServer, defineIdentityPlugin } from "@nifrajs/core"
+
+/**
+ * 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
+ * better-auth: you pass your own `auth` object and its concrete types flow through
+ * {@link getSession} / {@link requireSession} via inference.
+ */
+export interface BetterAuthLike {
+  /** better-auth's catch-all handler — serves every request under `basePath`. */
+  readonly handler: (request: Request) => Response | Promise<Response>
+  readonly api: {
+    /** Resolve the session from request headers (cookie or bearer). Returns a nullable payload. */
+    readonly getSession: (context: { readonly headers: Headers }) => Promise<unknown>
+  }
+  /** better-auth's resolved options; `basePath` (when set) defaults the mount path. */
+  readonly options?: { readonly basePath?: string }
+}
+
+/**
+ * The non-null session payload of a concrete better-auth instance `A`, inferred from its
+ * `api.getSession` return type (typically `{ user: User; session: Session }`).
+ */
+export type SessionOf<A extends BetterAuthLike> = NonNullable<
+  Awaited<ReturnType<A["api"]["getSession"]>>
+>
+
+export interface BetterAuthOptions {
+  /** Mount path for better-auth's routes. Defaults to `auth.options.basePath`, then `"/api/auth"`. */
+  readonly basePath?: string
+}
+
+// better-auth dispatches only GET (session, OAuth/email callbacks) and POST (sign-in/up/out, etc.).
+const HANDLED_METHODS = ["GET", "POST"] as const
+
+/**
+ * Mount a better-auth instance into a nifra app: registers its handler at `${basePath}/*`
+ * (default `/api/auth/*`) for `GET` + `POST`, so every better-auth endpoint — sign-in/up/out, OAuth
+ * callbacks, session, 2FA, magic links, … — is served by your nifra server.
+ *
+ * ```ts
+ * import { betterAuth, requireSession } from "@nifrajs/better-auth"
+ * import { auth } from "./auth"           // your configured better-auth instance
+ *
+ * const app = server().use(betterAuth(auth))            // wires /api/auth/*
+ *   .get("/me", async (c) => (await requireSession(auth, c.req)).user)
+ * ```
+ *
+ * Idempotent (named `"better-auth"` — applying twice mounts once). Read the session with
+ * {@link getSession} / {@link requireSession}, which infer your better-auth types.
+ */
+export function betterAuth(auth: BetterAuthLike, options: BetterAuthOptions = {}) {
+  const base = options.basePath ?? auth.options?.basePath ?? "/api/auth"
+  const pattern = `${base.replace(/\/+$/, "")}/*` // strip trailing slash(es), then wildcard the subtree
+  // A type-IDENTITY plugin (see defineIdentityPlugin): mounting the auth handler must NOT change the
+  // route registry's type. A plain `definePlugin((app) => app)` would infer `app: Server<any, any>`, so
+  // `use`'s result — and the entire typed client derived from it — collapsed to `any`. This was the #1
+  // reported anti-drift bug: routes declared after `.use(betterAuth(...))` silently lost their types.
+  return defineIdentityPlugin("better-auth", <S extends AnyServer>(app: S): S => {
+    for (const method of HANDLED_METHODS) {
+      // `register`'s handler is typed `(context: never) => unknown`; the framework invokes it with the
+      // real Context, so reading `c.req` is sound. Returning better-auth's Response passes through as-is.
+      app.register(method, pattern, undefined, (c: { readonly req: Request }) =>
+        auth.handler(c.req),
+      )
+    }
+    return app
+  })
+}
+
+/**
+ * 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
+ * (`c.req`) and web loaders/actions (`request`).
+ *
+ * ```ts
+ * const session = await getSession(auth, c.req) // typed: { user, session } | null
+ * if (session) c.set.headers["x-user"] = session.user.id
+ * ```
+ */
+export function getSession<A extends BetterAuthLike>(
+  auth: A,
+  request: Request,
+): Promise<SessionOf<A> | null> {
+  // `auth` is the concrete `A`, so `getSession`'s real return type is recovered by `SessionOf<A>`;
+  // the cast bridges the erased `Promise<unknown>` view inside this generic body.
+  return auth.api.getSession({ headers: request.headers }) as Promise<SessionOf<A> | null>
+}
+
+/**
+ * What {@link requireSession} does on a missing session: `302` to `redirectTo` (a same-origin path),
+ * or — when omitted — a `401` JSON (`{ ok: false, error: "unauthorized" }`). Mirrors `@nifrajs/auth` guards.
+ */
+export interface RequireSessionOptions {
+  readonly redirectTo?: string
+}
+
+const rejection = (options: RequireSessionOptions): Response => {
+  const to = options.redirectTo
+  if (to === undefined) return Response.json({ ok: false, error: "unauthorized" }, { status: 401 })
+  // Same-origin guard (mirrors @nifrajs/web `redirect` + @nifrajs/auth guards): a single leading "/", never
+  // "//host" or an absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug — fail loud.
+  if (!to.startsWith("/") || to.startsWith("//")) {
+    throw new Error(
+      `[nifra/better-auth] requireSession redirectTo must be a same-origin path beginning with "/" (got ${JSON.stringify(to)})`,
+    )
+  }
+  return new Response(null, { status: 302, headers: { location: to } })
+}
+
+/**
+ * Require an authenticated better-auth session at the top of a protected handler/loader/action.
+ * Returns the (non-null) session when present; otherwise **throws a `Response`** (302/401) — nifra
+ * returns a thrown `Response` as-is, short-circuiting the rest of the handler.
+ *
+ * ```ts
+ * const { user } = await requireSession(auth, c.req, { redirectTo: "/login" })
+ * ```
+ */
+export async function requireSession<A extends BetterAuthLike>(
+  auth: A,
+  request: Request,
+  options: RequireSessionOptions = {},
+): Promise<SessionOf<A>> {
+  const session = await getSession(auth, request)
+  if (session !== null) return session
+  throw rejection(options)
+}