@nexart/cli 0.15.0 → 0.16.0

package/dist/index.js

@@ -66,7 +66,8 @@ import { realpathSync } from 'fs';
 import { createRequire } from 'module';
 // Standalone (SDK-free) CER verifier. This module imports ONLY node:crypto and
 // nothing from @nexart/* — it is the auditable, dependency-free verification core.
-import { verifyBundleStandalone, } from './standaloneVerify.js';
+import { verifyBundleStandalone, resolvePublicKey, } from './standaloneVerify.js';
+import { DIGICERT_DEFAULT_ROOTS_PEM } from './trustRoots.js';
 import { verifyProjectBundle, verifyAiCerBundleDetailed, hasAttestation as sdkHasAttestation, isCerPackage as sdkIsCerPackage, getCerFromPackage, createSnapshot as sdkCreateSnapshot, sealCer as sdkSealCer, attachAnchor as sdkAttachAnchor, verifyAnchors as sdkVerifyAnchors, verifyTrustedTimestamps as sdkVerifyTrustedTimestamps, exportVerificationPackage as sdkExportVerificationPackage, isSupportedProtocolVersion, } from '@nexart/ai-execution';
 // Deterministic local renderer — reuses the canonical CodeMode SDK render core.
 // Importing the module does NOT load the native `canvas` package; `canvas` is
@@ -1397,9 +1398,15 @@ export async function verifyBundleStandaloneCommand(file, opts) {
 function resolveTimestampResult(timestampInfo, opts) {
     if (!timestampInfo.present)
         return { status: 'not-present' };
-    if (!opts.verifyTimestamp)
+    // `auto` (verify-record) always verifies when a token is present; `verifyTimestamp`
+    // (verify-bundle) keeps its opt-in gate so its behaviour is byte-for-byte unchanged.
+    if (!opts.auto && !opts.verifyTimestamp)
         return { status: 'present-unverified' };
-    let trustedRootsPem;
+    // Trust roots: an explicit --tsa-roots always wins (used by tests to anchor a
+    // freeTSA fixture); otherwise fall back to the caller's embedded default store
+    // (DigiCert, for verify-record). verify-bundle passes no default, so a missing
+    // --tsa-roots there still yields 'untrusted-root' exactly as before.
+    let trustedRootsPem = opts.defaultRootsPem;
     if (opts.tsaRoots) {
         try {
             trustedRootsPem = fs.readFileSync(opts.tsaRoots, 'utf-8');
@@ -1475,82 +1482,423 @@ function renderStandaloneVerification(result, tsaResult, opts) {
         console.error(`  ! Timestamp: ${tsaResult.reason}`);
     }
 }
+export async function verifyRecordStandaloneCommand(file, opts) {
+    // A single "-" reads the record from stdin, enabling pipelines such as
+    // `curl … | nexart verify-record -`.
+    const record = readJsonInput(file, 'record');
+    return verifyRecordFromObject(record, opts);
+}
 /**
- * nexart verify-record — Verify a full NexArt CER RECORD offline and independently.
- *
- * A "record" is the full verification envelope: { bundle, verification: { receipt,
- * receiptSignature }, timestamp? }. This command is STRICTLY ADDITIVE alongside
- * `verify-bundle` and reuses the exact same engine:
- *   - INTEGRITY + SIGNATURE: the record's `verification.receipt` /
- *     `verification.receiptSignature` are merged into a SHALLOW copy of `bundle`
- *     (which never affects the recomputed certificateHash — receipt/signature are
- *     not part of the certificate payload) and handed to verifyBundleStandalone().
- *     Behaviour, including --public-key / --kid, is identical to verify-bundle.
- *   - TIMESTAMP (optional, additive): the record-level `timestamp.token` (or a
- *     bundle-embedded timestamp) is verified via the same resolveTimestampResult()
- *     path used by verify-bundle. It NEVER affects integrity, signature, or the
- *     exit code, and the ASN.1 stack loads only behind --verify-timestamp.
+ * Verify an already-parsed CER record (or bare bundle) object and render the
+ * audit-grade report. This is the shared core behind `verify-record` (file / stdin)
+ * and `verify-url` (network), so key resolution, timestamp verification, and the rich
+ * renderer behave identically across all input sources.
  */
-export async function verifyRecordStandaloneCommand(file, opts) {
-    let record;
-    try {
-        record = JSON.parse(fs.readFileSync(file, 'utf-8'));
-    }
-    catch (err) {
-        console.error(`[nexart] Error: could not read record "${file}": ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
+export async function verifyRecordFromObject(record, opts) {
+    const rec = (record && typeof record === 'object') ? record : {};
+    // FLEXIBLE PARSING: accept either { bundle, verification?, timestamp? } or a bare
+    // bundle as the record root. No "missing bundle" error — a structurally invalid
+    // record falls through to a clean Integrity FAIL from the verifier.
+    const bundleObj = rec.bundle && typeof rec.bundle === 'object'
+        ? rec.bundle
+        : rec;
+    // Merge the record's signed receipt into a SHALLOW copy of the bundle so the
+    // existing verifier finds it. This never mutates the original and never changes the
+    // recomputed certificateHash (receipt/signature are not part of the cert payload).
+    const verification = rec.verification && typeof rec.verification === 'object' ? rec.verification : undefined;
+    const recReceipt = verification?.receipt;
+    const receiptSignature = verification?.receiptSignature;
+    const verifyInput = { ...bundleObj };
+    if (recReceipt && typeof recReceipt === 'object' && typeof receiptSignature === 'string') {
+        verifyInput.receipt = recReceipt;
+        verifyInput.signature = receiptSignature;
     }
+    // Receipt used for display + key selection: prefer the record's, else one already
+    // embedded in the bundle (root-as-bundle / certified bundles).
+    const receiptObj = (recReceipt && typeof recReceipt === 'object' ? recReceipt : undefined) ??
+        (bundleObj.receipt && typeof bundleObj.receipt === 'object' ? bundleObj.receipt : undefined);
+    const attestorKeyId = opts.kid ??
+        (typeof receiptObj?.attestorKeyId === 'string' ? receiptObj.attestorKeyId : undefined);
+    // ── Resolve the signing public key (priority: override → well-known → embedded) ──
     let publicKeyMaterial;
+    let keySource = 'none';
+    let nodeMeta = {};
     if (opts.publicKey) {
         try {
             publicKeyMaterial = fs.readFileSync(opts.publicKey, 'utf-8');
+            keySource = 'override';
         }
         catch (err) {
             console.error(`[nexart] Error: could not read public key "${opts.publicKey}": ${err instanceof Error ? err.message : String(err)}`);
             process.exit(1);
         }
     }
-    const rec = (record && typeof record === 'object') ? record : {};
-    const bundleObj = rec.bundle && typeof rec.bundle === 'object' ? rec.bundle : undefined;
-    if (!bundleObj) {
-        // Malformed record: surface a clear reason but DO NOT crash the process — fall
-        // through to the standalone verifier, which reports a clean integrity FAIL.
-        console.error('[nexart] Error: record is missing a "bundle" object');
-    }
-    // Merge the record's signed receipt into a SHALLOW copy of the bundle so the
-    // existing verifier finds it. This never mutates the original and never changes the
-    // recomputed certificateHash (receipt/signature are not part of the cert payload).
-    const verification = rec.verification && typeof rec.verification === 'object' ? rec.verification : undefined;
-    const receipt = verification?.receipt;
-    const receiptSignature = verification?.receiptSignature;
-    const verifyInput = { ...bundleObj };
-    if (receipt && typeof receipt === 'object' && typeof receiptSignature === 'string') {
-        verifyInput.receipt = receipt;
-        verifyInput.signature = receiptSignature;
+    else if (!opts.offline) {
+        const url = opts.wellKnownUrl ?? process.env.NEXART_NODE_WELLKNOWN_URL ?? DEFAULT_WELLKNOWN_URL;
+        const doc = await fetchNodeKeysDocument(url);
+        if (doc) {
+            // Only commit to the well-known document if it can actually yield a usable key
+            // for the target kid. resolvePublicKey is pure (node:crypto, no network); if it
+            // throws (malformed doc, or no key matching attestorKeyId), fall through to any
+            // bundle-embedded key, preserving the priority override > well-known > embedded.
+            try {
+                resolvePublicKey(doc.text, attestorKeyId);
+                publicKeyMaterial = doc.text;
+                keySource = 'well-known';
+                nodeMeta = { nodeId: doc.nodeId, operator: doc.operator };
+            }
+            catch {
+                keySource = 'well-known-unusable';
+            }
+        }
+        else {
+            keySource = 'well-known-unreachable';
+        }
     }
-    const result = verifyBundleStandalone(bundleObj ? verifyInput : undefined, {
+    const result = verifyBundleStandalone(verifyInput, {
         publicKeyMaterial,
-        kid: opts.kid,
+        kid: attestorKeyId,
         verbose: opts.verbose,
     });
-    // Locate the timestamp for the additive layer. The record-level `timestamp`
-    // (singular) takes precedence; otherwise fall back to a bundle-embedded one. The
-    // certificateHash / createdAt the verifier needs always come from the bundle.
-    const tsLocatorInput = rec.timestamp !== undefined
-        ? { certificateHash: bundleObj?.certificateHash, createdAt: bundleObj?.createdAt, timestamp: rec.timestamp }
-        : {
-            certificateHash: bundleObj?.certificateHash,
-            createdAt: bundleObj?.createdAt,
-            timestamp: bundleObj?.timestamp,
-            trustedTimestamps: bundleObj?.trustedTimestamps,
-        };
-    const maybeTsa = resolveTimestampResult(evaluateBundleTimestamp(tsLocatorInput), opts);
+    // If no override / well-known key was used but the signature still verified, the
+    // verifier must have used key material embedded in the bundle.
+    if ((keySource === 'none' || keySource === 'well-known-unreachable' || keySource === 'well-known-unusable') &&
+        result.signature !== 'skipped') {
+        keySource = 'embedded';
+    }
+    // Locate the timestamp. Precedence: record.verification.timestamp →
+    // record.timestamp → bundle-embedded. certificateHash / createdAt always come from
+    // the bundle (they are what the RFC 3161 imprint is verified against).
+    const recVerTimestamp = verification && verification.timestamp !== undefined ? verification.timestamp : undefined;
+    const tsLocatorInput = recVerTimestamp !== undefined
+        ? { certificateHash: bundleObj.certificateHash, createdAt: bundleObj.createdAt, timestamp: recVerTimestamp }
+        : rec.timestamp !== undefined
+            ? { certificateHash: bundleObj.certificateHash, createdAt: bundleObj.createdAt, timestamp: rec.timestamp }
+            : {
+                certificateHash: bundleObj.certificateHash,
+                createdAt: bundleObj.createdAt,
+                timestamp: bundleObj.timestamp,
+                trustedTimestamps: bundleObj.trustedTimestamps,
+            };
+    const maybeTsa = resolveTimestampResult(evaluateBundleTimestamp(tsLocatorInput), {
+        auto: true,
+        tsaRoots: opts.tsaRoots,
+        defaultRootsPem: DIGICERT_DEFAULT_ROOTS_PEM,
+    });
     const tsaResult = maybeTsa instanceof Promise ? await maybeTsa : maybeTsa;
-    renderStandaloneVerification(result, tsaResult, opts);
+    renderRecordVerification(result, tsaResult, {
+        bundle: bundleObj,
+        receipt: receiptObj,
+        keySource,
+        nodeMeta,
+        opts,
+    });
     // Exit code is determined SOLELY by integrity + signature — never by the timestamp.
     process.exitCode = result.status === 'verified' ? 0 : 1;
     return result;
 }
+/**
+ * Read JSON from a file path, or from stdin when `file` is "-". A read or parse error
+ * prints a clean message and exits 1 (never throws an uncaught error). Used by both
+ * `verify-record <file|->` and any other command that accepts piped JSON.
+ */
+function readJsonInput(file, label) {
+    let raw;
+    try {
+        raw = file === '-' ? fs.readFileSync(0, 'utf-8') : fs.readFileSync(file, 'utf-8');
+    }
+    catch (err) {
+        const src = file === '-' ? 'stdin' : `"${file}"`;
+        console.error(`[nexart] Error: could not read ${label} from ${src}: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const src = file === '-' ? 'stdin' : `"${file}"`;
+        console.error(`[nexart] Error: ${label} from ${src} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+}
+/**
+ * nexart verify-url — Fetch a CER record (or bare bundle) from a URL and verify it
+ * automatically, using the SAME rich renderer and key/timestamp resolution as
+ * `verify-record`. The single network fetch here is the record SOURCE; `--offline`
+ * still disables the (separate) signing-key auto-fetch, exactly as for verify-record.
+ */
+export async function verifyUrlCommand(url, opts) {
+    let text;
+    try {
+        const res = await fetch(url, { headers: { accept: 'application/json' } });
+        if (!res.ok) {
+            console.error(`[nexart] Error: could not fetch "${url}": HTTP ${res.status} ${res.statusText}`.trimEnd());
+            process.exit(1);
+        }
+        text = await res.text();
+    }
+    catch (err) {
+        console.error(`[nexart] Error: could not fetch "${url}": ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    let record;
+    try {
+        record = JSON.parse(text);
+    }
+    catch (err) {
+        console.error(`[nexart] Error: response from "${url}" is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    // Detect the payload shape for an informational line. Both a full record and a bare
+    // bundle route through the same rich verifier (which natively accepts either).
+    if (!opts.json && !opts.short) {
+        console.log(`Fetched ${detectRecordShape(record)} from ${url}`);
+        console.log('');
+    }
+    return verifyRecordFromObject(record, opts);
+}
+/** Classify a fetched payload as a full verification record or a bare bundle. */
+function detectRecordShape(record) {
+    if (record && typeof record === 'object') {
+        const r = record;
+        const v = r.verification;
+        if (v && typeof v === 'object' && v.receipt)
+            return 'full record';
+    }
+    return 'raw bundle';
+}
+/** Base URL for the public CER lookup endpoint resolved by `verify-hash <certificate_hash>`. */
+const PUBLIC_CER_ENDPOINT = 'https://node.nexart.io/v1/cer/public';
+/**
+ * nexart verify-hash — Resolve a certificate hash to its public CER record URL and verify it.
+ * This is a thin convenience wrapper over `verify-url`: it constructs
+ * `${PUBLIC_CER_ENDPOINT}?certificate_hash=<hash>` and delegates, so the output is
+ * identical to `verify-url`. The hash must carry the canonical `sha256:` prefix.
+ */
+export async function verifyHashCommand(certificateHash, opts) {
+    if (typeof certificateHash !== 'string' || !certificateHash.startsWith('sha256:')) {
+        console.error(`[nexart] Error: certificate hash must start with "sha256:" (got "${certificateHash}")`);
+        process.exit(1);
+    }
+    const url = `${PUBLIC_CER_ENDPOINT}?certificate_hash=${encodeURIComponent(certificateHash)}`;
+    return verifyUrlCommand(url, opts);
+}
+/** Default location of the node's published Ed25519 signing key set. */
+const DEFAULT_WELLKNOWN_URL = 'https://node.nexart.io/.well-known/nexart-node.json';
+/**
+ * Fetch the node's published key set (a NodeKeysDocument) over HTTPS. This is the ONLY
+ * network call in the verify path and lives entirely in the CLI layer — the auditable
+ * core (standaloneVerify.ts) never touches the network. Failure is graceful: any
+ * network/HTTP/timeout error returns `undefined`, and verification falls back to an
+ * explicit --public-key, an embedded key, or a skipped signature. It never throws.
+ */
+async function fetchNodeKeysDocument(url, timeoutMs = 8000) {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        try {
+            res = await fetch(url, { signal: controller.signal, headers: { accept: 'application/json' } });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok)
+            return undefined;
+        const text = await res.text();
+        let nodeId;
+        let operator;
+        try {
+            const j = JSON.parse(text);
+            if (typeof j.nodeId === 'string')
+                nodeId = j.nodeId;
+            if (typeof j.operator === 'string')
+                operator = j.operator;
+        }
+        catch {
+            // Not JSON we can summarise; resolvePublicKey will surface any real problem.
+        }
+        return { text, nodeId, operator };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Human-readable label for the Node info "Key source" line. */
+function keySourceLabel(source) {
+    switch (source) {
+        case 'override':
+            return 'supplied via --public-key';
+        case 'well-known':
+            return 'node.nexart.io (.well-known)';
+        case 'well-known-unreachable':
+            return 'unavailable (.well-known unreachable)';
+        case 'well-known-unusable':
+            return 'unavailable (.well-known has no matching key)';
+        case 'embedded':
+            return 'embedded in bundle';
+        case 'none':
+        default:
+            return 'none';
+    }
+}
+/**
+ * Map an RFC 3161 verification status to the verify-record timestamp headline
+ * (VERIFIED / INVALID (<reason>) / NOT INCLUDED). Distinct from formatTimestampLine()
+ * (verify-bundle), whose "Externally anchored timestamp: …" wording is unchanged.
+ */
+function formatRecordTimestampLine(status) {
+    const CHECK = '\u2714';
+    const CROSS = '\u2716';
+    const CIRCLE = '\u25CB';
+    switch (status) {
+        case 'valid':
+            return `${CHECK} Timestamp: VERIFIED`;
+        case 'invalid-signature':
+            return `${CROSS} Timestamp: INVALID (signature)`;
+        case 'invalid-imprint':
+            return `${CROSS} Timestamp: INVALID (imprint mismatch)`;
+        case 'untrusted-root':
+            return `${CROSS} Timestamp: INVALID (untrusted root)`;
+        case 'expired':
+            return `${CROSS} Timestamp: INVALID (expired)`;
+        case 'invalid-time':
+            return `${CROSS} Timestamp: INVALID (time)`;
+        case 'malformed':
+            return `${CROSS} Timestamp: INVALID (malformed token)`;
+        case 'present-unverified':
+            return `${CIRCLE} Timestamp: PRESENT BUT NOT VERIFIED`;
+        case 'not-present':
+        default:
+            return `${CIRCLE} Timestamp: NOT INCLUDED IN RECORD`;
+    }
+}
+/**
+ * Render the redesigned, audit-grade verify-record report (default human-readable, or
+ * --json). Sections: Integrity, Signature, Timestamp, Node, Identity, Execution. This
+ * is verify-record ONLY — renderStandaloneVerification (verify-bundle) is untouched.
+ */
+function renderRecordVerification(result, tsaResult, ctx) {
+    const snapshot = ctx.bundle.snapshot && typeof ctx.bundle.snapshot === 'object'
+        ? ctx.bundle.snapshot
+        : undefined;
+    const identity = snapshot?.identity && typeof snapshot.identity === 'object'
+        ? snapshot.identity
+        : undefined;
+    const params = snapshot?.parameters && typeof snapshot.parameters === 'object'
+        ? snapshot.parameters
+        : undefined;
+    const str = (v) => (typeof v === 'string' ? v : undefined);
+    const nodeId = ctx.nodeMeta.nodeId ?? str(ctx.receipt?.nodeId);
+    const keyId = str(ctx.receipt?.attestorKeyId);
+    const genTimeIso = tsaResult.genTime ? tsaResult.genTime.replace(/\.\d{3}Z$/, 'Z') : undefined;
+    if (ctx.opts.json) {
+        process.stdout.write(JSON.stringify({
+            status: result.status,
+            integrity: result.integrity,
+            signature: result.signature,
+            protocolVersion: result.protocolVersion,
+            certificateHash: result.expectedCertificateHash,
+            timestamp: {
+                status: tsaResult.status,
+                ...(tsaResult.tsa ? { tsa: tsaResult.tsa } : {}),
+                ...(genTimeIso ? { genTime: genTimeIso } : {}),
+                ...(tsaResult.reason ? { reason: tsaResult.reason } : {}),
+            },
+            node: {
+                ...(nodeId ? { nodeId } : {}),
+                ...(keyId ? { keyId } : {}),
+                keySource: ctx.keySource,
+                ...(ctx.nodeMeta.operator ? { operator: ctx.nodeMeta.operator } : {}),
+            },
+            identity: identity ?? null,
+            execution: {
+                ...(str(snapshot?.provider) ? { provider: str(snapshot?.provider) } : {}),
+                ...(str(snapshot?.model) ? { model: str(snapshot?.model) } : {}),
+                ...(str(snapshot?.inputHash) ? { inputHash: str(snapshot?.inputHash) } : {}),
+                ...(str(snapshot?.outputHash) ? { outputHash: str(snapshot?.outputHash) } : {}),
+                ...(params ? { parameters: params } : {}),
+                ...(str(ctx.bundle.createdAt) ? { createdAt: str(ctx.bundle.createdAt) } : {}),
+            },
+            reasons: result.reasons,
+        }, null, 2) + '\n');
+        return;
+    }
+    const mark = (p) => p === 'pass' ? '\u2714' : p === 'fail' ? '\u2716' : '\u25CB';
+    const label = (p) => p.toUpperCase();
+    // --short: a single machine-glanceable verdict line, nothing else.
+    if (ctx.opts.short) {
+        console.log(result.status === 'verified' ? '\u2714 VERIFIED' : '\u2716 FAILED');
+        return;
+    }
+    if (ctx.opts.verbose && result.steps.length > 0) {
+        console.log('Verification steps:');
+        for (const s of result.steps)
+            console.log(`  - ${s}`);
+        console.log('');
+    }
+    // ── Verdict block ──
+    console.log(`${mark(result.integrity)} Integrity: ${label(result.integrity)}`);
+    console.log(`${mark(result.signature)} Signature: ${label(result.signature)}`);
+    console.log(formatRecordTimestampLine(tsaResult.status));
+    if (tsaResult.status !== 'not-present' && genTimeIso) {
+        console.log(`  Time:      ${genTimeIso}`);
+        console.log(`  Authority: ${deriveTsaProvider(tsaResult.tsa)}`);
+    }
+    // ── Node info ──
+    console.log('');
+    console.log('Node');
+    console.log(`  Node ID:    ${nodeId ?? '(unknown)'}`);
+    console.log(`  Key ID:     ${keyId ?? '(unknown)'}`);
+    console.log(`  Key source: ${keySourceLabel(ctx.keySource)}`);
+    if (ctx.nodeMeta.operator)
+        console.log(`  Operator:   ${ctx.nodeMeta.operator}`);
+    // ── Identity summary ──
+    console.log('');
+    console.log('Identity');
+    if (identity) {
+        for (const [k, v] of Object.entries(identity)) {
+            console.log(`  ${k}: ${typeof v === 'object' ? JSON.stringify(v) : String(v)}`);
+        }
+    }
+    else {
+        console.log('  (none asserted)');
+    }
+    // ── Execution summary ──
+    console.log('');
+    console.log('Execution');
+    console.log(`  Protocol:   ${result.protocolVersion}`);
+    if (str(snapshot?.provider))
+        console.log(`  Provider:   ${str(snapshot?.provider)}`);
+    if (str(snapshot?.model))
+        console.log(`  Model:      ${str(snapshot?.model)}`);
+    if (str(snapshot?.inputHash))
+        console.log(`  Input:      ${str(snapshot?.inputHash)}`);
+    if (str(snapshot?.outputHash))
+        console.log(`  Output:     ${str(snapshot?.outputHash)}`);
+    if (params) {
+        const pretty = Object.entries(params)
+            .map(([k, v]) => `${k}=${typeof v === 'object' ? JSON.stringify(v) : String(v)}`)
+            .join(', ');
+        if (pretty)
+            console.log(`  Parameters: ${pretty}`);
+    }
+    if (str(ctx.bundle.createdAt))
+        console.log(`  Created:    ${str(ctx.bundle.createdAt)}`);
+    // ── Final verdict line ──
+    console.log('');
+    console.log(result.status === 'verified'
+        ? 'FINAL STATUS: VERIFIED EVIDENCE RECORD'
+        : 'FINAL STATUS: FAILED');
+    // ── Failure reasons (stderr) ──
+    if (result.status === 'failed' || result.reasons.length > 0) {
+        for (const r of result.reasons)
+            console.error(`  ! ${r}`);
+    }
+    if (ctx.opts.verbose && tsaResult.reason && tsaResult.status !== 'valid') {
+        console.error(`  ! Timestamp: ${tsaResult.reason}`);
+    }
+}
 /**
  * Locate an RFC 3161 timestamp in a CER bundle WITHOUT mutating it. Supports both
  * the canonical `trustedTimestamps[]` array (each { type:'rfc3161', tsa, timestamp,
@@ -2170,50 +2518,166 @@ if (_isMainModule) {
             tsaRoots: argv['tsa-roots'],
         });
     })
-        .command('verify-record <file>', 'Verify a full CER record (bundle + signature + externally anchored timestamp) offline', (yargs) => {
+        .command('verify-record <file>', 'Verify a full CER record automatically: integrity, receipt signature, and RFC 3161 timestamp', (yargs) => {
         return yargs
             .positional('file', {
-            describe: 'Path to the CER record JSON file ({ bundle, verification, timestamp? })',
+            describe: 'Path to the CER record JSON, or "-" to read it from stdin ({ bundle, verification?, timestamp? } or a bare bundle)',
             type: 'string',
             demandOption: true,
         })
             .option('public-key', {
-            describe: 'Path to the Ed25519 public key (PEM, JWK, NodeKeysDocument, or raw base64url)',
+            describe: 'Override the signing key (PEM, JWK, NodeKeysDocument, or raw base64url). Default: auto-fetched from the node .well-known key set',
             type: 'string',
+        })
+            .option('offline', {
+            describe: 'Do not contact the network; use --public-key or a bundle-embedded key only',
+            type: 'boolean',
+            default: false,
         })
             .option('kid', {
-            describe: 'Key id to select when --public-key is a NodeKeysDocument',
+            describe: 'Key id to select from the key set (default: the receipt attestorKeyId)',
             type: 'string',
         })
             .option('json', {
             describe: 'Output machine-readable JSON',
             type: 'boolean',
             default: false,
+        })
+            .option('short', {
+            describe: 'Print only a single verdict line (✔ VERIFIED / ✖ FAILED)',
+            type: 'boolean',
+            default: false,
         })
             .option('verbose', {
             describe: 'Show intermediate verification steps',
             type: 'boolean',
             default: false,
         })
-            .option('verify-timestamp', {
-            describe: 'Additionally verify the externally anchored RFC 3161 timestamp (offline; never affects the exit code)',
+            .option('tsa-roots', {
+            describe: 'Override the default DigiCert TSA trust roots with custom root certificate(s) (PEM)',
+            type: 'string',
+        })
+            .example('$0 verify-record record.json', 'Full automatic verification (auto-fetch key, verify timestamp)')
+            .example('$0 verify-record record.json --json', 'Machine-readable verification report')
+            .example('curl -s https://node/record.json | $0 verify-record -', 'Verify a record piped from stdin')
+            .example('$0 verify-record record.json --offline --public-key node-keys.json', 'Fully offline verification with an explicit key');
+    }, async (argv) => {
+        // yargs-parser collapses a bare "-" positional to an empty string; restore the
+        // stdin sentinel so `verify-record -` reads the record from stdin.
+        const file = argv.file === '' ? '-' : argv.file;
+        await verifyRecordStandaloneCommand(file, {
+            publicKey: argv['public-key'],
+            kid: argv.kid,
+            json: argv.json,
+            short: argv.short,
+            verbose: argv.verbose,
+            offline: argv.offline,
+            tsaRoots: argv['tsa-roots'],
+        });
+    })
+        .command('verify-hash <certificate_hash>', 'Resolve a certificate hash to its public CER record and verify it — one-command verification', (yargs) => {
+        return yargs
+            .positional('certificate_hash', {
+            describe: 'CER certificate hash (must include the "sha256:" prefix)',
+            type: 'string',
+            demandOption: true,
+        })
+            .option('public-key', {
+            describe: 'Override the signing key (PEM, JWK, NodeKeysDocument, or raw base64url). Default: auto-fetched from the node .well-known key set',
+            type: 'string',
+        })
+            .option('offline', {
+            describe: 'Do not auto-fetch the signing key (the record itself is still fetched); use --public-key or a bundle-embedded key only',
+            type: 'boolean',
+            default: false,
+        })
+            .option('kid', {
+            describe: 'Key id to select from the key set (default: the receipt attestorKeyId)',
+            type: 'string',
+        })
+            .option('json', {
+            describe: 'Output machine-readable JSON',
+            type: 'boolean',
+            default: false,
+        })
+            .option('short', {
+            describe: 'Print only a single verdict line (✔ VERIFIED / ✖ FAILED)',
+            type: 'boolean',
+            default: false,
+        })
+            .option('verbose', {
+            describe: 'Show intermediate verification steps',
             type: 'boolean',
             default: false,
         })
             .option('tsa-roots', {
-            describe: 'Path to trusted TSA root certificate(s) (PEM) for --verify-timestamp',
+            describe: 'Override the default DigiCert TSA trust roots with custom root certificate(s) (PEM)',
             type: 'string',
         })
-            .example('$0 verify-record record.json', 'Verify the bundle integrity offline')
-            .example('$0 verify-record record.json --public-key node-keys.json', 'Verify integrity and the receipt signature')
-            .example('$0 verify-record record.json --public-key node-keys.json --verify-timestamp --tsa-roots tsa-roots.pem', 'Full CER + externally anchored timestamp verification');
+            .example('$0 verify-hash sha256:abc123…', 'Resolve and fully verify a record by certificate hash')
+            .example('$0 verify-hash sha256:abc123… --short', 'One-line PASS/FAIL verdict')
+            .example('$0 verify-hash sha256:abc123… --json', 'Machine-readable verification report');
     }, async (argv) => {
-        await verifyRecordStandaloneCommand(argv.file, {
+        await verifyHashCommand(argv.certificate_hash, {
             publicKey: argv['public-key'],
             kid: argv.kid,
             json: argv.json,
+            short: argv.short,
             verbose: argv.verbose,
-            verifyTimestamp: argv['verify-timestamp'],
+            offline: argv.offline,
+            tsaRoots: argv['tsa-roots'],
+        });
+    })
+        .command('verify-url <url>', 'Fetch a CER record (or bundle) from a URL and verify it automatically — one-command verification', (yargs) => {
+        return yargs
+            .positional('url', {
+            describe: 'URL returning a CER record or bundle as JSON',
+            type: 'string',
+            demandOption: true,
+        })
+            .option('public-key', {
+            describe: 'Override the signing key (PEM, JWK, NodeKeysDocument, or raw base64url). Default: auto-fetched from the node .well-known key set',
+            type: 'string',
+        })
+            .option('offline', {
+            describe: 'Do not auto-fetch the signing key (the record URL itself is still fetched); use --public-key or a bundle-embedded key only',
+            type: 'boolean',
+            default: false,
+        })
+            .option('kid', {
+            describe: 'Key id to select from the key set (default: the receipt attestorKeyId)',
+            type: 'string',
+        })
+            .option('json', {
+            describe: 'Output machine-readable JSON',
+            type: 'boolean',
+            default: false,
+        })
+            .option('short', {
+            describe: 'Print only a single verdict line (✔ VERIFIED / ✖ FAILED)',
+            type: 'boolean',
+            default: false,
+        })
+            .option('verbose', {
+            describe: 'Show intermediate verification steps',
+            type: 'boolean',
+            default: false,
+        })
+            .option('tsa-roots', {
+            describe: 'Override the default DigiCert TSA trust roots with custom root certificate(s) (PEM)',
+            type: 'string',
+        })
+            .example('$0 verify-url https://node.example/records/abc.json', 'Fetch and fully verify a record')
+            .example('$0 verify-url https://node.example/records/abc.json --short', 'One-line PASS/FAIL verdict')
+            .example('$0 verify-url https://node.example/records/abc.json --json', 'Machine-readable verification report');
+    }, async (argv) => {
+        await verifyUrlCommand(argv.url, {
+            publicKey: argv['public-key'],
+            kid: argv.kid,
+            json: argv.json,
+            short: argv.short,
+            verbose: argv.verbose,
+            offline: argv.offline,
             tsaRoots: argv['tsa-roots'],
         });
     })