@majikah/majik-signature 0.2.4 → 0.2.5

package/dist/core/constants.d.ts

@@ -71,3 +71,12 @@ export declare const MJKSIG_HEADER_LEN: number;
  */
 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

@@ -77,3 +77,18 @@ export const MJKSIG_HEADER_LEN = MJKSIG_MAGIC_LEN + 1 + 1 + 4; // 12
  */
 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 | 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.
@@ -108,6 +154,30 @@ export declare class MajikSignatureEmbed {
     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,8 +129,22 @@ 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);
@@ -149,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)
@@ -156,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 ────────────────────────────────────────────────────────────────
     /**
@@ -245,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/mjksmap.d.ts

@@ -0,0 +1,103 @@
+/**
+ * core/mjksmap.ts
+ *
+ * MajikSignatureMap — a single manifest mapping every file in a batch/zip
+ * to its detached MajikSignatureEnvelope.
+ *
+ * Design constraints (same as MajikSignatureEnvelope):
+ *   - Pure/structural only. No crypto — verification is composed by callers
+ *     via MajikSignature.verifyFileDetached() using an entry's envelope.
+ *   - Immutable. withEntry() returns a new instance.
+ *   - Keyed by path, not contentHash — duplicate-content files across a
+ *     batch are legitimate and must not collide. contentHash is retained
+ *     per-entry as an integrity check and as a secondary lookup index.
+ */
+import { MajikSignatureEnvelope } from "./envelope";
+import type { MjksMapEntry, MjksMapFindResult, MjksMapJSON, MjksMapResolveResult } from "./types";
+export declare class MajikSignatureMap {
+    #private;
+    private readonly _version;
+    private readonly _createdAt;
+    private readonly _entries;
+    private readonly _byPath;
+    private readonly _byHash;
+    private constructor();
+    get version(): 1;
+    get createdAt(): string;
+    get entries(): readonly MjksMapEntry[];
+    get size(): number;
+    /**
+     * Resolve a file against the map, tolerating relocation.
+     *
+     * Tries the exact given path first (cheap, no hashing needed for the miss
+     * case... well, actually a match still needs the hash check below). If
+     * that path isn't in the map, falls back to a content-based search — this
+     * is what makes the map resilient to the batch being reorganized, renamed,
+     * or moved to a different folder/device after signing, since none of that
+     * changes a file's content or its signatures.
+     *
+     * "relocated" is reported as its own status rather than folded into
+     * "path_match" — a caller may reasonably want to flag/re-index a file
+     * that moved, even though its signature is still perfectly valid.
+     */
+    resolveEntry(path: string, file: Blob): Promise<MjksMapResolveResult>;
+    /** Raw entry lookup by exact path — no hash verification, no file needed. */
+    getEntry(path: string): MjksMapEntry | undefined;
+    /**
+     * Resolve a specific file's envelope, given its path AND its current bytes.
+     * Recomputes the hash and compares against the stored contentHash — this
+     * is the integrity check that catches "same name, edited after signing."
+     *
+     * Returns { found: false } if no entry exists at that path at all.
+     * Returns { found: true, hashMatches: false } if the entry exists but the
+     * file's current content no longer matches what was signed — the caller
+     * decides whether that's fatal (it usually should be, but this method
+     * doesn't throw so the caller can present a clear message rather than
+     * catching an exception).
+     */
+    findEntry(path: string, file: Blob): Promise<MjksMapFindResult>;
+    /**
+     * Find every entry matching a file's content, regardless of path.
+     * Returns an array (not a single entry) because duplicate-content files
+     * are legitimate — collapsing to one result would silently hide the rest.
+     * Use when the file may have been renamed/relocated after extraction.
+     */
+    findEntriesByHash(file: Blob): Promise<MjksMapEntry[]>;
+    /**
+     * Resolve a specific entry's envelope as a rich MajikSignatureEnvelope
+     * instance (not just the stored JSON) — matches the convention that every
+     * "give me a signature-shaped thing" method in this library returns the
+     * behavior-rich class, not raw wire JSON.
+     * Returns null if no entry exists at that path.
+     */
+    getEnvelope(path: string): MajikSignatureEnvelope | null;
+    /**
+     * All envelopes in the map, each paired with its path, as rich
+     * MajikSignatureEnvelope instances. Useful for bulk operations —
+     * e.g. rendering a signing-status table for an entire extracted batch
+     * without looking up each file individually.
+     */
+    getAllEnvelopes(): {
+        path: string;
+        envelope: MajikSignatureEnvelope;
+    }[];
+    hasEntry(path: string): boolean;
+    /**
+     * Add or replace an entry by path. Path is normalized before storage and
+     * before the uniqueness check, so "docs/a.pdf" and "docs\\a.pdf" collide
+     * as the same key rather than silently duplicating.
+     */
+    withEntry(entry: MjksMapEntry): MajikSignatureMap;
+    withoutEntry(path: string): MajikSignatureMap;
+    toJSON(): MjksMapJSON;
+    toMJKSMAPBytes(): Uint8Array;
+    toMJKSMAP(): Blob;
+    static fromMJKSMAP(input: Blob | Uint8Array): Promise<MajikSignatureMap>;
+    static isMJKSMAP(input: Blob | Uint8Array): Promise<boolean>;
+    static empty(): MajikSignatureMap;
+    static fromJSON(json: MjksMapJSON | string): MajikSignatureMap;
+    /** Accepts an instance, its JSON shape, or MJKSMAP bytes/Blob. */
+    static from(input: MajikSignatureMap | MjksMapJSON | Uint8Array | Blob): Promise<MajikSignatureMap>;
+    validate(): void;
+    isValid(): boolean;
+}

package/dist/core/mjksmap.js

@@ -0,0 +1,371 @@
+/**
+ * core/mjksmap.ts
+ *
+ * MajikSignatureMap — a single manifest mapping every file in a batch/zip
+ * to its detached MajikSignatureEnvelope.
+ *
+ * Design constraints (same as MajikSignatureEnvelope):
+ *   - Pure/structural only. No crypto — verification is composed by callers
+ *     via MajikSignature.verifyFileDetached() using an entry's envelope.
+ *   - Immutable. withEntry() returns a new instance.
+ *   - Keyed by path, not contentHash — duplicate-content files across a
+ *     batch are legitimate and must not collide. contentHash is retained
+ *     per-entry as an integrity check and as a secondary lookup index.
+ */
+import { MajikSignatureSerializationError, MajikSignatureValidationError, } from "./errors";
+import { hashContent, bytesToBase64 } from "./hash";
+import { MajikSignatureEnvelope } from "./envelope";
+import { MJKSMAP_HEADER_LEN, MJKSMAP_MAGIC, MJKSMAP_MAGIC_LEN, MJKSMAP_MEDIA_TYPE, MJKSMAP_SUPPORTED_VERSIONS, MJKSMAP_VERSION, } from "./constants";
+// ─── Path normalization ────────────────────────────────────────────────────────
+/**
+ * Normalize a path for use as a map key: forward slashes, no leading slash,
+ * no drive letters. Same normalization lesson already hit with Tauri
+ * fs:scope globs (backslashes silently fail) — applied here proactively
+ * rather than waiting to hit it again in batch workflows.
+ */
+function normalizePath(path) {
+    let p = path.replace(/\\/g, "/").trim();
+    p = p.replace(/^[a-zA-Z]:/, ""); // strip drive letters (C:, D:, ...)
+    p = p.replace(/^\/+/, ""); // strip leading slashes
+    return p;
+}
+// ─── MajikSignatureMap ─────────────────────────────────────────────────────────
+export class MajikSignatureMap {
+    _version;
+    _createdAt;
+    _entries;
+    // Lazily built, cached lookup indices — never serialized, purely in-memory
+    // acceleration derived from _entries. Rebuilt whenever a new instance is
+    // constructed via #withEntries(), never mutated in place.
+    _byPath;
+    _byHash;
+    constructor(data) {
+        this._version = data.version;
+        this._createdAt = data.createdAt;
+        this._entries = data.entries.map((e) => ({
+            ...e,
+            path: normalizePath(e.path),
+        }));
+        const byPath = new Map();
+        const byHash = new Map();
+        for (const entry of data.entries) {
+            byPath.set(entry.path, entry);
+            const existing = byHash.get(entry.contentHash);
+            if (existing)
+                existing.push(entry);
+            else
+                byHash.set(entry.contentHash, [entry]);
+        }
+        this._byPath = byPath;
+        this._byHash = byHash;
+    }
+    // ── Getters ─────────────────────────────────────────────────────────────────
+    get version() {
+        return this._version;
+    }
+    get createdAt() {
+        return this._createdAt;
+    }
+    get entries() {
+        return this._entries;
+    }
+    get size() {
+        return this._entries.length;
+    }
+    // ── Lookup ─────────────────────────────────────────────────────────────────
+    /**
+     * Resolve a file against the map, tolerating relocation.
+     *
+     * Tries the exact given path first (cheap, no hashing needed for the miss
+     * case... well, actually a match still needs the hash check below). If
+     * that path isn't in the map, falls back to a content-based search — this
+     * is what makes the map resilient to the batch being reorganized, renamed,
+     * or moved to a different folder/device after signing, since none of that
+     * changes a file's content or its signatures.
+     *
+     * "relocated" is reported as its own status rather than folded into
+     * "path_match" — a caller may reasonably want to flag/re-index a file
+     * that moved, even though its signature is still perfectly valid.
+     */
+    async resolveEntry(path, file) {
+        const direct = await this.findEntry(path, file);
+        if (direct.found) {
+            return direct.hashMatches
+                ? { status: "path_match", entry: direct.entry }
+                : { status: "path_tampered", entry: direct.entry };
+        }
+        const byHash = await this.findEntriesByHash(file);
+        if (byHash.length > 0) {
+            // Multiple matches (duplicate-content files) — first is a reasonable
+            // default, but exposing all of them lets the caller disambiguate.
+            return {
+                status: "relocated",
+                entry: byHash[0],
+                originalPath: byHash[0].path,
+            };
+        }
+        return { status: "not_found" };
+    }
+    /** Raw entry lookup by exact path — no hash verification, no file needed. */
+    getEntry(path) {
+        return this._byPath.get(normalizePath(path));
+    }
+    /**
+     * Resolve a specific file's envelope, given its path AND its current bytes.
+     * Recomputes the hash and compares against the stored contentHash — this
+     * is the integrity check that catches "same name, edited after signing."
+     *
+     * Returns { found: false } if no entry exists at that path at all.
+     * Returns { found: true, hashMatches: false } if the entry exists but the
+     * file's current content no longer matches what was signed — the caller
+     * decides whether that's fatal (it usually should be, but this method
+     * doesn't throw so the caller can present a clear message rather than
+     * catching an exception).
+     */
+    async findEntry(path, file) {
+        const entry = this.getEntry(path);
+        if (!entry)
+            return { found: false };
+        const bytes = new Uint8Array(await file.arrayBuffer());
+        const recomputedHash = bytesToBase64(hashContent(bytes));
+        return {
+            found: true,
+            entry,
+            hashMatches: recomputedHash === entry.contentHash,
+        };
+    }
+    /**
+     * Find every entry matching a file's content, regardless of path.
+     * Returns an array (not a single entry) because duplicate-content files
+     * are legitimate — collapsing to one result would silently hide the rest.
+     * Use when the file may have been renamed/relocated after extraction.
+     */
+    async findEntriesByHash(file) {
+        const bytes = new Uint8Array(await file.arrayBuffer());
+        const hash = bytesToBase64(hashContent(bytes));
+        return [...(this._byHash.get(hash) ?? [])];
+    }
+    /**
+     * Resolve a specific entry's envelope as a rich MajikSignatureEnvelope
+     * instance (not just the stored JSON) — matches the convention that every
+     * "give me a signature-shaped thing" method in this library returns the
+     * behavior-rich class, not raw wire JSON.
+     * Returns null if no entry exists at that path.
+     */
+    getEnvelope(path) {
+        const entry = this.getEntry(path);
+        return entry ? MajikSignatureEnvelope.fromJSON(entry.envelope) : null;
+    }
+    /**
+     * All envelopes in the map, each paired with its path, as rich
+     * MajikSignatureEnvelope instances. Useful for bulk operations —
+     * e.g. rendering a signing-status table for an entire extracted batch
+     * without looking up each file individually.
+     */
+    getAllEnvelopes() {
+        return this._entries.map((entry) => ({
+            path: entry.path,
+            envelope: MajikSignatureEnvelope.fromJSON(entry.envelope),
+        }));
+    }
+    hasEntry(path) {
+        return this._byPath.has(normalizePath(path));
+    }
+    // ── Builders (immutable) ─────────────────────────────────────────────────────
+    /**
+     * Add or replace an entry by path. Path is normalized before storage and
+     * before the uniqueness check, so "docs/a.pdf" and "docs\\a.pdf" collide
+     * as the same key rather than silently duplicating.
+     */
+    withEntry(entry) {
+        if (!entry.path || !entry.path.trim()) {
+            throw new MajikSignatureValidationError("Entry must have a non-empty path.", "path");
+        }
+        if (!entry.contentHash || !entry.contentHash.trim()) {
+            throw new MajikSignatureValidationError("Entry must have a non-empty contentHash.", "contentHash");
+        }
+        const normalized = {
+            ...entry,
+            path: normalizePath(entry.path),
+        };
+        const filtered = this._entries.filter((e) => e.path !== normalized.path);
+        return new MajikSignatureMap({
+            version: this._version,
+            createdAt: this._createdAt,
+            entries: [...filtered, normalized],
+        });
+    }
+    withoutEntry(path) {
+        const normalized = normalizePath(path);
+        return new MajikSignatureMap({
+            version: this._version,
+            createdAt: this._createdAt,
+            entries: this._entries.filter((e) => e.path !== normalized),
+        });
+    }
+    // ── Serialization ─────────────────────────────────────────────────────────────
+    toJSON() {
+        return {
+            version: this._version,
+            createdAt: this._createdAt,
+            entries: [...this._entries],
+        };
+    }
+    // ── MJKSMAP binary format ─────────────────────────────────────────────────
+    //
+    // Same rationale as MJKSIG: length-prefixed JSON behind a versioned,
+    // self-identifying header. toMJKSMAP() returns a Blob for direct use in
+    // zip packaging / downloads; toMJKSMAPBytes() is the sync Uint8Array
+    // escape hatch for non-Blob contexts (Node scripts, direct fs writes).
+    toMJKSMAPBytes() {
+        const payloadJson = new TextEncoder().encode(JSON.stringify(this.toJSON()));
+        const out = new Uint8Array(MJKSMAP_HEADER_LEN + payloadJson.length);
+        out.set(MJKSMAP_MAGIC, 0);
+        out[MJKSMAP_MAGIC_LEN] = MJKSMAP_VERSION;
+        out[MJKSMAP_MAGIC_LEN + 1] = 0x00; // reserved — always 0 in v1
+        const lenOffset = MJKSMAP_MAGIC_LEN + 2;
+        out[lenOffset] = (payloadJson.length >>> 24) & 0xff;
+        out[lenOffset + 1] = (payloadJson.length >>> 16) & 0xff;
+        out[lenOffset + 2] = (payloadJson.length >>> 8) & 0xff;
+        out[lenOffset + 3] = payloadJson.length & 0xff;
+        out.set(payloadJson, MJKSMAP_HEADER_LEN);
+        return out;
+    }
+    toMJKSMAP() {
+        const bytes = this.toMJKSMAPBytes();
+        return new Blob([bytes], { type: MJKSMAP_MEDIA_TYPE });
+    }
+    static async fromMJKSMAP(input) {
+        const raw = input instanceof Blob ? new Uint8Array(await input.arrayBuffer()) : input;
+        return MajikSignatureMap.#parseMJKSMAPBytes(raw);
+    }
+    static #parseMJKSMAPBytes(raw) {
+        if (raw.length < MJKSMAP_HEADER_LEN + 1) {
+            throw new MajikSignatureSerializationError("Malformed MJKSMAP: too short to contain a valid header");
+        }
+        for (let i = 0; i < MJKSMAP_MAGIC_LEN; i++) {
+            if (raw[i] !== MJKSMAP_MAGIC[i]) {
+                throw new MajikSignatureSerializationError('Malformed MJKSMAP: missing "MJKSMAP" magic bytes');
+            }
+        }
+        const version = raw[MJKSMAP_MAGIC_LEN];
+        if (!MJKSMAP_SUPPORTED_VERSIONS.includes(version)) {
+            throw new MajikSignatureSerializationError(`Unsupported MJKSMAP version: ${version} (supported: ${MJKSMAP_SUPPORTED_VERSIONS.join(", ")})`);
+        }
+        const lenOffset = MJKSMAP_MAGIC_LEN + 2;
+        const payloadLen = (raw[lenOffset] << 24) |
+            (raw[lenOffset + 1] << 16) |
+            (raw[lenOffset + 2] << 8) |
+            raw[lenOffset + 3];
+        if (payloadLen <= 0) {
+            throw new MajikSignatureSerializationError("Malformed MJKSMAP: invalid payload length");
+        }
+        const payloadStart = MJKSMAP_HEADER_LEN;
+        const payloadEnd = payloadStart + payloadLen;
+        if (payloadEnd > raw.length) {
+            throw new MajikSignatureSerializationError("Malformed MJKSMAP: declared payload length exceeds buffer");
+        }
+        const json = new TextDecoder().decode(raw.slice(payloadStart, payloadEnd));
+        return MajikSignatureMap.fromJSON(json);
+    }
+    static async isMJKSMAP(input) {
+        const header = input instanceof Blob
+            ? new Uint8Array(await input.slice(0, MJKSMAP_MAGIC_LEN).arrayBuffer())
+            : input;
+        if (header.length < MJKSMAP_MAGIC_LEN)
+            return false;
+        for (let i = 0; i < MJKSMAP_MAGIC_LEN; i++) {
+            if (header[i] !== MJKSMAP_MAGIC[i])
+                return false;
+        }
+        return true;
+    }
+    // ── Creation / parsing ───────────────────────────────────────────────────────
+    static empty() {
+        return new MajikSignatureMap({
+            version: MJKSMAP_VERSION,
+            createdAt: new Date().toISOString(),
+            entries: [],
+        });
+    }
+    static fromJSON(json) {
+        let parsed;
+        try {
+            parsed = typeof json === "string" ? JSON.parse(json) : json;
+        }
+        catch (err) {
+            throw new MajikSignatureSerializationError("MJKSMAP payload is not valid JSON", err);
+        }
+        if (parsed === null ||
+            typeof parsed !== "object" ||
+            Array.isArray(parsed)) {
+            throw new MajikSignatureSerializationError("MJKSMAP payload must be a JSON object");
+        }
+        MajikSignatureMap.#validateShape(parsed);
+        return new MajikSignatureMap(parsed);
+    }
+    /** Accepts an instance, its JSON shape, or MJKSMAP bytes/Blob. */
+    static async from(input) {
+        if (input instanceof MajikSignatureMap)
+            return input;
+        if (input instanceof Uint8Array || input instanceof Blob) {
+            return MajikSignatureMap.fromMJKSMAP(input);
+        }
+        return MajikSignatureMap.fromJSON(input);
+    }
+    validate() {
+        MajikSignatureMap.#validateShape(this.toJSON());
+    }
+    isValid() {
+        try {
+            this.validate();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── Private validation ───────────────────────────────────────────────────────
+    static #validateShape(obj) {
+        if (obj.version !== MJKSMAP_VERSION) {
+            throw new MajikSignatureValidationError(`Unsupported MJKSMAP schema version: ${String(obj.version)}`, "version");
+        }
+        if (typeof obj.createdAt !== "string" || !obj.createdAt) {
+            throw new MajikSignatureValidationError("createdAt must be a non-empty ISO 8601 string", "createdAt");
+        }
+        if (!Array.isArray(obj.entries)) {
+            throw new MajikSignatureValidationError("entries must be an array", "entries");
+        }
+        const seenPaths = new Set();
+        for (const [i, entry] of obj.entries.entries()) {
+            MajikSignatureMap.#validateEntry(entry, i);
+            const path = entry.path;
+            if (seenPaths.has(path)) {
+                throw new MajikSignatureValidationError(`Duplicate path in entries: "${path}"`, "path");
+            }
+            seenPaths.add(path);
+        }
+    }
+    static #validateEntry(entry, index) {
+        if (entry === null || typeof entry !== "object") {
+            throw new MajikSignatureValidationError(`entries[${index}] must be an object`, "entries");
+        }
+        const obj = entry;
+        if (typeof obj.path !== "string" || !obj.path.trim()) {
+            throw new MajikSignatureValidationError(`entries[${index}].path must be a non-empty string`, "path");
+        }
+        if (typeof obj.contentHash !== "string" || !obj.contentHash.trim()) {
+            throw new MajikSignatureValidationError(`entries[${index}].contentHash must be a non-empty string`, "contentHash");
+        }
+        if (obj.envelope === null || typeof obj.envelope !== "object") {
+            throw new MajikSignatureValidationError(`entries[${index}].envelope must be an object`, "envelope");
+        }
+        // Delegates to MajikSignatureEnvelope's own validation rather than
+        // duplicating envelope-shape checks here — single source of truth.
+        MajikSignatureEnvelope.fromJSON(obj.envelope);
+    }
+}
+// Freeze static methods
+Object.freeze(MajikSignatureMap);
+// Freeze instance methods
+Object.freeze(MajikSignatureMap.prototype);

package/dist/core/types.d.ts

@@ -2,6 +2,7 @@
  * types.ts
  * Public types for the MajikSignature library.
  */
+import { ISODateString } from "@majikah/majik-key";
 import { MajikChainAnchor } from "../anchor/types";
 import type { ContentType } from "./constants";
 import type { MajikSignatureEnvelope } from "./envelope";
@@ -297,3 +298,116 @@ export interface ExtractResult {
     envelope: MajikSignatureEnvelope;
     handler: string;
 }
+/**
+ * A single file's entry in a MajikSignatureMap.
+ * Keyed by `path` (unique within a batch) — NOT by contentHash alone,
+ * since duplicate-content files (identical boilerplate, empty templates)
+ * are a real case and hash-as-primary-key would silently collide them.
+ */
+export interface MjksMapEntry {
+    /** Relative path within the batch, POSIX-normalized: forward slashes,
+     *  no leading slash, no drive letters. */
+    path: string;
+    /** SHA-256 of the file's original (unsigned) content, base64.
+     *  Used as an integrity check on lookup-by-path, and as the index
+     *  for lookup-by-hash. */
+    contentHash: string;
+    /** Optional cheap-to-show metadata, no need to open the file for it */
+    size?: number;
+    mimeType?: string;
+    /** The full detached envelope for this specific file */
+    envelope: MajikSignatureEnvelopeJSON;
+}
+export interface MjksMapJSON {
+    version: 1;
+    createdAt: ISODateString;
+    entries: MjksMapEntry[];
+}
+export interface MjksMapFindResult {
+    found: boolean;
+    entry?: MjksMapEntry;
+    /** Only meaningful when found === true. False means the file at this
+     *  path was modified after signing — same name, different content. */
+    hashMatches?: boolean;
+}
+export interface BatchFileInput {
+    /** Relative path within the batch — must be unique across the batch. */
+    path: string;
+    blob: Blob;
+}
+export interface BatchSignOptions {
+    contentType?: string;
+    timestamp?: string;
+    expectedSigners?: ExpectedSigner[];
+    /** "map" (default) produces one MajikSignatureMap covering the whole
+     *  batch. "separate" produces one .mjksig Blob per file. */
+    mode?: "map" | "separate";
+    /**
+     * If false (default), the batch aborts on the first file that fails to
+     * sign — signing is security-sensitive, so silent partial failure is
+     * worse than a loud abort. Set true to collect failures and continue,
+     * useful for large batches where a handful of unreadable files
+     * shouldn't block everything else.
+     */
+    continueOnError?: boolean;
+}
+export interface BatchSignFailure {
+    path: string;
+    error: string;
+}
+export type BatchSignResult = {
+    mode: "map";
+    map: import("./mjksmap").MajikSignatureMap;
+    mapBlob: Blob;
+    failures: BatchSignFailure[];
+} | {
+    mode: "separate";
+    signatures: {
+        path: string;
+        blob: Blob;
+    }[];
+    failures: BatchSignFailure[];
+};
+export interface BatchVerifyInput {
+    path: string;
+    blob: Blob;
+}
+export type FileVerifyStatus = "verified" | "invalid" | "tampered" | "not_in_map";
+export interface FileVerifyResult {
+    path: string;
+    status: FileVerifyStatus;
+    /** Present for "verified" / "invalid" / "tampered" — absent for "not_in_map" */
+    results?: VerificationResult[];
+    /** Human-readable summary — always present, safe to show directly in UI */
+    reason?: string;
+    /** Present only when the file was found by content match at a different
+     *  path than requested — i.e. it moved after signing but is still valid. */
+    relocatedFrom?: string;
+}
+export interface BatchVerifyOptions {
+    expectedSignerId?: string;
+    /**
+     * If true, a file with status "not_in_map" is a hard error for the whole
+     * batch call (throws). Default false — missing files are reported per-file
+     * instead, since a batch verify is usually a "tell me what's wrong with
+     * each file" operation, not an all-or-nothing gate.
+     */
+    requireAllPresent?: boolean;
+}
+export interface BatchVerifySummary {
+    total: number;
+    verified: number;
+    invalid: number;
+    tampered: number;
+    notInMap: number;
+    /** True only when every file is "verified" — the one-glance pass/fail check */
+    allValid: boolean;
+}
+export type MjksMapResolveStatus = "path_match" | "path_tampered" | "relocated" | "not_found";
+export interface MjksMapResolveResult {
+    status: MjksMapResolveStatus;
+    entry?: MjksMapEntry;
+    /** Only set when status === "relocated" — where the file now lives
+     *  vs. where the map says it was originally signed. */
+    originalPath?: string;
+}

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from "./core/errors";
 export * from "./core/constants";
 export * from "./core/embed/majik-embed";
 export * from "./core/envelope";
+export * from "./core/mjksmap";
 export type * from "./anchor/types";
 export { buildSigningPayload } from "./core/payload";
 export { hashContent, bytesToBase64, base64ToBytes } from "./core/hash";

package/dist/index.js

@@ -10,6 +10,7 @@ export * from "./core/errors";
 export * from "./core/constants";
 export * from "./core/embed/majik-embed";
 export * from "./core/envelope";
+export * from "./core/mjksmap";
 // ── Low-level utilities (opt-in) ──────────────────────────────────────────────
 // These are exported for consumers who want to build on top of the primitives
 // without going through MajikSignature (e.g. streaming hash pipelines,

package/dist/majik-signature.d.ts

@@ -4,11 +4,12 @@
  *
  */
 import type { MajikKey } from "@majikah/majik-key";
-import type { EnvelopeInfo, ExpectedSigner, MajikSignatureEnvelopeJSON, MajikSignatureJSON, MajikSignerPublicKeys, MajikTimestamp, MajikTSARequest, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignatoryInfo, SignOptions, VerificationResult } from "./core/types";
+import type { BatchFileInput, BatchSignOptions, BatchVerifyInput, BatchVerifyOptions, EnvelopeInfo, ExpectedSigner, FileVerifyResult, MajikSignatureEnvelopeJSON, MajikSignatureJSON, MajikSignerPublicKeys, MajikTimestamp, MajikTSARequest, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignatoryInfo, SignOptions, VerificationResult } from "./core/types";
 import { MajikSignatureEmbed } from "./core/embed/majik-embed";
 import type { ImageVerificationResult, ImageSignOptions, ImageSignatureStub } from "./core/stamp";
 import { MajikChainAnchor, MajikChainAnchorMemo } from "./anchor/types";
 import { MajikSignatureEnvelope } from "./core/envelope";
+import { MajikSignatureMap } from "./core/mjksmap";
 /**
  * Majik Signature
  * ---
@@ -140,10 +141,16 @@ export declare class MajikSignature {
      * into the multi-sig structure, but does NOT embed it back.
      * Useful for external verification workflows where payloads and envelopes travel out-of-band.
      *
+     * Pass options.tsa to attach a Trusted Timestamp to this signature before
+     * it's added to the envelope — the digest-match and TSA-signature checks
+     * happen automatically inside addTSA().
+     *
      * @example
-     *   const { blob, signature } = await MajikSignature.signFileDetached(file, aliceKey, {
-     *     existingEnvelope: outOfBandEnvelope // Optionally pass state from an external source
+     *   const { blob, envelope, signature } = await MajikSignature.signFileDetached(file, aliceKey, {
+     *     existingEnvelope: outOfBandEnvelope, // Optionally pass state from an external source
+     *     tsa: myTsaTimestamp, // Optionally attach a Trusted Timestamp
      *   });
+     *   console.log(signature.hasTSA); // true if tsa was provided and accepted
      */
     static signFileDetached(file: Blob, key: MajikKey, options?: {
         contentType?: string;
@@ -151,7 +158,27 @@ export declare class MajikSignature {
         mimeType?: string;
         expectedSigners?: ExpectedSigner[];
         existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob;
-    }): ReturnType<typeof MajikSignatureEmbed.signDetached>;
+        tsa?: MajikTimestamp;
+    }): ReturnType<typeof MajikSignatureEmbed.signDetached<MajikSignature>>;
+    /**
+     * Sign a batch of files (e.g. a folder or zip's contents) as detached
+     * envelopes. Packaged either as one MajikSignatureMap covering the whole
+     * batch (default — meant to sit at the root of the zip as one .mjksmap),
+     * or as separate .mjksig Blobs per file when options.mode === "separate".
+     *
+     * @example
+     *   const result = await MajikSignature.signBatchDetached(
+     *     [
+     *       { path: "docs/report.pdf", blob: reportBlob },
+     *       { path: "docs/appendix.pdf", blob: appendixBlob },
+     *     ],
+     *     aliceKey,
+     *   );
+     *   if (result.mode === "map") {
+     *     zip.file("signatures.mjksmap", await result.mapBlob.arrayBuffer());
+     *   }
+     */
+    static signBatchDetached(files: BatchFileInput[], key: MajikKey, options?: BatchSignOptions): ReturnType<typeof MajikSignatureEmbed.signBatchDetached>;
     /**
      * Verify a file's embedded signatures.
      * Returns one VerificationResult per signer. Old single-sig files return a single-item array.
@@ -171,6 +198,25 @@ export declare class MajikSignature {
         expectedSignerId?: string;
         mimeType?: string;
     }, debug?: boolean): Promise<VerificationResult[]>;
+    /**
+     * Verify a batch of extracted files against a MajikSignatureMap (loaded via
+     * MajikSignatureMap.fromMJKSMAP()). Reports a per-file status rather than
+     * throwing — a missing, tampered, or invalidly-signed file is a normal
+     * possible outcome to display, not an exceptional one to catch.
+     *
+     * @example
+     *   const map = await MajikSignatureMap.fromMJKSMAP(mjksmapBlob);
+     *   const results = await MajikSignature.verifyFilesFromMjksMap(
+     *     map,
+     *     extractedFiles,
+     *     publicKeys,
+     *   );
+     *   const summary = MajikSignature.summarizeBatchVerification(results);
+     *   if (!summary.allValid) { ... }
+     */
+    static verifyFilesFromMjksMap(map: MajikSignatureMap, files: BatchVerifyInput[], publicKeys: MajikSignerPublicKeys, options?: BatchVerifyOptions, debug?: boolean): Promise<FileVerifyResult[]>;
+    static verifyFilesFromMjksMapWithKey(map: MajikSignatureMap, files: BatchVerifyInput[], key: MajikKey, options?: BatchVerifyOptions, debug?: boolean): Promise<FileVerifyResult[]>;
+    static summarizeBatchVerification(results: FileVerifyResult[]): ReturnType<typeof MajikSignatureEmbed.summarizeBatchVerification>;
     /**
      * Embed this MajikSignature instance into a file.
      * The signature must cover the original file bytes BEFORE embedding.

package/dist/majik-signature.js

@@ -411,14 +411,41 @@ export class MajikSignature {
      * into the multi-sig structure, but does NOT embed it back.
      * Useful for external verification workflows where payloads and envelopes travel out-of-band.
      *
+     * Pass options.tsa to attach a Trusted Timestamp to this signature before
+     * it's added to the envelope — the digest-match and TSA-signature checks
+     * happen automatically inside addTSA().
+     *
      * @example
-     *   const { blob, signature } = await MajikSignature.signFileDetached(file, aliceKey, {
-     *     existingEnvelope: outOfBandEnvelope // Optionally pass state from an external source
+     *   const { blob, envelope, signature } = await MajikSignature.signFileDetached(file, aliceKey, {
+     *     existingEnvelope: outOfBandEnvelope, // Optionally pass state from an external source
+     *     tsa: myTsaTimestamp, // Optionally attach a Trusted Timestamp
      *   });
+     *   console.log(signature.hasTSA); // true if tsa was provided and accepted
      */
     static async signFileDetached(file, key, options) {
         return MajikSignatureEmbed.signDetached(file, key, MajikSignature, options);
     }
+    /**
+     * Sign a batch of files (e.g. a folder or zip's contents) as detached
+     * envelopes. Packaged either as one MajikSignatureMap covering the whole
+     * batch (default — meant to sit at the root of the zip as one .mjksmap),
+     * or as separate .mjksig Blobs per file when options.mode === "separate".
+     *
+     * @example
+     *   const result = await MajikSignature.signBatchDetached(
+     *     [
+     *       { path: "docs/report.pdf", blob: reportBlob },
+     *       { path: "docs/appendix.pdf", blob: appendixBlob },
+     *     ],
+     *     aliceKey,
+     *   );
+     *   if (result.mode === "map") {
+     *     zip.file("signatures.mjksmap", await result.mapBlob.arrayBuffer());
+     *   }
+     */
+    static async signBatchDetached(files, key, options) {
+        return MajikSignatureEmbed.signBatchDetached(files, key, MajikSignature, options);
+    }
     /**
      * Verify a file's embedded signatures.
      * Returns one VerificationResult per signer. Old single-sig files return a single-item array.
@@ -442,6 +469,31 @@ export class MajikSignature {
         }
         return MajikSignatureEmbed.verifyDetached(file, envelope, keyOrPublicKeys, MajikSignature, options, debug);
     }
+    /**
+     * Verify a batch of extracted files against a MajikSignatureMap (loaded via
+     * MajikSignatureMap.fromMJKSMAP()). Reports a per-file status rather than
+     * throwing — a missing, tampered, or invalidly-signed file is a normal
+     * possible outcome to display, not an exceptional one to catch.
+     *
+     * @example
+     *   const map = await MajikSignatureMap.fromMJKSMAP(mjksmapBlob);
+     *   const results = await MajikSignature.verifyFilesFromMjksMap(
+     *     map,
+     *     extractedFiles,
+     *     publicKeys,
+     *   );
+     *   const summary = MajikSignature.summarizeBatchVerification(results);
+     *   if (!summary.allValid) { ... }
+     */
+    static async verifyFilesFromMjksMap(map, files, publicKeys, options, debug = false) {
+        return MajikSignatureEmbed.verifyFilesFromMjksMap(map, files, publicKeys, MajikSignature, options, debug);
+    }
+    static async verifyFilesFromMjksMapWithKey(map, files, key, options, debug = false) {
+        return MajikSignatureEmbed.verifyFilesFromMjksMapWithKey(map, files, key, MajikSignature, options, debug);
+    }
+    static summarizeBatchVerification(results) {
+        return MajikSignatureEmbed.summarizeBatchVerification(results);
+    }
     /**
      * Embed this MajikSignature instance into a file.
      * The signature must cover the original file bytes BEFORE embedding.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@majikah/majik-signature",
   "type": "module",
   "description": "Majik Signature is a hybrid post-quantum content signing and verification library for the Majikah ecosystem. Built on top of Majik Key, it provides tamper-proof, forgery-resistant digital signatures for any content format — using a dual-algorithm architecture that combines classical Ed25519 with post-quantum ML-DSA-87 (FIPS-204).",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",