@immahq/aegis 0.0.4 → 0.0.6

package/README.md

@@ -9,7 +9,7 @@
 
 ## **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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immahq/aegis",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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"