@immahq/aegis 0.0.2 → 0.0.5

package/README.md

@@ -1,15 +1,15 @@
-# **Aegis**
+# **Aegis** 
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/68e739263f9740b3be6693e795d17d0a)](https://app.codacy.com/gh/imma-hq/aegis/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)![git workflow](https://github.com/imma-hq/aegis/actions/workflows/ci.yml/badge.svg?branch=main)
+![NPM Version](https://img.shields.io/npm/v/@immahq/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.
 
 ---
 
-![git workflow](https://github.com/imma-hq/aegis/actions/workflows/ci.yml/badge.svg?branch=main)
-![NPM Version](https://img.shields.io/npm/v/@immahq/aegis)
 
 ## **Core Features**
 
-- **Post-Quantum Ready**: Uses **ML-KEM 768 (formerly Kyber)** for initial key encapsulation, aligning with NIST standards.
+- **Post-Quantum Ready**: Uses **ML-KEM 768** for initial key encapsulation, aligning with NIST standards.
 - **Storage-Agnostic**: You provide a simple key-value storage adapter (e.g., AsyncStorage, LocalStorage, SQLite, SecureStore).
 - **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.
@@ -26,6 +26,8 @@ npm install @immahq/aegis
 # or
 yarn add @immahq/aegis
 ```
+For React Native, you may need a
+[polyfill for getRandomValues](https://github.com/LinusU/react-native-get-random-values).
 
 ---
 
@@ -229,7 +231,7 @@ console.log(new TextDecoder().decode(groupPlaintext)); // "Dinner at 8 PM!"
 
 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).
+1.  **Key Agreement**: **ML-KEM 768** 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.
 

package/aegis.d.ts

@@ -0,0 +1,196 @@
+declare module "@immahq/aegis" {
+  export interface Identity {
+    kemKeyPair: { publicKey: Uint8Array; secretKey: Uint8Array };
+    dsaKeyPair: { publicKey: Uint8Array; secretKey: Uint8Array };
+    userId: string;
+    createdAt: number;
+    preKeySecret?: Uint8Array;
+  }
+
+  export interface PublicBundle {
+    userId: string;
+    kemPublicKey: Uint8Array;
+    dsaPublicKey: Uint8Array;
+    preKey: {
+      id: number;
+      key: Uint8Array;
+      signature: Uint8Array;
+    };
+    createdAt: number;
+  }
+
+  export interface RatchetChain {
+    chainKey: Uint8Array;
+    messageNumber: number;
+  }
+
+  export interface SkippedMessageKey {
+    messageKey: Uint8Array;
+    timestamp: number;
+  }
+
+  export interface PendingRatchetState {
+    newRootKey: Uint8Array;
+    newRatchetKeyPair: { publicKey: Uint8Array; secretKey: Uint8Array };
+    sendingChain: RatchetChain;
+    receivingChain: RatchetChain;
+    kemCiphertext: Uint8Array;
+    previousReceivingChain: RatchetChain | null;
+    previousSendingChain: RatchetChain | null;
+  }
+
+  export interface Session {
+    sessionId: string;
+    peerUserId: string;
+    peerDsaPublicKey: Uint8Array;
+    rootKey: Uint8Array;
+    currentRatchetKeyPair: {
+      publicKey: Uint8Array;
+      secretKey: Uint8Array;
+    } | null;
+    peerRatchetPublicKey: Uint8Array | null;
+
+    pendingRatchetState?: PendingRatchetState;
+
+    sendingChain: RatchetChain | null;
+    receivingChain: RatchetChain | null;
+    previousSendingChainLength: number;
+    skippedMessageKeys: Map<string, SkippedMessageKey>;
+    highestReceivedMessageNumber: number;
+    maxSkippedMessages: number;
+    createdAt: number;
+    lastUsed: number;
+    isInitiator: boolean;
+    ratchetCount: number;
+    state: "CREATED" | "KEY_CONFIRMED" | "ACTIVE" | "RATCHET_PENDING" | "ERROR";
+    confirmed: boolean;
+    confirmationMac?: Uint8Array;
+
+    receivedMessageIds: Set<string>;
+    replayWindowSize: number;
+    lastProcessedTimestamp: number;
+
+    groupData?: {
+      name: string;
+      members: string[];
+      owner: string;
+      memberKeys: [string, Uint8Array][];
+      memberPublicKeys: [string, Uint8Array][]; // KEM public keys for key encryption
+      memberDsaPublicKeys?: [string, Uint8Array][]; // DSA public keys for signature verification
+      receivedMessageNumbers?: [string, number][];
+    };
+  }
+
+  export interface MessageHeader {
+    messageId: string;
+    ratchetPublicKey: Uint8Array;
+    messageNumber: number;
+    previousChainLength: number;
+    kemCiphertext?: Uint8Array;
+    isRatchetMessage?: boolean;
+    timestamp: number;
+  }
+
+  export interface EncryptedMessage {
+    ciphertext: Uint8Array;
+    header: MessageHeader;
+    signature: Uint8Array;
+    confirmationMac?: Uint8Array;
+  }
+
+  export interface PreKey {
+    id: number;
+    keyPair: { publicKey: Uint8Array; secretKey: Uint8Array };
+    signature: Uint8Array;
+    used: boolean;
+    createdAt: number;
+  }
+
+  export interface StorageAdapter {
+    saveIdentity(identity: Identity): Promise<void>;
+    getIdentity(): Promise<Identity | null>;
+    deleteIdentity(): Promise<void>;
+    saveSession(sessionId: string, session: Session): Promise<void>;
+    getSession(sessionId: string): Promise<Session | null>;
+    deleteSession(sessionId: string): Promise<void>;
+    listSessions(): Promise<string[]>;
+    deleteAllSessions(): Promise<void>;
+  }
+
+  export interface KeyConfirmationData {
+    sessionId: string;
+    mac: Uint8Array;
+    timestamp: number;
+  }
+
+  export interface Group {
+    groupId: string;
+    name: string;
+    members: string[];
+    sharedKey: Uint8Array;
+    createdAt: number;
+    lastUpdated: number;
+    owner: string;
+    memberKeys: Map<string, Uint8Array>;
+    memberPublicKeys: Map<string, Uint8Array>; // KEM public keys for key encryption
+    memberDsaPublicKeys: Map<string, Uint8Array>; // DSA public keys for signature verification
+    receivedMessageNumbers: Map<string, number>;
+  }
+
+  export interface GroupMessage {
+    groupId: string;
+    message: Uint8Array;
+    header: GroupMessageHeader;
+    signature: Uint8Array;
+  }
+
+  export interface GroupMessageHeader {
+    messageId: string;
+    timestamp: number;
+    senderId: string;
+    messageNumber: number;
+  }
+
+  export interface GroupSession {
+    sessionId: string;
+    groupId: string;
+    userId: string;
+    sharedKey: Uint8Array;
+    lastUsed: number;
+    permissions: GroupPermissions;
+  }
+
+  export interface GroupPermissions {
+    canSend: boolean;
+    canReceive: boolean;
+    canManageMembers: boolean;
+    canUpdateGroup: boolean;
+  }
+
+  export interface GroupManager {
+    createGroup(
+      name: string,
+      members: string[],
+      memberKemPublicKeys: Map<string, Uint8Array>,
+      memberDsaPublicKeys: Map<string, Uint8Array>
+    ): Promise<Group>;
+    addMember(
+      groupId: string,
+      userId: string,
+      session: Session,
+      userPublicKey: Uint8Array
+    ): Promise<void>;
+    removeMember(groupId: string, userId: string): Promise<void>;
+    updateGroupKey(groupId: string): Promise<void>;
+    encryptMessage(
+      groupId: string,
+      message: string | Uint8Array
+    ): Promise<GroupMessage>;
+    decryptMessage(
+      groupId: string,
+      encrypted: GroupMessage
+    ): Promise<Uint8Array>;
+    getGroup(groupId: string): Promise<Group | null>;
+    getGroups(): Promise<Group[]>;
+  }
+}

package/dist/crypto-manager.js

@@ -3,10 +3,10 @@ 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";
+import { Logger } from "./logger";
+import { ERRORS, MAX_MESSAGE_AGE } from "./constants";
+import { serializeHeader } from "./utils";
+import { KemRatchet } from "./ratchet";
 export class CryptoManager {
     constructor(storage) {
         Object.defineProperty(this, "storage", {

package/dist/e2ee.js

@@ -1,10 +1,10 @@
-import { Logger } from "./logger.js";
-import { IdentityManager } from "./identity-manager.js";
-import { SessionManager } from "./session-manager.js";
-import { CryptoManager } from "./crypto-manager.js";
-import { RatchetManager } from "./ratchet-manager.js";
-import { ReplayProtection } from "./replay-protection.js";
-import { GroupManager } from "./group-manager.js";
+import { Logger } from "./logger";
+import { IdentityManager } from "./identity-manager";
+import { SessionManager } from "./session-manager";
+import { CryptoManager } from "./crypto-manager";
+import { RatchetManager } from "./ratchet-manager";
+import { ReplayProtection } from "./replay-protection";
+import { GroupManager } from "./group-manager";
 export class E2EE {
     constructor(storage) {
         Object.defineProperty(this, "identityManager", {

package/dist/group-manager.js

@@ -3,8 +3,8 @@ 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 { MAX_MESSAGE_AGE } from "./constants.js";
+import { Logger } from "./logger";
+import { MAX_MESSAGE_AGE } from "./constants";
 export class GroupManager {
     constructor(storage) {
         Object.defineProperty(this, "storage", {
@@ -124,8 +124,7 @@ export class GroupManager {
         return group;
     }
     async addMember(groupId, userId, _session, // Unused parameter, using underscore prefix
-    userPublicKey // New parameter for the user's public key
-    ) {
+    userPublicKey) {
         if (!this.identity) {
             throw new Error("GroupManager not initialized with identity");
         }

package/dist/identity-manager.js

@@ -2,9 +2,9 @@ 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";
+import { Logger } from "./logger";
+import { PreKeyManager } from "./prekey-manager";
+import { ERRORS } from "./constants";
 export class IdentityManager {
     constructor(storage) {
         Object.defineProperty(this, "storage", {

package/dist/index.js

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

package/dist/ratchet-manager.js

@@ -1,7 +1,7 @@
 import { bytesToHex } from "@noble/hashes/utils.js";
-import { Logger } from "./logger.js";
-import { RATCHET_AFTER_MESSAGES } from "./constants.js";
-import { KemRatchet } from "./ratchet.js";
+import { Logger } from "./logger";
+import { RATCHET_AFTER_MESSAGES } from "./constants";
+import { KemRatchet } from "./ratchet";
 export class RatchetManager {
     shouldPerformSendingRatchet(session) {
         const messageCount = session.sendingChain?.messageNumber || 0;

package/dist/replay-protection.js

@@ -1,4 +1,4 @@
-import { MAX_STORED_MESSAGE_IDS } from "./constants.js";
+import { MAX_STORED_MESSAGE_IDS } from "./constants";
 export class ReplayProtection {
     getSkippedKeyId(ratchetPublicKey, messageNumber) {
         return `${this.bytesToHex(ratchetPublicKey)}:${messageNumber}`;

package/dist/session-manager.js

@@ -1,9 +1,9 @@
 import { ml_kem768 } from "@noble/post-quantum/ml-kem.js";
 import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
-import { Logger } from "./logger.js";
-import { ERRORS } from "./constants.js";
-import { SessionKeyExchange } from "./session.js";
-import { validatePublicBundle } from "./utils.js";
+import { Logger } from "./logger";
+import { ERRORS } from "./constants";
+import { SessionKeyExchange } from "./session";
+import { validatePublicBundle } from "./utils";
 export class SessionManager {
     constructor(storage) {
         Object.defineProperty(this, "storage", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immahq/aegis",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "description": "Lightweight, storage-agnostic library for client-side End-to-End (E2E) encryption",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,7 +12,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "aegis.d.ts"
   ],
   "publishConfig": {
     "access": "public"
@@ -29,12 +30,10 @@
     "url": "git+ssh://git@github.com/imma-hq/aegis.git"
   },
   "keywords": [
-    "react",
-    "react native",
-    "native",
-    "select",
-    "dropdown",
-    "option"
+    "cryptography",
+    "encryption",
+    "e2e",
+    "end-to-end"
   ],
   "author": "Aegis",
   "license": "MIT",