@majikah/majik-signature 0.2.9 → 0.4.0

package/README.md

@@ -103,17 +103,19 @@ Verification requires **both** to pass. This means:
 Both signatures cover a **domain-separated canonical payload**:
 
 ```
-"majik-signature-v1:" + JSON({ v, id, ts, ct, hash[, alh] })
+"majik-signature-v1:" + JSON({ v, id, ts, ct, hash[, alh][, vu][, vch] })
 ```
 
-| Field  | Description                                                                 |
-| ------ | ---------------------------------------------------------------------------- |
-| `v`    | Envelope version                                                             |
-| `id`   | Signer fingerprint (MajikKey identity)                                      |
-| `ts`   | ISO 8601 timestamp                                                          |
-| `ct`   | Content type (advisory, or `null`)                                          |
-| `hash` | SHA-256 of the original content, base64                                     |
-| `alh`  | SHA-256 of the canonical allowlist, base64 — **present only** when this signer is establishing an allowlist |
+| Field  | Description                                                                                                                                                                                                                                                                                                                                                 |
+| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `v`    | Envelope version                                                                                                                                                                                                                                                                                                                                            |
+| `id`   | Signer fingerprint (MajikKey identity)                                                                                                                                                                                                                                                                                                                      |
+| `ts`   | ISO 8601 timestamp                                                                                                                                                                                                                                                                                                                                          |
+| `ct`   | Content type (advisory, or `null`)                                                                                                                                                                                                                                                                                                                          |
+| `hash` | SHA-256 of the original content, base64                                                                                                                                                                                                                                                                                                                     |
+| `alh`  | SHA-256 of the canonical allowlist, base64 — **present only** when this signer is establishing an allowlist                                                                                                                                                                                                                                                 |
+| `vu`   | Optional ISO 8601 expiry. When present, verify() treats the signature as invalid once the current time is past this value. Absent = never expires (matches all pre-existing signatures — fully backward compatible). Covered by the canonical signing payload when present, so it cannot be stripped or extended post-hoc without breaking both signatures. |
+| `vch`  | SHA-256 of the `fileVersions` revision chain, base64 — present only when file versioning is in use; covers the chain state as of this signer's own entry, so a rewritten chain breaks their signature.                                                                                                                                                      |
 
 `alh` is *omitted entirely* (not set to `null`) on every signature that isn't establishing an allowlist. This is a deliberate backward-compatibility guarantee: every signature produced before multi-sig support existed still verifies today, because its payload bytes are unchanged.
 
@@ -143,11 +145,17 @@ Files don't hold a single signature — they hold a **`MultiSigEnvelope`** (mode
 - **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.
 - **Sealing**: the issuer (and only the issuer) can seal an envelope, computing a **SHA3-512** hash over every current signatory plus a seal timestamp, domain-separated with `"majik-seal-v1:"`. A sealed envelope rejects all further signing attempts — including from the issuer.
 
-### 6. Trusted Timestamps (TSA)
+### 6. File Versioning for Visually-Mutating Multi-Sig Workflows
+
+Ordinary multi-sig assumes every signer signs the *same* underlying bytes. That breaks when signing also means visually stamping the document — each signer's stamp changes the file's content, so the next signer is working from different bytes than the one before them.
+
+`signFile()`'s `priorSignedFile` option handles this: pass the file as it was received (carrying the prior signer's envelope), and the library verifies that prior envelope is genuinely valid before extending it with a new `FileVersion` revision entry, cryptographically bound via `versionChainHash` — see [File Versioning & Multi-Sig Revisions](#file-versioning--multi-sig-revisions).
+
+### 7. 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. TSA timestamps are also what power *attested* [signing-order verification](#verifying-signing-order) — see below.
 
-### 7. Chain Anchoring
+### 8. 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.
 
@@ -462,8 +470,8 @@ if (result.mode === 'map') {
 }
 
 // Later — verify an extracted batch against the manifest
-const map = await MajikSignature.getSignatureMapFromMJKSMAP(mapBlob);
-// (or: const map = await MajikSignatureMap.fromMJKSMAP(mapBlob);)
+const map = await MajikSignatureMap.fromMJKSMAP(mapBlob);
+
 
 const results = await MajikSignature.verifyFilesFromMjksMap(
   map,
@@ -543,6 +551,49 @@ const blob = await MajikSignature.registerChainAnchor(sealedBlob, confirmedAncho
 const anchors = await MajikSignature.getChainAnchors(blob);
 ```
 
+---
+
+### File Versioning & Multi-Sig Revisions
+
+Use this when signing also means visually stamping the file (drawn signatures, watermark overlays) — so each signer's turn changes the bytes, not just adds a detached signature.
+
+```typescript
+import { MajikSignature } from '@majikah/majik-signature';
+
+// Issuer signs first — same as a normal first signature.
+const { blob: signedV1 } = await MajikSignature.signFile(originalFile, aliceKey, {
+  expectedSigners: [
+    MajikSignature.expectedSignerFromKey(aliceKey),
+    MajikSignature.expectedSignerFromKey(bobKey),
+  ],
+});
+
+// Bob visually stamps the file (application-specific), THEN signs — passing
+// priorSignedFile so the new revision correctly chains onto Alice's.
+const stampedByBob = await applyVisualStamp(signedV1, bobKey);
+const { blob: signedV2 } = await MajikSignature.signFile(stampedByBob, bobKey, {
+  priorSignedFile: signedV1,
+  message: 'Approved pending final review',
+});
+
+// Tier 1 — self-contained verification, no archived revisions needed.
+// Proves every signer's commitment is genuine and the chain hasn't been
+// rewritten, using only the final file.
+const chainResult = await MajikSignature.verifyFileChain(signedV2);
+console.log('Chain valid:', chainResult.chainValid);
+console.log('Latest signer valid:', chainResult.latest.valid);
+
+// Tier 2 — archive-assisted, full proof against retained revision bytes.
+// Accepts Blob, File, Uint8Array, or ArrayBuffer for each prior revision.
+const revisionResult = await MajikSignature.verifyFileRevisions(
+  signedV2,
+  [originalFile, signedV1],
+);
+console.log('All revisions valid:', revisionResult.allValid);
+console.log('Complete set supplied:', revisionResult.isCompleteSet);
+```
+
+
 ---
 
 ## API Reference
@@ -907,6 +958,48 @@ Embeds an **already-confirmed** `MajikChainAnchor` into the file's envelope. The
 
 ---
 
+### File Versioning API
+
+#### `MajikSignature.signFile(file, key, options?)` — versioning-relevant options
+- `options?.priorSignedFile?: Blob` — the file as received, before this signer's own visual change. Presence of this option is what makes the call a **revision** (2nd signer+) rather than a fresh signature: the prior file's embedded envelope is fully self-verified (commitment check, per §2.4 of the MJKSIG spec) before being extended.
+- `options?.message?: string` — optional human-readable note stored on this revision's `FileVersion` entry.
+
+Throws `MajikSignatureError` if `priorSignedFile` has no embedded envelope, or if any existing signature in it fails verification.
+
+#### `MajikSignature.verifyFileChain(file, options?)`
+Self-contained (Tier 1) verification — no archived revisions required. Verifies the most recent signer fully against the file's current bytes, and every earlier signer via commitment-only verification (`verifyCommitment()`, recomputed from stored fields) plus a recomputed `versionChainHash` check against the current `fileVersions`.
+
+**Returns:** `Promise<FileChainVerification>`
+```typescript
+{
+  latest: VerificationResult;
+  history: RevisionCommitmentResult[]; // VerificationResult & { commitmentOnly: true }
+  chainValid: boolean;
+}
+```
+
+#### `MajikSignature.verifyFileRevisions(finalFile, revisions, options?)`
+Archive-assisted (Tier 2) verification — full proof against retained revision bytes. `revisions` accepts any mix of `Blob`, `File`, `Uint8Array`, or `ArrayBuffer`; the final file is included automatically, no need to pass it twice.
+
+- `options?.resolvePublicKeys?: (signerId: string) => MajikSignerPublicKeys | Promise<MajikSignerPublicKeys>` — defaults to trusting the envelope's embedded keys, same as `verify()`; pass a resolver to cross-check against an external registry instead.
+- `options?.now?: Date`
+
+**Returns:** `Promise<RevisionSetVerification>`
+```typescript
+{
+  allValid: boolean;      // every fileVersions entry matched a supplied revision AND verified
+  isCompleteSet: boolean; // the supplied revisions cover the whole chain, no gaps
+  results: RevisionCheckResult[]; // per-version status: "verified" | "unmatched" | "chain_broken" | "signature_invalid"
+}
+```
+
+#### `MajikSignature.verifyCommitment(signature, publicKeys, now?)`
+Verifies a signature's cryptographic commitment (Ed25519 + ML-DSA-87 over the recomputed canonical payload, plus expiry) **without requiring the original content bytes**. Used internally by `verifyFileChain()` for every signer but the latest; exposed directly for callers building their own chain-inspection tooling.
+
+**Returns:** `RevisionCommitmentResult` — a `VerificationResult` with `commitmentOnly: true`.
+
+---
+
 ### Image Stamping (Experimental)
 
 > ⚠️ **These APIs are explicitly marked experimental in source and are not yet API-stable.** Expect breaking changes across minor versions.
@@ -951,18 +1044,18 @@ const restoredFromB64 = MajikSignature.deserialize(b64);
 
 Handlers are tried in order; the first one whose `canHandle()` matches wins. If nothing matches, the **universal trailer fallback** always applies — meaning *every* file type is signable, even ones with no dedicated handler.
 
-| Format(s)                          | Handler        | Embedding Mechanism                                             |
-| ----------------------------------- | -------------- | ----------------------------------------------------------------- |
-| PDF                                 | PDF            | Binary trailer appended after the last `%%EOF` marker (PDF 1.7 §7.5.6 compliant) |
-| PNG                                 | PNG            | `iTXt` metadata chunk                                             |
-| WAV                                 | WAV            | RIFF `LIST INFO` chunk, custom `ISIG` sub-chunk                   |
-| MP3                                 | MP3            | ID3v2 `TXXX` frame                                                 |
-| MP4, MOV, M4A, M4V                  | MP4/MOV        | `moov/udta` box, custom `majk` box type                           |
-| DOCX, XLSX, PPTX, ODT, ODS, ODP     | Office         | Dedicated `majik-signature.json` entry inside the ZIP container   |
-| MKV, WebM                           | MKV            | Custom Matroska metadata tag                                      |
-| JPEG, FLAC                          | JPEG / FLAC    | Native format metadata (non-destructive; same round-trip guarantees as other handlers) |
-| 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"]` |
+| Format(s)                                     | Handler     | Embedding Mechanism                                                                            |
+| --------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
+| PDF                                           | PDF         | Binary trailer appended after the last `%%EOF` marker (PDF 1.7 §7.5.6 compliant)               |
+| PNG                                           | PNG         | `iTXt` metadata chunk                                                                          |
+| WAV                                           | WAV         | RIFF `LIST INFO` chunk, custom `ISIG` sub-chunk                                                |
+| MP3                                           | MP3         | ID3v2 `TXXX` frame                                                                             |
+| MP4, MOV, M4A, M4V                            | MP4/MOV     | `moov/udta` box, custom `majk` box type                                                        |
+| DOCX, XLSX, PPTX, ODT, ODS, ODP               | Office      | Dedicated `majik-signature.json` entry inside the ZIP container                                |
+| MKV, WebM                                     | MKV         | Custom Matroska metadata tag                                                                   |
+| JPEG, FLAC                                    | JPEG / FLAC | Native format metadata (non-destructive; same round-trip guarantees as other handlers)         |
+| 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 (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.
 
@@ -986,11 +1079,13 @@ A single signer's envelope (`MajikSignatureJSON`):
   "edSignature": "base64-ed25519-signature-64-bytes",
   "mlDsaSignature": "base64-ml-dsa-87-signature-4595-bytes",
   "allowlistHash": "base64-sha256-of-allowlist-44-chars",
+  "validUntil": "2027-01-01T00:00:00.000Z",
+  "versionChainHash": "base64-sha256-of-version-chain-44-chars",
   "tsa": { "...": "optional MajikTimestamp, see below" }
 }
 ```
 
-`allowlistHash` and `tsa` are only present when applicable — omitted entirely otherwise, never `null`.
+`allowlistHash`, `validUntil`, `versionChainHash`, and `tsa` are only present when applicable — omitted entirely otherwise, never `null`.
 
 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`:
 
@@ -1003,7 +1098,8 @@ What's actually embedded into a file (or produced detached) is a **`MultiSigEnve
   "sealHash": "128-hex-char-sha3-512-hash",
   "sealTimestamp": "2026-01-01T00:00:00.000Z",
   "sealedBy": "fingerprint-of-issuer",
-  "chainAnchors": [ /* MajikChainAnchor[], optional */ ]
+  "chainAnchors": [ /* MajikChainAnchor[], optional */ ],
+  "fileVersions": [ /* FileVersion[], optional — see File Versioning API */ ]
 }
 ```
 
@@ -1030,9 +1126,9 @@ A batch manifest (`MjksMapJSON`, backing `MajikSignatureMap`) is a flat list of
 **Approximate serialized sizes (per signer):**
 
 | Format            | Size   |
-| ------------------ | ------ |
-| JSON (minified)     | ~10 KB |
-| Base64 serialized   | ~14 KB |
+| ----------------- | ------ |
+| JSON (minified)   | ~10 KB |
+| Base64 serialized | ~14 KB |
 
 The dominant contributor is `mlDsaSignature` (~6 KB base64) and `signerMlDsaPublicKey` (~3.5 KB base64) — the inherent cost of post-quantum signatures, negligible relative to any real content being signed.
 
@@ -1044,10 +1140,10 @@ Two dedicated, versioned, self-identifying binary containers exist for out-of-ba
 
 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` |
+| 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.
 
@@ -1074,14 +1170,14 @@ const isMjksmap = await MajikSignatureMap.isMJKSMAP(mapBlob);
 
 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 (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`), 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. |
+| Error Class                        | Thrown when...                                                                                                                                                                                 |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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`), 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.).
 
@@ -1105,6 +1201,7 @@ Order and batch verification methods follow the same philosophy: `SignatureOrder
 - **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
+- **Revision chain integrity** — a signer's `versionChainHash` commits to the exact `fileVersions` state as of their turn; rewriting any earlier revision's metadata (even without touching content bytes) is detectable via `verifyFileChain()`, without needing archived copies of earlier revisions.
 
 ### What is Your Responsibility
 
@@ -1114,6 +1211,7 @@ Order and batch verification methods follow the same philosophy: `SignatureOrder
 - **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()`.
+- **Revision archival, if full proof is needed** — `verifyFileChain()` proves every signer's commitment is genuine and the chain hasn't been rewritten, self-contained from the final file alone. It cannot independently prove an earlier `contentHash` ever corresponded to real bytes — that requires `verifyFileRevisions()` against retained copies of each revision, which your application is responsible for archiving if that stronger guarantee matters to your workflow.
 
 ### What NOT to Do
 

package/dist/core/constants.js

@@ -47,7 +47,7 @@ export const CONTENT_HASH_B64_LEN = 44; // SHA-256 → always 44 chars base64
  * Allowlist hash is also a SHA-256 output — identical length to CONTENT_HASH_B64_LEN.
  * Defined separately for clarity at validation call sites.
  */
-export const ALLOWLIST_HASH_B64_LEN = CONTENT_HASH_B64_LEN; // 44 chars
+export const ALLOWLIST_HASH_B64_LEN = 44; // 44 chars
 /**
  * Seal hash is SHA3-512 → 64 bytes → 128 hex chars.
  * Distinct from SHA-256 hashes — longer length makes tampering obvious at a glance.

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

@@ -21,7 +21,7 @@
  * extract/strip → delegate to the envelope class → re-embed.
  */
 import type { ISODateString, MajikKey } from "@majikah/majik-key";
-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 type { BatchFileInput, BatchSignOptions, BatchSignResult, BatchVerifyInput, BatchVerifyOptions, BatchVerifySummary, EmbedOptions, EmbedResult, EnvelopeInfo, ExpectedSigner, ExtractOptions, ExtractResult, FileChainVerification, FileLike, FileVerifyResult, MajikSignatureEnvelopeJSON, MajikSignatureJSON, MajikSignerPublicKeys, MajikTimestamp, RevisionSetVerification, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignOptions, VerificationResult } from "../../core/types";
 import { MajikSignatureEnvelope } from "../../core/envelope";
 import { FormatHandlerRegistry } from "./registry";
 import { MajikChainAnchor } from "../../anchor/types";
@@ -39,8 +39,11 @@ export interface MajikSignatureAdapter {
 export interface MajikSignatureStaticAdapter {
     sign(content: Uint8Array | string, key: MajikKey, options?: SignOptions & {
         allowlistHash?: string;
+        versionChainHash?: string;
     }): Promise<MajikSignatureAdapter>;
     verify(content: Uint8Array | string, signature: MajikSignatureAdapter | MajikSignatureJSON, publicKeys: MajikSignerPublicKeys, now?: Date): VerificationResult;
+    /** Commitment-only check — no content bytes required. See MajikSignature.verifyCommitment. */
+    verifyCommitment(signature: MajikSignatureAdapter | MajikSignatureJSON, publicKeys: MajikSignerPublicKeys, now?: Date): VerificationResult;
     publicKeysFromMajikKey(key: MajikKey): MajikSignerPublicKeys;
     fromJSON(json: MajikSignatureJSON | string): MajikSignatureAdapter;
 }
@@ -71,12 +74,18 @@ export declare class MajikSignatureEmbed {
         contentType?: string;
         timestamp?: ISODateString;
         expectedSigners?: ExpectedSigner[];
-        /** ISO 8601 expiry for this signature. Omit for one that never expires. */
         validUntil?: ISODateString;
+        message?: string;
+        /** The file as received, BEFORE this signer's own stamp. Presence of
+         *  this option is what makes this call a revision (2nd signer+) rather
+         *  than a fresh signature. */
+        priorSignedFile?: Blob;
     }, debug?: boolean): Promise<EmbedResult & {
         signature: T;
         envelope: MajikSignatureEnvelope;
     }>;
+    private static _readAndVerifyPriorEnvelope;
+    private static _verifyEnvelopeSelfContained;
     /**
      * Sign a file and return the envelope detached, along with the specific
      * signature just produced.
@@ -200,6 +209,13 @@ export declare class MajikSignatureEmbed {
      * (instance, JSON, MJKSIG bytes, or Blob).
      */
     static verifyDetachedOrder(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob, expectedOrder: readonly (MajikKey | ExpectedSigner)[], MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & VerifySignatureOrderOptions): Promise<SignatureOrderResult>;
+    static verifyFileChain(file: Blob, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
+        now?: Date;
+    }): Promise<FileChainVerification>;
+    static verifyFileRevisions(finalFile: Blob, revisions: FileLike[], MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
+        now?: Date;
+        resolvePublicKeys?: (signerId: string) => MajikSignerPublicKeys | Promise<MajikSignerPublicKeys>;
+    }): Promise<RevisionSetVerification>;
     /**
      * 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

@@ -22,7 +22,7 @@
  */
 import { MajikSignatureEnvelope } from "../../core/envelope";
 import { FormatHandlerRegistry } from "./registry";
-import { blobToBytes, bytesToBlob, detectMimeType } from "./utils";
+import { blobToBytes, bytesToBlob, detectMimeType, normalizeToBlob, normalizeToBytes, } from "./utils";
 import { PdfHandler } from "./handlers/pdf";
 import { PngHandler } from "./handlers/png";
 import { JpegHandler } from "./handlers/jpeg";
@@ -34,7 +34,7 @@ import { MkvHandler } from "./handlers/mkv";
 import { OfficeHandler } from "./handlers/office";
 import { TextHandler } from "./handlers/text";
 import { FallbackHandler } from "./fallback";
-import { bytesToBase64, hashContent } from "../hash";
+import { base64ToBytes, bytesToBase64, hashContent } from "../hash";
 import { MajikSignatureError, MajikSignatureValidationError } from "../errors";
 import { MajikSignatureMap } from "../mjksmap";
 import { verifySignatureOrder, } from "../order";
@@ -90,35 +90,47 @@ export class MajikSignatureEmbed {
      */
     static async signAndEmbed(file, key, MajikSig, options, debug = false) {
         const { bytes, mimeType, handler } = await MajikSignatureEmbed._prepare(file, options);
-        const envelope = await MajikSignatureEmbed._readEnvelope(handler, bytes);
-        // ── Sealed + allowlist gate (throws before any crypto) ──────────────────
+        const envelope = options?.priorSignedFile
+            ? await MajikSignatureEmbed._readAndVerifyPriorEnvelope(options.priorSignedFile, MajikSig, debug)
+            : await MajikSignatureEmbed._readEnvelope(handler, bytes);
         envelope.assertCanSign(key);
-        // ── Clean original bytes ─────────────────────────────────────────────────
         const originalBytes = await handler.strip(bytes);
-        if (debug) {
-            console.log("signAndEmbed — original bytes hash:", bytesToBase64(hashContent(originalBytes)));
-        }
-        // ── Resolve allowlistHash for this signer's payload ──────────────────────
+        if (debug)
+            console.log("signAndEmbed — bytes hash:", bytesToBase64(hashContent(originalBytes)));
         const allowlistHashValue = envelope.resolveAllowlistHashFor(key, options?.expectedSigners);
-        // ── Sign ──────────────────────────────────────────────────────────────────
+        const lastVersion = envelope.lastFileVersion;
+        const newVersionEntry = {
+            version: lastVersion ? lastVersion.version + 1 : 1,
+            timestamp: options?.timestamp ?? new Date().toISOString(),
+            contentHash: bytesToBase64(hashContent(originalBytes)),
+            ...(lastVersion
+                ? {
+                    previousVersionHash: MajikSignatureEnvelope.hashFileVersionEntry(lastVersion),
+                }
+                : {}),
+            createdBy: key.fingerprint,
+            ...(options?.message ? { message: options.message } : {}),
+        };
+        const versionChainHash = MajikSignatureEnvelope.hashFileVersionChain([
+            ...envelope.fileVersions,
+            newVersionEntry,
+        ]);
         const signature = await MajikSig.sign(originalBytes, key, {
             contentType: options?.contentType,
-            timestamp: options?.timestamp,
+            timestamp: newVersionEntry.timestamp,
             validUntil: options?.validUntil,
+            versionChainHash,
             ...(allowlistHashValue !== undefined
                 ? { allowlistHash: allowlistHashValue }
                 : {}),
         });
-        // ── Attach allowlist FIRST (requires zero signatures), then upsert ───────
-        // NOTE: withAllowlist() enforces "first signer only" by checking the
-        // envelope's current signature count. It must run before withSignature()
-        // adds this signer's entry, or the guard trips on the count it just added.
         const establishingAllowlist = envelope.isFirstSigner() && !!options?.expectedSigners?.length;
         const envelopeWithAllowlist = establishingAllowlist
             ? envelope.withAllowlist(options.expectedSigners, key.fingerprint)
             : envelope;
-        const nextEnvelope = envelopeWithAllowlist.withSignature(signature.toJSON());
-        // ── Embed ─────────────────────────────────────────────────────────────────
+        const nextEnvelope = envelopeWithAllowlist
+            .withFileVersion(newVersionEntry)
+            .withSignature(signature.toJSON());
         const resultBytes = await handler.embed(originalBytes, JSON.stringify(nextEnvelope.toJSON()));
         const blob = bytesToBlob(resultBytes, mimeType);
         return {
@@ -129,6 +141,118 @@ export class MajikSignatureEmbed {
             envelope: nextEnvelope,
         };
     }
+    // ── Private: read prior file's envelope, verify it fully, bootstrap chain ──
+    static async _readAndVerifyPriorEnvelope(priorFile, MajikSig, debug) {
+        const { bytes: priorBytes, handler: priorHandler } = await MajikSignatureEmbed._prepare(priorFile);
+        const raw = await priorHandler.extract(priorBytes);
+        if (!raw) {
+            throw new MajikSignatureError("priorSignedFile has no embedded signature envelope.");
+        }
+        let envelope = MajikSignatureEnvelope.fromJSON(raw);
+        const allowlistIntegrity = envelope.verifyAllowlistIntegrity();
+        if (!allowlistIntegrity.valid) {
+            throw new MajikSignatureError(`priorSignedFile allowlist integrity failed: ${allowlistIntegrity.reason}`);
+        }
+        const chainIntegrity = envelope.verifyVersionChainIntegrity();
+        if (!chainIntegrity.valid) {
+            throw new MajikSignatureError(`priorSignedFile version chain integrity failed: ${chainIntegrity.reason}`);
+        }
+        const priorStrippedBytes = await priorHandler.strip(priorBytes);
+        const { ok, latest, history } = MajikSignatureEmbed._verifyEnvelopeSelfContained(envelope, priorStrippedBytes, MajikSig);
+        if (!ok) {
+            const failed = [latest, ...history].find((r) => !r.valid);
+            throw new MajikSignatureError(`Refusing to build on priorSignedFile — signature by "${failed?.signerId}" is invalid: ${failed?.reason}`);
+        }
+        // Bootstrap fileVersions[0] for files signed before this feature existed.
+        if (envelope.fileVersions.length === 0 && envelope.signatures.length > 0) {
+            const firstSig = envelope.signatures[0];
+            envelope = envelope.withFileVersion({
+                version: 1,
+                timestamp: firstSig.timestamp,
+                contentHash: bytesToBase64(hashContent(priorStrippedBytes)),
+                createdBy: firstSig.signerId,
+            });
+        }
+        if (debug)
+            console.log("priorSignedFile bytes hash:", bytesToBase64(hashContent(priorStrippedBytes)));
+        return envelope;
+    }
+    static _verifyEnvelopeSelfContained(envelope, currentStrippedBytes, MajikSig, now) {
+        const chain = envelope.fileVersions;
+        const currentHash = bytesToBase64(hashContent(currentStrippedBytes));
+        const fullChainHash = MajikSignatureEnvelope.hashFileVersionChain(chain);
+        let latestSig = envelope.signatures.find((s) => s.contentHash === currentHash && s.versionChainHash === fullChainHash);
+        if (!latestSig) {
+            // Fallback for pre-feature files
+            latestSig = envelope.signatures.find((s) => s.contentHash === currentHash);
+        }
+        const checkChainHash = (sig) => {
+            if (sig.versionChainHash === undefined && chain.length === 0)
+                return { ok: true }; // pre-feature file
+            const idx = chain.findIndex((v, i) => v.contentHash === sig.contentHash &&
+                (sig.versionChainHash
+                    ? MajikSignatureEnvelope.hashFileVersionChain(chain.slice(0, i + 1)) === sig.versionChainHash
+                    : true));
+            if (idx === -1)
+                return {
+                    ok: false,
+                    reason: "No fileVersions entry matches this signature's state.",
+                };
+            const expected = MajikSignatureEnvelope.hashFileVersionChain(chain.slice(0, idx + 1));
+            return sig.versionChainHash === undefined ||
+                sig.versionChainHash === expected
+                ? { ok: true }
+                : {
+                    ok: false,
+                    reason: "versionChainHash does not match the recomputed chain prefix — chain may be tampered.",
+                };
+        };
+        const publicKeysOf = (sig) => ({
+            signerId: sig.signerId,
+            edPublicKey: base64ToBytes(sig.signerEdPublicKey),
+            mlDsaPublicKey: base64ToBytes(sig.signerMlDsaPublicKey),
+        });
+        let latest;
+        if (!latestSig) {
+            latest = {
+                valid: false,
+                reason: "No signature's contentHash matches the current bytes.",
+                timestamp: new Date().toISOString(),
+            };
+        }
+        else {
+            const chainCheck = checkChainHash(latestSig);
+            latest = chainCheck.ok
+                ? MajikSig.verify(currentStrippedBytes, latestSig, publicKeysOf(latestSig), now)
+                : {
+                    valid: false,
+                    signerId: latestSig.signerId,
+                    contentHash: latestSig.contentHash,
+                    timestamp: latestSig.timestamp,
+                    reason: chainCheck.reason,
+                };
+        }
+        const history = envelope.signatures
+            .filter((s) => s !== latestSig)
+            .map((sig) => {
+            const chainCheck = checkChainHash(sig);
+            const result = chainCheck.ok
+                ? MajikSig.verifyCommitment(sig, publicKeysOf(sig), now)
+                : {
+                    valid: false,
+                    signerId: sig.signerId,
+                    contentHash: sig.contentHash,
+                    timestamp: sig.timestamp,
+                    reason: chainCheck.reason,
+                };
+            return { ...result, commitmentOnly: true };
+        });
+        return {
+            latest,
+            history,
+            ok: latest.valid && history.every((h) => h.valid),
+        };
+    }
     // ── signDetached ───────────────────────────────────────────────────────────
     /**
      * Sign a file and return the envelope detached, along with the specific
@@ -513,6 +637,106 @@ export class MajikSignatureEmbed {
         const originalBytes = await handler.strip(bytes);
         return verifySignatureOrder(envelope, originalBytes, expectedOrder, (content, sig, pk) => MajikSig.verify(content, sig, pk), { strict: options?.strict });
     }
+    static async verifyFileChain(file, MajikSig, options) {
+        const { bytes, handler } = await MajikSignatureEmbed._prepare(file, options);
+        const raw = await handler.extract(bytes);
+        if (!raw)
+            throw new MajikSignatureError("Cannot verify chain — no embedded envelope found.");
+        const envelope = MajikSignatureEnvelope.fromJSON(raw);
+        const originalBytes = await handler.strip(bytes);
+        const allowlistIntegrity = envelope.verifyAllowlistIntegrity();
+        const chainIntegrity = envelope.verifyVersionChainIntegrity();
+        const { latest, history, ok } = MajikSignatureEmbed._verifyEnvelopeSelfContained(envelope, originalBytes, MajikSig, options?.now);
+        const chainValid = allowlistIntegrity.valid && chainIntegrity.valid && ok;
+        return { latest, history, chainValid };
+    }
+    static async verifyFileRevisions(finalFile, revisions, MajikSig, options) {
+        const { bytes, handler } = await MajikSignatureEmbed._prepare(finalFile, options);
+        const raw = await handler.extract(bytes);
+        if (!raw)
+            throw new MajikSignatureError("Cannot verify revisions — no embedded envelope found.");
+        const envelope = MajikSignatureEnvelope.fromJSON(raw);
+        const chain = envelope.fileVersions;
+        if (chain.length === 0) {
+            throw new MajikSignatureError("This file has no fileVersions chain to verify against.");
+        }
+        // Normalize + strip every supplied revision up front. Include finalFile
+        // to ensure the final state is naturally matchable without forcing
+        // the caller to pass it twice.
+        const normalized = await Promise.all([...revisions, finalFile].map(async (input) => {
+            const revBlob = normalizeToBlob(await normalizeToBytes(input));
+            const { bytes: rBytes, handler: rHandler } = await MajikSignatureEmbed._prepare(revBlob);
+            const stripped = await rHandler.strip(rBytes);
+            return { stripped, contentHash: bytesToBase64(hashContent(stripped)) };
+        }));
+        const results = [];
+        for (let i = 0; i < chain.length; i++) {
+            const entry = chain[i];
+            const match = normalized.find((r) => r.contentHash === entry.contentHash);
+            if (!match) {
+                results.push({
+                    version: entry.version,
+                    status: "unmatched",
+                    reason: `No supplied file matches fileVersions[${i}].`,
+                });
+                continue;
+            }
+            const expectedPrev = i === 0
+                ? undefined
+                : MajikSignatureEnvelope.hashFileVersionEntry(chain[i - 1]);
+            if (entry.previousVersionHash !== expectedPrev) {
+                results.push({
+                    version: entry.version,
+                    status: "chain_broken",
+                    reason: `fileVersions[${i}] does not chain onto the prior entry.`,
+                });
+                continue;
+            }
+            const expectedChainHash = MajikSignatureEnvelope.hashFileVersionChain(chain.slice(0, i + 1));
+            const sig = envelope.signatures.find((s) => s.contentHash === entry.contentHash &&
+                (entry.createdBy ? s.signerId === entry.createdBy : true) &&
+                (s.versionChainHash
+                    ? s.versionChainHash === expectedChainHash
+                    : true));
+            if (!sig) {
+                results.push({
+                    version: entry.version,
+                    status: "unmatched",
+                    reason: `No signature matches fileVersions[${i}].`,
+                });
+                continue;
+            }
+            if (sig.versionChainHash && sig.versionChainHash !== expectedChainHash) {
+                results.push({
+                    version: entry.version,
+                    status: "chain_broken",
+                    signerId: sig.signerId,
+                    reason: "versionChainHash does not match this revision's chain state.",
+                });
+                continue;
+            }
+            const publicKeys = options?.resolvePublicKeys
+                ? await options.resolvePublicKeys(sig.signerId)
+                : {
+                    signerId: sig.signerId,
+                    edPublicKey: base64ToBytes(sig.signerEdPublicKey),
+                    mlDsaPublicKey: base64ToBytes(sig.signerMlDsaPublicKey),
+                };
+            const verifyResult = MajikSig.verify(match.stripped, sig, publicKeys, options?.now);
+            results.push({
+                version: entry.version,
+                status: verifyResult.valid ? "verified" : "signature_invalid",
+                signerId: sig.signerId,
+                reason: verifyResult.reason,
+            });
+        }
+        return {
+            allValid: results.length === chain.length &&
+                results.every((r) => r.status === "verified"),
+            isCompleteSet: results.every((r) => r.status !== "unmatched"),
+            results,
+        };
+    }
     // ── seal ───────────────────────────────────────────────────────────────────
     /**
      * Seal a multi-sig envelope, preventing any further signatures.

package/dist/core/embed/utils.d.ts

@@ -1,6 +1,10 @@
 /**
  * utils.ts — Byte manipulation, MIME sniffing, and encoding helpers
  */
+import { FileLike } from "../types";
+/** Normalize any supported input into raw bytes, defensively copied. */
+export declare function normalizeToBytes(input: FileLike): Promise<Uint8Array>;
+export declare function normalizeToBlob(input: FileLike, mimeType?: string): Blob;
 export declare function textEncode(str: string): Uint8Array;
 export declare function textDecode(bytes: Uint8Array): string;
 export declare function concatBytes(...arrays: Uint8Array[]): Uint8Array;

package/dist/core/embed/utils.js

@@ -1,7 +1,27 @@
 /**
  * utils.ts — Byte manipulation, MIME sniffing, and encoding helpers
  */
+import { MajikSignatureValidationError } from "../errors";
 import { CANONICAL_MTIME, TRAILER_MAGIC, TRAILER_SUFFIX_LENGTH, } from "./constants";
+/** Normalize any supported input into raw bytes, defensively copied. */
+export async function normalizeToBytes(input) {
+    if (input instanceof Uint8Array)
+        return input.slice();
+    if (input instanceof ArrayBuffer)
+        return new Uint8Array(input.slice(0));
+    if (input instanceof Blob)
+        return blobToBytes(input); // File extends Blob
+    throw new MajikSignatureValidationError("Unsupported file input — expected Blob, File, Uint8Array, or ArrayBuffer.", "input");
+}
+export function normalizeToBlob(input, mimeType = "application/octet-stream") {
+    if (input instanceof Blob)
+        return input;
+    if (input instanceof Uint8Array)
+        return bytesToBlob(input, mimeType);
+    if (input instanceof ArrayBuffer)
+        return bytesToBlob(new Uint8Array(input), mimeType);
+    throw new MajikSignatureValidationError("Unsupported file input — expected Blob, File, Uint8Array, or ArrayBuffer.", "input");
+}
 // ─── Encoding ─────────────────────────────────────────────────────────────────
 export function textEncode(str) {
     return new TextEncoder().encode(str);

package/dist/core/envelope.d.ts

@@ -18,7 +18,7 @@
  *     counterpart — same relationship as MajikSignatureJSON / MajikSignature.
  */
 import type { MajikKey } from "@majikah/majik-key";
-import type { EnvelopeInfo, ExpectedSigner, MajikSignatureEnvelopeJSON, MajikSignatureJSON, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignatoryInfo } from "./types";
+import type { EnvelopeInfo, ExpectedSigner, FileVersion, MajikSignatureEnvelopeJSON, MajikSignatureJSON, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignatoryInfo } from "./types";
 import type { MajikChainAnchor } from "../anchor/types";
 export type AllowlistCheckResult = {
     permitted: true;
@@ -45,6 +45,7 @@ export declare class MajikSignatureEnvelope {
     private readonly _sealTimestamp?;
     private readonly _sealedBy?;
     private readonly _chainAnchors?;
+    private readonly _fileVersions?;
     private constructor();
     get version(): 1;
     get signatures(): readonly MajikSignatureJSON[];
@@ -54,6 +55,22 @@ export declare class MajikSignatureEnvelope {
     get sealTimestamp(): string | undefined;
     get sealedBy(): string | undefined;
     get chainAnchors(): readonly MajikChainAnchor[];
+    get fileVersions(): readonly FileVersion[];
+    get lastFileVersion(): FileVersion | undefined;
+    static hashFileVersionEntry(entry: FileVersion): string;
+    static hashFileVersionChain(chain: readonly FileVersion[]): string;
+    /**
+     * Append a new revision entry. Immutable. Validates the entry chains
+     * correctly onto the current last entry (sequential version number,
+     * previousVersionHash matching the prior entry's hash) before accepting
+     * it — a broken chain fails loudly here, not silently later.
+     */
+    withFileVersion(entry: FileVersion): MajikSignatureEnvelope;
+    /** Structural chain-linkage check — does not touch any signature. */
+    verifyVersionChainIntegrity(): {
+        valid: boolean;
+        reason?: string;
+    };
     isSealed(): boolean;
     hasAllowlist(): boolean;
     isFirstSigner(): boolean;

package/dist/core/envelope.js

@@ -32,6 +32,7 @@ export class MajikSignatureEnvelope {
     _sealTimestamp;
     _sealedBy;
     _chainAnchors;
+    _fileVersions;
     constructor(data) {
         this._version = data.version;
         this._signatures = data.signatures;
@@ -41,6 +42,7 @@ export class MajikSignatureEnvelope {
         this._sealTimestamp = data.sealTimestamp;
         this._sealedBy = data.sealedBy;
         this._chainAnchors = data.chainAnchors;
+        this._fileVersions = data.fileVersions;
     }
     // ── Getters ─────────────────────────────────────────────────────────────────
     get version() {
@@ -67,6 +69,78 @@ export class MajikSignatureEnvelope {
     get chainAnchors() {
         return this._chainAnchors ?? [];
     }
+    get fileVersions() {
+        return this._fileVersions ?? [];
+    }
+    get lastFileVersion() {
+        return this._fileVersions?.[this._fileVersions.length - 1];
+    }
+    // ── Version chain hashing ────────────────────────────────────────────────
+    static hashFileVersionEntry(entry) {
+        return bytesToBase64(hashContent(JSON.stringify(entry)));
+    }
+    static hashFileVersionChain(chain) {
+        return bytesToBase64(hashContent(JSON.stringify(chain)));
+    }
+    /**
+     * Append a new revision entry. Immutable. Validates the entry chains
+     * correctly onto the current last entry (sequential version number,
+     * previousVersionHash matching the prior entry's hash) before accepting
+     * it — a broken chain fails loudly here, not silently later.
+     */
+    withFileVersion(entry) {
+        if (this.isSealed()) {
+            throw new MajikSignatureError("Cannot add a file version to a sealed envelope.");
+        }
+        const chain = this._fileVersions ?? [];
+        const last = chain[chain.length - 1];
+        const expectedVersion = last ? last.version + 1 : 1;
+        if (entry.version !== expectedVersion) {
+            throw new MajikSignatureValidationError(`FileVersion.version must be ${expectedVersion}, got ${entry.version}`, "version");
+        }
+        const expectedPrevHash = last
+            ? MajikSignatureEnvelope.hashFileVersionEntry(last)
+            : undefined;
+        if (entry.previousVersionHash !== expectedPrevHash) {
+            throw new MajikSignatureValidationError("FileVersion.previousVersionHash does not chain onto the current last entry.", "previousVersionHash");
+        }
+        return new MajikSignatureEnvelope({
+            ...this.toJSON(),
+            fileVersions: [...chain, entry],
+        });
+    }
+    /** Structural chain-linkage check — does not touch any signature. */
+    verifyVersionChainIntegrity() {
+        const chain = this._fileVersions;
+        if (!chain || chain.length === 0)
+            return { valid: true };
+        for (let i = 0; i < chain.length; i++) {
+            const entry = chain[i];
+            if (entry.version !== i + 1) {
+                return {
+                    valid: false,
+                    reason: `fileVersions[${i}].version is ${entry.version}, expected ${i + 1}`,
+                };
+            }
+            if (i === 0) {
+                if (entry.previousVersionHash !== undefined) {
+                    return {
+                        valid: false,
+                        reason: "fileVersions[0] must not have a previousVersionHash",
+                    };
+                }
+                continue;
+            }
+            const expectedPrev = MajikSignatureEnvelope.hashFileVersionEntry(chain[i - 1]);
+            if (entry.previousVersionHash !== expectedPrev) {
+                return {
+                    valid: false,
+                    reason: `fileVersions[${i}].previousVersionHash mismatch`,
+                };
+            }
+        }
+        return { valid: true };
+    }
     // ── State predicates ─────────────────────────────────────────────────────────
     isSealed() {
         return this._sealHash !== undefined;
@@ -462,6 +536,7 @@ export class MajikSignatureEnvelope {
             ...(this._sealTimestamp ? { sealTimestamp: this._sealTimestamp } : {}),
             ...(this._sealedBy ? { sealedBy: this._sealedBy } : {}),
             ...(this._chainAnchors ? { chainAnchors: [...this._chainAnchors] } : {}),
+            ...(this._fileVersions ? { fileVersions: [...this._fileVersions] } : {}),
         };
     }
     serialize() {
@@ -727,6 +802,13 @@ export class MajikSignatureEnvelope {
         if (obj.chainAnchors !== undefined && !Array.isArray(obj.chainAnchors)) {
             throw new MajikSignatureValidationError("chainAnchors must be an array when present", "chainAnchors");
         }
+        const hasFileVersions = obj.fileVersions !== undefined;
+        if (hasFileVersions) {
+            const typedFileVersion = obj.fileVersions;
+            if (!Array.isArray(typedFileVersion)) {
+                throw new MajikSignatureValidationError("fileVersions must be an array when present", "fileVersions");
+            }
+        }
     }
     static #validateSignatureEntry(sig, index) {
         if (sig === null || typeof sig !== "object") {

package/dist/core/payload.d.ts

@@ -5,34 +5,14 @@
  *
  * Both Ed25519 and ML-DSA-87 sign the SAME payload bytes.
  * The payload encodes: version, signerId, timestamp, contentType, contentHash,
- * and — when an allowlist is being established — allowlistHash.
+ * and — when an allowlist is being established — allowlistHash, and validUntil
  *
- * Format:
- *   "majik-signature-v1:" + JSON.stringify({ v, id, ts, ct, hash[, alh] })
- *
- * where:
- *   v    — envelope version (integer)
- *   id   — signer fingerprint (string)
- *   ts   — ISO 8601 timestamp (string)
- *   ct   — content type or null
- *   hash — SHA-256 of original content, base64 (string)
- *   alh  — SHA-256 of canonical allowlist JSON, base64 (string) — OMITTED when
- *           not set. Omitting preserves byte-identical payloads for all signatures
- *           made before allowlist support was introduced (backward compat).
- *
- * The domain prefix prevents cross-protocol misuse.
- * JSON key order is fixed — same input always produces same bytes.
- *
- * Backward compatibility rule:
- *   `alh` is only included in the JSON when allowlistHash is explicitly provided.
- *   When absent it is NOT defaulted to null — omitting it entirely keeps the
- *   payload bytes identical to what pre-multi-sig signers produced, so all
- *   existing signatures continue to verify correctly.
  */
+import { ISODateString, MajikKeyFingerprint } from "@majikah/majik-key";
 import { MajikTSAPayload } from "./types";
 export interface PayloadFields {
-    signerId: string;
-    timestamp: string;
+    signerId: MajikKeyFingerprint;
+    timestamp: ISODateString;
     contentHash: string;
     contentType?: string;
     /**
@@ -41,7 +21,8 @@ export interface PayloadFields {
      * Must be omitted entirely (not null) for all other signatures.
      */
     allowlistHash?: string;
-    validUntil?: string;
+    validUntil?: ISODateString;
+    versionChainHash?: string;
 }
 /**
  * Build the canonical byte payload that both algorithms sign and verify.

package/dist/core/payload.js

@@ -5,29 +5,8 @@
  *
  * Both Ed25519 and ML-DSA-87 sign the SAME payload bytes.
  * The payload encodes: version, signerId, timestamp, contentType, contentHash,
- * and — when an allowlist is being established — allowlistHash.
+ * and — when an allowlist is being established — allowlistHash, and validUntil
  *
- * Format:
- *   "majik-signature-v1:" + JSON.stringify({ v, id, ts, ct, hash[, alh] })
- *
- * where:
- *   v    — envelope version (integer)
- *   id   — signer fingerprint (string)
- *   ts   — ISO 8601 timestamp (string)
- *   ct   — content type or null
- *   hash — SHA-256 of original content, base64 (string)
- *   alh  — SHA-256 of canonical allowlist JSON, base64 (string) — OMITTED when
- *           not set. Omitting preserves byte-identical payloads for all signatures
- *           made before allowlist support was introduced (backward compat).
- *
- * The domain prefix prevents cross-protocol misuse.
- * JSON key order is fixed — same input always produces same bytes.
- *
- * Backward compatibility rule:
- *   `alh` is only included in the JSON when allowlistHash is explicitly provided.
- *   When absent it is NOT defaulted to null — omitting it entirely keeps the
- *   payload bytes identical to what pre-multi-sig signers produced, so all
- *   existing signatures continue to verify correctly.
  */
 import { MAJIK_SIGNATURE_DOMAIN, MAJIK_SIGNATURE_VERSION, MAJIK_TSA_DOMAIN, } from "./constants";
 /**
@@ -46,14 +25,13 @@ export function buildSigningPayload(fields) {
         ts: fields.timestamp,
         ct: fields.contentType ?? null,
         hash: fields.contentHash,
-        // Conditionally include alh — omitting it entirely preserves byte-identical
-        // payloads for all pre-allowlist signatures (backward compat).
         ...(fields.allowlistHash !== undefined
             ? { alh: fields.allowlistHash }
             : {}),
-        // Conditionally include vu — same reasoning: omit entirely so all
-        // pre-expiry signatures reproduce byte-identical payloads (backward compat).
         ...(fields.validUntil !== undefined ? { vu: fields.validUntil } : {}),
+        ...(fields.versionChainHash !== undefined
+            ? { vch: fields.versionChainHash }
+            : {}),
     });
     const prefix = new TextEncoder().encode(MAJIK_SIGNATURE_DOMAIN);
     const body = new TextEncoder().encode(meta);

package/dist/core/types.d.ts

@@ -49,6 +49,12 @@ export interface MajikSignatureJSON {
      * stripped or extended post-hoc without breaking both signatures.
      */
     validUntil?: ISODateString;
+    /**
+     * SHA-256 of the fileVersions chain as it stood when this signer signed
+     * (i.e. including their own new entry). Covered by the canonical payload,
+     * same treatment as allowlistHash/validUntil — absent, never null.
+     */
+    versionChainHash?: string;
     tsa?: MajikTimestamp;
 }
 export interface MajikTSAPayload {
@@ -83,6 +89,7 @@ export interface MajikSignatureCompactJSON {
     mlDsaSignature: MLDSA87Signature;
     allowlistHash?: string;
     validUntil?: ISODateString;
+    versionChainHash?: string;
 }
 export interface MajikTSARequest {
     digest: {
@@ -155,6 +162,8 @@ export interface MultiSigEnvelope {
      */
     sealedBy?: string;
     chainAnchors?: MajikChainAnchor[];
+    /** Append-only revision chain. Absent on files predating this feature. */
+    fileVersions?: FileVersion[];
 }
 /**
  * Public key material needed to verify a MajikSignature.
@@ -461,3 +470,36 @@ export interface MjksMapResolveResult {
      *  vs. where the map says it was originally signed. */
     originalPath?: string;
 }
+export interface FileVersion {
+    version: number;
+    timestamp: ISODateString;
+    /** SHA-256 of this revision's stripped bytes, base64 */
+    contentHash: string;
+    /** hash of the ENTIRE prior FileVersion entry — absent only on version 1 */
+    previousVersionHash?: string;
+    createdBy?: MajikKeyFingerprint;
+    message?: string;
+}
+export interface RevisionCommitmentResult extends VerificationResult {
+    commitmentOnly: true;
+}
+export interface FileChainVerification {
+    latest: VerificationResult;
+    history: RevisionCommitmentResult[];
+    chainValid: boolean;
+}
+export type FileLike = Blob | File | Uint8Array | ArrayBuffer;
+export type RevisionCheckStatus = "verified" | "unmatched" | "chain_broken" | "signature_invalid";
+export interface RevisionCheckResult {
+    version: number;
+    status: RevisionCheckStatus;
+    signerId?: MajikKeyFingerprint;
+    reason?: string;
+}
+export interface RevisionSetVerification {
+    /** Every fileVersions entry matched a supplied file AND verified. */
+    allValid: boolean;
+    /** The supplied set exactly covers the current fileVersions chain — no gaps. */
+    isCompleteSet: boolean;
+    results: RevisionCheckResult[];
+}

package/dist/majik-signature.d.ts

@@ -4,7 +4,7 @@
  *
  */
 import type { ISODateString, MajikKey, MajikKeyFingerprint } from "@majikah/majik-key";
-import type { BatchFileInput, BatchSignOptions, BatchVerifyInput, BatchVerifyOptions, ED25519Signature, EnvelopeInfo, ExpectedSigner, FileVerifyResult, MajikSignatureCompactJSON, MajikSignatureEnvelopeJSON, MajikSignatureJSON, MajikSignerPublicKeys, MajikTimestamp, MajikTSARequest, MLDSA87Signature, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignatoryInfo, SignOptions, VerificationResult } from "./core/types";
+import type { BatchFileInput, BatchSignOptions, BatchVerifyInput, BatchVerifyOptions, ED25519Signature, EnvelopeInfo, ExpectedSigner, FileChainVerification, FileLike, FileVerifyResult, MajikSignatureCompactJSON, MajikSignatureEnvelopeJSON, MajikSignatureJSON, MajikSignerPublicKeys, MajikTimestamp, MajikTSARequest, MLDSA87Signature, RevisionCommitmentResult, RevisionSetVerification, 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";
@@ -70,6 +70,7 @@ export declare class MajikSignature {
     private readonly _mlDsaSignature;
     private readonly _allowlistHash?;
     private readonly _validUntil?;
+    private readonly _versionChainHash?;
     private _tsa?;
     private constructor();
     get version(): 1;
@@ -93,6 +94,7 @@ export declare class MajikSignature {
      * for every signature created before expiry support existed.
      */
     get validUntil(): ISODateString | undefined;
+    get versionChainHash(): string | undefined;
     get tsa(): MajikTimestamp | undefined;
     /**
      * Structural expiry check against this signature's validUntil — does NOT
@@ -116,6 +118,7 @@ export declare class MajikSignature {
      */
     static sign(content: Uint8Array | string, key: MajikKey, options?: SignOptions & {
         allowlistHash?: string;
+        versionChainHash?: string;
     }, debug?: boolean): Promise<MajikSignature>;
     /**
      * Verify a MajikSignature against content and the signer's public keys.
@@ -134,6 +137,7 @@ export declare class MajikSignature {
      *   otherwise.
      */
     static verify(content: Uint8Array | string, signature: MajikSignature | MajikSignatureJSON, publicKeys: MajikSignerPublicKeys, now?: Date): VerificationResult;
+    static verifyCommitment(signature: MajikSignature | MajikSignatureJSON, publicKeys: MajikSignerPublicKeys, now?: Date): RevisionCommitmentResult;
     validate(): void;
     isValid(): boolean;
     extractPublicKeys(): MajikSignerPublicKeys;
@@ -185,6 +189,8 @@ export declare class MajikSignature {
         mimeType?: string;
         expectedSigners?: ExpectedSigner[];
         validUntil?: string;
+        message?: string;
+        priorSignedFile?: Blob;
     }): ReturnType<typeof MajikSignatureEmbed.signAndEmbed<MajikSignature>>;
     /**
      * Sign a file and return the signature envelope detached.
@@ -312,6 +318,15 @@ export declare class MajikSignature {
         mimeType?: string;
         strict?: boolean;
     }): Promise<SignatureOrderResult>;
+    static verifyFileChain(file: Blob, options?: {
+        mimeType?: string;
+        now?: Date;
+    }): Promise<FileChainVerification>;
+    static verifyFileRevisions(finalFile: Blob, revisions: FileLike[], options?: {
+        mimeType?: string;
+        now?: Date;
+        resolvePublicKeys?: (signerId: string) => MajikSignerPublicKeys | Promise<MajikSignerPublicKeys>;
+    }): Promise<RevisionSetVerification>;
     /**
      * Normalize a mixed array of MajikKey instances / ExpectedSigner objects
      * into a plain ExpectedSigner[]. Exposed standalone in case you want to

package/dist/majik-signature.js

@@ -74,6 +74,7 @@ export class MajikSignature {
     _mlDsaSignature;
     _allowlistHash;
     _validUntil;
+    _versionChainHash;
     _tsa;
     constructor(data) {
         this._version = data.version;
@@ -87,6 +88,7 @@ export class MajikSignature {
         this._mlDsaSignature = data.mlDsaSignature;
         this._allowlistHash = data.allowlistHash;
         this._validUntil = data.validUntil;
+        this._versionChainHash = data.versionChainHash;
         this._tsa = data.tsa;
     }
     // ── Getters ─────────────────────────────────────────────────────────────────
@@ -133,6 +135,9 @@ export class MajikSignature {
     get validUntil() {
         return this._validUntil;
     }
+    get versionChainHash() {
+        return this._versionChainHash;
+    }
     get tsa() {
         return this._tsa;
     }
@@ -187,6 +192,7 @@ export class MajikSignature {
             const contentType = options?.contentType;
             const allowlistHash = options?.allowlistHash;
             const validUntil = options?.validUntil; // NEW
+            const versionChainHash = options?.versionChainHash;
             const payload = buildSigningPayload({
                 signerId,
                 timestamp,
@@ -194,6 +200,7 @@ export class MajikSignature {
                 contentType,
                 allowlistHash,
                 validUntil,
+                versionChainHash,
             });
             if (debug)
                 console.log("Signing Payload:", payload);
@@ -215,7 +222,8 @@ export class MajikSignature {
                 edSignature: bytesToBase64(edSigBytes),
                 mlDsaSignature: bytesToBase64(mlDsaSigBytes),
                 ...(allowlistHash !== undefined ? { allowlistHash } : {}),
-                ...(validUntil !== undefined ? { validUntil } : {}), // NEW
+                ...(validUntil !== undefined ? { validUntil } : {}),
+                ...(versionChainHash !== undefined ? { versionChainHash } : {}),
             };
             return new MajikSignature(envelope);
         }
@@ -280,6 +288,7 @@ export class MajikSignature {
                 contentType: env.contentType,
                 allowlistHash: env.allowlistHash,
                 validUntil: env.validUntil,
+                versionChainHash: env.versionChainHash,
             });
             let edOk;
             try {
@@ -323,6 +332,69 @@ export class MajikSignature {
             throw new MajikSignatureVerificationError("Verification failed unexpectedly", err);
         }
     }
+    static verifyCommitment(signature, publicKeys, now = new Date()) {
+        try {
+            MajikSignatureValidator.validateSignerPublicKeys(publicKeys);
+            const env = signature instanceof MajikSignature ? signature.toJSON() : signature;
+            MajikSignatureValidator.validateJSON(env);
+            const invalid = (reason) => ({
+                valid: false,
+                signerId: env.signerId,
+                contentHash: env.contentHash,
+                timestamp: env.timestamp,
+                contentType: env.contentType,
+                commitmentOnly: true,
+                ...(reason ? { reason } : {}),
+            });
+            const payload = buildSigningPayload({
+                signerId: env.signerId,
+                timestamp: env.timestamp,
+                contentHash: env.contentHash,
+                contentType: env.contentType,
+                allowlistHash: env.allowlistHash,
+                validUntil: env.validUntil,
+                versionChainHash: env.versionChainHash,
+            });
+            let edOk;
+            try {
+                edOk = ed25519.verify(publicKeys.edPublicKey, payload, base64ToBytes(env.edSignature));
+            }
+            catch {
+                return invalid("Failed to verify Ed25519 signature");
+            }
+            if (!edOk)
+                return invalid("Invalid Ed25519 signature");
+            let mlDsaOk;
+            try {
+                mlDsaOk = ml_dsa87.verify(base64ToBytes(env.mlDsaSignature), payload, publicKeys.mlDsaPublicKey);
+            }
+            catch {
+                return invalid("Failed to verify ML-DSA-87 signature");
+            }
+            if (!mlDsaOk)
+                return invalid("Invalid ML-DSA-87 signature");
+            if (env.validUntil !== undefined &&
+                now.getTime() > Date.parse(env.validUntil)) {
+                return {
+                    ...invalid(`Signature expired at ${env.validUntil}`),
+                    expired: true,
+                };
+            }
+            return {
+                valid: true,
+                signerId: env.signerId,
+                contentHash: env.contentHash,
+                timestamp: env.timestamp,
+                contentType: env.contentType,
+                commitmentOnly: true,
+            };
+        }
+        catch (err) {
+            if (err instanceof MajikSignatureError)
+                throw err;
+            throw new MajikSignatureVerificationError("Commitment verification failed unexpectedly", err);
+        }
+    }
     // ── SELF-VALIDATE ───────────────────────────────────────────────────────────
     validate() {
         MajikSignatureValidator.validateJSON(this.toJSON());
@@ -370,6 +442,9 @@ export class MajikSignature {
                 ? { validUntil: this._validUntil }
                 : {}),
             ...(this._tsa !== undefined ? { tsa: this._tsa } : {}),
+            ...(this._versionChainHash !== undefined
+                ? { versionChainHash: this._versionChainHash }
+                : {}),
         };
     }
     serialize() {
@@ -475,7 +550,7 @@ export class MajikSignature {
      *   });
      */
     static async signFile(file, key, options) {
-        return await MajikSignatureEmbed.signAndEmbed(file, key, MajikSignature, options);
+        return MajikSignatureEmbed.signAndEmbed(file, key, MajikSignature, options);
     }
     /**
      * Sign a file and return the signature envelope detached.
@@ -605,6 +680,12 @@ export class MajikSignature {
     static async verifyFileDetachedOrder(file, envelope, expectedOrder, options) {
         return MajikSignatureEmbed.verifyDetachedOrder(file, envelope, expectedOrder, MajikSignature, options);
     }
+    static async verifyFileChain(file, options) {
+        return MajikSignatureEmbed.verifyFileChain(file, MajikSignature, options);
+    }
+    static async verifyFileRevisions(finalFile, revisions, options) {
+        return MajikSignatureEmbed.verifyFileRevisions(finalFile, revisions, MajikSignature, options);
+    }
     /**
      * Normalize a mixed array of MajikKey instances / ExpectedSigner objects
      * into a plain ExpectedSigner[]. Exposed standalone in case you want to
@@ -924,6 +1005,7 @@ export class MajikSignature {
             mlDsaSignature: this._mlDsaSignature,
             allowlistHash: this._allowlistHash,
             validUntil: this._validUntil,
+            versionChainHash: this._versionChainHash,
         };
     }
     /**
@@ -952,6 +1034,7 @@ export class MajikSignature {
             mlDsaSignature: compact.mlDsaSignature,
             allowlistHash: compact.allowlistHash,
             validUntil: compact.validUntil,
+            versionChainHash: compact.versionChainHash,
         };
         return MajikSignature.fromJSON(full);
     }

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.9",
+  "version": "0.4.0",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",
@@ -51,15 +51,16 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@majikah/majik-key": "^0.3.4",
-    "@noble/post-quantum": "^0.7.0",
+    "@majikah/majik-key": "^0.4.0",
+    "@noble/hashes": "^2.4.0",
+    "@noble/post-quantum": "^0.7.1",
     "@stablelib/ed25519": "^2.1.0",
     "@stablelib/sha256": "^2.0.1",
     "fflate": "^0.8.3"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.1",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.11"
   }
 }