@majikah/majik-signature 0.2.1 → 0.2.3

package/dist/core/embed/handlers/mp4.js

@@ -42,58 +42,58 @@ export class Mp4Handler {
     async embed(bytes, signatureJson) {
         const clean = await this.strip(bytes);
         const majkBox = this._buildBox(MP4_BOX_TYPE, textEncode(signatureJson));
-        const boxes = this._parseBoxes(clean, 0, clean.length);
+        const { boxes, trailing: topTrailing } = this._parseBoxes(clean, 0, clean.length);
         const moovIdx = boxes.findIndex((b) => b.type === "moov");
         if (moovIdx < 0) {
-            // No moov box — use trailer fallback
             const { appendTrailer } = await import("../utils");
             return appendTrailer(clean, signatureJson);
         }
         const moovBox = boxes[moovIdx];
-        const moovChildren = this._parseBoxes(moovBox.data, 0, moovBox.data.length);
+        const { boxes: moovChildren, trailing: moovTrailing } = this._parseBoxes(moovBox.data, 0, moovBox.data.length);
         const udtaIdx = moovChildren.findIndex((b) => b.type === "udta");
-        let newUdta;
+        const { boxes: existingUdtaChildren, trailing: udtaTrailing } = udtaIdx >= 0
+            ? this._parseBoxes(moovChildren[udtaIdx].data, 0, moovChildren[udtaIdx].data.length)
+            : { boxes: [], trailing: new Uint8Array(0) };
+        const newUdta = this._buildBox("udta", concatBytes(...existingUdtaChildren.map((b) => b.raw), majkBox, // ← box-aligned, right after real children
+        udtaTrailing));
+        const newMoovChildren = [];
         if (udtaIdx >= 0) {
-            const udtaBox = moovChildren[udtaIdx];
-            // Append majk to udta
-            const newUdtaData = concatBytes(udtaBox.data, majkBox);
-            newUdta = this._buildBox("udta", newUdtaData);
+            // Retain the exact original index of the udta box to avoid byte shifting
+            for (let i = 0; i < moovChildren.length; i++) {
+                newMoovChildren.push(i === udtaIdx ? newUdta : moovChildren[i].raw);
+            }
         }
         else {
-            newUdta = this._buildBox("udta", majkBox);
-        }
-        // Rebuild moov
-        const newMoovChildren = [];
-        for (let i = 0; i < moovChildren.length; i++) {
-            if (i === udtaIdx)
-                continue; // skip old udta (we'll add new one)
-            newMoovChildren.push(moovChildren[i].raw);
+            // If it didn't exist previously, it's safe to append it to the end
+            for (let i = 0; i < moovChildren.length; i++) {
+                newMoovChildren.push(moovChildren[i].raw);
+            }
+            newMoovChildren.push(newUdta);
         }
-        newMoovChildren.push(newUdta);
-        const newMoov = this._buildBox("moov", concatBytes(...newMoovChildren));
-        // Rebuild file
+        const newMoov = this._buildBox("moov", concatBytes(...newMoovChildren, moovTrailing));
         const parts = [];
         for (let i = 0; i < boxes.length; i++) {
-            if (i === moovIdx)
-                parts.push(newMoov);
-            else
-                parts.push(boxes[i].raw);
+            parts.push(i === moovIdx ? newMoov : boxes[i].raw);
         }
-        return concatBytes(...parts);
+        return concatBytes(...parts, topTrailing);
     }
     async extract(bytes) {
         if (!this.canHandle(bytes))
             return null;
         try {
-            const boxes = this._parseBoxes(bytes, 0, bytes.length);
+            const { boxes } = this._parseBoxes(bytes, 0, bytes.length);
             const moov = boxes.find((b) => b.type === "moov");
-            if (!moov)
-                return null;
-            const moovChildren = this._parseBoxes(moov.data, 0, moov.data.length);
+            // Fallback: If no moov box exists, check for a Tier-2 trailer
+            if (!moov) {
+                const { extractTrailer } = await import("../utils");
+                const trailer = extractTrailer(bytes);
+                return trailer ? trailer.signatureJson : null;
+            }
+            const { boxes: moovChildren } = this._parseBoxes(moov.data, 0, moov.data.length);
             const udta = moovChildren.find((b) => b.type === "udta");
             if (!udta)
                 return null;
-            const udtaChildren = this._parseBoxes(udta.data, 0, udta.data.length);
+            const { boxes: udtaChildren } = this._parseBoxes(udta.data, 0, udta.data.length);
             const majk = udtaChildren.find((b) => b.type === MP4_BOX_TYPE);
             if (!majk)
                 return null;
@@ -107,32 +107,36 @@ export class Mp4Handler {
         if (!this.canHandle(bytes))
             return bytes;
         try {
-            const boxes = this._parseBoxes(bytes, 0, bytes.length);
+            const { boxes, trailing: topTrailing } = this._parseBoxes(bytes, 0, bytes.length);
             const moovIdx = boxes.findIndex((b) => b.type === "moov");
-            if (moovIdx < 0)
-                return bytes;
+            // Fallback: If no moov box exists, strip the Tier-2 trailer if present
+            if (moovIdx < 0) {
+                const { extractTrailer } = await import("../utils");
+                const trailer = extractTrailer(bytes);
+                return trailer ? trailer.original : bytes;
+            }
             const moovBox = boxes[moovIdx];
-            const moovChildren = this._parseBoxes(moovBox.data, 0, moovBox.data.length);
+            const { boxes: moovChildren, trailing: moovTrailing } = this._parseBoxes(moovBox.data, 0, moovBox.data.length);
             const udtaIdx = moovChildren.findIndex((b) => b.type === "udta");
             if (udtaIdx < 0)
                 return bytes;
             const udtaBox = moovChildren[udtaIdx];
-            const udtaChildren = this._parseBoxes(udtaBox.data, 0, udtaBox.data.length);
+            const { boxes: udtaChildren, trailing: udtaTrailing } = this._parseBoxes(udtaBox.data, 0, udtaBox.data.length);
             const filteredUdta = udtaChildren.filter((b) => b.type !== MP4_BOX_TYPE);
             let newMoovChildren;
-            if (filteredUdta.length === 0) {
-                // Remove udta entirely
+            // Only remove the udta box entirely if it is completely barren of data and trailing bytes
+            if (filteredUdta.length === 0 && udtaTrailing.length === 0) {
                 newMoovChildren = moovChildren
                     .filter((_, i) => i !== udtaIdx)
                     .map((b) => b.raw);
             }
             else {
-                const newUdta = this._buildBox("udta", concatBytes(...filteredUdta.map((b) => b.raw)));
+                const newUdta = this._buildBox("udta", concatBytes(...filteredUdta.map((b) => b.raw), udtaTrailing));
                 newMoovChildren = moovChildren.map((b, i) => i === udtaIdx ? newUdta : b.raw);
             }
-            const newMoov = this._buildBox("moov", concatBytes(...newMoovChildren));
+            const newMoov = this._buildBox("moov", concatBytes(...newMoovChildren, moovTrailing));
             const parts = boxes.map((b, i) => (i === moovIdx ? newMoov : b.raw));
-            return concatBytes(...parts);
+            return concatBytes(...parts, topTrailing);
         }
         catch {
             return bytes;
@@ -146,14 +150,11 @@ export class Mp4Handler {
             let size = readUint32BE(bytes, offset);
             const type = textDecode(bytes.slice(offset + 4, offset + 8));
             if (size === 1) {
-                // 64-bit extended size (large box)
-                // Read as two 32-bit values
                 const hi = readUint32BE(bytes, offset + 8);
                 const lo = readUint32BE(bytes, offset + 12);
                 size = hi * 0x100000000 + lo;
             }
             else if (size === 0) {
-                // Box extends to end of file
                 size = end - offset;
             }
             if (size < 8 || offset + size > end)
@@ -164,7 +165,10 @@ export class Mp4Handler {
             boxes.push({ type, data, raw });
             offset += size;
         }
-        return boxes;
+        // Anything left over (padding, malformed box, unparseable trailing bytes)
+        // — preserve it verbatim instead of silently dropping it.
+        const trailing = bytes.slice(offset, end);
+        return { boxes, trailing };
     }
     _buildBox(type, data) {
         const size = 8 + data.length;

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

@@ -10,17 +10,19 @@
  *
  *   majik-signature → majik-embed → majik-signature  ✗
  *
- * Instead, operations that need MajikSignature receive it via the
- * MajikSignatureStaticAdapter interface — no circular import needed.
+ * Operations that need MajikSignature (signing, verifying) receive it via
+ * the MajikSignatureStaticAdapter interface — no circular import needed.
  *
- * Multi-sig + allowlist + seal:
- * ─────────────────────────────
- * Files embed a MultiSigEnvelope (array of per-signer envelopes + optional
- * allowlist + optional seal). parseEnvelope() transparently promotes old
- * single-sig files — all code here always operates on MultiSigEnvelope.
+ * MajikSignatureEnvelope, by contrast, is pure/structural (no crypto), so it
+ * IS imported directly here — no adapter required for it. All parsing,
+ * validation, allowlist enforcement, seal computation, and signatory/issuer
+ * resolution now live on that class (core/envelope.ts). This file is
+ * reduced to file-format orchestration: read bytes → resolve handler →
+ * extract/strip → delegate to the envelope class → re-embed.
  */
 import type { MajikKey } from "@majikah/majik-key";
-import type { EmbedOptions, EmbedResult, EnvelopeInfo, ExpectedSigner, ExtractOptions, ExtractResult, MajikSignatureJSON, MajikSignerPublicKeys, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignOptions, VerificationResult } from "../../core/types";
+import type { EmbedOptions, EmbedResult, EnvelopeInfo, ExpectedSigner, ExtractOptions, ExtractResult, MajikSignatureEnvelopeJSON, MajikSignatureJSON, MajikSignerPublicKeys, SealInfo, SealVerificationResult, SignatoriesFilter, SignatoriesResult, SignOptions, VerificationResult } from "../../core/types";
+import { MajikSignatureEnvelope } from "../../core/envelope";
 import { FormatHandlerRegistry } from "./registry";
 import { MajikChainAnchor } from "../../anchor/types";
 export interface MajikSignatureAdapter {
@@ -38,7 +40,7 @@ export declare class MajikSignatureEmbed {
     /**
      * Embed a pre-computed signature into a file Blob.
      * Reads any existing envelope, upserts the new signature by signerId,
-     * and writes the updated MultiSigEnvelope back.
+     * and writes the updated envelope back.
      * Does NOT sign — call signAndEmbed() for sign + embed together.
      */
     static embed(file: Blob, signature: MajikSignatureAdapter | MajikSignatureJSON, options?: EmbedOptions): Promise<EmbedResult>;
@@ -46,15 +48,15 @@ export declare class MajikSignatureEmbed {
      * Sign a file and embed the signature in one call.
      *
      * Flow:
-     *   1. Extract existing MultiSigEnvelope (or start fresh)
-     *   2. Reject if envelope is sealed
-     *   3. Enforce allowlist — throw MajikSignatureAllowlistError before any crypto
-     *   4. Strip existing envelope to get clean original bytes
-     *   5. If first signer and options.expectedSigners provided: compute allowlistHash
-     *      to bind the allowlist into the signing payload
-     *   6. Sign the clean bytes (allowlistHash included in payload when present)
-     *   7. Upsert signature into envelope; if establishing allowlist, attach
-     *      allowlist + allowlistSignerId to envelope
+     *   1. Read existing envelope (or start fresh)
+     *   2. assertCanSign() — rejects sealed envelopes and non-allowlisted signers
+     *      before any cryptographic operation (issuer always bypasses)
+     *   3. Strip existing envelope to get clean original bytes
+     *   4. Resolve allowlistHash for this signer (establishing / re-signing / none)
+     *   5. Sign the clean bytes
+     *   6. If establishing an allowlist, attach it BEFORE upserting the signature
+     *      (withAllowlist() requires zero existing signatures — see note below)
+     *   7. Upsert signature into envelope
      *   8. Embed updated envelope back into the file
      */
     static signAndEmbed<T extends MajikSignatureAdapter>(file: Blob, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: EmbedOptions & {
@@ -63,17 +65,31 @@ export declare class MajikSignatureEmbed {
         expectedSigners?: ExpectedSigner[];
     }, debug?: boolean): Promise<EmbedResult & {
         signature: T;
+        envelope: MajikSignatureEnvelope;
     }>;
     /**
-     * Extract the MultiSigEnvelope from a file.
+     * Sign a file and return the envelope detached.
+     * Same flow as signAndEmbed(), minus the final embed step.
+     */
+    static signDetached(file: Blob, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: EmbedOptions & {
+        contentType?: string;
+        timestamp?: string;
+        expectedSigners?: ExpectedSigner[];
+        existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON;
+    }, debug?: boolean): Promise<{
+        blob: Blob;
+        envelope: MajikSignatureEnvelope;
+        handler: string;
+        mimeType: string;
+    }>;
+    /**
+     * Extract the envelope from a file as a MajikSignatureEnvelope instance.
      * Returns null if no signature is found.
-     * Old single-sig files are promoted to MultiSigEnvelope transparently.
      */
     static extract(file: Blob, options?: ExtractOptions): Promise<ExtractResult | null>;
     /**
      * Verify a file's embedded signatures against public keys.
      * Returns one VerificationResult per signature in the envelope.
-     * Old single-sig files return a single-item array.
      */
     static verify(file: Blob, publicKeys: MajikSignerPublicKeys, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
         expectedSignerId?: string;
@@ -81,19 +97,20 @@ export declare class MajikSignatureEmbed {
     static verifyWithKey(file: Blob, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
         expectedSignerId?: string;
     }, debug?: boolean): Promise<VerificationResult[]>;
+    /**
+     * Verify a file against a provided, detached envelope (instance or JSON).
+     * Still strips the file in case it also contains an embedded envelope,
+     * ensuring verification runs against the clean original bytes.
+     */
+    static verifyDetached(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON, publicKeys: MajikSignerPublicKeys, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
+        expectedSignerId?: string;
+    }, debug?: boolean): Promise<VerificationResult[]>;
+    static verifyDetachedWithKey(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
+        expectedSignerId?: string;
+    }, debug?: boolean): Promise<VerificationResult[]>;
     /**
      * Seal a multi-sig envelope, preventing any further signatures.
-     *
-     * Rules:
-     *   - Only the issuer (allowlistSignerId) may seal
-     *   - The envelope must have an allowlist (must be a restricted multi-sig file)
-     *   - The envelope must not already be sealed
-     *   - The key must be unlocked
-     *
-     * The seal hash is SHA3-512 of all current signatories + sealTimestamp,
-     * prefixed with MAJIK_SEAL_DOMAIN. It is stored in the envelope alongside
-     * the sealTimestamp and sealedBy fields. No new cryptographic signature
-     * is produced — the seal is a hash-based integrity lock.
+     * Issuer-only / already-sealed checks are enforced by envelope.withSeal().
      */
     static seal(file: Blob, key: MajikKey, options?: ExtractOptions & {
         timestamp?: string;
@@ -103,94 +120,41 @@ export declare class MajikSignatureEmbed {
         handler: string;
         mimeType: string;
     }>;
-    /**
-     * Verify the seal hash against the current signatories and sealTimestamp.
-     * Returns invalid if the envelope is not sealed.
-     * Does NOT verify the individual cryptographic signatures — call verify() for that.
-     */
     static verifySeal(file: Blob, options?: ExtractOptions): Promise<SealVerificationResult>;
-    /**
-     * Return seal metadata without verifying.
-     * Returns null if the envelope is not sealed or has no envelope.
-     */
     static getSealInfo(file: Blob, options?: ExtractOptions): Promise<SealInfo | null>;
-    /**
-     * Returns true if the file has a sealed envelope (structural check only).
-     * Does not verify the seal hash.
-     */
     static isSealed(file: Blob, options?: ExtractOptions): Promise<boolean>;
-    /**
-     * Returns true when the file has a restricted multi-sig envelope
-     * (allowlist present with more than one expected signer).
-     * Returns false for unsigned files, open-signing files, or single-signer files.
-     */
     static isMultiSig(file: Blob, options?: ExtractOptions): Promise<boolean>;
-    /**
-     * Check whether a MajikKey is permitted to add a signature to this file.
-     *
-     * Returns false (with a reason) when:
-     *   - The file is sealed
-     *   - The file has an allowlist and the key is not on it (all three fields checked)
-     *
-     * Returns true when:
-     *   - The file has no envelope (unsigned — anyone may sign)
-     *   - The file has no allowlist (open signing — anyone may sign)
-     *   - The key is on the allowlist
-     *
-     * Always requires a full MajikKey — fingerprint-only checks are not supported
-     * because they cannot verify the public key fields required by the allowlist.
-     */
     static canSign(file: Blob, key: MajikKey, options?: ExtractOptions): Promise<{
         permitted: boolean;
         reason?: string;
     }>;
-    /**
-     * Core signatories method. Returns all, signed, and pending arrays.
-     * Pass filter to narrow the return — the filtered array is still returned
-     * inside the full SignatoriesResult so callers always have the complete picture.
-     *
-     * Returns null if the file has no envelope.
-     */
     static getSignatories(file: Blob, options?: ExtractOptions, filter?: SignatoriesFilter): Promise<SignatoriesResult | null>;
-    /**
-     * Return the issuer (the signer who established the allowlist and controls sealing).
-     * Returns null for open-signing files or unsigned files.
-     */
     static getIssuer(file: Blob, options?: ExtractOptions): Promise<import("../../core/types").SignatoryInfo | null>;
-    /**
-     * Return a full summary of the envelope state in a single file read.
-     * Useful for rendering UI state (badge, status, signatories list) without
-     * making multiple separate calls.
-     * Returns null if the file has no envelope.
-     */
     static getEnvelopeInfo(file: Blob, options?: ExtractOptions): Promise<EnvelopeInfo | null>;
     static strip(file: Blob, options?: ExtractOptions): Promise<Blob>;
     static hasSignature(file: Blob, options?: ExtractOptions): Promise<boolean>;
     static getAllowlist(file: Blob, options?: ExtractOptions): Promise<ExpectedSigner[] | null>;
     static readonly registry: FormatHandlerRegistry;
     static listHandlers(): string[];
-    /**
-     * Check whether a file is eligible for chain anchoring.
-     * Anchoring requires a sealed envelope — permitted = isSealed(file).
-     * Chain-agnostic: does not know or care which chain the caller intends to use.
-     */
     static canAnchor(file: Blob, options?: ExtractOptions): Promise<{
         permitted: boolean;
         reason?: string;
     }>;
     /**
      * Embed an already-confirmed chain anchor into the envelope.
-     * Does NOT talk to any chain — purely appends a record it's handed.
-     *
-     * Defensive checks (beyond the master plan's minimum):
-     *   - File must be sealed
-     *   - anchor.payload.digest.value must match the envelope's current sealHash —
-     *     catches a caller accidentally embedding an anchor computed against a
-     *     stale seal (e.g. file was re-sealed between notarize() and this call)
-     *   - Upserts by anchor.id rather than blind-pushing, so a duplicate call
-     *     with the same anchor (e.g. retried after a network blip) doesn't
-     *     produce two entries for the same on-chain transaction
+     * Sealed check, digest match, and upsert-by-id dedup are all enforced by
+     * envelope.withChainAnchor().
      */
     static registerChainAnchor(file: Blob, anchor: MajikChainAnchor, options?: ExtractOptions): Promise<EmbedResult>;
     static getChainAnchors(file: Blob, options?: ExtractOptions): Promise<MajikChainAnchor[]>;
+    private static _prepare;
+    /** Extract + parse, or a fresh empty envelope when none exists. */
+    private static _readEnvelope;
+    private static _noSignatureResult;
+    /**
+     * Shared by verify() and verifyDetached(): filter by expectedSignerId,
+     * verify each remaining signature, and stamp the handler name onto each
+     * result. Previously duplicated near-verbatim in both methods.
+     */
+    private static _verifySignatures;
 }