@nexart/ai-execution 0.3.0 → 0.4.1

package/dist/index.mjs

@@ -0,0 +1,638 @@
+// 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;
+  constructor(errors) {
+    super(`CER verification failed: ${errors.join("; ")}`);
+    this.name = "CerVerificationError";
+    this.errors = errors;
+  }
+};
+var CerAttestationError = class extends Error {
+  statusCode;
+  responseBody;
+  details;
+  constructor(message, statusCode, responseBody, details) {
+    super(message);
+    this.name = "CerAttestationError";
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+    this.details = details;
+  }
+};
+
+// src/canonicalJson.ts
+function toCanonicalJson(value) {
+  return canonicalize(value);
+}
+function canonicalize(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(`Non-finite number not allowed in canonical JSON: ${value}`);
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((item) => canonicalize(item));
+    return "[" + items.join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const entries = keys.map((key) => {
+      const val = obj[key];
+      if (val === void 0) {
+        return null;
+      }
+      return JSON.stringify(key) + ":" + canonicalize(val);
+    }).filter((e) => e !== null);
+    return "{" + entries.join(",") + "}";
+  }
+  throw new Error(`Unsupported type for canonical JSON: ${typeof value}`);
+}
+
+// src/hash.ts
+import * as crypto from "crypto";
+function sha256Hex(data) {
+  const hash = crypto.createHash("sha256");
+  if (typeof data === "string") {
+    hash.update(data, "utf-8");
+  } else {
+    hash.update(data);
+  }
+  return hash.digest("hex");
+}
+function hashUtf8(value) {
+  return `sha256:${sha256Hex(value)}`;
+}
+function hashCanonicalJson(value) {
+  const canonical = toCanonicalJson(value);
+  return `sha256:${sha256Hex(canonical)}`;
+}
+function computeInputHash(input) {
+  if (typeof input === "string") {
+    return hashUtf8(input);
+  }
+  return hashCanonicalJson(input);
+}
+function computeOutputHash(output) {
+  if (typeof output === "string") {
+    return hashUtf8(output);
+  }
+  return hashCanonicalJson(output);
+}
+
+// src/snapshot.ts
+var PACKAGE_VERSION = "0.4.1";
+function validateParameters(params) {
+  const errors = [];
+  if (typeof params.temperature !== "number" || !Number.isFinite(params.temperature)) {
+    errors.push(`parameters.temperature must be a finite number, got: ${params.temperature}`);
+  }
+  if (typeof params.maxTokens !== "number" || !Number.isFinite(params.maxTokens)) {
+    errors.push(`parameters.maxTokens must be a finite number, got: ${params.maxTokens}`);
+  }
+  if (params.topP !== null && (typeof params.topP !== "number" || !Number.isFinite(params.topP))) {
+    errors.push(`parameters.topP must be a finite number or null, got: ${params.topP}`);
+  }
+  if (params.seed !== null && (typeof params.seed !== "number" || !Number.isFinite(params.seed))) {
+    errors.push(`parameters.seed must be a finite number or null, got: ${params.seed}`);
+  }
+  return errors;
+}
+function createSnapshot(params) {
+  const paramErrors = validateParameters(params.parameters);
+  if (paramErrors.length > 0) {
+    throw new Error(`Invalid parameters: ${paramErrors.join("; ")}`);
+  }
+  const inputHash = computeInputHash(params.input);
+  const outputHash = computeOutputHash(params.output);
+  const snapshot = {
+    type: "ai.execution.v1",
+    protocolVersion: "1.2.0",
+    executionSurface: "ai",
+    executionId: params.executionId,
+    timestamp: params.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+    provider: params.provider,
+    model: params.model,
+    modelVersion: params.modelVersion ?? null,
+    prompt: params.prompt,
+    input: params.input,
+    inputHash,
+    parameters: {
+      temperature: params.parameters.temperature,
+      maxTokens: params.parameters.maxTokens,
+      topP: params.parameters.topP ?? null,
+      seed: params.parameters.seed ?? null
+    },
+    output: params.output,
+    outputHash,
+    sdkVersion: params.sdkVersion ?? PACKAGE_VERSION,
+    appId: params.appId ?? null
+  };
+  if (params.runId !== void 0) snapshot.runId = params.runId ?? null;
+  if (params.stepId !== void 0) snapshot.stepId = params.stepId ?? null;
+  if (params.stepIndex !== void 0) snapshot.stepIndex = params.stepIndex ?? null;
+  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;
+  return snapshot;
+}
+function verifySnapshot(snapshot) {
+  const schemaErrors = [];
+  const formatErrors = [];
+  const inputHashErrors = [];
+  const outputHashErrors = [];
+  if (snapshot.type !== "ai.execution.v1") {
+    schemaErrors.push(`Expected type "ai.execution.v1", got "${snapshot.type}"`);
+  }
+  if (snapshot.protocolVersion !== "1.2.0") {
+    schemaErrors.push(`Expected protocolVersion "1.2.0", got "${snapshot.protocolVersion}"`);
+  }
+  if (snapshot.executionSurface !== "ai") {
+    schemaErrors.push(`Expected executionSurface "ai", got "${snapshot.executionSurface}"`);
+  }
+  if (!snapshot.executionId || typeof snapshot.executionId !== "string") {
+    schemaErrors.push("executionId must be a non-empty string");
+  }
+  if (!snapshot.timestamp || typeof snapshot.timestamp !== "string") {
+    schemaErrors.push("timestamp must be a non-empty string");
+  }
+  if (!snapshot.provider || typeof snapshot.provider !== "string") {
+    schemaErrors.push("provider must be a non-empty string");
+  }
+  if (!snapshot.model || typeof snapshot.model !== "string") {
+    schemaErrors.push("model must be a non-empty string");
+  }
+  if (!snapshot.prompt || typeof snapshot.prompt !== "string") {
+    schemaErrors.push("prompt must be a non-empty string");
+  }
+  if (snapshot.input === void 0 || snapshot.input === null) {
+    schemaErrors.push("input must be a string or object");
+  }
+  if (snapshot.output === void 0 || snapshot.output === null) {
+    schemaErrors.push("output must be a string or object");
+  }
+  const paramErrors = validateParameters(snapshot.parameters);
+  schemaErrors.push(...paramErrors);
+  if (!snapshot.inputHash || !snapshot.inputHash.startsWith("sha256:")) {
+    formatErrors.push(`inputHash must start with "sha256:", got "${snapshot.inputHash}"`);
+  }
+  if (!snapshot.outputHash || !snapshot.outputHash.startsWith("sha256:")) {
+    formatErrors.push(`outputHash must start with "sha256:", got "${snapshot.outputHash}"`);
+  }
+  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 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: false, errors, code, details };
+}
+
+// src/cer.ts
+function computeCertificateHash(payload) {
+  const canonical = toCanonicalJson(payload);
+  return `sha256:${sha256Hex(canonical)}`;
+}
+function sealCer(snapshot, options) {
+  const createdAt = options?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const payload = {
+    bundleType: "cer.ai.execution.v1",
+    createdAt,
+    snapshot,
+    version: "0.1"
+  };
+  const certificateHash = computeCertificateHash(payload);
+  const bundle = {
+    bundleType: "cer.ai.execution.v1",
+    certificateHash,
+    createdAt,
+    version: "0.1",
+    snapshot
+  };
+  if (options?.meta) {
+    bundle.meta = options.meta;
+  }
+  return bundle;
+}
+function verifyCer(bundle) {
+  const schemaErrors = [];
+  const formatErrors = [];
+  if (bundle.bundleType !== "cer.ai.execution.v1") {
+    schemaErrors.push(`Expected bundleType "cer.ai.execution.v1", got "${bundle.bundleType}"`);
+  }
+  if (bundle.version !== "0.1") {
+    schemaErrors.push(`Expected version "0.1", got "${bundle.version}"`);
+  }
+  if (!bundle.createdAt || typeof bundle.createdAt !== "string") {
+    schemaErrors.push("createdAt must be a non-empty string");
+  }
+  if (!bundle.certificateHash || !bundle.certificateHash.startsWith("sha256:")) {
+    formatErrors.push(`certificateHash must start with "sha256:", got "${bundle.certificateHash}"`);
+  }
+  if (!bundle.snapshot) {
+    schemaErrors.push("snapshot is required");
+    const allErrors = [...schemaErrors, ...formatErrors];
+    return { ok: false, errors: allErrors, code: CerVerifyCode.SCHEMA_ERROR, details: schemaErrors };
+  }
+  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: false, errors, code, details };
+}
+
+// src/certify.ts
+import * as crypto2 from "crypto";
+function certifyDecision(params) {
+  const executionId = params.executionId ?? crypto2.randomUUID();
+  const snapshot = createSnapshot({
+    executionId,
+    timestamp: params.timestamp,
+    provider: params.provider,
+    model: params.model,
+    modelVersion: params.modelVersion,
+    prompt: params.prompt,
+    input: params.input,
+    parameters: params.parameters,
+    output: params.output,
+    sdkVersion: params.sdkVersion,
+    appId: params.appId,
+    runId: params.runId,
+    stepId: params.stepId,
+    stepIndex: params.stepIndex,
+    workflowId: params.workflowId,
+    conversationId: params.conversationId,
+    prevStepHash: params.prevStepHash
+  });
+  return sealCer(snapshot, { meta: params.meta });
+}
+
+// src/run.ts
+import * as crypto3 from "crypto";
+var RunBuilder = class {
+  runId;
+  workflowId;
+  conversationId;
+  appId;
+  stepIndex = 0;
+  prevStepHash = null;
+  steps = [];
+  constructor(options) {
+    this.runId = options?.runId ?? crypto3.randomUUID();
+    this.workflowId = options?.workflowId ?? null;
+    this.conversationId = options?.conversationId ?? null;
+    this.appId = options?.appId ?? null;
+  }
+  step(params) {
+    const stepId = params.stepId ?? crypto3.randomUUID();
+    const executionId = `${this.runId}-step-${this.stepIndex}`;
+    const snapshot = createSnapshot({
+      executionId,
+      timestamp: params.timestamp,
+      provider: params.provider,
+      model: params.model,
+      modelVersion: params.modelVersion,
+      prompt: params.prompt,
+      input: params.input,
+      parameters: params.parameters,
+      output: params.output,
+      appId: this.appId,
+      runId: this.runId,
+      stepId,
+      stepIndex: this.stepIndex,
+      workflowId: this.workflowId,
+      conversationId: this.conversationId,
+      prevStepHash: this.prevStepHash
+    });
+    const bundle = sealCer(snapshot, { meta: params.meta });
+    this.steps.push({
+      stepIndex: this.stepIndex,
+      stepId,
+      executionId,
+      certificateHash: bundle.certificateHash,
+      prevStepHash: this.prevStepHash
+    });
+    this.prevStepHash = bundle.certificateHash;
+    this.stepIndex++;
+    return bundle;
+  }
+  finalize() {
+    return {
+      runId: this.runId,
+      workflowId: this.workflowId,
+      conversationId: this.conversationId,
+      stepCount: this.steps.length,
+      steps: [...this.steps],
+      finalStepHash: this.prevStepHash
+    };
+  }
+};
+
+// src/sanitize.ts
+function deepRemoveUndefined(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value === "bigint") {
+    throw new Error("BigInt values are not JSON-safe and cannot be sanitized");
+  }
+  if (typeof value === "function") {
+    throw new Error("Function values are not JSON-safe and cannot be sanitized");
+  }
+  if (typeof value === "symbol") {
+    throw new Error("Symbol values are not JSON-safe and cannot be sanitized");
+  }
+  if (Array.isArray(value)) {
+    return value.map(deepRemoveUndefined);
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      if (val === void 0) continue;
+      result[key] = deepRemoveUndefined(val);
+    }
+    return result;
+  }
+  return value;
+}
+function sanitizeForAttestation(bundle) {
+  return deepRemoveUndefined(bundle);
+}
+function hasAttestation(bundle) {
+  if (typeof bundle !== "object" || bundle === null) return false;
+  const b = bundle;
+  if (typeof b.attestationId === "string" && b.attestationId.length > 0) return true;
+  if (typeof b.nodeRuntimeHash === "string" && b.nodeRuntimeHash.length > 0) return true;
+  if (typeof b.attestation === "object" && b.attestation !== null) {
+    const att = b.attestation;
+    if (typeof att.attestationId === "string" && att.attestationId.length > 0) return true;
+    if (typeof att.nodeRuntimeHash === "string" && att.nodeRuntimeHash.length > 0) return true;
+  }
+  return false;
+}
+
+// src/attest.ts
+var SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+var DEFAULT_TIMEOUT_MS = 1e4;
+function validateHashFormat(value, fieldName) {
+  if (typeof value !== "string") return null;
+  if (!SHA256_PATTERN.test(value)) {
+    return `${fieldName} is not in sha256:<64hex> format: "${value}"`;
+  }
+  return null;
+}
+async function attest(bundle, options) {
+  const url = `${options.nodeUrl.replace(/\/+$/, "")}/api/attest`;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const sanitized = sanitizeForAttestation(bundle);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${options.apiKey}`
+      },
+      body: JSON.stringify(sanitized),
+      signal: controller.signal
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    const error = err;
+    if (error.name === "AbortError") {
+      throw new CerAttestationError(
+        `Attestation request timed out after ${timeoutMs}ms`
+      );
+    }
+    throw new CerAttestationError(
+      `Network error contacting attestation node: ${error.message}`
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    const text = await response.text().catch(() => "");
+    throw new CerAttestationError(
+      `Attestation node returned non-JSON response (${response.status}): ${text}`,
+      response.status
+    );
+  }
+  if (!response.ok) {
+    const result2 = body;
+    const msg = typeof result2.error === "string" ? result2.error : `HTTP ${response.status}`;
+    const details = Array.isArray(result2.details) ? result2.details : void 0;
+    throw new CerAttestationError(
+      `Attestation failed: ${msg}`,
+      response.status,
+      body,
+      details
+    );
+  }
+  const result = body;
+  const errors = [];
+  if (typeof result.certificateHash === "string" && result.certificateHash !== bundle.certificateHash) {
+    errors.push(
+      `Node returned certificateHash "${result.certificateHash}" but bundle has "${bundle.certificateHash}"`
+    );
+  }
+  const certHashErr = validateHashFormat(result.certificateHash, "response.certificateHash");
+  if (certHashErr) errors.push(certHashErr);
+  const runtimeHashErr = validateHashFormat(result.nodeRuntimeHash, "response.nodeRuntimeHash");
+  if (runtimeHashErr) errors.push(runtimeHashErr);
+  if (errors.length > 0) {
+    throw new CerAttestationError(
+      `Attestation response validation failed: ${errors.join("; ")}`,
+      response.status,
+      body,
+      errors
+    );
+  }
+  return {
+    ok: true,
+    attestationId: typeof result.attestationId === "string" ? result.attestationId : void 0,
+    nodeRuntimeHash: typeof result.nodeRuntimeHash === "string" ? result.nodeRuntimeHash : void 0,
+    certificateHash: typeof result.certificateHash === "string" ? result.certificateHash : void 0,
+    protocolVersion: typeof result.protocolVersion === "string" ? result.protocolVersion : void 0,
+    raw: body
+  };
+}
+
+// src/archive.ts
+function exportCer(bundle) {
+  return toCanonicalJson(bundle);
+}
+function importCer(json) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch (err) {
+    throw new CerVerificationError([`Invalid JSON: ${err.message}`]);
+  }
+  const bundle = parsed;
+  if (!bundle || typeof bundle !== "object") {
+    throw new CerVerificationError(["Parsed value is not an object"]);
+  }
+  if (bundle.bundleType !== "cer.ai.execution.v1") {
+    throw new CerVerificationError([`Expected bundleType "cer.ai.execution.v1", got "${bundle.bundleType}"`]);
+  }
+  const result = verifyCer(bundle);
+  if (!result.ok) {
+    throw new CerVerificationError(result.errors);
+  }
+  return bundle;
+}
+
+// src/providers/wrap.ts
+import * as crypto4 from "crypto";
+function wrapProvider(config) {
+  return {
+    async execute(params) {
+      const raw = await config.callFn(params.providerInput);
+      const output = config.extractOutput(raw);
+      const modelVersion = config.extractModelVersion ? config.extractModelVersion(raw) : params.modelVersion ?? null;
+      const snapshot = createSnapshot({
+        executionId: params.executionId ?? crypto4.randomUUID(),
+        provider: config.provider,
+        model: params.model,
+        modelVersion,
+        prompt: params.prompt,
+        input: params.input,
+        parameters: params.parameters,
+        output,
+        appId: params.appId
+      });
+      const bundle = sealCer(snapshot, { meta: params.meta });
+      return { output, snapshot, bundle };
+    }
+  };
+}
+export {
+  CerAttestationError,
+  CerVerificationError,
+  CerVerifyCode,
+  RunBuilder,
+  attest,
+  certifyDecision,
+  computeInputHash,
+  computeOutputHash,
+  createSnapshot,
+  exportCer,
+  hasAttestation,
+  hashCanonicalJson,
+  hashUtf8,
+  importCer,
+  sanitizeForAttestation,
+  sealCer,
+  sha256Hex,
+  toCanonicalJson,
+  verifyCer as verify,
+  verifyCer,
+  verifySnapshot,
+  wrapProvider
+};
+//# sourceMappingURL=index.mjs.map