@nexart/ai-execution 0.6.0 → 0.8.0

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(src_exports, {
   attest: () => attest,
   attestIfNeeded: () => attestIfNeeded,
   certifyAndAttestDecision: () => certifyAndAttestDecision,
+  certifyAndAttestRun: () => certifyAndAttestRun,
   certifyDecision: () => certifyDecision,
   certifyDecisionFromProviderCall: () => certifyDecisionFromProviderCall,
   computeInputHash: () => computeInputHash,
@@ -44,12 +45,17 @@ __export(src_exports, {
   createClient: () => createClient,
   createSnapshot: () => createSnapshot,
   exportCer: () => exportCer,
+  exportVerifiableRedacted: () => exportVerifiableRedacted,
   fetchNodeKeys: () => fetchNodeKeys,
   getAttestationReceipt: () => getAttestationReceipt,
   hasAttestation: () => hasAttestation,
   hashCanonicalJson: () => hashCanonicalJson,
+  hashToolOutput: () => hashToolOutput,
   hashUtf8: () => hashUtf8,
   importCer: () => importCer,
+  makeToolEvent: () => makeToolEvent,
+  mapToAiefReason: () => mapToAiefReason,
+  redactBeforeSeal: () => redactBeforeSeal,
   sanitizeForAttestation: () => sanitizeForAttestation,
   sanitizeForStamp: () => sanitizeForStamp,
   sanitizeForStorage: () => sanitizeForStorage,
@@ -57,10 +63,13 @@ __export(src_exports, {
   selectNodeKey: () => selectNodeKey,
   sha256Hex: () => sha256Hex,
   toCanonicalJson: () => toCanonicalJson,
+  validateProfile: () => validateProfile,
   verify: () => verifyCer,
+  verifyAief: () => verifyAief,
   verifyBundleAttestation: () => verifyBundleAttestation,
   verifyCer: () => verifyCer,
   verifyNodeReceiptSignature: () => verifyNodeReceiptSignature,
+  verifyRunSummary: () => verifyRunSummary,
   verifySnapshot: () => verifySnapshot,
   wrapProvider: () => wrapProvider
 });
@@ -80,7 +89,13 @@ var CerVerifyCode = {
   ATTESTATION_MISSING: "ATTESTATION_MISSING",
   ATTESTATION_KEY_NOT_FOUND: "ATTESTATION_KEY_NOT_FOUND",
   ATTESTATION_INVALID_SIGNATURE: "ATTESTATION_INVALID_SIGNATURE",
-  ATTESTATION_KEY_FORMAT_UNSUPPORTED: "ATTESTATION_KEY_FORMAT_UNSUPPORTED"
+  ATTESTATION_KEY_FORMAT_UNSUPPORTED: "ATTESTATION_KEY_FORMAT_UNSUPPORTED",
+  // v0.7.0 — Level 4 + AIEF interop codes
+  CHAIN_BREAK_DETECTED: "CHAIN_BREAK_DETECTED",
+  INCOMPLETE_ARTIFACT: "INCOMPLETE_ARTIFACT",
+  VERIFICATION_MATERIAL_UNAVAILABLE: "VERIFICATION_MATERIAL_UNAVAILABLE",
+  TOOL_EVIDENCE_MISSING: "TOOL_EVIDENCE_MISSING",
+  TOOL_OUTPUT_HASH_MISMATCH: "TOOL_OUTPUT_HASH_MISMATCH"
 };
 
 // src/errors.ts
@@ -176,7 +191,7 @@ function computeOutputHash(output) {
 }
 
 // src/snapshot.ts
-var PACKAGE_VERSION = "0.6.0";
+var PACKAGE_VERSION = "0.8.0";
 function validateParameters(params) {
   const errors = [];
   if (typeof params.temperature !== "number" || !Number.isFinite(params.temperature)) {
@@ -229,6 +244,9 @@ function createSnapshot(params) {
   if (params.workflowId !== void 0) snapshot.workflowId = params.workflowId ?? null;
   if (params.conversationId !== void 0) snapshot.conversationId = params.conversationId ?? null;
   if (params.prevStepHash !== void 0) snapshot.prevStepHash = params.prevStepHash ?? null;
+  if (params.toolCalls !== void 0 && params.toolCalls.length > 0) {
+    snapshot.toolCalls = params.toolCalls;
+  }
   return snapshot;
 }
 function verifySnapshot(snapshot) {
@@ -336,6 +354,9 @@ function sealCer(snapshot, options) {
   if (options?.meta) {
     bundle.meta = options.meta;
   }
+  if (options?.declaration) {
+    bundle.declaration = options.declaration;
+  }
   return bundle;
 }
 function verifyCer(bundle) {
@@ -2150,6 +2171,375 @@ function createClient(defaults = {}) {
     }
   };
 }
+
+// src/aief.ts
+var AIEF_REASON_MAP = {
+  [CerVerifyCode.OK]: "ok",
+  [CerVerifyCode.CERTIFICATE_HASH_MISMATCH]: "integrityProofMismatch",
+  [CerVerifyCode.SNAPSHOT_HASH_MISMATCH]: "integrityProofMismatch",
+  [CerVerifyCode.INPUT_HASH_MISMATCH]: "integrityProofMismatch",
+  [CerVerifyCode.OUTPUT_HASH_MISMATCH]: "integrityProofMismatch",
+  [CerVerifyCode.TOOL_OUTPUT_HASH_MISMATCH]: "integrityProofMismatch",
+  [CerVerifyCode.SCHEMA_ERROR]: "unsupportedSchema",
+  [CerVerifyCode.CANONICALIZATION_ERROR]: "malformedArtifact",
+  [CerVerifyCode.INVALID_SHA256_FORMAT]: "malformedArtifact",
+  [CerVerifyCode.UNKNOWN_ERROR]: "malformedArtifact",
+  [CerVerifyCode.INCOMPLETE_ARTIFACT]: "incompleteArtifact",
+  [CerVerifyCode.CHAIN_BREAK_DETECTED]: "chainBreakDetected",
+  [CerVerifyCode.VERIFICATION_MATERIAL_UNAVAILABLE]: "verificationMaterialUnavailable",
+  [CerVerifyCode.TOOL_EVIDENCE_MISSING]: "incompleteArtifact",
+  [CerVerifyCode.ATTESTATION_INVALID_SIGNATURE]: "signatureInvalid",
+  [CerVerifyCode.ATTESTATION_MISSING]: "verificationMaterialUnavailable",
+  [CerVerifyCode.ATTESTATION_KEY_NOT_FOUND]: "verificationMaterialUnavailable",
+  [CerVerifyCode.ATTESTATION_KEY_FORMAT_UNSUPPORTED]: "verificationMaterialUnavailable"
+};
+var INTEGRITY_FAILURE_CODES = /* @__PURE__ */ new Set([
+  CerVerifyCode.CERTIFICATE_HASH_MISMATCH,
+  CerVerifyCode.SNAPSHOT_HASH_MISMATCH,
+  CerVerifyCode.INPUT_HASH_MISMATCH,
+  CerVerifyCode.OUTPUT_HASH_MISMATCH,
+  CerVerifyCode.TOOL_OUTPUT_HASH_MISMATCH
+]);
+var SCHEMA_FAILURE_CODES = /* @__PURE__ */ new Set([
+  CerVerifyCode.SCHEMA_ERROR,
+  CerVerifyCode.CANONICALIZATION_ERROR,
+  CerVerifyCode.INVALID_SHA256_FORMAT,
+  CerVerifyCode.UNKNOWN_ERROR,
+  CerVerifyCode.INCOMPLETE_ARTIFACT
+]);
+function mapToAiefReason(code) {
+  return AIEF_REASON_MAP[code] ?? "malformedArtifact";
+}
+function verifyAief(bundle) {
+  const inner = verifyCer(bundle);
+  if (inner.ok) {
+    return {
+      result: "PASS",
+      reason: null,
+      checks: {
+        schemaSupported: true,
+        integrityValid: true,
+        protectedSetValid: true,
+        chainValid: true
+      }
+    };
+  }
+  const aiefReason = mapToAiefReason(inner.code);
+  const isIntegrityFailure = INTEGRITY_FAILURE_CODES.has(inner.code);
+  const isSchemaFailure = SCHEMA_FAILURE_CODES.has(inner.code);
+  const isChainFailure = inner.code === CerVerifyCode.CHAIN_BREAK_DETECTED;
+  const result = {
+    result: "FAIL",
+    reason: aiefReason,
+    checks: {
+      schemaSupported: !isSchemaFailure,
+      integrityValid: !isIntegrityFailure,
+      protectedSetValid: !isIntegrityFailure,
+      chainValid: !isChainFailure
+    }
+  };
+  if (inner.details && inner.details.length > 0) {
+    result.notes = inner.details;
+  } else if (inner.errors.length > 0) {
+    result.notes = inner.errors;
+  }
+  return result;
+}
+
+// src/tools.ts
+function hashToolOutput(value) {
+  if (typeof value === "string") {
+    return hashUtf8(value);
+  }
+  return hashCanonicalJson(value);
+}
+function makeToolEvent(params) {
+  const at = params.at ?? (/* @__PURE__ */ new Date()).toISOString();
+  const outputHash = hashToolOutput(params.output);
+  const event = {
+    toolId: params.toolId,
+    at,
+    outputHash
+  };
+  if (params.input !== void 0) {
+    event.inputHash = hashToolOutput(params.input);
+  }
+  if (params.evidenceRef !== void 0) {
+    event.evidenceRef = params.evidenceRef;
+  }
+  if (params.error !== void 0) {
+    event.error = params.error;
+  }
+  return event;
+}
+
+// src/chain.ts
+function verifyRunSummary(summary, bundles, opts) {
+  if (bundles.length !== summary.stepCount) {
+    return {
+      ok: false,
+      code: CerVerifyCode.INCOMPLETE_ARTIFACT,
+      errors: [
+        `Step count mismatch: summary declares ${summary.stepCount} step(s), received ${bundles.length}`
+      ],
+      details: ["Possible step deletion or insertion"]
+    };
+  }
+  if (bundles.length === 0) {
+    return { ok: true, code: CerVerifyCode.OK, errors: [] };
+  }
+  let prevHash = null;
+  for (let i = 0; i < bundles.length; i++) {
+    const bundle = bundles[i];
+    const summaryStep = summary.steps[i];
+    if (!summaryStep) {
+      return {
+        ok: false,
+        code: CerVerifyCode.INCOMPLETE_ARTIFACT,
+        errors: [`Missing summary entry for step index ${i}`],
+        breakAt: i
+      };
+    }
+    if (!opts?.skipBundleVerification) {
+      const bundleResult = verifyCer(bundle);
+      if (!bundleResult.ok) {
+        return {
+          ok: false,
+          code: bundleResult.code,
+          errors: [`Step ${i}: individual bundle verification failed: ${bundleResult.errors.join("; ")}`],
+          details: bundleResult.details,
+          breakAt: i
+        };
+      }
+    }
+    const stepIndex = bundle.snapshot?.stepIndex;
+    if (stepIndex !== i) {
+      return {
+        ok: false,
+        code: CerVerifyCode.CHAIN_BREAK_DETECTED,
+        errors: [`Step ${i}: expected stepIndex ${i}, got ${String(stepIndex)}`],
+        details: ["stepIndex mismatch indicates insertion or reordering"],
+        breakAt: i
+      };
+    }
+    const snapshotPrevHash = bundle.snapshot?.prevStepHash ?? null;
+    if (i === 0) {
+      if (snapshotPrevHash !== null) {
+        return {
+          ok: false,
+          code: CerVerifyCode.CHAIN_BREAK_DETECTED,
+          errors: [`Step 0: expected prevStepHash null, got "${snapshotPrevHash}"`],
+          details: ["First step must have prevStepHash null"],
+          breakAt: 0,
+          expectedPrev: "null",
+          observedPrev: snapshotPrevHash
+        };
+      }
+    } else {
+      if (snapshotPrevHash !== prevHash) {
+        return {
+          ok: false,
+          code: CerVerifyCode.CHAIN_BREAK_DETECTED,
+          errors: [`Step ${i}: prevStepHash mismatch \u2014 chain break detected`],
+          details: [
+            `Expected prevStepHash "${prevHash ?? "null"}", got "${snapshotPrevHash ?? "null"}"`
+          ],
+          breakAt: i,
+          expectedPrev: prevHash ?? void 0,
+          observedPrev: snapshotPrevHash ?? void 0
+        };
+      }
+    }
+    if (bundle.certificateHash !== summaryStep.certificateHash) {
+      return {
+        ok: false,
+        code: CerVerifyCode.CHAIN_BREAK_DETECTED,
+        errors: [`Step ${i}: certificateHash does not match summary record`],
+        details: [
+          `Summary has "${summaryStep.certificateHash}", bundle has "${bundle.certificateHash}"`
+        ],
+        breakAt: i
+      };
+    }
+    prevHash = bundle.certificateHash;
+  }
+  const lastBundle = bundles[bundles.length - 1];
+  if (summary.finalStepHash !== lastBundle.certificateHash) {
+    return {
+      ok: false,
+      code: CerVerifyCode.CHAIN_BREAK_DETECTED,
+      errors: ["summary.finalStepHash does not match last step certificateHash"],
+      details: [
+        `Expected "${summary.finalStepHash ?? "null"}", got "${lastBundle.certificateHash}"`
+      ],
+      breakAt: bundles.length - 1,
+      expectedPrev: summary.finalStepHash ?? void 0,
+      observedPrev: lastBundle.certificateHash
+    };
+  }
+  return { ok: true, code: CerVerifyCode.OK, errors: [] };
+}
+
+// src/redact.ts
+function hashValue(value) {
+  if (typeof value === "string") return hashUtf8(value);
+  return hashCanonicalJson(value);
+}
+function getNestedValue(obj, path) {
+  const parts = path.split(".");
+  let cursor = obj;
+  for (const part of parts) {
+    if (typeof cursor !== "object" || cursor === null) return void 0;
+    cursor = cursor[part];
+  }
+  return cursor;
+}
+function setNestedPath(obj, path, value) {
+  const parts = path.split(".");
+  const clone = { ...obj };
+  let cursor = clone;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i];
+    const child = cursor[key];
+    if (typeof child !== "object" || child === null) return clone;
+    cursor[key] = { ...child };
+    cursor = cursor[key];
+  }
+  const last = parts[parts.length - 1];
+  if (last in cursor) {
+    cursor[last] = value;
+  }
+  return clone;
+}
+function redactBeforeSeal(snapshot, policy) {
+  let result = { ...snapshot };
+  for (const path of policy.paths) {
+    const original = getNestedValue(result, path);
+    if (original === void 0) continue;
+    const envelope = {
+      _redacted: true,
+      hash: hashValue(original)
+    };
+    result = setNestedPath(result, path, envelope);
+    if (path === "input") {
+      result["inputHash"] = computeInputHash(envelope);
+    } else if (path === "output") {
+      result["outputHash"] = computeOutputHash(envelope);
+    }
+  }
+  return result;
+}
+
+// src/profile.ts
+var SHA256_PATTERN2 = /^sha256:[0-9a-f]{64}$/;
+function validateToolEvent(event, index) {
+  const errs = [];
+  if (!event.toolId || typeof event.toolId !== "string") {
+    errs.push(`toolCalls[${index}].toolId must be a non-empty string`);
+  }
+  if (!event.at || typeof event.at !== "string") {
+    errs.push(`toolCalls[${index}].at must be a non-empty ISO 8601 string`);
+  }
+  if (!event.outputHash || !SHA256_PATTERN2.test(event.outputHash)) {
+    errs.push(`toolCalls[${index}].outputHash must be in sha256:<64hex> format, got "${event.outputHash ?? ""}"`);
+  }
+  if (event.inputHash !== void 0 && !SHA256_PATTERN2.test(event.inputHash)) {
+    errs.push(`toolCalls[${index}].inputHash must be in sha256:<64hex> format when present`);
+  }
+  return errs;
+}
+function validateL2(snapshot, label) {
+  const errs = [];
+  if (!snapshot.executionId) errs.push(`executionId is required for ${label}`);
+  if (!snapshot.timestamp) errs.push(`timestamp is required for ${label}`);
+  if (!snapshot.provider) errs.push(`provider is required for ${label}`);
+  if (!snapshot.model) errs.push(`model is required for ${label}`);
+  if (snapshot.input === void 0 || snapshot.input === null) errs.push(`input is required for ${label}`);
+  if (snapshot.output === void 0 || snapshot.output === null) errs.push(`output is required for ${label}`);
+  if (!snapshot.inputHash) errs.push(`inputHash is required for ${label}`);
+  if (!snapshot.outputHash) errs.push(`outputHash is required for ${label}`);
+  return errs;
+}
+function resolveSnapshot(target) {
+  if ("snapshot" in target && target.snapshot) {
+    return target.snapshot;
+  }
+  return target;
+}
+function validateProfile(target, profile) {
+  if (profile === "flexible") {
+    return { ok: true, errors: [] };
+  }
+  const snapshot = resolveSnapshot(target);
+  const errors = [];
+  if (profile === "AIEF_L2" || profile === "AIEF_L3" || profile === "AIEF_L4") {
+    errors.push(...validateL2(snapshot, profile));
+  }
+  if (profile === "AIEF_L4") {
+    if (snapshot.toolCalls && snapshot.toolCalls.length > 0) {
+      for (let i = 0; i < snapshot.toolCalls.length; i++) {
+        errors.push(...validateToolEvent(snapshot.toolCalls[i], i));
+      }
+    }
+    if (snapshot.stepIndex !== null && snapshot.stepIndex !== void 0 && snapshot.stepIndex > 0 && !snapshot.prevStepHash) {
+      errors.push("prevStepHash is required when stepIndex > 0 in AIEF_L4 profile");
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// src/exportRedacted.ts
+function exportVerifiableRedacted(bundle, policy, options) {
+  const createdAt = options?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const redactedSnapshot = redactBeforeSeal(bundle.snapshot, policy);
+  const provenance = {
+    originalCertificateHash: bundle.certificateHash,
+    redactionPolicy: { paths: [...policy.paths] },
+    redactedAt: createdAt
+  };
+  const mergedMeta = {
+    ...bundle.meta,
+    provenance
+  };
+  const newBundle = sealCer(redactedSnapshot, {
+    createdAt,
+    meta: mergedMeta,
+    declaration: bundle.declaration
+  });
+  return {
+    bundle: newBundle,
+    originalCertificateHash: bundle.certificateHash
+  };
+}
+
+// src/runHelper.ts
+async function certifyAndAttestRun(steps, options) {
+  const run = new RunBuilder({
+    runId: options?.runId,
+    workflowId: options?.workflowId,
+    conversationId: options?.conversationId,
+    appId: options?.appId
+  });
+  const stepBundles = [];
+  const receipts = [];
+  for (const stepParams of steps) {
+    const bundle = run.step(stepParams);
+    stepBundles.push(bundle);
+    if (options?.attestStep) {
+      const receipt = await options.attestStep(bundle);
+      receipts.push(receipt);
+    } else {
+      receipts.push(null);
+    }
+  }
+  const runSummary = run.finalize();
+  return {
+    runSummary,
+    stepBundles,
+    receipts,
+    finalStepHash: runSummary.finalStepHash
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CerAttestationError,
@@ -2159,6 +2549,7 @@ function createClient(defaults = {}) {
   attest,
   attestIfNeeded,
   certifyAndAttestDecision,
+  certifyAndAttestRun,
   certifyDecision,
   certifyDecisionFromProviderCall,
   computeInputHash,
@@ -2166,12 +2557,17 @@ function createClient(defaults = {}) {
   createClient,
   createSnapshot,
   exportCer,
+  exportVerifiableRedacted,
   fetchNodeKeys,
   getAttestationReceipt,
   hasAttestation,
   hashCanonicalJson,
+  hashToolOutput,
   hashUtf8,
   importCer,
+  makeToolEvent,
+  mapToAiefReason,
+  redactBeforeSeal,
   sanitizeForAttestation,
   sanitizeForStamp,
   sanitizeForStorage,
@@ -2179,10 +2575,13 @@ function createClient(defaults = {}) {
   selectNodeKey,
   sha256Hex,
   toCanonicalJson,
+  validateProfile,
   verify,
+  verifyAief,
   verifyBundleAttestation,
   verifyCer,
   verifyNodeReceiptSignature,
+  verifyRunSummary,
   verifySnapshot,
   wrapProvider
 });