eve-ai-governance 0.2.0

package/LICENSE

@@ -0,0 +1,18 @@
+EVE AI Core Governance SDK (JavaScript) — Proprietary License
+Copyright (c) 2026 EVE NeuroSystems LLC. All rights reserved.
+
+This software (the "Software") is the confidential and proprietary property of
+EVE NeuroSystems LLC ("Licensor") and is licensed, not sold. Subject to a
+separate written commercial or pilot agreement with Licensor, you may use the
+Software solely to integrate with the EVE AI Core / EVE CoreGuard service.
+Absent such an agreement, no rights are granted other than to evaluate it.
+
+You may not redistribute, sublicense, sell, publish, reverse engineer, or create
+derivative works except as permitted by a commercial agreement or applicable
+law, nor remove proprietary notices.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL
+LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE
+SOFTWARE OR ITS USE.
+
+For licensing inquiries: sdk@eveaicore.com

package/README.md

@@ -0,0 +1,58 @@
+# eve-ai-governance
+
+**EVE AI Core Governance SDK (Node/TypeScript)** — deterministic AI decision
+enforcement in one API call, plus offline proof verification.
+
+```bash
+npm install eve-ai-governance
+```
+
+Zero-config, dependency-light, ships ESM + CJS + type declarations.
+
+## Enforce a decision
+
+```ts
+import { GovernanceClient, RateLimitError, PaymentRequiredError } from 'eve-ai-governance';
+
+const client = new GovernanceClient({ apiKey: 'eve_sk_...' });
+
+const result = await client.evaluate({
+  request_id: 'req-001',
+  tenant_id: 'bank_001',
+  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',
+});
+// result.decision.status -> "ALLOWED" | "BLOCKED" | "MODIFIED"
+
+// Billing / rate-limit metadata from the most recent call:
+client.subscriptionState; // 'active' | 'past_due' | ...
+client.rateLimit;         // { limit, remaining } | { limit: null, ... }
+client.quotaWarning;      // null | 'payment_past_due'
+```
+
+Auth is `Authorization: Bearer eve_...`; the org/tenant is derived from the key
+server-side. See the [Response-Header Contract](../../docs/sdk/RESPONSE_HEADER_CONTRACT.md)
+for the full status-code and accessor reference (`RateLimitError` on 429,
+`PaymentRequiredError` on 402).
+
+## Verify a proof offline
+
+`verifyProof` recomputes the canonical content hash and checks the HMAC-SHA256
+signature **locally** — no network call. The canonicalization is byte-for-byte
+compatible with the Python SDKs (`json.dumps(sort_keys=True)`), so a proof signed
+by EVE verifies here and vice-versa. Tampering any field (including nested ones)
+fails; a wrong/empty signature returns `false` (never throws).
+
+```ts
+import { GovernanceClient } from 'eve-ai-governance';
+
+const ok = GovernanceClient.verifyProof(proofBundle, sharedSigningKey); // boolean
+```
+
+The same canonicalizer is exported as `canonicalizeForHash` for custom tooling.
+
+## License
+
+Proprietary. See LICENSE.

package/dist/cjs/client.d.ts

@@ -0,0 +1,175 @@
+import type { GovernanceClientOptions, VerifyRequest, VerifyResult, BatchResult, CircuitBreakerStatus, HealthStatus, PipelineStats, FirewallResult, RedactionResult, SemanticResult, PolicyResult, PolicyDefinition, Policy, TurnAssessment, BudgetResult, WatermarkResult, CostResult, ComplianceReport, DecisionReplay, Webhook, TenantDashboard, DriftAssessment, VerificationResult, ReviewSubmission, ReviewTicket, GovernanceChain, ChainHop, ResidencyResult, TestCase, SimulationResult, EvaluateRequest, EvaluationResult, ProofBundle, AuditExport, ResponseMeta } from './models';
+/**
+ * EVE AI Core Governance Client.
+ *
+ * @example
+ * ```typescript
+ * const client = new GovernanceClient({ apiKey: 'eve_sk_...' });
+ *
+ * const result = await client.verify({
+ *   aiOutput: 'The capital of France is Paris.',
+ *   domain: 'factual',
+ *   confidence: 0.9,
+ * });
+ *
+ * if (result.blocked) {
+ *   console.log(`BLOCKED: ${result.veto.reason}`);
+ * } else {
+ *   console.log(`PASSED — CRD: ${result.crd.toFixed(2)}`);
+ * }
+ * ```
+ */
+export declare class GovernanceClient {
+    private baseUrl;
+    private apiKey;
+    private timeoutMs;
+    private maxRetries;
+    private raiseOnVeto;
+    private _lastResponseMeta;
+    constructor(opts: GovernanceClientOptions);
+    /** Full parsed metadata of the most recent response, or null before any call. */
+    get lastResponseMeta(): ResponseMeta | null;
+    /** Subscription state from the last call (e.g. 'active', 'past_due', 'restricted'). */
+    get subscriptionState(): string | null;
+    /** Access state from the last call (e.g. 'full_access', 'warning', 'read_only'). */
+    get accessState(): string | null;
+    /** Non-null when the account is in a billing warning (e.g. 'payment_past_due'). */
+    get quotaWarning(): string | null;
+    /** Seconds to wait before retrying, from the last 429 (else null). */
+    get retryAfter(): number | null;
+    /** Rate-limit budget from the last call: { limit, remaining }. */
+    get rateLimit(): {
+        limit: number | null;
+        remaining: number | null;
+    };
+    /**
+     * Run AI output through the 8-stage governance enforcement pipeline.
+     */
+    verify(req: VerifyRequest): Promise<VerifyResult>;
+    /**
+     * Verify up to 50 AI outputs in a single request.
+     */
+    verifyBatch(items: VerifyRequest[]): Promise<BatchResult>;
+    /** Get the current circuit breaker state. */
+    circuitBreaker(): Promise<CircuitBreakerStatus>;
+    /** Check pipeline health. */
+    health(): Promise<HealthStatus>;
+    /** Get aggregate pipeline statistics. */
+    stats(): Promise<PipelineStats>;
+    /** Scan input text through the prompt firewall. */
+    scanInput(text: string, sessionId?: string): Promise<FirewallResult>;
+    /** Redact personally identifiable information from text. */
+    redactPII(text: string): Promise<RedactionResult>;
+    /** Detect semantic attacks (jailbreak, injection, etc.). */
+    detectAttack(text: string): Promise<SemanticResult>;
+    /** Evaluate text against governance policies. */
+    evaluatePolicy(text: string, opts?: {
+        confidence?: number;
+        domain?: string;
+        tenantId?: string;
+    }): Promise<PolicyResult>;
+    /** List governance policies, optionally filtered by tenant. */
+    listPolicies(tenantId?: string): Promise<Policy[]>;
+    /** Add a new governance policy. Returns the policy ID. */
+    addPolicy(policy: PolicyDefinition): Promise<string>;
+    /** Assess cumulative risk across a multi-turn session. */
+    assessTurn(sessionId: string, message: string, riskScore?: number): Promise<TurnAssessment>;
+    /** Record output and check against the session's token budget. */
+    checkBudget(sessionId: string, responseText: string): Promise<BudgetResult>;
+    /** Verify a governance watermark on AI-generated content. */
+    verifyWatermark(watermarkId: string, text?: string): Promise<WatermarkResult>;
+    /** Record LLM usage costs and check budget compliance. */
+    recordCost(tenantId: string, model: string, inputTokens: number, outputTokens: number): Promise<CostResult>;
+    /** Generate a compliance report for a tenant against a framework. */
+    generateComplianceReport(tenantId: string, framework: string, periodDays?: number): Promise<ComplianceReport>;
+    /** Replay a specific governance decision by ID. */
+    replayDecision(decisionId: string): Promise<DecisionReplay>;
+    /** Query governance decisions with optional filters. */
+    queryDecisions(opts?: {
+        sessionId?: string;
+        vetoType?: string;
+        limit?: number;
+    }): Promise<DecisionReplay[]>;
+    /** Register a webhook to receive governance event notifications. */
+    registerWebhook(name: string, url: string, events: string[], format?: string): Promise<Webhook>;
+    /** List all registered webhooks. */
+    listWebhooks(): Promise<Webhook[]>;
+    /** Get the governance analytics dashboard for a tenant. */
+    getTenantDashboard(tenantId: string): Promise<TenantDashboard>;
+    /** Check for model output drift against baseline. */
+    checkDrift(modelId: string): Promise<DriftAssessment>;
+    /** Verify model supply chain integrity and provenance. */
+    verifyModel(modelId: string): Promise<VerificationResult>;
+    /** Submit a governance decision for human review. */
+    submitForReview(opts: ReviewSubmission): Promise<ReviewTicket>;
+    /** Get pending human review tickets. */
+    getPendingReviews(limit?: number): Promise<ReviewTicket[]>;
+    /** Start a new governance chain for multi-model interactions. */
+    startChain(initiator: string, purpose: string): Promise<GovernanceChain>;
+    /** Record a hop in a governance chain. */
+    recordHop(chainId: string, fromModel: string, toModel: string, crdScore: number, vetoType: string): Promise<ChainHop>;
+    /** Check data residency compliance for a tenant and target region. */
+    checkResidency(text: string, tenantId: string, targetRegion: string): Promise<ResidencyResult>;
+    /** Run a policy simulation in a sandboxed environment. */
+    runSimulation(policies: PolicyDefinition[], testCases?: TestCase[]): Promise<SimulationResult>;
+    /** Evaluate a proposed AI decision against enterprise policy. */
+    evaluate(request: EvaluateRequest): Promise<EvaluationResult>;
+    /** List available policy sets on the server. */
+    listPolicySets(): Promise<{
+        policy_sets: string[];
+    }>;
+    /** Retrieve a cryptographic proof bundle for a governance decision. */
+    getProof(proofId: string): Promise<ProofBundle>;
+    /** Export governance decision records for compliance reporting. */
+    exportAudit(options?: {
+        since?: string;
+        actionType?: string;
+        decision?: string;
+        limit?: number;
+    }): Promise<AuditExport>;
+    /** Verify the integrity of the governance proof hash chain. */
+    verifyChain(): Promise<{
+        total_records: number;
+        chain_valid: boolean;
+        chain_message: string;
+    }>;
+    /**
+     * Verify a proof bundle's integrity locally (no server call).
+     * Requires the signing key used by the server.
+     *
+     * Canonicalization target: the EVE backend / Python SDK compute the proof's
+     * content hash as `sha256(json.dumps(payload, sort_keys=True))` — see
+     * `sdks/coreguard/eve_coreguard/client.py::verify_proof_offline` (which
+     * verifies these IDENTICAL flat proof bundles) and
+     * `sdks/proof/eve_proof/verify.py::recompute_content_hash`. To verify a
+     * server-issued proof, this MUST reproduce Python's `json.dumps(...,
+     * sort_keys=True)` output BYTE-FOR-BYTE: keys sorted at every depth, the
+     * `", "` / `": "` separators (spaces after comma/colon), and `ensure_ascii`
+     * escaping (every non-ASCII code unit → `\uXXXX`, surrogate pairs included).
+     * The signature is then `HMAC-SHA256(signing_key, content_hash)` (hex).
+     * @see canonicalizeForHash
+     */
+    static verifyProof(proof: ProofBundle, signingKey: string): boolean;
+    private _request;
+    private _get;
+    private _post;
+    private _maybeThrow;
+}
+/**
+ * Deterministic, recursive canonical JSON serializer matching Python's
+ * `json.dumps(value, sort_keys=True)` byte-for-byte:
+ *   - object keys sorted by code point at EVERY depth (recurses into nested
+ *     objects AND arrays; arrays keep their element order),
+ *   - `", "` and `": "` separators (a space after each comma and colon),
+ *   - `ensure_ascii` escaping for all non-ASCII characters.
+ *
+ * Primitives (string/number/boolean/null) delegate to JSON.stringify, whose
+ * number formatting and control/quote escaping match Python for the integer
+ * and finite-decimal values proof bundles carry. (Exotic floats — e.g. 1e21 —
+ * could differ from Python's repr, but proofs use plain ints/decimals.)
+ * `undefined` and functions are dropped from objects and rendered as `null`
+ * inside arrays, mirroring JSON.stringify; non-finite numbers become `null`.
+ */
+export declare function canonicalizeForHash(value: unknown): string;
+export default GovernanceClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

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