vix11 1.0.0

package/README.md

@@ -0,0 +1,188 @@
+# Vix11 Node.js SDK
+
+Official Node.js SDK for the [Vix11](../../README.md) AI agent security platform. Provides a typed client for the Vix11 API and drop-in Express middleware.
+
+## Installation
+
+```bash
+npm install vix11
+```
+
+## Quick Start
+
+```js
+import { Vix11Client } from 'vix11';
+
+const client = new Vix11Client({
+  baseUrl: 'https://vix11.example.com',
+  agentId: 'my-agent',
+  apiKey: 'your-api-key',
+});
+
+const result = await client.detect({
+  endpoint: '/api/chat',
+  payload: '{"prompt": "hello"}',
+});
+
+if (result.detection.action === 'block') {
+  console.log('Request blocked:', result.detection);
+} else {
+  console.log('Request allowed');
+}
+```
+
+## Express Middleware
+
+The SDK includes middleware that automatically intercepts every incoming request, runs it through the Vix11 detection pipeline, and blocks or throttles suspicious traffic.
+
+```js
+import express from 'express';
+import { vix11Middleware } from 'vix11';
+
+const app = express();
+
+app.use(vix11Middleware({
+  baseUrl: 'https://vix11.example.com',
+  agentId: 'my-agent',
+  apiKey: 'your-api-key',
+}));
+
+app.post('/api/chat', (req, res) => {
+  // req.vix11 contains the detection result for downstream use
+  console.log('Detection score:', req.vix11);
+  res.json({ reply: 'Hello!' });
+});
+
+app.listen(3000);
+```
+
+**Middleware behavior:**
+
+- `block` action: responds with `403` and a JSON error body.
+- `throttle` action: responds with `429` and a `retryAfterMs` field.
+- `allow` / `shadow-ban`: calls `next()` and attaches the detection result to `req.vix11`.
+- On detection failure, the middleware **fails open** and forwards the error to the Express error handler.
+
+## API Reference
+
+### `new Vix11Client(config)`
+
+Creates a new client instance.
+
+### `client.detect(payload): Promise<DetectResponse>`
+
+Run the 11-layer detection pipeline against a request.
+
+**Parameters:**
+
+| Field      | Type     | Required | Description                        |
+|------------|----------|----------|------------------------------------|
+| `agentId`  | `string` | Yes      | Agent identifier                   |
+| `endpoint` | `string` | Yes      | Target endpoint path               |
+| `payload`  | `string` | No       | Request body as a string           |
+| `ip`       | `string` | No       | Client IP address                  |
+
+**Returns:** `DetectResponse` containing the detection result with `action` (`allow`, `block`, `throttle`, `shadow-ban`) and layer scores.
+
+### `client.shield(payload): Promise<ShieldResponse>`
+
+Run the shielded-request flow, which combines passport verification with the detection pipeline.
+
+**Parameters:** Same as `detect`.
+
+**Returns:** `ShieldResponse` with passport verification status and detection result.
+
+### `client.getAnalyticsSummary(from?, to?): Promise<AnalyticsSummary>`
+
+Retrieve the analytics summary for a time range, including the "$X saved" distillation metric.
+
+**Parameters:**
+
+| Field  | Type     | Required | Description                  |
+|--------|----------|----------|------------------------------|
+| `from` | `number` | No       | Start timestamp (epoch ms)   |
+| `to`   | `number` | No       | End timestamp (epoch ms)     |
+
+### `client.getAnalyticsEvents(page?, limit?): Promise<PaginatedEvents>`
+
+Retrieve paginated detection events.
+
+**Parameters:**
+
+| Field   | Type     | Required | Description            |
+|---------|----------|----------|------------------------|
+| `page`  | `number` | No       | Page number            |
+| `limit` | `number` | No       | Events per page        |
+
+### `client.getComplianceReport(): Promise<ComplianceReport>`
+
+Retrieve the current OWASP ASI compliance report.
+
+### `client.getDetectionStats(): Promise<DetectionStats>`
+
+Retrieve detection pipeline statistics, including per-layer performance and thresholds.
+
+### `client.health(): Promise<{ status: string }>`
+
+Check API health. Returns `{ status: "ok" }` when the service is operational.
+
+## Error Handling
+
+All API errors are thrown as `Vix11Error` instances.
+
+```js
+import { Vix11Error } from 'vix11';
+
+try {
+  await client.detect({ endpoint: '/api/chat', payload: '...' });
+} catch (err) {
+  if (err instanceof Vix11Error) {
+    console.error('Vix11 API error:', err.message);
+    console.error('HTTP status:', err.status);
+    console.error('Response body:', err.body);
+  }
+}
+```
+
+**`Vix11Error` properties:**
+
+| Property  | Type      | Description                                      |
+|-----------|-----------|--------------------------------------------------|
+| `message` | `string`  | Human-readable error message                     |
+| `status`  | `number`  | HTTP status code (0 for timeouts)                |
+| `body`    | `unknown` | Raw response body, if available                  |
+
+Timeout errors have `status` set to `0` and a message indicating the configured timeout value.
+
+## Configuration
+
+| Option    | Type     | Required | Default | Description                                   |
+|-----------|----------|----------|---------|-----------------------------------------------|
+| `baseUrl` | `string` | Yes      | --      | Base URL of the Vix11 API                     |
+| `agentId` | `string` | Yes      | --      | Agent identifier sent with every request      |
+| `apiKey`  | `string` | No       | --      | API key for authenticated requests            |
+| `timeout` | `number` | No       | `5000`  | Request timeout in milliseconds               |
+
+## TypeScript
+
+The SDK is written in TypeScript and exports all types used across the API:
+
+```ts
+import type {
+  Vix11Config,
+  DetectRequest,
+  DetectResponse,
+  ShieldRequest,
+  ShieldResponse,
+  AnalyticsSummary,
+  PaginatedEvents,
+  ComplianceReport,
+  DetectionStats,
+} from 'vix11';
+```
+
+No `@types` package is needed. Type definitions are bundled with the package.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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';
+/** 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 declare class Vix11Client {
+    private readonly baseUrl;
+    private readonly agentId;
+    private readonly apiKey?;
+    private readonly timeout;
+    constructor(config: Vix11Config);
+    /** Run the detection pipeline against a request payload. */
+    detect(payload: DetectRequest): Promise<DetectResponse>;
+    /** Run the shielded-request flow (passport verification + detection). */
+    shield(payload: ShieldRequest): Promise<ShieldResponse>;
+    /** Retrieve the analytics summary for a time range. */
+    getAnalyticsSummary(from?: number, to?: number): Promise<AnalyticsSummary>;
+    /** Retrieve paginated analytics events. */
+    getAnalyticsEvents(page?: number, limit?: number): Promise<PaginatedEvents>;
+    /** Retrieve the current compliance report. */
+    getComplianceReport(): Promise<ComplianceReport>;
+    /** Retrieve detection pipeline stats (layers, thresholds). */
+    getDetectionStats(): Promise<DetectionStats>;
+    /** Get the Agent Trust Score for a specific agent. */
+    getTrustScore(agentId: string): Promise<TrustScore>;
+    /** Issue a new KYA passport for an agent. */
+    issuePassport(params: {
+        agentId: string;
+        ownerId: string;
+        capabilities: PassportCapabilities;
+        ttlSeconds?: number;
+    }): Promise<{
+        passport: SignedPassport;
+        meta: {
+            latencyMs: number;
+        };
+    }>;
+    /** Verify a signed passport. */
+    verifyPassport(passport: SignedPassport): Promise<{
+        valid: boolean;
+        reason: string;
+        payload?: SignedPassport['payload'];
+        meta: {
+            latencyMs: number;
+        };
+    }>;
+    /** Revoke a passport by ID. */
+    revokePassport(passportId: string, reason: string): Promise<{
+        revoked: boolean;
+        passportId: string;
+    }>;
+    /** Check API health with KV connectivity probes. */
+    health(): Promise<HealthResponse>;
+    private buildHeaders;
+    private request;
+    private get;
+    private post;
+}

package/dist/client.js

@@ -0,0 +1,148 @@
+/**
+ * Vix11 SDK Client
+ *
+ * Provides a typed interface for interacting with the Vix11 API.
+ * Uses native fetch (no external dependencies).
+ */
+import { Vix11Error } from './types';
+export class Vix11Client {
+    baseUrl;
+    agentId;
+    apiKey;
+    timeout;
+    constructor(config) {
+        // 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) {
+        return this.post('/v1/detect', payload);
+    }
+    /** Run the shielded-request flow (passport verification + detection). */
+    async shield(payload) {
+        return this.post('/v1/shield', payload);
+    }
+    // -----------------------------------------------------------------------
+    // Analytics
+    // -----------------------------------------------------------------------
+    /** Retrieve the analytics summary for a time range. */
+    async getAnalyticsSummary(from, to) {
+        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(`/v1/analytics/summary${qs ? `?${qs}` : ''}`);
+    }
+    /** Retrieve paginated analytics events. */
+    async getAnalyticsEvents(page, limit) {
+        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(`/v1/analytics/events${qs ? `?${qs}` : ''}`);
+    }
+    // -----------------------------------------------------------------------
+    // Compliance
+    // -----------------------------------------------------------------------
+    /** Retrieve the current compliance report. */
+    async getComplianceReport() {
+        return this.get('/v1/compliance/report');
+    }
+    // -----------------------------------------------------------------------
+    // Stats
+    // -----------------------------------------------------------------------
+    /** Retrieve detection pipeline stats (layers, thresholds). */
+    async getDetectionStats() {
+        return this.get('/v1/detection/stats');
+    }
+    // -----------------------------------------------------------------------
+    // Trust
+    // -----------------------------------------------------------------------
+    /** Get the Agent Trust Score for a specific agent. */
+    async getTrustScore(agentId) {
+        return this.get(`/v1/trust/${encodeURIComponent(agentId)}`);
+    }
+    // -----------------------------------------------------------------------
+    // Passport
+    // -----------------------------------------------------------------------
+    /** Issue a new KYA passport for an agent. */
+    async issuePassport(params) {
+        return this.post('/v1/passport/issue', params);
+    }
+    /** Verify a signed passport. */
+    async verifyPassport(passport) {
+        return this.post('/v1/passport/verify', passport);
+    }
+    /** Revoke a passport by ID. */
+    async revokePassport(passportId, reason) {
+        return this.post('/v1/passport/revoke', { passportId, reason });
+    }
+    // -----------------------------------------------------------------------
+    // Health
+    // -----------------------------------------------------------------------
+    /** Check API health with KV connectivity probes. */
+    async health() {
+        return this.get('/v1/health');
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    buildHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-Vix11-Agent-Id': this.agentId,
+        };
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        return headers;
+    }
+    async request(method, path, body) {
+        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 = await response.json().catch(() => null);
+            if (!response.ok) {
+                const message = (responseBody && typeof responseBody === 'object' && 'error' in responseBody
+                    ? String(responseBody.error)
+                    : undefined) ?? `Request failed with status ${response.status}`;
+                throw new Vix11Error(message, response.status, responseBody);
+            }
+            return responseBody;
+        }
+        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);
+        }
+    }
+    get(path) {
+        return this.request('GET', path);
+    }
+    post(path, body) {
+        return this.request('POST', path, body);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * Vix11 SDK — AI Agent Security
+ *
+ * @packageDocumentation
+ */
+export { Vix11Client } from './client';
+export { vix11Middleware } from './middleware';
+export { Vix11Error, } from './types';

package/dist/middleware.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 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 declare function vix11Middleware(config: Vix11Config): RequestHandler;
+export {};

package/dist/middleware.js

@@ -0,0 +1,58 @@
+/**
+ * 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';
+/**
+ * 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) {
+    const client = new Vix11Client(config);
+    return (req, res, next) => {
+        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) => {
+            // On detection failure, fail open (let request through) and forward the error.
+            next(err);
+        });
+    };
+}