@meshwhisper/sdk 0.1.0

package/dist/relay/index.js

@@ -0,0 +1,286 @@
+// ============================================================
+// MeshWhisper SDK — Store-and-Forward Relay Module
+// Stores encrypted blobs for offline peers and delivers them
+// when the recipient announces presence.
+// ============================================================
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Generate a random 32-hex-char blob ID. */
+function generateBlobId() {
+    // crypto.randomUUID() is available in Node >= 19 and modern runtimes,
+    // but a hex string is more portable and avoids dashes.
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/** Constant-time-ish comparison for Uint8Array equality. */
+function uint8Equal(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;
+}
+/** Rough byte size of a StoredBlob (payload dominates, but we account for metadata too). */
+function blobByteSize(blob) {
+    return (blob.encryptedPayload.byteLength +
+        blob.destHash.byteLength +
+        blob.id.length * 2 + // JS string ≈ 2 bytes per char
+        32 // fixed overhead for numeric fields + object shell
+    );
+}
+// ---------------------------------------------------------------------------
+// Default constants
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_STORAGE_BYTES = 50 * 1024 * 1024; // 50 MB
+const DEFAULT_TTL_HOURS = 72;
+const DEFAULT_PRUNE_INTERVAL_MS = 60_000; // 1 minute
+export class RelayStore {
+    maxStorageBytes;
+    defaultTTLHours;
+    /** All stored blobs keyed by blob id. */
+    blobs = new Map();
+    /** Secondary index: destHash hex -> set of blob ids. */
+    destIndex = new Map();
+    /** Track insertion order for LRU eviction (oldest first). */
+    insertionOrder = [];
+    currentStorageBytes = 0;
+    pruneTimer = null;
+    constructor(options) {
+        this.maxStorageBytes = options?.maxStorageBytes ?? DEFAULT_MAX_STORAGE_BYTES;
+        this.defaultTTLHours = options?.defaultTTLHours ?? DEFAULT_TTL_HOURS;
+    }
+    // ----- helpers -----
+    destKey(destHash) {
+        return Array.from(destHash)
+            .map((b) => b.toString(16).padStart(2, "0"))
+            .join("");
+    }
+    isExpired(blob) {
+        const expiryMs = blob.receivedAt + blob.ttlHours * 3_600_000;
+        return Date.now() >= expiryMs;
+    }
+    // ----- Blob storage -----
+    /**
+     * Store an encrypted blob. Returns false if storage is full even after
+     * evicting the oldest blobs.
+     */
+    storeBlob(blob) {
+        const size = blobByteSize(blob);
+        // Evict oldest blobs until there is room (or nothing left to evict)
+        while (this.currentStorageBytes + size > this.maxStorageBytes &&
+            this.insertionOrder.length > 0) {
+            const oldestId = this.insertionOrder[0];
+            this.removeBlob(oldestId);
+        }
+        if (this.currentStorageBytes + size > this.maxStorageBytes) {
+            return false;
+        }
+        // Avoid duplicate ids
+        if (this.blobs.has(blob.id)) {
+            this.removeBlob(blob.id);
+        }
+        this.blobs.set(blob.id, blob);
+        this.currentStorageBytes += size;
+        this.insertionOrder.push(blob.id);
+        const dk = this.destKey(blob.destHash);
+        let set = this.destIndex.get(dk);
+        if (!set) {
+            set = new Set();
+            this.destIndex.set(dk, set);
+        }
+        set.add(blob.id);
+        return true;
+    }
+    /** Retrieve all stored blobs for a given destination hash. */
+    getBlobs(destHash) {
+        const dk = this.destKey(destHash);
+        const ids = this.destIndex.get(dk);
+        if (!ids)
+            return [];
+        const results = [];
+        for (const id of ids) {
+            const blob = this.blobs.get(id);
+            if (blob)
+                results.push(blob);
+        }
+        return results;
+    }
+    /** Remove a single blob by id. */
+    removeBlob(id) {
+        const blob = this.blobs.get(id);
+        if (!blob)
+            return;
+        this.currentStorageBytes -= blobByteSize(blob);
+        this.blobs.delete(id);
+        const dk = this.destKey(blob.destHash);
+        const set = this.destIndex.get(dk);
+        if (set) {
+            set.delete(id);
+            if (set.size === 0)
+                this.destIndex.delete(dk);
+        }
+        const idx = this.insertionOrder.indexOf(id);
+        if (idx !== -1)
+            this.insertionOrder.splice(idx, 1);
+    }
+    /** Remove all blobs targeting a specific destination hash. */
+    removeBlobsForDest(destHash) {
+        const dk = this.destKey(destHash);
+        const ids = this.destIndex.get(dk);
+        if (!ids)
+            return;
+        // Snapshot the ids before iterating — removeBlob mutates the set.
+        for (const id of [...ids]) {
+            this.removeBlob(id);
+        }
+    }
+    // ----- TTL management -----
+    /** Remove all expired blobs. Returns count of blobs removed. */
+    pruneExpired() {
+        let removed = 0;
+        // Iterate oldest-first for efficiency.
+        for (let i = this.insertionOrder.length - 1; i >= 0; i--) {
+            const id = this.insertionOrder[i];
+            const blob = this.blobs.get(id);
+            if (blob && this.isExpired(blob)) {
+                this.removeBlob(id);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /** Start automatic periodic pruning. */
+    startPruneInterval(intervalMs) {
+        this.stopPruneInterval();
+        this.pruneTimer = setInterval(() => this.pruneExpired(), intervalMs ?? DEFAULT_PRUNE_INTERVAL_MS);
+        // Allow the Node.js process to exit even if the timer is running.
+        if (typeof this.pruneTimer === "object" && "unref" in this.pruneTimer) {
+            this.pruneTimer.unref();
+        }
+    }
+    /** Stop automatic periodic pruning. */
+    stopPruneInterval() {
+        if (this.pruneTimer !== null) {
+            clearInterval(this.pruneTimer);
+            this.pruneTimer = null;
+        }
+    }
+    // ----- Storage metrics -----
+    /** Bytes currently consumed by stored blobs. */
+    getStorageUsed() {
+        return this.currentStorageBytes;
+    }
+    /** Configured maximum storage capacity in bytes. */
+    getStorageCapacity() {
+        return this.maxStorageBytes;
+    }
+    /** Total number of blobs currently stored. */
+    getBlobCount() {
+        return this.blobs.size;
+    }
+    handlePresenceAnnouncement(destHash, previousEpochDestHash) {
+        const delivered = [];
+        // Current epoch
+        const currentBlobs = this.getBlobs(destHash);
+        delivered.push(...currentBlobs);
+        this.removeBlobsForDest(destHash);
+        // Previous epoch (dest hashes rotate hourly)
+        if (previousEpochDestHash && !uint8Equal(destHash, previousEpochDestHash)) {
+            const prevBlobs = this.getBlobs(previousEpochDestHash);
+            delivered.push(...prevBlobs);
+            this.removeBlobsForDest(previousEpochDestHash);
+        }
+        return delivered;
+    }
+    // ----- Multi-hop forwarding -----
+    /**
+     * 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, closerRelayAvailable) {
+        return closerRelayAvailable && blob.hopsRemaining > 0;
+    }
+    /**
+     * Prepare a blob for multi-hop forwarding.
+     * Returns a new StoredBlob with decremented hopsRemaining and a fresh id.
+     */
+    prepareForward(blob) {
+        if (blob.hopsRemaining <= 0) {
+            throw new Error("Cannot forward blob with no remaining hops");
+        }
+        return {
+            ...blob,
+            id: generateBlobId(),
+            hopsRemaining: blob.hopsRemaining - 1,
+            receivedAt: Date.now(),
+        };
+    }
+}
+export class StoreAndForwardManager {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Store an encrypted payload destined for an offline peer.
+     * Returns the generated blob id, or throws if storage is completely full.
+     */
+    storeForDelivery(destHash, encryptedPayload, ttlHours) {
+        const blob = {
+            id: generateBlobId(),
+            destHash,
+            encryptedPayload,
+            receivedAt: Date.now(),
+            ttlHours: ttlHours ?? 72,
+            hopsRemaining: 3, // sensible default for multi-hop
+        };
+        const stored = this.store.storeBlob(blob);
+        if (!stored) {
+            throw new Error("Relay storage full: could not store blob even after eviction");
+        }
+        return blob.id;
+    }
+    /**
+     * Called when a peer comes online. Returns all stored blobs for its
+     * destination hash and removes them from the store.
+     */
+    deliverStored(destHash) {
+        return this.store.handlePresenceAnnouncement(destHash);
+    }
+    /** Return aggregate stats about the relay store. */
+    getStats() {
+        const blobCount = this.store.getBlobCount();
+        const bytesUsed = this.store.getStorageUsed();
+        let oldestBlobAge = 0;
+        if (blobCount > 0) {
+            // We don't have direct access to the internal insertion order,
+            // so scan all blobs via a destHash-agnostic approach: use getBlobs
+            // is not feasible without knowing hashes. Instead we expose a
+            // helper below or compute from the public API. Since we control
+            // both classes in this module, we reach into the store's blobs map
+            // via a dedicated accessor.
+            oldestBlobAge = this.computeOldestAge();
+        }
+        return { blobCount, bytesUsed, oldestBlobAge };
+    }
+    computeOldestAge() {
+        // Access internal state via the store — both classes live in the same
+        // module, so this tightly-coupled reach is acceptable.
+        const blobs = this.store
+            .blobs;
+        let oldest = Infinity;
+        for (const blob of blobs.values()) {
+            if (blob.receivedAt < oldest)
+                oldest = blob.receivedAt;
+        }
+        return oldest === Infinity ? 0 : Date.now() - oldest;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/relay/index.js.map

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

package/dist/routing/index.d.ts

@@ -0,0 +1,136 @@
+import type { Packet, PeerProximityEntry, RouteRequest, RouteOffer } from '../types.js';
+export interface Route {
+    destHash: Uint8Array;
+    nextHop: string;
+    hopCount: number;
+    estimatedLatency: number;
+    discoveredAt: number;
+    expiresAt: number;
+}
+/**
+ * Maintains a table of known peers indexed by social proximity.
+ * Entries are keyed by peerId and can also be looked up by destHash.
+ */
+export declare class PeerProximityTable {
+    private readonly entries;
+    private readonly destHashIndex;
+    private readonly ttlMs;
+    constructor(ttlMs?: number);
+    /** Add or replace a peer entry. */
+    addPeer(entry: PeerProximityEntry): void;
+    /** Remove a peer by ID. */
+    removePeer(peerId: string): void;
+    /** Partially update an existing peer entry. */
+    updatePeer(peerId: string, updates: Partial<PeerProximityEntry>): void;
+    /** Find a peer that owns the given destination hash. */
+    findPeer(destHash: Uint8Array): PeerProximityEntry | null;
+    /**
+     * Return the N peers whose known destHash is closest (by XOR distance) to
+     * the target destination hash.  Results are sorted closest-first.
+     */
+    getClosestPeers(destHash: Uint8Array, count: number): PeerProximityEntry[];
+    /** Remove entries whose lastSeen is older than maxAgeMs. */
+    pruneStale(maxAgeMs?: number): void;
+    /** Number of entries currently in the table. */
+    get size(): number;
+    /** Iterate all entries (snapshot). */
+    allEntries(): PeerProximityEntry[];
+}
+/**
+ * Core social graph router.
+ *
+ * Uses the peer proximity table as the routing topology.
+ * Route discovery gossips route requests to socially proximate peers
+ * and selects the shortest/fastest offered route.
+ */
+export declare class SocialGraphRouter {
+    readonly localPeerId: string;
+    readonly proximityTable: PeerProximityTable;
+    private readonly routeCache;
+    private readonly seenPackets;
+    private readonly pendingRequests;
+    private readonly routeTtlMs;
+    private readonly requestTimeoutMs;
+    constructor(localPeerId: string, proximityTable: PeerProximityTable, options?: {
+        routeTtlMs?: number;
+        requestTimeoutMs?: number;
+    });
+    /** Retrieve a cached route if it exists and has not expired. */
+    getCachedRoute(destHash: Uint8Array): Route | null;
+    /** Store a route in the cache. */
+    cacheRoute(route: Route): void;
+    /** Remove a cached route. */
+    invalidateRoute(destHash: Uint8Array): void;
+    /**
+     * Discover a route to the given destination hash.
+     *
+     * Algorithm:
+     *   1. Check the route cache for a non-expired entry.
+     *   2. Check if any connected peer in the proximity table has a recent
+     *      relay path to the destination.
+     *   3. If not, create a RouteRequest (containing only dest_hash, not
+     *      sender identity) and gossip it to socially proximate peers.
+     *   4. Collect RouteOffer responses within the request timeout.
+     *   5. Select the shortest/fastest offered route.
+     *
+     * Returns the route, or null if no route could be discovered within the
+     * timeout window.
+     */
+    findRoute(destHash: Uint8Array): Promise<Route | null>;
+    /**
+     * Handle an incoming route request from a neighbouring peer.
+     *
+     * If this node knows the destination (via its proximity table), it
+     * returns a RouteOffer.  Otherwise returns null (the caller should
+     * decide whether to forward the request further).
+     */
+    handleRouteRequest(request: RouteRequest, fromPeer: string): RouteOffer | null;
+    /**
+     * Register a received route offer against the matching pending request.
+     * If no pending request exists for the offer's requestId, the offer is
+     * silently dropped.
+     */
+    handleRouteOffer(offer: RouteOffer): void;
+    /**
+     * Return a list of the RouteRequests that are still awaiting responses.
+     * Expired requests are pruned as a side-effect.
+     */
+    getPendingRequests(): RouteRequest[];
+    /**
+     * Return the list of socially proximate peers that a route request
+     * should be gossiped to.  Useful for the transport layer to know where
+     * to send route requests produced by findRoute.
+     */
+    getGossipTargets(destHash: Uint8Array): PeerProximityEntry[];
+    /**
+     * Determine the next-hop peer to forward a message to for the given
+     * destination hash.
+     *
+     * Returns null if no route is known.
+     */
+    getNextHop(destHash: Uint8Array): string | null;
+    /**
+     * Determine whether this device should relay a given packet.
+     *
+     * A packet is relayed when:
+     *   - Its TTL is greater than 0
+     *   - It has not been seen before (deduplication)
+     */
+    shouldRelay(packet: Packet): boolean;
+    /**
+     * Return a copy of the packet with TTL decremented by 1.
+     * Callers must ensure TTL > 0 before calling (see shouldRelay).
+     */
+    decrementTTL(packet: Packet): Packet;
+    /** Check if a timestamp is recent enough to trust. */
+    private isRecent;
+    /** Convert a proximity entry to a Route. */
+    private peerToRoute;
+    /** Resolve a pending request by selecting the best offer. */
+    private resolvePendingRequest;
+    /** Remove pending requests that have exceeded their timeout. */
+    private pruneExpiredRequests;
+    /** Generate a random 16-byte request ID. */
+    private generateRequestId;
+}
+//# sourceMappingURL=index.d.ts.map

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

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