@veloxts/auth 0.6.69 → 0.6.71

package/dist/plugin.d.ts

@@ -1,13 +1,18 @@
 /**
  * VeloxTS Auth Plugin
- * Fastify plugin that integrates authentication with VeloxApp
+ *
+ * Unified authentication using the adapter pattern internally.
+ * This plugin provides a convenient API while using JwtAdapter under the hood.
+ *
  * @module auth/plugin
  */
 import type { Container, VeloxPlugin } from '@veloxts/core';
+import type { AuthAdapterPluginOptions } from './adapter.js';
+import type { JwtAdapterConfig } from './adapters/jwt-adapter.js';
 import { PasswordHasher } from './hash.js';
-import { JwtManager } from './jwt.js';
+import type { JwtManager, TokenStore } from './jwt.js';
 import { authMiddleware } from './middleware.js';
-import type { AuthConfig, AuthContext, TokenPair, User } from './types.js';
+import type { AdapterAuthContext, AuthConfig, TokenPair, User } from './types.js';
 /** Auth package version */
 export declare const AUTH_VERSION: string;
 /**
@@ -59,6 +64,10 @@ export interface AuthService {
      * Password hasher for secure password storage
      */
     hasher: PasswordHasher;
+    /**
+     * Token store for revocation (if configured)
+     */
+    tokenStore?: TokenStore;
     /**
      * Creates a token pair for a user
      */
@@ -66,7 +75,7 @@ export interface AuthService {
     /**
      * Verifies an access token and returns the auth context
      */
-    verifyToken(token: string): AuthContext;
+    verifyToken(token: string): AdapterAuthContext;
     /**
      * Refreshes tokens using a refresh token
      */
@@ -76,6 +85,7 @@ export interface AuthService {
      */
     middleware: ReturnType<typeof authMiddleware>;
 }
+import type { AuthContext } from './types.js';
 declare module 'fastify' {
     interface FastifyInstance {
         auth: AuthService;
@@ -86,7 +96,10 @@ declare module 'fastify' {
     }
 }
 /**
- * Creates the VeloxTS auth plugin (succinct API)
+ * Creates the VeloxTS auth plugin
+ *
+ * **Internally uses the JwtAdapter** for unified architecture.
+ * All authentication in VeloxTS uses the adapter pattern.
  *
  * This plugin provides:
  * - JWT token management (access + refresh tokens)
@@ -142,3 +155,55 @@ export declare function authPlugin(options: AuthPluginOptions): VeloxPlugin<Auth
  * ```
  */
 export declare function defaultAuthPlugin(): VeloxPlugin<AuthPluginOptions>;
+/**
+ * Options for jwtAuth convenience function
+ *
+ * Omits the 'name' field since it's auto-set to 'jwt'.
+ */
+export type JwtAuthOptions = Omit<JwtAdapterConfig, 'name'>;
+/**
+ * Creates JWT auth using the adapter pattern directly
+ *
+ * This is an alternative to `authPlugin` that gives you more control over
+ * adapter-specific features like built-in routes and route prefixes.
+ *
+ * **Note:** Both `authPlugin` and `jwtAuth` now use the adapter pattern internally.
+ * Choose based on your needs:
+ *
+ * **Use `authPlugin` when:**
+ * - You need the `authMiddleware` factory for fine-grained procedure control
+ * - You're using DI container integration
+ * - You want the familiar VeloxTS auth API (`fastify.auth.createTokens()`, etc.)
+ *
+ * **Use `jwtAuth` when:**
+ * - You want built-in `/api/auth/refresh` and `/api/auth/logout` routes
+ * - You're building a pure adapter-based setup
+ * - You want direct access to adapter features
+ *
+ * @param options - JWT adapter configuration
+ * @returns VeloxPlugin ready for registration
+ *
+ * @example
+ * ```typescript
+ * import { jwtAuth } from '@veloxts/auth';
+ *
+ * // With built-in routes
+ * app.use(jwtAuth({
+ *   jwt: {
+ *     secret: process.env.JWT_SECRET!,
+ *     accessTokenExpiry: '15m',
+ *     refreshTokenExpiry: '7d',
+ *   },
+ *   userLoader: async (userId) => {
+ *     return db.user.findUnique({ where: { id: userId } });
+ *   },
+ *   enableRoutes: true, // Mount /api/auth/refresh and /api/auth/logout
+ *   routePrefix: '/api/auth',
+ * }));
+ *
+ * // Access JWT utilities via fastify
+ * const tokens = fastify.jwtManager!.createTokenPair(user);
+ * await fastify.tokenStore!.revoke(tokenId);
+ * ```
+ */
+export declare function jwtAuth(options: JwtAuthOptions): VeloxPlugin<AuthAdapterPluginOptions<JwtAdapterConfig>>;

package/dist/plugin.js

@@ -1,11 +1,16 @@
 /**
  * VeloxTS Auth Plugin
- * Fastify plugin that integrates authentication with VeloxApp
+ *
+ * Unified authentication using the adapter pattern internally.
+ * This plugin provides a convenient API while using JwtAdapter under the hood.
+ *
  * @module auth/plugin
  */
 import { createRequire } from 'node:module';
+import { createAuthAdapterPlugin } from './adapter.js';
+import { createJwtAdapter } from './adapters/jwt-adapter.js';
+import { checkDoubleRegistration, decorateAuth } from './decoration.js';
 import { PasswordHasher } from './hash.js';
-import { JwtManager } from './jwt.js';
 import { authMiddleware } from './middleware.js';
 import { registerAuthProviders } from './providers.js';
 import { AUTH_SERVICE } from './tokens.js';
@@ -18,7 +23,26 @@ export const AUTH_VERSION = packageJson.version ?? '0.0.0-unknown';
 // Auth Plugin
 // ============================================================================
 /**
- * Creates the VeloxTS auth plugin (succinct API)
+ * Wraps isTokenRevoked callback as a TokenStore interface
+ * @internal
+ */
+function createCallbackTokenStore(isTokenRevoked) {
+    return {
+        revoke: () => {
+            // No-op: callback-based stores don't support revocation
+            // Users must implement their own revocation mechanism
+        },
+        isRevoked: isTokenRevoked,
+        clear: () => {
+            // No-op
+        },
+    };
+}
+/**
+ * Creates the VeloxTS auth plugin
+ *
+ * **Internally uses the JwtAdapter** for unified architecture.
+ * All authentication in VeloxTS uses the adapter pattern.
  *
  * This plugin provides:
  * - JWT token management (access + refresh tokens)
@@ -60,43 +84,103 @@ export function authPlugin(options) {
     return {
         name: '@veloxts/auth',
         version: AUTH_VERSION,
-        // No explicit dependencies - works with any Fastify instance
-        // The plugin decorates Fastify with auth functionality
         async register(server, _opts) {
             const config = { ...options, ..._opts };
             const { debug = false, container } = config;
+            // Prevent double-registration of auth systems
+            checkDoubleRegistration(server, 'authPlugin');
             if (debug) {
-                server.log.info('Registering @veloxts/auth plugin');
+                server.log.info('Registering @veloxts/auth plugin (adapter-based)');
             }
-            let authService;
+            // DI-enabled path: Use container for service resolution
             if (container) {
-                // DI-enabled path: Register providers and resolve from container
                 if (debug) {
                     server.log.info('Using DI container for auth services');
                 }
                 registerAuthProviders(container, config);
-                authService = container.resolve(AUTH_SERVICE);
+                const authService = container.resolve(AUTH_SERVICE);
+                server.decorate('auth', authService);
+                // Still need to register the adapter plugin for session loading
+                const { adapter, config: adapterConfig } = createJwtAdapter({
+                    jwt: config.jwt,
+                    userLoader: config.userLoader,
+                    tokenStore: config.isTokenRevoked
+                        ? createCallbackTokenStore(config.isTokenRevoked)
+                        : undefined,
+                    enableRoutes: false, // Don't mount routes when using authPlugin
+                    debug,
+                });
+                // Initialize the adapter for session loading
+                await adapter.initialize(server, adapterConfig);
+                // Decorate requests with auth context
+                decorateAuth(server);
+                // Add preHandler hook for session loading
+                server.addHook('preHandler', async (request) => {
+                    if (config.autoExtract === false)
+                        return;
+                    const session = await adapter.getSession(request);
+                    if (session) {
+                        const user = {
+                            id: session.user.id,
+                            email: session.user.email,
+                            ...(session.user.emailVerified !== undefined && {
+                                emailVerified: session.user.emailVerified,
+                            }),
+                            ...session.user.providerData,
+                        };
+                        const authContext = {
+                            authMode: 'adapter',
+                            isAuthenticated: true,
+                            user,
+                            providerId: 'jwt',
+                            session: session.session.providerData,
+                        };
+                        request.auth = authContext;
+                        request.user = user;
+                    }
+                });
             }
             else {
-                // Legacy path: Direct instantiation (backward compatible)
-                const jwt = new JwtManager(config.jwt);
+                // Adapter-based path: Use JwtAdapter directly
+                // Convert isTokenRevoked callback to TokenStore if provided
+                const tokenStore = config.isTokenRevoked
+                    ? createCallbackTokenStore(config.isTokenRevoked)
+                    : undefined;
+                // Create the JWT adapter
+                const { adapter, config: adapterConfig } = createJwtAdapter({
+                    jwt: config.jwt,
+                    userLoader: config.userLoader,
+                    tokenStore,
+                    enableRoutes: false, // authPlugin manages its own API
+                    debug,
+                });
+                // Initialize adapter
+                await adapter.initialize(server, adapterConfig);
+                // Decorate requests with auth context
+                decorateAuth(server);
+                // Get JWT manager from adapter
+                const jwt = adapter.getJwtManager();
                 const hasher = new PasswordHasher(config.hash);
                 const authMw = authMiddleware(config);
-                authService = {
+                // Build AuthService from adapter
+                const authService = {
                     jwt,
                     hasher,
+                    tokenStore: adapter.getTokenStore(),
                     createTokens(user, additionalClaims) {
                         return jwt.createTokenPair(user, additionalClaims);
                     },
                     verifyToken(token) {
                         const payload = jwt.verifyToken(token);
                         return {
+                            authMode: 'adapter',
                             user: {
                                 id: payload.sub,
                                 email: payload.email,
                             },
-                            token: payload,
                             isAuthenticated: true,
+                            providerId: 'jwt',
+                            session: { token, payload },
                         };
                     },
                     refreshTokens(refreshToken) {
@@ -107,56 +191,33 @@ export function authPlugin(options) {
                     },
                     middleware: authMw,
                 };
-            }
-            // Decorate server with auth service
-            server.decorate('auth', authService);
-            // Decorate requests with auth context (undefined initial value)
-            server.decorateRequest('auth', undefined);
-            server.decorateRequest('user', undefined);
-            // Add preHandler hook to extract auth from headers (optional)
-            if (config.autoExtract !== false) {
-                server.addHook('preHandler', async (request) => {
-                    const authHeader = request.headers.authorization;
-                    const token = authService.jwt.extractFromHeader(authHeader);
-                    if (token) {
-                        try {
-                            const payload = authService.jwt.verifyToken(token);
-                            // Check if token is revoked
-                            if (config.isTokenRevoked && payload.jti) {
-                                const revoked = await config.isTokenRevoked(payload.jti);
-                                if (revoked) {
-                                    // Token revoked - don't set auth context
-                                    return;
-                                }
-                            }
-                            // Load user if loader provided
-                            let user = null;
-                            if (config.userLoader) {
-                                user = await config.userLoader(payload.sub);
-                            }
-                            else {
-                                user = {
-                                    id: payload.sub,
-                                    email: payload.email,
-                                };
-                            }
-                            if (user) {
-                                request.auth = {
-                                    user,
-                                    token: payload,
-                                    isAuthenticated: true,
-                                };
-                                request.user = user;
-                            }
-                        }
-                        catch {
-                            // Invalid token - silently ignore (optional auth)
-                            if (debug) {
-                                server.log.debug('Invalid auth token in request');
-                            }
+                // Decorate server with auth service
+                server.decorate('auth', authService);
+                // Add preHandler hook for session loading (using adapter)
+                if (config.autoExtract !== false) {
+                    server.addHook('preHandler', async (request) => {
+                        const session = await adapter.getSession(request);
+                        if (session) {
+                            const user = {
+                                id: session.user.id,
+                                email: session.user.email,
+                                ...(session.user.emailVerified !== undefined && {
+                                    emailVerified: session.user.emailVerified,
+                                }),
+                                ...session.user.providerData,
+                            };
+                            const authContext = {
+                                authMode: 'adapter',
+                                isAuthenticated: true,
+                                user,
+                                providerId: 'jwt',
+                                session: session.session.providerData,
+                            };
+                            request.auth = authContext;
+                            request.user = user;
                         }
-                    }
-                });
+                    });
+                }
             }
             // Add shutdown hook for cleanup
             server.addHook('onClose', async () => {
@@ -196,3 +257,52 @@ export function defaultAuthPlugin() {
         jwt: { secret },
     });
 }
+/**
+ * Creates JWT auth using the adapter pattern directly
+ *
+ * This is an alternative to `authPlugin` that gives you more control over
+ * adapter-specific features like built-in routes and route prefixes.
+ *
+ * **Note:** Both `authPlugin` and `jwtAuth` now use the adapter pattern internally.
+ * Choose based on your needs:
+ *
+ * **Use `authPlugin` when:**
+ * - You need the `authMiddleware` factory for fine-grained procedure control
+ * - You're using DI container integration
+ * - You want the familiar VeloxTS auth API (`fastify.auth.createTokens()`, etc.)
+ *
+ * **Use `jwtAuth` when:**
+ * - You want built-in `/api/auth/refresh` and `/api/auth/logout` routes
+ * - You're building a pure adapter-based setup
+ * - You want direct access to adapter features
+ *
+ * @param options - JWT adapter configuration
+ * @returns VeloxPlugin ready for registration
+ *
+ * @example
+ * ```typescript
+ * import { jwtAuth } from '@veloxts/auth';
+ *
+ * // With built-in routes
+ * app.use(jwtAuth({
+ *   jwt: {
+ *     secret: process.env.JWT_SECRET!,
+ *     accessTokenExpiry: '15m',
+ *     refreshTokenExpiry: '7d',
+ *   },
+ *   userLoader: async (userId) => {
+ *     return db.user.findUnique({ where: { id: userId } });
+ *   },
+ *   enableRoutes: true, // Mount /api/auth/refresh and /api/auth/logout
+ *   routePrefix: '/api/auth',
+ * }));
+ *
+ * // Access JWT utilities via fastify
+ * const tokens = fastify.jwtManager!.createTokenPair(user);
+ * await fastify.tokenStore!.revoke(tokenId);
+ * ```
+ */
+export function jwtAuth(options) {
+    const { adapter, config } = createJwtAdapter(options);
+    return createAuthAdapterPlugin({ adapter, config });
+}

package/dist/providers.js

@@ -109,12 +109,14 @@ export function authServiceProvider() {
                 verifyToken(token) {
                     const payload = jwt.verifyToken(token);
                     return {
+                        authMode: 'adapter',
                         user: {
                             id: payload.sub,
                             email: payload.email,
                         },
-                        token: payload,
                         isAuthenticated: true,
+                        providerId: 'jwt',
+                        session: { token, payload },
                     };
                 },
                 refreshTokens(refreshToken) {

package/dist/types.d.ts

@@ -24,25 +24,36 @@ export declare class AuthError extends Error {
 /**
  * Base user interface for authenticated requests
  *
- * Applications should extend this via declaration merging:
+ * Applications should extend this via declaration merging to add
+ * custom properties without using index signatures:
+ *
  * @example
  * ```typescript
  * declare module '@veloxts/auth' {
  *   interface User {
- *     roles: ('admin' | 'user')[];
- *     permissions: string[];
+ *     name?: string;
+ *     avatarUrl?: string;
+ *     tenantId?: string;
  *   }
  * }
  * ```
+ *
+ * This approach provides:
+ * - Full type safety (no implicit `unknown` properties)
+ * - Better IDE autocomplete
+ * - Compile-time errors for typos
  */
 export interface User {
+    /** Unique user identifier */
     id: string;
+    /** User email address */
     email: string;
+    /** Whether the user's email has been verified */
+    emailVerified?: boolean;
     /** User roles for authorization */
     roles?: string[];
     /** User permissions for fine-grained access control */
     permissions?: string[];
-    [key: string]: unknown;
 }
 /**
  * Payload stored in JWT tokens
@@ -120,25 +131,6 @@ export interface HashConfig {
     /** argon2 parallelism (default: 4) */
     argon2Parallelism?: number;
 }
-/**
- * Legacy session cookie configuration (used by AuthConfig)
- *
- * @deprecated Use SessionConfig from session.ts for full session management
- */
-export interface LegacySessionConfig {
-    /** Cookie name (default: 'velox.session') */
-    cookieName?: string;
-    /** Session expiration in seconds (default: 86400 = 24h) */
-    maxAge?: number;
-    /** Cookie path (default: '/') */
-    path?: string;
-    /** HTTP only flag (default: true) */
-    httpOnly?: boolean;
-    /** Secure flag - use HTTPS only (default: true in production) */
-    secure?: boolean;
-    /** SameSite policy (default: 'lax') */
-    sameSite?: 'strict' | 'lax' | 'none';
-}
 /**
  * Rate limiting configuration
  */
@@ -162,11 +154,6 @@ export interface AuthConfig {
     jwt: JwtConfig;
     /** Password hashing configuration */
     hash?: HashConfig;
-    /**
-     * Legacy session cookie configuration
-     * @deprecated Use createSessionMiddleware from session.ts for full session management
-     */
-    session?: LegacySessionConfig;
     /** Rate limiting configuration */
     rateLimit?: RateLimitConfig;
     /**
@@ -177,6 +164,7 @@ export interface AuthConfig {
     /**
      * Token blacklist checker - check if token is revoked
      * Called on every authenticated request
+     * @deprecated Use `tokenStore` with TokenStore interface instead
      */
     isTokenRevoked?: (tokenId: string) => Promise<boolean>;
     /**
@@ -234,16 +222,65 @@ export interface AuthMiddlewareOptions {
     guards?: Array<GuardDefinition | string>;
 }
 /**
- * Authenticated request context extension
+ * Base auth context shared by all auth modes
+ */
+export interface BaseAuthContext {
+    /** Whether the request is authenticated */
+    isAuthenticated: boolean;
+}
+/**
+ * Auth context for native JWT authentication (authPlugin)
+ *
+ * This context is set when using the built-in authPlugin with JWT tokens.
+ * Provides access to the decoded token payload.
  */
-export interface AuthContext {
+export interface NativeAuthContext extends BaseAuthContext {
+    /** Discriminant for native JWT auth mode */
+    authMode: 'native';
     /** Authenticated user (undefined if optional auth and no token) */
     user?: User;
+    /** Raw JWT token string (if extracted from request) */
+    token?: string;
     /** Decoded token payload */
-    token?: TokenPayload;
-    /** Check if user is authenticated */
-    isAuthenticated: boolean;
+    payload?: TokenPayload;
 }
+/**
+ * Auth context for external authentication adapters
+ *
+ * This context is set when using an AuthAdapter (BetterAuth, Clerk, Auth0, etc.).
+ * Provides access to the provider's session data.
+ */
+export interface AdapterAuthContext extends BaseAuthContext {
+    /** Discriminant for adapter auth mode */
+    authMode: 'adapter';
+    /** Authenticated user (undefined if not authenticated) */
+    user?: User;
+    /** Provider identifier (e.g., 'better-auth', 'clerk', 'auth0') */
+    providerId: string;
+    /** Provider-specific session data */
+    session?: unknown;
+}
+/**
+ * Authenticated request context extension
+ *
+ * This is a discriminated union based on `authMode`:
+ * - `'native'`: Built-in JWT authentication via authPlugin
+ * - `'adapter'`: External provider via AuthAdapter
+ *
+ * Use the `authMode` discriminant for type-safe access to mode-specific properties:
+ *
+ * @example
+ * ```typescript
+ * if (ctx.auth?.authMode === 'native') {
+ *   // Access JWT-specific properties
+ *   console.log(ctx.auth.payload?.sub);
+ * } else if (ctx.auth?.authMode === 'adapter') {
+ *   // Access adapter-specific properties
+ *   console.log(ctx.auth.providerId);
+ * }
+ * ```
+ */
+export type AuthContext = NativeAuthContext | AdapterAuthContext;
 declare module '@veloxts/core' {
     interface BaseContext {
         /** Auth context - available when auth middleware is used */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/auth",
-  "version": "0.6.69",
+  "version": "0.6.71",
   "description": "Authentication and authorization system for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -57,8 +57,8 @@
   "dependencies": {
     "@fastify/cookie": "11.0.2",
     "fastify": "5.6.2",
-    "@veloxts/core": "0.6.69",
-    "@veloxts/router": "0.6.69"
+    "@veloxts/core": "0.6.71",
+    "@veloxts/router": "0.6.71"
   },
   "peerDependencies": {
     "argon2": ">=0.30.0",
@@ -82,8 +82,8 @@
     "fastify-plugin": "5.1.0",
     "typescript": "5.9.3",
     "vitest": "4.0.16",
-    "@veloxts/testing": "0.6.69",
-    "@veloxts/validation": "0.6.69"
+    "@veloxts/testing": "0.6.71",
+    "@veloxts/validation": "0.6.71"
   },
   "keywords": [
     "velox",