@nexart/ai-execution 0.5.0 → 0.6.0

package/README.md

@@ -1,7 +1,15 @@
-# @nexart/ai-execution v0.5.0
+# @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.**
@@ -332,10 +340,24 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | `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:
@@ -378,7 +400,8 @@ Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR`
 | 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.5.0** | Ed25519 signed receipt verification: `verifyNodeReceiptSignature`, `verifyBundleAttestation`, `fetchNodeKeys`, `selectNodeKey`; new attestation `CerVerifyCode` entries; `SPEC.md`; `NodeKeysDocument`, `SignedAttestationReceipt`, `NodeReceiptVerifyResult` types |
+| 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

package/dist/index.cjs

@@ -38,8 +38,10 @@ __export(src_exports, {
   attestIfNeeded: () => attestIfNeeded,
   certifyAndAttestDecision: () => certifyAndAttestDecision,
   certifyDecision: () => certifyDecision,
+  certifyDecisionFromProviderCall: () => certifyDecisionFromProviderCall,
   computeInputHash: () => computeInputHash,
   computeOutputHash: () => computeOutputHash,
+  createClient: () => createClient,
   createSnapshot: () => createSnapshot,
   exportCer: () => exportCer,
   fetchNodeKeys: () => fetchNodeKeys,
@@ -49,6 +51,8 @@ __export(src_exports, {
   hashUtf8: () => hashUtf8,
   importCer: () => importCer,
   sanitizeForAttestation: () => sanitizeForAttestation,
+  sanitizeForStamp: () => sanitizeForStamp,
+  sanitizeForStorage: () => sanitizeForStorage,
   sealCer: () => sealCer,
   selectNodeKey: () => selectNodeKey,
   sha256Hex: () => sha256Hex,
@@ -172,7 +176,7 @@ function computeOutputHash(output) {
 }
 
 // src/snapshot.ts
-var PACKAGE_VERSION = "0.5.0";
+var PACKAGE_VERSION = "0.6.0";
 function validateParameters(params) {
   const errors = [];
   if (typeof params.temperature !== "number" || !Number.isFinite(params.temperature)) {
@@ -523,9 +527,45 @@ function deepRemoveUndefined(value) {
   }
   return value;
 }
+function redactPath(obj, path, replacement) {
+  const parts = path.split(".");
+  const clone = { ...obj };
+  let cursor = clone;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i];
+    if (typeof cursor[key] !== "object" || cursor[key] === null) return clone;
+    cursor[key] = { ...cursor[key] };
+    cursor = cursor[key];
+  }
+  const last = parts[parts.length - 1];
+  if (last in cursor) cursor[last] = replacement;
+  return clone;
+}
 function sanitizeForAttestation(bundle) {
   return deepRemoveUndefined(bundle);
 }
+function sanitizeForStorage(bundle, options) {
+  let cleaned = deepRemoveUndefined(bundle);
+  if (options?.redactPaths && options.redactPaths.length > 0) {
+    const replacement = options.redactWith ?? "[REDACTED]";
+    let obj = cleaned;
+    for (const path of options.redactPaths) {
+      obj = redactPath(obj, path, replacement);
+    }
+    cleaned = obj;
+  }
+  return cleaned;
+}
+function sanitizeForStamp(bundle) {
+  const core = {
+    bundleType: bundle.bundleType,
+    certificateHash: bundle.certificateHash,
+    createdAt: bundle.createdAt,
+    version: bundle.version,
+    snapshot: bundle.snapshot
+  };
+  return deepRemoveUndefined(core);
+}
 function hasAttestation(bundle) {
   if (typeof bundle !== "object" || bundle === null) return false;
   const b = bundle;
@@ -844,10 +884,10 @@ var M = (a, b = P) => {
   return r >= 0n ? r : b + r;
 };
 var modN = (a) => M(a, N);
-var invert = (num, md) => {
-  if (num === 0n || md <= 0n)
-    err("no inverse n=" + num + " mod=" + md);
-  let a = M(num, md), b = md, x = 0n, y = 1n, u = 1n, v = 0n;
+var invert = (num2, md) => {
+  if (num2 === 0n || md <= 0n)
+    err("no inverse n=" + num2 + " mod=" + md);
+  let a = M(num2, md), b = md, x = 0n, y = 1n, u = 1n, v = 0n;
   while (a !== 0n) {
     const q = b / a, r = b % a;
     const m = x - u * q, n = y - v * q;
@@ -1064,7 +1104,7 @@ var G = new Point(Gx, Gy, 1n, M(Gx * Gy));
 var I = new Point(0n, 1n, 1n, 0n);
 Point.BASE = G;
 Point.ZERO = I;
-var numTo32bLE = (num) => hexToBytes(padh(assertRange(num, 0n, B256), L2)).reverse();
+var numTo32bLE = (num2) => hexToBytes(padh(assertRange(num2, 0n, B256), L2)).reverse();
 var bytesToNumLE = (b) => big("0x" + bytesToHex(u8fr(abytes(b)).reverse()));
 var pow2 = (x, power) => {
   let r = x;
@@ -1237,10 +1277,10 @@ function clean(...arrays) {
 function createView(arr) {
   return new DataView(arr.buffer, arr.byteOffset, arr.byteLength);
 }
-function utf8ToBytes(str) {
-  if (typeof str !== "string")
+function utf8ToBytes(str2) {
+  if (typeof str2 !== "string")
     throw new Error("string expected");
-  return new Uint8Array(new TextEncoder().encode(str));
+  return new Uint8Array(new TextEncoder().encode(str2));
 }
 function toBytes(data) {
   if (typeof data === "string")
@@ -1846,6 +1886,270 @@ async function verifyBundleAttestation(bundle, options) {
   if (contextLines.length === 0) return sigResult;
   return sigResult.ok ? { ok: true, code: CerVerifyCode.OK, details: contextLines } : { ...sigResult, details: [...contextLines, ...sigResult.details ?? []] };
 }
+
+// src/certifyFromProvider.ts
+var crypto5 = __toESM(require("crypto"), 1);
+
+// src/providerExtract.ts
+function str(v) {
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+function num(v, fallback) {
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+function numOrNull(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function extractChoicesOutput(response) {
+  const choices = response.choices;
+  if (!Array.isArray(choices) || choices.length === 0) return null;
+  const first = choices[0];
+  if (!first || typeof first !== "object") return null;
+  const msg = first.message;
+  if (!msg || typeof msg !== "object") return null;
+  if (typeof msg.content === "string") return msg.content;
+  if (Array.isArray(msg.content)) {
+    const texts = msg.content.filter((p) => typeof p === "object" && p !== null).map((p) => str(p.text)).filter((t) => t !== null);
+    return texts.length > 0 ? texts.join("\n") : null;
+  }
+  return null;
+}
+function extractAnthropicOutput(response) {
+  const content = response.content;
+  if (!Array.isArray(content) || content.length === 0) return null;
+  const first = content[0];
+  if (!first || typeof first !== "object") return null;
+  return str(first.text);
+}
+function extractGeminiOutput(response) {
+  const candidates = response.candidates;
+  if (!Array.isArray(candidates) || candidates.length === 0) return null;
+  const first = candidates[0];
+  if (!first || typeof first !== "object") return null;
+  const contentObj = first.content;
+  if (!contentObj || typeof contentObj !== "object") return null;
+  const parts = contentObj.parts;
+  if (!Array.isArray(parts) || parts.length === 0) return null;
+  const part = parts[0];
+  if (!part || typeof part !== "object") return null;
+  return str(part.text);
+}
+function extractGenericOutput(response) {
+  return str(response.text) ?? str(response.output_text) ?? (typeof response.output === "string" ? response.output : null) ?? str(response.result) ?? null;
+}
+function extractOutput(response) {
+  return extractChoicesOutput(response) ?? extractAnthropicOutput(response) ?? extractGeminiOutput(response) ?? extractGenericOutput(response);
+}
+function extractInput(request) {
+  if (Array.isArray(request.messages) && request.messages.length > 0) {
+    return { messages: request.messages };
+  }
+  if (Array.isArray(request.contents) && request.contents.length > 0) {
+    return { contents: request.contents };
+  }
+  if (typeof request.prompt === "string") return request.prompt;
+  if (typeof request.input === "string") return request.input;
+  if (typeof request.input === "object" && request.input !== null) {
+    return request.input;
+  }
+  return null;
+}
+function derivePrompt(request) {
+  if (typeof request.prompt === "string") return request.prompt;
+  if (Array.isArray(request.messages)) {
+    const msgs = request.messages;
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      const msg = msgs[i];
+      if (msg.role === "user" || msg.role === "human") {
+        const content = msg.content;
+        if (typeof content === "string") return content;
+        if (Array.isArray(content)) {
+          const text = content.filter((p) => typeof p === "object" && p !== null).map((p) => str(p.text)).filter((t) => t !== null).join("\n");
+          if (text) return text;
+        }
+      }
+    }
+  }
+  if (Array.isArray(request.contents)) {
+    const contents = request.contents;
+    for (let i = contents.length - 1; i >= 0; i--) {
+      const c = contents[i];
+      if (c.role === "user") {
+        const parts = c.parts;
+        if (Array.isArray(parts)) {
+          const text = parts.map((p) => str(p.text)).filter((t) => t !== null).join("\n");
+          if (text) return text;
+        }
+      }
+    }
+  }
+  return null;
+}
+function extractParams(request) {
+  const cfg = typeof request.generationConfig === "object" && request.generationConfig !== null ? request.generationConfig : request;
+  return {
+    temperature: num(cfg.temperature, 1),
+    maxTokens: num(cfg.max_tokens ?? cfg.maxTokens ?? cfg.maxOutputTokens ?? cfg.max_output_tokens, 1024),
+    topP: numOrNull(cfg.top_p ?? cfg.topP),
+    seed: numOrNull(cfg.seed)
+  };
+}
+function extractModel(providerHint, request, response, override) {
+  const raw = override ?? str(request.model) ?? str(request.modelId) ?? // Bedrock
+  str(response.model) ?? str(response.modelId) ?? null;
+  if (!raw) return null;
+  const parts = raw.split("/");
+  const modelName = parts[parts.length - 1];
+  const modelVersion = str(response.model_version ?? response.modelVersion) ?? null;
+  return { model: modelName, modelVersion };
+}
+function tryUnwrapBedrock(request) {
+  const modelId = str(request.modelId);
+  if (!modelId) return null;
+  let body = {};
+  if (typeof request.body === "string") {
+    try {
+      body = JSON.parse(request.body);
+    } catch {
+      body = {};
+    }
+  } else if (typeof request.body === "object" && request.body !== null) {
+    body = request.body;
+  }
+  return { req: { ...body, modelId }, modelId };
+}
+function extractFromProviderCall(provider, modelOverride, rawRequest, rawResponse) {
+  let request = rawRequest;
+  if (provider === "bedrock" || str(rawRequest.modelId)) {
+    const unwrapped = tryUnwrapBedrock(rawRequest);
+    if (unwrapped) request = unwrapped.req;
+  }
+  const modelResult = extractModel(provider, request, rawResponse, modelOverride);
+  if (!modelResult) {
+    return {
+      ok: false,
+      reason: "Could not determine model name. Provide it via the `model` field, or ensure request.model / request.modelId is present."
+    };
+  }
+  const input = extractInput(request);
+  if (input === null) {
+    return {
+      ok: false,
+      reason: "Could not extract input. Expected request.messages (OpenAI/Anthropic/Mistral), request.contents (Gemini), or request.prompt/request.input (generic)."
+    };
+  }
+  const prompt = derivePrompt(request) ?? (typeof input === "string" ? input : "[structured input]");
+  const output = extractOutput(rawResponse);
+  if (output === null) {
+    return {
+      ok: false,
+      reason: "Could not extract output text. Expected response.choices[0].message.content (OpenAI/Mistral), response.content[0].text (Anthropic), response.candidates[0].content.parts[0].text (Gemini), or response.text / response.output_text (generic)."
+    };
+  }
+  const parameters = extractParams(request);
+  return {
+    ok: true,
+    data: {
+      model: modelResult.model,
+      modelVersion: modelResult.modelVersion,
+      prompt,
+      input,
+      output,
+      parameters
+    }
+  };
+}
+
+// src/certifyFromProvider.ts
+function certifyDecisionFromProviderCall(params) {
+  const extracted = extractFromProviderCall(
+    params.provider,
+    params.model,
+    params.request,
+    params.response
+  );
+  if (!extracted.ok) {
+    return { ok: false, code: CerVerifyCode.SCHEMA_ERROR, reason: extracted.reason };
+  }
+  const { model, modelVersion, prompt, input, output, parameters } = extracted.data;
+  try {
+    const snapshot = createSnapshot({
+      executionId: params.executionId ?? crypto5.randomUUID(),
+      timestamp: params.timestamp,
+      provider: params.provider,
+      model,
+      modelVersion,
+      prompt,
+      input,
+      parameters,
+      output,
+      appId: params.appId ?? null,
+      workflowId: params.workflowId ?? null,
+      conversationId: params.conversationId ?? null
+    });
+    const bundle = sealCer(snapshot, { meta: params.meta, createdAt: params.createdAt });
+    return { ok: true, bundle };
+  } catch (err2) {
+    return {
+      ok: false,
+      code: CerVerifyCode.SCHEMA_ERROR,
+      reason: err2 instanceof Error ? err2.message : String(err2)
+    };
+  }
+}
+
+// src/client.ts
+async function resolveApiKey(key) {
+  if (typeof key === "function") return key();
+  return key ?? "";
+}
+function mergeDefaultMeta(defaults, meta) {
+  const base = {};
+  if (defaults.tags && defaults.tags.length > 0) base.tags = defaults.tags;
+  if (defaults.source) base.source = defaults.source;
+  if (!meta && Object.keys(base).length === 0) return void 0;
+  return { ...base, ...meta };
+}
+function createClient(defaults = {}) {
+  return {
+    certifyDecision(params) {
+      return certifyDecision({
+        appId: defaults.appId ?? null,
+        workflowId: defaults.workflowId ?? null,
+        ...params,
+        meta: mergeDefaultMeta(defaults, params.meta)
+      });
+    },
+    async certifyAndAttestDecision(params, options) {
+      const nodeUrl = options?.nodeUrl ?? defaults.nodeUrl;
+      if (!nodeUrl) {
+        throw new Error("certifyAndAttestDecision requires nodeUrl (set in defaults or options)");
+      }
+      const apiKey = options?.apiKey ?? await resolveApiKey(defaults.apiKey);
+      const mergedParams = {
+        appId: defaults.appId ?? null,
+        workflowId: defaults.workflowId ?? null,
+        ...params,
+        meta: mergeDefaultMeta(defaults, params.meta)
+      };
+      return certifyAndAttestDecision(mergedParams, {
+        nodeUrl,
+        apiKey,
+        timeoutMs: options?.timeoutMs
+      });
+    },
+    verify(bundle) {
+      return verifyCer(bundle);
+    },
+    async verifyBundleAttestation(bundle, options) {
+      const nodeUrl = options?.nodeUrl ?? defaults.nodeUrl;
+      if (!nodeUrl) {
+        throw new Error("verifyBundleAttestation requires nodeUrl (set in defaults or options)");
+      }
+      return verifyBundleAttestation(bundle, { nodeUrl, kid: options?.kid });
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CerAttestationError,
@@ -1856,8 +2160,10 @@ async function verifyBundleAttestation(bundle, options) {
   attestIfNeeded,
   certifyAndAttestDecision,
   certifyDecision,
+  certifyDecisionFromProviderCall,
   computeInputHash,
   computeOutputHash,
+  createClient,
   createSnapshot,
   exportCer,
   fetchNodeKeys,
@@ -1867,6 +2173,8 @@ async function verifyBundleAttestation(bundle, options) {
   hashUtf8,
   importCer,
   sanitizeForAttestation,
+  sanitizeForStamp,
+  sanitizeForStorage,
   sealCer,
   selectNodeKey,
   sha256Hex,