@majikah/majik-message 0.2.5 → 0.2.8

package/dist/core/crypto/keystore.d.ts

@@ -208,6 +208,7 @@ export declare class MajikKeyStore {
      * Drop-in for MajikKeyStore.deleteIdentity().
      */
     static deleteIdentity(id: string): Promise<void>;
+    static deleteAll(): Promise<void>;
     /**
      * Drop-in for MajikKeyStore.generateMnemonic().
      */

package/dist/core/crypto/keystore.js

@@ -519,6 +519,20 @@ export class MajikKeyStore {
     static async deleteIdentity(id) {
         return this.delete(id);
     }
+    static async deleteAll() {
+        const db = await this._getDB();
+        const clearStore = (storeName) => new Promise((resolve, reject) => {
+            if (!db.objectStoreNames.contains(storeName))
+                return resolve();
+            const tx = db.transaction(storeName, "readwrite");
+            const req = tx.objectStore(storeName).clear();
+            req.onsuccess = () => resolve();
+            req.onerror = () => reject(new MajikKeyStoreError(`Failed to clear store: ${storeName}`, req.error));
+        });
+        await clearStore(STORE_NAME);
+        await clearStore(LEGACY_STORE_NAME);
+        this._keys.clear();
+    }
     /**
      * Drop-in for MajikKeyStore.generateMnemonic().
      */

package/dist/majik-message.d.ts

@@ -402,6 +402,151 @@ export declare class MajikMessage {
         contentType?: string;
         timestamp?: string;
     }): Promise<MajikSignature>;
+    /**
+     * Convenience alias for signing a plain string.
+     *
+     * Identical to signContent() but accepts only strings — makes call-sites
+     * that deal exclusively with text cleaner (no Uint8Array overload noise).
+     *
+     * @example
+     *   const sig = await majik.signText("Hello world", { contentType: "text/plain" });
+     *   const b64 = sig.serialize(); // store alongside the text
+     */
+    signText(text: string, options?: {
+        contentType?: string;
+        timestamp?: string;
+        accountId?: string;
+    }): Promise<MajikSignature>;
+    /**
+     * Sign content and return both the MajikSignature instance and a portable
+     * base64-serialized string in one call.
+     *
+     * The serialized string is safe to store in a database column, embed in a
+     * JSON field, pass in an HTTP header, or encode in a QR code alongside the
+     * original content. Pass it back to verifyDetached() to verify.
+     *
+     * @example — sign a document and store the detached signature
+     *   const { serialized } = await majik.signAndDetach(docBytes, {
+     *     contentType: "application/pdf",
+     *   });
+     *   await db.insert({ doc_id, signature: serialized });
+     *
+     * @example — sign a text message
+     *   const { signature, serialized } = await majik.signAndDetach("Hello!", {
+     *     contentType: "text/plain",
+     *   });
+     */
+    signAndDetach(content: Uint8Array | string, options?: {
+        contentType?: string;
+        timestamp?: string;
+        accountId?: string;
+    }): Promise<{
+        signature: MajikSignature;
+        serialized: string;
+    }>;
+    /**
+     * Verify a plain string against a MajikSignature.
+     *
+     * Accepts the signature as a MajikSignature instance, a MajikSignatureJSON
+     * object, or a base64-serialized string — whichever form is easiest at the
+     * call-site.
+     *
+     * The signer can be identified by contact ID, raw public key base64, or a
+     * MajikKey instance. If none is provided the public keys embedded in the
+     * signature envelope are used (self-reported — cross-check result.signerId
+     * against a known contact fingerprint before trusting).
+     *
+     * @example
+     *   const result = await majik.verifyText("Hello world", sig, {
+     *     contactId: "contact_abc",
+     *   });
+     *   if (result.valid) console.log("Authentic");
+     */
+    verifyText(text: string, signature: MajikSignature | MajikSignatureJSON | string, options?: {
+        contactId?: string;
+        publicKeyBase64?: string;
+        key?: MajikKey;
+        expectedSignerId?: string;
+    }): Promise<VerificationResult>;
+    /**
+     * Verify content against a base64-serialized detached signature string.
+     *
+     * This is the pair to signAndDetach() — designed for call-sites that retrieve
+     * a stored base64 signature from a database or API and want to verify without
+     * importing MajikSignature themselves.
+     *
+     * The signer can be identified by contact ID, raw public key base64, or a
+     * MajikKey. If none is provided, self-reported keys from the envelope are used
+     * (see security note on verifyContent).
+     *
+     * @example
+     *   const row = await db.findOne({ doc_id });
+     *   const result = await majik.verifyDetached(docBytes, row.signature, {
+     *     contactId: row.signer_contact_id,
+     *   });
+     *   if (result.valid) console.log("Signed by", result.signerId);
+     */
+    verifyDetached(content: Uint8Array | string, serializedSignature: string, options?: {
+        contactId?: string;
+        publicKeyBase64?: string;
+        key?: MajikKey;
+        expectedSignerId?: string;
+    }): Promise<VerificationResult>;
+    /**
+     * Deserialize a base64 signature string into a MajikSignature instance.
+     *
+     * Round-trip partner for MajikSignature.serialize() / sig.toString().
+     * Use when you have a stored base64 string and need to inspect or pass
+     * the instance to another method.
+     *
+     * Throws MajikSignatureSerializationError on malformed input.
+     *
+     * @example
+     *   const sig = majik.deserializeSignature(storedBase64);
+     *   console.log(sig.signerId, sig.timestamp);
+     */
+    deserializeSignature(serialized: string): MajikSignature;
+    /**
+     * Extract lightweight metadata from a base64 or JSON signature string
+     * without performing cryptographic verification.
+     *
+     * Useful for displaying "Signed by X at Y" in a UI before the user
+     * explicitly triggers a verification step.
+     *
+     * Returns null if the string cannot be parsed as a MajikSignature.
+     *
+     * @example
+     *   const meta = majik.getSignatureMetadata(storedSig);
+     *   if (meta) {
+     *     const contact = majik.getContactByID(meta.signerId);
+     *     console.log(`Signed by ${contact?.meta?.label ?? meta.signerId} at ${meta.timestamp}`);
+     *   }
+     */
+    getSignatureMetadata(serialized: string): {
+        signerId: string;
+        timestamp: string;
+        contentType: string | undefined;
+        contentHash: string;
+        version: number;
+    } | null;
+    /**
+     * Check whether an account has signing keys without throwing.
+     *
+     * Use this as a fast boolean guard before showing signing UI or before
+     * calling any sign* method — those methods throw if signing keys are absent,
+     * so checking first lets you degrade gracefully (e.g. hide a "Sign" button).
+     *
+     * Checks the in-memory keystore cache only — the account must be loaded.
+     * Returns false for unknown accounts rather than throwing.
+     *
+     * @example
+     *   if (!majik.hasSigningCapability()) {
+     *     showUpgradePrompt("Re-import your account to enable signing");
+     *     return;
+     *   }
+     *   const sig = await majik.signText(message);
+     */
+    hasSigningCapability(accountId?: string): boolean;
     listCachedEnvelopes(offset?: number, limit?: number): Promise<EnvelopeCacheItem[]>;
     clearCachedEnvelopes(): Promise<boolean>;
     /**
@@ -461,6 +606,42 @@ export declare class MajikMessage {
         handler: string;
         mimeType: string;
     }>;
+    /**
+     * Sign multiple file blobs with the active (or specified) account in one call.
+     *
+     * Each file is signed independently — a failure on one does not abort the
+     * others. Check result.error on each item to handle partial failures.
+     *
+     * The hasSigningKeys check is done once upfront before any signing begins,
+     * so the whole batch fails fast if the account can't sign rather than
+     * discovering it mid-batch.
+     *
+     * @example
+     *   const results = await majik.batchSignFiles([
+     *     { file: pdfBlob, contentType: "application/pdf" },
+     *     { file: wavBlob, contentType: "audio/wav" },
+     *     { file: mp4Blob, contentType: "video/mp4" },
+     *   ]);
+     *   for (const r of results) {
+     *     if (r.error) console.error("Failed:", r.error.message);
+     *     else await r2.put(key, await r.blob!.arrayBuffer());
+     *   }
+     */
+    batchSignFiles(files: Array<{
+        file: Blob;
+        contentType?: string;
+        timestamp?: string;
+        mimeType?: string;
+    }>, options?: {
+        accountId?: string;
+    }): Promise<Array<{
+        blob: Blob | null;
+        signature: MajikSignature | null;
+        serialized: string | null;
+        handler: string | null;
+        mimeType: string | null;
+        error: Error | null;
+    }>>;
     /**
      * Verify raw bytes or a string against a MajikSignature.
      *
@@ -520,6 +701,34 @@ export declare class MajikMessage {
         handler?: string;
         reason?: string;
     }>;
+    /**
+     * Verify multiple files' embedded signatures against the same signer in
+     * one call.
+     *
+     * Each file is verified independently — a failed verification sets
+     * result.valid = false and populates result.error, it does not throw.
+     *
+     * @example
+     *   const results = await majik.batchVerifyFiles(
+     *     [pdfBlob, wavBlob, mp4Blob],
+     *     { contactId: "contact_abc" },
+     *   );
+     *   const allValid = results.every(r => r.valid);
+     */
+    batchVerifyFiles(files: Array<Blob | {
+        file: Blob;
+        mimeType?: string;
+        expectedSignerId?: string;
+    }>, options?: {
+        contactId?: string;
+        publicKeyBase64?: string;
+        key?: MajikKey;
+        expectedSignerId?: string;
+    }): Promise<Array<VerificationResult & {
+        handler: string | null;
+        mimeType: string | null;
+        error: Error | null;
+    }>>;
     /**
      * Extract the embedded MajikSignature from a file.
      * Returns a fully typed MajikSignature instance, or null if not found.
@@ -568,6 +777,52 @@ export declare class MajikMessage {
      *   // share myKeys with someone so they can verify your signatures
      */
     getSigningPublicKeys(accountId?: string): Promise<MajikSignerPublicKeys>;
+    /**
+     * Re-sign a file blob — strips any existing embedded signature, signs
+     * with the active (or specified) account, and returns the newly signed blob.
+     *
+     * Use after key rotation or when the signing account changes. The returned
+     * blob is the same format as the input — PDF stays PDF, WAV stays WAV.
+     *
+     * Distinct from resignMajikFile() which operates on a MajikFile instance
+     * (the encrypted .mjkb container). This operates on a plain file Blob.
+     *
+     * @example
+     *   const { blob } = await majik.resignFile(oldSignedPdf);
+     *   await r2.put(key, await blob.arrayBuffer());
+     */
+    resignFile(file: Blob, options?: {
+        contentType?: string;
+        timestamp?: string;
+        mimeType?: string;
+        accountId?: string;
+    }): Promise<{
+        blob: Blob;
+        signature: MajikSignature;
+        handler: string;
+        mimeType: string;
+    }>;
+    /**
+     * Extract metadata from a file's embedded signature without verifying it.
+     *
+     * Useful for rendering "Signed by X at Y" in a UI before the user
+     * explicitly triggers a verify step, or for routing to the correct
+     * contact record before calling verifyFile().
+     *
+     * Returns null if the file has no embedded signature or the JSON is
+     * structurally malformed.
+     *
+     * @example
+     *   const info = await majik.getFileSignatureInfo(pdfBlob);
+     *   if (info) {
+     *     const contact = majik.getContactByID(info.signerId);
+     *     console.log(`Signed by ${contact?.meta?.label ?? info.signerId}`);
+     *     console.log(`Format handled by: ${info.handler}`);
+     *   }
+     */
+    getFileSignatureInfo(file: Blob, options?: {
+        mimeType?: string;
+    }): Promise<MajikSignature | null>;
     /**
      * Resolve MajikSignerPublicKeys from whichever signer hint was provided.
      * Returns null if no hint was given (caller should fall back to self-reported keys).

package/dist/majik-message.js

@@ -1038,6 +1038,194 @@ export class MajikMessage {
         file.removeSignature();
         return this.signMajikFile(file, options);
     }
+    // ── Text / Detached Signing ───────────────────────────────────────────────────
+    /**
+     * Convenience alias for signing a plain string.
+     *
+     * Identical to signContent() but accepts only strings — makes call-sites
+     * that deal exclusively with text cleaner (no Uint8Array overload noise).
+     *
+     * @example
+     *   const sig = await majik.signText("Hello world", { contentType: "text/plain" });
+     *   const b64 = sig.serialize(); // store alongside the text
+     */
+    async signText(text, options) {
+        if (!text?.trim())
+            throw new Error("signText: text must be a non-empty string");
+        return this.signContent(text, options);
+    }
+    /**
+     * Sign content and return both the MajikSignature instance and a portable
+     * base64-serialized string in one call.
+     *
+     * The serialized string is safe to store in a database column, embed in a
+     * JSON field, pass in an HTTP header, or encode in a QR code alongside the
+     * original content. Pass it back to verifyDetached() to verify.
+     *
+     * @example — sign a document and store the detached signature
+     *   const { serialized } = await majik.signAndDetach(docBytes, {
+     *     contentType: "application/pdf",
+     *   });
+     *   await db.insert({ doc_id, signature: serialized });
+     *
+     * @example — sign a text message
+     *   const { signature, serialized } = await majik.signAndDetach("Hello!", {
+     *     contentType: "text/plain",
+     *   });
+     */
+    async signAndDetach(content, options) {
+        const signature = await this.signContent(content, options);
+        return { signature, serialized: signature.serialize() };
+    }
+    // ── Text / Detached Verification ──────────────────────────────────────────────
+    /**
+     * Verify a plain string against a MajikSignature.
+     *
+     * Accepts the signature as a MajikSignature instance, a MajikSignatureJSON
+     * object, or a base64-serialized string — whichever form is easiest at the
+     * call-site.
+     *
+     * The signer can be identified by contact ID, raw public key base64, or a
+     * MajikKey instance. If none is provided the public keys embedded in the
+     * signature envelope are used (self-reported — cross-check result.signerId
+     * against a known contact fingerprint before trusting).
+     *
+     * @example
+     *   const result = await majik.verifyText("Hello world", sig, {
+     *     contactId: "contact_abc",
+     *   });
+     *   if (result.valid) console.log("Authentic");
+     */
+    async verifyText(text, signature, options) {
+        if (!text?.trim())
+            throw new Error("verifyText: text must be a non-empty string");
+        const sig = typeof signature === "string"
+            ? MajikSignature.deserialize(signature)
+            : signature;
+        return this.verifyContent(text, sig, options);
+    }
+    /**
+     * Verify content against a base64-serialized detached signature string.
+     *
+     * This is the pair to signAndDetach() — designed for call-sites that retrieve
+     * a stored base64 signature from a database or API and want to verify without
+     * importing MajikSignature themselves.
+     *
+     * The signer can be identified by contact ID, raw public key base64, or a
+     * MajikKey. If none is provided, self-reported keys from the envelope are used
+     * (see security note on verifyContent).
+     *
+     * @example
+     *   const row = await db.findOne({ doc_id });
+     *   const result = await majik.verifyDetached(docBytes, row.signature, {
+     *     contactId: row.signer_contact_id,
+     *   });
+     *   if (result.valid) console.log("Signed by", result.signerId);
+     */
+    async verifyDetached(content, serializedSignature, options) {
+        if (!serializedSignature?.trim()) {
+            throw new Error("verifyDetached: serializedSignature must be a non-empty string");
+        }
+        let sig;
+        try {
+            sig = MajikSignature.deserialize(serializedSignature);
+        }
+        catch {
+            // Fallback: maybe caller passed raw JSON rather than base64
+            try {
+                sig = MajikSignature.fromJSON(serializedSignature);
+            }
+            catch {
+                throw new Error("verifyDetached: could not parse signature — expected a base64 " +
+                    "string from sig.serialize() or a JSON string from sig.toJSON()");
+            }
+        }
+        return this.verifyContent(content, sig, options);
+    }
+    // ── Signature Serialization Helpers ──────────────────────────────────────────
+    /**
+     * Deserialize a base64 signature string into a MajikSignature instance.
+     *
+     * Round-trip partner for MajikSignature.serialize() / sig.toString().
+     * Use when you have a stored base64 string and need to inspect or pass
+     * the instance to another method.
+     *
+     * Throws MajikSignatureSerializationError on malformed input.
+     *
+     * @example
+     *   const sig = majik.deserializeSignature(storedBase64);
+     *   console.log(sig.signerId, sig.timestamp);
+     */
+    deserializeSignature(serialized) {
+        if (!serialized?.trim()) {
+            throw new Error("deserializeSignature: input must be a non-empty string");
+        }
+        return MajikSignature.deserialize(serialized);
+    }
+    /**
+     * Extract lightweight metadata from a base64 or JSON signature string
+     * without performing cryptographic verification.
+     *
+     * Useful for displaying "Signed by X at Y" in a UI before the user
+     * explicitly triggers a verification step.
+     *
+     * Returns null if the string cannot be parsed as a MajikSignature.
+     *
+     * @example
+     *   const meta = majik.getSignatureMetadata(storedSig);
+     *   if (meta) {
+     *     const contact = majik.getContactByID(meta.signerId);
+     *     console.log(`Signed by ${contact?.meta?.label ?? meta.signerId} at ${meta.timestamp}`);
+     *   }
+     */
+    getSignatureMetadata(serialized) {
+        if (!serialized?.trim())
+            return null;
+        try {
+            let sig;
+            try {
+                sig = MajikSignature.deserialize(serialized);
+            }
+            catch {
+                sig = MajikSignature.fromJSON(serialized);
+            }
+            return {
+                signerId: sig.signerId,
+                timestamp: sig.timestamp,
+                contentType: sig.contentType,
+                contentHash: sig.contentHash,
+                version: sig.version,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── Signing Capability Guard ──────────────────────────────────────────────────
+    /**
+     * Check whether an account has signing keys without throwing.
+     *
+     * Use this as a fast boolean guard before showing signing UI or before
+     * calling any sign* method — those methods throw if signing keys are absent,
+     * so checking first lets you degrade gracefully (e.g. hide a "Sign" button).
+     *
+     * Checks the in-memory keystore cache only — the account must be loaded.
+     * Returns false for unknown accounts rather than throwing.
+     *
+     * @example
+     *   if (!majik.hasSigningCapability()) {
+     *     showUpgradePrompt("Re-import your account to enable signing");
+     *     return;
+     *   }
+     *   const sig = await majik.signText(message);
+     */
+    hasSigningCapability(accountId) {
+        const id = accountId ?? this.getActiveAccount()?.id;
+        if (!id)
+            return false;
+        const key = MajikKeyStore.get(id);
+        return key?.hasSigningKeys === true;
+    }
     // ── Envelope Cache ────────────────────────────────────────────────────────
     async listCachedEnvelopes(offset = 0, limit = 50) {
         return this.envelopeCache.listRecent(offset, limit);
@@ -1215,6 +1403,68 @@ export class MajikMessage {
             throw err;
         }
     }
+    /**
+     * Sign multiple file blobs with the active (or specified) account in one call.
+     *
+     * Each file is signed independently — a failure on one does not abort the
+     * others. Check result.error on each item to handle partial failures.
+     *
+     * The hasSigningKeys check is done once upfront before any signing begins,
+     * so the whole batch fails fast if the account can't sign rather than
+     * discovering it mid-batch.
+     *
+     * @example
+     *   const results = await majik.batchSignFiles([
+     *     { file: pdfBlob, contentType: "application/pdf" },
+     *     { file: wavBlob, contentType: "audio/wav" },
+     *     { file: mp4Blob, contentType: "video/mp4" },
+     *   ]);
+     *   for (const r of results) {
+     *     if (r.error) console.error("Failed:", r.error.message);
+     *     else await r2.put(key, await r.blob!.arrayBuffer());
+     *   }
+     */
+    async batchSignFiles(files, options) {
+        const id = options?.accountId ?? this.getActiveAccount()?.id;
+        if (!id)
+            throw new Error("No active account — call setActiveAccount() first");
+        await MajikKeyStore.ensureUnlocked(id);
+        const key = MajikKeyStore.get(id);
+        if (!key)
+            throw new Error(`Account not found in keystore: "${id}"`);
+        if (!key.hasSigningKeys) {
+            throw new Error(`Account "${id}" has no signing keys. ` +
+                `Re-import via importAccountFromMnemonicBackup() to enable signing.`);
+        }
+        return Promise.all(files.map(async ({ file, contentType, timestamp, mimeType }) => {
+            try {
+                const result = await MajikSignature.signFile(file, key, {
+                    contentType,
+                    timestamp,
+                    mimeType,
+                });
+                return {
+                    blob: result.blob,
+                    signature: result.signature,
+                    serialized: result.signature.serialize(),
+                    handler: result.handler,
+                    mimeType: result.mimeType,
+                    error: null,
+                };
+            }
+            catch (err) {
+                this.emit("error", err, { context: "batchSignFiles" });
+                return {
+                    blob: null,
+                    signature: null,
+                    serialized: null,
+                    handler: null,
+                    mimeType: null,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                };
+            }
+        }));
+    }
     // ── Verification ──────────────────────────────────────────────────────────
     /**
      * Verify raw bytes or a string against a MajikSignature.
@@ -1308,6 +1558,82 @@ export class MajikMessage {
             throw err;
         }
     }
+    /**
+     * Verify multiple files' embedded signatures against the same signer in
+     * one call.
+     *
+     * Each file is verified independently — a failed verification sets
+     * result.valid = false and populates result.error, it does not throw.
+     *
+     * @example
+     *   const results = await majik.batchVerifyFiles(
+     *     [pdfBlob, wavBlob, mp4Blob],
+     *     { contactId: "contact_abc" },
+     *   );
+     *   const allValid = results.every(r => r.valid);
+     */
+    async batchVerifyFiles(files, options) {
+        // Resolve public keys once — reused across all files in the batch
+        const publicKeys = await this._resolveSignerPublicKeys(options).catch(() => null);
+        return Promise.all(files.map(async (entry) => {
+            const { file, mimeType, expectedSignerId } = entry instanceof Blob
+                ? {
+                    file: entry,
+                    mimeType: undefined,
+                    expectedSignerId: options?.expectedSignerId,
+                }
+                : {
+                    ...entry,
+                    expectedSignerId: entry.expectedSignerId ?? options?.expectedSignerId,
+                };
+            try {
+                let result;
+                if (publicKeys) {
+                    result = await MajikSignature.verifyFile(file, publicKeys, {
+                        mimeType,
+                        expectedSignerId,
+                    });
+                }
+                else {
+                    // No signer hint — use self-reported keys from each file's envelope
+                    const extracted = await MajikSignature.extractFrom(file, {
+                        mimeType,
+                    });
+                    if (!extracted) {
+                        return {
+                            valid: false,
+                            signerId: "",
+                            contentHash: "",
+                            timestamp: new Date().toISOString(),
+                            reason: "No embedded signature found",
+                            handler: null,
+                            mimeType: mimeType ?? null,
+                            error: null,
+                        };
+                    }
+                    result = await MajikSignature.verifyFile(file, extracted.extractPublicKeys(), { mimeType, expectedSignerId });
+                }
+                return {
+                    ...result,
+                    handler: result.handler ?? null,
+                    mimeType: mimeType ?? null,
+                    error: null,
+                };
+            }
+            catch (err) {
+                this.emit("error", err, { context: "batchVerifyFiles" });
+                return {
+                    valid: false,
+                    signerId: "",
+                    contentHash: "",
+                    timestamp: new Date().toISOString(),
+                    handler: null,
+                    mimeType: mimeType ?? null,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                };
+            }
+        }));
+    }
     // ── Signature Utilities ───────────────────────────────────────────────────
     /**
      * Extract the embedded MajikSignature from a file.
@@ -1387,6 +1713,52 @@ export class MajikMessage {
         }
         return MajikSignature.publicKeysFromMajikKey(key);
     }
+    /**
+     * Re-sign a file blob — strips any existing embedded signature, signs
+     * with the active (or specified) account, and returns the newly signed blob.
+     *
+     * Use after key rotation or when the signing account changes. The returned
+     * blob is the same format as the input — PDF stays PDF, WAV stays WAV.
+     *
+     * Distinct from resignMajikFile() which operates on a MajikFile instance
+     * (the encrypted .mjkb container). This operates on a plain file Blob.
+     *
+     * @example
+     *   const { blob } = await majik.resignFile(oldSignedPdf);
+     *   await r2.put(key, await blob.arrayBuffer());
+     */
+    async resignFile(file, options) {
+        // signFile already strips before signing — resignFile is a named alias
+        // that makes the caller's intent explicit at the call-site.
+        return this.signFile(file, options);
+    }
+    /**
+     * Extract metadata from a file's embedded signature without verifying it.
+     *
+     * Useful for rendering "Signed by X at Y" in a UI before the user
+     * explicitly triggers a verify step, or for routing to the correct
+     * contact record before calling verifyFile().
+     *
+     * Returns null if the file has no embedded signature or the JSON is
+     * structurally malformed.
+     *
+     * @example
+     *   const info = await majik.getFileSignatureInfo(pdfBlob);
+     *   if (info) {
+     *     const contact = majik.getContactByID(info.signerId);
+     *     console.log(`Signed by ${contact?.meta?.label ?? info.signerId}`);
+     *     console.log(`Format handled by: ${info.handler}`);
+     *   }
+     */
+    async getFileSignatureInfo(file, options) {
+        try {
+            return MajikSignature.extractFrom(file, options);
+        }
+        catch (err) {
+            this.emit("error", err, { context: "getFileSignatureInfo" });
+            throw err;
+        }
+    }
     // ── Private: Signer resolution ────────────────────────────────────────────
     /**
      * Resolve MajikSignerPublicKeys from whichever signer hint was provided.
@@ -1626,6 +1998,12 @@ export class MajikMessage {
             catch {
                 /* ignore */
             }
+            try {
+                await MajikKeyStore.deleteAll();
+            }
+            catch {
+                /* ignore */
+            }
             this.pinHash = null;
             this.id = arrayToBase64(randomBytes(32));
             try {

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.5",
+  "version": "0.2.8",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",
@@ -81,9 +81,9 @@
   "dependencies": {
     "@bokuweb/zstd-wasm": "^0.0.27",
     "@majikah/majik-envelope": "^0.0.1",
-    "@majikah/majik-file": "^0.0.17",
-    "@majikah/majik-key": "^0.2.0",
-    "@majikah/majik-signature": "^0.0.3",
+    "@majikah/majik-file": "^0.0.19",
+    "@majikah/majik-key": "^0.2.1",
+    "@majikah/majik-signature": "^0.0.6",
     "@noble/hashes": "^2.0.1",
     "@noble/post-quantum": "^0.5.4",
     "@scure/bip39": "^1.6.0",