@naman_deep_singh/security 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @naman_deep_singh/security
 
-**Version:** 1.1.0
+**Version:** 1.2.0
 
 A complete, lightweight security toolkit for Node.js & TypeScript providing:
 
@@ -12,7 +12,11 @@ A complete, lightweight security toolkit for Node.js & TypeScript providing:
 🧰 **Robust token extraction** (Headers, Cookies, Query, Body, WebSocket)
 🧩 **Safe & strict JWT decode** utilities
 🚨 **Standardized error handling** with @naman_deep_singh/errors-utils
+
 ✔ **Fully typed** with TypeScript
+✔ **Branded token types** for compile-time safety (AccessToken/RefreshToken)
+✔ **Structured verification results** for better error handling
+✔ **Enhanced verification options** with flexible configuration
 ✔ **Consistent errors** across your application ecosystem
 ✔ **Works in both ESM and CommonJS**
 
@@ -60,13 +64,13 @@ hashPassword(password: string): Promise<string>
 const hashed = await hashPassword("mypassword");
 console.log(hashed); // $2a$10$...
 
+
 verifyPassword(password: string, hash: string): Promise<boolean>
 const isValid = await verifyPassword("mypassword", hashed);
 if (isValid) console.log("Correct password");
 
-comparePassword()
-
-Alias for backward compatibility.
+// Synchronous version also available
+const isValidSync = verifyPasswordSync("mypassword", hashed);
 
 🔑 2. JWT Signing
 signToken(payload, secret, expiresIn, options)

package/dist/cjs/core/jwt/extractToken.d.ts

@@ -2,8 +2,8 @@ export interface TokenSources {
     header?: string | undefined | null;
     cookies?: Record<string, string> | undefined;
     query?: Record<string, string | undefined> | undefined;
-    body?: Record<string, any> | undefined;
-    wsMessage?: string | Record<string, any> | undefined;
+    body?: Record<string, unknown> | undefined;
+    wsMessage?: string | Record<string, unknown> | undefined;
 }
 /**
  * Universal token extractor

package/dist/cjs/core/jwt/extractToken.js

@@ -23,7 +23,7 @@ function extractToken(sources) {
     if (query?.token)
         return query.token;
     // 4. Body: { token: "" }
-    if (body?.token)
+    if (body?.token && typeof body.token === 'string')
         return body.token;
     // 5. WebSocket message extraction (NEW)
     if (wsMessage) {
@@ -33,12 +33,17 @@ function extractToken(sources) {
             if (typeof wsMessage === "string") {
                 msg = JSON.parse(wsMessage);
             }
-            // Direct token
-            if (typeof msg.token === "string")
-                return msg.token;
-            // Nested token: { auth: { token: "" } }
-            if (msg.auth && typeof msg.auth.token === "string") {
-                return msg.auth.token;
+            // Ensure msg is an object before property access
+            if (typeof msg === 'object' && msg !== null) {
+                const m = msg;
+                if (typeof m['token'] === 'string')
+                    return m['token'];
+                const auth = m['auth'];
+                if (typeof auth === 'object' && auth !== null) {
+                    const a = auth;
+                    if (typeof a['token'] === 'string')
+                        return a['token'];
+                }
             }
         }
         catch {

package/dist/cjs/core/jwt/generateTokens.d.ts

@@ -1,7 +1,4 @@
 import { Secret } from "jsonwebtoken";
-export interface TokenPair {
-    accessToken: string;
-    refreshToken: string;
-}
-export declare const generateTokens: (payload: object, accessSecret: Secret, refreshSecret: Secret, accessExpiry?: string | number, refreshExpiry?: string | number) => TokenPair;
-export declare function rotateRefreshToken(oldToken: string, secret: Secret): string;
+import { RefreshToken, TokenPair } from "./types";
+export declare const generateTokens: (payload: Record<string, unknown>, accessSecret: Secret, refreshSecret: Secret, accessExpiry?: string | number, refreshExpiry?: string | number) => TokenPair;
+export declare function rotateRefreshToken(oldToken: string, secret: Secret): RefreshToken;

package/dist/cjs/core/jwt/generateTokens.js

@@ -4,10 +4,16 @@ exports.generateTokens = void 0;
 exports.rotateRefreshToken = rotateRefreshToken;
 const signToken_1 = require("./signToken");
 const verify_1 = require("./verify");
+// Helper function to create branded tokens
+const createBrandedToken = (token, _brand) => {
+    return token;
+};
 const generateTokens = (payload, accessSecret, refreshSecret, accessExpiry = "15m", refreshExpiry = "7d") => {
+    const accessToken = (0, signToken_1.signToken)(payload, accessSecret, accessExpiry, { algorithm: "HS256" });
+    const refreshToken = (0, signToken_1.signToken)(payload, refreshSecret, refreshExpiry, { algorithm: "HS256" });
     return {
-        accessToken: (0, signToken_1.signToken)(payload, accessSecret, accessExpiry, { algorithm: "HS256" }),
-        refreshToken: (0, signToken_1.signToken)(payload, refreshSecret, refreshExpiry, { algorithm: "HS256" }),
+        accessToken: accessToken,
+        refreshToken: refreshToken,
     };
 };
 exports.generateTokens = generateTokens;
@@ -19,5 +25,6 @@ function rotateRefreshToken(oldToken, secret) {
     const payload = { ...decoded };
     delete payload.iat;
     delete payload.exp;
-    return (0, signToken_1.signToken)(payload, secret, "7d");
+    const newToken = (0, signToken_1.signToken)(payload, secret, "7d");
+    return newToken;
 }

package/dist/cjs/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/cjs/core/jwt/index.js

@@ -19,5 +19,6 @@ __exportStar(require("./extractToken"), exports);
 __exportStar(require("./generateTokens"), exports);
 __exportStar(require("./parseDuration"), exports);
 __exportStar(require("./signToken"), exports);
+__exportStar(require("./types"), exports);
 __exportStar(require("./validateToken"), exports);
 __exportStar(require("./verify"), exports);

package/dist/cjs/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/cjs/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/cjs/core/jwt/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/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/cjs/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/cjs/core/jwt/verify.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.safeVerifyToken = exports.verifyToken = void 0;
+exports.safeVerifyTokenWithOptions = exports.verifyTokenWithOptions = exports.safeVerifyToken = exports.verifyToken = void 0;
 const jsonwebtoken_1 = require("jsonwebtoken");
 /**
  * Verify token (throws if invalid or expired)
@@ -10,7 +10,7 @@ const verifyToken = (token, secret) => {
 };
 exports.verifyToken = verifyToken;
 /**
- * Safe verify — never throws, returns { valid, payload?, error? }
+ * Safe verify — never throws, returns structured result
  */
 const safeVerifyToken = (token, secret) => {
     try {
@@ -18,7 +18,27 @@ const safeVerifyToken = (token, secret) => {
         return { valid: true, payload: decoded };
     }
     catch (error) {
-        return { valid: false, error };
+        return { valid: false, error: error };
     }
 };
 exports.safeVerifyToken = safeVerifyToken;
+/**
+ * Verify token with validation options
+ */
+const verifyTokenWithOptions = (token, secret, options = {}) => {
+    return (0, jsonwebtoken_1.verify)(token, secret, options);
+};
+exports.verifyTokenWithOptions = verifyTokenWithOptions;
+/**
+ * Safe verify with validation options
+ */
+const safeVerifyTokenWithOptions = (token, secret, options = {}) => {
+    try {
+        const decoded = (0, jsonwebtoken_1.verify)(token, secret, options);
+        return { valid: true, payload: decoded };
+    }
+    catch (error) {
+        return { valid: false, error: error };
+    }
+};
+exports.safeVerifyTokenWithOptions = safeVerifyTokenWithOptions;

package/dist/cjs/index.d.ts

@@ -13,11 +13,11 @@ declare const _default: {
     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 +25,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/esm/core/jwt/extractToken.d.ts

@@ -2,8 +2,8 @@ export interface TokenSources {
     header?: string | undefined | null;
     cookies?: Record<string, string> | undefined;
     query?: Record<string, string | undefined> | undefined;
-    body?: Record<string, any> | undefined;
-    wsMessage?: string | Record<string, any> | undefined;
+    body?: Record<string, unknown> | undefined;
+    wsMessage?: string | Record<string, unknown> | undefined;
 }
 /**
  * Universal token extractor

package/dist/esm/core/jwt/extractToken.js

@@ -20,7 +20,7 @@ export function extractToken(sources) {
     if (query?.token)
         return query.token;
     // 4. Body: { token: "" }
-    if (body?.token)
+    if (body?.token && typeof body.token === 'string')
         return body.token;
     // 5. WebSocket message extraction (NEW)
     if (wsMessage) {
@@ -30,12 +30,17 @@ export function extractToken(sources) {
             if (typeof wsMessage === "string") {
                 msg = JSON.parse(wsMessage);
             }
-            // Direct token
-            if (typeof msg.token === "string")
-                return msg.token;
-            // Nested token: { auth: { token: "" } }
-            if (msg.auth && typeof msg.auth.token === "string") {
-                return msg.auth.token;
+            // Ensure msg is an object before property access
+            if (typeof msg === 'object' && msg !== null) {
+                const m = msg;
+                if (typeof m['token'] === 'string')
+                    return m['token'];
+                const auth = m['auth'];
+                if (typeof auth === 'object' && auth !== null) {
+                    const a = auth;
+                    if (typeof a['token'] === 'string')
+                        return a['token'];
+                }
             }
         }
         catch {

package/dist/esm/core/jwt/generateTokens.d.ts

@@ -1,7 +1,4 @@
 import { Secret } from "jsonwebtoken";
-export interface TokenPair {
-    accessToken: string;
-    refreshToken: string;
-}
-export declare const generateTokens: (payload: object, accessSecret: Secret, refreshSecret: Secret, accessExpiry?: string | number, refreshExpiry?: string | number) => TokenPair;
-export declare function rotateRefreshToken(oldToken: string, secret: Secret): string;
+import { RefreshToken, TokenPair } from "./types";
+export declare const generateTokens: (payload: Record<string, unknown>, accessSecret: Secret, refreshSecret: Secret, accessExpiry?: string | number, refreshExpiry?: string | number) => TokenPair;
+export declare function rotateRefreshToken(oldToken: string, secret: Secret): RefreshToken;

package/dist/esm/core/jwt/generateTokens.js

@@ -1,9 +1,15 @@
 import { signToken } from "./signToken";
 import { verifyToken } from "./verify";
+// Helper function to create branded tokens
+const createBrandedToken = (token, _brand) => {
+    return token;
+};
 export const generateTokens = (payload, accessSecret, refreshSecret, accessExpiry = "15m", refreshExpiry = "7d") => {
+    const accessToken = signToken(payload, accessSecret, accessExpiry, { algorithm: "HS256" });
+    const refreshToken = signToken(payload, refreshSecret, refreshExpiry, { algorithm: "HS256" });
     return {
-        accessToken: signToken(payload, accessSecret, accessExpiry, { algorithm: "HS256" }),
-        refreshToken: signToken(payload, refreshSecret, refreshExpiry, { algorithm: "HS256" }),
+        accessToken: accessToken,
+        refreshToken: refreshToken,
     };
 };
 export function rotateRefreshToken(oldToken, secret) {
@@ -14,5 +20,6 @@ export function rotateRefreshToken(oldToken, secret) {
     const payload = { ...decoded };
     delete payload.iat;
     delete payload.exp;
-    return signToken(payload, secret, "7d");
+    const newToken = signToken(payload, secret, "7d");
+    return newToken;
 }

package/dist/esm/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/esm/core/jwt/index.js

@@ -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/esm/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/esm/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/esm/core/jwt/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/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/esm/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/esm/core/jwt/verify.js

@@ -6,7 +6,7 @@ export const verifyToken = (token, secret) => {
     return verify(token, secret);
 };
 /**
- * Safe verify — never throws, returns { valid, payload?, error? }
+ * Safe verify — never throws, returns structured result
  */
 export const safeVerifyToken = (token, secret) => {
     try {
@@ -14,6 +14,24 @@ export const safeVerifyToken = (token, secret) => {
         return { valid: true, payload: decoded };
     }
     catch (error) {
-        return { valid: false, error };
+        return { valid: false, error: error };
+    }
+};
+/**
+ * Verify token with validation options
+ */
+export const verifyTokenWithOptions = (token, secret, options = {}) => {
+    return verify(token, secret, options);
+};
+/**
+ * Safe verify with validation options
+ */
+export const safeVerifyTokenWithOptions = (token, secret, options = {}) => {
+    try {
+        const decoded = verify(token, secret, options);
+        return { valid: true, payload: decoded };
+    }
+    catch (error) {
+        return { valid: false, error: error };
     }
 };

package/dist/esm/index.d.ts

@@ -13,11 +13,11 @@ declare const _default: {
     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 +25,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/core/jwt/extractToken.d.ts

@@ -2,8 +2,8 @@ export interface TokenSources {
     header?: string | undefined | null;
     cookies?: Record<string, string> | undefined;
     query?: Record<string, string | undefined> | undefined;
-    body?: Record<string, any> | undefined;
-    wsMessage?: string | Record<string, any> | undefined;
+    body?: Record<string, unknown> | undefined;
+    wsMessage?: string | Record<string, unknown> | undefined;
 }
 /**
  * Universal token extractor

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

@@ -1,7 +1,4 @@
 import { Secret } from "jsonwebtoken";
-export interface TokenPair {
-    accessToken: string;
-    refreshToken: string;
-}
-export declare const generateTokens: (payload: object, accessSecret: Secret, refreshSecret: Secret, accessExpiry?: string | number, refreshExpiry?: string | number) => TokenPair;
-export declare function rotateRefreshToken(oldToken: string, secret: Secret): string;
+import { RefreshToken, TokenPair } from "./types";
+export declare const generateTokens: (payload: Record<string, unknown>, accessSecret: Secret, refreshSecret: Secret, accessExpiry?: string | number, refreshExpiry?: string | number) => TokenPair;
+export declare function rotateRefreshToken(oldToken: string, secret: Secret): RefreshToken;

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/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/index.d.ts

@@ -13,11 +13,11 @@ declare const _default: {
     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 +25,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/package.json

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