@zanii/certify 0.0.0-stage → 0.5.0

package/dist/cli.js

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+// spec/cli.md: the `certify` command. Its output is byte-identical with the Python `certify`.
+import { readFileSync } from "node:fs";
+import { canonicalBytes } from "@zanii/core";
+import { credentialHash, resolveIssuer, } from "@zanii/credentials";
+import { claimReasons, verifyCertificate } from "./certificate.js";
+import { verifyAuditAttestation } from "./audit.js";
+import messages from "./cli-messages.json" with { type: "json" };
+import { buildFingerprint, promptSha256, sha256Bytes, toolsSha256 } from "./fingerprint.js";
+import { pqPolicyOf } from "./pq.js";
+import { fetchJsonBounded, resolveIssuerDetailed } from "./issuer-resolution.js";
+import { registerTrust } from "./register.js";
+import { isDid, isInt, isIso, isObj } from "./shared.js";
+import { verifyStatus } from "./status.js";
+import { isIssuerPolicy } from "./verification-policy.js";
+import { witnessReasons } from "./witness.js";
+import { verifyCertificateVc } from "./vc.js";
+/** spec/cli.md section 4. */
+export const EXIT = { valid: 0, invalid: 1, partial: 2, usage: 3, online: 4 };
+const OPTIONS = {
+    verify: ["--status", "--issuer-doc", "--fingerprint", "--online", "--now", "--lang", "--pq", "--audit", "--trusted-bodies", "--body-register", "--status-witness", "--release-policy", "--strict-policy"],
+    fingerprint: ["--model", "--prompt-file", "--tools-file", "--policy-file", "--knowledge-file", "--lang"],
+};
+// Control and bidirectional formatting characters from input files are not written to the terminal.
+const UNSAFE = /[\u0000-\u001f\u007f-\u009f‎‏‪-‮⁦-⁩]/g;
+/** A value from an input file as printed: strings and integers as they are, nothing for a missing value, `?` otherwise. */
+const show = (v) => typeof v === "string" ? v.replace(UNSAFE, "?") : Number.isInteger(v) ? String(v) : v == null ? "" : "?";
+class Stop extends Error {
+    exit;
+    constructor(text, exit) {
+        super(text);
+        this.exit = exit;
+    }
+}
+/** Run `certify` with `argv` (without the program name); returns the exit code. */
+export async function main(argv, io = {}) {
+    const out = io.out ?? ((s) => process.stdout.write(s));
+    const err = io.err ?? ((s) => process.stderr.write(s));
+    const li = argv.indexOf("--lang");
+    const lang = argv[li + 1] === "ar" && li >= 0 ? "ar" : "en";
+    const t = (key, ...args) => messages[lang][key].replace(/\{(\d)\}/g, (_, i) => show(args[Number(i)]));
+    const fail = (key, ...args) => new Stop(t("error", t(key, ...args)), EXIT.usage);
+    try {
+        const [cmd, ...rest] = argv;
+        if (cmd === "--help-v2") {
+            out(`${t("usage_v2")}\n`);
+            return EXIT.valid;
+        }
+        if (cmd === "--help" || cmd === "-h") {
+            out(`${t("usage")}\n`);
+            return EXIT.valid;
+        }
+        if (!cmd || !OPTIONS[cmd])
+            throw new Stop(t("usage"), EXIT.usage);
+        const pos = [];
+        const opts = {};
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (!a.startsWith("--"))
+                pos.push(a);
+            else if (!OPTIONS[cmd].includes(a))
+                throw fail("unknown_option", a);
+            else if (i + 1 >= rest.length)
+                throw fail("missing_value", a);
+            else
+                opts[a] = rest[++i];
+        }
+        if (opts["--lang"] !== undefined && opts["--lang"] !== "en" && opts["--lang"] !== "ar")
+            throw fail("bad_lang");
+        const read = (path) => {
+            try {
+                return readFileSync(path);
+            }
+            catch {
+                throw fail("cannot_read", path);
+            }
+        };
+        const text = (path) => {
+            try {
+                return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(read(path));
+            }
+            catch (e) {
+                throw e instanceof Stop ? e : fail("not_text", path);
+            }
+        };
+        const json = (path) => {
+            const s = text(path);
+            try {
+                return JSON.parse(s);
+            }
+            catch {
+                throw fail("not_json", path);
+            }
+        };
+        if (cmd === "fingerprint") {
+            if (pos.length || opts["--model"] === undefined)
+                throw new Stop(t("usage"), EXIT.usage);
+            const p = opts["--prompt-file"];
+            const tf = opts["--tools-file"];
+            let tools = tf === undefined ? null : json(tf);
+            if (isObj(tools) && Array.isArray(tools.tools))
+                tools = tools.tools;
+            if (tf !== undefined && !Array.isArray(tools))
+                throw fail("not_tools", tf);
+            const pack = (k) => (opts[k] === undefined ? null : sha256Bytes(read(opts[k])));
+            let fp;
+            try {
+                fp = buildFingerprint({
+                    model: opts["--model"],
+                    prompt: p === undefined ? null : promptSha256(text(p)),
+                    tools: Array.isArray(tools) ? toolsSha256(tools) : null,
+                    policy: pack("--policy-file"),
+                    knowledge: pack("--knowledge-file"),
+                });
+            }
+            catch (e) {
+                throw e instanceof Stop ? e : new Stop(t("error", e.message), EXIT.usage);
+            }
+            out(`${new TextDecoder().decode(canonicalBytes(fp))}\n`);
+            return EXIT.valid;
+        }
+        // verify
+        if (pos.length !== 1)
+            throw new Stop(t("usage"), EXIT.usage);
+        const now = opts["--now"];
+        if (now !== undefined && !isIso(now))
+            throw fail("bad_now");
+        const input = json(pos[0]);
+        // A W3C VC export (spec/vc.md) is verified, then its certificate is checked as any other.
+        const vc = isObj(input) && Array.isArray(input.type) && input.type.includes("VerifiableCredential") ? verifyCertificateVc(input, now ? { at: now } : {}) : null;
+        if (vc && !vc.certificate) {
+            out(`${t("vc_bad")}\n${t("result_invalid")}\n`);
+            return EXIT.invalid;
+        }
+        const cert = (vc?.certificate ?? input);
+        let status;
+        let list;
+        let onlineStatusPq;
+        const takeStatus = (v, where) => {
+            if (isObj(v) && v.type === "certify.status")
+                status = v;
+            else if (isObj(v) && isObj(v.status) && v.status.type === "certify.status" && isObj(v.revocation_list) && v.revocation_list.type === "revocation_list") {
+                status = v.status;
+                list = v.revocation_list;
+                if (isObj(v.pq))
+                    onlineStatusPq = v.pq;
+            }
+            else
+                throw fail("not_status", where);
+        };
+        if (opts["--status"] !== undefined)
+            takeStatus(json(opts["--status"]), opts["--status"]);
+        const base = opts["--online"];
+        const doFetch = io.fetch ?? fetch;
+        if (base !== undefined && !status) {
+            let url = base;
+            try {
+                const u = new URL("/v1/status", base);
+                if (u.protocol !== "https:" && u.protocol !== "http:")
+                    throw new Error("not http(s)");
+                url = u.href;
+                const res = await fetchJsonBounded(url, { fetch: doFetch, maxBytes: 8_388_608 });
+                if (!res.ok)
+                    throw new Error(res.code);
+                takeStatus(res.document, url);
+            }
+            catch (e) {
+                throw e instanceof Stop ? e : new Stop(t("error", t("online_failed", url)), EXIT.online);
+            }
+        }
+        let resolver;
+        // certificate.md section 5: the issuer document's status_dids, when it lists them
+        let issuerDoc;
+        let resolutionFailure;
+        if (opts["--issuer-doc"] !== undefined) {
+            const doc = json(opts["--issuer-doc"]);
+            issuerDoc = doc;
+            resolver = (d, domain) => resolveIssuer(d, domain, { fetchImpl: async () => Response.json(doc) });
+        }
+        else if (base !== undefined) {
+            const resolved = await resolveIssuerDetailed(String(cert?.issuer), String(cert?.issuer_domain), { fetch: doFetch });
+            if (resolved.ok)
+                issuerDoc = resolved.document;
+            else
+                resolutionFailure = resolved;
+            resolver = (d, domain) => issuerDoc === undefined ? null : resolveIssuer(d, domain, { fetchImpl: async () => Response.json(issuerDoc) });
+        }
+        const sd = isObj(issuerDoc) ? issuerDoc.status_dids : undefined;
+        const statusDids = Array.isArray(sd) ? sd.filter((x) => typeof x === "string") : undefined;
+        const fingerprint = opts["--fingerprint"] === undefined ? undefined : json(opts["--fingerprint"]);
+        const policyFile = opts["--strict-policy"] === undefined ? undefined : json(opts["--strict-policy"]);
+        if (policyFile !== undefined && !isIssuerPolicy(policyFile))
+            throw fail("bad_policy", "--strict-policy");
+        const issuerPolicy = isIssuerPolicy(policyFile) ? policyFile : undefined;
+        const audit = opts["--audit"] === undefined ? undefined : json(opts["--audit"]);
+        if (audit !== undefined && (!isObj(audit) || audit.type !== "certify.audit-attestation"))
+            throw fail("bad_policy", "--audit");
+        const trustedBodies = opts["--trusted-bodies"] === undefined ? undefined : json(opts["--trusted-bodies"]);
+        if (trustedBodies !== undefined && (!Array.isArray(trustedBodies) || trustedBodies.length > 64 || !trustedBodies.every(isDid)))
+            throw fail("bad_policy", "--trusted-bodies");
+        const bodyRegister = opts["--body-register"] === undefined ? undefined : json(opts["--body-register"]);
+        if (bodyRegister !== undefined && (!isObj(bodyRegister) || !isDid(bodyRegister.owner) || !Array.isArray(bodyRegister.boards) || bodyRegister.boards.length > 10_000 || !Array.isArray(bodyRegister.registers) || bodyRegister.registers.length > 10_000))
+            throw fail("bad_policy", "--body-register");
+        const statusWitness = opts["--status-witness"] === undefined ? undefined : json(opts["--status-witness"]);
+        if (statusWitness !== undefined && (!isObj(statusWitness) || !isObj(statusWitness.checkpoint) || !Array.isArray(statusWitness.proof) || statusWitness.proof.length > 32
+            || !Array.isArray(statusWitness.cosignatures) || statusWitness.cosignatures.length > 64 || !Array.isArray(statusWitness.trusted) || statusWitness.trusted.length > 64
+            || !statusWitness.trusted.every(isDid) || !isInt(statusWitness.k, 1, 64)))
+            throw fail("bad_policy", "--status-witness");
+        const releases = opts["--release-policy"] === undefined ? undefined : json(opts["--release-policy"]);
+        if (releases !== undefined && !isObj(releases))
+            throw fail("bad_policy", "--release-policy");
+        // spec/cli.md section 2: `--pq <file>` holds the co-signatures ({certificate, status} or one
+        // for the certificate); `--pq off` opts out of the issuer document's require_pq, and is printed.
+        const pqArg = opts["--pq"];
+        const pqFile = pqArg === undefined || pqArg === "off" ? undefined : json(pqArg);
+        const pqPair = isObj(pqFile) && pqFile.type !== "certify.pq-signature" ? pqFile : { certificate: pqFile };
+        let certPq = isObj(pqPair.certificate) ? pqPair.certificate : undefined;
+        let statusPq = isObj(pqPair.status) ? pqPair.status : undefined;
+        if (pqFile !== undefined && !certPq && !statusPq)
+            throw fail("not_pq", pqArg);
+        const c = (isObj(cert) ? cert : {});
+        if (c.v !== 1 || c.type !== "credential" || !c.issuer || !c.holder || !c.issuer_domain) {
+            out(`${t("not_certificate")}\n${t("result_invalid")}\n`);
+            return EXIT.invalid;
+        }
+        const onlinePq = base !== undefined && pqArg !== "off" && (pqPolicyOf(issuerPolicy ?? issuerDoc, false, String(c.issued_at)) === "required");
+        if (onlinePq) {
+            statusPq ??= onlineStatusPq;
+            if (status && !statusPq) {
+                const url = new URL("/v1/status", base).href;
+                const response = await fetchJsonBounded(url, { fetch: doFetch, maxBytes: 8_388_608 });
+                if (!response.ok)
+                    throw new Stop(t("error", t("online_failed", url)), EXIT.online);
+                if (isObj(response.document) && isObj(response.document.pq))
+                    statusPq = response.document.pq;
+            }
+            if (!certPq) {
+                let url;
+                try {
+                    url = new URL(`/v1/certificates/${encodeURIComponent(credentialHash(cert))}`, base).href;
+                }
+                catch {
+                    throw new Stop(t("error", t("online_failed", base)), EXIT.online);
+                }
+                const response = await fetchJsonBounded(url, { fetch: doFetch, maxBytes: 1_048_576 });
+                if (!response.ok)
+                    throw new Stop(t("error", t("online_failed", url)), EXIT.online);
+                if (isObj(response.document) && isObj(response.document.pq))
+                    certPq = response.document.pq;
+            }
+        }
+        const r = await verifyCertificate(cert, {
+            ...(status ? { status } : {}),
+            ...(list ? { revocationList: list } : {}),
+            ...(resolver ? { resolver } : {}),
+            ...(statusDids ? { statusDids } : {}),
+            ...(fingerprint ? { fingerprint } : {}),
+            ...(now ? { now } : {}),
+            ...(issuerDoc !== undefined ? { issuerDoc } : {}),
+            ...(pqArg === "off" ? { allowNoPq: true } : {}),
+            ...(certPq ? { pq: certPq } : {}),
+            ...(statusPq ? { statusPq } : {}),
+            ...(issuerPolicy ? { issuerPolicy } : {}), ...(audit !== undefined ? { audit } : {}), ...(trustedBodies ? { trustedBodies } : {}),
+            ...(bodyRegister ? { bodyRegister } : {}), ...(statusWitness ? { statusWitness } : {}), ...(releases !== undefined ? { releases } : {}),
+        });
+        const cr = r.credential.reasons;
+        const claim = isObj(c.claim) ? c.claim : {};
+        const lines = [
+            t("certificate", credentialHash(cert)),
+            t("holder", c.holder),
+            t("profile", claim.profile, claim.level),
+            t("issuer", c.issuer, c.issuer_domain),
+            t("expires", c.exp),
+        ];
+        const marks = [];
+        const check = (name, mark, detail) => {
+            marks.push(mark);
+            lines.push(`[${mark}] ${t(name)}: ${detail}`);
+        };
+        if (vc)
+            check("vc", "ok", t("vc_ok"));
+        const sigBad = cr.includes("bad issuer signature");
+        check("signature", sigBad ? "fail" : "ok", t(sigBad ? "sig_bad" : "sig_ok"));
+        const expBad = cr.some((x) => x === "invalid exp" || x.startsWith("credential expired on"));
+        check("expiry", expBad ? "fail" : "ok", t(expBad ? "exp_bad" : "exp_ok", c.exp));
+        const claimBad = claimReasons(cert).length > 0;
+        check("claim", claimBad ? "fail" : "ok", t(claimBad ? "claim_bad" : "claim_ok"));
+        if (!status)
+            check("status", "skip", t("not_supplied"));
+        else {
+            // after a key rotation the document is signed by another DID the issuer domain publishes
+            const rotated = status.issuer !== c.issuer && !!statusDids?.includes(status.issuer) && !!resolver && !!(await resolver(status.issuer, String(c.issuer_domain)));
+            const s = verifyStatus(status, { issuer: rotated ? status.issuer : String(c.issuer), ...(now ? { now } : {}) });
+            const e = r.status;
+            if (s.reasons.some((x) => !x.startsWith("status document expired on")) || r.reasons.includes("status document is not signed by a current status key of the issuer"))
+                check("status", "fail", t("status_invalid"));
+            else if (s.freshness === "stale")
+                check("status", "fail", t("status_stale", status.valid_until));
+            else if (!e)
+                check("status", "fail", t("status_unlisted"));
+            else if (e.status === "valid")
+                check("status", "ok", t("status_valid", e.since));
+            else
+                check("status", "fail", t(e.status === "suspended" ? "status_suspended" : "status_revoked", e.reason, e.since));
+        }
+        if (!list)
+            check("revocation", "skip", t("not_supplied"));
+        else if (["revocation list is from a different issuer", "revocation list signature is invalid", "revocation list is not a revocation list (v1)", "revocation list is not signed by a current status key of the issuer"].some((x) => cr.includes(x)))
+            check("revocation", "fail", t("rev_invalid"));
+        else if (cr.includes("credential has been REVOKED by its issuer"))
+            check("revocation", "fail", t("rev_revoked"));
+        else if (cr.some((x) => x.startsWith("revocation list expired on")))
+            check("revocation", "fail", t("rev_stale", list.valid_until));
+        else
+            check("revocation", "ok", t("rev_ok"));
+        if (!resolver)
+            check("issuer_domain", "skip", t("issuer_skip"));
+        else {
+            const bad = cr.some((x) => x.includes(" is not published by "));
+            check("issuer_domain", bad ? "fail" : "ok", resolutionFailure && resolutionFailure.code !== "key_missing" ? t("issuer_resolution", resolutionFailure.code) : t(bad ? "issuer_bad" : "issuer_ok", c.issuer_domain));
+        }
+        if (r.fingerprint === null)
+            check("fingerprint", "skip", t("not_supplied"));
+        else
+            check("fingerprint", r.fingerprint === "match" ? "ok" : "fail", t(r.fingerprint === "match" ? "fp_ok" : "fp_bad"));
+        if (claim.level === 3) {
+            if (audit === undefined)
+                check("audit", "skip", t("audit_skip"));
+            else {
+                const reg = bodyRegister ? registerTrust(cert, audit?.body, bodyRegister) : null;
+                const checked = verifyAuditAttestation(audit, { certificate: cert, trustedBodies: reg?.trusted ?? trustedBodies, ...(now ? { now } : {}) });
+                const bad = !!reg?.reasons.length || !checked.ok;
+                check("audit", bad ? "fail" : "ok", t(bad ? "audit_bad" : "audit_ok"));
+            }
+        }
+        if (statusWitness) {
+            const checked = status ? witnessReasons(status, statusWitness) : null;
+            check("witness", checked && !checked.reasons.length ? "ok" : "fail", t(checked && !checked.reasons.length ? "policy_ok" : "policy_bad"));
+        }
+        for (const [policy, key, prefix] of [[issuerPolicy, "issuer_policy", "issuer policy:"], [releases, "release_policy", "release policy:"]])
+            if (policy !== undefined) {
+                const bad = r.reasons.filter((reason) => reason.startsWith(prefix));
+                check(key, bad.length ? "fail" : "ok", bad.length ? bad.join("; ") : t("policy_ok"));
+            }
+        if (r.pqPolicy === "opted_out")
+            check("pq", "skip", t("pq_optout"));
+        else if (r.pqPolicy === "required" || pqFile !== undefined || onlinePq || issuerPolicy?.require_pq) {
+            const bad = r.reasons.filter((x) => x.includes("post-quantum"));
+            if (!bad.length)
+                check("pq", "ok", t("pq_ok"));
+            else
+                check("pq", "fail", t(bad.every((x) => x.endsWith("a post-quantum signature is required")) ? "pq_missing" : "pq_bad"));
+        }
+        // A reason no line explains (none is expected) still makes the certificate invalid.
+        const failed = marks.includes("fail") || (!marks.includes("skip") && !r.ok);
+        const code = failed ? EXIT.invalid : marks.includes("skip") ? EXIT.partial : EXIT.valid;
+        lines.push(t(code === EXIT.valid ? "result_valid" : code === EXIT.invalid ? "result_invalid" : "result_partial"));
+        out(`${lines.join("\n")}\n`);
+        return resolutionFailure && ["dns", "tls", "timeout", "network", "busy", "http", "too_large"].includes(resolutionFailure.code) ? EXIT.online : code;
+    }
+    catch (e) {
+        if (!(e instanceof Stop))
+            throw e;
+        err(`${e.message}\n`);
+        return e.exit;
+    }
+}
+if (import.meta.main)
+    process.exitCode = await main(process.argv.slice(2));

package/dist/current-issuer-vc.d.ts

@@ -0,0 +1,20 @@
+import { type Credential } from "@zanii/credentials";
+import { type VerifiableCredential } from "@zanii/vc";
+import { type Signer } from "./signer.ts";
+import { type CertificateVcCheck } from "./vc.ts";
+export interface CurrentIssuerVcOptions {
+    created: string;
+    index: number;
+    revocationList: string;
+    suspensionList: string;
+    owner: string;
+    issuerDoc: unknown;
+}
+export interface CurrentIssuerVcTrust {
+    owner: string;
+    issuers: readonly string[];
+    domain: string;
+    at: string;
+}
+export declare function certificateToCurrentIssuerVc(cert: Credential, signer: Signer, opts: CurrentIssuerVcOptions): Promise<VerifiableCredential>;
+export declare function verifyCurrentIssuerCertificateVc(vc: unknown, opts: CurrentIssuerVcTrust): CertificateVcCheck;

package/dist/current-issuer-vc.js

@@ -0,0 +1,60 @@
+// A current-authority wrapper preserves the original signature; independent roots still establish trust.
+import { publicKeyFromDid } from "@zanii/core";
+import { credentialHash } from "@zanii/credentials";
+import { VC_CONTEXT, verifyVC } from "@zanii/vc";
+import { bitstringStatusEntry, isBitstringStatusEntry } from "./bitstring-status.js";
+import { claimReasons } from "./certificate.js";
+import { issuerArtifactAuthorization } from "./issuer-authorization.js";
+import { isIso, isObj, ms } from "./shared.js";
+import { signatureOk, signerDid } from "./signer.js";
+import { signVcWith } from "./vc.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const did = (v) => typeof v === "string" && v.length <= 69 && publicKeyFromDid(v) !== null;
+function authorization(cert, current, document, owner, domain, at) {
+    if (!withinVerificationBudget(document, { maxBytes: 1_048_576 }))
+        return ["issuer authorization exceeds its JSON budget"];
+    if (cert?.issuer_domain !== domain)
+        return ["current issuer wrapper requires independently pinned owner, domain and current key"];
+    if (!isObj(cert) || Object.keys(cert).length !== 10 || cert.v !== 1 || cert.type !== "credential" || !did(cert.issuer) || !did(cert.holder) || !isIso(cert.issued_at) || !isIso(cert.exp) || ms(cert.exp) <= ms(cert.issued_at)
+        || ms(cert.issued_at) > ms(at) || claimReasons(cert).length)
+        return ["invalid original certificate in current issuer wrapper"];
+    const { sig, ...unsigned } = cert;
+    if (typeof sig !== "string" || sig.length !== 136 || !signatureOk(unsigned, sig, cert.issuer))
+        return ["bad original certificate signature"];
+    return issuerArtifactAuthorization({ signer: cert.issuer, issued_at: cert.issued_at }, current, document, owner, domain, at).map((r) => r.replaceAll("artifact", "original certificate"));
+}
+export async function certificateToCurrentIssuerVc(cert, signer, opts) {
+    if (!withinVerificationBudget({ cert, opts }, { maxBytes: 4_194_304 }) || !isIso(opts.created) || opts.revocationList === opts.suspensionList)
+        throw new Error("invalid or oversized current issuer wrapper input");
+    const current = signerDid(signer), reasons = authorization(cert, current, opts.issuerDoc, opts.owner, cert?.issuer_domain, opts.created);
+    if (reasons.length)
+        throw new Error(reasons[0]);
+    return signVcWith({ "@context": [VC_CONTEXT], type: ["VerifiableCredential", "ZaniiCertifyCertificateV3"], issuer: current,
+        validFrom: cert.issued_at, validUntil: cert.exp, credentialSubject: { id: cert.holder, certificate: credentialHash(cert), credential: cert },
+        credentialStatus: [bitstringStatusEntry({ index: opts.index, list: opts.revocationList, purpose: "revocation" }), bitstringStatusEntry({ index: opts.index, list: opts.suspensionList, purpose: "suspension" })], issuerAuthorization: opts.issuerDoc }, signer, opts.created);
+}
+export function verifyCurrentIssuerCertificateVc(vc, opts) {
+    const denied = (reasons) => ({ ok: false, reasons, certificate: null });
+    if (!withinVerificationBudget({ vc, opts }, { maxBytes: 4_194_304 }) || !isObj(opts) || !did(opts.owner) || !Array.isArray(opts.issuers) || opts.issuers.length < 1 || opts.issuers.length > 64 || !Array.from(opts.issuers).every(did) || !isIso(opts.at))
+        return denied(["independent current issuer wrapper trust inputs are required"]);
+    if (!isObj(vc) || Object.keys(vc).length !== 9 || !Array.isArray(vc.type) || vc.type.length !== 2 || vc.type[0] !== "VerifiableCredential" || vc.type[1] !== "ZaniiCertifyCertificateV3" || !opts.issuers.includes(String(vc.issuer))
+        || !Array.isArray(vc["@context"]) || vc["@context"].length !== 1 || vc["@context"][0] !== VC_CONTEXT || !isObj(vc.proof) || Object.keys(vc.proof).length !== 6
+        || !isIso(vc.proof.created) || ms(vc.proof.created) > ms(opts.at) || typeof vc.proof.proofValue !== "string" || vc.proof.proofValue.length > 100)
+        return denied(["invalid current issuer wrapper v3 proof or pinned issuer"]);
+    if (!withinVerificationBudget(vc.issuerAuthorization, { maxBytes: 1_048_576 }))
+        return denied(["issuer authorization exceeds its JSON budget"]);
+    const checked = verifyVC(vc, { at: opts.at });
+    if (!checked.ok)
+        return denied(checked.reasons);
+    const subject = vc.credentialSubject;
+    if (!isObj(subject) || Object.keys(subject).length !== 3 || !isObj(subject.credential))
+        return denied(["current issuer wrapper does not carry the original certificate"]);
+    const cert = subject.credential, reasons = authorization(cert, String(vc.issuer), vc.issuerAuthorization, opts.owner, opts.domain, opts.at);
+    if (subject.id !== cert.holder || subject.certificate !== credentialHash(cert) || vc.validFrom !== cert.issued_at || vc.validUntil !== cert.exp)
+        reasons.push("current issuer wrapper changed the original certificate binding");
+    const entries = vc.credentialStatus;
+    if (!Array.isArray(entries) || entries.length !== 2 || !Array.from(entries).every(isBitstringStatusEntry) || entries[0].statusPurpose !== "revocation" || entries[1].statusPurpose !== "suspension"
+        || entries[0].statusListIndex !== entries[1].statusListIndex || entries[0].statusListCredential === entries[1].statusListCredential)
+        reasons.push("current issuer wrapper has invalid bitstring status bindings");
+    return { ok: reasons.length === 0, reasons, certificate: reasons.length ? null : cert };
+}

package/dist/evidence-share.d.ts

@@ -0,0 +1,89 @@
+import { type Identifier } from "@zanii/blackbox";
+import { type Disclosure, type RedactEnvelope } from "@zanii/redact";
+import type { EvidenceHead } from "./appliance.ts";
+import { type Signer } from "./signer.ts";
+/** Section 1: a Blackbox identifier, optionally redacting only its first capture group. */
+export type RedactionKind = Identifier & {
+    group?: 1;
+};
+/** Section 1: the GCC formats Blackbox's core identifiers do not cover. */
+export declare const GCC_IDENTIFIERS: readonly RedactionKind[];
+/** Section 1: every identifier kind `redactEvidence` knows, sorted. */
+export declare const REDACTION_KINDS: readonly string[];
+export interface RedactOptions {
+    /** The lab's redaction key (at least 16 bytes): the token and salt keys come from it. */
+    key: Uint8Array | string;
+    /** The identifier kinds to replace; default every kind in REDACTION_KINDS. */
+    kinds?: readonly string[];
+    /** Configured secret values (endpoint credentials, canary values), replaced as kind `secret`. */
+    secrets?: readonly string[];
+    /** Section 1: the run's 32 random bytes: tokens and salts are then keyed by HKDF of the key under it (version 2). */
+    saltSeed?: Uint8Array;
+    /** Section 1: RFC 6901 pointers of entry fields whose every leaf is replaced, as kind `withheld`. */
+    withhold?: readonly string[];
+}
+/**
+ * Section 1: the entries with every identifier of the chosen kinds and every configured secret
+ * replaced by a keyed token, in every string value (the top-level `seq`, `prev` and `hash` are
+ * kept), every withheld field replaced whole, and how many of each kind were replaced.
+ */
+export declare function redactEvidence(entries: readonly Record<string, unknown>[], opts: RedactOptions): {
+    entries: Record<string, unknown>[];
+    redactions: Record<string, number>;
+};
+export declare const AUDIENCES: readonly ["reviewer", "regulator", "applicant"];
+export type Audience = (typeof AUDIENCES)[number];
+export interface SharedEntry {
+    chain: string;
+    /** The redacted entry. */
+    entry: Record<string, unknown>;
+    /** @zanii/redact envelope over the original entry's fields (RFC 6901 pointers). */
+    envelope: RedactEnvelope;
+    /** One @zanii/redact disclosure per field the redaction left unchanged. */
+    disclosures: Disclosure[];
+}
+export interface EvidenceShare {
+    v: 1;
+    type: "certify.evidence-share";
+    audience: Audience;
+    heads: EvidenceHead[];
+    kinds: string[];
+    redactions: Record<string, number>;
+    items: SharedEntry[];
+    shared_at: string;
+    signer: string;
+    sig: string;
+}
+export interface EvidenceShareInput extends RedactOptions {
+    /** Whole evidence chains, entries from seq 0 (`{seq, prev, hash, ...}`, hash the jcsHash of the entry without it). */
+    chains: readonly {
+        chain: string;
+        entries: readonly Record<string, unknown>[];
+    }[];
+    audience: Audience;
+    sharedAt: string;
+}
+/**
+ * Section 4: the @zanii/redact disclosure of one field (`pointer`) of an original chain entry, as a
+ * share built with the same key and seed committed it: a field the share hid, opened for one
+ * receiver. Throws when the entry has no such field.
+ */
+export declare function discloseEvidenceField(entry: Record<string, unknown>, chain: string, pointer: string, opts: {
+    key: Uint8Array | string;
+    saltSeed?: Uint8Array;
+}): Disclosure;
+/** Section 2: redact whole evidence chains and sign them, with their heads and commitments, for one audience. */
+export declare function buildEvidenceShare(f: EvidenceShareInput, signer: Signer): Promise<EvidenceShare>;
+/** Internal detached-signing stage used by the server's bounded private broker worker. */
+export declare function buildEvidenceShareDraft(f: EvidenceShareInput): Omit<EvidenceShare, "signer" | "sig">;
+/**
+ * Section 3: `signers` are the lab DIDs this receiver trusts; `heads` the chain heads it holds from
+ * elsewhere (the result bundle's), each of which the share must carry unchanged.
+ */
+export declare function verifyEvidenceShare(doc: unknown, opts?: {
+    signers?: readonly string[];
+    heads?: readonly EvidenceHead[];
+}): {
+    ok: boolean;
+    reasons: string[];
+};