@nexart/ai-execution 0.1.0 → 0.3.0

package/README.md

@@ -1,7 +1,11 @@
-# @nexart/ai-execution v0.1.0
+# @nexart/ai-execution v0.3.0
 
 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.
+
 ## What This Does
 
 This package creates integrity records for AI executions. Every time you call an AI model, it captures:
@@ -11,10 +15,17 @@ 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 later to prove the execution happened as recorded.
+These records can be verified offline to prove the execution happened as recorded.
 
 **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.
 
+## Compatibility Guarantees
+
+- **v0.1.0 and v0.2.0 bundles verify forever.** Any CER bundle produced by any prior version will pass `verify()` in v0.3.0 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.
+
 ## Installation
 
 ```bash
@@ -23,87 +34,92 @@ npm install @nexart/ai-execution
 
 ## Quick Start
 
-### Create a Snapshot Manually
+### Single Decision (3 lines)
+
+```typescript
+import { certifyDecision } 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 },
+});
+console.log(cer.certificateHash); // "sha256:..."
+```
+
+### Manual Snapshot + Seal
 
 ```typescript
-import { createSnapshot, verifySnapshot, sealCer, verifyCer } from '@nexart/ai-execution';
+import { createSnapshot, sealCer, verify } from '@nexart/ai-execution';
 
-// Create a snapshot of an AI execution
 const snapshot = createSnapshot({
   executionId: 'exec-001',
   provider: 'openai',
   model: 'gpt-4o',
-  modelVersion: '2026-01-01',
   prompt: 'You are a helpful assistant.',
   input: 'What is 2+2?',
-  parameters: {
-    temperature: 0.7,
-    maxTokens: 1024,
-    topP: null,
-    seed: null,
-  },
+  parameters: { temperature: 0.7, maxTokens: 1024, topP: null, seed: null },
   output: 'The answer is 4.',
 });
 
-// Verify the snapshot hashes are correct
-const result = verifySnapshot(snapshot);
-console.log(result.ok); // true
-
-// Seal into a Certified Execution Record
 const bundle = sealCer(snapshot);
-console.log(bundle.certificateHash); // "sha256:..."
-
-// Verify the entire bundle
-const cerResult = verifyCer(bundle);
-console.log(cerResult.ok); // true
+const result = verify(bundle);
+console.log(result.ok); // true
 ```
 
-### With JSON Input/Output
+### Agentic Multi-Step Workflow
 
 ```typescript
-const snapshot = createSnapshot({
-  executionId: 'exec-002',
-  provider: 'openai',
-  model: 'gpt-4o',
-  prompt: 'Extract entities',
-  input: { text: 'John lives in Paris', lang: 'en' },
-  parameters: {
-    temperature: 0,
-    maxTokens: 512,
-    topP: null,
-    seed: 42,
-  },
-  output: { entities: ['John', 'Paris'], count: 2 },
+import { RunBuilder } from '@nexart/ai-execution';
+
+const run = new RunBuilder({ runId: 'analysis-run', workflowId: 'data-pipeline' });
+
+run.step({
+  provider: 'openai', model: 'gpt-4o',
+  prompt: 'Plan the analysis.',
+  input: 'Analyze Q1 sales data.',
+  output: 'I will: 1) load data, 2) compute totals, 3) summarize.',
+  parameters: { temperature: 0.3, maxTokens: 512, topP: null, seed: null },
 });
-```
 
-### OpenAI Provider (Optional)
+run.step({
+  provider: 'openai', model: 'gpt-4o',
+  prompt: 'Execute step 1.',
+  input: 'Load and total Q1 data.',
+  output: 'Total revenue: $1.2M.',
+  parameters: { temperature: 0.3, maxTokens: 512, topP: null, seed: null },
+});
 
-Convenience adapter only; the core value of this package is the snapshot + hashing format.
-The OpenAI adapter wraps a single `chat/completions` call and returns a sealed CER bundle.
-**Provider determinism is not guaranteed** — identical inputs may produce different outputs across calls.
+const summary = run.finalize();
+// { runId, stepCount: 2, steps: [...], finalStepHash: "sha256:..." }
+```
 
-If you have an OpenAI API key, the package includes a convenience adapter:
+### Attest to Canonical Node
 
 ```typescript
-import { runOpenAIChatExecution } from '@nexart/ai-execution/providers/openai';
+import { certifyDecision, attest } from '@nexart/ai-execution';
 
-const result = await runOpenAIChatExecution({
-  prompt: 'You are a helpful assistant.',
-  input: 'What is the capital of France?',
-  model: 'gpt-4o',
-  parameters: {
-    temperature: 0.7,
-    maxTokens: 256,
-  },
+const cer = certifyDecision({ /* ... */ });
+const proof = await attest(cer, {
+  nodeUrl: 'https://node.nexart.io',
+  apiKey: process.env.NEXART_API_KEY!,
 });
-
-console.log(result.output);           // "The capital of France is Paris."
-console.log(result.snapshot.inputHash);  // "sha256:..."
-console.log(result.bundle.certificateHash); // "sha256:..."
+console.log(proof.attestationId);
 ```
 
-Requires `OPENAI_API_KEY` environment variable or `apiKey` parameter.
+Attestation verifies internal integrity only. It does not re-run the model. The node confirms the bundle's hashes are consistent and records it in the proof ledger.
+
+### Archive (Export / Import)
+
+```typescript
+import { exportCer, importCer } from '@nexart/ai-execution';
+
+const json = exportCer(bundle);       // canonical JSON string
+const restored = importCer(json);     // parse + verify (throws on tamper)
+```
 
 ## Snapshot Format (ai.execution.v1)
 
@@ -123,46 +139,16 @@ Requires `OPENAI_API_KEY` environment variable or `apiKey` parameter.
 | `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 package version (`"0.1.0"`) |
+| `sdkVersion` | Optional | `string \| null` | Defaults to `"0.3.0"` |
 | `appId` | Optional | `string \| null` | Defaults to `null` |
+| `runId` | Optional | `string \| null` | Workflow run ID |
+| `stepId` | Optional | `string \| null` | Step identifier within a run |
+| `stepIndex` | Optional | `number \| null` | 0-based step position |
+| `workflowId` | Optional | `string \| null` | Workflow template ID |
+| `conversationId` | Optional | `string \| null` | Conversation/session ID |
+| `prevStepHash` | Optional | `string \| null` | certificateHash of previous step |
 
-The following fields are **auto-generated** by `createSnapshot` and must not be set manually:
-
-| Field | Value |
-|---|---|
-| `type` | `"ai.execution.v1"` |
-| `protocolVersion` | `"1.2.0"` |
-| `executionSurface` | `"ai"` |
-| `inputHash` | SHA-256 of input |
-| `outputHash` | SHA-256 of output |
-
-### Example Snapshot
-
-```json
-{
-  "type": "ai.execution.v1",
-  "protocolVersion": "1.2.0",
-  "executionSurface": "ai",
-  "executionId": "exec-001",
-  "timestamp": "2026-02-12T00:00:00.000Z",
-  "provider": "openai",
-  "model": "gpt-4o",
-  "modelVersion": "2026-01-01",
-  "prompt": "You are a helpful assistant.",
-  "input": "What is 2+2?",
-  "inputHash": "sha256:...",
-  "parameters": {
-    "temperature": 0.7,
-    "maxTokens": 1024,
-    "topP": null,
-    "seed": null
-  },
-  "output": "The answer is 4.",
-  "outputHash": "sha256:...",
-  "sdkVersion": "0.1.0",
-  "appId": null
-}
-```
+Auto-generated fields (set by `createSnapshot`, do not set manually): `type`, `protocolVersion`, `executionSurface`, `inputHash`, `outputHash`.
 
 ## CER Bundle Format
 
@@ -173,181 +159,109 @@ The following fields are **auto-generated** by `createSnapshot` and must not be
   "createdAt": "2026-02-12T00:00:00.000Z",
   "version": "0.1",
   "snapshot": { ... },
-  "meta": {
-    "source": "my-app",
-    "tags": ["production"]
-  }
+  "meta": { "source": "my-app", "tags": ["production"] }
 }
 ```
 
 ### Certificate Hash Computation
 
-The `certificateHash` is SHA-256 of the UTF-8 bytes of the canonical JSON of **exactly these four fields**:
+The `certificateHash` is SHA-256 of the UTF-8 bytes of the canonical JSON of exactly: `{ bundleType, version, createdAt, snapshot }`. `meta` is excluded. Key-ordering is recursive. This computation is identical across all SDK versions.
 
-```
-{ bundleType, version, createdAt, snapshot }
-```
+## Attestation
 
-- `meta` is **excluded** from the certificate hash. It is an informational envelope field that does not affect integrity verification.
-- Key-ordering rules apply **recursively** — every nested object within `snapshot` is also sorted lexicographically by key.
-- The bytes being hashed are the UTF-8 encoding of the canonical JSON string (no BOM, no trailing newline).
+Endpoint: `POST {nodeUrl}/api/attest`
 
-## Hashing Rules
+- Authorization: `Bearer {apiKey}`
+- Body: the full CER bundle as JSON
+- Returns: `AttestationResult` with `attestationId`, `nodeRuntimeHash`, `certificateHash`, `protocolVersion`
+- Default timeout: 10 seconds (configurable via `timeoutMs`)
+- Validates: response `certificateHash` matches submitted bundle; all hashes in `sha256:<64hex>` format
+- Throws: `CerAttestationError` on mismatch, network error, timeout, or HTTP error
 
-- **String values**: SHA-256 of UTF-8 bytes of the raw string
-- **Object/Array values**: SHA-256 of UTF-8 bytes of canonical JSON (sorted keys, no whitespace, stable array order)
-- All hashes use the format `sha256:<hex>` (lowercase hex, 64 characters)
+Attestation verifies internal integrity only. It does not re-run the model or validate the correctness of the AI output.
 
 ## Canonical JSON Constraints
 
-Canonical JSON is a deterministic subset of JSON. The following rules apply:
-
-1. **Object keys** are sorted lexicographically (Unicode codepoint order) at every nesting level.
-2. **No whitespace** — no spaces, tabs, or newlines between tokens.
-3. **Array order is preserved** — arrays are never re-sorted.
-4. **`null`** is valid and serialized as `null`.
-5. **Numbers** must be finite. `NaN`, `Infinity`, and `-Infinity` are **rejected** (throw).
-6. **`undefined`** values in object properties are **omitted** (the key is dropped).
-7. **`BigInt`**, **functions**, and **`Symbol`** are **not valid** JSON types and are **rejected** (throw).
-8. Strings are JSON-escaped (e.g. `"` → `\"`).
-
-These constraints ensure that the same logical value always produces the same byte sequence, which is essential for hash stability across implementations and languages.
-
-## Interoperability (Test Vectors)
-
-Cross-language implementations **must** match the test vectors exactly to be considered compatible. Vectors are committed as JSON fixtures at:
-
-```
-packages/ai-execution/fixtures/vectors/
-```
-
-### Vector 001
-
-**Input snapshot** (`vector-001.snapshot.json`):
-
-```json
-{
-  "type": "ai.execution.v1",
-  "protocolVersion": "1.2.0",
-  "executionSurface": "ai",
-  "executionId": "vec-001",
-  "timestamp": "2026-02-12T00:00:00.000Z",
-  "provider": "openai",
-  "model": "gpt-4o",
-  "modelVersion": "2026-01-01",
-  "prompt": "You are a helpful assistant.",
-  "input": "What is 2+2?",
-  "inputHash": "sha256:52cb6b5e4a038af1756708f98afb718a08c75b87b2f03dbee4dd9c8139c15c5e",
-  "parameters": {
-    "temperature": 0.7,
-    "maxTokens": 1024,
-    "topP": null,
-    "seed": null
-  },
-  "output": "The answer is 4.",
-  "outputHash": "sha256:ae758477f843049bd252ceb5498aa33f190326589ee92cbe5a1ab563f54bc05b",
-  "sdkVersion": "0.1.0",
-  "appId": "vector-test"
-}
-```
-
-**Expected hashes** (`vector-001.expected.json`):
-
-| Hash | Value |
-|---|---|
-| `inputHash` | `sha256:52cb6b5e4a038af1756708f98afb718a08c75b87b2f03dbee4dd9c8139c15c5e` |
-| `outputHash` | `sha256:ae758477f843049bd252ceb5498aa33f190326589ee92cbe5a1ab563f54bc05b` |
-| `certificateHash` | `sha256:86275d60d088483eefaf0bd31d79629b11342315816f3a1da26980e4a05352f4` |
-
-The `certificateHash` is computed with `cerCreatedAt: "2026-02-12T00:00:00.000Z"`.
-
-**Canonicalization rules for verification:**
-1. Object keys sorted lexicographically at every level.
+1. Object keys sorted lexicographically (Unicode codepoint order) at every nesting level.
 2. No whitespace between tokens.
-3. Arrays preserve insertion order.
-4. Hashes are SHA-256 of the UTF-8 bytes of the resulting string.
-
-To verify compatibility, a cross-language implementation should:
-1. Load `vector-001.snapshot.json`.
-2. Recompute `inputHash` from `snapshot.input` and assert it matches `expected.inputHash`.
-3. Recompute `outputHash` from `snapshot.output` and assert it matches `expected.outputHash`.
-4. Construct a CER payload `{ bundleType: "cer.ai.execution.v1", version: "0.1", createdAt: "2026-02-12T00:00:00.000Z", snapshot }`, canonicalize it, hash it, and assert it matches `expected.certificateHash`.
-
-## Threat Model
-
-This package provides **integrity and auditability** for AI execution records. It is an auditing tool, not a security boundary.
-
-### What it prevents
+3. Array order preserved.
+4. `null` serialized as `null`.
+5. Numbers must be finite. `NaN`, `Infinity`, `-Infinity` rejected (throw).
+6. `undefined` values in object properties omitted (key dropped).
+7. `BigInt`, functions, `Symbol` rejected (throw).
+8. Strings JSON-escaped.
 
-- **Output tampering** — any modification to the recorded output invalidates the `outputHash` and `certificateHash`.
-- **Parameter laundering** — changing temperature, model, seed, or other parameters after the fact is detectable because they are included in the certificate hash.
-- **Silent record edits** — any modification to a sealed CER bundle is detectable via `verifyCer()`.
+**Canonicalization is frozen for v1.** Number formatting uses `JSON.stringify()` (V8-consistent). This does not normalize `-0` to `0` and does not implement RFC 8785 exponential notation rules. These are documented known behaviors, not bugs. Any future stricter canonicalization will ship under a new bundle type.
 
-### What it does NOT prevent
+## Error Types
 
-- **Provider lying** — if the AI provider returns fabricated output, this package faithfully records it. The record proves what the provider returned, not that the provider was honest.
-- **Model drift** — models change over time. The same input may produce different output with the same model name on different dates. `modelVersion` helps track this but cannot prevent it.
-- **Correctness of the answer** — this package records what was said, not whether it was right.
+| Error | When thrown | Structured data |
+|---|---|---|
+| `CerVerificationError` | `importCer()` on invalid/tampered data | `.errors: string[]` |
+| `CerAttestationError` | `attest()` on failure | `.statusCode`, `.responseBody`, `.details: string[]` |
 
-## Verification Best Practice
+## Interoperability (Test Vectors)
 
-**Recommended flow:**
+Fixtures at `fixtures/vectors/` and `fixtures/golden/`. Cross-language implementations must match committed hash values exactly. Golden fixtures (v0.1.0 semantics) must verify with every future version.
 
-1. Call `createSnapshot(...)` immediately after receiving the AI response.
-2. Call `sealCer(snapshot)` to produce the CER bundle.
-3. Call `verifyCer(bundle)` **before** storing or transmitting the bundle — this catches any in-memory corruption.
-4. Store the full bundle as an audit artifact. Treat it as immutable.
-5. On retrieval, call `verifyCer(bundle)` again to confirm integrity.
+## API Reference
 
-```typescript
-const snapshot = createSnapshot({ ... });
-const bundle = sealCer(snapshot);
+### Core
 
-const check = verifyCer(bundle);
-if (!check.ok) {
-  throw new Error(`CER integrity failure: ${check.errors.join('; ')}`);
-}
+| Function | Description |
+|---|---|
+| `createSnapshot(params)` | Create snapshot with computed hashes |
+| `verifySnapshot(snapshot)` | Verify snapshot hashes and structure |
+| `sealCer(snapshot, options?)` | Seal snapshot into CER bundle |
+| `verify(bundle)` / `verifyCer(bundle)` | Verify CER bundle |
+| `certifyDecision(params)` | One-call: createSnapshot + sealCer |
 
-await store(bundle); // persist as audit artifact
-```
+### Workflow
 
-## Privacy & Data Handling
+| Export | Description |
+|---|---|
+| `RunBuilder` | Multi-step workflow builder with prevStepHash chaining |
 
-Snapshots include **raw prompt, input, and output by default**. This means:
+### Attestation & Archive
 
-- If the input contains PII, medical data, or other sensitive information, the snapshot will contain it verbatim.
-- If the output contains sensitive content, it will be stored in full.
+| Function | Description |
+|---|---|
+| `attest(bundle, options)` | Post CER to canonical node |
+| `exportCer(bundle)` | Serialize to canonical JSON string |
+| `importCer(json)` | Parse + verify from JSON string |
 
-**Recommendations:**
+### Providers (sub-exports)
 
-- For sensitive workloads, consider redacting input/output before calling `createSnapshot()`, then verify the redacted versions.
-- A hash-only mode (where only hashes are stored, not raw content) is **not implemented in v0.1.0**. It is planned for a future release.
-- Treat CER bundles with the same access controls as the underlying data they contain.
+| Function | Export path |
+|---|---|
+| `runOpenAIChatExecution` | `@nexart/ai-execution/providers/openai` |
+| `runAnthropicExecution` | `@nexart/ai-execution/providers/anthropic` |
+| `wrapProvider` | `@nexart/ai-execution/providers/wrap` |
 
-## API Reference
+## Version History
 
-| Function | Description |
-|----------|-------------|
-| `createSnapshot(params)` | Create an AI execution snapshot with computed hashes |
-| `verifySnapshot(snapshot)` | Verify snapshot hashes and structure |
-| `sealCer(snapshot, options?)` | Seal a snapshot into a CER bundle |
-| `verifyCer(bundle)` | Verify a CER bundle (snapshot + certificate hash) |
-| `computeInputHash(input)` | Compute hash for input (string or object) |
-| `computeOutputHash(output)` | Compute hash for output (string or object) |
-| `toCanonicalJson(value)` | Deterministic JSON serialization |
-| `sha256Hex(data)` | Raw SHA-256 hex digest |
-| `hashUtf8(value)` | Hash a UTF-8 string |
-| `hashCanonicalJson(value)` | Hash canonical JSON of a value |
+| Version | Description |
+|---|---|
+| 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 |
+| v1.0.0 | Planned: API stabilization, freeze public API surface |
 
-## How to Publish
+## Releasing
 
 ```bash
 cd packages/ai-execution
 npm run build
-npm run test
+npm test
 npm publish --access public
 ```
 
+The `release` script automates build, test, version bump, and publish:
+
+```bash
+npm run release
+```
+
 ## License
 
 MIT

package/dist/archive.d.ts

@@ -0,0 +1,4 @@
+import type { CerAiExecutionBundle } from './types.js';
+export declare function exportCer(bundle: CerAiExecutionBundle): string;
+export declare function importCer(json: string): CerAiExecutionBundle;
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAKvD,wBAAgB,SAAS,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAE9D;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAwB5D"}

package/dist/archive.js

@@ -0,0 +1,28 @@
+import { toCanonicalJson } from './canonicalJson.js';
+import { verifyCer } from './cer.js';
+import { CerVerificationError } from './errors.js';
+export function exportCer(bundle) {
+    return toCanonicalJson(bundle);
+}
+export 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;
+}
+//# sourceMappingURL=archive.js.map

package/dist/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,UAAU,SAAS,CAAC,MAA4B;IACpD,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,oBAAoB,CAAC,CAAC,iBAAkB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,MAAM,GAAG,MAA8B,CAAC;IAE9C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1C,MAAM,IAAI,oBAAoB,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC;IACpE,CAAC;IAED,IAAI,MAAM,CAAC,UAAU,KAAK,qBAAqB,EAAE,CAAC;QAChD,MAAM,IAAI,oBAAoB,CAAC,CAAC,mDAAmD,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;IAC5G,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,IAAI,oBAAoB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/attest.d.ts

@@ -0,0 +1,3 @@
+import type { CerAiExecutionBundle, AttestationResult, AttestOptions } from './types.js';
+export declare function attest(bundle: CerAiExecutionBundle, options: AttestOptions): Promise<AttestationResult>;
+//# sourceMappingURL=attest.d.ts.map

package/dist/attest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attest.d.ts","sourceRoot":"","sources":["../src/attest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAczF,wBAAsB,MAAM,CAC1B,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CA0F5B"}

package/dist/attest.js

@@ -0,0 +1,79 @@
+import { CerAttestationError } from './errors.js';
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const DEFAULT_TIMEOUT_MS = 10_000;
+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;
+}
+export async function attest(bundle, options) {
+    const url = `${options.nodeUrl.replace(/\/+$/, '')}/api/attest`;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    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(bundle),
+            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 result = body;
+        const msg = typeof result.error === 'string'
+            ? result.error
+            : `HTTP ${response.status}`;
+        const details = Array.isArray(result.details) ? result.details : undefined;
+        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 : undefined,
+        nodeRuntimeHash: typeof result.nodeRuntimeHash === 'string' ? result.nodeRuntimeHash : undefined,
+        certificateHash: typeof result.certificateHash === 'string' ? result.certificateHash : undefined,
+        protocolVersion: typeof result.protocolVersion === 'string' ? result.protocolVersion : undefined,
+        raw: body,
+    };
+}
+//# sourceMappingURL=attest.js.map

package/dist/attest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attest.js","sourceRoot":"","sources":["../src/attest.ts"],"names":[],"mappings":"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"}

package/dist/certify.d.ts

@@ -0,0 +1,3 @@
+import type { CerAiExecutionBundle, CertifyDecisionParams } from './types.js';
+export declare function certifyDecision(params: CertifyDecisionParams): CerAiExecutionBundle;
+//# sourceMappingURL=certify.d.ts.map

package/dist/certify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"certify.d.ts","sourceRoot":"","sources":["../src/certify.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAI9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,oBAAoB,CAwBnF"}