@nullbridge/sdk 1.0.0

package/src/credentials.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * CredentialVault — secure credential management for AI agents
+ * Stores, rotates, and revokes credentials with full audit trail
+ */
+class CredentialVault {
+  constructor(config, http) {
+    this._config = config;
+    this._http   = http;
+    this._cache  = new Map(); // local encrypted cache
+  }
+
+  /**
+   * Store a credential for an agent
+   *
+   * @param {object} options
+   * @param {string} options.agentId    - Agent ID this credential belongs to
+   * @param {string} options.name       - Credential name (e.g. 'openai-api-key')
+   * @param {string} options.value      - The secret value
+   * @param {string} [options.type]     - Credential type: 'api_key' | 'oauth_token' | 'password' | 'certificate'
+   * @param {number} [options.ttl]      - Time-to-live in seconds (0 = no expiry)
+   * @returns {Promise<string>}         - Credential ID
+   */
+  async store(options = {}) {
+    if (!options.agentId) throw new Error('[NullBridge] agentId is required');
+    if (!options.name)    throw new Error('[NullBridge] credential name is required');
+    if (!options.value)   throw new Error('[NullBridge] credential value is required');
+
+    const credId    = this._generateCredId(options.agentId, options.name);
+    const encrypted = this._encrypt(options.value);
+
+    // Store locally (encrypted)
+    this._cache.set(credId, {
+      id:       credId,
+      agentId:  options.agentId,
+      name:     options.name,
+      type:     options.type || 'api_key',
+      value:    encrypted,
+      ttl:      options.ttl || 0,
+      storedAt: Math.floor(Date.now() / 1000),
+    });
+
+    // Sync to NullBridge API (value is hashed, not stored in plaintext)
+    try {
+      await this._http.post(
+        this._config.apiUrl,
+        '/sdk/credentials/store',
+        {
+          license_key: this._config.licenseKey,
+          cred_id:     credId,
+          agent_id:    options.agentId,
+          name:        options.name,
+          type:        options.type || 'api_key',
+          value_hash:  this._hash(options.value),
+          ttl:         options.ttl || 0,
+        }
+      );
+    } catch {
+      // Continue with local storage if API unreachable
+    }
+
+    return credId;
+  }
+
+  /**
+   * Retrieve a credential value
+   *
+   * @param {string} credId - Credential ID returned from store()
+   * @returns {Promise<string|null>} - Decrypted credential value
+   */
+  async get(credId) {
+    const cached = this._cache.get(credId);
+    if (!cached) return null;
+
+    // Check TTL
+    if (cached.ttl > 0) {
+      const age = Math.floor(Date.now() / 1000) - cached.storedAt;
+      if (age > cached.ttl) {
+        this._cache.delete(credId);
+        console.warn(`[NullBridge] Credential ${credId} has expired (TTL: ${cached.ttl}s)`);
+        return null;
+      }
+    }
+
+    return this._decrypt(cached.value);
+  }
+
+  /**
+   * Rotate a credential — replaces the value and logs the rotation
+   *
+   * @param {string} credId    - Credential ID to rotate
+   * @param {string} newValue  - New credential value
+   */
+  async rotate(credId, newValue) {
+    if (!newValue) throw new Error('[NullBridge] newValue is required for rotation');
+
+    const cached = this._cache.get(credId);
+    if (!cached) throw new Error(`[NullBridge] Credential ${credId} not found`);
+
+    const encrypted = this._encrypt(newValue);
+    this._cache.set(credId, { ...cached, value: encrypted, storedAt: Math.floor(Date.now() / 1000) });
+
+    try {
+      await this._http.post(
+        this._config.apiUrl,
+        '/sdk/credentials/rotate',
+        {
+          license_key: this._config.licenseKey,
+          cred_id:     credId,
+          value_hash:  this._hash(newValue),
+          rotated_at:  Math.floor(Date.now() / 1000),
+        }
+      );
+      console.info(`[NullBridge] Credential rotated: ${cached.name} (${credId})`);
+    } catch (err) {
+      console.warn(`[NullBridge] Credential rotated locally only (API unreachable): ${err.message}`);
+    }
+  }
+
+  /**
+   * Revoke a credential — deletes it and logs revocation
+   *
+   * @param {string} credId - Credential ID to revoke
+   */
+  async revoke(credId) {
+    const cached = this._cache.get(credId);
+    this._cache.delete(credId);
+
+    try {
+      await this._http.post(
+        this._config.apiUrl,
+        '/sdk/credentials/revoke',
+        {
+          license_key: this._config.licenseKey,
+          cred_id:     credId,
+          revoked_at:  Math.floor(Date.now() / 1000),
+        }
+      );
+      console.info(`[NullBridge] Credential revoked: ${cached?.name || credId}`);
+    } catch {}
+  }
+
+  /**
+   * List all credentials for an agent (metadata only, no values)
+   */
+  list(agentId) {
+    const results = [];
+    for (const [id, cred] of this._cache.entries()) {
+      if (cred.agentId === agentId) {
+        results.push({ id, name: cred.name, type: cred.type, storedAt: cred.storedAt, ttl: cred.ttl });
+      }
+    }
+    return results;
+  }
+
+  // ── Encryption helpers (AES-256-GCM) ─────────────────────────────────────
+  _getKey() {
+    // Derive encryption key from license key
+    return crypto.createHash('sha256').update(this._config.licenseKey).digest();
+  }
+
+  _encrypt(plaintext) {
+    const key = this._getKey();
+    const iv  = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const enc  = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag  = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, enc]).toString('base64');
+  }
+
+  _decrypt(ciphertext) {
+    const key  = this._getKey();
+    const buf  = Buffer.from(ciphertext, 'base64');
+    const iv   = buf.slice(0, 12);
+    const tag  = buf.slice(12, 28);
+    const enc  = buf.slice(28);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(enc), decipher.final()]).toString('utf8');
+  }
+
+  _hash(value) {
+    return crypto.createHash('sha256').update(value).digest('hex');
+  }
+
+  _generateCredId(agentId, name) {
+    return 'cred-' + crypto.createHash('sha256')
+      .update(agentId + name + Date.now())
+      .digest('hex')
+      .slice(0, 16);
+  }
+}
+
+module.exports = { CredentialVault };

package/src/http.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const https = require('https');
+const http  = require('http');
+
+class HttpClient {
+  constructor(config) {
+    this._config = config;
+  }
+
+  post(baseUrl, path, body, timeoutMs = 10000) {
+    return this._request('POST', baseUrl, path, body, timeoutMs);
+  }
+
+  get(baseUrl, path, timeoutMs = 10000) {
+    return this._request('GET', baseUrl, path, null, timeoutMs);
+  }
+
+  _request(method, baseUrl, path, body, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const parsed  = new URL(baseUrl + path);
+      const lib     = parsed.protocol === 'https:' ? https : http;
+      const data    = body ? JSON.stringify(body) : null;
+
+      const options = {
+        hostname: parsed.hostname,
+        port:     parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        path:     parsed.pathname + (parsed.search || ''),
+        method,
+        headers: {
+          'Content-Type':  'application/json',
+          'User-Agent':    `nullbridge-sdk/1.0.0 node/${process.version}`,
+          'X-SDK-Version': '1.0.0',
+          ...(data ? { 'Content-Length': Buffer.byteLength(data) } : {}),
+        },
+        timeout: timeoutMs,
+      };
+
+      const req = lib.request(options, res => {
+        let raw = '';
+        res.on('data', chunk => raw += chunk);
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(raw);
+            resolve({ status: res.statusCode, body: parsed });
+          } catch {
+            resolve({ status: res.statusCode, body: { raw } });
+          }
+        });
+      });
+
+      req.on('error', reject);
+      req.on('timeout', () => { req.destroy(); reject(new Error('Request timeout')); });
+
+      if (data) req.write(data);
+      req.end();
+    });
+  }
+}
+
+module.exports = { HttpClient };

package/src/index.d.ts

@@ -0,0 +1,136 @@
+export interface NullBridgeConfig {
+  licenseKey: string;
+  serverUrl?: string;
+  apiUrl?: string;
+  skipLicense?: boolean;
+  autoShutdown?: boolean;
+  checkInterval?: number;
+  siem?: {
+    endpoint: string;
+    format?: 'json' | 'cef' | 'leef';
+  };
+  debug?: boolean;
+}
+
+export interface LicenseData {
+  valid: boolean;
+  reason: string;
+  customer: string;
+  company: string;
+  plan: 'starter' | 'professional' | 'enterprise';
+  max_agents: number;
+  expires_at: number | null;
+  warning?: boolean;
+}
+
+export interface AgentOptions {
+  name: string;
+  type: 'llm' | 'rpa' | 'workflow' | 'custom';
+  model?: string;
+  scopes?: string[];
+  metadata?: Record<string, any>;
+}
+
+export interface AuditEvent {
+  agentId: string;
+  agentName?: string;
+  action: string;
+  resource?: string;
+  outcome?: 'success' | 'failure' | 'blocked';
+  details?: Record<string, any>;
+  ip?: string;
+  duration?: number;
+}
+
+export interface AnomalyAlert {
+  agentId: string;
+  metric: string;
+  value: number;
+  mean: number;
+  zScore: number;
+  severity: 'medium' | 'high' | 'critical';
+  timestamp: number;
+}
+
+export interface CredentialOptions {
+  agentId: string;
+  name: string;
+  value: string;
+  type?: 'api_key' | 'oauth_token' | 'password' | 'certificate';
+  ttl?: number;
+}
+
+export declare class Agent {
+  id: string;
+  name: string;
+  type: string;
+  model: string | null;
+  scopes: string[];
+  metadata: Record<string, any>;
+  logAction(action: string, details?: Record<string, any>): Promise<void>;
+  hasScope(scope: string): boolean;
+  update(updates: Record<string, any>): Promise<void>;
+  deregister(): Promise<void>;
+  toJSON(): object;
+}
+
+export declare class AgentRegistry {
+  register(options: AgentOptions): Promise<Agent>;
+  list(): Promise<Agent[]>;
+  get(agentId: string): Agent | null;
+}
+
+export declare class CredentialVault {
+  store(options: CredentialOptions): Promise<string>;
+  get(credId: string): Promise<string | null>;
+  rotate(credId: string, newValue: string): Promise<void>;
+  revoke(credId: string): Promise<void>;
+  list(agentId: string): object[];
+}
+
+export declare class AuditLogger {
+  log(event: AuditEvent): string;
+  logViolation(agentId: string, agentName: string, action: string, reason: string, details?: object): string;
+  flush(): Promise<void>;
+  getQueue(): object[];
+  stop(): void;
+}
+
+export declare class AnomalyDetector {
+  record(agentId: string, metric: string, value: number): void;
+  check(agentId: string, metric: string, value: number): { anomalous: boolean; zScore: number; mean: number };
+  onAlert(handler: (alert: AnomalyAlert) => void): AnomalyDetector;
+  getBaseline(agentId: string): object | null;
+  resetBaseline(agentId: string, metric?: string): void;
+}
+
+export declare class NullBridge {
+  license: LicenseClient;
+  agents: AgentRegistry;
+  credentials: CredentialVault;
+  audit: AuditLogger;
+  anomaly: AnomalyDetector;
+  siem: SiemStreamer | null;
+
+  constructor(config: NullBridgeConfig);
+  init(): Promise<NullBridge>;
+  shutdown(): Promise<void>;
+  getLicenseInfo(): LicenseData | null;
+  getVersion(): string;
+}
+
+export declare class LicenseClient {
+  validate(): Promise<LicenseData | null>;
+  startWatcher(onInvalid: (valid: boolean, reason: string) => void): void;
+  stopWatcher(): void;
+  getData(): LicenseData | null;
+}
+
+export declare class SiemStreamer {
+  start(): Promise<void>;
+  push(event: object): void;
+  flush(): Promise<void>;
+  stop(): void;
+}
+
+export { NullBridge as default };

package/src/index.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const { LicenseClient }    = require('./license');
+const { AgentRegistry }    = require('./agents');
+const { CredentialVault }  = require('./credentials');
+const { AuditLogger }      = require('./audit');
+const { AnomalyDetector }  = require('./anomaly');
+const { SiemStreamer }      = require('./siem');
+const { HttpClient }        = require('./http');
+
+const SDK_VERSION = '1.0.0';
+
+/**
+ * NullBridge SDK
+ * AI Agent Identity Governance Platform
+ *
+ * @example
+ * 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: 'my-agent', type: 'llm' });
+ */
+class NullBridge {
+  /**
+   * @param {object} config
+   * @param {string} config.licenseKey         - Your NullBridge license key (NB-XXXX-XXXX-XXXX-XXXX)
+   * @param {string} [config.serverUrl]        - License server URL (default: https://nullbridge-license-server-production.up.railway.app)
+   * @param {string} [config.apiUrl]           - NullBridge API URL (default: https://api.nullbridge.ai)
+   * @param {boolean} [config.skipLicense]     - Skip license check (for development only)
+   * @param {boolean} [config.autoShutdown]    - Shut down process if license is revoked (default: true)
+   * @param {number} [config.checkInterval]    - License check interval in ms (default: 86400000 — 24 hours)
+   * @param {object} [config.siem]             - SIEM streaming config
+   * @param {string} [config.siem.endpoint]    - SIEM webhook URL
+   * @param {string} [config.siem.format]      - Log format: 'json' | 'cef' | 'leef' (default: 'json')
+   * @param {boolean} [config.debug]           - Enable debug logging
+   */
+  constructor(config = {}) {
+    if (!config.licenseKey && !config.skipLicense) {
+      throw new Error(
+        '[NullBridge] licenseKey is required. Set NULLBRIDGE_LICENSE_KEY in your environment variables.\n' +
+        'Contact brian@nullbridge.ai to obtain a license key.'
+      );
+    }
+
+    this._config = {
+      licenseKey:    config.licenseKey || '',
+      serverUrl:     config.serverUrl  || 'https://nullbridge-license-server-production.up.railway.app',
+      apiUrl:        config.apiUrl     || 'https://api.nullbridge.ai',
+      skipLicense:   config.skipLicense  || false,
+      autoShutdown:  config.autoShutdown !== false,
+      checkInterval: config.checkInterval || 24 * 60 * 60 * 1000,
+      siem:          config.siem || null,
+      debug:         config.debug || false,
+    };
+
+    this._initialized = false;
+    this._licenseData = null;
+    this._http        = new HttpClient(this._config);
+
+    // Sub-modules — available after init()
+    this.license     = new LicenseClient(this._config, this._http);
+    this.agents      = new AgentRegistry(this._config, this._http);
+    this.credentials = new CredentialVault(this._config, this._http);
+    this.audit       = new AuditLogger(this._config, this._http);
+    this.anomaly     = new AnomalyDetector(this._config, this._http);
+    this.siem        = this._config.siem ? new SiemStreamer(this._config, this._http) : null;
+
+    this._log('NullBridge SDK v' + SDK_VERSION + ' initialized');
+  }
+
+  /**
+   * Initialize NullBridge — validates license and starts background services.
+   * Call this once on application startup, before serving traffic.
+   *
+   * @returns {Promise<NullBridge>} — returns this for chaining
+   * @throws {Error} if license is invalid or expired
+   */
+  async init() {
+    if (this._initialized) {
+      this._log('Already initialized — skipping');
+      return this;
+    }
+
+    this._log('Initializing...');
+
+    // Validate license
+    if (!this._config.skipLicense) {
+      this._licenseData = await this.license.validate();
+      this._log(`License valid — customer: ${this._licenseData.customer}, plan: ${this._licenseData.plan}`);
+
+      // Start periodic license checks
+      this.license.startWatcher((valid, reason) => {
+        if (!valid) {
+          console.error(`[NullBridge] License revoked: ${reason}`);
+          if (this._config.autoShutdown) {
+            console.error('[NullBridge] Shutting down in 60 seconds. Contact brian@nullbridge.ai.');
+            setTimeout(() => process.exit(1), 60 * 1000);
+          }
+        }
+      });
+    } else {
+      this._log('License check skipped (development mode)');
+    }
+
+    // Start SIEM streaming if configured
+    if (this.siem) {
+      await this.siem.start();
+      this._log('SIEM streaming started');
+    }
+
+    this._initialized = true;
+    console.info('[NullBridge] Ready');
+    return this;
+  }
+
+  /**
+   * Gracefully shut down NullBridge — flushes audit logs and stops watchers.
+   */
+  async shutdown() {
+    this._log('Shutting down...');
+    this.license.stopWatcher();
+    if (this.siem) await this.siem.flush();
+    this._initialized = false;
+    this._log('Shutdown complete');
+  }
+
+  /**
+   * Returns current license data (customer, plan, max_agents, expires_at)
+   */
+  getLicenseInfo() {
+    return this._licenseData;
+  }
+
+  /**
+   * Returns SDK version
+   */
+  getVersion() {
+    return SDK_VERSION;
+  }
+
+  _log(msg) {
+    if (this._config.debug) {
+      console.debug(`[NullBridge] ${msg}`);
+    }
+  }
+}
+
+module.exports = { NullBridge, SDK_VERSION };

package/src/license.js

@@ -0,0 +1,100 @@
+'use strict';
+
+class LicenseClient {
+  constructor(config, http) {
+    this._config   = config;
+    this._http     = http;
+    this._watcher  = null;
+    this._data     = null;
+  }
+
+  /**
+   * Validate license against NullBridge license server.
+   * Throws if license is invalid, expired, suspended, or cancelled.
+   */
+  async validate() {
+    try {
+      const { status, body } = await this._http.post(
+        this._config.serverUrl,
+        '/api/validate',
+        { key: this._config.licenseKey }
+      );
+
+      if (status === 200 && body.valid) {
+        this._data = body;
+        return body;
+      }
+
+      // License exists but is not valid
+      const reason = body.reason || 'UNKNOWN';
+      const msg    = body.message || 'License validation failed.';
+
+      const errors = {
+        SUSPENDED:    `License suspended. Contact brian@nullbridge.ai to restore service.`,
+        CANCELLED:    `License cancelled. Contact brian@nullbridge.ai.`,
+        EXPIRED:      `License expired. Contact brian@nullbridge.ai to renew.`,
+        NOT_FOUND:    `License key not found. Verify your NULLBRIDGE_LICENSE_KEY is correct.`,
+        GRACE_PERIOD: null, // still valid — handled below
+      };
+
+      if (reason === 'GRACE_PERIOD') {
+        console.warn(`[NullBridge] Warning: ${msg}`);
+        this._data = body;
+        return body;
+      }
+
+      throw new Error(`[NullBridge] ${errors[reason] || msg}`);
+
+    } catch (err) {
+      if (err.message.startsWith('[NullBridge]')) throw err;
+
+      // Network error — allow startup but warn
+      console.warn(`[NullBridge] License server unreachable (${err.message}). Allowing startup — will retry in 24 hours.`);
+      return null;
+    }
+  }
+
+  /**
+   * Start periodic license checks.
+   * @param {function} onInvalid - callback(valid, reason) when license becomes invalid
+   */
+  startWatcher(onInvalid) {
+    if (this._watcher) return;
+
+    this._watcher = setInterval(async () => {
+      try {
+        const { status, body } = await this._http.post(
+          this._config.serverUrl,
+          '/api/validate',
+          { key: this._config.licenseKey }
+        );
+
+        if (status !== 200 || !body.valid) {
+          if (body.reason !== 'GRACE_PERIOD') {
+            onInvalid(false, body.reason || 'UNKNOWN');
+          } else {
+            console.warn(`[NullBridge] License check: grace period — payment overdue.`);
+          }
+        }
+      } catch (err) {
+        console.warn(`[NullBridge] License check: server unreachable. Will retry in 24 hours.`);
+      }
+    }, this._config.checkInterval);
+
+    // Don't let the watcher keep the process alive
+    if (this._watcher.unref) this._watcher.unref();
+  }
+
+  stopWatcher() {
+    if (this._watcher) {
+      clearInterval(this._watcher);
+      this._watcher = null;
+    }
+  }
+
+  getData() {
+    return this._data;
+  }
+}
+
+module.exports = { LicenseClient };