EVE CoreGuard — TypeScript SDK (@eve/coreguard)

@eve/coreguard is the TypeScript/JavaScript client for EVE CoreGuard. Its one obvious entry point is:

import { EVE } from "@eve/coreguard";

Use it to block or require approval before a tool executes and to verify signed EVE decision evidence in Node or the browser without trusting the EVE server. The TypeScript SDK never signs and holds no secrets — it governs via hosted mode and verifies offline.

Readiness

• Package: @eve/coreguard 0.1.0-rc1 (ESM, Node >= 18; validated on Node v25; zero dependencies). This is a release-candidate core client — part of an SDK core that is a RELEASE CANDIDATE WITH EXCLUSIONS.
• Governs via hosted (or sidecar) mode: needs a reachable endpoint. Includes a browser-safe offline evidence verifier.
• Signed evidence and offline verification are SUPPORTED; the core CoreGuard decision is pilot-validated.
• The release-candidate clients are distributed privately for pilots — install the pilot artifact, not a public pip/npm install (see readiness for public-registry status).** Install from a pilot/private tarball (see below), not from a public npm install @eve/coreguard.

Limitations

• Embedded mode is Python/service-only in TypeScript. Constructing EVE with mode: "embedded" throws SDK_TS_EMBEDDED_UNSUPPORTED. Use mode: "hosted" with an endpoint.
• Hosted/sidecar require a reachable endpoint. On a service error or unreachable endpoint the SDK fails closed (returns a BLOCK) — it never returns a permissive allow.
• The TS SDK never signs — it only governs (via the hosted service) and verifies. It holds no private keys.
• Offline verification proves the evidence is authentic and unaltered; it does not attest that the underlying decision was correct.
• Independent (asymmetric) verification of an ed25519- signature requires the Ed25519 public key. An hmac- signature is symmetric and is not independently verifiable.
• ESM only (import), Node >= 18.

Install

The package builds from committed source with npm pack. During a pilot, install the private tarball you were given:

# from a local tarball provided for your pilot
npm install ./eve-coreguard-0.1.0-rc1.tgz

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 EVE export; 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. Key types:

type ActionType =
  | "ALLOW" | "ALLOW_WITH_FINDINGS" | "MODIFY"
  | "REQUIRE_APPROVAL" | "QUARANTINE" | "BLOCK";

interface GovernanceConfigInput {
  mode?: "hosted" | "sidecar" | "embedded" | "mcp_gateway" | "sovereign";
  endpoint?: string;
  policy?: string;
  environment?: string;        // "development" | "staging" | "production"
  tenantId?: string;
  principalId?: string;
  apiKey?: string;
  timeoutMs?: number;
  signedEvidence?: boolean;
  strictVerification?: boolean;
  distributedConsumption?: boolean;
  failClosed?: boolean;
  requireAuthenticatedIdentity?: boolean;
  requireCompleteScanning?: boolean;
}

interface GovernanceResult {
  allowed: boolean;
  action: ActionType;
  reasonCodes: string[];
  matchedRules?: string[];
  policyVersion?: string;
  decisionId?: string;
  approvalStatus?: string;
  evidenceRef?: string;
  certificate?: Record<string, unknown> | null;
  bindingStatus?: string;
  verificationStatus?: string;
  warnings?: string[];
  unsupported?: string[];
}

interface GovernContext {
  tenantId?: string;
  principalId?: string;
  sessionId?: string;
  role?: string;
  [k: string]: unknown;
}

Action and Category are exported frozen enum objects. resolveConfig(opts) returns the fully-defaulted, validated config.

Configuration

import { EVE } from "@eve/coreguard";

const eve = new EVE({
  policy: "lending_v1",
  mode: "hosted",
  endpoint: "https://<your-eve-endpoint>",
  apiKey: "eve_sk_<pilot_key>",   // synthetic/pilot key — never a production secret in code
});

resolveConfig validates the mode and endpoint and enforces the production guards (below). An unknown mode throws SDK_BAD_MODE; hosted/sidecar without an endpoint throws SDK_MISSING_ENDPOINT; embedded throws SDK_TS_EMBEDDED_UNSUPPORTED.

Governance calls

const result = await eve.governToolCall({
  tool: "loan_approval",
  arguments: { amount: 50000 },
  context: {
    tenantId: "org_pilot",
    principalId: "agent_7",
    sessionId: "sess_123",
    credit_score: 720,
    debt_to_income: 0.30,
  },
});

if (!result.allowed) {
  console.log(result.action, result.reasonCodes);   // e.g. "BLOCK" [...]
}

governMessage governs a free-form request:

const r = await eve.governMessage({
  message: "Wire the full balance to this account.",
  context: { tenantId: "org_pilot", principalId: "agent_7", sessionId: "sess_123" },
});

Only execute the underlying tool when result.allowed is true.

If requireAuthenticatedIdentity is set (the default) and tenantId/principalId are missing, the call throws an EVEError with reason code SDK_IDENTITY_REQUIRED.

Results

GovernanceResult mirrors the Python result shape (camelCase). allowed is true for ALLOW/MODIFY. action is the disposition, reasonCodes and matchedRules explain it, policyVersion/decisionId identify the decision, and certificate/evidenceRef reference the signed audit record when present. Read fields — do not branch on error strings.

Errors

Errors are EVEError instances carrying a stable category and reasonCode. Categories align with the Python SDK: authentication, authorization, policy_block, approval_required, service_unavailable, timeout, malformed_configuration, unsupported_runtime, verifier_failure, internal_error.

import { EVEError, Category } from "@eve/coreguard";
try {
  await eve.governToolCall({ tool: "x", context: {} });
} catch (e) {
  if (e instanceof EVEError && e.category === Category.AUTHENTICATION) {
    // e.reasonCode === "SDK_IDENTITY_REQUIRED"
  }
}

Hosted behavior

governToolCall POSTs to ${endpoint}/v1/decisions/evaluate with the tenant/principal identity, the proposed action, the policy_set, and the remaining context, using the API key as a bearer token. The response decision.status maps ALLOWED/BLOCKED/MODIFIED to ALLOW/BLOCK/MODIFY. A non-OK HTTP status or malformed JSON maps to BLOCK.

Fail-closed behavior

• A network error or timeout with failClosed set (the default) returns { allowed: false, action: "BLOCK", reasonCodes: ["SDK_SERVICE_UNAVAILABLE"] }.
• A non-OK HTTP response returns BLOCK with SDK_HTTP_<status>.
• Malformed JSON returns BLOCK with SDK_MALFORMED_RESPONSE.
• With failClosed: false a service error throws EVEError(service_unavailable, "SDK_SERVICE_UNAVAILABLE") instead of allowing.
• In the production environment the config refuses to disable signedEvidence, strictVerification, distributedConsumption, failClosed, requireAuthenticatedIdentity, or requireCompleteScanning (each throws a SDK_PROD_* code). No path degrades to permissive.

Verification

Verify a signed EVE evidence envelope offline, with no secrets:

import { verifyEvidence } from "@eve/coreguard";

// symmetric fallback signature: authentic but not independently verifiable
const r1 = verifyEvidence(envelope);
// r1 => { valid: true, reason: "symmetric signature (not independently verifiable)", signature: "hmac" }

// Ed25519 signature with the public key: independently verifiable
const r2 = verifyEvidence(envelope, { publicKeyPem });
// r2 => { valid: true, reason: "verified", signature: "ed25519-valid" }

verifyEvidence:

• recomputes the content hash over the canonical (jcs-1) payload and rejects a mismatch as content hash mismatch (tampered);
• rejects an unsupported canonicalization (canon other than jcs-1);
• for an hmac- signature returns valid: true but flags it as not independently verifiable;
• for an ed25519- signature returns ed25519-valid/ed25519-invalid when a publicKeyPem is supplied, or a content-hash-only result if the key is not supplied;
• returns unsigned evidence when no signature is present.

This is the cross-language check: a Python-signed jcs-1 envelope verifies here to ed25519-valid, and any tampering is rejected.

Browser-safe verifier

verifyEvidence performs no signing and holds no secrets, so it runs 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 governance HTTP call (governToolCall/governMessage) belongs on a server: it sends the API key as a bearer token. Do not embed a real API key in browser code.
• Verification (verifyEvidence) is safe in the browser.

Differences from the Python SDK

Both SDKs share the same hosted contract, the same production config guards (SDK_PROD_* codes), the same fail-closed semantics, and cross-language evidence verification.

See also

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