# NexArt Documentation: Full Text > Part 1 of 5. This part contains 16 of 77 pages. > IMPORTANT: this is not the whole corpus. Continue with https://docs.nexart.io/llms-full.txt?part=2 > Part index: https://docs.nexart.io/llms-full.txt?parts > Single pages are also available as markdown at https://docs.nexart.io/md/.md ## Pages in this part - https://docs.nexart.io/docs/evidence-bridge - https://docs.nexart.io/docs/evidence-bridge/how-it-works - https://docs.nexart.io/docs/evidence-bridge/mapping-profiles - https://docs.nexart.io/docs/evidence-bridge/ai-execution - https://docs.nexart.io/docs/evidence-bridge/operational-execution - https://docs.nexart.io/docs/evidence-bridge/custom-json - https://docs.nexart.io/docs/evidence-bridge/authentication - https://docs.nexart.io/docs/evidence-bridge/confidential-evidence - https://docs.nexart.io/docs/evidence-bridge/attestation - https://docs.nexart.io/docs/evidence-bridge/integration-guide - https://docs.nexart.io/docs/evidence-bridge/security - https://docs.nexart.io/docs/what-is-nexart - https://docs.nexart.io/docs/getting-started - https://docs.nexart.io/docs/quickstart - https://docs.nexart.io/docs/architecture - https://docs.nexart.io/docs/cer-protocol --- # Evidence Bridge URL: https://docs.nexart.io/docs/evidence-bridge Evidence Bridge maps an existing JSON execution payload into a NexArt evidence family through a reviewed deterministic profile, then seals, verifies and submits the record for attestation. Evidence Bridge lets existing systems produce NexArt evidence without requiring them to adopt a NexArt-native payload format. Most applications, agents, workflow systems and automation platforms already emit execution data. The challenge is that every system structures that data differently. Evidence Bridge sits between the source system and NexArt's evidence formats. It receives an existing JSON execution payload, applies a reviewed deterministic mapping profile, checks whether the mapped event contains enough semantics for a supported NexArt evidence family, creates the appropriate confidential Certified Execution Record, verifies it locally, and submits the exact record to the NexArt Attestation Node. ## Architecture Evidence Bridge pipeline ``` Source system | Existing JSON payload | Evidence Bridge | Deterministic mapping profile | Evidence eligibility | +------------------------------+ | AI Execution V2 | | Operational Execution V1 | +------------------------------+ | Confidential CER | Local cryptographic verification | NexArt Attestation Node | Signed Node receipt | Independent RFC 3161 timestamp ``` Evidence Bridge adapts evidence. It does not decide whether an action was good, compliant, authorized, or correct. The source system remains responsible for producing the execution facts it reports. ## Why Evidence Bridge exists Without Evidence Bridge, every system integrating with NexArt would need to construct NexArt evidence records directly. That works well for systems designed around the NexArt SDKs, but many existing platforms already have their own execution formats. For example, one system might report: ``` { "execution_id": "exec_123", "action_type": "NODE_ISOLATION", "outcome": "APPLIED" } ``` while another might report: ``` { "runId": "run_456", "operation": "isolate_node", "status": "success" } ``` The source semantics may be similar even though the JSON structures are completely different. Evidence Bridge solves the adaptation problem by keeping the mapping layer separate from the evidence layer: ``` Source schema | Mapping | Normalized execution semantics | Evidence target ``` This separation means NexArt does not need a new cryptographic protocol for every source platform. ## Map once. Execute deterministically. Mapping profiles are created and reviewed before production use. AI may eventually assist with suggesting mappings during onboarding, but AI is not part of the production mapping path. Once a mapping profile is published, transformations are deterministic. Production rule ``` same source payload + same mapping profile revision + same mapping engine version = same mapped result ``` Mapping execution: - does not call an LLM - does not execute arbitrary JavaScript - does not perform network lookups - does not allow user-supplied executable functions This keeps the transformation reproducible and auditable. ## Supported evidence targets AI Execution V2. Record family `cer.ai.execution.v2`, protocol `1.3.1`, SDK `@nexart/ai-execution`. Use when the source represents an actual AI or model execution. See AI Execution through Evidence Bridge. Operational Execution. Canonical record family `cer.consequential.execution.v1`, protocol `1.3.1`, SDK `@nexart/consequential-execution`. Use when the source represents a consequential system action or state-changing execution: infrastructure remediation, deployment, workflow state changes, financial operation execution, agent tool actions that actually execute, automation actions, resource isolation, configuration changes. See Operational Execution. A tool call, authorization decision, proposal, or model recommendation is not automatically a consequential execution. The source must contain sufficient evidence that an execution was attempted and report its outcome. ## System ownership Three services, three responsibilities ``` nexart.io Control Plane / Dashboard ------------------------- Identity Plans API keys Entitlements | short-lived handoff | v bridge.nexart.io Evidence Bridge ----------------- Mapping profiles Source hashing Deterministic mapping Target eligibility Confidential CER creation Local verification | exact sealed CER | v node.nexart.io Attestation Node ----------------- CER verification Ed25519 receipt RFC 3161 timestamp Public resolution ``` Machine clients ``` Source application | | nx_live_ API key v Evidence Bridge | | exact customer-attributed CER v NexArt Node ``` ## Where to go next - How it works covers digests, provenance, idempotency and the status model. - Mapping profiles covers the profile lifecycle and the deterministic transforms. - Integration guide covers the quick start, request snippets and troubleshooting. - Security and trust boundaries states precisely what Evidence Bridge can and cannot prove. --- # How Evidence Bridge Works URL: https://docs.nexart.io/docs/evidence-bridge/how-it-works The Evidence Bridge pipeline in detail: raw and canonical source digests, transformation provenance, ephemeral payload handling, certificate identity, idempotent retries and the six status dimensions. ## The pipeline ``` receive -> hash -> parse -> map -> eligibility -> create CER -> verify locally -> persist -> attest -> verify receipt -> timestamp state ``` ## Source digests and provenance Evidence Bridge records two different source digests. ### Raw source digest This is calculated from the exact HTTP request bytes received by Evidence Bridge. ``` sha256: ``` Changing whitespace or JSON property order changes the raw digest. ### Canonical source digest The JSON is parsed and canonicalized using the Bridge's deterministic canonicalization rules before hashing. ``` sha256: ``` Equivalent JSON with different whitespace or property ordering can therefore have a different raw digest but the same canonical digest. The raw digest identifies the exact submitted byte representation. The canonical digest identifies the parsed JSON content under canonical serialization. ### Bridge provenance The evidence provenance includes values such as: Conceptual example ``` { "sourceRawDigest": "sha256:...", "sourceCanonicalDigest": "sha256:...", "profileId": "...", "profileRevision": 1, "profileHash": "sha256:...", "engineVersion": 1, "targetConfigHash": "sha256:...", "sourceSystem": "...", "externalEventId": "..." } ``` These values establish the provenance of the Bridge transformation. They do not prove that the source system itself reported the truth. ## Raw payloads are ephemeral by default Evidence Bridge is designed to avoid unnecessary retention of customer source payloads. The normal flow is: ``` receive -> hash -> parse -> map -> create evidence -> discard raw payload ``` Evidence Bridge retains the cryptographic provenance needed to understand how the evidence was produced without requiring permanent storage of the original source JSON. Where confidential evidence requires private opening material, that material is stored separately from the public CER and remains tenant-scoped. Source payloads are never publicly stored. ## One certificate identity ``` Local certificate hash = submitted certificate hash = Node-attested certificate hash ``` Evidence Bridge creates and verifies the CER before sending it to the Node. The Node verifies and attests that exact producer-created CER. The Node does not rebuild the execution record or replace its certificate identity. ## Safe retries Evidence creation and Node attestation are separate operations. Evidence Bridge persists the created CER before Node attestation. If a Node or network request fails, retrying the attestation reuses the same persisted CER and the same certificate hash. It does not reconstruct or reseal the execution. For ingestion idempotency: ``` same tenant + same profile/revision + same idempotency key + same source digest = the authoritative existing result is returned ``` Reusing the same idempotency key for different source content fails rather than silently creating conflicting evidence. ## Bridge status model Evidence Bridge reports six independent status dimensions. They are intentionally separate, because a failure in one does not invalidate the others. Fully successful result ``` Mapping VALID Evidence target Operational Execution V1 CER CREATED Local integrity VERIFIED Node attestation VERIFIED Independent timestamp VERIFIED ``` Node outage ``` Mapping VALID Evidence target Operational Execution V1 CER CREATED Local integrity VERIFIED Node attestation FAILED Independent timestamp NOT_VERIFIED ``` A Node outage does not make the locally created CER invalid. Do not collapse these states into a single generic pass or fail. ## What happens when evidence is incomplete - Unknown mapped outcome: mapping and eligibility fail. - Missing execution ID: target ineligible. - Applied outcome without an applied change: target ineligible. - Authorization-only payload: target unsupported. - Local cryptographic verification failure: the Node is not called. - Wrong or incomplete confidential opening set: the Node is not called. - Node unavailable: the existing CER is retained for retry. - Certificate hash mismatch in the Node response: attestation verification fails. - Unknown Node key: receipt verification fails. - Invalid RFC 3161 chain: the timestamp is not marked VERIFIED. See Attestation and verification for how node receipts and timestamp evidence are checked. --- # Mapping Profiles URL: https://docs.nexart.io/docs/evidence-bridge/mapping-profiles Mapping profiles are reviewed before production and immutable once published: draft, review, publish, ingest, with a closed set of deterministic transforms and fail-closed value maps. ## DRAFT, REVIEW, PUBLISH, INGEST A mapping profile starts as a draft. Users can preview mappings against sample JSON, review the resulting evidence fields, and make changes before publishing. Published profile revisions are immutable. If a mapping needs to change, create a new revision rather than modifying the published revision. This allows an evidence result to retain a stable reference to the exact mapping configuration used to create it. Each published revision records: - Profile identity - Profile revision - Profile hash - Mapping engine version - Target configuration hash These values become part of the Bridge provenance attached to the evidence record. See How it works. ## Transforms The mapping engine exposes a closed set of deterministic operations: - JSON Pointer extraction - Constants - Required and optional mappings - Primitive conversions - Timestamp normalization - Object and array preservation - Selected-value hashing - Explicit valueMap normalization A valueMap normalizes a source vocabulary to the evidence vocabulary. Source value: ``` "APPLIED" ``` Mapping configuration: ``` { "APPLIED": "applied", "FAILED": "failed" } ``` Output: ``` "applied" ``` Unknown values fail closed unless explicitly configured. Evidence Bridge does not support arbitrary JavaScript, expressions, eval, callbacks or network transforms. ## Conceptual example The following is a conceptual illustration of a mapping profile, not the literal stored schema. Conceptual example ``` { "name": "Operational remediation", "target": "consequential-execution-v1", "mappings": [ { "from": "/execution_id", "to": "source.eventId", "required": true }, { "from": "/execution_timestamp", "to": "source.occurredAt", "required": true }, { "from": "/pre_state", "to": "execution.preState", "required": true }, { "from": "/outcome", "to": "execution.outcome", "valueMap": { "APPLIED": "applied", "PARTIAL": "partial", "FAILED": "failed" } } ] } ``` Actual profile API fields may contain additional immutable revision and provenance metadata. ## Integration types Preset source profile. Used when a platform emits a predictable execution format. A predefined template creates a tenant-owned draft profile that the user reviews and publishes. Agent frameworks, workflow systems, automation platforms and deployment systems are candidate future presets rather than shipped integrations. Generic evidence template. AI Execution and Operational Execution, used when the customer already has a payload close to one of the canonical evidence models. Custom JSON. Used when the source has its own schema and requires a custom mapping. See Custom JSON. --- # AI Execution V2 through Evidence Bridge URL: https://docs.nexart.io/docs/evidence-bridge/ai-execution Map an existing model-execution payload to the cer.ai.execution.v2 evidence family: required semantics, conceptual field mapping, reviewed target configuration and confidential sealing. Use the AI Execution target when the source represents an actual AI or model execution. The canonical record family is `cer.ai.execution.v2` at protocol `1.3.1`, produced by `@nexart/ai-execution`. See AI Execution V2 for the normative schema. ## Required semantics - execution identity - execution timestamp - provider - model - input - output - parameters - execution role Optional fields may include instruction, instruction kind, model evidence, decision references and extensions. ## Source example Source payload ``` { "run_id": "run_9281", "timestamp": "2026-09-09T10:20:30.000Z", "provider": "openai", "model": "gpt-4.1", "prompt": { "customer": "Example request" }, "response": { "classification": "approved" }, "temperature": 0 } ``` ## Conceptual mapping ``` run_id -> executionId timestamp -> timestamp provider -> provider model -> model prompt -> input response -> output temperature -> parameters.temperature ``` Field names alone are not sufficient. Evidence Bridge requires a reviewed target configuration so that arbitrary JSON fields cannot automatically acquire AI execution semantics merely because they are named "input", "output" or "model". ## AI confidentiality Production AI evidence is confidentially sealed before Node attestation. Protected plaintext such as model input and output is replaced by cryptographic commitment envelopes in the public CER: Public representation of a protected field ``` { "_redacted": true, "mode": "confidential", "commitmentScheme": "hmac-sha256-v1", "commitment": "hmac-sha256:..." } ``` Private opening material is kept separately. The Node receives the confidential CER, not the private openings. An opening can later be used for selective verification of the committed value. NexArt confidentiality uses keyed, salted HMAC commitments managed by the canonical SDK. A plain SHA-256 hash does not provide confidentiality. See Confidential evidence for openings and selective verification. --- # Operational Execution URL: https://docs.nexart.io/docs/evidence-bridge/operational-execution Operational Execution is the Evidence Bridge category for consequential system actions, backed by the cer.consequential.execution.v1 evidence family with outcome-sensitive applied-change rules. Canonical evidence family: Consequential Execution V1 (`cer.consequential.execution.v1`). Operational Execution is the user-facing Evidence Bridge category for consequential system actions. The canonical NexArt evidence family underneath it is `cer.consequential.execution.v1` at protocol `1.3.1`, produced by `@nexart/consequential-execution`. It is designed for executions where a system reports that it attempted an action against a target and records the resulting outcome. ## Semantic model ``` executionId occurredAt producer actionType target request OR preState action outcome result OR postState ``` Outcome is one of: ``` applied partial failed ``` ## Action versus applied change Outcome-sensitive rule ``` applied -> appliedChange required partial -> appliedChange required failed -> appliedChange forbidden ``` action describes what the execution attempted to do. appliedChange describes the change the producer reports was actually applied. This distinction prevents a failed execution from falsely implying that a state change occurred. ## Example Source payload ``` { "execution_id": "exec_9f83a1d04b7e", "execution_timestamp": "2026-09-08T20:14:02.115Z", "component": "sre/remediator", "action_type": "NODE_ISOLATION", "target_resource": "node_03", "pre_state": { "status": "ONLINE", "latency_ms": 312.45, "slo_threshold_ms": 250 }, "action_applied": { "command": "ISOLATE", "route_shift": "drain_ingress_traffic" }, "outcome": "APPLIED", "post_state": { "status": "ISOLATED", "health_status": "DEGRADED_FAILOVER" }, "proposal_id": "prop_a712f9b8c340", "consensus_seal": "opaque-source-seal" } ``` Conceptual mapping ``` execution_id -> executionId execution_timestamp -> occurredAt component -> producer component NODE_ISOLATION -> example:node-isolation target_resource -> target pre_state -> preState action_applied -> action action_applied -> appliedChange APPLIED -> applied post_state -> postState proposal_id -> decision reference consensus_seal -> opaque external seal/reference ``` Evidence Bridge does not infer cryptographic algorithms from the appearance of source values. A 64-character hexadecimal seal is not automatically declared to be SHA-256 unless the source explicitly defines it that way. ## Consequential claim boundary A valid Consequential Execution record establishes the integrity of a producer-reported execution claim. It can cryptographically bind: - what execution was identified - when the producer reported it occurred - which producer or component reported it - what action was attempted - which target was involved - what pre-state or request was captured - what change the producer reports was applied - what outcome was reported - what result or post-state was captured - which external decision or governance references were attached Verification does not independently prove: - that the physical action actually occurred - that the producer was honest - that the action was authorized - that governance was valid - that the action complied with policy - that the action was legally compliant - that the action caused the reported post-state - that the record represents the complete system history Producer identity assurance is currently represented as CLAIM_ONLY unless a separate cryptographic identity mechanism establishes stronger producer authentication. ## Authorization is not execution This payload is not sufficient to create Consequential Execution evidence: ``` { "proposal_id": "prop_123", "status": "AUTHORIZED" } ``` Neither is this, because it does not prove that the tool actually executed: ``` { "tool": "delete_user", "arguments": { "id": "123" } } ``` The source must contain execution-stage semantics such as: - execution identity - target - attempted action - outcome - result or observed post-state This is an important NexArt trust boundary. See Security and trust boundaries. --- # Custom JSON URL: https://docs.nexart.io/docs/evidence-bridge/custom-json Custom JSON is the generic Evidence Bridge entry point for systems with their own schema: define a deterministic mapping profile, then satisfy the eligibility rules of a supported evidence family. Custom JSON is the generic Evidence Bridge entry point for systems without a predefined integration template. Users provide a sample source payload and define a deterministic mapping profile. Custom JSON does not mean that any JSON can automatically become certified evidence. The mapped payload must still satisfy the semantic eligibility rules of a supported evidence family. ## Flow ``` Custom JSON -> Mapping Profile -> Evidence Eligibility -> AI Execution V2 ``` ``` Custom JSON -> Mapping Profile -> Evidence Eligibility -> Operational Execution V1 ``` ## When required semantics are missing ``` targetEligible = false ``` No CER is created. The NexArt Node is not called. Review the required semantics for AI Execution V2 and Operational Execution before building a custom profile, and see Mapping profiles for the available transforms. --- # Evidence Bridge Authentication URL: https://docs.nexart.io/docs/evidence-bridge/authentication Two authentication paths: a short-lived single-use ES256 handoff from the NexArt dashboard for humans, and the existing NexArt API key as a request-scoped bearer credential for machines. ## Connecting from the NexArt dashboard ``` User authenticates at nexart.io | Dashboard > Integrations > Connect | NexArt creates a short-lived Bridge handoff | browser opens bridge.nexart.io | Bridge verifies and consumes handoff | Bridge creates its own secure local session ``` The handoff token is: - ES256 - short lived, approximately 90 seconds - issuer `https://nexart.io` - audience `bridge.nexart.io` - tenant-bound - single-use via `jti` replay protection The token is delivered in the browser URL fragment: ``` #handoff= ``` Fragments are not sent to the destination server as part of the HTTP request. The Bridge client consumes the token and removes the fragment from browser history. The resulting Bridge session uses a secure local cookie with `HttpOnly`, `Secure`, `SameSite=Lax` and the `__Host-` cookie prefix. Normal usage never requires manually copying a handoff token. The Connect flow performs the exchange for you. ## Session endpoints Verified against the deployed Bridge ``` POST https://bridge.nexart.io/api/v1/auth/handoff GET https://bridge.nexart.io/api/v1/auth/session POST https://bridge.nexart.io/api/v1/auth/logout ``` ## Server-to-server ingestion Evidence Bridge does not introduce a second customer API-key system. Machine clients use their existing NexArt API key: ``` nx_live_... ``` The Bridge validates the credential against the NexArt control plane and resolves: - tenant - API-key identity - scopes - account status - plan and limits - Bridge entitlement The customer API key remains request-scoped. It is not stored by Evidence Bridge, it is not returned to the browser, and it must not be logged. For Node attestation, the acting customer's NexArt credential is forwarded request-only so successful certification remains attributed to the correct NexArt account. Unauthenticated request ``` HTTP/1.1 401 {"error":"Authentication required"} ``` ## API key security Never: - embed `nx_live` keys in browser JavaScript - commit them to source control - include them in screenshots - put them in public examples - log them - send them to third parties Server-side examples should read `NEXART_API_KEY` from the application's secret or environment configuration. --- # Confidential Evidence URL: https://docs.nexart.io/docs/evidence-bridge/confidential-evidence Evidence Bridge seals protected content as keyed, salted HMAC commitments before attestation, keeps private openings separate from the public record, and supports later selective verification. A confidential CER contains commitments. The private opening contains the information necessary to verify a committed value. Conceptually: Public CER ``` { "commitment": "hmac-sha256:..." } ``` Private opening ``` { "field": "preState", "salt": "...", "value": { "status": "ONLINE" } } ``` ## How openings are handled The opening is not sent to the NexArt Node. Openings are: - tenant-scoped - record-family-scoped - stored separately from public CERs - excluded from public APIs - excluded from normal result responses - never logged ## Selective verification A verifier with the correct opening can verify that the disclosed value matches the commitment in the certified record. A wrong opening fails verification. NexArt confidentiality uses keyed, salted HMAC commitments managed by the canonical SDK. This is not encryption, and a plain SHA-256 hash does not provide confidentiality. For the underlying commitment scheme, domain separation and the V2 sealing API, see Confidential Mode. --- # Attestation and Verification URL: https://docs.nexart.io/docs/evidence-bridge/attestation Evidence Bridge submits the exact sealed CER to the NexArt Attestation Node, then verifies the Ed25519 receipt and any RFC 3161 timestamp evidence cryptographically rather than trusting HTTP status. ## Node attestation Production Node ``` Discovery: GET https://node.nexart.io/.well-known/nexart-node.json Attestation: POST https://node.nexart.io/api/attest ``` The Bridge submits the exact already-sealed CER. Successful HTTP status alone is not considered proof. Evidence Bridge verifies the returned Node receipt cryptographically. Verification includes: - certificate-hash binding - Node identity - `kid` - Ed25519 signature - published key - key lifecycle - canonical receipt payload A 200 or 201 response alone does not mean VERIFIED. The production Node may return different successful 2xx status codes depending on the path or version. The cryptographic receipt verification is authoritative. ## Node discovery Discovery values such as `activeKid` change over time, so treat the following as an illustration of the shape rather than fixed values. Illustrative discovery response ``` { "service": "NexArt Attestation Node", "nodeId": "nexart-node-prod-1", "activeKid": "k1", "status": "ok", "protocol": { "default": "1.3.1", "supported": ["1.2.0", "1.3.1"] }, "wellKnown": "/.well-known/nexart-node.json" } ``` Read `protocol.default` for the current default and `protocol.supported` for supported protocol versions. Do not interpret the legacy top-level `protocolVersion` field as the authoritative current default. The Node supports protocol 1.2.0 and 1.3.1; the current default is 1.3.1. ## RFC 3161 timestamping NexArt Node receipts can include independent RFC 3161 timestamp evidence. This timestamp is separate from the execution timestamp reported by the producer. - Producer-reported execution time: the producer reports that this execution occurred at time T. - RFC 3161 timestamp: an independent timestamp authority provides cryptographic evidence that the relevant digest existed by timestamp T2. These are different claims and must not be equated. Timestamp verification states ``` VERIFIED PRESENT_NOT_VERIFIED NOT_PRESENT NOT_VERIFIED ``` Presence of a timestamp token alone is not enough to mark it VERIFIED. The verifier must validate: - timestamp token - message imprint binding - certificate chain - trusted TSA roots - time validity Production NexArt uses RFC 3161 timestamp infrastructure including DigiCert TSA services. Responder certificates and chains can rotate, so verifiers should validate against trusted roots rather than a hardcoded responder name. For the wider verification model, see Verification Model and Independent Verification. --- # Evidence Bridge Integration Guide URL: https://docs.nexart.io/docs/evidence-bridge/integration-guide Quick start for both paths: connect from the NexArt dashboard, publish a mapping profile, then post source execution payloads server-side to the Evidence Bridge ingestion endpoint. ## Human path - Sign in to nexart.io. - Open Dashboard, then Integrations. - Choose AI Execution, Operational Execution, or Custom JSON. - Click Connect. - Review the source mapping profile in Evidence Bridge. - Preview the mapping using synthetic or sample JSON. - Publish the mapping profile. - Send an execution payload. - Review mapping, eligibility, CER, Node attestation and timestamp status. ## Dashboard to Bridge connection At nexart.io, in Dashboard, then Integrations, a user selects an integration and clicks Connect. The control plane then: - verifies the authenticated NexArt user - creates a short-lived Bridge handoff token - opens bridge.nexart.io with the selected template - the Bridge verifies the handoff - the Bridge creates a tenant-scoped session - the Bridge instantiates or opens the selected draft mapping profile See Authentication for the token properties. ## Machine path - Create or use an existing NexArt API key. - Create and publish a mapping profile. - Keep the API key server-side. - POST a source execution payload to the Bridge ingestion endpoint. - Use an idempotency key where supported. - Inspect the returned result and evidence status. - Independently verify the resulting NexArt evidence. ## Ingestion endpoint Verified against the deployed Bridge ``` POST https://bridge.nexart.io/api/v1/ingest/{profileId}/{revision} ``` The published profile page in Evidence Bridge shows the exact path for your profile and revision. cURL ``` curl -X POST "https://bridge.nexart.io/api/v1/ingest/$PROFILE_ID/$PROFILE_REVISION" \ -H "Authorization: Bearer $NEXART_API_KEY" \ -H "Content-Type: application/json" \ --data @execution.json ``` Python ``` import os import requests response = requests.post( f"https://bridge.nexart.io/api/v1/ingest/{os.environ['PROFILE_ID']}/{os.environ['PROFILE_REVISION']}", headers={ "Authorization": f"Bearer {os.environ['NEXART_API_KEY']}", "Content-Type": "application/json", }, json={ # source execution payload }, ) response.raise_for_status() print(response.json()) ``` Never place a real API key in documentation, source control or client-side code. Read `NEXART_API_KEY` from your secret or environment configuration. ## Profile and result endpoints Verified against the deployed Bridge ``` POST /api/v1/profiles/preview POST /api/v1/profiles POST /api/v1/profiles/{profileId}/{revision}/publish GET /api/v1/profiles GET /api/v1/profiles/{profileId}/{revision} GET /api/v1/results/{resultId} ``` A Bridge result exposes the mapping, evidence and attestation state for one ingested payload: Result fields ``` { "resultId": "...", "sourceRawDigest": "sha256:...", "sourceCanonicalDigest": "sha256:...", "profileHash": "sha256:...", "selectedTarget": "consequential-execution-v1", "targetEligibility": { "eligible": true }, "mappedEvent": { }, "provenance": [ ], "cer": { "certificateHash": "sha256:..." }, "localVerification": { }, "nodeAttestation": { } } ``` Field values are illustrative. Additional fields may be present depending on the target and attestation state. ## Troubleshooting 401. Invalid API key, revoked API key, expired or invalid human handoff, already redeemed handoff, or invalid Bridge session. 403. Missing required write scope, Bridge entitlement unavailable, or account not usable. 404. The resource belongs to another tenant, or the profile or revision does not exist. Cross-tenant resource enumeration is deliberately hidden. 409. The same idempotency key was reused with different source content. Target ineligible. The mapping succeeded but required evidence semantics are missing. Node attestation failed. The local CER can remain valid even if Node attestation failed. Retry should reuse the same persisted CER rather than recreating it. Timestamp PRESENT_NOT_VERIFIED. The Node returned timestamp evidence, but the Bridge verifier does not currently have an approved TSA trust chain configured, or verification did not complete successfully. --- # Security and Trust Boundaries URL: https://docs.nexart.io/docs/evidence-bridge/security Exactly what Evidence Bridge proves and what it does not: transformation provenance and record integrity are cryptographic, producer claims about the world remain producer claims. ## What Evidence Bridge can prove - which source bytes were received - which canonical source JSON was mapped - which mapping profile and revision was used - which deterministic transformation was applied - which CER was created - that protected CER content has not been changed - that the Node attested the same certificate identity - that the Node receipt signature verifies - that timestamp evidence verifies when TSA trust validation succeeds ## What Evidence Bridge cannot prove from source data - that the source application told the truth - that an externally reported action physically occurred - that a model response was correct - that an action was authorized - that governance was valid - that an operation was legally compliant - that a producer identity is independently authenticated unless separate identity evidence exists - that the execution caused the reported state change NexArt proves integrity of captured execution evidence. It does not convert producer assertions into independently observed facts. ## Language rules NexArt documentation says "proves the integrity of the captured record", "cryptographically binds", "producer-reported", "independently verifiable", "Node-attested" and "confidential commitment". It avoids claims such as "proves the event is true", "proves the action definitely happened", "proves the AI was correct", "guarantees compliance", "guarantees governance" and "immutable", where the accurate claim is tamper-evident or cryptographically verifiable. ## Privacy and storage - profiles and evidence metadata are tenant-scoped - raw source payloads are ephemeral by default - confidential openings are stored separately and privately - public CERs never contain openings The production database and persistence architecture is implementation-specific and may change. Evidence Bridge does not promise a particular database or guarantee permanent storage of all profiles and results. See also Privacy and Data Handling. ## API key handling The customer NexArt API key is request-scoped: not stored by Evidence Bridge, not returned to the browser, never logged. See Authentication and Key Management. © 2025–2026 NexArt · Operated by Artnames Ltd, United Kingdom · hello@nexart.io --- # What is NexArt? Overview URL: https://docs.nexart.io/docs/what-is-nexart NexArt provides cryptographic proof of execution integrity for AI systems, sealing executions into verifiable records that anyone can check without trusting. ## The problem - Logs describe what happened but do not prove it. - Logs can be altered, incomplete, or reconstructed after the fact. - Audits rely on trusting systems, not verifying them. - There is no standard way to prove that an AI or code execution produced a specific output from a specific input. ## What NexArt does Every execution becomes a Certified Execution Record (CER). CERs capture: - Inputs - Outputs - Parameters - Metadata - Optional contextual evidence such as signals The record is hashed (SHA-256) to produce a `certificateHash`. Any change to the record breaks the hash. Single executions are identified by a `certificateHash`. Multi-step workflows are identified by a `projectHash`. Logs describe events. CERs prove execution integrity. ## Core components ### SDK Creates CERs and verifies them locally. See AI Execution SDK. ### CER (Certified Execution Record) The atomic unit of proof. One execution, one sealed record. See CERs. ### Project Bundles Group multi-step workflows into a single verifiable structure with a `projectHash`. See Project Bundles. ### Node Independent witness and public trust surface. Provides attestation and lookup. Verification always happens independently. No trust in NexArt is required to verify a record. See Attestation Node. ### verify.nexart.io Public verification interface. Runs verification locally in the browser. See verify.nexart.io. ## How it works - Execute: AI or code runs via SDK - Record: CER is created - Seal: `certificateHash` is computed - Attest (optional): node issues attestation - Bundle (optional): Project Bundle created, `projectHash` derived - Verify: using SDK or verify.nexart.io ## What you can prove - What ran - With what inputs - What it produced - In what sequence (for workflows) - That it has not been altered ## Where NexArt fits - AI agents - Multi-step workflows - Compliance and audit trails - Decision traceability - Evidence-backed automation ## What NexArt is NOT - Not observability - Not logging - Not model evaluation - Not correctness validation NexArt confirms the integrity of what was recorded and, when applicable trust material is present, that it was attested by the node. It does not establish that an AI output was correct, fair, lawful, or complete. The completeness and truthfulness of the recorded execution data depend on the integration and capture boundary. ## What NexArt guarantees - Integrity of what was recorded (tamper-evidence via hashing) - Independent verification without trusting NexArt infrastructure - Attestation as an optional layer (node receipt, not required for integrity) NexArt does NOT guarantee completeness. Recording every step is the developer's responsibility. ## Next steps - Certified Execution Records - Project Bundles - Verification - AI Execution SDK - Agent Kit --- # Getting Started with NexArt URL: https://docs.nexart.io/docs/getting-started Start with NexArt in a few steps: install the SDK, certify an execution, read the certificate hash and verify that record locally or via the node API. Start here. This is the canonical NexArt integration model. ## 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 ## Start here The recommended path. Follow these four steps in order. - 1 Run the minimal example Copy one script, set two environment variables, and produce your first certified record. Open the Quickstart → - 2 Understand what was created Read the canonical reference: how the record is built, what is hashed, and how it is verified. Read the Architecture → - 3 Integrate into your system Wire NexArt into your application using the official SDK reference. Open the SDK reference → - 4 Verify your first record Confirm the record is intact and independently verifiable. Open the Verification guide → ## Technical truth What a CER isA Certified Execution Record (CER) is a canonical, tamper-evident bundle representing one execution. It has `bundleType: "cer.ai.execution.v1"`, a `version`, a `createdAt` ISO-8601 timestamp, a `snapshot` (model, inputHash, outputHash, metadata), and an optional `context` / `contextSummary`. The CER is identified by its `certificateHash` (SHA-256). Inputs and outputs are stored as hashes; raw payloads are not part of the bundle. Fields covered by certificateHash (whitelist)The hash is SHA-256 over a strict whitelist projection, canonicalized per the profile selected by `protocolVersion` (`1.2.0` → nexart-v1, default; `1.3.0` → jcs-v1, RFC 8785, opt-in). Whitelist:`bundleType`, `version`, `createdAt`, `snapshot`, and (only when present) `context`, `contextSummary`, `policyEvaluation`. Any modification to a covered field changes the hash. Canonicalization is protocol-bound: verifiers MUST use the profile corresponding to the bundle's `protocolVersion`. Fields excluded from hashingThe following are explicitly excluded from the hash payload and may be added, updated, or removed without invalidating the `certificateHash`: `certificateHash` itself, `meta` (including `meta.attestation` and the receipt), `declaration`, `verificationEnvelope`, `verificationEnvelopeSignature`, `receipt`, and any unknown fields not in the whitelist. Verifiers MUST apply the whitelist projection to the bundle as received; no reconstruction beyond the canonicalization profile bound to the bundle's protocolVersion. The three verification layers- certificateHash (integrity) — recompute SHA-256 over the canonicalized whitelist projection (profile bound to `snapshot.protocolVersion`: `nexart-v1` for 1.2.0; `jcs-v1` / RFC 8785 for 1.3.0 and 1.3.1) and compare with the bundle's `certificateHash`. - receipt signature (node attestation) — validate the Ed25519 receipt at `meta.attestation` using the node key matched by `kid`, and confirm it references the bundle's `certificateHash`. - verification envelope (full bundle signature, v0.16.1) — validate `meta.verificationEnvelopeSignature` against `meta.verificationEnvelope`. When absent, this layer returns SKIPPED. Each layer reports independently as PASS, FAIL, or SKIPPED. Verification statuses: VERIFIED, FAILED, NOT_FOUND. Independence model: local sealing, optional node certification, independent verificationLocal sealing — produced by the SDK (`@nexart/ai-execution@1.2.0` via `sealCer()`) or the CLI (`@nexart/cli@1.1.0` via `nexart ai seal`). Builds a canonical CER bundle and computes the `certificateHash` fully offline. No API key, no network call, no receipt, no verification envelope. The result is a sealed bundle: integrity only. Optional node certification — performed by the attestation node (`POST /v1/cer/ai/certify` / `nexart ai certify`). The node validates the bundle and issues an Ed25519-signed receipt (identified by `kid`) referencing the bundle's `certificateHash`, plus a verification envelope. Receipt and signatures are stored at `bundle.meta.attestation` and `meta.verificationEnvelope`. Certification adds attestation layers; it does not change the `certificateHash`. The result is a certified bundle. Independent verification — performed by anyone, with no trust in NexArt infrastructure required. Available via verify.nexart.io, the SDK, or the CLI. The bundle plus the node's published public keys are sufficient. For sealed bundles, only Layer 1 (integrity) is applicable; Layers 2 and 3 return SKIPPED. For certified bundles, all three layers return PASS. 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. Mental model - Logs describe. CERs prove. - Integrity ≠ Stamp ≠ Envelope. - Verification does not require trust. ## Quick Implementation Flow Four steps. Each has a single responsibility. Following them in order produces a record anyone can verify without trusting your infrastructure. Quick Implementation Flow The four steps required to integrate NexArt correctly. Each step has a single responsibility. - Step 1Capture execution What: Record provider, model, prompt, input, parameters, and output. All six are required on CertifyDecisionParams. Why: The certificateHash is computed from this data. Capture must happen before sealing. @nexart/signals · createContext() (optional) → passed into certifyDecision(...) - Step 2Create CER What: Seal a CER bundle and compute certificateHash over the strict whitelist (JCS). Why: The hash is the canonical identity of the record. It binds the bundle to its content. certifyDecision(params) · or sealCer(snapshot) for the lower-level path - Step 3Certify via node What: Submit the bundle to the attestation node. Receive a signed receipt and verification envelope. Why: The node provides an independent witness and a public verification surface. certifyAndAttestDecision(params, options) · or attest(bundle, options) · POST /v1/cer/ai/certify - Step 4Verify independently What: Anyone can re-derive certificateHash, validate the receipt signature, and validate the envelope. Why: Verification requires no trust in your infrastructure or the node beyond its published key. verifyAiCerBundleDetailed(bundle) · or https://verify.nexart.io/c/{bundle.certificateHash} Deeper reference: Verification · Verification Layers · Hashes ## Minimal working example One execution, one CER, one certification, one verification. This is the canonical example reused across the docs. How the SDK is split - Creation is local and deterministic (`certifyDecision`). It produces a sealed bundle and a `certificateHash`. No network call. - Certification is node-based (`certifyAndAttestDecision` or `attest(bundle, options)`). It returns an`AttestationReceipt` and the bundle gains a verification envelope. - A public verification URL exists ONLY after certification. Construct it as `https://verify.nexart.io/c/{certificateHash}`. - `prompt` and `parameters` are REQUIRED fields on `CertifyDecisionParams`, alongside `provider`, `model`, `input`, and `output`. Flow A - Certified execution (recommended) ``` import { certifyAndAttestDecision, verifyAiCerBundleDetailed, } from "@nexart/ai-execution"; // Steps 1-3: capture execution, seal the CER, attest via the node. // certifyAndAttestDecision is async because it contacts the attestation node. 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); // sha256:... console.log(receipt.attestationId); // node-issued id console.log(verificationUrl); // https://verify.nexart.io/c/sha256:... // Step 4: independent verification. No trust in your infrastructure required. const report = await verifyAiCerBundleDetailed(bundle); // report.checks.bundleIntegrity -> PASS (Layer 1) // report.checks.nodeSignature -> PASS (Layer 2) // report.checks.receiptConsistency -> PASS (Layer 3) ``` Flow B - Local-only execution (no node interaction) ``` import { certifyDecision, verifyAiCerBundleDetailed } from "@nexart/ai-execution"; // certifyDecision is synchronous and deterministic. // It produces a sealed CER bundle and certificateHash WITHOUT contacting the node. // There is no receipt, no envelope, and no public verificationUrl in this flow. const bundle = certifyDecision({ 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" }, }); const certificateHash = bundle.certificateHash; console.log(certificateHash); // sha256:... // Local verification: Layer 1 PASS, Layers 2 & 3 SKIPPED. const report = await verifyAiCerBundleDetailed(bundle); // To obtain a signed receipt and a public verificationUrl, attest the bundle // via certifyAndAttestDecision(...) or attest(bundle, options). ``` Using LangChain? See the dedicated LangChain integration page for the optional adapters `createLangChainCer` / `certifyLangChainRun` imported from `@nexart/ai-execution/langchain`. ## What NexArt Does NexArt is the AI Evidence Layer: verifiable execution infrastructure that produces cryptographic evidence about what was executed. NexArt creates Certified Execution Records (CERs), cryptographically bound records of AI or deterministic execution that can be independently verified. Every CER produces a deterministic `certificateHash`. That hash is the canonical identity of the record. Optional node attestation produces a signed receipt so anyone can verify the record without trusting your infrastructure. What NexArt is not NexArt is not an observability dashboard, and it does not judge whether a model output was correct, truthful, fair, or compliant with any regulation. It proves canonical artifact integrity, hash equality, signed node attestation, and (for confidential fields) commitment consistency. See the Glossary for precise definitions of these terms. ## Two Integration Paths NexArt supports both single-execution certification and multi-step workflow certification. Pick the one that matches your use case. You do not need Project Bundles for every integration. Path A - Single CER One execution, one verifiable record. - Run the execution - Seal a CER locally (`sealCer()`) — offline, no API key - Verify locally (integrity PASS, receipt & envelope SKIPPED) - Optional: certify via node and share `/c/{certificateHash}` Path B - Project Bundle Multi-step or multi-agent workflows verified as a unit. - Create a CER per step - Assemble a Project Bundle - Register the bundle on the node - Verify publicly at `verify.nexart.io` ## Install the SDK ``` npm install @nexart/ai-execution ``` Current version: `@nexart/ai-execution@1.4.0`. See AI Execution V2 for the full V2 schema reference. ## Path A (recommended): Certify and Attest a Single CER, V2 The primary happy path. One execution produces one verifiable V2 record. Sealing is fully offline (no API key, no network call); attestation is a single call to the node. Every V2 record declares an `executionRole` (`'advisory' | 'operative' | 'unspecified'`), and, when an `instruction` is present, a matching `instructionKind` (`'system' | 'derived' | 'label'`). Both are producer-declared; NexArt never infers them. Seal and attest a V2 CER ``` import { certifyDecisionV2, attest, verifyCerV2 } from "@nexart/ai-execution"; // certifyDecisionV2 is synchronous. No network call. const { bundle } = certifyDecisionV2({ provider: "openai", model: "gpt-4o-mini", instruction: "Answer the user's arithmetic question.", instructionKind: "system", input: { messages: [{ role: "user", content: "What is 2 + 2?" }] }, parameters: { temperature: 0, maxTokens: 1024, topP: null, seed: null }, output: { text: "4" }, executionRole: "advisory", }); const certificateHash = bundle.certificateHash; console.log(certificateHash); // Local verification, no node call. Re-derives protectedSet and re-checks hashes. const local = verifyCerV2(bundle); // local.code === "OK", local.verdict === "VERIFIED" // Attest to the node. The certificateHash already exists; attest() never // creates or replaces it. const attestation = await attest(bundle, { nodeUrl: process.env.NEXART_NODE_ENDPOINT!, apiKey: process.env.NEXART_API_KEY!, }); // attestation.ok === true ``` The `certificateHash` is the canonical identity of the record and does not change between sealing and attestation. `attest()` POSTs the already-sealed bundle to the node's `/api/attest` route, which dispatches on `bundleType` and accepts both `cer.ai.execution.v1` and `cer.ai.execution.v2`. Note: `executionId` is not a unique artifact identifier. Always look up records by `certificateHash`. V1 integrations (existing, still supported) `cer.ai.execution.v1` is unchanged and remains fully supported. New integrations SHOULD use V2. If you already have a V1 integration, keep using `certifyDecision` / `sealCer` from `@nexart/ai-execution`. For upgrading, see Migration: V1 to V2 and V1/V2 Compatibility. V1 (legacy, still supported): Seal a Single CER (offline) ``` import { certifyDecision, verifyAiCerBundleDetailed } from "@nexart/ai-execution"; // certifyDecision (V1, from @nexart/ai-execution) is synchronous. No network call. const bundle = certifyDecision({ provider: "openai", model: "gpt-4o-mini", prompt: "What is 2 + 2?", input: { messages: [{ role: "user", content: "What is 2 + 2?" }] }, parameters: { temperature: 0, maxTokens: 1024, topP: null, seed: null }, output: { text: "4" }, }); const certificateHash = bundle.certificateHash; const report = await verifyAiCerBundleDetailed(bundle); // report.checks.bundleIntegrity === "PASS" // report.checks.nodeSignature === "SKIPPED" (no node attestation yet) // report.checks.receiptConsistency === "SKIPPED" (no envelope yet) ``` ## Path B: Workflow with a Project Bundle For multi-step or multi-agent workflows, certify each step as its own CER and group them into a Project Bundle. The bundle has its own `projectHash` covering all step `certificateHash` values. Linear workflow with @nexart/agent-kit ``` import { startWorkflow } from "@nexart/agent-kit"; const workflow = startWorkflow({ projectTitle: "Contract review" }); const clauses = await workflow.step("Extract clauses", async () => { return await llm.call("Extract key clauses..."); }); const risks = await workflow.step("Summarize risks", async () => { return await llm.call("Summarize risks from: " + clauses); }); const bundle = workflow.finish(); // bundle.integrity.projectHash is the verifiable hash ``` For public verification on `verify.nexart.io`, the bundle must be registered on the node. See End-to-End Verification for the full registration flow. ## Verify the Record Verification can be performed independently. Open https://verify.nexart.io and paste the `certificateHash`, or open the URL directly: ``` https://verify.nexart.io/c/{certificateHash} ``` ## Official Example Repos LangChain example Create and verify CERs in LangChain chains and agent workflows. github.com/artnames/nexart-langchain n8n example Turn n8n workflow outcomes into Certified Execution Records. github.com/artnames/nexart-n8n ## Common mistakes Common Mistakes Verified failure patterns observed in real integrations. Avoid these to prevent verification errors. - Wrong: Setting version: "1.0" on the bundle Right: Use version: "0.1" (matches cer.ai.execution.v1). Why: An incorrect version changes the canonical projection and breaks certificateHash recomputation. - Wrong: Hashing the full bundle (including meta.attestation, signature, receipt) Right: Hash only the strict whitelist: bundleType, version, createdAt, snapshot, context, contextSummary (JCS). Why: meta and attestation are added after sealing. Hashing them produces a different, non-verifiable hash. - Wrong: Trying to verify the Verification Envelope from a publicly redacted record Right: Layer 3 envelope verification requires the full attestation projection. Redacted public payloads support Layer 1 and Layer 2 only. Why: Envelope signature covers a 5-field projection that may be removed by redaction. - Wrong: Mutating the bundle after certification (re-ordering keys, adding fields, normalizing dates) Right: Treat the certified bundle as immutable. Persist it byte-for-byte. Why: Any mutation invalidates certificateHash and the receipt. The node enforces EXECUTION_MUTATION_DETECTED (409) on resubmit. - Wrong: Looking up records by executionId Right: Always look up by certificateHash. executionId is not a unique artifact identity. Why: Two attempts of the same execution can share an executionId but produce different certificateHashes. ## What happens if it fails What happens if verification fails Each verification layer fails for a different, specific reason. Isolating the failed layer tells you exactly what went wrong. | Layer | Failure | Meaning | Action | | --- | --- | --- | --- | | Layer 1 — Integrity | certificateHash mismatch | The bundle was modified after sealing, or the wrong projection was hashed. | Re-derive certificateHash with sealCer(...) over the strict whitelist. If it still differs, the stored bundle is no longer authentic. | | Layer 2 — Signed Receipt | Receipt signature invalid | The receipt was not produced by the published node key, or the receipt payload was modified. | Refetch the node key set from /.well-known/nexart-node.json. If signature still fails, the receipt is not trustworthy. | | Layer 3 — Verification Envelope | Envelope signature invalid or projection mismatch | The envelope payload (5-field attestation projection) does not match what was signed, or the kid is wrong. | Confirm the bundle includes meta.verificationEnvelope and meta.verificationEnvelopeSignature. Public/redacted payloads cannot satisfy Layer 3. | | Node | EXECUTION_MUTATION_DETECTED (409) | An execution_id already maps to a different certificateHash. The node rejects mutation by design. | Do not re-submit modified bundles under the same execution_id. Create a new execution. | ## Next Steps - Quickstart: the shortest path through both paths - AI Execution V2: full V2 schema, executionRole, instructionKind, decisionRefs - Migration: V1 to V2 and V1/V2 Compatibility - Glossary and AIEF: precise terminology and claim boundaries - Project Bundles: how multi-step workflows are grouped and verified - End-to-End Verification: node registration and public verification - LangChain and n8n: framework integrations - CLI: create and verify CERs from the command line --- # Quickstart: Certify Your First CER URL: https://docs.nexart.io/docs/quickstart Certify your first AI execution with NexArt in minutes: install the SDK, call certify, read the certificate hash and verify the resulting CER on the node. This is the fastest correct integration path. ## 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 The fastest path from zero to a verified record. For a broader overview, see Getting Started. Verify Your First Execution (2 minutes) Local-first. No API key, no node call, no network access. Seal a CER and verify it locally with the SDK. 1. Install ``` npm install @nexart/ai-execution ``` 2. seal-and-verify.ts (single file, copy as-is, V2) ``` import { certifyDecisionV2, verifyCerV2, } from "@nexart/ai-execution"; async function main() { // Seal locally. Fully offline. certifyDecisionV2 is synchronous. const { bundle } = certifyDecisionV2({ provider: "openai", model: "gpt-4o-mini", instruction: "Decide whether to approve the refund.", instructionKind: "system", 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" }, executionRole: "advisory", }); console.log("certificateHash :", bundle.certificateHash); // Independent local verification. No node call. const result = verifyCerV2(bundle); console.log("code :", result.code); // "OK" console.log("verdict :", result.verdict); // "VERIFIED" } main().catch((err) => { console.error("FAILED:", err); process.exit(1); }); ``` 3. Run ``` npx tsx seal-and-verify.ts ``` Expected output (sealed bundle) ``` certificateHash : sha256:9f2b1c8e4a7d6f3b0c5e8a1d2f4b6c8e9a0d3f5b7c2e4a6d8f1b3c5e7a9d0f2b code : OK verdict : VERIFIED ``` Local sealing and verification proves integrity. Attesting to the node adds a signed receipt. A sealed-only V2 bundle is fully valid and independently verifiable offline. Attestation is optional and adds a node-signed receipt on top of the existing `certificateHash`. Add node certification (optional) Certification is optional. It submits the bundle to the attestation node, which adds an Ed25519 receipt and a verification envelope, and returns a public `verificationUrl`. The `certificateHash` does not change. 1. Configure node access ``` export NEXART_NODE_ENDPOINT="https://node.nexart.io" export NEXART_API_KEY="" ``` 2. certify-and-attest.ts (V2) ``` import { certifyDecisionV2, attest, verifyCerV2, } from "@nexart/ai-execution"; async function main() { // Seal locally first. certifyDecisionV2 is synchronous and does not // contact the node. The certificateHash exists before attestation. const { bundle } = certifyDecisionV2({ provider: "openai", model: "gpt-4o-mini", instruction: "Decide whether to approve the refund.", instructionKind: "system", 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" }, executionRole: "advisory", }); const certificateHash = bundle.certificateHash; const verificationUrl = `https://verify.nexart.io/c/${certificateHash}`; // Attest the sealed bundle. Posts to ${nodeUrl}/api/attest. The node // never creates or replaces certificateHash. const attestation = await attest(bundle, { nodeUrl: process.env.NEXART_NODE_ENDPOINT!, apiKey: process.env.NEXART_API_KEY!, }); console.log("certificateHash :", certificateHash); console.log("attestation.ok :", attestation.ok); console.log("verificationUrl :", verificationUrl); const result = verifyCerV2(bundle); console.log("code :", result.code); // "OK" console.log("verdict :", result.verdict); // "VERIFIED" } main().catch((err) => { console.error("FAILED:", err); process.exit(1); }); ``` Expected output (certified bundle) ``` certificateHash : sha256:9f2b1c8e4a7d6f3b0c5e8a1d2f4b6c8e9a0d3f5b7c2e4a6d8f1b3c5e7a9d0f2b verificationUrl : https://verify.nexart.io/c/sha256:9f2b1c8e4a7d6f3b0c5e8a1d2f4b6c8e9a0d3f5b7c2e4a6d8f1b3c5e7a9d0f2b attestation.ok : true code : OK verdict : VERIFIED ``` With node attestation, the bundle is independently verifiable end-to-end. The `verificationUrl` is publicly resolvable at verify.nexart.io. Mental model - Logs describe. CERs prove. - Integrity ≠ Stamp ≠ Envelope. - Verification does not require trust. ## Quick Implementation Flow The four steps every NexArt integration must perform, in order. Quick Implementation Flow The four steps required to integrate NexArt correctly. Each step has a single responsibility. - Step 1Capture execution What: Record provider, model, prompt, input, parameters, and output. All six are required on CertifyDecisionParams. Why: The certificateHash is computed from this data. Capture must happen before sealing. @nexart/signals · createContext() (optional) → passed into certifyDecision(...) - Step 2Create CER What: Seal a CER bundle and compute certificateHash over the strict whitelist (JCS). Why: The hash is the canonical identity of the record. It binds the bundle to its content. certifyDecision(params) · or sealCer(snapshot) for the lower-level path - Step 3Certify via node What: Submit the bundle to the attestation node. Receive a signed receipt and verification envelope. Why: The node provides an independent witness and a public verification surface. certifyAndAttestDecision(params, options) · or attest(bundle, options) · POST /v1/cer/ai/certify - Step 4Verify independently What: Anyone can re-derive certificateHash, validate the receipt signature, and validate the envelope. Why: Verification requires no trust in your infrastructure or the node beyond its published key. verifyAiCerBundleDetailed(bundle) · or https://verify.nexart.io/c/{bundle.certificateHash} Deeper reference: Verification · Verification Layers · Hashes ## Minimal working example The canonical example. Reuse this shape in your own integration. How the SDK is split - Creation is local and deterministic (`certifyDecision`). It produces a sealed bundle and a `certificateHash`. No network call. - Certification is node-based (`certifyAndAttestDecision` or `attest(bundle, options)`). It returns an`AttestationReceipt` and the bundle gains a verification envelope. - A public verification URL exists ONLY after certification. Construct it as `https://verify.nexart.io/c/{certificateHash}`. - `prompt` and `parameters` are REQUIRED fields on `CertifyDecisionParams`, alongside `provider`, `model`, `input`, and `output`. Flow A - Certified execution (recommended) ``` import { certifyAndAttestDecision, verifyAiCerBundleDetailed, } from "@nexart/ai-execution"; // Steps 1-3: capture execution, seal the CER, attest via the node. // certifyAndAttestDecision is async because it contacts the attestation node. 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); // sha256:... console.log(receipt.attestationId); // node-issued id console.log(verificationUrl); // https://verify.nexart.io/c/sha256:... // Step 4: independent verification. No trust in your infrastructure required. const report = await verifyAiCerBundleDetailed(bundle); // report.checks.bundleIntegrity -> PASS (Layer 1) // report.checks.nodeSignature -> PASS (Layer 2) // report.checks.receiptConsistency -> PASS (Layer 3) ``` Flow B - Local-only execution (no node interaction) ``` import { certifyDecision, verifyAiCerBundleDetailed } from "@nexart/ai-execution"; // certifyDecision is synchronous and deterministic. // It produces a sealed CER bundle and certificateHash WITHOUT contacting the node. // There is no receipt, no envelope, and no public verificationUrl in this flow. const bundle = certifyDecision({ 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" }, }); const certificateHash = bundle.certificateHash; console.log(certificateHash); // sha256:... // Local verification: Layer 1 PASS, Layers 2 & 3 SKIPPED. const report = await verifyAiCerBundleDetailed(bundle); // To obtain a signed receipt and a public verificationUrl, attest the bundle // via certifyAndAttestDecision(...) or attest(bundle, options). ``` Using LangChain? See the dedicated LangChain integration page for the optional adapters `createLangChainCer` / `certifyLangChainRun` imported from `@nexart/ai-execution/langchain`. ## Choose a Path - Path A - Single CER: certify one execution. The most common starting point. - Path B - Project Bundle: certify a multi-step or multi-agent workflow as a single verifiable unit. Project Bundles are not required for single-execution use cases. ## Path A: Single CER (V2, recommended) Canonical workflow: create input → seal with certifyDecisionV2 → verify locally → attest() → verify again. Sealing is offline and requires no API key. Attestation is optional and adds node signing without changing `certificateHash`. Existing V1 integrations remain supported; see Migration: V1 to V2. ### 1. Install the SDK ``` npm install @nexart/ai-execution ``` Current version: `@nexart/ai-execution@1.4.0`. ### 2. Seal a V2 CER locally (offline) Seal a V2 CER locally: no node, no API key ``` import { certifyDecisionV2, verifyCerV2 } from "@nexart/ai-execution"; // certifyDecisionV2 is synchronous. const { bundle } = certifyDecisionV2({ provider: "openai", model: "gpt-4o-mini", instruction: "Decide whether to approve the report.", instructionKind: "system", input: { messages: [{ role: "user", content: "Should this report be approved?" }] }, parameters: { temperature: 0, maxTokens: 1024, topP: null, seed: null }, output: { decision: "approve", reason: "policy_passed" }, executionRole: "advisory", }); console.log(bundle.certificateHash); // Verify locally. No network call. const result = verifyCerV2(bundle); console.log(result.code); // "OK" console.log(result.verdict); // "VERIFIED" ``` A sealed V2 bundle is fully verifiable offline via `verifyCerV2`. `executionRole` is REQUIRED; `instructionKind` is REQUIRED only when `instruction` is present. ### 3. (Optional) Attest via the node Add node attestation ``` import { attest, verifyCerV2 } from "@nexart/ai-execution"; const attestation = await attest(bundle, { nodeUrl: process.env.NEXART_NODE_ENDPOINT!, apiKey: process.env.NEXART_API_KEY!, }); const verificationUrl = `https://verify.nexart.io/c/${bundle.certificateHash}`; const result = verifyCerV2(bundle); console.log(result.code); // "OK" console.log(result.verdict); // "VERIFIED" ``` The `certificateHash` is identical whether the bundle is sealed or attested for the same input. `attest()` POSTs the already-sealed bundle to `${nodeUrl}/api/attest`; the node never creates or replaces `certificateHash`. ### 4. Verify publicly Open verify.nexart.io and paste the `certificateHash`, or open the URL directly: ``` https://verify.nexart.io/c/{certificateHash} ``` Public resolution on `verify.nexart.io` requires the bundle to have been certified (or otherwise registered) by the attestation node. Sealed bundles can still be verified locally with the SDK. The verifier checks Bundle Integrity, Node Signature (if attested), Receipt Consistency, and Verification Envelope. ## Path B: Project Bundle (Multi-Step Workflow) ### 1. Install agent-kit ``` npm install @nexart/agent-kit ``` Current version: `@nexart/agent-kit@0.6.0`. Wiring this up with an AI assistant? See the Agent-Kit Instructions for AI Agents page. ### 2. Build a workflow Linear workflow producing a Project Bundle ``` import { startWorkflow } from "@nexart/agent-kit"; const workflow = startWorkflow({ projectTitle: "Refund decision" }); const policy = await workflow.step("Check policy", async () => { return { eligible: true, policyId: "ret-30d" }; }); const decision = await workflow.step("Final decision", async () => { return { decision: "approve_refund", policy }; }); const bundle = workflow.finish(); console.log(bundle.integrity.projectHash); ``` ### 3. Register on the node and verify publicly To make the bundle verifiable on `verify.nexart.io`, register it on the node. See End-to-End Verification for the registration flow and node behavior. ## Important: certificateHash, not executionId Always look up and share records by `certificateHash`. `executionId` is not a unique artifact identifier and must not be used as the primary identity for verification. ## Common mistakes Common Mistakes Verified failure patterns observed in real integrations. Avoid these to prevent verification errors. - Wrong: Setting version: "1.0" on the bundle Right: Use version: "0.1" (matches cer.ai.execution.v1). Why: An incorrect version changes the canonical projection and breaks certificateHash recomputation. - Wrong: Hashing the full bundle (including meta.attestation, signature, receipt) Right: Hash only the strict whitelist: bundleType, version, createdAt, snapshot, context, contextSummary (JCS). Why: meta and attestation are added after sealing. Hashing them produces a different, non-verifiable hash. - Wrong: Trying to verify the Verification Envelope from a publicly redacted record Right: Layer 3 envelope verification requires the full attestation projection. Redacted public payloads support Layer 1 and Layer 2 only. Why: Envelope signature covers a 5-field projection that may be removed by redaction. - Wrong: Mutating the bundle after certification (re-ordering keys, adding fields, normalizing dates) Right: Treat the certified bundle as immutable. Persist it byte-for-byte. Why: Any mutation invalidates certificateHash and the receipt. The node enforces EXECUTION_MUTATION_DETECTED (409) on resubmit. - Wrong: Looking up records by executionId Right: Always look up by certificateHash. executionId is not a unique artifact identity. Why: Two attempts of the same execution can share an executionId but produce different certificateHashes. ## What happens if it fails What happens if verification fails Each verification layer fails for a different, specific reason. Isolating the failed layer tells you exactly what went wrong. | Layer | Failure | Meaning | Action | | --- | --- | --- | --- | | Layer 1 — Integrity | certificateHash mismatch | The bundle was modified after sealing, or the wrong projection was hashed. | Re-derive certificateHash with sealCer(...) over the strict whitelist. If it still differs, the stored bundle is no longer authentic. | | Layer 2 — Signed Receipt | Receipt signature invalid | The receipt was not produced by the published node key, or the receipt payload was modified. | Refetch the node key set from /.well-known/nexart-node.json. If signature still fails, the receipt is not trustworthy. | | Layer 3 — Verification Envelope | Envelope signature invalid or projection mismatch | The envelope payload (5-field attestation projection) does not match what was signed, or the kid is wrong. | Confirm the bundle includes meta.verificationEnvelope and meta.verificationEnvelopeSignature. Public/redacted payloads cannot satisfy Layer 3. | | Node | EXECUTION_MUTATION_DETECTED (409) | An execution_id already maps to a different certificateHash. The node rejects mutation by design. | Do not re-submit modified bundles under the same execution_id. Create a new execution. | ## Next Steps - AI Execution V2: full V2 schema reference - Migration: V1 to V2 and V1/V2 Compatibility - LangChain Integration: certify chain and agent executions - n8n Integration: certify workflow automation results - Project Bundles: deeper look at multi-step verification - CLI: create and verify CERs from the command line - Verification: deep dive into verification semantics --- # 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. ## Claim boundaries NexArt is verifiable execution infrastructure, an AI Evidence Layer over integrity, not a truth oracle. Proves: canonical artifact integrity, hash equality, signed node attestation, workflow structure integrity, timestamp evidence, commitment consistency. Does NOT prove: model output correctness, truthfulness, fairness, regulatory compliance, that a producer-declared field is factually true, that a self-asserted identity is real, that a provider actually ran the model (absent provider-signed evidence), or legal admissibility. Producer-declared fields (`executionRole`, `instruction`, `modelEvidence`, `identity`, `policyEvaluation`) are attributable but not independently proven. Cryptographic binding is not identity assurance. ## 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. --- # Certified Execution Record (CER) Protocol URL: https://docs.nexart.io/docs/cer-protocol The CER Protocol specification: bundle structure, certificateHash coverage, protocol bound canonicalization, signature rules and the verification checks. Version: Draft v1Status: Public Specification Draft The NexArt protocol defines a standardized structure for Certified Execution Records (CERs) and the rules for verifying and evolving those records. CERs allow AI executions and deterministic computations to produce portable, verifiable execution artifacts. A CER contains: - Execution snapshot - Deterministic certificate hash - Optional node attestation - Verification metadata These artifacts can be verified by any NexArt-compatible verifier. ## Protocol Scope The CER protocol defines the structure and verification semantics for execution records produced by NexArt-compatible systems. The protocol currently supports multiple execution surfaces, including: - AI execution certification - Deterministic rendering (Code Mode) Each surface defines its own namespace. Examples: ``` cer.ai.execution.v1 cer.codemode.render.v1 ``` The protocol governs: - CER bundle structure - Verification semantics - Schema versioning - Compatibility rules - Deprecation policies ## Canonical CER Structure A CER bundle is a structured JSON object. Example CER Bundle ``` { "bundleType": "cer.ai.execution.v1", "version": "0.1", "createdAt": "2026-03-08T20:30:00Z", "certificateHash": "sha256:...", "snapshot": { "type": "ai.execution.v1", "executionId": "demo-001", "provider": "openai", "model": "gpt-4o-mini", "inputHash": "sha256:...", "outputHash": "sha256:..." }, "meta": { "attestation": { "receipt": { "certificateHash": "sha256:...", "timestamp": "2026-03-08T20:30:00Z", "nodeId": "nexart-node-primary", "kid": "k1" }, "signature": "BASE64_SIGNATURE" } } } ``` A CER bundle contains three logical layers: ### Snapshot Execution data describing the inputs and outputs of a run. ### Certificate Hash A deterministic hash of the canonicalized bundle. ### Attestation An optional node receipt and signature confirming observation of the execution. ## Canonical Hash Computation The `certificateHash` is computed by hashing the canonicalized CER bundle. Canonicalization ensures that equivalent bundles produce identical hashes regardless of JSON formatting. The canonicalization process: - Removes non-deterministic fields - Sorts object keys deterministically - Serializes the bundle using canonical JSON encoding The hash algorithm used by the protocol is: ``` SHA-256 ``` The resulting certificate hash is formatted as: ``` sha256: ``` Hash comparison must be performed on the normalized hexadecimal digest without whitespace or case differences. All NexArt-compatible verifiers must compute the certificate hash using this canonicalization process. ### Hash Scope The certificate hash is computed from the canonicalized CER bundle excluding attestation metadata. Fields under the following paths are excluded from the hash computation: ``` meta.attestation meta.attestation.receipt meta.attestation.signature ``` These fields are excluded because they are produced after the certificate hash is computed. This ensures the bundle hash remains stable before and after node attestation. ## Verification Semantics Verification confirms that a CER bundle is internally consistent and optionally attested by a NexArt node. Verification consists of three checks: ### Bundle Integrity The certificate hash must match the canonicalized bundle contents. ### Node Signature If a node attestation exists, the signature must validate against the node's public keys. ### Receipt Consistency The receipt `certificateHash` must match the bundle `certificateHash`. Node attestation is optional. A CER bundle without attestation can still be verified for bundle integrity, but cannot prove that a NexArt node observed the execution. ## Verification Result Schema All NexArt-compatible verifiers should produce a standardized verification result. Verification Result (with attestation) ``` { "status": "VERIFIED", "checks": { "bundleIntegrity": "PASS", "nodeSignature": "PASS", "receiptConsistency": "PASS" }, "reasonCodes": [], "certificateHash": "sha256:...", "bundleType": "cer.ai.execution.v1", "verifiedAt": "2026-03-08T20:40:00Z", "verifier": "nexart-verifier/1.0.0" } ``` Each check value must be one of: ``` PASS FAIL SKIPPED ``` - PASS: check succeeded - FAIL: check failed - SKIPPED: check not applicable (e.g. no attestation present) Example verification result without attestation: Verification Result (without attestation) ``` { "checks": { "bundleIntegrity": "PASS", "nodeSignature": "SKIPPED", "receiptConsistency": "SKIPPED" } } ``` This structure allows verification results to be consumed consistently across: - CLI verification - Public verifier - Dashboard verification reports - Exported audit packages ## Verification Status Values The `status` field indicates the overall verification outcome. Allowed values: ``` VERIFIED FAILED NOT_FOUND ``` - VERIFIED. All verification checks passed. - FAILED. One or more verification checks failed. - NOT_FOUND. The requested execution record was not located. ## Reason Codes Reason codes provide machine-readable explanations for verification failures. Current codes include: ``` BUNDLE_HASH_MISMATCH NODE_SIGNATURE_INVALID NODE_SIGNATURE_MISSING RECEIPT_HASH_MISMATCH SCHEMA_VERSION_UNSUPPORTED RECORD_NOT_FOUND BUNDLE_CORRUPTED ``` Reason codes must remain stable across protocol versions. Human-readable messages may change, but reason codes must remain consistent. ## Schema Versioning CER bundles include a namespace and schema version. Example: ``` cer.ai.execution.v1 ``` The namespace (`cer.ai.execution`, `cer.codemode.render`) identifies the execution surface and ensures schema evolution can occur independently across surfaces. Minor schema updates may introduce new optional fields without breaking compatibility. Example: `v1.0 → v1.1` Breaking changes require a new namespace version. Example: `cer.ai.execution.v2` ## Compatibility Rules CER readers must support forward compatibility. Readers should: - Ignore unknown optional fields - Preserve unknown metadata - Support verification of earlier revisions within the same major version These rules allow the protocol to evolve without breaking existing integrations. ## Deprecation Policy Fields may be deprecated but must remain readable for a minimum period. Standard policy: - Deprecated fields remain readable for at least 12 months. - Deprecated fields must be documented in the protocol specification. - Removal of deprecated fields requires a new major version. ## Conformance Requirements A NexArt-compliant verifier must: - Compute the canonical bundle hash - Validate node attestation signatures - Confirm receipt consistency - Produce a standardized verification result Systems implementing these steps can be considered CER-compatible verifiers. ## Alignment with AIEF The CER protocol aligns with the AI Execution Integrity Framework (AIEF). | AIEF Concept | CER Equivalent | | --- | --- | | Execution Artifact | CER Snapshot | | Execution Fingerprint | certificateHash | | Integrity Proof | Node Attestation Receipt | | Audit Evidence | Verification Report | This alignment allows CERs to serve as verifiable execution artifacts within AIEF-compliant systems. ## Record Management Layer Lifecycle management, archival behavior, and record actions (hide, delete, revoke, export) are defined separately in the CER Record Management documentation. These concepts operate at the storage, visibility, and governance layer and do not modify the CER bundle, `certificateHash`, or verification semantics. ## Protocol Surfaces The CER protocol is implemented across several NexArt system surfaces. These surfaces share the same schema and verification semantics. Current protocol implementations include: - NexArt Node: produces CER bundles and node attestations - NexArt CLI: local creation and verification of CER bundles - NexArt Verifier: public verification interface - NexArt Dashboard: storage, export, and audit reports - NexArt SDKs: developer libraries for generating and verifying CERs All implementations must follow the verification semantics defined in this specification. --- End of part 1 of 5. Continue with https://docs.nexart.io/llms-full.txt?part=2