inslash 1.1.1 → 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,
@@ -108,11 +117,90 @@ const decodePassport = (passport) => {
     }
 };
 
-// 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(", ")}`);
@@ -155,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,
@@ -372,6 +481,9 @@ module.exports = {
     encodePassport,
     decodePassport,
 
+    // API configuration
+    configure,
+
     // New enhanced functions
     batchVerify,
     inspectPassport,
@@ -385,5 +497,5 @@ module.exports = {
     SUPPORTED_ENCODINGS,
 
     // Version info
-    VERSION: "1.1.0"
+    VERSION: "1.2.0"
 };

package/package.json

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