nostr-double-ratchet 0.0.11 → 0.0.13

package/src/Invite.ts

@@ -1,13 +1,13 @@
 import { generateSecretKey, getPublicKey, nip44, finalizeEvent, VerifiedEvent, UnsignedEvent, verifyEvent, Filter } from "nostr-tools";
 import { INVITE_EVENT_KIND, NostrSubscribe, Unsubscribe } from "./types";
 import { getConversationKey } from "nostr-tools/nip44";
-import { Channel } from "./Channel";
+import { Session } from "./Session.ts";
 import { MESSAGE_EVENT_KIND } from "./types";
 import { EncryptFunction, DecryptFunction } from "./types";
 import { hexToBytes, bytesToHex } from "@noble/hashes/utils";
 
 /**
- * Invite is a safe way to exchange session keys and initiate secret channels.
+ * Invite is a safe way to exchange session keys and initiate secret sessions.
  * 
  * It can be shared privately as an URL (e.g. QR code) or published as a Nostr event.
  * 
@@ -18,10 +18,10 @@ import { hexToBytes, bytesToHex } from "@noble/hashes/utils";
  */
 export class Invite {
     constructor(
-        public inviterSessionPublicKey: string,
+        public inviterEphemeralPublicKey: string,
         public linkSecret: string,
         public inviter: string,
-        public inviterSessionPrivateKey?: Uint8Array,
+        public inviterEphemeralPrivateKey?: Uint8Array,
         public label?: string,
         public maxUses?: number,
         public usedBy: string[] = [],
@@ -31,14 +31,14 @@ export class Invite {
         if (!inviter) {
             throw new Error("Inviter public key is required");
         }
-        const inviterSessionPrivateKey = generateSecretKey();
-        const inviterSessionPublicKey = getPublicKey(inviterSessionPrivateKey);
+        const inviterEphemeralPrivateKey = generateSecretKey();
+        const inviterEphemeralPublicKey = getPublicKey(inviterEphemeralPrivateKey);
         const linkSecret = bytesToHex(generateSecretKey());
         return new Invite(
-            inviterSessionPublicKey,
+            inviterEphemeralPublicKey,
             linkSecret,
             inviter,
-            inviterSessionPrivateKey,
+            inviterEphemeralPrivateKey,
             label,
             maxUses
         );
@@ -59,13 +59,13 @@ export class Invite {
             throw new Error("Invite data in URL hash is not valid JSON: " + err);
         }
 
-        const { inviter, sessionKey, linkSecret } = data;
-        if (!inviter || !sessionKey || !linkSecret) {
-            throw new Error("Missing required fields (inviter, sessionKey, linkSecret) in invite data.");
+        const { inviter, ephemeralKey, linkSecret } = data;
+        if (!inviter || !ephemeralKey || !linkSecret) {
+            throw new Error("Missing required fields (inviter, ephemeralKey, linkSecret) in invite data.");
         }
 
         return new Invite(
-            sessionKey,
+            ephemeralKey,
             linkSecret,
             inviter
         );
@@ -74,10 +74,10 @@ export class Invite {
     static deserialize(json: string): Invite {
         const data = JSON.parse(json);
         return new Invite(
-            data.inviterSessionPublicKey,
+            data.inviterEphemeralPublicKey,
             data.linkSecret,
             data.inviter,
-            data.inviterSessionPrivateKey ? new Uint8Array(data.inviterSessionPrivateKey) : undefined,
+            data.inviterEphemeralPrivateKey ? new Uint8Array(data.inviterEphemeralPrivateKey) : undefined,
             data.label,
             data.maxUses,
             data.usedBy
@@ -92,16 +92,16 @@ export class Invite {
             throw new Error("Event signature is invalid");
         }
         const { tags } = event;
-        const inviterSessionPublicKey = tags.find(([key]) => key === 'sessionKey')?.[1];
+        const inviterEphemeralPublicKey = tags.find(([key]) => key === 'ephemeralKey')?.[1];
         const linkSecret = tags.find(([key]) => key === 'linkSecret')?.[1];
         const inviter = event.pubkey;
 
-        if (!inviterSessionPublicKey || !linkSecret) {
+        if (!inviterEphemeralPublicKey || !linkSecret) {
             throw new Error("Invalid invite event: missing session key or link secret");
         }
 
         return new Invite(
-            inviterSessionPublicKey,
+            inviterEphemeralPublicKey,
             linkSecret,
             inviter
         );
@@ -124,7 +124,7 @@ export class Invite {
                 const inviteLink = Invite.fromEvent(event);
                 onInvite(inviteLink);
             } catch (error) {
-                console.error("Error processing invite:", error);
+                console.error("Error processing invite:", error, "event:", event);
             }
         });
 
@@ -136,10 +136,10 @@ export class Invite {
      */
     serialize(): string {
         return JSON.stringify({
-            inviterSessionPublicKey: this.inviterSessionPublicKey,
+            inviterEphemeralPublicKey: this.inviterEphemeralPublicKey,
             linkSecret: this.linkSecret,
             inviter: this.inviter,
-            inviterSessionPrivateKey: this.inviterSessionPrivateKey ? Array.from(this.inviterSessionPrivateKey) : undefined,
+            inviterEphemeralPrivateKey: this.inviterEphemeralPrivateKey ? Array.from(this.inviterEphemeralPrivateKey) : undefined,
             label: this.label,
             maxUses: this.maxUses,
             usedBy: this.usedBy,
@@ -152,7 +152,7 @@ export class Invite {
     getUrl(root = "https://iris.to") {
         const data = {
             inviter: this.inviter,
-            sessionKey: this.inviterSessionPublicKey,
+            ephemeralKey: this.inviterEphemeralPublicKey,
             linkSecret: this.linkSecret
         };
         const url = new URL(root);
@@ -167,16 +167,16 @@ export class Invite {
             pubkey: this.inviter,
             content: "",
             created_at: Math.floor(Date.now() / 1000),
-            tags: [['sessionKey', this.inviterSessionPublicKey], ['linkSecret', this.linkSecret], ['d', 'nostr-double-ratchet/invite']],
+            tags: [['ephemeralKey', this.inviterEphemeralPublicKey], ['linkSecret', this.linkSecret], ['d', 'nostr-double-ratchet/invite']],
         };
     }
 
     /**
-     * Called by the invitee. Accepts the invite and creates a new channel with the inviter.
+     * Called by the invitee. Accepts the invite and creates a new session with the inviter.
      * 
      * @param inviteeSecretKey - The invitee's secret key or a signing function
      * @param nostrSubscribe - A function to subscribe to Nostr events
-     * @returns An object containing the new channel and an event to be published
+     * @returns An object containing the new session and an event to be published
      * 
      * 1. Inner event: No signature, content encrypted with DH(inviter, invitee).
      *    Purpose: Authenticate invitee. Contains invitee session key.
@@ -184,19 +184,19 @@ export class Invite {
      *    Purpose: Contains inner event. Hides invitee from others who might have the shared Nostr key.
 
      * Note: You need to publish the returned event on Nostr using NDK or another Nostr system of your choice,
-     * so the inviter can create the channel on their side.
+     * so the inviter can create the session on their side.
      */
     async accept(
         nostrSubscribe: NostrSubscribe,
         inviteePublicKey: string,
         inviteeSecretKey: Uint8Array | EncryptFunction,
-    ): Promise<{ channel: Channel, event: VerifiedEvent }> {
+    ): Promise<{ session: Session, event: VerifiedEvent }> {
         const inviteeSessionKey = generateSecretKey();
         const inviteeSessionPublicKey = getPublicKey(inviteeSessionKey);
-        const inviterPublicKey = this.inviter || this.inviterSessionPublicKey;
+        const inviterPublicKey = this.inviter || this.inviterEphemeralPublicKey;
 
         const sharedSecret = hexToBytes(this.linkSecret);
-        const channel = Channel.init(nostrSubscribe, this.inviterSessionPublicKey, inviteeSessionKey, true, sharedSecret, undefined);
+        const session = Session.init(nostrSubscribe, this.inviterEphemeralPublicKey, inviteeSessionKey, true, sharedSecret, undefined);
 
         // Create a random keypair for the envelope sender
         const randomSenderKey = generateSecretKey();
@@ -216,22 +216,22 @@ export class Invite {
         const envelope = {
             kind: MESSAGE_EVENT_KIND,
             pubkey: randomSenderPublicKey,
-            content: nip44.encrypt(JSON.stringify(innerEvent), getConversationKey(randomSenderKey, this.inviterSessionPublicKey)),
+            content: nip44.encrypt(JSON.stringify(innerEvent), getConversationKey(randomSenderKey, this.inviterEphemeralPublicKey)),
             created_at: Math.floor(Date.now() / 1000),
-            tags: [['p', this.inviterSessionPublicKey]],
+            tags: [['p', this.inviterEphemeralPublicKey]],
         };
 
-        return { channel, event: finalizeEvent(envelope, randomSenderKey) };
+        return { session, event: finalizeEvent(envelope, randomSenderKey) };
     }
 
-    listen(inviterSecretKey: Uint8Array | DecryptFunction, nostrSubscribe: NostrSubscribe, onChannel: (channel: Channel, identity?: string) => void): Unsubscribe {
-        if (!this.inviterSessionPrivateKey) {
+    listen(inviterSecretKey: Uint8Array | DecryptFunction, nostrSubscribe: NostrSubscribe, onSession: (session: Session, identity?: string) => void): Unsubscribe {
+        if (!this.inviterEphemeralPrivateKey) {
             throw new Error("Inviter session key is not available");
         }
         
         const filter = {
             kinds: [MESSAGE_EVENT_KIND],
-            '#p': [this.inviterSessionPublicKey],
+            '#p': [this.inviterEphemeralPublicKey],
         };
 
         return nostrSubscribe(filter, async (event) => {
@@ -241,7 +241,7 @@ export class Invite {
                     return;
                 }
 
-                const decrypted = await nip44.decrypt(event.content, getConversationKey(this.inviterSessionPrivateKey!, event.pubkey));
+                const decrypted = await nip44.decrypt(event.content, getConversationKey(this.inviterEphemeralPrivateKey!, event.pubkey));
                 const innerEvent = JSON.parse(decrypted);
 
                 if (!innerEvent.tags || !innerEvent.tags.some(([key, value]: [string, string]) => key === 'secret' && value === this.linkSecret)) {
@@ -260,11 +260,11 @@ export class Invite {
                 const sharedSecret = hexToBytes(this.linkSecret);
 
                 const name = event.id;
-                const channel = Channel.init(nostrSubscribe, inviteeSessionPublicKey, this.inviterSessionPrivateKey!, false, sharedSecret, name);
+                const session = Session.init(nostrSubscribe, inviteeSessionPublicKey, this.inviterEphemeralPrivateKey!, false, sharedSecret, name);
 
-                onChannel(channel, inviteeIdentity);
+                onSession(session, inviteeIdentity);
             } catch (error) {
-                console.error("Error processing invite message:", error);
+                console.error("Error processing invite message:", error, "event", event);
             }
         });
     }

package/src/{Channel.ts → Session.ts}

@@ -1,7 +1,7 @@
 import { generateSecretKey, getPublicKey, nip44, finalizeEvent, VerifiedEvent } from "nostr-tools";
 import { bytesToHex } from "@noble/hashes/utils";
 import {
-  ChannelState,
+  SessionState,
   Header,
   Unsubscribe,
   NostrSubscribe,
@@ -13,12 +13,12 @@ import { kdf, skippedMessageIndexKey } from "./utils";
 const MAX_SKIP = 1000;
 
 /**
- * Double ratchet secure communication channel over Nostr
+ * Double ratchet secure communication session over Nostr
  * 
  * Very similar to Signal's "Double Ratchet with header encryption"
  * https://signal.org/docs/specifications/doubleratchet/
  */
-export class Channel {
+export class Session {
   private nostrUnsubscribe?: Unsubscribe;
   private nostrNextUnsubscribe?: Unsubscribe;
   private internalSubscriptions = new Map<number, MessageCallback>();
@@ -26,21 +26,21 @@ export class Channel {
   public name: string;
 
   // 1. CHANNEL PUBLIC INTERFACE
-  constructor(private nostrSubscribe: NostrSubscribe, public state: ChannelState) {
+  constructor(private nostrSubscribe: NostrSubscribe, public state: SessionState) {
     this.name = Math.random().toString(36).substring(2, 6);
   }
 
   /**
-   * Initializes a new secure communication channel
+   * Initializes a new secure communication session
    * @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
+   * @param name Optional name for the session (for debugging)
+   * @returns A new Session instance
    */
-  static init(nostrSubscribe: NostrSubscribe, theirNostrPublicKey: string, ourCurrentPrivateKey: Uint8Array, isInitiator: boolean, sharedSecret: Uint8Array, name?: string): Channel {
+  static init(nostrSubscribe: NostrSubscribe, theirNostrPublicKey: string, ourCurrentPrivateKey: Uint8Array, isInitiator: boolean, sharedSecret: Uint8Array, name?: string): Session {
     const ourNextPrivateKey = generateSecretKey();
     const [rootKey, sendingChainKey] = kdf(sharedSecret, nip44.getConversationKey(ourNextPrivateKey, theirNostrPublicKey), 2);
     let ourCurrentNostrKey;
@@ -51,7 +51,7 @@ export class Channel {
     } else {
       ourNextNostrKey = { publicKey: getPublicKey(ourCurrentPrivateKey), privateKey: ourCurrentPrivateKey };
     }
-    const state: ChannelState = {
+    const state: SessionState = {
       rootKey: isInitiator ? rootKey : sharedSecret,
       theirNostrPublicKey,
       ourCurrentNostrKey,
@@ -64,13 +64,13 @@ export class Channel {
       skippedMessageKeys: {},
       skippedHeaderKeys: {},
     };
-    const channel = new Channel(nostrSubscribe, state);
-    if (name) channel.name = name;
-    return channel;
+    const session = new Session(nostrSubscribe, state);
+    if (name) session.name = name;
+    return session;
   }
 
   /**
-   * Sends an encrypted message through the channel
+   * Sends an encrypted message through the session
    * @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
@@ -96,7 +96,7 @@ export class Channel {
   }
 
   /**
-   * Subscribes to incoming messages on this channel
+   * Subscribes to incoming messages on this session
    * @param callback Function to be called when a message is received
    * @returns Unsubscribe function to stop receiving messages
    */

package/src/index.ts

@@ -1,4 +1,4 @@
-export * from "./Channel"
+export * from "./Session.ts"
 export * from "./Invite"
 export * from "./types"
 export * from "./utils"

package/src/types.ts

@@ -26,16 +26,16 @@ export type KeyPair = {
 }
 
 /** 
- * State of a Double Ratchet channel between two parties. Needed for persisting channels.
+ * State of a Double Ratchet session between two parties. Needed for persisting sessions.
  */
-export interface ChannelState {
+export interface SessionState {
   /** Root key used to derive new sending / receiving chain keys */
   rootKey: Uint8Array;
   
   /** The other party's current Nostr public key */
   theirNostrPublicKey: string;
 
-  /** Our current Nostr keypair used for this channel */
+  /** Our current Nostr keypair used for this session */
   ourCurrentNostrKey?: KeyPair;
   
   /** Our next Nostr keypair, used when ratcheting forward. It is advertised in messages we send. */

package/src/utils.ts

@@ -1,10 +1,10 @@
 import { hexToBytes, bytesToHex } from "@noble/hashes/utils";
-import { ChannelState, Message } from "./types";
-import { Channel } from "./Channel";
+import { SessionState, Message } from "./types";
+import { Session } from "./Session.ts";
 import { extract as hkdf_extract, expand as hkdf_expand } from '@noble/hashes/hkdf';
 import { sha256 } from '@noble/hashes/sha256';
 
-export function serializeChannelState(state: ChannelState): string {
+export function serializeSessionState(state: SessionState): string {
   return JSON.stringify({
     rootKey: bytesToHex(state.rootKey),
     theirNostrPublicKey: state.theirNostrPublicKey,
@@ -36,7 +36,7 @@ export function serializeChannelState(state: ChannelState): string {
   });
 }
 
-export function deserializeChannelState(data: string): ChannelState {
+export function deserializeSessionState(data: string): SessionState {
   const state = JSON.parse(data);
   return {
     rootKey: hexToBytes(state.rootKey),
@@ -69,11 +69,11 @@ export function deserializeChannelState(data: string): ChannelState {
   };
 }
 
-export async function* createMessageStream(channel: Channel): AsyncGenerator<Message, void, unknown> {
+export async function* createMessageStream(session: Session): AsyncGenerator<Message, void, unknown> {
   const messageQueue: Message[] = [];
   let resolveNext: ((value: Message) => void) | null = null;
 
-  const unsubscribe = channel.onMessage((message) => {
+  const unsubscribe = session.onMessage((message) => {
     if (resolveNext) {
       resolveNext(message);
       resolveNext = null;