# AI CER Package Format

URL: https://docs.nexart.io/docs/ai-cer-package-format

The normative six-field AI CER transport package format, covering each required field, its encoding rules, and how receivers parse and validate a package.

Version: 1.0Status: Normative
This document defines the official JSON structure for NexArt AI CER artifacts. It is normative: third-party builders, verifiers, and integrations MUST conform to this specification when producing, consuming, or transporting AI CER packages.

## 1. Official Package Format

The official exported or transported AI CER artifact MUST use the following top-level shape. This object is the package. It is the transport and export envelope. It is NOT the signed CER bundle.

Official AI CER Package (top-level shape)

```
{
  "cer": { /* exact node-signed CER bundle */ },
  "receipt": { /* attestation receipt */ },
  "signature": "base64url...",
  "attestation": { /* attestation summary */ },
  "verificationEnvelope": { /* verification envelope metadata */ },
  "verificationEnvelopeSignature": "base64url..."
}
```

The top-level package is the transport/export object. It is not itself the signed CER bundle. For the official AI CER package format, verifiers MUST extract `cer` as the bundle input. For Verification Envelope v2, verifiers MUST reconstruct the signable payload from `verificationEnvelope.attestation`, `cer`, and `envelopeType`, rather than from the full package object.

## 2. CER Bundle Format

The `cer` field MUST contain the canonical CER bundle object. For AI execution records (`cer.ai.execution.v1`), the bundle MUST use this top-level structure:

Canonical AI CER Bundle

```
{
  "bundleType": "cer.ai.execution.v1",
  "certificateHash": "sha256:...",
  "createdAt": "2026-03-18T00:26:11.619Z",
  "version": "0.1",
  "snapshot": { ... },
  "context": { ... },
  "meta": { ... }
}
```

### 2a. Top-level fields inside cer

| Field | Required | Description |
| --- | --- | --- |
| bundleType | REQUIRED | Namespace identifier. For AI execution: cer.ai.execution.v1 |
| certificateHash | REQUIRED | Deterministic hash of the canonicalized bundle. Format: sha256:<hex> |
| createdAt | REQUIRED | ISO-8601 timestamp of bundle creation. |
| version | REQUIRED | Schema version string. |
| snapshot | REQUIRED | Execution data: inputs, outputs, provider, model, hashes. |
| context | OPTIONAL | Structured context signals. Included in certificateHash when present. |
| meta | OPTIONAL | Normal bundle metadata such as source and tags. See section 2c. |

JSON key order is not semantically important. Canonicalization handles deterministic ordering before hash computation.

### 2b. cer Immutability

`cer` MUST be the exact bundle object that was sent to and signed by the attestation node.

- Builders MUST NOT mutate `cer` after node signing.
- Builders MUST NOT add package-level attestation or verification fields into `cer` after signing.
- Any mutation to `cer` after signing will cause verification envelope failure, because the signable payload includes `cer` as-is.

### 2c. meta inside cer

The `cer.meta` object is used for normal bundle metadata. Allowed contents include:

- `source` — origin identifier (e.g. application name)
- `tags` — array of classification tags
- Other fields explicitly defined by the current schema version

`cer.meta` MUST NOT contain package-level verification artifacts. See section 3.

`cer.meta` MUST NOT receive post-signing package-level attestation injection.

## 3. Fields That MUST NOT Appear Inside cer.meta

The following fields are package-level verification artifacts. They MUST NOT be embedded inside `cer.meta` in the official format:

Prohibited cer.meta fields

```
meta.verificationEnvelope
meta.verificationEnvelopeSignature
meta.verificationEnvelopeVerification
meta.verificationEnvelopeType
```

These fields belong at the package level (top-level siblings of `cer`), not inside the CER bundle. Embedding them inside the bundle after signing mutates `cer`, which breaks verification envelope verification because the signable payload includes `cer` as-is.

## 4. Package-Level Verification Artifacts

These fields remain outside `cer` at the package level:

### receipt

The attestation receipt object returned by the NexArt attestation node. Contains the certificate hash, timestamp, node identifier, and key identifier.

### signature

Base64url-encoded node signature for the attestation receipt. Used for independent attestation receipt verification.

### attestation

Attestation summary object containing attestation metadata such as node identifier, timestamp, and key identifier.

### verificationEnvelope

An object containing metadata describing the v2 verification envelope. Fields include:

| Field | Description |
| --- | --- |
| algorithm | Signature algorithm (e.g. Ed25519) |
| attestation | Attestation metadata: attestationId, attestedAt, kid, nodeRuntimeHash, protocolVersion |
| canonicalization | Canonicalization method (e.g. jcs) |
| envelopeType | Envelope version identifier (e.g. nexart.verification.envelope.v2) |
| excludedFields | Array of field paths excluded from the signed payload |
| kid | Key identifier used for signing |
| scope | Signing scope (e.g. full_bundle) |
| signedFields | Indicator of which fields are signed (e.g. * for all) |

### verificationEnvelopeSignature

Base64url-encoded signature over the v2 signable payload reconstructed from the package. This signature covers the payload built from `verificationEnvelope.attestation`, `cer`, and `verificationEnvelope.envelopeType`.

## 5. Verification Envelope Signable Payload

For Verification Envelope v2, verifiers MUST reconstruct the signable payload as follows:

v2 Signable Payload Construction

```
{
  "attestation": package.verificationEnvelope.attestation,
  "bundle": package.cer,
  "envelopeType": package.verificationEnvelope.envelopeType
}
```

Key rules for payload reconstruction:

- `bundle` comes from `package.cer`
- `attestation` comes from `package.verificationEnvelope.attestation`
- `envelopeType` comes from `package.verificationEnvelope.envelopeType`
- The `cer` object used in the signable payload is the raw CER bundle, not the full package wrapper
- For the package path, `cer` is used as-is
- `verificationEnvelope` itself is NOT the signed payload
- The whole package object is NOT the signed payload

The reconstructed payload is canonicalized (using the method specified in `verificationEnvelope.canonicalization`) and then verified against `verificationEnvelopeSignature`.

## 6. Builder Rules

- Builders MUST package AI CER artifacts using the top-level `cer` wrapper format.
- Builders MUST NOT mutate `cer` after node signing.
- Builders MUST NOT add package-level attestation or verification fields into `cer` after signing.
- Builders MUST keep verification artifacts at the package level.
- Builders MUST NOT merge verification envelope fields into `cer.meta`.
- Builders MUST verify against `cer`, not against the whole package.
- Builders SHOULD preserve the package structure unchanged when storing, exporting, or forwarding artifacts.

## 7. Invalid Package Format

The following is an invalid official package format:

❌ Invalid: cer mutated after signing

```
{
  "cer": {
    "bundleType": "cer.ai.execution.v1",
    "certificateHash": "sha256:...",
    "createdAt": "2026-03-18T00:26:11.619Z",
    "version": "0.1",
    "snapshot": { "...": "..." },
    "context": { "...": "..." },
    "meta": {
      "source": "example-app",
      "tags": ["demo"],
      "attestation": { "nodeId": "...", "attestedAt": "..." },
      "verificationEnvelope": { "...": "..." },
      "verificationEnvelopeSignature": "base64url..."
    }
  },
  "receipt": { "...": "..." },
  "signature": "base64url..."
}
```

This format is invalid because:

- `meta.attestation` was injected into `cer` after the node signed the bundle. This changes `cer`.
- `verificationEnvelope` and `verificationEnvelopeSignature` were merged into `cer.meta` instead of remaining at the package level.
- `cer` no longer matches the exact bundle that was sent to and signed by the node.
- Verification Envelope v2 will fail because the signable payload uses `cer` as-is, and the mutated bundle does not match the original signed bundle.

## 8. Valid Package Format

The following is a complete, valid AI CER package:

✅ Valid: official AI CER package

```
{
  "cer": {
    "bundleType": "cer.ai.execution.v1",
    "certificateHash": "sha256:a1b2c3d4e5f6...",
    "createdAt": "2026-03-18T00:26:11.619Z",
    "version": "0.1",
    "snapshot": {
      "type": "ai.execution.v1",
      "executionId": "exec-001",
      "provider": "openai",
      "model": "gpt-4o-mini",
      "inputHash": "sha256:...",
      "outputHash": "sha256:..."
    },
    "context": {
      "signals": [
        {
          "type": "policy.check",
          "payload": { "result": "pass" }
        }
      ]
    },
    "meta": {
      "source": "audiot-demonstrator",
      "tags": ["demo"]
    }
  },
  "receipt": {
    "certificateHash": "sha256:a1b2c3d4e5f6...",
    "timestamp": "2026-03-18T00:26:12.000Z",
    "nodeId": "nexart-node-primary",
    "kid": "k1"
  },
  "signature": "base64url...",
  "attestation": {
    "nodeId": "nexart-node-primary",
    "attestedAt": "2026-03-18T00:26:12.000Z",
    "kid": "k1"
  },
  "verificationEnvelope": {
    "algorithm": "Ed25519",
    "attestation": {
      "attestationId": "att-uuid-001",
      "attestedAt": "2026-03-18T00:26:12.000Z",
      "kid": "k1",
      "nodeRuntimeHash": "sha256:...",
      "protocolVersion": "1.2.0"
    },
    "canonicalization": "jcs",
    "envelopeType": "nexart.verification.envelope.v2",
    "excludedFields": [
      "meta.verificationEnvelopeSignature",
      "meta.verificationEnvelopeVerification"
    ],
    "kid": "k1",
    "scope": "full_bundle",
    "signedFields": "*"
  },
  "verificationEnvelopeSignature": "base64url..."
}
```

## 9. Legacy Compatibility

- Legacy raw bundle artifacts (without the package wrapper) remain supported by the NexArt verifier.
- Existing raw bundle verification behavior is unchanged.
- The package format defined in this document is the recommended format for new builder integrations.
- Historical artifacts that store verification envelope fields inside `cer.meta` are accepted by the verifier as a compatibility fallback when no package-level envelope is present.
- Historical public artifacts MAY not include `context` in the certificate hash computation. The verifier detects this and validates using the hash rules active at the time the artifact was created.

## 10. Related Documentation

- AI CER Verification Layers — the three-layer verification model
- CER Protocol — protocol governance, verification semantics, and schema versioning
- Verification — how to verify CER artifacts
- AI Execution SDK — programmatic CER creation and verification
- Attestation Node — node contract and key publication
- Certified Execution Records — conceptual overview of CERs