@zanii/certify 0.5.0 → 0.6.0

package/src/cli.ts

@@ -0,0 +1,331 @@
+#!/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 {
+  type Credential,
+  credentialHash,
+  type IssuerResolver,
+  type RevocationList,
+  resolveIssuer,
+} from "@zanii/credentials";
+import { claimReasons, verifyCertificate } from "./certificate.ts";
+import { type AuditAttestation, verifyAuditAttestation } from "./audit.ts";
+import messages from "./cli-messages.json" with { type: "json" };
+import { buildFingerprint, type Fingerprint, promptSha256, sha256Bytes, toolsSha256 } from "./fingerprint.ts";
+import { type PqCosignature, pqPolicyOf } from "./pq.ts";
+import { fetchJsonBounded, type ResolutionFailure, resolveIssuerDetailed } from "./issuer-resolution.ts";
+import { type BodyRegisterOptions, registerTrust } from "./register.ts";
+import { isDid, isInt, isIso, isObj } from "./shared.ts";
+import { type StatusDocument, type StatusWitness, verifyStatus } from "./status.ts";
+import { isIssuerPolicy, type ReleaseVerificationPolicy } from "./verification-policy.ts";
+import { witnessReasons } from "./witness.ts";
+import { verifyCertificateVc } from "./vc.ts";
+
+/** spec/cli.md section 4. */
+export const EXIT = { valid: 0, invalid: 1, partial: 2, usage: 3, online: 4 } as const;
+
+type Lang = keyof typeof messages;
+type Key = keyof (typeof messages)["en"];
+export interface CliIo {
+  fetch?: typeof fetch;
+  out?: (text: string) => void;
+  err?: (text: string) => void;
+}
+
+const OPTIONS: Record<string, string[]> = {
+  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: unknown): string =>
+  typeof v === "string" ? v.replace(UNSAFE, "?") : Number.isInteger(v) ? String(v) : v == null ? "" : "?";
+
+class Stop extends Error {
+  exit: number;
+  constructor(text: string, exit: number) {
+    super(text);
+    this.exit = exit;
+  }
+}
+
+/** Run `certify` with `argv` (without the program name); returns the exit code. */
+export async function main(argv: readonly string[], io: CliIo = {}): Promise<number> {
+  const out = io.out ?? ((s: string) => process.stdout.write(s));
+  const err = io.err ?? ((s: string) => process.stderr.write(s));
+  const li = argv.indexOf("--lang");
+  const lang: Lang = argv[li + 1] === "ar" && li >= 0 ? "ar" : "en";
+  const t = (key: Key, ...args: unknown[]) =>
+    messages[lang][key].replace(/\{(\d)\}/g, (_, i) => show(args[Number(i)]));
+  const fail = (key: Key, ...args: unknown[]) => 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: string[] = [];
+    const opts: Record<string, string> = {};
+    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: string): Uint8Array => {
+      try {
+        return readFileSync(path);
+      } catch {
+        throw fail("cannot_read", path);
+      }
+    };
+    const text = (path: string): string => {
+      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: string): unknown => {
+      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: unknown = 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: string) => (opts[k] === undefined ? null : sha256Bytes(read(opts[k]!)));
+      let fp: Fingerprint;
+      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 as Error).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) as Credential;
+    let status: StatusDocument | undefined;
+    let list: RevocationList | undefined;
+    let onlineStatusPq: PqCosignature | undefined;
+    const takeStatus = (v: unknown, where: string) => {
+      if (isObj(v) && v.type === "certify.status") status = v as unknown as StatusDocument;
+      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 as unknown as StatusDocument;
+        list = v.revocation_list as unknown as RevocationList;
+        if (isObj(v.pq)) onlineStatusPq = v.pq as unknown as PqCosignature;
+      } 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: IssuerResolver | undefined;
+    // certificate.md section 5: the issuer document's status_dids, when it lists them
+    let issuerDoc: unknown;
+    let resolutionFailure: ResolutionFailure | undefined;
+    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): x is string => typeof x === "string") : undefined;
+    const fingerprint = opts["--fingerprint"] === undefined ? undefined : (json(opts["--fingerprint"]) as 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"]) as AuditAttestation;
+    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"]) as string[];
+    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"]) as BodyRegisterOptions;
+    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"]) as StatusWitness;
+    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"]) as ReleaseVerificationPolicy;
+    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 as unknown as PqCosignature) : undefined;
+    let statusPq = isObj(pqPair.status) ? (pqPair.status as unknown as PqCosignature) : undefined;
+    if (pqFile !== undefined && !certPq && !statusPq) throw fail("not_pq", pqArg);
+
+    const c = (isObj(cert) ? cert : {}) as Record<string, unknown>;
+    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 as unknown as PqCosignature;
+      }
+      if (!certPq) {
+        let url: string;
+        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 as unknown as PqCosignature;
+      }
+    }
+    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: string[] = [];
+    const check = (name: Key, mark: "ok" | "fail" | "skip", detail: string) => {
+      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 as unknown as Record<string, unknown>, 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:"]] as const) 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));