@velajs/better-auth 0.3.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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.module.d.ts

@@ -3,22 +3,17 @@ import type { BetterAuthInstance, BetterAuthModuleOptions } from './better-auth.
 /**
  * Options for {@link BetterAuthModule.forRootAsync}.
  *
- * The `Inject` type parameter captures the literal `inject` tuple at the
- * call site (via `const` inference on the consuming generic) so
- * `useFactory` parameters are typed from the inject array, position-by-position.
- * No `as const`, no `(...deps: any[])` workaround:
+ * 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
+ *   useFactory: (d1, config) =>            // d1: D1Service, config: ConfigService
  *     betterAuth({ database: drizzleAdapter(drizzle(d1.database), ...) }),
  * });
  * ```
- *
- * When `inject` isn't a literal tuple (or is omitted), `Inject` falls back
- * to `readonly Token<unknown>[]` and `useFactory` accepts variadic
- * `unknown[]` — the historical loose-typing behavior.
  */
 interface ForRootAsyncOptions<Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]> {
     inject?: Inject;
@@ -32,26 +27,25 @@ interface ForRootAsyncOptions<Inject extends readonly Token<unknown>[] = readonl
 }
 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 `betterAuth({...})` are available at startup (Node apps with
-     * a static DB connection, in-memory adapters, etc.).
+     * 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): DynamicModule;
+    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 as a closure inside the builder
-     * 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 are resolved at module load (cheap; e.g. D1Service is a
-     * thin BindingRef wrapper). Their *values* are read at first auth use,
-     * inside your factory body — `(d1: D1Service) => betterAuth({ database:
-     * drizzleAdapter(drizzle(d1.database), ...) })`.
+     * 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;
 }

package/dist/better-auth.module.js

@@ -1,144 +1,138 @@
-import { APP_GUARD, stableHash } from "@velajs/vela";
+import { defineModule, lazyProvider, provideGlobal, stableHash } from "@velajs/vela";
 import { createBetterAuthCatchallController } from "./better-auth.controller.js";
 import { BetterAuthService, BETTER_AUTH_BUILDER } from "./better-auth.service.js";
 import { BETTER_AUTH_OPTIONS } from "./better-auth.tokens.js";
 import { AuthGuard } from "./guards/auth.guard.js";
 import { RolesGuard } from "./guards/roles.guard.js";
 const DEFAULT_BASE_PATH = '/api/auth';
+function normalize(options) {
+    return {
+        basePath: options.basePath ?? DEFAULT_BASE_PATH,
+        isGlobal: options.isGlobal ?? false,
+        defaultPolicy: options.defaultPolicy ?? 'deny',
+        mountHandler: options.mountHandler ?? true
+    };
+}
+/** Providers, controllers, and exports shared by both entry points. */ function commonContributions(n) {
+    return {
+        providers: [
+            BetterAuthService,
+            AuthGuard,
+            RolesGuard
+        ],
+        controllers: n.mountHandler ? [
+            createBetterAuthCatchallController(n.basePath)
+        ] : [],
+        exports: [
+            BetterAuthService,
+            BETTER_AUTH_OPTIONS,
+            AuthGuard,
+            RolesGuard
+        ]
+    };
+}
+/**
+ * The blessed engine generates `forRoot`. `setup` runs once per instance at
+ * call time: it re-provides {@link BETTER_AUTH_OPTIONS} with defaults applied,
+ * derives the auth builder from those options, mounts the catch-all controller,
+ * and — via the `global:` slot — registers the app-wide guard when `isGlobal`.
+ *
+ * `isGlobal` here means "apply AuthGuard app-wide", NOT "make this a global
+ * module", so the default `isGlobal → global: true` extras transform is
+ * replaced with identity; the flag reaches `setup` through the options bag.
+ */ const authModuleHost = defineModule({
+    name: 'BetterAuth',
+    optionsToken: BETTER_AUTH_OPTIONS,
+    transform: (definition)=>definition,
+    // The auth instance is a stateful value — key off the structural subset only.
+    key: (options)=>stableHash(normalize(options)),
+    setup: ({ OPTIONS, options })=>{
+        const n = normalize(options);
+        const common = commonContributions(n);
+        const auth = options.auth;
+        return {
+            providers: [
+                // Override the auto-provided raw bag with the normalized shape so
+                // BETTER_AUTH_OPTIONS consumers always see defaults + the auth instance.
+                {
+                    provide: OPTIONS,
+                    useValue: {
+                        ...n,
+                        auth
+                    }
+                },
+                // Eager auth: the builder hands back the instance the caller passed in.
+                lazyProvider({
+                    provide: BETTER_AUTH_BUILDER,
+                    inject: [
+                        OPTIONS
+                    ],
+                    useFactory: (o)=>o.auth
+                }),
+                ...common.providers
+            ],
+            controllers: common.controllers,
+            exports: common.exports,
+            global: n.isGlobal ? {
+                guards: [
+                    AuthGuard
+                ]
+            } : undefined
+        };
+    }
+});
 export 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.).
+   * 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) {
-        const normalized = normalize(options);
-        const providers = buildProviders(normalized, ()=>options.auth);
+        // Delegate to the generated static, then rebrand the module identity so the
+        // public `BetterAuthModule` class is the one registered (consistent with
+        // `forRootAsync` and better diagnostics).
         return {
-            module: BetterAuthModule,
-            key: stableHash({
-                basePath: normalized.basePath,
-                defaultPolicy: normalized.defaultPolicy,
-                isGlobal: !!options.isGlobal,
-                mountHandler: !!normalized.mountHandler
-            }),
-            providers,
-            controllers: normalized.mountHandler ? [
-                createBetterAuthCatchallController(normalized.basePath)
-            ] : [],
-            exports: [
-                BetterAuthService,
-                BETTER_AUTH_OPTIONS,
-                AuthGuard,
-                RolesGuard
-            ]
+            ...authModuleHost.ConfigurableModuleClass.forRoot(options),
+            module: BetterAuthModule
         };
     }
     /**
-   * 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 as a closure inside the builder
-   * 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 are resolved at module load (cheap; e.g. D1Service is a
-   * thin BindingRef wrapper). Their *values* are read at first auth use,
-   * inside your factory body — `(d1: D1Service) => betterAuth({ database:
-   * drizzleAdapter(drizzle(d1.database), ...) })`.
+   * 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(options) {
-        const mountHandler = options.mountHandler !== false;
-        const isGlobal = options.isGlobal === true;
-        const basePath = options.basePath ?? DEFAULT_BASE_PATH;
-        const defaultPolicy = options.defaultPolicy ?? 'deny';
-        const providers = [
-            {
-                provide: BETTER_AUTH_OPTIONS,
-                useValue: {
-                    basePath,
-                    defaultPolicy,
-                    isGlobal,
-                    mountHandler
-                }
-            },
-            {
-                // The builder is a zero-arg closure capturing the DI'd deps. It is
-                // invoked lazily by BetterAuthService.auth on first access; vela
-                // can resolve this provider at module load without running the user
-                // factory — the factory body lives behind the closure.
-                //
-                // The inner factory is typed `unknown[]` (vela's runtime contract:
-                // deps are resolved by token order). The outer user-facing
-                // `options.useFactory` is statically typed via `InferTokens<Inject>`.
-                // We narrow at the boundary with a single cast — runtime order
-                // matches the declared `inject` order by construction.
-                provide: BETTER_AUTH_BUILDER,
-                useFactory: (...deps)=>()=>options.useFactory(...deps),
-                inject: options.inject ?? []
-            },
-            BetterAuthService,
-            AuthGuard,
-            RolesGuard
-        ];
-        if (isGlobal) {
-            providers.push({
-                provide: APP_GUARD,
-                useExisting: AuthGuard
-            });
-        }
+        const n = normalize(options);
+        const common = commonContributions(n);
         return {
             module: BetterAuthModule,
             key: options.key ?? stableHash({
-                inject: options.inject,
-                isGlobal,
-                mountHandler,
-                basePath,
-                defaultPolicy
+                ...n,
+                inject: options.inject
             }),
             imports: options.imports ?? [],
-            providers,
-            controllers: mountHandler ? [
-                createBetterAuthCatchallController(basePath)
-            ] : [],
-            exports: [
-                BetterAuthService,
-                BETTER_AUTH_OPTIONS,
-                AuthGuard,
-                RolesGuard
-            ]
+            providers: [
+                {
+                    provide: BETTER_AUTH_OPTIONS,
+                    useValue: n
+                },
+                // The deferred auth builder: `lazyProvider` wraps the user factory in a
+                // memoized thunk, replacing the hand-rolled `(...deps) => () => f(...deps)`.
+                lazyProvider({
+                    provide: BETTER_AUTH_BUILDER,
+                    inject: options.inject,
+                    useFactory: options.useFactory
+                }),
+                ...common.providers,
+                ...n.isGlobal ? provideGlobal('guard', AuthGuard) : []
+            ],
+            controllers: common.controllers,
+            exports: common.exports
         };
     }
 }
-function normalize(options) {
-    return {
-        auth: options.auth,
-        basePath: options.basePath ?? DEFAULT_BASE_PATH,
-        isGlobal: options.isGlobal ?? false,
-        defaultPolicy: options.defaultPolicy ?? 'deny',
-        mountHandler: options.mountHandler ?? true
-    };
-}
-function buildProviders(normalized, builder) {
-    const providers = [
-        {
-            provide: BETTER_AUTH_OPTIONS,
-            useValue: normalized
-        },
-        {
-            provide: BETTER_AUTH_BUILDER,
-            useValue: builder
-        },
-        BetterAuthService,
-        AuthGuard,
-        RolesGuard
-    ];
-    if (normalized.isGlobal) {
-        providers.push({
-            provide: APP_GUARD,
-            useExisting: AuthGuard
-        });
-    }
-    return providers;
-}

package/dist/testing/acting-as.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The slice of `@velajs/testing`'s `TestingModule` this resolver depends on.
+ * Declared structurally so `@velajs/better-auth/testing` carries NO runtime
+ * (or type) dependency on `@velajs/testing` — a real `TestingModule` satisfies
+ * it, and the resolver stays assignable to `@velajs/testing`'s `ActingAsResolver`.
+ */
+export interface TestModuleLike {
+    get<T>(token: unknown): T;
+}
+/**
+ * A test principal. Opaque `Record<string, unknown>` to stay compatible with
+ * `@velajs/testing`'s `TestPrincipal`. Recognized fields:
+ *
+ * - `id`    — reuse the user with this id if it already exists.
+ * - `email` — reuse the user with this email, else create one.
+ * - `name`  — display name for a created user (defaults to the email).
+ *
+ * Any other fields are forwarded to `internalAdapter.createUser` (e.g. `role`)
+ * when a new user is minted, so role-guarded routes can be exercised.
+ */
+export type ActingAsPrincipal = Record<string, unknown>;
+/**
+ * actingAs — a `@velajs/testing` auth resolver for better-auth.
+ *
+ * Resolves {@link BetterAuthService} from the module, mints a REAL better-auth
+ * session for `principal` through `auth.$context.internalAdapter`, and returns
+ * a `Headers` carrying a properly signed session cookie. Guarded routes
+ * (`AuthGuard`) then accept requests carrying those headers because
+ * `auth.api.getSession` validates the cookie against the same session store.
+ *
+ * The signature `(module, principal) => Promise<Headers>` is exactly
+ * `@velajs/testing`'s `ActingAsResolver`, so it plugs straight in:
+ *
+ * @example
+ * ```ts
+ * import { actingAs } from '@velajs/better-auth/testing';
+ *
+ * // As the default resolver for the module:
+ * module.setAuthResolver(actingAs);
+ * await module.http.get('/me').actingAs({ email: 'ada@example.com' }).send();
+ *
+ * // Or passed per-request:
+ * await module.http.get('/me').actingAs({ id: existingUserId }, actingAs).send();
+ * ```
+ */
+export declare function actingAs(module: TestModuleLike, principal: ActingAsPrincipal): Promise<Headers>;

package/dist/testing/acting-as.js

@@ -0,0 +1,70 @@
+// Mechanics adapted from @stratal/testing (MIT, © Temitayo Fadojutimi):
+// mint a real better-auth session via `$context.internalAdapter` and hand back
+// a signed session-cookie header. Adapted to better-auth >=1.6: the session
+// cookie is signed with the package's own `makeSignature` (better-auth/crypto)
+// — the same primitive better-auth's built-in test cookie builder uses — so no
+// endpoint-context shim or `setSessionCookie` mock is needed.
+import { makeSignature } from "better-auth/crypto";
+import { BetterAuthService } from "../better-auth.service.js";
+/**
+ * actingAs — a `@velajs/testing` auth resolver for better-auth.
+ *
+ * Resolves {@link BetterAuthService} from the module, mints a REAL better-auth
+ * session for `principal` through `auth.$context.internalAdapter`, and returns
+ * a `Headers` carrying a properly signed session cookie. Guarded routes
+ * (`AuthGuard`) then accept requests carrying those headers because
+ * `auth.api.getSession` validates the cookie against the same session store.
+ *
+ * The signature `(module, principal) => Promise<Headers>` is exactly
+ * `@velajs/testing`'s `ActingAsResolver`, so it plugs straight in:
+ *
+ * @example
+ * ```ts
+ * import { actingAs } from '@velajs/better-auth/testing';
+ *
+ * // As the default resolver for the module:
+ * module.setAuthResolver(actingAs);
+ * await module.http.get('/me').actingAs({ email: 'ada@example.com' }).send();
+ *
+ * // Or passed per-request:
+ * await module.http.get('/me').actingAs({ id: existingUserId }, actingAs).send();
+ * ```
+ */ export async function actingAs(module, principal) {
+    const auth = module.get(BetterAuthService).auth;
+    const ctx = await auth.$context;
+    const internalAdapter = ctx.internalAdapter;
+    const id = typeof principal.id === 'string' ? principal.id : undefined;
+    const email = typeof principal.email === 'string' ? principal.email : undefined;
+    const name = typeof principal.name === 'string' ? principal.name : undefined;
+    // `findUserById`/`createUser` yield a bare user; `findUserByEmail` nests it
+    // under `{ user, accounts }` — normalize to the id we need.
+    let user = null;
+    if (id) user = await internalAdapter.findUserById(id);
+    if (!user && email) {
+        const found = await internalAdapter.findUserByEmail(email);
+        user = found?.user ?? null;
+    }
+    if (!user) {
+        if (!email) {
+            throw new Error('actingAs: principal must carry an `email` (to create a user) or an ' + '`id` matching an existing user.');
+        }
+        const { id: _id, email: _email, name: _name, ...extra } = principal;
+        user = await internalAdapter.createUser({
+            ...extra,
+            email,
+            name: name ?? email,
+            ...id ? {
+                id
+            } : {}
+        });
+    }
+    const session = await internalAdapter.createSession(user.id, false, {
+        ipAddress: '127.0.0.1',
+        userAgent: 'vela-test'
+    });
+    const cookieName = ctx.authCookies.sessionToken.name;
+    const signedToken = `${session.token}.${await makeSignature(session.token, ctx.secret)}`;
+    const headers = new Headers();
+    headers.set('Cookie', `${cookieName}=${signedToken}`);
+    return headers;
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export { actingAs } from './acting-as';
+export type { ActingAsPrincipal, TestModuleLike } from './acting-as';

package/dist/testing/index.js

@@ -0,0 +1,3 @@
+// `@velajs/better-auth/testing` — test-only helpers. Kept in a separate subpath
+// so nothing here is pulled into the runtime surface of `@velajs/better-auth`.
+export { actingAs } from "./acting-as.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/better-auth",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "better-auth integration for the Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
     }
   },
   "files": [
@@ -17,13 +21,6 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
-  "scripts": {
-    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "prepare": "swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
-    "prepublishOnly": "pnpm run typecheck && pnpm test"
-  },
   "sideEffects": false,
   "keywords": [
     "vela",
@@ -49,26 +46,24 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@velajs/vela": ">=1.8.2",
+    "@velajs/vela": ">=1.11.0",
     "better-auth": ">=1.2.0",
     "hono": ">=4"
   },
   "devDependencies": {
     "@swc/cli": "^0.8.1",
     "@swc/core": "^1.15.41",
-    "@velajs/testing": "^0.2.1",
-    "@velajs/vela": "^1.8.5",
+    "@velajs/testing": "^0.4.0",
+    "@velajs/vela": "^1.12.0",
     "better-auth": "^1.6.20",
     "hono": "^4.12.26",
     "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.1.9"
   },
-  "packageManager": "pnpm@10.20.0",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "@swc/core",
-      "esbuild"
-    ]
+  "scripts": {
+    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}