@vorionsys/cognigate 1.0.0 → 1.0.2

package/dist/proof-bridge-CkzbawwC.d.cts

@@ -0,0 +1,394 @@
+import { z } from 'zod';
+import { TrustTier } from '@vorionsys/shared-constants';
+
+/**
+ * Cognigate TypeScript SDK - Type Definitions
+ *
+ * Core types for the Cognigate AI governance API
+ */
+
+type GovernanceDecision = 'ALLOW' | 'DENY' | 'ESCALATE' | 'DEGRADE';
+interface GovernanceResult {
+    decision: GovernanceDecision;
+    trustScore: number;
+    trustTier: TrustTier;
+    grantedCapabilities: string[];
+    deniedCapabilities: string[];
+    reasoning: string;
+    constraints?: Record<string, unknown>;
+    proofId?: string;
+    timestamp: Date;
+}
+interface Intent {
+    id: string;
+    entityId: string;
+    rawInput: string;
+    parsedAction: string;
+    parameters: Record<string, unknown>;
+    riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+    requiredCapabilities: string[];
+    timestamp: Date;
+}
+interface IntentParseResult {
+    intent: Intent;
+    confidence: number;
+    alternativeInterpretations?: Intent[];
+}
+interface TrustStatus {
+    entityId: string;
+    trustScore: number;
+    trustTier: TrustTier;
+    tierName: string;
+    capabilities: string[];
+    factorScores: Record<string, number>;
+    lastEvaluated: Date;
+    compliant: boolean;
+    warnings: string[];
+}
+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>;
+}
+interface ProofChainStats {
+    totalRecords: number;
+    successRate: number;
+    averageTrustScore: number;
+    chainIntegrity: boolean;
+    lastVerified: Date;
+}
+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>;
+}
+interface CreateAgentRequest {
+    name: string;
+    description?: string;
+    template?: string;
+    initialCapabilities?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface UpdateAgentRequest {
+    name?: string;
+    description?: string;
+    status?: 'ACTIVE' | 'PAUSED';
+    metadata?: Record<string, unknown>;
+}
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: ApiError;
+    requestId: string;
+    timestamp: Date;
+}
+interface ApiError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    hasMore: boolean;
+}
+interface WebhookEvent {
+    id: string;
+    type: WebhookEventType;
+    entityId: string;
+    payload: Record<string, unknown>;
+    timestamp: Date;
+    signature: string;
+}
+type WebhookEventType = 'agent.created' | 'agent.updated' | 'agent.deleted' | 'agent.status_changed' | 'trust.score_changed' | 'trust.tier_changed' | 'governance.decision' | 'proof.recorded' | 'alert.triggered';
+interface CognigateConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    retries?: number;
+    debug?: boolean;
+    webhookSecret?: string;
+}
+declare const TrustStatusSchema: z.ZodObject<{
+    entityId: z.ZodString;
+    trustScore: z.ZodNumber;
+    trustTier: z.ZodNativeEnum<typeof TrustTier>;
+    tierName: z.ZodString;
+    capabilities: z.ZodArray<z.ZodString, "many">;
+    factorScores: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    lastEvaluated: z.ZodDate;
+    compliant: z.ZodBoolean;
+    warnings: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    trustScore: number;
+    entityId: string;
+    trustTier: TrustTier;
+    tierName: string;
+    capabilities: string[];
+    factorScores: Record<string, number>;
+    lastEvaluated: Date;
+    compliant: boolean;
+    warnings: string[];
+}, {
+    trustScore: number;
+    entityId: string;
+    trustTier: TrustTier;
+    tierName: string;
+    capabilities: string[];
+    factorScores: Record<string, number>;
+    lastEvaluated: Date;
+    compliant: boolean;
+    warnings: string[];
+}>;
+declare const GovernanceResultSchema: z.ZodObject<{
+    decision: z.ZodEnum<["ALLOW", "DENY", "ESCALATE", "DEGRADE"]>;
+    trustScore: z.ZodNumber;
+    trustTier: z.ZodNativeEnum<typeof TrustTier>;
+    grantedCapabilities: z.ZodArray<z.ZodString, "many">;
+    deniedCapabilities: z.ZodArray<z.ZodString, "many">;
+    reasoning: z.ZodString;
+    constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    proofId: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodDate;
+}, "strip", z.ZodTypeAny, {
+    decision: "ALLOW" | "DENY" | "ESCALATE" | "DEGRADE";
+    trustScore: number;
+    reasoning: string;
+    trustTier: TrustTier;
+    grantedCapabilities: string[];
+    deniedCapabilities: string[];
+    timestamp: Date;
+    constraints?: Record<string, unknown> | undefined;
+    proofId?: string | undefined;
+}, {
+    decision: "ALLOW" | "DENY" | "ESCALATE" | "DEGRADE";
+    trustScore: number;
+    reasoning: string;
+    trustTier: TrustTier;
+    grantedCapabilities: string[];
+    deniedCapabilities: string[];
+    timestamp: Date;
+    constraints?: Record<string, unknown> | undefined;
+    proofId?: string | undefined;
+}>;
+declare const ProofRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    entityId: z.ZodString;
+    intentId: z.ZodString;
+    decision: z.ZodEnum<["ALLOW", "DENY", "ESCALATE", "DEGRADE"]>;
+    action: z.ZodString;
+    outcome: z.ZodEnum<["SUCCESS", "FAILURE", "PARTIAL", "PENDING"]>;
+    trustScoreBefore: z.ZodNumber;
+    trustScoreAfter: z.ZodNumber;
+    timestamp: z.ZodDate;
+    hash: z.ZodString;
+    previousHash: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    intentId: string;
+    decision: "ALLOW" | "DENY" | "ESCALATE" | "DEGRADE";
+    entityId: string;
+    timestamp: Date;
+    id: string;
+    action: string;
+    outcome: "SUCCESS" | "FAILURE" | "PARTIAL" | "PENDING";
+    trustScoreBefore: number;
+    trustScoreAfter: number;
+    hash: string;
+    previousHash: string;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    intentId: string;
+    decision: "ALLOW" | "DENY" | "ESCALATE" | "DEGRADE";
+    entityId: string;
+    timestamp: Date;
+    id: string;
+    action: string;
+    outcome: "SUCCESS" | "FAILURE" | "PARTIAL" | "PENDING";
+    trustScoreBefore: number;
+    trustScoreAfter: number;
+    hash: string;
+    previousHash: string;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+declare const AgentSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    ownerId: z.ZodString;
+    trustScore: z.ZodNumber;
+    trustTier: z.ZodNativeEnum<typeof TrustTier>;
+    status: z.ZodEnum<["ACTIVE", "PAUSED", "SUSPENDED", "TERMINATED"]>;
+    capabilities: z.ZodArray<z.ZodString, "many">;
+    executions: z.ZodNumber;
+    successRate: z.ZodNumber;
+    createdAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    trustScore: number;
+    trustTier: TrustTier;
+    status: "ACTIVE" | "PAUSED" | "SUSPENDED" | "TERMINATED";
+    capabilities: string[];
+    id: string;
+    name: string;
+    description: string;
+    ownerId: string;
+    executions: number;
+    successRate: number;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    trustScore: number;
+    trustTier: TrustTier;
+    status: "ACTIVE" | "PAUSED" | "SUSPENDED" | "TERMINATED";
+    capabilities: string[];
+    id: string;
+    name: string;
+    description: string;
+    ownerId: string;
+    executions: number;
+    successRate: number;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+
+/**
+ * Cognigate TypeScript SDK - Webhook Utilities
+ *
+ * Helpers for handling Cognigate webhooks
+ */
+
+/**
+ * Verify webhook signature
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
+/**
+ * Parse and validate a webhook payload
+ */
+declare function parseWebhookPayload(body: string, signature: string, secret: string): Promise<WebhookEvent>;
+/**
+ * Webhook handler type
+ */
+type WebhookHandler<T extends WebhookEventType = WebhookEventType> = (event: WebhookEvent & {
+    type: T;
+}) => void | Promise<void>;
+/**
+ * Webhook router for handling different event types
+ */
+declare class WebhookRouter {
+    private handlers;
+    /**
+     * Register a handler for a specific event type
+     */
+    on<T extends WebhookEventType>(type: T, handler: WebhookHandler<T>): this;
+    /**
+     * Register a handler for all events
+     */
+    onAll(handler: WebhookHandler): this;
+    /**
+     * Handle a webhook event
+     */
+    handle(event: WebhookEvent): Promise<void>;
+    /**
+     * Create an Express/Connect compatible middleware
+     */
+    middleware(secret: string): (req: {
+        headers: Record<string, string>;
+        body: unknown;
+    }, res: {
+        status: (code: number) => {
+            json: (data: unknown) => void;
+        };
+    }) => Promise<void>;
+}
+
+/**
+ * Cognigate Proof Bridge
+ *
+ * Bridges Cognigate webhook events to the Proof Plane for immutable audit trails.
+ * Listens for `governance.decision` events and emits `DECISION_MADE` proof events.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Structural type for proof-plane integration (avoids hard dependency on @vorionsys/proof-plane)
+ */
+interface ProofPlaneEmitter {
+    logDecisionMade(decision: {
+        decisionId: string;
+        intentId: string;
+        agentId: string;
+        correlationId: string;
+        permitted: boolean;
+        trustBand: number;
+        trustScore: number;
+        reasoning: string[];
+        decidedAt: Date;
+        expiresAt: Date;
+        latencyMs: number;
+        version: number;
+    }, correlationId?: string): Promise<unknown>;
+}
+/**
+ * Configuration for the proof bridge
+ */
+interface ProofBridgeConfig {
+    /** Proof plane emitter instance */
+    proofPlane: ProofPlaneEmitter;
+    /** Webhook router to subscribe to */
+    webhookRouter: WebhookRouter;
+}
+/**
+ * Handle for disconnecting the proof bridge
+ */
+interface ProofBridgeHandle {
+    /** Disconnect the bridge (stops forwarding events) */
+    disconnect: () => void;
+}
+/**
+ * Create a proof bridge that forwards Cognigate governance.decision webhooks
+ * to the Proof Plane as DECISION_MADE events.
+ *
+ * @example
+ * ```typescript
+ * import { WebhookRouter } from '@vorionsys/cognigate';
+ * import { createProofBridge } from '@vorionsys/cognigate/proof-bridge';
+ * import { ProofPlane } 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
+ *
+ * bridge.disconnect(); // stop forwarding
+ * ```
+ */
+declare function createProofBridge(config: ProofBridgeConfig): ProofBridgeHandle;
+
+export { type Agent as A, type CognigateConfig as C, type GovernanceResult as G, type IntentParseResult as I, type ProofRecord as P, type TrustStatus as T, type UpdateAgentRequest as U, type WebhookEvent as W, type Intent as a, type PaginatedResponse as b, type ProofChainStats as c, type CreateAgentRequest as d, AgentSchema as e, type ApiError as f, type ApiResponse as g, type GovernanceDecision as h, GovernanceResultSchema as i, type ProofBridgeConfig as j, type ProofBridgeHandle as k, type ProofPlaneEmitter as l, ProofRecordSchema as m, TrustStatusSchema as n, type WebhookEventType as o, type WebhookHandler as p, WebhookRouter as q, createProofBridge as r, parseWebhookPayload as s, verifyWebhookSignature as v };