@immahq/aegis 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 imma-hq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,257 @@
+# **Aegis**
+
+**Aegis** is a lightweight, storage-agnostic library for client-side End-to-End (E2E) encryption, designed for future security. It combines the NIST-standardized ML-KEM 768 algorithm for quantum-resistant key agreement with high-performance symmetric cryptography (ChaCha20-Poly1305, Blake3) to provide secure 1:1 sessions and scalable group messaging.
+
+---
+
+## **Core Features**
+
+- **Post-Quantum Ready**: Uses **ML-KEM 768 (formerly Kyber)** for initial key encapsulation, aligning with NIST standards.
+- **Storage-Agnostic**: You provide a simple key-value storage adapter (e.g., AsyncStorage, LocalStorage, SQLite).
+- **Modern Cryptography**: Symmetric ratchets for forward secrecy and Sender Keys for O(1) group encryption.
+- **Enhanced Security**: Implements proper group key encryption, pre-key signature verification, and secure group membership protocols.
+- **Minimal Dependencies**: Relies on robust, well-audited libraries like `@noble/curves` and `@noble/hashes`.
+
+---
+
+## **Installation**
+
+Install the library using npm, yarn, or pnpm.
+
+```bash
+npm install @immahq/aegis
+# or
+yarn add @immahq/aegis
+```
+
+---
+
+## **Quick Start**
+
+### **1. Implement a Storage Adapter**
+
+Aegis requires a minimal async storage adapter to persist keys and session state.
+
+```typescript
+import { StorageAdapter, Identity, Session } from "@immahq/aegis";
+
+const myStorage: StorageAdapter = {
+  async saveIdentity(identity: Identity) {
+    /* Save to secure storage (e.g., JSON.stringify(identity)) */
+  },
+  async getIdentity(): Promise<Identity | null> {
+    /* Retrieve and parse from storage */
+    return null;
+  },
+  async deleteIdentity() {
+    /* Delete from storage */
+  },
+  async saveSession(sessionId: string, session: Session) {
+    /* Save session state */
+  },
+  async getSession(sessionId: string): Promise<Session | null> {
+    /* Retrieve session state */
+    return null;
+  },
+  async deleteSession(sessionId: string) {
+    /* Delete specific session */
+  },
+  async listSessions(): Promise<string[]> {
+    /* Return list of all session IDs */
+    return [];
+  },
+  async deleteAllSessions() {
+    /* Clear all sessions */
+  },
+};
+
+// Initialize the library before any other operation
+import { E2EE } from "@immahq/aegis";
+const aegis = new E2EE(myStorage);
+```
+
+> **Security Note**: The adapter will store secret key material. In production, always use platform-secured storage (e.g., iOS Keychain, Android Keystore, or a securely encrypted database).
+
+### **2. Create a User Identity**
+
+A user identity consists of a post-quantum KEM key pair, a signing key pair, and pre-keys for session establishment.
+
+```typescript
+// This creates and automatically saves the identity to your storage
+const { identity, publicBundle } = await aegis.createIdentity();
+console.log("Your Public Bundle:", publicBundle);
+```
+
+### **3. Establish a 1:1 Encrypted Session**
+
+#### **Initiator (Alice)**
+
+```typescript
+// 1. Fetch recipient's public bundle from your server
+const bobBundle = await getPublicKeyBundle();
+
+// 2. Create a session. This performs the ML-KEM key encapsulation.
+const { sessionId, ciphertext, confirmationMac } = await aegis.createSession(
+  bobBundle
+);
+
+// 3. Send `ciphertext` and `confirmationMac` to Bob via your server
+```
+
+#### **Recipient (Bob)**
+
+```typescript
+// 1. Create the session as a responder using the received ciphertext
+const { sessionId, confirmationMac, isValid } =
+  await aegis.createResponderSession(
+    aliceBundle,
+    receivedCiphertext,
+    receivedConfirmationMac
+  );
+
+if (isValid) {
+  console.log("Session established and verified!");
+}
+```
+
+### **4. Exchange Messages**
+
+#### **Encrypt a Message**
+
+```typescript
+const encryptedMessage = await aegis.encryptMessage(
+  sessionId,
+  "Hello, Bob! This is a secret."
+);
+```
+
+#### **Decrypt a Message**
+
+```typescript
+const plaintext = await aegis.decryptMessage(sessionId, encryptedMessage);
+console.log(plaintext); // "Hello, Bob! This is a secret."
+```
+
+### **5. Group Messaging with Enhanced Security**
+
+Aegis uses the Sender Key protocol for efficient group messaging, where each member encrypts a message once for the entire group. With enhanced security features, group keys are now properly encrypted with member public keys and pre-key signatures are verified.
+
+#### **Create a Group with Secure Key Distribution**
+
+```typescript
+import { Aegis, MemoryStorage } from "@immahq/aegis";
+
+// Initialize Aegis with your storage adapter
+const aegis = new Aegis(new MemoryStorage());
+
+// Prepare member public keys
+const memberKemPublicKeys = new Map<string, Uint8Array>();
+memberKemPublicKeys.set(aliceUserId, aliceKem);
+// ... add other members ...
+
+const memberDsaPublicKeys = new Map<string, Uint8Array>();
+memberDsaPublicKeys.set(aliceUserId, aliceDsa);
+// ... add other members ...
+
+// Alice creates a group
+const group = await aegis.createGroup(
+  "family_chat_2025",
+  [aliceUserId, bobUserId, charlieUserId],
+  memberKemPublicKeys,
+  memberDsaPublicKeys
+);
+```
+
+#### **Broadcast and Decrypt Group Messages**
+
+```typescript
+// Alice encrypts a message for the entire group
+const groupCiphertext = await aegis.encryptGroupMessage(
+  "family_chat_2025",
+  "Dinner at 8 PM!"
+);
+
+// Bob decrypts the group message
+const groupPlaintext = await aegis.decryptGroupMessage(
+  "family_chat_2025",
+  groupCiphertext
+);
+console.log(new TextDecoder().decode(groupPlaintext)); // "Dinner at 8 PM!"
+```
+
+---
+
+## **API Reference**
+
+### **Core & Configuration**
+
+### **Identity Management**
+
+- **`aegis.createIdentity(): Promise<{ identity, publicBundle }>`**
+- **`aegis.getIdentity(): Promise<Identity>`**
+- **`aegis.getPublicBundle(): Promise<PublicBundle>`**
+- **`aegis.rotateIdentity(): Promise<{ identity, publicBundle }>`**
+
+### **1:1 Sessions**
+
+- **`aegis.createSession(peerBundle): Promise<{ sessionId, ciphertext, confirmationMac }>`**
+- **`aegis.createResponderSession(peerBundle, ciphertext, initiatorMac?): Promise<{ sessionId, confirmationMac, isValid }>`**
+- **`aegis.confirmSession(sessionId, responderMac): Promise<boolean>`**
+- **`aegis.encryptMessage(sessionId, plaintext): Promise<EncryptedMessage>`**
+- **`aegis.decryptMessage(sessionId, encryptedMsg): Promise<Uint8Array>`**
+- **`aegis.triggerRatchet(sessionId): Promise<void>`**
+
+### **Group Sessions**
+
+- **`aegis.createGroup(name, members, kemKeys, dsaKeys): Promise<Group>`**
+- **`aegis.addGroupMember(groupId, userId, session, userPublicKey): Promise<void>`**
+- **`aegis.removeGroupMember(groupId, userId): Promise<void>`**
+- **`aegis.updateGroupKey(groupId): Promise<void>`**
+- **`aegis.encryptGroupMessage(groupId, message): Promise<GroupMessage>`**
+- **`aegis.decryptGroupMessage(groupId, encryptedMsg): Promise<Uint8Array>`**
+- **`aegis.getGroup(groupId): Promise<Group | null>`**
+
+---
+
+## **Testing and Examples**
+
+- **Run Sample Flow**: `npm run sample`
+  - This executes `examples/usage.ts`, demonstrating a complete flow: identity creation, session handshake, 1:1 messaging, and group setup.
+
+---
+
+## **Security Model & Best Practices**
+
+### **Cryptographic Foundation**
+
+Aegis is built on a hybrid model:
+
+1.  **Key Agreement**: **ML-KEM 768 (Kyber)** provides quantum-resistant key encapsulation. This algorithm is now a finalized NIST standard (FIPS 203).
+2.  **Data Encryption**: **ChaCha20-Poly1305** is used for fast, authenticated encryption of message contents.
+3.  **Key Derivation & Hashing**: **Blake3** is used for key derivation and hashing, providing high speed and security.
+
+### **Critical Implementation Notes**
+
+⚠️ **These points are essential for production security:**
+
+- **Signed Pre-Key Signatures**: The library verifies pre-key signatures during session initialization. This provides protection against active man-in-the-middle attacks during session establishment.
+- **One-Time Pre-Keys (OTPKs)**: The `getPublicBundle()` function returns a pre-key. Your server should track used keys and ensure they are rotated.
+- **Group Key Encryption**: Group shared keys are properly encrypted using ML-KEM with each member's public key, ensuring that only authorized group members can access the group key.
+- **Storage Security**: The storage adapter you provide holds all secret keys. **You are responsible for its security.** Use platform-backed secure storage.
+
+---
+
+## **Contributing & Roadmap**
+
+We welcome contributions. Priority areas include:
+
+- Enhanced utilities for server-side OTPK lifecycle management.
+- Improved examples for cross-platform secure storage.
+- Advanced group management features (admin roles, permissions, etc.).
+- Performance optimizations for large group messaging.
+
+---
+
+## **License**
+
+MIT

package/dist/constants.js

@@ -0,0 +1,42 @@
+import { utf8ToBytes } from "@noble/hashes/utils.js";
+export const CONTEXT_MSG_KEY = utf8ToBytes("msg_key");
+export const CONTEXT_CHAIN_KEY = utf8ToBytes("chain_key");
+export const CONTEXT_CONFIRMATION = utf8ToBytes("key_confirmation");
+export const CONTEXT_CONFIRMATION_RESPONSE = utf8ToBytes("key_confirmation_response");
+// Session states
+export const SESSION_STATES = {
+    CREATED: "CREATED",
+    KEY_CONFIRMED: "KEY_CONFIRMED",
+    ACTIVE: "ACTIVE",
+    RATCHET_PENDING: "RATCHET_PENDING",
+    ERROR: "ERROR",
+};
+// Error messages
+export const ERRORS = {
+    IDENTITY_NOT_FOUND: "Identity not found",
+    SESSION_NOT_FOUND: "Session not found",
+    INVALID_PREKEY_SIGNATURE: "Invalid prekey signature",
+    INVALID_MESSAGE_SIGNATURE: "Invalid message signature",
+    REPLAY_ATTACK: "Possible replay attack - message number too low",
+    INVALID_PEER_BUNDLE: "Invalid peer bundle",
+    MESSAGE_TOO_OLD: "Message is too old to process",
+    SESSION_NOT_CONFIRMED: "Session keys not confirmed",
+    INVALID_SESSION_STATE: "Invalid session state",
+    RATCHET_CIPHERTEXT_MISSING: "KEM ratchet ciphertext missing",
+    KEY_CONFIRMATION_FAILED: "Key confirmation failed",
+    // Simple replay protection errors
+    DUPLICATE_MESSAGE: "Duplicate message detected",
+    MESSAGE_TOO_OLD_TIMESTAMP: "Message timestamp is too old",
+};
+// KEM constants
+export const ML_KEM768_PUBLIC_KEY_LENGTH = 1184;
+export const ML_KEM768_SECRET_KEY_LENGTH = 2400;
+export const ML_KEM768_CIPHERTEXT_LENGTH = 1088;
+// Ratchet constants
+export const RATCHET_AFTER_MESSAGES = 50;
+export const MAX_SKIPPED_MESSAGES = 100;
+export const KEY_CONFIRMATION_TIMEOUT = 30000; // 30 seconds
+// Simple replay protection constants
+export const REPLAY_WINDOW_SIZE = 100; // Accept messages up to 100 behind current
+export const MAX_MESSAGE_AGE = 5 * 60 * 1000; // 5 minutes maximum message age
+export const MAX_STORED_MESSAGE_IDS = 1000; // Store last 1000 message IDs

package/dist/crypto-manager.js

@@ -0,0 +1,306 @@
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { blake3 } from "@noble/hashes/blake3.js";
+import { randomBytes } from "@noble/post-quantum/utils.js";
+import { bytesToHex, concatBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+import { Logger } from "./logger.js";
+import { ERRORS, MAX_MESSAGE_AGE } from "./constants.js";
+import { serializeHeader } from "./utils.js";
+import { KemRatchet } from "./ratchet.js";
+export class CryptoManager {
+    constructor(storage) {
+        Object.defineProperty(this, "storage", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.storage = storage;
+    }
+    async encryptMessage(sessionId, plaintext, identity, shouldRatchet, performSendingRatchet, updateSessionState) {
+        try {
+            Logger.log("Encrypt", "Encrypting message");
+            const session = await this.storage.getSession(sessionId);
+            if (!session)
+                throw new Error(ERRORS.SESSION_NOT_FOUND);
+            if (!session.confirmed && session.state !== "CREATED") {
+                throw new Error(ERRORS.SESSION_NOT_CONFIRMED);
+            }
+            const plaintextBytes = typeof plaintext === "string" ? utf8ToBytes(plaintext) : plaintext;
+            const shouldRatchetResult = shouldRatchet(session);
+            let kemCiphertext;
+            let updatedSession = session;
+            if (shouldRatchetResult) {
+                Logger.log("Ratchet", "Performing sending KEM ratchet before encryption");
+                if (!session.peerRatchetPublicKey) {
+                    throw new Error("No peer ratchet public key available for ratchet");
+                }
+                const ratchetResult = performSendingRatchet(session);
+                updatedSession = ratchetResult.session;
+                kemCiphertext = ratchetResult.kemCiphertext;
+                Logger.log("Ratchet", "Prepared sending KEM ratchet", {
+                    ratchetCount: updatedSession.ratchetCount,
+                });
+            }
+            else if (session.pendingRatchetState) {
+                kemCiphertext = session.pendingRatchetState.kemCiphertext;
+                updatedSession = session;
+                Logger.log("Ratchet", "Using pending ratchet ciphertext", {
+                    ratchetCount: session.ratchetCount,
+                });
+            }
+            const chainToUse = kemCiphertext
+                ? updatedSession.pendingRatchetState?.previousSendingChain ||
+                    session.sendingChain
+                : updatedSession.sendingChain;
+            if (!chainToUse) {
+                throw new Error("No sending chain available");
+            }
+            const { messageKey, newChain } = KemRatchet.symmetricRatchet(chainToUse);
+            const nonce = randomBytes(24);
+            const cipher = xchacha20poly1305(messageKey, nonce);
+            const ciphertext = cipher.encrypt(plaintextBytes);
+            const fullciphertext = concatBytes(nonce, ciphertext);
+            const ratchetPublicKey = updatedSession.currentRatchetKeyPair.publicKey;
+            const header = {
+                messageId: bytesToHex(blake3(fullciphertext, { dkLen: 32 })),
+                ratchetPublicKey: ratchetPublicKey,
+                messageNumber: chainToUse.messageNumber,
+                previousChainLength: updatedSession.previousSendingChainLength,
+                kemCiphertext: kemCiphertext,
+                isRatchetMessage: kemCiphertext ? true : false,
+                timestamp: Date.now(),
+            };
+            let confirmationMac;
+            if (updatedSession.state === "CREATED" && updatedSession.isInitiator) {
+                confirmationMac = updatedSession.confirmationMac;
+                Logger.log("Session", "Including key confirmation MAC in first message");
+            }
+            const headerBytes = serializeHeader(header);
+            const messageToSign = concatBytes(headerBytes, fullciphertext);
+            const signature = ml_dsa65.sign(messageToSign, identity.dsaKeyPair.secretKey);
+            let finalSessionState = updatedSession;
+            if (kemCiphertext) {
+                if (updatedSession.pendingRatchetState) {
+                    finalSessionState = {
+                        ...updatedSession,
+                        sendingChain: newChain,
+                        rootKey: updatedSession.pendingRatchetState.newRootKey,
+                        currentRatchetKeyPair: updatedSession.pendingRatchetState.newRatchetKeyPair,
+                        state: "ACTIVE",
+                    };
+                }
+            }
+            else {
+                finalSessionState.sendingChain = newChain;
+            }
+            finalSessionState.lastUsed = Date.now();
+            if (finalSessionState.state === "CREATED" &&
+                finalSessionState.isInitiator) {
+                finalSessionState.state = "KEY_CONFIRMED";
+            }
+            await updateSessionState(sessionId, finalSessionState);
+            Logger.log("Encrypt", "Message encrypted", {
+                messageNumber: header.messageNumber,
+                ratchetCount: finalSessionState.ratchetCount,
+                usedRatchetKey: shouldRatchetResult,
+                state: finalSessionState.state,
+                isRatchetMessage: !!kemCiphertext,
+            });
+            return {
+                ciphertext: fullciphertext,
+                header,
+                signature,
+                confirmationMac,
+            };
+        }
+        catch (error) {
+            Logger.error("Encrypt", "Failed to encrypt message", error);
+            throw error;
+        }
+    }
+    async decryptMessage(sessionId, encrypted, needsReceivingRatchet, performReceivingRatchet, getSkippedKeyId, storeReceivedMessageId, cleanupSkippedKeys, applyPendingRatchet, getDecryptionChainForRatchetMessage, updateSessionState) {
+        try {
+            Logger.log("Decrypt", "Decrypting message");
+            const session = await this.storage.getSession(sessionId);
+            if (!session)
+                throw new Error(ERRORS.SESSION_NOT_FOUND);
+            const headerBytes = serializeHeader(encrypted.header);
+            const messageToVerify = concatBytes(headerBytes, encrypted.ciphertext);
+            const isValid = ml_dsa65.verify(encrypted.signature, messageToVerify, session.peerDsaPublicKey);
+            if (!isValid) {
+                throw new Error(ERRORS.INVALID_MESSAGE_SIGNATURE);
+            }
+            if (session.receivedMessageIds.has(encrypted.header.messageId)) {
+                Logger.warn("Replay", "Duplicate message detected", {
+                    messageId: encrypted.header.messageId.substring(0, 16) + "...",
+                });
+                throw new Error(ERRORS.DUPLICATE_MESSAGE);
+            }
+            const now = Date.now();
+            const messageAge = now - encrypted.header.timestamp;
+            if (messageAge > MAX_MESSAGE_AGE) {
+                Logger.warn("Replay", "Message too old", {
+                    age: `${Math.round(messageAge / 1000)}s`,
+                    maxAge: `${MAX_MESSAGE_AGE / 1000}s`,
+                });
+                throw new Error(ERRORS.MESSAGE_TOO_OLD_TIMESTAMP);
+            }
+            session.lastProcessedTimestamp = now;
+            if (encrypted.confirmationMac &&
+                !session.isInitiator &&
+                session.state === "CREATED") {
+                Logger.log("Session", "Processing key confirmation from initiator");
+                const isValidConfirmation = KemRatchet.verifyConfirmationMac(sessionId, session.rootKey, session.receivingChain.chainKey, encrypted.confirmationMac, false);
+                if (isValidConfirmation) {
+                    session.confirmed = true;
+                    session.state = "KEY_CONFIRMED";
+                    Logger.log("Session", "Key confirmation received and verified");
+                }
+                else {
+                    session.state = "ERROR";
+                    await updateSessionState(sessionId, session);
+                    throw new Error(ERRORS.KEY_CONFIRMATION_FAILED);
+                }
+            }
+            const needsRatchet = needsReceivingRatchet(session, encrypted.header);
+            let updatedSession = session;
+            let isRatchetMessage = false;
+            if (needsRatchet && encrypted.header.kemCiphertext) {
+                Logger.log("Ratchet", "Performing receiving KEM ratchet");
+                if (!session.currentRatchetKeyPair?.secretKey) {
+                    throw new Error("No current ratchet secret key available");
+                }
+                updatedSession = performReceivingRatchet(session, encrypted.header.kemCiphertext);
+                updatedSession.peerRatchetPublicKey = encrypted.header.ratchetPublicKey;
+                updatedSession.previousSendingChainLength =
+                    session.sendingChain?.messageNumber ?? 0;
+                isRatchetMessage = true;
+                Logger.log("Ratchet", "Received KEM ratchet", {
+                    ratchetCount: updatedSession.ratchetCount,
+                    peerKeyHash: bytesToHex(encrypted.header.ratchetPublicKey).substring(0, 16) +
+                        "...",
+                });
+            }
+            else if (needsRatchet && !encrypted.header.kemCiphertext) {
+                throw new Error(ERRORS.RATCHET_CIPHERTEXT_MISSING);
+            }
+            if (!updatedSession.peerRatchetPublicKey &&
+                encrypted.header.ratchetPublicKey) {
+                updatedSession.peerRatchetPublicKey = encrypted.header.ratchetPublicKey;
+                Logger.log("Session", "Stored peer ratchet public key", {
+                    keyHash: bytesToHex(encrypted.header.ratchetPublicKey).substring(0, 16) +
+                        "...",
+                });
+            }
+            const skippedKeyId = getSkippedKeyId(encrypted.header.ratchetPublicKey, encrypted.header.messageNumber);
+            const skippedKey = updatedSession.skippedMessageKeys.get(skippedKeyId);
+            if (skippedKey) {
+                Logger.log("Decrypt", "Using skipped message key", {
+                    messageNumber: encrypted.header.messageNumber,
+                });
+                const plaintext = this.decryptWithKey(encrypted.ciphertext, skippedKey.messageKey);
+                storeReceivedMessageId(updatedSession, encrypted.header.messageId);
+                updatedSession.skippedMessageKeys.delete(skippedKeyId);
+                updatedSession.lastUsed = Date.now();
+                await updateSessionState(sessionId, updatedSession);
+                return { plaintext };
+            }
+            let chainToUseForDecryption;
+            if (isRatchetMessage) {
+                chainToUseForDecryption =
+                    getDecryptionChainForRatchetMessage(updatedSession);
+            }
+            else {
+                // If we have a pending ratchet and this message doesn't seem to fit the current receiving chain,
+                // it might be the first message acknowledging our ratchet.
+                if (updatedSession.state === "RATCHET_PENDING" &&
+                    updatedSession.pendingRatchetState &&
+                    encrypted.header.messageNumber <
+                        updatedSession.receivingChain.messageNumber) {
+                    chainToUseForDecryption =
+                        updatedSession.pendingRatchetState.receivingChain;
+                    Logger.log("Decrypt", "Message number is lower than current chain, trying pending ratchet chain");
+                }
+                else {
+                    chainToUseForDecryption = updatedSession.receivingChain;
+                }
+            }
+            if (chainToUseForDecryption &&
+                encrypted.header.messageNumber > chainToUseForDecryption.messageNumber) {
+                const skipCount = encrypted.header.messageNumber -
+                    chainToUseForDecryption.messageNumber;
+                if (skipCount > updatedSession.maxSkippedMessages) {
+                    throw new Error(`Cannot skip ${skipCount} messages, max is ${updatedSession.maxSkippedMessages}`);
+                }
+                Logger.log("Decrypt", "Skipping message keys", {
+                    from: chainToUseForDecryption.messageNumber,
+                    to: encrypted.header.messageNumber,
+                    count: skipCount,
+                });
+                const { skippedKeys, newChain } = KemRatchet.skipMessageKeys(chainToUseForDecryption, encrypted.header.messageNumber, updatedSession.maxSkippedMessages);
+                for (const [msgNum, msgKey] of skippedKeys) {
+                    const keyId = getSkippedKeyId(encrypted.header.ratchetPublicKey, msgNum);
+                    updatedSession.skippedMessageKeys.set(keyId, {
+                        messageKey: msgKey,
+                        timestamp: Date.now(),
+                    });
+                }
+                chainToUseForDecryption = newChain;
+            }
+            if (!chainToUseForDecryption) {
+                throw new Error("No receiving chain available for decryption");
+            }
+            const { messageKey, newChain } = KemRatchet.symmetricRatchet(chainToUseForDecryption);
+            const plaintext = this.decryptWithKey(encrypted.ciphertext, messageKey);
+            if (isRatchetMessage) {
+                // Chains are already updated in updatedSession by performReceivingRatchet
+            }
+            else {
+                updatedSession.receivingChain = newChain;
+            }
+            updatedSession.highestReceivedMessageNumber = Math.max(updatedSession.highestReceivedMessageNumber, encrypted.header.messageNumber);
+            updatedSession.lastUsed = Date.now();
+            storeReceivedMessageId(updatedSession, encrypted.header.messageId);
+            cleanupSkippedKeys(updatedSession);
+            const needsConfirmation = !updatedSession.isInitiator &&
+                encrypted.confirmationMac &&
+                updatedSession.state === "KEY_CONFIRMED" &&
+                !updatedSession.confirmed;
+            if (needsConfirmation) {
+                updatedSession.confirmed = true;
+                Logger.log("Session", "Ready to send key confirmation response");
+            }
+            if (updatedSession.pendingRatchetState) {
+                if (isRatchetMessage) {
+                    updatedSession = applyPendingRatchet(updatedSession);
+                }
+                else if (chainToUseForDecryption ===
+                    updatedSession.pendingRatchetState.receivingChain) {
+                    updatedSession = applyPendingRatchet(updatedSession);
+                }
+            }
+            await updateSessionState(sessionId, updatedSession);
+            Logger.log("Decrypt", "Message decrypted successfully", {
+                messageNumber: encrypted.header.messageNumber,
+                ratchetCount: updatedSession.ratchetCount,
+                state: updatedSession.state,
+                isRatchetMessage,
+            });
+            return {
+                plaintext,
+                needsConfirmation: needsConfirmation,
+            };
+        }
+        catch (error) {
+            Logger.error("Decrypt", "Failed to decrypt message", error);
+            throw error;
+        }
+    }
+    decryptWithKey(ciphertext, messageKey) {
+        const nonce = ciphertext.slice(0, 24);
+        const encryptedData = ciphertext.slice(24);
+        const cipher = xchacha20poly1305(messageKey, nonce);
+        return cipher.decrypt(encryptedData);
+    }
+}