vix11 1.0.0

package/src/types.ts

@@ -0,0 +1,232 @@
+/**
+ * Vix11 SDK Type Definitions
+ *
+ * SDK-specific types for requests and responses when interacting
+ * with the Vix11 AI agent security platform API.
+ */
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+/** Error thrown by the Vix11 SDK on non-2xx responses. */
+export class Vix11Error extends Error {
+  /** HTTP status code returned by the API. */
+  public readonly status: number;
+  /** Raw response body (if available). */
+  public readonly body: unknown;
+
+  constructor(message: string, status: number, body?: unknown) {
+    super(message);
+    this.name = 'Vix11Error';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+
+/** Layer-level score returned by the detection pipeline. */
+export interface LayerScore {
+  id: string;
+  score: number;
+  reason: string;
+  durationMs: number;
+}
+
+/** Detection metadata returned by detect/shield endpoints. */
+export interface DetectionMeta {
+  action: 'allow' | 'throttle' | 'shadow-ban' | 'block';
+  score: number;
+  totalDurationMs: number;
+  trustScore?: number;
+  trustTier?: TrustTier;
+}
+
+/** Body sent to POST /v1/detect. */
+export interface DetectRequest {
+  agentId: string;
+  endpoint?: string;
+  payload?: string;
+  parameters?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+/** Response from POST /v1/detect. */
+export interface DetectResponse {
+  detection: {
+    action: 'allow' | 'throttle' | 'shadow-ban' | 'block';
+    score: number;
+    layers: LayerScore[];
+    totalDurationMs: number;
+    trustScore?: number;
+    trustTier?: TrustTier;
+  };
+}
+
+/** Body sent to POST /v1/shield. */
+export interface ShieldRequest {
+  agentId: string;
+  passport?: SignedPassport;
+  endpoint?: string;
+  payload?: string;
+  parameters?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+/** Response from POST /v1/shield. */
+export interface ShieldResponse {
+  status: 'allowed' | 'throttled' | 'blocked';
+  retryAfterMs?: number;
+  error?: string;
+  data?: Record<string, unknown>;
+  meta: DetectionMeta;
+}
+
+// ---------------------------------------------------------------------------
+// Passport
+// ---------------------------------------------------------------------------
+
+export interface PassportCapabilities {
+  maxTokensPerDay: number;
+  allowedEndpoints: string[];
+  maxRequestsPerMinute: number;
+}
+
+export interface PassportPayload {
+  passportId: string;
+  agentId: string;
+  ownerHash: string;
+  capabilities: PassportCapabilities;
+  issuedAt: number;
+  expiresAt: number;
+  version: 1;
+}
+
+export interface SignedPassport {
+  payload: PassportPayload;
+  signature: string;
+  publicKey: string;
+}
+
+// ---------------------------------------------------------------------------
+// Analytics
+// ---------------------------------------------------------------------------
+
+/** Response from GET /v1/analytics/summary. */
+export interface AnalyticsSummary {
+  from: number;
+  to: number;
+  totalRequests: number;
+  blockedRequests: number;
+  shadowBannedRequests: number;
+  distillationAttempts: number;
+  estimatedTokensSaved: number;
+  estimatedValueSaved: number;
+  topAgents: { agentId: string; attempts: number }[];
+  layerBreakdown: { layerId: string; avgScore: number; triggerCount: number }[];
+}
+
+/** Response from GET /v1/analytics/events. */
+export interface PaginatedEvents {
+  events: DistillationEvent[];
+  page: number;
+  limit: number;
+  total: number;
+}
+
+export interface DistillationEvent {
+  id: string;
+  timestamp: number;
+  agentId: string;
+  action: 'block' | 'shadow-ban' | 'throttle';
+  score: number;
+  semanticScore: number;
+  intentScore: number;
+  estimatedTokens: number;
+  estimatedValue: number;
+}
+
+// ---------------------------------------------------------------------------
+// Compliance
+// ---------------------------------------------------------------------------
+
+/** Response from GET /v1/compliance/report. */
+export interface ComplianceReport {
+  status: string;
+  generatedAt: string;
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Trust
+// ---------------------------------------------------------------------------
+
+/** Trust tier for an AI agent. */
+export type TrustTier = 'untrusted' | 'low' | 'medium' | 'high' | 'verified';
+
+/** Response from GET /v1/trust/:agentId. */
+export interface TrustScore {
+  agentId: string;
+  trustScore: number;
+  trustTier: TrustTier;
+  totalRequests: number;
+  decisions: {
+    allow: number;
+    throttle: number;
+    shadowBan: number;
+    block: number;
+  };
+  lastAction: string;
+  lastDetectionScore: number;
+  lastUpdated: string;
+  createdAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Health
+// ---------------------------------------------------------------------------
+
+/** KV probe result from health check. */
+export interface HealthCheck {
+  name: string;
+  status: 'pass' | 'fail';
+  durationMs: number;
+}
+
+/** Response from GET /v1/health. */
+export interface HealthResponse {
+  status: 'ok' | 'degraded';
+  service: string;
+  version: string;
+  timestamp: string;
+  environment: string;
+  pipeline: {
+    mode: string;
+    layers: number;
+  };
+  thresholds: {
+    throttle: number;
+    shadowBan: number;
+    block: number;
+  };
+  checks: Record<string, HealthCheck>;
+  totalDurationMs: number;
+}
+
+// ---------------------------------------------------------------------------
+// Detection Stats
+// ---------------------------------------------------------------------------
+
+/** Response from GET /v1/detection/stats. */
+export interface DetectionStats {
+  status: string;
+  layers: { id: string; status: string; version: string }[];
+  thresholds: {
+    throttle: number;
+    shadowBan: number;
+    block: number;
+  };
+}

package/tests/client.test.ts

@@ -0,0 +1,280 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Vix11Client } from '../src/client';
+import { Vix11Error } from '../src/types';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeClient(overrides: Record<string, unknown> = {}) {
+  return new Vix11Client({
+    baseUrl: 'https://vix11.test',
+    agentId: 'agent-1',
+    apiKey: 'sk-test',
+    timeout: 5000,
+    ...overrides,
+  });
+}
+
+function mockFetchResponse(body: unknown, status = 200) {
+  return vi.fn().mockResolvedValue({
+    ok: status >= 200 && status < 300,
+    status,
+    json: () => Promise.resolve(body),
+  });
+}
+
+const DETECT_RESPONSE = {
+  detection: {
+    action: 'allow' as const,
+    score: 0.12,
+    layers: [{ id: 'velocity', score: 0.1, reason: 'ok', durationMs: 1 }],
+    totalDurationMs: 2,
+  },
+};
+
+const SHIELD_RESPONSE = {
+  status: 'allowed' as const,
+  meta: { action: 'allow' as const, score: 0.05, totalDurationMs: 3 },
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Vix11Client', () => {
+  let originalFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  // ---- Construction -------------------------------------------------------
+
+  it('should construct with config', () => {
+    const client = makeClient();
+    expect(client).toBeInstanceOf(Vix11Client);
+  });
+
+  it('should strip trailing slash from baseUrl', async () => {
+    const fetchMock = mockFetchResponse({ status: 'ok' });
+    globalThis.fetch = fetchMock;
+
+    const client = makeClient({ baseUrl: 'https://vix11.test/' });
+    await client.health();
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const url = fetchMock.mock.calls[0][0] as string;
+    expect(url).toBe('https://vix11.test/v1/health');
+  });
+
+  // ---- Headers ------------------------------------------------------------
+
+  it('should include X-Vix11-Agent-Id header', async () => {
+    const fetchMock = mockFetchResponse({ status: 'ok' });
+    globalThis.fetch = fetchMock;
+
+    await makeClient().health();
+
+    const options = fetchMock.mock.calls[0][1] as RequestInit;
+    const headers = options.headers as Record<string, string>;
+    expect(headers['X-Vix11-Agent-Id']).toBe('agent-1');
+  });
+
+  it('should include Authorization header when apiKey is set', async () => {
+    const fetchMock = mockFetchResponse({ status: 'ok' });
+    globalThis.fetch = fetchMock;
+
+    await makeClient({ apiKey: 'sk-secret' }).health();
+
+    const options = fetchMock.mock.calls[0][1] as RequestInit;
+    const headers = options.headers as Record<string, string>;
+    expect(headers['Authorization']).toBe('Bearer sk-secret');
+  });
+
+  it('should omit Authorization header when apiKey is not set', async () => {
+    const fetchMock = mockFetchResponse({ status: 'ok' });
+    globalThis.fetch = fetchMock;
+
+    await makeClient({ apiKey: undefined }).health();
+
+    const options = fetchMock.mock.calls[0][1] as RequestInit;
+    const headers = options.headers as Record<string, string>;
+    expect(headers['Authorization']).toBeUndefined();
+  });
+
+  // ---- detect() -----------------------------------------------------------
+
+  it('should POST to /v1/detect with correct body', async () => {
+    const fetchMock = mockFetchResponse(DETECT_RESPONSE);
+    globalThis.fetch = fetchMock;
+
+    const result = await makeClient().detect({ agentId: 'agent-1', endpoint: '/chat' });
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, options] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('https://vix11.test/v1/detect');
+    expect(options.method).toBe('POST');
+    expect(JSON.parse(options.body as string)).toEqual({ agentId: 'agent-1', endpoint: '/chat' });
+    expect(result).toEqual(DETECT_RESPONSE);
+  });
+
+  // ---- shield() -----------------------------------------------------------
+
+  it('should POST to /v1/shield with correct body', async () => {
+    const fetchMock = mockFetchResponse(SHIELD_RESPONSE);
+    globalThis.fetch = fetchMock;
+
+    const result = await makeClient().shield({ agentId: 'agent-1' });
+
+    const [url, options] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('https://vix11.test/v1/shield');
+    expect(options.method).toBe('POST');
+    expect(result).toEqual(SHIELD_RESPONSE);
+  });
+
+  // ---- Analytics ----------------------------------------------------------
+
+  it('should GET /v1/analytics/summary with query params', async () => {
+    const summary = { from: 0, to: 1000, totalRequests: 5 };
+    const fetchMock = mockFetchResponse(summary);
+    globalThis.fetch = fetchMock;
+
+    const result = await makeClient().getAnalyticsSummary(100, 200);
+
+    const url = fetchMock.mock.calls[0][0] as string;
+    expect(url).toBe('https://vix11.test/v1/analytics/summary?from=100&to=200');
+    expect(result).toEqual(summary);
+  });
+
+  it('should GET /v1/analytics/summary without query params when omitted', async () => {
+    const fetchMock = mockFetchResponse({ from: 0, to: 1000 });
+    globalThis.fetch = fetchMock;
+
+    await makeClient().getAnalyticsSummary();
+
+    const url = fetchMock.mock.calls[0][0] as string;
+    expect(url).toBe('https://vix11.test/v1/analytics/summary');
+  });
+
+  it('should GET /v1/analytics/events with pagination', async () => {
+    const events = { events: [], page: 2, limit: 10, total: 0 };
+    const fetchMock = mockFetchResponse(events);
+    globalThis.fetch = fetchMock;
+
+    const result = await makeClient().getAnalyticsEvents(2, 10);
+
+    const url = fetchMock.mock.calls[0][0] as string;
+    expect(url).toBe('https://vix11.test/v1/analytics/events?page=2&limit=10');
+    expect(result).toEqual(events);
+  });
+
+  // ---- Detection stats ----------------------------------------------------
+
+  it('should GET /v1/detection/stats', async () => {
+    const stats = { status: 'ok', layers: [], thresholds: { throttle: 0.3, shadowBan: 0.6, block: 0.85 } };
+    const fetchMock = mockFetchResponse(stats);
+    globalThis.fetch = fetchMock;
+
+    const result = await makeClient().getDetectionStats();
+
+    const url = fetchMock.mock.calls[0][0] as string;
+    expect(url).toBe('https://vix11.test/v1/detection/stats');
+    expect(result).toEqual(stats);
+  });
+
+  // ---- Health -------------------------------------------------------------
+
+  it('should GET /v1/health', async () => {
+    const fetchMock = mockFetchResponse({ status: 'ok' });
+    globalThis.fetch = fetchMock;
+
+    const result = await makeClient().health();
+
+    expect(result).toEqual({ status: 'ok' });
+  });
+
+  // ---- Error handling -----------------------------------------------------
+
+  it('should throw Vix11Error on non-2xx response', async () => {
+    const fetchMock = mockFetchResponse({ error: 'agentId is required' }, 400);
+    globalThis.fetch = fetchMock;
+
+    await expect(makeClient().detect({ agentId: '' })).rejects.toThrow(Vix11Error);
+  });
+
+  it('should include status and message in Vix11Error', async () => {
+    const fetchMock = mockFetchResponse({ error: 'Forbidden' }, 403);
+    globalThis.fetch = fetchMock;
+
+    try {
+      await makeClient().detect({ agentId: 'x' });
+      expect.fail('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(Vix11Error);
+      const vixErr = err as Vix11Error;
+      expect(vixErr.status).toBe(403);
+      expect(vixErr.message).toBe('Forbidden');
+      expect(vixErr.body).toEqual({ error: 'Forbidden' });
+    }
+  });
+
+  it('should throw Vix11Error with generic message when response has no error field', async () => {
+    const fetchMock = mockFetchResponse(null, 500);
+    globalThis.fetch = fetchMock;
+
+    try {
+      await makeClient().health();
+      expect.fail('should have thrown');
+    } catch (err) {
+      const vixErr = err as Vix11Error;
+      expect(vixErr.status).toBe(500);
+      expect(vixErr.message).toBe('Request failed with status 500');
+    }
+  });
+
+  // ---- Timeout ------------------------------------------------------------
+
+  it('should throw Vix11Error on timeout', async () => {
+    globalThis.fetch = vi.fn().mockImplementation((_url: string, init: RequestInit) => {
+      return new Promise((_resolve, reject) => {
+        const onAbort = () => {
+          reject(new DOMException('The operation was aborted.', 'AbortError'));
+        };
+        if (init.signal) {
+          init.signal.addEventListener('abort', onAbort);
+        }
+      });
+    });
+
+    const client = makeClient({ timeout: 50 });
+
+    try {
+      await client.health();
+      expect.fail('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(Vix11Error);
+      const vixErr = err as Vix11Error;
+      expect(vixErr.status).toBe(0);
+      expect(vixErr.message).toContain('timed out');
+    }
+  });
+
+  // ---- Compliance ---------------------------------------------------------
+
+  it('should GET /v1/compliance/report', async () => {
+    const report = { status: 'compliant', generatedAt: '2025-01-01T00:00:00Z' };
+    const fetchMock = mockFetchResponse(report);
+    globalThis.fetch = fetchMock;
+
+    const result = await makeClient().getComplianceReport();
+
+    const url = fetchMock.mock.calls[0][0] as string;
+    expect(url).toBe('https://vix11.test/v1/compliance/report');
+    expect(result).toEqual(report);
+  });
+});

package/tests/middleware.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { vix11Middleware } from '../src/middleware';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeReq(overrides: Record<string, unknown> = {}) {
+  return {
+    ip: '127.0.0.1',
+    path: '/api/chat',
+    method: 'POST',
+    body: { message: 'hello' },
+    headers: {} as Record<string, string | string[] | undefined>,
+    ...overrides,
+  };
+}
+
+function makeRes() {
+  const res = {
+    statusCode: 200,
+    body: null as unknown,
+    status(code: number) {
+      res.statusCode = code;
+      return res;
+    },
+    json(data: unknown) {
+      res.body = data;
+    },
+  };
+  return res;
+}
+
+const CONFIG = {
+  baseUrl: 'https://vix11.test',
+  agentId: 'agent-1',
+  apiKey: 'sk-test',
+};
+
+function mockDetectResponse(action: string) {
+  return {
+    detection: {
+      action,
+      score: action === 'allow' ? 0.05 : 0.9,
+      layers: [],
+      totalDurationMs: 1,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('vix11Middleware', () => {
+  let originalFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('should pass clean requests through (action=allow)', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(mockDetectResponse('allow')),
+    });
+
+    const middleware = vix11Middleware(CONFIG);
+    const req = makeReq();
+    const res = makeRes();
+    const next = vi.fn();
+
+    await new Promise<void>((resolve) => {
+      middleware(req, res, (...args: unknown[]) => {
+        next(...args);
+        resolve();
+      });
+    });
+
+    expect(next).toHaveBeenCalledOnce();
+    expect(next).toHaveBeenCalledWith(); // no error argument
+  });
+
+  it('should block suspicious requests (action=block) with 403', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(mockDetectResponse('block')),
+    });
+
+    const middleware = vix11Middleware(CONFIG);
+    const req = makeReq();
+    const res = makeRes();
+    const next = vi.fn();
+
+    // Wait for the async middleware to finish.
+    await new Promise<void>((resolve) => {
+      const originalJson = res.json.bind(res);
+      res.json = (data: unknown) => {
+        originalJson(data);
+        resolve();
+      };
+      middleware(req, res, next);
+    });
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(403);
+    expect(res.body).toEqual({
+      error: 'Request blocked by Vix11 security policy',
+      action: 'block',
+    });
+  });
+
+  it('should throttle requests (action=throttle) with 429', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(mockDetectResponse('throttle')),
+    });
+
+    const middleware = vix11Middleware(CONFIG);
+    const req = makeReq();
+    const res = makeRes();
+    const next = vi.fn();
+
+    await new Promise<void>((resolve) => {
+      const originalJson = res.json.bind(res);
+      res.json = (data: unknown) => {
+        originalJson(data);
+        resolve();
+      };
+      middleware(req, res, next);
+    });
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(429);
+    expect(res.body).toEqual({
+      error: 'Request throttled by Vix11 security policy',
+      action: 'throttle',
+      retryAfterMs: 5000,
+    });
+  });
+
+  it('should attach detection result to req.vix11', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(mockDetectResponse('allow')),
+    });
+
+    const middleware = vix11Middleware(CONFIG);
+    const req = makeReq();
+    const res = makeRes();
+
+    await new Promise<void>((resolve) => {
+      middleware(req, res, () => {
+        resolve();
+      });
+    });
+
+    expect(req.vix11).toBeDefined();
+    expect(req.vix11).toEqual({
+      action: 'allow',
+      score: 0.05,
+      layers: [],
+      totalDurationMs: 1,
+    });
+  });
+
+  it('should call next with error when detection fails', async () => {
+    globalThis.fetch = vi.fn().mockRejectedValue(new Error('network error'));
+
+    const middleware = vix11Middleware(CONFIG);
+    const req = makeReq();
+    const res = makeRes();
+    const next = vi.fn();
+
+    await new Promise<void>((resolve) => {
+      middleware(req, res, (...args: unknown[]) => {
+        next(...args);
+        resolve();
+      });
+    });
+
+    expect(next).toHaveBeenCalledOnce();
+    expect(next.mock.calls[0][0]).toBeInstanceOf(Error);
+  });
+});