@nexart/codemode-sdk 1.8.3 → 1.9.0

package/CHANGELOG.md

@@ -4,6 +4,95 @@ All notable changes to @nexart/codemode-sdk will be documented in this file.
 
 ---
 
+## [1.9.0] — 2026-02-25
+
+### Added — Attestation Parity (Reason Codes + Signed Receipt Verification)
+
+**Feature Release — Additive only. No existing APIs changed.**
+
+Brings the Code Mode SDK attestation layer to parity with `@nexart/ai-execution` v0.5.0.
+
+#### New Types (`types.ts`)
+- `CodeVerifyCode` — stable string-valued reason code enum (12 codes)
+- `CodeVerificationResult` — `{ ok, code, details? }` returned by all verification functions
+- `NodeReceiptVerifyResult` — alias of `CodeVerificationResult` for receipt-specific call sites
+- `NodeKeysDocument` — shape of `/.well-known/nexart-node.json`
+- `SignedAttestationReceipt` — payload signed by the attestation node
+- `CodeAttestationReceipt` — normalised receipt extracted from any bundle layout
+
+#### New Module — `nodeReceipt.ts`
+- `verifyNodeReceiptSignature({ receipt, signatureB64Url, key })` — offline Ed25519 verification (browser + Node, @noble/ed25519)
+- `fetchNodeKeys(nodeUrl)` — fetch `NodeKeysDocument` from attestation node
+- `selectNodeKey(doc, kid?)` — select key by explicit kid → activeKid → first
+- `verifyBundleAttestation(bundle, { nodeUrl, kid? })` — full offline attestation check with certificateHash cross-check (receipt-swap prevention), all three bundle layouts supported
+
+#### New Module — `attestation.ts`
+- `getAttestationReceipt(bundle)` — normalised receipt or null; recognises Layout A (top-level), Layout B (nested envelope), Layout C (legacy flat fields)
+- `hasAttestation(bundle)` — boolean shorthand
+
+#### New Module — `canonicalJson.ts`
+- `toCanonicalJson(value)` — deterministic sorted-key JSON serialisation used for signing/verifying receipt bytes
+
+#### New Dependencies
+- `@noble/ed25519` ^3.0.0 (browser-compatible Ed25519) — declared in `dependencies` (installed per-package, no hoisting required)
+- `@noble/hashes` ^1.7.0 (sha512 for noble ed25519) — same
+- `@types/node` ^20.0.0 (dev) — added to `devDependencies` so `Buffer`/`process`/`require` resolve correctly under TypeScript strict mode; prevents "works only when hoisted" failures
+
+#### TypeScript Config
+- `"types": ["node"]` added to both `tsconfig.json` and `tsconfig.types.json` `compilerOptions`
+- `nodeReceipt.ts`, `attestation.ts`, `canonicalJson.ts` added explicitly to both `files` arrays
+
+#### Tests
+- `tests/attestation.test.ts` — 25 tests covering all code paths, error cases, and all three bundle layouts; `npm run test:attestation`
+
+#### Fixtures
+- `fixtures/attestation/keys-v1.json`
+- `fixtures/attestation/receipt-v1.json`
+- `fixtures/attestation/receipt-v1.sig`
+- `fixtures/attestation/receipt-v1.pub`
+
+#### Docs
+- README: new Attestation & Verification section with reason codes, `verifyBundleAttestation` usage, node keys endpoint, and receipt extraction helpers
+
+#### Unchanged
+- No protocol changes (v1.2.0)
+- No changes to existing hashing or canonicalisation semantics
+- All existing `executeCodeMode`, `createRuntime`, `validateSnapshot` APIs unchanged
+- All existing smoke tests and execution boundary tests pass
+
+---
+
+## [1.8.4] — 2026-01-25
+
+### Fixed — Node ESM Compatibility
+
+**Patch Release — Packaging Fix Only**
+
+This release fixes Node.js ESM compatibility by switching to dual build output (ESM + CJS) via tsup.
+
+#### Breaking Change (Internal Only)
+- Dist structure changed from `dist/entry/*.js` to `dist/esm/*.js` and `dist/cjs/*.js`
+- Types now in `dist/types/`
+- Exports map updated to support both `import` and `require`
+
+#### Fixes
+- Node ESM: Imports now resolve correctly (no more missing .js extension errors)
+- Node CJS: `require('@nexart/codemode-sdk')` now works
+- Bundlers: Continue to work via exports map
+
+#### Build Changes
+- Added tsup for dual ESM/CJS bundling
+- Types emitted separately via tsc
+- New smoke tests: `scripts/smoke-node.mjs` and `scripts/smoke-node.cjs`
+
+#### Unchanged
+- No protocol changes (v1.2.0)
+- No runtime API changes
+- No behavior changes
+- Full backward compatibility with v1.8.3 API
+
+---
+
 ## [1.8.3] — 2026-01-25
 
 ### Changed — CLI v0.2 Remote Renderer + Version Bump

package/README.md

@@ -1,6 +1,6 @@
 # @nexart/codemode-sdk
 
-**Version: 1.8.3 (Protocol v1.2.0)**
+**Version: 1.9.0 (Protocol v1.2.0)**
 
 A deterministic execution runtime for reproducible, verifiable computation.
 
@@ -33,6 +33,43 @@ A deterministic execution runtime for reproducible, verifiable computation.
 
 ---
 
+## Quickstart: CLI Examples
+
+The SDK includes ready-to-run example sketches. Use the `@nexart/cli` to render them via the canonical renderer.
+
+### Setup
+
+```bash
+# Set up authentication for remote rendering
+export NEXART_RENDERER_ENDPOINT=https://nexart-canonical-renderer-production.up.railway.app
+export NEXART_API_KEY=nx_live_your_key_here
+```
+
+### Run Examples
+
+```bash
+# Run the main example sketch
+npx @nexart/cli run ./examples/sketch.js --seed 12345 --include-code --out ./out.png
+
+# Verify the output is deterministic
+npx @nexart/cli verify ./out.snapshot.json
+# Output: [nexart] Result: PASS
+```
+
+### Example Sketches
+
+| File | Description |
+|------|-------------|
+| `examples/sketch.js` | Main example — VAR controls + random palette, protocol-safe |
+| `examples/sketch-minimal.js` | Simple shapes, no randomness — identical every run |
+| `examples/sketch-vars.js` | Uses VAR + random() — demonstrates determinism |
+
+### Canonical Size
+
+The canonical renderer enforces a fixed canvas size of **1950x2400**. Do not pass custom `--width` or `--height` to the canonical endpoint — the size is enforced server-side for consistent, verifiable output.
+
+---
+
 ## What This SDK Does
 
 This SDK provides a **deterministic runtime layer** for executing code that must produce identical output given identical inputs — across environments, over time, and under verification.
@@ -236,7 +273,7 @@ These are examples — the SDK is designed for any system requiring deterministi
 |----------|-------|
 | Protocol Version | v1.2.0 |
 | Status | **STABLE** |
-| SDK Version | 1.8.3 |
+| SDK Version | 1.8.4 |
 
 **Core protocol surface is frozen. Breaking changes require v2.0.0.**
 
@@ -434,6 +471,88 @@ The following are rejected with `[Code Mode Protocol Error]`:
 
 ---
 
+## Attestation & Verification (v1.9.0)
+
+### Verification Reason Codes
+
+Every verification function returns a `CodeVerificationResult` with a stable, machine-readable `code`:
+
+```typescript
+import { CodeVerifyCode } from '@nexart/codemode-sdk';
+
+// Stable string codes — safe to switch on, persist to storage, or compare:
+// CodeVerifyCode.OK
+// CodeVerifyCode.CERTIFICATE_HASH_MISMATCH
+// CodeVerifyCode.SNAPSHOT_HASH_MISMATCH
+// CodeVerifyCode.RENDER_HASH_MISMATCH
+// CodeVerifyCode.INVALID_SHA256_FORMAT
+// CodeVerifyCode.CANONICALIZATION_ERROR
+// CodeVerifyCode.SCHEMA_ERROR
+// CodeVerifyCode.NODE_RECEIPT_MISSING
+// CodeVerifyCode.NODE_RECEIPT_KEY_NOT_FOUND
+// CodeVerifyCode.NODE_RECEIPT_INVALID_SIGNATURE
+// CodeVerifyCode.NODE_RECEIPT_KEY_FORMAT_UNSUPPORTED
+// CodeVerifyCode.UNKNOWN_ERROR
+```
+
+### Signed Node Receipt Verification (offline)
+
+Verify that a Code Mode snapshot bundle was attested by an authorised NexArt attestation node — entirely offline, browser and Node.js compatible:
+
+```typescript
+import { verifyBundleAttestation } from '@nexart/codemode-sdk';
+
+const res = await verifyBundleAttestation(bundle, { nodeUrl: 'https://node.nexart.dev' });
+console.log(res.ok, res.code);
+// true  "OK"
+// false "CERTIFICATE_HASH_MISMATCH"  (receipt doesn't match bundle)
+// false "NODE_RECEIPT_INVALID_SIGNATURE"  (tampered receipt)
+```
+
+`verifyBundleAttestation` performs these steps automatically:
+1. Extracts the signed receipt and signature from the bundle (top-level or nested layout).
+2. Cross-checks `receipt.certificateHash === bundle.certificateHash` to prevent receipt-swapping attacks.
+3. Fetches the node's public keys from `/.well-known/nexart-node.json`.
+4. Selects the appropriate key (by `kid`, `activeKid`, or first available).
+5. Verifies the Ed25519 signature over the canonical JSON bytes of the receipt.
+
+### Node Keys Endpoint
+
+Public keys are discovered automatically from:
+
+```
+GET {nodeUrl}/.well-known/nexart-node.json
+```
+
+You can also fetch or inspect keys directly:
+
+```typescript
+import { fetchNodeKeys, selectNodeKey } from '@nexart/codemode-sdk';
+
+const doc = await fetchNodeKeys('https://node.nexart.dev');
+const { key } = selectNodeKey(doc, 'kid-optional');
+```
+
+### Receipt Extraction Helpers
+
+Inspect bundles without performing full verification:
+
+```typescript
+import { getAttestationReceipt, hasAttestation } from '@nexart/codemode-sdk';
+
+if (hasAttestation(bundle)) {
+  const receipt = getAttestationReceipt(bundle);
+  console.log(receipt?.attestationId, receipt?.nodeId);
+}
+```
+
+Both helpers recognise:
+- **Layout A** — `bundle.receipt` + `bundle.signature` (signed envelope)
+- **Layout B** — `bundle.attestation.receipt` + `bundle.attestation.signature` (nested envelope)
+- **Layout C** — legacy flat fields (`bundle.attestationId`, `bundle.nodeRuntimeHash`, …)
+
+---
+
 ## Examples
 
 ```bash