@meshwhisper/sdk 0.1.0

package/dist/compliance/index.d.ts

@@ -0,0 +1,129 @@
+import type { ComplianceConfig, Message, MessageHook } from '../types.js';
+/** A single logged message with metadata. */
+export interface LogEntry {
+    message: Message;
+    direction: 'sent' | 'received';
+    loggedAt: number;
+}
+/** Options for filtering the message log. */
+export interface LogQueryOptions {
+    /** Only entries logged at or after this timestamp (ms). */
+    since?: number;
+    /** Only entries logged at or before this timestamp (ms). */
+    until?: number;
+    /** Only entries involving this peer (as sender or recipient). */
+    peerId?: string;
+}
+/** Options for exporting the audit log. */
+export interface AuditExportOptions {
+    /** Only entries logged at or after this timestamp (ms). */
+    since?: number;
+    /** Only entries logged at or before this timestamp (ms). */
+    until?: number;
+}
+/** Result of a content scan. */
+export interface ScanResult {
+    approved: boolean;
+    reason?: string;
+}
+export declare class ComplianceManager {
+    private config;
+    private log;
+    private complianceKey;
+    private beforeSendHooks;
+    private afterReceiveHooks;
+    private retentionTimer;
+    constructor(config?: ComplianceConfig);
+    /**
+     * Apply a new compliance configuration. Merges with the existing config.
+     */
+    configure(config: ComplianceConfig): void;
+    /**
+     * Return a shallow copy of the current compliance configuration.
+     */
+    getConfig(): ComplianceConfig;
+    /**
+     * Returns true if any compliance feature is active:
+     * logging enabled, audit export mode set, retention configured,
+     * or a content scanner registered.
+     */
+    isEnabled(): boolean;
+    /**
+     * Store a plaintext message in the local log.
+     * Only records when logging is enabled in the config.
+     */
+    logMessage(message: Message, direction: 'sent' | 'received'): void;
+    /**
+     * Retrieve logged messages, optionally filtering by time range and peer.
+     */
+    getMessageLog(options?: LogQueryOptions): LogEntry[];
+    /**
+     * Clear log entries older than the given timestamp.
+     * If no timestamp is provided, clears the entire log.
+     * Returns the number of entries removed.
+     */
+    clearLog(before?: number): number;
+    /**
+     * Export the audit log as a Uint8Array.
+     *
+     * - If auditExport is 'plaintext', returns UTF-8 encoded JSON.
+     * - If auditExport is 'encrypted', encrypts the JSON with AES-256-GCM
+     *   using the compliance key set via setComplianceKey().
+     * - If auditExport is not configured, defaults to 'plaintext'.
+     *
+     * The encrypted format is: [12-byte nonce][ciphertext+tag].
+     */
+    exportAuditLog(options?: AuditExportOptions): Uint8Array;
+    /**
+     * Set the AES-256 key used to encrypt audit exports.
+     */
+    setComplianceKey(key: Uint8Array): void;
+    /**
+     * Run the developer-supplied content scanner on a message.
+     * Returns { approved: true } if no scanner is configured.
+     */
+    scanMessage(message: Message): Promise<ScanResult>;
+    /** Register a hook that runs before a message is sent. */
+    addBeforeSendHook(hook: MessageHook): void;
+    /** Register a hook that runs after a message is received. */
+    addAfterReceiveHook(hook: MessageHook): void;
+    /** Remove a previously registered before-send hook. */
+    removeBeforeSendHook(hook: MessageHook): void;
+    /** Remove a previously registered after-receive hook. */
+    removeAfterReceiveHook(hook: MessageHook): void;
+    /**
+     * Run all before-send hooks in order.
+     * Returns false if any hook returns false (message should be blocked).
+     */
+    runBeforeSendHooks(message: Message): Promise<boolean>;
+    /**
+     * Run all after-receive hooks in order.
+     * Returns false if any hook returns false (message should be rejected).
+     */
+    runAfterReceiveHooks(message: Message): Promise<boolean>;
+    /**
+     * Start a periodic timer that prunes log entries older than
+     * retentionDays. No-op if retentionDays is not configured.
+     *
+     * @param intervalMs How often to run the prune (default: 1 hour).
+     */
+    startRetentionEnforcement(intervalMs?: number): void;
+    /**
+     * Stop the periodic retention enforcement timer.
+     */
+    stopRetentionEnforcement(): void;
+    /**
+     * Run an ordered list of hooks against a message.
+     * Returns false as soon as any hook returns false; true if all pass.
+     */
+    private runHooks;
+    /**
+     * Remove log entries older than the configured retentionDays.
+     */
+    private pruneExpiredEntries;
+    /**
+     * Filter log entries by optional time range.
+     */
+    private getFilteredEntries;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compliance/index.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAAmB,MAAM,aAAa,CAAC;AAsB3F,6CAA6C;AAC7C,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,UAAU,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,2CAA2C;AAC3C,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gCAAgC;AAChC,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAaD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,GAAG,CAAkB;IAC7B,OAAO,CAAC,aAAa,CAA2B;IAEhD,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,iBAAiB,CAAqB;IAE9C,OAAO,CAAC,cAAc,CAA+C;gBAEzD,MAAM,CAAC,EAAE,gBAAgB;IAQrC;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAIzC;;OAEG;IACH,SAAS,IAAI,gBAAgB;IAI7B;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAapB;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAYlE;;OAEG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,QAAQ,EAAE;IAgBpD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM;IAgBjC;;;;;;;;;OASG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,UAAU;IAoCxD;;OAEG;IACH,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAavC;;;OAGG;IACG,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAYxD,0DAA0D;IAC1D,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAI1C,6DAA6D;IAC7D,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAI5C,uDAAuD;IACvD,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAO7C,yDAAyD;IACzD,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAO/C;;;OAGG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAI5D;;;OAGG;IACG,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ9D;;;;;OAKG;IACH,yBAAyB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAmBpD;;OAEG;IACH,wBAAwB,IAAI,IAAI;IAWhC;;;OAGG;YACW,QAAQ;IAQtB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAM3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAU3B"}

package/dist/compliance/index.js

@@ -0,0 +1,315 @@
+// ============================================================
+// MeshWhisper SDK — Compliance API
+// Optional compliance layer for message logging, audit export,
+// content scanning, and middleware hooks as described in PRD §12.3.
+//
+// The protocol never accesses plaintext — the developer's app does.
+// All hooks are entirely optional and the app developer's
+// responsibility.
+// ============================================================
+import { gcm } from '@noble/ciphers/aes';
+import { randomBytes } from '@noble/hashes/utils';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** AES-256-GCM nonce length in bytes. */
+const AES_GCM_NONCE_LENGTH = 12;
+/** AES-256 key length in bytes. */
+const AES_256_KEY_LENGTH = 32;
+/** Default retention enforcement interval: 1 hour. */
+const DEFAULT_ENFORCEMENT_INTERVAL_MS = 60 * 60 * 1000;
+/** Milliseconds per day. */
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Text encoder / decoder
+// ---------------------------------------------------------------------------
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+// ---------------------------------------------------------------------------
+// ComplianceManager
+// ---------------------------------------------------------------------------
+export class ComplianceManager {
+    config;
+    log = [];
+    complianceKey = null;
+    beforeSendHooks = [];
+    afterReceiveHooks = [];
+    retentionTimer = null;
+    constructor(config) {
+        this.config = config ?? {};
+    }
+    // -----------------------------------------------------------------------
+    // Configuration
+    // -----------------------------------------------------------------------
+    /**
+     * Apply a new compliance configuration. Merges with the existing config.
+     */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Return a shallow copy of the current compliance configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Returns true if any compliance feature is active:
+     * logging enabled, audit export mode set, retention configured,
+     * or a content scanner registered.
+     */
+    isEnabled() {
+        return (this.config.logging === true ||
+            this.config.auditExport !== undefined ||
+            this.config.retentionDays !== undefined ||
+            this.config.contentScanning !== undefined);
+    }
+    // -----------------------------------------------------------------------
+    // Message logging
+    // -----------------------------------------------------------------------
+    /**
+     * Store a plaintext message in the local log.
+     * Only records when logging is enabled in the config.
+     */
+    logMessage(message, direction) {
+        if (!this.config.logging)
+            return;
+        const entry = {
+            message,
+            direction,
+            loggedAt: Date.now(),
+        };
+        this.log.push(entry);
+    }
+    /**
+     * Retrieve logged messages, optionally filtering by time range and peer.
+     */
+    getMessageLog(options) {
+        if (!options)
+            return [...this.log];
+        const { since, until, peerId } = options;
+        return this.log.filter((entry) => {
+            if (since !== undefined && entry.loggedAt < since)
+                return false;
+            if (until !== undefined && entry.loggedAt > until)
+                return false;
+            if (peerId !== undefined) {
+                const msg = entry.message;
+                if (msg.senderId !== peerId && msg.recipientId !== peerId)
+                    return false;
+            }
+            return true;
+        });
+    }
+    /**
+     * Clear log entries older than the given timestamp.
+     * If no timestamp is provided, clears the entire log.
+     * Returns the number of entries removed.
+     */
+    clearLog(before) {
+        if (before === undefined) {
+            const count = this.log.length;
+            this.log = [];
+            return count;
+        }
+        const originalLength = this.log.length;
+        this.log = this.log.filter((entry) => entry.loggedAt >= before);
+        return originalLength - this.log.length;
+    }
+    // -----------------------------------------------------------------------
+    // Audit export
+    // -----------------------------------------------------------------------
+    /**
+     * Export the audit log as a Uint8Array.
+     *
+     * - If auditExport is 'plaintext', returns UTF-8 encoded JSON.
+     * - If auditExport is 'encrypted', encrypts the JSON with AES-256-GCM
+     *   using the compliance key set via setComplianceKey().
+     * - If auditExport is not configured, defaults to 'plaintext'.
+     *
+     * The encrypted format is: [12-byte nonce][ciphertext+tag].
+     */
+    exportAuditLog(options) {
+        const entries = this.getFilteredEntries(options);
+        const json = JSON.stringify(entries, serializeReplacer);
+        const plainBytes = textEncoder.encode(json);
+        const mode = this.config.auditExport ?? 'plaintext';
+        if (mode === 'plaintext') {
+            return plainBytes;
+        }
+        // Encrypted export
+        if (!this.complianceKey) {
+            throw new Error('Compliance key not set. Call setComplianceKey() before exporting an encrypted audit log.');
+        }
+        if (this.complianceKey.length !== AES_256_KEY_LENGTH) {
+            throw new Error(`Compliance key must be ${AES_256_KEY_LENGTH} bytes for AES-256-GCM.`);
+        }
+        const nonce = randomBytes(AES_GCM_NONCE_LENGTH);
+        const cipher = gcm(this.complianceKey, nonce);
+        const ciphertext = cipher.encrypt(plainBytes);
+        // Pack as [nonce][ciphertext+tag]
+        const result = new Uint8Array(nonce.length + ciphertext.length);
+        result.set(nonce, 0);
+        result.set(ciphertext, nonce.length);
+        return result;
+    }
+    /**
+     * Set the AES-256 key used to encrypt audit exports.
+     */
+    setComplianceKey(key) {
+        if (key.length !== AES_256_KEY_LENGTH) {
+            throw new Error(`Compliance key must be ${AES_256_KEY_LENGTH} bytes for AES-256-GCM.`);
+        }
+        this.complianceKey = new Uint8Array(key);
+    }
+    // -----------------------------------------------------------------------
+    // Content scanning
+    // -----------------------------------------------------------------------
+    /**
+     * Run the developer-supplied content scanner on a message.
+     * Returns { approved: true } if no scanner is configured.
+     */
+    async scanMessage(message) {
+        if (!this.config.contentScanning) {
+            return { approved: true };
+        }
+        return this.config.contentScanning(message);
+    }
+    // -----------------------------------------------------------------------
+    // Middleware hooks
+    // -----------------------------------------------------------------------
+    /** Register a hook that runs before a message is sent. */
+    addBeforeSendHook(hook) {
+        this.beforeSendHooks.push(hook);
+    }
+    /** Register a hook that runs after a message is received. */
+    addAfterReceiveHook(hook) {
+        this.afterReceiveHooks.push(hook);
+    }
+    /** Remove a previously registered before-send hook. */
+    removeBeforeSendHook(hook) {
+        const idx = this.beforeSendHooks.indexOf(hook);
+        if (idx !== -1) {
+            this.beforeSendHooks.splice(idx, 1);
+        }
+    }
+    /** Remove a previously registered after-receive hook. */
+    removeAfterReceiveHook(hook) {
+        const idx = this.afterReceiveHooks.indexOf(hook);
+        if (idx !== -1) {
+            this.afterReceiveHooks.splice(idx, 1);
+        }
+    }
+    /**
+     * Run all before-send hooks in order.
+     * Returns false if any hook returns false (message should be blocked).
+     */
+    async runBeforeSendHooks(message) {
+        return this.runHooks(this.beforeSendHooks, message);
+    }
+    /**
+     * Run all after-receive hooks in order.
+     * Returns false if any hook returns false (message should be rejected).
+     */
+    async runAfterReceiveHooks(message) {
+        return this.runHooks(this.afterReceiveHooks, message);
+    }
+    // -----------------------------------------------------------------------
+    // Retention enforcement
+    // -----------------------------------------------------------------------
+    /**
+     * Start a periodic timer that prunes log entries older than
+     * retentionDays. No-op if retentionDays is not configured.
+     *
+     * @param intervalMs How often to run the prune (default: 1 hour).
+     */
+    startRetentionEnforcement(intervalMs) {
+        if (this.retentionTimer !== null)
+            return; // already running
+        if (this.config.retentionDays === undefined)
+            return;
+        const interval = intervalMs ?? DEFAULT_ENFORCEMENT_INTERVAL_MS;
+        this.retentionTimer = setInterval(() => {
+            this.pruneExpiredEntries();
+        }, interval);
+        // Prevent the timer from keeping the process alive in Node.js.
+        if (typeof this.retentionTimer === 'object' && 'unref' in this.retentionTimer) {
+            this.retentionTimer.unref();
+        }
+        // Run an initial prune immediately.
+        this.pruneExpiredEntries();
+    }
+    /**
+     * Stop the periodic retention enforcement timer.
+     */
+    stopRetentionEnforcement() {
+        if (this.retentionTimer !== null) {
+            clearInterval(this.retentionTimer);
+            this.retentionTimer = null;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Run an ordered list of hooks against a message.
+     * Returns false as soon as any hook returns false; true if all pass.
+     */
+    async runHooks(hooks, message) {
+        for (const hook of hooks) {
+            const result = await hook(message);
+            if (result === false)
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Remove log entries older than the configured retentionDays.
+     */
+    pruneExpiredEntries() {
+        if (this.config.retentionDays === undefined)
+            return;
+        const cutoff = Date.now() - this.config.retentionDays * MS_PER_DAY;
+        this.log = this.log.filter((entry) => entry.loggedAt >= cutoff);
+    }
+    /**
+     * Filter log entries by optional time range.
+     */
+    getFilteredEntries(options) {
+        if (!options)
+            return [...this.log];
+        const { since, until } = options;
+        return this.log.filter((entry) => {
+            if (since !== undefined && entry.loggedAt < since)
+                return false;
+            if (until !== undefined && entry.loggedAt > until)
+                return false;
+            return true;
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// JSON serialization helpers
+// ---------------------------------------------------------------------------
+/**
+ * Custom replacer for JSON.stringify that converts Uint8Array fields
+ * to base64 strings so the audit log is portable.
+ */
+function serializeReplacer(_key, value) {
+    if (value instanceof Uint8Array) {
+        return { __type: 'Uint8Array', data: uint8ArrayToBase64(value) };
+    }
+    return value;
+}
+/**
+ * Encode a Uint8Array to a base64 string without depending on Node.js
+ * Buffer.  Works in both browser and Node.js environments.
+ */
+function uint8ArrayToBase64(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+//# sourceMappingURL=index.js.map

package/dist/compliance/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compliance/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,mCAAmC;AACnC,+DAA+D;AAC/D,oEAAoE;AACpE,EAAE;AACF,oEAAoE;AACpE,0DAA0D;AAC1D,kBAAkB;AAClB,+DAA+D;AAE/D,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlD,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,yCAAyC;AACzC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEhC,mCAAmC;AACnC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAE9B,sDAAsD;AACtD,MAAM,+BAA+B,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEvD,4BAA4B;AAC5B,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAqCvC,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AACtC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAEtC,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,MAAM,OAAO,iBAAiB;IACpB,MAAM,CAAmB;IACzB,GAAG,GAAe,EAAE,CAAC;IACrB,aAAa,GAAsB,IAAI,CAAC;IAExC,eAAe,GAAkB,EAAE,CAAC;IACpC,iBAAiB,GAAkB,EAAE,CAAC;IAEtC,cAAc,GAA0C,IAAI,CAAC;IAErE,YAAY,MAAyB;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;IAC7B,CAAC;IAED,0EAA0E;IAC1E,gBAAgB;IAChB,0EAA0E;IAE1E;;OAEG;IACH,SAAS,CAAC,MAAwB;QAChC,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,SAAS;QACP,OAAO,CACL,IAAI,CAAC,MAAM,CAAC,OAAO,KAAK,IAAI;YAC5B,IAAI,CAAC,MAAM,CAAC,WAAW,KAAK,SAAS;YACrC,IAAI,CAAC,MAAM,CAAC,aAAa,KAAK,SAAS;YACvC,IAAI,CAAC,MAAM,CAAC,eAAe,KAAK,SAAS,CAC1C,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,kBAAkB;IAClB,0EAA0E;IAE1E;;;OAGG;IACH,UAAU,CAAC,OAAgB,EAAE,SAA8B;QACzD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO;QAEjC,MAAM,KAAK,GAAa;YACtB,OAAO;YACP,SAAS;YACT,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE;SACrB,CAAC;QAEF,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,OAAyB;QACrC,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QAEnC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAEzC,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YAC/B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,GAAG,KAAK;gBAAE,OAAO,KAAK,CAAC;YAChE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,GAAG,KAAK;gBAAE,OAAO,KAAK,CAAC;YAChE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC;gBAC1B,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,GAAG,CAAC,WAAW,KAAK,MAAM;oBAAE,OAAO,KAAK,CAAC;YAC1E,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,MAAe;QACtB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YAC9B,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;YACd,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;QACvC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,MAAM,CAAC,CAAC;QAChE,OAAO,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;IAC1C,CAAC;IAED,0EAA0E;IAC1E,eAAe;IACf,0EAA0E;IAE1E;;;;;;;;;OASG;IACH,cAAc,CAAC,OAA4B;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QACxD,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAE5C,MAAM,IAAI,GAAoB,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,WAAW,CAAC;QAErE,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;YACzB,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,mBAAmB;QACnB,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,0FAA0F,CAC3F,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,KAAK,kBAAkB,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CACb,0BAA0B,kBAAkB,yBAAyB,CACtE,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,WAAW,CAAC,oBAAoB,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAE9C,kCAAkC;QAClC,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QAChE,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACrB,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAErC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,GAAe;QAC9B,IAAI,GAAG,CAAC,MAAM,KAAK,kBAAkB,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACb,0BAA0B,kBAAkB,yBAAyB,CACtE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAED,0EAA0E;IAC1E,mBAAmB;IACnB,0EAA0E;IAE1E;;;OAGG;IACH,KAAK,CAAC,WAAW,CAAC,OAAgB;QAChC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;YACjC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC5B,CAAC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,0EAA0E;IAC1E,mBAAmB;IACnB,0EAA0E;IAE1E,0DAA0D;IAC1D,iBAAiB,CAAC,IAAiB;QACjC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,6DAA6D;IAC7D,mBAAmB,CAAC,IAAiB;QACnC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,uDAAuD;IACvD,oBAAoB,CAAC,IAAiB;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,yDAAyD;IACzD,sBAAsB,CAAC,IAAiB;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,kBAAkB,CAAC,OAAgB;QACvC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,oBAAoB,CAAC,OAAgB;QACzC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;IAED,0EAA0E;IAC1E,wBAAwB;IACxB,0EAA0E;IAE1E;;;;;OAKG;IACH,yBAAyB,CAAC,UAAmB;QAC3C,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI;YAAE,OAAO,CAAC,kBAAkB;QAC5D,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,KAAK,SAAS;YAAE,OAAO;QAEpD,MAAM,QAAQ,GAAG,UAAU,IAAI,+BAA+B,CAAC;QAE/D,IAAI,CAAC,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE;YACrC,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC7B,CAAC,EAAE,QAAQ,CAAC,CAAC;QAEb,+DAA+D;QAC/D,IAAI,OAAO,IAAI,CAAC,cAAc,KAAK,QAAQ,IAAI,OAAO,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YAC7E,IAAI,CAAC,cAAiC,CAAC,KAAK,EAAE,CAAC;QAClD,CAAC;QAED,oCAAoC;QACpC,IAAI,CAAC,mBAAmB,EAAE,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,wBAAwB;QACtB,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;YACjC,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YACnC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,kBAAkB;IAClB,0EAA0E;IAE1E;;;OAGG;IACK,KAAK,CAAC,QAAQ,CAAC,KAAoB,EAAE,OAAgB;QAC3D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;YACnC,IAAI,MAAM,KAAK,KAAK;gBAAE,OAAO,KAAK,CAAC;QACrC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACK,mBAAmB;QACzB,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,KAAK,SAAS;YAAE,OAAO;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,GAAG,UAAU,CAAC;QACnE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,MAAM,CAAC,CAAC;IAClE,CAAC;IAED;;OAEG;IACK,kBAAkB,CAAC,OAA4B;QACrD,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QAEnC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;QACjC,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YAC/B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,GAAG,KAAK;gBAAE,OAAO,KAAK,CAAC;YAChE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,GAAG,KAAK;gBAAE,OAAO,KAAK,CAAC;YAChE,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,8EAA8E;AAC9E,6BAA6B;AAC7B,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,iBAAiB,CAAC,IAAY,EAAE,KAAc;IACrD,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;IACnE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,kBAAkB,CAAC,KAAiB;IAC3C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC"}

package/dist/crypto/index.d.ts

@@ -0,0 +1,65 @@
+import type { KeyPair, EncryptedPayload } from '../types.js';
+/**
+ * Returns the current epoch hour: floor(Date.now() / 3_600_000).
+ * Used for hourly destHash rotation.
+ */
+export declare function getCurrentEpochHour(): number;
+/**
+ * Generates cryptographically secure random bytes.
+ */
+export declare function randomBytes(length: number): Uint8Array;
+/**
+ * Concatenates multiple Uint8Arrays into a single Uint8Array.
+ */
+export declare function concat(...arrays: Uint8Array[]): Uint8Array;
+/**
+ * General-purpose BLAKE3 hash. Returns 32-byte digest.
+ */
+export declare function hash(data: Uint8Array): Uint8Array;
+/**
+ * Derives a 256-bit namespace ID via BLAKE3(appBundleId || developerPublicKey || salt).
+ * The namespace isolates different applications sharing the same mesh.
+ */
+export declare function deriveNamespaceId(appBundleId: string, developerPublicKey: Uint8Array, salt: Uint8Array): Uint8Array;
+/**
+ * Derives a truncated 8-byte destination hash via BLAKE3(recipientPublicKey || epochHour).
+ * Rotates every hour to limit linkability.
+ */
+export declare function deriveDestHash(recipientPublicKey: Uint8Array, epochHour: number): Uint8Array;
+/**
+ * Generates a long-lived X25519 identity key pair.
+ */
+export declare function generateKeyPair(): KeyPair;
+/**
+ * Generates an ephemeral X25519 key pair for single-use key agreement.
+ * Functionally identical to generateKeyPair but semantically distinct:
+ * ephemeral keys should be discarded after use.
+ */
+export declare function generateEphemeralKeyPair(): KeyPair;
+/**
+ * Computes an X25519 shared secret from a private key and a peer's public key.
+ * Returns a 32-byte shared secret suitable for key derivation.
+ */
+export declare function computeSharedSecret(privateKey: Uint8Array, publicKey: Uint8Array): Uint8Array;
+/**
+ * Encrypts plaintext with AES-256-GCM using a random 12-byte nonce.
+ * The key must be exactly 32 bytes.
+ *
+ * Returns ciphertext, nonce, and authentication tag as separate fields.
+ */
+export declare function encrypt(plaintext: Uint8Array, key: Uint8Array): EncryptedPayload;
+/**
+ * Decrypts an AES-256-GCM EncryptedPayload.
+ * Throws if the tag verification fails (tampered or wrong key).
+ */
+export declare function decrypt(encrypted: EncryptedPayload, key: Uint8Array): Uint8Array;
+/**
+ * Key derivation function built on BLAKE3's built-in KDF mode.
+ * Uses BLAKE3(inputKeyMaterial, { context: info, dkLen: length }).
+ *
+ * @param inputKeyMaterial - The raw key material (e.g., shared secret).
+ * @param info - Application-specific context string for domain separation.
+ * @param length - Desired output length in bytes (default 32).
+ */
+export declare function kdf(inputKeyMaterial: Uint8Array, info: string, length?: number): Uint8Array;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAkB7D;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAEtD;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,CAY1D;AAID;;GAEG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAEjD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,UAAU,EAC9B,IAAI,EAAE,UAAU,GACf,UAAU,CAKZ;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,kBAAkB,EAAE,UAAU,EAC9B,SAAS,EAAE,MAAM,GAChB,UAAU,CAWZ;AAID;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAIzC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAIlD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,UAAU,GACpB,UAAU,CAEZ;AAID;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,SAAS,EAAE,UAAU,EACrB,GAAG,EAAE,UAAU,GACd,gBAAgB,CAUlB;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACrB,SAAS,EAAE,gBAAgB,EAC3B,GAAG,EAAE,UAAU,GACd,UAAU,CAOZ;AAID;;;;;;;GAOG;AACH,wBAAgB,GAAG,CACjB,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,MAA2B,GAClC,UAAU,CAEZ"}

package/dist/crypto/index.js

@@ -0,0 +1,146 @@
+// ============================================================
+// MeshWhisper SDK — Crypto Primitives
+// BLAKE3 hashing, X25519 key exchange, AES-256-GCM encryption,
+// BLAKE3-based KDF, and utilities.
+// ============================================================
+import { blake3 } from '@noble/hashes/blake3';
+import { randomBytes as nobleRandomBytes } from '@noble/hashes/utils';
+import { x25519 } from '@noble/curves/ed25519';
+import { gcm } from '@noble/ciphers/aes';
+// ---- Constants ----
+/** AES-GCM nonce length in bytes (96-bit). */
+const GCM_NONCE_LENGTH = 12;
+/** AES-GCM authentication tag length in bytes. */
+const GCM_TAG_LENGTH = 16;
+/** DestHash truncation length in bytes. */
+const DEST_HASH_LENGTH = 8;
+/** Default KDF output length in bytes. */
+const DEFAULT_KDF_LENGTH = 32;
+// ---- Utilities ----
+/**
+ * Returns the current epoch hour: floor(Date.now() / 3_600_000).
+ * Used for hourly destHash rotation.
+ */
+export function getCurrentEpochHour() {
+    return Math.floor(Date.now() / 3_600_000);
+}
+/**
+ * Generates cryptographically secure random bytes.
+ */
+export function randomBytes(length) {
+    return nobleRandomBytes(length);
+}
+/**
+ * Concatenates multiple Uint8Arrays into a single Uint8Array.
+ */
+export function concat(...arrays) {
+    let totalLength = 0;
+    for (const arr of arrays) {
+        totalLength += arr.length;
+    }
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const arr of arrays) {
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    return result;
+}
+// ---- BLAKE3 Hashing ----
+/**
+ * General-purpose BLAKE3 hash. Returns 32-byte digest.
+ */
+export function hash(data) {
+    return blake3(data);
+}
+/**
+ * Derives a 256-bit namespace ID via BLAKE3(appBundleId || developerPublicKey || salt).
+ * The namespace isolates different applications sharing the same mesh.
+ */
+export function deriveNamespaceId(appBundleId, developerPublicKey, salt) {
+    const encoder = new TextEncoder();
+    const appBytes = encoder.encode(appBundleId);
+    const input = concat(appBytes, developerPublicKey, salt);
+    return blake3(input);
+}
+/**
+ * Derives a truncated 8-byte destination hash via BLAKE3(recipientPublicKey || epochHour).
+ * Rotates every hour to limit linkability.
+ */
+export function deriveDestHash(recipientPublicKey, epochHour) {
+    // Encode epochHour as 8-byte big-endian uint64
+    const epochBytes = new Uint8Array(8);
+    const view = new DataView(epochBytes.buffer);
+    // Use two 32-bit writes for full 64-bit range (epochHour fits in 53-bit JS number)
+    view.setUint32(0, Math.floor(epochHour / 0x100000000), false);
+    view.setUint32(4, epochHour >>> 0, false);
+    const input = concat(recipientPublicKey, epochBytes);
+    const fullHash = blake3(input);
+    return fullHash.slice(0, DEST_HASH_LENGTH);
+}
+// ---- X25519 Key Exchange ----
+/**
+ * Generates a long-lived X25519 identity key pair.
+ */
+export function generateKeyPair() {
+    const privateKey = x25519.utils.randomSecretKey();
+    const publicKey = x25519.getPublicKey(privateKey);
+    return { publicKey, privateKey };
+}
+/**
+ * Generates an ephemeral X25519 key pair for single-use key agreement.
+ * Functionally identical to generateKeyPair but semantically distinct:
+ * ephemeral keys should be discarded after use.
+ */
+export function generateEphemeralKeyPair() {
+    const privateKey = x25519.utils.randomSecretKey();
+    const publicKey = x25519.getPublicKey(privateKey);
+    return { publicKey, privateKey };
+}
+/**
+ * Computes an X25519 shared secret from a private key and a peer's public key.
+ * Returns a 32-byte shared secret suitable for key derivation.
+ */
+export function computeSharedSecret(privateKey, publicKey) {
+    return x25519.getSharedSecret(privateKey, publicKey);
+}
+// ---- AES-256-GCM Encryption ----
+/**
+ * Encrypts plaintext with AES-256-GCM using a random 12-byte nonce.
+ * The key must be exactly 32 bytes.
+ *
+ * Returns ciphertext, nonce, and authentication tag as separate fields.
+ */
+export function encrypt(plaintext, key) {
+    const nonce = randomBytes(GCM_NONCE_LENGTH);
+    const cipher = gcm(key, nonce);
+    const sealed = cipher.encrypt(plaintext);
+    // noble/ciphers GCM appends the 16-byte tag to the ciphertext
+    const ciphertext = sealed.slice(0, sealed.length - GCM_TAG_LENGTH);
+    const tag = sealed.slice(sealed.length - GCM_TAG_LENGTH);
+    return { ciphertext, nonce, tag };
+}
+/**
+ * Decrypts an AES-256-GCM EncryptedPayload.
+ * Throws if the tag verification fails (tampered or wrong key).
+ */
+export function decrypt(encrypted, key) {
+    const { ciphertext, nonce, tag } = encrypted;
+    // Reconstruct the sealed format expected by noble: ciphertext || tag
+    const sealed = concat(ciphertext, tag);
+    const cipher = gcm(key, nonce);
+    return cipher.decrypt(sealed);
+}
+// ---- BLAKE3-based KDF ----
+/**
+ * Key derivation function built on BLAKE3's built-in KDF mode.
+ * Uses BLAKE3(inputKeyMaterial, { context: info, dkLen: length }).
+ *
+ * @param inputKeyMaterial - The raw key material (e.g., shared secret).
+ * @param info - Application-specific context string for domain separation.
+ * @param length - Desired output length in bytes (default 32).
+ */
+export function kdf(inputKeyMaterial, info, length = DEFAULT_KDF_LENGTH) {
+    return blake3(inputKeyMaterial, { context: info, dkLen: length });
+}
+//# sourceMappingURL=index.js.map