@zanii/certify 0.0.0-stage → 0.5.0

package/dist/certificate.js

@@ -0,0 +1,345 @@
+// spec/certificate.md: a Certify certificate is a @zanii/credentials Credential with a certify claim.
+import { credentialHash, verifyCredential, } from "@zanii/credentials";
+import { jcsHash } from "@zanii/core";
+import { bindingHash } from "@zanii/pq";
+import { verifyAuditAttestation } from "./audit.js";
+import { checkFingerprint } from "./fingerprint.js";
+import { licenceCoverage, licenceReasons, verifyLicence } from "./licence.js";
+import { checkPqBinding, pqCommitment, pqPolicyOf, verifyPqCosignature } from "./pq.js";
+import { registerTrust } from "./register.js";
+import { addDays, isDid, isIso, isObj, isSha, ms, SLUG, sortedUnique } from "./shared.js";
+import { signatureOk, signatureOver, signerDid } from "./signer.js";
+import { verifyStatus } from "./status.js";
+import { afterCompromise, compromisedKeyReasons, issuerLineage, succeeds } from "./succession.js";
+import { issuerPolicyCheck, releasePolicyReasons } from "./verification-policy.js";
+import { verifyAuditRenewal } from "./audit-renewal.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+import { signingIdentityReasons } from "./signing-identity.js";
+/** scheme.md section 8: every scheme version a certificate or bundle may name. */
+export const SCHEMES = ["zanii-certify/0.1", "zanii-certify/0.2", "zanii-certify/0.3"];
+/** The current scheme. */
+export const SCHEME = "zanii-certify/0.3";
+export const LEVELS = [1, 2, 3];
+/** scheme.md section 2: the levels each scheme version issues. */
+export const SCHEME_LEVELS = {
+    "zanii-certify/0.1": [1, 2],
+    "zanii-certify/0.2": [1, 2, 3],
+    "zanii-certify/0.3": [1, 2, 3],
+};
+/**
+ * scheme.md section 8: the scheme a certificate or bundle is issued under. Given, it must issue
+ * `level` (and allow 0.2 features when `needs02`, 0.3 features when `needs03`); absent, 0.3 with a
+ * 0.3 feature (a licence), else 0.1 for Levels 1 and 2 without 0.2 features, else 0.2.
+ */
+export function pickScheme(scheme, level, needs02 = false, needs03 = false) {
+    const s = scheme ?? (needs03 ? "zanii-certify/0.3" : level === 3 || needs02 ? "zanii-certify/0.2" : "zanii-certify/0.1");
+    if (!SCHEMES.includes(s))
+        throw new Error(`scheme must be one of ${SCHEMES.join(", ")}`);
+    if (!SCHEME_LEVELS[s].includes(level))
+        throw new Error(`level ${level} is not issued under ${s}`);
+    if (needs02 && s === "zanii-certify/0.1")
+        throw new Error("a post-quantum binding needs scheme zanii-certify/0.2");
+    if (needs03 && s !== "zanii-certify/0.3")
+        throw new Error("a licence needs scheme zanii-certify/0.3");
+    return s;
+}
+export const CONFLICTS = [
+    "blackbox_customer",
+    "ledger_customer",
+    "investor",
+    "staff_link",
+    "other",
+];
+/** scheme.md section 5: the default re-test interval per level. */
+export const SURVEILLANCE = { 1: "P30D", 2: "P90D", 3: "P90D" };
+/** scheme.md section 4: validity is 365 days from issue. */
+export const VALIDITY_DAYS = 365;
+export const DOMAIN = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+const COUNTRY = /^[A-Z]{2}$/;
+const DURATION = /^P[1-9][0-9]{0,3}D$/;
+/** `certify.<profile slug>.l<level>` */
+export const certificateScope = (slug, level) => `certify.${slug}.l${level}`;
+/** Issue a certificate, signed by `signer` (the lab issuer key, in a KMS or HSM). */
+export async function issueCertificate(input, signer) {
+    const { profile, level, fingerprint, applicant } = input;
+    const domain = String(input.issuerDomain ?? "").toLowerCase();
+    if (!DOMAIN.test(domain))
+        throw new Error("issuerDomain must be a DNS name");
+    if (!isDid(input.holder))
+        throw new Error("holder must be a did:key");
+    if (!SLUG.test(profile?.slug ?? "") || !Number.isInteger(profile.version) || profile.version < 1)
+        throw new Error("profile needs a slug and a version >= 1");
+    if (!LEVELS.includes(level))
+        throw new Error("level must be 1, 2 or 3");
+    const scheme = pickScheme(input.scheme, level, input.pqBinding !== undefined, input.licence !== undefined);
+    if (!checkFingerprint(fingerprint))
+        throw new Error("fingerprint is not a valid fingerprint");
+    if (!isSha(input.bundle))
+        throw new Error("bundle must be a result bundle hash");
+    if (!input.conflicts.every((c) => CONFLICTS.includes(c)))
+        throw new Error("unknown conflict");
+    const name = typeof applicant?.name === "string" ? applicant.name : "";
+    if (!name || name.length > 200 || !COUNTRY.test(applicant.country ?? ""))
+        throw new Error("applicant needs a name (1-200) and an ISO 3166-1 alpha-2 country");
+    if (!isIso(input.issuedAt))
+        throw new Error("issuedAt must be an ISO UTC timestamp");
+    const exp = input.exp ?? addDays(input.issuedAt, VALIDITY_DAYS);
+    if (!isIso(exp) || ms(exp) <= ms(input.issuedAt))
+        throw new Error("exp must be after issuedAt");
+    const surveillance = input.surveillance ?? SURVEILLANCE[level];
+    if (!DURATION.test(surveillance))
+        throw new Error("surveillance must be PnD");
+    const issuer = signerDid(signer);
+    if (input.pqBinding !== undefined)
+        checkPqBinding(input.pqBinding, issuer);
+    if ((level === 3) !== (input.audit !== undefined))
+        throw new Error("an audit attestation is required at Level 3 and only there");
+    if (input.audit) {
+        const a = input.audit;
+        // Whether the body is trusted is the issuer's decision before issuing; here: signature,
+        // fields, validity at issue, and that it is for this agent and applicant.
+        const check = verifyAuditAttestation(a, { trustedBodies: [a.body], now: input.issuedAt });
+        if (!check.ok)
+            throw new Error(check.reasons[0]);
+        if (a.holder !== input.holder || a.applicant.name !== name || a.applicant.country !== applicant.country)
+            throw new Error("audit attestation is for a different agent or applicant");
+        if (ms(a.audited_at) > ms(input.issuedAt))
+            throw new Error("audit is dated after issuedAt");
+    }
+    if (input.licence !== undefined) {
+        // Signature and fields (whether the owner is trusted is the verifier's), and that it covers this certificate.
+        const l = input.licence;
+        const check = verifyLicence(l, { owner: String(l?.signer) });
+        if (!check.ok)
+            throw new Error(check.reasons[0]);
+        const covered = licenceCoverage(l, {
+            issuer,
+            issued_at: input.issuedAt,
+            claim: { profile: `${profile.slug}/${profile.version}`, level, applicant: { name, country: applicant.country } },
+        }, input.lineage ?? []);
+        if (covered.length)
+            throw new Error(covered[0]);
+    }
+    const claim = {
+        scheme,
+        profile: `${profile.slug}/${profile.version}`,
+        level,
+        fingerprint: fingerprint.id,
+        configuration: fingerprint.configuration,
+        bundle: input.bundle,
+        surveillance,
+        conflicts: sortedUnique(input.conflicts),
+        applicant: { name, country: applicant.country },
+        ...(input.audit ? { audit: jcsHash(input.audit) } : {}),
+        ...(input.pqBinding ? { pq_binding: bindingHash(input.pqBinding) } : {}),
+        ...(input.licence ? { licence: jcsHash(input.licence) } : {}),
+    };
+    // The exact unsigned shape @zanii/credentials buildCredential signs.
+    const unsigned = {
+        v: 1,
+        type: "credential",
+        issuer,
+        issuer_domain: domain,
+        holder: input.holder,
+        scope: certificateScope(profile.slug, level),
+        claim: claim,
+        issued_at: input.issuedAt,
+        exp,
+    };
+    return { ...unsigned, sig: await signatureOver(unsigned, signer) };
+}
+/** A @zanii/credentials revocation list in shape: v 1, type revocation_list, revoked a list of strings. */
+const isRevocationList = (l) => isObj(l) && l.v === 1 && l.type === "revocation_list" && Array.isArray(l.revoked) && l.revoked.every((x) => typeof x === "string");
+/** The certify claim's own rules (certificate.md section 2); empty when the claim is well formed. */
+export function claimReasons(cert) {
+    const c = isObj(cert?.claim) ? cert.claim : {};
+    const out = [];
+    const scheme = SCHEMES.includes(c.scheme) ? c.scheme : null;
+    if (!scheme)
+        out.push(`claim scheme is not one of ${SCHEMES.join(", ")}`);
+    const [slug, version] = typeof c.profile === "string" ? c.profile.split("/") : [];
+    if (!slug || !SLUG.test(slug) || !/^[1-9][0-9]*$/.test(version ?? ""))
+        out.push("claim profile is not <slug>/<version>");
+    if (!LEVELS.includes(c.level) || (scheme && !SCHEME_LEVELS[scheme].includes(c.level)))
+        out.push("claim level is not a level of the claim scheme");
+    else if (slug && cert.scope !== certificateScope(slug, c.level))
+        out.push("scope does not match the claim profile and level");
+    if (!isSha(c.fingerprint) || !isSha(c.bundle))
+        out.push("claim fingerprint or bundle is not a hash");
+    if (c.level === 3 ? !isSha(c.audit) : "audit" in c)
+        out.push("claim audit is an audit attestation hash, required at level 3 and only there");
+    if ("pq_binding" in c && ((scheme !== "zanii-certify/0.2" && scheme !== "zanii-certify/0.3") || !isSha(c.pq_binding)))
+        out.push("claim pq_binding needs scheme zanii-certify/0.2 and a binding hash");
+    if ("licence" in c && (scheme !== "zanii-certify/0.3" || !isSha(c.licence)))
+        out.push("claim licence needs scheme zanii-certify/0.3 and a licence hash");
+    return out;
+}
+/** `verifyCredential`'s revocation check, for a list signed by another DID of the issuer document. */
+function rotatedListCheck(credential, cert, list, now) {
+    const reasons = credential.reasons.filter((r) => !r.startsWith("no revocation list supplied"));
+    const { sig, ...unsigned } = list;
+    let revocationFreshness = null;
+    if (!signatureOk(unsigned, sig, list.issuer))
+        reasons.push("revocation list signature is invalid");
+    else {
+        revocationFreshness = Date.parse(list.valid_until) >= (now ? Date.parse(now) : Date.now()) ? "fresh" : "stale";
+        if (list.revoked.includes(credentialHash(cert)))
+            reasons.push("credential has been REVOKED by its issuer");
+        // the @zanii/credentials wording, its dash written as an escape
+        if (revocationFreshness === "stale")
+            reasons.push(`revocation list expired on ${list.valid_until} \u2014 revocation status is a stale snapshot`);
+    }
+    return { ...credential, ok: reasons.length === 0, reasons, revocationFreshness };
+}
+/**
+ * Verify a certificate: the four @zanii/credentials checks, the certify claim, its live status in
+ * the signed status document, and (when supplied) that the agent's current fingerprint matches.
+ * Anything not checked is reported, never assumed.
+ */
+export async function verifyCertificate(cert, opts = {}) {
+    if (opts.auditRenewal !== undefined) {
+        const { resolver: _, ...bounded } = opts;
+        if (!isObj(opts.auditRenewal) || !withinVerificationBudget({ cert, opts: bounded }, { maxBytes: 4_194_304 })) {
+            const reasons = ["audit renewal verification exceeds its JSON budget or has an invalid renewal policy"];
+            return { ok: false, reasons, status: null, fingerprint: null, credential: { ok: false, reasons, revocationFreshness: null }, pq: null, witnesses: null };
+        }
+    }
+    // Section 5: after a key rotation the status document and revocation list are signed by the
+    // issuer's current DID, which the issuer document lists beside the certificate's (resolver).
+    // A retired key stays in `dids` (its certificates still verify) but signs no status: with
+    // statusDids, only a current status signer is accepted.
+    // Section 5a: with an issuer document that lists successions, a key the certificate's issuer
+    // key was succeeded by signs status without the resolver.
+    const lineage = opts.issuerDoc === undefined ? null : issuerLineage(opts.issuerDoc);
+    const issuerStatusDids = isObj(opts.issuerDoc) && "status_dids" in opts.issuerDoc
+        ? Array.isArray(opts.issuerDoc.status_dids) ? opts.issuerDoc.status_dids.filter((x) => typeof x === "string") : []
+        : undefined;
+    const statusDids = opts.statusDids ?? issuerStatusDids;
+    const current = (did) => !statusDids || statusDids.includes(did);
+    const rotated = async (did) => (succeeds(lineage, cert?.issuer, did) && current(did)) ||
+        (typeof did === "string" && did !== cert?.issuer && !!statusDids?.includes(did) && !!opts.resolver &&
+            !!(await opts.resolver(did, String(cert?.issuer_domain ?? ""))));
+    const given = opts.revocationList;
+    const list = isRevocationList(given) ? given : undefined;
+    const otherList = list !== undefined && (await rotated(list.issuer));
+    let credential = await verifyCredential(cert, {
+        ...(opts.resolver ? { resolver: opts.resolver } : {}),
+        ...(list && !otherList ? { revocationList: list } : {}),
+        ...(opts.now ? { now: opts.now } : {}),
+    });
+    if (list && otherList)
+        credential = rotatedListCheck(credential, cert, list, opts.now);
+    const listReasons = given === undefined ? [] : !list ? ["revocation list is not a revocation list (v1)"] : current(list.issuer) ? [] : ["revocation list is not signed by a current status key of the issuer"];
+    if (list)
+        listReasons.push(...compromisedKeyReasons(lineage, list.issuer, "revocation list"));
+    if (listReasons.length) {
+        const kept = credential.reasons.filter((r) => !r.startsWith("no revocation list supplied"));
+        credential = { ...credential, ok: false, reasons: [...kept, ...listReasons], ...(list ? {} : { revocationFreshness: null }) };
+    }
+    const reasons = [...credential.reasons];
+    const schemeOwner = opts.schemeOwner ?? opts.bodyRegister?.owner ?? opts.releases?.owner;
+    if (schemeOwner !== undefined)
+        reasons.push(...signingIdentityReasons(schemeOwner, [cert?.issuer], statusDids ?? []));
+    if (schemeOwner !== undefined && list)
+        reasons.push(...signingIdentityReasons(schemeOwner, [], [list.issuer]));
+    if (cert?.type === "credential")
+        reasons.push(...claimReasons(cert));
+    if (lineage)
+        reasons.push(...lineage.reasons, ...afterCompromise(lineage, cert?.issuer, cert?.issued_at, "certificate"));
+    const pqPolicy = opts.issuerDoc === undefined ? undefined : pqPolicyOf(opts.issuerDoc, opts.allowNoPq, String(cert?.issued_at));
+    const strict = opts.issuerPolicy === undefined ? null : issuerPolicyCheck(cert, opts.issuerDoc, opts.issuerPolicy, { allowNoPq: opts.allowNoPq, status: opts.status, revocationList: opts.revocationList });
+    if (strict)
+        reasons.push(...strict.reasons);
+    const requirePq = opts.requirePq === true || pqPolicy === "required" || strict?.requirePq === true;
+    let pq = null;
+    if (opts.pq) {
+        const r = verifyPqCosignature(cert, opts.pq);
+        pq = r.ok;
+        reasons.push(...r.reasons);
+    }
+    else if (requirePq) {
+        pq = false;
+        reasons.push(pqCommitment(cert)
+            ? "no post-quantum co-signature supplied: a post-quantum signature is required"
+            : "certificate has no post-quantum co-signature: a post-quantum signature is required");
+    }
+    const claim = isObj(cert?.claim) ? cert.claim : {};
+    const bodies = claim.level !== 3 ? undefined : opts.bodyRegister ? "register" : opts.trustedBodies ? "local" : undefined;
+    if (claim.level === 3) {
+        if (!opts.audit)
+            reasons.push("level 3: no audit attestation supplied, the control audit was NOT checked");
+        else {
+            const renewal = opts.auditRenewal;
+            const renewalAt = isObj(renewal?.document) && isIso(renewal.document.issued_at) ? renewal.document.issued_at : "";
+            const reg = opts.bodyRegister ? registerTrust(renewal ? { ...cert, issued_at: renewalAt } : cert, opts.audit.body, opts.bodyRegister) : null;
+            if (reg)
+                reasons.push(...reg.reasons);
+            const trustedBodies = reg ? reg.trusted : opts.trustedBodies;
+            if (renewal) {
+                const originalReg = opts.bodyRegister ? registerTrust(cert, isObj(renewal.originalAudit) ? renewal.originalAudit.body : null, opts.bodyRegister) : null;
+                if (originalReg)
+                    reasons.push(...originalReg.reasons);
+                reasons.push(...verifyAuditRenewal(renewal.document, {
+                    ...renewal, certificate: cert, audit: opts.audit, trustedBodies: trustedBodies ?? [],
+                    originalTrustedBodies: originalReg ? originalReg.trusted : renewal.originalTrustedBodies ?? opts.trustedBodies ?? [], now: opts.now ?? new Date().toISOString(),
+                }).reasons);
+            }
+            else
+                reasons.push(...verifyAuditAttestation(opts.audit, {
+                    ...(trustedBodies ? { trustedBodies } : {}),
+                    ...(opts.now ? { now: opts.now } : {}),
+                    certificate: cert,
+                }).reasons);
+        }
+    }
+    if (opts.auditRenewal !== undefined && !(isObj(cert?.claim) && cert.claim.level === 3))
+        reasons.push("audit renewal is only valid for a Level 3 certificate");
+    // section 5a: a licence naming an earlier key of the issuer's verified lineage covers a later one
+    if (opts.licences)
+        reasons.push(...licenceReasons(cert, opts.licences.lineage === undefined && lineage?.ok ? { ...opts.licences, lineage: lineage.lineage } : opts.licences));
+    if (opts.releases !== undefined)
+        reasons.push(...releasePolicyReasons(cert, opts.releases));
+    let status = null;
+    let witnesses = null;
+    if (opts.status) {
+        const s = verifyStatus(opts.status, {
+            ...(schemeOwner !== undefined ? { schemeOwner } : {}),
+            issuer: (await rotated(opts.status.issuer)) ? opts.status.issuer : cert?.issuer,
+            ...(opts.now ? { now: opts.now } : {}),
+            ...(opts.statusPq ? { pq: opts.statusPq } : {}),
+            ...(requirePq ? { requirePq: true } : {}),
+            ...(opts.statusWitness ? { witness: opts.statusWitness } : {}),
+        });
+        reasons.push(...s.reasons, ...compromisedKeyReasons(lineage, opts.status.issuer, "status document"));
+        if (!current(opts.status.issuer))
+            reasons.push("status document is not signed by a current status key of the issuer");
+        witnesses = s.witnesses ?? null;
+        status = (isObj(opts.status.entries) && opts.status.entries[credentialHash(cert)]) || null;
+        if (!status)
+            reasons.push("certificate is not listed in the status document");
+        else if (status.status !== "valid")
+            reasons.push(`certificate is ${status.status} (${status.reason}) since ${status.since}`);
+    }
+    else {
+        reasons.push("no status document supplied: status was NOT checked");
+    }
+    let fingerprint = null;
+    if (opts.fingerprint) {
+        const claimed = isObj(cert?.claim) ? cert.claim.fingerprint : undefined;
+        fingerprint =
+            checkFingerprint(opts.fingerprint) && opts.fingerprint.id === claimed ? "match" : "mismatch";
+        if (fingerprint === "mismatch")
+            reasons.push("agent fingerprint does not match the certificate");
+    }
+    return {
+        ok: reasons.length === 0,
+        reasons,
+        status,
+        fingerprint,
+        credential,
+        pq,
+        witnesses,
+        ...(pqPolicy ? { pqPolicy } : {}),
+        ...(bodies ? { bodies: bodies } : {}),
+    };
+}

package/dist/cli-messages.json

@@ -0,0 +1,148 @@
+{
+    "en": {
+        "usage_v2": "certify CLI help v2\nusage: certify verify <cert.json> [--status <file>] [--issuer-doc <file>] [--fingerprint <file>] [--online <base url>] [--now <time>] [--lang en|ar] [--pq <file>|off]\n       [--audit <file>] [--trusted-bodies <file>] [--body-register <file>] [--status-witness <file>] [--release-policy <file>] [--strict-policy <file>]\n       certify fingerprint --model <model> [--prompt-file <file>] [--tools-file <file>] [--policy-file <file>] [--knowledge-file <file>]\n--strict-policy pins issuer keys and PQ requirements independently. --pq off is incompatible with it. See spec/cli.md for policy file schemas. Legacy help: --help; current help: --help-v2.",
+        "bad_policy": "invalid verification input for {0}; see certify --help-v2",
+        "issuer_resolution": "issuer resolution failed ({0}); this is not proof that the key is unpublished",
+        "audit_ok": "attestation and trusted body verified",
+        "audit_bad": "attestation or trusted body invalid",
+        "witness": "Status witnesses",
+        "issuer_policy": "Pinned issuer policy",
+        "release_policy": "Release policy",
+        "policy_ok": "verified",
+        "policy_bad": "missing or invalid evidence",
+        "usage": "usage: certify verify <cert.json> [--status <status.json>] [--issuer-doc <file>] [--fingerprint <fp.json>] [--online <base url>] [--now <time>] [--lang en|ar]\n       certify fingerprint --model <model> [--prompt-file <file>] [--tools-file <file>] [--policy-file <file>] [--knowledge-file <file>]",
+        "error": "error: {0}",
+        "unknown_option": "unknown option {0}",
+        "missing_value": "{0} needs a value",
+        "bad_lang": "--lang must be en or ar",
+        "bad_now": "--now must be an ISO UTC timestamp",
+        "cannot_read": "cannot read {0}",
+        "not_json": "{0} is not JSON",
+        "not_status": "{0} holds neither a status document nor a {status, revocation_list} pair",
+        "not_tools": "{0} holds no list of tool definitions",
+        "not_text": "{0} is not UTF-8 text",
+        "online_failed": "could not fetch {0}",
+        "not_certificate": "Not a Zanii Certify certificate",
+        "certificate": "Certificate: {0}",
+        "holder": "Holder: {0}",
+        "profile": "Profile: {0}, level {1}",
+        "issuer": "Issuer: {0} ({1})",
+        "expires": "Expires: {0}",
+        "signature": "Signature",
+        "expiry": "Expiry",
+        "claim": "Certify claim",
+        "status": "Status",
+        "revocation": "Revocation list",
+        "issuer_domain": "Issuer domain",
+        "fingerprint": "Fingerprint",
+        "audit": "Control audit (level 3)",
+        "sig_ok": "valid",
+        "sig_bad": "invalid",
+        "exp_ok": "valid until {0}",
+        "exp_bad": "expired on {0}",
+        "claim_ok": "well formed",
+        "claim_bad": "malformed",
+        "status_valid": "valid since {0}",
+        "status_suspended": "suspended ({0}) since {1}",
+        "status_revoked": "revoked ({0}) since {1}",
+        "status_unlisted": "the certificate is not listed",
+        "status_stale": "the status document expired on {0}",
+        "status_invalid": "the status document is not a valid document of this issuer",
+        "rev_ok": "not revoked",
+        "rev_revoked": "revoked",
+        "rev_stale": "the list expired on {0}",
+        "rev_invalid": "the list is not a valid list of this issuer",
+        "issuer_ok": "{0} publishes the issuer key",
+        "issuer_bad": "{0} does not publish the issuer key",
+        "issuer_skip": "not checked (use --issuer-doc or --online)",
+        "fp_ok": "matches the certificate",
+        "fp_bad": "does not match the certificate",
+        "not_supplied": "not supplied",
+        "audit_skip": "not checked by this command (verifyCertificate with the audit attestation and trusted bodies)",
+        "vc": "VC proof",
+        "vc_ok": "valid (eddsa-jcs-2022), carries the certificate",
+        "vc_bad": "Not a valid Zanii Certify verifiable credential",
+        "not_pq": "{0} holds no post-quantum co-signature",
+        "pq": "Post-quantum signature",
+        "pq_ok": "valid (ML-DSA-65)",
+        "pq_bad": "invalid",
+        "pq_missing": "required by the issuer document, not supplied (use --pq)",
+        "pq_optout": "not checked: the issuer document requires it, opted out with --pq off",
+        "result_valid": "Result: VALID",
+        "result_invalid": "Result: INVALID",
+        "result_partial": "Result: NOT FULLY CHECKED"
+    },
+    "ar": {
+        "usage_v2": "مساعدة certify، الإصدار 2\nusage: certify verify <cert.json> [--status <file>] [--issuer-doc <file>] [--fingerprint <file>] [--online <base url>] [--now <time>] [--lang en|ar] [--pq <file>|off]\n       [--audit <file>] [--trusted-bodies <file>] [--body-register <file>] [--status-witness <file>] [--release-policy <file>] [--strict-policy <file>]\n       certify fingerprint --model <model> [--prompt-file <file>] [--tools-file <file>] [--policy-file <file>] [--knowledge-file <file>]\nيثبت --strict-policy مفاتيح الجهة المصدرة ومتطلبات التوقيع المقاوم للحوسبة الكمية بصورة مستقلة، ولا يقبل --pq off. صيغ الملفات في spec/cli.md. المساعدة السابقة: --help؛ المساعدة الحالية: --help-v2.",
+        "bad_policy": "مدخل تحقق غير صالح للخيار {0}؛ راجع certify --help-v2",
+        "issuer_resolution": "تعذر التحقق من نطاق الجهة المصدرة ({0})؛ لا يثبت ذلك أن المفتاح غير منشور",
+        "audit_ok": "تم التحقق من شهادة التدقيق والجهة الموثوقة",
+        "audit_bad": "شهادة التدقيق أو الجهة الموثوقة غير صالحة",
+        "witness": "شهود الحالة",
+        "issuer_policy": "سياسة الجهة المصدرة المثبتة",
+        "release_policy": "سياسة الإصدار",
+        "policy_ok": "تم التحقق",
+        "policy_bad": "الأدلة غير متاحة أو غير صالحة",
+        "usage": "الاستخدام: certify verify <cert.json> [--status <status.json>] [--issuer-doc <file>] [--fingerprint <fp.json>] [--online <base url>] [--now <time>] [--lang en|ar]\n           certify fingerprint --model <model> [--prompt-file <file>] [--tools-file <file>] [--policy-file <file>] [--knowledge-file <file>]",
+        "error": "خطأ: {0}",
+        "unknown_option": "خيار غير معروف {0}",
+        "missing_value": "الخيار {0} يحتاج إلى قيمة",
+        "bad_lang": "قيمة --lang يجب أن تكون en أو ar",
+        "bad_now": "قيمة --now يجب أن تكون طابعا زمنيا ISO بتوقيت UTC",
+        "cannot_read": "تعذرت قراءة {0}",
+        "not_json": "الملف {0} ليس JSON",
+        "not_status": "الملف {0} لا يحتوي وثيقة حالة ولا زوج {status, revocation_list}",
+        "not_tools": "الملف {0} لا يحتوي قائمة تعريفات أدوات",
+        "not_text": "الملف {0} ليس نصا بترميز UTF-8",
+        "online_failed": "تعذر جلب {0}",
+        "not_certificate": "ليست شهادة من Zanii Certify",
+        "certificate": "الشهادة: {0}",
+        "holder": "الحامل: {0}",
+        "profile": "الملف القطاعي: {0}، المستوى {1}",
+        "issuer": "الجهة المصدرة: {0} ({1})",
+        "expires": "تنتهي في: {0}",
+        "signature": "التوقيع",
+        "expiry": "الصلاحية",
+        "claim": "بيانات الاعتماد",
+        "status": "الحالة",
+        "revocation": "قائمة الإلغاء",
+        "issuer_domain": "نطاق الجهة المصدرة",
+        "fingerprint": "البصمة",
+        "audit": "تدقيق الضوابط (المستوى 3)",
+        "sig_ok": "صالح",
+        "sig_bad": "غير صالح",
+        "exp_ok": "صالحة حتى {0}",
+        "exp_bad": "انتهت في {0}",
+        "claim_ok": "سليمة",
+        "claim_bad": "غير سليمة",
+        "status_valid": "سارية منذ {0}",
+        "status_suspended": "معلقة ({0}) منذ {1}",
+        "status_revoked": "ملغاة ({0}) منذ {1}",
+        "status_unlisted": "الشهادة غير مدرجة",
+        "status_stale": "انتهت وثيقة الحالة في {0}",
+        "status_invalid": "وثيقة الحالة ليست وثيقة صالحة لهذه الجهة المصدرة",
+        "rev_ok": "غير ملغاة",
+        "rev_revoked": "ملغاة",
+        "rev_stale": "انتهت القائمة في {0}",
+        "rev_invalid": "القائمة ليست قائمة صالحة لهذه الجهة المصدرة",
+        "issuer_ok": "النطاق {0} ينشر مفتاح الجهة المصدرة",
+        "issuer_bad": "النطاق {0} لا ينشر مفتاح الجهة المصدرة",
+        "issuer_skip": "لم يفحص (استخدم --issuer-doc أو --online)",
+        "fp_ok": "تطابق الشهادة",
+        "fp_bad": "لا تطابق الشهادة",
+        "not_supplied": "لم تقدم",
+        "audit_skip": "لا يتحقق منه هذا الأمر (verifyCertificate مع شهادة التدقيق والجهات الموثوقة)",
+        "vc": "إثبات الشهادة القابلة للتحقق",
+        "vc_ok": "صالح (eddsa-jcs-2022)، ويحمل الشهادة",
+        "vc_bad": "ليست شهادة Zanii Certify قابلة للتحقق صالحة",
+        "not_pq": "الملف {0} لا يحتوي توقيعا مشتركا مقاوما للحوسبة الكمية",
+        "pq": "التوقيع المقاوم للحوسبة الكمية",
+        "pq_ok": "صالح (ML-DSA-65)",
+        "pq_bad": "غير صالح",
+        "pq_missing": "تشترطه وثيقة الجهة المصدرة ولم يقدم (استخدم --pq)",
+        "pq_optout": "لم يتحقق منه: تشترطه وثيقة الجهة المصدرة، وتم التنازل عنه بالخيار --pq off",
+        "result_valid": "النتيجة: صالحة",
+        "result_invalid": "النتيجة: غير صالحة",
+        "result_partial": "النتيجة: لم يكتمل الفحص"
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/** spec/cli.md section 4. */
+export declare const EXIT: {
+    readonly valid: 0;
+    readonly invalid: 1;
+    readonly partial: 2;
+    readonly usage: 3;
+    readonly online: 4;
+};
+export interface CliIo {
+    fetch?: typeof fetch;
+    out?: (text: string) => void;
+    err?: (text: string) => void;
+}
+/** Run `certify` with `argv` (without the program name); returns the exit code. */
+export declare function main(argv: readonly string[], io?: CliIo): Promise<number>;