@nexart/ai-execution 0.4.2 → 0.6.0

package/README.md

@@ -1,7 +1,15 @@
-# @nexart/ai-execution v0.4.2
+# @nexart/ai-execution v0.6.0
 
 Tamper-evident records and Certified Execution Records (CER) for AI operations.
 
+## Version Information
+
+| Component | Version |
+|---|---|
+| Service | — |
+| SDK | 0.6.0 |
+| Protocol | 1.2.0 |
+
 ## Why Not Just Store Logs?
 
 Logs tell you what happened. CERs prove integrity. A log entry can be edited, truncated, or fabricated after the fact with no way to detect it. A CER bundle is cryptographically sealed: any modification — to the input, output, parameters, or ordering — invalidates the certificate hash. If you need to demonstrate to an auditor, regulator, or downstream system that a recorded execution has not been modified post-hoc, logs are insufficient. CERs provide the tamper-evident chain of custody that logs cannot. **CERs certify records, not model determinism or provider execution.**
@@ -192,6 +200,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 +231,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,11 +335,29 @@ 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 |
+| `sanitizeForStorage(bundle, options?)` | Sanitize for DB storage with optional path-based redaction; does not recompute hashes (v0.6.0+) |
+| `sanitizeForStamp(bundle)` | Extract attestable core (no meta); does not recompute hashes (v0.6.0+) |
 | `hasAttestation(bundle)` | Check if bundle already has attestation fields |
 | `exportCer(bundle)` | Serialize to canonical JSON string |
 | `importCer(json)` | Parse + verify from JSON string |
 
+### Provider Drop-in (v0.6.0+)
+
+| Function | Description |
+|---|---|
+| `certifyDecisionFromProviderCall(params)` | One-function wrapper: extracts prompt/input/output/params from raw provider request+response and returns `{ ok, bundle }` or `{ ok: false, code: 'SCHEMA_ERROR', reason }`. Supports OpenAI, Anthropic, Gemini, Mistral, Bedrock, and generic shapes. |
+
+### Opinionated Client (v0.6.0+)
+
+| Export | Description |
+|---|---|
+| `createClient(defaults)` | Returns a `NexArtClient` with bound defaults (`appId`, `workflowId`, `nodeUrl`, `apiKey`, `tags`, `source`). Methods: `certifyDecision`, `certifyAndAttestDecision`, `verify`, `verifyBundleAttestation`. Defaults do not affect bundle hashing. |
+
 ### Reason Codes
 
 `CerVerifyCode` — stable string-union constant exported from the package root:
@@ -302,6 +373,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 +399,9 @@ 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 |
+| **v0.6.0** | Frictionless integration: `certifyDecisionFromProviderCall` (OpenAI/Anthropic/Gemini/Mistral/Bedrock drop-in); `sanitizeForStorage` + `sanitizeForStamp` redaction helpers; `createClient(defaults)` factory; regression fixture suite; all backward-compatible, no hash changes |
 | v1.0.0 | Planned: API stabilization, freeze public API surface |
 
 ## Releasing