@dunx/auth 2.5.0 → 3.0.1

package/README.md

@@ -1,251 +1,83 @@
 # @dunx/auth
 
-[Better Auth](https://better-auth.com) for dunx. **This package is not an
-authentication system** - better-auth is, and it is very good at it. This is the
-wiring: a module that builds the instance from your `ConfigService`, five routes that
-mount its handler, a guard that composes with the `@Public()` and `@Roles()` metadata
-`@dunx/http` already carries, and two adapters that let it drive Bun's own APIs.
+[Better Auth](https://better-auth.com) for
+[dunx](https://github.com/petarzarkov/dunx).
 
-`better-auth` is a **required peer dependency**. Install it yourself and own its
-version - dunx does not bundle it - but it is not optional, because this package
-imports `betterAuth` as a value and cannot load without it. Marking it optional would
-trade an install-time warning for a module-resolution crash.
+**This package is not an authentication system.** better-auth is, and it is very
+good at it. This is the wiring: a module that builds the instance from your
+`ConfigService`, five routes that mount its handler, a guard that composes with
+the `@Public()` and `@Roles()` metadata `@dunx/http` already carries, and two
+adapters that let it drive Bun's own APIs.
+
+There is no dunx sign-in flow, no dunx session table and no dunx OAuth. Each is
+a better-auth feature reached through `AuthModule.forRoot`'s options, which
+**are** better-auth's `BetterAuthOptions`.
+
+## Install
 
 ```bash
 bun add @dunx/auth better-auth
 ```
 
-`drizzle-orm` **is** an optional peer, needed only by `@dunx/auth/drizzle` - which is
-its own subpath precisely so that a Prisma, Kysely or MongoDB app never loads it.
-`dist/index.js` contains no reference to drizzle, the test a peer has to
-pass to be called optional.
-
-There is no dunx sign-in flow, no dunx session table, no dunx password reset and no
-dunx OAuth. Every one of those is a better-auth feature reached through
-`AuthModule.forRoot`'s options, which **are** better-auth's `BetterAuthOptions`. Its
-documentation is the documentation.
-
-## What dunx adds
-
-| Export                | What it is                                                            |
-| --------------------- | --------------------------------------------------------------------- |
-| `AuthModule`          | `forRoot` / `forRootAsync`, binding the instance and mounting it       |
-| `Auth`                | The injection token for the better-auth instance                      |
-| `SessionGuard`        | Middleware: authenticates, then reads `@Public()` and `@Roles()`       |
-| `AuthContext`         | The authenticated caller, reachable from any service in the request    |
-| `Principal`           | `{ session, user }` - better-auth's own inferred session type          |
-| `bunPassword`         | `Bun.password` bcrypt in place of better-auth's JavaScript scrypt      |
-| `redisStorage`        | `secondaryStorage` over `Bun.RedisClient`                             |
-| `drizzleDatabase`     | `database` over the drizzle handle `@dunx/infra/db` already opened     |
-| `rolesOf`             | The `admin` plugin's `role` column read as a list                     |
-| `AuthOptions`         | The resolved options, the `basePath` and where the handler mounted     |
-
-## Getting started
+`better-auth` is a **required** peer: this package imports `betterAuth` as a
+value and cannot load without it. `drizzle-orm` is an optional peer, needed only
+by `@dunx/auth/drizzle` - its own subpath so a Prisma, Kysely or MongoDB app
+never loads it.
+
+## Usage
 
 ```ts
 import { AuthModule } from '@dunx/auth';
 import { drizzleDatabase } from '@dunx/auth/drizzle';
-import { Module } from '@dunx/core';
 import { DbConnection } from '@dunx/infra/db';
-import { admin, bearer } from 'better-auth/plugins';
 
 @Module({
   imports: [
     AuthModule.forRootAsync({
+      imports: [DatabaseModule],
+      inject: [AppConfigService, DbConnection],
       useFactory: (config: AppConfigService, connection: DbConnection) => ({
         secret: config.get('auth').secret,
-        baseURL: config.get('appUrl'),
+        basePath: '/api/auth',
         database: drizzleDatabase(connection),
         emailAndPassword: { enabled: true },
-        plugins: [admin(), bearer()],
       }),
-      inject: [AppConfigService, DbConnection] as const,
     }),
   ],
 })
-export class AccountsModule {}
-```
-
-That is the whole integration. `forRoot(options)` is the same thing without a factory,
-for when the secret is not behind config.
-
-`forRootAsync` exists for the one reason it exists on `LoggerModule`, `DbModule` and
-the rest: a zero-argument function cannot read `ConfigService`. It is not a second
-mechanism - dunx settles every async factory before the first constructor runs, so
-the instance is built and the connection handshaked before anything can ask for
-either.
-
-### The database tables
-
-**dunx ships no schema for better-auth's tables.** They are better-auth's, they change
-with the plugins you enable, and its own CLI generates them:
-
-```bash
-bunx @better-auth/cli generate
-```
-
-Put the result in the schema object you already hand `@dunx/infra/db`, and
-`drizzleDatabase(connection)` needs no schema argument - `@dunx/infra/db` builds its
-handle with `drizzle({ client, schema })`, and better-auth's adapter reads
-`db._.fullSchema` off it. `examples/full/src/database/auth.schema.ts` is a
-generated schema in place.
-
-A framework carrying its own copy of a library's tables is a copy that rots against
-the library that reads them.
-
-## Mounting
-
-`AuthHandler` puts better-auth's `(request: Request) => Promise<Response>` behind five
-wildcard routes - `GET`, `POST`, `PUT`, `PATCH` and `DELETE` at `<basePath>/*`.
-`Bun.serve` matches a wildcard natively, so **Bun is still the router**: dunx does not
-restate, wrap or re-dispatch a single better-auth endpoint, and the `Response` comes
-back untouched, `Set-Cookie` headers and redirects included.
-
-`basePath` is better-auth's own option, defaulting to `/api/auth`.
-
-### With `setGlobalPrefix`
-
-better-auth resolves an endpoint by comparing the **whole pathname** to its
-`basePath`, so a global prefix makes the mount and the base path two different
-strings for one URL:
-
-```ts
-// app.setGlobalPrefix('api') turns the `/auth` route into `/api/auth`.
-AuthModule.forRootAsync({ useFactory: () => ({ basePath: '/api/auth', ... }) }, '/auth');
-```
-
-The second argument is the **route** path; `basePath` is what the browser sees. Get it
-wrong and the first request through the handler fails with an `AuthError` naming both
-paths, rather than better-auth quietly answering 404 to everything.
-
-## The guard
-
-```ts
-// Global - every route needs a session unless it says otherwise.
-HttpFactory.create(root, { middleware: [SessionGuard] });
-
-// or scoped - this controller needs one, nothing else does.
-@UseGuards(SessionGuard)
-@Controller('profile')
-class ProfileController {}
-```
-
-`AuthModule` registers `SessionGuard` as a provider either way. It resolves the
-session through better-auth's own `api.getSession`, so a cookie and the `bearer`
-plugin's `Authorization: Bearer <token>` both work, and then reads the metadata
-`@dunx/http` already had:
+export class AuthFeatureModule {}
 
-- **`@Public()`** - skipped outright. No session lookup, no rejection, no role check.
-  The guard is safe to install globally for that reason: `AuthHandler` is `@Public()`,
-  and a sign-in endpoint that required a session could never be reached.
-- **`@Roles('admin', 'editor')`** - a 403 unless the caller holds one of them.
-  `@dunx/openapi` already reads the same key for its security schemes.
-
-A public route that wants to *adapt* to an optional caller asks better-auth itself:
-
-```ts
-const principal = await this.auth.api.getSession({ headers: req.headers });
-```
-
-One line, and it keeps a session lookup off every public request in the app.
-
-## Reaching the caller
-
-`AuthContext` is `AsyncLocalStorage`, so a service three constructor hops from the
-route sees the principal without it being threaded through a signature:
-
-```ts
-export class Audit {
-  constructor(private readonly auth: AuthContext) {}
-
-  entries(): readonly string[] {
-    const { user } = this.auth.require(); // 401 if there is none
-    return this.log.forUser(user.id);
-  }
-}
-```
-
-`current()` returns `Principal | undefined`; `require()` throws a 401.
-
-Two alternatives were rejected. Request-scoped DI was measured and turned down
-(`docs/ARCHITECTURE.md`), and hanging the principal off `req` reaches a route handler
-but nothing a route handler calls. `AsyncLocalStorage` is a Node built-in Bun
-implements natively, and it is already how `@dunx/core` carries request state.
-
-It is a **second** store rather than a key in `RequestContext`, because that one is
-the log record - every field in it is serialized into every line the request writes,
-so a session object there would be noise on each entry and a redaction hazard in the
-ones that matter. `userId` does go there, so every log line inside a
-guarded request is already correlated to the user.
-
-### Plugin types
-
-`Auth` is generic over the options it was built from, the same trick
-`@dunx/infra/db` uses for drizzle's schema: the token is the erased class, the type
-argument rides on the annotation.
-
-```ts
-export const authOptions = { plugins: [admin()], ... } as const;
-
-// `api` here has the admin plugin's endpoints on it.
-constructor(private readonly auth: Auth<typeof authOptions>) {}
-```
-
-Written bare, `Auth` carries better-auth's core endpoints only.
-
-## Password hashing
-
-better-auth's default hasher is **pure-JavaScript scrypt**. `AuthModule` replaces it
-with `bunPassword` - native bcrypt through `Bun.password` - whenever
-`emailAndPassword` is enabled and you did not supply a `password` of your own. That is
-The rule is simple: if Bun ships it, use Bun.
-
-Bun pre-hashes the input, so bcrypt's 72-byte cap is a non-issue even for a
-maximum-length multibyte password, and `verify` reads a hash from another algorithm as
-a clean authentication failure rather than a 500.
-
-**Migrating an existing user table?** Those users' scrypt hashes will no longer verify
-and they will have to reset their passwords. Pass your own `emailAndPassword.password`
-to keep the old hasher, or a hybrid that tries both.
-
-## Sessions in Redis
-
-```ts
-import { redisStorage } from '@dunx/auth';
-
-AuthModule.forRootAsync({
-  useFactory: (redis: RedisConnection) => ({
-    secondaryStorage: redisStorage(redis),
-    ...
-  }),
-  inject: [RedisConnection] as const,
-});
+// Globally, and opt routes out with @Public():
+HttpFactory.create(AppModule, { middleware: [SessionGuard] });
 ```
 
-Sessions, verification values and rate-limit counters then live in Redis instead of
-costing a database round trip per request.
+## What is here
 
-All five methods are implemented, beyond the three that are mandatory. `getAndDelete` and
-`increment` are optional in better-auth's interface because most clients cannot do
-them atomically - `Bun.RedisClient` can, through `GETDEL` and `INCR`. Without them
-better-auth falls back to read-then-delete for single-use credentials, which is a
-race, and to a non-atomic rate-limit counter.
+The [Authentication guide](../../docs/guide/17-authentication.md) is canonical.
 
-`redisStorage` takes a `RedisStore`, which is six methods restated rather than
-imported - an `@dunx/infra/redis` `RedisConnection` satisfies it structurally, and so
-does anything else shaped like `Bun.RedisClient`.
+| Export                | What it does                                                    |
+| --------------------- | ----------------------------------------------------------------- |
+| `AuthModule`          | Builds the instance, mounts the handler, binds the guard          |
+| `Auth`                | The better-auth instance, injectable                              |
+| `SessionGuard`        | Authenticates, honours `@Public()` and `@Roles()`                 |
+| `AuthContext`         | The authenticated caller, anywhere in the request                 |
+| `betterAuthDocument`  | better-auth's own paths merged into the OpenAPI document          |
+| `bunPassword`         | `Bun.password` native bcrypt, applied by default                  |
+| `@dunx/auth/drizzle`  | better-auth over the connection the app already opened            |
+| `@dunx/auth/redis`    | `secondaryStorage` over `Bun.RedisClient`                         |
 
-## What is bound
+## Notes
 
-`AuthModule` binds four things and mounts one controller:
+- dunx ships no schema for better-auth's tables. They are better-auth's, they
+  change with its plugins, and `bunx @better-auth/cli generate` writes them.
+  Export them under the singular model names the adapter looks up.
+- Under `setGlobalPrefix`, `basePath` is what better-auth matches and `mountAt`
+  is where the route is mounted. Omitting `mountAt` with a non-default
+  `basePath` is a boot error.
+- `AuthContext` is a second `AsyncLocalStorage` store rather than a key in
+  `RequestContext`, because everything in that store is serialized into every
+  log line the request writes.
 
-| Token         | Resolves to                                                     |
-| ------------- | --------------------------------------------------------------- |
-| `AuthOptions` | The resolved options, the `basePath`, and the mount path         |
-| `Auth`        | The better-auth instance                                        |
-| `AuthContext` | The per-request principal store                                 |
-| `SessionGuard`| The guard, ready for `middleware: [...]` or `@UseGuards`         |
+## License
 
-Every one of them declares its own `inject` list, so none of it needs
-`@dunx/transform`'s transform to have run - `@dunx/auth` works in an app with no
-preload.
+MIT

package/dist/auth.d.ts

@@ -1,20 +1,13 @@
 import type { Auth as Instance, BetterAuthOptions } from 'better-auth';
 /**
  * The injection token for the better-auth instance, and the whole of dunx's
- * contract with the library.
+ * contract with the library. `betterAuth()` returns a plain object, so there is no
+ * class to use: this is an abstract class whose members alias better-auth's own,
+ * which a real instance satisfies structurally.
  *
- * `betterAuth()` returns a plain object, so there is no class to use as a token.
- * This is the same trick `Logger` and `RequestContext` use in `@dunx/core`: an
- * abstract class whose members are **aliases of better-auth's own** - not
- * restatements - which a real instance satisfies structurally. That is what makes
- * `constructor(private readonly auth: Auth)` work, since `@dunx/transform` records
- * the bare type name and the container resolves it.
- *
- * The type argument is the `DbModule` trick from `@dunx/infra/db`: the token is the
- * erased class, so `Auth<typeof authOptions>` at an injection site keeps the
- * plugin-widened `api` while still resolving the one binding. Written bare, `Auth`
- * carries better-auth's core endpoints only - a plugin's endpoints are on the
- * annotation, not on the token.
+ * The type argument is `DbModule`'s trick - the token is the erased class, so
+ * `Auth<typeof authOptions>` keeps the plugin-widened `api` while resolving the
+ * one binding. Written bare it carries better-auth's core endpoints only.
  */
 export declare abstract class Auth<O extends BetterAuthOptions = BetterAuthOptions> {
     /**

package/dist/context.d.ts

@@ -2,21 +2,16 @@ import { RequestContext } from '@dunx/core';
 import type { BetterAuthOptions } from 'better-auth';
 import type { Principal } from './auth.js';
 /**
- * How the authenticated caller reaches a handler - and anything the handler calls,
- * however deep.
+ * How the authenticated caller reaches a handler, and anything the handler calls.
  *
- * `AsyncLocalStorage`, for the same reason `@dunx/core`'s `RequestContext` is: it is
- * a Node built-in Bun implements natively, and it is the only mechanism that gets a
- * value from middleware to a service three constructor hops away without passing
- * it. The alternatives were both worse - request-scoped DI was measured and rejected
- * (docs/ARCHITECTURE.md), and hanging the principal off `req` reaches a route
- * handler but nothing a route handler calls.
+ * `AsyncLocalStorage`, the only mechanism that gets a value from middleware to a
+ * service three constructor hops away without passing it. Request-scoped DI was
+ * measured and rejected; hanging the principal off `req` reaches a route handler
+ * but nothing it calls.
  *
- * It is a **second** store rather than a key in `RequestContext`. That store is the
- * log record: every field in it is serialized into every line the request writes, so
- * a session object there would be noise on each entry and a redaction hazard in the
- * ones that matter. What does go there is `userId` - a well-known `RequestFields`
- * key - so the log lines are correlated without carrying the principal.
+ * A second store rather than a key in `RequestContext`: that one is the log
+ * record, so a session object there would be noise on every line and a redaction
+ * hazard. `userId` does go there, so lines correlate without the principal.
  */
 export declare class AuthContext {
     #private;

package/dist/drizzle.d.ts

@@ -14,9 +14,9 @@ export interface DrizzleSource {
     readonly db: unknown;
 }
 /**
- * better-auth's `database` option over a connection the app already opened. Nothing
- * here connects: the point is that the app keeps **one** pool, one SQLite handle and
- * one shutdown path, instead of better-auth opening a second.
+ * better-auth's `database` option over a connection the app already opened, so the
+ * app keeps one pool and one shutdown path rather than better-auth opening a
+ * second. Nothing here connects.
  *
  * ```ts
  * AuthModule.forRootAsync({
@@ -27,29 +27,12 @@ export interface DrizzleSource {
  * });
  * ```
  *
- * The `provider` comes from the connection's own dialect, so swapping `bun:sqlite`
- * for `Bun.SQL` needs no edit at the call site. The schema does not have to be passed
- * either - `@dunx/infra/db` builds its handle with `drizzle({ client, schema })` and
- * the adapter reads `db._.fullSchema`.
- *
- * **The tables have to be exported under the names better-auth looks up**, which is
- * the singular model name and not the table name. The adapter does `fullSchema['user']`,
- * so a barrel exporting `users` fails on the first query rather than at boot:
- *
- * ```
- * BetterAuthError: [# Drizzle Adapter]: The model "user" was not found in the schema object.
- * ```
- *
- * Either name the exports `user`, `session`, `account` and `verification`, or map them
- * where the schema is assembled:
+ * The `provider` comes from the connection's dialect and the schema off
+ * `db._.fullSchema`. Tables must be exported under better-auth's singular model
+ * names, so a barrel exporting `users` fails on first query:
  *
  * ```ts
  * schema: { user: users, session: sessions, account: accounts, verification: verifications }
  * ```
- *
- * dunx ships **no** schema for those tables. They are better-auth's, they change with
- * its plugins, and its own CLI generates them: `bunx @better-auth/cli generate`. A
- * copy of them inside a framework is a copy that silently rots against the library
- * that reads it.
  */
 export declare const drizzleDatabase: (connection: DrizzleSource, config?: Omit<DrizzleAdapterConfig, 'provider'>) => ReturnType<typeof drizzleAdapter>;

package/dist/guard.d.ts

@@ -10,20 +10,16 @@ import { AuthContext } from './context.js';
  */
 export declare const rolesOf: (user: object) => readonly string[];
 /**
- * Authenticates every request it sees through better-auth's own session lookup, and
- * composes with the metadata `@dunx/http` already carries:
+ * Authenticates every request through better-auth's own session lookup, composing
+ * with the metadata `@dunx/http` carries:
  *
- * - `@Public()` - skipped outright. No session lookup, no rejection, no role check.
- *   That is what makes it safe to install globally: better-auth's own endpoints are
- *   `@Public()`, and a sign-in route that needed a session could never be reached.
- *   A public route that wants to *adapt* to an optional caller injects `Auth` and
- *   calls `auth.api.getSession({ headers: req.headers })` itself - one line, and it
- *   does not put a lookup on every public request in the app.
- * - `@Roles('admin')` - a 403 unless the caller holds one of them.
+ * - `@Public()` - skipped outright, which is what makes it safe to install
+ *   globally: better-auth's own endpoints are public. A public route adapting to
+ *   an optional caller injects `Auth` and looks the session up itself.
+ * - `@Roles('admin')` - a 403 unless the caller holds one.
  *
- * Install it globally with `HttpFactory.create(root, { middleware: [SessionGuard] })`
- * and opt routes out with `@Public()`, or scope it with `@UseGuards(SessionGuard)`
- * and leave the rest of the app open. `AuthModule` registers it either way.
+ * Install it in `HttpFactory.create(root, { middleware: [SessionGuard] })`, or
+ * scope it with `@UseGuards(SessionGuard)`. `AuthModule` registers it either way.
  */
 export declare class SessionGuard implements Middleware {
     private readonly auth;

package/dist/handler.d.ts

@@ -2,25 +2,14 @@ import { type Ctor } from '@dunx/core';
 import { type Input, type RouteSchemas } from '@dunx/http';
 /**
  * better-auth's handler is a plain `(request: Request) => Promise<Response>`, so
- * mounting it is five one-line routes and nothing else. Every endpoint the library
- * and its plugins declare lives under one wildcard - dunx does not restate, wrap or
- * re-dispatch a single one of them.
+ * mounting it is five one-line routes. Every endpoint it and its plugins declare
+ * lives under one wildcard, which `Bun.serve` matches natively, so Bun is still
+ * the router. All five verbs, because a plugin may declare any of them.
  *
- * `Bun.serve` matches `<basePath>/*` natively (verified on Bun 1.3.14), so Bun is
- * still the router. All five verbs are mounted because a plugin may declare any of
- * them; better-auth's own endpoints are `GET` and `POST`.
- *
- * The `Response` is returned untouched - `buildRoutes` passes one straight through,
- * which is what keeps better-auth's `Set-Cookie` headers and redirects intact.
- *
- * `@Public()` at class scope, so all five inherit it - `mergeMeta` reads the class's
- * record under the handler's. Without it a globally installed `SessionGuard` would
- * demand a session from the sign-in endpoint, and no session could ever be created.
- *
- * `inject(Auth)` in a field rather than a constructor parameter, because a bare
- * class in `controllers` is bound as a class provider and would then need
- * `@dunx/transform`'s transform to have run. This way mounting works in an app that
- * never added the preload.
+ * The `Response` is returned untouched, keeping `Set-Cookie` and redirects intact.
+ * `@Public()` at class scope, or a global `SessionGuard` would demand a session
+ * from the sign-in endpoint. `inject(Auth)` in a field rather than a constructor
+ * parameter, so mounting works without the transform preload.
  */
 export declare class AuthHandler {
     #private;
@@ -33,17 +22,12 @@ export declare class AuthHandler {
 /**
  * The controller `AuthModule` registers, prefixed with `AuthOptions.mountAt`.
  *
- * A subclass rather than `@Controller(...)` on {@link AuthHandler} itself: the prefix
- * is only known once the module is configured, and mutating the shared class from a
- * factory would make two configurations fight over one prefix. The subclass declares
- * nothing of its own and inherits everything - `discoverRoutes` walks the prototype
- * chain for the routes, and `metaOf` and `prefixOf` are plain lookups, so `@Public()`
- * comes down from the base while the prefix stays own to the subclass.
+ * A subclass rather than `@Controller(...)` on {@link AuthHandler}: the prefix is
+ * only known once the module is configured, and mutating the shared class would
+ * make two configurations fight over one. The subclass inherits the routes and
+ * `@Public()` off the prototype chain while owning the prefix.
  *
- * `@ApiHidden()` because the mount is a wildcard. The route is real and has to be
- * served, but `*` is not an OpenAPI path template, so documenting it produced an
- * invalid entry tagged with this class's internal name - alongside the paths
- * `betterAuthDocument` describes properly, which is where the auth surface should
- * be read from.
+ * `@ApiHidden()` because `*` is not an OpenAPI path template;
+ * `betterAuthDocument` describes the auth surface properly.
  */
 export declare const mountHandler: (mountAt: string) => Ctor<AuthHandler>;

package/dist/index.js

@@ -51,9 +51,7 @@ class AuthContext {
     return this.#storage.run(principal, callback);
   }
 }
-Object.defineProperty(AuthContext, Symbol.for("dunx.deps"), {
-  value: () => [RequestContext]
-});
+Object.defineProperty(AuthContext, Symbol.for("dunx.deps"), { value: () => [RequestContext] });
 // src/guard.ts
 import {
   HttpError as HttpError2,
@@ -98,9 +96,7 @@ class SessionGuard {
     return this.context.run(principal, next);
   }
 }
-Object.defineProperty(SessionGuard, Symbol.for("dunx.deps"), {
-  value: () => [Auth, AuthContext]
-});
+Object.defineProperty(SessionGuard, Symbol.for("dunx.deps"), { value: () => [Auth, AuthContext] });
 // src/handler.ts
 import { inject } from "@dunx/core";
 import {
@@ -158,9 +154,7 @@ class AuthOptions {
     this.options = withBunPassword({ ...init, basePath: this.basePath });
   }
 }
-Object.defineProperty(AuthOptions, Symbol.for("dunx.deps"), {
-  value: () => [{ unresolved: "init: O" }, { unresolved: "mountAt?: string" }]
-});
+Object.defineProperty(AuthOptions, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "init: O" }, { unresolved: "mountAt?: string" }] });
 
 // src/handler.ts
 var _dec = [

package/dist/module.d.ts

@@ -1,17 +1,11 @@
 import { type Deps, type DynamicModule, type AsyncModuleConfig } from '@dunx/core';
 import { type BetterAuthOptions } from 'better-auth';
 /**
- * Binds three tokens and one controller:
+ * Binds `AuthOptions`, `Auth` and `AuthContext`, plus a prefixed `AuthHandler`
+ * serving every better-auth endpoint under `basePath`.
  *
- * - `AuthOptions` - what `betterAuth()` was called with, and where it is mounted.
- * - `Auth` - the better-auth instance itself.
- * - `AuthContext` - the authenticated caller, per request.
- * - a prefixed `AuthHandler`, serving every better-auth endpoint under `basePath`.
- *
- * `SessionGuard` is registered as a provider rather than installed as global
- * middleware, because whether it guards the whole app or one controller is the app's
- * decision - pass it to `HttpFactory.create(root, { middleware: [SessionGuard] })`
- * or to `@UseGuards(SessionGuard)`.
+ * `SessionGuard` is a provider rather than global middleware: whether it guards
+ * the whole app or one controller is the app's decision.
  */
 export declare class AuthModule {
     /**
@@ -33,9 +27,8 @@ export declare class AuthModule {
      */
     static forRoot<const O extends BetterAuthOptions>(options: O, mountAt?: string): DynamicModule;
     /**
-     * `forRoot` with the options behind a factory that may await and may inject -
-     * which is the only way the secret, the base URL and the database can come from
-     * `ConfigService` rather than from module scope:
+     * `forRoot` with the options behind a factory that may await and inject, so the
+     * secret, base URL and database can come from `ConfigService`:
      *
      * ```ts
      * AuthModule.forRootAsync({
@@ -49,13 +42,10 @@ export declare class AuthModule {
      * });
      * ```
      *
-     * `mountAt` is a second, **synchronous** argument for the same reason
-     * `DbModule.forRootAsync` takes its token positionally: the mount is a route in
-     * Bun's table, and that table is built before any factory has run. It is only
-     * needed under a global prefix - see {@link AuthOptions.mountAt}. Omitting it while
-     * the factory returns a non-default `basePath` is a boot error, because that
-     * combination could only ever have mounted the handler where better-auth is not
-     * looking.
+     * `mountAt` is a second, synchronous argument: the mount is a route in Bun's
+     * table, built before any factory has run. Only needed under a global prefix.
+     * Omitting it while the factory returns a non-default `basePath` is a boot
+     * error, since that would mount the handler where better-auth is not looking.
      */
     static forRootAsync<const D extends Deps>(provider: AsyncModuleConfig<BetterAuthOptions, D>, mountAt?: string): DynamicModule;
 }

package/dist/openapi.d.ts

@@ -38,16 +38,12 @@ export interface AuthDocumentOptions {
     readonly tag?: string;
 }
 /**
- * Better Auth's own endpoints, as a contribution to the app's OpenAPI document.
+ * better-auth's own endpoints, contributed to the app's OpenAPI document. It
+ * serves `<basePath>/*` from its own handler, so route discovery sees none of it
+ * and the document would omit the whole authentication surface.
  *
- * Better Auth serves `<basePath>/*` from its own handler rather than from dunx
- * controllers, so route discovery cannot see any of it and the document would
- * describe an API missing its entire authentication surface. This asks the
- * library for its schema and hands it over:
- *
- * **`forRootAsync`, not `forRoot`.** `forRoot` is evaluated while the module graph
- * is being described, before there is a container, so there is nowhere for the
- * `Auth` instance to come from. The async pair injects it:
+ * `forRootAsync`, not `forRoot`: the latter is evaluated while the module graph is
+ * described, before there is a container to take `Auth` from.
  *
  * ```ts
  * OpenApiModule.forRootAsync({
@@ -61,16 +57,7 @@ export interface AuthDocumentOptions {
  * });
  * ```
  *
- * Building a second `betterAuth()` purely to generate the schema is the workaround
- * this replaces, and it is not needed.
- *
- * **Better Auth only generates a schema when the `openAPI()` plugin is enabled.**
- * Without it `generateOpenAPISchema` is absent and this contributes nothing rather
- * than throwing, because a missing plugin should cost documentation and not boot.
- * Pass `openAPI({ disableDefaultReference: true })` if you want the schema without
- * Better Auth also mounting its own reference page next to the dunx one.
- *
- * Paths are rewritten to sit under `basePath`, since the library reports them
- * relative to its own mount.
+ * A schema exists only with the `openAPI()` plugin enabled; without it this
+ * contributes nothing rather than throwing. Paths are rewritten under `basePath`.
  */
 export declare const betterAuthDocument: (auth: OpenApiCapableAuth, options: AuthDocumentOptions) => () => Promise<AuthDocumentFragment>;

package/dist/password.d.ts

@@ -1,19 +1,12 @@
 /**
- * better-auth's `emailAndPassword.password`, backed by `Bun.password`.
+ * better-auth's `emailAndPassword.password`, backed by `Bun.password`. Applied by
+ * `AuthModule` when `emailAndPassword` is enabled and no hasher is given;
+ * better-auth's own default is JavaScript scrypt. Bun pre-hashes the input, so
+ * bcrypt's 72-byte cap is a non-issue.
  *
- * Applied by `AuthModule` whenever `emailAndPassword` is enabled and no `password`
- * of your own is given. better-auth's default is a **pure-JavaScript scrypt**;
- * `Bun.password` is native bcrypt, and the rule is simple - if Bun ships it,
- * use Bun.
- *
- * Bun pre-hashes the input, so bcrypt's 72-byte cap is a non-issue even for a
- * maximum-length multibyte password.
- *
- * `verify` swallows Bun's `UnsupportedAlgorithm` throw, so a hash produced by a
- * *different* algorithm - a scrypt hash written before this was in place - is a
- * clean authentication failure rather than a 500. Those users must reset their
- * password to get a bcrypt hash; pass your own `password` implementation instead
- * if you are migrating an existing user table and cannot.
+ * `verify` swallows Bun's `UnsupportedAlgorithm` throw, so a hash from a different
+ * algorithm is a clean authentication failure rather than a 500. Those users must
+ * reset; pass your own implementation if you are migrating a table and cannot.
  */
 export declare const bunPassword: {
     hash: (password: string) => Promise<string>;

package/dist/redis.d.ts

@@ -17,25 +17,17 @@ export interface RedisStore {
     del(key: string): Promise<number>;
 }
 /**
- * better-auth's `secondaryStorage` over `Bun.RedisClient`, so sessions, verification
- * values and rate-limit counters live in Redis instead of costing a database round
- * trip on every request.
+ * better-auth's `secondaryStorage` over `Bun.RedisClient`, so sessions and
+ * rate-limit counters cost no database round trip.
  *
- * All five methods are implemented, not the three that are mandatory.
- * `getAndDelete` and `increment` are optional in better-auth's interface because most
- * clients cannot do them atomically - `Bun.RedisClient` can, through `GETDEL` and
- * `INCR`, both already on `@dunx/infra/redis`'s contract. Without them better-auth
- * falls back to read-then-delete for single-use credentials, which is a race, and to
- * a non-atomic rate-limit counter.
+ * All five methods, not the three that are mandatory: `getAndDelete` and
+ * `increment` are optional because most clients cannot do them atomically, and
+ * `Bun.RedisClient` can through `GETDEL` and `INCR`. Without them better-auth
+ * falls back to a read-then-delete race and a non-atomic counter.
  *
- * `increment`'s TTL applies on creation only, which is what makes the counter expire
- * a fixed window after the first hit rather than sliding forever: `INCR` returning
- * `1` is the signal that this call created the key.
- *
- * Redis being unreachable is deliberately **not** softened here. Bun's client
- * connects lazily and queues, so a command against a down server rejects and
- * better-auth's own error path is what should see it - a swallowed `null` from `get`
- * would read as "no session" and sign every user out.
+ * `increment`'s TTL applies on creation only, so the window is fixed from the
+ * first hit. An unreachable Redis is not softened: a swallowed `null` would read
+ * as "no session" and sign every user out.
  */
 export declare const redisStorage: (connection: RedisStore) => SecondaryStorage;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/auth",
-  "version": "2.5.0",
+  "version": "3.0.1",
   "description": "Better Auth for dunx: its handler mounted on Bun.serve, a session guard reading @Public() and @Roles(), the caller in async context, and Bun.password hashing",
   "keywords": [
     "auth",
@@ -58,8 +58,8 @@
     "drizzle-orm": "^0.45.2"
   },
   "peerDependencies": {
-    "@dunx/core": "^2.5.0",
-    "@dunx/http": "^2.5.0",
+    "@dunx/core": "^3.0.1",
+    "@dunx/http": "^3.0.1",
     "@types/bun": ">=1.3.0",
     "better-auth": "^1.6.25",
     "drizzle-orm": "^0.45.2"