@veloxts/auth 0.6.68 → 0.6.70

package/dist/adapters/jwt-adapter.js

@@ -0,0 +1,360 @@
+/**
+ * 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 { AuthAdapterError, BaseAuthAdapter } from '../adapter.js';
+import { createInMemoryTokenStore, JwtManager } from '../jwt.js';
+// ============================================================================
+// JWT Adapter Implementation
+// ============================================================================
+/**
+ * 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 class JwtAdapter extends BaseAuthAdapter {
+    jwt = null;
+    tokenStore = null;
+    userLoader;
+    enableRoutes = true;
+    routePrefix = '/api/auth';
+    constructor() {
+        super('jwt', '1.0.0');
+    }
+    /**
+     * Initialize the adapter with JWT configuration
+     *
+     * Sets up the JwtManager, token store, and configuration options.
+     * Also exposes `jwtManager` and `tokenStore` on the Fastify instance.
+     */
+    async initialize(fastify, config) {
+        await super.initialize(fastify, config);
+        if (!config.jwt) {
+            throw new AuthAdapterError('JWT configuration is required in adapter config', 500, 'ADAPTER_NOT_CONFIGURED');
+        }
+        // Initialize JWT manager
+        this.jwt = new JwtManager(config.jwt);
+        /**
+         * Initialize token store (default: in-memory with warning)
+         *
+         * @example Production Redis store passed in config:
+         * ```typescript
+         * import { createRedisTokenStore } from '@veloxts/auth/redis';
+         * …
+         * tokenStore: createRedisTokenStore({ url: process.env.REDIS_URL })
+         * ```
+         */
+        this.tokenStore = config.tokenStore ?? createInMemoryTokenStore();
+        if (!config.tokenStore) {
+            this.debug('Using in-memory token store. Use Redis in production.');
+        }
+        this.userLoader = config.userLoader;
+        this.enableRoutes = config.enableRoutes ?? true;
+        this.routePrefix = config.routePrefix ?? '/api/auth';
+        // Expose JWT manager and token store on fastify for direct access
+        if (!fastify.hasDecorator('jwtManager')) {
+            fastify.decorate('jwtManager', this.jwt);
+        }
+        if (!fastify.hasDecorator('tokenStore')) {
+            fastify.decorate('tokenStore', this.tokenStore);
+        }
+        this.info('JWT adapter initialized');
+    }
+    /**
+     * 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
+     */
+    async getSession(request) {
+        if (!this.jwt || !this.tokenStore) {
+            throw new AuthAdapterError('JWT adapter not initialized', 500, 'ADAPTER_NOT_CONFIGURED');
+        }
+        // Extract token from Authorization header
+        const authHeader = request.headers.authorization;
+        const token = this.jwt.extractFromHeader(authHeader);
+        if (!token) {
+            return null;
+        }
+        try {
+            // Verify token
+            const payload = this.jwt.verifyToken(token);
+            // Check for access token type
+            if (payload.type !== 'access') {
+                this.debug('Non-access token in Authorization header');
+                return null;
+            }
+            // Check if token is revoked
+            if (payload.jti) {
+                const isRevoked = await this.tokenStore.isRevoked(payload.jti);
+                if (isRevoked) {
+                    this.debug('Token has been revoked');
+                    return null;
+                }
+            }
+            // Load user if loader provided
+            let user;
+            if (this.userLoader) {
+                user = await this.userLoader(payload.sub);
+                if (!user) {
+                    this.debug('User not found for token');
+                    return null;
+                }
+            }
+            else {
+                user = { id: payload.sub, email: payload.email };
+            }
+            // Store token and payload on request for middleware access
+            // Using type assertion to avoid modifying Fastify types
+            const requestWithJwt = request;
+            requestWithJwt.__jwtToken = token;
+            requestWithJwt.__jwtPayload = payload;
+            return {
+                user: {
+                    id: user.id,
+                    email: user.email,
+                    name: user.name,
+                    emailVerified: user.emailVerified,
+                    providerData: { roles: user.roles, permissions: user.permissions },
+                },
+                session: {
+                    sessionId: payload.jti ?? `jwt-${payload.sub}`,
+                    userId: payload.sub,
+                    expiresAt: payload.exp * 1000, // Convert to ms
+                    isActive: true,
+                    providerData: { token, payload },
+                },
+            };
+        }
+        catch (error) {
+            this.debug(`Token verification failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return null;
+        }
+    }
+    /**
+     * Get routes for token refresh and logout
+     *
+     * Returns routes only if `enableRoutes` is true in config.
+     */
+    getRoutes() {
+        if (!this.enableRoutes) {
+            return [];
+        }
+        return [
+            // Refresh token endpoint
+            {
+                path: `${this.routePrefix}/refresh`,
+                methods: ['POST'],
+                handler: this.handleRefresh.bind(this),
+                description: 'Refresh access token using refresh token',
+            },
+            // Logout endpoint (revoke token)
+            {
+                path: `${this.routePrefix}/logout`,
+                methods: ['POST'],
+                handler: this.handleLogout.bind(this),
+                description: 'Revoke current access token',
+            },
+        ];
+    }
+    /**
+     * Handle token refresh requests
+     *
+     * Expects `refreshToken` in request body.
+     * Returns new token pair on success.
+     */
+    async handleRefresh(request, reply) {
+        if (!this.jwt) {
+            throw new AuthAdapterError('JWT adapter not initialized', 500, 'ADAPTER_NOT_CONFIGURED');
+        }
+        const body = request.body;
+        const refreshToken = body?.refreshToken;
+        if (!refreshToken) {
+            reply.status(400).send({ error: 'Missing refreshToken in request body' });
+            return;
+        }
+        try {
+            const tokens = await this.jwt.refreshTokens(refreshToken, this.userLoader);
+            reply.send(tokens);
+        }
+        catch (error) {
+            reply.status(401).send({
+                error: error instanceof Error ? error.message : 'Token refresh failed',
+            });
+        }
+    }
+    /**
+     * Handle logout requests
+     *
+     * Revokes the current access token by adding its JTI to the token store.
+     * The token is extracted from the Authorization header.
+     */
+    async handleLogout(request, reply) {
+        if (!this.tokenStore) {
+            throw new AuthAdapterError('JWT adapter not initialized', 500, 'ADAPTER_NOT_CONFIGURED');
+        }
+        // Get payload from request (set during getSession in preHandler)
+        const requestWithJwt = request;
+        const payload = requestWithJwt.__jwtPayload;
+        if (payload?.jti) {
+            await this.tokenStore.revoke(payload.jti);
+            this.debug(`Token ${payload.jti} revoked`);
+        }
+        reply.status(200).send({ success: true });
+    }
+    /**
+     * Clean up adapter resources
+     */
+    async cleanup() {
+        await super.cleanup();
+        this.jwt = null;
+        this.tokenStore = null;
+        this.userLoader = undefined;
+        this.info('JWT adapter cleaned up');
+    }
+    // ============================================================================
+    // Public API Methods
+    // ============================================================================
+    /**
+     * 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, additionalClaims) {
+        if (!this.jwt) {
+            throw new AuthAdapterError('JWT adapter not initialized', 500, 'ADAPTER_NOT_CONFIGURED');
+        }
+        return this.jwt.createTokenPair(user, additionalClaims);
+    }
+    /**
+     * Get the underlying JwtManager instance
+     *
+     * Useful for advanced token operations.
+     */
+    getJwtManager() {
+        if (!this.jwt) {
+            throw new AuthAdapterError('JWT adapter not initialized', 500, 'ADAPTER_NOT_CONFIGURED');
+        }
+        return this.jwt;
+    }
+    /**
+     * Get the token store instance
+     *
+     * Useful for manual token revocation.
+     */
+    getTokenStore() {
+        if (!this.tokenStore) {
+            throw new AuthAdapterError('JWT adapter not initialized', 500, 'ADAPTER_NOT_CONFIGURED');
+        }
+        return this.tokenStore;
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * 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 function createJwtAdapter(config) {
+    const adapter = new JwtAdapter();
+    const fullConfig = {
+        name: 'jwt',
+        ...config,
+    };
+    return { adapter, config: fullConfig };
+}
+// ============================================================================
+// Re-exports
+// ============================================================================
+export { AuthAdapterError } from '../adapter.js';

package/dist/decoration.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Shared decoration utilities for @veloxts/auth
+ *
+ * This module provides common functionality for decorating Fastify instances
+ * and requests with authentication state, shared between the native auth plugin
+ * and external auth adapters.
+ *
+ * @module auth/decoration
+ */
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import type { AuthContext, User } from './types.js';
+/**
+ * Symbol used to mark a Fastify instance as having auth already registered.
+ *
+ * This prevents double-registration of conflicting auth systems (e.g., using
+ * both authPlugin and an AuthAdapter on the same server).
+ */
+export declare const AUTH_REGISTERED: unique symbol;
+/**
+ * Checks for double-registration of auth systems and throws if detected.
+ *
+ * Call this at the start of both `authPlugin` and `createAuthAdapterPlugin`
+ * registration to ensure only one auth system is active.
+ *
+ * @param fastify - Fastify server instance
+ * @param source - Identifier for the auth system being registered (e.g., 'authPlugin', 'adapter:better-auth')
+ * @throws {Error} If auth has already been registered by another source
+ *
+ * @example
+ * ```typescript
+ * // In authPlugin registration
+ * checkDoubleRegistration(fastify, 'authPlugin');
+ *
+ * // In adapter plugin registration
+ * checkDoubleRegistration(fastify, `adapter:${adapter.name}`);
+ * ```
+ */
+export declare function checkDoubleRegistration(fastify: FastifyInstance, source: string): void;
+/**
+ * Decorates a Fastify instance with auth-related request decorators.
+ *
+ * This function safely adds `auth` and `user` properties to requests,
+ * checking if they already exist (idempotent operation).
+ *
+ * @param fastify - Fastify server instance to decorate
+ *
+ * @example
+ * ```typescript
+ * decorateAuth(fastify);
+ * // Now all requests will have request.auth and request.user available
+ * ```
+ */
+export declare function decorateAuth(fastify: FastifyInstance): void;
+/**
+ * Sets the auth context and user on a request.
+ *
+ * This is a type-safe helper that properly casts the request to include
+ * auth properties before setting them.
+ *
+ * @param request - Fastify request object
+ * @param auth - Auth context to set
+ * @param user - User to set (optional, defaults to auth.user if NativeAuthContext)
+ *
+ * @example
+ * ```typescript
+ * setRequestAuth(request, {
+ *   authMode: 'native',
+ *   isAuthenticated: true,
+ *   token: tokenPayload,
+ *   payload: tokenPayload,
+ * }, user);
+ * ```
+ */
+export declare function setRequestAuth(request: FastifyRequest, auth: AuthContext, user?: User): void;
+/**
+ * Gets the current auth context from a request.
+ *
+ * @param request - Fastify request object
+ * @returns The auth context, or undefined if not set
+ */
+export declare function getRequestAuth(request: FastifyRequest): AuthContext | undefined;
+/**
+ * Gets the current user from a request.
+ *
+ * @param request - Fastify request object
+ * @returns The user, or undefined if not authenticated
+ */
+export declare function getRequestUser(request: FastifyRequest): User | undefined;

package/dist/decoration.js

@@ -0,0 +1,112 @@
+/**
+ * Shared decoration utilities for @veloxts/auth
+ *
+ * This module provides common functionality for decorating Fastify instances
+ * and requests with authentication state, shared between the native auth plugin
+ * and external auth adapters.
+ *
+ * @module auth/decoration
+ */
+// ============================================================================
+// Registration Protection
+// ============================================================================
+/**
+ * Symbol used to mark a Fastify instance as having auth already registered.
+ *
+ * This prevents double-registration of conflicting auth systems (e.g., using
+ * both authPlugin and an AuthAdapter on the same server).
+ */
+export const AUTH_REGISTERED = Symbol.for('@veloxts/auth/registered');
+/**
+ * Checks for double-registration of auth systems and throws if detected.
+ *
+ * Call this at the start of both `authPlugin` and `createAuthAdapterPlugin`
+ * registration to ensure only one auth system is active.
+ *
+ * @param fastify - Fastify server instance
+ * @param source - Identifier for the auth system being registered (e.g., 'authPlugin', 'adapter:better-auth')
+ * @throws {Error} If auth has already been registered by another source
+ *
+ * @example
+ * ```typescript
+ * // In authPlugin registration
+ * checkDoubleRegistration(fastify, 'authPlugin');
+ *
+ * // In adapter plugin registration
+ * checkDoubleRegistration(fastify, `adapter:${adapter.name}`);
+ * ```
+ */
+export function checkDoubleRegistration(fastify, source) {
+    const decorated = fastify;
+    if (decorated[AUTH_REGISTERED]) {
+        throw new Error(`Auth already registered by "${decorated[AUTH_REGISTERED]}". ` +
+            `Cannot register "${source}". ` +
+            `Use either authPlugin OR an AuthAdapter, not both.`);
+    }
+    decorated[AUTH_REGISTERED] = source;
+}
+/**
+ * Decorates a Fastify instance with auth-related request decorators.
+ *
+ * This function safely adds `auth` and `user` properties to requests,
+ * checking if they already exist (idempotent operation).
+ *
+ * @param fastify - Fastify server instance to decorate
+ *
+ * @example
+ * ```typescript
+ * decorateAuth(fastify);
+ * // Now all requests will have request.auth and request.user available
+ * ```
+ */
+export function decorateAuth(fastify) {
+    if (!fastify.hasRequestDecorator('auth')) {
+        fastify.decorateRequest('auth', undefined);
+    }
+    if (!fastify.hasRequestDecorator('user')) {
+        fastify.decorateRequest('user', undefined);
+    }
+}
+/**
+ * Sets the auth context and user on a request.
+ *
+ * This is a type-safe helper that properly casts the request to include
+ * auth properties before setting them.
+ *
+ * @param request - Fastify request object
+ * @param auth - Auth context to set
+ * @param user - User to set (optional, defaults to auth.user if NativeAuthContext)
+ *
+ * @example
+ * ```typescript
+ * setRequestAuth(request, {
+ *   authMode: 'native',
+ *   isAuthenticated: true,
+ *   token: tokenPayload,
+ *   payload: tokenPayload,
+ * }, user);
+ * ```
+ */
+export function setRequestAuth(request, auth, user) {
+    const decoratedRequest = request;
+    decoratedRequest.auth = auth;
+    decoratedRequest.user = user ?? (auth.isAuthenticated && 'user' in auth ? auth.user : undefined);
+}
+/**
+ * Gets the current auth context from a request.
+ *
+ * @param request - Fastify request object
+ * @returns The auth context, or undefined if not set
+ */
+export function getRequestAuth(request) {
+    return request.auth;
+}
+/**
+ * Gets the current user from a request.
+ *
+ * @param request - Fastify request object
+ * @returns The user, or undefined if not authenticated
+ */
+export function getRequestUser(request) {
+    return request.user;
+}

package/dist/guards-narrowing.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Narrowing Guards (Experimental)
+ *
+ * These guards provide TypeScript type narrowing after they pass.
+ * When using `guardNarrow(authenticatedNarrow)`, the context type
+ * is narrowed to guarantee `ctx.user` is non-null.
+ *
+ * EXPERIMENTAL: This API may change. The current recommended approach
+ * is to use middleware for context type extension.
+ *
+ * @module auth/guards-narrowing
+ */
+import type { AuthContext, GuardFunction, User } from './types.js';
+/**
+ * A guard that narrows the context type after passing.
+ *
+ * The `_narrows` phantom type indicates what the guard guarantees
+ * about the context after it passes.
+ *
+ * @template TRequired - Context properties required to run the guard
+ * @template TGuaranteed - Context properties guaranteed after guard passes
+ */
+export interface NarrowingGuard<TRequired, TGuaranteed> {
+    /** Guard name for error messages */
+    name: string;
+    /** Guard check function (matches GuardFunction signature) */
+    check: GuardFunction<TRequired>;
+    /** Custom error message */
+    message?: string;
+    /** HTTP status code for guard failures */
+    statusCode?: number;
+    /**
+     * Phantom type declaring what the guard guarantees.
+     * Used by ProcedureBuilder.guardNarrow() for type narrowing.
+     * @internal
+     */
+    readonly _narrows: TGuaranteed;
+}
+/**
+ * Context type with a guaranteed authenticated user.
+ *
+ * After `authenticatedNarrow` passes, the context is narrowed to this type.
+ */
+export interface AuthenticatedContext {
+    auth: AuthContext & {
+        isAuthenticated: true;
+    };
+    user: User;
+}
+/**
+ * Context type with a guaranteed user having specific roles.
+ */
+export interface RoleNarrowedContext {
+    user: User & {
+        roles: string[];
+    };
+}
+/**
+ * Authenticated guard with type narrowing.
+ *
+ * When used with `guardNarrow()`, narrows `ctx.user` from `User | undefined`
+ * to `User`, eliminating the need for null checks in the handler.
+ *
+ * @example
+ * ```typescript
+ * import { authenticatedNarrow } from '@veloxts/auth';
+ *
+ * // With guardNarrow (experimental):
+ * procedure()
+ *   .guardNarrow(authenticatedNarrow)
+ *   .query(({ ctx }) => {
+ *     // ctx.user is typed as User (non-null)
+ *     return { email: ctx.user.email };
+ *   });
+ *
+ * // Current recommended alternative using middleware:
+ * procedure()
+ *   .guard(authenticated)
+ *   .use(async ({ ctx, next }) => {
+ *     if (!ctx.user) throw new Error('Unreachable');
+ *     return next({ ctx: { user: ctx.user } });
+ *   })
+ *   .query(({ ctx }) => {
+ *     // ctx.user is non-null via middleware
+ *   });
+ * ```
+ */
+export declare const authenticatedNarrow: NarrowingGuard<{
+    auth?: AuthContext;
+}, AuthenticatedContext>;
+/**
+ * Creates a role-checking guard with type narrowing.
+ *
+ * Narrows `ctx.user` to guarantee non-null with roles array.
+ *
+ * @param roles - Required role(s)
+ * @returns NarrowingGuard that guarantees user with roles
+ *
+ * @example
+ * ```typescript
+ * import { hasRoleNarrow } from '@veloxts/auth';
+ *
+ * procedure()
+ *   .guardNarrow(hasRoleNarrow('admin'))
+ *   .mutation(({ ctx }) => {
+ *     // ctx.user is typed as User (non-null)
+ *     // ctx.user.roles is string[]
+ *   });
+ * ```
+ */
+export declare function hasRoleNarrow(roles: string | string[]): NarrowingGuard<{
+    user?: User;
+}, RoleNarrowedContext>;
+/**
+ * Extracts the narrowed context type from a NarrowingGuard.
+ *
+ * @example
+ * ```typescript
+ * type Ctx = InferNarrowedContext<typeof authenticatedNarrow>;
+ * // Ctx = AuthenticatedContext = { auth: AuthContext & { isAuthenticated: true }; user: User }
+ * ```
+ */
+export type InferNarrowedContext<T> = T extends NarrowingGuard<unknown, infer U> ? U : never;