@nexart/cli 0.8.1 → 0.10.0

package/dist/index.js

@@ -64,7 +64,12 @@ import * as https from 'https';
 import { fileURLToPath } from 'url';
 import { realpathSync } from 'fs';
 import { createRequire } from 'module';
-import { verifyProjectBundle, verifyAiCerBundleDetailed, hasAttestation as sdkHasAttestation, isCerPackage as sdkIsCerPackage, getCerFromPackage, createSnapshot as sdkCreateSnapshot, sealCer as sdkSealCer, } from '@nexart/ai-execution';
+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, } 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
+// required lazily only when a local render is actually performed, so this import
+// is safe even when the optional dependency is absent.
+import { renderStaticPng } from '@nexart/codemode-sdk/node';
 // Dynamic version source: read from this CLI package's own package.json at
 // load time so `--version` output, CER metadata, and verify-report verifier
 // strings can never drift from the published npm version. createRequire
@@ -304,6 +309,83 @@ function createPlaceholderPng() {
         0x44, 0xAE, 0x42, 0x60, 0x82
     ]);
 }
+/**
+ * Resolve the installed @nexart/codemode-sdk version (descriptive only).
+ */
+function getSdkCodemodeVersion() {
+    try {
+        const req = createRequire(import.meta.url);
+        const pkg = req('@nexart/codemode-sdk/package.json');
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Resolve the installed native `canvas` version if present (descriptive only).
+ * Returns undefined when the optional dependency is not installed.
+ */
+function getCanvasVersion() {
+    try {
+        const req = createRequire(import.meta.url);
+        const pkg = req('canvas/package.json');
+        return pkg.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build the environment fingerprint for the current process. Descriptive
+ * metadata only — never hashed, never affects pass/fail.
+ */
+function buildEnvironmentFingerprint() {
+    return {
+        cliVersion: CLI_VERSION,
+        sdkVersion: getSdkCodemodeVersion(),
+        protocolVersion: PROTOCOL_VERSION,
+        node: process.version,
+        platform: process.platform,
+        arch: process.arch,
+        canvas: getCanvasVersion(),
+    };
+}
+/**
+ * Compare two environment fingerprints on the fields that can affect
+ * byte-level render reproducibility (runtime + render libs). Returns the list
+ * of differing fields (empty array === environments are equivalent).
+ */
+function diffEnvironmentFingerprints(a, b) {
+    const fields = [
+        'sdkVersion', 'protocolVersion', 'node', 'platform', 'arch', 'canvas',
+    ];
+    return fields.filter((f) => a[f] !== b[f]);
+}
+/**
+ * Render a controlled CodeMode sketch locally using the canonical SDK render
+ * core. Hashing basis is sha256 of the encoded PNG bytes — identical to the
+ * remote renderer's definition. Exits with a clear, actionable error (never a
+ * silent placeholder fallback) when the optional `canvas` dependency or its
+ * native libraries are missing.
+ */
+async function renderLocal(code, seed, VAR, width, height) {
+    try {
+        const result = await renderStaticPng({ mode: 'static', width, height }, { code, seed, vars: VAR });
+        return { pngBytes: result.png, pixelHash: result.pixelHash };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(`[nexart] Local render failed: ${msg}`);
+        if (/canvas/i.test(msg)) {
+            console.error('[nexart] The local renderer requires the optional `canvas` package and its');
+            console.error('[nexart] native libraries (cairo, pango, libjpeg, giflib, librsvg, pixman).');
+            console.error('[nexart] Install with: npm install canvas');
+            console.error('[nexart] Or render remotely with: --renderer remote');
+        }
+        process.exit(1);
+    }
+}
 async function runCommand(file, options) {
     console.log(`[nexart] Running: ${file}`);
     console.log(`[nexart] Renderer: ${options.renderer}`);
@@ -339,9 +421,11 @@ async function runCommand(file, options) {
         }
     }
     else {
-        console.log(`[nexart] WARNING: Local renderer NOT implemented yet — outputs placeholder image only`);
-        pngBytes = createPlaceholderPng();
+        console.log(`[nexart] Rendering locally (deterministic CodeMode SDK renderer)`);
+        const result = await renderLocal(code, seed, VAR, width, height);
+        pngBytes = result.pngBytes;
         runtimeHash = options.runtimeHash || sha256(CODE_MODE_RUNTIME_TAG);
+        console.log(`[nexart] Rendered ${pngBytes.length} bytes locally`);
     }
     const outputHash = sha256(pngBytes);
     const snapshot = {
@@ -359,6 +443,12 @@ async function runCommand(file, options) {
     if (options.includeCode) {
         snapshot.code = code;
     }
+    // Additive: capture the render environment for local renders so replay can
+    // warn on environment drift. Remote renders are produced server-side, so a
+    // local fingerprint would be misleading — omit it there.
+    if (options.renderer === 'local') {
+        snapshot.environment = buildEnvironmentFingerprint();
+    }
     const pngPath = resolveOutputPath(options.out);
     const snapshotPath = deriveSnapshotPath(pngPath);
     const pngAbsPath = writeFileAndVerify(pngPath, pngBytes);
@@ -397,6 +487,32 @@ async function replayCommand(snapshotFile, options) {
     console.log(`[nexart] Seed: ${snapshot.seed}`);
     console.log(`[nexart] VAR: [${snapshot.VAR.join(', ')}]`);
     console.log(`[nexart] Canvas: ${snapshot.canvas.width}x${snapshot.canvas.height}`);
+    // Code integrity check — independent of the render. A mismatch here means the
+    // code being replayed is not the code the snapshot was produced from.
+    const computedCodeHash = hashCode(code);
+    const codeMatch = computedCodeHash === snapshot.codeHash;
+    if (!codeMatch) {
+        console.warn(`[nexart] WARNING: code hash mismatch — replaying DIFFERENT code than the snapshot.`);
+        console.warn(`[nexart]   expected: ${snapshot.codeHash}`);
+        console.warn(`[nexart]   actual:   ${computedCodeHash}`);
+    }
+    // Environment drift check (additive). Only meaningful when the snapshot
+    // carries a fingerprint (local renders). Legacy snapshots omit it.
+    const currentEnv = buildEnvironmentFingerprint();
+    let envDiff = null;
+    if (snapshot.environment) {
+        envDiff = diffEnvironmentFingerprints(snapshot.environment, currentEnv);
+        if (envDiff.length > 0) {
+            console.warn(`[nexart] WARNING: replay environment differs from capture environment: ${envDiff.join(', ')}`);
+            console.warn(`[nexart]   byte-level reproducibility is only guaranteed within the same runtime/render libs.`);
+        }
+        else {
+            console.log(`[nexart] Environment matches capture fingerprint.`);
+        }
+    }
+    else {
+        console.warn(`[nexart] NOTE: snapshot has no environment fingerprint (legacy snapshot) — cannot verify environment parity.`);
+    }
     let pngBytes;
     if (options.renderer === 'remote') {
         validateApiKey(options.apiKey, options.endpoint);
@@ -415,14 +531,54 @@ async function replayCommand(snapshotFile, options) {
         }
     }
     else {
-        console.log(`[nexart] WARNING: Local renderer NOT implemented yet — outputs placeholder image only`);
-        pngBytes = createPlaceholderPng();
+        console.log(`[nexart] Rendering locally (deterministic CodeMode SDK renderer)`);
+        const result = await renderLocal(code, snapshot.seed, snapshot.VAR, snapshot.canvas.width, snapshot.canvas.height);
+        pngBytes = result.pngBytes;
+        console.log(`[nexart] Rendered ${pngBytes.length} bytes locally`);
     }
     const outputHash = sha256(pngBytes);
+    const outputMatch = outputHash === snapshot.outputHash;
+    // Overall PASS requires both the output AND the code to match the snapshot.
+    const pass = outputMatch && codeMatch;
     const pngPath = resolveOutputPath(options.out);
     const pngAbsPath = writeFileAndVerify(pngPath, pngBytes);
     console.log(`[nexart] Wrote PNG: ${pngAbsPath} (${pngBytes.length} bytes)`);
-    console.log(`[nexart] outputHash: ${outputHash}`);
+    console.log(`[nexart] Expected outputHash: ${snapshot.outputHash}`);
+    console.log(`[nexart] Actual   outputHash: ${outputHash}`);
+    console.log(`[nexart] Replay result: ${pass ? 'PASS' : 'FAIL'}`);
+    if (options.evidence) {
+        const evidence = {
+            protocol: 'nexart',
+            kind: 'codemode.replay.evidence.v1',
+            result: pass ? 'PASS' : 'FAIL',
+            snapshotFile,
+            renderer: options.renderer,
+            protocolVersion: snapshot.protocolVersion,
+            seed: snapshot.seed,
+            VAR: snapshot.VAR,
+            canvas: snapshot.canvas,
+            codeHash: {
+                expected: snapshot.codeHash,
+                actual: computedCodeHash,
+                match: codeMatch,
+            },
+            outputHash: {
+                expected: snapshot.outputHash,
+                actual: outputHash,
+                match: outputMatch,
+            },
+            environment: {
+                snapshot: snapshot.environment ?? null,
+                current: currentEnv,
+                diff: envDiff,
+            },
+            replayedAt: new Date().toISOString(),
+            cliVersion: CLI_VERSION,
+        };
+        const evidenceAbsPath = writeFileAndVerify(options.evidence, JSON.stringify(evidence, null, 2));
+        console.log(`[nexart] Wrote replay evidence: ${evidenceAbsPath}`);
+    }
+    process.exit(pass ? 0 : 1);
 }
 async function verifyCommand(snapshotFile, options) {
     const verifiedAt = new Date().toISOString();
@@ -511,8 +667,28 @@ async function verifyCommand(snapshotFile, options) {
     }
     else {
         if (!options.json)
-            console.log(`[nexart] WARNING: Local renderer NOT implemented — using placeholder hash`);
-        actual = sha256(createPlaceholderPng());
+            console.log(`[nexart] Rendering locally (deterministic CodeMode SDK renderer)`);
+        // Environment drift check (additive). Mirrors `replay`. Only meaningful for
+        // local renders; emitted to stderr so it never pollutes machine-readable
+        // output and never affects the verification result. Legacy snapshots (no
+        // fingerprint) still verify, with an explanatory NOTE.
+        if (!options.json) {
+            if (snapshot.environment) {
+                const envDiff = diffEnvironmentFingerprints(snapshot.environment, buildEnvironmentFingerprint());
+                if (envDiff.length > 0) {
+                    console.warn(`[nexart] WARNING: verify environment differs from capture environment: ${envDiff.join(', ')}`);
+                    console.warn(`[nexart]   byte-level reproducibility is only guaranteed within the same runtime/render libs.`);
+                }
+                else {
+                    console.log(`[nexart] Environment matches capture fingerprint.`);
+                }
+            }
+            else {
+                console.warn(`[nexart] NOTE: snapshot has no environment fingerprint (legacy snapshot) — cannot verify environment parity.`);
+            }
+        }
+        const result = await renderLocal(code, snapshot.seed, snapshot.VAR, snapshot.canvas.width, snapshot.canvas.height);
+        actual = sha256(result.pngBytes);
     }
     const outputMatch = expected === actual;
     if (options.json) {
@@ -901,6 +1077,17 @@ export async function aiCertifyCommand(file, opts, fetchFn = globalThis.fetch, s
  * `cli` envelope describing input handling. The SDK fields are never rewritten
  * or reinterpreted.
  */
+/**
+ * Map an AnchorVerifyResult to the user-facing label.
+ *   checked=false           → NOT PRESENT
+ *   checked=true, valid     → VALID
+ *   checked=true, !valid    → INVALID
+ */
+function anchorLabel(status) {
+    if (!status.checked)
+        return 'NOT PRESENT';
+    return status.valid ? 'VALID' : 'INVALID';
+}
 export async function aiVerifyCommand(file, opts, stdinReader = readStdinText) {
     const raw = await readInputJson(file, stdinReader);
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
@@ -921,6 +1108,18 @@ export async function aiVerifyCommand(file, opts, stdinReader = readStdinText) {
     // Delegate ALL verification to the SDK. The CLI does not interpret, fall
     // back, or aggregate. The result object is the protocol's source of truth.
     const result = verifyAiCerBundleDetailed(bundleForVerification);
+    // Anchoring Layer (opt-in via --anchors). Independently verified and reported
+    // SEPARATELY from the three protocol layers. Anchor validity NEVER affects the
+    // exit code or base verification — anchors are a secondary proof layer.
+    const anchorStatus = opts.anchors
+        ? sdkVerifyAnchors(bundleForVerification)
+        : null;
+    // Trusted Timestamp Layer (opt-in via --timestamps). Same secondary-proof
+    // semantics as anchors: verified independently (OFFLINE) and NEVER affecting
+    // the exit code or base verification outcome.
+    const timestampStatus = opts.timestamps
+        ? sdkVerifyTrustedTimestamps(bundleForVerification)
+        : null;
     if (opts.json) {
         // Pass the SDK result through verbatim. Add only a small `cli` envelope
         // so callers can tell whether the input was a bundle or a package and
@@ -931,6 +1130,7 @@ export async function aiVerifyCommand(file, opts, stdinReader = readStdinText) {
                 version: CLI_VERSION,
                 sdkVersion: getSdkVersion(),
                 inputType,
+                protocolVersion: bundleForVerification?.snapshot?.protocolVersion ?? null,
                 ...(isPackage
                     ? {
                         verifiedInnerCer: true,
@@ -938,6 +1138,8 @@ export async function aiVerifyCommand(file, opts, stdinReader = readStdinText) {
                     }
                     : {}),
             },
+            ...(anchorStatus ? { anchorStatus } : {}),
+            ...(timestampStatus ? { timestampStatus } : {}),
         };
         process.stdout.write(JSON.stringify(output, null, 2) + '\n');
     }
@@ -950,12 +1152,47 @@ export async function aiVerifyCommand(file, opts, stdinReader = readStdinText) {
         }
         console.log(`Verification result: ${result.status}`);
         console.log(`bundleType:          ${result.bundleType || '(missing)'}`);
+        console.log(`protocolVersion:     ${bundleForVerification?.snapshot?.protocolVersion || '(missing)'}`);
         console.log(`certificateHash:     ${result.certificateHash || '(missing)'}`);
         console.log('');
         console.log('Layers:');
         console.log(`  bundleIntegrity    (Integrity): ${result.checks.bundleIntegrity}`);
         console.log(`  nodeSignature      (Receipt):   ${result.checks.nodeSignature}`);
         console.log(`  receiptConsistency (Envelope):  ${result.checks.receiptConsistency}`);
+        if (anchorStatus) {
+            // Anchors are reported as an INDEPENDENT proof layer, separate from the
+            // three protocol layers above. They never affect the exit code.
+            console.log(`  anchors            (Anchoring): ${anchorLabel(anchorStatus)}`);
+            if (anchorStatus.errors && anchorStatus.errors.length > 0) {
+                for (const err of anchorStatus.errors) {
+                    console.log(`      - ${err}`);
+                }
+            }
+        }
+        if (timestampStatus) {
+            // Trusted timestamps are an INDEPENDENT proof layer, like anchors. Never
+            // affect the exit code.
+            console.log(`  trustedTimestamps  (Timestamp): ${anchorLabel(timestampStatus)}`);
+            if (timestampStatus.errors && timestampStatus.errors.length > 0) {
+                for (const err of timestampStatus.errors) {
+                    console.log(`      - ${err}`);
+                }
+            }
+        }
+        // Enterprise Trust summary — concise, layer-oriented overview. Signature is
+        // derived from the node-signature protocol check; anchors/timestamps reflect
+        // the opt-in secondary proof layers (NOT CHECKED when their flag is absent).
+        const signatureLabel = result.checks.nodeSignature === 'PASS'
+            ? 'VALID'
+            : result.checks.nodeSignature === 'FAIL'
+                ? 'INVALID'
+                : 'NOT PRESENT';
+        console.log('');
+        console.log('Trust summary:');
+        console.log(`  Signature:        ${signatureLabel}`);
+        console.log(`  Anchors:          ${anchorStatus ? anchorLabel(anchorStatus) : 'NOT CHECKED'}`);
+        console.log(`  Timestamp:        ${timestampStatus ? anchorLabel(timestampStatus) : 'NOT CHECKED'}`);
+        console.log(`  Protocol Version: ${bundleForVerification?.snapshot?.protocolVersion || '(missing)'}`);
         if (result.reasonCodes.length > 0) {
             console.log('');
             console.log('Reason codes:');
@@ -973,6 +1210,105 @@ export async function aiVerifyCommand(file, opts, stdinReader = readStdinText) {
     }
     process.exit(result.status === 'VERIFIED' ? 0 : 1);
 }
+/**
+ * nexart ai attach-anchor — Attach an external anchor (proof of existence) to a
+ * CER bundle and emit the updated bundle.
+ *
+ * Reads a CER bundle JSON and an anchor JSON, calls the SDK's pure
+ * `attachAnchor()` (new object, no mutation), and writes the result to stdout
+ * (or --out). The certificateHash is GUARANTEED unchanged: anchors are
+ * non-evidentiary and never participate in hashing or signing.
+ *
+ * The SDK does NOT generate anchors — they come from external systems (e.g. the
+ * attestation node's transparency log). This command only attaches a supplied
+ * anchor.
+ */
+export async function aiAttachAnchorCommand(bundleFile, anchorFile, opts) {
+    let rawBundle;
+    let rawAnchor;
+    try {
+        rawBundle = JSON.parse(fs.readFileSync(bundleFile, 'utf-8'));
+    }
+    catch (err) {
+        console.error(`[nexart] Error: could not read bundle "${bundleFile}": ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    try {
+        rawAnchor = JSON.parse(fs.readFileSync(anchorFile, 'utf-8'));
+    }
+    catch (err) {
+        console.error(`[nexart] Error: could not read anchor "${anchorFile}": ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    if (!rawBundle || typeof rawBundle !== 'object' || Array.isArray(rawBundle)) {
+        console.error('[nexart] Error: bundle input is not a valid CER bundle object');
+        process.exit(1);
+    }
+    if (!rawAnchor || typeof rawAnchor !== 'object' || Array.isArray(rawAnchor)) {
+        console.error('[nexart] Error: anchor input is not a valid anchor object');
+        process.exit(1);
+    }
+    const bundle = rawBundle;
+    const anchor = rawAnchor;
+    const updated = sdkAttachAnchor(bundle, anchor);
+    const json = JSON.stringify(updated, null, 2);
+    if (opts.out) {
+        fs.writeFileSync(opts.out, json + '\n');
+        console.error(`[nexart] Anchored bundle written to ${opts.out}`);
+        console.error(`[nexart] certificateHash unchanged: ${updated.certificateHash}`);
+    }
+    else {
+        process.stdout.write(json + '\n');
+    }
+}
+/**
+ * nexart export-verification — Produce a self-contained verification package for
+ * a CER bundle so a third party can verify it INDEPENDENTLY (no NexArt node, no
+ * this SDK required).
+ *
+ * Delegates entirely to the SDK's `exportVerificationPackage()`. The CLI only
+ * handles file/stdin I/O and (optionally) supplies key material:
+ *   --public-key <b64url>  raw Ed25519 public key (highest priority)
+ *   --node-keys <file>     a NodeKeysDocument JSON to select the receipt's key from
+ *   --out <file>           write the package to a file (default: stdout)
+ *
+ * Read-only and additive: never re-hashes, re-signs, or mutates the bundle.
+ */
+export async function exportVerificationCommand(file, opts, stdinReader = readStdinText) {
+    const raw = await readInputJson(file, stdinReader);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        console.error('[nexart] Error: Input is not a valid CER bundle or CER package object');
+        process.exit(1);
+    }
+    // Accept either a raw bundle or a CER package (unwrap to the inner bundle).
+    const bundle = sdkIsCerPackage(raw)
+        ? getCerFromPackage(raw)
+        : raw;
+    let nodeKeys;
+    if (opts.nodeKeys) {
+        try {
+            nodeKeys = JSON.parse(fs.readFileSync(opts.nodeKeys, 'utf-8'));
+        }
+        catch (err) {
+            console.error(`[nexart] Error: could not read node keys "${opts.nodeKeys}": ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    }
+    const pkg = sdkExportVerificationPackage(bundle, {
+        publicKey: opts.publicKey,
+        nodeKeys,
+    });
+    const json = JSON.stringify(pkg, null, 2);
+    if (opts.out) {
+        fs.writeFileSync(opts.out, json + '\n');
+        console.error(`[nexart] Verification package written to ${opts.out}`);
+        console.error(`[nexart] certificateHash: ${pkg.bundle.certificateHash}`);
+        console.error(`[nexart] publicKey: ${pkg.publicKey ?? '(not resolved — supply --public-key or --node-keys)'}`);
+    }
+    else {
+        process.stdout.write(json + '\n');
+    }
+}
 /**
  * nexart ai project-verify — Read a cer.project.bundle.v1 JSON from file or stdin,
  * delegate all verification to verifyProjectBundle() from @nexart/ai-execution,
@@ -1142,7 +1478,7 @@ if (_isMainModule) {
             default: 2400,
         })
             .option('renderer', {
-            describe: 'Renderer mode: remote (default) or local (placeholder)',
+            describe: 'Renderer mode: remote (default) or local (deterministic CodeMode SDK renderer)',
             choices: ['local', 'remote'],
             default: 'remote',
         })
@@ -1196,7 +1532,7 @@ if (_isMainModule) {
             type: 'string',
         })
             .option('renderer', {
-            describe: 'Renderer mode',
+            describe: 'Renderer mode: remote (default) or local (deterministic CodeMode SDK renderer)',
             choices: ['local', 'remote'],
             default: 'remote',
         })
@@ -1205,7 +1541,12 @@ if (_isMainModule) {
             type: 'string',
             default: DEFAULT_ENDPOINT,
         })
-            .options(apiKeyOption);
+            .option('evidence', {
+            describe: 'Write a JSON replay-evidence file (PASS/FAIL + hash comparison) to this path',
+            type: 'string',
+        })
+            .options(apiKeyOption)
+            .example('$0 replay sketch.snapshot.json --renderer local --evidence replay.evidence.json', 'Deterministically replay locally and emit PASS/FAIL evidence');
     }, async (argv) => {
         await replayCommand(argv.snapshot, {
             out: argv.out,
@@ -1213,6 +1554,7 @@ if (_isMainModule) {
             renderer: argv.renderer,
             endpoint: argv.endpoint,
             apiKey: argv['api-key'],
+            evidence: argv.evidence,
         });
     })
         .command('verify <snapshot>', 'Verify a snapshot produces the expected output', (yargs) => {
@@ -1228,7 +1570,7 @@ if (_isMainModule) {
             type: 'string',
         })
             .option('renderer', {
-            describe: 'Renderer mode',
+            describe: 'Renderer mode: remote (default) or local (deterministic CodeMode SDK renderer)',
             choices: ['local', 'remote'],
             default: 'remote',
         })
@@ -1350,13 +1692,46 @@ if (_isMainModule) {
                 describe: 'Print machine-readable JSON result',
                 type: 'boolean',
                 default: false,
+            })
+                .option('anchors', {
+                describe: 'Also verify the bundle\'s anchors (secondary proof layer; never affects exit code)',
+                type: 'boolean',
+                default: false,
+            })
+                .option('timestamps', {
+                describe: 'Also verify the bundle\'s trusted timestamps (secondary proof layer; never affects exit code)',
+                type: 'boolean',
+                default: false,
             })
                 .example('$0 ai verify cer.json', 'Verify a raw CER bundle')
                 .example('$0 ai verify cer-package.json', 'Verify a CER package (inner bundle verified)')
                 .example('cat cer.json | $0 ai verify', 'Verify from stdin')
-                .example('$0 ai verify cer.json --json', 'Machine-readable output');
+                .example('$0 ai verify cer.json --json', 'Machine-readable output')
+                .example('$0 ai verify cer.json --anchors', 'Verify and report anchor status (VALID/INVALID/NOT PRESENT)')
+                .example('$0 ai verify cer.json --anchors --timestamps', 'Report anchor + trusted timestamp status with a trust summary');
         }, async (argv) => {
-            await aiVerifyCommand(argv.file, { json: argv.json });
+            await aiVerifyCommand(argv.file, { json: argv.json, anchors: argv.anchors, timestamps: argv.timestamps });
+        })
+            .command('attach-anchor <bundle> <anchor>', 'Attach an external anchor (proof of existence) to a CER bundle — certificateHash is unchanged', (yargs) => {
+            return yargs
+                .positional('bundle', {
+                describe: 'Path to the CER bundle JSON to anchor',
+                type: 'string',
+            })
+                .positional('anchor', {
+                describe: 'Path to the anchor JSON to attach (supplied by an external system, e.g. the attestation node)',
+                type: 'string',
+            })
+                .option('out', {
+                alias: 'o',
+                describe: 'Save the anchored bundle to this file (default: stdout)',
+                type: 'string',
+            })
+                .example('$0 ai attach-anchor cer.json anchor.json', 'Attach an anchor and print the updated bundle')
+                .example('$0 ai attach-anchor cer.json anchor.json --out anchored.json', 'Save the anchored bundle')
+                .example('$0 ai attach-anchor cer.json anchor.json | $0 ai verify --anchors', 'Attach then verify anchors in a pipe');
+        }, async (argv) => {
+            await aiAttachAnchorCommand(argv.bundle, argv.anchor, { out: argv.out });
         })
             .command('project-verify [file]', 'Verify a project bundle (cer.project.bundle.v1) locally (no network required)', (yargs) => {
             return yargs
@@ -1376,9 +1751,38 @@ if (_isMainModule) {
         }, async (argv) => {
             await aiProjectVerifyCommand(argv.file, { json: argv.json });
         })
-            .demandCommand(1, 'You must provide a subcommand: create, certify, verify, or project-verify')
+            .demandCommand(1, 'You must provide a subcommand: create, certify, seal, verify, attach-anchor, or project-verify')
             .help();
     }, () => { })
+        .command('export-verification [file]', 'Produce a self-contained verification package so a third party can verify a CER bundle independently', (yargs) => {
+        return yargs
+            .positional('file', {
+            describe: 'Path to CER bundle or CER package JSON (omit to read from stdin)',
+            type: 'string',
+        })
+            .option('node-keys', {
+            describe: 'Path to a NodeKeysDocument JSON; the receipt\'s public key is selected from it',
+            type: 'string',
+        })
+            .option('public-key', {
+            describe: 'Raw Ed25519 public key (base64url) to embed (highest priority)',
+            type: 'string',
+        })
+            .option('out', {
+            alias: 'o',
+            describe: 'Save the verification package to this file (default: stdout)',
+            type: 'string',
+        })
+            .example('$0 export-verification cer.json', 'Print a verification package to stdout')
+            .example('$0 export-verification cer.json --node-keys keys.json --out pkg.json', 'Resolve the public key and save the package')
+            .example('cat cer.json | $0 export-verification', 'Build a package from stdin');
+    }, async (argv) => {
+        await exportVerificationCommand(argv.file, {
+            out: argv.out,
+            nodeKeys: argv['node-keys'],
+            publicKey: argv['public-key'],
+        });
+    })
         .demandCommand(1, 'You must provide a command')
         .help()
         .version(`@nexart/cli           ${CLI_VERSION}