@nexart/ai-execution 0.4.2 → 0.6.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as CreateSnapshotParams, A as AiExecutionSnapshotV1, V as VerificationResult, a as CerMeta, b as CerAiExecutionBundle, c as CertifyDecisionParams, R as RunBuilderOptions, S as StepParams, d as RunSummary, e as AttestOptions, f as AttestationResult, g as AttestationReceipt } from './types-Cnm2G_rg.cjs';
-export { i as AiExecutionParameters, j as AttestationReceiptResult, h as CerVerifyCode, h as CerVerifyCodeType, P as ProviderConfig, W as WrappedExecutionParams, k as WrappedExecutionResult } from './types-Cnm2G_rg.cjs';
+import { C as CreateSnapshotParams, A as AiExecutionSnapshotV1, V as VerificationResult, a as CerMeta, b as CerAiExecutionBundle, c as CertifyDecisionParams, R as RunBuilderOptions, S as StepParams, d as RunSummary, e as AttestOptions, f as AttestationResult, g as SanitizeStorageOptions, h as AttestationReceipt, N as NodeKeysDocument, i as NodeReceiptVerifyResult, j as SignedAttestationReceipt, k as CerVerifyCode } from './types-Cgb52dTx.cjs';
+export { l as AiExecutionParameters, m as AttestationReceiptResult, n as ClientDefaults, o as NexArtClient, P as ProviderCallParams, p as ProviderCallResult, q as ProviderConfig, W as WrappedExecutionParams, r as WrappedExecutionResult } from './types-Cgb52dTx.cjs';
 export { wrapProvider } from './providers/wrap.cjs';
 
 declare class CerVerificationError extends Error {
@@ -50,7 +50,27 @@ declare function attest(bundle: CerAiExecutionBundle, options: AttestOptions): P
 declare function exportCer(bundle: CerAiExecutionBundle): string;
 declare function importCer(json: string): CerAiExecutionBundle;
 
+/** @deprecated Use sanitizeForStorage or sanitizeForStamp instead. */
 declare function sanitizeForAttestation(bundle: CerAiExecutionBundle): CerAiExecutionBundle;
+/**
+ * Prepare a bundle for safe storage:
+ * - Removes undefined keys.
+ * - Removes non-JSON-serializable types (bigint, function, symbol).
+ * - Optionally redacts sensitive field paths.
+ *
+ * Does NOT recompute certificateHash or any content hashes.
+ */
+declare function sanitizeForStorage(bundle: CerAiExecutionBundle, options?: SanitizeStorageOptions): CerAiExecutionBundle;
+/**
+ * Produce the minimal "attestable core" envelope for a bundle.
+ *
+ * Returns only: bundleType, certificateHash, createdAt, version, snapshot.
+ * The meta field is excluded — it is informational and not included in the
+ * certificateHash computation.
+ *
+ * Does NOT recompute any hashes.
+ */
+declare function sanitizeForStamp(bundle: CerAiExecutionBundle): Omit<CerAiExecutionBundle, 'meta'>;
 declare function hasAttestation(bundle: unknown): boolean;
 
 declare function getAttestationReceipt(bundle: unknown): AttestationReceipt | null;
@@ -64,4 +84,121 @@ declare function attestIfNeeded(bundle: CerAiExecutionBundle, options: AttestOpt
     receipt: AttestationReceipt;
 }>;
 
-export { AiExecutionSnapshotV1, AttestOptions, AttestationReceipt, AttestationResult, CerAiExecutionBundle, CerAttestationError, CerMeta, CerVerificationError, CertifyDecisionParams, CreateSnapshotParams, RunBuilder, RunBuilderOptions, RunSummary, StepParams, VerificationResult, attest, attestIfNeeded, certifyAndAttestDecision, certifyDecision, computeInputHash, computeOutputHash, createSnapshot, exportCer, getAttestationReceipt, hasAttestation, hashCanonicalJson, hashUtf8, importCer, sanitizeForAttestation, sealCer, sha256Hex, toCanonicalJson, verifyCer as verify, verifyCer, verifySnapshot };
+declare function verifyNodeReceiptSignature(params: {
+    receipt: SignedAttestationReceipt;
+    signatureB64Url: string;
+    key: {
+        jwk?: NodeKeysDocument['keys'][number]['publicKeyJwk'];
+        spkiB64?: string;
+        rawB64Url?: string;
+    };
+}): Promise<NodeReceiptVerifyResult>;
+declare function fetchNodeKeys(nodeUrl: string): Promise<NodeKeysDocument>;
+type SelectKeySuccess = {
+    key: NodeKeysDocument['keys'][number];
+    error?: never;
+};
+type SelectKeyFailure = {
+    error: NodeReceiptVerifyResult;
+    key?: never;
+};
+type SelectKeyResult = SelectKeySuccess | SelectKeyFailure;
+declare function selectNodeKey(doc: NodeKeysDocument, kid?: string): SelectKeyResult;
+declare function verifyBundleAttestation(bundle: unknown, options: {
+    nodeUrl: string;
+    kid?: string;
+}): Promise<NodeReceiptVerifyResult>;
+
+/**
+ * @nexart/ai-execution — certifyDecisionFromProviderCall (v0.6.0)
+ *
+ * High-level one-function wrapper for common AI provider call patterns.
+ * Extracts prompt / input / output / parameters from raw request+response
+ * objects and produces a sealed CerAiExecutionBundle.
+ *
+ * Supported providers: openai, anthropic, mistral, gemini, bedrock, + generic.
+ *
+ * Returns { ok: true, bundle } on success.
+ * Returns { ok: false, code: 'SCHEMA_ERROR', reason } when a required field
+ * cannot be extracted — never silently guesses.
+ */
+
+interface ProviderCallParams {
+    provider: string;
+    model?: string;
+    request: Record<string, unknown>;
+    response: Record<string, unknown>;
+    meta?: CerMeta;
+    executionId?: string;
+    timestamp?: string;
+    /** CER creation timestamp. Defaults to current time if omitted. */
+    createdAt?: string;
+    appId?: string | null;
+    workflowId?: string | null;
+    conversationId?: string | null;
+}
+type ProviderCallResult = {
+    ok: true;
+    bundle: CerAiExecutionBundle;
+} | {
+    ok: false;
+    code: typeof CerVerifyCode.SCHEMA_ERROR;
+    reason: string;
+};
+/**
+ * Certify an AI provider call from raw request + response objects.
+ *
+ * @example
+ * ```typescript
+ * const res = certifyDecisionFromProviderCall({
+ *   provider: 'openai',
+ *   request: { model: 'gpt-4o', messages: [...] },
+ *   response: { choices: [{ message: { content: 'Hello' } }] },
+ * });
+ * if (res.ok) console.log(res.bundle.certificateHash);
+ * else console.error(res.reason);
+ * ```
+ */
+declare function certifyDecisionFromProviderCall(params: ProviderCallParams): ProviderCallResult;
+
+/**
+ * @nexart/ai-execution — createClient factory (v0.6.0)
+ *
+ * Returns a configured client with opinionated defaults applied to every call.
+ * Defaults NEVER affect bundle hashing — they are only injected into snapshot
+ * fields (appId, workflowId) and attestation options (nodeUrl, apiKey).
+ *
+ * Usage:
+ *   const client = createClient({ appId: 'my-app', nodeUrl: 'https://...' });
+ *   const bundle = client.certifyDecision({ provider, model, ... });
+ *   const result = await client.verify(bundle);
+ */
+
+interface ClientDefaults {
+    appId?: string | null;
+    workflowId?: string | null;
+    nodeUrl?: string;
+    apiKey?: string | (() => string | Promise<string>);
+    tags?: string[];
+    source?: string;
+}
+interface NexArtClient {
+    certifyDecision(params: CertifyDecisionParams): CerAiExecutionBundle;
+    certifyAndAttestDecision(params: CertifyDecisionParams, options?: Partial<AttestOptions>): Promise<{
+        bundle: CerAiExecutionBundle;
+        receipt: AttestationReceipt;
+    }>;
+    verify(bundle: CerAiExecutionBundle): VerificationResult;
+    verifyBundleAttestation(bundle: unknown, options?: {
+        nodeUrl?: string;
+        kid?: string;
+    }): Promise<NodeReceiptVerifyResult>;
+}
+/**
+ * Create a pre-configured client that applies defaults to every operation.
+ *
+ * @param defaults — Shared configuration applied to all client calls.
+ */
+declare function createClient(defaults?: ClientDefaults): NexArtClient;
+
+export { AiExecutionSnapshotV1, AttestOptions, AttestationReceipt, AttestationResult, CerAiExecutionBundle, CerAttestationError, CerMeta, CerVerificationError, CerVerifyCode, CerVerifyCode as CerVerifyCodeType, CertifyDecisionParams, CreateSnapshotParams, NodeKeysDocument, NodeReceiptVerifyResult, RunBuilder, RunBuilderOptions, RunSummary, SanitizeStorageOptions, SignedAttestationReceipt, StepParams, VerificationResult, attest, attestIfNeeded, certifyAndAttestDecision, certifyDecision, certifyDecisionFromProviderCall, computeInputHash, computeOutputHash, createClient, createSnapshot, exportCer, fetchNodeKeys, getAttestationReceipt, hasAttestation, hashCanonicalJson, hashUtf8, importCer, sanitizeForAttestation, sanitizeForStamp, sanitizeForStorage, sealCer, selectNodeKey, sha256Hex, toCanonicalJson, verifyCer as verify, verifyBundleAttestation, verifyCer, verifyNodeReceiptSignature, verifySnapshot };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as CreateSnapshotParams, A as AiExecutionSnapshotV1, V as VerificationResult, a as CerMeta, b as CerAiExecutionBundle, c as CertifyDecisionParams, R as RunBuilderOptions, S as StepParams, d as RunSummary, e as AttestOptions, f as AttestationResult, g as AttestationReceipt } from './types-Cnm2G_rg.js';
-export { i as AiExecutionParameters, j as AttestationReceiptResult, h as CerVerifyCode, h as CerVerifyCodeType, P as ProviderConfig, W as WrappedExecutionParams, k as WrappedExecutionResult } from './types-Cnm2G_rg.js';
+import { C as CreateSnapshotParams, A as AiExecutionSnapshotV1, V as VerificationResult, a as CerMeta, b as CerAiExecutionBundle, c as CertifyDecisionParams, R as RunBuilderOptions, S as StepParams, d as RunSummary, e as AttestOptions, f as AttestationResult, g as SanitizeStorageOptions, h as AttestationReceipt, N as NodeKeysDocument, i as NodeReceiptVerifyResult, j as SignedAttestationReceipt, k as CerVerifyCode } from './types-Cgb52dTx.js';
+export { l as AiExecutionParameters, m as AttestationReceiptResult, n as ClientDefaults, o as NexArtClient, P as ProviderCallParams, p as ProviderCallResult, q as ProviderConfig, W as WrappedExecutionParams, r as WrappedExecutionResult } from './types-Cgb52dTx.js';
 export { wrapProvider } from './providers/wrap.js';
 
 declare class CerVerificationError extends Error {
@@ -50,7 +50,27 @@ declare function attest(bundle: CerAiExecutionBundle, options: AttestOptions): P
 declare function exportCer(bundle: CerAiExecutionBundle): string;
 declare function importCer(json: string): CerAiExecutionBundle;
 
+/** @deprecated Use sanitizeForStorage or sanitizeForStamp instead. */
 declare function sanitizeForAttestation(bundle: CerAiExecutionBundle): CerAiExecutionBundle;
+/**
+ * Prepare a bundle for safe storage:
+ * - Removes undefined keys.
+ * - Removes non-JSON-serializable types (bigint, function, symbol).
+ * - Optionally redacts sensitive field paths.
+ *
+ * Does NOT recompute certificateHash or any content hashes.
+ */
+declare function sanitizeForStorage(bundle: CerAiExecutionBundle, options?: SanitizeStorageOptions): CerAiExecutionBundle;
+/**
+ * Produce the minimal "attestable core" envelope for a bundle.
+ *
+ * Returns only: bundleType, certificateHash, createdAt, version, snapshot.
+ * The meta field is excluded — it is informational and not included in the
+ * certificateHash computation.
+ *
+ * Does NOT recompute any hashes.
+ */
+declare function sanitizeForStamp(bundle: CerAiExecutionBundle): Omit<CerAiExecutionBundle, 'meta'>;
 declare function hasAttestation(bundle: unknown): boolean;
 
 declare function getAttestationReceipt(bundle: unknown): AttestationReceipt | null;
@@ -64,4 +84,121 @@ declare function attestIfNeeded(bundle: CerAiExecutionBundle, options: AttestOpt
     receipt: AttestationReceipt;
 }>;
 
-export { AiExecutionSnapshotV1, AttestOptions, AttestationReceipt, AttestationResult, CerAiExecutionBundle, CerAttestationError, CerMeta, CerVerificationError, CertifyDecisionParams, CreateSnapshotParams, RunBuilder, RunBuilderOptions, RunSummary, StepParams, VerificationResult, attest, attestIfNeeded, certifyAndAttestDecision, certifyDecision, computeInputHash, computeOutputHash, createSnapshot, exportCer, getAttestationReceipt, hasAttestation, hashCanonicalJson, hashUtf8, importCer, sanitizeForAttestation, sealCer, sha256Hex, toCanonicalJson, verifyCer as verify, verifyCer, verifySnapshot };
+declare function verifyNodeReceiptSignature(params: {
+    receipt: SignedAttestationReceipt;
+    signatureB64Url: string;
+    key: {
+        jwk?: NodeKeysDocument['keys'][number]['publicKeyJwk'];
+        spkiB64?: string;
+        rawB64Url?: string;
+    };
+}): Promise<NodeReceiptVerifyResult>;
+declare function fetchNodeKeys(nodeUrl: string): Promise<NodeKeysDocument>;
+type SelectKeySuccess = {
+    key: NodeKeysDocument['keys'][number];
+    error?: never;
+};
+type SelectKeyFailure = {
+    error: NodeReceiptVerifyResult;
+    key?: never;
+};
+type SelectKeyResult = SelectKeySuccess | SelectKeyFailure;
+declare function selectNodeKey(doc: NodeKeysDocument, kid?: string): SelectKeyResult;
+declare function verifyBundleAttestation(bundle: unknown, options: {
+    nodeUrl: string;
+    kid?: string;
+}): Promise<NodeReceiptVerifyResult>;
+
+/**
+ * @nexart/ai-execution — certifyDecisionFromProviderCall (v0.6.0)
+ *
+ * High-level one-function wrapper for common AI provider call patterns.
+ * Extracts prompt / input / output / parameters from raw request+response
+ * objects and produces a sealed CerAiExecutionBundle.
+ *
+ * Supported providers: openai, anthropic, mistral, gemini, bedrock, + generic.
+ *
+ * Returns { ok: true, bundle } on success.
+ * Returns { ok: false, code: 'SCHEMA_ERROR', reason } when a required field
+ * cannot be extracted — never silently guesses.
+ */
+
+interface ProviderCallParams {
+    provider: string;
+    model?: string;
+    request: Record<string, unknown>;
+    response: Record<string, unknown>;
+    meta?: CerMeta;
+    executionId?: string;
+    timestamp?: string;
+    /** CER creation timestamp. Defaults to current time if omitted. */
+    createdAt?: string;
+    appId?: string | null;
+    workflowId?: string | null;
+    conversationId?: string | null;
+}
+type ProviderCallResult = {
+    ok: true;
+    bundle: CerAiExecutionBundle;
+} | {
+    ok: false;
+    code: typeof CerVerifyCode.SCHEMA_ERROR;
+    reason: string;
+};
+/**
+ * Certify an AI provider call from raw request + response objects.
+ *
+ * @example
+ * ```typescript
+ * const res = certifyDecisionFromProviderCall({
+ *   provider: 'openai',
+ *   request: { model: 'gpt-4o', messages: [...] },
+ *   response: { choices: [{ message: { content: 'Hello' } }] },
+ * });
+ * if (res.ok) console.log(res.bundle.certificateHash);
+ * else console.error(res.reason);
+ * ```
+ */
+declare function certifyDecisionFromProviderCall(params: ProviderCallParams): ProviderCallResult;
+
+/**
+ * @nexart/ai-execution — createClient factory (v0.6.0)
+ *
+ * Returns a configured client with opinionated defaults applied to every call.
+ * Defaults NEVER affect bundle hashing — they are only injected into snapshot
+ * fields (appId, workflowId) and attestation options (nodeUrl, apiKey).
+ *
+ * Usage:
+ *   const client = createClient({ appId: 'my-app', nodeUrl: 'https://...' });
+ *   const bundle = client.certifyDecision({ provider, model, ... });
+ *   const result = await client.verify(bundle);
+ */
+
+interface ClientDefaults {
+    appId?: string | null;
+    workflowId?: string | null;
+    nodeUrl?: string;
+    apiKey?: string | (() => string | Promise<string>);
+    tags?: string[];
+    source?: string;
+}
+interface NexArtClient {
+    certifyDecision(params: CertifyDecisionParams): CerAiExecutionBundle;
+    certifyAndAttestDecision(params: CertifyDecisionParams, options?: Partial<AttestOptions>): Promise<{
+        bundle: CerAiExecutionBundle;
+        receipt: AttestationReceipt;
+    }>;
+    verify(bundle: CerAiExecutionBundle): VerificationResult;
+    verifyBundleAttestation(bundle: unknown, options?: {
+        nodeUrl?: string;
+        kid?: string;
+    }): Promise<NodeReceiptVerifyResult>;
+}
+/**
+ * Create a pre-configured client that applies defaults to every operation.
+ *
+ * @param defaults — Shared configuration applied to all client calls.
+ */
+declare function createClient(defaults?: ClientDefaults): NexArtClient;
+
+export { AiExecutionSnapshotV1, AttestOptions, AttestationReceipt, AttestationResult, CerAiExecutionBundle, CerAttestationError, CerMeta, CerVerificationError, CerVerifyCode, CerVerifyCode as CerVerifyCodeType, CertifyDecisionParams, CreateSnapshotParams, NodeKeysDocument, NodeReceiptVerifyResult, RunBuilder, RunBuilderOptions, RunSummary, SanitizeStorageOptions, SignedAttestationReceipt, StepParams, VerificationResult, attest, attestIfNeeded, certifyAndAttestDecision, certifyDecision, certifyDecisionFromProviderCall, computeInputHash, computeOutputHash, createClient, createSnapshot, exportCer, fetchNodeKeys, getAttestationReceipt, hasAttestation, hashCanonicalJson, hashUtf8, importCer, sanitizeForAttestation, sanitizeForStamp, sanitizeForStorage, sealCer, selectNodeKey, sha256Hex, toCanonicalJson, verifyCer as verify, verifyBundleAttestation, verifyCer, verifyNodeReceiptSignature, verifySnapshot };