@majikah/majik-signature 0.2.2 → 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

@@ -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, MajikSignatureEnvelope, 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 & {
@@ -67,15 +69,13 @@ export declare class MajikSignatureEmbed {
     }>;
     /**
      * Sign a file and return the envelope detached.
-     * Extracts any existing envelope (or uses a provided one), validates constraints,
-     * signs the stripped bytes, and returns the updated MultiSigEnvelope.
-     * Does NOT embed the envelope back into the file.
+     * 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;
+        existingEnvelope?: MajikSignatureEnvelope | MajikSignatureEnvelopeJSON | Uint8Array | Blob;
     }, debug?: boolean): Promise<{
         blob: Blob;
         envelope: MajikSignatureEnvelope;
@@ -83,15 +83,13 @@ export declare class MajikSignatureEmbed {
         mimeType: string;
     }>;
     /**
-     * Extract the MultiSigEnvelope from a file.
+     * 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;
@@ -100,29 +98,19 @@ export declare class MajikSignatureEmbed {
         expectedSignerId?: string;
     }, debug?: boolean): Promise<VerificationResult[]>;
     /**
-     * Verify a file against a provided, detached MultiSigEnvelope.
-     * Skips extraction but still strips the file in case it contains an embedded envelope,
+     * 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, envelope: MajikSignatureEnvelope, 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, envelope: MajikSignatureEnvelope, 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[]>;
     /**
      * 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;
@@ -132,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;
 }