@majikah/majik-signature 0.2.3 → 0.2.4

package/dist/core/constants.d.ts

@@ -59,3 +59,15 @@ export declare const MAJIK_TIMESTAMP_VERSION: 1;
 export declare const MAJIK_TSA_DOMAIN: "majikah-tsa-v-1:";
 export declare const MAJIK_NOTARY_VERSION: 1;
 export declare const MAJIK_NOTARY_MEMO_DOMAIN: "majik-notary-v-1:";
+export declare const MJKSIG_MAGIC: number[];
+export declare const MJKSIG_MAGIC_LEN: number;
+export declare const MJKSIG_VERSION = 1;
+export declare const MJKSIG_SUPPORTED_VERSIONS: readonly [1];
+export declare const MJKSIG_HEADER_LEN: number;
+/**
+ * Proposed IANA media type / conventional file extension for this format.
+ * Referenced here so both live in one place ahead of registration —
+ * update if/when the registration settles on different values.
+ */
+export declare const MJKSIG_MEDIA_TYPE: "application/vnd.majikah.mjksig";
+export declare const MJKSIG_FILE_EXTENSION: ".mjksig";

package/dist/core/constants.js

@@ -58,3 +58,22 @@ export const MAJIK_TIMESTAMP_VERSION = 1;
 export const MAJIK_TSA_DOMAIN = `majikah-tsa-v-${MAJIK_TIMESTAMP_VERSION}:`;
 export const MAJIK_NOTARY_VERSION = 1;
 export const MAJIK_NOTARY_MEMO_DOMAIN = `majik-notary-v-${MAJIK_NOTARY_VERSION}:`;
+// ─── MJKSIG binary format ───────────────────────────────────────────────────
+//
+// Layout: [magic(6)][version(1)][reserved(1)][payloadLen(4, BE u32)][payload JSON]
+// Header length is fixed at 12 bytes regardless of version — only the
+// payload shape may change between versions, never the header layout.
+// This lets fromMJKSIG() always locate and validate the header before it
+// needs to know anything about the payload's internal shape.
+export const MJKSIG_MAGIC = [0x4d, 0x4a, 0x4b, 0x53, 0x49, 0x47]; // "MJKSIG"
+export const MJKSIG_MAGIC_LEN = MJKSIG_MAGIC.length;
+export const MJKSIG_VERSION = 0x01;
+export const MJKSIG_SUPPORTED_VERSIONS = [MJKSIG_VERSION];
+export const MJKSIG_HEADER_LEN = MJKSIG_MAGIC_LEN + 1 + 1 + 4; // 12
+/**
+ * Proposed IANA media type / conventional file extension for this format.
+ * Referenced here so both live in one place ahead of registration —
+ * update if/when the registration settles on different values.
+ */
+export const MJKSIG_MEDIA_TYPE = "application/vnd.majikah.mjksig";
+export const MJKSIG_FILE_EXTENSION = ".mjksig";

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

@@ -75,7 +75,7 @@ export declare class MajikSignatureEmbed {
         contentType?: string;
         timestamp?: string;
         expectedSigners?: ExpectedSigner[];
-        existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON;
+        existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob;
     }, debug?: boolean): Promise<{
         blob: Blob;
         envelope: MajikSignatureEnvelope;
@@ -98,14 +98,14 @@ export declare class MajikSignatureEmbed {
         expectedSignerId?: string;
     }, debug?: boolean): Promise<VerificationResult[]>;
     /**
-     * Verify a file against a provided, detached envelope (instance or JSON).
+     * Verify a file against a provided, detached envelope (instance, blob or JSON).
      * Still strips the file in case it also contains an embedded envelope,
      * ensuring verification runs against the clean original bytes.
      */
-    static verifyDetached(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON, publicKeys: MajikSignerPublicKeys, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
+    static verifyDetached(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob, publicKeys: MajikSignerPublicKeys, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
         expectedSignerId?: string;
     }, debug?: boolean): Promise<VerificationResult[]>;
-    static verifyDetachedWithKey(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
+    static verifyDetachedWithKey(file: Blob, envelopeInput: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob, key: MajikKey, MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & {
         expectedSignerId?: string;
     }, debug?: boolean): Promise<VerificationResult[]>;
     /**

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

@@ -133,9 +133,8 @@ export class MajikSignatureEmbed {
      */
     static async signDetached(file, key, MajikSig, options, debug = false) {
         const { bytes, mimeType, handler } = await MajikSignatureEmbed._prepare(file, options);
-        // ── Resolve the working envelope ─────────────────────────────────────────
         const envelope = options?.existingEnvelope
-            ? MajikSignatureEnvelope.from(options.existingEnvelope)
+            ? await MajikSignatureEnvelope.from(options.existingEnvelope)
             : await MajikSignatureEmbed._readEnvelope(handler, bytes);
         envelope.assertCanSign(key);
         const originalBytes = await handler.strip(bytes);
@@ -218,13 +217,13 @@ export class MajikSignatureEmbed {
     }
     // ── verifyDetached ─────────────────────────────────────────────────────────
     /**
-     * Verify a file against a provided, detached envelope (instance or JSON).
+     * Verify a file against a provided, detached envelope (instance, blob or JSON).
      * Still strips the file in case it also contains an embedded envelope,
      * ensuring verification runs against the clean original bytes.
      */
     static async verifyDetached(file, envelopeInput, publicKeys, MajikSig, options, debug = false) {
         const { bytes, handler } = await MajikSignatureEmbed._prepare(file, options);
-        const envelope = MajikSignatureEnvelope.from(envelopeInput);
+        const envelope = await MajikSignatureEnvelope.from(envelopeInput);
         const originalBytes = await handler.strip(bytes);
         if (debug) {
             console.log("verifyDetached — original bytes hash:", bytesToBase64(hashContent(originalBytes)));

package/dist/core/envelope.d.ts

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

package/dist/core/envelope.js

@@ -19,7 +19,7 @@
  */
 import { sha3_512 } from "@noble/hashes/sha3.js";
 import { bytesToHex } from "@noble/hashes/utils.js";
-import { MAJIK_ENVELOPE_VERSION, MAJIK_SEAL_DOMAIN } from "./constants";
+import { MAJIK_ENVELOPE_VERSION, MAJIK_SEAL_DOMAIN, MJKSIG_HEADER_LEN, MJKSIG_MAGIC, MJKSIG_MAGIC_LEN, MJKSIG_MEDIA_TYPE, MJKSIG_SUPPORTED_VERSIONS, MJKSIG_VERSION, } from "./constants";
 import { MajikSignatureAllowlistError, MajikSignatureError, MajikSignatureKeyError, MajikSignatureSerializationError, MajikSignatureValidationError, } from "./errors";
 import { hashContent, bytesToBase64 } from "./hash";
 // ─── MajikSignatureEnvelope ────────────────────────────────────────────────────
@@ -490,6 +490,131 @@ export class MajikSignatureEnvelope {
             throw new MajikSignatureSerializationError("Failed to deserialize envelope from base64", err);
         }
     }
+    // ── MJKSIG binary format ─────────────────────────────────────────────────
+    //
+    // A dedicated, versioned, self-identifying binary container for a detached
+    // envelope — distinct from serialize()/deserialize() (plain base64 of the
+    // JSON, no header) which remains for lightweight in-app round-tripping.
+    // MJKSIG is the wire/on-disk format intended for out-of-band travel,
+    // storage, and eventual IANA registration.
+    // ── MJKSIG binary format ─────────────────────────────────────────────────
+    //
+    // A dedicated, versioned, self-identifying binary container for a detached
+    // envelope — distinct from serialize()/deserialize() (plain base64 of the
+    // JSON, no header) which remains for lightweight in-app round-tripping.
+    // MJKSIG is the wire/on-disk format intended for out-of-band travel,
+    // storage, and eventual IANA registration.
+    /**
+     * Raw MJKSIG bytes, no Blob wrapper. Exposed as a public escape hatch for
+     * non-browser contexts (Node scripts, tests, direct fs writes) where
+     * wrapping in a Blob just to immediately unwrap it again is pure overhead.
+     * toMJKSIG() is the primary API for anything Blob-facing.
+     */
+    toMJKSIGBytes() {
+        const payloadJson = new TextEncoder().encode(JSON.stringify(this.toJSON()));
+        const out = new Uint8Array(MJKSIG_HEADER_LEN + payloadJson.length);
+        out.set(MJKSIG_MAGIC, 0);
+        out[MJKSIG_MAGIC_LEN] = MJKSIG_VERSION;
+        out[MJKSIG_MAGIC_LEN + 1] = 0x00; // reserved — always 0 in v1
+        const lenOffset = MJKSIG_MAGIC_LEN + 2;
+        out[lenOffset] = (payloadJson.length >>> 24) & 0xff;
+        out[lenOffset + 1] = (payloadJson.length >>> 16) & 0xff;
+        out[lenOffset + 2] = (payloadJson.length >>> 8) & 0xff;
+        out[lenOffset + 3] = payloadJson.length & 0xff;
+        out.set(payloadJson, MJKSIG_HEADER_LEN);
+        return out;
+    }
+    /**
+     * Encode this envelope as an MJKSIG file Blob.
+     * Always writes the current MJKSIG_VERSION — encoding an old payload
+     * shape under an old version tag is not supported; old versions only
+     * ever appear when *reading* pre-existing MJKSIG binaries.
+     */
+    toMJKSIG() {
+        const bytes = this.toMJKSIGBytes();
+        return new Blob([bytes], {
+            type: MJKSIG_MEDIA_TYPE,
+        });
+    }
+    /**
+     * Decode MJKSIG bytes back into a MajikSignatureEnvelope.
+     * Validates magic bytes, version, and declared payload length before
+     * attempting to parse — a truncated or corrupted buffer fails fast with
+     * a clear reason rather than an obscure JSON.parse error.
+     *
+     * Accepts either a Blob (as produced by toMJKSIG()) or raw Uint8Array
+     * (as produced by toMJKSIGBytes(), or read directly off disk) — mirrors
+     * the same "accept either shape" pattern as from(). Reading a Blob
+     * requires awaiting its bytes, which is why this method is async.
+     */
+    static async fromMJKSIG(input) {
+        const raw = input instanceof Blob ? new Uint8Array(await input.arrayBuffer()) : input;
+        return MajikSignatureEnvelope.#parseMJKSIGBytes(raw);
+    }
+    /** Core MJKSIG byte parser — shared by fromMJKSIG() after Blob resolution. */
+    static #parseMJKSIGBytes(raw) {
+        if (raw.length < MJKSIG_HEADER_LEN + 1) {
+            // +1 == at least one byte of payload JSON
+            throw new MajikSignatureSerializationError("Malformed MJKSIG: too short to contain a valid header");
+        }
+        for (let i = 0; i < MJKSIG_MAGIC_LEN; i++) {
+            if (raw[i] !== MJKSIG_MAGIC[i]) {
+                throw new MajikSignatureSerializationError('Malformed MJKSIG: missing "MJKSIG" magic bytes');
+            }
+        }
+        const version = raw[MJKSIG_MAGIC_LEN];
+        if (!MJKSIG_SUPPORTED_VERSIONS.includes(version)) {
+            throw new MajikSignatureSerializationError(`Unsupported MJKSIG version: ${version} (supported: ${MJKSIG_SUPPORTED_VERSIONS.join(", ")})`);
+        }
+        const lenOffset = MJKSIG_MAGIC_LEN + 2;
+        const payloadLen = (raw[lenOffset] << 24) |
+            (raw[lenOffset + 1] << 16) |
+            (raw[lenOffset + 2] << 8) |
+            raw[lenOffset + 3];
+        if (payloadLen <= 0) {
+            throw new MajikSignatureSerializationError("Malformed MJKSIG: invalid payload length");
+        }
+        const payloadStart = MJKSIG_HEADER_LEN;
+        const payloadEnd = payloadStart + payloadLen;
+        if (payloadEnd > raw.length) {
+            throw new MajikSignatureSerializationError("Malformed MJKSIG: declared payload length exceeds buffer");
+        }
+        const json = new TextDecoder().decode(raw.slice(payloadStart, payloadEnd));
+        // fromJSON() runs full #validateShape() — MJKSIG framing validity does
+        // NOT imply envelope validity, so this is not a redundant check.
+        return MajikSignatureEnvelope.fromJSON(json);
+    }
+    /**
+     * Cheap structural sniff — checks magic bytes only, does not parse or
+     * validate the payload. For a Blob, slices only the header bytes rather
+     * than reading the whole file, so this stays cheap even on large inputs.
+     */
+    static async isMJKSIG(input) {
+        const header = input instanceof Blob
+            ? new Uint8Array(await input.slice(0, MJKSIG_MAGIC_LEN).arrayBuffer())
+            : input;
+        if (header.length < MJKSIG_MAGIC_LEN)
+            return false;
+        for (let i = 0; i < MJKSIG_MAGIC_LEN; i++) {
+            if (header[i] !== MJKSIG_MAGIC[i])
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Read just the version byte without parsing the payload.
+     * Returns null if the input isn't MJKSIG-shaped at all.
+     */
+    static async getMJKSIGVersion(input) {
+        const header = input instanceof Blob
+            ? new Uint8Array(await input.slice(0, MJKSIG_MAGIC_LEN + 1).arrayBuffer())
+            : input;
+        if (!(await MajikSignatureEnvelope.isMJKSIG(header)))
+            return null;
+        if (header.length < MJKSIG_MAGIC_LEN + 1)
+            return null;
+        return header[MJKSIG_MAGIC_LEN];
+    }
     // ── Creation / parsing ───────────────────────────────────────────────────────
     static empty() {
         return new MajikSignatureEnvelope({
@@ -533,11 +658,24 @@ export class MajikSignatureEnvelope {
         MajikSignatureEnvelope.#validateShape(promoted);
         return new MajikSignatureEnvelope(promoted);
     }
-    /** Accepts either an instance or its JSON shape — normalizes to an instance. */
-    static from(input) {
-        return input instanceof MajikSignatureEnvelope
-            ? input
-            : MajikSignatureEnvelope.fromJSON(input);
+    /**
+     * Accepts an instance, its JSON shape, or MJKSIG bytes/Blob — normalizes to
+     * an instance. This is the single entry point that lets every downstream
+     * caller (verifyDetached, verifyDetachedWithKey, signDetached's
+     * existingEnvelope option) transparently accept a detached envelope
+     * regardless of which form it arrived in.
+     *
+     * Now async: resolving a Blob input requires awaiting its bytes. Every
+     * existing call site is already inside an async method, so this only
+     * costs an added `await` at each call site — no structural changes.
+     */
+    static async from(input) {
+        if (input instanceof MajikSignatureEnvelope)
+            return input;
+        if (input instanceof Uint8Array || input instanceof Blob) {
+            return MajikSignatureEnvelope.fromMJKSIG(input);
+        }
+        return MajikSignatureEnvelope.fromJSON(input);
     }
     validate() {
         MajikSignatureEnvelope.#validateShape(this.toJSON());

package/dist/majik-signature.d.ts

@@ -150,7 +150,7 @@ export declare class MajikSignature {
         timestamp?: string;
         mimeType?: string;
         expectedSigners?: ExpectedSigner[];
-        existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON;
+        existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob;
     }): ReturnType<typeof MajikSignatureEmbed.signDetached>;
     /**
      * Verify a file's embedded signatures.
@@ -167,7 +167,7 @@ export declare class MajikSignature {
      * Returns one VerificationResult per signer.
      * Pass options.expectedSignerId to verify only a specific signer.
      */
-    static verifyFileDetached(file: Blob, envelope: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON, keyOrPublicKeys: MajikKey | MajikSignerPublicKeys, options?: {
+    static verifyFileDetached(file: Blob, envelope: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob, keyOrPublicKeys: MajikKey | MajikSignerPublicKeys, options?: {
         expectedSignerId?: string;
         mimeType?: string;
     }, debug?: boolean): Promise<VerificationResult[]>;

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.3",
+  "version": "0.2.4",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",