@veloxts/auth 0.6.68 → 0.6.70

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @veloxts/auth
 
+## 0.6.70
+
+### Patch Changes
+
+- ### feat(auth): Unified Adapter-Only Architecture
+
+  **New Features:**
+
+  - Add `JwtAdapter` implementing the `AuthAdapter` interface for unified JWT authentication
+  - Add `jwtAuth()` convenience function for direct adapter usage with optional built-in routes (`/api/auth/refresh`, `/api/auth/logout`)
+  - Add `AuthContext` discriminated union (`NativeAuthContext | AdapterAuthContext`) for type-safe auth mode handling
+  - Add double-registration protection to prevent conflicting auth system setups
+  - Add shared decoration utilities (`decorateAuth`, `setRequestAuth`, `checkDoubleRegistration`)
+
+  **Architecture Changes:**
+
+  - `authPlugin` now uses `JwtAdapter` internally - all authentication flows through the adapter pattern
+  - Single code path for authentication (no more dual native/adapter modes)
+  - `authContext.authMode` is now always `'adapter'` with `providerId='jwt'` when using `authPlugin`
+
+  **Breaking Changes:**
+
+  - Remove deprecated `LegacySessionConfig` interface (use `sessionMiddleware` instead)
+  - Remove deprecated `session` field from `AuthConfig`
+  - `User` interface no longer has index signature (extend via declaration merging)
+
+  **Type Safety Improvements:**
+
+  - `AuthContext` discriminated union enables exhaustive type narrowing based on `authMode`
+  - Export `NativeAuthContext` and `AdapterAuthContext` types for explicit typing
+
+  **Migration:**
+
+  - Existing `authPlugin` usage remains backward-compatible
+  - If checking `authContext.token`, use `authContext.session` instead (token stored in session for adapter mode)
+
+- Updated dependencies
+  - @veloxts/core@0.6.70
+  - @veloxts/router@0.6.70
+
+## 0.6.69
+
+### Patch Changes
+
+- implement user feedback improvements across packages
+
+  ## Summary
+
+  Addresses 9 user feedback items to improve DX, reduce boilerplate, and eliminate template duplications.
+
+  ### Phase 1: Validation Helpers (`@veloxts/validation`)
+
+  - Add `prismaDecimal()`, `prismaDecimalNullable()`, `prismaDecimalOptional()` for Prisma Decimal → number conversion
+  - Add `dateToIso`, `dateToIsoNullable`, `dateToIsoOptional` aliases for consistency
+
+  ### Phase 2: Template Deduplication (`@veloxts/auth`)
+
+  - Export `createEnhancedTokenStore()` with token revocation and refresh token reuse detection
+  - Export `parseUserRoles()` and `DEFAULT_ALLOWED_ROLES`
+  - Fix memory leak: track pending timeouts for proper cleanup on `destroy()`
+  - Update templates to import from `@veloxts/auth` instead of duplicating code
+  - Fix jwtManager singleton pattern in templates
+
+  ### Phase 3: Router Helpers (`@veloxts/router`)
+
+  - Add `createRouter()` returning `{ collections, router }` for DRY setup
+  - Add `toRouter()` for router-only use cases
+  - Update all router templates to use `createRouter()`
+
+  ### Phase 4: Guard Type Narrowing - Experimental (`@veloxts/auth`, `@veloxts/router`)
+
+  - Add `NarrowingGuard` interface with phantom `_narrows` type
+  - Add `authenticatedNarrow` and `hasRoleNarrow()` guards
+  - Add `guardNarrow()` method to `ProcedureBuilder` for context narrowing
+  - Enables `ctx.user` to be non-null after guard passes
+
+  ### Phase 5: Documentation (`@veloxts/router`)
+
+  - Document `.rest()` override patterns
+  - Document `createRouter()` helper usage
+  - Document `guardNarrow()` experimental API
+  - Add schema browser-safety patterns for RSC apps
+
+- Updated dependencies
+  - @veloxts/core@0.6.69
+  - @veloxts/router@0.6.69
+
 ## 0.6.68
 
 ### Patch Changes

package/dist/adapter.d.ts

@@ -551,9 +551,15 @@ export interface AdapterMiddlewareOptions {
     optional?: boolean;
 }
 /**
- * Context extension for adapter-based authentication
+ * Context extension for adapter-based authentication middleware
+ *
+ * This interface extends the procedure context with auth-related properties
+ * when using `createAdapterAuthMiddleware()`.
+ *
+ * Note: This is different from `AdapterAuthContext` in types.ts, which represents
+ * the discriminated union variant for adapter-based authentication on requests.
  */
-export interface AdapterAuthContext {
+export interface AdapterMiddlewareContext {
     /** Authenticated user (undefined if optional and not authenticated) */
     user?: User;
     /** Whether the request is authenticated */
@@ -590,7 +596,7 @@ export interface AdapterAuthContext {
  * ```
  */
 export declare function createAdapterAuthMiddleware(): {
-    middleware: <TInput, TContext extends BaseContext, TOutput>(options?: AdapterMiddlewareOptions) => MiddlewareFunction<TInput, TContext, TContext & AdapterAuthContext, TOutput>;
+    middleware: <TInput, TContext extends BaseContext, TOutput>(options?: AdapterMiddlewareOptions) => MiddlewareFunction<TInput, TContext, TContext & AdapterMiddlewareContext, TOutput>;
     requireAuth: <TInput, TContext extends BaseContext, TOutput>() => MiddlewareFunction<TInput, TContext, TContext & {
         user: User;
         isAuthenticated: true;
@@ -699,7 +705,7 @@ export declare abstract class BaseAuthAdapter<TConfig extends AuthAdapterConfig
      */
     protected debug(message: string): void;
     /**
-     * Log an info message
+     * Log an info message (if debug is enabled)
      */
     protected info(message: string): void;
     /**

package/dist/adapter.js

@@ -26,6 +26,7 @@
  * app.use(authPlugin);
  * ```
  */
+import { checkDoubleRegistration, decorateAuth, setRequestAuth } from './decoration.js';
 import { AuthError } from './types.js';
 /**
  * Authentication adapter error
@@ -216,6 +217,8 @@ export function createAuthAdapterPlugin(options) {
         dependencies: ['@veloxts/core'],
         async register(server, _opts) {
             const mergedConfig = { ...config, ..._opts.config };
+            // Prevent double-registration of auth systems
+            checkDoubleRegistration(server, `adapter:${adapter.name}`);
             if (debug) {
                 server.log.info(`Registering auth adapter: ${adapter.name}`);
             }
@@ -232,8 +235,7 @@ export function createAuthAdapterPlugin(options) {
                 throw adapterError;
             }
             // Decorate requests with auth context
-            server.decorateRequest('auth', undefined);
-            server.decorateRequest('user', undefined);
+            decorateAuth(server);
             // Mount adapter routes
             const routes = adapter.getRoutes();
             for (const route of routes) {
@@ -313,15 +315,15 @@ export function createAuthAdapterPlugin(options) {
                         catch (error) {
                             throw new AuthAdapterError('Failed to transform user', 500, 'ADAPTER_USER_TRANSFORM_ERROR', error instanceof Error ? error : undefined);
                         }
-                        // Set auth context on request
+                        // Set auth context on request using AdapterAuthContext
                         const authContext = {
+                            authMode: 'adapter',
                             user,
                             isAuthenticated: true,
-                            // Token payload is not available from adapters
-                            // (they use sessions, not JWTs internally)
+                            providerId: adapter.name,
+                            session: sessionResult.session.providerData,
                         };
-                        request.auth = authContext;
-                        request.user = user;
+                        setRequestAuth(request, authContext, user);
                     }
                 }
                 catch (error) {
@@ -404,9 +406,13 @@ export function createAdapterAuthMiddleware() {
             if (!user || !auth?.isAuthenticated) {
                 if (options.optional) {
                     // Optional auth - continue without user
+                    // Create a minimal adapter auth context for unauthenticated state
                     const authContext = {
+                        authMode: 'adapter',
                         user: undefined,
                         isAuthenticated: false,
+                        providerId: 'unknown',
+                        session: undefined,
                     };
                     return next({
                         ctx: {
@@ -559,10 +565,10 @@ export class BaseAuthAdapter {
         }
     }
     /**
-     * Log an info message
+     * Log an info message (if debug is enabled)
      */
     info(message) {
-        if (this.fastify) {
+        if (this.config?.debug && this.fastify) {
             this.fastify.log.info(`[${this.name}] ${message}`);
         }
     }

package/dist/adapters/index.d.ts

@@ -1,13 +1,31 @@
 /**
- * Auth Adapters - External authentication provider integrations
+ * Auth Adapters - Authentication provider integrations
  *
- * This module exports adapters for integrating external authentication
- * providers with VeloxTS. Each adapter implements the AuthAdapter interface
- * and can be used with createAuthAdapterPlugin.
+ * This module exports adapters for integrating authentication providers
+ * with VeloxTS. Each adapter implements the AuthAdapter interface and
+ * can be used with createAuthAdapterPlugin.
+ *
+ * Available adapters:
+ * - **JwtAdapter** - Built-in JWT authentication using the adapter pattern
+ * - **BetterAuthAdapter** - Integration with BetterAuth library
  *
  * @module auth/adapters
  *
- * @example
+ * @example JWT Adapter
+ * ```typescript
+ * import { createJwtAdapter } from '@veloxts/auth/adapters';
+ * import { createAuthAdapterPlugin } from '@veloxts/auth';
+ *
+ * const { adapter, config } = createJwtAdapter({
+ *   jwt: { secret: process.env.JWT_SECRET! },
+ *   userLoader: async (userId) => db.user.findUnique({ where: { id: userId } }),
+ * });
+ *
+ * const plugin = createAuthAdapterPlugin({ adapter, config });
+ * app.use(plugin);
+ * ```
+ *
+ * @example BetterAuth Adapter
  * ```typescript
  * import { createBetterAuthAdapter } from '@veloxts/auth/adapters';
  * import { createAuthAdapterPlugin } from '@veloxts/auth';
@@ -23,5 +41,7 @@
  * });
  * ```
  */
+export type { JwtAdapterConfig } from './jwt-adapter.js';
+export { AuthAdapterError, createJwtAdapter, JwtAdapter } from './jwt-adapter.js';
 export type { BetterAuthAdapterConfig, BetterAuthApi, BetterAuthHandler, BetterAuthInstance, BetterAuthSession, BetterAuthSessionResult, BetterAuthUser, } from './better-auth.js';
-export { AuthAdapterError, BetterAuthAdapter, createBetterAuthAdapter, } from './better-auth.js';
+export { BetterAuthAdapter, createBetterAuthAdapter } from './better-auth.js';

package/dist/adapters/index.js

@@ -1,13 +1,31 @@
 /**
- * Auth Adapters - External authentication provider integrations
+ * Auth Adapters - Authentication provider integrations
  *
- * This module exports adapters for integrating external authentication
- * providers with VeloxTS. Each adapter implements the AuthAdapter interface
- * and can be used with createAuthAdapterPlugin.
+ * This module exports adapters for integrating authentication providers
+ * with VeloxTS. Each adapter implements the AuthAdapter interface and
+ * can be used with createAuthAdapterPlugin.
+ *
+ * Available adapters:
+ * - **JwtAdapter** - Built-in JWT authentication using the adapter pattern
+ * - **BetterAuthAdapter** - Integration with BetterAuth library
  *
  * @module auth/adapters
  *
- * @example
+ * @example JWT Adapter
+ * ```typescript
+ * import { createJwtAdapter } from '@veloxts/auth/adapters';
+ * import { createAuthAdapterPlugin } from '@veloxts/auth';
+ *
+ * const { adapter, config } = createJwtAdapter({
+ *   jwt: { secret: process.env.JWT_SECRET! },
+ *   userLoader: async (userId) => db.user.findUnique({ where: { id: userId } }),
+ * });
+ *
+ * const plugin = createAuthAdapterPlugin({ adapter, config });
+ * app.use(plugin);
+ * ```
+ *
+ * @example BetterAuth Adapter
  * ```typescript
  * import { createBetterAuthAdapter } from '@veloxts/auth/adapters';
  * import { createAuthAdapterPlugin } from '@veloxts/auth';
@@ -23,5 +41,5 @@
  * });
  * ```
  */
-// BetterAuth Adapter
-export { AuthAdapterError, BetterAuthAdapter, createBetterAuthAdapter, } from './better-auth.js';
+export { AuthAdapterError, createJwtAdapter, JwtAdapter } from './jwt-adapter.js';
+export { BetterAuthAdapter, createBetterAuthAdapter } from './better-auth.js';

package/dist/adapters/jwt-adapter.d.ts

@@ -0,0 +1,261 @@
+/**
+ * JWT Authentication Adapter for @veloxts/auth
+ *
+ * Implements the AuthAdapter interface using JWT tokens.
+ * This allows JWT auth to follow the same pattern as external providers,
+ * enabling easy swapping between authentication strategies.
+ *
+ * @module auth/adapters/jwt-adapter
+ *
+ * @example
+ * ```typescript
+ * import { createAuthAdapterPlugin } from '@veloxts/auth';
+ * import { createJwtAdapter, jwtAuth } from '@veloxts/auth/adapters/jwt-adapter';
+ *
+ * // Option 1: Using createJwtAdapter + createAuthAdapterPlugin
+ * const { adapter, config } = createJwtAdapter({
+ *   jwt: {
+ *     secret: process.env.JWT_SECRET!,
+ *     accessTokenExpiry: '15m',
+ *     refreshTokenExpiry: '7d',
+ *   },
+ *   userLoader: async (userId) => db.user.findUnique({ where: { id: userId } }),
+ * });
+ *
+ * const authPlugin = createAuthAdapterPlugin({ adapter, config });
+ * app.use(authPlugin);
+ *
+ * // Option 2: Using jwtAuth convenience function (recommended)
+ * import { jwtAuth } from '@veloxts/auth';
+ *
+ * app.use(jwtAuth({
+ *   jwt: {
+ *     secret: process.env.JWT_SECRET!,
+ *     accessTokenExpiry: '15m',
+ *     refreshTokenExpiry: '7d',
+ *   },
+ *   userLoader: async (userId) => db.user.findUnique({ where: { id: userId } }),
+ * }));
+ * ```
+ */
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import type { AdapterRoute, AdapterSessionResult, AuthAdapterConfig } from '../adapter.js';
+import { BaseAuthAdapter } from '../adapter.js';
+import type { TokenStore } from '../jwt.js';
+import { JwtManager } from '../jwt.js';
+import type { JwtConfig, TokenPair, User } from '../types.js';
+/**
+ * JWT adapter configuration
+ *
+ * Extends the base AuthAdapterConfig with JWT-specific options.
+ *
+ * @example
+ * ```typescript
+ * const config: JwtAdapterConfig = {
+ *   name: 'jwt',
+ *   jwt: {
+ *     secret: process.env.JWT_SECRET!,
+ *     accessTokenExpiry: '15m',
+ *     refreshTokenExpiry: '7d',
+ *   },
+ *   userLoader: async (userId) => db.user.findUnique({ where: { id: userId } }),
+ *   enableRoutes: true,
+ *   routePrefix: '/api/auth',
+ * };
+ * ```
+ */
+export interface JwtAdapterConfig extends AuthAdapterConfig {
+    /**
+     * JWT configuration (secret, expiry, etc.)
+     *
+     * This is passed directly to JwtManager.
+     */
+    jwt: JwtConfig;
+    /**
+     * Token store for revocation tracking
+     *
+     * Used to check if tokens have been revoked (e.g., on logout).
+     * Defaults to in-memory store (not suitable for production).
+     *
+     * For production, use Redis or database-backed storage.
+     */
+    tokenStore?: TokenStore;
+    /**
+     * Load user by ID
+     *
+     * Called when verifying tokens to load the full user object.
+     * If not provided, a minimal user object is created from token claims.
+     *
+     * @param userId - The user ID from the token's `sub` claim
+     * @returns The user object or null if not found
+     */
+    userLoader?: (userId: string) => Promise<User | null>;
+    /**
+     * Enable built-in auth routes
+     *
+     * When true, mounts routes for token refresh and logout:
+     * - POST `${routePrefix}/refresh` - Refresh access token
+     * - POST `${routePrefix}/logout` - Revoke current token
+     *
+     * @default true
+     */
+    enableRoutes?: boolean;
+    /**
+     * Base path for auth routes
+     *
+     * Only used when `enableRoutes` is true.
+     *
+     * @default '/api/auth'
+     */
+    routePrefix?: string;
+}
+/**
+ * JWT Authentication Adapter
+ *
+ * Implements the AuthAdapter interface using JWT tokens.
+ * Provides session loading from Authorization headers and
+ * optional routes for token refresh and logout.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new JwtAdapter();
+ * await adapter.initialize(fastify, {
+ *   name: 'jwt',
+ *   jwt: { secret: process.env.JWT_SECRET! },
+ * });
+ *
+ * // Get session from request
+ * const session = await adapter.getSession(request);
+ * if (session) {
+ *   console.log('User:', session.user.email);
+ * }
+ * ```
+ */
+export declare class JwtAdapter extends BaseAuthAdapter<JwtAdapterConfig> {
+    private jwt;
+    private tokenStore;
+    private userLoader?;
+    private enableRoutes;
+    private routePrefix;
+    constructor();
+    /**
+     * Initialize the adapter with JWT configuration
+     *
+     * Sets up the JwtManager, token store, and configuration options.
+     * Also exposes `jwtManager` and `tokenStore` on the Fastify instance.
+     */
+    initialize(fastify: FastifyInstance, config: JwtAdapterConfig): Promise<void>;
+    /**
+     * Get session from JWT token in Authorization header
+     *
+     * Extracts and verifies the JWT token, checks revocation status,
+     * and loads the user if a userLoader is configured.
+     *
+     * @returns Session result with user and session data, or null if not authenticated
+     */
+    getSession(request: FastifyRequest): Promise<AdapterSessionResult | null>;
+    /**
+     * Get routes for token refresh and logout
+     *
+     * Returns routes only if `enableRoutes` is true in config.
+     */
+    getRoutes(): AdapterRoute[];
+    /**
+     * Handle token refresh requests
+     *
+     * Expects `refreshToken` in request body.
+     * Returns new token pair on success.
+     */
+    private handleRefresh;
+    /**
+     * Handle logout requests
+     *
+     * Revokes the current access token by adding its JTI to the token store.
+     * The token is extracted from the Authorization header.
+     */
+    private handleLogout;
+    /**
+     * Clean up adapter resources
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Create a token pair for a user
+     *
+     * Convenience method that delegates to the underlying JwtManager.
+     * Can be accessed via `fastify.jwtManager.createTokenPair()` as well.
+     *
+     * @param user - The user to create tokens for
+     * @param additionalClaims - Custom claims to include in the token
+     * @returns Token pair with access and refresh tokens
+     *
+     * @example
+     * ```typescript
+     * const tokens = adapter.createTokenPair(user);
+     * // { accessToken, refreshToken, expiresIn, tokenType }
+     * ```
+     */
+    createTokenPair(user: User, additionalClaims?: Record<string, unknown>): TokenPair;
+    /**
+     * Get the underlying JwtManager instance
+     *
+     * Useful for advanced token operations.
+     */
+    getJwtManager(): JwtManager;
+    /**
+     * Get the token store instance
+     *
+     * Useful for manual token revocation.
+     */
+    getTokenStore(): TokenStore;
+}
+/**
+ * Create a JWT auth adapter
+ *
+ * This is the recommended way to create a JWT adapter for use with
+ * createAuthAdapterPlugin. Returns both the adapter instance and
+ * the configuration for convenience.
+ *
+ * @param config - JWT adapter configuration (without name, which is auto-set to 'jwt')
+ * @returns Object with adapter and config
+ *
+ * @example
+ * ```typescript
+ * import { createJwtAdapter } from '@veloxts/auth/adapters/jwt-adapter';
+ * import { createAuthAdapterPlugin } from '@veloxts/auth';
+ *
+ * const { adapter, config } = createJwtAdapter({
+ *   jwt: {
+ *     secret: process.env.JWT_SECRET!,
+ *     accessTokenExpiry: '15m',
+ *     refreshTokenExpiry: '7d',
+ *   },
+ *   userLoader: async (userId) => db.user.findUnique({ where: { id: userId } }),
+ * });
+ *
+ * const authPlugin = createAuthAdapterPlugin({ adapter, config });
+ * app.use(authPlugin);
+ * ```
+ */
+export declare function createJwtAdapter(config: Omit<JwtAdapterConfig, 'name'>): {
+    adapter: JwtAdapter;
+    config: JwtAdapterConfig;
+};
+declare module 'fastify' {
+    interface FastifyInstance {
+        /**
+         * JWT manager instance (from JwtAdapter)
+         *
+         * Available after registering the JWT adapter plugin.
+         * Use for creating tokens, verifying tokens, etc.
+         */
+        jwtManager?: JwtManager;
+        /**
+         * Token store instance (from JwtAdapter)
+         *
+         * Available after registering the JWT adapter plugin.
+         * Use for manual token revocation.
+         */
+        tokenStore?: TokenStore;
+    }
+}
+export { AuthAdapterError } from '../adapter.js';