@aleph-ai/tinyaleph 1.5.7 → 1.6.1

package/examples/crypto/02-key-derivation.js

@@ -0,0 +1,210 @@
+/**
+ * @example Key Derivation
+ * @description Derive cryptographic keys from passwords using TinyAleph
+ * 
+ * Key derivation functions (KDFs) create strong cryptographic keys from
+ * potentially weak passwords. TinyAleph's deriveKey function:
+ * - Uses salt to prevent rainbow table attacks
+ * - Supports configurable iterations for work factor
+ * - Produces keys of specified length
+ */
+
+const { CryptographicBackend } = require('../../modular');
+
+// ===========================================
+// SETUP
+// ===========================================
+
+const backend = new CryptographicBackend({ dimension: 32 });
+
+console.log('TinyAleph Key Derivation Example');
+console.log('=================================\n');
+
+// ===========================================
+// BASIC KEY DERIVATION
+// ===========================================
+
+console.log('Basic Key Derivation:');
+console.log('-'.repeat(50) + '\n');
+
+var password = 'MySecretPassword123';
+var salt = 'randomsalt12345678';
+var keyLength = 32;
+var iterations = 1000;
+
+console.log('Input:');
+console.log('  Password: ' + password);
+console.log('  Salt: ' + salt);
+console.log('  Key Length: ' + keyLength + ' bytes');
+console.log('  Iterations: ' + iterations);
+
+var derivedKey = backend.deriveKey(password, salt, keyLength, iterations);
+console.log('\nDerived Key (hex): ' + derivedKey.toString('hex'));
+
+// ===========================================
+// SALT IMPORTANCE
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Salt Importance:');
+console.log('='.repeat(50) + '\n');
+
+console.log('Same password with different salts produces different keys:\n');
+
+var salts = ['salt_user_1', 'salt_user_2', 'salt_user_3'];
+
+for (var i = 0; i < salts.length; i++) {
+    var s = salts[i];
+    var key = backend.deriveKey(password, s, 32, 1000);
+    console.log('  Salt: "' + s + '"');
+    console.log('  Key:  ' + key.toString('hex').substring(0, 40) + '...\n');
+}
+
+// ===========================================
+// ITERATION COUNT
+// ===========================================
+
+console.log('='.repeat(50));
+console.log('Iteration Count (Work Factor):');
+console.log('='.repeat(50) + '\n');
+
+console.log('Higher iterations = more secure but slower:\n');
+
+var iterCounts = [100, 1000, 10000];
+
+for (var i = 0; i < iterCounts.length; i++) {
+    var count = iterCounts[i];
+    var start = Date.now();
+    var key = backend.deriveKey(password, salt, 32, count);
+    var elapsed = Date.now() - start;
+    
+    console.log('  Iterations: ' + count);
+    console.log('  Time: ' + elapsed + 'ms');
+    console.log('  Key: ' + key.toString('hex').substring(0, 32) + '...\n');
+}
+
+// ===========================================
+// KEY LENGTH VARIATIONS
+// ===========================================
+
+console.log('='.repeat(50));
+console.log('Variable Key Lengths:');
+console.log('='.repeat(50) + '\n');
+
+console.log('Derive keys of different lengths for different purposes:\n');
+
+var keyPurposes = [
+    { name: 'AES-128', length: 16 },
+    { name: 'AES-256', length: 32 },
+    { name: 'HMAC-SHA256', length: 32 },
+    { name: 'ChaCha20', length: 32 }
+];
+
+for (var i = 0; i < keyPurposes.length; i++) {
+    var purpose = keyPurposes[i];
+    var key = backend.deriveKey(password, salt, purpose.length, 1000);
+    console.log('  ' + purpose.name + ' (' + purpose.length + ' bytes):');
+    console.log('  ' + key.toString('hex'));
+    console.log('');
+}
+
+// ===========================================
+// MULTIPLE KEYS FROM ONE PASSWORD
+// ===========================================
+
+console.log('='.repeat(50));
+console.log('Deriving Multiple Keys:');
+console.log('='.repeat(50) + '\n');
+
+console.log('Use different salts or purposes to derive multiple keys:\n');
+
+function deriveMultipleKeys(password, masterSalt, keySpecs) {
+    var keys = {};
+    for (var i = 0; i < keySpecs.length; i++) {
+        var spec = keySpecs[i];
+        var specificSalt = masterSalt + ':' + spec.purpose;
+        keys[spec.purpose] = backend.deriveKey(password, specificSalt, spec.length, 1000);
+    }
+    return keys;
+}
+
+var keySpecs = [
+    { purpose: 'encryption', length: 32 },
+    { purpose: 'authentication', length: 32 },
+    { purpose: 'signing', length: 64 }
+];
+
+var keys = deriveMultipleKeys(password, 'master_salt', keySpecs);
+
+for (var purpose in keys) {
+    if (keys.hasOwnProperty(purpose)) {
+        console.log('  ' + purpose + ': ' + keys[purpose].toString('hex').substring(0, 40) + '...');
+    }
+}
+
+// ===========================================
+// PASSWORD STRENGTH
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Password Strength Consideration:');
+console.log('='.repeat(50) + '\n');
+
+console.log('Even with KDF, use strong passwords:\n');
+
+var testPasswords = [
+    { pwd: '123456', strength: 'Very Weak' },
+    { pwd: 'password', strength: 'Weak' },
+    { pwd: 'MyP@ss!', strength: 'Medium' },
+    { pwd: 'Tr0ub4dor&3', strength: 'Strong' },
+    { pwd: 'correct-horse-battery-staple', strength: 'Very Strong' }
+];
+
+for (var i = 0; i < testPasswords.length; i++) {
+    var test = testPasswords[i];
+    var key = backend.deriveKey(test.pwd, salt, 32, 1000);
+    console.log('  "' + test.pwd + '" (' + test.strength + ')');
+    console.log('  Key: ' + key.toString('hex').substring(0, 32) + '...\n');
+}
+
+// ===========================================
+// KEY VERIFICATION
+// ===========================================
+
+console.log('='.repeat(50));
+console.log('Key Verification:');
+console.log('='.repeat(50) + '\n');
+
+console.log('Store salt and verify derived key matches:\n');
+
+// "Store" the salt and a verification hash
+var storedSalt = 'user_specific_salt_123';
+var masterPassword = 'UserMasterPassword';
+var storedVerifier = backend.deriveKey(masterPassword, storedSalt + ':verify', 16, 1000);
+
+console.log('Stored Salt: ' + storedSalt);
+console.log('Stored Verifier: ' + storedVerifier.toString('hex') + '\n');
+
+// Attempt verification
+var attempts = ['UserMasterPassword', 'WrongPassword', 'usermasterpassword'];
+
+for (var i = 0; i < attempts.length; i++) {
+    var attempt = attempts[i];
+    var computedVerifier = backend.deriveKey(attempt, storedSalt + ':verify', 16, 1000);
+    var isValid = computedVerifier.toString('hex') === storedVerifier.toString('hex');
+    
+    console.log('  "' + attempt + '" -> ' + (isValid ? 'VALID' : 'INVALID'));
+}
+
+// ===========================================
+// KEY TAKEAWAYS
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('KEY TAKEAWAYS:');
+console.log('1. Always use a unique salt per user/purpose');
+console.log('2. Increase iterations for stronger security');
+console.log('3. Derive multiple keys using different salts');
+console.log('4. Higher iterations = more time = harder to brute force');
+console.log('5. Key derivation cannot fix weak passwords');
+console.log('6. Store salt with derived key (salt is not secret)');

package/examples/crypto/03-hmac.js

@@ -0,0 +1,229 @@
+/**
+ * @example HMAC (Hash-based Message Authentication Code)
+ * @description Create message authentication codes with TinyAleph
+ * 
+ * HMAC combines a secret key with a message to create an authentication code:
+ * - Verifies message integrity (not tampered)
+ * - Verifies message authenticity (from expected sender)
+ * - Uses a shared secret key
+ */
+
+const { CryptographicBackend } = require('../../modular');
+
+// ===========================================
+// SETUP
+// ===========================================
+
+const backend = new CryptographicBackend({ dimension: 32 });
+
+console.log('TinyAleph HMAC Example');
+console.log('======================\n');
+
+// ===========================================
+// HMAC IMPLEMENTATION
+// ===========================================
+
+function hmac(key, message, outputLength) {
+    outputLength = outputLength || 32;
+    
+    // HMAC uses two passes with padded keys
+    var blockSize = 64;
+    
+    // If key is too long, hash it first
+    if (key.length > blockSize) {
+        key = backend.hash(key, blockSize).toString('hex');
+    }
+    
+    // Pad key to block size
+    while (key.length < blockSize) {
+        key += '\x00';
+    }
+    
+    // Create inner and outer padded keys
+    var ipad = '';
+    var opad = '';
+    for (var i = 0; i < blockSize; i++) {
+        var keyChar = key.charCodeAt(i);
+        ipad += String.fromCharCode(keyChar ^ 0x36);
+        opad += String.fromCharCode(keyChar ^ 0x5c);
+    }
+    
+    // Inner hash: hash(ipad || message)
+    var innerData = ipad + message;
+    var innerHash = backend.hash(innerData, outputLength);
+    
+    // Outer hash: hash(opad || inner_hash)
+    var outerData = opad + innerHash.toString('hex');
+    var hmacResult = backend.hash(outerData, outputLength);
+    
+    return hmacResult;
+}
+
+// ===========================================
+// BASIC HMAC
+// ===========================================
+
+console.log('Basic HMAC:');
+console.log('-'.repeat(50) + '\n');
+
+var secretKey = 'my_secret_key_123';
+var message = 'Hello, this is a secret message.';
+
+var mac = hmac(secretKey, message);
+
+console.log('Key:     ' + secretKey);
+console.log('Message: ' + message);
+console.log('HMAC:    ' + mac.toString('hex'));
+
+// ===========================================
+// MESSAGE VERIFICATION
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Message Verification:');
+console.log('='.repeat(50) + '\n');
+
+function verifyMessage(key, message, expectedMac) {
+    var computedMac = hmac(key, message);
+    return computedMac.toString('hex') === expectedMac;
+}
+
+var originalMac = hmac(secretKey, message).toString('hex');
+
+var testCases = [
+    { msg: message, desc: 'Original message' },
+    { msg: message + ' ', desc: 'Message with extra space' },
+    { msg: 'Hello, this is a SECRET message.', desc: 'Modified message' },
+    { msg: 'Completely different message', desc: 'Different message' }
+];
+
+console.log('Testing message integrity:\n');
+
+for (var i = 0; i < testCases.length; i++) {
+    var test = testCases[i];
+    var isValid = verifyMessage(secretKey, test.msg, originalMac);
+    console.log('  ' + test.desc + ': ' + (isValid ? 'VALID' : 'INVALID'));
+}
+
+// ===========================================
+// KEY VERIFICATION
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Key Authentication:');
+console.log('='.repeat(50) + '\n');
+
+console.log('Only the correct key produces matching HMAC:\n');
+
+var keys = [
+    'my_secret_key_123',  // Correct
+    'my_secret_key_124',  // One char different
+    'wrong_key',          // Wrong
+    ''                     // Empty
+];
+
+for (var i = 0; i < keys.length; i++) {
+    var testKey = keys[i];
+    var testMac = hmac(testKey, message);
+    var matches = testMac.toString('hex') === originalMac;
+    console.log('  Key "' + (testKey || '(empty)') + '": ' + (matches ? 'MATCHES' : 'No match'));
+}
+
+// ===========================================
+// API REQUEST SIGNING
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('API Request Signing:');
+console.log('='.repeat(50) + '\n');
+
+function signRequest(apiKey, method, path, body, timestamp) {
+    var payload = method + '\n' + path + '\n' + timestamp + '\n' + (body || '');
+    var signature = hmac(apiKey, payload);
+    return signature.toString('hex');
+}
+
+function verifyRequest(apiKey, method, path, body, timestamp, signature) {
+    var expectedSig = signRequest(apiKey, method, path, body, timestamp);
+    return expectedSig === signature;
+}
+
+var apiKey = 'api_secret_abc123';
+var method = 'POST';
+var path = '/api/users';
+var body = '{"name":"John","email":"john@example.com"}';
+var timestamp = '2024-01-15T12:00:00Z';
+
+var signature = signRequest(apiKey, method, path, body, timestamp);
+
+console.log('Request Details:');
+console.log('  Method: ' + method);
+console.log('  Path: ' + path);
+console.log('  Body: ' + body);
+console.log('  Timestamp: ' + timestamp);
+console.log('  Signature: ' + signature.substring(0, 32) + '...\n');
+
+console.log('Verification:');
+console.log('  Valid request: ' + verifyRequest(apiKey, method, path, body, timestamp, signature));
+console.log('  Tampered body: ' + verifyRequest(apiKey, method, path, body + 'x', timestamp, signature));
+console.log('  Wrong timestamp: ' + verifyRequest(apiKey, method, path, body, '2024-01-15T12:00:01Z', signature));
+
+// ===========================================
+// WEBHOOK VERIFICATION
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Webhook Signature Verification:');
+console.log('='.repeat(50) + '\n');
+
+// Simulate webhook delivery and verification
+function createWebhook(secret, event, payload) {
+    var payloadStr = JSON.stringify(payload);
+    var signature = hmac(secret, payloadStr);
+    
+    return {
+        headers: {
+            'X-Webhook-Signature': signature.toString('hex'),
+            'X-Webhook-Event': event
+        },
+        body: payloadStr
+    };
+}
+
+function verifyWebhook(secret, webhook) {
+    var expectedSig = hmac(secret, webhook.body).toString('hex');
+    return expectedSig === webhook.headers['X-Webhook-Signature'];
+}
+
+var webhookSecret = 'whsec_mysecretkey';
+var event = 'payment.completed';
+var payload = { orderId: '12345', amount: 99.99, currency: 'USD' };
+
+var webhook = createWebhook(webhookSecret, event, payload);
+
+console.log('Webhook Received:');
+console.log('  Event: ' + webhook.headers['X-Webhook-Event']);
+console.log('  Signature: ' + webhook.headers['X-Webhook-Signature'].substring(0, 32) + '...');
+console.log('  Body: ' + webhook.body);
+console.log('  Valid: ' + verifyWebhook(webhookSecret, webhook));
+
+// Tampered webhook
+var tamperedWebhook = {
+    headers: webhook.headers,
+    body: '{"orderId":"12345","amount":0.01,"currency":"USD"}'
+};
+console.log('\n  Tampered Body: ' + tamperedWebhook.body);
+console.log('  Tampered Valid: ' + verifyWebhook(webhookSecret, tamperedWebhook));
+
+// ===========================================
+// KEY TAKEAWAYS
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('KEY TAKEAWAYS:');
+console.log('1. HMAC verifies both integrity and authenticity');
+console.log('2. Only holders of the secret key can create valid MACs');
+console.log('3. Any message change invalidates the MAC');
+console.log('4. Use for API signing, webhooks, and data verification');
+console.log('5. Keep the secret key secure and never expose it');
+console.log('6. Use constant-time comparison for verification');

package/examples/crypto/04-file-integrity.js

@@ -0,0 +1,263 @@
+/**
+ * @example File Integrity Verification
+ * @description Verify file integrity using cryptographic hashes
+ * 
+ * File integrity verification ensures files haven't been modified:
+ * - Compute hash of original file
+ * - Store hash securely
+ * - Recompute and compare to detect changes
+ */
+
+const { CryptographicBackend } = require('../../modular');
+
+// ===========================================
+// SETUP
+// ===========================================
+
+const backend = new CryptographicBackend({ dimension: 32 });
+
+console.log('TinyAleph File Integrity Example');
+console.log('=================================\n');
+
+// ===========================================
+// SIMULATED FILE SYSTEM
+// ===========================================
+
+// Simulate files (in real use, you'd read actual files)
+var files = {
+    'config.json': '{"version":"1.0","debug":false,"timeout":30}',
+    'script.js': 'function main() { console.log("Hello"); }\nmain();',
+    'data.txt': 'Important data that must not be modified.\nLine 2.',
+    'readme.md': '# Project\n\nThis is the readme file.'
+};
+
+// ===========================================
+// COMPUTE FILE HASHES
+// ===========================================
+
+console.log('Computing File Hashes:');
+console.log('-'.repeat(50) + '\n');
+
+function hashFile(content) {
+    return backend.hash(content, 32).toString('hex');
+}
+
+var manifest = {};
+
+for (var filename in files) {
+    if (files.hasOwnProperty(filename)) {
+        var hash = hashFile(files[filename]);
+        manifest[filename] = {
+            hash: hash,
+            size: files[filename].length,
+            timestamp: new Date().toISOString()
+        };
+        console.log('  ' + filename.padEnd(15) + ' ' + hash.substring(0, 40) + '...');
+    }
+}
+
+// ===========================================
+// VERIFY FILE INTEGRITY
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Verifying File Integrity:');
+console.log('='.repeat(50) + '\n');
+
+function verifyFile(filename, content, manifest) {
+    if (!manifest[filename]) {
+        return { valid: false, reason: 'File not in manifest' };
+    }
+    
+    var currentHash = hashFile(content);
+    var expectedHash = manifest[filename].hash;
+    
+    if (currentHash === expectedHash) {
+        return { valid: true, reason: 'Hash matches' };
+    } else {
+        return { valid: false, reason: 'Hash mismatch', expected: expectedHash, actual: currentHash };
+    }
+}
+
+console.log('Verification of unchanged files:\n');
+
+for (var filename in files) {
+    if (files.hasOwnProperty(filename)) {
+        var result = verifyFile(filename, files[filename], manifest);
+        console.log('  ' + filename + ': ' + (result.valid ? 'OK' : 'FAILED'));
+    }
+}
+
+// ===========================================
+// DETECT MODIFICATIONS
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Detecting Modifications:');
+console.log('='.repeat(50) + '\n');
+
+// Simulate file modifications
+var modifiedFiles = {
+    'config.json': '{"version":"1.0","debug":true,"timeout":30}',  // Changed debug to true
+    'script.js': 'function main() { console.log("Hello"); }\nmain();',  // Unchanged
+    'data.txt': 'Important data that WAS modified.\nLine 2.',  // Modified
+    'readme.md': '# Project\n\nThis is the readme file.'  // Unchanged
+};
+
+console.log('After modifications:\n');
+
+for (var filename in modifiedFiles) {
+    if (modifiedFiles.hasOwnProperty(filename)) {
+        var result = verifyFile(filename, modifiedFiles[filename], manifest);
+        var status = result.valid ? 'UNCHANGED' : 'MODIFIED';
+        console.log('  ' + filename + ': ' + status);
+    }
+}
+
+// ===========================================
+// DETAILED CHANGE DETECTION
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Detailed Change Analysis:');
+console.log('='.repeat(50) + '\n');
+
+function analyzeChanges(originalFiles, currentFiles, manifest) {
+    var report = {
+        unchanged: [],
+        modified: [],
+        added: [],
+        deleted: []
+    };
+    
+    // Check existing files
+    for (var filename in manifest) {
+        if (manifest.hasOwnProperty(filename)) {
+            if (!currentFiles[filename]) {
+                report.deleted.push(filename);
+            } else {
+                var result = verifyFile(filename, currentFiles[filename], manifest);
+                if (result.valid) {
+                    report.unchanged.push(filename);
+                } else {
+                    report.modified.push({
+                        filename: filename,
+                        originalHash: manifest[filename].hash.substring(0, 16) + '...',
+                        currentHash: hashFile(currentFiles[filename]).substring(0, 16) + '...'
+                    });
+                }
+            }
+        }
+    }
+    
+    // Check for new files
+    for (var filename in currentFiles) {
+        if (currentFiles.hasOwnProperty(filename)) {
+            if (!manifest[filename]) {
+                report.added.push(filename);
+            }
+        }
+    }
+    
+    return report;
+}
+
+// Add a new file and delete one
+var scenario = Object.assign({}, modifiedFiles);
+scenario['new-file.txt'] = 'This is a new file';
+delete scenario['readme.md'];
+
+var report = analyzeChanges(files, scenario, manifest);
+
+console.log('Change Report:');
+console.log('  Unchanged: ' + (report.unchanged.length > 0 ? report.unchanged.join(', ') : 'none'));
+console.log('  Modified:  ' + (report.modified.length > 0 ? report.modified.map(function(m) { return m.filename; }).join(', ') : 'none'));
+console.log('  Added:     ' + (report.added.length > 0 ? report.added.join(', ') : 'none'));
+console.log('  Deleted:   ' + (report.deleted.length > 0 ? report.deleted.join(', ') : 'none'));
+
+if (report.modified.length > 0) {
+    console.log('\nModified file details:');
+    for (var i = 0; i < report.modified.length; i++) {
+        var mod = report.modified[i];
+        console.log('  ' + mod.filename + ':');
+        console.log('    Original: ' + mod.originalHash);
+        console.log('    Current:  ' + mod.currentHash);
+    }
+}
+
+// ===========================================
+// MANIFEST FILE FORMAT
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Manifest File Format:');
+console.log('='.repeat(50) + '\n');
+
+function createManifest(files) {
+    var manifest = {
+        version: '1.0',
+        created: new Date().toISOString(),
+        algorithm: 'tinyaleph-hash-32',
+        files: {}
+    };
+    
+    for (var filename in files) {
+        if (files.hasOwnProperty(filename)) {
+            manifest.files[filename] = {
+                hash: hashFile(files[filename]),
+                size: files[filename].length
+            };
+        }
+    }
+    
+    // Sign the manifest itself
+    var manifestContent = JSON.stringify(manifest.files);
+    manifest.signature = hashFile(manifestContent);
+    
+    return manifest;
+}
+
+var fullManifest = createManifest(files);
+console.log(JSON.stringify(fullManifest, null, 2));
+
+// ===========================================
+// INCREMENTAL UPDATES
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Incremental Manifest Updates:');
+console.log('='.repeat(50) + '\n');
+
+function updateManifest(manifest, filename, content) {
+    var newManifest = JSON.parse(JSON.stringify(manifest));
+    newManifest.files[filename] = {
+        hash: hashFile(content),
+        size: content.length
+    };
+    newManifest.updated = new Date().toISOString();
+    
+    // Re-sign
+    var manifestContent = JSON.stringify(newManifest.files);
+    newManifest.signature = hashFile(manifestContent);
+    
+    return newManifest;
+}
+
+console.log('Updating manifest after file change:\n');
+var updatedManifest = updateManifest(fullManifest, 'config.json', '{"version":"2.0"}');
+console.log('  Old config.json hash: ' + fullManifest.files['config.json'].hash.substring(0, 32) + '...');
+console.log('  New config.json hash: ' + updatedManifest.files['config.json'].hash.substring(0, 32) + '...');
+console.log('  New signature: ' + updatedManifest.signature.substring(0, 32) + '...');
+
+// ===========================================
+// KEY TAKEAWAYS
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('KEY TAKEAWAYS:');
+console.log('1. Hash files to create integrity fingerprints');
+console.log('2. Store hashes in a manifest file');
+console.log('3. Recompute and compare to detect changes');
+console.log('4. Sign manifests to protect against tampering');
+console.log('5. Track added, modified, and deleted files');
+console.log('6. Use incremental updates for efficiency');