@naman_deep_singh/security 1.1.0 → 1.3.0

package/dist/types/core/jwt/index.d.ts

@@ -3,5 +3,6 @@ export * from "./extractToken";
 export * from "./generateTokens";
 export * from "./parseDuration";
 export * from "./signToken";
+export * from "./types";
 export * from "./validateToken";
 export * from "./verify";

package/dist/types/core/jwt/jwtManager.d.ts

@@ -0,0 +1,66 @@
+import { JwtPayload, Secret } from "jsonwebtoken";
+import { ITokenManager, TokenPair, AccessToken, RefreshToken, JWTConfig, TokenValidationOptions } from "../../interfaces/jwt.interface";
+export declare class JWTManager implements ITokenManager {
+    private accessSecret;
+    private refreshSecret;
+    private accessExpiry;
+    private refreshExpiry;
+    private cache?;
+    constructor(config: JWTConfig);
+    /**
+     * Generate both access and refresh tokens
+     */
+    generateTokens(payload: Record<string, unknown>): Promise<TokenPair>;
+    /**
+     * Generate access token
+     */
+    generateAccessToken(payload: Record<string, unknown>): Promise<AccessToken>;
+    /**
+     * Generate refresh token
+     */
+    generateRefreshToken(payload: Record<string, unknown>): Promise<RefreshToken>;
+    /**
+     * Verify access token
+     */
+    verifyAccessToken(token: string): Promise<JwtPayload | string>;
+    /**
+     * Verify refresh token
+     */
+    verifyRefreshToken(token: string): Promise<JwtPayload | string>;
+    /**
+     * Decode token without verification
+     */
+    decodeToken(token: string, complete?: boolean): JwtPayload | string | null;
+    /**
+     * Extract token from Authorization header
+     */
+    extractTokenFromHeader(authHeader: string): string | null;
+    /**
+     * Validate token without throwing exceptions
+     */
+    validateToken(token: string, secret: Secret, options?: TokenValidationOptions): boolean;
+    /**
+     * Rotate refresh token
+     */
+    rotateRefreshToken(oldToken: string): Promise<RefreshToken>;
+    /**
+     * Check if token is expired
+     */
+    isTokenExpired(token: string): boolean;
+    /**
+     * Get token expiration date
+     */
+    getTokenExpiration(token: string): Date | null;
+    /**
+     * Clear token cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+    } | null;
+    private validatePayload;
+}

package/dist/types/core/jwt/signToken.d.ts

@@ -1,2 +1,2 @@
 import { Secret, SignOptions } from "jsonwebtoken";
-export declare const signToken: (payload: Record<string, any>, secret: Secret, expiresIn?: string | number, options?: SignOptions) => string;
+export declare const signToken: (payload: Record<string, unknown>, secret: Secret, expiresIn?: string | number, options?: SignOptions) => string;

package/dist/types/core/jwt/types.d.ts

@@ -0,0 +1,22 @@
+import { JwtPayload } from "jsonwebtoken";
+export interface AccessTokenBrand {
+    readonly access: unique symbol;
+}
+export interface RefreshTokenBrand {
+    readonly refresh: unique symbol;
+}
+export type AccessToken = string & AccessTokenBrand;
+export type RefreshToken = string & RefreshTokenBrand;
+export interface TokenPair {
+    accessToken: AccessToken;
+    refreshToken: RefreshToken;
+}
+export interface VerificationResult<T = JwtPayload> {
+    valid: boolean;
+    payload?: T | string;
+    error?: Error;
+}
+export interface TokenValidationOptions {
+    ignoreExpiration?: boolean;
+    ignoreIssuedAt?: boolean;
+}

package/dist/types/core/jwt/validateToken.d.ts

@@ -4,7 +4,7 @@ export interface TokenRequirements {
     forbiddenFields?: string[];
     validateTypes?: Record<string, "string" | "number" | "boolean">;
 }
-export declare function validateTokenPayload(payload: Record<string, any>, rules?: TokenRequirements): {
+export declare function validateTokenPayload(payload: Record<string, unknown>, rules?: TokenRequirements): {
     valid: true;
 } | {
     valid: false;

package/dist/types/core/jwt/verify.d.ts

@@ -1,13 +1,18 @@
-import { Secret, JwtPayload } from "jsonwebtoken";
+import jwt, { Secret, JwtPayload } from "jsonwebtoken";
+import { VerificationResult } from "./types";
 /**
  * Verify token (throws if invalid or expired)
  */
 export declare const verifyToken: (token: string, secret: Secret) => string | JwtPayload;
 /**
- * Safe verify — never throws, returns { valid, payload?, error? }
+ * Safe verify — never throws, returns structured result
  */
-export declare const safeVerifyToken: (token: string, secret: Secret) => {
-    valid: boolean;
-    payload?: string | JwtPayload;
-    error?: unknown;
-};
+export declare const safeVerifyToken: (token: string, secret: Secret) => VerificationResult;
+/**
+ * Verify token with validation options
+ */
+export declare const verifyTokenWithOptions: (token: string, secret: Secret, options?: jwt.VerifyOptions) => string | JwtPayload;
+/**
+ * Safe verify with validation options
+ */
+export declare const safeVerifyTokenWithOptions: (token: string, secret: Secret, options?: jwt.VerifyOptions) => VerificationResult;

package/dist/types/core/password/passwordManager.d.ts

@@ -0,0 +1,29 @@
+import { IPasswordManager, PasswordConfig, PasswordValidationResult, HashedPassword, PasswordStrength } from "../../interfaces/password.interface";
+export declare class PasswordManager implements IPasswordManager {
+    private defaultConfig;
+    constructor(config?: PasswordConfig);
+    /**
+     * Hash a password asynchronously using bcrypt
+     */
+    hash(password: string, salt?: string): Promise<HashedPassword>;
+    /**
+     * Verify password against hash and salt
+     */
+    verify(password: string, hash: string, salt: string): Promise<boolean>;
+    /**
+     * Generate a random password
+     */
+    generate(length?: number, options?: PasswordConfig): string;
+    /**
+     * Validate password against configuration
+     */
+    validate(password: string, config?: PasswordConfig): PasswordValidationResult;
+    /**
+     * Check password strength
+     */
+    checkStrength(password: string): PasswordStrength;
+    /**
+     * Check if password hash needs upgrade (different salt rounds)
+     */
+    needsUpgrade(hash: string, currentConfig: PasswordConfig): boolean;
+}

package/dist/types/index.d.ts

@@ -3,6 +3,7 @@ export * from "./core/jwt";
 export * from "./core/crypto";
 export { BadRequestError, UnauthorizedError, ValidationError, InternalServerError } from "@naman_deep_singh/errors-utils";
 import * as JWTUtils from "./core/jwt";
+import * as CryptoUtils from "./core/crypto";
 declare const _default: {
     decrypt: (data: string, secret: string) => string;
     encrypt: (text: string, secret: string) => string;
@@ -10,14 +11,17 @@ declare const _default: {
     hmacVerify: (message: string, secret: string, signature: string) => boolean;
     randomToken: (length?: number) => string;
     generateStrongPassword: (length?: number) => string;
+    CryptoManager: typeof CryptoUtils.CryptoManager;
+    createCryptoManager: (config?: CryptoUtils.CryptoManagerConfig) => CryptoUtils.CryptoManager;
+    cryptoManager: CryptoUtils.CryptoManager;
     decodeToken(token: string): null | string | import("node_modules/@types/jsonwebtoken").JwtPayload;
     decodeTokenStrict(token: string): import("node_modules/@types/jsonwebtoken").JwtPayload;
     extractToken(sources: JWTUtils.TokenSources): string | null;
-    rotateRefreshToken(oldToken: string, secret: import("node_modules/@types/jsonwebtoken").Secret): string;
-    generateTokens: (payload: object, accessSecret: import("node_modules/@types/jsonwebtoken").Secret, refreshSecret: import("node_modules/@types/jsonwebtoken").Secret, accessExpiry?: string | number, refreshExpiry?: string | number) => JWTUtils.TokenPair;
+    rotateRefreshToken(oldToken: string, secret: import("node_modules/@types/jsonwebtoken").Secret): JWTUtils.RefreshToken;
+    generateTokens: (payload: Record<string, unknown>, accessSecret: import("node_modules/@types/jsonwebtoken").Secret, refreshSecret: import("node_modules/@types/jsonwebtoken").Secret, accessExpiry?: string | number, refreshExpiry?: string | number) => JWTUtils.TokenPair;
     parseDuration(input: string | number): number;
-    signToken: (payload: Record<string, any>, secret: import("node_modules/@types/jsonwebtoken").Secret, expiresIn?: string | number, options?: import("node_modules/@types/jsonwebtoken").SignOptions) => string;
-    validateTokenPayload(payload: Record<string, any>, rules?: JWTUtils.TokenRequirements): {
+    signToken: (payload: Record<string, unknown>, secret: import("node_modules/@types/jsonwebtoken").Secret, expiresIn?: string | number, options?: import("node_modules/@types/jsonwebtoken").SignOptions) => string;
+    validateTokenPayload(payload: Record<string, unknown>, rules?: JWTUtils.TokenRequirements): {
         valid: true;
     } | {
         valid: false;
@@ -25,11 +29,9 @@ declare const _default: {
     };
     isTokenExpired(payload: import("node_modules/@types/jsonwebtoken").JwtPayload): boolean;
     verifyToken: (token: string, secret: import("node_modules/@types/jsonwebtoken").Secret) => string | import("node_modules/@types/jsonwebtoken").JwtPayload;
-    safeVerifyToken: (token: string, secret: import("node_modules/@types/jsonwebtoken").Secret) => {
-        valid: boolean;
-        payload?: string | import("node_modules/@types/jsonwebtoken").JwtPayload;
-        error?: unknown;
-    };
+    safeVerifyToken: (token: string, secret: import("node_modules/@types/jsonwebtoken").Secret) => JWTUtils.VerificationResult;
+    verifyTokenWithOptions: (token: string, secret: import("node_modules/@types/jsonwebtoken").Secret, options?: import("node_modules/@types/jsonwebtoken").VerifyOptions) => string | import("node_modules/@types/jsonwebtoken").JwtPayload;
+    safeVerifyTokenWithOptions: (token: string, secret: import("node_modules/@types/jsonwebtoken").Secret, options?: import("node_modules/@types/jsonwebtoken").VerifyOptions) => JWTUtils.VerificationResult;
     hashPasswordWithPepper(password: string, pepper: string): Promise<string>;
     hashPasswordWithPepperSync(password: string, pepper: string): string;
     hashPassword: (password: string, saltRounds?: number) => Promise<string>;

package/dist/types/interfaces/jwt.interface.d.ts

@@ -0,0 +1,47 @@
+import { JwtPayload, Secret } from "jsonwebtoken";
+export interface AccessToken extends String {
+    readonly __type: 'AccessToken';
+}
+export interface RefreshToken extends String {
+    readonly __type: 'RefreshToken';
+}
+export interface TokenPair {
+    accessToken: AccessToken;
+    refreshToken: RefreshToken;
+}
+export interface JWTConfig {
+    accessSecret: Secret;
+    refreshSecret: Secret;
+    accessExpiry?: string | number;
+    refreshExpiry?: string | number;
+    enableCaching?: boolean;
+    maxCacheSize?: number;
+}
+export interface TokenValidationOptions {
+    ignoreExpiration?: boolean;
+    ignoreNotBefore?: boolean;
+    audience?: string | string[];
+    issuer?: string;
+    algorithms?: string[];
+}
+export interface TokenGenerationOptions {
+    algorithm?: string;
+    expiresIn?: string | number;
+    audience?: string | string[];
+    issuer?: string;
+    subject?: string;
+    kid?: string;
+}
+export interface ITokenManager {
+    generateTokens(payload: Record<string, unknown>): Promise<TokenPair>;
+    generateAccessToken(payload: Record<string, unknown>): Promise<AccessToken>;
+    generateRefreshToken(payload: Record<string, unknown>): Promise<RefreshToken>;
+    verifyAccessToken(token: string): Promise<JwtPayload | string>;
+    verifyRefreshToken(token: string): Promise<JwtPayload | string>;
+    decodeToken(token: string, complete?: boolean): JwtPayload | string | null;
+    extractTokenFromHeader(authHeader: string): string | null;
+    validateToken(token: string, secret: Secret, options?: TokenValidationOptions): boolean;
+    rotateRefreshToken(oldToken: string): Promise<RefreshToken>;
+    isTokenExpired(token: string): boolean;
+    getTokenExpiration(token: string): Date | null;
+}

package/dist/types/interfaces/password.interface.d.ts

@@ -0,0 +1,60 @@
+export interface PasswordConfig {
+    saltRounds?: number;
+    minLength?: number;
+    maxLength?: number;
+    requireUppercase?: boolean;
+    requireLowercase?: boolean;
+    requireNumbers?: boolean;
+    requireSpecialChars?: boolean;
+    customRules?: PasswordRule[];
+}
+export interface PasswordRule {
+    test: (password: string) => boolean;
+    message: string;
+}
+export interface PasswordStrength {
+    score: number;
+    label: 'very-weak' | 'weak' | 'fair' | 'good' | 'strong';
+    feedback: string[];
+    suggestions: string[];
+}
+export interface PasswordValidationResult {
+    isValid: boolean;
+    errors: string[];
+    strength: PasswordStrength;
+}
+export interface HashedPassword {
+    hash: string;
+    salt: string;
+}
+export interface IPasswordManager {
+    hash(password: string, salt?: string): Promise<HashedPassword>;
+    verify(password: string, hash: string, salt: string): Promise<boolean>;
+    generate(length?: number, options?: PasswordConfig): string;
+    validate(password: string, config?: PasswordConfig): PasswordValidationResult;
+    checkStrength(password: string): PasswordStrength;
+    needsUpgrade(hash: string, currentConfig: PasswordConfig): boolean;
+}
+export interface IPasswordStrengthChecker {
+    analyze(password: string): PasswordStrength;
+    checkLength(password: string): {
+        valid: boolean;
+        message: string;
+    };
+    checkComplexity(password: string, config: PasswordConfig): {
+        valid: boolean;
+        message: string;
+    }[];
+    checkCommonPasswords(password: string): {
+        valid: boolean;
+        message: string;
+    };
+    checkSequential(password: string): {
+        valid: boolean;
+        message: string;
+    };
+    checkRepetition(password: string): {
+        valid: boolean;
+        message: string;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naman_deep_singh/security",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Security utilities for password hashing and JWT token management with TypeScript",
   "type": "module",
   "main": "./dist/cjs/index.js",