@majikah/majik-signature 0.2.3 → 0.2.5

package/dist/core/constants.d.ts

@@ -59,3 +59,24 @@ export declare const MAJIK_TIMESTAMP_VERSION: 1;
 export declare const MAJIK_TSA_DOMAIN: "majikah-tsa-v-1:";
 export declare const MAJIK_NOTARY_VERSION: 1;
 export declare const MAJIK_NOTARY_MEMO_DOMAIN: "majik-notary-v-1:";
+export declare const MJKSIG_MAGIC: number[];
+export declare const MJKSIG_MAGIC_LEN: number;
+export declare const MJKSIG_VERSION = 1;
+export declare const MJKSIG_SUPPORTED_VERSIONS: readonly [1];
+export declare const MJKSIG_HEADER_LEN: number;
+/**
+ * Proposed IANA media type / conventional file extension for this format.
+ * Referenced here so both live in one place ahead of registration —
+ * update if/when the registration settles on different values.
+ */
+export declare const MJKSIG_MEDIA_TYPE: "application/vnd.majikah.mjksig";
+export declare const MJKSIG_FILE_EXTENSION: ".mjksig";
+export declare const MJKSMAP_MAGIC: number[];
+export declare const MJKSMAP_MAGIC_LEN: number;
+export declare const MJKSMAP_VERSION = 1;
+export declare const MJKSMAP_SUPPORTED_VERSIONS: readonly [1];
+export declare const MJKSMAP_HEADER_LEN: number;
+export declare const MJKSMAP_MEDIA_TYPE = "application/vnd.majikah.mjksmap";
+export declare const MJKSMAP_FILE_EXTENSION = ".mjksmap";
+/** Conventional name/location when packaged in a signed batch zip. */
+export declare const MJKSMAP_DEFAULT_FILENAME = "signatures.mjksmap";

package/dist/core/constants.js

@@ -58,3 +58,37 @@ export const MAJIK_TIMESTAMP_VERSION = 1;
 export const MAJIK_TSA_DOMAIN = `majikah-tsa-v-${MAJIK_TIMESTAMP_VERSION}:`;
 export const MAJIK_NOTARY_VERSION = 1;
 export const MAJIK_NOTARY_MEMO_DOMAIN = `majik-notary-v-${MAJIK_NOTARY_VERSION}:`;
+// ─── MJKSIG binary format ───────────────────────────────────────────────────
+//
+// Layout: [magic(6)][version(1)][reserved(1)][payloadLen(4, BE u32)][payload JSON]
+// Header length is fixed at 12 bytes regardless of version — only the
+// payload shape may change between versions, never the header layout.
+// This lets fromMJKSIG() always locate and validate the header before it
+// needs to know anything about the payload's internal shape.
+export const MJKSIG_MAGIC = [0x4d, 0x4a, 0x4b, 0x53, 0x49, 0x47]; // "MJKSIG"
+export const MJKSIG_MAGIC_LEN = MJKSIG_MAGIC.length;
+export const MJKSIG_VERSION = 0x01;
+export const MJKSIG_SUPPORTED_VERSIONS = [MJKSIG_VERSION];
+export const MJKSIG_HEADER_LEN = MJKSIG_MAGIC_LEN + 1 + 1 + 4; // 12
+/**
+ * Proposed IANA media type / conventional file extension for this format.
+ * Referenced here so both live in one place ahead of registration —
+ * update if/when the registration settles on different values.
+ */
+export const MJKSIG_MEDIA_TYPE = "application/vnd.majikah.mjksig";
+export const MJKSIG_FILE_EXTENSION = ".mjksig";
+// ─── MJKSMAP binary format ───────────────────────────────────────────────────
+//
+// Layout: [magic(7)][version(1)][reserved(1)][payloadLen(4, BE u32)][payload JSON]
+// A single manifest file mapping every file in a batch/zip to its detached
+// MajikSignatureEnvelope — one file to track instead of N loose .mjksig files.
+// Header layout mirrors MJKSIG deliberately; only the magic differs.
+export const MJKSMAP_MAGIC = [0x4d, 0x4a, 0x4b, 0x53, 0x4d, 0x41, 0x50]; // "MJKSMAP"
+export const MJKSMAP_MAGIC_LEN = MJKSMAP_MAGIC.length;
+export const MJKSMAP_VERSION = 0x01;
+export const MJKSMAP_SUPPORTED_VERSIONS = [MJKSMAP_VERSION];
+export const MJKSMAP_HEADER_LEN = MJKSMAP_MAGIC_LEN + 1 + 1 + 4; // 13
+export const MJKSMAP_MEDIA_TYPE = "application/vnd.majikah.mjksmap";
+export const MJKSMAP_FILE_EXTENSION = ".mjksmap";
+/** Conventional name/location when packaged in a signed batch zip. */
+export const MJKSMAP_DEFAULT_FILENAME = "signatures.mjksmap";

package/dist/core/embed/majik-embed.d.ts

@@ -21,12 +21,19 @@
  * extract/strip → delegate to the envelope class → re-embed.
  */
 import type { MajikKey } from "@majikah/majik-key";
-import type { EmbedOptions, EmbedResult, EnvelopeInfo, ExpectedSigner, ExtractOptions, ExtractResult, MajikSignatureEnvelopeJSON, MajikSignatureJSON, MajikSignerPublicKeys, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignOptions, VerificationResult } from "../../core/types";
+import type { BatchFileInput, BatchSignOptions, BatchSignResult, BatchVerifyInput, BatchVerifyOptions, BatchVerifySummary, EmbedOptions, EmbedResult, EnvelopeInfo, ExpectedSigner, ExtractOptions, ExtractResult, FileVerifyResult, MajikSignatureEnvelopeJSON, MajikSignatureJSON, MajikSignerPublicKeys, MajikTimestamp, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignOptions, VerificationResult } from "../../core/types";
 import { MajikSignatureEnvelope } from "../../core/envelope";
 import { FormatHandlerRegistry } from "./registry";
 import { MajikChainAnchor } from "../../anchor/types";
+import { MajikSignatureMap } from "../mjksmap";
 export interface MajikSignatureAdapter {
     toJSON(): MajikSignatureJSON;
+    /**
+     * Optional — attach a TSA timestamp to this signature. Present because
+     * MajikSignature implements it; declared optional here so any future
+     * adapter that doesn't support TSA still satisfies this interface.
+     */
+    addTSA?(tsa: MajikTimestamp): void;
 }
 export interface MajikSignatureStaticAdapter {
     sign(content: Uint8Array | string, key: MajikKey, options?: SignOptions & {
@@ -68,20 +75,59 @@ export declare class MajikSignatureEmbed {
         envelope: MajikSignatureEnvelope;
     }>;
     /**
-     * Sign a file and return the envelope detached.
-     * Same flow as signAndEmbed(), minus the final embed step.
+     * Sign a file and return the envelope detached, along with the specific
+     * signature just produced.
+     *
+     * If options.tsa is provided, it's attached to this signer's signature
+     * via addTSA() immediately after signing and before it's upserted into
+     * the envelope — addTSA() itself validates that the TSA's digest matches
+     * this content's hash and that the TSA's own signature verifies, so no
+     * duplicate validation is needed here. If the adapter doesn't support
+     * addTSA (i.e. MajikSig.addTSA is undefined), a TSA option is a hard
+     * error rather than a silent no-op — attaching a timestamp is something
+     * the caller explicitly asked for, so failing to do it must be loud.
+     *
+     * Returns `signature` — the most recent signature produced by this call
+     * (with the TSA attached, if one was provided) — in addition to the full
+     * `envelope`, so callers don't have to re-extract it via
+     * envelope.findSignature(key.fingerprint) themselves.
      */
-    static signDetached(file: Blob, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: EmbedOptions & {
+    static signDetached<T extends MajikSignatureAdapter = MajikSignatureAdapter>(file: Blob, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: EmbedOptions & {
         contentType?: string;
         timestamp?: string;
         expectedSigners?: ExpectedSigner[];
-        existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON;
+        existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob;
+        tsa?: MajikTimestamp;
     }, debug?: boolean): Promise<{
         blob: Blob;
         envelope: MajikSignatureEnvelope;
+        signature: T;
         handler: string;
         mimeType: string;
     }>;
+    /**
+     * Sign a batch of files (folder or zip contents) as detached envelopes,
+     * packaged either as one MajikSignatureMap (default) or as separate
+     * .mjksig Blobs per file.
+     *
+     * Reuses signDetached() per file — no duplicated crypto path. The only
+     * new logic here is path-uniqueness validation and result packaging.
+     */
+    static signBatchDetached(files: BatchFileInput[], key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: BatchSignOptions, debug?: boolean): Promise<BatchSignResult>;
+    /**
+     * Sign one file detached and extract the contentHash this signer produced
+     * for it — needed to populate the map entry without re-hashing separately.
+     */
+    private static _signOneDetached;
+    /**
+     * Validate the batch before touching any crypto: non-empty, every file has
+     * a non-empty path, and no two files share a path. Duplicate paths would
+     * otherwise silently overwrite each other's map entry via withEntry()'s
+     * replace-on-match semantics — catching it here means the failure is
+     * "your batch has a duplicate path" up front, not a mysteriously missing
+     * entry discovered later.
+     */
+    private static _assertValidBatch;
     /**
      * Extract the envelope from a file as a MajikSignatureEnvelope instance.
      * Returns null if no signature is found.
@@ -98,16 +144,40 @@ export declare class MajikSignatureEmbed {
         expectedSignerId?: string;
     }, debug?: boolean): Promise<VerificationResult[]>;
     /**
-     * Verify a file against a provided, detached envelope (instance or JSON).
+     * Verify a file against a provided, detached envelope (instance, blob or JSON).
      * Still strips the file in case it also contains an embedded envelope,
      * ensuring verification runs against the clean original bytes.
      */
-    static verifyDetached(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON, publicKeys: MajikSignerPublicKeys, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
+    static verifyDetached(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob, publicKeys: MajikSignerPublicKeys, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
         expectedSignerId?: string;
     }, debug?: boolean): Promise<VerificationResult[]>;
-    static verifyDetachedWithKey(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
+    static verifyDetachedWithKey(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
         expectedSignerId?: string;
     }, debug?: boolean): Promise<VerificationResult[]>;
+    /**
+     * Verify a batch of extracted files against a MajikSignatureMap.
+     *
+     * For each file: resolve against the map (tolerating relocation — a file
+     * moved or renamed after signing is still found and verified by content,
+     * not just by its original path), then run the normal signature
+     * verification via the envelope stored in that entry. Never throws
+     * per-file — every outcome (missing, tampered, relocated-but-valid,
+     * invalid, verified) is reported in the returned array, so a caller can
+     * render a full per-file status table in one pass instead of catching
+     * exceptions.
+     *
+     * Set options.requireAllPresent to escalate a missing file to a thrown
+     * error instead — useful when the caller expects a closed, complete set
+     * (e.g. "this zip must contain everything the map lists").
+     */
+    static verifyFilesFromMjksMap(map: MajikSignatureMap, files: BatchVerifyInput[], publicKeys: MajikSignerPublicKeys, MajikSig: MajikSignatureStaticAdapter, options?: BatchVerifyOptions, debug?: boolean): Promise<FileVerifyResult[]>;
+    /** Convenience overload — resolves public keys from a MajikKey. */
+    static verifyFilesFromMjksMapWithKey(map: MajikSignatureMap, files: BatchVerifyInput[], key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: BatchVerifyOptions, debug?: boolean): Promise<FileVerifyResult[]>;
+    /**
+     * Summarize a batch verification result — one glance at pass/fail counts
+     * without the caller re-deriving it from the array each time.
+     */
+    static summarizeBatchVerification(results: FileVerifyResult[]): BatchVerifySummary;
     /**
      * Seal a multi-sig envelope, preventing any further signatures.
      * Issuer-only / already-sealed checks are enforced by envelope.withSeal().

package/dist/core/embed/majik-embed.js

@@ -35,7 +35,8 @@ import { OfficeHandler } from "./handlers/office";
 import { TextHandler } from "./handlers/text";
 import { FallbackHandler } from "./fallback";
 import { bytesToBase64, hashContent } from "../hash";
-import { MajikSignatureError } from "../errors";
+import { MajikSignatureError, MajikSignatureValidationError } from "../errors";
+import { MajikSignatureMap } from "../mjksmap";
 // ─── Registry ─────────────────────────────────────────────────────────────────
 const DEFAULT_REGISTRY = new FormatHandlerRegistry()
     .register(new PdfHandler())
@@ -128,14 +129,27 @@ export class MajikSignatureEmbed {
     }
     // ── signDetached ───────────────────────────────────────────────────────────
     /**
-     * Sign a file and return the envelope detached.
-     * Same flow as signAndEmbed(), minus the final embed step.
+     * Sign a file and return the envelope detached, along with the specific
+     * signature just produced.
+     *
+     * If options.tsa is provided, it's attached to this signer's signature
+     * via addTSA() immediately after signing and before it's upserted into
+     * the envelope — addTSA() itself validates that the TSA's digest matches
+     * this content's hash and that the TSA's own signature verifies, so no
+     * duplicate validation is needed here. If the adapter doesn't support
+     * addTSA (i.e. MajikSig.addTSA is undefined), a TSA option is a hard
+     * error rather than a silent no-op — attaching a timestamp is something
+     * the caller explicitly asked for, so failing to do it must be loud.
+     *
+     * Returns `signature` — the most recent signature produced by this call
+     * (with the TSA attached, if one was provided) — in addition to the full
+     * `envelope`, so callers don't have to re-extract it via
+     * envelope.findSignature(key.fingerprint) themselves.
      */
     static async signDetached(file, key, MajikSig, options, debug = false) {
         const { bytes, mimeType, handler } = await MajikSignatureEmbed._prepare(file, options);
-        // ── Resolve the working envelope ─────────────────────────────────────────
         const envelope = options?.existingEnvelope
-            ? MajikSignatureEnvelope.from(options.existingEnvelope)
+            ? await MajikSignatureEnvelope.from(options.existingEnvelope)
             : await MajikSignatureEmbed._readEnvelope(handler, bytes);
         envelope.assertCanSign(key);
         const originalBytes = await handler.strip(bytes);
@@ -150,6 +164,16 @@ export class MajikSignatureEmbed {
                 ? { allowlistHash: allowlistHashValue }
                 : {}),
         });
+        // ── Attach TSA, if provided ──────────────────────────────────────────────
+        // Must happen before toJSON()/upsert — the envelope needs the signature
+        // WITH its tsa field already set, not a bare signature followed by a
+        // separate mutation the caller has to remember to do.
+        if (options?.tsa) {
+            if (typeof signature.addTSA !== "function") {
+                throw new MajikSignatureError("options.tsa was provided, but the given MajikSig adapter does not support TSA attachment (addTSA is not implemented).");
+            }
+            signature.addTSA(options.tsa);
+        }
         const establishingAllowlist = envelope.isFirstSigner() && !!options?.expectedSigners?.length;
         const envelopeWithAllowlist = establishingAllowlist
             ? envelope.withAllowlist(options.expectedSigners, key.fingerprint)
@@ -157,7 +181,102 @@ export class MajikSignatureEmbed {
         const nextEnvelope = envelopeWithAllowlist.withSignature(signature.toJSON());
         // ── Return DETACHED (no embedding) ───────────────────────────────────────
         const blob = bytesToBlob(originalBytes, mimeType);
-        return { blob, handler: handler.name, mimeType, envelope: nextEnvelope };
+        return {
+            blob,
+            handler: handler.name,
+            mimeType,
+            envelope: nextEnvelope,
+            signature: signature,
+        };
+    }
+    // ── signBatchDetached ────────────────────────────────────────────────────────
+    /**
+     * Sign a batch of files (folder or zip contents) as detached envelopes,
+     * packaged either as one MajikSignatureMap (default) or as separate
+     * .mjksig Blobs per file.
+     *
+     * Reuses signDetached() per file — no duplicated crypto path. The only
+     * new logic here is path-uniqueness validation and result packaging.
+     */
+    static async signBatchDetached(files, key, MajikSig, options, debug = false) {
+        MajikSignatureEmbed._assertValidBatch(files);
+        const mode = options?.mode ?? "map";
+        const continueOnError = options?.continueOnError ?? false;
+        const failures = [];
+        let map = mode === "map" ? MajikSignatureMap.empty() : undefined;
+        const signatures = [];
+        for (const file of files) {
+            try {
+                const { envelope, contentHash } = await MajikSignatureEmbed._signOneDetached(file, key, MajikSig, options, debug);
+                if (mode === "map") {
+                    map = map.withEntry({
+                        path: file.path,
+                        contentHash,
+                        size: file.blob.size,
+                        mimeType: file.blob.type || undefined,
+                        envelope: envelope.toJSON(),
+                    });
+                }
+                else {
+                    signatures.push({ path: file.path, blob: envelope.toMJKSIG() });
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (!continueOnError) {
+                    throw err instanceof MajikSignatureError
+                        ? err
+                        : new MajikSignatureError(`Batch signing failed on "${file.path}": ${message}`, err);
+                }
+                failures.push({ path: file.path, error: message });
+            }
+        }
+        return mode === "map"
+            ? { mode: "map", map: map, mapBlob: map.toMJKSMAP(), failures }
+            : { mode: "separate", signatures, failures };
+    }
+    // ── Private batch helpers ───────────────────────────────────────────────────
+    /**
+     * Sign one file detached and extract the contentHash this signer produced
+     * for it — needed to populate the map entry without re-hashing separately.
+     */
+    static async _signOneDetached(file, key, MajikSig, options, debug) {
+        const { envelope } = await MajikSignatureEmbed.signDetached(file.blob, key, MajikSig, {
+            contentType: options?.contentType,
+            timestamp: options?.timestamp,
+            expectedSigners: options?.expectedSigners,
+        }, debug);
+        const sig = envelope.findSignature(key.fingerprint);
+        if (!sig) {
+            // Should be unreachable — signDetached() always upserts this signer's
+            // entry — but fail loudly rather than silently omitting the file from
+            // the map if signDetached's contract is ever violated.
+            throw new MajikSignatureError(`Internal error: no signature found for this signer after signing "${file.path}"`);
+        }
+        return { envelope, contentHash: sig.contentHash };
+    }
+    /**
+     * Validate the batch before touching any crypto: non-empty, every file has
+     * a non-empty path, and no two files share a path. Duplicate paths would
+     * otherwise silently overwrite each other's map entry via withEntry()'s
+     * replace-on-match semantics — catching it here means the failure is
+     * "your batch has a duplicate path" up front, not a mysteriously missing
+     * entry discovered later.
+     */
+    static _assertValidBatch(files) {
+        if (!files || files.length === 0) {
+            throw new MajikSignatureValidationError("Batch must contain at least one file.", "files");
+        }
+        const seen = new Set();
+        for (const file of files) {
+            if (!file.path || !file.path.trim()) {
+                throw new MajikSignatureValidationError("Every batch file must have a non-empty path.", "path");
+            }
+            if (seen.has(file.path)) {
+                throw new MajikSignatureValidationError(`Duplicate path in batch: "${file.path}"`, "path");
+            }
+            seen.add(file.path);
+        }
     }
     // ── extract ────────────────────────────────────────────────────────────────
     /**
@@ -218,13 +337,13 @@ export class MajikSignatureEmbed {
     }
     // ── verifyDetached ─────────────────────────────────────────────────────────
     /**
-     * Verify a file against a provided, detached envelope (instance or JSON).
+     * Verify a file against a provided, detached envelope (instance, blob or JSON).
      * Still strips the file in case it also contains an embedded envelope,
      * ensuring verification runs against the clean original bytes.
      */
     static async verifyDetached(file, envelopeInput, publicKeys, MajikSig, options, debug = false) {
         const { bytes, handler } = await MajikSignatureEmbed._prepare(file, options);
-        const envelope = MajikSignatureEnvelope.from(envelopeInput);
+        const envelope = await MajikSignatureEnvelope.from(envelopeInput);
         const originalBytes = await handler.strip(bytes);
         if (debug) {
             console.log("verifyDetached — original bytes hash:", bytesToBase64(hashContent(originalBytes)));
@@ -246,6 +365,114 @@ export class MajikSignatureEmbed {
         const publicKeys = MajikSig.publicKeysFromMajikKey(key);
         return MajikSignatureEmbed.verifyDetached(file, envelopeInput, publicKeys, MajikSig, options, debug);
     }
+    // ── verifyFilesFromMjksMap ───────────────────────────────────────────────────
+    /**
+     * Verify a batch of extracted files against a MajikSignatureMap.
+     *
+     * For each file: resolve against the map (tolerating relocation — a file
+     * moved or renamed after signing is still found and verified by content,
+     * not just by its original path), then run the normal signature
+     * verification via the envelope stored in that entry. Never throws
+     * per-file — every outcome (missing, tampered, relocated-but-valid,
+     * invalid, verified) is reported in the returned array, so a caller can
+     * render a full per-file status table in one pass instead of catching
+     * exceptions.
+     *
+     * Set options.requireAllPresent to escalate a missing file to a thrown
+     * error instead — useful when the caller expects a closed, complete set
+     * (e.g. "this zip must contain everything the map lists").
+     */
+    static async verifyFilesFromMjksMap(map, files, publicKeys, MajikSig, options, debug = false) {
+        const results = [];
+        for (const file of files) {
+            const resolved = await map.resolveEntry(file.path, file.blob);
+            if (resolved.status === "not_found") {
+                if (options?.requireAllPresent) {
+                    throw new MajikSignatureError(`File "${file.path}" was not found in the signature map.`);
+                }
+                results.push({
+                    path: file.path,
+                    status: "not_in_map",
+                    reason: `No signature entry found for "${file.path}" (checked by path and by content).`,
+                });
+                continue;
+            }
+            if (resolved.status === "path_tampered") {
+                results.push({
+                    path: file.path,
+                    status: "tampered",
+                    reason: "File content no longer matches what was signed — it may have been modified after signing.",
+                });
+                continue;
+            }
+            // At this point status is "path_match" or "relocated" — both have a
+            // confirmed content match against resolved.entry, so verification
+            // proceeds identically. Only the reported metadata differs.
+            const originalBytes = new Uint8Array(await file.blob.arrayBuffer());
+            if (debug) {
+                console.log(`verifyFilesFromMjksMap — "${file.path}" bytes hash:`, bytesToBase64(hashContent(originalBytes)));
+            }
+            const envelope = MajikSignatureEnvelope.fromJSON(resolved.entry.envelope);
+            const integrity = envelope.verifyAllowlistIntegrity();
+            const relocatedFrom = resolved.status === "relocated" ? resolved.originalPath : undefined;
+            if (!integrity.valid) {
+                results.push({
+                    path: file.path,
+                    status: "invalid",
+                    reason: integrity.reason,
+                    ...(relocatedFrom ? { relocatedFrom } : {}),
+                });
+                continue;
+            }
+            const verifyResults = MajikSignatureEmbed._verifySignatures(envelope, originalBytes, publicKeys, MajikSig, "mjksmap", options?.expectedSignerId);
+            const allValid = verifyResults.every((r) => r.valid);
+            results.push({
+                path: file.path,
+                status: allValid ? "verified" : "invalid",
+                results: verifyResults,
+                ...(relocatedFrom ? { relocatedFrom } : {}),
+                ...(relocatedFrom
+                    ? {
+                        reason: allValid
+                            ? `Verified by content match — originally signed as "${relocatedFrom}".`
+                            : undefined,
+                    }
+                    : {}),
+            });
+        }
+        return results;
+    }
+    /** Convenience overload — resolves public keys from a MajikKey. */
+    static async verifyFilesFromMjksMapWithKey(map, files, key, MajikSig, options, debug = false) {
+        const publicKeys = MajikSig.publicKeysFromMajikKey(key);
+        return MajikSignatureEmbed.verifyFilesFromMjksMap(map, files, publicKeys, MajikSig, options, debug);
+    }
+    /**
+     * Summarize a batch verification result — one glance at pass/fail counts
+     * without the caller re-deriving it from the array each time.
+     */
+    static summarizeBatchVerification(results) {
+        const summary = {
+            total: results.length,
+            verified: 0,
+            invalid: 0,
+            tampered: 0,
+            notInMap: 0,
+            allValid: false,
+        };
+        for (const r of results) {
+            if (r.status === "verified")
+                summary.verified++;
+            else if (r.status === "invalid")
+                summary.invalid++;
+            else if (r.status === "tampered")
+                summary.tampered++;
+            else if (r.status === "not_in_map")
+                summary.notInMap++;
+        }
+        summary.allValid = summary.verified === summary.total && summary.total > 0;
+        return summary;
+    }
     // ── seal ───────────────────────────────────────────────────────────────────
     /**
      * Seal a multi-sig envelope, preventing any further signatures.

package/dist/core/envelope.d.ts

@@ -161,6 +161,43 @@ export declare class MajikSignatureEnvelope {
     toJSON(): MajikSignatureEnvelopeJSON;
     serialize(): string;
     static deserialize(base64: string): MajikSignatureEnvelope;
+    /**
+     * Raw MJKSIG bytes, no Blob wrapper. Exposed as a public escape hatch for
+     * non-browser contexts (Node scripts, tests, direct fs writes) where
+     * wrapping in a Blob just to immediately unwrap it again is pure overhead.
+     * toMJKSIG() is the primary API for anything Blob-facing.
+     */
+    toMJKSIGBytes(): Uint8Array;
+    /**
+     * Encode this envelope as an MJKSIG file Blob.
+     * Always writes the current MJKSIG_VERSION — encoding an old payload
+     * shape under an old version tag is not supported; old versions only
+     * ever appear when *reading* pre-existing MJKSIG binaries.
+     */
+    toMJKSIG(): Blob;
+    /**
+     * Decode MJKSIG bytes back into a MajikSignatureEnvelope.
+     * Validates magic bytes, version, and declared payload length before
+     * attempting to parse — a truncated or corrupted buffer fails fast with
+     * a clear reason rather than an obscure JSON.parse error.
+     *
+     * Accepts either a Blob (as produced by toMJKSIG()) or raw Uint8Array
+     * (as produced by toMJKSIGBytes(), or read directly off disk) — mirrors
+     * the same "accept either shape" pattern as from(). Reading a Blob
+     * requires awaiting its bytes, which is why this method is async.
+     */
+    static fromMJKSIG(input: Blob | Uint8Array): Promise<MajikSignatureEnvelope>;
+    /**
+     * Cheap structural sniff — checks magic bytes only, does not parse or
+     * validate the payload. For a Blob, slices only the header bytes rather
+     * than reading the whole file, so this stays cheap even on large inputs.
+     */
+    static isMJKSIG(input: Blob | Uint8Array): Promise<boolean>;
+    /**
+     * Read just the version byte without parsing the payload.
+     * Returns null if the input isn't MJKSIG-shaped at all.
+     */
+    static getMJKSIGVersion(input: Blob | Uint8Array): Promise<number | null>;
     static empty(): MajikSignatureEnvelope;
     /**
      * Parse a raw string or plain object into a MajikSignatureEnvelope.
@@ -174,8 +211,18 @@ export declare class MajikSignatureEnvelope {
      * This is the only place that knows about the legacy on-disk shape.
      */
     static fromJSON(json: MajikSignatureEnvelopeJSON | MajikSignatureJSON | string): MajikSignatureEnvelope;
-    /** Accepts either an instance or its JSON shape — normalizes to an instance. */
-    static from(input: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON): MajikSignatureEnvelope;
+    /**
+     * Accepts an instance, its JSON shape, or MJKSIG bytes/Blob — normalizes to
+     * an instance. This is the single entry point that lets every downstream
+     * caller (verifyDetached, verifyDetachedWithKey, signDetached's
+     * existingEnvelope option) transparently accept a detached envelope
+     * regardless of which form it arrived in.
+     *
+     * Now async: resolving a Blob input requires awaiting its bytes. Every
+     * existing call site is already inside an async method, so this only
+     * costs an added `await` at each call site — no structural changes.
+     */
+    static from(input: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob): Promise<MajikSignatureEnvelope>;
     validate(): void;
     isValid(): boolean;
 }