@vorionsys/cognigate 1.0.1 → 1.0.2

package/README.md

@@ -1,6 +1,11 @@
-# @vorion/cognigate
+# @vorionsys/cognigate
 
-Official TypeScript SDK for the [Cognigate](https://cognigate.dev) AI Governance API.
+Real-time AI governance decision engine -- the TypeScript SDK for the [Cognigate](https://cognigate.dev) API.
+
+[![npm version](https://img.shields.io/npm/v/@vorionsys/cognigate)](https://www.npmjs.com/package/@vorionsys/cognigate)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+---
 
 ## Installation
 
@@ -8,220 +13,283 @@ Official TypeScript SDK for the [Cognigate](https://cognigate.dev) AI Governance
 npm install @vorionsys/cognigate
 ```
 
-## Quick Start
+## What is Cognigate?
+
+**Cognigate** is Vorion's real-time AI governance decision engine. It sits between your AI agents and the actions they want to perform, evaluating every request against trust scores, capability policies, and risk levels before granting or denying permission. Every decision is recorded as an immutable proof record, creating a tamper-evident audit trail.
+
+Cognigate implements the trust-tier model defined by the **BASIS** (Baseline Authority for Safe & Interoperable Systems) specification. BASIS defines eight trust tiers (T0 through T7) that govern what an AI agent is allowed to do based on its demonstrated track record. As agents prove reliability, they earn higher trust scores and unlock broader capabilities -- all enforced automatically by Cognigate.
+
+### Core concepts
+
+| Concept | Description |
+|---|---|
+| **Trust Score** | A 0--1000 numeric score reflecting an agent's reliability. Computed from outcomes, compliance, and behavioral signals. |
+| **Trust Tier** | One of eight BASIS tiers (T0 Sandbox through T7 Autonomous) derived from the trust score. Each tier grants a specific set of capabilities. |
+| **Governance Decision** | The verdict for a requested action: `ALLOW`, `DENY`, `ESCALATE` (requires human approval), or `DEGRADE` (partial access). |
+| **Intent** | A structured representation of what an agent wants to do, parsed from natural-language input. |
+| **Proof Record** | An immutable, hash-chained audit entry recording each governance decision and its outcome. |
+| **Proof Bridge** | Optional integration that forwards Cognigate decisions to the Vorion Proof Plane for cross-system audit trails. |
+
+---
+
+## Quick start
 
 ```typescript
 import { Cognigate } from '@vorionsys/cognigate';
 
 const client = new Cognigate({
-  apiKey: process.env.COGNIGATE_API_KEY,
+  apiKey: process.env.COGNIGATE_API_KEY!,
 });
 
-// Get trust status for an agent
-const status = await client.trust.getStatus('agent-123');
+// 1. Register an agent
+const agent = await client.agents.create({
+  name: 'DataProcessor',
+  description: 'ETL pipeline agent',
+  initialCapabilities: ['read_database', 'write_s3'],
+});
+
+// 2. Check trust status
+const status = await client.trust.getStatus(agent.id);
 console.log(`Trust Score: ${status.trustScore}`);
 console.log(`Tier: ${status.tierName}`);
 console.log(`Capabilities: ${status.capabilities.join(', ')}`);
-```
 
-## Features
+// 3. Evaluate a governance request (parse intent + enforce)
+const { intent, result } = await client.governance.evaluate(
+  agent.id,
+  'Read customer data from the sales database'
+);
 
-- **Full TypeScript Support**: Complete type definitions with Zod runtime validation
-- **Trust Management**: Query and update agent trust scores
-- **Governance Enforcement**: Parse intents and enforce governance rules
-- **Proof Chain**: Immutable audit trail for all agent actions
-- **Webhook Support**: Handle Cognigate webhooks with signature verification
+if (result.decision === 'ALLOW') {
+  console.log('Proceeding -- granted:', result.grantedCapabilities);
+} else if (result.decision === 'ESCALATE') {
+  console.log('Needs human approval:', result.reasoning);
+} else {
+  console.log('Blocked:', result.reasoning);
+}
+```
 
-## API Reference
+---
 
-### Initialization
+## Usage examples
+
+### Creating and managing agents
 
 ```typescript
-const client = new Cognigate({
-  apiKey: 'your-api-key',      // Required
-  baseUrl: 'https://...',       // Optional: custom API URL
-  timeout: 30000,               // Optional: request timeout in ms
-  retries: 3,                   // Optional: number of retries
-  debug: false,                 // Optional: enable debug logging
-  webhookSecret: 'secret',      // Optional: for webhook verification
-});
-```
+import { Cognigate } from '@vorionsys/cognigate';
 
-### Agents
+const client = new Cognigate({ apiKey: process.env.COGNIGATE_API_KEY! });
 
-```typescript
-// List agents
+// List all active agents
 const agents = await client.agents.list({ status: 'ACTIVE' });
+console.log(`Found ${agents.total} active agents`);
 
-// Get agent
+// Get a specific agent
 const agent = await client.agents.get('agent-123');
 
-// Create agent
+// Create an agent
 const newAgent = await client.agents.create({
   name: 'DataProcessor',
   description: 'Processes data pipelines',
   template: 'data-processor',
+  initialCapabilities: ['read_database'],
 });
 
-// Update agent
-await client.agents.update('agent-123', { name: 'New Name' });
+// Update an agent
+await client.agents.update('agent-123', { name: 'RenamedAgent' });
 
-// Pause/Resume
+// Pause / Resume
 await client.agents.pause('agent-123');
 await client.agents.resume('agent-123');
 
-// Delete agent
+// Delete an agent
 await client.agents.delete('agent-123');
 ```
 
-### Trust
+### Querying trust status and history
 
 ```typescript
-// Get trust status
+// Get current trust status
 const status = await client.trust.getStatus('agent-123');
-// Returns: { trustScore, trustTier, tierName, capabilities, factorScores, ... }
+// Returns: { trustScore, trustTier, tierName, capabilities, factorScores, compliant, warnings, ... }
 
-// Get trust history
+// Get trust history over a time range
 const history = await client.trust.getHistory('agent-123', {
-  from: new Date('2024-01-01'),
+  from: new Date('2026-01-01'),
   limit: 100,
 });
 
-// Submit outcome (updates trust score)
+// Submit an outcome to update the trust score
 const updated = await client.trust.submitOutcome('agent-123', 'proof-456', {
   success: true,
   metrics: { latency: 234, accuracy: 0.98 },
+  notes: 'Completed ETL run without errors',
 });
 ```
 
-### Governance
+### Submitting governance requests and checking decisions
 
 ```typescript
-// Parse intent
+// Option A: Parse intent, then enforce separately
 const parsed = await client.governance.parseIntent(
   'agent-123',
   'Read customer data from the sales database'
 );
+console.log(`Parsed action: ${parsed.intent.parsedAction}`);
+console.log(`Risk level: ${parsed.intent.riskLevel}`);
+console.log(`Confidence: ${parsed.confidence}`);
 
-// Enforce governance
 const result = await client.governance.enforce(parsed.intent);
-// Returns: { decision, trustScore, grantedCapabilities, reasoning, proofId }
+// result.decision is 'ALLOW' | 'DENY' | 'ESCALATE' | 'DEGRADE'
 
-// Combined: parse + enforce
-const { intent, result } = await client.governance.evaluate(
+// Option B: Combined parse + enforce in one call
+const { intent, result: govResult } = await client.governance.evaluate(
   'agent-123',
   'Send email to customer'
 );
 
-if (result.decision === 'ALLOW') {
-  // Proceed with action
-} else if (result.decision === 'ESCALATE') {
+if (govResult.decision === 'ALLOW') {
+  // Proceed -- action is permitted
+} else if (govResult.decision === 'ESCALATE') {
   // Request human approval
+} else if (govResult.decision === 'DEGRADE') {
+  // Partial access: check govResult.grantedCapabilities
 } else {
-  // Action denied
-  console.log(result.reasoning);
+  // DENY
+  console.log('Denied:', govResult.reasoning);
 }
 
-// Check capability without creating proof
+// Quick capability check (no proof record created)
 const check = await client.governance.canPerform(
   'agent-123',
   'write_file',
   ['file_write', 'approved_directories']
 );
+console.log(check.allowed, check.reason);
 ```
 
-### Proofs
+### Querying the proof chain
 
 ```typescript
-// Get proof record
+// Get a specific proof record
 const proof = await client.proofs.get('proof-123');
 
-// List proofs for entity
+// List proofs for an entity
 const proofs = await client.proofs.list('agent-123', {
-  from: new Date('2024-01-01'),
+  from: new Date('2026-01-01'),
   outcome: 'SUCCESS',
+  pageSize: 50,
 });
 
 // Get chain statistics
 const stats = await client.proofs.getStats('agent-123');
 // Returns: { totalRecords, successRate, averageTrustScore, chainIntegrity }
 
-// Verify chain integrity
+// Verify proof chain integrity (hash-chain validation)
 const verification = await client.proofs.verify('agent-123');
+console.log('Chain valid:', verification.valid);
+if (verification.errors.length > 0) {
+  console.error('Integrity errors:', verification.errors);
+}
 ```
 
-### Webhooks
+### Handling webhooks
 
 ```typescript
 import { WebhookRouter, parseWebhookPayload } from '@vorionsys/cognigate';
 
 const router = new WebhookRouter();
 
-// Handle specific events
+// Handle specific event types
 router.on('trust.tier_changed', async (event) => {
   console.log(`Agent ${event.entityId} tier changed:`, event.payload);
 });
 
 router.on('governance.decision', async (event) => {
   if (event.payload.decision === 'ESCALATE') {
-    // Alert human reviewer
+    // Alert a human reviewer
   }
 });
 
-// Handle all events
+// Handle all events (logging, analytics, etc.)
 router.onAll(async (event) => {
   await logEvent(event);
 });
 
-// Express middleware
-app.post('/webhooks/cognigate', router.middleware(process.env.WEBHOOK_SECRET));
+// Express middleware (signature verification included)
+app.post('/webhooks/cognigate', router.middleware(process.env.WEBHOOK_SECRET!));
 
-// Or manual verification
+// Or verify manually
 app.post('/webhooks/cognigate', async (req, res) => {
   try {
     const event = await parseWebhookPayload(
       req.body,
-      req.headers['x-cognigate-signature'],
-      process.env.WEBHOOK_SECRET
+      req.headers['x-cognigate-signature'] as string,
+      process.env.WEBHOOK_SECRET!
     );
     await router.handle(event);
     res.json({ received: true });
   } catch (error) {
-    res.status(400).json({ error: error.message });
+    res.status(400).json({ error: (error as Error).message });
   }
 });
 ```
 
-### Trust Tiers
+### Proof Bridge (Proof Plane integration)
+
+The proof bridge forwards Cognigate `governance.decision` webhook events to the Vorion Proof Plane, creating cross-system `DECISION_MADE` audit records.
+
+```typescript
+import { WebhookRouter } from '@vorionsys/cognigate';
+import { createProofBridge } from '@vorionsys/cognigate/proof-bridge';
+import { ProofPlane, memoryStore } from '@vorionsys/proof-plane';
+
+const router = new WebhookRouter();
+const proofPlane = new ProofPlane({ storage: memoryStore() });
+
+const bridge = createProofBridge({
+  proofPlane,
+  webhookRouter: router,
+});
+
+// governance.decision events now automatically emit DECISION_MADE proofs
+
+// Later, disconnect the bridge:
+bridge.disconnect();
+```
+
+### Trust tiers (BASIS specification)
 
 ```typescript
 import { Cognigate, TrustTier, TIER_THRESHOLDS } from '@vorionsys/cognigate';
 
-// Get tier from score
+// Derive tier from score
 const tier = Cognigate.getTierFromScore(750);
 // Returns: TrustTier.T4_STANDARD
 
-// Get tier name
+// Get human-readable tier name
 const name = Cognigate.getTierName(TrustTier.T5_TRUSTED);
 // Returns: "Trusted"
 
-// Get tier thresholds
+// Get score thresholds for a tier
 const thresholds = Cognigate.getTierThresholds(TrustTier.T4_STANDARD);
 // Returns: { min: 650, max: 799, name: "Standard" }
-
-// All tiers (BASIS specification)
-console.log(TIER_THRESHOLDS);
-// T0_SANDBOX:     0-199    Sandbox     - Isolated, no external access
-// T1_OBSERVED:    200-349  Observed    - Read-only, monitored
-// T2_PROVISIONAL: 350-500  Provisional - Basic operations, supervised
-// T3_MONITORED:   501-649  Monitored   - Standard operations with monitoring
-// T4_STANDARD:    650-799  Standard    - External API access, policy-governed
-// T5_TRUSTED:     800-875  Trusted     - Cross-agent communication
-// T6_CERTIFIED:   876-950  Certified   - Admin tasks, minimal oversight
-// T7_AUTONOMOUS:  951-1000 Autonomous  - Full autonomy, self-governance
 ```
 
-## Error Handling
+The eight BASIS trust tiers:
+
+| Tier | Score range | Name | Description |
+|---|---|---|---|
+| T0 | 0--199 | Sandbox | Isolated, no external access |
+| T1 | 200--349 | Observed | Read-only, monitored |
+| T2 | 350--499 | Provisional | Basic operations, supervised |
+| T3 | 500--649 | Monitored | Standard operations with monitoring |
+| T4 | 650--799 | Standard | External API access, policy-governed |
+| T5 | 800--875 | Trusted | Cross-agent communication |
+| T6 | 876--950 | Certified | Admin tasks, minimal oversight |
+| T7 | 951--1000 | Autonomous | Full autonomy, self-governance |
+
+### Error handling
 
 ```typescript
 import { Cognigate, CognigateError } from '@vorionsys/cognigate';
@@ -230,41 +298,163 @@ try {
   const status = await client.trust.getStatus('invalid-id');
 } catch (error) {
   if (error instanceof CognigateError) {
-    console.log('Code:', error.code);
-    console.log('Message:', error.message);
-    console.log('Status:', error.status);
-    console.log('Details:', error.details);
+    console.log('Code:', error.code);       // e.g. 'NOT_FOUND'
+    console.log('Message:', error.message);  // e.g. 'Entity not found'
+    console.log('Status:', error.status);    // e.g. 404
+    console.log('Details:', error.details);  // additional context
   }
 }
 ```
 
-## TypeScript Types
-
-All types are exported and can be imported:
+The client automatically retries server errors (5xx) with exponential backoff. Client errors (4xx) are thrown immediately.
+
+---
+
+## API reference
+
+### Main export: `@vorionsys/cognigate`
+
+#### Classes
+
+| Export | Description |
+|---|---|
+| `Cognigate` | Main SDK client. Instantiate with `CognigateConfig` to access all sub-clients. |
+| `CognigateError` | Error class with `code`, `status`, and `details` properties. |
+| `WebhookRouter` | Event router for Cognigate webhooks with Express middleware support. |
+
+#### Sub-clients (accessed via `Cognigate` instance)
+
+| Property | Type | Description |
+|---|---|---|
+| `client.agents` | `AgentsClient` | CRUD operations for agents: `list`, `get`, `create`, `update`, `delete`, `pause`, `resume`. |
+| `client.trust` | `TrustClient` | Trust score queries: `getStatus`, `getHistory`, `submitOutcome`. |
+| `client.governance` | `GovernanceClient` | Governance enforcement: `parseIntent`, `enforce`, `evaluate`, `canPerform`. |
+| `client.proofs` | `ProofsClient` | Proof chain access: `get`, `list`, `getStats`, `verify`. |
+
+#### Static methods on `Cognigate`
+
+| Method | Description |
+|---|---|
+| `Cognigate.getTierFromScore(score)` | Convert a 0--1000 score to a `TrustTier` enum value. |
+| `Cognigate.getTierName(tier)` | Get the human-readable name of a tier. |
+| `Cognigate.getTierThresholds(tier)` | Get `{ min, max, name }` for a tier. |
+
+#### Enums and constants
+
+| Export | Description |
+|---|---|
+| `TrustTier` | Enum: `T0_SANDBOX` through `T7_AUTONOMOUS`. |
+| `TIER_THRESHOLDS` | Mapping from `TrustTier` to `{ min, max, name }`. |
+
+#### Types
+
+| Type | Description |
+|---|---|
+| `CognigateConfig` | Client configuration: `apiKey`, `baseUrl?`, `timeout?`, `retries?`, `debug?`, `webhookSecret?`. |
+| `Agent` | Registered agent record. |
+| `CreateAgentRequest` | Payload for creating an agent. |
+| `UpdateAgentRequest` | Payload for updating an agent. |
+| `TrustStatus` | Trust score, tier, capabilities, factor scores, compliance status. |
+| `GovernanceDecision` | Union: `'ALLOW' \| 'DENY' \| 'ESCALATE' \| 'DEGRADE'`. |
+| `GovernanceResult` | Full decision result with reasoning, capabilities, constraints, and proof ID. |
+| `Intent` | Structured representation of a parsed action request. |
+| `IntentParseResult` | Parse result with confidence score and alternative interpretations. |
+| `ProofRecord` | Immutable hash-chained audit record for a single decision. |
+| `ProofChainStats` | Aggregate stats: total records, success rate, average score, chain integrity. |
+| `WebhookEvent` | Webhook payload with type, entity ID, and signature. |
+| `WebhookEventType` | Union of all supported event types (e.g. `'trust.tier_changed'`). |
+| `ApiResponse<T>` | Standard API response wrapper. |
+| `ApiError` | API error structure. |
+| `PaginatedResponse<T>` | Paginated list with `items`, `total`, `page`, `pageSize`, `hasMore`. |
+| `AgentsClient` | Type of the agents sub-client. |
+| `TrustClient` | Type of the trust sub-client. |
+| `GovernanceClient` | Type of the governance sub-client. |
+| `ProofsClient` | Type of the proofs sub-client. |
+
+#### Zod schemas (runtime validation)
+
+| Export | Validates |
+|---|---|
+| `TrustStatusSchema` | `TrustStatus` objects |
+| `GovernanceResultSchema` | `GovernanceResult` objects |
+| `ProofRecordSchema` | `ProofRecord` objects |
+| `AgentSchema` | `Agent` objects |
+
+#### Webhook utilities
+
+| Export | Description |
+|---|---|
+| `verifyWebhookSignature(payload, signature, secret)` | HMAC-SHA256 signature verification with timing-safe comparison. |
+| `parseWebhookPayload(body, signature, secret)` | Verify signature and parse the webhook body into a `WebhookEvent`. |
+| `WebhookRouter` | Event router: `on(type, handler)`, `onAll(handler)`, `handle(event)`, `middleware(secret)`. |
+
+### Sub-export: `@vorionsys/cognigate/proof-bridge`
+
+| Export | Description |
+|---|---|
+| `createProofBridge(config)` | Create a bridge forwarding `governance.decision` webhooks to the Proof Plane. Returns a `ProofBridgeHandle`. |
+| `ProofPlaneEmitter` | Structural interface for Proof Plane integration (avoids hard dependency on `@vorionsys/proof-plane`). |
+| `ProofBridgeConfig` | Config: `{ proofPlane, webhookRouter }`. |
+| `ProofBridgeHandle` | Handle with `disconnect()` method to stop forwarding. |
+
+---
+
+## Webhook event types
+
+| Event type | Fired when |
+|---|---|
+| `agent.created` | A new agent is registered |
+| `agent.updated` | An agent's configuration changes |
+| `agent.deleted` | An agent is deleted |
+| `agent.status_changed` | An agent's status changes (active/paused/suspended) |
+| `trust.score_changed` | An agent's trust score is updated |
+| `trust.tier_changed` | An agent's trust tier changes |
+| `governance.decision` | A governance decision is rendered |
+| `proof.recorded` | A proof record is committed to the chain |
+| `alert.triggered` | A system or compliance alert fires |
+
+---
+
+## Configuration reference
 
 ```typescript
-import type {
-  Agent,
-  TrustStatus,
-  GovernanceResult,
-  Intent,
-  ProofRecord,
-  WebhookEvent,
-  TrustTier,
-  GovernanceDecision,
-} from '@vorionsys/cognigate';
+interface CognigateConfig {
+  /** API key (required). */
+  apiKey: string;
+  /** Base URL for the Cognigate API. Default: https://cognigate.dev/v1 */
+  baseUrl?: string;
+  /** Request timeout in milliseconds. Default: 30000 */
+  timeout?: number;
+  /** Number of retries for server errors. Default: 3 */
+  retries?: number;
+  /** Enable debug logging. Default: false */
+  debug?: boolean;
+  /** Webhook signing secret for signature verification. */
+  webhookSecret?: string;
+}
 ```
 
-## Runtime Validation
+---
 
-Zod schemas are exported for runtime validation:
+## Requirements
 
-```typescript
-import { TrustStatusSchema, AgentSchema } from '@vorionsys/cognigate';
+- Node.js >= 18.0.0
+- TypeScript >= 5.0.0 (peer dependency)
 
-const validatedStatus = TrustStatusSchema.parse(untrustedData);
-```
+---
 
 ## License
 
-MIT
+[Apache-2.0](./LICENSE)
+
+---
+
+## Contributing
+
+This package is part of the [Vorion monorepo](https://github.com/vorionsys/vorion). See the root `CONTRIBUTING.md` for guidelines.
+
+## Links
+
+- [Cognigate API Documentation](https://cognigate.dev)
+- [Vorion Monorepo](https://github.com/vorionsys/vorion)
+- [npm: @vorionsys/cognigate](https://www.npmjs.com/package/@vorionsys/cognigate)

package/dist/chunk-OIPPFRDP.js

@@ -0,0 +1,35 @@
+// src/proof-bridge.ts
+function createProofBridge(config) {
+  const { proofPlane, webhookRouter } = config;
+  let connected = true;
+  const handler = async (event) => {
+    if (!connected) return;
+    const payload = event.payload;
+    const now = /* @__PURE__ */ new Date();
+    const decision = {
+      decisionId: payload.decisionId ?? event.id,
+      intentId: payload.intentId ?? "",
+      agentId: payload.agentId ?? event.entityId,
+      correlationId: payload.correlationId ?? event.id,
+      permitted: payload.permitted ?? payload.decision === "ALLOW",
+      trustBand: payload.trustBand ?? 4,
+      trustScore: payload.trustScore ?? 0,
+      reasoning: Array.isArray(payload.reasoning) ? payload.reasoning : typeof payload.reasoning === "string" ? [payload.reasoning] : [],
+      decidedAt: payload.decidedAt ? new Date(payload.decidedAt) : now,
+      expiresAt: payload.expiresAt ? new Date(payload.expiresAt) : new Date(now.getTime() + 24 * 60 * 60 * 1e3),
+      latencyMs: payload.latencyMs ?? 0,
+      version: payload.version ?? 1
+    };
+    await proofPlane.logDecisionMade(decision, decision.correlationId);
+  };
+  webhookRouter.on("governance.decision", handler);
+  return {
+    disconnect: () => {
+      connected = false;
+    }
+  };
+}
+
+export {
+  createProofBridge
+};