# Governed Execution Quickstart

URL: https://docs.nexart.io/docs/governed-execution/quickstart

Seal a governed CER locally, verify it, run stateless verification, attest it through the production Node and verify the receipt independently.

@nexart/governed-execution0.4.2NexArt Node0.30.1

## 1. Install

```
npm install --save-exact @nexart/governed-execution@0.4.2
```

Pin the exact version so verification is reproducible.

## 2. Configure

.env (placeholders only)

```
# Production canonical Node. This is production, not staging.
NEXART_NODE_ENDPOINT=https://node.nexart.io
# Temporary key from your secret manager. Never commit a real key.
NEXART_API_KEY=<TEMPORARY_API_KEY>
```

## 3. Seal and verify locally

The producer supplies a complete CAGE `AttestationBundle` and, optionally, a `GraphTopology`. Sealing validates the evidence and throws on invalid input (for example `TOPOLOGY_ERROR: UNKNOWN_NODE`).

seal.ts

```
import {
  CAGE_GOVERNANCE_PROFILE,
  sealGovernedExecution,
  verifyGovernedExecution,
  type AttestationBundle,
  type GraphTopology,
} from "@nexart/governed-execution";

declare const bundle: AttestationBundle;          // produced by your workflow
declare const topology: GraphTopology | undefined; // optional

export const cer = sealGovernedExecution(
  { profile: CAGE_GOVERNANCE_PROFILE, evidence: { bundle, ...(topology ? { topology } : {}) } },
  { createdAt: "2026-10-01T09:00:06.000Z" }, // part of certificate identity
);

const local = verifyGovernedExecution(cer);
if (!local.ok) throw new Error(`${local.code}: ${local.errors.join("; ")}`);
// local.stateHashVerification === "not-performed" is expected, not a failure.
```

## 4. Stateless verification

`POST /v1/cer/verify` takes `{ bundle }`. It does not persist, publish or sign. HTTP 200 means the operation completed; read `status` and `reasonCode` for the verdict.

```
const res = await fetch(`${process.env.NEXART_NODE_ENDPOINT}/v1/cer/verify`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ bundle: cer }),
});
const v = await res.json();
// v.status: "verified" | "failed"; v.reasonCode: "OK" | "TOPOLOGY_ERROR" | ...
// v.governedVerification mirrors the SDK result layers.
if (v.status !== "verified") throw new Error(v.reasonCode);
```

Observed production response for the sample CER on the schema page (abridged):

```
{
  "status": "verified",
  "reasonCode": "OK",
  "checks": {
    "certificateIntegrity": "valid",
    "cageSchemaValidity": "valid",
    "causalGraphValidity": "valid",
    "topologyValidation": "valid",
    "resourceSafety": "valid",
    "signature": "skipped"
  },
  "classification": "VERIFIED",
  "node": "nexart-node-prod-1",
  "governedVerification": {
    "stateHashVerification": "not-performed",
    "producerAuthentication": "not-performed",
    "completeness": "not-claimed"
  }
}
```

`signature: "skipped"` is correct for an unattested CER.

## 5. Authenticated attestation

The body is the complete sealed CER itself, not `{ bundle }`. Neither `kid` nor `nodeId` is sent; the Node selects its signing key.

```
const att = await fetch(`${process.env.NEXART_NODE_ENDPOINT}/api/attest`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.NEXART_API_KEY}`,
    // Optional: "X-NexArt-Visibility": "private" | "public". Omitted -> "hidden".
  },
  body: JSON.stringify(cer), // the sealed CER, unwrapped
});
if (att.status === 401) throw new Error("Missing or invalid API key");
const attestation = await att.json();
if (!att.ok) throw new Error(`${attestation.error}: ${attestation.reasonCode ?? ""}`);
// attestation.ok === true
// attestation.receipt, attestation.signature                      (receipt + Ed25519 signature)
// attestation.verificationEnvelope, .verificationEnvelopeSignature (v2 projection signature)
// attestation.governedVerification                                 (nine-key report)
// attestation.visibility                                           ("hidden" by default)
// The CER is NOT returned. Keep your sealed copy.
```

Full redacted request and response, field reference and failure codes: Governed Attestation Contract.

## 6. Verify independently

- Recompute `certificateHash` (RFC 8785 JCS, SHA-256) with `verifyGovernedExecution(cer)`.
- Fetch `GET /.well-known/nexart-node.json` and select the key whose `kid` equals `receipt.attestorKeyId`.
- Verify `signature`: Ed25519 over `UTF8(JCS(receipt))`, the whole receipt, base64url-decoded.
- Verify `verificationEnvelopeSignature`: Ed25519 over `UTF8(JCS({ attestation, bundle }))`, the whitelisted projection. Not over the envelope descriptor.
- Check that `receipt.certificateHash` equals your CER&#x27;s hash and `receipt.protocolVersion` equals its `version`.

Step-by-step code: receipt and envelope procedures. Do not treat a Node `ok` field as independent verification.

## 7. Persistence is not publication

A successful attestation is stored with visibility `hidden`. It is not public. The returned `verificationUrl` is formatted, not checked, so do not present it as a public record until you have confirmed it resolves. Full rules: persistence versus publication.