@velajs/better-auth 0.6.0 → 1.0.0

package/CHANGELOG.md

@@ -1,10 +1,21 @@
 # Changelog
 
+## 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
+
+- 89f5473: Modernize the package build, validation, and release toolchain.
+
 ## 0.4.0 (2026-07-04)
 
 - Rebuilt on vela 1.11 `defineModule` + `lazyProvider` + `provideGlobal` (lazy auth-builder deferral preserved; public API unchanged). Requires `@velajs/vela >=1.11.0`.
 
-
 All notable changes to `@velajs/better-auth` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 

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)
@@ -170,26 +171,30 @@ Under `forRootAsync`, the underlying `betterAuth({...})` instance is constructed
 
 | 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).
+- **`AuthGuard`** — singleton. Reads `Authorization` header / cookies via `auth.api.getSession`, populates `REQUEST_CONTEXT`, and publishes Vela's trusted principal/tenant identity 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.
 - **`RolesGuard`** — singleton. Reads `@Roles([...])` metadata, compares against `user.role`. Use with `@UseGuards(AuthGuard, RolesGuard)` — order matters.
 
-Global registration: pass `isGlobal: true` to `forRoot` (binds AuthGuard to `APP_GUARD`). Routes are deny-by-default; mark public ones with `@Public(true)`.
+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.
 
 ## Edge-safe DB adapters
 
@@ -223,7 +228,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

@@ -0,0 +1,63 @@
+import { Inject, Injectable, InjectionToken } from "@velajs/vela";
+//#region \0@oxc-project+runtime@0.139.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
+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
+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);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/better-auth.service.ts
+/**
+* Internal token holding the auth-construction closure with its inject deps
+* closed over. Resolves cheaply at module load (just captures references);
+* the inner call happens lazily on first auth use (see `BetterAuthService`).
+*
+* Not exported from the public surface — only the service consumes it.
+*/
+const BETTER_AUTH_BUILDER = new InjectionToken("vela.better-auth.Builder");
+let BetterAuthService = class BetterAuthService {
+	build;
+	cached;
+	constructor(build) {
+		this.build = build;
+	}
+	/**
+	* 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() {
+		if (!this.cached) this.cached = this.build();
+		return this.cached;
+	}
+	/** Convenience accessor — equivalent to `service.auth.api`. */
+	get api() {
+		return this.auth.api;
+	}
+	/** Convenience accessor — equivalent to `service.auth.handler`. */
+	get handler() {
+		return this.auth.handler;
+	}
+};
+BetterAuthService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(BETTER_AUTH_BUILDER)),
+	__decorateMetadata("design:paramtypes", [Function])
+], BetterAuthService);
+//#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

package/dist/better-auth.service-BMkyFX-w.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-auth.service-BMkyFX-w.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 bindings are populated 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 {\n  private cached: BetterAuthInstance | undefined;\n\n  constructor(@Inject(BETTER_AUTH_BUILDER) private readonly build: () => BetterAuthInstance) {}\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(): BetterAuthInstance {\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(): BetterAuthInstance['api'] {\n    return this.auth.api;\n  }\n\n  /** Convenience accessor — equivalent to `service.auth.handler`. */\n  get handler(): BetterAuthInstance['handler'] {\n    return this.auth.handler;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAUA,MAAa,sBAAsB,IAAI,eACrC,0BACF;AAoBO,IAAA,oBAAA,MAAM,kBAAkB;CAG6B;CAF1D;CAEA,YAAY,OAA+E;EAAjC,KAAA,QAAA;CAAkC;;;;;;CAO5F,IAAI,OAA2B;EAC7B,IAAI,CAAC,KAAK,QAAQ,KAAK,SAAS,KAAK,MAAM;EAC3C,OAAO,KAAK;CACd;;CAGA,IAAI,MAAiC;EACnC,OAAO,KAAK,KAAK;CACnB;;CAGA,IAAI,UAAyC;EAC3C,OAAO,KAAK,KAAK;CACnB;AACF;;CAzBC,WAAW;oBAIG,OAAO,mBAAmB,CAAA"}

package/dist/index.d.ts

@@ -1,12 +1,280 @@
-export { BetterAuthModule } from './better-auth.module';
-export { BetterAuthService } from './better-auth.service';
-export { BetterAuthCatchallController, createBetterAuthCatchallController, } from './better-auth.controller';
-export { BETTER_AUTH_OPTIONS, AUTH_USER_KEY, AUTH_SESSION_KEY, } from './better-auth.tokens';
-export { AuthGuard } from './guards/auth.guard';
-export { RolesGuard } from './guards/roles.guard';
-export { CurrentUser } from './decorators/current-user.decorator';
-export { CurrentSession } from './decorators/current-session.decorator';
-export { Public, PUBLIC_KEY } from './decorators/public.decorator';
-export { OptionalAuth, OPTIONAL_AUTH_KEY } from './decorators/optional-auth.decorator';
-export { Roles, ROLES_KEY } from './decorators/roles.decorator';
-export type { BetterAuthInstance, BetterAuthModuleOptions, Session, User, } from './better-auth.types';
+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;
+  /** 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;
+  /** @deprecated Authentication is deny-by-default. Only `'deny'` is accepted. */
+  defaultPolicy?: 'deny';
+  mountHandler?: boolean;
+}
+type User = User$1;
+type Session = Session$1;
+//#endregion
+//#region src/better-auth.module.d.ts
+/**
+ * Options for {@link BetterAuthModule.forRootAsync}.
+ *
+ * The `Inject` type parameter captures the literal `inject` tuple at the call
+ * site (via `const` inference) so `useFactory` parameters are typed from the
+ * inject array, position-by-position — no `as const`, no `(...deps: any[])`:
+ *
+ * ```ts
+ * BetterAuthModule.forRootAsync({
+ *   inject: [D1Service, ConfigService],   // captured as readonly tuple
+ *   useFactory: (d1, config) =>            // d1: D1Service, config: ConfigService
+ *     betterAuth({ database: drizzleAdapter(drizzle(d1.database), ...) }),
+ * });
+ * ```
+ */
+interface ForRootAsyncOptions<Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]> {
+  inject?: Inject;
+  imports?: DynamicModule['imports'];
+  useFactory: (...deps: InferTokens<Inject>) => BetterAuthInstance;
+  isGlobal?: boolean;
+  mountHandler?: boolean;
+  basePath?: string;
+  issuer?: string;
+  /** @deprecated Authentication is deny-by-default. Only `'deny'` is accepted. */
+  defaultPolicy?: 'deny';
+  key?: string;
+}
+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
+   * `betterAuth({...})` are available at startup (Node apps with a static DB
+   * connection, in-memory adapters, etc.).
+   */
+  static forRoot(options: BetterAuthModuleOptions & {
+    isGlobal?: boolean;
+    key?: string;
+  }): DynamicModule;
+  /**
+   * Deferred / DI-driven registration. The user factory runs **lazily**, on the
+   * 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).
+   */
+  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'];
+}
+//#endregion
+//#region src/better-auth.controller.d.ts
+/**
+ * Build a catch-all controller that mounts better-auth's handler at `basePath`
+ * (default `/api/auth`). This is a factory because vela reads a controller's
+ * route off the class at decoration time, so a custom base path needs its own
+ * decorated class — the path can't be parametrized on a single shared class.
+ *
+ * Two base paths to keep consistent:
+ * - this `basePath` is RELATIVE to vela's `globalPrefix` (always prepended);
+ * - better-auth routes against its OWN absolute `basePath` (the one you pass to
+ *   `betterAuth({ basePath })`), which must equal `globalPrefix + basePath`.
+ *
+ * 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;
+//#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;
+declare const AUTH_ISSUER_KEY: unique symbol;
+declare const AUTH_PRINCIPAL_TYPE_KEY: unique symbol;
+//#endregion
+//#region src/guards/auth.guard.d.ts
+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 canonical request-local auth state, so this guard must
+ * run *after* `AuthGuard` (e.g. `@UseGuards(AuthGuard, PermissionGuard)`).
+ *
+ * `AUTHZ` is resolved at request time from the per-request container. Exactly
+ * one reachable engine is required; zero or multiple registrations deny rather
+ * than selecting one by import order.
+ *
+ * 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 request-local auth state → 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;
+  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;
+//#endregion
+//#region src/decorators/current-session.decorator.d.ts
+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;
+//#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;
+//#endregion
+//#region src/authz-bridge.d.ts
+/**
+ * A better-auth user carrying the optional `role` field contributed by the
+ * admin plugin. `role` may be a single role, a comma-separated list, or an
+ * array — {@link identityFromUser} normalizes all three.
+ */
+type AuthUser = User & {
+  role?: string | string[] | null;
+};
+/** Stable issuer namespace used for better-auth session principals. */
+declare const BETTER_AUTH_ISSUER = "better-auth";
+/**
+ * Adapts a 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, 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
+ * `{ authorize, statements }`; `statements` is the `{ resource: actions[] }`
+ * grant map for that role — the only accessor {@link betterAuthAcResolver}
+ * reads.
+ */
+interface BetterAuthAcRole {
+  readonly statements: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Flattens a better-auth AC role's `statements` into `resource:action`
+ * permission strings — the granted-side format `@velajs/authz` matches
+ * (wildcards included).
+ */
+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
+ * shape passed to better-auth's admin/organization plugins). An identity's
+ * `roles` are unioned into their granted permission strings; unknown roles
+ * contribute nothing.
+ *
+ * ```ts
+ * const ac = createAccessControl({ posts: ['read', 'write'] });
+ * const authz = createAuthz({
+ *   resolver: betterAuthAcResolver({ editor: ac.newRole({ posts: ['write'] }) }),
+ * });
+ * await authz.can(identityFromUser(user), 'posts:write');
+ * ```
+ */
+declare const betterAuthAcResolver: (roles: Readonly<Record<string, BetterAuthAcRole>>) => PermissionResolver;
+//#endregion
+export { AUTH_ISSUER_KEY, AUTH_PRINCIPAL_TYPE_KEY, AUTH_SESSION_KEY, AUTH_USER_KEY, AuthGuard, type AuthUser, BETTER_AUTH_ISSUER, 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 };
+//# sourceMappingURL=index.d.ts.map