@majikah/majik-message 0.2.2 → 0.2.3

package/dist/core/crypto/crypto-provider.d.ts

@@ -51,7 +51,6 @@ export declare function deriveKeyFromPassphrase(passphrase: string, salt: Uint8A
  */
 export declare function deriveKeyFromMnemonic(mnemonic: string, salt: Uint8Array, iterations?: number, keyLen?: number): Uint8Array;
 export declare function x25519SharedSecret(privRaw: Uint8Array, pubRaw: Uint8Array): Uint8Array;
-export declare function sha256(input: string): string;
 /**
  * Derive a deterministic ML-KEM-768 keypair from a BIP-39 mnemonic seed.
  *
@@ -116,3 +115,5 @@ export declare function mlKemEncapsulate(recipientPublicKey: Uint8Array): {
  * @returns sharedSecret (32 bytes)
  */
 export declare function mlKemDecapsulate(cipherText: Uint8Array, recipientSecretKey: Uint8Array): Uint8Array;
+export declare function sha256(input: string): string;
+export declare function sha512(input: string): string;

package/dist/core/crypto/crypto-provider.js

@@ -10,6 +10,8 @@ import { arrayToBase64 } from "../utils/utilities";
 import { argon2id } from "@noble/hashes/argon2.js";
 import { ARGON2_PARAMS } from "./constants";
 import { ml_kem768 } from "@noble/post-quantum/ml-kem.js";
+import { sha3_512 } from "@noble/hashes/sha3.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
 export const IV_LENGTH = 12;
 export function generateRandomBytes(len) {
     const b = new Uint8Array(len);
@@ -113,10 +115,6 @@ export function x25519SharedSecret(privRaw, pubRaw) {
     }
     throw new Error("@stablelib/x25519: compatible API not found");
 }
-export function sha256(input) {
-    const hashed = hash(new TextEncoder().encode(input));
-    return arrayToBase64(hashed);
-}
 // ─── ML-KEM-768: Post-Quantum Key Encapsulation ───────────────────────────────
 /**
  * Derive a deterministic ML-KEM-768 keypair from a BIP-39 mnemonic seed.
@@ -185,3 +183,12 @@ export function mlKemEncapsulate(recipientPublicKey) {
 export function mlKemDecapsulate(cipherText, recipientSecretKey) {
     return ml_kem768.decapsulate(cipherText, recipientSecretKey);
 }
+// ─── Hashing ───────────────────────────────
+export function sha256(input) {
+    const hashed = hash(new TextEncoder().encode(input));
+    return arrayToBase64(hashed);
+}
+export function sha512(input) {
+    const hashed = sha3_512(new TextEncoder().encode(input));
+    return bytesToHex(hashed);
+}

package/dist/core/database/thread/majik-message-thread.d.ts

@@ -62,9 +62,28 @@ export interface MajikMessageThreadJSON {
     participants: string[];
     status: ThreadStatus;
     hash: string;
+    t_hash: string | null;
     deletion_approvals: DeletionApproval[];
     starred: boolean;
 }
+export interface MajikMessageThreadExport {
+    thread: MajikMessageThreadJSON;
+    messages: MajikMessageMailJSON[];
+    exported_at: ISODateString;
+    message_count: number;
+}
+/**
+ * Result shape returned by MajikMessageThread.auditThread().
+ * isValid is true only when ALL three checks pass.
+ */
+export interface ThreadAuditResult {
+    isValid: boolean;
+    threadValid: boolean;
+    chainValid: boolean;
+    hashValid: boolean;
+    errors: string[];
+    tamperedMailIDs: string[];
+}
 export declare class MajikThreadError extends Error {
     code: string;
     constructor(message: string, code: string);
@@ -84,6 +103,7 @@ export declare class MajikMessageThread {
     private readonly _participants;
     private _status;
     private readonly _hash;
+    private _thash;
     private _deletionApprovals;
     private _starred;
     private constructor();
@@ -95,9 +115,83 @@ export declare class MajikMessageThread {
     get participants(): readonly MajikMessagePublicKey[];
     get status(): ThreadStatus;
     get hash(): string;
+    get threadHash(): string | null;
     get deletionApprovals(): readonly DeletionApproval[];
     get starred(): boolean;
+    set subject(value: string | undefined);
     static create(userID: MajikUserID, owner: MajikMessageIdentity, participants: MajikMessagePublicKey[], metadata?: ThreadMetadata): MajikMessageThread;
+    /**
+     * Computes and stamps the t_hash for this thread.
+     *
+     * The t_hash is a SHA3-512 fingerprint of the entire thread's message history
+     * combined with the thread's own identity hash. It acts as a tamper-evident
+     * seal over the full conversation — if any message is altered, the t_hash
+     * won't match.
+     *
+     * Input string layout (joined with ":"):
+     *   <thread.hash> : <mail[0].hash> : <mail[1].hash> : … : <thread.id>
+     *   where mails are sorted by timestamp ascending (oldest first).
+     *
+     * Calling this with an empty array is valid — it seals a thread that has no
+     * messages yet (useful for archival of zero-message threads).
+     *
+     * @param mails - The full list of MajikMessageMailJSON for this thread.
+     *                Does not need to be pre-sorted.
+     * @returns The updated thread instance (for chaining).
+     */
+    generateThreadHash(mails: MajikMessageMailJSON[]): this;
+    /**
+     * Verifies that the stored t_hash matches a freshly computed one.
+     *
+     * @param mails - The full list of MajikMessageMailJSON for this thread.
+     * @returns true if the t_hash is valid and matches, false if t_hash not yet set.
+     * @throws ValidationError if the computed hash does not match the stored one.
+     */
+    verifyThreadHash(mails: MajikMessageMailJSON[]): boolean;
+    /**
+     * Performs a full forensic audit of the thread.
+     *
+     * Accepts raw MajikMessageMailJSON — instances are hydrated internally via
+     * MajikMessageMail.fromJSON so the call site only needs one array.
+     *
+     * Three checks must all pass for `isValid` to be true:
+     *
+     *   1. **threadValid** — `thread.validate()` passes (structural integrity of the
+     *      thread object itself: UUID, hash, participants, deletion approvals, etc.)
+     *
+     *   2. **chainValid** — `MajikMessageMail.validateMailChain()` passes (every
+     *      message hash is self-consistent and the blockchain p_hash linkage from
+     *      thread → mail[0] → mail[1] → … is intact).
+     *
+     *   3. **hashValid** — `thread.verifyThreadHash()` passes (the SHA3-512 t_hash
+     *      sealed over the full message list still matches). Returns false — not an
+     *      error — when t_hash has not yet been generated, meaning the thread is
+     *      structurally sound but still unsealed.
+     *
+     * @param thread    - The thread instance to audit.
+     * @param mailJSONs - Full list of MajikMessageMailJSON for this thread.
+     *                    Does not need to be pre-sorted.
+     * @returns ThreadAuditResult with granular pass/fail per check plus error details.
+     */
+    static auditThread(thread: MajikMessageThread, mailJSONs: MajikMessageMailJSON[]): ThreadAuditResult;
+    /**
+     * Exports the thread and its full message history as a self-contained snapshot.
+     *
+     * Requires that `generateThreadHash()` has already been called — the t_hash is
+     * the integrity seal over the exported payload and must be present before the
+     * export is considered authoritative. Call `generateThreadHash(mails)` first if
+     * it has not been set yet.
+     *
+     * The returned messages are sorted by timestamp ascending (oldest first) so the
+     * export is always deterministic regardless of the order they were passed in.
+     *
+     * @param mails - The full list of MajikMessageMailJSON for this thread.
+     * @returns MajikMessageThreadExport containing the sealed thread JSON, sorted
+     *          messages, export timestamp, and message count.
+     * @throws OperationNotAllowedError if t_hash has not been generated yet.
+     * @throws ValidationError if any mail does not belong to this thread.
+     */
+    exportThread(mails: MajikMessageMailJSON[]): MajikMessageThreadExport;
     /**
      * Stars the thread for the user
      */

package/dist/core/database/thread/majik-message-thread.js

@@ -1,6 +1,7 @@
 import { v4 as uuidv4 } from "uuid";
 import { ThreadStatus } from "./enums";
-import { sha256 } from "../../crypto/crypto-provider";
+import { sha256, sha512 } from "../../crypto/crypto-provider";
+import { MajikMessageMail, } from "./mail/majik-message-mail";
 // ==================== Custom Errors ====================
 export class MajikThreadError extends Error {
     code;
@@ -22,6 +23,38 @@ export class OperationNotAllowedError extends MajikThreadError {
         this.name = "OperationNotAllowedError";
     }
 }
+/**
+ * Sorts an array of MajikMessageMailJSON by timestamp (oldest → newest).
+ * Returns a new array — does not mutate the input.
+ */
+function sortMailsByTimestamp(mails) {
+    return [...mails].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+}
+/**
+ * Joins an array of strings with ":" as the delimiter.
+ *
+ * joinWithColon(["abc", "def", "ghi"]) → "abc:def:ghi"
+ */
+function joinWithColon(parts) {
+    return parts.join(":");
+}
+/**
+ * Builds the raw string fed into SHA3-512 for t_hash.
+ *
+ * Layout:  <thread.hash> : <mail[0].hash> : … : <mail[n].hash> : <thread.id>
+ *
+ * @param threadHash   - The thread's own SHA-256 hash
+ * @param threadID     - The thread's UUID
+ * @param sortedMails  - Messages pre-sorted by timestamp ascending
+ */
+function buildThreadHashInput(threadHash, threadID, sortedMails) {
+    const parts = [
+        threadHash,
+        ...sortedMails.map((m) => m.hash),
+        threadID,
+    ];
+    return joinWithColon(parts);
+}
 // ==================== Main Class ====================
 export class MajikMessageThread {
     _id;
@@ -32,10 +65,11 @@ export class MajikMessageThread {
     _participants;
     _status;
     _hash;
+    _thash;
     _deletionApprovals;
     _starred;
     // ==================== Private Constructor ====================
-    constructor(id, userID, owner, metadata, timestamp, participants, status, hash, deletionApprovals = [], starred = false) {
+    constructor(id, userID, owner, metadata, timestamp, participants, status, hash, deletionApprovals = [], starred = false, thash = null) {
         this._id = id;
         this._userID = userID;
         this._owner = owner;
@@ -44,6 +78,7 @@ export class MajikMessageThread {
         this._participants = participants;
         this._status = status;
         this._hash = hash;
+        this._thash = thash;
         this._deletionApprovals = deletionApprovals;
         this._starred = starred;
         // Validate on construction
@@ -74,12 +109,18 @@ export class MajikMessageThread {
     get hash() {
         return this._hash;
     }
+    get threadHash() {
+        return this._thash;
+    }
     get deletionApprovals() {
         return [...this._deletionApprovals];
     }
     get starred() {
         return this._starred;
     }
+    set subject(value) {
+        this.updateMetadata({ subject: value });
+    }
     // ==================== Static Create Method ====================
     static create(userID, owner, participants, metadata = {}) {
         try {
@@ -108,7 +149,7 @@ export class MajikMessageThread {
             const status = ThreadStatus.ONGOING;
             // Generate hash
             const hash = MajikMessageThread.generateHash(userID, timestamp, id, uniqueParticipants);
-            return new MajikMessageThread(id, userID, owner.id, metadata, timestamp, uniqueParticipants, status, hash, []);
+            return new MajikMessageThread(id, userID, owner.id, metadata, timestamp, uniqueParticipants, status, hash, [], false, null);
         }
         catch (error) {
             if (error instanceof MajikThreadError) {
@@ -117,6 +158,210 @@ export class MajikMessageThread {
             throw new MajikThreadError(`Failed to create MajikMessageThread: ${error instanceof Error ? error.message : "Unknown error"}`, "CREATE_FAILED");
         }
     }
+    // ==================== Thread Hash (t_hash) ====================
+    /**
+     * Computes and stamps the t_hash for this thread.
+     *
+     * The t_hash is a SHA3-512 fingerprint of the entire thread's message history
+     * combined with the thread's own identity hash. It acts as a tamper-evident
+     * seal over the full conversation — if any message is altered, the t_hash
+     * won't match.
+     *
+     * Input string layout (joined with ":"):
+     *   <thread.hash> : <mail[0].hash> : <mail[1].hash> : … : <thread.id>
+     *   where mails are sorted by timestamp ascending (oldest first).
+     *
+     * Calling this with an empty array is valid — it seals a thread that has no
+     * messages yet (useful for archival of zero-message threads).
+     *
+     * @param mails - The full list of MajikMessageMailJSON for this thread.
+     *                Does not need to be pre-sorted.
+     * @returns The updated thread instance (for chaining).
+     */
+    generateThreadHash(mails) {
+        try {
+            // ── One-time seal guard ────────────────────────────────────────────────
+            // t_hash is write-once. Once stamped it represents a finalized snapshot
+            // of the conversation. If you need to re-seal (e.g. after more messages),
+            // reconstruct the thread via fromJSON with t_hash: null first.
+            if (this._thash !== null) {
+                throw new OperationNotAllowedError("Thread hash has already been generated. t_hash is write-once and cannot be overwritten.");
+            }
+            if (!Array.isArray(mails)) {
+                throw new ValidationError("mails must be an array");
+            }
+            // Validate every mail belongs to this thread
+            for (const mail of mails) {
+                if (mail.thread_id !== this._id) {
+                    throw new ValidationError(`Mail "${mail.id}" belongs to thread "${mail.thread_id}", not "${this._id}"`);
+                }
+            }
+            const sorted = sortMailsByTimestamp(mails);
+            const input = buildThreadHashInput(this._hash, this._id, sorted);
+            this._thash = sha512(input);
+            return this;
+        }
+        catch (error) {
+            if (error instanceof MajikThreadError) {
+                throw error;
+            }
+            throw new MajikThreadError(`Failed to generate thread hash: ${error instanceof Error ? error.message : "Unknown error"}`, "THREAD_HASH_FAILED");
+        }
+    }
+    /**
+     * Verifies that the stored t_hash matches a freshly computed one.
+     *
+     * @param mails - The full list of MajikMessageMailJSON for this thread.
+     * @returns true if the t_hash is valid and matches, false if t_hash not yet set.
+     * @throws ValidationError if the computed hash does not match the stored one.
+     */
+    verifyThreadHash(mails) {
+        if (this._thash === null) {
+            return false; // Not yet generated — nothing to verify
+        }
+        if (!Array.isArray(mails)) {
+            throw new ValidationError("mails must be an array");
+        }
+        const sorted = sortMailsByTimestamp(mails);
+        const input = buildThreadHashInput(this._hash, this._id, sorted);
+        const expected = sha512(input);
+        if (this._thash !== expected) {
+            throw new ValidationError("Thread hash (t_hash) mismatch — message history integrity compromised");
+        }
+        return true;
+    }
+    // ==================== Full Thread Audit ====================
+    /**
+     * Performs a full forensic audit of the thread.
+     *
+     * Accepts raw MajikMessageMailJSON — instances are hydrated internally via
+     * MajikMessageMail.fromJSON so the call site only needs one array.
+     *
+     * Three checks must all pass for `isValid` to be true:
+     *
+     *   1. **threadValid** — `thread.validate()` passes (structural integrity of the
+     *      thread object itself: UUID, hash, participants, deletion approvals, etc.)
+     *
+     *   2. **chainValid** — `MajikMessageMail.validateMailChain()` passes (every
+     *      message hash is self-consistent and the blockchain p_hash linkage from
+     *      thread → mail[0] → mail[1] → … is intact).
+     *
+     *   3. **hashValid** — `thread.verifyThreadHash()` passes (the SHA3-512 t_hash
+     *      sealed over the full message list still matches). Returns false — not an
+     *      error — when t_hash has not yet been generated, meaning the thread is
+     *      structurally sound but still unsealed.
+     *
+     * @param thread    - The thread instance to audit.
+     * @param mailJSONs - Full list of MajikMessageMailJSON for this thread.
+     *                    Does not need to be pre-sorted.
+     * @returns ThreadAuditResult with granular pass/fail per check plus error details.
+     */
+    static auditThread(thread, mailJSONs) {
+        const errors = [];
+        let tamperedMailIDs = [];
+        let threadValid = false;
+        let chainValid = false;
+        let hashValid = false;
+        // ── 1. Structural thread validation ───────────────────────────────────────
+        try {
+            thread.validate();
+            threadValid = true;
+        }
+        catch (err) {
+            errors.push(`Thread structure invalid: ${err instanceof Error ? err.message : "Unknown error"}`);
+        }
+        // ── 2. Hydrate JSON → instances, then run chain validation ────────────────
+        // bypassValidation=false so fromJSON still runs per-mail validation.
+        // If any individual mail fails to parse we record the error and skip the
+        // chain check rather than throwing out of the audit entirely.
+        let mailInstances = [];
+        try {
+            mailInstances = mailJSONs.map((json) => MajikMessageMail.fromJSON(json));
+        }
+        catch (err) {
+            errors.push(`Failed to hydrate mail JSON: ${err instanceof Error ? err.message : "Unknown error"}`);
+        }
+        // Only run chain validation when hydration succeeded (or the list was empty)
+        if (mailInstances.length === mailJSONs.length) {
+            try {
+                const chainResult = MajikMessageMail.validateMailChain(thread, mailInstances);
+                chainValid = chainResult.isValid;
+                if (!chainResult.isValid) {
+                    errors.push(...chainResult.errors);
+                    tamperedMailIDs = chainResult.tamperedItems;
+                }
+            }
+            catch (err) {
+                errors.push(`Mail chain audit threw unexpectedly: ${err instanceof Error ? err.message : "Unknown error"}`);
+            }
+        }
+        // ── 3. Thread hash (t_hash) verification ──────────────────────────────────
+        // At this point t_hash is guaranteed non-null (the early guard above threw
+        // otherwise). verifyThreadHash only throws on an actual mismatch.
+        try {
+            hashValid = thread.verifyThreadHash(mailJSONs);
+        }
+        catch (err) {
+            errors.push(`Thread hash mismatch: ${err instanceof Error ? err.message : "Unknown error"}`);
+        }
+        return {
+            isValid: threadValid && chainValid && hashValid,
+            threadValid,
+            chainValid,
+            hashValid,
+            errors,
+            tamperedMailIDs: Array.from(new Set(tamperedMailIDs)),
+        };
+    }
+    // ==================== Thread Export ====================
+    /**
+     * Exports the thread and its full message history as a self-contained snapshot.
+     *
+     * Requires that `generateThreadHash()` has already been called — the t_hash is
+     * the integrity seal over the exported payload and must be present before the
+     * export is considered authoritative. Call `generateThreadHash(mails)` first if
+     * it has not been set yet.
+     *
+     * The returned messages are sorted by timestamp ascending (oldest first) so the
+     * export is always deterministic regardless of the order they were passed in.
+     *
+     * @param mails - The full list of MajikMessageMailJSON for this thread.
+     * @returns MajikMessageThreadExport containing the sealed thread JSON, sorted
+     *          messages, export timestamp, and message count.
+     * @throws OperationNotAllowedError if t_hash has not been generated yet.
+     * @throws ValidationError if any mail does not belong to this thread.
+     */
+    exportThread(mails) {
+        try {
+            // t_hash must be set — an unsealed thread cannot be exported
+            if (this._thash === null) {
+                throw new OperationNotAllowedError("Cannot export thread: t_hash has not been generated yet. " +
+                    "Call generateThreadHash(mails) before exporting.");
+            }
+            if (!Array.isArray(mails)) {
+                throw new ValidationError("mails must be an array");
+            }
+            // Validate every mail belongs to this thread
+            for (const mail of mails) {
+                if (mail.thread_id !== this._id) {
+                    throw new ValidationError(`Mail "${mail.id}" belongs to thread "${mail.thread_id}", not "${this._id}"`);
+                }
+            }
+            const sortedMails = sortMailsByTimestamp(mails);
+            return {
+                thread: this.toJSON(),
+                messages: sortedMails,
+                exported_at: new Date().toISOString(),
+                message_count: sortedMails.length,
+            };
+        }
+        catch (error) {
+            if (error instanceof MajikThreadError) {
+                throw error;
+            }
+            throw new MajikThreadError(`Failed to export thread: ${error instanceof Error ? error.message : "Unknown error"}`, "EXPORT_THREAD_FAILED");
+        }
+    }
     // ==================== Star Management ====================
     /**
      * Stars the thread for the user
@@ -225,8 +470,8 @@ export class MajikMessageThread {
                         throw new ValidationError(`Deletion approval from non-participant: ${approval.publicKey}`);
                     }
                     // Verify approval hash
-                    const expectedHash = MajikMessageThread.generateApprovalHash(approval.publicKey, this._id, approval.timestamp);
-                    if (approval.approvalHash !== expectedHash) {
+                    const expectedApprovalHash = MajikMessageThread.generateApprovalHash(approval.publicKey, this._id, approval.timestamp);
+                    if (approval.approvalHash !== expectedApprovalHash) {
                         throw new ValidationError(`Invalid approval hash for participant: ${approval.publicKey}`);
                     }
                 }
@@ -474,6 +719,7 @@ export class MajikMessageThread {
             participants: [...this._participants],
             status: this._status,
             hash: this._hash,
+            t_hash: this._thash,
             deletion_approvals: this._deletionApprovals.length > 0
                 ? this._deletionApprovals.map((approval) => ({
                     ...approval,
@@ -496,7 +742,7 @@ export class MajikMessageThread {
                 ...approval,
                 timestamp: new Date(approval.timestamp),
             }));
-            return new MajikMessageThread(data.id, data.user_id, data.owner, data.metadata, timestamp, data.participants, data.status, data.hash, deletionApprovals, data.starred);
+            return new MajikMessageThread(data.id, data.user_id, data.owner, data.metadata, timestamp, data.participants, data.status, data.hash, deletionApprovals, data.starred, data.t_hash);
         }
         catch (error) {
             if (error instanceof MajikThreadError) {
@@ -581,6 +827,7 @@ export class MajikMessageThread {
                 participants: [...this._participants],
                 status: finalStatus,
                 hash: this._hash,
+                t_hash: this._thash,
                 deletion_approvals: this._deletionApprovals.map((approval) => ({
                     ...approval,
                     timestamp: approval.timestamp,

package/package.json

@@ -2,7 +2,7 @@
   "name": "@majikah/majik-message",
   "type": "module",
   "description": "Post-quantum end-to-end encryption with ML-KEM-768. Seed phrase–based accounts. Auto-expiring messages. Offline-ready. Exportable encrypted messages. Tamper-proof threads with blockchain-like integrity. Quantum-resistant messaging.",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",