@e-sig/core 0.5.1 → 0.7.0

package/dist/pq-seal.d.ts

@@ -0,0 +1,183 @@
+import crypto from "node:crypto";
+/** Seal schema version. Bump on any breaking change to the signed payload shape. */
+export declare const PQ_SEAL_VERSION: 1;
+/** Hybrid algorithm identifier embedded in (and bound by) every seal. */
+export declare const PQ_SEAL_ALG: "hybrid-ed25519-ml-dsa-65";
+/** Bundle schema version for the wrapped at-rest key material. */
+declare const PQ_BUNDLE_VERSION: 1;
+/**
+ * True if `value` is a structurally well-formed UUAID assertion — the exact rule
+ * `buildPqSeal` enforces on input and `verifyPqSealSignatures` enforces on a
+ * seal that carries one. This is an envelope check, NOT proof that the
+ * identifier resolves, exists, or belongs to the signer.
+ *
+ * Accepted here does NOT imply accepted by the UUAID registry: the registry
+ * additionally enforces semantics this package deliberately does not know
+ * (registered subject classes and object types, canonical UUID form). Expect a
+ * band of identifiers this will sign and a resolver will still reject.
+ */
+export declare function isWellFormedUuaidAssertion(value: unknown): value is string;
+/**
+ * The wrappable at-rest key bundle. Persist `wrapPqKeyBundle(bundle, passphrase)`;
+ * never store the raw bundle. Compact by design: an Ed25519 PKCS#8 key plus a
+ * 32-byte ML-DSA seed (the full 4032-byte ML-DSA secret key is re-derived
+ * deterministically via `ml_dsa65.keygen(seed)`).
+ */
+export interface PqKeyBundle {
+    v: typeof PQ_BUNDLE_VERSION;
+    /** base64 PKCS#8 DER of the Ed25519 private key. */
+    ed25519Pkcs8: string;
+    /** base64 32-byte ML-DSA-65 seed. */
+    mldsa65Seed: string;
+}
+/** Public key material derived from a bundle — safe to publish/pin as the signer identity. */
+export interface PqPublicMaterial {
+    /** base64 raw 32-byte Ed25519 public key. */
+    ed25519: string;
+    /** base64 raw 1952-byte ML-DSA-65 public key. */
+    mldsa65: string;
+    /** SHA-256 hex of the raw ML-DSA-65 public key — the post-quantum identity fingerprint. */
+    mldsa65Fpr: string;
+    /** Stable 128-bit hex id over both public keys (bound into every seal). */
+    keyId: string;
+}
+/** In-memory signing keys, ready to produce seals. Never persisted directly. */
+export interface PqSigningKeys {
+    ed25519PrivateKey: crypto.KeyObject;
+    ed25519PublicRaw: Uint8Array;
+    mldsa65SecretKey: Uint8Array;
+    mldsa65PublicKey: Uint8Array;
+}
+/**
+ * A hybrid post-quantum seal. The signed payload is every field EXCEPT `sig`,
+ * serialized canonically (see `canonicalJson`). `digest` is the SHA-256 (hex) of
+ * the first `coveredBytes` bytes of the final document — the PDF-verify layer
+ * checks that binding; `verifyPqSealSignatures` only checks the two signatures.
+ */
+export interface PqSeal {
+    v: typeof PQ_SEAL_VERSION;
+    alg: typeof PQ_SEAL_ALG;
+    /** Digest algorithm over the covered document bytes. */
+    over: "sha256";
+    /** SHA-256 hex of the covered document bytes (the first `coveredBytes` bytes). */
+    digest: string;
+    /** Byte length of the document prefix the digest covers (P0 = rendered PDF pre-seal). */
+    coveredBytes: number;
+    /** ISO 8601 seal creation time. */
+    signedAt: string;
+    /** 128-bit hex id over both public keys. */
+    keyId: string;
+    /**
+     * OPTIONAL signer-asserted UUAID (IAASO-0004 attribution). Omitted entirely
+     * unless the signer supplies one. Signed like every other payload field, so it
+     * is immutable once sealed — but it is a CLAIM by the seal key, not proof of
+     * identity: it binds key -> uuaid only. See the identity note at the top of
+     * this file before relying on it for attribution.
+     */
+    uuaid?: string;
+    keys: {
+        ed25519: string;
+        mldsa65: string;
+        mldsa65Fpr: string;
+    };
+    sig: {
+        /** base64 Ed25519 signature over canonicalJson(payload). */
+        ed25519: string;
+        /** base64 ML-DSA-65 signature over canonicalJson(payload). */
+        mldsa65: string;
+    };
+}
+/** Result of verifying a seal's two signatures (does NOT check document binding). */
+export interface PqSealVerification {
+    /** Classical Ed25519 signature valid. */
+    ed25519: boolean;
+    /** Post-quantum ML-DSA-65 signature valid. */
+    mldsa65: boolean;
+    /** The embedded `mldsa65Fpr` matches SHA-256(mldsa65 public key). */
+    fingerprintOk: boolean;
+    /** The embedded `keyId` matches the digest of the two public keys it claims. */
+    keyIdOk: boolean;
+    /**
+     * The seal either asserts no UUAID, or asserts a structurally well-formed one.
+     * A seal carrying a malformed `uuaid` is rejected (fail-closed) even though its
+     * signatures are intact — a hand-crafted identity field is not something to
+     * pass downstream. True does NOT mean the assertion was verified.
+     */
+    uuaidOk: boolean;
+    /** Hybrid verdict: every check passed (both signatures + fingerprint + keyId + uuaid shape). */
+    ok: boolean;
+}
+export interface GeneratePqKeyBundleOptions {
+    /**
+     * 32-byte ML-DSA-65 keygen seed. The same seed always derives the same
+     * keypair — supply one for deterministic key provisioning (e.g. from a KMS
+     * or sealed secret). Omit for a fresh random seed.
+     */
+    mldsa65Seed?: Uint8Array;
+    /**
+     * PKCS#8 DER Ed25519 private key to use instead of generating a fresh one.
+     * Together with `mldsa65Seed` this makes the whole bundle deterministic.
+     */
+    ed25519Pkcs8?: Uint8Array;
+}
+/**
+ * Generate a fresh hybrid key bundle plus its derived public material. The bundle
+ * is what you wrap + persist; the public material is what you publish/pin as the
+ * signer's post-quantum identity. Pass `opts` to provision deterministically
+ * from existing key material instead of random generation.
+ */
+export declare function generatePqKeyBundle(opts?: GeneratePqKeyBundleOptions): {
+    bundle: PqKeyBundle;
+    public: PqPublicMaterial;
+};
+/** Rehydrate in-memory signing keys from a bundle (deterministically re-derives the ML-DSA keypair). */
+export declare function loadPqSigningKeys(bundle: PqKeyBundle): PqSigningKeys;
+/** Derive the publishable public material for a set of signing keys. */
+export declare function publicMaterialForKeys(keys: PqSigningKeys): PqPublicMaterial;
+/** AES-256-GCM-wrap a key bundle for persistence. `passphrase` ≥ 24 chars. */
+export declare function wrapPqKeyBundle(bundle: PqKeyBundle, passphrase: string): Uint8Array;
+/** Inverse of `wrapPqKeyBundle`. Throws on wrong passphrase / tampering (auth-tag mismatch). */
+export declare function unwrapPqKeyBundle(blob: Uint8Array, passphrase: string): PqKeyBundle;
+export interface BuildPqSealInput {
+    /** SHA-256 hex of the covered document bytes. */
+    digestHex: string;
+    /** Byte length the digest covers (the document prefix protected by the seal). */
+    coveredBytes: number;
+    keys: PqSigningKeys;
+    /** Seal timestamp. Defaults to now. */
+    signedAt?: Date;
+    /**
+     * OPTIONAL UUAID to assert as the signer identity (IAASO-0004 attribution).
+     * Omit — the default — to produce a seal byte-identical to pre-`uuaid` output.
+     * Rejected at build time unless structurally well-formed, so a malformed
+     * identifier can never be signed into a document. That check is structural
+     * only: passing it does not mean the UUAID registry will resolve or accept the
+     * identifier (see `isWellFormedUuaidAssertion`).
+     */
+    uuaid?: string;
+}
+/**
+ * Produce a hybrid seal over `digestHex`. Both signatures are computed over the
+ * exact same canonical bytes (the seal minus `sig`), binding digest, covered
+ * length, public keys, timestamp and keyId under BOTH schemes.
+ */
+export declare function buildPqSeal(input: BuildPqSealInput): PqSeal;
+/**
+ * Verify a seal's two signatures over its own payload (does NOT bind the seal to a
+ * document — the PDF-verify layer checks `digest` against the covered bytes).
+ *
+ * Fails CLOSED: any malformed field, wrong-length key/signature, or thrown error
+ * yields `ok:false` rather than propagating. The hybrid verdict requires BOTH
+ * signatures valid AND the ML-DSA fingerprint self-consistent.
+ */
+export declare function verifyPqSealSignatures(seal: PqSeal): PqSealVerification;
+/**
+ * Deterministic JSON serialization (recursively key-sorted, no insignificant
+ * whitespace) used as the signing input. The seal payload contains only strings
+ * and safe integers, so this is unambiguous without full RFC 8785 number
+ * canonicalization. Both signing and verification serialize the identical field
+ * set (payload = seal minus `sig`), so the two sides always agree.
+ */
+export declare function canonicalJson(value: unknown): string;
+export {};
+//# sourceMappingURL=pq-seal.d.ts.map

package/dist/pq-seal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pq-seal.d.ts","sourceRoot":"","sources":["../src/pq-seal.ts"],"names":[],"mappings":"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"}

package/dist/pq-seal.js

@@ -0,0 +1,345 @@
+// pq-seal.ts
+//
+// Hybrid post-quantum document seal — Ed25519 (classical) + ML-DSA-65 (FIPS 204,
+// module-lattice, quantum-resistant). This is the cryptographic core of e-sig's
+// post-quantum wedge: every sealed document carries TWO independent signatures
+// over the same payload, and a verifier requires BOTH to pass. If either scheme
+// is ever broken (a CRQC breaks Ed25519, or an unforeseen lattice attack dents
+// ML-DSA), the seal still stands on the other — the belt-and-suspenders
+// migration path NIST/CNSA 2.0 recommends over a hard cutover.
+//
+// The seal is a small canonical-JSON object signed over a SHA-256 digest of the
+// document bytes it covers. It does NOT replace the PDF's PKCS#7/PAdES RSA
+// signature (which stays valid in every PDF reader, including Adobe Acrobat —
+// no mainstream reader validates ML-DSA in PAdES yet, 2026). Instead the seal is
+// embedded in the PDF and the RSA /ByteRange signature is applied on top, so the
+// classical signature cryptographically covers the seal (see sign-pdf.ts).
+//
+// Identity model (v1): raw ML-DSA-65 public key + its SHA-256 fingerprint carried
+// in the seal (the `keyId` / `mldsa65Fpr`), verified TOFU / against-published-key.
+// A self-signed ML-DSA-65 X.509 certificate (RFC 9881 OID 2.16.840.1.101.3.4.3.18)
+// is a deliberate fast-follow, not required to ship the seal.
+//
+// Optional signer-asserted UUAID (`uuaid`): a signer MAY additionally assert the
+// UUAID identity it signs as, for IAASO-0004 (Media Provenance & Attribution)
+// attribution. The field is part of the signed payload, so it is bound under BOTH
+// schemes and cannot be added, removed or swapped on an existing seal.
+//
+//   What it proves:     the holder of THIS seal key claims to be THAT UUAID.
+//   What it does NOT:   that the UUAID's owner authorised this document.
+//
+// It is one half of a mutual binding (key -> uuaid). The other half (uuaid -> key,
+// i.e. the UUAID owner authenticating this seal key as theirs) lives in the UUAID
+// registry and is NOT established here. A relying party MUST NOT treat a bare
+// `uuaid` assertion as attribution: unmatched, it is worth exactly the TOFU
+// fingerprint next to it. Absent the second direction, an attacker who can mint
+// any seal can assert any UUAID.
+//
+// Backward compatibility: the field is omitted entirely when not supplied, so
+// seals from callers that never set it are byte-identical to pre-`uuaid` output,
+// and verifiers that predate the field still verify uuaid-bearing seals (the
+// signed payload is reconstructed generically as "the seal minus `sig`"). This is
+// why the field is additive at v1 rather than a version bump: bumping
+// PQ_SEAL_VERSION would break every already-deployed verifier, the added field
+// does not.
+//
+// Algorithm binding: both signatures are computed over the SAME canonical bytes —
+// the seal object minus its `sig` field — so digest, covered length, public keys,
+// timestamp and keyId are all bound together and cannot be swapped independently.
+import crypto from "node:crypto";
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { encryptKeyPem, decryptKeyPem } from "./cert-issuer.js";
+// ---------- Constants ----------
+/** Seal schema version. Bump on any breaking change to the signed payload shape. */
+export const PQ_SEAL_VERSION = 1;
+/** Hybrid algorithm identifier embedded in (and bound by) every seal. */
+export const PQ_SEAL_ALG = "hybrid-ed25519-ml-dsa-65";
+/** Bundle schema version for the wrapped at-rest key material. */
+const PQ_BUNDLE_VERSION = 1;
+/**
+ * DER SubjectPublicKeyInfo prefix for an Ed25519 key (RFC 8410 §4). A raw 32-byte
+ * Ed25519 public key is exactly this 12-byte prefix followed by the key, so we
+ * can round-trip raw keys ↔ node KeyObjects without a heavier ASN.1 dependency.
+ */
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+// FIPS 204 ML-DSA-65 sizes (raw, unencoded) — asserted defensively at load time.
+const MLDSA65_PUBLIC_LEN = 1952;
+const MLDSA65_SIGNATURE_LEN = 3309;
+const MLDSA65_SEED_LEN = 32;
+const ED25519_RAW_PUBLIC_LEN = 32;
+const ED25519_SIGNATURE_LEN = 64;
+/** Upper bound on an asserted UUAID string — bounds the seal, not the namespace. */
+const UUAID_MAX_LEN = 255;
+/**
+ * Structural shape of a UUAID: `uuaid:` followed by three or four
+ * `[A-Za-z0-9_-]` segments — covering both the compact profile
+ * (`uuaid:foundation:<objectType>:<uuid>`) and the federated profile
+ * (`uuaid:<subjectClass>:<jurisdiction>:<authority>:<localId>`).
+ *
+ * Deliberately structural only. Which subject classes and object types exist is
+ * a registry that evolves in the UUAID lane; hard-coding that enum here would
+ * make this package reject newly-registered-but-valid identifiers until it is
+ * republished, and it would bake another system's policy into a signed wire
+ * format. Semantic validation and resolution belong to the UUAID verifier.
+ */
+const UUAID_ASSERTION_RE = /^uuaid:[A-Za-z0-9_-]+:[A-Za-z0-9_-]+:[A-Za-z0-9_-]+(?::[A-Za-z0-9_-]+)?$/;
+/**
+ * True if `value` is a structurally well-formed UUAID assertion — the exact rule
+ * `buildPqSeal` enforces on input and `verifyPqSealSignatures` enforces on a
+ * seal that carries one. This is an envelope check, NOT proof that the
+ * identifier resolves, exists, or belongs to the signer.
+ *
+ * Accepted here does NOT imply accepted by the UUAID registry: the registry
+ * additionally enforces semantics this package deliberately does not know
+ * (registered subject classes and object types, canonical UUID form). Expect a
+ * band of identifiers this will sign and a resolver will still reject.
+ */
+export function isWellFormedUuaidAssertion(value) {
+    return typeof value === "string" && value.length <= UUAID_MAX_LEN && UUAID_ASSERTION_RE.test(value);
+}
+/**
+ * Generate a fresh hybrid key bundle plus its derived public material. The bundle
+ * is what you wrap + persist; the public material is what you publish/pin as the
+ * signer's post-quantum identity. Pass `opts` to provision deterministically
+ * from existing key material instead of random generation.
+ */
+export function generatePqKeyBundle(opts = {}) {
+    let ed25519Pkcs8;
+    let ed25519PublicRaw;
+    if (opts.ed25519Pkcs8) {
+        const privateKey = crypto.createPrivateKey({
+            key: Buffer.from(opts.ed25519Pkcs8),
+            format: "der",
+            type: "pkcs8",
+        });
+        if (privateKey.asymmetricKeyType !== "ed25519") {
+            throw new Error(`generatePqKeyBundle: ed25519Pkcs8 must be an Ed25519 key, got ${privateKey.asymmetricKeyType}`);
+        }
+        ed25519Pkcs8 = Buffer.from(opts.ed25519Pkcs8);
+        ed25519PublicRaw = rawEd25519FromKeyObject(crypto.createPublicKey(privateKey));
+    }
+    else {
+        const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+        ed25519Pkcs8 = privateKey.export({ type: "pkcs8", format: "der" });
+        ed25519PublicRaw = rawEd25519FromKeyObject(publicKey);
+    }
+    if (opts.mldsa65Seed && opts.mldsa65Seed.length !== MLDSA65_SEED_LEN) {
+        throw new Error(`generatePqKeyBundle: mldsa65Seed must be ${MLDSA65_SEED_LEN} bytes, got ${opts.mldsa65Seed.length}`);
+    }
+    const seed = opts.mldsa65Seed ? Buffer.from(opts.mldsa65Seed) : crypto.randomBytes(MLDSA65_SEED_LEN);
+    const { publicKey: mldsa65PublicKey } = ml_dsa65.keygen(seed);
+    const bundle = {
+        v: PQ_BUNDLE_VERSION,
+        ed25519Pkcs8: b64(ed25519Pkcs8),
+        mldsa65Seed: b64(seed),
+    };
+    return { bundle, public: publicMaterial(ed25519PublicRaw, mldsa65PublicKey) };
+}
+/** Rehydrate in-memory signing keys from a bundle (deterministically re-derives the ML-DSA keypair). */
+export function loadPqSigningKeys(bundle) {
+    if (bundle.v !== PQ_BUNDLE_VERSION) {
+        throw new Error(`loadPqSigningKeys: unknown bundle version ${bundle.v}`);
+    }
+    const ed25519PrivateKey = crypto.createPrivateKey({
+        key: Buffer.from(bundle.ed25519Pkcs8, "base64"),
+        format: "der",
+        type: "pkcs8",
+    });
+    const ed25519PublicRaw = rawEd25519FromKeyObject(crypto.createPublicKey(ed25519PrivateKey));
+    const seed = Buffer.from(bundle.mldsa65Seed, "base64");
+    if (seed.length !== MLDSA65_SEED_LEN) {
+        throw new Error(`loadPqSigningKeys: ML-DSA seed must be ${MLDSA65_SEED_LEN} bytes, got ${seed.length}`);
+    }
+    const { publicKey, secretKey } = ml_dsa65.keygen(seed);
+    return {
+        ed25519PrivateKey,
+        ed25519PublicRaw,
+        mldsa65SecretKey: secretKey,
+        mldsa65PublicKey: publicKey,
+    };
+}
+/** Derive the publishable public material for a set of signing keys. */
+export function publicMaterialForKeys(keys) {
+    return publicMaterial(keys.ed25519PublicRaw, keys.mldsa65PublicKey);
+}
+// ---------- At-rest wrapping (reuses cert-issuer AES-256-GCM) ----------
+/** AES-256-GCM-wrap a key bundle for persistence. `passphrase` ≥ 24 chars. */
+export function wrapPqKeyBundle(bundle, passphrase) {
+    return encryptKeyPem(JSON.stringify(bundle), passphrase);
+}
+/** Inverse of `wrapPqKeyBundle`. Throws on wrong passphrase / tampering (auth-tag mismatch). */
+export function unwrapPqKeyBundle(blob, passphrase) {
+    const bundle = JSON.parse(decryptKeyPem(blob, passphrase));
+    if (bundle.v !== PQ_BUNDLE_VERSION) {
+        throw new Error(`unwrapPqKeyBundle: unknown bundle version ${bundle.v}`);
+    }
+    return bundle;
+}
+/**
+ * Produce a hybrid seal over `digestHex`. Both signatures are computed over the
+ * exact same canonical bytes (the seal minus `sig`), binding digest, covered
+ * length, public keys, timestamp and keyId under BOTH schemes.
+ */
+export function buildPqSeal(input) {
+    if (!/^[0-9a-f]{64}$/.test(input.digestHex)) {
+        throw new Error("buildPqSeal: digestHex must be 64 lowercase hex chars (SHA-256)");
+    }
+    if (!Number.isInteger(input.coveredBytes) || input.coveredBytes <= 0) {
+        throw new Error("buildPqSeal: coveredBytes must be a positive integer");
+    }
+    if (input.uuaid !== undefined && !isWellFormedUuaidAssertion(input.uuaid)) {
+        throw new Error("buildPqSeal: uuaid must be a well-formed UUAID (uuaid:<3-or-4 segments>) — refusing to sign a malformed identity claim");
+    }
+    const pub = publicMaterialForKeys(input.keys);
+    const payload = {
+        v: PQ_SEAL_VERSION,
+        alg: PQ_SEAL_ALG,
+        over: "sha256",
+        digest: input.digestHex,
+        coveredBytes: input.coveredBytes,
+        signedAt: (input.signedAt ?? new Date()).toISOString(),
+        keyId: pub.keyId,
+        // Spread-in rather than `uuaid: input.uuaid` so the key is ABSENT (not
+        // `undefined`) when unused — canonicalJson would otherwise serialize it and
+        // change the signed bytes of every seal that never asked for attribution.
+        ...(input.uuaid !== undefined ? { uuaid: input.uuaid } : {}),
+        keys: { ed25519: pub.ed25519, mldsa65: pub.mldsa65, mldsa65Fpr: pub.mldsa65Fpr },
+    };
+    const signingInput = Buffer.from(canonicalJson(payload), "utf8");
+    const ed25519Sig = crypto.sign(null, signingInput, input.keys.ed25519PrivateKey);
+    const mldsa65Sig = ml_dsa65.sign(signingInput, input.keys.mldsa65SecretKey);
+    return { ...payload, sig: { ed25519: b64(ed25519Sig), mldsa65: b64(mldsa65Sig) } };
+}
+/**
+ * Verify a seal's two signatures over its own payload (does NOT bind the seal to a
+ * document — the PDF-verify layer checks `digest` against the covered bytes).
+ *
+ * Fails CLOSED: any malformed field, wrong-length key/signature, or thrown error
+ * yields `ok:false` rather than propagating. The hybrid verdict requires BOTH
+ * signatures valid AND the ML-DSA fingerprint self-consistent.
+ */
+export function verifyPqSealSignatures(seal) {
+    const fail = {
+        ed25519: false,
+        mldsa65: false,
+        fingerprintOk: false,
+        keyIdOk: false,
+        uuaidOk: false,
+        ok: false,
+    };
+    try {
+        if (seal.v !== PQ_SEAL_VERSION || seal.alg !== PQ_SEAL_ALG || seal.over !== "sha256")
+            return fail;
+        const ed25519Pub = Buffer.from(seal.keys.ed25519, "base64");
+        const mldsa65Pub = Buffer.from(seal.keys.mldsa65, "base64");
+        const ed25519Sig = Buffer.from(seal.sig.ed25519, "base64");
+        const mldsa65Sig = Buffer.from(seal.sig.mldsa65, "base64");
+        if (ed25519Pub.length !== ED25519_RAW_PUBLIC_LEN)
+            return fail;
+        if (mldsa65Pub.length !== MLDSA65_PUBLIC_LEN)
+            return fail;
+        if (ed25519Sig.length !== ED25519_SIGNATURE_LEN)
+            return fail;
+        if (mldsa65Sig.length !== MLDSA65_SIGNATURE_LEN)
+            return fail;
+        // Reconstruct the exact signed payload: the seal minus `sig`.
+        const { sig: _sig, ...payload } = seal;
+        void _sig;
+        const signingInput = Buffer.from(canonicalJson(payload), "utf8");
+        // Self-consistency of the identity fields carried in the (signed) payload:
+        // fingerprint over the ML-DSA key, and keyId over BOTH public keys. These
+        // don't add trust (the keys are the seal's own), but they make the identity
+        // fields the signature commits to actually correspond to the keys present.
+        const fingerprintOk = sha256Hex(mldsa65Pub) === seal.keys.mldsa65Fpr;
+        const expectedKeyId = crypto
+            .createHash("sha256")
+            .update(ed25519Pub)
+            .update(mldsa65Pub)
+            .digest("hex")
+            .slice(0, 32);
+        const keyIdOk = seal.keyId === expectedKeyId;
+        // An absent `uuaid` asserts nothing and is fine; a present one must be
+        // structurally sound. Both cases are already covered by the signatures —
+        // this only rejects identity fields no honest signer could have produced.
+        const uuaidOk = seal.uuaid === undefined || isWellFormedUuaidAssertion(seal.uuaid);
+        let ed25519 = false;
+        try {
+            ed25519 = crypto.verify(null, signingInput, ed25519RawToPublicKey(ed25519Pub), ed25519Sig);
+        }
+        catch {
+            ed25519 = false;
+        }
+        let mldsa65 = false;
+        try {
+            mldsa65 = ml_dsa65.verify(mldsa65Sig, signingInput, mldsa65Pub);
+        }
+        catch {
+            mldsa65 = false;
+        }
+        return {
+            ed25519,
+            mldsa65,
+            fingerprintOk,
+            keyIdOk,
+            uuaidOk,
+            ok: ed25519 && mldsa65 && fingerprintOk && keyIdOk && uuaidOk,
+        };
+    }
+    catch {
+        return fail;
+    }
+}
+// ---------- Internals ----------
+function publicMaterial(ed25519PublicRaw, mldsa65PublicKey) {
+    const ed25519 = b64(ed25519PublicRaw);
+    const mldsa65 = b64(mldsa65PublicKey);
+    const mldsa65Fpr = sha256Hex(mldsa65PublicKey);
+    const keyId = crypto
+        .createHash("sha256")
+        .update(ed25519PublicRaw)
+        .update(mldsa65PublicKey)
+        .digest("hex")
+        .slice(0, 32);
+    return { ed25519, mldsa65, mldsa65Fpr, keyId };
+}
+/** Extract the raw 32-byte Ed25519 public key from a node KeyObject (SPKI tail). */
+function rawEd25519FromKeyObject(pub) {
+    const spki = pub.export({ type: "spki", format: "der" });
+    return Uint8Array.prototype.slice.call(spki, spki.length - ED25519_RAW_PUBLIC_LEN);
+}
+/** Rebuild a node public KeyObject from a raw 32-byte Ed25519 key. */
+function ed25519RawToPublicKey(raw) {
+    if (raw.length !== ED25519_RAW_PUBLIC_LEN) {
+        throw new Error(`ed25519 raw public key must be ${ED25519_RAW_PUBLIC_LEN} bytes`);
+    }
+    return crypto.createPublicKey({
+        key: Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(raw)]),
+        format: "der",
+        type: "spki",
+    });
+}
+function sha256Hex(bytes) {
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+function b64(bytes) {
+    return Buffer.from(bytes).toString("base64");
+}
+/**
+ * Deterministic JSON serialization (recursively key-sorted, no insignificant
+ * whitespace) used as the signing input. The seal payload contains only strings
+ * and safe integers, so this is unambiguous without full RFC 8785 number
+ * canonicalization. Both signing and verification serialize the identical field
+ * set (payload = seal minus `sig`), so the two sides always agree.
+ */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => canonicalJson(v)).join(",")}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+}
+//# sourceMappingURL=pq-seal.js.map

package/dist/pq-seal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pq-seal.js","sourceRoot":"","sources":["../src/pq-seal.ts"],"names":[],"mappings":"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"}

package/dist/pq-verify.d.ts

@@ -0,0 +1,99 @@
+import { type VerifyResult } from "./verify-pdf.js";
+export interface PqSealVerdict {
+    /** A seal was found and parsed. */
+    present: boolean;
+    /** Hybrid verdict: digest binds to the document AND both signatures + fingerprint valid. */
+    ok: boolean;
+    /** SHA-256 over the covered document prefix equals the seal's `digest`. */
+    digestBinds?: boolean;
+    /** Classical Ed25519 signature valid. */
+    ed25519?: boolean;
+    /** Post-quantum ML-DSA-65 signature valid. */
+    mldsa65?: boolean;
+    /** Embedded ML-DSA fingerprint matches its public key. */
+    fingerprintOk?: boolean;
+    /** A `signerCert` was supplied AND it is a valid ML-DSA-65 cert for this seal's key. */
+    certIdentityOk?: boolean;
+    alg?: string;
+    keyId?: string;
+    /** ML-DSA-65 public-key fingerprint — the post-quantum signer identity to pin. */
+    mldsa65Fpr?: string;
+    signedAt?: string;
+    coveredBytes?: number;
+    /**
+     * The signer-asserted UUAID carried in the seal, when present (IAASO-0004).
+     * ASSERTION, NOT ATTRIBUTION: a valid seal proves the seal key claimed this
+     * identity, never that the identity's owner authorised the document. Treat it
+     * as attribution only once an independent uuaid -> key direction has been
+     * checked (a UUAID-side registration of this seal key). Unmatched, it carries
+     * no more weight than `mldsa65Fpr`.
+     */
+    uuaid?: string;
+    /** A `expectedUuaid` was supplied AND the seal asserts exactly that UUAID. */
+    uuaidMatches?: boolean;
+    failures: string[];
+}
+export interface VerifyPqSealOptions {
+    /**
+     * Pin the expected post-quantum signer. When set, the seal's ML-DSA-65
+     * fingerprint MUST equal this value (case-insensitive hex) or verification
+     * fails — this is how a relying party asserts "signed by THIS party" in-band
+     * (the raw-key TOFU trust model). Compare against a fingerprint you published
+     * or received out-of-band.
+     */
+    expectedMldsa65Fpr?: string;
+    /**
+     * A self-signed ML-DSA-65 X.509 certificate (PEM or DER) asserting the signer
+     * identity. When set, the cert must be valid AND its public key must be the one
+     * that produced the seal — the X.509 upgrade of `expectedMldsa65Fpr`.
+     */
+    signerCert?: string | Uint8Array;
+    /**
+     * Pin the expected signer-asserted UUAID. When set, the seal MUST carry
+     * exactly this `uuaid` (case-sensitive — UUAID segments are case-preserving)
+     * or verification fails.
+     *
+     * This pins an ASSERTION. It answers "does this seal claim the identity I
+     * expected?", not "does that identity vouch for this key?" — the relying party
+     * still supplies the trust, exactly as with `expectedMldsa65Fpr`. Pinning a
+     * UUAID you obtained from the document itself proves nothing.
+     */
+    expectedUuaid?: string;
+}
+/**
+ * Verify the embedded post-quantum seal against the document bytes. Never throws;
+ * a missing or malformed seal returns `{ present:false, ok:false }`. Pass
+ * `expectedMldsa65Fpr` to also pin the signer identity.
+ */
+export declare function verifyPqSeal(pdf: Buffer, opts?: VerifyPqSealOptions): PqSealVerdict;
+export interface DocumentVerification {
+    /**
+     * Overall: the classical signature is valid AND, if a post-quantum seal is
+     * present, it too is valid and lies within the classically-signed region. A
+     * document with no seal is judged on the classical signature alone (backward
+     * compatible); callers that REQUIRE post-quantum protection should also assert
+     * `postQuantum.present`.
+     */
+    ok: boolean;
+    /** Classical PAdES / PKCS#7 (RSA) verification. */
+    classical: VerifyResult;
+    /** Post-quantum hybrid seal verification. */
+    postQuantum: PqSealVerdict;
+}
+export interface VerifyDocumentOptions extends VerifyPqSealOptions {
+    /**
+     * Require a valid post-quantum seal. When true, a document without a seal (or
+     * with an invalid one) fails overall — use this where post-quantum protection
+     * is mandatory, to prevent a silent downgrade to classical-only.
+     */
+    requirePq?: boolean;
+}
+/**
+ * Full document verification: classical PAdES signature + post-quantum hybrid
+ * seal. Also asserts that the seal-covered region falls within the RSA-signed
+ * prefix, so the classical signature genuinely protects the seal. Pass
+ * `requirePq` to reject unsealed documents and `expectedMldsa65Fpr` to pin the
+ * post-quantum signer.
+ */
+export declare function verifyDocument(pdf: Buffer, opts?: VerifyDocumentOptions): DocumentVerification;
+//# sourceMappingURL=pq-verify.d.ts.map

package/dist/pq-verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pq-verify.d.ts","sourceRoot":"","sources":["../src/pq-verify.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAKxE,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,4FAA4F;IAC5F,EAAE,EAAE,OAAO,CAAC;IACZ,2EAA2E;IAC3E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yCAAyC;IACzC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wFAAwF;IACxF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IACjC;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,aAAa,CAgFvF;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,EAAE,EAAE,OAAO,CAAC;IACZ,mDAAmD;IACnD,SAAS,EAAE,YAAY,CAAC;IACxB,6CAA6C;IAC7C,WAAW,EAAE,aAAa,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,oBAAoB,CA+BlG"}