@thezelijah/majik-message 1.0.0

package/dist/core/messages/envelope-cache.js

@@ -0,0 +1,375 @@
+import { arrayBufferToBase64, base64ToArrayBuffer } from "../utils/utilities";
+import { MessageEnvelope } from "./message-envelope";
+/* -------------------------------
+ * Errors
+ * ------------------------------- */
+export class EnvelopeCacheError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "EnvelopeCacheError";
+        this.cause = cause;
+    }
+}
+/* -------------------------------
+ * EnvelopeCache
+ * ------------------------------- */
+export class EnvelopeCache {
+    dbPromise;
+    dbName;
+    storeName;
+    maxEntries;
+    // In-memory cache
+    memoryCache;
+    memoryCacheSize;
+    constructor(config) {
+        this.dbName = config?.dbName || "MajikEnvelopeDB";
+        this.storeName = config?.storeName || "envelopes";
+        this.maxEntries = config?.maxEntries;
+        this.memoryCacheSize = config?.memoryCacheSize || 100;
+        this.memoryCache = new Map();
+        this.dbPromise = this.initDB();
+    }
+    /* -------------------------------
+     * IndexedDB Initialization
+     * ------------------------------- */
+    initDB() {
+        return new Promise((resolve, reject) => {
+            const request = indexedDB.open(this.dbName, 1);
+            request.onupgradeneeded = (event) => {
+                const db = event.target.result;
+                if (!db.objectStoreNames.contains(this.storeName)) {
+                    const store = db.createObjectStore(this.storeName, { keyPath: "id" });
+                    store.createIndex("timestamp", "timestamp");
+                }
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(new EnvelopeCacheError("Failed to open IndexedDB", request.error));
+        });
+    }
+    /* -------------------------------
+     * Generate unique ID for envelope (SHA-256)
+     * ------------------------------- */
+    async getEnvelopeId(envelope) {
+        const hashBuffer = await crypto.subtle.digest("SHA-256", envelope.encryptedBlob);
+        const hashArray = Array.from(new Uint8Array(hashBuffer));
+        return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    }
+    /* -------------------------------
+     * Save envelope to cache (IDB + memory)
+     * -------------------------------
+     */
+    async set(envelope, source) {
+        const id = await this.getEnvelopeId(envelope);
+        try {
+            // Add to memory cache
+            this.memoryCache.set(id, envelope);
+            if (this.memoryCache.size > this.memoryCacheSize) {
+                // Remove oldest entry
+                const firstKey = this.memoryCache.keys().next().value;
+                if (firstKey !== undefined) {
+                    this.memoryCache.delete(firstKey);
+                }
+            }
+            // Persist to IndexedDB
+            const db = await this.dbPromise;
+            const tx = db.transaction(this.storeName, "readwrite");
+            const store = tx.objectStore(this.storeName);
+            const timestamp = Date.now();
+            await new Promise((resolve, reject) => {
+                const req = store.put({ id, envelope, timestamp, source });
+                req.onsuccess = () => resolve();
+                req.onerror = () => reject(new EnvelopeCacheError("Failed to save envelope", req.error));
+            });
+            // Optional: enforce maxEntries in IDB
+            if (this.maxEntries)
+                await this.enforceMaxEntries();
+        }
+        catch (err) {
+            console.error("EnvelopeCache set error:", err);
+            throw err;
+        }
+    }
+    /* -------------------------------
+     * List recent envelopes with pagination (most recent first)
+     * Returns array of objects: { id, envelope, timestamp, source }
+     * -------------------------------
+     */
+    async listRecent(offset = 0, limit = 50) {
+        const results = [];
+        try {
+            const db = await this.dbPromise;
+            const tx = db.transaction(this.storeName, "readonly");
+            const store = tx.objectStore(this.storeName);
+            const index = store.index("timestamp");
+            // Iterate newest first
+            const req = index.openCursor(null, "prev");
+            let skipped = 0;
+            await new Promise((resolve, reject) => {
+                req.onsuccess = (event) => {
+                    const cursor = event.target
+                        .result;
+                    if (!cursor)
+                        return resolve();
+                    if (skipped < offset) {
+                        skipped++;
+                        cursor.continue();
+                        return;
+                    }
+                    if (results.length < limit) {
+                        const val = cursor.value;
+                        const envelope = new MessageEnvelope(val.envelope.encryptedBlob); // wrap here
+                        results.push({
+                            id: val.id,
+                            envelope: envelope,
+                            timestamp: val.timestamp,
+                            source: val.source,
+                        });
+                        cursor.continue();
+                    }
+                    else {
+                        resolve();
+                    }
+                };
+                req.onerror = () => reject(new EnvelopeCacheError("Failed to list recent envelopes", req.error));
+            });
+        }
+        catch (err) {
+            console.error("EnvelopeCache listRecent error:", err);
+        }
+        return results;
+    }
+    /* -------------------------------
+     * Get envelope (checks memory first)
+     * ------------------------------- */
+    async get(envelope) {
+        const id = await this.getEnvelopeId(envelope);
+        // 1️⃣ Try memory cache
+        if (this.memoryCache.has(id))
+            return this.memoryCache.get(id);
+        // 2️⃣ Fallback to IndexedDB
+        const dbEnvelope = await this.getById(id);
+        if (dbEnvelope) {
+            // Populate memory cache
+            this.memoryCache.set(id, dbEnvelope);
+            if (this.memoryCache.size > this.memoryCacheSize) {
+                const firstKey = this.memoryCache.keys().next().value;
+                if (firstKey !== undefined) {
+                    this.memoryCache.delete(firstKey);
+                }
+            }
+        }
+        return dbEnvelope;
+    }
+    /* -------------------------------
+     * Get envelope by ID directly
+     * ------------------------------- */
+    async getById(id) {
+        try {
+            const db = await this.dbPromise;
+            const tx = db.transaction(this.storeName, "readonly");
+            const store = tx.objectStore(this.storeName);
+            return await new Promise((resolve, reject) => {
+                const req = store.get(id);
+                req.onsuccess = () => resolve(req.result?.envelope);
+                req.onerror = () => reject(new EnvelopeCacheError("Failed to get envelope", req.error));
+            });
+        }
+        catch (err) {
+            console.error("EnvelopeCache getById error:", err);
+            return undefined;
+        }
+    }
+    /* -------------------------------
+     * Check if envelope exists
+     * ------------------------------- */
+    async has(envelope) {
+        const id = await this.getEnvelopeId(envelope);
+        if (this.memoryCache.has(id))
+            return true;
+        try {
+            const db = await this.dbPromise;
+            const tx = db.transaction(this.storeName, "readonly");
+            const store = tx.objectStore(this.storeName);
+            return await new Promise((resolve) => {
+                const req = store.getKey(id);
+                req.onsuccess = () => resolve(req.result !== undefined);
+                req.onerror = () => resolve(false);
+            });
+        }
+        catch (err) {
+            console.error("EnvelopeCache has error:", err);
+            return false;
+        }
+    }
+    /* -------------------------------
+     * Delete envelope (memory + IDB)
+     * ------------------------------- */
+    async delete(envelope) {
+        const id = await this.getEnvelopeId(envelope);
+        // Remove from memory
+        this.memoryCache.delete(id);
+        try {
+            const db = await this.dbPromise;
+            const tx = db.transaction(this.storeName, "readwrite");
+            const store = tx.objectStore(this.storeName);
+            await new Promise((resolve, reject) => {
+                const req = store.delete(id);
+                req.onsuccess = () => resolve();
+                req.onerror = () => reject(new EnvelopeCacheError("Failed to delete envelope", req.error));
+            });
+        }
+        catch (err) {
+            console.error("EnvelopeCache delete error:", err);
+            throw err;
+        }
+    }
+    /* -------------------------------
+     * Delete all envelopes by fingerprint
+     * ------------------------------- */
+    async deleteByFingerprint(fingerprint) {
+        try {
+            const db = await this.dbPromise;
+            const tx = db.transaction(this.storeName, "readwrite");
+            const store = tx.objectStore(this.storeName);
+            // First, collect all IDs to delete
+            const idsToDelete = [];
+            const cursorReq = store.openCursor();
+            await new Promise((resolve, reject) => {
+                cursorReq.onsuccess = (event) => {
+                    const cursor = event.target
+                        .result;
+                    if (!cursor)
+                        return resolve();
+                    const val = cursor.value;
+                    const env = new MessageEnvelope(val.envelope.encryptedBlob);
+                    const envelopeFingerprint = env.extractFingerprint();
+                    if (envelopeFingerprint === fingerprint) {
+                        idsToDelete.push(val.id);
+                    }
+                    cursor.continue();
+                };
+                cursorReq.onerror = () => reject(new EnvelopeCacheError("Failed to iterate envelopes", cursorReq.error));
+            });
+            // Delete from IndexedDB and memory cache
+            for (const id of idsToDelete) {
+                await new Promise((resolve, reject) => {
+                    const req = store.delete(id);
+                    req.onsuccess = () => resolve();
+                    req.onerror = () => reject(new EnvelopeCacheError("Failed to delete envelope", req.error));
+                });
+                // Remove from memory cache
+                this.memoryCache.delete(id);
+            }
+        }
+        catch (err) {
+            console.error("EnvelopeCache deleteByFingerprint error:", err);
+            throw err;
+        }
+    }
+    /* -------------------------------
+     * Clear all envelopes (memory + IDB)
+     * ------------------------------- */
+    async clear() {
+        // Clear memory cache
+        this.memoryCache.clear();
+        try {
+            const db = await this.dbPromise;
+            const tx = db.transaction(this.storeName, "readwrite");
+            const store = tx.objectStore(this.storeName);
+            await new Promise((resolve, reject) => {
+                const req = store.clear();
+                req.onsuccess = () => resolve();
+                req.onerror = () => reject(new EnvelopeCacheError("Failed to clear envelope cache", req.error));
+            });
+        }
+        catch (err) {
+            console.error("EnvelopeCache clear error:", err);
+            return {
+                message: "Failed to clear envelope cache",
+                success: false,
+            };
+        }
+        return {
+            success: true,
+            message: "Envelope cache cleared successfully",
+        };
+    }
+    /* -------------------------------
+     * Enforce max entries in IDB (oldest first)
+     * ------------------------------- */
+    async enforceMaxEntries() {
+        if (!this.maxEntries)
+            return;
+        try {
+            const db = await this.dbPromise;
+            const tx = db.transaction(this.storeName, "readwrite");
+            const store = tx.objectStore(this.storeName);
+            const index = store.index("timestamp");
+            const countReq = store.count();
+            const total = await new Promise((resolve, reject) => {
+                countReq.onsuccess = () => resolve(countReq.result);
+                countReq.onerror = () => reject(countReq.error);
+            });
+            if (total <= this.maxEntries)
+                return;
+            const toDelete = total - this.maxEntries;
+            const keys = [];
+            const cursorReq = index.openKeyCursor();
+            await new Promise((resolve, reject) => {
+                cursorReq.onsuccess = (event) => {
+                    const cursor = event.target
+                        .result;
+                    if (cursor && keys.length < toDelete) {
+                        keys.push(cursor.primaryKey);
+                        cursor.continue();
+                    }
+                    else {
+                        resolve();
+                    }
+                };
+                cursorReq.onerror = () => reject(cursorReq.error);
+            });
+            for (const key of keys) {
+                await new Promise((resolve, reject) => {
+                    const req = store.delete(key);
+                    req.onsuccess = () => resolve();
+                    req.onerror = () => reject(req.error);
+                });
+            }
+        }
+        catch (err) {
+            console.error("EnvelopeCache enforceMaxEntries error:", err);
+        }
+    }
+    toJSON() {
+        const items = [];
+        this.memoryCache.forEach((envelope, id) => {
+            items.push({
+                id,
+                base64Payload: arrayBufferToBase64(envelope.encryptedBlob),
+                timestamp: Date.now(),
+            });
+        });
+        return {
+            config: {
+                dbName: this.dbName,
+                storeName: this.storeName,
+                maxEntries: this.maxEntries,
+                memoryCacheSize: this.memoryCacheSize,
+            },
+            items,
+        };
+    }
+    /* -------------------------------
+     * Deserialize cache from JSON
+     * ------------------------------- */
+    static fromJSON(json) {
+        const cache = new EnvelopeCache(json.config);
+        for (const item of json.items) {
+            const envelope = new MessageEnvelope(base64ToArrayBuffer(item.base64Payload));
+            cache.memoryCache.set(item.id, envelope);
+        }
+        return cache;
+    }
+}

package/dist/core/messages/message-envelope.d.ts

@@ -0,0 +1,36 @@
+import type { EnvelopePayload, RecipientKeys, SingleRecipientPayload } from "../types";
+export type EnvelopeErrorCode = "INVALID_INPUT" | "FORMAT_ERROR" | "VALIDATION_ERROR";
+export declare class MessageEnvelopeError extends Error {
+    readonly code: EnvelopeErrorCode;
+    readonly raw?: string;
+    constructor(code: EnvelopeErrorCode, message: string, raw?: string);
+}
+export declare class MessageEnvelope {
+    /** Raw decoded encrypted payload */
+    readonly encryptedBlob: ArrayBuffer;
+    static readonly PREFIX = "~*$MJKMSG";
+    static readonly DEFAULT_FINGERPRINT_LENGTH = 32;
+    constructor(blob: ArrayBuffer);
+    get raw(): ArrayBuffer;
+    /** Quick validation without throwing */
+    static tryFromString(raw: unknown): {
+        envelope?: MessageEnvelope;
+        error?: MessageEnvelopeError;
+    };
+    static isEnvelopeCandidate(input: unknown): boolean;
+    getVersion(): number;
+    static fromMatchedString(raw: unknown): MessageEnvelope;
+    extractFingerprint(fingerprintLength?: number): string;
+    extractEncryptedPayload(): EnvelopePayload;
+    /**
+     * Returns the ephemeral encrypted key for a given fingerprint
+     */
+    getRecipientKey(fingerprint: string): RecipientKeys | undefined;
+    getSingleRecipientPayload(): SingleRecipientPayload | undefined;
+    /**
+     * Checks if this envelope contains a key for the given fingerprint
+     */
+    hasRecipient(fingerprint: string): boolean;
+    isGroup(): boolean;
+    isSolo(): boolean;
+}

package/dist/core/messages/message-envelope.js

@@ -0,0 +1,161 @@
+import { base64ToArrayBuffer, arrayBufferToBase64 } from "../utils/utilities";
+/* -------------------------------
+ * Constants
+ * ------------------------------- */
+const ENVELOPE_PREFIX = "~*$MJKMSG";
+const ENVELOPE_REGEX = /^~\*\$MJKMSG:([A-Za-z0-9+/=]+)$/;
+const MAX_ENVELOPE_LENGTH = 16_384; // raw string
+const MAX_PAYLOAD_BYTES = 12_288; // decoded binary
+export class MessageEnvelopeError extends Error {
+    code;
+    raw;
+    constructor(code, message, raw) {
+        super(message);
+        this.name = "MessageEnvelopeError";
+        this.code = code;
+        this.raw = raw;
+    }
+}
+/* -------------------------------
+ * MessageEnvelope
+ * ------------------------------- */
+export class MessageEnvelope {
+    /** Raw decoded encrypted payload */
+    encryptedBlob;
+    static PREFIX = ENVELOPE_PREFIX;
+    static DEFAULT_FINGERPRINT_LENGTH = 32;
+    constructor(blob) {
+        this.encryptedBlob = blob;
+    }
+    get raw() {
+        return this.encryptedBlob;
+    }
+    /** Quick validation without throwing */
+    static tryFromString(raw) {
+        try {
+            return { envelope: MessageEnvelope.fromMatchedString(raw) };
+        }
+        catch (err) {
+            return { error: err };
+        }
+    }
+    static isEnvelopeCandidate(input) {
+        return (typeof input === "string" &&
+            input.length <= MAX_ENVELOPE_LENGTH &&
+            ENVELOPE_REGEX.test(input.trim()));
+    }
+    getVersion() {
+        const view = new Uint8Array(this.encryptedBlob);
+        if (view.length < 1) {
+            throw new MessageEnvelopeError("VALIDATION_ERROR", "Encrypted blob too short to contain version byte");
+        }
+        return view[0];
+    }
+    /* -------------------------------
+     * Factory
+     * ------------------------------- */
+    static fromMatchedString(raw) {
+        if (typeof raw !== "string") {
+            throw new MessageEnvelopeError("INVALID_INPUT", "Envelope input must be a string");
+        }
+        const trimmed = raw.trim();
+        if (trimmed.length > MAX_ENVELOPE_LENGTH) {
+            throw new MessageEnvelopeError("VALIDATION_ERROR", "Envelope exceeds maximum allowed length", raw);
+        }
+        const match = ENVELOPE_REGEX.exec(trimmed);
+        if (!match) {
+            throw new MessageEnvelopeError("FORMAT_ERROR", `Invalid envelope format. Expected ${ENVELOPE_PREFIX}:<base64>`, raw);
+        }
+        let decoded;
+        try {
+            decoded = base64ToArrayBuffer(match[1]);
+        }
+        catch {
+            throw new MessageEnvelopeError("VALIDATION_ERROR", "Base64 payload failed to decode", raw);
+        }
+        if (decoded.byteLength === 0) {
+            throw new MessageEnvelopeError("VALIDATION_ERROR", "Decoded payload is empty", raw);
+        }
+        if (decoded.byteLength > MAX_PAYLOAD_BYTES) {
+            throw new MessageEnvelopeError("VALIDATION_ERROR", "Decoded payload exceeds size limit", raw);
+        }
+        return new MessageEnvelope(decoded);
+    }
+    /* -------------------------------
+     * Extract Fingerprint (first one)
+     * ------------------------------- */
+    extractFingerprint(fingerprintLength = MessageEnvelope.DEFAULT_FINGERPRINT_LENGTH) {
+        const view = new Uint8Array(this.encryptedBlob);
+        if (view.length < 1 + fingerprintLength) {
+            throw new MessageEnvelopeError("VALIDATION_ERROR", "Encrypted blob too short to contain fingerprint");
+        }
+        const fingerprintBytes = view.slice(1, 1 + fingerprintLength);
+        const ab = fingerprintBytes.buffer.slice(fingerprintBytes.byteOffset, fingerprintBytes.byteOffset + fingerprintBytes.length);
+        return arrayBufferToBase64(ab);
+    }
+    /* -------------------------------
+     * Extract Encrypted Payload
+     * ------------------------------- */
+    extractEncryptedPayload() {
+        const view = new Uint8Array(this.encryptedBlob);
+        const versionLength = 1;
+        const fingerprintLength = MessageEnvelope.DEFAULT_FINGERPRINT_LENGTH;
+        if (view.length < versionLength + fingerprintLength + 1) {
+            throw new MessageEnvelopeError("VALIDATION_ERROR", "Encrypted blob too short to contain payload");
+        }
+        const payloadBytes = view.slice(versionLength + fingerprintLength);
+        const payloadText = new TextDecoder().decode(payloadBytes);
+        let parsed;
+        try {
+            parsed = JSON.parse(payloadText);
+        }
+        catch {
+            throw new MessageEnvelopeError("VALIDATION_ERROR", "Failed to parse encrypted payload JSON");
+        }
+        // Validate multi-recipient
+        if ("keys" in parsed) {
+            if (!parsed.iv ||
+                !parsed.ciphertext ||
+                !parsed.ephemeralPublicKey ||
+                !Array.isArray(parsed.keys)) {
+                throw new MessageEnvelopeError("VALIDATION_ERROR", "Multi-recipient payload missing required fields");
+            }
+            for (const k of parsed.keys) {
+                if (!k.fingerprint || !k.ephemeralEncryptedKey || !k.nonce) {
+                    throw new MessageEnvelopeError("VALIDATION_ERROR", "Invalid key entry in multi-recipient payload");
+                }
+            }
+        }
+        return parsed;
+    }
+    /* -------------------------------
+     * Multi-Recipient Helpers
+     * ------------------------------- */
+    /**
+     * Returns the ephemeral encrypted key for a given fingerprint
+     */
+    getRecipientKey(fingerprint) {
+        const payload = this.extractEncryptedPayload();
+        if ("keys" in payload) {
+            return payload.keys.find((k) => k.fingerprint === fingerprint);
+        }
+        return undefined;
+    }
+    getSingleRecipientPayload() {
+        const payload = this.extractEncryptedPayload();
+        return "keys" in payload ? undefined : payload;
+    }
+    /**
+     * Checks if this envelope contains a key for the given fingerprint
+     */
+    hasRecipient(fingerprint) {
+        return !!this.getRecipientKey(fingerprint);
+    }
+    isGroup() {
+        const payload = this.extractEncryptedPayload();
+        return "keys" in payload;
+    }
+    isSolo() {
+        return !this.isGroup();
+    }
+}

package/dist/core/scanner/scanner-engine.d.ts

@@ -0,0 +1,27 @@
+import { MessageEnvelope } from "../messages/message-envelope";
+import { MajikContactDirectory } from "../contacts/majik-contact-directory";
+import { EnvelopeCache } from "../messages/envelope-cache";
+interface ScannerEngineConfig {
+    contactDirectory: MajikContactDirectory;
+    envelopeCache?: EnvelopeCache;
+    onEnvelopeFound?: (envelope: MessageEnvelope) => void;
+    onUntrusted?: (raw: string) => void;
+    onError?: (err: Error, context?: {
+        raw?: string;
+    }) => void;
+}
+export declare class ScannerEngine {
+    private observer?;
+    private contactDirectory;
+    private envelopeCache?;
+    private onEnvelopeFound?;
+    private onUntrusted?;
+    private onError?;
+    private processedNodes;
+    constructor(config: ScannerEngineConfig);
+    scanText(text: string): Promise<void>;
+    scanDOM(rootNode: Node): void;
+    startDOMObserver(rootNode: Node): void;
+    stopDOMObserver(): void;
+}
+export {};