inslash 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [1.1.0] - 2026-02-18
+
+### Added
+- 🚀 **Version 2 passport format** with encoding support
+- 🔐 **API Key generation** utility (`generateApiKey()`)
+- 📊 **Batch verification** for multiple values (`batchVerify()`)
+- 🔍 **Passport inspection** without verification (`inspectPassport()`)
+- ⚖️ **Passport comparison** utility (`comparePassports()`)
+- 📈 **Security strength estimation** (`estimateSecurity()`)
+- 🎨 **Multiple encoding support** (hex, base64, base64url, latin1)
+- ✅ **Algorithm validation** for supported algorithms
+- 📝 **Detailed upgrade reasons** in verify response
+- ⏱️ **Timing information** for debugging
+
+### Enhanced
+- 🔧 More detailed verification response with metadata
+- 📚 Better error messages with suggestions
+- 🔄 Backward compatibility with v1 passports
+- ⚡ Performance improvements in hashWithSalt
+
+### Fixed
+- 🐛 Timing attack protection improvements
+- 🔒 Better input validation
+
+## [1.0.3] - 2026-02-16
+- Initial release with core functionality

package/index.d.ts

@@ -0,0 +1,122 @@
+declare module 'inslash' {
+    export interface HashOptions {
+        saltLength?: number;
+        hashLength?: number;
+        iterations?: number;
+        algorithm?: 'sha256' | 'sha512' | 'sha384';
+        encoding?: 'hex' | 'base64' | 'base64url' | 'latin1';
+    }
+
+    export interface HashResult {
+        passport: string;
+        algorithm: string;
+        iterations: number;
+        saltLength: number;
+        hashLength: number;
+        salt: string;
+        hash: string;
+        encoding: string;
+        history: Array<{
+            date: string;
+            algorithm: string;
+            iterations: number;
+            encoding?: string;
+        }>;
+    }
+
+    export interface VerifyResult {
+        valid: boolean;
+        needsUpgrade: boolean;
+        upgradeReasons?: string[];
+        upgradedPassport: string | null;
+        upgradedMetadata: {
+            algorithm: string;
+            iterations: number;
+            encoding: string;
+        } | null;
+        metadata: {
+            algorithm: string;
+            iterations: number;
+            encoding: string;
+            hashLength: number;
+            saltLength: number;
+        };
+    }
+
+    export interface InspectResult {
+        valid: boolean;
+        algorithm?: string;
+        iterations?: number;
+        saltLength?: number;
+        hashLength?: number;
+        salt?: string;
+        hash?: string;
+        history?: any[];
+        encoding?: string;
+        error?: string;
+    }
+
+    export interface CompareResult {
+        sameAlgorithm: boolean;
+        sameIterations: boolean;
+        sameSalt: boolean;
+        sameHash: boolean;
+        sameEncoding: boolean;
+        完全相同: boolean;
+        error?: string;
+    }
+
+    export interface SecurityEstimate {
+        score: number;
+        level: 'Excellent' | 'Strong' | 'Good' | 'Fair' | 'Weak' | 'Invalid';
+        recommendations: string[];
+        metadata: {
+            algorithm: string;
+            iterations: number;
+            saltLength: number;
+            hashLength: number;
+        };
+        error?: string;
+    }
+
+    export interface ApiKeyOptions {
+        prefix?: string;
+        length?: number;
+        encoding?: 'hex' | 'base64' | 'base64url';
+    }
+
+    export function hash(
+        value: string,
+        secret: string,
+        options?: HashOptions
+    ): Promise<HashResult>;
+
+    export function verify(
+        value: string,
+        passport: string,
+        secret: string,
+        options?: Partial<HashOptions>
+    ): Promise<VerifyResult>;
+
+    export function encodePassport(meta: any): string;
+    export function decodePassport(passport: string): any;
+    
+    // New functions
+    export function batchVerify(
+        values: string[],
+        passport: string,
+        secret: string,
+        options?: Partial<HashOptions>
+    ): Promise<Array<{ value: string; valid: boolean; needsUpgrade?: boolean; error?: string }>>;
+
+    export function inspectPassport(passport: string): InspectResult;
+    export function comparePassports(passport1: string, passport2: string): CompareResult;
+    export function estimateSecurity(passport: string): SecurityEstimate;
+    export function generateApiKey(options?: ApiKeyOptions): string;
+
+    // Constants
+    export const DEFAULTS: Required<HashOptions>;
+    export const SUPPORTED_ALGORITHMS: string[];
+    export const SUPPORTED_ENCODINGS: string[];
+    export const VERSION: string;
+}

package/index.js

@@ -4,27 +4,54 @@ const DEFAULTS = {
     saltLength: 16,
     hashLength: 32,
     iterations: 100_000,
-    algorithm: "sha256"
+    algorithm: "sha256",
+    encoding: "hex" // New: support for different encodings
 };
 
+const SUPPORTED_ALGORITHMS = ["sha256", "sha512", "sha384"];
+const SUPPORTED_ENCODINGS = ["hex", "base64", "base64url", "latin1"];
+
 const createSalt = (length) => crypto.randomBytes(length).toString("hex");
 
+// New: Generate a secure API key
+const generateApiKey = (options = {}) => {
+    const {
+        prefix = "inslash",
+        length = 32,
+        encoding = "hex"
+    } = options;
+    
+    const random = crypto.randomBytes(length).toString(encoding);
+    return prefix ? `${prefix}_${random}` : random;
+};
+
+// New: Hash with timing attack protection info
 const hashWithSalt = async (value, salt, secret, options) => {
-    const { iterations, hashLength, algorithm } = options;
+    const { iterations, hashLength, algorithm, encoding = "hex" } = options;
     let data = value + salt;
     let digest = Buffer.from(data);
 
+    console.time(`Hash operation (${iterations} iterations)`);
     for (let i = 0; i < iterations; i++) {
         digest = crypto.createHmac(algorithm, secret).update(digest).digest();
     }
+    console.timeEnd(`Hash operation (${iterations} iterations)`);
 
-    return digest.toString("hex").slice(0, hashLength);
+    const result = digest.toString(encoding).slice(0, hashLength);
+    
+    return {
+        hash: result,
+        timing: iterations, // For informational purposes
+        algorithm
+    };
 };
 
+// Enhanced: Passport encoding with versioning
 const encodePassport = (meta) => {
     const history = Buffer.from(JSON.stringify(meta.history || [])).toString("base64");
-    return [
+    const parts = [
         "$inslash",
+        meta.version || "1",
         meta.algorithm,
         meta.iterations,
         meta.saltLength,
@@ -32,45 +59,89 @@ const encodePassport = (meta) => {
         meta.salt,
         meta.hash,
         history
-    ].join("$");
+    ];
+    
+    // Add optional metadata if present
+    if (meta.encoding) parts.push(meta.encoding);
+    
+    return parts.join("$");
 };
 
+// Enhanced: Decode with backward compatibility
 const decodePassport = (passport) => {
     const parts = passport.split("$");
     if (parts[1] !== "inslash") throw new Error("Invalid passport format");
-    const [ , , algorithm, iterations, saltLength, hashLength, salt, hash, history ] = parts;
-    return {
-        algorithm,
-        iterations: Number(iterations),
-        saltLength: Number(saltLength),
-        hashLength: Number(hashLength),
-        salt,
-        hash,
-        history: JSON.parse(Buffer.from(history, "base64").toString())
-    };
+    
+    // Check version (new format includes version at index 2)
+    const version = parts[2] || "1";
+    
+    if (version === "1") {
+        // Legacy format
+        const [ , , algorithm, iterations, saltLength, hashLength, salt, hash, history ] = parts;
+        return {
+            version: "1",
+            algorithm,
+            iterations: Number(iterations),
+            saltLength: Number(saltLength),
+            hashLength: Number(hashLength),
+            salt,
+            hash,
+            history: JSON.parse(Buffer.from(history, "base64").toString())
+        };
+    } else {
+        // New format with encoding
+        const [ , , , algorithm, iterations, saltLength, hashLength, salt, hash, history, encoding ] = parts;
+        return {
+            version,
+            algorithm,
+            iterations: Number(iterations),
+            saltLength: Number(saltLength),
+            hashLength: Number(hashLength),
+            salt,
+            hash,
+            history: JSON.parse(Buffer.from(history, "base64").toString()),
+            encoding: encoding || "hex"
+        };
+    }
 };
 
+// Enhanced: Hash function with more options
 const hash = async (value, secret, opts = {}) => {
     if (!secret) throw new Error("Secret key is required");
     if (typeof value !== "string" || !value) throw new Error("Value to hash must be a non-empty string");
+    
+    // Validate algorithm
+    if (opts.algorithm && !SUPPORTED_ALGORITHMS.includes(opts.algorithm)) {
+        throw new Error(`Unsupported algorithm: ${opts.algorithm}. Supported: ${SUPPORTED_ALGORITHMS.join(", ")}`);
+    }
+    
+    // Validate encoding
+    if (opts.encoding && !SUPPORTED_ENCODINGS.includes(opts.encoding)) {
+        throw new Error(`Unsupported encoding: ${opts.encoding}. Supported: ${SUPPORTED_ENCODINGS.join(", ")}`);
+    }
+    
     const options = { ...DEFAULTS, ...opts };
     const salt = createSalt(options.saltLength);
     const pepper = process.env.HASH_PEPPER || "";
     const valueWithPepper = value + pepper;
-    const hashed = await hashWithSalt(valueWithPepper, salt, secret, options);
+    
+    const { hash: hashed } = await hashWithSalt(valueWithPepper, salt, secret, options);
 
     const meta = {
+        version: "2",
         algorithm: options.algorithm,
         iterations: options.iterations,
         saltLength: options.saltLength,
         hashLength: options.hashLength,
         salt,
         hash: hashed,
+        encoding: options.encoding,
         history: [
             {
                 date: new Date().toISOString(),
                 algorithm: options.algorithm,
-                iterations: options.iterations
+                iterations: options.iterations,
+                encoding: options.encoding
             }
         ]
     };
@@ -81,6 +152,7 @@ const hash = async (value, secret, opts = {}) => {
     };
 };
 
+// Enhanced: Verify with more detailed response
 const verify = async (value, passport, secret, opts = {}) => {
     const meta = decodePassport(passport);
     const options = {
@@ -88,37 +160,227 @@ const verify = async (value, passport, secret, opts = {}) => {
         iterations: meta.iterations,
         saltLength: meta.saltLength,
         hashLength: meta.hashLength,
+        encoding: meta.encoding || "hex",
         ...opts
     };
+    
     const pepper = process.env.HASH_PEPPER || "";
     const valueWithPepper = value + pepper;
-    const computed = await hashWithSalt(valueWithPepper, meta.salt, secret, options);
-    const valid = crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(meta.hash));
+    
+    const { hash: computed } = await hashWithSalt(valueWithPepper, meta.salt, secret, options);
+    
+    // Use timing-safe comparison
+    const valid = crypto.timingSafeEqual(
+        Buffer.from(computed, options.encoding),
+        Buffer.from(meta.hash, meta.encoding || "hex")
+    );
+    
     let needsUpgrade = false;
-    if (opts.iterations && opts.iterations > meta.iterations) needsUpgrade = true;
-    if (opts.algorithm && opts.algorithm !== meta.algorithm) needsUpgrade = true;
+    let upgradeReasons = [];
+    
+    if (opts.iterations && opts.iterations > meta.iterations) {
+        needsUpgrade = true;
+        upgradeReasons.push(`iterations (${meta.iterations} -> ${opts.iterations})`);
+    }
+    if (opts.algorithm && opts.algorithm !== meta.algorithm) {
+        needsUpgrade = true;
+        upgradeReasons.push(`algorithm (${meta.algorithm} -> ${opts.algorithm})`);
+    }
+    if (opts.encoding && opts.encoding !== meta.encoding) {
+        needsUpgrade = true;
+        upgradeReasons.push(`encoding (${meta.encoding} -> ${opts.encoding})`);
+    }
+    
     let upgradedPassport = null;
+    let upgradedMetadata = null;
+    
     if (valid && needsUpgrade) {
         const newMeta = { ...meta, ...opts };
-        newMeta.history = meta.history.concat([
+        newMeta.history = (meta.history || []).concat([
             {
                 date: new Date().toISOString(),
                 algorithm: opts.algorithm || meta.algorithm,
-                iterations: opts.iterations || meta.iterations
+                iterations: opts.iterations || meta.iterations,
+                encoding: opts.encoding || meta.encoding,
+                reason: "security upgrade"
             }
         ]);
+        
         const newSalt = createSalt(newMeta.saltLength);
-        const newHash = await hashWithSalt(valueWithPepper, newSalt, secret, newMeta);
+        const { hash: newHash } = await hashWithSalt(valueWithPepper, newSalt, secret, newMeta);
+        
         newMeta.salt = newSalt;
         newMeta.hash = newHash;
+        newMeta.version = "2";
+        
         upgradedPassport = encodePassport(newMeta);
+        upgradedMetadata = {
+            algorithm: newMeta.algorithm,
+            iterations: newMeta.iterations,
+            encoding: newMeta.encoding
+        };
+    }
+    
+    return {
+        valid,
+        needsUpgrade,
+        upgradeReasons,
+        upgradedPassport,
+        upgradedMetadata,
+        metadata: {
+            algorithm: meta.algorithm,
+            iterations: meta.iterations,
+            encoding: meta.encoding,
+            hashLength: meta.hashLength,
+            saltLength: meta.saltLength
+        }
+    };
+};
+
+// New: Batch verify multiple values against same passport
+const batchVerify = async (values, passport, secret, opts = {}) => {
+    const results = [];
+    for (const value of values) {
+        try {
+            const result = await verify(value, passport, secret, opts);
+            results.push({
+                value,
+                valid: result.valid,
+                needsUpgrade: result.needsUpgrade
+            });
+        } catch (error) {
+            results.push({
+                value,
+                error: error.message,
+                valid: false
+            });
+        }
     }
-    return { valid, needsUpgrade, upgradedPassport };
+    return results;
 };
 
+// New: Extract metadata without verification
+const inspectPassport = (passport) => {
+    try {
+        const meta = decodePassport(passport);
+        return {
+            valid: true,
+            ...meta,
+            history: meta.history || []
+        };
+    } catch (error) {
+        return {
+            valid: false,
+            error: error.message
+        };
+    }
+};
+
+// New: Compare two passports
+const comparePassports = (passport1, passport2) => {
+    try {
+        const meta1 = decodePassport(passport1);
+        const meta2 = decodePassport(passport2);
+        
+        return {
+            sameAlgorithm: meta1.algorithm === meta2.algorithm,
+            sameIterations: meta1.iterations === meta2.iterations,
+            sameSalt: meta1.salt === meta2.salt,
+            sameHash: meta1.hash === meta2.hash,
+            sameEncoding: (meta1.encoding || "hex") === (meta2.encoding || "hex"),
+           完全相同: meta1.hash === meta2.hash && meta1.salt === meta2.salt
+        };
+    } catch (error) {
+        return {
+            error: error.message,
+            identical: false
+        };
+    }
+};
+
+// New: Estimate security strength
+const estimateSecurity = (passport) => {
+    try {
+        const meta = decodePassport(passport);
+        const now = new Date();
+        const year = now.getFullYear();
+        
+        // Rough estimate of security level
+        let score = 0;
+        let recommendations = [];
+        
+        // Algorithm score
+        if (meta.algorithm === "sha512") score += 40;
+        else if (meta.algorithm === "sha384") score += 35;
+        else if (meta.algorithm === "sha256") score += 30;
+        
+        // Iterations score (based on year)
+        if (meta.iterations >= 300000) score += 40;
+        else if (meta.iterations >= 200000) score += 35;
+        else if (meta.iterations >= 150000) score += 30;
+        else if (meta.iterations >= 100000) score += 25;
+        else {
+            score += 15;
+            recommendations.push("Increase iterations (current: " + meta.iterations + ")");
+        }
+        
+        // Salt length
+        if (meta.saltLength >= 32) score += 20;
+        else if (meta.saltLength >= 16) score += 15;
+        else {
+            score += 5;
+            recommendations.push("Increase salt length (current: " + meta.saltLength + ")");
+        }
+        
+        // Hash length
+        if (meta.hashLength >= 32) score += 10;
+        
+        let level = "Weak";
+        if (score >= 90) level = "Excellent";
+        else if (score >= 75) level = "Strong";
+        else if (score >= 60) level = "Good";
+        else if (score >= 40) level = "Fair";
+        
+        return {
+            score,
+            level,
+            recommendations,
+            metadata: {
+                algorithm: meta.algorithm,
+                iterations: meta.iterations,
+                saltLength: meta.saltLength,
+                hashLength: meta.hashLength
+            }
+        };
+    } catch (error) {
+        return {
+            error: error.message,
+            score: 0,
+            level: "Invalid"
+        };
+    }
+};
+
+// Export everything
 module.exports = {
+    // Core functions
     hash,
     verify,
     encodePassport,
-    decodePassport
-};
+    decodePassport,
+    
+    // New enhanced functions
+    batchVerify,
+    inspectPassport,
+    comparePassports,
+    estimateSecurity,
+    generateApiKey,
+    
+    // Utilities
+    DEFAULTS,
+    SUPPORTED_ALGORITHMS,
+    SUPPORTED_ENCODINGS,
+    
+    // Version info
+    VERSION: "1.1.0"
+};

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "inslash",
-  "version": "1.0.3",
-  "description": "A modern, upgradeable, and secure password hashing utility with passport encoding and hash ancestry.",
+  "version": "1.1.0",
+  "description": "A modern, upgradeable, and secure password hashing utility with passport encoding, hash ancestry, and comprehensive security features.",
   "main": "index.js",
-  "types": "index.d.ts", 
+  "types": "index.d.ts",
   "scripts": {
-    "test": "node cstest.js"
+    "test": "node test.js",
+    "benchmark": "node benchmark.js",
+    "prepublishOnly": "npm test"
   },
   "keywords": [
     "password",
@@ -16,7 +18,12 @@
     "pepper",
     "upgradeable",
     "passport",
-    "nodejs"
+    "nodejs",
+    "authentication",
+    "hashing",
+    "hmac",
+    "key-derivation",
+    "security-tools"
   ],
   "author": "Reshuk Sapkota",
   "license": "MIT",
@@ -30,10 +37,20 @@
   "homepage": "https://github.com/reshuk-code/inslash#readme",
   "files": [
     "index.js",
+    "index.d.ts",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=16"
+  },
+  "devDependencies": {
+    "concurrently": "^9.2.1"
+  },
+  "dependencies": {},
+  "funding": {
+    "type": "individual",
+    "url": "https://github.com/sponsors/reshuk-code"
   }
 }