@immahq/aegis 0.1.2 → 0.1.3

package/README.md

@@ -16,10 +16,11 @@
 - **Identity Management**: Create identities with specific userIds for better user correlation and management.
 - **Key Rotation**: Supports identity rotation with option to maintain same userId or assign new ones.
 - **Replay Protection**: Built-in protection against message replay attacks.
-- **Minimal Dependencies**: Relies on robust, well-audited libraries like `@noble/curves` and `@noble/hashes`.
 
 ---
 
+
+
 ## **Installation**
 
 Install the library using npm, yarn, or pnpm.
@@ -35,7 +36,10 @@ For React Native, you may need a
 
 ---
 
-## **Quick Start**
+## **Setup**
+
+**Quick start**: Check [examples](/examples) for samples with browser, React Native, Electron, and Tauri
+
 
 ### **1. Implement a Storage Adapter**
 
@@ -217,8 +221,6 @@ console.log(new TextDecoder().decode(groupPlaintext)); // "Dinner at 8 PM!"
 
 ## **API Reference**
 
-### **Core & Configuration**
-
 ### **Identity Management**
 
 - **`aegis.createIdentity(userId?: string): Promise<{ identity, publicBundle }>`** - Creates a new identity with optional userId
@@ -250,10 +252,8 @@ console.log(new TextDecoder().decode(groupPlaintext)); // "Dinner at 8 PM!"
 ## **Testing and Examples**
 
 - **Run All Tests**: `npm test`
-- **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.
-- **Run Benchmarks**: `npm run benchmark`
-  - Executes performance benchmarks for various operations including identity creation, session establishment, message encryption/decryption, and group operations.
+- **Run peer messaging demo**: `npm run demo`
+- **Run group messaging demo**: `npm run demo:group`
 
 ---
 
@@ -279,32 +279,6 @@ Aegis is built on a hybrid model:
 
 ---
 
-## **Performance & Benchmarks**
-
-Aegis includes comprehensive benchmarking to measure performance across various operations:
-
-- **Identity Creation**: ~30-50ms per operation
-- **Session Establishment**: ~25-50ms per operation
-- **Message Encryption/Decryption**: ~30-70ms per round-trip
-- **Group Operations**: ~40-130ms depending on group size
-- **Ratchet Operations**: ~30-60ms per operation
-
-Run `npm run benchmark` to see performance metrics on your system.
-
----
-
-## **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.
-- Additional storage adapters for popular databases and platforms.
-
----
-
 ## **License**
 
 MIT

package/aegis.d.ts

@@ -1,6 +1,250 @@
+//Types
 declare module "@immahq/aegis" {
-  export class Aegis {}
-  export interface MemoryStorage extends StorageAdapter {}
+  export class Aegis {
+    constructor(storage: StorageAdapter);
+    createIdentity(userId?: string): Promise<AegisIdentity>;
+    getIdentity(): Promise<Identity>;
+    rotateIdentity(userId?: string): Promise<AegisIdentity>;
+    getPublicBundle(): Promise<PublicBundle>;
+    createSession(publicBundle: PublicBundle): Promise<{
+      sessionId: string;
+      ciphertext: Uint8Array;
+      confirmationMac: Uint8Array;
+    }>;
+    createResponderSession(
+      publicBundle: PublicBundle,
+      ciphertext: Uint8Array,
+      initiatorConfirmationMac?: Uint8Array,
+    ): Promise<{
+      sessionId: string;
+      confirmationMac: Uint8Array;
+      isValid: boolean;
+    }>;
+    confirmSession(
+      sessionId: string,
+      responderConfirmationMac: Uint8Array,
+    ): Promise<boolean>;
+    getSessions(): Promise<Session[]>;
+    cleanupOldSessions(maxAge?: number): Promise<void>;
+    encryptMessage(
+      sessionId: string,
+      plaintext: string | Uint8Array,
+    ): Promise<EncryptedMessage>;
+    decryptMessage(
+      sessionId: string,
+      encrypted: EncryptedMessage,
+    ): Promise<{
+      plaintext: Uint8Array;
+      needsConfirmation?: boolean;
+    }>;
+    triggerRatchet(sessionId: string): Promise<void>;
+    getReplayProtectionStatus(sessionId: string): Promise<{
+      storedMessageIds: number;
+      lastProcessedTimestamp: number;
+      replayWindowSize: number;
+    }>;
+    getConfirmationMac(sessionId: string): Promise<Uint8Array | null>;
+    getStorage(): StorageAdapter;
+    createGroup(
+      name: string,
+      members: string[],
+      memberKemPublicKeys: Map<string, Uint8Array>,
+      memberDsaPublicKeys: Map<string, Uint8Array>,
+    ): Promise<Group>;
+    addGroupMember(
+      groupId: string,
+      userId: string,
+      session: Session,
+      userPublicKey: Uint8Array,
+    ): Promise<void>;
+    removeGroupMember(groupId: string, userId: string): Promise<void>;
+    updateGroupKey(groupId: string): Promise<void>;
+    encryptGroupMessage(
+      groupId: string,
+      message: string | Uint8Array,
+    ): Promise<GroupMessage>;
+    decryptGroupMessage(
+      groupId: string,
+      encrypted: GroupMessage,
+    ): Promise<Uint8Array>;
+    getGroup(groupId: string): Promise<Group | null>;
+    getGroups(): Promise<Group[]>;
+  }
+
+  export class MemoryStorage implements 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 class Logger {
+    static log(
+      component: string,
+      message: string,
+      data?: Record<string, any>,
+    ): void;
+    static error(component: string, message: string, error?: any): void;
+    static warn(
+      component: string,
+      message: string,
+      data?: Record<string, any>,
+    ): void;
+  }
+
+  export class KemRatchet {}
+
+  export class SessionKeyExchange {
+    static createInitiatorSession(
+      identity: Identity,
+      peerBundle: PublicBundle,
+    ): {
+      sessionId: string;
+      rootKey: Uint8Array;
+      sendingChainKey: Uint8Array;
+      receivingChainKey: Uint8Array;
+      ciphertext: Uint8Array;
+      confirmationMac: Uint8Array;
+    };
+    static createResponderSession(
+      identity: Identity,
+      peerBundle: PublicBundle,
+      ciphertext: Uint8Array,
+      initiatorConfirmationMac?: Uint8Array,
+    ): {
+      sessionId: string;
+      rootKey: Uint8Array;
+      sendingChainKey: Uint8Array;
+      receivingChainKey: Uint8Array;
+      confirmationMac: Uint8Array;
+      isValid: boolean;
+    };
+    static verifyKeyConfirmation(
+      sessionId: string,
+      rootKey: Uint8Array,
+      receivingChainKey: Uint8Array,
+      confirmationMac: Uint8Array,
+    ): boolean;
+  }
+
+  export class IdentityManager {
+    constructor(storage: StorageAdapter);
+    createIdentity(userId?: string): Promise<AegisIdentity>;
+    getIdentity(): Promise<Identity>;
+    getPublicBundle(): Promise<PublicBundle>;
+    rotateIdentity(userId?: string): Promise<AegisIdentity>;
+  }
+
+  export class SessionManager {
+    constructor(storage: StorageAdapter);
+    createSession(
+      identity: Identity,
+      peerBundle: PublicBundle,
+    ): Promise<{
+      sessionId: string;
+      ciphertext: Uint8Array;
+      confirmationMac: Uint8Array;
+    }>;
+    createResponderSession(
+      identity: Identity,
+      peerBundle: PublicBundle,
+      ciphertext: Uint8Array,
+      initiatorConfirmationMac?: Uint8Array,
+    ): Promise<{
+      sessionId: string;
+      confirmationMac: Uint8Array;
+      isValid: boolean;
+    }>;
+    confirmSession(
+      sessionId: string,
+      responderConfirmationMac: Uint8Array,
+    ): Promise<boolean>;
+    getSessions(): Promise<Session[]>;
+    cleanupOldSessions(maxAge?: number): Promise<void>;
+  }
+
+  export class CryptoManager {
+    constructor(storage: StorageAdapter);
+  }
+
+  export class RatchetManager {
+    shouldPerformSendingRatchet(session: Session): boolean;
+    performSendingRatchet(session: Session): Session;
+    needsReceivingRatchet(session: Session, header: any): boolean;
+    performReceivingRatchet(
+      session: Session,
+      kemCiphertext: Uint8Array,
+    ): Session;
+    applyPendingRatchet(session: Session): Session;
+    getDecryptionChainForRatchetMessage(session: Session): RatchetChain | null;
+    triggerRatchet(sessionId: string, session: Session): Promise<Session>;
+  }
+
+  export class ReplayProtection {
+    getSkippedKeyId(
+      ratchetPublicKey: Uint8Array,
+      messageNumber: number,
+    ): string;
+    storeReceivedMessageId(session: Session, messageId: string): void;
+    cleanupSkippedKeys(session: Session): void;
+    getReplayProtectionStatus(
+      sessionId: string,
+      session: Session,
+    ): Promise<{
+      storedMessageIds: number;
+      lastProcessedTimestamp: number;
+      replayWindowSize: number;
+    }>;
+  }
+
+  export class GroupManager {
+    constructor(storage: StorageAdapter);
+    initialize(identity: Identity): Promise<void>;
+    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[]>;
+  }
+
+  export interface AegisIdentity {
+    identity: Identity;
+    publicBundle: PublicBundle;
+  }
+
+  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 Identity {
     kemKeyPair: { publicKey: Uint8Array; secretKey: Uint8Array };
@@ -109,17 +353,6 @@ declare module "@immahq/aegis" {
     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;
@@ -169,31 +402,4 @@ declare module "@immahq/aegis" {
     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/storage.js

@@ -1,3 +1,4 @@
+//Default storage adapter for the SDK. Stores data in memory.
 export class MemoryStorage {
     constructor() {
         Object.defineProperty(this, "identity", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immahq/aegis",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Lightweight, storage-agnostic library for client-side End-to-End (E2E) encryption",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,6 +33,7 @@
     "cryptography",
     "encryption",
     "e2e",
+    "e2ee",
     "end-to-end",
     "pqc",
     "post-quantum",
@@ -52,7 +53,6 @@
     "buffer": "^6.0.3"
   },
   "devDependencies": {
-    "@types/node": "^25.0.3",
     "rimraf": "^6.1.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",