# NexArt Architecture URL: https://docs.nexart.io/docs/architecture How NexArt fits together: SDK sealing, snapshot construction, certificate hashing, attestation node signing, and the independent verification path used by. This flow reflects the system boundaries (SDK, CLI, Node). ## NexArt Integration (Canonical Flow) Flow: - Capture execution input - Seal locally (offline) - Verify locally - (Optional) Certify via node - Verify again Verification outcomes: - Sealed → Integrity: PASS, Receipt: SKIPPED, Envelope: SKIPPED - Certified → Integrity: PASS, Receipt: PASS, Envelope: PASS Rules: - Sealing does NOT require a node - Certification is OPTIONAL - Verification does NOT require trust - SKIPPED is expected for local artifacts and is NOT a failure Do NOT: - call the node before sealing - recompute hashes manually - modify bundles after sealing - treat SKIPPED as failure Mental model - Capture is producer-side. Hashing is deterministic. Verification is independent. - certificateHash binds the whitelist. Everything else is mutable metadata. - Bundles are immutable. State transitions live outside the bundle. ## Copy-Paste Test Harness The fastest way to validate an integration against the canonical pipeline. One script, one set of environment variables, one expected output: three PASS lines for Integrity, Receipt, and Envelope. Verify Your First Certified Execution (2 minutes) Copy this script, set two environment variables, run it. If you see three PASS lines, NexArt is working end-to-end. No abstractions, no helpers, no partial snippets. 1. Install ``` npm install @nexart/ai-execution export NEXART_NODE_ENDPOINT="https://node.nexart.io" export NEXART_API_KEY="" ``` 2. test-harness.ts (single file, copy as-is) ``` import { certifyAndAttestDecision, verifyAiCerBundleDetailed, } from "@nexart/ai-execution"; async function main() { // Seal + attest in one node round-trip. const { bundle, receipt } = await certifyAndAttestDecision( { provider: "openai", model: "gpt-4o-mini", prompt: "Should this refund be approved?", input: { messages: [{ role: "user", content: "Should this refund be approved?" }] }, parameters: { temperature: 0, maxTokens: 1024, topP: null, seed: null }, output: { decision: "approve", reason: "policy_passed" }, }, { nodeUrl: process.env.NEXART_NODE_ENDPOINT!, apiKey: process.env.NEXART_API_KEY!, }, ); const certificateHash = bundle.certificateHash; const verificationUrl = `https://verify.nexart.io/c/${certificateHash}`; console.log("certificateHash :", certificateHash); console.log("attestationId :", receipt.attestationId); console.log("verificationUrl :", verificationUrl); // Independent verification of the returned bundle. No trust required. const report = await verifyAiCerBundleDetailed(bundle); console.log("Integrity (Layer 1) :", report.checks.bundleIntegrity); console.log("Receipt (Layer 2) :", report.checks.nodeSignature); console.log("Envelope (Layer 3) :", report.checks.receiptConsistency); } main().catch((err) => { console.error("FAILED:", err); process.exit(1); }); ``` 3. Run ``` npx tsx test-harness.ts ``` Expected output (success) ``` certificateHash : sha256:9f2b1c8e4a7d6f3b0c5e8a1d2f4b6c8e9a0d3f5b7c2e4a6d8f1b3c5e7a9d0f2b verificationUrl : https://verify.nexart.io/c/sha256:9f2b1c8e4a7d6f3b0c5e8a1d2f4b6c8e9a0d3f5b7c2e4a6d8f1b3c5e7a9d0f2b Integrity (Layer 1) : PASS Receipt (Layer 2) : PASS Envelope (Layer 3) : PASS ``` Three PASS lines mean the bundle is byte-identical to what the node attested, the receipt signature validates against the node key, and the verification envelope binds the attestation projection to the bundle. Expected verification result — Sealed bundle (local, offline) integrity: PASS receipt: SKIPPED envelope: SKIPPED Produced by `nexart ai seal` or the SDK`sealCer()`. No node call, no API key. Expected verification result — Certified bundle (node-attested) integrity: PASS receipt: PASS envelope: PASS Produced by `nexart ai certify` or the SDK`certifyAndAttestDecision()`. Node returns receipt + envelope. If any layer returns FAIL, the integration is incorrect. SKIPPED is expected for local (sealed) artifacts and MUST NOT be treated as a failure. If something fails - Integrity FAIL (Layer 1) Payload mismatch. The recomputed `certificateHash` does not match the bundle. Cause: the bundle was mutated, re-serialized with a different canonicalization, or the `version` field was changed. The bundle MUST be persisted byte-for-byte after certification. - Receipt FAIL (Layer 2) Node or auth issue. The receipt signature did not validate against the node key. Cause: wrong `NEXART_NODE_ENDPOINT`, missing or invalid `NEXART_API_KEY`, or the node key published at `/.well-known/nexart-node.json` does not match the receipt `kid`. - Envelope FAIL (Layer 3) Bundle mutation after attestation. The envelope signature covers a 5-field attestation projection (`attestationId`, `attestedAt`, `kid`, `nodeRuntimeHash`, `protocolVersion`). If any of those fields were altered or stripped, the envelope cannot validate. Do not modify `meta.attestation` after sealing. ## Audience and scope This page is the developer reference for the NexArt protocol. It defines the exact structure of a Certified Execution Record (CER), the inputs to the certificateHash, the verification layers, and the invariants that all producers, attestation nodes, and verifiers MUST honor. It is intentionally precise and aligned with the protocol. Where RFC keywords (MUST, MUST NOT, SHOULD) appear, they carry their normal protocol meaning. ## Component ownership boundaries The system has three components with strict, non-overlapping responsibilities. The CLI contains zero CER cryptographic logic. All hashing, canonicalization, and verification is implemented in the SDK. - SDK (`@nexart/ai-execution@1.2.0`) owns: snapshot creation (`createSnapshot`), local sealing (`sealCer`), protocol-bound canonicalization (nexart-v1 / jcs-v1), SHA-256 hashing, and verification logic (`verifyAiCerBundleDetailed`). - CLI (`@nexart/cli@1.1.0`) owns: the command surface (`ai seal`, `ai certify`, `ai verify`), file I/O, argument parsing, and output formatting. It delegates every cryptographic operation to the SDK. - Node (attestation node) owns: bundle attestation (`POST /v1/cer/ai/certify`), Ed25519 receipt signing, verification envelope signature, and public key publication at `/.well-known/nexart-node.json`. ## End-to-end flow The pipeline has five stages. Stages 1 to 3 are local to the producer (SDK or CLI). Stage 4 is optional and adds node attestation. Stage 5 is independent and may be performed by anyone. The canonical workflow is: create input → seal → verify → (optional) certify → verify. ### 1. Execution capture The producer executes an AI call or a deterministic computation and captures the observable evidence: model identity, inputs, outputs, parameters, and any contextual signals. Inputs and outputs are not stored in the bundle directly; they are reduced to SHA-256 digests (`inputHash`, `outputHash`) inside`snapshot`. Capture is the producer's responsibility. NexArt does not guarantee completeness of what was captured. It guarantees that what was captured cannot be altered without detection. ### 2. CER creation (local sealing) The producer assembles the canonical CER bundle and computes the `certificateHash`. This stage is fully offline: it requires no network access and no API key. In SDK form this is `sealCer()`; in CLI form it is `nexart ai seal`. The output is a sealed CER bundle (integrity only; no attestation). Required top-level fields: - `bundleType` - constant string `"cer.ai.execution.v1"` for AI executions. - `version` - bundle schema/format version (currently `"0.1"`). This is NOT the canonicalization protocol; that is `snapshot.protocolVersion`. - `createdAt` - ISO 8601 timestamp in UTC. - `snapshot` - object containing `model`, `inputHash`, `outputHash`, and `metadata` (e.g. `appId`, `projectId`). - `context` - optional. Structured signals included in the hash when present. See Context Signals. - `contextSummary` - optional, summary of context. Included in the hash when present. - `policyEvaluation` - optional. Captured policy decision result. Included in the hash when present. ### 3. Hash computation (whitelist + protocol-bound canonicalization) The `certificateHash` is computed as SHA-256 over the canonicalized projection of the bundle to a strict whitelist. The canonicalization profile is selected by `snapshot.protocolVersion` (`1.2.0` → `nexart-v1` (legacy default); `1.3.0` and `1.3.1` → `jcs-v1` (RFC 8785)). The result is written into the bundle as`certificateHash`. The hash field itself is excluded from its own input. Producers and verifiers MUST use identical canonicalization for the bundle's protocol profile. Implementations MUST NOT reconstruct, normalize, strip, or add fields beyond the whitelist projection. ### 4. Node certification (optional) A sealed bundle (Stage 2) is already a valid CER. Certification is optional and adds independently verifiable node attestation. After certification, the bundle is certified rather than only sealed. The producer may submit the bundle to an attestation node (`POST /v1/cer/ai/certify`). The node validates the bundle and issues a deterministic, Ed25519-signed receipt that references the bundle's`certificateHash`. The receipt and signature are stored at`bundle.meta.attestation` with fields `receipt`, `signature`, and `kid`. Attestation does not modify any field covered by the whitelist. The`certificateHash` MUST remain unchanged after attestation. ### 5. Verification Any party with the bundle and the node's published public keys can verify. The verifier runs up to four checks; each returns `PASS`, `FAIL`, or `SKIPPED`. The overall verification status is `VERIFIED`, `FAILED`, or `NOT_FOUND`. ## Exact payload contract The canonical AI CER bundle shape: CER bundle (cer.ai.execution.v1) ``` { "bundleType": "cer.ai.execution.v1", "version": "0.1", "createdAt": "2026-04-30T10:15:32.000Z", "snapshot": { "model": "gpt-4o-mini", "inputHash": "sha256:7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069", "outputHash": "sha256:9c56cc51b374c3ba189210d5b6d4bf57790d351c96c47c02190ecf1e430635ab", "metadata": { "appId": "app_01HX...", "projectId": "proj_01HX..." } }, "context": { "user": "anon", "policy": "approve_v1" }, "contextSummary": "Policy review of automated report.", "certificateHash": "sha256:...", "meta": { "attestation": { "receipt": { "certificateHash": "sha256:...", "timestamp": "2026-04-30T10:15:32.500Z", "nodeId": "node_nexart_prod_01", "kid": "key_01HX..." }, "signature": "", "kid": "key_01HX..." }, "verificationEnvelope": { }, "verificationEnvelopeSignature": "" } } ``` ### Field rules - bundleType - REQUIRED. Constant. Identifies the bundle schema. For AI executions, exactly `"cer.ai.execution.v1"`. Hashed. - version - REQUIRED. Bundle schema version. Hashed. Verifiers MUST refuse to upgrade or downgrade the value. - createdAt - REQUIRED. ISO 8601 UTC timestamp at the moment of CER creation. Hashed. - snapshot - REQUIRED. Hashed. Carries `model`, `inputHash`, `outputHash`, and `metadata`. Sub-fields are stable; producers MUST NOT inject mutable runtime data into snapshot. - context - OPTIONAL. Hashed when present. Used for structured signals that bind to the certificateHash. - contextSummary - OPTIONAL. Hashed when present. Human-readable companion to `context`. - certificateHash - REQUIRED in the persisted bundle. Excluded from its own hash input. - meta - OPTIONAL. Excluded from hash. Carries attestation, verification envelope, declaration, and any non-normative metadata. ## Hash whitelist (normative) The certificateHash input is the canonicalization (profile selected by `snapshot.protocolVersion`: `nexart-v1` for 1.2.0; `jcs-v1` / RFC 8785 for 1.3.0 and 1.3.1) of an object containing only: - `bundleType` - `version` - `createdAt` - `snapshot` - `context` (only if present in bundle) - `contextSummary` (only if present in bundle) - `policyEvaluation` (only if present in bundle) ### Excluded from the hash input - `certificateHash` - `meta` and all subfields, including `meta.attestation`, `meta.verificationEnvelope`, `meta.verificationEnvelopeSignature` - `declaration` - `receipt` (top-level convenience copy, when present) - any unknown fields not in the whitelist ## Verification layers ### Layer 1 - certificateHash (Bundle Integrity) The verifier projects the received bundle to the whitelist, canonicalizes with JCS, and computes SHA-256. The result MUST equal the bundle's`certificateHash`. Any difference is `FAIL`. This layer is always evaluated. ### Layer 2 - Receipt signature (Node Signature + Receipt Consistency) When `meta.attestation` is present, the verifier: - Resolves the node public key by `kid` from `node.nexart.io/.well-known/nexart-node.json`. - Validates the Ed25519 signature over the canonical receipt payload. - Confirms `receipt.certificateHash` equals the bundle's `certificateHash`. If `meta.attestation` is absent, both checks return`SKIPPED`. Skipping is not a failure of integrity. ### Layer 3 - Verification envelope (v0.16.1) Newer bundles MAY include`meta.verificationEnvelope` and`meta.verificationEnvelopeSignature`. The envelope signature covers the signable payload `{ attestation, bundle }`, where `attestation` = `{ attestationId, attestedAt, kid, nodeRuntimeHash, protocolVersion }` and `bundle` = `{ bundleType, version, createdAt, snapshot, context?, contextSummary? }` (the bundle whitelist projection used by Layer 1, minus `policyEvaluation`). Mutating any field in either projection — not only the 5 attestation fields — invalidates the envelope. Excluded from envelope coverage: `certificateHash`, `meta`, `receipt`, `verificationEnvelope*`, and unknown keys. Failure of the envelope MUST NOT be reported as failure of bundle integrity. Historical artifacts without an envelope return`SKIPPED` for this layer (compatibility fallback). Note: `policyEvaluation` is covered by Layer 1 (it contributes to `certificateHash`) but is NOT part of the Layer 3 bundle projection. The two projections are not identical; verifier authors MUST NOT assume `policyEvaluation` is envelope-signed. For the full layer specification and edge cases, see AI CER Verification Layers and Verification Statuses and Errors. ## Critical constraints ### No mutation A CER bundle MUST NOT be mutated after creation. Lifecycle state changes (`Active`, `Archived`, `Hidden`, `Deleted`) are recorded in registry state external to the bundle. Republishing a modified bundle produces a new`certificateHash` and is a different record. ### Idempotency Given identical inputs to the canonicalization and hashing pipeline, every conformant implementation MUST produce the same`certificateHash`. Re-issuing the same execution capture MUST yield bit-identical hashes. Producers SHOULD treat `certificateHash` as the deduplication key for downstream systems. ### Canonicalization (protocol-bound) Canonicalization is bound to the bundle's `snapshot.protocolVersion`. `1.2.0` uses `nexart-v1` (legacy default, custom canonicalization). `1.3.0` and `1.3.1` both use `jcs-v1` (RFC 8785, standards-based); 1.3.1 is the confidential-execution protocol and is the node's advertised default. Verifiers MUST select the profile by `snapshot.protocolVersion`, apply the whitelist projection to the bundle as received, and canonicalize without further normalization. There is no tolerant parsing and no universal default. ### Independence of verification Verification MUST be possible without contacting NexArt's APIs. The bundle plus the node's published public keys are sufficient. Theverify.nexart.io portal is a convenience layer; it runs the same checks any client can run. ## Sealed vs Certified Two valid CER states. Sealed is produced offline by the SDK or CLI and proves integrity only. Certified adds an Ed25519 receipt and a verification envelope from the attestation node, making the bundle independently verifiable end-to-end. Certification does not change the `certificateHash`. ### Sealed vs Certified | Property | Sealed (local) | Certified (node) | | --- | --- | --- | | Origin | SDK / CLI, fully offline | Attestation node (POST /v1/cer/ai/certify) | | API key required | no | yes (NEXART_API_KEY) | | certificateHash | present | present (identical input → identical hash) | | meta.attestation (receipt) | absent | present, Ed25519-signed | | meta.verificationEnvelope | absent | present (v0.16.1) | | Layer 1 — Integrity | PASS | PASS | | Layer 2 — Receipt | SKIPPED | PASS | | Layer 3 — Envelope | SKIPPED | PASS | | Third-party verifiable | integrity only | yes (attested) | SKIPPED is not a failure. A sealed bundle is a valid CER; it simply has not been attested by a node. Certification adds Layers 2 and 3 without changing the`certificateHash`. ## What NexArt guarantees - Execution integrity — the recorded execution cannot be modified after sealing without breaking the `certificateHash`. - Tamper detection — any change to a hashed field is detectable by recomputation against the canonicalized whitelist projection (per the bundle's protocol profile). - Independent verification — any party can verify a bundle using only the bundle and the node's published public keys. No NexArt API access required. ## What NexArt does not guarantee - Output correctness — NexArt does not validate whether the captured output is right, useful, or safe. - Model validity — NexArt does not certify the model, its weights, or its behavior. - Deterministic replay — NexArt does not guarantee that re-running the same input produces the same output. It records what happened; it does not reproduce it. ## Authoritative references - Certified Execution Records - bundle definition. - certificateHash vs projectHash - hash scope and algorithm. - CER Protocol - normative protocol specification. - AI CER Verification Layers - layer-by-layer semantics. - AI CER Package Format - transport envelope. - Attestation Node - node contract and key publication. - Verification Semantics - status mapping and error codes.