@velajs/better-auth 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,10 +1,15 @@
 # Changelog
 
+## 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/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,270 @@
-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;
+  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}.
+ *
+ * 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;
+  defaultPolicy?: 'deny' | 'allow';
+  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;
+//#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 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;
+  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;
+};
+/**
+ * Adapts a better-auth user into a `@velajs/authz` {@link Identity}. Maps
+ * `user.id` → `userId` and the admin-plugin `role` field → `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;
+/**
+ * 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_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 };
+//# sourceMappingURL=index.d.ts.map