@nexart/ai-execution 0.11.0 → 0.12.0

package/README.md

@@ -1,4 +1,4 @@
-# @nexart/ai-execution v0.11.0
+# @nexart/ai-execution v0.12.0
 
 Tamper-evident records and Certified Execution Records (CER) for AI operations.
 
@@ -7,7 +7,7 @@ Tamper-evident records and Certified Execution Records (CER) for AI operations.
 | Component | Version |
 |---|---|
 | Service | — |
-| SDK | 0.11.0 |
+| SDK | 0.12.0 |
 | Protocol | 1.2.0 |
 
 ## Why Not Just Store Logs?
@@ -213,6 +213,78 @@ const bundle = sealCer(snapshot, {
 // verifyCer(bundle).ok === true — declaration does not affect the result
 ```
 
+## CER Packages (v0.12.0+)
+
+A **CER package** is a transport/export envelope that wraps a sealed `cer.ai.execution.v1` bundle with optional receipt, signature, and attestation metadata.
+
+```
+{
+  "cer": { ...sealed cer.ai.execution.v1 bundle... },
+  "receipt":  { ...optional attestation receipt... },
+  "signature": "base64url...",
+  "attestation": { ...optional attestation summary... },
+  "verificationEnvelope": { ...optional envelope metadata... },
+  "verificationEnvelopeSignature": "base64url..."
+}
+```
+
+**When to use package helpers vs raw bundle helpers**
+
+| Use case | Recommended API |
+|---|---|
+| Creating, verifying, or archiving a CER locally | `certifyDecision`, `verifyCer`, `exportCer` / `importCer` (raw bundle) |
+| Wrapping a CER for transport or external storage with optional metadata | `createCerPackage`, `exportCerPackage`, `importCerPackage` |
+| Detecting whether an object is a package or a raw bundle | `isCerPackage` |
+| Extracting the CER from a received package | `getCerFromPackage` |
+| Verifying integrity of a received package's inner CER | `verifyCerPackage` |
+
+The `cer` field inside a package is authoritative. Package helpers never mutate it, never re-hash it, and never inject package-level fields into the CER.
+
+### Creating and exporting a package
+
+```typescript
+import { certifyDecision, createCerPackage, exportCerPackage } from '@nexart/ai-execution';
+
+const cer = certifyDecision({
+  provider: 'openai',
+  model: 'gpt-4o',
+  prompt: 'Summarize.',
+  input: userQuery,
+  output: llmResponse,
+  parameters: { temperature: 0.7, maxTokens: 1024, topP: null, seed: null },
+});
+
+const pkg = createCerPackage({
+  cer,
+  receipt: myAttestationReceipt, // optional
+  signature: 'base64url...',     // optional
+});
+
+const json = exportCerPackage(pkg); // stable canonical JSON
+```
+
+### Importing and verifying a package
+
+```typescript
+import { importCerPackage, verifyCerPackage, getCerFromPackage } from '@nexart/ai-execution';
+
+// importCerPackage parses + validates shape + verifies inner CER hash
+const pkg = importCerPackage(receivedJsonString); // throws CerVerificationError on failure
+
+// Alternatively: parse yourself then verify
+const result = verifyCerPackage(parsedObj);
+if (!result.ok) throw new Error(result.errors.join('; '));
+
+const cer = getCerFromPackage(parsedObj); // throws if not a valid package
+```
+
+**Design constraints of package helpers:**
+- Additive only — no changes to CER hashing, canonicalization, or `verifyCer()` semantics
+- `verifyCerPackage` only verifies the inner `cer` bundle; receipt/signature/envelope fields are opaque transport metadata not verified here
+- All existing raw bundle flows (`importCer`, `exportCer`, `verifyCer`) are unchanged
+
+---
+
 ## Attestation
 
 Endpoint: `POST {nodeUrl}/api/attest`
@@ -635,6 +707,19 @@ Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implement
 | `exportCer(bundle)` | Serialize to canonical JSON string |
 | `importCer(json)` | Parse + verify from JSON string |
 
+### CER Package Helpers (v0.12.0+)
+
+| Function | Description |
+|---|---|
+| `isCerPackage(value)` | Type guard: returns `true` if `value` is a CER package shape (`{ cer: { bundleType: 'cer.ai.execution.v1', ... }, ... }`). Structural check only — does not verify the inner CER hash. |
+| `createCerPackage(params)` | Assemble a CER package from a sealed CER and optional transport fields (`receipt`, `signature`, `attestation`, `verificationEnvelope`, `verificationEnvelopeSignature`). Assembly only — does not re-hash or re-sign. |
+| `getCerFromPackage(pkg)` | Extract and return the inner CER bundle. Throws `CerVerificationError` if `pkg` is not a valid package shape. |
+| `exportCerPackage(pkg)` | Serialize a CER package to a stable canonical JSON string. |
+| `importCerPackage(json)` | Parse a CER package JSON string, validate its shape, and verify the inner CER with `verifyCer()`. Throws `CerVerificationError` on any failure. |
+| `verifyCerPackage(pkg)` | Verify the inner CER of a package using `verifyCer()`. Returns a `VerificationResult`. Conservative: only verifies the inner `cer` — does not verify receipt/signature/envelope. |
+
+**Exported types:** `AiCerPackage`, `CreateCerPackageParams`
+
 ### Provider Drop-in (v0.6.0+)
 
 | Function | Description |
@@ -686,7 +771,7 @@ Priority when multiple failures exist: `CANONICALIZATION_ERROR` > `SCHEMA_ERROR`
 
 ## LangChain Integration
 
-`@nexart/ai-execution` includes a minimal LangChain helper surface (introduced v0.10.0, current v0.11.0). Certify the final input and output of any LangChain chain, agent, or runnable as a tamper-evident CER — no LangChain package dependency required.
+`@nexart/ai-execution` includes a minimal LangChain helper surface (introduced v0.10.0, current v0.12.0). Certify the final input and output of any LangChain chain, agent, or runnable as a tamper-evident CER — no LangChain package dependency required.
 
 `certifyLangChainRun` operates in two modes depending on whether `nodeUrl` and `apiKey` are supplied:
 
@@ -957,7 +1042,8 @@ import type { CerContextSignal, CerContext } from '@nexart/ai-execution';
 | v0.8.0 | Helper APIs: `exportVerifiableRedacted()` (post-seal re-seal with redacted snapshot + provenance metadata); `certifyAndAttestRun()` (one-call multi-step certify + optional per-step attestation with injectable mock); test determinism fix; all v0.1–v0.7 bundles verify identically |
 | v0.9.0 | CER Protocol types: `CerVerificationResult`, `ReasonCode`, `CheckStatus`; `verifyAiCerBundleDetailed()`; `CertifyDecisionParams.createdAt` wired through; determinism bug fix |
 | v0.10.0 | LangChain integration: `createLangChainCer()` (sync/local); `certifyLangChainRun()` dual-mode — local (sync) or node-attested (`Promise<LangChainAttestedResult>` when `nodeUrl`+`apiKey` supplied); `LangChainAttestedResult`, `AttestDecisionFn`; injectable `_attestFn` for test mocking. **Context signals:** optional `signals?: CerContextSignal[]` on `certifyDecision`, `certifyLangChainRun`, and `createLangChainCer` — sealed into `bundle.context` and included in `certificateHash` when non-empty; absent or empty = hash unchanged from pre-v0.10.0. New types: `CerContextSignal`, `CerContext`. New example: `examples/signals-cer.ts`. 413 total tests; all prior bundles verify identically |
-| **v0.11.0** | Version release. Ships all v0.10.0 features (LangChain integration + context signals) as the published package version. `cerSignals.test.js` added to the `npm test` script. No API, hash, or canonicalization changes |
+| v0.11.0 | Version release. Ships all v0.10.0 features (LangChain integration + context signals) as the published package version. `cerSignals.test.js` added to the `npm test` script. No API, hash, or canonicalization changes |
+| **v0.12.0** | CER package helpers: `isCerPackage`, `createCerPackage`, `getCerFromPackage`, `exportCerPackage`, `importCerPackage`, `verifyCerPackage`. New types: `AiCerPackage`, `CreateCerPackageParams`. Additive only — no changes to CER hashing, canonicalization, or verification semantics. 466 total tests; all prior bundles verify identically |
 | v1.0.0 | Planned: API stabilization, freeze public API surface |
 
 ## Releasing

package/dist/index.cjs

@@ -44,18 +44,23 @@ __export(src_exports, {
   certifyLangChainRun: () => certifyLangChainRun,
   computeInputHash: () => computeInputHash,
   computeOutputHash: () => computeOutputHash,
+  createCerPackage: () => createCerPackage,
   createClient: () => createClient,
   createLangChainCer: () => createLangChainCer,
   createSnapshot: () => createSnapshot,
   exportCer: () => exportCer,
+  exportCerPackage: () => exportCerPackage,
   exportVerifiableRedacted: () => exportVerifiableRedacted,
   fetchNodeKeys: () => fetchNodeKeys,
   getAttestationReceipt: () => getAttestationReceipt,
+  getCerFromPackage: () => getCerFromPackage,
   hasAttestation: () => hasAttestation,
   hashCanonicalJson: () => hashCanonicalJson,
   hashToolOutput: () => hashToolOutput,
   hashUtf8: () => hashUtf8,
   importCer: () => importCer,
+  importCerPackage: () => importCerPackage,
+  isCerPackage: () => isCerPackage,
   makeToolEvent: () => makeToolEvent,
   mapToAiefReason: () => mapToAiefReason,
   redactBeforeSeal: () => redactBeforeSeal,
@@ -72,6 +77,7 @@ __export(src_exports, {
   verifyAief: () => verifyAief,
   verifyBundleAttestation: () => verifyBundleAttestation,
   verifyCer: () => verifyCer,
+  verifyCerPackage: () => verifyCerPackage,
   verifyNodeReceiptSignature: () => verifyNodeReceiptSignature,
   verifyRunSummary: () => verifyRunSummary,
   verifySnapshot: () => verifySnapshot,
@@ -2737,6 +2743,67 @@ function certifyLangChainRun(input, _options) {
   }
   return createLangChainCer(input);
 }
+
+// src/package.ts
+function isCerPackage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const pkg = value;
+  if (typeof pkg["cer"] !== "object" || pkg["cer"] === null) return false;
+  const cer = pkg["cer"];
+  return cer["bundleType"] === "cer.ai.execution.v1";
+}
+function createCerPackage(params) {
+  const pkg = { cer: params.cer };
+  if (params.receipt !== void 0) pkg.receipt = params.receipt;
+  if (params.signature !== void 0) pkg.signature = params.signature;
+  if (params.attestation !== void 0) pkg.attestation = params.attestation;
+  if (params.verificationEnvelope !== void 0) pkg.verificationEnvelope = params.verificationEnvelope;
+  if (params.verificationEnvelopeSignature !== void 0) pkg.verificationEnvelopeSignature = params.verificationEnvelopeSignature;
+  return pkg;
+}
+function getCerFromPackage(pkg) {
+  if (!isCerPackage(pkg)) {
+    throw new CerVerificationError([
+      "getCerFromPackage: value is not a valid CER package (missing or invalid cer field)"
+    ]);
+  }
+  return pkg.cer;
+}
+function exportCerPackage(pkg) {
+  return toCanonicalJson(pkg);
+}
+function importCerPackage(json) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch (err2) {
+    throw new CerVerificationError([
+      `importCerPackage: invalid JSON: ${err2.message}`
+    ]);
+  }
+  if (!isCerPackage(parsed)) {
+    throw new CerVerificationError([
+      "importCerPackage: parsed value is not a CER package (missing or invalid cer field)"
+    ]);
+  }
+  const result = verifyCer(parsed.cer);
+  if (!result.ok) {
+    throw new CerVerificationError([
+      `importCerPackage: inner CER failed verification: ${result.errors.join("; ")}`
+    ]);
+  }
+  return parsed;
+}
+function verifyCerPackage(pkg) {
+  if (!isCerPackage(pkg)) {
+    return {
+      ok: false,
+      errors: ["verifyCerPackage: value is not a CER package (missing or invalid cer field)"],
+      code: CerVerifyCode.SCHEMA_ERROR
+    };
+  }
+  return verifyCer(pkg.cer);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CerAttestationError,
@@ -2753,18 +2820,23 @@ function certifyLangChainRun(input, _options) {
   certifyLangChainRun,
   computeInputHash,
   computeOutputHash,
+  createCerPackage,
   createClient,
   createLangChainCer,
   createSnapshot,
   exportCer,
+  exportCerPackage,
   exportVerifiableRedacted,
   fetchNodeKeys,
   getAttestationReceipt,
+  getCerFromPackage,
   hasAttestation,
   hashCanonicalJson,
   hashToolOutput,
   hashUtf8,
   importCer,
+  importCerPackage,
+  isCerPackage,
   makeToolEvent,
   mapToAiefReason,
   redactBeforeSeal,
@@ -2781,6 +2853,7 @@ function certifyLangChainRun(input, _options) {
   verifyAief,
   verifyBundleAttestation,
   verifyCer,
+  verifyCerPackage,
   verifyNodeReceiptSignature,
   verifyRunSummary,
   verifySnapshot,