@nexart/cli 0.12.2 → 0.15.0

package/dist/index.js

@@ -1345,7 +1345,7 @@ export async function exportVerificationCommand(file, opts, stdinReader = readSt
  * NOTE: named `verify-bundle` (not `verify`) because `nexart verify <snapshot>`
  * already exists for Code Mode snapshots and must not change (additive only).
  */
-export function verifyBundleStandaloneCommand(file, opts) {
+export async function verifyBundleStandaloneCommand(file, opts) {
     let bundle;
     try {
         bundle = JSON.parse(fs.readFileSync(file, 'utf-8'));
@@ -1369,34 +1369,304 @@ export function verifyBundleStandaloneCommand(file, opts) {
         kid: opts.kid,
         verbose: opts.verbose,
     });
+    // ── OPTIONAL, ADDITIVE: RFC 3161 timestamp verification ──────────────────────
+    // Strictly additive: this NEVER alters integrity, signature, status, or the exit
+    // code, and the heavy ASN.1 stack is only imported when --verify-timestamp is set.
+    // resolveTimestampResult stays synchronous unless it actually verifies a token, so
+    // a timestamp-less bundle never introduces an await (preserving prior sync behavior).
+    const maybeTsa = resolveTimestampResult(evaluateBundleTimestamp(bundle), opts);
+    const tsaResult = maybeTsa instanceof Promise ? await maybeTsa : maybeTsa;
+    renderStandaloneVerification(result, tsaResult, opts);
+    // Exit code is determined SOLELY by integrity + signature — never by the timestamp.
+    process.exitCode = result.status === 'verified' ? 0 : 1;
+    return result;
+}
+/**
+ * Resolve the (strictly additive) RFC 3161 timestamp status for an already-located
+ * timestamp. Shared by `verify-bundle` and `verify-record`. Every operational failure
+ * is mapped to a timestamp STATUS — never to process.exit or a thrown error — so the
+ * timestamp layer can never influence the exit code. The ASN.1 stack (pkijs/asn1js)
+ * is dynamically imported ONLY when --verify-timestamp is set and a token is present.
+ *
+ * Returns SYNCHRONOUSLY for every non-verify path (not-present / present-unverified /
+ * unreadable-roots) and only returns a Promise when it actually has async work to do
+ * (the dynamic import + verification). This mirrors the original verify-bundle control
+ * flow exactly — where the sole `await` lived behind `present && --verify-timestamp` —
+ * so timestamp-less bundles stay fully synchronous (callers must handle both shapes).
+ */
+function resolveTimestampResult(timestampInfo, opts) {
+    if (!timestampInfo.present)
+        return { status: 'not-present' };
+    if (!opts.verifyTimestamp)
+        return { status: 'present-unverified' };
+    let trustedRootsPem;
+    if (opts.tsaRoots) {
+        try {
+            trustedRootsPem = fs.readFileSync(opts.tsaRoots, 'utf-8');
+        }
+        catch (err) {
+            return {
+                status: 'untrusted-root',
+                reason: `could not read TSA roots "${opts.tsaRoots}": ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    return (async () => {
+        try {
+            const { verifyRfc3161Timestamp } = await import('./tsaVerify.js');
+            return await verifyRfc3161Timestamp({
+                token: timestampInfo.token,
+                certificateHash: timestampInfo.certificateHash ?? '',
+                createdAt: timestampInfo.createdAt,
+                trustedRootsPem,
+            });
+        }
+        catch (err) {
+            return { status: 'malformed', reason: err instanceof Error ? err.message : String(err) };
+        }
+    })();
+}
+/**
+ * Render a standalone verification result plus its (additive) timestamp status, in
+ * either the human-readable or --json form. Shared by `verify-bundle` and
+ * `verify-record` so the two commands are byte-for-byte identical in output. This
+ * never sets the exit code — that stays a function of integrity + signature alone.
+ */
+function renderStandaloneVerification(result, tsaResult, opts) {
     if (opts.json) {
         process.stdout.write(JSON.stringify({
             status: result.status,
             integrity: result.integrity,
             signature: result.signature,
             protocolVersion: result.protocolVersion,
+            timestamp: {
+                status: tsaResult.status,
+                ...(tsaResult.tsa ? { tsa: tsaResult.tsa } : {}),
+                ...(tsaResult.genTime ? { genTime: tsaResult.genTime } : {}),
+                ...(tsaResult.reason ? { reason: tsaResult.reason } : {}),
+            },
         }, null, 2) + '\n');
+        return;
+    }
+    const mark = (p) => p === 'pass' ? '\u2714' : p === 'fail' ? '\u2716' : '\u25CB';
+    const label = (p) => p.toUpperCase();
+    if (opts.verbose && result.steps.length > 0) {
+        console.log('Verification steps:');
+        for (const s of result.steps)
+            console.log(`  - ${s}`);
+        console.log('');
     }
-    else {
-        const mark = (p) => p === 'pass' ? '\u2714' : p === 'fail' ? '\u2716' : '\u25CB';
-        const label = (p) => p.toUpperCase();
-        if (opts.verbose && result.steps.length > 0) {
-            console.log('Verification steps:');
-            for (const s of result.steps)
-                console.log(`  - ${s}`);
-            console.log('');
+    console.log(`${mark(result.integrity)} Integrity: ${label(result.integrity)}`);
+    console.log(`${mark(result.signature)} Signature: ${label(result.signature)}`);
+    console.log(`Protocol: ${result.protocolVersion}`);
+    console.log(formatTimestampLine(tsaResult.status));
+    const tsDetails = formatTimestampDetails(tsaResult);
+    if (tsDetails.length > 0) {
+        console.log('');
+        console.log('Timestamp Details:');
+        for (const d of tsDetails)
+            console.log(`  ${d}`);
+    }
+    if (result.status === 'failed' || result.reasons.length > 0) {
+        for (const r of result.reasons)
+            console.error(`  ! ${r}`);
+    }
+    if (opts.verbose && tsaResult.reason && tsaResult.status !== 'valid') {
+        console.error(`  ! Timestamp: ${tsaResult.reason}`);
+    }
+}
+/**
+ * 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.
+ */
+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);
+    }
+    let publicKeyMaterial;
+    if (opts.publicKey) {
+        try {
+            publicKeyMaterial = fs.readFileSync(opts.publicKey, 'utf-8');
         }
-        console.log(`${mark(result.integrity)} Integrity: ${label(result.integrity)}`);
-        console.log(`${mark(result.signature)} Signature: ${label(result.signature)}`);
-        console.log(`Protocol: ${result.protocolVersion}`);
-        if (result.status === 'failed' || result.reasons.length > 0) {
-            for (const r of result.reasons)
-                console.error(`  ! ${r}`);
+        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;
+    }
+    const result = verifyBundleStandalone(bundleObj ? verifyInput : undefined, {
+        publicKeyMaterial,
+        kid: opts.kid,
+        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);
+    const tsaResult = maybeTsa instanceof Promise ? await maybeTsa : maybeTsa;
+    renderStandaloneVerification(result, tsaResult, opts);
+    // Exit code is determined SOLELY by integrity + signature — never by the timestamp.
     process.exitCode = result.status === 'verified' ? 0 : 1;
     return result;
 }
+/**
+ * Locate an RFC 3161 timestamp in a CER bundle WITHOUT mutating it. Supports both
+ * the canonical `trustedTimestamps[]` array (each { type:'rfc3161', tsa, timestamp,
+ * token }) and a singular `timestamp` object. Returns the base64 token plus the
+ * certificateHash/createdAt needed to verify it. Reading this never affects any
+ * other verification result.
+ */
+function evaluateBundleTimestamp(bundle) {
+    if (!bundle || typeof bundle !== 'object')
+        return { present: false };
+    const b = bundle;
+    const certificateHash = typeof b.certificateHash === 'string' ? b.certificateHash : undefined;
+    const createdAt = typeof b.createdAt === 'string' ? b.createdAt : undefined;
+    let token;
+    const arr = b.trustedTimestamps;
+    if (Array.isArray(arr)) {
+        const entry = arr.find((e) => e && typeof e === 'object' && e.type === 'rfc3161' && typeof e.token === 'string');
+        if (entry)
+            token = entry.token;
+    }
+    if (!token && b.timestamp && typeof b.timestamp === 'object') {
+        const t = b.timestamp;
+        if (typeof t.token === 'string')
+            token = t.token;
+    }
+    return token ? { present: true, token, certificateHash, createdAt } : { present: false };
+}
+/**
+ * Render the human-readable timestamp STATUS line WITHOUT importing the ASN.1 stack.
+ * This deliberately mirrors formatTsaLine() in tsaVerify.ts but lives here so the
+ * present-unverified / not-present paths never load pkijs (non-negotiable: ASN.1
+ * libs are only loaded behind --verify-timestamp). The wording — "Externally
+ * anchored timestamp" — reflects that we are proving anchoring to an INDEPENDENT
+ * authority, not running an internal check. Provider/time/imprint are surfaced
+ * separately in the Timestamp Details block (formatTimestampDetails).
+ */
+export function formatTimestampLine(status) {
+    const CHECK = '\u2714';
+    const CROSS = '\u2716';
+    const CIRCLE = '\u25CB';
+    switch (status) {
+        case 'valid':
+            return `${CHECK} Externally anchored timestamp: valid`;
+        case 'invalid-signature':
+            return `${CROSS} Externally anchored timestamp: invalid (signature)`;
+        case 'invalid-imprint':
+            return `${CROSS} Externally anchored timestamp: invalid (imprint mismatch)`;
+        case 'untrusted-root':
+            return `${CROSS} Externally anchored timestamp: untrusted (unknown root)`;
+        case 'expired':
+            return `${CROSS} Externally anchored timestamp: invalid (expired)`;
+        case 'invalid-time':
+            return `${CROSS} Externally anchored timestamp: invalid (time)`;
+        case 'malformed':
+            return `${CROSS} Externally anchored timestamp: invalid (malformed token)`;
+        case 'present-unverified':
+            return `${CIRCLE} Externally anchored timestamp: present (not verified)`;
+        case 'not-present':
+        default:
+            return `${CIRCLE} Externally anchored timestamp: not present`;
+    }
+}
+/**
+ * Build the "Timestamp Details" block lines (Provider / Time / Imprint). Returns an
+ * empty array when no verification was attempted (flag absent → present-unverified,
+ * or no token → not-present), so the block only appears for an actually-verified
+ * token. Pure string logic — no ASN.1 import. The imprint state is INFERRED from the
+ * status: the verifier checks signature → imprint → trust → validity → time in that
+ * order, so any status at or past the trust stage implies the imprint already matched.
+ */
+function formatTimestampDetails(result) {
+    if (result.status === 'present-unverified' || result.status === 'not-present')
+        return [];
+    // No genTime ⇒ the token was never parsed (operational error such as an unreadable
+    // --tsa-roots, or a malformed token). There is nothing meaningful to show, and in
+    // particular the imprint was NOT checked — so suppress the block entirely.
+    if (!result.genTime)
+        return [];
+    const time = result.genTime.replace(/\.\d{3}Z$/, 'Z');
+    return [
+        `Provider: ${deriveTsaProvider(result.tsa)}`,
+        `Time: ${time}`,
+        `Imprint: ${imprintState(result.status)}`,
+    ];
+}
+/** Map a TSA signer common name to a friendly provider label (best-effort). */
+function deriveTsaProvider(tsa) {
+    if (!tsa)
+        return 'unknown';
+    const n = tsa.toLowerCase();
+    if (n.includes('digicert'))
+        return 'DigiCert';
+    if (n.includes('freetsa') || n.includes('free tsa'))
+        return 'freeTSA';
+    if (n.includes('sectigo'))
+        return 'Sectigo';
+    if (n.includes('globalsign'))
+        return 'GlobalSign';
+    if (n.includes('apple'))
+        return 'Apple';
+    return tsa;
+}
+/** Infer imprint state from the verification status (see formatTimestampDetails). */
+function imprintState(status) {
+    switch (status) {
+        case 'valid':
+        case 'untrusted-root':
+        case 'expired':
+        case 'invalid-time':
+            return 'match';
+        case 'invalid-imprint':
+            return 'mismatch \u2716';
+        default:
+            return 'not checked';
+    }
+}
 /**
  * nexart ai project-verify — Read a cer.project.bundle.v1 JSON from file or stdin,
  * delegate all verification to verifyProjectBundle() from @nexart/ai-execution,
@@ -1876,16 +2146,75 @@ if (_isMainModule) {
             describe: 'Show intermediate verification steps',
             type: 'boolean',
             default: false,
+        })
+            .option('verify-timestamp', {
+            describe: 'Additionally verify an embedded RFC 3161 timestamp (offline; never affects the exit code)',
+            type: 'boolean',
+            default: false,
+        })
+            .option('tsa-roots', {
+            describe: 'Path to trusted TSA root certificate(s) (PEM) for --verify-timestamp',
+            type: 'string',
         })
             .example('$0 verify-bundle cer.json', 'Verify integrity offline')
             .example('$0 verify-bundle cer.json --public-key node-keys.json', 'Verify integrity and the node signature')
-            .example('$0 verify-bundle cer.json --json', 'Emit a machine-readable result');
+            .example('$0 verify-bundle cer.json --json', 'Emit a machine-readable result')
+            .example('$0 verify-bundle cer.json --verify-timestamp --tsa-roots tsa-roots.pem', 'Also verify an RFC 3161 timestamp');
+    }, async (argv) => {
+        await verifyBundleStandaloneCommand(argv.file, {
+            publicKey: argv['public-key'],
+            kid: argv.kid,
+            json: argv.json,
+            verbose: argv.verbose,
+            verifyTimestamp: argv['verify-timestamp'],
+            tsaRoots: argv['tsa-roots'],
+        });
+    })
+        .command('verify-record <file>', 'Verify a full CER record (bundle + signature + externally anchored timestamp) offline', (yargs) => {
+        return yargs
+            .positional('file', {
+            describe: 'Path to the CER record JSON file ({ bundle, verification, timestamp? })',
+            type: 'string',
+            demandOption: true,
+        })
+            .option('public-key', {
+            describe: 'Path to the Ed25519 public key (PEM, JWK, NodeKeysDocument, or raw base64url)',
+            type: 'string',
+        })
+            .option('kid', {
+            describe: 'Key id to select when --public-key is a NodeKeysDocument',
+            type: 'string',
+        })
+            .option('json', {
+            describe: 'Output machine-readable JSON',
+            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)',
+            type: 'boolean',
+            default: false,
+        })
+            .option('tsa-roots', {
+            describe: 'Path to trusted TSA root certificate(s) (PEM) for --verify-timestamp',
+            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');
     }, async (argv) => {
-        verifyBundleStandaloneCommand(argv.file, {
+        await verifyRecordStandaloneCommand(argv.file, {
             publicKey: argv['public-key'],
             kid: argv.kid,
             json: argv.json,
             verbose: argv.verbose,
+            verifyTimestamp: argv['verify-timestamp'],
+            tsaRoots: argv['tsa-roots'],
         });
     })
         .command('export-verification [file]', 'Produce a self-contained verification package so a third party can verify a CER bundle independently', (yargs) => {