@stvor/sdk 2.4.0 → 3.0.0

package/dist/ratchet/index.d.ts

@@ -1,88 +1,59 @@
 /**
  * X3DH + Double Ratchet Implementation
- * This module handles session establishment and message encryption/decryption.
+ * Uses ONLY Node.js built-in crypto module — zero external dependencies
+ *
+ * Implements the Signal Protocol Double Ratchet with deferred initialization:
+ *   - First send  → "initiator" DH ratchet (DH with peer's SPK)
+ *   - First receive → "responder" DH ratchet (use own SPK, then fresh key)
+ * This allows either side to send first after symmetric X3DH key agreement.
+ *
+ * Provides:
+ *   - X3DH key agreement (symmetric variant, both sides derive same SK)
+ *   - Double Ratchet with DH ratchet + symmetric-key ratchet
+ *   - AES-256-GCM AEAD encryption with header as AAD
+ *   - ECDSA P-256 signing / verification
+ *   - HKDF-SHA256 key derivation
+ *   - HMAC-based chain-key ratchet (Signal-style)
  */
+export interface KeyPair {
+    publicKey: Buffer;
+    privateKey: Buffer;
+}
 export interface SessionState {
+    myIdentityPublicKey: Buffer;
+    peerIdentityPublicKey: Buffer;
+    rootKey: Buffer;
+    sendingChainKey: Buffer;
+    receivingChainKey: Buffer;
+    myRatchetKeyPair: KeyPair;
+    theirRatchetPublicKey: Buffer | null;
+    sendCount: number;
+    recvCount: number;
+    prevSendCount: number;
+    skippedKeys: Map<string, Buffer>;
+    isPostCompromise: boolean;
+    peerSPK: Buffer | null;
+    mySPKPair: KeyPair | null;
     identityKey: Uint8Array;
     signedPreKey: Uint8Array;
     oneTimePreKey: Uint8Array;
-    rootKey: Uint8Array;
-    sendingChainKey: Uint8Array;
-    receivingChainKey: Uint8Array;
-    skippedMessageKeys: Map<string, Uint8Array>;
-    isPostCompromise: boolean;
+    sendingChainMessageNumber: number;
+    receivingChainMessageNumber: number;
+    previousSendingChainLength: number;
 }
 export declare function initializeCrypto(): Promise<void>;
-/**
- * X3DH Session Establishment
- * @param identityKeyPair - The user's identity key pair
- * @param signedPreKeyPair - The user's signed pre-key pair
- * @param oneTimePreKey - A one-time pre-key
- * @param recipientIdentityKey - The recipient's identity key
- * @param recipientSignedPreKey - The recipient's signed pre-key
- * @param recipientOneTimePreKey - The recipient's one-time pre-key
- * @param recipientSPKSignature - Signature of SPK by recipient's identity key
- * @param protocolVersion - The protocol version
- * @param cipherSuite - The cipher suite
- * @returns SessionState
- */
-export declare function establishSession(identityKeyPair: {
-    publicKey: Uint8Array;
-    privateKey: Uint8Array;
-}, signedPreKeyPair: {
-    publicKey: Uint8Array;
-    privateKey: Uint8Array;
-}, oneTimePreKey: Uint8Array, recipientIdentityKey: Uint8Array, recipientSignedPreKey: Uint8Array, recipientOneTimePreKey: Uint8Array, recipientSPKSignature: Uint8Array, protocolVersion: string, cipherSuite: string): SessionState;
-/**
- * Double Ratchet Encryption
- * @param plaintext - The message to encrypt
- * @param session - The current session state
- * @returns { ciphertext: Uint8Array; header: { publicKey: Uint8Array; nonce: Uint8Array } }
- */
-export declare function encryptMessage(plaintext: string, session: SessionState): {
-    ciphertext: any;
-    header: {
-        publicKey: any;
-        nonce: any;
-    };
+export declare function generateKeyPair(): KeyPair;
+/** ECDSA-P256-SHA256 sign */
+export declare function ecSign(data: Buffer, kp: KeyPair): Buffer;
+/** ECDSA-P256-SHA256 verify */
+export declare function ecVerify(data: Buffer, sig: Buffer, pub: Buffer): boolean;
+export declare function x3dhSymmetric(myIK: KeyPair, mySPK: KeyPair, peerIK: Buffer, peerSPK: Buffer): Buffer;
+export declare function establishSession(myIK: KeyPair, mySPK: KeyPair, peerIK: Buffer, peerSPK: Buffer): SessionState;
+export declare function encryptMessage(session: SessionState, plaintext: Buffer): {
+    ciphertext: Buffer;
+    header: Buffer;
 };
-/**
- * Double Ratchet Decryption
- * @param ciphertext - The encrypted message
- * @param header - The message header containing the sender's public key and nonce
- * @param session - The current session state
- * @returns The decrypted plaintext
- */
-export declare function decryptMessage(ciphertext: Uint8Array, header: {
-    publicKey: Uint8Array;
-    nonce: Uint8Array;
-}, session: SessionState): string;
-export declare function addSkippedKey(session: SessionState, header: {
-    publicKey: Uint8Array;
-    nonce: Uint8Array;
-}, messageKey: Uint8Array): void;
-export declare function removeSkippedKey(session: SessionState, header: {
-    publicKey: Uint8Array;
-    nonce: Uint8Array;
-}): void;
-export declare function processSkippedKeys(session: SessionState): void;
-export declare function handleSimultaneousSend(session: SessionState, isInitiator: boolean): void;
-export declare function generateOPKPool(): void;
-export declare function consumeOPKAtomically(userId: string): Uint8Array;
-export declare function enforceDHRatchetPolicy(session: SessionState, remotePublicKey: Uint8Array, suspectedCompromise?: boolean): void;
-/**
- * Increment message counter and enforce policy.
- */
-export declare function incrementMessageCounter(session: SessionState, remotePublicKey: Uint8Array): void;
-/**
- * Force a DH ratchet step to enable PCS.
- * @param session - The current session state.
- * @param remotePublicKey - The remote party's ephemeral public key.
- */
-export declare function forceDHRatchet(session: SessionState, remotePublicKey: Uint8Array): void;
-/**
- * Trigger PCS recovery only after receiving a new DH public key.
- * @param session - The current session state.
- * @param remotePublicKey - The new DH public key from the remote party.
- */
-export declare function receiveNewDHPublicKey(session: SessionState, remotePublicKey: Uint8Array): void;
+export declare function decryptMessage(session: SessionState, ciphertext: Buffer, header: Buffer): Buffer;
+export declare function forceRatchet(session: SessionState): void;
+export declare function serializeSession(s: SessionState): Buffer;
+export declare function deserializeSession(data: Buffer): SessionState;