@nexart/ai-execution 0.4.0 → 0.4.2

package/README.md

@@ -1,10 +1,10 @@
-# @nexart/ai-execution v0.4.0
+# @nexart/ai-execution v0.4.2
 
 Tamper-evident records and Certified Execution Records (CER) for AI operations.
 
 ## Why Not Just Store Logs?
 
-Logs tell you what happened. CERs prove it. 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 specific AI model produced a specific output for a specific input with specific parameters, logs are insufficient. CERs provide the tamper-evident chain of custody that logs cannot.
+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.**
 
 ## What This Does
 
@@ -15,13 +15,13 @@ This package creates integrity records for AI executions. Every time you call an
 - The exact parameters used (temperature, model, etc.)
 - SHA-256 hashes of everything for tamper detection
 
-These records can be verified offline to prove the execution happened as recorded.
+These records can be verified offline to detect any post-hoc modification and prove integrity of the recorded execution.
 
-**Important:** This does NOT promise that an AI model will produce the same output twice. LLMs are not deterministic. This package provides **integrity and auditability** — proof that a specific input produced a specific output at a specific time with specific parameters.
+**Important:** This does NOT promise that an AI model will produce the same output twice, and it does not verify provider or model identity. LLMs are not deterministic. This package provides **integrity and auditability** — proof that the recorded input, output, and parameters have not been modified, and chain-of-custody for the execution record.
 
 ## 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.0 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.0"` |
+| `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,47 @@ 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
+};
+```
+
+**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
+
 ### Sanitization and Redaction
 
 `sanitizeForAttestation(bundle)` returns a JSON-safe deep clone:
@@ -238,11 +279,34 @@ 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` |
 | `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 |
 | `importCer(json)` | Parse + verify from JSON string |
 
+### Reason Codes
+
+`CerVerifyCode` — stable string-union constant exported from the package root:
+
+| Code | When set |
+|---|---|
+| `OK` | Verification passed |
+| `CERTIFICATE_HASH_MISMATCH` | `certificateHash` doesn't match recomputed hash |
+| `INPUT_HASH_MISMATCH` | `inputHash` doesn't match recomputed hash |
+| `OUTPUT_HASH_MISMATCH` | `outputHash` doesn't match recomputed hash |
+| `SNAPSHOT_HASH_MISMATCH` | Both `inputHash` and `outputHash` are wrong |
+| `INVALID_SHA256_FORMAT` | A hash field doesn't start with `sha256:` |
+| `SCHEMA_ERROR` | Wrong bundleType/version, missing snapshot, non-finite parameters, etc. |
+| `CANONICALIZATION_ERROR` | `toCanonicalJson` threw during verification |
+| `UNKNOWN_ERROR` | Catch-all for unclassified failures |
+
+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`.
+
+**These codes are stable across all future versions.** New codes may be added but existing codes will not be renamed or removed.
+
 ### Providers (sub-exports)
 
 | Function | Export path |
@@ -258,7 +322,9 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | v0.1.0 | Core snapshot + CER + verify + OpenAI adapter |
 | 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.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` |
 | v1.0.0 | Planned: API stabilization, freeze public API surface |
 
 ## Releasing

package/dist/index.cjs

@@ -32,13 +32,17 @@ var src_exports = {};
 __export(src_exports, {
   CerAttestationError: () => CerAttestationError,
   CerVerificationError: () => CerVerificationError,
+  CerVerifyCode: () => CerVerifyCode,
   RunBuilder: () => RunBuilder,
   attest: () => attest,
+  attestIfNeeded: () => attestIfNeeded,
+  certifyAndAttestDecision: () => certifyAndAttestDecision,
   certifyDecision: () => certifyDecision,
   computeInputHash: () => computeInputHash,
   computeOutputHash: () => computeOutputHash,
   createSnapshot: () => createSnapshot,
   exportCer: () => exportCer,
+  getAttestationReceipt: () => getAttestationReceipt,
   hasAttestation: () => hasAttestation,
   hashCanonicalJson: () => hashCanonicalJson,
   hashUtf8: () => hashUtf8,
@@ -54,6 +58,19 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// src/types.ts
+var CerVerifyCode = {
+  OK: "OK",
+  CERTIFICATE_HASH_MISMATCH: "CERTIFICATE_HASH_MISMATCH",
+  SNAPSHOT_HASH_MISMATCH: "SNAPSHOT_HASH_MISMATCH",
+  INPUT_HASH_MISMATCH: "INPUT_HASH_MISMATCH",
+  OUTPUT_HASH_MISMATCH: "OUTPUT_HASH_MISMATCH",
+  INVALID_SHA256_FORMAT: "INVALID_SHA256_FORMAT",
+  CANONICALIZATION_ERROR: "CANONICALIZATION_ERROR",
+  SCHEMA_ERROR: "SCHEMA_ERROR",
+  UNKNOWN_ERROR: "UNKNOWN_ERROR"
+};
+
 // src/errors.ts
 var CerVerificationError = class extends Error {
   errors;
@@ -147,7 +164,7 @@ function computeOutputHash(output) {
 }
 
 // src/snapshot.ts
-var PACKAGE_VERSION = "0.4.0";
+var PACKAGE_VERSION = "0.4.2";
 function validateParameters(params) {
   const errors = [];
   if (typeof params.temperature !== "number" || !Number.isFinite(params.temperature)) {
@@ -203,54 +220,84 @@ function createSnapshot(params) {
   return snapshot;
 }
 function verifySnapshot(snapshot) {
-  const errors = [];
+  const schemaErrors = [];
+  const formatErrors = [];
+  const inputHashErrors = [];
+  const outputHashErrors = [];
   if (snapshot.type !== "ai.execution.v1") {
-    errors.push(`Expected type "ai.execution.v1", got "${snapshot.type}"`);
+    schemaErrors.push(`Expected type "ai.execution.v1", got "${snapshot.type}"`);
   }
   if (snapshot.protocolVersion !== "1.2.0") {
-    errors.push(`Expected protocolVersion "1.2.0", got "${snapshot.protocolVersion}"`);
+    schemaErrors.push(`Expected protocolVersion "1.2.0", got "${snapshot.protocolVersion}"`);
   }
   if (snapshot.executionSurface !== "ai") {
-    errors.push(`Expected executionSurface "ai", got "${snapshot.executionSurface}"`);
+    schemaErrors.push(`Expected executionSurface "ai", got "${snapshot.executionSurface}"`);
   }
   if (!snapshot.executionId || typeof snapshot.executionId !== "string") {
-    errors.push("executionId must be a non-empty string");
+    schemaErrors.push("executionId must be a non-empty string");
   }
   if (!snapshot.timestamp || typeof snapshot.timestamp !== "string") {
-    errors.push("timestamp must be a non-empty string");
+    schemaErrors.push("timestamp must be a non-empty string");
   }
   if (!snapshot.provider || typeof snapshot.provider !== "string") {
-    errors.push("provider must be a non-empty string");
+    schemaErrors.push("provider must be a non-empty string");
   }
   if (!snapshot.model || typeof snapshot.model !== "string") {
-    errors.push("model must be a non-empty string");
+    schemaErrors.push("model must be a non-empty string");
   }
   if (!snapshot.prompt || typeof snapshot.prompt !== "string") {
-    errors.push("prompt must be a non-empty string");
+    schemaErrors.push("prompt must be a non-empty string");
   }
   if (snapshot.input === void 0 || snapshot.input === null) {
-    errors.push("input must be a string or object");
+    schemaErrors.push("input must be a string or object");
   }
   if (snapshot.output === void 0 || snapshot.output === null) {
-    errors.push("output must be a string or object");
+    schemaErrors.push("output must be a string or object");
   }
   const paramErrors = validateParameters(snapshot.parameters);
-  errors.push(...paramErrors);
+  schemaErrors.push(...paramErrors);
   if (!snapshot.inputHash || !snapshot.inputHash.startsWith("sha256:")) {
-    errors.push(`inputHash must start with "sha256:", got "${snapshot.inputHash}"`);
+    formatErrors.push(`inputHash must start with "sha256:", got "${snapshot.inputHash}"`);
   }
   if (!snapshot.outputHash || !snapshot.outputHash.startsWith("sha256:")) {
-    errors.push(`outputHash must start with "sha256:", got "${snapshot.outputHash}"`);
+    formatErrors.push(`outputHash must start with "sha256:", got "${snapshot.outputHash}"`);
   }
-  const expectedInputHash = computeInputHash(snapshot.input);
-  if (snapshot.inputHash !== expectedInputHash) {
-    errors.push(`inputHash mismatch: expected ${expectedInputHash}, got ${snapshot.inputHash}`);
+  if (formatErrors.length === 0) {
+    const expectedInputHash = computeInputHash(snapshot.input);
+    if (snapshot.inputHash !== expectedInputHash) {
+      inputHashErrors.push(`inputHash mismatch: expected ${expectedInputHash}, got ${snapshot.inputHash}`);
+    }
+    const expectedOutputHash = computeOutputHash(snapshot.output);
+    if (snapshot.outputHash !== expectedOutputHash) {
+      outputHashErrors.push(`outputHash mismatch: expected ${expectedOutputHash}, got ${snapshot.outputHash}`);
+    }
   }
-  const expectedOutputHash = computeOutputHash(snapshot.output);
-  if (snapshot.outputHash !== expectedOutputHash) {
-    errors.push(`outputHash mismatch: expected ${expectedOutputHash}, got ${snapshot.outputHash}`);
+  const errors = [...schemaErrors, ...formatErrors, ...inputHashErrors, ...outputHashErrors];
+  if (errors.length === 0) {
+    return { ok: true, errors: [], code: CerVerifyCode.OK };
+  }
+  let code;
+  let details;
+  if (schemaErrors.length > 0) {
+    code = CerVerifyCode.SCHEMA_ERROR;
+    details = schemaErrors;
+  } else if (formatErrors.length > 0) {
+    code = CerVerifyCode.INVALID_SHA256_FORMAT;
+    details = formatErrors;
+  } else if (inputHashErrors.length > 0 && outputHashErrors.length > 0) {
+    code = CerVerifyCode.SNAPSHOT_HASH_MISMATCH;
+    details = [...inputHashErrors, ...outputHashErrors];
+  } else if (inputHashErrors.length > 0) {
+    code = CerVerifyCode.INPUT_HASH_MISMATCH;
+    details = inputHashErrors;
+  } else if (outputHashErrors.length > 0) {
+    code = CerVerifyCode.OUTPUT_HASH_MISMATCH;
+    details = outputHashErrors;
+  } else {
+    code = CerVerifyCode.UNKNOWN_ERROR;
+    details = errors;
   }
-  return { ok: errors.length === 0, errors };
+  return { ok: false, errors, code, details };
 }
 
 // src/cer.ts
@@ -280,36 +327,80 @@ function sealCer(snapshot, options) {
   return bundle;
 }
 function verifyCer(bundle) {
-  const errors = [];
+  const schemaErrors = [];
+  const formatErrors = [];
   if (bundle.bundleType !== "cer.ai.execution.v1") {
-    errors.push(`Expected bundleType "cer.ai.execution.v1", got "${bundle.bundleType}"`);
+    schemaErrors.push(`Expected bundleType "cer.ai.execution.v1", got "${bundle.bundleType}"`);
   }
   if (bundle.version !== "0.1") {
-    errors.push(`Expected version "0.1", got "${bundle.version}"`);
+    schemaErrors.push(`Expected version "0.1", got "${bundle.version}"`);
   }
   if (!bundle.createdAt || typeof bundle.createdAt !== "string") {
-    errors.push("createdAt must be a non-empty string");
+    schemaErrors.push("createdAt must be a non-empty string");
   }
   if (!bundle.certificateHash || !bundle.certificateHash.startsWith("sha256:")) {
-    errors.push(`certificateHash must start with "sha256:", got "${bundle.certificateHash}"`);
+    formatErrors.push(`certificateHash must start with "sha256:", got "${bundle.certificateHash}"`);
   }
   if (!bundle.snapshot) {
-    errors.push("snapshot is required");
-    return { ok: false, errors };
+    schemaErrors.push("snapshot is required");
+    const allErrors = [...schemaErrors, ...formatErrors];
+    return { ok: false, errors: allErrors, code: CerVerifyCode.SCHEMA_ERROR, details: schemaErrors };
   }
-  const snapshotResult = verifySnapshot(bundle.snapshot);
-  errors.push(...snapshotResult.errors);
-  const payload = {
-    bundleType: "cer.ai.execution.v1",
-    createdAt: bundle.createdAt,
-    snapshot: bundle.snapshot,
-    version: "0.1"
-  };
-  const expectedHash = computeCertificateHash(payload);
-  if (bundle.certificateHash !== expectedHash) {
-    errors.push(`certificateHash mismatch: expected ${expectedHash}, got ${bundle.certificateHash}`);
+  let canonicalizationError = null;
+  let snapshotResult = null;
+  try {
+    snapshotResult = verifySnapshot(bundle.snapshot);
+  } catch (err) {
+    canonicalizationError = err instanceof Error ? err.message : String(err);
+  }
+  if (canonicalizationError !== null) {
+    const errors2 = [...schemaErrors, ...formatErrors, canonicalizationError];
+    return { ok: false, errors: errors2, code: CerVerifyCode.CANONICALIZATION_ERROR, details: [canonicalizationError] };
+  }
+  const snapshotErrors = snapshotResult.errors;
+  const certHashErrors = [];
+  try {
+    const payload = {
+      bundleType: "cer.ai.execution.v1",
+      createdAt: bundle.createdAt,
+      snapshot: bundle.snapshot,
+      version: "0.1"
+    };
+    const expectedHash = computeCertificateHash(payload);
+    if (bundle.certificateHash !== expectedHash) {
+      certHashErrors.push(`certificateHash mismatch: expected ${expectedHash}, got ${bundle.certificateHash}`);
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const errors2 = [...schemaErrors, ...formatErrors, ...snapshotErrors, msg];
+    return { ok: false, errors: errors2, code: CerVerifyCode.CANONICALIZATION_ERROR, details: [msg] };
+  }
+  const errors = [...schemaErrors, ...formatErrors, ...snapshotErrors, ...certHashErrors];
+  if (errors.length === 0) {
+    return { ok: true, errors: [], code: CerVerifyCode.OK };
+  }
+  let code;
+  let details;
+  if (schemaErrors.length > 0) {
+    code = CerVerifyCode.SCHEMA_ERROR;
+    details = schemaErrors;
+  } else if (formatErrors.length > 0) {
+    code = CerVerifyCode.INVALID_SHA256_FORMAT;
+    details = formatErrors;
+  } else if (certHashErrors.length > 0 && snapshotErrors.length === 0) {
+    code = CerVerifyCode.CERTIFICATE_HASH_MISMATCH;
+    details = certHashErrors;
+  } else if (snapshotResult && snapshotResult.code !== CerVerifyCode.OK) {
+    code = snapshotResult.code;
+    details = snapshotResult.details ?? snapshotErrors;
+  } else if (certHashErrors.length > 0) {
+    code = CerVerifyCode.CERTIFICATE_HASH_MISMATCH;
+    details = certHashErrors;
+  } else {
+    code = CerVerifyCode.UNKNOWN_ERROR;
+    details = errors;
   }
-  return { ok: errors.length === 0, errors };
+  return { ok: false, errors, code, details };
 }
 
 // src/certify.ts
@@ -580,17 +671,93 @@ function wrapProvider(config) {
     }
   };
 }
+
+// src/receipt.ts
+function extractStr(obj, key) {
+  const v = obj[key];
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+function buildReceipt(obj) {
+  const attestationId = extractStr(obj, "attestationId");
+  const certificateHash = extractStr(obj, "certificateHash");
+  const nodeRuntimeHash = extractStr(obj, "nodeRuntimeHash");
+  const protocolVersion = extractStr(obj, "protocolVersion");
+  if (!attestationId || !certificateHash || !nodeRuntimeHash || !protocolVersion) {
+    return null;
+  }
+  const receipt = {
+    attestationId,
+    certificateHash,
+    nodeRuntimeHash,
+    protocolVersion
+  };
+  const nodeId = extractStr(obj, "nodeId");
+  if (nodeId) receipt.nodeId = nodeId;
+  const attestedAt = extractStr(obj, "attestedAt");
+  if (attestedAt) receipt.attestedAt = attestedAt;
+  return receipt;
+}
+function getAttestationReceipt(bundle) {
+  if (typeof bundle !== "object" || bundle === null) return null;
+  const b = bundle;
+  const topLevel = buildReceipt(b);
+  if (topLevel) return topLevel;
+  if (typeof b.meta === "object" && b.meta !== null) {
+    const meta = b.meta;
+    if (typeof meta.attestation === "object" && meta.attestation !== null) {
+      const nested = buildReceipt(meta.attestation);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+// src/wrappers.ts
+function receiptFromProof(proof, bundle) {
+  if (!proof.attestationId || !proof.nodeRuntimeHash || !proof.protocolVersion) {
+    throw new CerAttestationError(
+      "Attestation proof is missing required fields (attestationId, nodeRuntimeHash, protocolVersion)"
+    );
+  }
+  return {
+    attestationId: proof.attestationId,
+    certificateHash: proof.certificateHash ?? bundle.certificateHash,
+    nodeRuntimeHash: proof.nodeRuntimeHash,
+    protocolVersion: proof.protocolVersion
+  };
+}
+async function certifyAndAttestDecision(params, options) {
+  const bundle = certifyDecision(params);
+  const proof = await attest(bundle, options);
+  const receipt = receiptFromProof(proof, bundle);
+  return { bundle, receipt };
+}
+async function attestIfNeeded(bundle, options) {
+  if (hasAttestation(bundle)) {
+    const existing = getAttestationReceipt(bundle);
+    if (existing) {
+      return { bundle, receipt: existing };
+    }
+  }
+  const proof = await attest(bundle, options);
+  const receipt = receiptFromProof(proof, bundle);
+  return { bundle, receipt };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CerAttestationError,
   CerVerificationError,
+  CerVerifyCode,
   RunBuilder,
   attest,
+  attestIfNeeded,
+  certifyAndAttestDecision,
   certifyDecision,
   computeInputHash,
   computeOutputHash,
   createSnapshot,
   exportCer,
+  getAttestationReceipt,
   hasAttestation,
   hashCanonicalJson,
   hashUtf8,