@nexart/ai-execution 0.4.2 → 0.5.0

package/README.md

@@ -1,4 +1,4 @@
-# @nexart/ai-execution v0.4.2
+# @nexart/ai-execution v0.5.0
 
 Tamper-evident records and Certified Execution Records (CER) for AI operations.
 
@@ -192,6 +192,8 @@ type AttestationReceipt = {
   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+)
 };
 ```
 
@@ -221,6 +223,49 @@ const receipt = getAttestationReceipt(bundle); // null if not yet attested
 - `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:
@@ -282,6 +327,10 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | `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 |
@@ -302,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`.
 
@@ -324,7 +377,8 @@ Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR`
 | 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.2** | `AttestationReceipt`, `getAttestationReceipt`, `certifyAndAttestDecision`, `attestIfNeeded` |
+| 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