@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

npm install @nullbridge/sdk

Requires Node.js 18+.

Quick Start

import { NullBridge } from '@nullbridge/sdk';

const nb = new NullBridge({
  licenseKey: process.env.NULLBRIDGE_LICENSE_KEY,
});

await nb.init();

const agent = await nb.agents.register({
  id:     'claims-processor-001',   // unique identifier for this agent
  name:   'Claims Processor',
  type:   'llm',
  model:  'gpt-4o',
  scopes: ['read:claims', 'write:reports'],
});

// Log every action your agent takes
await agent.logAction('process_claim', { claimId: 'CLM-001', outcome: 'approved' });

// Graceful shutdown
await nb.shutdown();

That's it. NullBridge validates your license on startup, registers your agent with a cryptographic identity, and begins monitoring automatically. Every action appears in your NullBridge dashboard in real time.

Environment Variables

NULLBRIDGE_LICENSE_KEY=NB-XXXX-XXXX-XXXX-XXXX

Contact [email protected] to obtain a license key.

Configuration

const nb = new NullBridge({
  licenseKey:    process.env.NULLBRIDGE_LICENSE_KEY, // required
  apiUrl:        'https://api.nullbridge.ai',         // default
  skipLicense:   false,    // set true for local dev only
  autoShutdown:  true,     // shut down process if license is revoked
  checkInterval: 86400000, // license recheck interval in ms (default: 24h)
  debug:         false,    // enable verbose logging
});

API Reference

nb.init()

Initialize NullBridge. Call once on application startup before serving traffic. Validates your license key and starts background services.

await nb.init();

nb.agents

nb.agents.register(options)

Register an AI agent with NullBridge. The agent appears immediately in your NullBridge dashboard under Agent Registry.

const agent = await nb.agents.register({
  id:     'fraud-detector-001',  // required — unique, stable identifier
  name:   'Fraud Detector',      // required — display name
  type:   'llm',                 // required — 'llm' | 'rpa' | 'workflow' | 'custom'
  model:  'claude-3-5-sonnet',   // optional
  scopes: ['read:transactions', 'write:alerts'], // optional
  metadata: {
    team:        'risk',
    environment: 'prod',
    owner_email: '[email protected]',
  },
});

Returns an agent instance with the following methods:

agent.logAction(action, details?)

Log an action this agent performed. Appears in the audit trail.

await agent.logAction('analyze_transaction', {
  txId:   'TX-1234',
  amount: 5000,
  result: 'approved',
});

agent.hasScope(scope)

Check if the agent has a specific permission scope.

if (!agent.hasScope('write:alerts')) {
  throw new Error('Agent not authorized for this action');
}

agent.deregister()

Deregister the agent and revoke its identity. The agent status updates to deprovisioned in the dashboard.

await agent.deregister();

nb.audit

nb.audit.log(event)

Log an agent action to the audit trail. Supports fire-and-forget (no await required for non-critical logging).

await nb.audit.log({
  agentId:    agent.id,           // required
  agentName:  agent.name,         // recommended
  action:     'process_claim',    // required
  resource:   'claim:CLM-001',    // optional
  outcome:    'success',          // 'success' | 'failure' | 'blocked'
  details:    { amount: 15000 },  // optional
  ip:         req.ip,             // optional
  duration_ms: 1240,              // optional
});

nb.audit.batch(events)

Log multiple events in a single request. More efficient for high-throughput agents.

await nb.audit.batch([
  { agentId: agent.id, agentName: agent.name, action: 'read_record',   outcome: 'success' },
  { agentId: agent.id, agentName: agent.name, action: 'write_report',  outcome: 'success' },
  { agentId: agent.id, agentName: agent.name, action: 'delete_record', outcome: 'blocked' },
]);

nb.audit.logViolation(agentId, agentName, action, reason)

Log a policy violation. Outcome is automatically set to blocked and triggers a SIEM alert.

await nb.audit.logViolation(agent.id, agent.name, 'delete_record', 'scope_denied');

nb.credentials

NullBridge tracks credential lifecycle metadata — store, rotate, and revoke events are logged to your audit trail and SIEM automatically.

nb.credentials.store(options)

Register a credential and log it to the audit trail.

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: seconds until expiry
});

nb.credentials.rotate(credId, newValue?)

Log a credential rotation event.

await nb.credentials.rotate(credId, newApiKey);

nb.credentials.revoke(credId)

Permanently revoke a credential and log the revocation.

await nb.credentials.revoke(credId);

nb.anomaly

nb.anomaly.record(agentId, metric, value)

Record a behavioral metric. NullBridge builds a statistical baseline and fires an alert when a value deviates significantly (z-score threshold configurable in dashboard).

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 that fires when an anomaly is detected.

nb.anomaly.onAlert(alert => {
  console.error(`Anomaly detected: ${alert.agentId} — ${alert.metric} (z=${alert.zScore})`);
  // Forward to PagerDuty, Slack, OpsGenie, etc.
});

nb.anomaly.check(agentId, metric, value)

Check if a value is anomalous without recording it.

const { anomalous, zScore } = nb.anomaly.check(agent.id, 'api_calls', 500);
if (anomalous) console.warn(`Unusual API call volume — z-score: ${zScore}`);

nb.shutdown()

Gracefully shut down NullBridge — flushes pending audit logs and stops background services. Call before process.exit().

process.on('SIGTERM', async () => {
  await nb.shutdown();
  process.exit(0);
});

Full Example

import { NullBridge } from '@nullbridge/sdk';

const nb = new NullBridge({
  licenseKey: process.env.NULLBRIDGE_LICENSE_KEY,
  debug: false,
});

await nb.init();

// Register your agent once on startup
const agent = await nb.agents.register({
  id:     'invoice-processor-001',
  name:   'Invoice Processor',
  type:   'llm',
  model:  'gpt-4o',
  scopes: ['read:invoices', 'write:payments'],
  metadata: { team: 'finance', environment: 'prod' },
});

// Store credentials securely
const credId = await nb.credentials.store({
  agentId: agent.id,
  name:    'stripe-api-key',
  value:   process.env.STRIPE_SECRET_KEY,
  type:    'api_key',
});

// Monitor behavior
nb.anomaly.onAlert(alert => {
  console.error(`[NullBridge] Anomaly: ${alert.metric} — z=${alert.zScore}`);
});

// Log every action
async function processInvoice(invoiceId) {
  if (!agent.hasScope('write:payments')) {
    await nb.audit.logViolation(agent.id, agent.name, 'process_payment', 'scope_denied');
    throw new Error('Unauthorized');
  }

  // ... your agent logic ...

  await agent.logAction('process_invoice', { invoiceId, outcome: 'success' });
  nb.anomaly.record(agent.id, 'invoices_per_hour', 1);
}

// Graceful shutdown
process.on('SIGTERM', async () => {
  await nb.shutdown();
  process.exit(0);
});

Dashboard

All agent activity flows into your NullBridge dashboard at app.nullbridge.ai:

• Agent Registry — all registered agents, their status, tier, and risk score
• Audit Trail — every action logged with full context
• SIEM Events — policy violations, anomalies, and credential events
• Anomaly Detection — behavioral baselines and z-score alerts

Support

• Email: [email protected]
• Website: nullbridge.ai

License

This software is proprietary and confidential. Use requires a valid NullBridge license key.

NullBridge Technologies

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.