@velajs/better-auth 0.6.1 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.0.0
+
+Native environment configuration and one immutable verified identity shared with provider-independent authorization.
+
+Requires the coordinated Vela 2.0 package set. See the workspace migration guide.
+
+## 1.0.0
+
+### Major Changes
+
+- a468b57: Run guards before ordinary identity parameters, install authentication globally and deny application routes by default, remove the insecure `defaultPolicy: 'allow'` mode and implicit auth-path bypass, enforce canonical auth mount paths, reject ambiguous authorization engines, and key module instances by the actual auth/factory reference. Anonymous routes must now use explicit `@Public()` or `@OptionalAuth()` metadata. Verified sessions now publish Vela's framework-owned principal identity and, when present, the Better Auth organization plugin's `activeOrganizationId` so downstream throttling can partition by principal and tenant before IP fallback.
+
 ## 0.6.1
 
 ### Patch Changes

package/README.md

@@ -8,13 +8,13 @@ pnpm add @velajs/better-auth better-auth
 
 ## Quick start
 
-Construct your better-auth instance once, hand it to `BetterAuthModule.forRoot`, then use `AuthGuard` + `@CurrentUser()` like any other vela primitive.
+Construct your better-auth instance once and hand it to `BetterAuthModule.forRoot`. The module installs `AuthGuard` application-wide by default; use `@CurrentUser()` on authenticated routes and mark the small anonymous surface explicitly.
 
 ```ts
 import { betterAuth } from 'better-auth';
-import { Module, Controller, Get, UseGuards, VelaFactory } from '@velajs/vela';
+import { Module, Controller, Get, VelaFactory } from '@velajs/vela';
 import {
-  BetterAuthModule, AuthGuard, CurrentUser, Public,
+  BetterAuthModule, CurrentUser, Public,
 } from '@velajs/better-auth';
 
 const auth = betterAuth({
@@ -24,7 +24,6 @@ const auth = betterAuth({
 });
 
 @Controller('/me')
-@UseGuards(AuthGuard)
 class MeController {
   @Get() me(@CurrentUser() user: { id: string; email: string }) {
     return { id: user.id, email: user.email };
@@ -35,7 +34,7 @@ class MeController {
 }
 
 @Module({
-  imports: [BetterAuthModule.forRoot({ auth, isGlobal: true })],
+  imports: [BetterAuthModule.forRoot({ auth })],
   controllers: [MeController],
 })
 class AppModule {}
@@ -51,13 +50,15 @@ export default app; // edge-compatible (.fetch)
 ```ts
 BetterAuthModule.forRoot({
   auth,                          // pre-constructed betterAuth({ ... }) instance
+  issuer: 'my-app:better-auth',  // stable namespace paired with user ids
   basePath: '/api/auth',         // default — must match your better-auth config
-  isGlobal: false,               // register AuthGuard as APP_GUARD (deny-by-default)
-  defaultPolicy: 'deny',         // 'deny' | 'allow' for unauthenticated requests
+  isGlobal: true,                // default — register AuthGuard as APP_GUARD
   mountHandler: true,            // mount /api/auth/* catch-all controller
 });
 ```
 
+Authentication has no allow-by-default compatibility mode. Use `@Public(true)` for routes that intentionally skip authentication, or `@OptionalAuth(true)` when the route accepts an anonymous identity. `isGlobal: false` is intended only for applications that install an equivalent global authentication guard themselves.
+
 ## Three composition patterns
 
 ### Pattern A — inline (simplest)
@@ -73,22 +74,19 @@ imports: [
 
 ### Pattern B — DI'd plugin construction
 
-`forRootAsync` lets vela services participate in your better-auth config. Required for Cloudflare D1 / Hyperdrive bindings, since env bindings only resolve at request time.
+`forRootAsync` requires an explicit `inject` tuple (use `inject: []` when there are no dependencies), so factory parameter types always have matching runtime tokens. It lets Vela services participate in your Better Auth configuration. On Workers, declare `WORKER_ENV = new InjectionToken<WorkerEnv>('app.Env')` and pass that token to `createCloudflareWorker(AppModule, { envToken: WORKER_ENV })`; the native event environment is available before DI factories run.
 
 ```ts
 imports: [
-  D1Module.forRoot({ binding: 'DB' }),
   BetterAuthModule.forRootAsync({
-    inject: [D1Service, EmailService],
-    useFactory: (d1: D1Service, email: EmailService) => ({
-      auth: betterAuth({
-        database: drizzleAdapter(drizzle(d1.binding), { provider: 'sqlite' }),
+    inject: [WORKER_ENV, EmailService],
+    useFactory: (env, email) => betterAuth({
+        database: drizzleAdapter(drizzle(env.DB), { provider: 'sqlite' }),
         plugins: [
           magicLink({ sendMagicLink: (data) => email.send(data) }), // DI'd EmailService
           apiKey(),
           twoFactor(),
         ],
-      }),
     }),
     isGlobal: true,
   }),
@@ -101,7 +99,7 @@ Each feature ships a self-contained vela module that exports a plugin token. App
 
 ```ts
 // magic-link-auth.module.ts
-import { Module, InjectionToken } from '@velajs/vela';
+import { Module, InjectionToken, defineProvider } from '@velajs/vela';
 import { magicLink } from 'better-auth/plugins';
 import { EmailService } from './email.service';
 
@@ -112,12 +110,11 @@ export const MAGIC_LINK_PLUGIN = new InjectionToken<ReturnType<typeof magicLink>
 @Module({
   providers: [
     EmailService,
-    {
-      provide: MAGIC_LINK_PLUGIN,
+    defineProvider(MAGIC_LINK_PLUGIN, {
       inject: [EmailService],
       useFactory: (email: EmailService) =>
         magicLink({ sendMagicLink: (d) => email.send({ to: d.email, link: d.url }) }),
-    },
+    }),
   ],
   exports: [MAGIC_LINK_PLUGIN],
 })
@@ -133,9 +130,7 @@ export class MagicLinkAuthModule {}
     BetterAuthModule.forRootAsync({
       imports: [MagicLinkAuthModule, OAuthAuthModule],
       inject: [MAGIC_LINK_PLUGIN, OAUTH_PLUGIN],
-      useFactory: (magicLink, oauth) => ({
-        auth: betterAuth({ database, plugins: [magicLink, oauth] }),
-      }),
+      useFactory: (magicLink, oauth) => betterAuth({ database, plugins: [magicLink, oauth] }),
       isGlobal: true,
     }),
   ],
@@ -153,7 +148,7 @@ import { BetterAuthService } from '@velajs/better-auth';
 
 @Injectable()
 class AdminUserService {
-  constructor(@Inject(BetterAuthService) private readonly auth: BetterAuthService) {}
+  constructor(@Inject(BetterAuthService) private readonly auth: BetterAuthService<typeof auth>) {}
 
   listSessions(userId: string) {
     return this.auth.api.listUserSessions({ userId });
@@ -164,32 +159,47 @@ class AdminUserService {
 }
 ```
 
-Under `forRootAsync`, the underlying `betterAuth({...})` instance is constructed **lazily on first `.auth` / `.api` / `.handler` access**. That's what makes Cloudflare bindings (D1, KV, R2) work: the user factory only runs after request-time middleware has populated env. No proxies, no lifecycle hooks — just a service with a cached field.
+Under `forRootAsync`, the underlying `betterAuth({...})` instance is constructed lazily on first `.auth` / `.api` / `.handler` access. The Workers adapter supplies the typed environment before DI and owns a separate application for each environment, so a cached auth instance never crosses environments.
 
 ## Decorators
 
 | Decorator           | Purpose                                                                  |
 | ------------------- | ------------------------------------------------------------------------ |
-| `@CurrentUser()`    | Lazy parameter — better-auth `User` from the request (read by AuthGuard) |
-| `@CurrentSession()` | Lazy parameter — better-auth `Session`                                   |
+| `@CurrentUser()`    | Better-auth `User` from the request after guards run                      |
+| `@CurrentSession()` | Better-auth `Session` after guards run                                    |
 | `@Public(true)`     | Class or method — bypass AuthGuard entirely                              |
 | `@OptionalAuth(true)` | Class or method — populate user if present, never throw 401            |
-| `@Roles(['admin'])` | Method — read by `RolesGuard`. Compares against `user.role`.            |
 
-`@CurrentUser()` returns a lazy proxy. It's always object-truthy (because it's a proxy). When auth is optional, probe a property instead of `!!user`:
+Optional identities are ordinary values: an anonymous caller receives the actual `undefined`, so normal truthiness checks are safe.
 
 ```ts
 handle(@CurrentUser() user: User | undefined) {
-  return { hasUser: user?.id != null };  // ✓ correct
+  return { hasUser: Boolean(user) };
 }
 ```
 
 ## Guards
 
-- **`AuthGuard`** — singleton. Reads `Authorization` header / cookies via `auth.api.getSession`, populates `REQUEST_CONTEXT`. Honors `@Public()` and `@OptionalAuth()` overrides. Always lets requests under `basePath` through (so the catch-all controller can run unauthenticated).
-- **`RolesGuard`** — singleton. Reads `@Roles([...])` metadata, compares against `user.role`. Use with `@UseGuards(AuthGuard, RolesGuard)` — order matters.
+- **`AuthGuard`** — singleton. Reads `Authorization` header / cookies via `auth.api.getSession`, validates the full base user/session models, and publishes Vela's trusted principal, tenant, roles, and session expiry for downstream security components. The Better Auth organization plugin's verified `activeOrganizationId` becomes the tenant partition when present. The guard honors only explicit `@Public()` / `@OptionalAuth()` metadata. The generated Better Auth catch-all controller is explicitly public; sharing its URL prefix never makes an application controller public.
+Permission and role guards live in `@velajs/authz/vela`: import `PermissionGuard`, `RequirePermission`, `RolesGuard`, and `Roles` there. They read the same trusted identity for Better Auth and Cloudflare Access. Run authentication before authorization.
+
+Global registration is the default: installing the module binds `AuthGuard` to `APP_GUARD`. Routes are deny-by-default; mark public ones with `@Public(true)`. The generated Better Auth controller is already marked public.
+
+When using `ThrottlerModule`, import Better Auth first. Vela then rate-limits by
+the verified issuer, subject, principal type, and active organization before it
+falls back to a platform-attested client address.
+
+`BETTER_AUTH_OPTIONS` now contains only runtime configuration; read the auth instance from `BetterAuthService`. The obsolete `defaultPolicy` option and default-path controller constant were removed. Use `createBetterAuthCatchallController()` for a manually mounted catch-all.
+
+## Trusted identity and typing
+
+`@CurrentUser()` and `@CurrentSession()` expose only validated Better Auth data tied to the exact current trusted identity. Public routes, missing/rejected sessions, logout, expiry, and another provider replacing the identity invalidate those values. Hono user variables and removed compatibility symbols cannot grant roles or permissions.
+
+Core `getTrustedRequestIdentity(request)` and authz `@CurrentIdentity()` return the verified issuer/subject/type, optional tenant, explicit roles, and credential expiry. WebSocket guards consume only the normalized server connection attachment and do not consult HTTP cookies or arbitrary socket role metadata.
+
+The integration accepts the minimal `BetterAuthInstance` contract instead of `Auth<any>`. `new BetterAuthService(() => auth)` infers the concrete instance and retains plugin API/result types. For an injected service, annotate `BetterAuthService<typeof auth>` with the same configured instance type. The unparameterized service intentionally exposes only the operations the framework itself requires.
 
-Global registration: pass `isGlobal: true` to `forRoot` (binds AuthGuard to `APP_GUARD`). Routes are deny-by-default; mark public ones with `@Public(true)`.
+Migration: identity symbols (`AUTH_USER_KEY`, `AUTH_SESSION_KEY`, issuer/type keys) were removed. Use validated parameter decorators or core's trusted identity reader. Authorization imports moved to `@velajs/authz/vela`; the module no longer registers duplicate provider-specific permission guards.
 
 ## Edge-safe DB adapters
 
@@ -223,7 +233,7 @@ class CustomCatchallController {
 }
 ```
 
-Pass `basePath: '/auth'` to `BetterAuthModule.forRoot` so `AuthGuard` skips the right paths, and keep your `betterAuth({ basePath: '/auth' })` config in sync.
+Pass `basePath: '/auth'` to `BetterAuthModule.forRoot` to mount the generated controller there, and keep your `betterAuth({ basePath: '/auth' })` config in sync. A custom catch-all must carry `@Public(true)` itself. Base paths must be canonical absolute paths: no root mount, trailing slash, wildcards, query/fragment, backslashes, or dot segments.
 
 ## License
 

package/dist/{better-auth.service-BMkyFX-w.js → better-auth.service-DurQ4JQf.js}

@@ -1,17 +1,17 @@
 import { Inject, Injectable, InjectionToken } from "@velajs/vela";
-//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorateParam.js
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorateParam.js
 function __decorateParam(paramIndex, decorator) {
 	return function(target, key) {
 		decorator(target, key, paramIndex);
 	};
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -60,4 +60,4 @@ BetterAuthService = __decorate([
 //#endregion
 export { __decorateMetadata as a, __decorateParam as i, BetterAuthService as n, __decorate as r, BETTER_AUTH_BUILDER as t };
 
-//# sourceMappingURL=better-auth.service-BMkyFX-w.js.map
+//# sourceMappingURL=better-auth.service-DurQ4JQf.js.map

package/dist/better-auth.service-DurQ4JQf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-auth.service-DurQ4JQf.js","names":[],"sources":["../src/better-auth.service.ts"],"sourcesContent":["import { Inject, Injectable, InjectionToken } from '@velajs/vela';\nimport type { BetterAuthInstance } from './better-auth.types';\n\n/**\n * Internal token holding the auth-construction closure with its inject deps\n * closed over. Resolves cheaply at module load (just captures references);\n * the inner call happens lazily on first auth use (see `BetterAuthService`).\n *\n * Not exported from the public surface — only the service consumes it.\n */\nexport const BETTER_AUTH_BUILDER = new InjectionToken<() => BetterAuthInstance>(\n  'vela.better-auth.Builder',\n);\n\n/**\n * The single injectable consumers reach for to interact with better-auth.\n * Wraps the underlying `betterAuth({...})` instance with lazy construction:\n *\n * - `forRoot({ auth })` — the builder returns the eagerly-provided instance,\n *   so the first `.auth` / `.api` / `.handler` access is effectively a\n *   read-and-cache.\n * - `forRootAsync({ inject, useFactory })` — the builder wraps the user's\n *   factory + inject deps. First access triggers `useFactory(...deps)`. This\n *   is what makes Cloudflare D1/KV bindings work: at module load the factory\n *   doesn't run; on first request (when AuthGuard or the catch-all calls\n *   `service.api` / `service.handler`), the native environment is registered and the\n *   factory can read them safely.\n *\n * Used directly by AuthGuard and the catch-all controller. Consumers in\n * application code inject the same way: `@Inject(BetterAuthService)`.\n */\n@Injectable()\nexport class BetterAuthService<TAuth extends BetterAuthInstance = BetterAuthInstance> {\n  private cached: TAuth | undefined;\n\n  constructor(@Inject(BETTER_AUTH_BUILDER) private readonly build: () => TAuth) {}\n\n  /**\n   * The underlying better-auth instance. Constructed once on first access.\n   * Safe to call from any request-time code path (guards, controllers,\n   * services invoked from handlers).\n   */\n  get auth(): TAuth {\n    if (!this.cached) this.cached = this.build();\n    return this.cached;\n  }\n\n  /** Convenience accessor — equivalent to `service.auth.api`. */\n  get api(): TAuth['api'] {\n    return this.auth.api;\n  }\n\n  /** Convenience accessor — equivalent to `service.auth.handler`. */\n  get handler(): TAuth['handler'] {\n    return this.auth.handler;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAUA,MAAa,sBAAsB,IAAI,eACrC,0BACF;AAoBO,IAAM,oBAAN,MAAM,kBAAyE;CAG1B;CAF1D;CAEA,YAAY,OAAkE;EAApB,KAAA,QAAA;CAAqB;;;;;;CAO/E,IAAI,OAAc;EAChB,IAAI,CAAC,KAAK,QAAQ,KAAK,SAAS,KAAK,MAAM;EAC3C,OAAO,KAAK;CACd;;CAGA,IAAI,MAAoB;EACtB,OAAO,KAAK,KAAK;CACnB;;CAGA,IAAI,UAA4B;EAC9B,OAAO,KAAK,KAAK;CACnB;AACF;;CAzBC,WAAW;CAIG,gBAAA,GAAA,OAAO,mBAAmB,CAAA"}

package/dist/better-auth.service-NOlWXxd4.d.ts

@@ -0,0 +1,68 @@
+import { InjectionToken } from "@velajs/vela";
+import { Auth, Session, User } from "better-auth";
+//#region src/better-auth.types.d.ts
+/** The runtime surface required by the integration; concrete instances retain their generics. */
+interface BetterAuthInstance {
+  readonly api: {
+    getSession(input: {
+      headers: Headers;
+    }): Promise<unknown>;
+  };
+  readonly handler: (request: Request) => Promise<Response>;
+  /** Used only by the real-session testing helper. */
+  readonly $context?: Promise<Pick<Awaited<Auth['$context']>, 'internalAdapter' | 'authCookies' | 'secret'>>;
+}
+interface BetterAuthModuleOptions<TAuth extends BetterAuthInstance = BetterAuthInstance> extends BetterAuthRuntimeOptions {
+  auth: TAuth;
+}
+/** Provider configuration, separate from the lazily constructed auth instance. */
+interface BetterAuthRuntimeOptions {
+  /** Stable namespace paired with user ids in authorization identities. */
+  issuer?: string;
+  basePath?: string;
+  /**
+   * Register AuthGuard application-wide. Defaults to `true`; opt out only when
+   * the application installs an equivalent global authentication guard itself.
+   */
+  isGlobal?: boolean;
+  mountHandler?: boolean;
+}
+type User$1 = User;
+type Session$1 = Session;
+//#endregion
+//#region src/better-auth.service.d.ts
+/**
+ * The single injectable consumers reach for to interact with better-auth.
+ * Wraps the underlying `betterAuth({...})` instance with lazy construction:
+ *
+ * - `forRoot({ auth })` — the builder returns the eagerly-provided instance,
+ *   so the first `.auth` / `.api` / `.handler` access is effectively a
+ *   read-and-cache.
+ * - `forRootAsync({ inject, useFactory })` — the builder wraps the user's
+ *   factory + inject deps. First access triggers `useFactory(...deps)`. This
+ *   is what makes Cloudflare D1/KV bindings work: at module load the factory
+ *   doesn't run; on first request (when AuthGuard or the catch-all calls
+ *   `service.api` / `service.handler`), the native environment is registered and the
+ *   factory can read them safely.
+ *
+ * Used directly by AuthGuard and the catch-all controller. Consumers in
+ * application code inject the same way: `@Inject(BetterAuthService)`.
+ */
+declare class BetterAuthService<TAuth extends BetterAuthInstance = BetterAuthInstance> {
+  private readonly build;
+  private cached;
+  constructor(build: () => TAuth);
+  /**
+   * The underlying better-auth instance. Constructed once on first access.
+   * Safe to call from any request-time code path (guards, controllers,
+   * services invoked from handlers).
+   */
+  get auth(): TAuth;
+  /** Convenience accessor — equivalent to `service.auth.api`. */
+  get api(): TAuth['api'];
+  /** Convenience accessor — equivalent to `service.auth.handler`. */
+  get handler(): TAuth['handler'];
+}
+//#endregion
+export { Session$1 as a, BetterAuthRuntimeOptions as i, BetterAuthInstance as n, User$1 as o, BetterAuthModuleOptions as r, BetterAuthService as t };
+//# sourceMappingURL=better-auth.service-NOlWXxd4.d.ts.map

package/dist/index.d.ts

@@ -1,18 +1,6 @@
+import { a as Session, i as BetterAuthRuntimeOptions, n as BetterAuthInstance, o as User, r as BetterAuthModuleOptions, t as BetterAuthService } from "./better-auth.service-NOlWXxd4.js";
 import { CanActivate, DynamicModule, ExecutionContext, InferTokens, InjectionToken, Token, Type } from "@velajs/vela";
-import { Auth, Session as Session$1, User as User$1 } from "better-auth";
 import { Identity, PermissionResolver } from "@velajs/authz";
-//#region src/better-auth.types.d.ts
-type BetterAuthInstance = Auth<any>;
-interface BetterAuthModuleOptions {
-  auth: BetterAuthInstance;
-  basePath?: string;
-  isGlobal?: boolean;
-  defaultPolicy?: 'deny' | 'allow';
-  mountHandler?: boolean;
-}
-type User = User$1;
-type Session = Session$1;
-//#endregion
 //#region src/better-auth.module.d.ts
 /**
  * Options for {@link BetterAuthModule.forRootAsync}.
@@ -23,23 +11,23 @@ type Session = Session$1;
  *
  * ```ts
  * BetterAuthModule.forRootAsync({
- *   inject: [D1Service, ConfigService],   // captured as readonly tuple
- *   useFactory: (d1, config) =>            // d1: D1Service, config: ConfigService
- *     betterAuth({ database: drizzleAdapter(drizzle(d1.database), ...) }),
+ *   inject: [WORKER_ENV, ConfigService], // captured as readonly tuple
+ *   useFactory: (env, config) =>          // inferred from the tokens
+ *     betterAuth({ database: drizzleAdapter(drizzle(env.DB), ...) }),
  * });
  * ```
  */
-interface ForRootAsyncOptions<Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]> {
-  inject?: Inject;
+interface ForRootAsyncOptions<Inject extends readonly Token[] = readonly Token[]> {
+  inject: Inject;
   imports?: DynamicModule['imports'];
   useFactory: (...deps: InferTokens<Inject>) => BetterAuthInstance;
   isGlobal?: boolean;
   mountHandler?: boolean;
   basePath?: string;
-  defaultPolicy?: 'deny' | 'allow';
+  issuer?: string;
   key?: string;
 }
-declare class BetterAuthModule {
+export declare class BetterAuthModule {
   /**
    * Synchronous registration. The auth instance is constructed by the consumer
    * at module-load time and passed in directly. Use this when the inputs to
@@ -55,47 +43,11 @@ declare class BetterAuthModule {
    * first time anything reads `BetterAuthService.auth` (or `.api` / `.handler`).
    * In normal request handling that's `AuthGuard.canActivate` or the catch-all
    * controller's `.handle`. At module load the factory does NOT run — it's only
-   * captured behind {@link lazyProvider}'s memoized thunk. This is what makes
-   * Cloudflare bindings (D1, KV, R2) work: the binding isn't ready at boot, but
-   * it IS by the time a request flows through and the guard / catch-all reads
-   * the service. Inject deps resolve at module load (cheap BindingRef wrappers);
-   * their *values* are read at first auth use, inside your factory body.
-   */
-  static forRootAsync<const Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]>(options: ForRootAsyncOptions<Inject>): DynamicModule;
-}
-//#endregion
-//#region src/better-auth.service.d.ts
-/**
- * The single injectable consumers reach for to interact with better-auth.
- * Wraps the underlying `betterAuth({...})` instance with lazy construction:
- *
- * - `forRoot({ auth })` — the builder returns the eagerly-provided instance,
- *   so the first `.auth` / `.api` / `.handler` access is effectively a
- *   read-and-cache.
- * - `forRootAsync({ inject, useFactory })` — the builder wraps the user's
- *   factory + inject deps. First access triggers `useFactory(...deps)`. This
- *   is what makes Cloudflare D1/KV bindings work: at module load the factory
- *   doesn't run; on first request (when AuthGuard or the catch-all calls
- *   `service.api` / `service.handler`), the bindings are populated and the
- *   factory can read them safely.
- *
- * Used directly by AuthGuard and the catch-all controller. Consumers in
- * application code inject the same way: `@Inject(BetterAuthService)`.
- */
-declare class BetterAuthService {
-  private readonly build;
-  private cached;
-  constructor(build: () => BetterAuthInstance);
-  /**
-   * The underlying better-auth instance. Constructed once on first access.
-   * Safe to call from any request-time code path (guards, controllers,
-   * services invoked from handlers).
+   * captured in the checked builder provider. The Workers adapter supplies its
+   * native environment before DI; the lazily constructed auth instance belongs
+   * to that environment's application and never captures another app's bindings.
    */
-  get auth(): BetterAuthInstance;
-  /** Convenience accessor — equivalent to `service.auth.api`. */
-  get api(): BetterAuthInstance['api'];
-  /** Convenience accessor — equivalent to `service.auth.handler`. */
-  get handler(): BetterAuthInstance['handler'];
+  static forRootAsync<const Inject extends readonly Token[] = readonly Token[]>(options: ForRootAsyncOptions<Inject>): DynamicModule;
 }
 //#endregion
 //#region src/better-auth.controller.d.ts
@@ -112,108 +64,33 @@ declare class BetterAuthService {
  *
  * Both default to `/api/auth`, so the no-prefix / no-config case just works.
  */
-declare function createBetterAuthCatchallController(basePath?: string): Type;
-/**
- * Default-path (`/api/auth`) catch-all controller. Retained for back-compat;
- * `BetterAuthModule` now mounts {@link createBetterAuthCatchallController} with
- * the configured `basePath`. Prefer the factory for a custom base path.
- */
-declare const BetterAuthCatchallController: Type;
+export declare function createBetterAuthCatchallController(basePath?: string): Type;
 //#endregion
 //#region src/better-auth.tokens.d.ts
-declare const BETTER_AUTH_OPTIONS: InjectionToken<BetterAuthModuleOptions>;
-declare const AUTH_USER_KEY: unique symbol;
-declare const AUTH_SESSION_KEY: unique symbol;
+export declare const BETTER_AUTH_OPTIONS: InjectionToken<BetterAuthRuntimeOptions>;
 //#endregion
 //#region src/guards/auth.guard.d.ts
-declare class AuthGuard implements CanActivate {
+export declare class AuthGuard implements CanActivate {
   private readonly auth;
   private readonly opts;
   private readonly reflector;
-  constructor(auth: BetterAuthService, opts: BetterAuthModuleOptions);
-  canActivate(context: ExecutionContext): Promise<boolean>;
-}
-//#endregion
-//#region src/guards/roles.guard.d.ts
-declare class RolesGuard implements CanActivate {
-  private readonly reflector;
-  canActivate(context: ExecutionContext): boolean;
-}
-//#endregion
-//#region src/guards/permission.guard.d.ts
-/**
- * Enforces the `@RequirePermission(...)` metadata against the `@velajs/authz`
- * engine. For each required permission it calls `authz.can(identity, perm)`,
- * requiring **all** of them (AND semantics — contrast {@link RolesGuard}, which
- * is OR over roles). The caller's `Identity` is derived from the better-auth
- * user that {@link AuthGuard} placed in the request context, so this guard must
- * run *after* `AuthGuard` (e.g. `@UseGuards(AuthGuard, PermissionGuard)`).
- *
- * `AUTHZ` is resolved at **request time** from the per-request container (the
- * same container `REQUEST_CONTEXT` is resolved from), not constructor-injected.
- * This deliberately avoids DI visibility coupling: the guard works whether or
- * not `AuthzModule` is registered as global — a present-but-non-global
- * `AuthzModule` resolves fine and, crucially, never crashes bootstrap. If
- * `AuthzModule` is not registered at all the resolve fails and the guard fails
- * closed (403) rather than granting access.
- *
- * Fail-closed on every abnormal path — no branch grants access on missing
- * wiring or a missing caller:
- * - no required permissions → allow (nothing to enforce);
- * - `AUTHZ` unresolvable (`AuthzModule` not registered) → deny (`ForbiddenException`);
- * - no authenticated user in the request context → deny;
- * - any single required permission not granted → deny.
- *
- * The guard is stateless (no injected dependencies), so it is safe to register
- * as a plain provided guard.
- */
-declare class PermissionGuard implements CanActivate {
-  private readonly reflector;
+  constructor(auth: BetterAuthService, opts: BetterAuthRuntimeOptions);
   canActivate(context: ExecutionContext): Promise<boolean>;
 }
 //#endregion
 //#region src/decorators/current-user.decorator.d.ts
-declare const CurrentUser: (data?: unknown, ...pipes: import("@velajs/vela").PipeType[]) => ParameterDecorator;
+export declare const CurrentUser: (data?: unknown, ...pipes: import("@velajs/vela").PipeType[]) => ParameterDecorator;
 //#endregion
 //#region src/decorators/current-session.decorator.d.ts
-declare const CurrentSession: (data?: unknown, ...pipes: import("@velajs/vela").PipeType[]) => ParameterDecorator;
+export declare const CurrentSession: (data?: unknown, ...pipes: import("@velajs/vela").PipeType[]) => ParameterDecorator;
 //#endregion
 //#region src/decorators/public.decorator.d.ts
-declare const Public: import("@velajs/vela").ReflectableDecorator<boolean>;
-declare const PUBLIC_KEY: string;
+export declare const Public: import("@velajs/vela").ReflectableDecorator<boolean>;
+export declare const PUBLIC_KEY: string;
 //#endregion
 //#region src/decorators/optional-auth.decorator.d.ts
-declare const OptionalAuth: import("@velajs/vela").ReflectableDecorator<boolean>;
-declare const OPTIONAL_AUTH_KEY: string;
-//#endregion
-//#region src/decorators/roles.decorator.d.ts
-declare const Roles: import("@velajs/vela").ReflectableDecorator<string[]>;
-declare const ROLES_KEY: string;
-//#endregion
-//#region src/decorators/require-permission.decorator.d.ts
-/**
- * Declares the `@velajs/authz` permission(s) required to reach a controller or
- * route handler. Read via `Reflector` in an authorization guard, then checked
- * against the caller's `Identity` with `authz.can(...)`.
- *
- * ```ts
- * @RequirePermission(['posts:write'])
- * @Post()
- * create() { ... }
- * ```
- *
- * The metadata is a plain `string[]` of permission strings in the granted-side
- * format `@velajs/authz` matches (`resource:action`, or wildcards like
- * `posts:*`). Handler-level metadata overrides class-level (standard
- * `Reflector.getAllAndOverride` precedence).
- *
- * Semantics are **require-ALL** (AND): every listed permission must be granted
- * for access — the `PermissionGuard` denies if any one is missing. This
- * contrasts with `@Roles`, which is **OR** (any one of the listed roles
- * suffices).
- */
-declare const RequirePermission: import("@velajs/vela").ReflectableDecorator<string[]>;
-declare const REQUIRE_PERMISSION_KEY: string;
+export declare const OptionalAuth: import("@velajs/vela").ReflectableDecorator<boolean>;
+export declare const OPTIONAL_AUTH_KEY: string;
 //#endregion
 //#region src/authz-bridge.d.ts
 /**
@@ -221,18 +98,22 @@ declare const REQUIRE_PERMISSION_KEY: string;
  * admin plugin. `role` may be a single role, a comma-separated list, or an
  * array — {@link identityFromUser} normalizes all three.
  */
-type AuthUser = User & {
+type AuthUser = Pick<User, 'id'> & {
   role?: string | string[] | null;
 };
+/** Stable issuer namespace used for better-auth session principals. */
+export declare const BETTER_AUTH_ISSUER = "better-auth";
 /**
- * Adapts a better-auth user into a `@velajs/authz` {@link Identity}. Maps
- * `user.id` → `userId` and the admin-plugin `role` field → `roles`.
+ * Pure authorization projection; this does not authenticate or publish trusted state.
+ * Adapts an already verified better-auth user into a stable `@velajs/authz` {@link Identity}.
+ * The issuer scopes `user.id` as both `subject` and the compatibility `userId`;
+ * the admin-plugin `role` field supplies local roles.
  *
  * Fail-closed: a missing user (`null`/`undefined`, i.e. an unauthenticated
  * request) maps to the zero-privilege identity `{ roles: [] }`, so downstream
  * `can()` checks grant nothing.
  */
-declare const identityFromUser: (user: AuthUser | null | undefined) => Identity;
+export declare const identityFromUser: (user: AuthUser | null | undefined, issuer?: string, principalType?: 'user' | 'service') => Identity;
 /**
  * The minimal slice of a better-auth access-control role consumed here. Both
  * `createAccessControl(...).newRole(...)` and the standalone `role(...)` return
@@ -248,7 +129,7 @@ interface BetterAuthAcRole {
  * permission strings — the granted-side format `@velajs/authz` matches
  * (wildcards included).
  */
-declare const permissionsFromAcRole: (role: BetterAuthAcRole) => string[];
+export declare const permissionsFromAcRole: (role: BetterAuthAcRole) => string[];
 /**
  * Builds a fail-closed `@velajs/authz` {@link PermissionResolver} from a
  * better-auth access-control role table (`{ roleName: acRole }` — the same map
@@ -264,7 +145,7 @@ declare const permissionsFromAcRole: (role: BetterAuthAcRole) => string[];
  * await authz.can(identityFromUser(user), 'posts:write');
  * ```
  */
-declare const betterAuthAcResolver: (roles: Readonly<Record<string, BetterAuthAcRole>>) => PermissionResolver;
+export declare const betterAuthAcResolver: (roles: Readonly<Record<string, BetterAuthAcRole>>) => PermissionResolver;
 //#endregion
-export { AUTH_SESSION_KEY, AUTH_USER_KEY, AuthGuard, type AuthUser, BETTER_AUTH_OPTIONS, type BetterAuthAcRole, BetterAuthCatchallController, type BetterAuthInstance, BetterAuthModule, type BetterAuthModuleOptions, BetterAuthService, CurrentSession, CurrentUser, OPTIONAL_AUTH_KEY, OptionalAuth, PUBLIC_KEY, PermissionGuard, Public, REQUIRE_PERMISSION_KEY, ROLES_KEY, RequirePermission, Roles, RolesGuard, type Session, type User, betterAuthAcResolver, createBetterAuthCatchallController, identityFromUser, permissionsFromAcRole };
+export { type AuthUser, type BetterAuthAcRole, type BetterAuthInstance, type BetterAuthModuleOptions, type BetterAuthRuntimeOptions, BetterAuthService, type Session, type User };
 //# sourceMappingURL=index.d.ts.map