@nexart/cli 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,298 @@
+# @nexart/cli — Changelog
+
+## v0.10.0 (2026-06-11) — protocolVersion awareness (versioned canonicalisation)
+
+Additive and fully backward-compatible. No command, flag, or output format was
+removed or changed.
+
+- **`ai verify` now surfaces the bundle's `protocolVersion`** in both human-readable
+  and `--json` output (`cli.protocolVersion`), so operators can see which
+  canonicalisation mode (`1.2.0`→`nexart-v1`, `1.3.0`→`jcs-v1`) was verified.
+- **Fail-closed behaviour for unknown versions is inherited from the SDK.** All AI
+  verification still delegates entirely to `@nexart/ai-execution`
+  (`verifyAiCerBundleDetailed`); a record with an unsupported `protocolVersion` is
+  reported as `FAILED` (verify code `SCHEMA_ERROR`, reason code
+  `SCHEMA_VERSION_UNSUPPORTED`, exit 1) rather than mis-verified. The CLI
+  adds no fallback or default.
+- **Requires `@nexart/ai-execution` `^0.17.0`** — the first public release that ships
+  `protocolVersion` `1.3.0` (`jcs-v1` / RFC 8785). Earlier public ai-execution
+  releases are `1.2.0`-only; pinning to `^0.17.0` is what lets a fresh
+  `npm install -g @nexart/cli` verify `1.3.0` records (and fail closed on unknown
+  versions).
+
+### Also in v0.10.0 — Enterprise trust layers surfaced in the CLI (additive, NON-evidentiary)
+
+All additive; no existing command, flag, or output format was removed or changed. These layers are
+**secondary proofs** — they are reported separately and **never** change the verification result or
+exit code (`VERIFIED` → exit 0, `FAILED` → exit 1 still derive solely from base SDK verification).
+
+- **`nexart ai verify --anchors`** — verify and report anchor status (`VALID` / `INVALID` /
+  `NOT PRESENT`).
+- **`nexart ai verify --timestamps`** — verify and report trusted-timestamp status; adds a human
+  `Layers:` block and a `Trust summary` block (Signature / Anchors / Timestamp / Protocol Version),
+  and top-level `anchorStatus` / `timestampStatus` to `--json` output.
+- **`nexart ai attach-anchor <cer> <anchor>`** — append-only attach of an external anchor (no
+  re-hash/re-sign).
+- **`nexart export-verification <cer>`** (new top-level command) — emit a self-contained, offline
+  verification package (`{ bundle, publicKey, verificationInstructions }`); `--out`, `--node-keys`,
+  `--public-key`.
+
+## v0.9.0 (2026-06-08)
+
+### New Features — Deterministic Replay (controlled CodeMode / canonical renders)
+
+Additive and fully backward-compatible. No public command, flag, snapshot, or
+verifier-output format was removed or changed; legacy snapshots continue to
+verify and replay exactly as before.
+
+- **`--renderer local` is now a real deterministic renderer.** `run`, `replay`,
+  and `verify` render locally through the canonical CodeMode render core
+  (`renderStaticPng` from `@nexart/codemode-sdk/node`) and hash the encoded PNG
+  bytes — the same `outputHash` definition as the remote renderer. The previous
+  1×1 placeholder behavior is gone; a missing optional `canvas` dependency now
+  fails clearly (exit 1, install hint) instead of producing a false pass.
+- **`nexart replay` performs real load → render → compare.** It reports
+  `PASS`/`FAIL` (exit `0`/`1`), comparing both the recomputed `outputHash` and
+  the replayed `codeHash` against the snapshot.
+- **`nexart replay --evidence <file>`** writes a `codemode.replay.evidence.v1`
+  JSON document (result, expected vs. actual `outputHash`/`codeHash`, renderer,
+  and environment fingerprints).
+- **Optional, additive snapshot `environment` fingerprint** (`cliVersion`,
+  `sdkVersion`, `protocolVersion`, `node`, `platform`, `arch`, `canvas`) is
+  attached to locally-rendered snapshots. It is descriptive metadata only —
+  never hashed, never affects pass/fail — and lets `replay`/`verify` warn on
+  environment drift. Legacy snapshots omit it and are unaffected.
+- Added `@nexart/codemode-sdk` dependency and `canvas` as an optional
+  dependency. Added Deterministic Replay test suite (`replay.test.ts`).
+
+---
+
+## v0.8.1 (2026-05-28)
+
+### Fixes
+
+- **Version-drift prevention** — `CLI_VERSION` is now sourced dynamically from `package.json` at load time via `createRequire(import.meta.url)('../package.json')`, replacing the previously hardcoded `'0.8.0'` literal. The `--version` output, CER metadata `version` field, and `verify` report verifier string can no longer drift from the published npm version on subsequent bumps.
+- No API changes. No behavior changes for the current 0.8.x line — the runtime value remains identical, only its source has changed. Added drift-prevention test (Suite Z) that asserts the dynamic resolution matches `package.json`.
+
+---
+
+## v0.8.0 (2026-04-30)
+
+### New Features
+
+- **`nexart ai seal [file]`** — local sealing of an AI execution input into a `cer.ai.execution.v1` bundle, fully offline. No node, no network, no API key required.
+  Useful for offline workflows, CI pipelines, pre-certification, and piping straight into `nexart ai verify`.
+
+  All snapshot construction, canonicalization, and certificate hashing is delegated to `createSnapshot()` + `sealCer()` from `@nexart/ai-execution`. The CLI performs input-shape validation only — it never recomputes hashes or canonicalizes JSON. A defensive `hasAttestation()` re-check refuses to ship a misclassified artifact.
+
+  ```bash
+  nexart ai seal execution.json                          # seal from file → stdout
+  cat execution.json | nexart ai seal                    # seal from stdin
+  cat execution.json | nexart ai seal --quiet | nexart ai verify   # pipe to verify
+  nexart ai seal execution.json --out cer.json           # save to file
+  ```
+
+  - **Bundle JSON → stdout**, status banner → **stderr**, so pipes stay clean.
+  - **`--quiet` / `-q`** suppresses the stderr banner entirely.
+  - **`--out` / `-o`** writes the bundle to disk; stdout output is byte-equal to the file.
+  - Status banner: `Local CER created` / `State: Sealed (integrity only)` / `No node attestation present` / `This record is not certified — use \`nexart ai certify\` to attest via a node` / `certificateHash: sha256:...`
+  - Help epilogue distinguishes Sealed (this command, integrity only) from Certified (`ai certify`, integrity + node receipt + signature).
+  - Sealed bundles verify as `VERIFIED` with Receipt and Envelope reported as `SKIPPED` — that is correct, not a failure (only the Integrity layer applies to local artifacts).
+
+### Verify alignment (Phase 1)
+
+- **`nexart ai verify` is now a pure delegation surface** for `verifyAiCerBundleDetailed()` from `@nexart/ai-execution`.
+  - The 3 verification layers (`bundleIntegrity`, `nodeSignature`, `receiptConsistency`) are reported independently with SDK reason codes used verbatim.
+  - `--json` output now puts the SDK's `CerVerificationResult` at the **top level** (including `verifier: "@nexart/ai-execution"`) and adds an additive `cli` envelope containing `version`, `sdkVersion`, `inputType`, and (for packages) `verifiedInnerCer` / `packageTrustLayersVerified`.
+  - The CLI no longer owns any verification semantics: no canonicalization, no hash recomputation, no inner-CER comparison logic.
+
+### Architecture
+
+- **Removed** `interface CerBundle` from `src/index.ts` — the canonical bundle type is now `CerAiExecutionBundle` from `@nexart/ai-execution` (a parallel local type would be a drift hazard).
+- **Removed** the dead `sha256hex()` helper from `__tests__/ai.test.ts` — tests no longer recompute CER hashes by hand; all CER cryptographic semantics belong to the SDK.
+- Strict TypeScript audit (`tsc --noUnusedLocals --noUnusedParameters`) is now clean.
+- All `crypto.createHash()` / `sha256()` usage in `src/index.ts` is confined to **Code Mode** paths (runtimeHash, output PNG hash, separate wire protocol `1.2.0`). Zero CER hashing remains in the CLI.
+
+### Compatibility
+
+- Fully backward-compatible. All pre-existing commands (`run`, `replay`, `verify` (Code Mode), `ai create`, `ai certify`, `ai project-verify`) are unchanged in behavior.
+- The `--json` output for `ai verify` is **shape-evolved**, not breaking: prior fields are preserved at the top level (now sourced from the SDK result verbatim) and prior CLI-only fields (`inputType`, `verifiedInnerCer`, `packageTrustLayersVerified`) have moved into the new additive `cli` envelope. Consumers that read top-level fields keep working; consumers that read the moved fields need to read them from `cli.*`.
+- The `verifier` field at the top level of `ai verify --json` changes from `"@nexart/cli"` to `"@nexart/ai-execution"`, reflecting that verification semantics now live in the SDK.
+- `ai project-verify --json` is intentionally **out of scope** for this alignment — it continues to emit `verifier: "@nexart/cli"` and its own envelope shape (the underlying verification logic is still fully delegated to `verifyProjectBundle()`). Aligning this is a candidate for a future release.
+
+### Dependencies
+
+- Bumped `@nexart/ai-execution` from `^0.13.0` to `^0.16.1` (brings `createSnapshot`, `sealCer`, layered `verifyAiCerBundleDetailed`, and stable reason codes).
+
+### Tests
+
+New test group:
+
+| Group | What it covers |
+|-------|---------------|
+| **X** | `aiSealCommand` — local CER sealing (12 assertions): X1 bundle shape (`bundleType`, `version`, `certificateHash`, `createdAt`, `snapshot`), X2 no-attestation invariant, X3 stderr banner content, X4 `--quiet` silences stderr, X5 `--out` byte-equal to stdout, X6 round-trip `seal → verify` produces `VERIFIED` with Integrity `PASS` and Receipt+Envelope `SKIPPED`, X7 signals binding into `certificateHash`, X8 tamper detection (`BUNDLE_HASH_MISMATCH`), X9 missing-required-field rejection, X10 array input rejection, X11 malformed `parameters` rejection, X12 determinism (same input → same `certificateHash`) |
+
+**Total: 74 tests across 22 suites, all passing.**
+
+---
+
+## v0.7.0 (2026-04-06)
+
+### New Features
+
+- **`nexart ai project-verify [file]`** — local verification of `cer.project.bundle.v1` artifacts.  
+  No network required. Accepts a file path or stdin. Delegates all verification logic to `verifyProjectBundle()` from `@nexart/ai-execution`, which is the canonical source of truth. The CLI owns the command surface, input handling, and output formatting only.
+
+  `@nexart/ai-execution` is now a declared runtime dependency of `@nexart/cli`.
+
+  Checks performed (in order, via `@nexart/ai-execution`):
+  1. `bundleType` discriminant: must be `cer.project.bundle.v1`
+  2. Required field presence: `version`, `protocolVersion`, `projectBundleId`, `projectTitle`, `startedAt`, `completedAt`, `integrity` block shape
+  3. `stepRegistry` is a non-empty array
+  4. `embeddedBundles` is a plain object keyed by `stepId`
+  5. `totalSteps` consistency: must equal `stepRegistry.length`
+  6. Per-step: embedded bundle exists for every registry entry; `executionId` and `certificateHash` match; inner CER `certificateHash` is independently valid
+  7. `integrity.projectHash` is recomputed from all material project metadata and compared to the declared value
+
+  Exit code: `0` on `VERIFIED`, `1` on `FAILED` or structural error.
+
+- **`--json` flag** on `nexart ai project-verify`  
+  Prints a machine-readable `ProjectVerifyResult` object to stdout:
+  ```json
+  {
+    "status": "VERIFIED",
+    "bundleType": "cer.project.bundle.v1",
+    "projectBundleId": "...",
+    "projectTitle": "...",
+    "totalSteps": 2,
+    "passedSteps": 2,
+    "failedSteps": 0,
+    "projectHashValid": true,
+    "checks": {
+      "structuralValid": true,
+      "projectHashIntegrity": "PASS",
+      "stepIntegrity": "PASS"
+    },
+    "steps": [ ... ],
+    "errors": [],
+    "verifiedAt": "...",
+    "verifier": "@nexart/cli"
+  }
+  ```
+
+### Architecture
+
+`nexart ai project-verify` follows the same CLI ownership model as `nexart ai verify`:
+- The CLI owns: input routing, argument parsing, discriminant check, and output formatting.
+- `@nexart/ai-execution` owns: project bundle schema, project hash computation, per-step CER verification semantics, and `ProjectBundleVerifyResult` type.
+- The CLI does **not** duplicate or shadow any of `@nexart/ai-execution`'s project bundle verification logic.
+
+### Compatibility
+
+- Fully backward-compatible. All existing commands (`create`, `certify`, `verify`) are unchanged.
+- `nexart ai verify` continues to handle `cer.ai.execution.v1` bundles and CER packages. Project bundles require the new `nexart ai project-verify` command.
+- The `ai` group's `demandCommand` hint is updated to include `project-verify` in the listed subcommands.
+
+### Dependencies
+
+- **Added**: `@nexart/ai-execution@^0.13.0` as a runtime dependency.
+
+### Tests
+
+New test group:
+
+| Group | What it covers |
+|-------|---------------|
+| **W** | `aiProjectVerifyCommand` — project bundle verification (9 assertions): W1 PASS human-readable via file, W2 PASS --json with full field checks, W3 FAIL wrong bundleType, W4 FAIL tampered projectHash (human-readable), W5 FAIL tampered projectHash (--json), W6 FAIL inner CER certificateHash tampered (step-level failure), W7 PASS with all optional fields (projectGoal, projectSummary, appName, frameworkName, tags), W8 FAIL totalSteps mismatch, W9 PASS via stdin |
+
+Test fixtures for the W group use `createProjectBundle` and `sealCer` from `@nexart/ai-execution` to build fully valid `cer.project.bundle.v1` and `cer.ai.execution.v1` artifacts, ensuring the tests exercise the same verification path as the published package.
+
+**Total: 78 tests, all passing (groups A–W).**
+
+---
+
+## v0.6.0 (2026-03-25)
+
+### New Features
+
+- **CER package support in `nexart ai verify`** (v0.6.0)  
+  `nexart ai verify` now accepts both raw CER bundles and **CER packages** — envelope objects with the shape `{ cer: <bundle>, receipt?, signature?, ... }`.  
+  Detection is automatic; no extra flags are needed.
+  - If the input has a top-level `bundleType === 'cer.ai.execution.v1'`, it is treated as a raw bundle (behavior unchanged from v0.5.0).
+  - If the input has a `cer` field whose inner `bundleType === 'cer.ai.execution.v1'`, it is treated as a CER package. Only the inner bundle is verified; receipt, signature, and other envelope fields are not verified by this command.
+
+- **`isCerPackageInput` internal helper**  
+  Mirrors the detection logic of `isCerPackage()` from `@nexart/ai-execution` inline. The CLI remains self-contained with no runtime dependency on the SDK.
+
+- **`inputType` field in `--json` output**  
+  All `nexart ai verify --json` output now includes `"inputType": "bundle"` or `"inputType": "package"` (additive, backward-compatible).
+
+- **Package-specific `--json` output fields**  
+  When verifying a CER package, the JSON output additionally includes:
+  - `"verifiedInnerCer": true` — confirms the inner `cer` bundle was the verification target.
+  - `"packageTrustLayersVerified": false` — signals that receipt/signature/envelope verification is not performed by this command.
+
+### Compatibility
+
+- Fully backward-compatible with all existing raw CER bundle inputs.
+- Existing JSON consumers that read `nexart ai verify --json` output will see the new additive `inputType` field; all prior fields are preserved.
+- Compatible with CER packages produced by `@nexart/ai-execution@0.12.0` (`createCerPackage`, `exportCerPackage`).
+
+### Tests
+
+New test group:
+
+| Group | What it covers |
+|-------|---------------|
+| **V** | `aiVerifyCommand` — CER package input (8 assertions): PASS human-readable via stdin/file, PASS JSON with package fields, FAIL tampered inner CER (human-readable + JSON), PASS with receipt/signature envelope, backward-compat `inputType: "bundle"` for raw bundles, non-package `cer` field falls through to error path |
+
+**Total: 69 tests, all passing (groups A–V).**
+
+---
+
+## v0.5.0 (2026-03-17)
+
+### New Features
+
+- **`--signals-file` flag** on `nexart ai create` and `nexart ai certify`.  
+  Reads a JSON array of context signals from the given file and merges them into the request body as `{ signals: [...] }`. The node API embeds the signals in the CER under `context.signals` and includes them in the `certificateHash`.
+
+- **`loadSignalsFile(path)` export** — new utility that reads, parses, and validates a signals JSON array from disk. Exits with a clear error message if the file is missing, contains invalid JSON, or is not a JSON array.
+
+### Bug Fixes
+
+- **Critical: `computeBundleHash` now includes `context` in the protected set** when present (non-null/non-undefined).  
+  Previously, `nexart ai verify` on a v0.11.0+ CER containing `context.signals` would always fail with a spurious `BUNDLE_HASH_MISMATCH` because the hash was computed without `context`. The fix aligns the CLI's local hash computation with `@nexart/ai-execution@0.11.0` semantics.  
+  **Backward compatible:** bundles without `context` continue to produce the same hash as before.
+
+### Compatibility
+
+- Compatible with `@nexart/ai-execution@0.11.0` CER format (optional `context.signals`).
+- `nexart ai verify` handles both plain CERs (no `context`) and CERs with `context.signals` without any extra flags.
+
+### Tests
+
+New test groups:
+
+| Group | What it covers |
+|-------|---------------|
+| **R** | `computeBundleHash` with context signals (7 assertions) |
+| **S** | `aiVerifyCommand` — signals-containing CER bundle PASS/FAIL (4 assertions) |
+| **T** | `loadSignalsFile` helper — valid array, missing file, invalid JSON, non-array, empty array (5 assertions) |
+| **U** | `aiCreateCommand` / `aiCertifyCommand` `--signals-file` merges signals into request body (4 assertions) |
+
+---
+
+## v0.4.0 (2026-03-10)
+
+- `nexart ai create` — `--out` flag saves returned CER bundle to file (group P)
+- `nexart ai certify` — 401/422 error handling (group Q)
+- `callNodeApi` — correctly omits `Authorization` header when no API key provided (group M)
+- All AI command stdinReader tests (groups N, O)
+
+## v0.3.0 (2026-03-01)
+
+- Initial `nexart ai create`, `nexart ai certify`, `nexart ai verify` commands
+- `canonicalJson` + `computeBundleHash` (protected set: `bundleType`, `version`, `createdAt`, `snapshot`)
+- `hasAttestation` helper
+- Test groups A–L covering core AI certification commands

package/README.md

@@ -1,7 +1,23 @@
-# @nexart/cli v0.8.0
+# @nexart/cli v0.10.0
 
 Command-line interface for NexArt — run, replay, and verify deterministic generative art, plus AI execution certification commands.
 
+## protocolVersion: 1.2.0 vs 1.3.0
+
+Verified records carry a `protocolVersion` that selects how their bytes are
+canonicalised before hashing — `ai verify` surfaces it in both human-readable and
+`--json` output (`cli.protocolVersion`).
+
+- **1.2.0 (legacy, default):** the original NexArt canonicalisation (`nexart-v1`),
+  fully supported and **frozen**.
+- **1.3.0 (stranger-verifiable):** RFC 8785 (JSON Canonicalization Scheme, `jcs-v1`).
+  **Required for independent / external verification** by a third party who does not
+  run our exact code.
+
+A record with an unknown or unsupported `protocolVersion` fails closed (verify code
+`SCHEMA_ERROR`, reason code `SCHEMA_VERSION_UNSUPPORTED`, exit 1) — it is never
+mis-verified. The CLI adds no fallback or default.
+
 ## Installation
 
 ```bash
@@ -130,10 +146,23 @@ nexart run sketch.js --seed 12345 --out render.png
 # With code embedded for standalone verify/replay
 nexart run sketch.js --seed 12345 --include-code
 
-# Local mode (placeholder PNG, no auth required)
-nexart run sketch.js --renderer local
+# Local deterministic mode (no auth required; requires the optional `canvas` dependency)
+nexart run sketch.js --renderer local --include-code
 ```
 
+> **Deterministic Replay (local renderer).** With `--renderer local`, the CLI
+> renders the sketch using the same canonical CodeMode render core as the SDK
+> and hashes the encoded PNG bytes — the identical `outputHash` definition used
+> by the remote renderer. For **controlled CodeMode / canonical render**
+> snapshots this is byte-reproducible **within the same runtime and render
+> libraries** (Node version, platform/arch, and `canvas` native libs). To make
+> that reproducibility checkable, local snapshots additionally embed an
+> optional, additive `environment` fingerprint (see below). Reproducibility
+> across *different* environments is not guaranteed; `replay`/`verify` will warn
+> when the environment differs. The local renderer requires the optional
+> `canvas` package and its native libraries — if they are missing, local
+> rendering fails with a clear, actionable error (never a silent placeholder).
+
 **Options:**
 | Flag | Default | Description |
 |------|---------|-------------|
@@ -152,32 +181,74 @@ nexart run sketch.js --renderer local
 - `render.png` — The rendered image
 - `render.snapshot.json` — Snapshot for replay/verify
 
+**Snapshot `environment` field (additive, optional).** Snapshots produced with
+`--renderer local` include an `environment` object describing the render
+environment (`cliVersion`, `sdkVersion`, `protocolVersion`, `node`, `platform`,
+`arch`, `canvas`). It is **descriptive metadata only** — it is never hashed and
+never affects pass/fail. It exists so `replay`/`verify` can warn when the replay
+environment differs from the capture environment. Legacy snapshots (and
+remote-rendered snapshots) omit this field and continue to verify and replay
+exactly as before.
+
 ### verify
 
 Check that a snapshot produces the expected output:
 
 ```bash
+# Verify against the canonical remote renderer (default)
 nexart verify render.snapshot.json
 
+# Verify locally with the deterministic CodeMode renderer (requires `canvas`)
+nexart verify render.snapshot.json --renderer local
+
 # With external code file
 nexart verify render.snapshot.json --code sketch.js
 ```
 
+The local path performs a **real render** (no placeholder) — a missing `canvas`
+dependency fails clearly rather than producing a false pass.
+
 **Exit codes:**
 - `0` — PASS (hashes match)
 - `1` — FAIL (hashes differ or error)
 
 ### replay
 
-Re-execute from a snapshot:
+Re-execute from a snapshot, compare the result against the snapshot, and report
+`PASS`/`FAIL`:
 
 ```bash
-nexart replay render.snapshot.json --out replay.png
+# Deterministic local replay with PASS/FAIL evidence
+nexart replay render.snapshot.json --renderer local --out replay.png \
+  --evidence replay.evidence.json
 
 # With external code file
 nexart replay render.snapshot.json --code sketch.js --out replay.png
 ```
 
+`replay` recomputes the output hash and compares it to the snapshot's
+`outputHash`, and independently checks that the replayed code matches the
+snapshot's `codeHash`. The overall result is `PASS` only when **both** match.
+
+**Options:**
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--out, -o` | replay.png | Output PNG path |
+| `--code, -c` | — | Code file (if not embedded in snapshot) |
+| `--renderer` | remote | `remote` or `local` (deterministic CodeMode renderer) |
+| `--endpoint` | env/localhost:5000 | Remote renderer URL |
+| `--evidence` | — | Write a JSON replay-evidence file (PASS/FAIL + hash comparison) |
+| `--api-key` | env | API key for authentication |
+
+**Exit codes:**
+- `0` — PASS (output and code match the snapshot)
+- `1` — FAIL (output or code differs, or render error)
+
+When `--evidence <file>` is given, `replay` writes a
+`codemode.replay.evidence.v1` JSON document recording the `PASS`/`FAIL` result,
+the expected vs. actual `outputHash` and `codeHash`, the renderer used, and the
+snapshot vs. current `environment` fingerprints (with any differing fields).
+
 ---
 
 ## AI Certification Commands (`nexart ai`)
@@ -400,7 +471,7 @@ bundleIntegrity: FAIL
   "verifiedAt": "2026-04-30T12:00:00.000Z",
   "verifier": "@nexart/ai-execution",
   "cli": {
-    "version": "0.8.0",
+    "version": "0.9.0",
     "sdkVersion": "0.16.1",
     "inputType": "bundle"
   }
@@ -422,7 +493,7 @@ bundleIntegrity: FAIL
   "verifiedAt": "2026-04-30T12:00:00.000Z",
   "verifier": "@nexart/ai-execution",
   "cli": {
-    "version": "0.8.0",
+    "version": "0.9.0",
     "sdkVersion": "0.16.1",
     "inputType": "package",
     "verifiedInnerCer": true,
@@ -433,10 +504,29 @@ bundleIntegrity: FAIL
 
 The top-level fields (`status`, `checks`, `reasonCodes`, `certificateHash`, `bundleType`, `verifiedAt`, `verifier`) are the SDK's `CerVerificationResult` verbatim. The additive `cli` envelope carries CLI-only metadata (`version`, `sdkVersion`, `inputType`, and package-specific flags when applicable).
 
+**Enterprise trust layers (`--anchors`, `--timestamps`):** these flags opt in to the
+**non-evidentiary** secondary-proof layers. They are reported separately and **never** change the
+base verification result or the exit code — they cannot turn a `VERIFIED` bundle into `FAILED` or
+vice-versa.
+
+```bash
+# Report anchor status (VALID / INVALID / NOT PRESENT)
+nexart ai verify cer.json --anchors
+
+# Report anchor + trusted timestamp status with a trust summary
+nexart ai verify cer.json --anchors --timestamps
+```
+
+When enabled, the human-readable output adds a `Layers:` block (Anchoring / Timestamp lines) and a
+`Trust summary` block (Signature / Anchors / Timestamp / Protocol Version); the JSON output adds
+top-level `anchorStatus` and `timestampStatus` objects (`{ checked, valid, errors? }`).
+
 **Options:**
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--json` | false | Machine-readable JSON output |
+| `--anchors` | false | Verify and report anchor status (non-evidentiary; does not affect exit code) |
+| `--timestamps` | false | Verify and report trusted-timestamp status + trust summary (non-evidentiary) |
 
 **Exit codes:**
 - `0` — PASS (inner bundle hash matches)
@@ -444,6 +534,47 @@ The top-level fields (`status`, `checks`, `reasonCodes`, `certificateHash`, `bun
 
 ---
 
+### `nexart ai attach-anchor`
+
+Attach an external anchor (transparency log / TSA / blockchain) to a CER bundle. This is an
+append-only, non-evidentiary operation — it does not re-hash or re-sign the bundle.
+
+```bash
+# Attach an anchor and verify it in one pipe
+nexart ai attach-anchor cer.json anchor.json | nexart ai verify --anchors
+```
+
+---
+
+### `nexart export-verification`
+
+Produce a self-contained verification package that a third party can verify **offline**, without the
+NexArt node or this SDK. It is read-only — nothing is re-hashed or re-signed.
+
+```bash
+# Print a verification package to stdout
+nexart export-verification cer.json
+
+# Resolve the signing public key from a node-keys document and save the package
+nexart export-verification cer.json --node-keys keys.json --out pkg.json
+
+# From stdin
+cat cer.json | nexart export-verification
+```
+
+The package contains `{ bundle, publicKey, verificationInstructions }`, where
+`verificationInstructions` lists the `protocolVersion`, `canonicalMode`, `certificateHash`,
+`signatureAlgorithm`, the present layer flags, and ordered verification steps.
+
+**Options:**
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--out, -o` | — | Save the package to this file (otherwise printed to stdout) |
+| `--node-keys` | — | Path to a `NodeKeysDocument` JSON to resolve the signing public key |
+| `--public-key` | — | Provide the public key directly (takes precedence over `--node-keys`) |
+
+---
+
 ### `nexart ai project-verify` (v0.7.0+)
 
 Verify a **project bundle** (`cer.project.bundle.v1`) locally. No network required. Delegates all verification logic to `verifyProjectBundle()` from `@nexart/ai-execution` — the canonical source of truth for project bundle semantics. The CLI provides the command surface and output formatting.

package/dist/index.d.ts

@@ -145,32 +145,44 @@ export declare function aiCertifyCommand(file: string | undefined, opts: {
     apiKey?: string;
     signalsFile?: string;
 }, fetchFn?: typeof fetch, stdinReader?: () => Promise<string>): Promise<void>;
-/**
- * nexart ai verify — Read a CER bundle or CER package JSON from file or stdin,
- * delegate verification to verifyAiCerBundleDetailed() from @nexart/ai-execution,
- * and report the protocol layer results.
- *
- * The CLI does ZERO crypto here. It only:
- *   1. parses input
- *   2. unwraps a CER package to its inner CER bundle (via SDK's isCerPackage / getCerFromPackage)
- *   3. calls verifyAiCerBundleDetailed(bundle)
- *   4. formats the SDK's CerVerificationResult for human / JSON output
- *
- * The three SDK protocol layers are reported INDEPENDENTLY (no aggregation):
- *   - bundleIntegrity   (Integrity layer:  certificate hash recomputation)
- *   - nodeSignature     (Receipt layer:    node attestation signature validity)
- *   - receiptConsistency (Envelope layer:  bundle/receipt envelope consistency)
- *
- * Each layer is PASS / FAIL / SKIPPED. SDK reason codes are passed through
- * unmodified. Exit code is driven by the SDK's `status` field (VERIFIED → 0,
- * anything else → 1).
- *
- * --json prints the SDK's CerVerificationResult verbatim, plus a minimal
- * `cli` envelope describing input handling. The SDK fields are never rewritten
- * or reinterpreted.
- */
 export declare function aiVerifyCommand(file: string | undefined, opts: {
     json: boolean;
+    anchors?: boolean;
+    timestamps?: boolean;
+}, stdinReader?: () => Promise<string>): Promise<void>;
+/**
+ * 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 declare function aiAttachAnchorCommand(bundleFile: string, anchorFile: string, opts: {
+    out?: string;
+}): Promise<void>;
+/**
+ * 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 declare function exportVerificationCommand(file: string | undefined, opts: {
+    out?: string;
+    nodeKeys?: string;
+    publicKey?: string;
 }, stdinReader?: () => Promise<string>): Promise<void>;
 /**
  * nexart ai project-verify — Read a cer.project.bundle.v1 JSON from file or stdin,

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAYH,OAAO,EAGL,cAAc,IAAI,iBAAiB,EAYpC,MAAM,sBAAsB,CAAC;AAgmB9B;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAerD;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,OAAO,CAAC,CA0BlB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,GAAE,OAAO,KAAwB,GACvC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAoB5C;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,0BAAoB,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,EAAE,CAwB9D;AAuDD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,EACD,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,IAAI,CAAC,CAuCf;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,EACD,OAAO,GAAE,OAAO,KAAwB,EACxC,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,IAAI,CAAC,CA8Cf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,EACD,OAAO,GAAE,OAAO,KAAwB,EACxC,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,IAAI,CAAC,CA8Df;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,EACvB,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,IAAI,CAAC,CA0Ef;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,EACvB,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,IAAI,CAAC,CAwBf"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAYH,OAAO,EAGL,cAAc,IAAI,iBAAiB,EAoBpC,MAAM,sBAAsB,CAAC;AAi0B9B;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAerD;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,OAAO,CAAC,CA0BlB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,GAAE,OAAO,KAAwB,GACvC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAoB5C;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,0BAAoB,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,EAAE,CAwB9D;AAuDD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,EACD,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,IAAI,CAAC,CAuCf;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,EACD,OAAO,GAAE,OAAO,KAAwB,EACxC,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,IAAI,CAAC,CA8Cf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,EACD,OAAO,GAAE,OAAO,KAAwB,EACxC,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,IAAI,CAAC,CA8Df;AAqCD,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,EAChE,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,IAAI,CAAC,CA+Hf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACrB,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAC7D,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,IAAI,CAAC,CAqCf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,EACvB,WAAW,GAAE,MAAM,OAAO,CAAC,MAAM,CAAiB,GACjD,OAAO,CAAC,IAAI,CAAC,CAwBf"}