@nexart/ai-execution 0.4.1 → 0.5.0

package/README.md

@@ -1,4 +1,4 @@
-# @nexart/ai-execution v0.4.1
+# @nexart/ai-execution v0.5.0
 
 Tamper-evident records and Certified Execution Records (CER) for AI operations.
 
@@ -21,7 +21,7 @@ These records can be verified offline to detect any post-hoc modification and pr
 
 ## Compatibility Guarantees
 
-- **v0.1.0, v0.2.0, and v0.3.0 bundles verify forever.** Any CER bundle produced by any prior version will pass `verify()` in v0.4.1 and all future versions.
+- **v0.1.0, v0.2.0, and v0.3.0 bundles verify forever.** Any CER bundle produced by any prior version will pass `verify()` in v0.4.2 and all future versions.
 - **Hashing rules are frozen for `cer.ai.execution.v1`.** The canonicalization, SHA-256 computation, and certificate hash inputs (bundleType, version, createdAt, snapshot) are unchanged.
 - **New optional snapshot fields** (runId, stepId, stepIndex, etc.) default to undefined and are excluded from legacy snapshots. They participate in the certificate hash only when present.
 - **Canonicalization is frozen for v1.** Number-to-string conversion uses `JSON.stringify()`, which is consistent across JavaScript engines but does not implement RFC 8785 (JCS) for edge cases like `-0`. If stricter canonicalization is required, it will ship as a new bundle type (`cer.ai.execution.v2`), never as a modification to v1.
@@ -139,7 +139,7 @@ const restored = importCer(json);     // parse + verify (throws on tamper)
 | `modelVersion` | Optional | `string \| null` | Defaults to `null` |
 | `parameters.topP` | Optional | `number \| null` | Defaults to `null` |
 | `parameters.seed` | Optional | `number \| null` | Defaults to `null` |
-| `sdkVersion` | Optional | `string \| null` | Defaults to `"0.4.1"` |
+| `sdkVersion` | Optional | `string \| null` | Defaults to `"0.4.2"` |
 | `appId` | Optional | `string \| null` | Defaults to `null` |
 | `runId` | Optional | `string \| null` | Workflow run ID |
 | `stepId` | Optional | `string \| null` | Step identifier within a run |
@@ -180,6 +180,92 @@ Endpoint: `POST {nodeUrl}/api/attest`
 
 Attestation verifies internal integrity only. It does not re-run the model or validate the correctness of the AI output.
 
+### Attestation Receipt
+
+After a successful attestation, you get a normalized `AttestationReceipt`:
+
+```ts
+type AttestationReceipt = {
+  attestationId: string;
+  certificateHash: string;    // sha256:...
+  nodeRuntimeHash: string;    // sha256:...
+  protocolVersion: string;
+  nodeId?: string;
+  attestedAt?: string;        // ISO 8601
+  attestorKeyId?: string;     // kid of the signing key (v0.5.0+)
+  signatureB64Url?: string;   // base64url Ed25519 signature (v0.5.0+)
+};
+```
+
+**Recommended one-call integration:**
+
+```ts
+import { certifyAndAttestDecision } from '@nexart/ai-execution';
+
+const { bundle, receipt } = await certifyAndAttestDecision(params, {
+  nodeUrl: 'https://my-node.example.com',
+  apiKey: process.env.NODE_API_KEY!,
+});
+// bundle is the sealed CER, receipt is the normalized attestation proof
+```
+
+**Skip re-attestation when already attested:**
+
+```ts
+import { attestIfNeeded, getAttestationReceipt } from '@nexart/ai-execution';
+
+const { receipt } = await attestIfNeeded(bundle, options);
+// or just read without network call:
+const receipt = getAttestationReceipt(bundle); // null if not yet attested
+```
+
+- `getAttestationReceipt(bundle)` — extracts a normalized receipt from any supported shape (top-level fields or `bundle.meta.attestation`); returns `null` if required fields are missing, never throws
+- `attestIfNeeded(bundle, options)` — skips the node call if a valid receipt is already present; prevents double-attestation
+- `certifyAndAttestDecision(params, options)` — recommended one-call integration: `certifyDecision` + `attest` + normalized receipt
+
+### Signed Receipt Verification (v0.5.0+)
+
+After a node signs the receipt, verify it offline without a round-trip:
+
+```ts
+import {
+  verifyNodeReceiptSignature,
+  verifyBundleAttestation,
+  fetchNodeKeys,
+  selectNodeKey,
+} from '@nexart/ai-execution';
+
+// One-call: fetches node keys, selects correct key, verifies Ed25519 signature
+const result = await verifyBundleAttestation(bundle, {
+  nodeUrl: 'https://my-node.example.com',
+});
+// result.ok === true  → signature is valid
+// result.code         → CerVerifyCode enum value
+// result.details      → string[] with failure explanation (when ok=false)
+```
+
+**Verify against a specific key directly:**
+
+```ts
+const result = await verifyNodeReceiptSignature({
+  receipt: { attestationId: '...', certificateHash: 'sha256:...', ... },
+  signatureB64Url: 'aDEKyu...Q',
+  key: { jwk: { kty: 'OKP', crv: 'Ed25519', x: '<base64url pubkey>' } },
+  // or: key: { rawB64Url: '<base64url raw 32 bytes>' }
+});
+```
+
+**Failure codes:**
+
+| Code | Meaning |
+|---|---|
+| `ATTESTATION_MISSING` | No signed receipt in bundle |
+| `ATTESTATION_KEY_NOT_FOUND` | kid not found in node keys document |
+| `ATTESTATION_INVALID_SIGNATURE` | Ed25519 signature did not verify |
+| `ATTESTATION_KEY_FORMAT_UNSUPPORTED` | Key cannot be decoded (wrong crv, no fields, etc.) |
+
+**Node keys document** is fetched from `{nodeUrl}/.well-known/nexart-node.json`. See `SPEC.md` for the full shape.
+
 ### Sanitization and Redaction
 
 `sanitizeForAttestation(bundle)` returns a JSON-safe deep clone:
@@ -238,6 +324,13 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | Function | Description |
 |---|---|
 | `attest(bundle, options)` | Post CER to canonical node (auto-sanitizes) |
+| `certifyAndAttestDecision(params, options)` | One-call: certifyDecision + attest + receipt |
+| `attestIfNeeded(bundle, options)` | Attest only if no receipt already present |
+| `getAttestationReceipt(bundle)` | Extract normalized `AttestationReceipt` or `null` |
+| `verifyNodeReceiptSignature(params)` | Verify an Ed25519-signed receipt offline (v0.5.0+) |
+| `fetchNodeKeys(nodeUrl)` | Fetch `NodeKeysDocument` from `/.well-known/nexart-node.json` (v0.5.0+) |
+| `selectNodeKey(doc, kid?)` | Select a key from a `NodeKeysDocument` by kid or activeKid (v0.5.0+) |
+| `verifyBundleAttestation(bundle, options)` | One-call offline attestation verification (v0.5.0+) |
 | `sanitizeForAttestation(bundle)` | Remove `undefined` keys, reject BigInt/functions/symbols |
 | `hasAttestation(bundle)` | Check if bundle already has attestation fields |
 | `exportCer(bundle)` | Serialize to canonical JSON string |
@@ -258,6 +351,10 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | `SCHEMA_ERROR` | Wrong bundleType/version, missing snapshot, non-finite parameters, etc. |
 | `CANONICALIZATION_ERROR` | `toCanonicalJson` threw during verification |
 | `UNKNOWN_ERROR` | Catch-all for unclassified failures |
+| `ATTESTATION_MISSING` | No signed receipt found in bundle (v0.5.0+) |
+| `ATTESTATION_KEY_NOT_FOUND` | kid not found in node keys document (v0.5.0+) |
+| `ATTESTATION_INVALID_SIGNATURE` | Ed25519 signature did not verify (v0.5.0+) |
+| `ATTESTATION_KEY_FORMAT_UNSUPPORTED` | Key cannot be decoded (v0.5.0+) |
 
 Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR` > `INVALID_SHA256_FORMAT` > `CERTIFICATE_HASH_MISMATCH` > `INPUT_HASH_MISMATCH` > `OUTPUT_HASH_MISMATCH` > `SNAPSHOT_HASH_MISMATCH` > `UNKNOWN_ERROR`.
 
@@ -279,7 +376,9 @@ Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR`
 | v0.2.0 | certifyDecision, RunBuilder, attest, archive, Anthropic, wrapProvider, typed errors, workflow fields |
 | v0.3.0 | Attestation hardening (hash validation, timeout), `verify` alias, `CerAttestationError.details`, release hygiene |
 | v0.4.0 | Dual ESM/CJS build, `sanitizeForAttestation`, `hasAttestation`, auto-sanitize in `attest()`, fixed `ERR_PACKAGE_PATH_NOT_EXPORTED` |
-| **v0.4.1** | Verification reason codes (`CerVerifyCode`), `code` + `details` on `VerificationResult`, README provenance wording tightened |
+| v0.4.1 | Verification reason codes (`CerVerifyCode`), `code` + `details` on `VerificationResult`, README provenance wording tightened |
+| v0.4.2 | `AttestationReceipt`, `getAttestationReceipt`, `certifyAndAttestDecision`, `attestIfNeeded` |
+| **v0.5.0** | Ed25519 signed receipt verification: `verifyNodeReceiptSignature`, `verifyBundleAttestation`, `fetchNodeKeys`, `selectNodeKey`; new attestation `CerVerifyCode` entries; `SPEC.md`; `NodeKeysDocument`, `SignedAttestationReceipt`, `NodeReceiptVerifyResult` types |
 | v1.0.0 | Planned: API stabilization, freeze public API surface |
 
 ## Releasing