@immahq/aegis 0.0.1

package/dist/identity-manager.js

@@ -0,0 +1,112 @@
+import { ml_kem768 } from "@noble/post-quantum/ml-kem.js";
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { blake3 } from "@noble/hashes/blake3.js";
+import { bytesToHex, concatBytes } from "@noble/hashes/utils.js";
+import { Logger } from "./logger.js";
+import { PreKeyManager } from "./prekey-manager.js";
+import { ERRORS } from "./constants.js";
+export class IdentityManager {
+    constructor(storage) {
+        Object.defineProperty(this, "storage", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "preKeyManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.storage = storage;
+        this.preKeyManager = new PreKeyManager();
+    }
+    async createIdentity() {
+        try {
+            Logger.log("Identity", "Creating new identity");
+            const kemKeyPair = ml_kem768.keygen();
+            const dsaKeyPair = ml_dsa65.keygen();
+            const userId = bytesToHex(blake3(concatBytes(kemKeyPair.publicKey, dsaKeyPair.publicKey), {
+                dkLen: 32,
+            }));
+            const preKeyPair = ml_kem768.keygen();
+            const preKeySignature = ml_dsa65.sign(preKeyPair.publicKey, dsaKeyPair.secretKey);
+            const preKey = {
+                id: 1,
+                keyPair: preKeyPair,
+                signature: preKeySignature,
+                used: false,
+                createdAt: Date.now(),
+            };
+            await this.preKeyManager.savePreKey(preKey);
+            const identity = {
+                kemKeyPair,
+                dsaKeyPair,
+                userId,
+                createdAt: Date.now(),
+                preKeySecret: preKeyPair.secretKey,
+            };
+            const publicBundle = {
+                userId,
+                kemPublicKey: kemKeyPair.publicKey,
+                dsaPublicKey: dsaKeyPair.publicKey,
+                preKey: {
+                    id: preKey.id,
+                    key: preKeyPair.publicKey,
+                    signature: preKeySignature,
+                },
+                createdAt: Date.now(),
+            };
+            await this.storage.saveIdentity(identity);
+            Logger.log("Identity", "Identity created successfully", {
+                userId: userId.substring(0, 16) + "...",
+            });
+            return { identity, publicBundle };
+        }
+        catch (error) {
+            Logger.error("Identity", "Failed to create identity", error);
+            throw error;
+        }
+    }
+    async getIdentity() {
+        const identity = await this.storage.getIdentity();
+        if (!identity)
+            throw new Error(ERRORS.IDENTITY_NOT_FOUND);
+        return identity;
+    }
+    async getPublicBundle() {
+        const identity = await this.getIdentity();
+        const preKey = await this.preKeyManager.getUnusedPreKey();
+        if (!preKey) {
+            const newPreKey = await this.preKeyManager.generatePreKey(identity);
+            return {
+                userId: identity.userId,
+                kemPublicKey: identity.kemKeyPair.publicKey,
+                dsaPublicKey: identity.dsaKeyPair.publicKey,
+                preKey: {
+                    id: newPreKey.id,
+                    key: newPreKey.keyPair.publicKey,
+                    signature: newPreKey.signature,
+                },
+                createdAt: identity.createdAt,
+            };
+        }
+        return {
+            userId: identity.userId,
+            kemPublicKey: identity.kemKeyPair.publicKey,
+            dsaPublicKey: identity.dsaKeyPair.publicKey,
+            preKey: {
+                id: preKey.id,
+                key: preKey.keyPair.publicKey,
+                signature: preKey.signature,
+            },
+            createdAt: identity.createdAt,
+        };
+    }
+    async rotateIdentity() {
+        const result = await this.createIdentity();
+        await this.preKeyManager.clear();
+        return result;
+    }
+}

package/dist/index.js

@@ -0,0 +1,11 @@
+export { E2EE as Aegis } from "./e2ee.js";
+export { MemoryStorage } from "./storage.js";
+export { Logger } from "./logger.js";
+export { KemRatchet } from "./ratchet.js";
+export { SessionKeyExchange } from "./session.js";
+export { IdentityManager } from "./identity-manager.js";
+export { SessionManager } from "./session-manager.js";
+export { CryptoManager } from "./crypto-manager.js";
+export { RatchetManager } from "./ratchet-manager.js";
+export { ReplayProtection } from "./replay-protection.js";
+export { GroupManager } from "./group-manager.js";

package/dist/logger.js

@@ -0,0 +1,23 @@
+export class Logger {
+    static log(component, message, data) {
+        const safeData = data ? { ...data } : undefined;
+        // Remove any sensitive data from logs
+        if (safeData) {
+            const sensitiveKeys = [
+                "secretKey",
+                "privateKey",
+                "rootKey",
+                "chainKey",
+                "ciphertext",
+            ];
+            sensitiveKeys.forEach((key) => delete safeData[key]);
+        }
+        console.log(`[Aegis:${component}] ${message}`, safeData || "");
+    }
+    static error(component, message, error) {
+        console.error(`[Aegis:${component}] ERROR: ${message}`, error || "");
+    }
+    static warn(component, message, data) {
+        console.warn(`[Aegis:${component}] WARN: ${message}`, data || "");
+    }
+}

package/dist/prekey-manager.js

@@ -0,0 +1,63 @@
+import { ml_kem768 } from "@noble/post-quantum/ml-kem.js";
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+export class PreKeyManager {
+    constructor() {
+        Object.defineProperty(this, "preKeys", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "nextPreKeyId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 1
+        });
+    }
+    async generatePreKey(identity) {
+        const preKeyPair = ml_kem768.keygen();
+        const preKeySignature = ml_dsa65.sign(preKeyPair.publicKey, identity.dsaKeyPair.secretKey);
+        const preKey = {
+            id: this.nextPreKeyId++,
+            keyPair: preKeyPair,
+            signature: preKeySignature,
+            used: false,
+            createdAt: Date.now(),
+        };
+        this.preKeys.set(preKey.id, preKey);
+        return preKey;
+    }
+    async savePreKey(preKey) {
+        this.preKeys.set(preKey.id, preKey);
+    }
+    getPreKey(id) {
+        return this.preKeys.get(id) || null;
+    }
+    getUnusedPreKey() {
+        for (const preKey of this.preKeys.values()) {
+            if (!preKey.used) {
+                return preKey;
+            }
+        }
+        return null;
+    }
+    markPreKeyAsUsed(id) {
+        const preKey = this.preKeys.get(id);
+        if (preKey) {
+            preKey.used = true;
+        }
+    }
+    removeOldPreKeys(maxAge = 7 * 24 * 60 * 60 * 1000) {
+        const now = Date.now();
+        for (const [id, preKey] of this.preKeys.entries()) {
+            if (now - preKey.createdAt > maxAge) {
+                this.preKeys.delete(id);
+            }
+        }
+    }
+    clear() {
+        this.preKeys.clear();
+        this.nextPreKeyId = 1;
+    }
+}

package/dist/ratchet-manager.js

@@ -0,0 +1,130 @@
+import { bytesToHex } from "@noble/hashes/utils.js";
+import { Logger } from "./logger.js";
+import { RATCHET_AFTER_MESSAGES } from "./constants.js";
+import { KemRatchet } from "./ratchet.js";
+export class RatchetManager {
+    shouldPerformSendingRatchet(session) {
+        const messageCount = session.sendingChain?.messageNumber || 0;
+        const isFirstMessageAsInitiator = session.isInitiator && messageCount === 0;
+        return (session.peerRatchetPublicKey !== null &&
+            !isFirstMessageAsInitiator &&
+            messageCount >= RATCHET_AFTER_MESSAGES);
+    }
+    needsReceivingRatchet(session, header) {
+        return (header.isRatchetMessage === true ||
+            (session.peerRatchetPublicKey !== null &&
+                bytesToHex(header.ratchetPublicKey) !==
+                    bytesToHex(session.peerRatchetPublicKey)));
+    }
+    performSendingRatchet(session) {
+        if (!session.peerRatchetPublicKey) {
+            throw new Error("No peer ratchet public key available for ratchet");
+        }
+        const result = KemRatchet.performKemRatchetEncapsulate(session.rootKey, session.peerRatchetPublicKey);
+        const newSession = { ...session };
+        const pendingRatchetState = {
+            newRootKey: result.newRootKey,
+            newRatchetKeyPair: result.newRatchetKeyPair,
+            sendingChain: result.sendingChain,
+            receivingChain: result.receivingChain,
+            kemCiphertext: result.kemCiphertext,
+            previousReceivingChain: session.receivingChain,
+            previousSendingChain: session.sendingChain,
+        };
+        newSession.pendingRatchetState = pendingRatchetState;
+        newSession.previousSendingChainLength =
+            session.sendingChain?.messageNumber ?? 0;
+        newSession.ratchetCount++;
+        newSession.state = "RATCHET_PENDING";
+        Logger.log("Ratchet", "Prepared sending KEM ratchet", {
+            ratchetCount: newSession.ratchetCount,
+            messageNumber: session.sendingChain?.messageNumber || 0,
+        });
+        return {
+            session: newSession,
+            kemCiphertext: result.kemCiphertext,
+        };
+    }
+    performReceivingRatchet(session, kemCiphertext) {
+        if (!session.currentRatchetKeyPair?.secretKey) {
+            throw new Error("No current ratchet secret key available");
+        }
+        const result = KemRatchet.performKemRatchetDecapsulate(session.rootKey, kemCiphertext, session.currentRatchetKeyPair.secretKey);
+        const previousReceivingChain = session.receivingChain;
+        const updatedSession = { ...session };
+        updatedSession.rootKey = result.newRootKey;
+        updatedSession.currentRatchetKeyPair = result.newRatchetKeyPair;
+        updatedSession.sendingChain = result.sendingChain;
+        updatedSession.receivingChain = result.receivingChain;
+        updatedSession.ratchetCount++;
+        updatedSession.state = "ACTIVE";
+        updatedSession.pendingRatchetState = {
+            newRootKey: result.newRootKey,
+            newRatchetKeyPair: result.newRatchetKeyPair,
+            sendingChain: result.sendingChain,
+            receivingChain: result.receivingChain,
+            kemCiphertext,
+            previousReceivingChain,
+            previousSendingChain: session.sendingChain,
+        };
+        Logger.log("Ratchet", "Performed receiving KEM ratchet", {
+            ratchetCount: updatedSession.ratchetCount,
+            hasOldChain: previousReceivingChain !== null,
+        });
+        return updatedSession;
+    }
+    applyPendingRatchet(session) {
+        if (!session.pendingRatchetState) {
+            return session;
+        }
+        const { pendingRatchetState } = session;
+        const updatedSession = { ...session };
+        updatedSession.rootKey = pendingRatchetState.newRootKey;
+        updatedSession.currentRatchetKeyPair =
+            pendingRatchetState.newRatchetKeyPair;
+        updatedSession.sendingChain = pendingRatchetState.sendingChain;
+        updatedSession.receivingChain = pendingRatchetState.receivingChain;
+        updatedSession.pendingRatchetState = undefined;
+        updatedSession.state = "ACTIVE";
+        Logger.log("Ratchet", "Applied pending ratchet state", {
+            ratchetCount: updatedSession.ratchetCount,
+        });
+        return updatedSession;
+    }
+    async triggerRatchet(sessionId, session) {
+        if (!session.peerRatchetPublicKey) {
+            throw new Error("No peer ratchet public key available");
+        }
+        const result = KemRatchet.performKemRatchetEncapsulate(session.rootKey, session.peerRatchetPublicKey);
+        const newSession = {
+            ...session,
+            rootKey: result.newRootKey,
+            currentRatchetKeyPair: result.newRatchetKeyPair,
+            sendingChain: result.sendingChain,
+            receivingChain: result.receivingChain,
+            previousSendingChainLength: session.sendingChain?.messageNumber ?? 0,
+            ratchetCount: session.ratchetCount + 1,
+            state: "ACTIVE",
+            pendingRatchetState: {
+                newRootKey: result.newRootKey,
+                newRatchetKeyPair: result.newRatchetKeyPair,
+                sendingChain: result.sendingChain,
+                receivingChain: result.receivingChain,
+                kemCiphertext: result.kemCiphertext,
+                previousReceivingChain: session.receivingChain,
+                previousSendingChain: session.sendingChain,
+            },
+        };
+        Logger.log("Ratchet", "Manually triggered ratchet", {
+            sessionId: sessionId.substring(0, 16) + "...",
+            newRatchetCount: newSession.ratchetCount,
+        });
+        return newSession;
+    }
+    getDecryptionChainForRatchetMessage(session) {
+        if (!session.pendingRatchetState?.previousReceivingChain) {
+            return session.receivingChain;
+        }
+        return session.pendingRatchetState.previousReceivingChain;
+    }
+}

package/dist/ratchet.js

@@ -0,0 +1,168 @@
+import { ml_kem768 } from "@noble/post-quantum/ml-kem.js";
+import { blake3 } from "@noble/hashes/blake3.js";
+import { concatBytes } from "@noble/hashes/utils.js";
+import { ML_KEM768_PUBLIC_KEY_LENGTH } from "./constants";
+export class KemRatchet {
+    // Perform KEM ratchet as encapsulator (when we send a new ratchet key)
+    static performKemRatchetEncapsulate(rootKey, peerRatchetPublicKey) {
+        if (!peerRatchetPublicKey) {
+            throw new Error("peerRatchetPublicKey is required for KEM ratchet encapsulation");
+        }
+        // Validate peer's ratchet public key
+        if (!this.validateRatchetPublicKey(peerRatchetPublicKey)) {
+            throw new Error("Invalid peer ratchet public key");
+        }
+        // Generate new ratchet keypair for NEXT round
+        const newRatchetKeyPair = ml_kem768.keygen();
+        // Perform KEM encapsulation to peer's CURRENT ratchet public key
+        const { sharedSecret, cipherText } = ml_kem768.encapsulate(peerRatchetPublicKey);
+        // Derive new root key
+        const newRootKey = this.deriveKey(rootKey, sharedSecret, this.CONTEXT_ROOT_KEY);
+        // Derive sending and receiving chain keys
+        const sendingChainKey = this.deriveKey(newRootKey, cipherText, this.CONTEXT_CHAIN_KEY);
+        const receivingChainKey = this.deriveKey(newRootKey, sharedSecret, this.CONTEXT_CHAIN_KEY);
+        return {
+            newRootKey,
+            newRatchetKeyPair,
+            sendingChain: {
+                chainKey: sendingChainKey,
+                messageNumber: 0,
+            },
+            receivingChain: {
+                chainKey: receivingChainKey,
+                messageNumber: 0,
+            },
+            kemCiphertext: cipherText,
+        };
+    }
+    // Perform KEM ratchet as decapsulator (when we receive a new ratchet key)
+    static performKemRatchetDecapsulate(rootKey, kemCiphertext, currentRatchetSecretKey) {
+        if (!kemCiphertext || kemCiphertext.length === 0) {
+            throw new Error("KEM ciphertext is required for decapsulation");
+        }
+        // Decapsulate the KEM cipherText using our current secret key
+        const sharedSecret = ml_kem768.decapsulate(kemCiphertext, currentRatchetSecretKey);
+        // Generate new ratchet keypair for next round
+        const newRatchetKeyPair = ml_kem768.keygen();
+        // Derive new root key (must match encapsulator's derivation)
+        const newRootKey = this.deriveKey(rootKey, sharedSecret, this.CONTEXT_ROOT_KEY);
+        // Derive chain keys (roles are swapped compared to encapsulator)
+        const sendingChainKey = this.deriveKey(newRootKey, sharedSecret, this.CONTEXT_CHAIN_KEY);
+        const receivingChainKey = this.deriveKey(newRootKey, kemCiphertext, this.CONTEXT_CHAIN_KEY);
+        return {
+            newRootKey,
+            newRatchetKeyPair,
+            sendingChain: {
+                chainKey: sendingChainKey,
+                messageNumber: 0,
+            },
+            receivingChain: {
+                chainKey: receivingChainKey,
+                messageNumber: 0,
+            },
+            kemCiphertext: new Uint8Array(0),
+        };
+    }
+    // Generate confirmation MAC for session keys
+    static generateConfirmationMac(sessionId, rootKey, chainKey, isResponse = false) {
+        const context = isResponse
+            ? new Uint8Array([0x06]) // Different context for response
+            : this.CONTEXT_CONFIRMATION;
+        const data = concatBytes(new TextEncoder().encode(sessionId), rootKey, chainKey, new Uint8Array([isResponse ? 1 : 0]));
+        return this.deriveKey(rootKey, data, context);
+    }
+    // Verify confirmation MAC
+    static verifyConfirmationMac(sessionId, rootKey, chainKey, receivedMac, isResponse = false) {
+        const expectedMac = this.generateConfirmationMac(sessionId, rootKey, chainKey, isResponse);
+        // Constant-time comparison
+        if (expectedMac.length !== receivedMac.length)
+            return false;
+        let result = 0;
+        for (let i = 0; i < expectedMac.length; i++) {
+            result |= expectedMac[i] ^ receivedMac[i];
+        }
+        return result === 0;
+    }
+    // Symmetric ratchet for deriving message keys within a chain
+    static symmetricRatchet(chain) {
+        // Derive message key from current chain key
+        const messageKey = this.deriveKey(chain.chainKey, new Uint8Array([0x00]), this.CONTEXT_MESSAGE_KEY);
+        // Derive new chain key
+        const newChainKey = this.deriveKey(chain.chainKey, new Uint8Array([0x01]), this.CONTEXT_CHAIN_KEY);
+        const newChain = {
+            chainKey: newChainKey,
+            messageNumber: chain.messageNumber + 1,
+        };
+        return { messageKey, newChain };
+    }
+    // Skip message keys for out-of-order messages
+    static skipMessageKeys(chain, targetMessageNumber, maxSkip) {
+        const skippedKeys = new Map();
+        if (targetMessageNumber <= chain.messageNumber) {
+            throw new Error("Cannot skip to earlier message number");
+        }
+        const skipCount = targetMessageNumber - chain.messageNumber;
+        if (skipCount > maxSkip) {
+            throw new Error(`Skip count ${skipCount} exceeds maximum ${maxSkip}`);
+        }
+        let currentChain = { ...chain };
+        // Generate keys for skipped messages
+        for (let i = 0; i < skipCount; i++) {
+            const { messageKey, newChain } = this.symmetricRatchet(currentChain);
+            skippedKeys.set(currentChain.messageNumber, messageKey);
+            currentChain = newChain;
+        }
+        return { skippedKeys, newChain: currentChain };
+    }
+    // Helper method for key derivation
+    static deriveKey(key, data, context) {
+        return blake3(concatBytes(key, data, context), { dkLen: 32 });
+    }
+    // Generate a fresh ratchet keypair
+    static generateRatchetKeyPair() {
+        return ml_kem768.keygen();
+    }
+    // Check if we should perform a KEM ratchet
+    static shouldPerformRatchet(messageCount, lastRatchetTime, maxMessages = 100, maxTime = 7 * 24 * 60 * 60 * 1000 // 7 days
+    ) {
+        const now = Date.now();
+        return messageCount >= maxMessages || now - lastRatchetTime >= maxTime;
+    }
+    // Validate a ratchet public key
+    static validateRatchetPublicKey(publicKey) {
+        return (publicKey instanceof Uint8Array &&
+            publicKey.length === ML_KEM768_PUBLIC_KEY_LENGTH);
+    }
+    // Derive a unique ratchet identifier
+    static deriveRatchetId(publicKey, chainKey) {
+        const hash = blake3(concatBytes(publicKey, chainKey), { dkLen: 16 });
+        return Array.from(hash)
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+    }
+}
+// Constants for key derivation contexts
+Object.defineProperty(KemRatchet, "CONTEXT_ROOT_KEY", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array([0x01])
+});
+Object.defineProperty(KemRatchet, "CONTEXT_CHAIN_KEY", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array([0x02])
+});
+Object.defineProperty(KemRatchet, "CONTEXT_MESSAGE_KEY", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array([0x03])
+});
+Object.defineProperty(KemRatchet, "CONTEXT_CONFIRMATION", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array([0x05])
+});

package/dist/replay-protection.js

@@ -0,0 +1,37 @@
+import { MAX_STORED_MESSAGE_IDS } from "./constants.js";
+export class ReplayProtection {
+    getSkippedKeyId(ratchetPublicKey, messageNumber) {
+        return `${this.bytesToHex(ratchetPublicKey)}:${messageNumber}`;
+    }
+    bytesToHex(bytes) {
+        return Array.from(bytes)
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+    }
+    cleanupSkippedKeys(session) {
+        const maxAge = 7 * 24 * 60 * 60 * 1000; // 7 days
+        const now = Date.now();
+        for (const [keyId, key] of session.skippedMessageKeys.entries()) {
+            if (now - key.timestamp > maxAge) {
+                session.skippedMessageKeys.delete(keyId);
+            }
+        }
+    }
+    // Simple replay protection: Store received message IDs
+    storeReceivedMessageId(session, messageId) {
+        session.receivedMessageIds.add(messageId);
+        // Keep the set size manageable
+        if (session.receivedMessageIds.size > MAX_STORED_MESSAGE_IDS) {
+            // Remove oldest entries (Set doesn't have order, so we recreate)
+            const ids = Array.from(session.receivedMessageIds);
+            session.receivedMessageIds = new Set(ids.slice(-MAX_STORED_MESSAGE_IDS));
+        }
+    }
+    async getReplayProtectionStatus(_sessionId, session) {
+        return {
+            storedMessageIds: session.receivedMessageIds.size,
+            lastProcessedTimestamp: session.lastProcessedTimestamp,
+            replayWindowSize: session.replayWindowSize,
+        };
+    }
+}