verifyhash 0.1.0

package/cli/identity.js

@@ -0,0 +1,1072 @@
+"use strict";
+
+// cli/identity.js — the PURE producer-IDENTITY core for verifyhash (EPIC-49 / T-49.1).
+//
+// WHY THIS EXISTS
+//   Every sealed/signed artifact this family mints (an evidence seal, a signed license, a dataset
+//   attestation) pins its producer by a vendor ADDRESS the recipient must learn OUT OF BAND — an email,
+//   a slide, a README line. A cold prospect therefore has NO first-class, OFFLINE-verifiable way to
+//   answer "does this 0x-address really belong to THIS vendor, and what exactly do they attest — and,
+//   just as load-bearing, what do they explicitly NOT attest?". The producer IDENTITY CARD closes that
+//   gap: a vendor SIGNS, with the SAME key that signs their evidence/licenses, a small self-describing
+//   container that binds their `vendorAddress` to a bounded `claims[]` set and an honest `nonClaims[]`
+//   set. A recipient who holds the card can recover the signer, confirm it equals the card's OWN
+//   `vendorAddress` (the key controls the address it claims), and OPTIONALLY pin it to an address they
+//   learned out of band — all OFFLINE, no network, no key, no I/O.
+//
+// IT IS JUST ONE MORE PRODUCT ON THE SHARED SIGNED-ATTESTATION ENVELOPE.
+//   Exactly like the seal/license/dataset, the identity card defines an UNSIGNED PAYLOAD (a versioned
+//   object: vendorAddress + a CLOSED productLine + the bounded claims[]/nonClaims[] + publishedAt), a
+//   canonical serializer, and a strict validator, then hands those to `cli/core/attestation.js` as the
+//   product framing. The attestation core does ALL the crypto: it embeds the EXACT canonical payload
+//   bytes as the `attestation`, attaches the detached EIP-191 signature, and later RE-DERIVES the signer
+//   from those bytes. There is NO new crypto here, NO new dependency, NO new scheme — `buildIdentityCard`
+//   wraps via `signAttestation`, `verifyIdentityCard` recovers via `verifySignedAttestation`, byte-for-byte
+//   the SAME shared paths the seal uses.
+//
+// THE LOAD-BEARING EXTRA CHECK — the key controls the address it claims.
+//   A license pins the signer to a caller-supplied `vendorAddress`. An identity card carries its OWN
+//   `vendorAddress` INSIDE the signed payload, so the card asserts "the holder of this key IS this
+//   address". `verifyIdentityCard` therefore REQUIRES recovered === the embedded `vendorAddress`: a card
+//   whose signature recovers to any OTHER key is REJECTED (`vendorAddressMatchesSigner` fails), never a
+//   silent accept. `buildIdentityCard` enforces the SAME invariant at mint time — it refuses to produce a
+//   card for an address the provisioned signer does not control — so a card can never round-trip into a
+//   false ACCEPT.
+//
+// PURE + I/O-FREE + KEY-AGNOSTIC.
+//   Every function here is pure: no filesystem, no clock, no network. The only key handling is a passed-in
+//   ethers signer-like object (an ephemeral `Wallet.createRandom()` in tests; the loop NEVER holds a real
+//   key) whose private key lives ONLY inside that object — never read, persisted, or logged here. The
+//   `publishedAt` instant is a CALLER-supplied argument; this core never reads the system clock, so the
+//   same inputs always yield byte-identical bytes + verdict. PRODUCT-AGNOSTIC: this module requires the
+//   GENERIC attestation core, never the reverse — no back-edge.
+
+const fs = require("fs");
+const path = require("path");
+const coreAttestation = require("./core/attestation");
+const coreTrustAsOf = require("./core/trust-asof");
+const { getAddress, isAddress } = require("ethers");
+
+// On-disk schema discriminators. The identity card carries its OWN kind + version (distinct from every
+// seal/license/manifest kind) so a random JSON file, a license, or a seal is never misread as a card.
+const IDENTITY_CARD_KIND = "vh-identity-card";
+const IDENTITY_CARD_SCHEMA_VERSION = 1;
+const SUPPORTED_IDENTITY_CARD_SCHEMA_VERSIONS = Object.freeze([1]);
+
+// The SIGNED-container framing (the detached-signature envelope kind) — its OWN discriminator.
+const SIGNED_IDENTITY_CARD_KIND = "vh-identity-card-signed";
+const SIGNED_IDENTITY_CARD_SCHEMA_VERSION = 1;
+const SUPPORTED_SIGNED_IDENTITY_CARD_SCHEMA_VERSIONS = Object.freeze([1]);
+
+// The CLOSED productLine set. A card declares WHICH product family the vendor publishes under; an
+// out-of-set value is a HARD build/validate error (never silently honored), exactly like the license
+// core's closed entitlement table. Frozen + a derived sorted list so error messages are deterministic.
+const PRODUCT_LINES = Object.freeze(["evidence", "dataledger", "trustledger"]);
+const PRODUCT_LINE_SET = Object.freeze(PRODUCT_LINES.slice().sort());
+
+// A claimed 0x-address INSIDE the payload: 0x + 40 LOWERCASE hex chars. Lowercase-only for the SAME
+// byte-determinism reason the attestation core lowercases the signer — an EIP-55-checksummed address is
+// the canonical address in a DIFFERENT encoding, so accepting it verbatim would let one vendor serialize
+// two ways. A caller holding a checksummed address lowercases it before building the card (buildIdentityCard
+// normalizes for them via getAddress, so a checksummed input is accepted and canonicalized).
+const ADDRESS_RE = /^0x[0-9a-f]{40}$/;
+
+// A strict ISO-8601 UTC instant ("YYYY-MM-DDTHH:MM:SS(.mmm)Z"). Same canonical instant grammar the license
+// core pins issuedAt/expiresAt to, so two logically-identical cards serialize to identical bytes. We pin
+// the SHAPE here and require the canonical millis round-trip below.
+const ISO_INSTANT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
+
+// The in-band trust caveat — stated ONCE so the human + JSON paths agree and the boundary can never drift.
+// It is the load-bearing honesty of the artifact: a card proves IDENTITY + a bounded claim SET; it is NOT
+// a per-packet truth claim, NOT a trusted timestamp, NOT a legal opinion.
+const IDENTITY_CARD_TRUST_NOTE =
+  "This is a verifyhash producer IDENTITY CARD: the holder of `vendorAddress`'s key SIGNED it, binding " +
+  "that address to the `claims` it attests and the `nonClaims` it explicitly does NOT. verify RE-DERIVES " +
+  "the signer from these exact bytes and REQUIRES it to equal `vendorAddress` — it never trusts the file's " +
+  "own claims. It proves IDENTITY + the claim SET ONLY: it does NOT prove any specific sealed/signed packet " +
+  'is true (each packet carries its own proof), it is NOT a trusted TIMESTAMP ("published since T" rides ' +
+  "the human-owned signing/timestamp trust-root, STRATEGY.md P-3), and it is NOT a legal opinion.";
+
+const SIGNED_IDENTITY_CARD_TRUST_NOTE =
+  "This is a SIGNED verifyhash identity-card container: it WRAPS (never edits) the EXACT canonical " +
+  "identity-card bytes in `attestation` and attaches a detached EIP-191 signature. verifyIdentityCard " +
+  "RE-DERIVES the signer from those bytes and pins it to the embedded `vendorAddress` — it never trusts " +
+  "the file's own claims. Every caveat of the embedded card applies. " +
+  IDENTITY_CARD_TRUST_NOTE;
+
+// A dedicated error type so callers/tests catch ONE identity error for the HARD validation failures
+// (a closed-field/closed-productLine/empty-claims violation, an out-of-control mint). An ordinary verify
+// REJECT is NOT thrown — it is a clean verdict (verdict: "REJECTED"), exactly like the rest of the family.
+class IdentityCardError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "IdentityCardError";
+  }
+}
+
+function isPlainObject(v) {
+  return v != null && typeof v === "object" && !Array.isArray(v);
+}
+
+// The CLOSED field set of an UNSIGNED identity-card payload. An UNKNOWN/extraneous key is a HARD error
+// (never silently dropped) so the card's shape ossifies with exactly these fields. `kind`/`schemaVersion`/
+// `note` are the framing the core fixes; the rest is the producer-supplied identity.
+const IDENTITY_CARD_FIELDS = Object.freeze([
+  "kind",
+  "schemaVersion",
+  "note",
+  "vendorAddress",
+  "productLine",
+  "claims",
+  "nonClaims",
+  "publishedAt",
+]);
+
+/**
+ * STRICT structural validation of an UNSIGNED identity-card payload. Throws an IdentityCardError on the
+ * FIRST problem (named + localized); returns the object unchanged on success. NEVER half-accepts and NEVER
+ * fills defaults. This is the `validateUnsigned` the attestation core re-runs on the embedded payload (the
+ * wrap-don't-edit invariant), so a signed container can never smuggle a malformed/edited card.
+ *
+ * REJECTS (HARD): a non-object; a wrong kind/schemaVersion/note; an UNKNOWN/extraneous field; a missing/
+ * malformed (not lowercase-0x) vendorAddress; an out-of-set productLine; a non-array OR EMPTY claims;
+ * a non-array OR EMPTY nonClaims; any claim/nonClaim that is not a non-empty string OR a duplicate; a
+ * non-canonical-ISO publishedAt.
+ *
+ * @param {any} obj
+ * @returns {object} the same object, if valid
+ */
+function validateIdentityCard(obj) {
+  if (!isPlainObject(obj)) {
+    throw new IdentityCardError("identity card payload must be a JSON object");
+  }
+
+  // CLOSED FIELD SET: every key must be one of IDENTITY_CARD_FIELDS. An unknown/extraneous key HARD-errors
+  // (never silently kept) so the card can never carry a smuggled, unvalidated field.
+  for (const key of Object.keys(obj)) {
+    if (!IDENTITY_CARD_FIELDS.includes(key)) {
+      throw new IdentityCardError(
+        `identity card has an unknown field: ${JSON.stringify(key)} ` +
+          `(the closed field set is ${JSON.stringify(IDENTITY_CARD_FIELDS)})`
+      );
+    }
+  }
+
+  if (obj.kind !== IDENTITY_CARD_KIND) {
+    throw new IdentityCardError(
+      `not a verifyhash identity card (kind: ${JSON.stringify(obj.kind)}; expected ${JSON.stringify(IDENTITY_CARD_KIND)})`
+    );
+  }
+  if (!SUPPORTED_IDENTITY_CARD_SCHEMA_VERSIONS.includes(obj.schemaVersion)) {
+    throw new IdentityCardError(
+      `unsupported identity card schemaVersion: ${JSON.stringify(obj.schemaVersion)} ` +
+        `(this build understands ${JSON.stringify(SUPPORTED_IDENTITY_CARD_SCHEMA_VERSIONS)})`
+    );
+  }
+  if (obj.note !== IDENTITY_CARD_TRUST_NOTE) {
+    throw new IdentityCardError(
+      "identity card `note` must be the standing IDENTITY_CARD_TRUST_NOTE (caveat must not drift)"
+    );
+  }
+
+  // vendorAddress — the address the card BINDS to the signing key. A lowercase 0x-address (checksummed/
+  // mixed-case is rejected here for byte-determinism; buildIdentityCard lowercases a checksummed input).
+  if (typeof obj.vendorAddress !== "string" || !ADDRESS_RE.test(obj.vendorAddress)) {
+    throw new IdentityCardError(
+      "identity card vendorAddress must be a 0x-prefixed 20-byte LOWERCASE-hex address " +
+        `(checksummed/mixed-case rejected for byte-determinism — lowercase it first), got: ${String(obj.vendorAddress)}`
+    );
+  }
+
+  // productLine — a single value drawn from the CLOSED PRODUCT_LINES set. An out-of-set value HARD-errors.
+  if (typeof obj.productLine !== "string" || !PRODUCT_LINE_SET.includes(obj.productLine)) {
+    throw new IdentityCardError(
+      `identity card productLine must be one of the closed set ${JSON.stringify(PRODUCT_LINE_SET)}, ` +
+        `got: ${JSON.stringify(obj.productLine)}`
+    );
+  }
+
+  // claims / nonClaims — each a NON-EMPTY array of unique, non-empty strings. An empty array is a HARD
+  // error: a card with no claims attests nothing, and a card with no nonClaims drops the load-bearing
+  // honest boundary. Validated by the SAME helper so both stay byte-identical.
+  _validateStringList(obj.claims, "claims");
+  _validateStringList(obj.nonClaims, "nonClaims");
+
+  // publishedAt — a strict, CANONICAL ISO-8601 UTC instant. The regex pins the SHAPE; the millis round-trip
+  // FORCES the `.mmm` form and REJECTS every rolled-over/impossible instant (e.g. Feb-29 in a non-leap year),
+  // exactly like the license core, so a self-asserted date can never silently coerce.
+  if (typeof obj.publishedAt !== "string" || !ISO_INSTANT_RE.test(obj.publishedAt)) {
+    throw new IdentityCardError(
+      `identity card publishedAt must be an ISO-8601 UTC instant ("YYYY-MM-DDTHH:MM:SS(.mmm)Z"), got: ${String(obj.publishedAt)}`
+    );
+  }
+  const ms = Date.parse(obj.publishedAt);
+  if (Number.isNaN(ms) || new Date(ms).toISOString() !== obj.publishedAt) {
+    throw new IdentityCardError(
+      `identity card publishedAt must be a canonical ISO-8601 UTC instant ("YYYY-MM-DDTHH:MM:SS.mmmZ", ` +
+        `millis required, no rolled-over/impossible fields), got: ${String(obj.publishedAt)}`
+    );
+  }
+
+  return obj;
+}
+
+/**
+ * Internal: validate a `claims`/`nonClaims` list — a NON-EMPTY array of unique, non-empty strings. The
+ * field NAME parameterizes the error so each list localizes its own failure. HARD-errors (IdentityCardError).
+ */
+function _validateStringList(list, fieldName) {
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new IdentityCardError(
+      `identity card ${fieldName} must be a non-empty array of strings`
+    );
+  }
+  const seen = new Set();
+  for (const item of list) {
+    if (typeof item !== "string" || item.length === 0) {
+      throw new IdentityCardError(
+        `identity card ${fieldName} entry must be a non-empty string, got: ${JSON.stringify(item)}`
+      );
+    }
+    if (seen.has(item)) {
+      throw new IdentityCardError(
+        `identity card ${fieldName} has a duplicate entry: ${JSON.stringify(item)}`
+      );
+    }
+    seen.add(item);
+  }
+}
+
+/**
+ * Serialize a validated UNSIGNED identity-card payload to its canonical, byte-deterministic bytes: a FIXED
+ * key order, NO insignificant whitespace, a single trailing newline. claims/nonClaims are emitted in the
+ * caller's order (their order is part of the card the vendor publishes — NOT order-independent like the
+ * license entitlement table). This is the EXACT byte sequence the envelope signs over and verifyIdentityCard
+ * re-derives the signer from, so two logically-identical cards sign identically.
+ * @param {object} payload a validated identity-card payload
+ * @returns {string} the canonical serialization (newline-terminated)
+ */
+function serializeIdentityCard(payload) {
+  validateIdentityCard(payload);
+  const canonical = {
+    kind: payload.kind,
+    schemaVersion: payload.schemaVersion,
+    note: payload.note,
+    vendorAddress: payload.vendorAddress,
+    productLine: payload.productLine,
+    claims: payload.claims.slice(),
+    nonClaims: payload.nonClaims.slice(),
+    publishedAt: payload.publishedAt,
+  };
+  return JSON.stringify(canonical) + "\n";
+}
+
+/**
+ * Assemble + strictly validate an UNSIGNED identity-card payload from caller fields. PURE. This is the
+ * payload `buildIdentityCard` then wraps in the signed envelope. Splitting it out lets a caller hold/inspect
+ * the unsigned card before signing (and validates it the SAME way the embedded payload is re-validated on
+ * read). A checksummed/mixed-case vendorAddress is normalized to lowercase here (a syntactically invalid
+ * address HARD-errors); every other field passes through to validateIdentityCard.
+ *
+ * @param {object} params { vendorAddress, productLine, claims, nonClaims, publishedAt }
+ * @returns {object} a validated, canonicalized identity-card payload
+ */
+function buildIdentityCardPayload(params) {
+  if (!isPlainObject(params)) {
+    throw new IdentityCardError(
+      "buildIdentityCardPayload requires a { vendorAddress, productLine, claims, nonClaims, publishedAt } object"
+    );
+  }
+  // Normalize a checksummed/mixed-case vendorAddress to canonical lowercase (so a caller may paste an EIP-55
+  // address). A syntactically invalid address is a HARD error (named, no surprise).
+  let vendorAddress;
+  try {
+    vendorAddress = getAddress(params.vendorAddress).toLowerCase();
+  } catch (_e) {
+    throw new IdentityCardError(
+      `identity card vendorAddress must be a valid 0x-address, got: ${String(params.vendorAddress)}`
+    );
+  }
+  const payload = {
+    kind: IDENTITY_CARD_KIND,
+    schemaVersion: IDENTITY_CARD_SCHEMA_VERSION,
+    note: IDENTITY_CARD_TRUST_NOTE,
+    vendorAddress,
+    productLine: params.productLine,
+    claims: params.claims,
+    nonClaims: params.nonClaims,
+    publishedAt: params.publishedAt,
+  };
+  // validateIdentityCard throws a named error on any malformed/unknown/missing/empty field — never silently
+  // accepts. Return the canonicalized payload (re-parsed from serializeIdentityCard) so the in-memory
+  // object's field order matches the signed bytes exactly.
+  validateIdentityCard(payload);
+  return JSON.parse(serializeIdentityCard(payload));
+}
+
+// The SIGNED-attestation framing passed to the GENERIC attestation core. The core does ALL the crypto +
+// the wrap-don't-edit invariant; this supplies ONLY the identity-card framing + the unsigned codec. SAME
+// pattern the seal/license/dataset use — frozen so it can never be mutated mid-flight.
+const SIGNED_IDENTITY_CARD_CFG = Object.freeze({
+  kind: SIGNED_IDENTITY_CARD_KIND,
+  schemaVersion: SIGNED_IDENTITY_CARD_SCHEMA_VERSION,
+  supportedSchemaVersions: SUPPORTED_SIGNED_IDENTITY_CARD_SCHEMA_VERSIONS,
+  note: SIGNED_IDENTITY_CARD_TRUST_NOTE,
+  label: "signed identity card",
+  validateUnsigned: validateIdentityCard,
+  serializeUnsigned: serializeIdentityCard,
+});
+
+/**
+ * Mint a SIGNED identity-card container. Builds + validates the unsigned payload (canonicalizing
+ * vendorAddress), then routes it + the caller's signer through the SHARED `signAttestation` core, which
+ * signs the EXACT canonical bytes (EIP-191 personal_sign) and wraps + validates the container.
+ *
+ * THE LOAD-BEARING MINT INVARIANT — the key MUST control the address it claims. After signing, the
+ * recovered signer is required to EQUAL the embedded `vendorAddress`. A provisioned key that does NOT
+ * control the claimed address HARD-errors (IdentityCardError) — the loop refuses to mint a card asserting
+ * an identity the signer cannot back. So a built card ALWAYS round-trips to ACCEPT by construction.
+ *
+ * NO key handling here — the key lives only inside the signer object (an ephemeral Wallet in tests).
+ *
+ * @param {object} params { vendorAddress, productLine, claims, nonClaims, publishedAt }
+ * @param {object} signer an ethers signer-like object: async getAddress() + signMessage()
+ * @returns {Promise<object>} the validated signed-identity-card container
+ */
+async function buildIdentityCard(params, signer) {
+  const payload = buildIdentityCardPayload(params);
+  const container = await coreAttestation.signAttestation(
+    { attestation: payload, signer },
+    SIGNED_IDENTITY_CARD_CFG
+  );
+  // Enforce the mint invariant: recover the signer from the just-signed bytes and require it to EQUAL the
+  // embedded vendorAddress. signAttestation already pinned the container's CLAIMED signer to the signer's
+  // own address, so this catches the genuine "minting a card for an address this key does not control"
+  // case — never a silent mint of an unbacked identity.
+  const recovered = coreAttestation.recoverSigner(container); // lowercase 0x-address
+  if (recovered !== payload.vendorAddress) {
+    throw new IdentityCardError(
+      "refusing to mint an identity card the signing key does not control: the recovered signer " +
+        `(${recovered}) does NOT equal the card's vendorAddress (${payload.vendorAddress}). Sign with the ` +
+        "key that controls vendorAddress, or set vendorAddress to the signing key's address."
+    );
+  }
+  return container;
+}
+
+/** Strictly validate a parsed SIGNED identity-card container — thin wrapper over the shared core. */
+function validateSignedIdentityCard(obj) {
+  return coreAttestation.validateSignedAttestation(obj, SIGNED_IDENTITY_CARD_CFG);
+}
+
+/** Serialize a SIGNED identity-card container to its canonical bytes — thin wrapper over the shared core. */
+function serializeSignedIdentityCard(container) {
+  return coreAttestation.serializeSignedAttestation(container, SIGNED_IDENTITY_CARD_CFG);
+}
+
+/**
+ * Read + strictly validate a SIGNED identity-card container (JSON string or object). A parse error is an
+ * IdentityCardError (never a raw SyntaxError); a malformed/corrupt container is rejected by the shared
+ * validator, never half-accepted.
+ * @param {string|object} input
+ * @returns {object} the validated container
+ */
+function readIdentityCard(input) {
+  let obj;
+  if (typeof input === "string") {
+    try {
+      obj = JSON.parse(input);
+    } catch (e) {
+      throw new IdentityCardError(`identity card container is not valid JSON: ${e.message}`);
+    }
+  } else if (isPlainObject(input)) {
+    obj = input;
+  } else {
+    throw new IdentityCardError("readIdentityCard requires a JSON string or a signed-identity-card container object");
+  }
+  try {
+    coreAttestation.validateSignedAttestation(obj, SIGNED_IDENTITY_CARD_CFG);
+  } catch (e) {
+    throw new IdentityCardError(e.message);
+  }
+  return obj;
+}
+
+/**
+ * Verify (purely, OFFLINE) a SIGNED identity-card container — the STRICT, PURE verify path. It recovers the
+ * signer from the embedded canonical card bytes + signature and:
+ *   (1) confirms it equals the container's CLAIMED `signer` (signatureMatchesSigner — ALWAYS run);
+ *   (2) confirms it equals the card's OWN embedded `vendorAddress` (vendorAddressMatchesSigner — ALWAYS
+ *       run; this is the load-bearing "the key controls the address it claims" check);
+ *   (3) OPTIONALLY pins it to an EXPECTED signer (`expectedSigner` / the CLI `--signer` flag —
+ *       signerMatchesExpected, run ONLY when present).
+ * The verdict is ACCEPTED only when EVERY requested check passes; a forged/mismatched/tampered card is a
+ * clean REJECTED — NEVER a silent pass, NEVER a thrown error for an ordinary rejection.
+ *
+ * It is OFFLINE / key-free / network-free / I/O-free: it recovers a PUBLIC address from a signature, holds
+ * no private key, contacts nothing, writes nothing, and mutates the container NOT at all. The returned
+ * shape EXTENDS the FAMILY verdict shape (the byte-for-byte fields `verifySignedAttestation` returns,
+ * including `checks`/`failedChecks`/`recoveredSigner`/`claimedSigner` so a future indexer/UI depends on
+ * ONE stable shape) with the identity-specific `vendorAddress` + `checks.vendorAddressMatchesSigner`.
+ *
+ * STRUCTURAL SAFETY: the container is validated FIRST (validateSignedIdentityCard); a structurally invalid
+ * container HARD-errors (IdentityCardError) before any recovery, so an ordinary REJECTED verdict only ever
+ * describes a SOUND card whose signature simply doesn't back its claims.
+ *
+ * @param {object} params
+ * @param {object} params.container        a signed-identity-card container (from buildIdentityCard/readIdentityCard)
+ * @param {string} [params.expectedSigner] OPTIONAL expected signer 0x-address (--signer); checked when present
+ * @returns {{
+ *   verdict: "ACCEPTED"|"REJECTED",
+ *   accepted: boolean,
+ *   recoveredSigner: string,
+ *   claimedSigner: string,
+ *   vendorAddress: string,
+ *   scheme: string,
+ *   checks: {
+ *     signatureMatchesSigner: boolean,
+ *     vendorAddressMatchesSigner: boolean,
+ *     signerMatchesExpected: boolean|null,
+ *   },
+ *   expectedSigner: string|null,
+ *   failedChecks: string[],
+ * }}
+ */
+function verifyIdentityCard(params) {
+  if (!isPlainObject(params)) {
+    throw new IdentityCardError("verifyIdentityCard requires { container, [expectedSigner] }");
+  }
+  // Validate the container FIRST (and re-validate the embedded card) so an ordinary REJECTED verdict only
+  // ever describes a STRUCTURALLY SOUND card. A corrupt/foreign container is a HARD error, never a verdict.
+  const container = validateSignedIdentityCard(params.container);
+  const vendorAddress = JSON.parse(container.attestation).vendorAddress; // lowercase 0x (validated above)
+
+  // Route the signature recovery + the OPTIONAL expected-signer pin through the SHARED generic core (the
+  // SAME path the seal/license use). We do NOT pass expectedCanonical — the identity-specific binding is
+  // the vendorAddress check below, computed from the embedded card, not from a caller's directory.
+  const att = coreAttestation.verifySignedAttestation({
+    container,
+    expectedSigner: params.expectedSigner,
+  });
+
+  // (2) The load-bearing identity check: the RECOVERED signer must equal the card's OWN vendorAddress. We
+  //     pin against the RECOVERED signer (not the merely-CLAIMED one), so a card that claims a vendorAddress
+  //     its signature does not back is REJECTED. When the signature is unrecoverable, recoveredSigner is the
+  //     "(unrecoverable)" sentinel, which can never equal a lowercase 0x-address — so this is false (REJECT).
+  const vendorAddressMatchesSigner = att.recoveredSigner === vendorAddress;
+
+  // The verdict is ACCEPTED only when EVERY requested check passes. signatureMatchesSigner +
+  // vendorAddressMatchesSigner are ALWAYS required; signerMatchesExpected only when --signer was given
+  // (null = not requested, never fails the gate). We REBUILD failedChecks (the core's list does not know
+  // about vendorAddressMatchesSigner) so the verdict, the checks, and failedChecks can never disagree.
+  const failedChecks = [];
+  if (!att.checks.signatureMatchesSigner) failedChecks.push("signatureMatchesSigner");
+  if (!vendorAddressMatchesSigner) failedChecks.push("vendorAddressMatchesSigner");
+  if (att.checks.signerMatchesExpected === false) failedChecks.push("signerMatchesExpected");
+  const accepted = failedChecks.length === 0;
+
+  return {
+    verdict: accepted ? "ACCEPTED" : "REJECTED",
+    accepted,
+    recoveredSigner: att.recoveredSigner,
+    claimedSigner: att.claimedSigner,
+    vendorAddress,
+    scheme: att.scheme,
+    checks: {
+      signatureMatchesSigner: att.checks.signatureMatchesSigner,
+      vendorAddressMatchesSigner,
+      signerMatchesExpected: att.checks.signerMatchesExpected,
+    },
+    expectedSigner: att.expectedSigner,
+    failedChecks,
+  };
+}
+
+// ===========================================================================
+// THE CLI SURFACE — `vh identity publish` (mint) + `vh identity verify` (check + pin).
+//
+// `vh identity publish` MINTS the signed producer identity card the family's recipients verify. It signs
+// with a HUMAN-provisioned key (EXACTLY ONE of --key-env/--key-file, read-used-discarded via the SHARED
+// loadSigningWallet — the loop NEVER generates/persists/logs a key). It mints ONLY when the provisioned
+// key's address EQUALS the caller's --address (the buildIdentityCard mint invariant), so a card can never
+// assert an identity the key does not control. Default prints the card + writes NOTHING; --out writes to a
+// caller-chosen path (never silently to cwd).
+//
+// `vh identity verify <card>` is the OFFLINE / key-free / network-free read path. It LEADS with the trust
+// line, prints the claims/non-claims + per-check PASS/FAIL, and OPTIONALLY pins --signer. ACCEPT/REJECT/
+// usage exits map 0/3/2/1 (mirrors the family's read commands).
+//
+// The CLI is a THIN I/O shell over the PURE core above: all crypto/validation lives in buildIdentityCard/
+// verifyIdentityCard; this layer only parses argv, reads/writes files, and renders.
+// ===========================================================================
+
+// Exit contract shared with the rest of the family: 0 ok/ACCEPTED / 1 IO / 2 usage / 3 gate-fail
+// (verify REJECTED). Mirrors cli/evidence.js's EXIT so every gate reads the same.
+const EXIT = Object.freeze({ OK: 0, IO: 1, USAGE: 2, FAIL: 3 });
+
+// Parse `identity publish` argv. --claim/--non-claim are REPEATABLE (each occurrence appends, preserving
+// order — the order is part of the published card). EXACTLY-ONE-of key sources is enforced downstream by
+// loadSigningWallet (so neither/both error key-free); the parser only collects flags. A flag without its
+// value, or an unknown flag, is a usage error (e.usage=true) — a typo never silently changes the card.
+function parsePublishArgs(argv) {
+  const opts = {
+    address: undefined,
+    productLine: undefined,
+    claims: [],
+    nonClaims: [],
+    publishedAt: undefined,
+    keyEnv: undefined,
+    keyFile: undefined,
+    out: undefined,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const need = (flag) => {
+      const v = argv[++i];
+      if (v === undefined) {
+        const e = new Error(`${flag} requires a value`);
+        e.usage = true;
+        throw e;
+      }
+      return v;
+    };
+    switch (a) {
+      case "--address":
+        opts.address = need("--address");
+        break;
+      case "--product-line":
+        opts.productLine = need("--product-line");
+        break;
+      case "--claim":
+        opts.claims.push(need("--claim"));
+        break;
+      case "--non-claim":
+        opts.nonClaims.push(need("--non-claim"));
+        break;
+      case "--published-at":
+        opts.publishedAt = need("--published-at");
+        break;
+      case "--key-env":
+        opts.keyEnv = need("--key-env");
+        break;
+      case "--key-file":
+        opts.keyFile = need("--key-file");
+        break;
+      case "--out":
+        opts.out = need("--out");
+        break;
+      case "--json":
+        opts.json = true;
+        break;
+      default: {
+        const e = new Error(`unknown flag: ${a} (identity publish takes no positional arguments)`);
+        e.usage = true;
+        throw e;
+      }
+    }
+  }
+  return opts;
+}
+
+// Real "now" as a canonical ISO-8601 UTC instant — the publish default clock, isolated + injectable
+// (io.nowISO) so the command stays deterministic under test. publishedAt defaults to this when omitted.
+function nowISO() {
+  return new Date().toISOString();
+}
+
+/**
+ * `vh identity publish` — MINT a signed identity card. PURE core + the only I/O being the OPTIONAL --out
+ * write (the signing is offline/key-free in the sense that the loop holds no key; the human's key lives
+ * ONLY inside the in-process Wallet loadSigningWallet builds and is discarded).
+ *
+ * The mint is REFUSED (HARD error, BEFORE any write) when the provisioned key's address != --address — so
+ * a card can never assert an identity the key does not control. The output LEADS with the trust line.
+ *
+ * Exit: 0 ok / 2 usage (missing/invalid field, key-source error, mint-control mismatch) / 1 IO (--out write).
+ */
+async function runIdentityPublish(opts, io = {}) {
+  const write = io.write || ((s) => process.stdout.write(s));
+  const writeErr = io.writeErr || ((s) => process.stderr.write(s));
+
+  // Required order fields up front (a missing one is a clean usage error, never a confusing core throw).
+  if (opts.address == null) {
+    writeErr("error: `vh identity publish` requires --address <0xaddr> (the vendor address the card binds)\n");
+    return EXIT.USAGE;
+  }
+  if (opts.productLine == null) {
+    writeErr(
+      `error: \`vh identity publish\` requires --product-line <line> (one of ${JSON.stringify(PRODUCT_LINE_SET)})\n`
+    );
+    return EXIT.USAGE;
+  }
+  if (opts.claims.length === 0) {
+    writeErr("error: `vh identity publish` requires at least one --claim <text> (what the vendor attests)\n");
+    return EXIT.USAGE;
+  }
+  if (opts.nonClaims.length === 0) {
+    writeErr(
+      "error: `vh identity publish` requires at least one --non-claim <text> " +
+        "(the honest boundary: what the vendor explicitly does NOT attest)\n"
+    );
+    return EXIT.USAGE;
+  }
+
+  // Validate the --address SHAPE up front so a malformed address is a usage error (2), never a runtime
+  // throw mid-mint. buildIdentityCardPayload also normalizes/validates, but failing fast here gives the
+  // clean exit-2 the contract promises. (isAddress accepts checksummed/lowercase 0x-addresses.)
+  if (!isAddress(opts.address)) {
+    writeErr(`error: invalid --address: ${opts.address} (expected a 20-byte 0x-hex address)\n`);
+    return EXIT.USAGE;
+  }
+
+  // Resolve the HUMAN-supplied key into an in-process Wallet FIRST — neither/both sources, a missing env
+  // var, an unreadable file, or a malformed/zero key HARD-ERRORS here with a KEY-FREE message (the SAME
+  // core + posture as `vh evidence seal --sign`). The loop NEVER holds/generates/persists/logs a key.
+  let wallet;
+  try {
+    ({ wallet } = coreAttestation.loadSigningWallet({ keyEnv: opts.keyEnv, keyFile: opts.keyFile }));
+  } catch (e) {
+    writeErr(`error: ${e.message}\n`);
+    return EXIT.USAGE;
+  }
+
+  // publishedAt defaults to the injectable clock (a real ISO instant at runtime; a pinned one in tests).
+  const publishedAt = opts.publishedAt != null ? opts.publishedAt : (io.nowISO || nowISO)();
+
+  // Build + sign + enforce the mint invariant in the PURE core. A malformed field (out-of-set productLine,
+  // empty/duplicate claim, non-canonical date) OR the key NOT controlling --address throws IdentityCardError
+  // — a usage error (2), BEFORE any --out write. The message never includes the key.
+  let container;
+  try {
+    container = await buildIdentityCard(
+      {
+        vendorAddress: opts.address,
+        productLine: opts.productLine,
+        claims: opts.claims,
+        nonClaims: opts.nonClaims,
+        publishedAt,
+      },
+      wallet
+    );
+  } catch (e) {
+    writeErr(`error: ${e.message}\n`);
+    return EXIT.USAGE;
+  }
+
+  const canonical = serializeSignedIdentityCard(container);
+  const payload = JSON.parse(container.attestation);
+  // The PUBLIC vendor address — recovered from the signature, never the key. By the mint invariant it
+  // equals payload.vendorAddress; we recover it to PROVE that (and to print "signed by" from the signature).
+  const signedBy = coreAttestation.recoverSigner(container);
+
+  // Write to --out (caller-chosen path; NEVER cwd) or print to stdout (writes nothing).
+  let outAbs = null;
+  if (opts.out) {
+    outAbs = path.resolve(opts.out);
+    try {
+      fs.writeFileSync(outAbs, canonical);
+    } catch (e) {
+      writeErr(`error: cannot write --out file ${opts.out}: ${e.message}\n`);
+      return EXIT.IO;
+    }
+  }
+
+  if (opts.json) {
+    // ONLY public fields: the vendor ADDRESS (recovered), the card summary, the path — NEVER the key. With
+    // no --out the canonical bytes ride in `container` so --json never drops the artifact (family parity).
+    write(
+      JSON.stringify(
+        {
+          published: true,
+          note: IDENTITY_CARD_TRUST_NOTE,
+          kind: SIGNED_IDENTITY_CARD_KIND,
+          vendorAddress: payload.vendorAddress,
+          signer: signedBy,
+          productLine: payload.productLine,
+          claims: payload.claims,
+          nonClaims: payload.nonClaims,
+          publishedAt: payload.publishedAt,
+          out: outAbs,
+          container: outAbs ? null : canonical,
+        },
+        null,
+        2
+      ) + "\n"
+    );
+  } else {
+    write(IDENTITY_CARD_TRUST_NOTE + "\n\n");
+    write(`published a signed identity card for ${payload.vendorAddress} (signed by ${signedBy})\n`);
+    write(`  productLine:  ${payload.productLine}\n`);
+    write(`  publishedAt:  ${payload.publishedAt}\n`);
+    write(`  claims (${payload.claims.length}):\n`);
+    for (const c of payload.claims) write(`    + ${c}\n`);
+    write(`  nonClaims (${payload.nonClaims.length}):\n`);
+    for (const c of payload.nonClaims) write(`    - ${c}\n`);
+    if (outAbs) {
+      write(`  written:      ${outAbs}\n`);
+    } else {
+      // Default: print the card bytes so a publisher can eyeball/redirect them — still writes nothing.
+      write(canonical);
+    }
+  }
+  return EXIT.OK;
+}
+
+// Parse `identity verify` argv. Takes exactly one positional <card> + OPTIONAL --signer/--json.
+function parseVerifyArgs(argv) {
+  const opts = {
+    card: undefined,
+    signer: undefined,
+    revocations: undefined,
+    asOf: undefined,
+    json: false,
+    _positionals: [],
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const need = (flag) => {
+      const v = argv[++i];
+      if (v === undefined) {
+        const e = new Error(`${flag} requires a value`);
+        e.usage = true;
+        throw e;
+      }
+      return v;
+    };
+    switch (a) {
+      case "--signer":
+        opts.signer = need("--signer");
+        break;
+      case "--revocations":
+        opts.revocations = need("--revocations");
+        break;
+      case "--as-of":
+        opts.asOf = need("--as-of");
+        break;
+      case "--json":
+        opts.json = true;
+        break;
+      default:
+        if (a && a.startsWith("--")) {
+          const e = new Error(`unknown flag: ${a}`);
+          e.usage = true;
+          throw e;
+        }
+        opts._positionals.push(a);
+    }
+  }
+  if (opts._positionals.length > 1) {
+    const e = new Error(
+      `unexpected extra argument: ${opts._positionals[1]} (identity verify takes exactly one <card>)`
+    );
+    e.usage = true;
+    throw e;
+  }
+  opts.card = opts._positionals[0];
+  return opts;
+}
+
+// The standing trust line the verify path LEADS with — reuses the SIGNED-card note verbatim (so the human
+// + JSON caveats can NEVER drift). It is the load-bearing honesty of the read: an ACCEPT proves IDENTITY +
+// the claim SET, NOT any specific packet, NOT a timestamp (P-3), NOT a legal opinion.
+const VERIFY_TRUST_NOTE = SIGNED_IDENTITY_CARD_TRUST_NOTE;
+
+// Render the human verify report. PURE. LEADS with the trust line, prints the verdict, the recovered/
+// claimed/vendor address, the per-check PASS/FAIL (Check 1 + the vendorAddress identity check ALWAYS; the
+// --signer pin only when requested), then the published CLAIMS + NON-CLAIMS. A REJECTED verdict NAMES the
+// failing check(s). The claims/non-claims are rendered FROM THE RECOVERED, validated card (never trusted
+// blindly: a REJECTED card's claims are shown but the verdict makes clear they are NOT backed).
+function renderVerify(r, card, ctx) {
+  const L = [];
+  // TRUST FIRST.
+  L.push("TRUST: " + VERIFY_TRUST_NOTE);
+  L.push("");
+  L.push(`# vh identity verify — ${ctx.card}`);
+  L.push(`identity:         ${r.verdict}`);
+  L.push(`scheme:           ${r.scheme}`);
+  L.push(`vendorAddress:    ${r.vendorAddress}  (the address the card BINDS to the signing key)`);
+  L.push(`recovered signer: ${r.recoveredSigner}  (from the embedded canonical card bytes + signature)`);
+  L.push(`claimed signer:   ${r.claimedSigner}  (the container's \`signer\` field)`);
+  L.push(`productLine:      ${card.productLine}`);
+  L.push(`publishedAt:      ${card.publishedAt}`);
+  // Check 1 (ALWAYS): the signature recovers to the claimed signer.
+  L.push(`  [${r.checks.signatureMatchesSigner ? "PASS" : "FAIL"}] signature recovers to the claimed signer`);
+  // The load-bearing identity check (ALWAYS): the recovered signer IS the card's own vendorAddress.
+  L.push(
+    `  [${r.checks.vendorAddressMatchesSigner ? "PASS" : "FAIL"}] the recovered signer IS the card's ` +
+      "vendorAddress (the key controls the address it claims)"
+  );
+  // Check 3 (only under --signer): the recovered signer equals the expected, out-of-band signer.
+  if (r.checks.signerMatchesExpected === null) {
+    L.push("  [skip] expected-signer pin: not requested (pass --signer <0xaddr> to pin the signer)");
+  } else {
+    L.push(
+      `  [${r.checks.signerMatchesExpected ? "PASS" : "FAIL"}] recovered signer matches the expected ` +
+        `signer (${r.expectedSigner})`
+    );
+  }
+  // The published CLAIMS + NON-CLAIMS — the WHOLE point of the card (what the vendor attests + does NOT).
+  L.push(`claims (${card.claims.length}) — what this vendor attests:`);
+  for (const c of card.claims) L.push(`    + ${c}`);
+  L.push(`nonClaims (${card.nonClaims.length}) — what this vendor explicitly does NOT attest:`);
+  for (const c of card.nonClaims) L.push(`    - ${c}`);
+  if (r.accepted) {
+    L.push("ACCEPTED: every requested check passed — this card's identity + claim set are backed by the signer.");
+  } else {
+    L.push(`REJECTED: failed check(s): ${r.failedChecks.join(", ")}.`);
+    if (r.failedChecks.includes("signatureMatchesSigner")) {
+      L.push(
+        "  forged/tampered: the signature does NOT recover to the claimed `signer` — the card's claims are UNBACKED."
+      );
+    }
+    if (r.failedChecks.includes("vendorAddressMatchesSigner")) {
+      L.push(
+        "  vendor-mismatch: the recovered signer is NOT the card's vendorAddress — the card asserts an identity"
+      );
+      L.push("  the signing key does NOT control. Its claims are NOT backed by the address it names.");
+    }
+    if (r.failedChecks.includes("signerMatchesExpected")) {
+      L.push(
+        "  pin-mismatch: the signature is genuine but the signer is NOT the address you pinned with --signer."
+      );
+    }
+  }
+  L.push("");
+  return L.join("\n");
+}
+
+/**
+ * `vh identity verify <card> [--signer <0xaddr>] [--json]` — OFFLINE / key-free / network-free. RECOVERS
+ * the signer from a signed identity card and confirms (1) the signature backs the claimed signer, (2) the
+ * recovered signer IS the card's own vendorAddress (the load-bearing identity check), and OPTIONALLY (3)
+ * pins it to an expected --signer. LEADS with the trust line; prints the claims/non-claims + per-check
+ * PASS/FAIL. A forged/tampered/wrong-key card, or a wrong --signer, is a clean REJECTED — NEVER a silent
+ * pass. Writes NOTHING. Exit: 0 ACCEPTED / 3 REJECTED / 2 usage / 1 IO.
+ */
+// Shared up-front shape validation for the OPTIONAL recipient-side trust-decision flags (--revocations /
+// --as-of, T-51.2). Returns null when fine, else a usage-error message. A malformed --as-of is a usage error
+// (never a runtime throw mid-verify); --as-of without --revocations is a usage error. Mirrors the trust-asof
+// core's canonical-instant grammar.
+function validateAsOfFlags(opts) {
+  if (opts.asOf !== undefined && !opts.revocations) {
+    return "--as-of requires --revocations (it pins the instant the revocation decision is made AS OF)";
+  }
+  if (opts.asOf !== undefined) {
+    const re = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
+    const ms = Date.parse(opts.asOf);
+    if (
+      typeof opts.asOf !== "string" ||
+      !re.test(opts.asOf) ||
+      Number.isNaN(ms) ||
+      new Date(ms).toISOString() !== opts.asOf
+    ) {
+      return `invalid --as-of: ${opts.asOf} (expected a canonical ISO-8601 UTC instant, e.g. 2026-06-01T00:00:00.000Z)`;
+    }
+  }
+  return null;
+}
+
+function runIdentityVerify(opts, io = {}) {
+  const write = io.write || ((s) => process.stdout.write(s));
+  const writeErr = io.writeErr || ((s) => process.stderr.write(s));
+
+  if (!opts.card) {
+    writeErr("error: `vh identity verify` requires a <card> (a signed identity-card file path)\n");
+    return EXIT.USAGE;
+  }
+
+  // Validate the --signer SHAPE up front (when given) so a malformed pin is a usage error (2), never a
+  // runtime throw inside verifyIdentityCard (which normalizes via getAddress and would throw). OFFLINE.
+  if (opts.signer !== undefined && opts.signer !== null) {
+    if (!isAddress(opts.signer)) {
+      writeErr(`error: invalid --signer address: ${opts.signer} (expected a 20-byte 0x-hex address)\n`);
+      return EXIT.USAGE;
+    }
+  }
+
+  // Validate the OPTIONAL trust-decision flags (--revocations/--as-of, T-51.2) SHAPE up front so a malformed
+  // --as-of (or --as-of without --revocations) is a usage error (2), never a runtime throw mid-verify.
+  {
+    const asOfErr = validateAsOfFlags(opts);
+    if (asOfErr) {
+      writeErr(`error: ${asOfErr}\n`);
+      return EXIT.USAGE;
+    }
+  }
+
+  // Read + STRICT-validate the container BEFORE any recovery — a malformed/edited/foreign container (or a
+  // non-card file) hard-errors (exit 1), never half-accepted. A forged signature is NOT a parse error:
+  // readIdentityCard proves the bytes are canonical; the recovery (the verdict) runs below in the PURE core.
+  let container;
+  try {
+    const text = fs.readFileSync(path.resolve(opts.card), "utf8");
+    container = readIdentityCard(text);
+  } catch (e) {
+    writeErr(`error: cannot read signed identity card ${opts.card}: ${e.message}\n`);
+    return EXIT.IO;
+  }
+
+  // Run the PURE, OFFLINE verify. No I/O, no key, no network. A structurally-sound-but-forged/mismatched
+  // card is a clean REJECTED verdict (not a throw); only a genuinely broken read would throw (caught above).
+  let result;
+  try {
+    result = verifyIdentityCard({ container, expectedSigner: opts.signer });
+  } catch (e) {
+    writeErr(`error: ${e.message}\n`);
+    return EXIT.IO;
+  }
+  const card = JSON.parse(container.attestation); // the validated embedded card (claims/nonClaims/etc.)
+
+  // OPTIONAL recipient-side TRUST-DECISION-AS-OF (EPIC-51 / T-51.2). Runs ONLY under --revocations — with no
+  // flag the result is byte-identical to the pre-EPIC baseline. A card whose vendor key was revoked-before-
+  // as-of downgrades an otherwise-ACCEPTED card to REVOKED (exit 3); a later revocation is informational; a
+  // forged one is ignored with a warning. OFFLINE / key-free on the read side. The revocations file is the
+  // ONLY new I/O. The subject is the card's RECOVERED signer (== its vendorAddress on an ACCEPTED card).
+  let defaulted = false;
+  if (opts.revocations) {
+    try {
+      const applied = coreTrustAsOf.loadAndApply({
+        result,
+        revocationsPath: opts.revocations,
+        asOf: opts.asOf,
+        nowISO: io.nowISO || new Date().toISOString(),
+        readFile: (p) => fs.readFileSync(path.resolve(p), "utf8"),
+      });
+      result = applied.result;
+      defaulted = applied.defaulted;
+    } catch (e) {
+      writeErr(`error: cannot evaluate --revocations ${opts.revocations}: ${e.message}\n`);
+      return EXIT.IO;
+    }
+  }
+
+  if (opts.json) {
+    write(
+      JSON.stringify(
+        {
+          ...result,
+          // The published claim set the verdict is about (so a machine reader gets identity + claims in one).
+          productLine: card.productLine,
+          claims: card.claims,
+          nonClaims: card.nonClaims,
+          publishedAt: card.publishedAt,
+          card: opts.card,
+          note: VERIFY_TRUST_NOTE,
+        },
+        null,
+        2
+      ) + "\n"
+    );
+  } else {
+    let out = renderVerify(result, card, { card: opts.card });
+    if (result.trustAsOf) {
+      out += coreTrustAsOf.renderTrustAsOf(result.trustAsOf, { defaulted }).join("\n") + "\n";
+    }
+    write(out);
+  }
+
+  // Exit non-zero on REJECTED/REVOKED so a buyer's CI can gate (0 ACCEPTED / 3 not-OK — the family's read contract).
+  return result.accepted ? EXIT.OK : EXIT.FAIL;
+}
+
+function identityUsage() {
+  return [
+    "vh identity — publish + verify a producer IDENTITY CARD (bind a vendor address to a bounded claim set)",
+    "",
+    "Usage:",
+    "  vh identity publish --address <0xaddr> --product-line <line> --claim <text> [--claim ...]",
+    "        --non-claim <text> [--non-claim ...] [--published-at <ISO>]",
+    "        (--key-env <VAR> | --key-file <path>) [--out <p>] [--json]",
+    "  vh identity verify <card> [--signer <0xaddr>] [--revocations <f> --as-of <ISO>] [--json]",
+    "",
+    "publish MINTS a signed card binding --address to the --claim set it attests + the --non-claim set it",
+    "  explicitly does NOT. It signs with a HUMAN-provisioned key (EXACTLY ONE of --key-env/--key-file,",
+    "  read-used-discarded; the loop sets/holds NO key) and MINTS ONLY when that key's address EQUALS",
+    "  --address (else it hard-errors BEFORE writing). --product-line is one of " +
+      JSON.stringify(PRODUCT_LINE_SET) + ".",
+    "  Default prints the card + writes NOTHING; --out writes to a caller-chosen path (never cwd).",
+    "  Exit: 0 ok / 2 usage (missing/invalid field, key-source error, key does not control --address) / 1 IO.",
+    "verify is OFFLINE/key-free/network-free: it RECOVERS the signer, confirms the signature backs it AND that",
+    "  the recovered signer IS the card's vendorAddress, OPTIONALLY pins --signer, OPTIONALLY checks the vendor",
+    "  key was not REVOKED as of --as-of (default now) via --revocations, and prints the claims/non-claims +",
+    "  per-check PASS/FAIL. A forged/tampered/wrong-key card, a wrong --signer, or a key revoked-before-as-of is",
+    "  a clean REJECTED/REVOKED — never a silent pass. Exit: 0 ACCEPTED / 3 REJECTED|REVOKED / 2 usage / 1 IO.",
+    "",
+    "A card proves IDENTITY + the claim SET only: NOT any specific sealed packet (each carries its own proof),",
+    "NOT a trusted TIMESTAMP (P-3), and NOT a legal opinion.",
+    "",
+  ].join("\n");
+}
+
+/**
+ * CLI dispatch: `vh identity <publish|verify> ...`. An UNKNOWN subcommand is a USAGE error (2) — the loop
+ * never silently accepts a typo'd subcommand. `-h`/`--help`/`help`/no-subcommand prints usage.
+ */
+async function cmdIdentity(argv, io = {}) {
+  const writeErr = io.writeErr || ((s) => process.stderr.write(s));
+  const [sub, ...rest] = argv;
+  if (sub === "publish") {
+    let opts;
+    try {
+      opts = parsePublishArgs(rest);
+    } catch (e) {
+      writeErr(`error: ${e.message}\n`);
+      return EXIT.USAGE;
+    }
+    return runIdentityPublish(opts, io);
+  }
+  if (sub === "verify") {
+    let opts;
+    try {
+      opts = parseVerifyArgs(rest);
+    } catch (e) {
+      writeErr(`error: ${e.message}\n`);
+      return EXIT.USAGE;
+    }
+    return runIdentityVerify(opts, io);
+  }
+  if (sub === undefined || sub === "-h" || sub === "--help" || sub === "help") {
+    io.write ? io.write(identityUsage()) : process.stdout.write(identityUsage());
+    return sub === undefined ? EXIT.USAGE : EXIT.OK;
+  }
+  writeErr(`error: unknown identity subcommand: ${sub} (expected: publish, verify)\n`);
+  return EXIT.USAGE;
+}
+
+module.exports = {
+  // kinds + closed sets
+  IDENTITY_CARD_KIND,
+  IDENTITY_CARD_SCHEMA_VERSION,
+  SUPPORTED_IDENTITY_CARD_SCHEMA_VERSIONS,
+  SIGNED_IDENTITY_CARD_KIND,
+  SIGNED_IDENTITY_CARD_SCHEMA_VERSION,
+  SUPPORTED_SIGNED_IDENTITY_CARD_SCHEMA_VERSIONS,
+  PRODUCT_LINES,
+  PRODUCT_LINE_SET,
+  IDENTITY_CARD_FIELDS,
+  IDENTITY_CARD_TRUST_NOTE,
+  SIGNED_IDENTITY_CARD_TRUST_NOTE,
+  IdentityCardError,
+  // unsigned-payload codec
+  validateIdentityCard,
+  serializeIdentityCard,
+  buildIdentityCardPayload,
+  // signed container
+  buildIdentityCard,
+  validateSignedIdentityCard,
+  serializeSignedIdentityCard,
+  readIdentityCard,
+  verifyIdentityCard,
+  // CLI surface
+  EXIT,
+  nowISO,
+  VERIFY_TRUST_NOTE,
+  parsePublishArgs,
+  parseVerifyArgs,
+  runIdentityPublish,
+  runIdentityVerify,
+  renderVerify,
+  identityUsage,
+  cmdIdentity,
+};