@yobekasbah/sdk 6.0.0

package/README.md

@@ -0,0 +1,180 @@
+# @kasbah/sdk
+
+[![npm version](https://img.shields.io/npm/v/@kasbah/sdk.svg?color=cc3300)](https://www.npmjs.com/package/@kasbah/sdk)
+[![KasbahOS Governed](https://api.bekasbah.com/v1/badge/global.svg)](https://bekasbah.com)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Full%20Types-blue.svg)](https://bekasbah.com)
+
+Official Node.js SDK for [KasbahOS](https://bekasbah.com) — govern any AI agent in 5 lines. Cryptographic receipts, 37 detection systems, drop-in proxy for OpenAI and Anthropic.
+
+## Install
+
+```bash
+npm install @kasbah/sdk
+```
+
+## 5-line quick start
+
+```js
+const Kasbah = require('@kasbah/sdk');
+
+const k = new Kasbah({ apiKey: process.env.KASBAH_API_KEY });
+
+const result = await k.govern({ prompt: userInput, agent: 'my-agent' });
+if (result.verdict === 'DENY') throw new Error('Blocked: ' + result.threats.join(', '));
+
+console.log(`Safe — proof: ${result.proof}`);
+```
+
+## Drop-in OpenAI proxy
+
+```js
+const Kasbah = require('@kasbah/sdk');
+const OpenAI = require('openai');
+
+const kasbah = new Kasbah({ apiKey: process.env.KASBAH_API_KEY });
+const openai  = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+// Create a governed agent session
+const session = await kasbah.createAgent({
+  agentId:   'research-bot',
+  passportId: process.env.KASBAH_PASSPORT_ID,
+  goal:      'Summarize recent papers on LLM safety',
+  manifest:  { allowedTools: ['search', 'read_url'], maxTokens: 50000 },
+});
+
+// Wrap OpenAI — every call is auto-governed
+const governed = kasbah.wrapOpenAI(openai, session.sessionId);
+
+// This call transparently goes through KasbahOS governance
+const completion = await governed.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Summarize this paper...' }],
+});
+```
+
+## Drop-in Anthropic proxy
+
+```js
+const Kasbah   = require('@kasbah/sdk');
+const Anthropic = require('@anthropic-ai/sdk');
+
+const kasbah    = new Kasbah({ apiKey: process.env.KASBAH_API_KEY });
+const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+const session = await kasbah.createAgent({
+  agentId:   'claude-agent',
+  passportId: process.env.KASBAH_PASSPORT_ID,
+  goal:      'Answer customer questions safely',
+});
+
+const governed = kasbah.wrapAnthropic(anthropic, session.sessionId);
+const message  = await governed.messages.create({ model: 'claude-opus-4-5', ... });
+```
+
+## Per-agent passports
+
+```js
+// Issue a passport for an agent — limits what it can do
+const passport = await k.passport.issue({
+  agentId:      'data-pipeline',
+  capabilities: ['read_database', 'write_report'],
+  trustLevel:   'medium',
+  spendPolicy:  { maxTokensPerDay: 100000, hardBlockOnExceed: true },
+});
+
+// Every govern() call tracks passport trust score
+const result = await k.govern({
+  prompt:     userInput,
+  passportId: passport.passportId,
+});
+```
+
+## Scan for secrets and threats
+
+```js
+const scan = await k.scan(codeSnippet);
+if (!scan.safe) {
+  console.log('Threats:', scan.threats);
+  // e.g. ['AWS Access Key', 'Hardcoded Password']
+}
+```
+
+## Verify a governance proof (auditors)
+
+```js
+// Zero-trust: verify any governance decision mathematically, no KasbahOS trust needed
+const verified = await fetch('https://api.bekasbah.com/v1/zk/verify', {
+  method: 'POST',
+  body: JSON.stringify({ proof: result.proof, publicInput: { verdict: 'ALLOW' } }),
+});
+// { valid: true, rulesVerified: ['no_injection', 'no_pii', 'no_secrets'] }
+```
+
+## All methods
+
+| Method | Description |
+|--------|-------------|
+| `govern(opts)` | Govern a prompt/response through all 37 systems |
+| `scan(text)` | Lightweight threat scan |
+| `explain(prompt)` | Explain why a prompt would be blocked |
+| `bells(text)` | Bell's Inequality AI detection (CHSH S-value) |
+| `maqasid(text)` | 5-pillar ethics scoring |
+| `rtp(text)` | RTP governance pipeline |
+| `passport.issue(opts)` | Create agent passport |
+| `passport.revoke(id)` | Revoke a passport |
+| `delegation.issue(opts)` | Issue delegation token (agent A acts as B) |
+| `honeytoken.deploy(service)` | Plant a canary credential |
+| `honeytoken.check(text)` | Check text for leaked canaries |
+| `createAgent(opts)` | Create governed agent session |
+| `governTool(sessionId, tool, args)` | Govern a tool call before executing |
+| `scanToolResult(sessionId, tool, output)` | Scan tool output for injections |
+| `wrapOpenAI(client, sessionId)` | Auto-govern all OpenAI calls |
+| `wrapAnthropic(client, sessionId)` | Auto-govern all Anthropic calls |
+| `proxyOpenAI(body, key)` | Proxy an OpenAI completion |
+| `proxyAnthropic(body, key)` | Proxy an Anthropic message |
+| `getUsage(passportId)` | Token/cost usage for a passport |
+| `setBudget(passportId, policy)` | Set hard token/cost limits |
+| `health()` | API health check |
+| `stats()` | Governance statistics |
+| `auditChain()` | Tamper-evident audit ledger |
+
+## TypeScript
+
+Full TypeScript types are included:
+
+```typescript
+import Kasbah, { GovernResult, Verdict, Passport, AgentSession } from '@kasbah/sdk';
+
+const k = new Kasbah({ apiKey: process.env.KASBAH_API_KEY! });
+
+const result: GovernResult = await k.govern({ prompt: 'Hello world' });
+const verdict: Verdict = result.verdict; // 'ALLOW' | 'WARN' | 'DENY'
+```
+
+## Configuration
+
+```js
+const k = new Kasbah({
+  apiKey:    process.env.KASBAH_API_KEY,    // your API key
+  baseUrl:   'http://your-server:8788',     // self-hosted instance
+  timeout:   10000,                         // ms (default: 10000)
+  autoRetry: true,                          // retry on 5xx (default: true)
+  passportId: 'pp_default_agent',           // default passport for all govern() calls
+});
+```
+
+## Self-hosted
+
+```bash
+docker run -p 8788:8788 kasbahguard/kasbah-os:latest
+```
+
+Then:
+```js
+const k = new Kasbah({ baseUrl: 'http://localhost:8788' });
+```
+
+---
+
+[bekasbah.com](https://bekasbah.com)  |  [GitHub](https://github.com/kasbah-guard)  |  [Docs](https://bekasbah.com/public/glassbox.html)

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@yobekasbah/sdk",
+  "version": "6.0.0",
+  "description": "KasbahOS — govern any AI agent in one line. Cryptographic receipts, multi-layer threat detection, drop-in middleware for OpenAI, Anthropic, LangChain.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": [
+    "src/index.js",
+    "src/index.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node src/test.js"
+  },
+  "keywords": [
+    "ai", "security", "governance", "llm", "openai", "anthropic",
+    "langchain", "prompt-injection", "kasbah", "kasbah-os", "receipt",
+    "audit", "compliance", "hipaa", "soc2", "middleware"
+  ],
+  "author": "Kasbah Guard <hello@bekasbah.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kasbah-guard/kasbah"
+  },
+  "homepage": "https://bekasbah.com",
+  "bugs": { "url": "https://github.com/kasbah-guard/kasbah/issues" },
+  "engines": { "node": ">=18.0.0" }
+}

package/src/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * KasbahOS SDK — TypeScript definitions
+ * @version 6.0.0
+ */
+
+export interface GovernOptions {
+  agent?: string;
+  passportId?: string;
+  context?: Record<string, unknown>;
+}
+
+export interface GovernResult {
+  verdict: 'ALLOW' | 'WARN' | 'DENY';
+  score: number;
+  threats: string[];
+  receipt: string;
+  receiptPayload?: string;
+  ticket?: { id: string; expiresAt: number; ttlMs: number };
+  latency_ms: number;
+  timestamp: string;
+  requestId: string;
+  passport?: Record<string, unknown>;
+  pii?: { detected: boolean; count: number; riskScore: number };
+  steg?: { detected: boolean; method: string; confidence: number };
+  sentinel?: { score: number; threats: string[]; deontic?: string };
+  secrets?: { found: boolean; count: number; types: string[] };
+  intent?: { intent: string; confidence: number; riskLevel: string };
+  manipulation?: { patterns: number; risk: string };
+  bells?: { sValue: number; isAI: boolean };
+  maqasid?: { compliance: number; concerns: string[] };
+  rtp?: { intent: string; modulatorScore: number; obfuscationScore: number };
+}
+
+export interface ScanResult {
+  verdict: 'ALLOW' | 'WARN' | 'DENY';
+  threats: string[];
+  risk_score: number;
+  safe: boolean;
+  latency_ms: number;
+  timestamp: string;
+}
+
+export interface HealthResult {
+  status: string;
+  version: string;
+  engine: string;
+  uptime_s: string;
+  persistence: 'redis' | 'memory';
+  systems: { active: number; total: number; wasm: boolean };
+  timestamp: string;
+}
+
+export interface ReceiptVerification {
+  valid: boolean;
+  verdict?: string;
+  requestId?: string;
+  timestamp?: number;
+  error?: string;
+}
+
+export interface PassportResult {
+  passportId: string;
+  agentId: string;
+  publicKey: string;
+  privateKey: string;
+  issuedAt: string;
+  warning: string;
+}
+
+export interface StreamHandle {
+  close(): void;
+  on(event: 'error', handler: (err: Error) => void): StreamHandle;
+  on(event: 'open', handler: () => void): StreamHandle;
+}
+
+export interface ProxyResult {
+  id: string;
+  object: string;
+  choices: unknown[];
+  usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+  _kasbahReceipt?: string;
+  _kasbahVerdict?: string;
+}
+
+export interface UsageResult {
+  passportId: string;
+  spendLedger: { tokens1m: number; tokens24h: number; costCents24h: number };
+  watcherState: { band: string; brittleness: number; tokensPerHour: number; costPerHour: number };
+  timestamp: string;
+}
+
+export interface BudgetPolicy {
+  maxTokensPerMin?: number;
+  maxTokensPerDay?: number;
+  maxCostCentsPerDay?: number;
+}
+
+export declare class KasbahError extends Error {
+  statusCode?: number;
+  verdict?: string;
+}
+
+export declare class Kasbah {
+  constructor(options: { apiKey: string; baseUrl?: string; timeout?: number });
+
+  /** Govern any prompt — returns verdict, receipt, threats */
+  govern(prompt: string | { prompt: string; [key: string]: unknown }, options?: GovernOptions): Promise<GovernResult>;
+
+  /** Lightweight text scan without full policy gate */
+  scan(text: string): Promise<ScanResult>;
+
+  /** Check API health */
+  health(): Promise<HealthResult>;
+
+  /** Verify a governance receipt offline — no API call needed */
+  verifyReceipt(receipt: string, payload?: string): ReceiptVerification;
+
+  /** Issue a Governance Passport for an agent */
+  issuePassport(agentId: string, capabilities?: string[]): Promise<PassportResult>;
+
+  /** Stream real-time governance events via SSE */
+  stream(onEvent: (event: GovernResult) => void): StreamHandle;
+
+  /** Proxy an OpenAI chat completion through Kasbah governance */
+  proxyOpenAI(body: Record<string, unknown>, upstreamKey: string, options?: GovernOptions): Promise<ProxyResult>;
+
+  /** Proxy an Anthropic messages call through Kasbah governance */
+  proxyAnthropic(body: Record<string, unknown>, upstreamKey: string, options?: GovernOptions): Promise<ProxyResult>;
+
+  /** Get token/cost usage for a passport */
+  getUsage(passportId: string): Promise<UsageResult>;
+
+  /** Set token/cost budget policy for a passport */
+  setBudget(passportId: string, policy: BudgetPolicy): Promise<{ ok: boolean; passportId: string; policy: BudgetPolicy }>;
+
+  /** Get current budget policy for a passport */
+  getBudget(passportId: string): Promise<{ passportId: string; policy: BudgetPolicy; usage: UsageResult }>;
+
+  readonly passport: {
+    issue(options: { agentId?: string; capabilities?: string[] }): Promise<PassportResult>;
+    get(passportId: string): Promise<Record<string, unknown>>;
+    revoke(passportId: string): Promise<{ ok: boolean }>;
+    list(): Promise<{ passports: PassportResult[]; total: number }>;
+  };
+}
+
+export default Kasbah;

package/src/index.js

@@ -0,0 +1,701 @@
+'use strict';
+
+/**
+ * Kasbah Guard SDK — Official Node.js Client
+ *
+ * Govern AI agents from any Node.js app. Wraps the Kasbah API
+ * with automatic passport management, retry logic, and streaming.
+ *
+ * Usage:
+ *   const Kasbah = require('@yobekasbah/sdk');
+ *   const k = new Kasbah({ apiKey: 'kg_...', baseUrl: 'https://api.bekasbah.com' });
+ *
+ *   // Govern a prompt
+ *   const result = await k.govern({ prompt: 'User message here' });
+ *   if (result.verdict === 'DENY') throw new Error('Blocked: ' + result.threats.join(', '));
+ *
+ *   // Issue a passport for an agent
+ *   const passport = await k.passport.issue({ agentId: 'my-agent', capabilities: ['search'] });
+ *
+ *   // Check system health
+ *   const health = await k.health();
+ */
+
+const http  = require('http');
+const https = require('https');
+const url   = require('url');
+
+const SDK_VERSION = '6.0.0';
+
+class KasbahError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = 'KasbahError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+class Kasbah {
+  /**
+   * @param {object} opts
+   * @param {string} opts.apiKey     — API key (default: 'kg_desktop_builtin')
+   * @param {string} opts.baseUrl    — API base URL (default: 'https://api.bekasbah.com')
+   * @param {number} opts.timeout    — Request timeout ms (default: 10000)
+   * @param {boolean} opts.autoRetry — Retry on 5xx with backoff (default: true)
+   */
+  constructor(opts = {}) {
+    this.apiKey    = opts.apiKey   || 'kg_desktop_builtin';
+    this.baseUrl   = (opts.baseUrl || 'https://api.bekasbah.com').replace(/\/$/, '');
+    this.timeout   = opts.timeout  || 10_000;
+    this.autoRetry = opts.autoRetry !== false;
+    this._passportId = opts.passportId || null;
+
+    // Sub-clients
+    this.passport   = new PassportClient(this);
+    this.delegation = new DelegationClient(this);
+    this.honeytoken = new HoneytokenClient(this);
+    this.spend      = new SpendClient(this);
+  }
+
+  // ── Core govern ─────────────────────────────────────────────────────────
+
+  /**
+   * Govern a prompt/response through all 17 frontier systems.
+   * @param {object} body — { prompt?, response?, passportId?, delegationTokenId?, agent? }
+   * @returns {Promise<GovernResult>}
+   */
+  async govern(body = {}) {
+    if (this._passportId && !body.passportId) body.passportId = this._passportId;
+    return this._post('/v1/govern', body);
+  }
+
+  /**
+   * Scan text for threats (lightweight — no passport/delegation processing).
+   * @param {string} text
+   * @returns {Promise<ScanResult>}
+   */
+  async scan(text) {
+    const raw = await this._post('/v1/scan', { text });
+    // /v1/scan returns {threats, risk, risk_score, safe, latency_ms} — normalize
+    // to {decision, verdict, blocked, risk, threats, ...raw} so callers can rely on it.
+    const threats = raw.threats || raw.violations || [];
+    const risk    = raw.risk_score ?? raw.riskScore ?? raw.risk ?? 0;
+    const safe    = raw.safe !== false;
+    const verdict = raw.verdict || raw.decision || (safe ? 'ALLOW' : (risk < 0.7 ? 'WARN' : 'DENY'));
+    return Object.assign({}, raw, {
+      verdict,
+      decision: verdict,
+      blocked:  verdict === 'DENY',
+      risk,
+      threats
+    });
+  }
+
+  /**
+   * Explain why a prompt would be blocked/warned.
+   * @param {string} prompt
+   * @returns {Promise<ExplainResult>}
+   */
+  async explain(prompt) {
+    return this._post('/v1/explain', { prompt });
+  }
+
+  /**
+   * Evaluate an action against compliance + biometric-surveillance rule packs
+   * BEFORE it runs. Packs default to HIPAA, GDPR, SOC2 and BIOMETRIC_GUARD —
+   * the latter blocks facial-micro-expression / silent-speech / subvocal / BCI /
+   * QAI intent-surveillance vectors.
+   * @param {object} opts - { verb, target?, content?, packs? }
+   * @returns {Promise<{decision, reason, violations}>}
+   */
+  async checkCompliance({ verb, target = '', content = '', packs = 'HIPAA,GDPR,SOC2,BIOMETRIC_GUARD' } = {}) {
+    if (!verb) throw new KasbahError('checkCompliance requires a verb');
+    return this._post('/v1/algorithms/policy-engine/run', { verb, target, content, packs });
+  }
+
+  /**
+   * Defensive check: is this action a silent-speech / biometric surveillance
+   * attempt? Returns DENY (with cited BIOMETRIC_GUARD rule) if so. Kasbah never
+   * captures or analyzes facial/biometric data — it blocks those attempts.
+   * @param {object} opts - { verb?, target?, content? }
+   */
+  async guardBiometric({ verb = 'CAPTURE_VIDEO', target = 'facial_expression', content = '' } = {}) {
+    return this._post('/v1/algorithms/policy-engine/run', { verb, target, content, packs: 'BIOMETRIC_GUARD' });
+  }
+
+  // ── Governance Proxy (wrap an LLM turn) ─────────────────────────────────────
+
+  /**
+   * Govern a full LLM turn: pass message history + proposed tool calls, get a
+   * bounded advisory verdict (CLEAR / WARN / REQUIRE_APPROVAL) plus authoritative
+   * DENY for forbidden verbs / non-whitelisted domains. Includes multi-step
+   * attack-trajectory detection and a forward-secure audit receipt.
+   */
+  async governTurn({ messages = [], tools = [], clearance = 2 } = {}) {
+    return this._post('/v1/proxy/turn', { messages, tools, clearance });
+  }
+
+  /** List actions queued for human approval (REQUIRE_APPROVAL). */
+  async pendingApprovals() { return this._request('GET', '/v1/proxy/pending'); }
+
+  /** Approve a queued action (requires OPERATOR clearance ≥ 3). */
+  async approveAction(actionId, clearance = 3, approver = 'sdk') {
+    return this._post(`/v1/proxy/approve/${encodeURIComponent(actionId)}`, { clearance, approver });
+  }
+
+  /** Run a single advisory analyzer directly (detectgpt, intent, conformal, …). */
+  async advisory(module, payload = {}) {
+    return this._post(`/v1/advisory/${module}`, payload);
+  }
+
+  /** Access the kasbah-os Python engine (defensive live; offensive introspect-only). */
+  async kasbahOS(action, params = {}) {
+    if (action === 'govern') return this._post('/v1/kasbah-os/governance/turn', params);
+    const path = action === 'audit-verify' ? 'audit/verify' : action === 'offensive-info' ? 'offensive/info' : 'health';
+    return this._request('GET', `/v1/kasbah-os/${path}`);
+  }
+
+  // ── New v4.0 endpoints ──────────────────────────────────────────────────
+
+  /**
+   * Run Bell's Inequality AI text detection (CHSH S-value).
+   * S > 2.0 = AI-generated text with non-local semantic correlations.
+   */
+  async bells(text) {
+    return this._post('/v1/bells', { text });
+  }
+
+  /**
+   * Run Maqasid Ethics Framework (5-pillar Islamic ethics scoring).
+   */
+  async maqasid(text) {
+    return this._post('/v1/maqasid', { text });
+  }
+
+  /**
+   * Run RTP pipeline (f0–f5 governance stages, no side-effects).
+   */
+  async rtp(text, passportId = null) {
+    return this._post('/v1/rtp', { text, passportId });
+  }
+
+  /**
+   * Run Witt-Crystalline Cohomology Analysis.
+   * Novel mathematical framework: de Rham + crystalline + Witt vectors.
+   * Computes [ω] ∈ H^k → W(ω) = η → lim σ_n (perfect governance state).
+   */
+  async witt(data) {
+    return this._post('/v1/witt/analyze', { data });
+  }
+
+  /**
+   * Run Nexus unified engine (RTP + Kernel + Bell's + Detector in one call).
+   */
+  async nexus(text) {
+    return this._post('/v1/nexus', { text });
+  }
+
+  /**
+   * Verify and consume an execution ticket.
+   */
+  async verifyTicket(ticketId, hmac) {
+    return this._post('/v1/ticket/verify', { ticketId, hmac });
+  }
+
+  // ── System ──────────────────────────────────────────────────────────────
+
+  async health()     { return this._get('/v1/health'); }
+  async stats()      { return this._get('/v1/stats'); }
+  async audit(n=50)  { return this._get(`/v1/audit?limit=${n}`); }
+  async integrity()  { return this._get('/v1/integrity'); }
+  async forecast()   { return this._get('/v1/forecast'); }
+  async swarm()      { return this._get('/v1/swarm/status'); }
+  async auditChain() { return this._get('/v1/audit/chain'); }
+  async policy()     { return this._get('/v1/policy/active'); }
+
+  async setPolicy(policy) { return this._request('PUT', '/v1/policy/active', policy); }
+
+  // ── Products (all 16 engines) ─────────────────────────────────────────────
+
+  async productsStatus()        { return this._get('/v1/products/status'); }
+  async productScan(product, t) { return this._post(`/v1/products/${product}`, { text: t }); }
+
+  // ── Trinity ───────────────────────────────────────────────────────────────
+
+  async forgeKSI(text)       { return this._post('/v1/forge/ksi', { text }); }
+  async forgeConfig()         { return this._get('/v1/forge/config'); }
+  async nexusCommand(cmd)     { return this._post('/v1/nexus/command', { command: cmd }); }
+  async nexusStatus()         { return this._get('/v1/nexus/status'); }
+  async cortexExec(cmd)       { return this._post('/v1/cortex/exec', { command: cmd }); }
+
+  // ── Crypto ────────────────────────────────────────────────────────────────
+
+  async shamirSplit(s, n, k)  { return this._post('/v1/crypto/shamir/split', { secret: s, n, k }); }
+  async shamirCombine(shares) { return this._post('/v1/crypto/shamir/combine', { shares }); }
+  async mmrAppend(data)       { return this._post('/v1/crypto/mmr/append', { data }); }
+  async vdfEval(input, it)    { return this._post('/v1/crypto/vdf/eval', { input, iterations: it }); }
+
+  // ── Silent speech + Zero-trust audit ──────────────────────────────────────
+
+  async silentSpeech(opts)   { return this._post('/v1/silent-speech', opts); }
+  async auditReceipt(opts)   { return this._post('/v1/audit/receipt', opts); }
+
+  // ── Receipts (v3) ─────────────────────────────────────────────────────────
+
+  async signReceipt(opts)     { return this._post('/v1/sign', opts); }
+  async signReceiptV3(opts)   { return this._post('/v1/sign?v=3', opts); }
+  async verifyReceipt(opts)   { return this._post('/v1/receipt/verify', opts); }
+  async verifyReceiptBatch(opts) { return this._post('/v1/receipt/verify-batch', opts); }
+
+  // ── KasbahOS Python core ──────────────────────────────────────────────────
+
+  async kasbahOSIngest(opts)  { return this._post('/v1/kasbah-os/ingest', opts); }
+  async kasbahOSHealth()      { return this._get('/v1/kasbah-os/health'); }
+  async kasbahOSRetrieve(id)  { return this._post('/v1/kasbah-os/retrieve', { receipt_id: id }); }
+
+  // ── v4.0 Mythos-Class Engines ────────────────────────────────────────────
+
+  // Crypto
+  async kasbahOSKeygen()            { return this._post('/v1/kasbah-os/crypto/keygen'); }
+  async kasbahOSSign(opts)          { return this._post('/v1/kasbah-os/crypto/sign', opts); }
+  async kasbahOSVerify(opts)        { return this._post('/v1/kasbah-os/crypto/verify', opts); }
+  async kasbahOSPubkey(seedHex)     { return this._post('/v1/kasbah-os/crypto/pubkey', { seed_hex: seedHex }); }
+
+  // Audit / Zero-Trust
+  async kasbahOSAuditEvent(opts)    { return this._post('/v1/kasbah-os/audit/event', opts); }
+  async kasbahOSAuditReport()       { return this._get('/v1/kasbah-os/audit/report'); }
+  async kasbahOSAuditChain()        { return this._get('/v1/kasbah-os/audit/chain'); }
+  async kasbahOSAuditChainImport(chain) { return this._post('/v1/kasbah-os/audit/chain/import', { chain }); }
+  async kasbahOSAuditTrust(engine)  { return this._post('/v1/kasbah-os/audit/trust', { engine: engine || 'bridge' }); }
+
+  // Merkle
+  async kasbahOSMerkleBuild(entries)  { return this._post('/v1/kasbah-os/merkle/build', { entries }); }
+  async kasbahOSMerkleVerify(opts)    { return this._post('/v1/kasbah-os/merkle/verify', opts); }
+
+  // Binary Analysis
+  async kasbahOSBinaryAnalyze(hex, sampleId) {
+    return this._post('/v1/kasbah-os/binary/analyze', { binary_hex: hex, sample_id: sampleId || 'sdk' });
+  }
+
+  // Pipeline / Orchestration
+  async kasbahOSPipelineRun(hex, targetInfo) {
+    return this._post('/v1/kasbah-os/pipeline/run', { binary_hex: hex, target_info: targetInfo || {} });
+  }
+
+  // System
+  async kasbahOSModules()          { return this._get('/v1/kasbah-os/modules'); }
+  async kasbahOSPing()             { return this._get('/v1/kasbah-os/ping'); }
+
+  // ── Governance Proxy ─────────────────────────────────────────────────────
+
+  async kasbahOSGovernanceProcess(messages, tools, clearance) {
+    return this._post('/v1/kasbah-os/governance/process', {
+      messages: messages || [], tools: tools || [], clearance: clearance ?? 2
+    });
+  }
+  async kasbahOSGovernanceApprove(actionId) {
+    return this._post('/v1/kasbah-os/governance/approve/' + actionId);
+  }
+  async kasbahOSGovernanceHealth() { return this._get('/v1/kasbah-os/governance/health'); }
+
+  // ── Unified pipeline ──────────────────────────────────────────────────────
+
+  async pipelineUnified(text) { return this._post('/v1/pipeline/unified', { text }); }
+
+  // ── Keys ──────────────────────────────────────────────────────────────────
+
+  async keys()                { return this._get('/v1/keys'); }
+  async wellKnownKeys()       { return this._get('/.well-known/kasbah-keys.json'); }
+  async models()              { return this._get('/v1/models'); }
+
+  // ── Multi-MCP Governance ──────────────────────────────────────────────────
+
+  async mcpServers()               { return this._get('/v1/mcp/servers'); }
+  async mcpCreateTeam(name, admin) { return this._post('/v1/mcp/teams', { name, adminPassportId: admin }); }
+  async mcpAddMember(teamId, pid)  { return this._post(`/v1/mcp/teams/${teamId}/members`, { passportId: pid }); }
+  async mcpAddServer(teamId, mcp)  { return this._post(`/v1/mcp/teams/${teamId}/mcp`, { mcpServer: mcp }); }
+  async mcpPolicies()              { return this._get('/v1/mcp/policies'); }
+  async mcpApplyPolicy(teamId, pol){ return this._post(`/v1/mcp/teams/${teamId}/policies`, { policyId: pol }); }
+
+  // ── Proxy helpers ───────────────────────────────────────────────────────
+
+  /**
+   * Proxy an OpenAI chat completion through Kasbah governance.
+   * Drop-in replacement for OpenAI's /v1/chat/completions
+   * @param {object} body - OpenAI chat completion request body
+   * @param {string} upstreamKey - Your OpenAI API key
+   * @param {object} [options]
+   * @returns OpenAI-compatible response with _kasbahReceipt captured
+   */
+  async proxyOpenAI(body, upstreamKey, options = {}) {
+    const extraHeaders = { 'Authorization': `Bearer ${upstreamKey}` };
+    const { body: json, headers } = await this._requestRaw(
+      'POST', '/v1/proxy/openai/v1/chat/completions', body, extraHeaders
+    );
+    return { ...json, _kasbahReceipt: headers['x-kasbah-receipt'] || null };
+  }
+
+  /**
+   * Proxy an Anthropic messages call through Kasbah governance.
+   * Drop-in replacement for Anthropic's /v1/messages
+   * @param {object} body - Anthropic messages request body
+   * @param {string} upstreamKey - Your Anthropic API key
+   * @param {object} [options]
+   * @returns Anthropic-compatible response with _kasbahReceipt captured
+   */
+  async proxyAnthropic(body, upstreamKey, options = {}) {
+    const extraHeaders = { 'x-api-key': upstreamKey };
+    const { body: json, headers } = await this._requestRaw(
+      'POST', '/v1/proxy/anthropic/v1/messages', body, extraHeaders
+    );
+    return { ...json, _kasbahReceipt: headers['x-kasbah-receipt'] || null };
+  }
+
+  // ── Budget management ───────────────────────────────────────────────────
+
+  /**
+   * Get token/cost usage for a passport.
+   * @param {string} passportId
+   */
+  async getUsage(passportId) {
+    return this._request('GET', `/v1/usage/${passportId}`);
+  }
+
+  /**
+   * Set token/cost budget policy for a passport.
+   * @param {string} passportId
+   * @param {object} policy - { maxTokensPerMin?, maxTokensPerDay?, maxCostCentsPerDay? }
+   */
+  async setBudget(passportId, policy) {
+    return this._request('POST', `/v1/budgets/${passportId}`, policy);
+  }
+
+  /**
+   * Get current budget policy for a passport.
+   * @param {string} passportId
+   */
+  async getBudget(passportId) {
+    return this._request('GET', `/v1/budgets/${passportId}`);
+  }
+
+  // ── Agentic Layer ───────────────────────────────────────────────────────
+
+  /**
+   * Create a governed agent session.
+   * Returns { sessionId, agentId, status, manifest, ... }
+   * @param {object} opts
+   * @param {string} opts.agentId      - human-readable agent name
+   * @param {string} opts.passportId   - Kasbah passport for this agent
+   * @param {string} opts.goal         - agent objective (logged)
+   * @param {object} opts.manifest     - { allowedTools, maxTokens, maxCostCents, ... }
+   */
+  async createAgent(opts = {}) {
+    return this._request('POST', '/v1/agents', opts);
+  }
+
+  /**
+   * Govern a tool call for an active session.
+   * Call this BEFORE executing any tool.
+   * Returns { ok, verdict, reason?, receipt?, riskScore }
+   * @param {string} sessionId
+   * @param {string} tool        - tool name, e.g. 'bash', 'write_file'
+   * @param {object} args        - raw args object
+   * @param {string} argsText    - flattened text for content scanning
+   */
+  async governTool(sessionId, tool, args = {}, argsText = '') {
+    return this._request('POST', `/v1/agents/${sessionId}/tool`, { tool, args, argsText });
+  }
+
+  /**
+   * Scan a tool result for injected instructions.
+   * Call this AFTER receiving a tool result, before feeding it back to the agent.
+   * Returns { ok, verdict?, reason?, riskScore }
+   * @param {string} sessionId
+   * @param {string} tool
+   * @param {string} result  - raw tool output text
+   */
+  async scanToolResult(sessionId, tool, result) {
+    return this._request('POST', `/v1/agents/${sessionId}/tool-result`, { tool, result });
+  }
+
+  /**
+   * Record a conversation turn for budget and chain tracking.
+   * @param {string} sessionId
+   * @param {string} role        - 'user' | 'assistant' | 'system' | 'tool'
+   * @param {string} content
+   * @param {number} tokens      - token count for this turn
+   * @param {number} costCents   - cost in cents for this turn
+   */
+  async recordTurn(sessionId, role, content, tokens = 0, costCents = 0) {
+    return this._request('POST', `/v1/agents/${sessionId}/turn`, { role, content, tokens, costCents });
+  }
+
+  /**
+   * Get the current state of a governed session.
+   * @param {string} sessionId
+   */
+  async getAgent(sessionId) {
+    return this._request('GET', `/v1/agents/${sessionId}`);
+  }
+
+  /**
+   * List all active governed sessions.
+   */
+  async listAgents() {
+    return this._request('GET', '/v1/agents');
+  }
+
+  /**
+   * Emergency kill: immediately stop a governed agent session.
+   * @param {string} sessionId
+   * @param {string} reason
+   */
+  async killAgent(sessionId, reason = 'manual') {
+    return this._request('DELETE', `/v1/agents/${sessionId}`, { reason });
+  }
+
+  /**
+   * Mark a session as completed normally.
+   * @param {string} sessionId
+   */
+  async completeAgent(sessionId) {
+    return this._request('POST', `/v1/agents/${sessionId}/complete`);
+  }
+
+  /**
+   * Wrap an OpenAI client so every API call is auto-governed.
+   *
+   * The wrapped client is a Proxy — it has the exact same interface as the
+   * original. All method calls transparently go through governTool() first.
+   *
+   * Usage:
+   *   const session = await kasbah.createAgent({ agentId: 'my-bot', ... });
+   *   const governed = kasbah.wrapOpenAI(openai, session.sessionId);
+   *   // now governed.chat.completions.create(...) is auto-governed
+   *
+   * @param {object} openaiClient  - OpenAI SDK client instance
+   * @param {string} sessionId
+   */
+  wrapOpenAI(openaiClient, sessionId) {
+    return this._wrapClient(openaiClient, sessionId, 'openai');
+  }
+
+  /**
+   * Wrap an Anthropic client so every API call is auto-governed.
+   * @param {object} anthropicClient - Anthropic SDK client instance
+   * @param {string} sessionId
+   */
+  wrapAnthropic(anthropicClient, sessionId) {
+    return this._wrapClient(anthropicClient, sessionId, 'anthropic');
+  }
+
+  _wrapClient(client, sessionId, type) {
+    const self = this;
+    const intercept = async (methodPath, originalFn, args) => {
+      // Extract text for governance
+      const firstArg = args[0] || {};
+      const messages = firstArg.messages || firstArg.prompt || '';
+      const argsText = typeof messages === 'string'
+        ? messages
+        : Array.isArray(messages)
+          ? messages.map(m => (typeof m.content === 'string' ? m.content : JSON.stringify(m.content))).join('\n')
+          : JSON.stringify(firstArg).slice(0, 800);
+
+      const decision = await self.governTool(sessionId, methodPath, firstArg, argsText);
+      if (!decision.ok) {
+        const err    = new Error(`KasbahOS blocked: ${decision.reason}`);
+        err.kasbah   = decision;
+        err.verdict  = decision.verdict;
+        throw err;
+      }
+
+      // Execute the real call
+      const result = await originalFn.apply(client, args);
+
+      // Scan response for injection
+      const responseText = type === 'openai'
+        ? result?.choices?.[0]?.message?.content || ''
+        : result?.content?.[0]?.text || '';
+      if (responseText) {
+        await self.scanToolResult(sessionId, methodPath, responseText);
+      }
+
+      // Record token usage
+      const usage  = result?.usage;
+      const tokens = usage
+        ? (usage.total_tokens || (usage.input_tokens || 0) + (usage.output_tokens || 0))
+        : 0;
+      if (tokens > 0) {
+        await self.recordTurn(sessionId, 'assistant', responseText.slice(0, 400), tokens, 0);
+      }
+
+      return result;
+    };
+
+    // Build a recursive proxy
+    const makeProxy = (target, pathPrefix) => new Proxy(target, {
+      get(inner, prop) {
+        const val = inner[prop];
+        if (typeof val === 'function') {
+          return (...args) => intercept(`${pathPrefix}.${String(prop)}`, val, args);
+        }
+        if (val && typeof val === 'object') {
+          return makeProxy(val, `${pathPrefix}.${String(prop)}`);
+        }
+        return val;
+      },
+    });
+
+    return makeProxy(client, type);
+  }
+
+  // ── HTTP internals ──────────────────────────────────────────────────────
+
+  async _get(path)         { return this._request('GET', path); }
+  async _post(path, body)  { return this._request('POST', path, body); }
+
+  async _request(method, path, body = null, attempt = 1) {
+    const parsed  = new url.URL(this.baseUrl + path);
+    const isHttps = parsed.protocol === 'https:';
+    const lib     = isHttps ? https : http;
+
+    const bodyStr = body ? JSON.stringify(body) : null;
+    const headers = {
+      'Content-Type':  'application/json',
+      'x-api-key':     this.apiKey,
+      'x-kasbah-sdk':  `node/${SDK_VERSION}`,
+    };
+    if (bodyStr) headers['Content-Length'] = Buffer.byteLength(bodyStr);
+
+    return new Promise((resolve, reject) => {
+      const req = lib.request({
+        hostname: parsed.hostname,
+        port:     parsed.port || (isHttps ? 443 : 80),
+        path:     parsed.pathname + parsed.search,
+        method,
+        headers,
+        timeout:  this.timeout,
+      }, (res) => {
+        let data = '';
+        res.on('data', chunk => { data += chunk; });
+        res.on('end',  () => {
+          try {
+            const json = JSON.parse(data);
+            if (res.statusCode >= 200 && res.statusCode < 300) {
+              resolve(json);
+            } else if (res.statusCode >= 500 && this.autoRetry && attempt < 3) {
+              setTimeout(() => this._request(method, path, body, attempt + 1).then(resolve).catch(reject),
+                Math.pow(2, attempt) * 200);
+            } else {
+              reject(new KasbahError(json.error || `HTTP ${res.statusCode}`, res.statusCode, json));
+            }
+          } catch (e) {
+            reject(new KasbahError('Invalid JSON response', res.statusCode, data));
+          }
+        });
+      });
+
+      req.on('error',   reject);
+      req.on('timeout', () => { req.destroy(); reject(new KasbahError('Request timeout', 408)); });
+      if (bodyStr) req.write(bodyStr);
+      req.end();
+    });
+  }
+
+  /**
+   * Like _request but returns { body, headers } so callers can inspect
+   * response headers (e.g. x-kasbah-receipt for proxy endpoints).
+   * @param {string} method
+   * @param {string} path
+   * @param {object|null} body
+   * @param {object} [extraHeaders] - Additional headers to merge in (e.g. Authorization)
+   * @param {number} [attempt]
+   * @returns {Promise<{ body: object, headers: object }>}
+   */
+  async _requestRaw(method, path, body = null, extraHeaders = {}, attempt = 1) {
+    const parsed  = new url.URL(this.baseUrl + path);
+    const isHttps = parsed.protocol === 'https:';
+    const lib     = isHttps ? https : http;
+
+    const bodyStr = body ? JSON.stringify(body) : null;
+    const headers = {
+      'Content-Type':  'application/json',
+      'x-api-key':     this.apiKey,
+      'x-kasbah-sdk':  `node/${SDK_VERSION}`,
+      ...extraHeaders,
+    };
+    if (bodyStr) headers['Content-Length'] = Buffer.byteLength(bodyStr);
+
+    return new Promise((resolve, reject) => {
+      const req = lib.request({
+        hostname: parsed.hostname,
+        port:     parsed.port || (isHttps ? 443 : 80),
+        path:     parsed.pathname + parsed.search,
+        method,
+        headers,
+        timeout:  this.timeout,
+      }, (res) => {
+        let data = '';
+        res.on('data', chunk => { data += chunk; });
+        res.on('end',  () => {
+          try {
+            const json = JSON.parse(data);
+            if (res.statusCode >= 200 && res.statusCode < 300) {
+              resolve({ body: json, headers: res.headers });
+            } else if (res.statusCode >= 500 && this.autoRetry && attempt < 3) {
+              setTimeout(() => this._requestRaw(method, path, body, extraHeaders, attempt + 1).then(resolve).catch(reject),
+                Math.pow(2, attempt) * 200);
+            } else {
+              reject(new KasbahError(json.error || `HTTP ${res.statusCode}`, res.statusCode, json));
+            }
+          } catch (e) {
+            reject(new KasbahError('Invalid JSON response', res.statusCode, data));
+          }
+        });
+      });
+
+      req.on('error',   reject);
+      req.on('timeout', () => { req.destroy(); reject(new KasbahError('Request timeout', 408)); });
+      if (bodyStr) req.write(bodyStr);
+      req.end();
+    });
+  }
+}
+
+// ── Sub-clients ──────────────────────────────────────────────────────────────
+
+class PassportClient {
+  constructor(k) { this._k = k; }
+  async issue(opts = {})    { return this._k._post('/v1/passport/issue', opts); }
+  async list()              { return this._k._get('/v1/passport/list'); }
+  async get(id)             { return this._k._get(`/v1/passport/${id}`); }
+  async revoke(id)          { return this._k._request('DELETE', `/v1/passport/${id}`); }
+  async spend(id)           { return this._k._get(`/v1/passport/${id}/spend`); }
+  async setSpendPolicy(id, policy) { return this._k._post(`/v1/passport/${id}/spend/policy`, policy); }
+}
+
+class DelegationClient {
+  constructor(k) { this._k = k; }
+  async issue(opts = {})    { return this._k._post('/v1/delegation/issue', opts); }
+  async verify(tokenId)     { return this._k._post('/v1/delegation/verify', { tokenId }); }
+}
+
+class HoneytokenClient {
+  constructor(k) { this._k = k; }
+  async list()              { return this._k._get('/v1/honeytokens'); }
+  async deploy(service)     { return this._k._post('/v1/honeytokens/deploy', { service }); }
+  async check(text)         { return this._k._post('/v1/honeytokens/check', { text }); }
+}
+
+class SpendClient {
+  constructor(k) { this._k = k; }
+  async get(passportId)     { return this._k._get(`/v1/passport/${passportId}/spend`); }
+  async setPolicy(passportId, policy) { return this._k._post(`/v1/passport/${passportId}/spend/policy`, policy); }
+}
+
+module.exports = Kasbah;
+module.exports.Kasbah    = Kasbah;
+module.exports.KasbahError = KasbahError;
+// Public-key receipt v2 — world-proof Ed25519 verification.
+module.exports.receipt   = require('./receipt');