AI Execution SDK

Overview

The AI Execution SDK provides functions for sealing CERs locally and for certifying them via the attestation node. The canonical workflow is: seal → verify → (optional) certify → verify. Sealing is offline and requires no API key. Certification adds independently verifiable node attestation without changing the certificateHash.

Quick Implementation Flow

Capture, seal, verify, optionally certify, verify again. The SDK exposes one function per step.

Minimal working example

The canonical example used across the docs. Use this as the starting point for any integration.

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)

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).

Copy-Paste Test Harness

Single-file script that exercises the full SDK flow end-to-end and prints PASS / FAIL per verification layer. Use it to validate an integration in under two minutes without mixing APIs or guessing at parameters.

npm install @nexart/ai-execution
export NEXART_NODE_ENDPOINT="https://node.nexart.io"
export NEXART_API_KEY="<your-api-key>"

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);
});

npx tsx test-harness.ts

certificateHash : sha256:9f2b1c8e4a7d6f3b0c5e8a1d2f4b6c8e9a0d3f5b7c2e4a6d8f1b3c5e7a9d0f2b
verificationUrl : https://verify.nexart.io/c/sha256:9f2b1c8e4a7d6f3b0c5e8a1d2f4b6c8e9a0d3f5b7c2e4a6d8f1b3c5e7a9d0f2b
Integrity (Layer 1) : PASS
Receipt   (Layer 2) : PASS
Envelope  (Layer 3) : PASS

API Endpoints

POST /v1/cer/ai/certify

Creates a Certified Execution Record, attests it through the node, and returns a signed receipt with a verification URL. This is the simplest way to get a verifiable proof of an AI execution.

What it does:

• Creates a CER bundle with execution metadata
• Computes the certificateHash (SHA-256)
• Submits the bundle to the attestation node
• Returns the signed receipt, signature, and a public verification URL

POST /v1/cer/ai/certify
Authorization: Bearer NEXART_API_KEY

{
  "model": "gpt-4",
  "input": "Summarize this contract...",
  "output": "The contract states that...",
  "metadata": {
    "appId": "my-app",
    "projectId": "proj_abc123"
  }
}

{
  "verificationUrl": "https://verify.nexart.io/e/exec_abc123",
  "certificateHash": "sha256:9e8d7c6b5a4f3210...",
  "receipt": {
    "certificateHash": "sha256:9e8d7c6b5a4f3210...",
    "timestamp": "2026-03-06T12:00:01.000Z",
    "nodeId": "nexart-node-primary",
    "kid": "key_01HXYZ..."
  },
  "signatureB64Url": "MEUCIQD3a8b1c4d5e6f..."
}

The API response includes receipt and signature fields for convenience. The canonical location for attestation data within the CER bundle is bundle.meta.attestation.

POST /v1/cer/ai/create

Creates a CER bundle without attestation. The bundle is returned with a certificateHash, but no receipt or verification URL is generated.

When to use this:

• You want to generate the CER bundle for your own records
• You plan to submit the bundle for attestation separately
• You need the bundle structure but do not need node signing right now

POST /v1/cer/ai/create
Authorization: Bearer NEXART_API_KEY

{
  "model": "gpt-4",
  "input": "Summarize this contract...",
  "output": "The contract states that...",
  "metadata": {
    "appId": "my-app",
    "projectId": "proj_abc123"
  }
}

{
  "bundleType": "cer.ai.execution.v1",
  "version": "0.1",
  "createdAt": "2026-03-06T12:00:00.000Z",
  "snapshot": {
    "model": "gpt-4",
    "inputHash": "sha256:a1b2c3d4e5f67890...",
    "outputHash": "sha256:f6e5d4c3b2a10987...",
    "metadata": {
      "appId": "my-app",
      "projectId": "proj_abc123"
    }
  },
  "certificateHash": "sha256:9e8d7c6b5a4f3210..."
}

Note: the create response returns the CER bundle directly. There is no receipt, signature, or verification URL. The meta.attestation field is absent. To get attestation, use /certify instead.

Authentication

Both endpoints require an API key passed as a Bearer token:

Authorization: Bearer NEXART_API_KEY

CER Bundle Shape

A fully certified CER bundle follows this structure:

{
  "bundleType": "cer.ai.execution.v1",
  "version": "0.1",
  "createdAt": "2026-03-06T12:00:00.000Z",
  "snapshot": {
    "model": "gpt-4",
    "inputHash": "sha256:a1b2c3d4e5f67890...",
    "outputHash": "sha256:f6e5d4c3b2a10987...",
    "metadata": {
      "appId": "my-app",
      "projectId": "proj_abc123"
    }
  },
  "certificateHash": "sha256:9e8d7c6b5a4f3210...",
  "meta": {
    "attestation": {
      "receipt": {
        "certificateHash": "sha256:9e8d7c6b5a4f3210...",
        "timestamp": "2026-03-06T12:00:01.000Z",
        "nodeId": "nexart-node-primary",
        "kid": "key_01HXYZ..."
      },
      "signature": "<raw Ed25519 signature bytes>",
      "kid": "key_01HXYZ..."
    }
  }
}

The snapshot contains execution metadata. Input and output content is hashed (SHA-256) rather than stored directly. Attestation data lives under meta.attestation.

Key Terms

• create vs certify. create produces a CER bundle. certify produces a CER bundle and gets it attested by the node in one step.
• Attestation vs verification. Attestation is when the node signs a record. Verification is when anyone checks that the signature and bundle are valid.
• Signed receipt vs hash-only timestamp. A signed receipt attests the full CER bundle. A hash-only timestamp attests only the certificateHash, without the snapshot contents.

Context Signals

Both endpoints accept an optional signals parameter - an array of structured metadata objects recorded alongside the execution.

{
  "model": "gpt-4",
  "input": "Summarize this contract...",
  "output": "The contract states that...",
  "signals": [
    {
      "type": "policy.check",
      "source": "compliance-engine",
      "payload": { "policyId": "ret-30d", "result": "pass" }
    }
  ]
}

When signals are present, they are included in the certificateHash computation. This makes them part of the tamper-evidence chain - any modification to a signal after certification will cause verification to fail.

Signals are backward-compatible. Requests without the signals field behave exactly as before. Existing CER bundles without signals remain valid and verifiable.

For the builder API to capture structured signals (input, tool calls, decisions, output) using @nexart/signals, see the Signals SDK reference and Execution Context and Signals.

Verification

As of v0.16.1, the SDK provides both sync and async verification functions:

You no longer need to write your own browser verifier. The async functions use the Web Crypto API internally.

CERs produced by the certify endpoint can be verified across multiple layers:

• Bundle Integrity. The CER bundle hashes are internally consistent.
• Node Signature. The receipt signature is valid against the node's published Ed25519 key.
• Receipt Consistency. The receipt's certificateHash matches the CER bundle.
• Verification Envelope. When present, meta.verificationEnvelopeSignature validates the authoritative displayed verification surface.

Verification statuses: VERIFIED, FAILED, or NOT_FOUND. Each check returns PASS, FAIL, or SKIPPED.

Verify at verify.nexart.io or locally using the bundle and node keys from node.nexart.io/.well-known/nexart-node.json. For a full breakdown of verification layers, see AI CER Verification Layers. For browser examples, see Browser Verification.

CER Package Helpers

As of @nexart/ai-execution@1.0.0, the SDK includes official helpers for working with the CER package format. A CER package is a transport/export wrapper around the inner cer bundle. The inner cer remains the actual execution artifact.

API

• isCerPackage(value) - type guard; returns true if the value conforms to the CER package shape
• createCerPackage(params) - creates a CER package from a bundle, receipt, signature, and optional verification artifacts
• getCerFromPackage(pkg) - extracts the inner cer bundle from a package
• exportCerPackage(pkg) - serializes a CER package to JSON
• importCerPackage(json) - deserializes and validates a CER package from JSON
• verifyCerPackage(pkg) - verifies the inner CER bundle within a package

Creating a CER Package

import { createCerPackage, exportCerPackage } from "@nexart/ai-execution";

const pkg = createCerPackage({
  cer: bundle,
  receipt,
  signature: signatureB64Url,
  attestation: { nodeId, kid, timestamp }
});

const json = exportCerPackage(pkg);
// json is a serialized CER package ready for storage or transport

Importing and Verifying a CER Package

import {
  importCerPackage,
  getCerFromPackage,
  verifyCerPackage
} from "@nexart/ai-execution";

const pkg = importCerPackage(jsonString);
const cer = getCerFromPackage(pkg);

const result = await verifyCerPackage(pkg);
// result contains inner CER verification status
// Package-level trust layers (e.g. verification envelope) are not fully verified by this helper

Package helpers are additive only. They do not change CER hashing, attestation, or verification semantics. See the AI CER Package Format specification for the normative package structure.

Additional Exports

The SDK exports a number of helpers for advanced or operator-level workflows. Importable from @nexart/ai-execution.

verifyAiCerBundleDetailed(bundle)

Returns a structured per-layer verification report covering Integrity (Layer 1), Receipt (Layer 2), and Verification Envelope (Layer 3). Each layer reports independently. Envelope failure is reported separately from integrity failure.

sealCer(snapshot, options?)

Lower-level seal. Takes a pre-built AiExecutionSnapshotV1 (not the high-level CertifyDecisionParams) and computes the certificateHash over the strict whitelist projection (bundleType, version, createdAt, snapshot, context, contextSummary, policyEvaluation) using the canonicalization profile bound to snapshot.protocolVersion (1.2.0 → nexart-v1 by default; 1.3.0 → jcs-v1 / RFC 8785 when explicitly set). For most callers, certifyDecision(params) is the recommended entry point.

import { createSnapshot, sealCer } from "@nexart/ai-execution";

const snapshot = createSnapshot({
  // protocolVersion MUST be set at creation time. Default is "1.2.0"
  // (nexart-v1) for backward compatibility. Set "1.3.0" explicitly to
  // use RFC 8785 JCS canonicalization for the certificateHash.
  protocolVersion: "1.3.0",
  model: "gpt-4o",
  input,
  output,
});

const cer = sealCer(snapshot);
// cer.snapshot.protocolVersion              === "1.3.0"
// cer.meta.attestation.protocolVersion      === "1.3.0" (mirrored by the node)
// verificationEnvelope attestation.protocolVersion === "1.3.0"
//
// Verifiers MUST canonicalize with jcs-v1 for this bundle.
// Do NOT mutate protocolVersion after sealing — it is inside the
// whitelist projection that produces the certificateHash.

wrapProvider(provider, opts)

Wraps an LLM/tool provider so each invocation is automatically certified through /v1/cer/ai/certify. Returns the original provider response augmented with the CER bundle and verificationUrl.

redactBeforeSeal(bundle, fields)

Removes specified fields from the snapshot prior to computing certificateHash. Use to keep sensitive content out of the hashed payload while preserving verifiability over the redacted bundle.

sanitizeForAttestation(bundle)

Returns the strict whitelist projection of a bundle suitable for attestation submission. Strips fields outside the certificateHash whitelist.

sanitizeForStorage(bundle)

Returns a representation safe to store at rest. Preserves all fields required for verification while applying configured redactions.

Canonicalization helpers

• canonicalJson(value, profile?) — protocol-bound canonicalization. profile is selected from the bundle's protocolVersion: nexart-v1 for 1.2.0 (default), jcs-v1 (RFC 8785) for 1.3.0 (opt-in).
• hashCanonicalJson(value, profile?) — SHA-256 over the canonicalized serialization. Used internally by sealCer.
• deriveSignablePayload(bundle, attestation) — produces the derived canonical payload that the node Ed25519-signs. The signed payload is NOT the raw bundle.

Project Bundle helpers

• createProjectBundle(steps, metadata) — assembles a Project Bundle from step CERs.
• verifyProjectBundle(bundle) / verifyProjectBundleAsync(bundle) — verify a Project Bundle (sync/async).
• computeProjectHash(bundle) — recompute projectHash from canonical step content.

Agent Kit

For agent workflows, @nexart/agent-kit provides wrapTool() and certifyDecision() as thin convenience wrappers over this SDK.

Common mistakes

What happens if it fails

Scope

The SDK API surface is still evolving. This page documents the current endpoints and data model. Check back for updates as new capabilities are added.