@meshwhisper/sdk 0.1.0

package/dist/reciprocity/index.js

@@ -0,0 +1,311 @@
+// ============================================================
+// MeshWhisper SDK — Reciprocity Engine
+// Maintains a local relay ledger implementing tit-for-tat
+// relay fairness as described in PRD section 7.3.
+// ============================================================
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default grace period for newly registered devices (48 hours). */
+const DEFAULT_GRACE_PERIOD_HOURS = 48;
+/** Tier thresholds for reciprocity scoring. */
+const TIER_CONTRIBUTOR_THRESHOLD = 1.0;
+const TIER_BALANCED_THRESHOLD = 0.5;
+const TIER_CONSUMER_THRESHOLD = 0.1;
+/** Relay priority values per tier. */
+const PRIORITY_CONTRIBUTOR = 1.0;
+const PRIORITY_BALANCED = 0.7;
+const PRIORITY_CONSUMER = 0.3;
+const PRIORITY_FREERIDER = 0.0;
+/** Serialization format version. */
+const SERIALIZATION_VERSION = 1;
+// ---------------------------------------------------------------------------
+// RelayLedger
+// ---------------------------------------------------------------------------
+/**
+ * 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 class RelayLedger {
+    gracePeriodMs;
+    entries = new Map();
+    deviceId = null;
+    deviceRegisteredAt = null;
+    constructor(options) {
+        const hours = options?.gracePeriodHours ?? DEFAULT_GRACE_PERIOD_HOURS;
+        if (hours < 0) {
+            throw new RangeError('gracePeriodHours must be non-negative');
+        }
+        this.gracePeriodMs = hours * 60 * 60 * 1000;
+    }
+    // -----------------------------------------------------------------------
+    // Ledger operations
+    // -----------------------------------------------------------------------
+    /**
+     * Record that we relayed `bytes` of data on behalf of `peerId`.
+     */
+    recordRelayedForPeer(peerId, bytes) {
+        if (bytes < 0) {
+            throw new RangeError('bytes must be non-negative');
+        }
+        const entry = this.getOrCreateEntry(peerId);
+        entry.bytesRelayedForThem += bytes;
+        entry.lastUpdated = Date.now();
+    }
+    /**
+     * Record that `peerId` relayed `bytes` of data for us.
+     */
+    recordPeerRelayedForUs(peerId, bytes) {
+        if (bytes < 0) {
+            throw new RangeError('bytes must be non-negative');
+        }
+        const entry = this.getOrCreateEntry(peerId);
+        entry.bytesTheyRelayedForUs += bytes;
+        entry.lastUpdated = Date.now();
+    }
+    /**
+     * Return the ledger entry for a given peer, or `null` if none exists.
+     */
+    getEntry(peerId) {
+        const entry = this.entries.get(peerId);
+        return entry ? { ...entry } : null;
+    }
+    /**
+     * Return a snapshot of all ledger entries.
+     */
+    getAllEntries() {
+        return Array.from(this.entries.values()).map((e) => ({ ...e }));
+    }
+    // -----------------------------------------------------------------------
+    // Score computation
+    // -----------------------------------------------------------------------
+    /**
+     * 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) {
+        const entry = this.entries.get(peerId);
+        if (!entry) {
+            return 1.0; // unknown peer — treat as neutral
+        }
+        return this.computeScore(entry.bytesRelayedForThem, entry.bytesTheyRelayedForUs);
+    }
+    /**
+     * Compute the aggregate reciprocity score across all peers.
+     *
+     * Uses total bytes relayed for all peers vs total bytes all peers
+     * relayed for us.
+     */
+    getGlobalScore() {
+        let totalRelayedForThem = 0;
+        let totalTheyRelayedForUs = 0;
+        for (const entry of this.entries.values()) {
+            totalRelayedForThem += entry.bytesRelayedForThem;
+            totalTheyRelayedForUs += entry.bytesTheyRelayedForUs;
+        }
+        return this.computeScore(totalRelayedForThem, totalTheyRelayedForUs);
+    }
+    /**
+     * Determine the reciprocity tier for a given peer.
+     */
+    getTier(peerId) {
+        if (this.isInGracePeriod()) {
+            return 'balanced';
+        }
+        const score = this.getScore(peerId);
+        return RelayLedger.tierFromScore(score);
+    }
+    // -----------------------------------------------------------------------
+    // Relay priority
+    // -----------------------------------------------------------------------
+    /**
+     * Determine whether we should relay traffic for this peer.
+     *
+     * Free-riders are refused unless we are still in our grace period.
+     */
+    shouldRelay(peerId) {
+        if (this.isInGracePeriod()) {
+            return true;
+        }
+        return this.getTier(peerId) !== 'freerider';
+    }
+    /**
+     * 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) {
+        const tier = this.getTier(peerId);
+        switch (tier) {
+            case 'contributor':
+                return PRIORITY_CONTRIBUTOR;
+            case 'balanced':
+                return PRIORITY_BALANCED;
+            case 'consumer':
+                return PRIORITY_CONSUMER;
+            case 'freerider':
+                return PRIORITY_FREERIDER;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Grace period
+    // -----------------------------------------------------------------------
+    /**
+     * Register this device, recording the current time as the creation
+     * timestamp for grace-period purposes.
+     */
+    registerDevice(deviceId) {
+        if (!deviceId) {
+            throw new TypeError('deviceId must be a non-empty string');
+        }
+        this.deviceId = deviceId;
+        this.deviceRegisteredAt = Date.now();
+    }
+    /**
+     * Returns `true` if this device was registered within the configured
+     * grace period (default 48 hours).
+     */
+    isInGracePeriod() {
+        if (this.deviceRegisteredAt === null) {
+            return false;
+        }
+        return Date.now() - this.deviceRegisteredAt < this.gracePeriodMs;
+    }
+    // -----------------------------------------------------------------------
+    // Ledger maintenance
+    // -----------------------------------------------------------------------
+    /**
+     * 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) {
+        if (factor < 0 || factor > 1) {
+            throw new RangeError('decay factor must be between 0 and 1');
+        }
+        for (const entry of this.entries.values()) {
+            entry.bytesRelayedForThem = Math.floor(entry.bytesRelayedForThem * factor);
+            entry.bytesTheyRelayedForUs = Math.floor(entry.bytesTheyRelayedForUs * factor);
+        }
+    }
+    /**
+     * Remove entries for peers whose `lastUpdated` timestamp is older
+     * than `maxAgeMs` milliseconds ago.
+     */
+    pruneInactive(maxAgeMs) {
+        if (maxAgeMs < 0) {
+            throw new RangeError('maxAgeMs must be non-negative');
+        }
+        const cutoff = Date.now() - maxAgeMs;
+        for (const [peerId, entry] of this.entries) {
+            if (entry.lastUpdated < cutoff) {
+                this.entries.delete(peerId);
+            }
+        }
+    }
+    /**
+     * Clear all ledger entries.  Device registration is preserved.
+     */
+    reset() {
+        this.entries.clear();
+    }
+    // -----------------------------------------------------------------------
+    // Serialization
+    // -----------------------------------------------------------------------
+    /**
+     * Serialize the entire ledger state to a `Uint8Array` for persistence.
+     */
+    serialize() {
+        const payload = {
+            version: SERIALIZATION_VERSION,
+            gracePeriodHours: this.gracePeriodMs / (60 * 60 * 1000),
+            deviceId: this.deviceId,
+            deviceRegisteredAt: this.deviceRegisteredAt,
+            entries: this.getAllEntries(),
+        };
+        const json = JSON.stringify(payload);
+        return new TextEncoder().encode(json);
+    }
+    /**
+     * Restore a `RelayLedger` from previously serialized data.
+     */
+    static deserialize(data) {
+        let parsed;
+        try {
+            const json = new TextDecoder().decode(data);
+            parsed = JSON.parse(json);
+        }
+        catch {
+            throw new Error('Failed to deserialize RelayLedger: invalid data');
+        }
+        if (parsed.version !== SERIALIZATION_VERSION) {
+            throw new Error(`Unsupported RelayLedger serialization version: ${parsed.version}`);
+        }
+        const ledger = new RelayLedger({
+            gracePeriodHours: parsed.gracePeriodHours,
+        });
+        if (parsed.deviceId !== null && parsed.deviceRegisteredAt !== null) {
+            ledger.deviceId = parsed.deviceId;
+            ledger.deviceRegisteredAt = parsed.deviceRegisteredAt;
+        }
+        for (const entry of parsed.entries) {
+            ledger.entries.set(entry.peerId, {
+                peerId: entry.peerId,
+                bytesRelayedForThem: entry.bytesRelayedForThem,
+                bytesTheyRelayedForUs: entry.bytesTheyRelayedForUs,
+                lastUpdated: entry.lastUpdated,
+            });
+        }
+        return ledger;
+    }
+    // -----------------------------------------------------------------------
+    // Static helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Map a numeric reciprocity score to a tier label.
+     */
+    static tierFromScore(score) {
+        if (score > TIER_CONTRIBUTOR_THRESHOLD)
+            return 'contributor';
+        if (score >= TIER_BALANCED_THRESHOLD)
+            return 'balanced';
+        if (score >= TIER_CONSUMER_THRESHOLD)
+            return 'consumer';
+        return 'freerider';
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    getOrCreateEntry(peerId) {
+        let entry = this.entries.get(peerId);
+        if (!entry) {
+            entry = {
+                peerId,
+                bytesRelayedForThem: 0,
+                bytesTheyRelayedForUs: 0,
+                lastUpdated: Date.now(),
+            };
+            this.entries.set(peerId, entry);
+        }
+        return entry;
+    }
+    computeScore(relayedForThem, theyRelayedForUs) {
+        if (relayedForThem === 0 && theyRelayedForUs === 0) {
+            return 1.0; // no data — neutral
+        }
+        if (theyRelayedForUs === 0) {
+            return Infinity; // pure contributor
+        }
+        return relayedForThem / theyRelayedForUs;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/reciprocity/index.js.map

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

package/dist/relay/index.d.ts

@@ -0,0 +1,87 @@
+import type { StoredBlob } from "../types";
+export interface RelayStoreOptions {
+    maxStorageBytes?: number;
+    defaultTTLHours?: number;
+}
+export declare class RelayStore {
+    private readonly maxStorageBytes;
+    private readonly defaultTTLHours;
+    /** All stored blobs keyed by blob id. */
+    private readonly blobs;
+    /** Secondary index: destHash hex -> set of blob ids. */
+    private readonly destIndex;
+    /** Track insertion order for LRU eviction (oldest first). */
+    private readonly insertionOrder;
+    private currentStorageBytes;
+    private pruneTimer;
+    constructor(options?: RelayStoreOptions);
+    private destKey;
+    private isExpired;
+    /**
+     * Store an encrypted blob. Returns false if storage is full even after
+     * evicting the oldest blobs.
+     */
+    storeBlob(blob: StoredBlob): boolean;
+    /** Retrieve all stored blobs for a given destination hash. */
+    getBlobs(destHash: Uint8Array): StoredBlob[];
+    /** Remove a single blob by id. */
+    removeBlob(id: string): void;
+    /** Remove all blobs targeting a specific destination hash. */
+    removeBlobsForDest(destHash: Uint8Array): void;
+    /** Remove all expired blobs. Returns count of blobs removed. */
+    pruneExpired(): number;
+    /** Start automatic periodic pruning. */
+    startPruneInterval(intervalMs?: number): void;
+    /** Stop automatic periodic pruning. */
+    stopPruneInterval(): void;
+    /** Bytes currently consumed by stored blobs. */
+    getStorageUsed(): number;
+    /** Configured maximum storage capacity in bytes. */
+    getStorageCapacity(): number;
+    /** Total number of blobs currently stored. */
+    getBlobCount(): number;
+    /**
+     * Handle a presence announcement. When a peer announces it is online we
+     * return (and remove) all blobs matching its destination hash.
+     *
+     * Destination hashes rotate hourly. The caller should provide both the
+     * current-epoch and the previous-epoch destination hashes so we can match
+     * blobs stored under either.
+     */
+    handlePresenceAnnouncement(destHash: Uint8Array): StoredBlob[];
+    handlePresenceAnnouncement(destHash: Uint8Array, previousEpochDestHash?: Uint8Array): StoredBlob[];
+    /**
+     * Decide whether a blob should be forwarded to a closer relay.
+     * Returns true when the blob still has remaining hops and a closer relay
+     * is available.
+     */
+    shouldForward(blob: StoredBlob, closerRelayAvailable: boolean): boolean;
+    /**
+     * Prepare a blob for multi-hop forwarding.
+     * Returns a new StoredBlob with decremented hopsRemaining and a fresh id.
+     */
+    prepareForward(blob: StoredBlob): StoredBlob;
+}
+export interface StoreAndForwardStats {
+    blobCount: number;
+    bytesUsed: number;
+    oldestBlobAge: number;
+}
+export declare class StoreAndForwardManager {
+    private readonly store;
+    constructor(store: RelayStore);
+    /**
+     * Store an encrypted payload destined for an offline peer.
+     * Returns the generated blob id, or throws if storage is completely full.
+     */
+    storeForDelivery(destHash: Uint8Array, encryptedPayload: Uint8Array, ttlHours?: number): string;
+    /**
+     * Called when a peer comes online. Returns all stored blobs for its
+     * destination hash and removes them from the store.
+     */
+    deliverStored(destHash: Uint8Array): StoredBlob[];
+    /** Return aggregate stats about the relay store. */
+    getStats(): StoreAndForwardStats;
+    private computeOldestAge;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/relay/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAiD3C,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAEzC,yCAAyC;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IAEvD,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAE5D,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAE/C,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,UAAU,CAA+C;gBAErD,OAAO,CAAC,EAAE,iBAAiB;IAOvC,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,SAAS;IAOjB;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;IAoCpC,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE;IAY5C,kCAAkC;IAClC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAkB5B,8DAA8D;IAC9D,kBAAkB,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI;IAY9C,gEAAgE;IAChE,YAAY,IAAI,MAAM;IActB,wCAAwC;IACxC,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAY7C,uCAAuC;IACvC,iBAAiB,IAAI,IAAI;IASzB,gDAAgD;IAChD,cAAc,IAAI,MAAM;IAIxB,oDAAoD;IACpD,kBAAkB,IAAI,MAAM;IAI5B,8CAA8C;IAC9C,YAAY,IAAI,MAAM;IAMtB;;;;;;;OAOG;IACH,0BAA0B,CAAC,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE;IAC9D,0BAA0B,CACxB,QAAQ,EAAE,UAAU,EACpB,qBAAqB,CAAC,EAAE,UAAU,GACjC,UAAU,EAAE;IAwBf;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,oBAAoB,EAAE,OAAO,GAAG,OAAO;IAIvE;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU;CAW7C;AAMD,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;gBAEvB,KAAK,EAAE,UAAU;IAI7B;;;OAGG;IACH,gBAAgB,CACd,QAAQ,EAAE,UAAU,EACpB,gBAAgB,EAAE,UAAU,EAC5B,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM;IAoBT;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE;IAIjD,oDAAoD;IACpD,QAAQ,IAAI,oBAAoB;IAkBhC,OAAO,CAAC,gBAAgB;CAWzB"}