@majikah/majik-signature 0.2.6 → 0.2.7

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

@@ -26,6 +26,7 @@ import { MajikSignatureEnvelope } from "../../core/envelope";
 import { FormatHandlerRegistry } from "./registry";
 import { MajikChainAnchor } from "../../anchor/types";
 import { MajikSignatureMap } from "../mjksmap";
+import { SignatureOrderResult, VerifySignatureOrderOptions } from "../order";
 export interface MajikSignatureAdapter {
     toJSON(): MajikSignatureJSON;
     /**
@@ -178,6 +179,18 @@ export declare class MajikSignatureEmbed {
      * without the caller re-deriving it from the array each time.
      */
     static summarizeBatchVerification(results: FileVerifyResult[]): BatchVerifySummary;
+    /**
+     * Verify the chronological signing order of a file's embedded envelope
+     * against an expected sequence of signers.
+     * expectedOrder accepts MajikKey instances and/or ExpectedSigner objects,
+     * mixed freely — normalized internally.
+     */
+    static verifyFileOrder(file: Blob, expectedOrder: readonly (MajikKey | ExpectedSigner)[], MajikSig: MajikSignatureStaticAdapter, options?: ExtractOptions & VerifySignatureOrderOptions): Promise<SignatureOrderResult>;
+    /**
+     * Verify the chronological signing order against a detached envelope
+     * (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>;
     /**
      * 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

@@ -37,6 +37,7 @@ import { FallbackHandler } from "./fallback";
 import { bytesToBase64, hashContent } from "../hash";
 import { MajikSignatureError, MajikSignatureValidationError } from "../errors";
 import { MajikSignatureMap } from "../mjksmap";
+import { verifySignatureOrder } from "../order";
 // ─── Registry ─────────────────────────────────────────────────────────────────
 const DEFAULT_REGISTRY = new FormatHandlerRegistry()
     .register(new PdfHandler())
@@ -473,6 +474,41 @@ export class MajikSignatureEmbed {
         summary.allValid = summary.verified === summary.total && summary.total > 0;
         return summary;
     }
+    /**
+     * Verify the chronological signing order of a file's embedded envelope
+     * against an expected sequence of signers.
+     * expectedOrder accepts MajikKey instances and/or ExpectedSigner objects,
+     * mixed freely — normalized internally.
+     */
+    static async verifyFileOrder(file, expectedOrder, MajikSig, options) {
+        const { bytes, handler } = await MajikSignatureEmbed._prepare(file, options);
+        const raw = await handler.extract(bytes);
+        const envelope = raw
+            ? MajikSignatureEnvelope.fromJSON(raw)
+            : MajikSignatureEnvelope.empty();
+        if (raw) {
+            const integrity = envelope.verifyAllowlistIntegrity();
+            if (!integrity.valid) {
+                throw new MajikSignatureError(integrity.reason ?? "Allowlist integrity check failed");
+            }
+        }
+        const originalBytes = raw ? await handler.strip(bytes) : bytes;
+        return verifySignatureOrder(envelope, originalBytes, expectedOrder, (content, sig, pk) => MajikSig.verify(content, sig, pk), { strict: options?.strict });
+    }
+    /**
+     * Verify the chronological signing order against a detached envelope
+     * (instance, JSON, MJKSIG bytes, or Blob).
+     */
+    static async verifyDetachedOrder(file, envelopeInput, expectedOrder, MajikSig, options) {
+        const { bytes, handler } = await MajikSignatureEmbed._prepare(file, options);
+        const envelope = await MajikSignatureEnvelope.from(envelopeInput);
+        const integrity = envelope.verifyAllowlistIntegrity();
+        if (!integrity.valid) {
+            throw new MajikSignatureError(integrity.reason ?? "Allowlist integrity check failed");
+        }
+        const originalBytes = await handler.strip(bytes);
+        return verifySignatureOrder(envelope, originalBytes, expectedOrder, (content, sig, pk) => MajikSig.verify(content, sig, pk), { strict: options?.strict });
+    }
     // ── seal ───────────────────────────────────────────────────────────────────
     /**
      * Seal a multi-sig envelope, preventing any further signatures.

package/dist/core/order.d.ts

@@ -0,0 +1,100 @@
+/**
+ * core/order.ts
+ *
+ * Chronological signing-order verification.
+ *
+ * Pure /structural, like envelope.ts — no MajikSig-specific imports beyond a
+ * caller-supplied verify callback, so this has zero circular-dependency risk
+ * with majik-signature.ts or majik-embed.ts.
+ *
+ * Trust model:
+ *   - tsa.payload.timestamp is server-attested (a TSA stamped a nonce) —
+ *     preferred whenever present.
+ *   - The bare `timestamp` field is self-reported by the signer's local
+ *     clock. It's tamper-evident (covered by the signature) but NOT
+ *     independently attested — a signer could set their clock to anything.
+ *   - Every result surfaces `usesUnattestedTimestamp` so callers can show
+ *     a caveat when order was decided using a self-reported clock.
+ */
+import type { MajikKey } from "@majikah/majik-key";
+import type { MajikSignatureEnvelope } from "./envelope";
+import type { ExpectedSigner, MajikSignatureJSON, MajikSignerPublicKeys, VerificationResult } from "./types";
+export type TimestampSource = "tsa" | "self-reported";
+export interface SignerOrderStatus {
+    signerId: string;
+    expectedPosition: number;
+    hasSigned: boolean;
+    /** Present only when hasSigned is true */
+    valid?: boolean;
+    /** Present only when hasSigned && !valid */
+    reason?: string;
+    effectiveTimestamp?: string;
+    timestampSource?: TimestampSource;
+}
+export interface OrderViolation {
+    /** signerId expected to have signed earlier */
+    earlier: string;
+    /** signerId expected to have signed later */
+    later: string;
+    earlierTimestamp: string;
+    laterTimestamp: string;
+}
+export interface SoftTieWarning {
+    a: string;
+    b: string;
+    timestamp: string;
+}
+export interface SignatureOrderResult {
+    /** True only when everyone expected signed, every signature is valid,
+     *  the order was respected, AND (in strict mode) no extra signers exist. */
+    valid: boolean;
+    allExpectedSigned: boolean;
+    allValid: boolean;
+    orderRespected: boolean;
+    strict: boolean;
+    /** Only populated when strict === true */
+    unexpectedSigners: string[];
+    pendingSigners: string[];
+    invalidSigners: string[];
+    violations: OrderViolation[];
+    /** True if any timestamp used in a comparison was self-reported rather
+     *  than TSA-attested — order in that case is a claim, not a proof. */
+    usesUnattestedTimestamp: boolean;
+    /** Two signers landed on the identical instant — order between them is
+     *  indistinguishable. Doesn't fail `valid`, just a note. */
+    softTieWarnings: SoftTieWarning[];
+    signers: SignerOrderStatus[];
+    reason?: string;
+}
+export interface VerifySignatureOrderOptions {
+    /** When true, any signer present in the envelope but absent from
+     *  expectedOrder is reported and fails the overall result. */
+    strict?: boolean;
+}
+/** Minimal shape the order verifier needs to check one signature's crypto. */
+export type OrderVerifyFn = (content: Uint8Array, signature: MajikSignatureJSON, publicKeys: MajikSignerPublicKeys) => VerificationResult;
+/**
+ * Normalize a mixed array of MajikKey instances and/or ExpectedSigner
+ * objects into a plain ExpectedSigner[]. Order-preserving — position in
+ * the input array IS the expected signing position.
+ */
+export declare function normalizeExpectedOrder(input: readonly (MajikKey | ExpectedSigner)[]): ExpectedSigner[];
+export declare function resolveEffectiveTimestamp(sig: MajikSignatureJSON): {
+    timestamp: string;
+    source: TimestampSource;
+};
+/**
+ * Verify that an envelope's signatures were produced in the sequence given
+ * by expectedOrder (array position == expected chronological position).
+ *
+ * Each expected signer is verified against THEIR OWN publicly-known keys
+ * (as supplied in expectedOrder), not the self-asserted keys embedded in
+ * their own envelope entry — this ties identity to a key you actually
+ * trust, rather than trusting whatever key a signature claims to be signed
+ * with.
+ *
+ * Only signers who (a) signed and (b) verified valid are compared for
+ * order — an invalid signature's timestamp isn't trustworthy, so it's
+ * excluded from ordering but still reported via invalidSigners.
+ */
+export declare function verifySignatureOrder(envelope: MajikSignatureEnvelope, originalBytes: Uint8Array, expectedOrder: readonly (MajikKey | ExpectedSigner)[], verifyFn: OrderVerifyFn, options?: VerifySignatureOrderOptions): SignatureOrderResult;

package/dist/core/order.js

@@ -0,0 +1,209 @@
+/**
+ * core/order.ts
+ *
+ * Chronological signing-order verification.
+ *
+ * Pure /structural, like envelope.ts — no MajikSig-specific imports beyond a
+ * caller-supplied verify callback, so this has zero circular-dependency risk
+ * with majik-signature.ts or majik-embed.ts.
+ *
+ * Trust model:
+ *   - tsa.payload.timestamp is server-attested (a TSA stamped a nonce) —
+ *     preferred whenever present.
+ *   - The bare `timestamp` field is self-reported by the signer's local
+ *     clock. It's tamper-evident (covered by the signature) but NOT
+ *     independently attested — a signer could set their clock to anything.
+ *   - Every result surfaces `usesUnattestedTimestamp` so callers can show
+ *     a caveat when order was decided using a self-reported clock.
+ */
+import { MajikSignatureKeyError, MajikSignatureValidationError, } from "./errors";
+import { base64ToBytes, bytesToBase64 } from "./hash";
+// ─── Normalization ─────────────────────────────────────────────────────────
+function isExpectedSignerShape(v) {
+    return typeof v.edPublicKey === "string";
+}
+function toExpectedSigner(input) {
+    if (isExpectedSignerShape(input))
+        return input;
+    const key = input;
+    if (!key.hasSigningKeys) {
+        throw new MajikSignatureKeyError("MajikKey has no signing public keys — cannot build expected order entry.");
+    }
+    return {
+        signerId: key.fingerprint,
+        edPublicKey: bytesToBase64(key.edPublicKey),
+        mlDsaPublicKey: bytesToBase64(key.mlDsaPublicKey),
+    };
+}
+/**
+ * Normalize a mixed array of MajikKey instances and/or ExpectedSigner
+ * objects into a plain ExpectedSigner[]. Order-preserving — position in
+ * the input array IS the expected signing position.
+ */
+export function normalizeExpectedOrder(input) {
+    return input.map(toExpectedSigner);
+}
+// ─── Timestamp resolution ───────────────────────────────────────────────────
+export function resolveEffectiveTimestamp(sig) {
+    if (sig.tsa?.payload?.timestamp) {
+        return { timestamp: sig.tsa.payload.timestamp, source: "tsa" };
+    }
+    return { timestamp: sig.timestamp, source: "self-reported" };
+}
+// ─── Core verification ───────────────────────────────────────────────────────
+/**
+ * Verify that an envelope's signatures were produced in the sequence given
+ * by expectedOrder (array position == expected chronological position).
+ *
+ * Each expected signer is verified against THEIR OWN publicly-known keys
+ * (as supplied in expectedOrder), not the self-asserted keys embedded in
+ * their own envelope entry — this ties identity to a key you actually
+ * trust, rather than trusting whatever key a signature claims to be signed
+ * with.
+ *
+ * Only signers who (a) signed and (b) verified valid are compared for
+ * order — an invalid signature's timestamp isn't trustworthy, so it's
+ * excluded from ordering but still reported via invalidSigners.
+ */
+export function verifySignatureOrder(envelope, originalBytes, expectedOrder, verifyFn, options) {
+    const strict = options?.strict ?? false;
+    const normalizedExpected = normalizeExpectedOrder(expectedOrder);
+    if (normalizedExpected.length === 0) {
+        throw new MajikSignatureValidationError("expectedOrder must contain at least one signer.", "expectedOrder");
+    }
+    const seenIds = new Set();
+    for (const e of normalizedExpected) {
+        if (seenIds.has(e.signerId)) {
+            throw new MajikSignatureValidationError(`Duplicate signerId in expectedOrder: "${e.signerId}"`, "expectedOrder");
+        }
+        seenIds.add(e.signerId);
+    }
+    const sigsById = new Map(envelope.signatures.map((s) => [s.signerId, s]));
+    const signers = [];
+    const pendingSigners = [];
+    const invalidSigners = [];
+    let usesUnattestedTimestamp = false;
+    // Only expected signers who signed AND verified valid are eligible for
+    // order comparison — their timestamps are the only trustworthy ones.
+    const considered = [];
+    for (let i = 0; i < normalizedExpected.length; i++) {
+        const expected = normalizedExpected[i];
+        const sig = sigsById.get(expected.signerId);
+        if (!sig) {
+            pendingSigners.push(expected.signerId);
+            signers.push({
+                signerId: expected.signerId,
+                expectedPosition: i,
+                hasSigned: false,
+            });
+            continue;
+        }
+        const publicKeys = {
+            signerId: expected.signerId,
+            edPublicKey: base64ToBytes(expected.edPublicKey),
+            mlDsaPublicKey: base64ToBytes(expected.mlDsaPublicKey),
+        };
+        const result = verifyFn(originalBytes, sig, publicKeys);
+        const { timestamp, source } = resolveEffectiveTimestamp(sig);
+        if (!result.valid) {
+            invalidSigners.push(expected.signerId);
+            signers.push({
+                signerId: expected.signerId,
+                expectedPosition: i,
+                hasSigned: true,
+                valid: false,
+                reason: result.reason,
+                effectiveTimestamp: timestamp,
+                timestampSource: source,
+            });
+            continue;
+        }
+        if (source === "self-reported")
+            usesUnattestedTimestamp = true;
+        signers.push({
+            signerId: expected.signerId,
+            expectedPosition: i,
+            hasSigned: true,
+            valid: true,
+            effectiveTimestamp: timestamp,
+            timestampSource: source,
+        });
+        considered.push({
+            signerId: expected.signerId,
+            timestamp,
+            timeMs: Date.parse(timestamp),
+        });
+    }
+    // ── Order check — every pair among considered signers, not just neighbors ──
+    const violations = [];
+    const softTieWarnings = [];
+    for (let i = 0; i < considered.length; i++) {
+        for (let j = i + 1; j < considered.length; j++) {
+            const a = considered[i]; // expected earlier
+            const b = considered[j]; // expected later
+            if (a.timeMs > b.timeMs) {
+                violations.push({
+                    earlier: a.signerId,
+                    later: b.signerId,
+                    earlierTimestamp: a.timestamp,
+                    laterTimestamp: b.timestamp,
+                });
+            }
+            else if (a.timeMs === b.timeMs) {
+                softTieWarnings.push({
+                    a: a.signerId,
+                    b: b.signerId,
+                    timestamp: a.timestamp,
+                });
+            }
+        }
+    }
+    // ── Strict mode: any actual signer absent from expectedOrder ────────────
+    const unexpectedSigners = [];
+    if (strict) {
+        for (const sig of envelope.signatures) {
+            if (!seenIds.has(sig.signerId))
+                unexpectedSigners.push(sig.signerId);
+        }
+    }
+    const allExpectedSigned = pendingSigners.length === 0;
+    const allValid = invalidSigners.length === 0;
+    const orderRespected = violations.length === 0;
+    const strictSatisfied = !strict || unexpectedSigners.length === 0;
+    const valid = allExpectedSigned && allValid && orderRespected && strictSatisfied;
+    let reason;
+    if (!allExpectedSigned) {
+        reason = `Missing signature(s) from: ${pendingSigners.join(", ")}`;
+    }
+    else if (!allValid) {
+        reason = `Invalid signature(s) from: ${invalidSigners.join(", ")}`;
+    }
+    else if (!strictSatisfied) {
+        reason = `Unexpected signer(s) present (strict mode): ${unexpectedSigners.join(", ")}`;
+    }
+    else if (!orderRespected) {
+        reason = `Signing order violated: ${violations
+            .map((v) => `"${v.earlier}" expected before "${v.later}" but signed after`)
+            .join("; ")}`;
+    }
+    else if (softTieWarnings.length > 0) {
+        reason = `All signatures valid and in order, but ${softTieWarnings.length} pair(s) share an identical timestamp — order cannot be distinguished for: ${softTieWarnings
+            .map((w) => `"${w.a}"/"${w.b}"`)
+            .join(", ")}`;
+    }
+    return {
+        valid,
+        allExpectedSigned,
+        allValid,
+        orderRespected,
+        strict,
+        unexpectedSigners,
+        pendingSigners,
+        invalidSigners,
+        violations,
+        usesUnattestedTimestamp,
+        softTieWarnings,
+        signers,
+        reason,
+    };
+}

package/dist/majik-signature.d.ts

@@ -10,6 +10,7 @@ import type { ImageVerificationResult, ImageSignOptions, ImageSignatureStub } fr
 import { MajikChainAnchor, MajikChainAnchorMemo } from "./anchor/types";
 import { MajikSignatureEnvelope } from "./core/envelope";
 import { MajikSignatureMap } from "./core/mjksmap";
+import { SignatureOrderResult } from "./core/order";
 /**
  * Majik Signature
  * ---
@@ -217,6 +218,32 @@ export declare class MajikSignature {
     static verifyFilesFromMjksMap(map: MajikSignatureMap, files: BatchVerifyInput[], publicKeys: MajikSignerPublicKeys, options?: BatchVerifyOptions, debug?: boolean): Promise<FileVerifyResult[]>;
     static verifyFilesFromMjksMapWithKey(map: MajikSignatureMap, files: BatchVerifyInput[], key: MajikKey, options?: BatchVerifyOptions, debug?: boolean): Promise<FileVerifyResult[]>;
     static summarizeBatchVerification(results: FileVerifyResult[]): ReturnType<typeof MajikSignatureEmbed.summarizeBatchVerification>;
+    /**
+     * Verify that a file's embedded signatures were produced in the given
+     * order. expectedOrder accepts MajikKey instances and/or ExpectedSigner
+     * objects, mixed freely.
+     *
+     * @example
+     *   const result = await MajikSignature.verifyFileOrder(file, [bobKey, daveKey]);
+     *   if (!result.valid) console.warn(result.reason);
+     */
+    static verifyFileOrder(file: Blob, expectedOrder: readonly (MajikKey | ExpectedSigner)[], options?: {
+        mimeType?: string;
+        strict?: boolean;
+    }): Promise<SignatureOrderResult>;
+    /**
+     * Verify signing order against a detached envelope.
+     */
+    static verifyFileDetachedOrder(file: Blob, envelope: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob, expectedOrder: readonly (MajikKey | ExpectedSigner)[], options?: {
+        mimeType?: string;
+        strict?: boolean;
+    }): Promise<SignatureOrderResult>;
+    /**
+     * Normalize a mixed array of MajikKey instances / ExpectedSigner objects
+     * into a plain ExpectedSigner[]. Exposed standalone in case you want to
+     * cache/store the normalized order without immediately verifying.
+     */
+    static normalizeExpectedOrder(expectedOrder: readonly (MajikKey | ExpectedSigner)[]): ExpectedSigner[];
     /**
      * Embed this MajikSignature instance into a file.
      * The signature must cover the original file bytes BEFORE embedding.

package/dist/majik-signature.js

@@ -13,6 +13,7 @@ import { hashContent, bytesToBase64, base64ToBytes } from "./core/hash";
 import { MajikSignatureEmbed } from "./core/embed/majik-embed";
 // ── Stamp (image signing) imports ─────────────────────────────────────────────
 import { MajikImageSignature } from "./core/stamp/image-signature";
+import { normalizeExpectedOrder as normalizeExpectedOrderUtil, } from "./core/order";
 const secureFill = Uint8Array.prototype.fill;
 /**
  * Majik Signature
@@ -494,6 +495,32 @@ export class MajikSignature {
     static summarizeBatchVerification(results) {
         return MajikSignatureEmbed.summarizeBatchVerification(results);
     }
+    /**
+     * Verify that a file's embedded signatures were produced in the given
+     * order. expectedOrder accepts MajikKey instances and/or ExpectedSigner
+     * objects, mixed freely.
+     *
+     * @example
+     *   const result = await MajikSignature.verifyFileOrder(file, [bobKey, daveKey]);
+     *   if (!result.valid) console.warn(result.reason);
+     */
+    static async verifyFileOrder(file, expectedOrder, options) {
+        return MajikSignatureEmbed.verifyFileOrder(file, expectedOrder, MajikSignature, options);
+    }
+    /**
+     * Verify signing order against a detached envelope.
+     */
+    static async verifyFileDetachedOrder(file, envelope, expectedOrder, options) {
+        return MajikSignatureEmbed.verifyDetachedOrder(file, envelope, expectedOrder, MajikSignature, options);
+    }
+    /**
+     * Normalize a mixed array of MajikKey instances / ExpectedSigner objects
+     * into a plain ExpectedSigner[]. Exposed standalone in case you want to
+     * cache/store the normalized order without immediately verifying.
+     */
+    static normalizeExpectedOrder(expectedOrder) {
+        return normalizeExpectedOrderUtil(expectedOrder);
+    }
     /**
      * Embed this MajikSignature instance into a file.
      * The signature must cover the original file bytes BEFORE embedding.

package/package.json

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