@nauth-toolkit/core 0.1.14 → 0.1.18

package/dist/services/jwt.service.d.ts

@@ -1,65 +1,322 @@
 import { JwtConfig } from '../interfaces/config.interface';
+/**
+ * JWT Payload structure
+ */
 export interface JwtPayload {
+    /** User ID */
     sub: string;
+    /** User email */
     email: string;
+    /** Token type (access or refresh) */
     type: 'access' | 'refresh';
+    /** Session ID */
     sessionId: string;
+    /** Token family ID (for rotation detection) */
     tokenFamily?: string;
+    /** Issued at timestamp */
     iat: number;
+    /** Expiration timestamp */
     exp: number;
+    /** Issuer */
     iss?: string;
+    /** Audience */
     aud?: string | string[];
+    /** Device ID */
     deviceId?: string;
 }
+/**
+ * Token validation result
+ */
 export interface TokenValidationResult {
+    /** Whether token is valid */
     valid: boolean;
+    /** Decoded payload if valid */
     payload?: JwtPayload;
+    /** Error message if invalid */
     error?: string;
+    /** Error type for specific handling */
     errorType?: 'expired' | 'invalid' | 'malformed' | 'blacklisted';
 }
+/**
+ * Token pair (access + refresh)
+ */
 export interface TokenPair {
+    /** Short-lived access token */
     accessToken: string;
+    /** Long-lived refresh token */
     refreshToken: string;
+    /** Access token expiration in seconds */
     expiresIn: number;
 }
+/**
+ * JWT Service (Platform-Agnostic)
+ *
+ * Handles all JWT token operations using jose library for platform independence.
+ *
+ * **Features:**
+ * - Platform-agnostic (no framework dependencies)
+ * - Support for multiple algorithms (HS256, HS384, HS512, RS256, RS384, RS512)
+ * - Token rotation with family tracking
+ * - Token reuse detection
+ * - Symmetric and asymmetric key support
+ *
+ * **Security Features:**
+ * - HS256 as default algorithm (symmetric key)
+ * - HS256/HS384/HS512 for symmetric keys
+ * - RS256/RS384/RS512 for asymmetric keys
+ * - Token rotation on refresh
+ * - Token family tracking for reuse detection
+ * - Configurable expiration times
+ * - Standard JWT claims (iss, aud, sub, exp, iat)
+ *
+ * @example
+ * ```typescript
+ * const jwtService = new JwtService(config);
+ *
+ * // Generate token pair
+ * const tokens = await jwtService.generateTokenPair({
+ *   userId: 'user-123',
+ *   email: 'user@example.com',
+ *   sessionId: 'session-456',
+ * });
+ *
+ * // Validate token
+ * const result = await jwtService.validateAccessToken(tokens.accessToken);
+ * if (result.valid) {
+ *   console.log('User ID:', result.payload.sub);
+ * }
+ * ```
+ */
 export declare class JwtService {
+    /** JWT configuration */
     private readonly config;
+    /** Cached access token key (for performance) */
     private accessTokenKey;
+    /** Cached refresh token key (for performance) */
     private refreshTokenKey;
+    /**
+     * Cached dynamic import of jose.
+     * Kept as a promise so concurrent calls share the same module load.
+     */
     private joseModulePromise;
     constructor(jwtConfig: JwtConfig);
+    /**
+     * Lazy-load jose (ESM-only) in a CJS-compatible way.
+     * @private
+     */
     private getJose;
+    /**
+     * Prepare and cache signing keys for better performance
+     * @private
+     */
     private prepareKeys;
+    /**
+     * Get algorithm for signing access tokens
+     *
+     * Automatically selects appropriate algorithm based on key material:
+     * - If privateKey is provided → uses configured algorithm (RS256, RS384, RS512)
+     * - If only secret is provided → uses configured algorithm or defaults to HS256
+     *
+     * @private
+     */
     private getAlgorithm;
+    /**
+     * Get algorithm for signing refresh tokens
+     *
+     * Refresh tokens only support symmetric algorithms (HS256/HS384/HS512)
+     * because RefreshTokenConfig only provides a secret, not a privateKey.
+     *
+     * Automatically selects appropriate symmetric algorithm:
+     * - If configured algorithm is symmetric (HS256/HS384/HS512) → uses it
+     * - If configured algorithm is asymmetric (RS256, RS384, RS512) → falls back to HS256
+     * - Defaults to HS256 if no algorithm is configured
+     *
+     * @private
+     */
     private getRefreshTokenAlgorithm;
+    /**
+     * Generate both access and refresh tokens
+     *
+     * Creates a pair of tokens with the same token family for rotation tracking.
+     * The token family allows detection of token reuse attacks.
+     *
+     * @param data - User and session information
+     * @returns Token pair with access and refresh tokens
+     *
+     * @example
+     * ```typescript
+     * const tokens = await jwtService.generateTokenPair({
+     *   userId: 'user-123',
+     *   email: 'user@example.com',
+     *   sessionId: 'session-456',
+     * });
+     *
+     * // Store tokens and send to client
+     * res.json({
+     *   accessToken: tokens.accessToken,
+     *   refreshToken: tokens.refreshToken,
+     *   expiresIn: tokens.expiresIn,
+     * });
+     * ```
+     */
     generateTokenPair(data: {
         userId: string;
         email: string;
         sessionId: string;
         tokenFamily?: string;
     }): Promise<TokenPair>;
+    /**
+     * Generate an access token
+     *
+     * Access tokens are short-lived (typically 15 minutes) and used for API authentication.
+     * They contain user identity and authorization information.
+     *
+     * @param data - Token payload data
+     * @returns Signed JWT access token
+     */
     generateAccessToken(data: {
         userId: string;
         email: string;
         sessionId: string;
         tokenFamily: string;
     }): Promise<string>;
+    /**
+     * Generate a refresh token
+     *
+     * Refresh tokens are long-lived (typically 30 days) and used to obtain new access tokens.
+     * They should be stored securely and rotated on each use.
+     *
+     * NOTE: Refresh tokens always use a symmetric algorithm (HS256/HS384/HS512)
+     * because RefreshTokenConfig only provides a secret, not a privateKey.
+     * This ensures compatibility between the algorithm and key type.
+     *
+     * @param data - Token payload data
+     * @returns Signed JWT refresh token
+     */
     generateRefreshToken(data: {
         userId: string;
         email: string;
         sessionId: string;
         tokenFamily: string;
     }): Promise<string>;
+    /**
+     * Validate an access token
+     *
+     * Verifies:
+     * - Token signature is valid
+     * - Token hasn't expired
+     * - Token type is 'access'
+     * - Token structure is correct
+     *
+     * @param token - JWT access token to validate
+     * @returns Validation result with payload or error
+     *
+     * @example
+     * ```typescript
+     * const result = await jwtService.validateAccessToken(token);
+     *
+     * if (!result.valid) {
+     *   if (result.errorType === 'expired') {
+     *     // Attempt to refresh token
+     *   } else {
+     *     // Invalid token, reject request
+     *   }
+     * }
+     * ```
+     */
     validateAccessToken(token: string): Promise<TokenValidationResult>;
+    /**
+     * Validate a refresh token
+     *
+     * Similar to access token validation but checks for 'refresh' type.
+     * Also verifies token hasn't been used before (if rotation is enabled).
+     *
+     * @param token - JWT refresh token to validate
+     * @returns Validation result with payload or error
+     */
     validateRefreshToken(token: string): Promise<TokenValidationResult>;
+    /**
+     * Decode a token without verification
+     *
+     * WARNING: This method does NOT validate the token signature or expiration.
+     * Only use for non-security-critical operations like logging or analytics.
+     *
+     * @param token - JWT token to decode
+     * @returns Decoded payload or null if malformed
+     */
     decodeToken(token: string): JwtPayload | null;
+    /**
+     * Convert base64url-encoded strings to standard base64 for decoding.
+     * @private
+     */
     private base64UrlToBase64;
+    /**
+     * Generate a unique token family identifier
+     *
+     * Token families are used to track token rotation and detect reuse attacks.
+     * All tokens in the same "family" (original + rotated versions) share this ID.
+     *
+     * SECURITY FIX #10: Increased from 16 bytes (128 bits) to 32 bytes (256 bits)
+     *
+     * @returns Random token family ID (256 bits)
+     */
     generateTokenFamily(): string;
+    /**
+     * Hash a token for storage
+     *
+     * Tokens should be hashed before storing in the database for security.
+     * This prevents token exposure if the database is compromised.
+     *
+     * @param token - Token to hash
+     * @returns SHA-256 hash of the token
+     */
     hashToken(token: string): string;
+    /**
+     * Get access token expiry time in seconds
+     *
+     * @returns Access token expiry time in seconds
+     *
+     * @example
+     * ```typescript
+     * const expiry = jwtService.getAccessTokenExpiry();
+     * console.log(expiry); // 900 (15 minutes)
+     * ```
+     */
     getAccessTokenExpiry(): number;
+    /**
+     * Get refresh token TTL in seconds
+     *
+     * Used for setting expiration on used-token tracking in storage.
+     *
+     * @returns TTL in seconds
+     */
     getRefreshTokenTTL(): number;
+    /**
+     * Extract token from Authorization header
+     *
+     * Supports standard "Bearer <token>" format
+     *
+     * @param authHeader - Authorization header value
+     * @returns Extracted token or null
+     *
+     * @example
+     * ```typescript
+     * const token = jwtService.extractTokenFromHeader('Bearer eyJhbGc...');
+     * // Returns: 'eyJhbGc...'
+     * ```
+     */
     extractTokenFromHeader(authHeader?: string): string | null;
+    /**
+     * Parse expiration time from string or number
+     * @param expiresIn - Expiration time (e.g., '15m', 900, '1h')
+     * @returns Expiration time in seconds
+     */
     private parseExpiresIn;
+    /**
+     * Handle JWT validation errors and convert to standardized result
+     * @param error - Error from JWT verification
+     * @returns Standardized validation result
+     */
     private handleValidationError;
 }
 //# sourceMappingURL=jwt.service.d.ts.map

package/dist/services/jwt.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.service.d.ts","sourceRoot":"","sources":["../../src/services/jwt.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAiB3D,MAAM,WAAW,UAAU;IAEzB,GAAG,EAAE,MAAM,CAAC;IAGZ,KAAK,EAAE,MAAM,CAAC;IAGd,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAG3B,SAAS,EAAE,MAAM,CAAC;IAGlB,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,GAAG,EAAE,MAAM,CAAC;IAGZ,GAAG,EAAE,MAAM,CAAC;IAGZ,GAAG,CAAC,EAAE,MAAM,CAAC;IAGb,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAGxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD,MAAM,WAAW,qBAAqB;IAEpC,KAAK,EAAE,OAAO,CAAC;IAGf,OAAO,CAAC,EAAE,UAAU,CAAC;IAGrB,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,CAAC;CACjE;AAKD,MAAM,WAAW,SAAS;IAExB,WAAW,EAAE,MAAM,CAAC;IAGpB,YAAY,EAAE,MAAM,CAAC;IAGrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAyCD,qBAAa,UAAU;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IAGnC,OAAO,CAAC,cAAc,CAA8C;IAGpE,OAAO,CAAC,eAAe,CAA8C;IAMrE,OAAO,CAAC,iBAAiB,CAAoC;gBAEjD,SAAS,EAAE,SAAS;YAalB,OAAO;IAerB,OAAO,CAAC,WAAW;IAyBnB,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,wBAAwB;IA2C1B,iBAAiB,CAAC,IAAI,EAAE;QAC5B,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,SAAS,CAAC;IAmChB,mBAAmB,CAAC,IAAI,EAAE;QAC9B,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC;IAmDb,oBAAoB,CAAC,IAAI,EAAE;QAC/B,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC;IAmDb,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAoDlE,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAwCzE,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAmB7C,OAAO,CAAC,iBAAiB;IAqBzB,mBAAmB,IAAI,MAAM;IAa7B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAehC,oBAAoB,IAAI,MAAM;IAW9B,kBAAkB,IAAI,MAAM;IAkB5B,sBAAsB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAoB1D,OAAO,CAAC,cAAc;IA2BtB,OAAO,CAAC,qBAAqB;CAgC9B"}
+{"version":3,"file":"jwt.service.d.ts","sourceRoot":"","sources":["../../src/services/jwt.service.ts"],"names":[],"mappings":"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"}