EVE CoreGuard — TypeScript SDK (eve-ai-governance)

eve-ai-governance is the TypeScript/JavaScript offline verification library for EVE CoreGuard evidence. It is a set of plain functions — there is no client class. Its primary entry point is:

import { verifyDecisionCertificate } from "eve-ai-governance";

Use it to verify signed EVE decision evidence in Node or the browser without trusting the EVE server. The package never signs, holds no secrets, and performs no enforcement — it only verifies, using public keys. To enforce (block or require approval before an action runs), call the CoreGuard REST API or the Python eve-coreguard client; this package does not gate actions.

Readiness

• Package: eve-ai-governance 0.3.1 (ESM, Node >= 18; validated on Node v25; zero dependencies). This is a release-candidate offline verification library — part of an SDK core that is a RELEASE CANDIDATE WITH EXCLUSIONS.
• Verification only: a browser-safe offline evidence verifier with no client and no network calls. Enforcement lives in the CoreGuard REST API or the Python eve-coreguard client.
• Signed evidence and offline verification are SUPPORTED; the core CoreGuard decision is pilot-validated.
• The packages are published on public registries: pip install eve-coreguard (PyPI) and npm install eve-ai-governance (npm).

Limitations

• No enforcement in TypeScript. This package cannot block or require approval — it only verifies evidence. There is no TypeScript governance client class and no in-process/embedded TypeScript governance. Enforce from Node via the CoreGuard REST API (POST /v1/decisions/evaluate) or the Python eve-coreguard client.
• The verifier never signs and holds no private keys; it verifies with public keys only.
• Offline verification proves the evidence is authentic and unaltered; it does not attest that the underlying decision was correct.
• Independent (asymmetric) verification of an kms-ecdsa-p384- signature requires the ECDSA P-384 public key. An hmac- signature is symmetric and is not independently verifiable.
• ESM only (import), Node >= 18.

Install

eve-ai-governance is published on npm and installs with a plain npm install:

# install the published client from npm
npm install eve-ai-governance

package.json must use ESM ("type": "module") or .mjs files; the SDK is import-only and sets sideEffects: false.

Node >= 18 and ESM

• Runtime: Node >= 18 (validated on Node v25).
• Module system: ESM. Import the named verifier functions (e.g. verifyDecisionCertificate); there is no CommonJS require.
• The offline verifier uses only node:crypto primitives that are also available in the browser build path (see Browser-safe verifier).

Types

The package ships index.d.ts. It exports plain verifier functions plus their result/options types — there is no client, config, or governance-result object. Key exports:

// Verifier functions — each returns a VerificationResult (public keys only, no network):
verifyDecisionCertificate(cert, opts?)   // primary: verify a signed decision certificate
verifyDecisionRecord(record, opts?)      // verify a signed decision record
verifyChain(chain, opts?)                // verify a hash-chain
verifyBundle(bundle, opts?)              // verify an evidence bundle
verifyHmac(payload, opts?)               // verify an HMAC (symmetric) signature
// also: verifyDeploymentAttestation, verifyTrustCertificate, verifyOnboardingBundle,
//       verifyItiSnapshot, verifyTrustRootClosure, validatePolicyPack, healthBand

interface VerificationResult {
  valid: boolean;      // the load-bearing field: did verification pass?
  // a result may carry additional diagnostic fields (e.g. a failure reason)
}

interface VerifyOptions {
  publicKeyPem?: string;   // ECDSA P-384 public key for independent (asymmetric) verification
}

// DecisionCertificate — the signed evidence object produced by a governed decision.

Every verifier resolves to a VerificationResult; branch on the boolean result.valid, never on message text.

No client to configure

There is no client to construct and no API key to configure — the package is a set of verifier functions that take an evidence object and an optional public key:

import { verifyDecisionCertificate } from "eve-ai-governance";

// offline; public keys only, no network, no secrets
const result = await verifyDecisionCertificate(cert, { publicKeyPem });
console.log(result.valid ? "VERIFIED" : "FAILED");

Because verification uses only public keys, it is safe in the browser (see Browser-safe verifier). Enforcement — which does need an API key — is a separate concern handled server-side (see Server-only).

Enforcement (not in this package)

This package does not gate actions. To block or require approval before an action runs, call the CoreGuard REST API from Node (or use the Python eve-coreguard client):

// There is no TypeScript enforcement client; enforce from Node via the REST API.
const res = await fetch("https://api.eveaicore.com/v1/decisions/evaluate", {
  method: "POST",
  headers: { Authorization: "Bearer eve_sk_...", "Content-Type": "application/json" },
  body: JSON.stringify({
    request_id: "req-001", tenant_id: "org_123",
    proposed_action: { type: "loan_approval", amount: 250000 },
    model_output: { decision: "approve", confidence: 0.91 },
    context: { credit_score: 580, debt_to_income: 0.52 },
    policy_set: "lending_v1",
  }),
});
const { decision, risk } = await res.json();
if (decision.status === "BLOCKED") console.log(`Blocked (risk ${risk.level})`);

Only proceed when decision.status is not BLOCKED. The REST call sends the API key as a bearer token, so it must run server-side (see Server-only).

Verification results

Each verifier resolves to a VerificationResult whose load-bearing field is the boolean valid: true when the evidence is authentic and unaltered, false on a tampered hash, an unsupported canonicalization, or a bad signature. A result may carry additional diagnostic fields; branch on result.valid — do not branch on message text.

Errors

Verification is local and takes no network. Malformed evidence, an unsupported canonicalization, a content-hash mismatch, or a bad signature all resolve to valid: false rather than throwing on the happy path. Inspect result.valid; never branch on message text.

Fail-closed behavior

Fail-closed enforcement is a property of the enforcement path, not this verifier. When you enforce over the CoreGuard REST API or the Python eve-coreguard client, a service error, timeout, or non-OK response yields a BLOCK rather than a permissive allow, and the production configuration refuses to disable signed evidence, strict verification, distributed consumption, or fail-closed behavior.

On the verification side, the verifier fails safe: tampered or malformed evidence, an unsupported canonicalization, or a bad signature resolve to valid: false. It never reports a bad artifact as valid.

Verification

Verify a signed EVE decision certificate offline, with no secrets:

import { verifyDecisionCertificate } from "eve-ai-governance";

// symmetric (HMAC) fallback signature: authentic but not independently verifiable
const r1 = await verifyDecisionCertificate(cert);
console.log(r1.valid); // true — content hash and HMAC checked

// ECDSA P-384 signature with the public key: independently verifiable
const r2 = await verifyDecisionCertificate(cert, { publicKeyPem });
console.log(r2.valid); // true — signature independently verified

verifyDecisionCertificate (and the sibling verifiers):

• recompute the content hash over the canonical (jcs-1) payload and return valid: false on a mismatch (tampered);
• reject an unsupported canonicalization (canon other than jcs-1);
• for an hmac- signature return valid: true but treat it as not independently verifiable;
• for an kms-ecdsa-p384- signature verify against the supplied publicKeyPem (asymmetric, independently verifiable), or fall back to a content-hash-only check if no key is supplied;
• return valid: false for unsigned or malformed evidence.

Use the matching verifier for the artifact — verifyDecisionRecord for a decision record, verifyChain for a hash-chain, verifyBundle for a bundle. This is the cross-language check: a Python-signed jcs-1 certificate verifies here, and any tampering resolves to valid: false.

Browser-safe verifier

The verifier functions perform no signing and hold no secrets, so they run in the browser (with a Web Crypto or bundler-provided crypto shim) to verify EVE evidence client-side. The tarball contains no server-only signing code.

Server-only

• The enforcement HTTP call (POST /v1/decisions/evaluate) belongs on a server: it sends the API key as a bearer token. Do not embed a real API key in browser code.
• Verification (verifyDecisionCertificate and the sibling verifiers) is safe in the browser.

Differences from the Python SDK

The Python eve-coreguard client governs (hosted, sidecar, or in-service) and verifies; the TypeScript eve-ai-governance package verifies only. Both share the same jcs-1 canonicalization and cross-language evidence verification, so a certificate signed by the Python path verifies byte-for-byte in TypeScript.

See also

• Python SDK
• Reference — API, hosted endpoint, CLI, reason codes, evidence schemas, config fields, env vars, exit codes.