nostr-double-ratchet 0.0.3 → 0.0.5

package/src/Channel.ts

@@ -13,7 +13,9 @@ import { kdf, skippedMessageIndexKey } from "./utils";
 const MAX_SKIP = 1000;
 
 /**
- * Similar to Signal's "Double Ratchet with header encryption"
+ * Double ratchet secure communication channel over Nostr
+ * 
+ * Very similar to Signal's "Double Ratchet with header encryption"
  * https://signal.org/docs/specifications/doubleratchet/
  */
 export class Channel {
@@ -23,15 +25,22 @@ export class Channel {
   private currentInternalSubscriptionId = 0;
   public name: string;
 
+  // 1. CHANNEL PUBLIC INTERFACE
   constructor(private nostrSubscribe: NostrSubscribe, public state: ChannelState) {
     this.name = Math.random().toString(36).substring(2, 6);
   }
 
   /**
-   * @param sharedSecret optional, but useful to keep the first chain of messages secure. Unlike the Nostr keys, it can be forgotten after the 1st message in the chain.
-   * @param isInitiator determines which chain key is used for sending vs receiving
+   * Initializes a new secure communication channel
+   * @param nostrSubscribe Function to subscribe to Nostr events
+   * @param theirNostrPublicKey The public key of the other party
+   * @param ourCurrentPrivateKey Our current private key for Nostr
+   * @param isInitiator Whether we are initiating the conversation (true) or responding (false)
+   * @param sharedSecret Initial shared secret for securing the first message chain
+   * @param name Optional name for the channel (for debugging)
+   * @returns A new Channel instance
    */
-  static init(nostrSubscribe: NostrSubscribe, theirNostrPublicKey: string, ourCurrentPrivateKey: Uint8Array, sharedSecret = new Uint8Array(), name?: string, isInitiator = true): Channel {
+  static init(nostrSubscribe: NostrSubscribe, theirNostrPublicKey: string, ourCurrentPrivateKey: Uint8Array, isInitiator: boolean, sharedSecret: Uint8Array, name?: string): Channel {
     const ourNextPrivateKey = generateSecretKey();
     const [rootKey, sendingChainKey] = kdf(sharedSecret, nip44.getConversationKey(ourNextPrivateKey, theirNostrPublicKey), 2);
     let ourCurrentNostrKey;
@@ -56,10 +65,15 @@ export class Channel {
     };
     const channel = new Channel(nostrSubscribe, state);
     if (name) channel.name = name;
-    console.log(channel.name, 'initial root key', bytesToHex(state.rootKey).slice(0,4))
     return channel;
   }
 
+  /**
+   * Sends an encrypted message through the channel
+   * @param data The plaintext message to send
+   * @returns A verified Nostr event containing the encrypted message
+   * @throws Error if we are not the initiator and trying to send the first message
+   */
   send(data: string): VerifiedEvent {
     if (!this.state.theirNostrPublicKey || !this.state.ourCurrentNostrKey) {
       throw new Error("we are not the initiator, so we can't send the first message");
@@ -80,6 +94,11 @@ export class Channel {
     return nostrEvent;
   }
 
+  /**
+   * Subscribes to incoming messages on this channel
+   * @param callback Function to be called when a message is received
+   * @returns Unsubscribe function to stop receiving messages
+   */
   onMessage(callback: MessageCallback): Unsubscribe {
     const id = this.currentInternalSubscriptionId++
     this.internalSubscriptions.set(id, callback)
@@ -87,6 +106,7 @@ export class Channel {
     return () => this.internalSubscriptions.delete(id)
   }
 
+  // 2. RATCHET FUNCTIONS
   private ratchetEncrypt(plaintext: string): [Header, string] {
     const [newSendingChainKey, messageKey] = kdf(this.state.sendingChainKey!, new Uint8Array([1]), 2);
     this.state.sendingChainKey = newSendingChainKey;
@@ -129,7 +149,7 @@ export class Channel {
     this.state.theirNostrPublicKey = theirNostrPublicKey;
 
     const conversationKey1 = nip44.getConversationKey(this.state.ourNextNostrKey.privateKey, this.state.theirNostrPublicKey!);
-    const [intermediateRootKey, receivingChainKey] = kdf(this.state.rootKey, conversationKey1, 3);
+    const [theirRootKey, receivingChainKey] = kdf(this.state.rootKey, conversationKey1, 2);
 
     this.state.receivingChainKey = receivingChainKey;
 
@@ -141,11 +161,12 @@ export class Channel {
     };
 
     const conversationKey2 = nip44.getConversationKey(this.state.ourNextNostrKey.privateKey, this.state.theirNostrPublicKey!);
-    const [rootKey2, sendingChainKey] = kdf(intermediateRootKey, conversationKey2, 3);
-    this.state.rootKey = rootKey2;
+    const [rootKey, sendingChainKey] = kdf(theirRootKey, conversationKey2, 2);
+    this.state.rootKey = rootKey;
     this.state.sendingChainKey = sendingChainKey;
   }
 
+  // 3. MESSAGE KEY FUNCTIONS
   private skipMessageKeys(until: number, nostrSender: string) {
     if (this.state.receivingChainMessageNumber + MAX_SKIP < until) {
       throw new Error("Too many skipped messages");
@@ -169,10 +190,11 @@ export class Channel {
     return null;
   }
 
-  private decryptHeader(e: any): [Header, boolean] {
-    const encryptedHeader = e.tags[0][1];
+  // 4. NOSTR EVENT HANDLING
+  private decryptHeader(event: any): [Header, boolean] {
+    const encryptedHeader = event.tags[0][1];
     if (this.state.ourCurrentNostrKey) {
-      const currentSecret = nip44.getConversationKey(this.state.ourCurrentNostrKey.privateKey, e.pubkey);
+      const currentSecret = nip44.getConversationKey(this.state.ourCurrentNostrKey.privateKey, event.pubkey);
       try {
         const header = JSON.parse(nip44.decrypt(encryptedHeader, currentSecret)) as Header;
         return [header, false];
@@ -181,7 +203,7 @@ export class Channel {
       }
     }
 
-    const nextSecret = nip44.getConversationKey(this.state.ourNextNostrKey.privateKey, e.pubkey);
+    const nextSecret = nip44.getConversationKey(this.state.ourNextNostrKey.privateKey, event.pubkey);
     try {
       const header = JSON.parse(nip44.decrypt(encryptedHeader, nextSecret)) as Header;
       return [header, true];
@@ -217,15 +239,27 @@ export class Channel {
 
   private subscribeToNostrEvents() {
     if (this.nostrNextUnsubscribe) return;
-    if (this.state.theirNostrPublicKey) {
-      this.nostrUnsubscribe = this.nostrSubscribe(
-        {authors: [this.state.theirNostrPublicKey], kinds: [EVENT_KIND]},
-        (e) => this.handleNostrEvent(e)
-      );
-    }
     this.nostrNextUnsubscribe = this.nostrSubscribe(
       {authors: [this.state.theirNostrPublicKey], kinds: [EVENT_KIND]},
       (e) => this.handleNostrEvent(e)
     );
+    
+    // Subscribe to all public keys from skipped messages
+    const uniquePublicKeys = new Set<string>();
+    for (const key of Object.keys(this.state.skippedMessageKeys)) {
+      const [pubkey] = key.split(':');
+      if (pubkey !== this.state.theirNostrPublicKey) {
+        uniquePublicKeys.add(pubkey);
+      }
+    }
+
+    if (uniquePublicKeys.size > 0) {
+      // do we want this unsubscribed on rotation or should we keep it open
+      // in case more skipped messages are found by relays or peers?
+      this.nostrUnsubscribe = this.nostrSubscribe(
+        {authors: Array.from(uniquePublicKeys), kinds: [EVENT_KIND]},
+        (e) => this.handleNostrEvent(e)
+      );
+    }
   }
 }

package/src/InviteLink.ts

@@ -1,10 +1,10 @@
 import { generateSecretKey, getPublicKey, nip44, finalizeEvent, VerifiedEvent, nip19 } from "nostr-tools";
-import { base58 } from '@scure/base';
 import { NostrSubscribe, Unsubscribe } from "./types";
 import { getConversationKey } from "nostr-tools/nip44";
 import { Channel } from "./Channel";
 import { EVENT_KIND } from "./types";
 import { EncryptFunction, DecryptFunction } from "./types";
+import { hexToBytes, bytesToHex } from "@noble/hashes/utils";
 
 /**
  * Invite link is a safe way to exchange session keys and initiate secret channels.
@@ -31,7 +31,7 @@ export class InviteLink {
     static createNew(inviter: string, label?: string, maxUses?: number): InviteLink {
         const inviterSessionPrivateKey = generateSecretKey();
         const inviterSessionPublicKey = getPublicKey(inviterSessionPrivateKey);
-        const linkSecret = base58.encode(generateSecretKey()).slice(8, 40);
+        const linkSecret = bytesToHex(generateSecretKey());
         return new InviteLink(
             inviterSessionPublicKey,
             linkSecret,
@@ -127,7 +127,8 @@ export class InviteLink {
         const inviteeSessionPublicKey = getPublicKey(inviteeSessionKey);
         const inviterPublicKey = this.inviter || this.inviterSessionPublicKey;
 
-        const channel = Channel.init(nostrSubscribe, this.inviterSessionPublicKey, inviteeSessionKey, new Uint8Array(), undefined, true);
+        const sharedSecret = hexToBytes(this.linkSecret);
+        const channel = Channel.init(nostrSubscribe, this.inviterSessionPublicKey, inviteeSessionKey, true, sharedSecret, undefined);
 
         // Create a random keypair for the envelope sender
         const randomSenderKey = generateSecretKey();
@@ -180,9 +181,10 @@ export class InviteLink {
                     (ciphertext: string, pubkey: string) => Promise.resolve(nip44.decrypt(ciphertext, getConversationKey(inviterSecretKey, pubkey)));
     
                 const inviteeSessionPublicKey = await innerDecrypt(innerEvent.content, innerEvent.pubkey);
+                const sharedSecret = hexToBytes(this.linkSecret);
 
                 const name = event.id;
-                const channel = Channel.init(nostrSubscribe, inviteeSessionPublicKey, this.inviterSessionPrivateKey!, new Uint8Array(), name, false);
+                const channel = Channel.init(nostrSubscribe, inviteeSessionPublicKey, this.inviterSessionPrivateKey!, false, sharedSecret, name);
 
                 onChannel(channel, innerEvent.pubkey);
             } catch (error) {

package/src/types.ts

@@ -1,5 +1,8 @@
 import { VerifiedEvent } from "nostr-tools";
 
+/**
+ * An event that has been verified to be from the Nostr network.
+ */
 export type Message = {
   id: string;
   data: string;
@@ -19,13 +22,16 @@ export type NostrFilter = {
   kinds?: number[];
 }
 
+/**
+ * A keypair used for encryption and decryption.
+ */
 export type KeyPair = {
   publicKey: string;
   privateKey: Uint8Array;
 }
 
 /** 
- * Represents the state of a Double Ratchet channel between two parties. Needed for persisting channels.
+ * State of a Double Ratchet channel between two parties. Needed for persisting channels.
  */
 export interface ChannelState {
   /** Root key used to derive new sending / receiving chain keys */
@@ -59,8 +65,20 @@ export interface ChannelState {
   skippedMessageKeys: Record<string, Uint8Array>;
 }
 
+/**
+ * Unsubscribe from a subscription or event listener.
+ */
 export type Unsubscribe = () => void;
+
+/** 
+ * Function that subscribes to Nostr events matching a filter and calls onEvent for each event.
+ */
 export type NostrSubscribe = (filter: NostrFilter, onEvent: (e: VerifiedEvent) => void) => Unsubscribe;
+
+/** 
+ * Callback function for handling decrypted messages
+ * @param message - The decrypted message object
+ */
 export type MessageCallback = (message: Message) => void;
 
 export const EVENT_KIND = 4;