@vorionsys/cognigate 1.0.0

package/src/types.ts

@@ -0,0 +1,272 @@
+/**
+ * Cognigate TypeScript SDK - Type Definitions
+ *
+ * Core types for the Cognigate AI governance API
+ */
+
+import { z } from 'zod';
+
+// =============================================================================
+// TRUST TIERS (BASIS Framework)
+// =============================================================================
+
+export enum TrustTier {
+  T0_SANDBOX = 0,
+  T1_OBSERVED = 1,
+  T2_PROVISIONAL = 2,
+  T3_VERIFIED = 3,
+  T4_OPERATIONAL = 4,
+  T5_TRUSTED = 5,
+  T6_CERTIFIED = 6,
+  T7_AUTONOMOUS = 7,
+}
+
+export const TIER_THRESHOLDS: Record<TrustTier, { min: number; max: number; name: string }> = {
+  [TrustTier.T0_SANDBOX]: { min: 0, max: 199, name: 'Sandbox' },
+  [TrustTier.T1_OBSERVED]: { min: 200, max: 349, name: 'Observed' },
+  [TrustTier.T2_PROVISIONAL]: { min: 350, max: 499, name: 'Provisional' },
+  [TrustTier.T3_VERIFIED]: { min: 500, max: 649, name: 'Verified' },
+  [TrustTier.T4_OPERATIONAL]: { min: 650, max: 799, name: 'Operational' },
+  [TrustTier.T5_TRUSTED]: { min: 800, max: 875, name: 'Trusted' },
+  [TrustTier.T6_CERTIFIED]: { min: 876, max: 949, name: 'Certified' },
+  [TrustTier.T7_AUTONOMOUS]: { min: 950, max: 1000, name: 'Autonomous' },
+};
+
+// =============================================================================
+// GOVERNANCE DECISIONS
+// =============================================================================
+
+export type GovernanceDecision = 'ALLOW' | 'DENY' | 'ESCALATE' | 'DEGRADE';
+
+export interface GovernanceResult {
+  decision: GovernanceDecision;
+  trustScore: number;
+  trustTier: TrustTier;
+  grantedCapabilities: string[];
+  deniedCapabilities: string[];
+  reasoning: string;
+  constraints?: Record<string, unknown>;
+  proofId?: string;
+  timestamp: Date;
+}
+
+// =============================================================================
+// INTENT PARSING
+// =============================================================================
+
+export interface Intent {
+  id: string;
+  entityId: string;
+  rawInput: string;
+  parsedAction: string;
+  parameters: Record<string, unknown>;
+  riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+  requiredCapabilities: string[];
+  timestamp: Date;
+}
+
+export interface IntentParseResult {
+  intent: Intent;
+  confidence: number;
+  alternativeInterpretations?: Intent[];
+}
+
+// =============================================================================
+// TRUST STATUS
+// =============================================================================
+
+export interface TrustStatus {
+  entityId: string;
+  trustScore: number;
+  trustTier: TrustTier;
+  tierName: string;
+  capabilities: string[];
+  factorScores: Record<string, number>;
+  lastEvaluated: Date;
+  compliant: boolean;
+  warnings: string[];
+}
+
+// =============================================================================
+// PROOF RECORDS (Immutable Audit Trail)
+// =============================================================================
+
+export interface ProofRecord {
+  id: string;
+  entityId: string;
+  intentId: string;
+  decision: GovernanceDecision;
+  action: string;
+  outcome: 'SUCCESS' | 'FAILURE' | 'PARTIAL' | 'PENDING';
+  trustScoreBefore: number;
+  trustScoreAfter: number;
+  timestamp: Date;
+  hash: string;
+  previousHash: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ProofChainStats {
+  totalRecords: number;
+  successRate: number;
+  averageTrustScore: number;
+  chainIntegrity: boolean;
+  lastVerified: Date;
+}
+
+// =============================================================================
+// AGENTS
+// =============================================================================
+
+export interface Agent {
+  id: string;
+  name: string;
+  description: string;
+  ownerId: string;
+  trustScore: number;
+  trustTier: TrustTier;
+  status: 'ACTIVE' | 'PAUSED' | 'SUSPENDED' | 'TERMINATED';
+  capabilities: string[];
+  executions: number;
+  successRate: number;
+  createdAt: Date;
+  updatedAt: Date;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CreateAgentRequest {
+  name: string;
+  description?: string;
+  template?: string;
+  initialCapabilities?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface UpdateAgentRequest {
+  name?: string;
+  description?: string;
+  status?: 'ACTIVE' | 'PAUSED';
+  metadata?: Record<string, unknown>;
+}
+
+// =============================================================================
+// API RESPONSES
+// =============================================================================
+
+export interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: ApiError;
+  requestId: string;
+  timestamp: Date;
+}
+
+export interface ApiError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export interface PaginatedResponse<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  hasMore: boolean;
+}
+
+// =============================================================================
+// WEBHOOKS
+// =============================================================================
+
+export interface WebhookEvent {
+  id: string;
+  type: WebhookEventType;
+  entityId: string;
+  payload: Record<string, unknown>;
+  timestamp: Date;
+  signature: string;
+}
+
+export type WebhookEventType =
+  | 'agent.created'
+  | 'agent.updated'
+  | 'agent.deleted'
+  | 'agent.status_changed'
+  | 'trust.score_changed'
+  | 'trust.tier_changed'
+  | 'governance.decision'
+  | 'proof.recorded'
+  | 'alert.triggered';
+
+// =============================================================================
+// CONFIGURATION
+// =============================================================================
+
+export interface CognigateConfig {
+  apiKey: string;
+  baseUrl?: string;
+  timeout?: number;
+  retries?: number;
+  debug?: boolean;
+  webhookSecret?: string;
+}
+
+// =============================================================================
+// ZOD SCHEMAS (for runtime validation)
+// =============================================================================
+
+export const TrustStatusSchema = z.object({
+  entityId: z.string(),
+  trustScore: z.number().min(0).max(1000),
+  trustTier: z.nativeEnum(TrustTier),
+  tierName: z.string(),
+  capabilities: z.array(z.string()),
+  factorScores: z.record(z.string(), z.number()),
+  lastEvaluated: z.coerce.date(),
+  compliant: z.boolean(),
+  warnings: z.array(z.string()),
+});
+
+export const GovernanceResultSchema = z.object({
+  decision: z.enum(['ALLOW', 'DENY', 'ESCALATE', 'DEGRADE']),
+  trustScore: z.number(),
+  trustTier: z.nativeEnum(TrustTier),
+  grantedCapabilities: z.array(z.string()),
+  deniedCapabilities: z.array(z.string()),
+  reasoning: z.string(),
+  constraints: z.record(z.string(), z.unknown()).optional(),
+  proofId: z.string().optional(),
+  timestamp: z.coerce.date(),
+});
+
+export const ProofRecordSchema = z.object({
+  id: z.string(),
+  entityId: z.string(),
+  intentId: z.string(),
+  decision: z.enum(['ALLOW', 'DENY', 'ESCALATE', 'DEGRADE']),
+  action: z.string(),
+  outcome: z.enum(['SUCCESS', 'FAILURE', 'PARTIAL', 'PENDING']),
+  trustScoreBefore: z.number(),
+  trustScoreAfter: z.number(),
+  timestamp: z.coerce.date(),
+  hash: z.string(),
+  previousHash: z.string(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const AgentSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  ownerId: z.string(),
+  trustScore: z.number(),
+  trustTier: z.nativeEnum(TrustTier),
+  status: z.enum(['ACTIVE', 'PAUSED', 'SUSPENDED', 'TERMINATED']),
+  capabilities: z.array(z.string()),
+  executions: z.number(),
+  successRate: z.number(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});

package/src/webhooks.ts

@@ -0,0 +1,146 @@
+/**
+ * Cognigate TypeScript SDK - Webhook Utilities
+ *
+ * Helpers for handling Cognigate webhooks
+ */
+
+import { WebhookEvent, WebhookEventType } from './types.js';
+
+/**
+ * Verify webhook signature
+ */
+export async function verifyWebhookSignature(
+  payload: string,
+  signature: string,
+  secret: string
+): Promise<boolean> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(payload);
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign']
+  );
+
+  const signatureBuffer = await crypto.subtle.sign('HMAC', key, data);
+  const expectedSignature = bufferToHex(signatureBuffer);
+
+  return timingSafeEqual(signature, expectedSignature);
+}
+
+/**
+ * Parse and validate a webhook payload
+ */
+export function parseWebhookPayload(
+  body: string,
+  signature: string,
+  secret: string
+): Promise<WebhookEvent> {
+  return new Promise(async (resolve, reject) => {
+    const isValid = await verifyWebhookSignature(body, signature, secret);
+
+    if (!isValid) {
+      reject(new Error('Invalid webhook signature'));
+      return;
+    }
+
+    try {
+      const event = JSON.parse(body) as WebhookEvent;
+      event.timestamp = new Date(event.timestamp);
+      resolve(event);
+    } catch (error) {
+      reject(new Error('Invalid webhook payload'));
+    }
+  });
+}
+
+/**
+ * Webhook handler type
+ */
+export type WebhookHandler<T extends WebhookEventType = WebhookEventType> = (
+  event: WebhookEvent & { type: T }
+) => void | Promise<void>;
+
+/**
+ * Webhook router for handling different event types
+ */
+export class WebhookRouter {
+  private handlers: Map<WebhookEventType | '*', WebhookHandler[]> = new Map();
+
+  /**
+   * Register a handler for a specific event type
+   */
+  on<T extends WebhookEventType>(type: T, handler: WebhookHandler<T>): this {
+    const existing = this.handlers.get(type) || [];
+    existing.push(handler as WebhookHandler);
+    this.handlers.set(type, existing);
+    return this;
+  }
+
+  /**
+   * Register a handler for all events
+   */
+  onAll(handler: WebhookHandler): this {
+    const existing = this.handlers.get('*') || [];
+    existing.push(handler);
+    this.handlers.set('*', existing);
+    return this;
+  }
+
+  /**
+   * Handle a webhook event
+   */
+  async handle(event: WebhookEvent): Promise<void> {
+    const typeHandlers = this.handlers.get(event.type) || [];
+    const allHandlers = this.handlers.get('*') || [];
+
+    const handlers = [...typeHandlers, ...allHandlers];
+
+    for (const handler of handlers) {
+      await handler(event);
+    }
+  }
+
+  /**
+   * Create an Express/Connect compatible middleware
+   */
+  middleware(secret: string) {
+    return async (req: any, res: any, _next?: () => void) => {
+      try {
+        const signature = req.headers['x-cognigate-signature'];
+        const body = typeof req.body === 'string' ? req.body : JSON.stringify(req.body);
+
+        const event = await parseWebhookPayload(body, signature, secret);
+        await this.handle(event);
+
+        res.status(200).json({ received: true });
+      } catch (error) {
+        res.status(400).json({ error: (error as Error).message });
+      }
+    };
+  }
+}
+
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+
+function bufferToHex(buffer: ArrayBuffer): string {
+  return Array.from(new Uint8Array(buffer))
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['**/*.test.ts', '**/index.ts'],
+    },
+  },
+});