inslash 1.1.0 → 1.2.1

package/README.md

@@ -35,8 +35,44 @@ const verifyResult = await verify("myPassword", result.passport, secret);
 console.log(verifyResult.valid); // true or false
 ```
 
+## API Mode (Hosted Hashing)
+
+`inslash` can connect to a hosted API for password hashing, with automatic fallback to local crypto if the API is unavailable.
+
+### Setup
+
+```js
+const inslash = require('inslash');
+
+// Configure once with your API key
+inslash.configure({
+    apiKey: 'inslash_your_api_key_here',
+    apiUrl: 'https://api.inslash.com' // or http://localhost:3001 for testing
+});
+
+// Now hash() and verify() automatically use the API
+const result = await inslash.hash('myPassword');
+const verified = await inslash.verify('myPassword', result.passport);
+```
+
+### How It Works
+
+1. **API First**: When configured, `hash()` and `verify()` call your hosted API
+2. **Silent Fallback**: If the API is down or slow, falls back to local crypto automatically
+3. **Zero Config Local**: If not configured, uses local crypto only (no secret needed from you)
+
+### Get an API Key
+
+Visit [https://inslash.com](https://inslash.com) to create a project and get your API key.
+
 ## API
 
+### `configure(options)`
+- `options.apiKey` (string): Your Inslash API key.
+- `options.apiUrl` (string): API endpoint URL.
+- **Returns:** Current configuration object.
+- **Note:** Call this once before using `hash()` or `verify()` to enable API mode.
+
 ### `async hash(value, secret, options?)`
 - `value` (string): The value to hash.
 - `secret` (string): Secret key for HMAC.

package/index.js

@@ -1,4 +1,13 @@
 const crypto = require("crypto");
+const https = require("https");
+const http = require("http");
+
+// Module-level configuration for API mode
+let CONFIG = {
+    apiKey: null,
+    apiUrl: null,
+    strictMode: false // If true, throw error instead of falling back to local
+};
 
 const DEFAULTS = {
     saltLength: 16,
@@ -20,7 +29,7 @@ const generateApiKey = (options = {}) => {
         length = 32,
         encoding = "hex"
     } = options;
-    
+
     const random = crypto.randomBytes(length).toString(encoding);
     return prefix ? `${prefix}_${random}` : random;
 };
@@ -38,7 +47,7 @@ const hashWithSalt = async (value, salt, secret, options) => {
     console.timeEnd(`Hash operation (${iterations} iterations)`);
 
     const result = digest.toString(encoding).slice(0, hashLength);
-    
+
     return {
         hash: result,
         timing: iterations, // For informational purposes
@@ -60,10 +69,10 @@ const encodePassport = (meta) => {
         meta.hash,
         history
     ];
-    
+
     // Add optional metadata if present
     if (meta.encoding) parts.push(meta.encoding);
-    
+
     return parts.join("$");
 };
 
@@ -71,13 +80,15 @@ const encodePassport = (meta) => {
 const decodePassport = (passport) => {
     const parts = passport.split("$");
     if (parts[1] !== "inslash") throw new Error("Invalid passport format");
-    
-    // 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;
+
+    // Detect format: check if parts[2] is a numeric version or an algorithm name
+    // Legacy format: $inslash$algorithm$iterations$...
+    // New format: $inslash$version$algorithm$iterations$...
+    const isLegacyFormat = SUPPORTED_ALGORITHMS.includes(parts[2]);
+
+    if (isLegacyFormat) {
+        // Legacy format without explicit version
+        const [, , algorithm, iterations, saltLength, hashLength, salt, hash, history] = parts;
         return {
             version: "1",
             algorithm,
@@ -86,11 +97,12 @@ const decodePassport = (passport) => {
             hashLength: Number(hashLength),
             salt,
             hash,
-            history: JSON.parse(Buffer.from(history, "base64").toString())
+            history: history ? JSON.parse(Buffer.from(history, "base64").toString()) : []
         };
     } else {
-        // New format with encoding
-        const [ , , , algorithm, iterations, saltLength, hashLength, salt, hash, history, encoding ] = parts;
+        // New format with explicit version
+        const version = parts[2];
+        const [, , , algorithm, iterations, saltLength, hashLength, salt, hash, history, encoding] = parts;
         return {
             version,
             algorithm,
@@ -99,32 +111,111 @@ const decodePassport = (passport) => {
             hashLength: Number(hashLength),
             salt,
             hash,
-            history: JSON.parse(Buffer.from(history, "base64").toString()),
+            history: history ? JSON.parse(Buffer.from(history, "base64").toString()) : [],
             encoding: encoding || "hex"
         };
     }
 };
 
-// Enhanced: Hash function with more options
+// Helper: Call API endpoint
+const callAPI = (endpoint, body) => {
+    return new Promise((resolve, reject) => {
+        const url = new URL(endpoint, CONFIG.apiUrl);
+        const client = url.protocol === 'https:' ? https : http;
+
+        const postData = JSON.stringify(body);
+        const options = {
+            hostname: url.hostname,
+            port: url.port || (url.protocol === 'https:' ? 443 : 80),
+            path: url.pathname,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': CONFIG.apiKey,
+                'Content-Length': Buffer.byteLength(postData)
+            },
+            timeout: 10000
+        };
+
+        const req = client.request(options, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                if (res.statusCode >= 200 && res.statusCode < 300) {
+                    try {
+                        resolve(JSON.parse(data));
+                    } catch (e) {
+                        reject(new Error('Invalid JSON response'));
+                    }
+                } else {
+                    reject(new Error(`API error: ${res.statusCode}`));
+                }
+            });
+        });
+
+        req.on('error', reject);
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error('API request timeout'));
+        });
+
+        req.write(postData);
+        req.end();
+    });
+};
+
+// Configure API mode
+const configure = (options = {}) => {
+    const { apiKey, apiUrl, strictMode } = options;
+
+    if (apiKey) CONFIG.apiKey = apiKey;
+    if (apiUrl) CONFIG.apiUrl = apiUrl;
+    if (typeof strictMode !== 'undefined') CONFIG.strictMode = strictMode;
+
+    return CONFIG;
+};
+
+// Enhanced: Hash function with more options and API support
 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");
-    
+
+    // API Mode: Try API first if configured
+    if (CONFIG.apiKey && CONFIG.apiUrl) {
+        try {
+            const apiResult = await callAPI('/api/hash', {
+                value,
+                secret,
+                options: opts
+            });
+            return apiResult;
+        } catch (error) {
+            // In strict mode, throw the error instead of falling back
+            if (CONFIG.strictMode) {
+                throw new Error(`API hash failed: ${error.message}`);
+            }
+            // Silent fallback to local crypto
+            console.warn('API hash failed, falling back to local:', error.message);
+        }
+    }
+
+    // Local Mode: Original crypto implementation
+    if (!secret) throw new Error("Secret key is required");
+
     // 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 { hash: hashed } = await hashWithSalt(valueWithPepper, salt, secret, options);
 
     const meta = {
@@ -152,8 +243,29 @@ const hash = async (value, secret, opts = {}) => {
     };
 };
 
-// Enhanced: Verify with more detailed response
+// Enhanced: Verify with more detailed response and API support
 const verify = async (value, passport, secret, opts = {}) => {
+    // API Mode: Try API first if configured
+    if (CONFIG.apiKey && CONFIG.apiUrl) {
+        try {
+            const apiResult = await callAPI('/api/verify', {
+                value,
+                passport,
+                secret,
+                options: opts
+            });
+            return apiResult;
+        } catch (error) {
+            // In strict mode, throw the error instead of falling back
+            if (CONFIG.strictMode) {
+                throw new Error(`API verify failed: ${error.message}`);
+            }
+            // Silent fallback to local crypto
+            console.warn('API verify failed, falling back to local:', error.message);
+        }
+    }
+
+    // Local Mode: Original crypto implementation
     const meta = decodePassport(passport);
     const options = {
         algorithm: meta.algorithm,
@@ -163,21 +275,21 @@ const verify = async (value, passport, secret, opts = {}) => {
         encoding: meta.encoding || "hex",
         ...opts
     };
-    
+
     const pepper = process.env.HASH_PEPPER || "";
     const valueWithPepper = value + pepper;
-    
+
     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;
     let upgradeReasons = [];
-    
+
     if (opts.iterations && opts.iterations > meta.iterations) {
         needsUpgrade = true;
         upgradeReasons.push(`iterations (${meta.iterations} -> ${opts.iterations})`);
@@ -190,10 +302,10 @@ const verify = async (value, passport, secret, opts = {}) => {
         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([
@@ -205,14 +317,14 @@ const verify = async (value, passport, secret, opts = {}) => {
                 reason: "security upgrade"
             }
         ]);
-        
+
         const newSalt = createSalt(newMeta.saltLength);
         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,
@@ -220,7 +332,7 @@ const verify = async (value, passport, secret, opts = {}) => {
             encoding: newMeta.encoding
         };
     }
-    
+
     return {
         valid,
         needsUpgrade,
@@ -281,14 +393,14 @@ 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
+            完全相同: meta1.hash === meta2.hash && meta1.salt === meta2.salt
         };
     } catch (error) {
         return {
@@ -304,16 +416,16 @@ const estimateSecurity = (passport) => {
         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;
@@ -323,7 +435,7 @@ const estimateSecurity = (passport) => {
             score += 15;
             recommendations.push("Increase iterations (current: " + meta.iterations + ")");
         }
-        
+
         // Salt length
         if (meta.saltLength >= 32) score += 20;
         else if (meta.saltLength >= 16) score += 15;
@@ -331,16 +443,16 @@ const estimateSecurity = (passport) => {
             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,
@@ -368,19 +480,22 @@ module.exports = {
     verify,
     encodePassport,
     decodePassport,
-    
+
+    // API configuration
+    configure,
+
     // New enhanced functions
     batchVerify,
     inspectPassport,
     comparePassports,
     estimateSecurity,
     generateApiKey,
-    
+
     // Utilities
     DEFAULTS,
     SUPPORTED_ALGORITHMS,
     SUPPORTED_ENCODINGS,
-    
+
     // Version info
-    VERSION: "1.1.0"
+    VERSION: "1.2.0"
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inslash",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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",