@majikah/majik-signature 0.2.7 → 0.2.9

package/README.md

@@ -1,11 +1,11 @@
 # Majik Signature
 
 [![Developed by Zelijah](https://img.shields.io/badge/Developed%20by-Zelijah-red?logo=github&logoColor=white)](https://thezelijah.world) ![GitHub Sponsors](https://img.shields.io/github/sponsors/jedlsf?style=plastic&label=Sponsors&link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fjedlsf)
-![npm](https://img.shields.io/npm/v/@majikah/majik-signature) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-signature) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-signature) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+![npm](https://img.shields.io/npm/v/@majikah/majik-signature) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-signature) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-signature) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue) [![Static Badge](https://img.shields.io/badge/IANA-vnd.majikah.mjksig-green)](https://www.iana.org/assignments/media-types/application/vnd.majikah.mjksig)
 
 **Majik Signature** is a hybrid post-quantum content signing and verification library for the Majikah ecosystem. Built on top of [**Majik Key**](https://www.npmjs.com/package/@majikah/majik-key), it produces tamper-evident, forgery-resistant digital signatures for any content — plaintext, JSON, PDFs, audio, video, Office documents, or raw binary — using a dual-algorithm architecture that combines classical **Ed25519** with post-quantum **ML-DSA-87** (FIPS-204).
 
-Beyond signing raw bytes, Majik Signature can **embed signatures directly into a file's native format**. PDFs stay PDFs, WAVs stay WAVs, DOCX files stay editable — the signature travels with the file, no sidecar `.sig` file required. On top of that, it supports **multi-party signing**, **signing allowlists**, **envelope sealing**, and **trusted timestamps (TSA)**.
+Beyond signing raw bytes, Majik Signature can **embed signatures directly into a file's native format**, or produce **detached envelopes** that travel independently of the file — as portable JSON, base64, or a dedicated self-describing binary container (`.mjksig`). It supports **multi-party signing**, **signing allowlists**, **envelope sealing**, **trusted timestamps (TSA)**, **batch/folder signing** via a manifest format (`.mjksmap`), **chronological signing-order verification**, and **blockchain anchor registration**.
 
 ---
 
@@ -19,19 +19,28 @@ Beyond signing raw bytes, Majik Signature can **embed signatures directly into a
 - [Quick Start](#quick-start)
   - [Signing Raw Content](#signing-raw-content)
   - [File Embedding](#file-embedding)
+  - [Detached Signing](#detached-signing)
   - [Multi-Signature Files & Allowlists](#multi-signature-files--allowlists)
   - [Sealing an Envelope](#sealing-an-envelope)
   - [Trusted Timestamps (TSA)](#trusted-timestamps-tsa)
+  - [Batch Signing a Folder](#batch-signing-a-folder)
+  - [Verifying Signing Order](#verifying-signing-order)
+  - [Chain Anchoring](#chain-anchoring)
 - [API Reference](#api-reference)
   - [Content Signing](#content-signing-bytesstrings)
   - [File Embedding](#file-embedding-api)
+  - [Detached Signing & MajikSignatureEnvelope](#detached-signing--majiksignatureenvelope-api)
   - [Multi-Signature & Allowlist](#multi-signature--allowlist-api)
   - [Sealing](#sealing-api)
   - [Trusted Timestamps](#trusted-timestamps-api)
+  - [Batch Signing & MajikSignatureMap](#batch-signing--majiksignaturemap-api)
+  - [Signature Order Verification](#signature-order-verification-api)
+  - [Chain Anchoring API](#chain-anchoring-api)
   - [Image Stamping (Experimental)](#image-stamping-experimental)
   - [Serialization](#serialization)
 - [Supported File Formats](#supported-file-formats)
 - [Signature & Envelope Structure](#signature--envelope-structure)
+- [Binary Container Formats (MJKSIG / MJKSMAP)](#binary-container-formats-mjksig--mjksmap)
 - [Error Handling](#error-handling)
 - [Security Considerations](#security-considerations)
 - [The Majikah Ecosystem](#the-majikah-ecosystem)
@@ -48,8 +57,9 @@ Beyond signing raw bytes, Majik Signature can **embed signatures directly into a
 Most "digital signature" libraries only sign raw bytes and leave you to figure out storage, transport, and file compatibility yourself. Majik Signature is built to be dropped into a real application:
 
 - **Hybrid post-quantum by default** — every signature is Ed25519 + ML-DSA-87, not an opt-in extra.
-- **Signatures live inside the file** — no sidecar files to lose, mismatch, or forget to ship.
-- **Multi-party signing is a first-class concept** — not bolted on. Allowlists, sealing, and issuer semantics are part of the core envelope format.
+- **Signatures live inside the file, or travel detached** — embed directly into the file's native format, or produce a portable envelope (JSON, base64, or the self-describing `.mjksig` binary container) for out-of-band verification workflows.
+- **Multi-party signing is a first-class concept** — not bolted on. Allowlists, sealing, issuer semantics, and chronological order verification are part of the core envelope model.
+- **Batch-aware** — sign or verify an entire folder or zip's contents against a single manifest (`.mjksmap`) instead of tracking one signature file per asset.
 - **Deterministic by design** — the library goes out of its way to guarantee that signing and verifying the same content always produces the same canonical bytes (see [Signature & Envelope Structure](#signature--envelope-structure)).
 - **No native dependencies** — pure TypeScript/WASM-free cryptography, works identically in Node.js, browsers, Tauri, Deno, and Bun.
 
@@ -57,7 +67,6 @@ Most "digital signature" libraries only sign raw bytes and leave you to figure o
 
 ## Security Architecture
 
-
 ```mermaid
 flowchart TD
     A[12/24-word BIP-39 Seed Phrase] --> B[Majik Key]
@@ -67,28 +76,16 @@ flowchart TD
     S --> S1[Ed25519]
     S --> S2[ML-DSA-87]
 
-  
-
     %% Identity branch
     B --> I[Identity]
     I --> I1[BIP-39]
     I --> I2[X25519]
 
-
-
     %% Products (fan-in)
     S1 --> P1[Majik Signature]
     S2 --> P1
-
- 
-    
-
-
-
-
 ```
 
-
 ### 1. Hybrid Dual-Algorithm Signing
 
 Every Majik Signature is produced by **two independent signing algorithms** over the same canonical payload:
@@ -126,7 +123,7 @@ This binding means a valid signature cannot be reused on different content, tran
 
 Content is never embedded in the envelope — only its SHA-256 hash is signed. A 500 MB video signs at the same speed as a 10-byte string, and every content type is supported identically.
 
-### 4. File Embedding Integrity
+### 4. File Embedding & Detachment Integrity
 
 When a signature is embedded into a file, it always covers the **original file bytes before embedding**. Verification strips the embedded envelope before re-hashing, so the round-trip is always:
 
@@ -134,11 +131,13 @@ When a signature is embedded into a file, it always covers the **original file b
 sign(originalBytes) → embed into file → extract → strip → verify(originalBytes)
 ```
 
+The same guarantee applies to **detached** signing: `signFileDetached()` signs the clean, stripped bytes and returns them alongside the envelope — the envelope and the file travel separately, but verification always strips the file first, so an accidentally-still-embedded envelope never double-counts or corrupts the hash.
+
 Re-signing (or re-embedding) the same file is always safe — the existing envelope is stripped before the new one is written, so signatures never stack or corrupt each other.
 
 ### 5. Multi-Party Signing, Allowlists & Sealing
 
-Files don't hold a single signature — they hold a **`MultiSigEnvelope`**: an array of per-signer envelopes, plus optional allowlist and seal metadata.
+Files don't hold a single signature — they hold a **`MultiSigEnvelope`** (modeled at runtime by the `MajikSignatureEnvelope` class): an array of per-signer envelopes, plus optional allowlist, seal, and chain-anchor metadata.
 
 - **Open signing** (default): anyone with a `MajikKey` can add a signature.
 - **Restricted signing**: the first signer may supply an `expectedSigners` allowlist. That allowlist is cryptographically committed to via `allowlistHash` in the issuer's own canonical payload — tampering with the allowlist after the fact breaks the issuer's signature. Non-listed signers are rejected *before* any cryptographic operation runs.
@@ -146,7 +145,11 @@ Files don't hold a single signature — they hold a **`MultiSigEnvelope`**: an a
 
 ### 6. Trusted Timestamps (TSA)
 
-A `MajikSignature` can optionally carry a `MajikTimestamp` — a signature from a timestamp authority over a canonical payload (`"majikah-tsa-v-1:"` domain) binding a digest, a server-generated nonce, and a server-authoritative timestamp. The TSA signature is itself a full Majik Signature (Ed25519 + ML-DSA-87), so it inherits the same hybrid guarantees.
+A `MajikSignature` can optionally carry a `MajikTimestamp` — a signature from a timestamp authority over a canonical payload (`"majikah-tsa-v-1:"` domain) binding a digest, a server-generated nonce, and a server-authoritative timestamp. The TSA signature is itself a full Majik Signature (Ed25519 + ML-DSA-87), so it inherits the same hybrid guarantees. TSA timestamps are also what power *attested* [signing-order verification](#verifying-signing-order) — see below.
+
+### 7. Chain Anchoring
+
+A sealed envelope's seal hash can be committed to an external blockchain (handled by a companion product, e.g. `majik-notary`) and the resulting confirmed anchor registered back into the envelope via `MajikChainAnchor` records. The SDK does not talk to any chain itself — it only builds the canonical memo to anchor (`buildChainAnchorMemo()`) and embeds/reads already-confirmed anchors. Anchoring requires the envelope to already be sealed.
 
 ---
 
@@ -163,10 +166,12 @@ Verification is fully **public** — anyone with the signer's public keys can ve
 - **Content Provenance** — prove that music, art, a document, or a dataset was produced by a specific identity.
 - **File Integrity** — detect any tampering or modification to distributed files.
 - **API Payload Signing** — sign JSON requests/responses for non-repudiation.
-- **Document Authentication** — certify contracts, legal records, or invoices, with support for multiple independent signers and a final seal.
+- **Document Authentication** — certify contracts, legal records, or invoices, with support for multiple independent signers, chronological approval order, and a final seal.
 - **Media Certification** — stamp audio, video, or image files as authentic originals, with the signature embedded directly in the file.
 - **Software Distribution** — sign release artifacts to prove they come from the original author.
 - **Identity-Bound Messaging** — bind signed content to a verifiable identity across the Majikah ecosystem.
+- **Batch Asset Signing** — sign every file in a folder, project export, or zip archive against a single manifest, resilient to files being renamed or relocated afterward.
+- **Approval Workflows** — verify not just *who* signed a contract, but that they signed it in the *required order* (e.g. legal before finance, requester before approver).
 
 ---
 
@@ -176,28 +181,40 @@ Verification is fully **public** — anyone with the signer's public keys can ve
 
 - **Hybrid signatures** — Ed25519 (classical) + ML-DSA-87 (post-quantum, FIPS-204, Category 5); both must verify
 - **Tamper detection** — SHA-256 content hash is bound inside the signed payload; any byte change invalidates both signatures
-- **Domain separation** — distinct prefixes for signing (`majik-signature-v1:`), sealing (`majik-seal-v1:`), and timestamping (`majikah-tsa-v-1:`) prevent cross-protocol signature reuse
+- **Domain separation** — distinct prefixes for signing (`majik-signature-v1:`), sealing (`majik-seal-v1:`), timestamping (`majikah-tsa-v-1:`), and chain anchoring (`majik-notary-v-1:`) prevent cross-protocol signature reuse
 - **Signer & timestamp binding** — both are part of the signed payload; neither can be altered or transferred after signing
 - **No private key for verification** — pure public-key verification, safe to run anywhere
 
 ### Multi-Party Signing
 
-- **Multi-signature envelopes** — any number of independent signers on one file
+- **Multi-signature envelopes** — any number of independent signers on one file, modeled by the immutable `MajikSignatureEnvelope` class
 - **Signing allowlists** — restrict who may sign, enforced before any cryptographic operation
 - **Cryptographically committed allowlists** — tampering with the allowlist invalidates the issuer's signature
 - **Sealing** — the issuer can permanently lock an envelope against further signatures
+- **Chronological order verification** — verify that signers signed in a required sequence, with TSA-attested timestamps preferred over self-reported ones, and a strict mode to reject unexpected extra signers
 - **Status queries** — `getSignatories()`, `getIssuer()`, `getEnvelopeInfo()`, `canSign()` for building signing-status UI without manually walking the envelope
 
+### Detached Signing & Batch Workflows
+
+[![Static Badge](https://img.shields.io/badge/IANA-vnd.majikah.mjksig-green)](https://www.iana.org/assignments/media-types/application/vnd.majikah.mjksig)
+
+- **Detached envelopes** — sign a file and receive the envelope separately, for external verification pipelines where payload and signature travel independently
+- **Self-describing binary containers** — `.mjksig` for a single detached envelope, `.mjksmap` for a manifest covering an entire batch, each with magic bytes, a version header, and a length-prefixed payload
+- **Batch signing** — sign every file in a folder or zip in one call, packaged as one `.mjksmap` manifest or as separate `.mjksig` files per asset
+- **Relocation-tolerant batch verification** — a file renamed or moved after signing is still found and verified by content hash, not just by its original path
+- **Per-file batch verification reporting** — `verified` / `invalid` / `tampered` / `not_in_map` status per file, plus a one-glance summary
+
 ### Content Format Support
 
 - **Plain text, JSON, binary** — `Uint8Array` or `string`
 - **PDF** — signature appended as a spec-compliant binary trailer after the file's `%%EOF`
-- **PNG** — embedded in a `iTXt` metadata chunk
+- **PNG** — embedded in an `iTXt` metadata chunk
 - **WAV** — embedded in a RIFF `LIST INFO` chunk
 - **MP3** — embedded in an ID3v2 `TXXX` frame
-- **MP4, MOV, M4A, M4V** — embedded in the `moov/udta` box
+- **MP4, MOV, M4A, M4V** — embedded in the `moov/udta` box, custom `majk` box type
 - **DOCX, XLSX, PPTX, ODT, ODS, ODP** — embedded as a dedicated entry inside the ZIP container
 - **MKV, WebM** — embedded via a custom Matroska metadata tag
+- **JPEG, FLAC** — native format metadata, same round-trip guarantees as other handlers
 - **HTML, Markdown, JSON, plain text, source code** — embedded as an appended, format-appropriate metadata block
 - **Any other format** — universal binary trailer: `[original bytes][signature JSON][8-byte length][8-byte magic]` — cleanly detectable and strippable regardless of format
 
@@ -206,19 +223,21 @@ See [Supported File Formats](#supported-file-formats) for the full handler table
 ### Developer Experience
 
 - **First-class TypeScript support** — full type definitions for every interface and class
-- **Simple core API** — `sign()` / `verify()` for bytes and strings; `signFile()` / `verifyFile()` for files
+- **Simple core API** — `sign()` / `verify()` for bytes and strings; `signFile()` / `verifyFile()` for embedded files; `signFileDetached()` / `verifyFileDetached()` for detached workflows
 - **One-liner file signing** — `MajikSignature.signFile(blob, key)` signs and embeds in a single call
 - **Format auto-detection** — MIME type and magic-byte sniffing, no manual format hints required in most cases
 - **Idempotent re-signing** — safely re-sign or re-embed any file without accumulating stacked or orphaned envelopes
+- **Immutable envelope model** — `MajikSignatureEnvelope` and `MajikSignatureMap` are both immutable; every mutation returns a new instance
 - **Typed error hierarchy** — precise, catchable error classes instead of generic exceptions
 - **Isomorphic** — Node.js, browsers, Tauri, Deno, and Bun; no native bindings
 
 ### Serialization & Portability
 
-- **JSON envelope** — full `toJSON()` / `fromJSON()` round-trip
+- **JSON envelope** — full `toJSON()` / `fromJSON()` round-trip, at both the signature and envelope level
 - **Base64 serialization** — `serialize()` / `deserialize()` for compact transport (HTTP headers, DB columns, etc.)
 - **File-embedded** — the signature lives inside the file itself, no sidecar files needed
 - **Self-contained** — the envelope includes the signer's public keys, verifiable without a separate key registry
+- **Binary containers** — `.mjksig` and `.mjksmap` for detached envelopes and batch manifests that need to travel or be stored on disk as their own file
 
 ---
 
@@ -303,6 +322,42 @@ const originalBlob = await MajikSignature.stripFrom(signedBlob);
 
 ---
 
+### Detached Signing
+
+Use detached signing when the signature envelope needs to travel independently of the file — for example, storing envelopes in a database while files sit in blob storage, or verification pipelines that never touch the original file storage layer.
+
+```typescript
+import { MajikSignature } from '@majikah/majik-signature';
+
+// Sign — returns the clean file bytes AND the envelope, separately
+const { blob, envelope, signature } = await MajikSignature.signFileDetached(file, aliceKey);
+
+// The envelope can be stored/transported however you like:
+const envelopeJson = envelope.toJSON();
+const envelopeB64 = envelope.serialize();
+const envelopeBinary = envelope.toMJKSIG(); // a portable .mjksig Blob
+
+// Verify later, against the same clean file bytes + the detached envelope
+const results = await MajikSignature.verifyFileDetached(blob, envelope, aliceKey);
+console.log('Valid:', results.every((r) => r.valid));
+
+// Multiple signers can be added to the same detached envelope before it's ever embedded
+const { envelope: envelope2 } = await MajikSignature.signFileDetached(blob, bobKey, {
+  existingEnvelope: envelope, // continue from Alice's envelope
+});
+```
+
+You can attach a Trusted Timestamp to a detached signature in the same call:
+
+```typescript
+const { envelope, signature } = await MajikSignature.signFileDetached(file, aliceKey, {
+  tsa: myTsaTimestamp,
+});
+console.log(signature.hasTSA); // true
+```
+
+---
+
 ### Multi-Signature Files & Allowlists
 
 ```typescript
@@ -385,6 +440,111 @@ console.log('TSA still valid:', signature.verifyTSA().valid);
 
 ---
 
+### Batch Signing a Folder
+
+Sign every file in a folder, project export, or zip's contents in one call, packaged as a single manifest.
+
+```typescript
+import { MajikSignature } from '@majikah/majik-signature';
+
+const result = await MajikSignature.signBatchDetached(
+  [
+    { path: 'docs/report.pdf', blob: reportBlob },
+    { path: 'docs/appendix.pdf', blob: appendixBlob },
+    { path: 'assets/cover.png', blob: coverBlob },
+  ],
+  aliceKey,
+);
+
+if (result.mode === 'map') {
+  // result.map is a MajikSignatureMap instance; result.mapBlob is a ready-to-store .mjksmap Blob
+  zip.file('signatures.mjksmap', await result.mapBlob.arrayBuffer());
+}
+
+// Later — verify an extracted batch against the manifest
+const map = await MajikSignature.getSignatureMapFromMJKSMAP(mapBlob);
+// (or: const map = await MajikSignatureMap.fromMJKSMAP(mapBlob);)
+
+const results = await MajikSignature.verifyFilesFromMjksMap(
+  map,
+  extractedFiles, // { path, blob }[]
+  publicKeys,
+);
+
+const summary = MajikSignature.summarizeBatchVerification(results);
+console.log(`${summary.verified}/${summary.total} verified`);
+
+if (!summary.allValid) {
+  for (const r of results) {
+    if (r.status !== 'verified') console.log(r.path, r.status, r.reason);
+  }
+}
+```
+
+A batch-verified file that was renamed or moved after signing is still resolved correctly — matched by content hash and reported with `relocatedFrom` set to its original path, rather than showing up as missing.
+
+---
+
+### Verifying Signing Order
+
+Beyond confirming *who* signed a file, you can confirm they signed in a required *sequence* — e.g. "Bob must sign before Dave." TSA-attested timestamps are preferred automatically when present; self-reported timestamps are used as a fallback and flagged accordingly.
+
+```typescript
+import { MajikSignature } from '@majikah/majik-signature';
+
+// expectedOrder accepts MajikKey instances and/or ExpectedSigner objects, mixed freely
+const result = await MajikSignature.verifyFileOrder(signedBlob, [bobKey, daveKey]);
+
+if (!result.allExpectedSigned) {
+  console.log('Still pending:', result.pendingSigners);
+} else if (!result.allValid) {
+  console.log('Invalid/tampered signature(s):', result.invalidSigners);
+} else if (!result.orderRespected) {
+  console.log('Signed out of order:', result.violations);
+} else if (result.softTieWarnings.length > 0) {
+  console.log('Valid, but note:', result.reason); // identical timestamps — order indistinguishable
+} else {
+  console.log('Signed in the expected order — all valid.');
+}
+
+if (result.usesUnattestedTimestamp) {
+  console.log('Note: order relied on at least one self-reported (non-TSA) timestamp.');
+}
+
+// Strict mode — fail if anyone outside expectedOrder signed at all
+const strictResult = await MajikSignature.verifyFileOrder(
+  signedBlob,
+  [bobKey, daveKey],
+  { strict: true },
+);
+```
+
+The same check works against a detached envelope via `verifyFileDetachedOrder(file, envelope, expectedOrder, options?)`.
+
+---
+
+### Chain Anchoring
+
+Chain anchoring is a two-step handoff: this SDK prepares and reads anchor data; a separate chain-integration layer (e.g. `majik-notary`) is responsible for actually submitting and confirming the transaction.
+
+```typescript
+import { MajikSignature } from '@majikah/majik-signature';
+
+// 1. File must be sealed first
+const { permitted, reason } = await MajikSignature.canAnchor(sealedBlob);
+
+// 2. Build the canonical memo to submit on-chain (elsewhere, e.g. via majik-notary)
+const memo = MajikSignature.buildChainAnchorMemo(sealInfo.sealHash);
+
+// 3. Once the external chain integration confirms the transaction, register the anchor
+const blob = await MajikSignature.registerChainAnchor(sealedBlob, confirmedAnchor);
+
+// 4. Read anchors back later
+const anchors = await MajikSignature.getChainAnchors(blob);
+```
+
+---
+
 ## API Reference
 
 ### Content Signing (bytes/strings)
@@ -398,6 +558,7 @@ Sign raw bytes or a string with an unlocked `MajikKey`.
 - `options?: SignOptions`
   - `contentType?: string` — advisory label (see `CONTENT_TYPES`)
   - `timestamp?: string` — ISO 8601 override (defaults to `new Date().toISOString()`)
+  - `expectedSigners?: ExpectedSigner[]` — accepted at the type level for allowlist-establishing flows; ignored by the bare `sign()` call itself (only meaningful via the file-level allowlist APIs)
 
 **Returns:** `Promise<MajikSignature>`
 **Throws:** `MajikSignatureKeyError` if the key is locked or has no signing keys.
@@ -417,7 +578,8 @@ Verify a signature against content and the signer's public keys. Both Ed25519 an
   contentHash?: string;
   timestamp: string;
   contentType?: string;
-  reason?: string; // present when valid is false
+  handler?: string;  // present when result came from a file-level verify
+  reason?: string;   // present when valid is false
 }
 ```
 
@@ -429,6 +591,14 @@ Convenience wrapper — verifies directly against a `MajikKey` instance. Works e
 #### `MajikSignature.publicKeysFromMajikKey(key)`
 Extracts `{ signerId, edPublicKey, mlDsaPublicKey }` from a `MajikKey` for use with `verify()`. Works on locked keys.
 
+#### `signature.extractPublicKeys()` *(instance method)*
+Extracts `{ signerId, edPublicKey, mlDsaPublicKey }` **from the signature envelope itself**, rather than from a `MajikKey`. Useful when you only have a serialized signature and need its embedded public keys — for example, to independently verify a TSA token via `verifyTSA()`. Validates key lengths before returning.
+
+> ⚠️ Keys extracted this way are **self-asserted by the envelope** — always cross-check the returned `signerId` against a trusted source before relying on the result. See [Security Considerations](#security-considerations).
+
+#### `signature.validate()` / `signature.isValid()`
+`validate()` re-runs structural validation on the signature's own JSON shape and throws on failure; `isValid()` is the non-throwing boolean wrapper. Useful as a cheap sanity check after deserializing from untrusted storage, before running full cryptographic verification.
+
 #### `MajikSignature.fromJSON(json)` / `MajikSignature.deserialize(base64)`
 Reconstruct a `MajikSignature` instance from stored JSON or a base64 string.
 
@@ -450,7 +620,7 @@ Sign a file and embed the signature in one call. Strips any existing envelope fi
   - `mimeType?: string` — override auto-detected MIME type
   - `expectedSigners?: ExpectedSigner[]` — only honored on the **first** signature; establishes a signing allowlist
 
-**Returns:** `Promise<{ blob: Blob; signature: MajikSignature; handler: string; mimeType: string }>`
+**Returns:** `Promise<{ blob: Blob; signature: MajikSignature; envelope: MajikSignatureEnvelope; handler: string; mimeType: string }>`
 
 ---
 
@@ -487,10 +657,55 @@ Structural presence check — does the file contain an envelope at all? Does not
 
 ---
 
+### Detached Signing & MajikSignatureEnvelope API
+
+#### `MajikSignature.signFileDetached(file, key, options?)`
+
+Sign a file and return the resulting envelope **detached** — the returned `blob` is the clean, stripped file; the envelope travels separately.
+
+- `options?.existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob` — continue signing an envelope that started out-of-band (any of: an instance, its JSON shape, raw `.mjksig` bytes, or a `.mjksig` Blob)
+- `options?.expectedSigners?: ExpectedSigner[]` — same allowlist-establishing semantics as `signFile()`
+- `options?.tsa?: MajikTimestamp` — attach a Trusted Timestamp to this signer's entry before it's added to the envelope
+
+**Returns:** `Promise<{ blob: Blob; envelope: MajikSignatureEnvelope; signature: MajikSignature; handler: string; mimeType: string }>`
+
+#### `MajikSignature.verifyFileDetached(file, envelope, keyOrPublicKeys, options?)`
+Verify a file against a detached envelope (instance, JSON, `.mjksig` bytes, or Blob — accepted via the same flexible shape as `existingEnvelope` above). Strips the file first, in case it also happens to carry an embedded envelope.
+
+**Returns:** `Promise<VerificationResult[]>`
+
+---
+
+#### `MajikSignatureEnvelope`
+
+The behavior-rich, immutable in-memory counterpart to the wire-format `MultiSigEnvelope` JSON. Every `with*` method returns a **new** instance — the receiver is never mutated. This is the class returned by `signFileDetached()`, accepted by `verifyFileDetached()`, and underlying every multi-sig query method.
+
+**State predicates:** `isSealed()`, `hasAllowlist()`, `isFirstSigner()`, `isMultiSig()`, `hasMultipleSignatories()`, `isIssuer(keyOrFingerprint)`
+
+**Lookup:** `findSignature(signerId)`, `get signatures`, `get allowlist`, `get chainAnchors`
+
+**Allowlist enforcement:** `checkAllowlist(key)`, `assertCanSign(key)` (throws), `canSign(key)` (non-throwing), `verifyAllowlistIntegrity()`
+
+**Builders (immutable):** `withSignature(sig)`, `withAllowlist(allowlist, signerId)`, `withSeal(sealedBy, timestamp?)`, `withChainAnchor(anchor)`
+
+**Seal queries:** `verifySeal()`, `getSealInfo()`, `canAnchor()`
+
+**Signatory resolution:** `resolveIssuer()`, `getSignatories(filter?)`, `getEnvelopeInfo()`
+
+**Serialization:** `toJSON()`, `serialize()` / `MajikSignatureEnvelope.deserialize(base64)`, `toMJKSIG()` / `toMJKSIGBytes()` / `MajikSignatureEnvelope.fromMJKSIG(input)`, `MajikSignatureEnvelope.isMJKSIG(input)`, `MajikSignatureEnvelope.getMJKSIGVersion(input)`
+
+**Creation / parsing:** `MajikSignatureEnvelope.empty()`, `MajikSignatureEnvelope.fromJSON(json)` (also transparently promotes legacy bare single-sig JSON), `MajikSignatureEnvelope.from(input)` (accepts an instance, JSON, `.mjksig` bytes, or Blob — the universal entry point used internally by every detached-envelope-accepting method)
+
+**Validation:** `validate()` (throws), `isValid()` (boolean)
+
+See [Binary Container Formats](#binary-container-formats-mjksig--mjksmap) for details on `.mjksig`.
+
+---
+
 ### Multi-Signature & Allowlist API
 
 #### `MajikSignature.expectedSignerFromKey(key)`
-Builds an `ExpectedSigner` entry (`{ signerId, edPublicKey, mlDsaPublicKey }`) from a `MajikKey`, for use in `signFile()`'s `expectedSigners` option. The key does not need to be unlocked.
+Builds an `ExpectedSigner` entry (`{ signerId, edPublicKey, mlDsaPublicKey }`) from a `MajikKey`, for use in `signFile()`'s / `signFileDetached()`'s `expectedSigners` option. The key does not need to be unlocked.
 
 #### `MajikSignature.getAllowlist(file, options?)`
 **Returns:** `Promise<ExpectedSigner[] | null>` — `null` for open-signing or unsigned files.
@@ -557,7 +772,7 @@ Builds a `MajikTSARequest` (`{ digest: { algorithm: "SHA-256", value } }`) from
 **Server-side.** Signs a TSA payload and returns a complete `MajikTimestamp`, including a server-generated nonce and timestamp.
 
 #### `signature.addTSA(timestamp)`
-Attaches and validates a `MajikTimestamp` on an existing signature instance. Throws `MajikSignatureError` if a TSA is already present, if the digest doesn't match, or `MajikSignatureVerificationError` if the TSA signature itself doesn't verify. A TSA, once attached, cannot be replaced.
+Attaches and validates a `MajikTimestamp` on an existing signature instance. Throws `MajikSignatureError` if a TSA is already present or if the digest doesn't match, or `MajikSignatureVerificationError` if the TSA signature itself doesn't verify. A TSA, once attached, cannot be replaced.
 
 #### `signature.verifyTSA()`
 Re-verifies the attached TSA's own signature — useful after deserializing a signature from storage.
@@ -567,6 +782,131 @@ Re-verifies the attached TSA's own signature — useful after deserializing a si
 
 ---
 
+### Batch Signing & MajikSignatureMap API
+
+#### `MajikSignature.signBatchDetached(files, key, options?)`
+
+Sign a batch of files (e.g. a folder or zip's contents) as detached envelopes.
+
+- `files: { path: string; blob: Blob }[]` — every path must be unique within the batch
+- `options?.mode?: "map" | "separate"` — `"map"` (default) produces one `MajikSignatureMap` covering the whole batch; `"separate"` produces one `.mjksig` Blob per file
+- `options?.continueOnError?: boolean` — default `false` (abort the whole batch on the first failure); set `true` to collect failures per-file and continue
+
+**Returns:**
+```typescript
+| { mode: "map"; map: MajikSignatureMap; mapBlob: Blob; failures: BatchSignFailure[] }
+| { mode: "separate"; signatures: { path: string; blob: Blob }[]; failures: BatchSignFailure[] }
+```
+
+#### `MajikSignature.verifyFilesFromMjksMap(map, files, publicKeys, options?)`
+Verify a batch of extracted files against a `MajikSignatureMap`. Never throws per-file by default — every outcome (missing, tampered, relocated-but-valid, invalid, verified) is reported so you can render a full status table in one pass.
+
+- `options?.expectedSignerId?: string`
+- `options?.requireAllPresent?: boolean` — escalate a missing file to a thrown error instead of a per-file `"not_in_map"` result
+
+**Returns:** `Promise<FileVerifyResult[]>`
+
+```typescript
+{
+  path: string;
+  status: "verified" | "invalid" | "tampered" | "not_in_map";
+  results?: VerificationResult[];
+  reason?: string;
+  relocatedFrom?: string; // present only when found by content match at a different path
+}
+```
+
+#### `MajikSignature.verifyFilesFromMjksMapWithKey(map, files, key, options?)`
+Convenience overload — resolves public keys from a `MajikKey` instead of requiring `MajikSignerPublicKeys` directly.
+
+#### `MajikSignature.summarizeBatchVerification(results)`
+One-glance pass/fail summary over a `FileVerifyResult[]`.
+
+**Returns:** `{ total, verified, invalid, tampered, notInMap, allValid }`
+
+---
+
+#### `MajikSignatureMap`
+
+The behavior-rich, immutable class backing `.mjksmap`. Keyed by **path**, not content hash alone — duplicate-content files across a batch are legitimate and must not collide.
+
+**Lookup:** `getEntry(path)`, `hasEntry(path)`, `findEntry(path, file)` (hash-verified against stored bytes), `findEntriesByHash(file)`, `resolveEntry(path, file)` (relocation-tolerant — tries the given path first, falls back to content match), `getEnvelope(path)`, `getAllEnvelopes()`
+
+**Builders (immutable):** `withEntry(entry)`, `withoutEntry(path)`
+
+**Serialization:** `toJSON()`, `toMJKSMAP()` / `toMJKSMAPBytes()` / `MajikSignatureMap.fromMJKSMAP(input)`, `MajikSignatureMap.isMJKSMAP(input)`
+
+**Creation / parsing:** `MajikSignatureMap.empty()`, `MajikSignatureMap.fromJSON(json)`, `MajikSignatureMap.from(input)` (accepts an instance, JSON, `.mjksmap` bytes, or Blob)
+
+**Validation:** `validate()` (throws), `isValid()` (boolean)
+
+`resolveEntry()`'s status values: `"path_match"` (found, content unchanged), `"path_tampered"` (found at that path, content no longer matches), `"relocated"` (not at the given path, but found elsewhere by content hash), `"not_found"`.
+
+See [Binary Container Formats](#binary-container-formats-mjksig--mjksmap) for details on `.mjksmap`.
+
+---
+
+### Signature Order Verification API
+
+Verifies that a set of expected signers signed in a required chronological sequence. TSA-attested timestamps (`tsa.payload.timestamp`) are preferred automatically over self-reported ones (`timestamp`); every result flags whether any comparison relied on a self-reported, non-attested clock.
+
+#### `MajikSignature.verifyFileOrder(file, expectedOrder, options?)`
+
+- `expectedOrder: (MajikKey | ExpectedSigner)[]` — array position is the expected chronological position; `MajikKey` instances and `ExpectedSigner` objects can be mixed freely and are normalized internally
+- `options?.strict?: boolean` — default `false`. When `true`, any signer present in the envelope but absent from `expectedOrder` fails the overall result
+
+**Returns:** `Promise<SignatureOrderResult>`
+
+```typescript
+{
+  valid: boolean;                  // true only if everyone expected signed, all valid, order respected (and, in strict mode, no extra signers)
+  allExpectedSigned: boolean;
+  allValid: boolean;
+  orderRespected: boolean;
+  strict: boolean;
+  unexpectedSigners: string[];     // populated only when strict is true
+  pendingSigners: string[];
+  invalidSigners: string[];
+  violations: OrderViolation[];    // { earlier, later, earlierTimestamp, laterTimestamp }
+  usesUnattestedTimestamp: boolean;
+  softTieWarnings: SoftTieWarning[]; // identical timestamps between two signers — order indistinguishable, doesn't fail `valid`
+  signers: SignerOrderStatus[];
+  reason?: string;
+}
+```
+
+#### `MajikSignature.verifyFileDetachedOrder(file, envelope, expectedOrder, options?)`
+Same semantics as `verifyFileOrder()`, against a detached envelope (instance, JSON, `.mjksig` bytes, or Blob).
+
+#### `MajikSignature.normalizeExpectedOrder(expectedOrder)`
+Normalizes a mixed array of `MajikKey` instances and/or `ExpectedSigner` objects into a plain `ExpectedSigner[]`. Exposed standalone in case you want to build and cache the normalized order ahead of time, without immediately verifying.
+
+> Order comparisons only run between signers who **both** signed and **both** produced a valid signature — an invalid signature's timestamp isn't trustworthy, so it's excluded from the ordering check but still reported via `invalidSigners`. Order verification checks the relative sequence of your `expectedOrder` list; in non-strict mode it does not detect an unlisted signer signing *between* two expected signers — use `strict: true` if the presence of any signer outside your expected set must itself be treated as a failure.
+
+---
+
+### Chain Anchoring API (Experimental)
+
+> ⚠️ **These APIs are explicitly marked experimental in source and are not yet API-stable.** Expect breaking changes across minor versions.
+
+#### `MajikSignature.canAnchor(file, options?)`
+Checks whether a file is eligible for chain anchoring (requires the envelope to be sealed).
+
+**Returns:** `Promise<{ permitted: boolean; reason?: string }>`
+
+#### `MajikSignature.buildChainAnchorMemo(sealHash)`
+Builds the canonical, domain-separated memo string (`"majik-notary-v-1:" + sealHash`) intended to be submitted on-chain by an external integration layer. Does not talk to any chain itself.
+
+#### `MajikSignature.registerChainAnchor(file, anchor, options?)`
+Embeds an **already-confirmed** `MajikChainAnchor` into the file's envelope. The caller is responsible for submitting and confirming the transaction beforehand (e.g. via a separate chain-integration product). Upserts by `anchor.id`, so retried registration doesn't produce duplicates.
+
+**Returns:** `Promise<Blob>`
+
+#### `MajikSignature.getChainAnchors(file, options?)`
+**Returns:** `Promise<MajikChainAnchor[]>` — empty array if none, or if the file has no envelope.
+
+---
+
 ### Image Stamping (Experimental)
 
 > ⚠️ **These APIs are explicitly marked experimental in source and are not yet API-stable.** Expect breaking changes across minor versions.
@@ -583,6 +923,15 @@ Full round-trip to/from the `MajikSignatureJSON` shape.
 #### `signature.serialize()` / `MajikSignature.deserialize(base64)`
 Compact base64 transport format — useful for HTTP headers or database columns.
 
+#### `envelope.toJSON()` / `MajikSignatureEnvelope.fromJSON(json)`
+Full round-trip to/from the `MultiSigEnvelope` shape, including transparent promotion of legacy bare single-sig JSON.
+
+#### `envelope.serialize()` / `MajikSignatureEnvelope.deserialize(base64)`
+Base64 transport for a full multi-sig envelope.
+
+#### `envelope.toMJKSIG()` / `MajikSignatureEnvelope.fromMJKSIG(input)`
+Self-describing binary container for a detached envelope — see [Binary Container Formats](#binary-container-formats-mjksig--mjksmap).
+
 ```typescript
 const signature = await MajikSignature.sign(content, key);
 
@@ -615,7 +964,9 @@ Handlers are tried in order; the first one whose `canHandle()` matches wins. If
 | HTML, Markdown, JSON, plain text, source code | Text | Appended, format-appropriate metadata block                       |
 | Anything else                       | Fallback       | Universal binary trailer: `[original][signature JSON][8-byte length][8-byte magic "MAJIKSIG"]` |
 
-All handlers guarantee: files remain fully usable after signing (PDFs still open, videos still play, Office files stay editable), signing is idempotent (safe to re-sign), and `strip()` always reproduces exactly the bytes that were originally hashed — including deterministic ZIP re-canonicalization for Office formats, so that identical content always strips to identical bytes regardless of when it was last re-zipped.
+All handlers guarantee: files remain fully usable after signing (PDFs still open, videos still play, Office files stay editable), signing is idempotent (safe to re-sign), and `strip()` always reproduces exactly the bytes that were originally hashed — including deterministic ZIP re-canonicalization for Office formats (the ZIP is always rebuilt via a full unzip/rezip pass on `strip()`, even when no signature entry exists yet), so that identical content always strips to identical bytes regardless of when it was last re-zipped.
+
+The MP4/MOV handler additionally preserves box order and byte-for-byte trailing/leftover data at every nesting level (top-level boxes, `moov` children, and `udta` children) rather than silently discarding anything it doesn't recognize — unparsed trailing bytes are always carried forward rather than dropped.
 
 ---
 
@@ -641,7 +992,7 @@ A single signer's envelope (`MajikSignatureJSON`):
 
 `allowlistHash` and `tsa` are only present when applicable — omitted entirely otherwise, never `null`.
 
-What's actually embedded into a file is a **`MultiSigEnvelope`**, wrapping one or more of the above:
+What's actually embedded into a file (or produced detached) is a **`MultiSigEnvelope`**, wrapping one or more of the above — modeled at runtime by `MajikSignatureEnvelope`:
 
 ```json
 {
@@ -651,12 +1002,31 @@ What's actually embedded into a file is a **`MultiSigEnvelope`**, wrapping one o
   "allowlistSignerId": "fingerprint-of-issuer",
   "sealHash": "128-hex-char-sha3-512-hash",
   "sealTimestamp": "2026-01-01T00:00:00.000Z",
-  "sealedBy": "fingerprint-of-issuer"
+  "sealedBy": "fingerprint-of-issuer",
+  "chainAnchors": [ /* MajikChainAnchor[], optional */ ]
 }
 ```
 
 Files signed before multi-sig support existed contain a bare `MajikSignatureJSON` object at the root instead of this wrapper. The library detects and promotes this shape transparently — every public API always returns/accepts `MultiSigEnvelope` semantics, and old signatures continue to verify unmodified.
 
+A batch manifest (`MjksMapJSON`, backing `MajikSignatureMap`) is a flat list of per-path entries, each carrying its own detached envelope:
+
+```json
+{
+  "version": 1,
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "entries": [
+    {
+      "path": "docs/report.pdf",
+      "contentHash": "base64-sha256-of-original-content",
+      "size": 245678,
+      "mimeType": "application/pdf",
+      "envelope": { "...": "MultiSigEnvelope for this file" }
+    }
+  ]
+}
+```
+
 **Approximate serialized sizes (per signer):**
 
 | Format            | Size   |
@@ -668,19 +1038,54 @@ The dominant contributor is `mlDsaSignature` (~6 KB base64) and `signerMlDsaPubl
 
 ---
 
+## Binary Container Formats (MJKSIG / MJKSMAP)
+
+Two dedicated, versioned, self-identifying binary containers exist for out-of-band travel and on-disk storage — distinct from `serialize()`/`deserialize()` (plain base64 of the JSON, no header), which remains for lightweight in-app round-tripping.
+
+Both share the same header layout: `[magic bytes][1-byte version][1-byte reserved][4-byte big-endian payload length][payload JSON]`.
+
+| Format | Magic | Magic Length | Header Length | Media Type | Extension |
+| ------ | ----- | ------------ | -------------- | ---------- | --------- |
+| `.mjksig` — a single detached envelope | `MJKSIG` | 6 bytes | 12 bytes | `application/vnd.majikah.mjksig` | `.mjksig` |
+| `.mjksmap` — a batch manifest | `MJKSMAP` | 7 bytes | 13 bytes | `application/vnd.majikah.mjksmap` | `.mjksmap` |
+
+Both formats validate magic bytes, supported version, and declared payload length **before** attempting to parse the JSON payload — a truncated or corrupted buffer fails fast with a clear `MajikSignatureSerializationError` rather than an obscure `JSON.parse` error.
+
+```typescript
+// MJKSIG
+const bytes = envelope.toMJKSIGBytes();     // sync Uint8Array — Node scripts, direct fs writes
+const blob = envelope.toMJKSIG();           // Blob — browser downloads, zip packaging
+const restored = await MajikSignatureEnvelope.fromMJKSIG(blob); // accepts Blob or Uint8Array
+const isMjksig = await MajikSignatureEnvelope.isMJKSIG(blob);   // cheap magic-byte sniff, no parse
+const version = await MajikSignatureEnvelope.getMJKSIGVersion(blob);
+
+// MJKSMAP
+const mapBytes = map.toMJKSMAPBytes();
+const mapBlob = map.toMJKSMAP();
+const restoredMap = await MajikSignatureMap.fromMJKSMAP(mapBlob);
+const isMjksmap = await MajikSignatureMap.isMJKSMAP(mapBlob);
+```
+
+`MajikSignatureEnvelope.from(input)` and `MajikSignatureMap.from(input)` are universal entry points that accept an instance, its plain JSON shape, raw bytes, or a Blob — every method that accepts a detached envelope or map (`verifyFileDetached()`, `signFileDetached()`'s `existingEnvelope` option, `verifyFilesFromMjksMap()`, etc.) normalizes through these internally, so callers don't need to know or care which shape they currently have on hand.
+
+---
+
 ## Error Handling
 
 Majik Signature throws a typed error hierarchy rather than generic `Error` objects, so you can catch precisely what you need:
 
 | Error Class                          | Thrown when...                                                          |
 | ------------------------------------- | ------------------------------------------------------------------------- |
-| `MajikSignatureError`                 | Base class; also thrown for general/unexpected failures                  |
+| `MajikSignatureError`                 | Base class; also thrown for general/unexpected failures (e.g. signing a sealed envelope, missing envelope on seal/anchor)|
 | `MajikSignatureKeyError`              | The key is locked, lacks signing keys, or isn't the required issuer      |
-| `MajikSignatureVerificationError`     | Verification fails unexpectedly (not the same as `valid: false`)         |
-| `MajikSignatureSerializationError`    | JSON/base64 parsing or encoding fails                                    |
+| `MajikSignatureVerificationError`     | Verification fails unexpectedly (not the same as `valid: false`), including a failed TSA signature check |
+| `MajikSignatureSerializationError`    | JSON/base64/MJKSIG/MJKSMAP parsing or encoding fails, including malformed binary headers |
 | `MajikSignatureAllowlistError`        | A non-listed signer attempts to sign a restricted file                   |
+| `MajikSignatureValidationError`       | A structural shape check fails — malformed envelope, malformed batch manifest entry, empty/duplicate batch paths, empty allowlist, mismatched seal fields, invalid `expectedOrder` input, etc. |
+
+Note the distinction: `verify()`/`verifyFile()` return `{ valid: false, reason }` for a signature that *fails cryptographic verification* — that's an expected, handled outcome, not an exception. Exceptions are reserved for misuse (locked keys, malformed envelopes, disallowed signers, sealed files, malformed batch input, etc.).
 
-Note the distinction: `verify()`/`verifyFile()` return `{ valid: false, reason }` for a signature that *fails cryptographic verification* — that's an expected, handled outcome, not an exception. Exceptions are reserved for misuse (locked keys, malformed envelopes, disallowed signers, sealed files, etc.).
+Order and batch verification methods follow the same philosophy: `SignatureOrderResult` and `FileVerifyResult` both report failure states (`pendingSigners`, `invalidSigners`, `violations`, `"tampered"`, `"not_in_map"`, etc.) as normal return values rather than throwing, since "this didn't pass" is an expected outcome you'll want to render in a UI — not an exceptional code path.
 
 ---
 
@@ -697,6 +1102,9 @@ Note the distinction: `verify()`/`verifyFile()` return `{ valid: false, reason }
 - **Allowlist integrity** — tampering with a restricted file's allowlist invalidates the issuer's own signature
 - **Seal integrity** — sealed envelopes reject all further signing attempts, including from the issuer
 - **Embed integrity** — file embedding always signs original bytes; the container format is never part of what's signed
+- **Detachment integrity** — detached verification always strips the target file first, so a stray embedded envelope never interferes with verifying against a separately-supplied envelope
+- **Batch relocation resistance** — `MajikSignatureMap` resolves files by content hash when a path lookup misses, so renaming/moving a signed batch after the fact doesn't break verification
+- **Order-check independence** — signing-order verification checks each expected signer against the public keys **you supplied**, not the keys self-asserted inside their own envelope entry, so a forged identity claim can't also forge its way into a valid order result
 
 ### What is Your Responsibility
 
@@ -704,6 +1112,8 @@ Note the distinction: `verify()`/`verifyFile()` return `{ valid: false, reason }
 - **Byte-for-byte content consistency** — the same bytes must be passed to both `sign()` and `verify()`. For strings, both sides must use UTF-8; for JSON, both sides must use the same `JSON.stringify()` output.
 - **Key upgrade** — legacy `MajikKey` accounts without signing keys must be re-imported via `importFromMnemonicBackup()` before signing. Check with `key.hasSigningKeys`.
 - **TSA trust** — the library verifies a TSA signature cryptographically, but trusting *which* TSA identity to accept is your application's decision.
+- **Timestamp trust level in order verification** — a self-reported (non-TSA) timestamp is tamper-evident but not independently attested; a signer could set their local clock to anything. Always check `result.usesUnattestedTimestamp` before treating an order result as strong proof rather than a claim.
+- **Chain anchor submission and confirmation** — this SDK never talks to a blockchain itself. Submitting the memo from `buildChainAnchorMemo()` and confirming the transaction is entirely your (or a companion product's) responsibility before calling `registerChainAnchor()`.
 
 ### What NOT to Do
 
@@ -714,16 +1124,20 @@ Note the distinction: `verify()`/`verifyFile()` return `{ valid: false, reason }
 - ❌ **DON'T** use `contentType` as a security mechanism — it is advisory only and not enforced
 - ❌ **DON'T** assume a Tier-2 trailer signature survives re-muxing or re-encoding — use native-metadata formats where durability matters
 - ❌ **DON'T** treat the experimental image-stamping APIs as stable in production
+- ❌ **DON'T** treat a non-strict `verifyFileOrder()` pass as proof that *no one else* signed — use `strict: true` when the complete signer set matters, not just the relative order of the signers you named
+- ❌ **DON'T** register a chain anchor before the corresponding transaction is actually confirmed externally — `registerChainAnchor()` trusts the `MajikChainAnchor` you pass it and does not itself verify on-chain state
 
 ### What TO Do
 
 - ✅ **DO** verify `result.signerId` for every entry returned by `verifyFile()` against a known trusted fingerprint
 - ✅ **DO** use `verifyWithKey()` / `verifyFile(key)` when you have the signer's `MajikKey` — it handles key extraction safely
 - ✅ **DO** lock the key immediately after signing — `key.lock()` purges secret keys from memory
-- ✅ **DO** use `signFile()` for media and documents to keep signature and content together
+- ✅ **DO** use `signFile()` for media and documents to keep signature and content together, or `signFileDetached()` when the envelope needs to live and travel separately from the file
 - ✅ **DO** use `isSigned()` as a fast guard before calling `verifyFile()` in hot paths
 - ✅ **DO** use `canSign()` to give users a clear reason *before* they attempt to sign a restricted file
 - ✅ **DO** use `CONTENT_TYPES` constants for standard content type labels
+- ✅ **DO** use `signBatchDetached()` with `continueOnError: true` for large batches where a handful of unreadable files shouldn't block the rest — and inspect `failures` afterward
+- ✅ **DO** check `result.softTieWarnings` even on a passing order-verification result — it's a legitimate caveat worth surfacing, not just a failure signal
 
 ---
 
@@ -735,7 +1149,6 @@ Majik Signature is the cryptographic signing layer shared across Majikah's produ
 
 [![Majik Signature Hero](https://github.com/user-attachments/assets/781bb778-9535-4b1f-bbc5-820550ecc864)](https://signature.majikah.solutions)
 
-
 The standalone desktop and web application built on top of this SDK. It's the fastest way to sign and verify files without writing any code:
 
 - Sign virtually any file — documents, PDFs, Office files, images, audio, video, source code, archives, and more — entirely **locally on your device**. No account, no upload, no internet connection required for offline signing and verification.
@@ -743,7 +1156,7 @@ The standalone desktop and web application built on top of this SDK. It's the fa
 - **Audio Stamping** — embed producer tags, voice tags, or audio watermarks directly into signed audio, with a full mixing timeline (volume, pan, pitch, EQ, trim, loop).
 - **Trusted Timestamps** — every account gets 5 free Trusted Timestamps every 24 hours; local timestamps remain fully supported offline.
 - **Batch processing** — drag-and-drop folders, recursive ZIP processing, individual or bulk sealing, per-file verification results.
-- **Multi-party workflows** — signing allowlists, open or restricted modes, progress tracking for pending vs. completed signatures.
+- **Multi-party workflows** — signing allowlists, open or restricted modes, progress tracking for pending vs. completed signatures, and chronological signing-order verification.
 - Built with Tauri for a lightweight, fast, secure desktop experience — available on the **Microsoft Store**, with a full-featured **web app** as well.
 
 ### 🧾 Majik Buwiz
@@ -788,7 +1201,6 @@ If you want to contribute or help extend support to more platforms or file forma
 
 Developed by **Josef Elijah Fabian (Zelijah)** | [Majikah Solutions OPC](https://majikah.solutions/about)
 
-
 **Developer**: [Josef Elijah Fabian](https://github.com/jedlsf)
 **GitHub**: [https://github.com/Majikah](https://github.com/Majikah)
 **Project Repository**: [https://github.com/Majikah/majik-signature](https://github.com/Majikah/majik-signature)