@nullbridge/sdk 1.0.0

package/README.md

@@ -0,0 +1,232 @@
+# @nullbridge/sdk
+
+**AI Agent Identity Governance for Node.js**
+
+NullBridge gives your AI agents a cryptographic identity, secure credential vault, continuous audit trail, and behavioral anomaly detection — in three lines of code.
+
+---
+
+## Installation
+
+```bash
+npm install @nullbridge/sdk
+```
+
+---
+
+## Quick Start
+
+```js
+const { NullBridge } = require('@nullbridge/sdk');
+
+const nb = new NullBridge({
+  licenseKey: process.env.NULLBRIDGE_LICENSE_KEY,
+});
+
+await nb.init();
+
+const agent = await nb.agents.register({
+  name:   'claims-processor',
+  type:   'llm',
+  model:  'gpt-4o',
+  scopes: ['read:claims', 'write:reports'],
+});
+```
+
+That's it. NullBridge validates your license on startup, registers your agent with a cryptographic identity, and begins monitoring automatically.
+
+---
+
+## Configuration
+
+```js
+const nb = new NullBridge({
+  licenseKey:    process.env.NULLBRIDGE_LICENSE_KEY, // required
+  serverUrl:     'https://nullbridge-license-server-production.up.railway.app', // default
+  apiUrl:        'https://api.nullbridge.ai',        // default
+  skipLicense:   false,   // set true for local development only
+  autoShutdown:  true,    // shut down process if license is revoked
+  checkInterval: 86400000, // license check interval in ms (default: 24 hours)
+  debug:         false,   // enable verbose logging
+  siem: {
+    endpoint: 'https://your-siem.com/ingest', // optional
+    format:   'json', // 'json' | 'cef' | 'leef'
+  },
+});
+```
+
+---
+
+## Environment Variables
+
+```bash
+NULLBRIDGE_LICENSE_KEY=NB-XXXX-XXXX-XXXX-XXXX
+```
+
+Contact brian@nullbridge.ai to obtain a license key.
+
+---
+
+## API Reference
+
+### `nb.init()`
+Initialize NullBridge. Call once on application startup before serving traffic.
+Validates license and starts background services.
+
+```js
+await nb.init();
+```
+
+---
+
+### `nb.agents`
+
+#### `nb.agents.register(options)`
+Register an AI agent with NullBridge.
+
+```js
+const agent = await nb.agents.register({
+  name:   'fraud-detector',    // required — human readable name
+  type:   'llm',               // required — 'llm' | 'rpa' | 'workflow' | 'custom'
+  model:  'claude-3-5-sonnet', // optional
+  scopes: ['read:transactions', 'write:alerts'], // optional
+  metadata: { team: 'risk' },  // optional
+});
+```
+
+#### `agent.logAction(action, details)`
+Log an action this agent performed.
+
+```js
+await agent.logAction('analyze_transaction', { txId: 'TX-1234', amount: 5000 });
+```
+
+#### `agent.hasScope(scope)`
+Check if agent has a specific permission.
+
+```js
+if (!agent.hasScope('write:alerts')) throw new Error('Not authorized');
+```
+
+#### `agent.deregister()`
+Deregister agent and revoke its identity.
+
+---
+
+### `nb.credentials`
+
+#### `nb.credentials.store(options)`
+Store a credential securely (AES-256-GCM encrypted).
+
+```js
+const credId = await nb.credentials.store({
+  agentId: agent.id,
+  name:    'openai-api-key',
+  value:   process.env.OPENAI_API_KEY,
+  type:    'api_key', // 'api_key' | 'oauth_token' | 'password' | 'certificate'
+  ttl:     86400,     // optional: expire after 24 hours
+});
+```
+
+#### `nb.credentials.get(credId)`
+Retrieve a credential value.
+
+```js
+const apiKey = await nb.credentials.get(credId);
+```
+
+#### `nb.credentials.rotate(credId, newValue)`
+Rotate a credential and log the rotation in audit trail.
+
+```js
+await nb.credentials.rotate(credId, newApiKey);
+```
+
+#### `nb.credentials.revoke(credId)`
+Permanently revoke a credential.
+
+---
+
+### `nb.audit`
+
+#### `nb.audit.log(event)`
+Log an agent action to the audit trail.
+
+```js
+nb.audit.log({
+  agentId:   agent.id,
+  agentName: agent.name,
+  action:    'process_claim',         // required
+  resource:  'claim:CLM-20240001',    // optional
+  outcome:   'success',               // 'success' | 'failure' | 'blocked'
+  details:   { amount: 15000 },       // optional
+  ip:        req.ip,                  // optional
+  duration:  1240,                    // optional: ms
+});
+```
+
+#### `nb.audit.logViolation(agentId, agentName, action, reason)`
+Log a policy violation (outcome is automatically set to 'blocked').
+
+```js
+nb.audit.logViolation(agent.id, agent.name, 'delete_record', 'scope_denied');
+```
+
+---
+
+### `nb.anomaly`
+
+#### `nb.anomaly.record(agentId, metric, value)`
+Record a behavioral metric. NullBridge builds a statistical baseline and alerts on deviations.
+
+```js
+nb.anomaly.record(agent.id, 'api_calls_per_minute', 14);
+nb.anomaly.record(agent.id, 'tokens_used',          3200);
+nb.anomaly.record(agent.id, 'unique_endpoints',     3);
+```
+
+#### `nb.anomaly.onAlert(handler)`
+Register a callback for anomaly alerts.
+
+```js
+nb.anomaly.onAlert(alert => {
+  console.error(`Anomaly: ${alert.agentId} — ${alert.metric} (z=${alert.zScore})`);
+  // Send to PagerDuty, Slack, etc.
+});
+```
+
+#### `nb.anomaly.check(agentId, metric, value)`
+Check if a value is anomalous without recording it.
+
+```js
+const { anomalous, zScore } = nb.anomaly.check(agent.id, 'api_calls', 500);
+if (anomalous) console.warn('Unusual API call volume');
+```
+
+---
+
+### `nb.shutdown()`
+Gracefully shut down — flushes audit logs and stops background services.
+
+```js
+process.on('SIGTERM', async () => {
+  await nb.shutdown();
+  process.exit(0);
+});
+```
+
+---
+
+## License
+
+This software is proprietary and confidential. Use requires a valid NullBridge license key.
+Contact brian@nullbridge.ai for licensing.
+
+**NullBridge Technologies**
+brian@nullbridge.ai | nullbridge.ai
+
+---
+
+CONFIDENTIALITY & IP NOTICE: This software and documentation contain proprietary and confidential
+information belonging to NullBridge Technologies. Protected under applicable intellectual property
+laws. Unauthorized use, disclosure, or distribution is strictly prohibited.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@nullbridge/sdk",
+  "version": "1.0.0",
+  "description": "NullBridge AI Agent Identity Governance SDK",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "license": "UNLICENSED",
+  "author": "NullBridge Technologies <brian@nullbridge.ai>",
+  "homepage": "https://nullbridge.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bwes03-afk/nullbridge-sdk"
+  },
+  "keywords": [
+    "ai", "agents", "identity", "governance", "iam",
+    "security", "audit", "nullbridge", "license"
+  ],
+  "engines": { "node": ">=16.0.0" },
+  "files": ["src/", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "node examples/basic.js",
+    "prepublishOnly": "node -e \"console.log('Publishing @nullbridge/sdk...')\""
+  },
+  "dependencies": {}
+}

package/src/agents.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * AgentRegistry — register, manage, and monitor AI agents
+ */
+class AgentRegistry {
+  constructor(config, http) {
+    this._config = config;
+    this._http   = http;
+    this._agents = new Map(); // local cache
+  }
+
+  /**
+   * Register a new AI agent with NullBridge.
+   *
+   * @param {object} options
+   * @param {string} options.name        - Human-readable agent name (e.g. 'claims-processor')
+   * @param {string} options.type        - Agent type: 'llm' | 'rpa' | 'workflow' | 'custom'
+   * @param {string} [options.model]     - Model name (e.g. 'gpt-4o', 'claude-3-5-sonnet')
+   * @param {string[]} [options.scopes]  - What this agent is allowed to do (e.g. ['read:claims', 'write:reports'])
+   * @param {object} [options.metadata]  - Any additional metadata
+   * @returns {Promise<Agent>}
+   */
+  async register(options = {}) {
+    if (!options.name) throw new Error('[NullBridge] agent.name is required');
+    if (!options.type) throw new Error('[NullBridge] agent.type is required');
+
+    const agentId = this._generateAgentId(options.name);
+
+    const payload = {
+      id:         agentId,
+      name:       options.name,
+      type:       options.type,
+      model:      options.model     || null,
+      scopes:     options.scopes    || [],
+      metadata:   options.metadata  || {},
+      sdk_version: '1.0.0',
+      registered_at: Math.floor(Date.now() / 1000),
+    };
+
+    try {
+      const { status, body } = await this._http.post(
+        this._config.apiUrl,
+        '/sdk/agents/register',
+        { license_key: this._config.licenseKey, agent: payload }
+      );
+
+      const agent = status === 200 || status === 201
+        ? { ...payload, ...body.agent, _registered: true }
+        : { ...payload, _registered: false, _local: true };
+
+      this._agents.set(agentId, agent);
+      console.info(`[NullBridge] Agent registered: ${options.name} (${agentId})`);
+      return new Agent(agent, this._config, this._http);
+
+    } catch (err) {
+      // API unreachable — register locally and continue
+      const agent = { ...payload, _registered: false, _local: true };
+      this._agents.set(agentId, agent);
+      console.warn(`[NullBridge] Agent registered locally (API unreachable): ${options.name}`);
+      return new Agent(agent, this._config, this._http);
+    }
+  }
+
+  /**
+   * Get all registered agents
+   */
+  async list() {
+    try {
+      const { status, body } = await this._http.get(
+        this._config.apiUrl,
+        `/sdk/agents?license_key=${encodeURIComponent(this._config.licenseKey)}`
+      );
+      return status === 200 ? body.agents : Array.from(this._agents.values());
+    } catch {
+      return Array.from(this._agents.values());
+    }
+  }
+
+  /**
+   * Get a registered agent by ID
+   */
+  get(agentId) {
+    const agent = this._agents.get(agentId);
+    if (!agent) return null;
+    return new Agent(agent, this._config, this._http);
+  }
+
+  _generateAgentId(name) {
+    const slug = name.toLowerCase().replace(/[^a-z0-9]/g, '-');
+    const hash = crypto.createHash('sha256')
+      .update(this._config.licenseKey + name + Date.now())
+      .digest('hex')
+      .slice(0, 8);
+    return `agent-${slug}-${hash}`;
+  }
+}
+
+/**
+ * Agent — represents a single registered AI agent
+ */
+class Agent {
+  constructor(data, config, http) {
+    this._data   = data;
+    this._config = config;
+    this._http   = http;
+
+    // Expose agent properties
+    this.id       = data.id;
+    this.name     = data.name;
+    this.type     = data.type;
+    this.model    = data.model;
+    this.scopes   = data.scopes || [];
+    this.metadata = data.metadata || {};
+  }
+
+  /**
+   * Log an action this agent performed (creates an audit trail entry)
+   *
+   * @param {string} action      - What the agent did (e.g. 'read_claim', 'send_email')
+   * @param {object} [details]   - Additional context
+   */
+  async logAction(action, details = {}) {
+    try {
+      await this._http.post(
+        this._config.apiUrl,
+        '/sdk/audit',
+        {
+          license_key: this._config.licenseKey,
+          agent_id:    this.id,
+          agent_name:  this.name,
+          action,
+          details,
+          timestamp:   Math.floor(Date.now() / 1000),
+        }
+      );
+    } catch {
+      // Never throw from audit logging — don't break agent operation
+    }
+  }
+
+  /**
+   * Check if this agent has a specific scope/permission
+   *
+   * @param {string} scope - e.g. 'write:claims'
+   * @returns {boolean}
+   */
+  hasScope(scope) {
+    return this.scopes.includes(scope) || this.scopes.includes('*');
+  }
+
+  /**
+   * Update agent metadata or status
+   */
+  async update(updates = {}) {
+    try {
+      await this._http.post(
+        this._config.apiUrl,
+        `/sdk/agents/${this.id}/update`,
+        { license_key: this._config.licenseKey, ...updates }
+      );
+      Object.assign(this._data, updates);
+    } catch {}
+  }
+
+  /**
+   * Deregister this agent — revokes its identity and credentials
+   */
+  async deregister() {
+    try {
+      await this._http.post(
+        this._config.apiUrl,
+        `/sdk/agents/${this.id}/deregister`,
+        { license_key: this._config.licenseKey }
+      );
+      console.info(`[NullBridge] Agent deregistered: ${this.name}`);
+    } catch (err) {
+      console.warn(`[NullBridge] Could not deregister agent remotely: ${err.message}`);
+    }
+  }
+
+  toJSON() {
+    return {
+      id: this.id, name: this.name, type: this.type,
+      model: this.model, scopes: this.scopes, metadata: this.metadata,
+    };
+  }
+}
+
+module.exports = { AgentRegistry, Agent };

package/src/anomaly.js

@@ -0,0 +1,148 @@
+'use strict';
+
+/**
+ * AnomalyDetector — behavioral baseline monitoring for AI agents
+ * Detects unusual patterns and alerts when agents deviate from normal behavior
+ */
+class AnomalyDetector {
+  constructor(config, http) {
+    this._config   = config;
+    this._http     = http;
+    this._baselines = new Map(); // agentId -> baseline metrics
+    this._handlers  = [];        // alert handlers
+  }
+
+  /**
+   * Record a metric for an agent — used to build behavioral baseline
+   *
+   * @param {string} agentId
+   * @param {string} metric      - e.g. 'api_calls_per_minute', 'tokens_used', 'unique_endpoints'
+   * @param {number} value
+   */
+  record(agentId, metric, value) {
+    if (!this._baselines.has(agentId)) {
+      this._baselines.set(agentId, {});
+    }
+
+    const baseline = this._baselines.get(agentId);
+    if (!baseline[metric]) {
+      baseline[metric] = { samples: [], mean: 0, stddev: 0, count: 0 };
+    }
+
+    const m = baseline[metric];
+    m.samples.push({ value, ts: Date.now() });
+
+    // Keep last 100 samples
+    if (m.samples.length > 100) m.samples.shift();
+
+    // Recalculate mean and stddev
+    const values = m.samples.map(s => s.value);
+    m.count  = values.length;
+    m.mean   = values.reduce((a, b) => a + b, 0) / m.count;
+    m.stddev = Math.sqrt(values.map(v => Math.pow(v - m.mean, 2)).reduce((a, b) => a + b, 0) / m.count);
+
+    // Check for anomaly (> 3 standard deviations from mean)
+    if (m.count >= 10 && m.stddev > 0) {
+      const zScore = Math.abs((value - m.mean) / m.stddev);
+      if (zScore > 3) {
+        this._triggerAlert(agentId, metric, value, m.mean, zScore);
+      }
+    }
+  }
+
+  /**
+   * Check if a specific value is anomalous for an agent/metric
+   *
+   * @param {string} agentId
+   * @param {string} metric
+   * @param {number} value
+   * @returns {{ anomalous: boolean, zScore: number, mean: number }}
+   */
+  check(agentId, metric, value) {
+    const baseline = this._baselines.get(agentId);
+    if (!baseline || !baseline[metric] || baseline[metric].count < 10) {
+      return { anomalous: false, zScore: 0, mean: value, reason: 'insufficient_data' };
+    }
+
+    const m = baseline[metric];
+    const zScore = m.stddev > 0 ? Math.abs((value - m.mean) / m.stddev) : 0;
+
+    return {
+      anomalous: zScore > 3,
+      zScore:    Math.round(zScore * 100) / 100,
+      mean:      Math.round(m.mean * 100) / 100,
+      stddev:    Math.round(m.stddev * 100) / 100,
+      samples:   m.count,
+    };
+  }
+
+  /**
+   * Register an alert handler — called when anomaly is detected
+   *
+   * @param {function} handler - function(alert) where alert = { agentId, metric, value, mean, zScore }
+   */
+  onAlert(handler) {
+    this._handlers.push(handler);
+    return this; // chainable
+  }
+
+  /**
+   * Get baseline metrics for an agent
+   */
+  getBaseline(agentId) {
+    const baseline = this._baselines.get(agentId);
+    if (!baseline) return null;
+
+    const result = {};
+    for (const [metric, data] of Object.entries(baseline)) {
+      result[metric] = {
+        mean:    Math.round(data.mean * 100) / 100,
+        stddev:  Math.round(data.stddev * 100) / 100,
+        samples: data.count,
+      };
+    }
+    return result;
+  }
+
+  /**
+   * Reset baseline for an agent (e.g. after a known behavior change)
+   */
+  resetBaseline(agentId, metric = null) {
+    if (metric) {
+      const baseline = this._baselines.get(agentId);
+      if (baseline) delete baseline[metric];
+    } else {
+      this._baselines.delete(agentId);
+    }
+  }
+
+  async _triggerAlert(agentId, metric, value, mean, zScore) {
+    const alert = {
+      agentId,
+      metric,
+      value,
+      mean:      Math.round(mean * 100) / 100,
+      zScore:    Math.round(zScore * 100) / 100,
+      severity:  zScore > 6 ? 'critical' : zScore > 4 ? 'high' : 'medium',
+      timestamp: Math.floor(Date.now() / 1000),
+    };
+
+    console.warn(`[NullBridge] Anomaly detected — agent: ${agentId}, metric: ${metric}, value: ${value}, mean: ${mean.toFixed(2)}, z-score: ${zScore.toFixed(2)}`);
+
+    // Call registered handlers
+    for (const handler of this._handlers) {
+      try { handler(alert); } catch {}
+    }
+
+    // Send to NullBridge API
+    try {
+      await this._http.post(
+        this._config.apiUrl,
+        '/sdk/anomalies',
+        { license_key: this._config.licenseKey, alert }
+      );
+    } catch {}
+  }
+}
+
+module.exports = { AnomalyDetector };

package/src/audit.js

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * AuditLogger — tamper-evident audit trail for all AI agent actions
+ */
+class AuditLogger {
+  constructor(config, http) {
+    this._config = config;
+    this._http   = http;
+    this._queue  = [];
+    this._flushing = false;
+
+    // Flush queue every 30 seconds
+    this._flushTimer = setInterval(() => this.flush(), 30 * 1000);
+    if (this._flushTimer.unref) this._flushTimer.unref();
+  }
+
+  /**
+   * Log an audit event
+   *
+   * @param {object} event
+   * @param {string} event.agentId      - Agent that performed the action
+   * @param {string} event.agentName    - Agent name
+   * @param {string} event.action       - Action performed (e.g. 'read_claim', 'send_email', 'call_api')
+   * @param {string} [event.resource]   - Resource acted on (e.g. 'claim:CLM-1234')
+   * @param {string} [event.outcome]    - 'success' | 'failure' | 'blocked'
+   * @param {object} [event.details]    - Additional context
+   * @param {string} [event.ip]         - IP address if applicable
+   * @param {number} [event.duration]   - Duration in ms
+   */
+  log(event = {}) {
+    if (!event.agentId)   throw new Error('[NullBridge] audit.log: agentId is required');
+    if (!event.action)    throw new Error('[NullBridge] audit.log: action is required');
+
+    const entry = {
+      id:          this._generateEventId(),
+      license_key: this._config.licenseKey,
+      agent_id:    event.agentId,
+      agent_name:  event.agentName  || 'unknown',
+      action:      event.action,
+      resource:    event.resource   || null,
+      outcome:     event.outcome    || 'success',
+      details:     event.details    || {},
+      ip:          event.ip         || null,
+      duration_ms: event.duration   || null,
+      timestamp:   Math.floor(Date.now() / 1000),
+    };
+
+    this._queue.push(entry);
+
+    // Flush immediately for critical events
+    if (event.outcome === 'failure' || event.outcome === 'blocked') {
+      this.flush();
+    }
+
+    return entry.id;
+  }
+
+  /**
+   * Log a policy violation — automatically sets outcome to 'blocked'
+   */
+  logViolation(agentId, agentName, action, reason, details = {}) {
+    return this.log({
+      agentId, agentName, action,
+      outcome: 'blocked',
+      details: { reason, ...details },
+    });
+  }
+
+  /**
+   * Flush queued events to NullBridge API
+   */
+  async flush() {
+    if (this._flushing || this._queue.length === 0) return;
+    this._flushing = true;
+
+    const batch = this._queue.splice(0, 100); // max 100 per flush
+
+    try {
+      await this._http.post(
+        this._config.apiUrl,
+        '/sdk/audit/batch',
+        { events: batch }
+      );
+    } catch {
+      // Put events back in queue if flush fails
+      this._queue.unshift(...batch);
+    } finally {
+      this._flushing = false;
+    }
+  }
+
+  /**
+   * Get queued (unflushed) events
+   */
+  getQueue() {
+    return [...this._queue];
+  }
+
+  /**
+   * Stop the flush timer
+   */
+  stop() {
+    if (this._flushTimer) clearInterval(this._flushTimer);
+  }
+
+  _generateEventId() {
+    return 'evt-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8);
+  }
+}
+
+module.exports = { AuditLogger };