@meshwhisper/sdk 0.1.0

package/dist/ratchet/index.js

@@ -0,0 +1,259 @@
+// ============================================================
+// MeshWhisper SDK — Double Ratchet Module
+// Per-message forward secrecy using the Signal Double Ratchet algorithm.
+// ============================================================
+import { x25519 } from '@noble/curves/ed25519';
+import { blake3 } from '@noble/hashes/blake3';
+import { concatBytes } from '@noble/hashes/utils';
+import { gcm } from '@noble/ciphers/aes';
+// ---- Constants ----
+const MAX_SKIP = 1000;
+const KEY_LENGTH = 32;
+const GCM_NONCE_LENGTH = 12;
+// ---- Key helpers ----
+/** Generate a fresh X25519 keypair for the DH ratchet. */
+function generateDHKeyPair() {
+    const secretKey = x25519.utils.randomSecretKey();
+    const publicKey = x25519.getPublicKey(secretKey);
+    return { privateKey: secretKey, publicKey };
+}
+/** Compute an X25519 shared secret. */
+function dh(keyPair, publicKey) {
+    return x25519.getSharedSecret(keyPair.privateKey, publicKey);
+}
+// ---- KDF operations ----
+/**
+ * KDF root step: derive a new root key and chain key from a root key and DH output.
+ * output = BLAKE3(rootKey || dhOutput, dkLen=64), split into two 32-byte halves.
+ */
+export function kdfRootStep(rootKey, dhOutput) {
+    const input = concatBytes(rootKey, dhOutput);
+    const output = blake3(input, { dkLen: 64, key: rootKey });
+    return {
+        newRootKey: output.slice(0, KEY_LENGTH),
+        chainKey: output.slice(KEY_LENGTH, KEY_LENGTH * 2),
+    };
+}
+/**
+ * KDF chain step: derive a message key and the next chain key from the current chain key.
+ * messageKey  = BLAKE3(chainKey || 0x01)
+ * newChainKey = BLAKE3(chainKey || 0x02)
+ */
+export function kdfChainStep(chainKey) {
+    const messageKey = blake3(concatBytes(chainKey, new Uint8Array([0x01])));
+    const newChainKey = blake3(concatBytes(chainKey, new Uint8Array([0x02])));
+    return { newChainKey, messageKey };
+}
+// ---- Skipped-key bookkeeping ----
+/** Build a map key for a skipped message from the sender's DH public key and the message number. */
+function skippedKeyId(dhPublicKey, messageNumber) {
+    // Encode as hex(dhPub) + ":" + messageNumber for uniqueness.
+    let hex = '';
+    for (let i = 0; i < dhPublicKey.length; i++) {
+        hex += dhPublicKey[i].toString(16).padStart(2, '0');
+    }
+    return hex + ':' + messageNumber;
+}
+/**
+ * Skip ahead in the receiving chain, storing message keys for out-of-order messages.
+ * Throws if too many messages would be skipped (DoS protection).
+ */
+function skipMessageKeys(state, until) {
+    if (state.receivingChainKey === null) {
+        return state;
+    }
+    if (until - state.receiveMessageNumber > MAX_SKIP) {
+        throw new Error(`Cannot skip more than ${MAX_SKIP} messages (requested skip of ${until - state.receiveMessageNumber})`);
+    }
+    const skippedMessageKeys = new Map(state.skippedMessageKeys);
+    let chainKey = state.receivingChainKey;
+    let n = state.receiveMessageNumber;
+    while (n < until) {
+        const { newChainKey, messageKey } = kdfChainStep(chainKey);
+        const id = skippedKeyId(state.dhReceiving, n);
+        skippedMessageKeys.set(id, messageKey);
+        chainKey = newChainKey;
+        n++;
+    }
+    return {
+        ...state,
+        receivingChainKey: chainKey,
+        receiveMessageNumber: n,
+        skippedMessageKeys,
+    };
+}
+// ---- DH ratchet step ----
+/**
+ * Perform a DH ratchet step: compute new root key / receiving chain key from the
+ * remote's new public key, then generate a new sending keypair and compute the
+ * sending chain key.
+ */
+export function dhRatchetStep(state, remotePublicKey) {
+    const previousSendingChainLength = state.sendMessageNumber;
+    // Receiving side: DH with our current sending keypair and their new public key.
+    const dhReceiveOutput = dh(state.dhSending, remotePublicKey);
+    const { newRootKey: rootKey1, chainKey: receivingChainKey } = kdfRootStep(state.rootKey, dhReceiveOutput);
+    // Sending side: generate new DH keypair, compute DH with new keypair and their public key.
+    const dhSending = generateDHKeyPair();
+    const dhSendOutput = dh(dhSending, remotePublicKey);
+    const { newRootKey: rootKey2, chainKey: sendingChainKey } = kdfRootStep(rootKey1, dhSendOutput);
+    return {
+        ...state,
+        dhSending,
+        dhReceiving: remotePublicKey,
+        rootKey: rootKey2,
+        sendingChainKey,
+        receivingChainKey,
+        sendMessageNumber: 0,
+        receiveMessageNumber: 0,
+        previousSendingChainLength,
+    };
+}
+// ---- Encrypt / Decrypt helpers ----
+/** Encrypt plaintext with AES-256-GCM using a message key. Nonce is derived deterministically. */
+function aesEncrypt(messageKey, plaintext) {
+    // Derive a nonce from the message key via BLAKE3 to avoid needing random state.
+    const nonce = blake3(messageKey, { dkLen: GCM_NONCE_LENGTH });
+    const cipher = gcm(messageKey, nonce);
+    const ciphertext = cipher.encrypt(plaintext);
+    // Prepend nonce so the receiver can decrypt.
+    return concatBytes(nonce, ciphertext);
+}
+/** Decrypt ciphertext produced by aesEncrypt. */
+function aesDecrypt(messageKey, nonceAndCiphertext) {
+    const nonce = nonceAndCiphertext.slice(0, GCM_NONCE_LENGTH);
+    const ciphertext = nonceAndCiphertext.slice(GCM_NONCE_LENGTH);
+    const cipher = gcm(messageKey, nonce);
+    return cipher.decrypt(ciphertext);
+}
+// ---- Initialization ----
+/**
+ * Initialize the ratchet state as the sender (initiator) after X3DH.
+ *
+ * The sender knows the shared secret and the remote's signed pre-key (or ratchet public key).
+ * It performs the first DH ratchet step immediately so it can begin sending.
+ */
+export function initSender(sharedSecret, remotePublicKey) {
+    const dhSending = generateDHKeyPair();
+    const dhOutput = dh(dhSending, remotePublicKey);
+    const { newRootKey, chainKey } = kdfRootStep(sharedSecret, dhOutput);
+    return {
+        dhSending,
+        dhReceiving: remotePublicKey,
+        rootKey: newRootKey,
+        sendingChainKey: chainKey,
+        receivingChainKey: null,
+        sendMessageNumber: 0,
+        receiveMessageNumber: 0,
+        previousSendingChainLength: 0,
+        skippedMessageKeys: new Map(),
+    };
+}
+/**
+ * Initialize the ratchet state as the receiver (responder) after X3DH.
+ *
+ * The receiver provides its own keypair (the signed pre-key used in X3DH) and
+ * the shared secret. It waits for the first message to complete the DH ratchet.
+ */
+export function initReceiver(sharedSecret, localKeyPair) {
+    return {
+        dhSending: localKeyPair,
+        dhReceiving: null,
+        rootKey: sharedSecret,
+        sendingChainKey: null,
+        receivingChainKey: null,
+        sendMessageNumber: 0,
+        receiveMessageNumber: 0,
+        previousSendingChainLength: 0,
+        skippedMessageKeys: new Map(),
+    };
+}
+// ---- Encrypt ----
+/**
+ * Encrypt a plaintext message, advancing the sending chain.
+ *
+ * Returns the updated state, a header (to be sent alongside the ciphertext), and
+ * the AES-256-GCM ciphertext.
+ */
+export function ratchetEncrypt(state, plaintext) {
+    if (state.sendingChainKey === null) {
+        throw new Error('Sending chain not initialized — cannot encrypt before the first DH ratchet step');
+    }
+    const { newChainKey, messageKey } = kdfChainStep(state.sendingChainKey);
+    const header = {
+        dhPublicKey: state.dhSending.publicKey,
+        previousChainLength: state.previousSendingChainLength,
+        messageNumber: state.sendMessageNumber,
+    };
+    const ciphertext = aesEncrypt(messageKey, plaintext);
+    const newState = {
+        ...state,
+        sendingChainKey: newChainKey,
+        sendMessageNumber: state.sendMessageNumber + 1,
+    };
+    return { state: newState, header, ciphertext };
+}
+// ---- Decrypt ----
+/**
+ * Decrypt a received message, handling DH ratchet steps and out-of-order delivery.
+ *
+ * 1. Try skipped message keys first (for out-of-order messages).
+ * 2. If the header's DH public key differs from our stored remote key, perform
+ *    a DH ratchet step (advancing the root chain).
+ * 3. Advance the receiving chain to the header's message number, storing any
+ *    skipped message keys along the way.
+ * 4. Decrypt with the derived message key.
+ */
+export function ratchetDecrypt(state, header, ciphertext) {
+    // 1. Check skipped message keys.
+    const skippedId = skippedKeyId(header.dhPublicKey, header.messageNumber);
+    const skippedKey = state.skippedMessageKeys.get(skippedId);
+    if (skippedKey !== undefined) {
+        const skippedMessageKeys = new Map(state.skippedMessageKeys);
+        skippedMessageKeys.delete(skippedId);
+        const plaintext = aesDecrypt(skippedKey, ciphertext);
+        return {
+            state: { ...state, skippedMessageKeys },
+            plaintext,
+        };
+    }
+    let currentState = state;
+    // 2. DH ratchet step if the remote key has changed.
+    const remoteKeyChanged = currentState.dhReceiving === null ||
+        !bytesEqual(header.dhPublicKey, currentState.dhReceiving);
+    if (remoteKeyChanged) {
+        // Skip any remaining messages on the old receiving chain.
+        if (currentState.dhReceiving !== null && currentState.receivingChainKey !== null) {
+            currentState = skipMessageKeys(currentState, header.previousChainLength);
+        }
+        currentState = dhRatchetStep(currentState, header.dhPublicKey);
+    }
+    // 3. Skip messages on the current receiving chain up to this message number.
+    currentState = skipMessageKeys(currentState, header.messageNumber);
+    // 4. Derive the message key.
+    if (currentState.receivingChainKey === null) {
+        throw new Error('Receiving chain key is null — protocol state error');
+    }
+    const { newChainKey, messageKey } = kdfChainStep(currentState.receivingChainKey);
+    const plaintext = aesDecrypt(messageKey, ciphertext);
+    return {
+        state: {
+            ...currentState,
+            receivingChainKey: newChainKey,
+            receiveMessageNumber: currentState.receiveMessageNumber + 1,
+        },
+        plaintext,
+    };
+}
+// ---- Utility ----
+/** Constant-time(ish) byte array comparison. */
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a[i] ^ b[i];
+    }
+    return diff === 0;
+}
+//# sourceMappingURL=index.js.map

package/dist/ratchet/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ratchet/index.ts"],"names":[],"mappings":"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"}

package/dist/reciprocity/index.d.ts

@@ -0,0 +1,109 @@
+import { RelayLedgerEntry, ReciprocityTier } from '../types.js';
+export interface RelayLedgerOptions {
+    /** Duration of the new-device grace period, in hours. Defaults to 48. */
+    gracePeriodHours?: number;
+}
+/**
+ * Tracks bytes relayed for and by each peer, computes reciprocity scores,
+ * and makes relay-priority decisions.  Purely local and approximate — there
+ * is no global accounting.
+ */
+export declare class RelayLedger {
+    private readonly gracePeriodMs;
+    private entries;
+    private deviceId;
+    private deviceRegisteredAt;
+    constructor(options?: RelayLedgerOptions);
+    /**
+     * Record that we relayed `bytes` of data on behalf of `peerId`.
+     */
+    recordRelayedForPeer(peerId: string, bytes: number): void;
+    /**
+     * Record that `peerId` relayed `bytes` of data for us.
+     */
+    recordPeerRelayedForUs(peerId: string, bytes: number): void;
+    /**
+     * Return the ledger entry for a given peer, or `null` if none exists.
+     */
+    getEntry(peerId: string): RelayLedgerEntry | null;
+    /**
+     * Return a snapshot of all ledger entries.
+     */
+    getAllEntries(): RelayLedgerEntry[];
+    /**
+     * Compute the reciprocity score for a specific peer.
+     *
+     * Score = bytes_relayed_for_them / bytes_they_relayed_for_us
+     *
+     * - If neither party has relayed anything, returns 1.0 (neutral).
+     * - If we have relayed for them but they haven't for us, returns Infinity
+     *   (we are a pure contributor to this peer).
+     * - If they have relayed for us but we haven't for them, returns 0.0
+     *   (we are a pure consumer from this peer).
+     */
+    getScore(peerId: string): number;
+    /**
+     * Compute the aggregate reciprocity score across all peers.
+     *
+     * Uses total bytes relayed for all peers vs total bytes all peers
+     * relayed for us.
+     */
+    getGlobalScore(): number;
+    /**
+     * Determine the reciprocity tier for a given peer.
+     */
+    getTier(peerId: string): ReciprocityTier;
+    /**
+     * Determine whether we should relay traffic for this peer.
+     *
+     * Free-riders are refused unless we are still in our grace period.
+     */
+    shouldRelay(peerId: string): boolean;
+    /**
+     * Return a relay-queue priority between 0.0 and 1.0 for this peer.
+     *
+     * Higher values mean packets for/from this peer should be relayed sooner.
+     */
+    getRelayPriority(peerId: string): number;
+    /**
+     * Register this device, recording the current time as the creation
+     * timestamp for grace-period purposes.
+     */
+    registerDevice(deviceId: string): void;
+    /**
+     * Returns `true` if this device was registered within the configured
+     * grace period (default 48 hours).
+     */
+    isInGracePeriod(): boolean;
+    /**
+     * Apply exponential decay to every entry in the ledger.
+     *
+     * Multiplies both byte counters by `factor` (should be between 0 and 1).
+     * This prevents ancient history from permanently dominating the score.
+     */
+    decayLedger(factor: number): void;
+    /**
+     * Remove entries for peers whose `lastUpdated` timestamp is older
+     * than `maxAgeMs` milliseconds ago.
+     */
+    pruneInactive(maxAgeMs: number): void;
+    /**
+     * Clear all ledger entries.  Device registration is preserved.
+     */
+    reset(): void;
+    /**
+     * Serialize the entire ledger state to a `Uint8Array` for persistence.
+     */
+    serialize(): Uint8Array;
+    /**
+     * Restore a `RelayLedger` from previously serialized data.
+     */
+    static deserialize(data: Uint8Array): RelayLedger;
+    /**
+     * Map a numeric reciprocity score to a tier label.
+     */
+    static tierFromScore(score: number): ReciprocityTier;
+    private getOrCreateEntry;
+    private computeScore;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/reciprocity/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/reciprocity/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA2BhE,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAkBD;;;;GAIG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,OAAO,CAA4C;IAC3D,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,kBAAkB,CAAuB;gBAErC,OAAO,CAAC,EAAE,kBAAkB;IAYxC;;OAEG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IASzD;;OAEG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAS3D;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAKjD;;OAEG;IACH,aAAa,IAAI,gBAAgB,EAAE;IAQnC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAQhC;;;;;OAKG;IACH,cAAc,IAAI,MAAM;IAUxB;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe;IAYxC;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAOpC;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAkBxC;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQtC;;;OAGG;IACH,eAAe,IAAI,OAAO;IAW1B;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAUjC;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAYrC;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,SAAS,IAAI,UAAU;IAYvB;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW;IAwCjD;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe;IAWpD,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,YAAY;CASrB"}