vix11 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Vix11 SDK Type Definitions
+ *
+ * SDK-specific types for requests and responses when interacting
+ * with the Vix11 AI agent security platform API.
+ */
+/** Error thrown by the Vix11 SDK on non-2xx responses. */
+export declare class Vix11Error extends Error {
+    /** HTTP status code returned by the API. */
+    readonly status: number;
+    /** Raw response body (if available). */
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 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;
+}
+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;
+}
+/** 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;
+}
+/** Response from GET /v1/compliance/report. */
+export interface ComplianceReport {
+    status: string;
+    generatedAt: string;
+    [key: string]: unknown;
+}
+/** 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;
+}
+/** 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;
+}
+/** 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/dist/types.js

@@ -0,0 +1,22 @@
+/**
+ * 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. */
+    status;
+    /** Raw response body (if available). */
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = 'Vix11Error';
+        this.status = status;
+        this.body = body;
+    }
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "vix11",
+  "version": "1.0.0",
+  "description": "Vix11 SDK - AI Agent Security",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,211 @@
+/**
+ * Vix11 SDK Client
+ *
+ * Provides a typed interface for interacting with the Vix11 API.
+ * Uses native fetch (no external dependencies).
+ */
+
+import type {
+  DetectRequest,
+  DetectResponse,
+  ShieldRequest,
+  ShieldResponse,
+  AnalyticsSummary,
+  PaginatedEvents,
+  ComplianceReport,
+  DetectionStats,
+  TrustScore,
+  HealthResponse,
+  SignedPassport,
+  PassportCapabilities,
+} from './types';
+import { Vix11Error } from './types';
+
+/** Configuration for the Vix11 client. */
+export interface Vix11Config {
+  /** Base URL of the Vix11 API (e.g. "https://vix11.example.com"). */
+  baseUrl: string;
+  /** Agent identifier sent with every request. */
+  agentId: string;
+  /** Optional API key for authenticated requests. */
+  apiKey?: string;
+  /** Request timeout in milliseconds (default: 5000). */
+  timeout?: number;
+}
+
+export class Vix11Client {
+  private readonly baseUrl: string;
+  private readonly agentId: string;
+  private readonly apiKey?: string;
+  private readonly timeout: number;
+
+  constructor(config: Vix11Config) {
+    // Strip trailing slash for consistent URL building.
+    this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+    this.agentId = config.agentId;
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout ?? 5000;
+  }
+
+  // -----------------------------------------------------------------------
+  // Detection
+  // -----------------------------------------------------------------------
+
+  /** Run the detection pipeline against a request payload. */
+  async detect(payload: DetectRequest): Promise<DetectResponse> {
+    return this.post<DetectResponse>('/v1/detect', payload);
+  }
+
+  /** Run the shielded-request flow (passport verification + detection). */
+  async shield(payload: ShieldRequest): Promise<ShieldResponse> {
+    return this.post<ShieldResponse>('/v1/shield', payload);
+  }
+
+  // -----------------------------------------------------------------------
+  // Analytics
+  // -----------------------------------------------------------------------
+
+  /** Retrieve the analytics summary for a time range. */
+  async getAnalyticsSummary(from?: number, to?: number): Promise<AnalyticsSummary> {
+    const params = new URLSearchParams();
+    if (from !== undefined) params.set('from', String(from));
+    if (to !== undefined) params.set('to', String(to));
+    const qs = params.toString();
+    return this.get<AnalyticsSummary>(`/v1/analytics/summary${qs ? `?${qs}` : ''}`);
+  }
+
+  /** Retrieve paginated analytics events. */
+  async getAnalyticsEvents(page?: number, limit?: number): Promise<PaginatedEvents> {
+    const params = new URLSearchParams();
+    if (page !== undefined) params.set('page', String(page));
+    if (limit !== undefined) params.set('limit', String(limit));
+    const qs = params.toString();
+    return this.get<PaginatedEvents>(`/v1/analytics/events${qs ? `?${qs}` : ''}`);
+  }
+
+  // -----------------------------------------------------------------------
+  // Compliance
+  // -----------------------------------------------------------------------
+
+  /** Retrieve the current compliance report. */
+  async getComplianceReport(): Promise<ComplianceReport> {
+    return this.get<ComplianceReport>('/v1/compliance/report');
+  }
+
+  // -----------------------------------------------------------------------
+  // Stats
+  // -----------------------------------------------------------------------
+
+  /** Retrieve detection pipeline stats (layers, thresholds). */
+  async getDetectionStats(): Promise<DetectionStats> {
+    return this.get<DetectionStats>('/v1/detection/stats');
+  }
+
+  // -----------------------------------------------------------------------
+  // Trust
+  // -----------------------------------------------------------------------
+
+  /** Get the Agent Trust Score for a specific agent. */
+  async getTrustScore(agentId: string): Promise<TrustScore> {
+    return this.get<TrustScore>(`/v1/trust/${encodeURIComponent(agentId)}`);
+  }
+
+  // -----------------------------------------------------------------------
+  // Passport
+  // -----------------------------------------------------------------------
+
+  /** Issue a new KYA passport for an agent. */
+  async issuePassport(params: {
+    agentId: string;
+    ownerId: string;
+    capabilities: PassportCapabilities;
+    ttlSeconds?: number;
+  }): Promise<{ passport: SignedPassport; meta: { latencyMs: number } }> {
+    return this.post('/v1/passport/issue', params);
+  }
+
+  /** Verify a signed passport. */
+  async verifyPassport(passport: SignedPassport): Promise<{
+    valid: boolean;
+    reason: string;
+    payload?: SignedPassport['payload'];
+    meta: { latencyMs: number };
+  }> {
+    return this.post('/v1/passport/verify', passport);
+  }
+
+  /** Revoke a passport by ID. */
+  async revokePassport(passportId: string, reason: string): Promise<{
+    revoked: boolean;
+    passportId: string;
+  }> {
+    return this.post('/v1/passport/revoke', { passportId, reason });
+  }
+
+  // -----------------------------------------------------------------------
+  // Health
+  // -----------------------------------------------------------------------
+
+  /** Check API health with KV connectivity probes. */
+  async health(): Promise<HealthResponse> {
+    return this.get<HealthResponse>('/v1/health');
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal helpers
+  // -----------------------------------------------------------------------
+
+  private buildHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'X-Vix11-Agent-Id': this.agentId,
+    };
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+    return headers;
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: this.buildHeaders(),
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      const responseBody: unknown = await response.json().catch(() => null);
+
+      if (!response.ok) {
+        const message =
+          (responseBody && typeof responseBody === 'object' && 'error' in responseBody
+            ? String((responseBody as Record<string, unknown>).error)
+            : undefined) ?? `Request failed with status ${response.status}`;
+        throw new Vix11Error(message, response.status, responseBody);
+      }
+
+      return responseBody as T;
+    } catch (err) {
+      if (err instanceof Vix11Error) throw err;
+      if (err instanceof DOMException && err.name === 'AbortError') {
+        throw new Vix11Error(`Request timed out after ${this.timeout}ms`, 0);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private get<T>(path: string): Promise<T> {
+    return this.request<T>('GET', path);
+  }
+
+  private post<T>(path: string, body: unknown): Promise<T> {
+    return this.request<T>('POST', path, body);
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Vix11 SDK — AI Agent Security
+ *
+ * @packageDocumentation
+ */
+
+export { Vix11Client } from './client';
+export type { Vix11Config } from './client';
+export { vix11Middleware } from './middleware';
+export type { RequestHandler } from './middleware';
+
+export {
+  Vix11Error,
+  type LayerScore,
+  type DetectionMeta,
+  type DetectRequest,
+  type DetectResponse,
+  type ShieldRequest,
+  type ShieldResponse,
+  type PassportCapabilities,
+  type PassportPayload,
+  type SignedPassport,
+  type AnalyticsSummary,
+  type PaginatedEvents,
+  type DistillationEvent,
+  type ComplianceReport,
+  type DetectionStats,
+  type TrustTier,
+  type TrustScore,
+  type HealthCheck,
+  type HealthResponse,
+} from './types';

package/src/middleware.ts

@@ -0,0 +1,88 @@
+/**
+ * Vix11 Express Middleware
+ *
+ * Drop-in Express middleware that intercepts incoming requests,
+ * runs them through the Vix11 detection pipeline, and blocks or
+ * throttles suspicious traffic automatically.
+ */
+
+import { Vix11Client } from './client';
+import type { Vix11Config } from './client';
+import type { DetectResponse } from './types';
+
+/** Minimal Express-compatible types so we avoid a dependency on @types/express. */
+interface Request {
+  ip?: string;
+  path?: string;
+  method?: string;
+  body?: unknown;
+  headers: Record<string, string | string[] | undefined>;
+  vix11?: DetectResponse['detection'];
+  [key: string]: unknown;
+}
+
+interface Response {
+  status(code: number): Response;
+  json(body: unknown): void;
+}
+
+type NextFunction = (err?: unknown) => void;
+
+/** Express-compatible RequestHandler signature. */
+export type RequestHandler = (req: Request, res: Response, next: NextFunction) => void;
+
+/**
+ * Create Express middleware that runs every incoming request through
+ * Vix11 detection.
+ *
+ * - If the action is `block`, responds with 403.
+ * - If the action is `throttle`, responds with 429.
+ * - Otherwise calls `next()` and attaches the detection result to `req.vix11`.
+ */
+export function vix11Middleware(config: Vix11Config): RequestHandler {
+  const client = new Vix11Client(config);
+
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const agentIdHeader = req.headers['x-vix11-agent-id'];
+    const agentId = (typeof agentIdHeader === 'string' ? agentIdHeader : undefined) ?? config.agentId;
+
+    const ip =
+      (typeof req.headers['x-forwarded-for'] === 'string'
+        ? req.headers['x-forwarded-for'].split(',')[0]?.trim()
+        : undefined) ?? req.ip ?? '0.0.0.0';
+
+    client
+      .detect({
+        agentId,
+        endpoint: req.path ?? '/',
+        payload: req.body ? JSON.stringify(req.body) : undefined,
+        ip,
+      })
+      .then((result) => {
+        // Attach to request for downstream handlers.
+        req.vix11 = result.detection;
+
+        switch (result.detection.action) {
+          case 'block':
+            res.status(403).json({
+              error: 'Request blocked by Vix11 security policy',
+              action: 'block',
+            });
+            return;
+          case 'throttle':
+            res.status(429).json({
+              error: 'Request throttled by Vix11 security policy',
+              action: 'throttle',
+              retryAfterMs: 5000,
+            });
+            return;
+          default:
+            next();
+        }
+      })
+      .catch((err: unknown) => {
+        // On detection failure, fail open (let request through) and forward the error.
+        next(err);
+      });
+  };
+}