@sovr/sdk

@sovr/sdk

The Responsibility Layer for AI Agents — Official Node.js/TypeScript SDK for the SOVR API.

Most users should start with sovr-mcp-proxy for zero-code AI agent integration. This SDK is for advanced scenarios: custom agent frameworks, Express/Fastify middleware, CI/CD pipeline checks, or business logic that embeds SOVR gate-checks directly.

What SOVR Does

SOVR is not a security product. It is a decision accountability layer that sits between AI intent and real-world execution. Every action goes through a five-step lifecycle:

• Gate Check — evaluate the action against compiled policy artifacts
• Approval — route high-risk decisions to human reviewers
• Permit — issue a time-limited, cryptographically signed execution permit
• Execute — your code runs the action
• Receipt — close the audit loop with outcome evidence and output fingerprint

This creates an immutable audit trail proving what was decided, why, by whom, and what happened.

Installation

npm install @sovr/sdk

Zero runtime dependencies. Works with Node.js 18+.

Quick Start — Full Lifecycle with protect()

import { SOVRClient, sha256 } from '@sovr/sdk';

// With API key (recommended) — unlocks full tier capabilities
const sovr = new SOVRClient({
  apiKey: process.env.SOVR_API_KEY!,
});

// Without API key — runs in Free tier (degraded mode)
// const sovr = new SOVRClient();

const lifecycle = await sovr.protect({
  action: 'send_payment',
  resource: 'stripe/charge',
  context: { amount: 5000, currency: 'usd' },
});

if (!lifecycle.isAllowed) {
  throw new Error(`Blocked: ${lifecycle.decision.reason}`);
}

if (lifecycle.needsApproval) {
  await lifecycle.requestApproval_ext('Monthly payroll run');
}

const permit = await lifecycle.getPermit();

// Execute your action
const result = await stripe.charges.create({ amount: 5000, currency: 'usd' });

// Close the audit loop
await lifecycle.submitReceipt_ext({
  external_ref: result.id,
  status: 'success',
  output_hash: sha256(JSON.stringify(result)),
});

Low-Level API

For fine-grained control over each lifecycle step:

import { SOVRClient, sha256 } from '@sovr/sdk';

const sovr = new SOVRClient({ apiKey: process.env.SOVR_API_KEY! });

// Step 1: Gate check
const decision = await sovr.gateCheck({
  action: 'delete_records',
  resource: 'database/users',
  context: { count: 1500 },
});

if (!decision.allowed) {
  console.log(`Blocked: ${decision.reason}`);
  process.exit(1);
}

// Step 2: Request approval (if required)
if (decision.requires_approval) {
  await sovr.requestApproval({
    decision_id: decision.decision_id,
    justification: 'Quarterly data cleanup per policy',
    urgency: 'medium',
  });
}

// Step 3: Obtain permit
const permit = await sovr.grantPermit({
  decision_id: decision.decision_id,
  ttl_seconds: 300,
});

// Step 4: Execute action
const result = await db.deleteMany({ where: { inactive: true } });

// Step 5: Submit receipt
await sovr.submitReceipt({
  decision_id: decision.decision_id,
  permit_id: permit.permit_id,
  external_ref: `batch_delete_${Date.now()}`,
  status: 'success',
  started_at: Date.now() - 2000,
  finished_at: Date.now(),
  output_hash: sha256(JSON.stringify(result)),
});

Function Call Interceptor

For AI agent tool-calling patterns, wrap functions to automatically insert SOVR checks:

async function sendEmail(to: string, subject: string, body: string) {
  return mailer.send({ to, subject, body });
}

const safeSendEmail = sovr.wrap(sendEmail, {
  action: 'send_email',
  resource: 'email/outbound',
});

// Every call now goes through gate-check → permit → receipt automatically
await safeSendEmail('[e-mail]', 'Invoice', 'Your invoice is ready.');

Configuration

const sovr = new SOVRClient({
  apiKey: 'sovr_sk_...',
  // endpoint: 'https://api.sovr.inc',  // default
  // mode: 'cloud',                      // 'mcp' (default) or 'cloud'
  // timeout: 30000,                     // ms
  // maxRetries: 2,                      // for transient failures
});

Parameter	Env Var	Default	Description
apiKey	SOVR_API_KEY	—	Optional. Omit for Free tier (degraded). Get a key at sovr.inc/register
endpoint	SOVR_API_ENDPOINT	https://api.sovr.inc	API base URL
mode	SOVR_API_MODE	mcp	mcp or cloud
timeout	—	30000	Request timeout (ms)
maxRetries	—	2	Retries for transient failures

SDK Capabilities by Tier

The SDK provides access to SOVR's full capability stack. Available methods depend on your API key tier:

Tier	Price	Capabilities	API Key Required?
Free	$0	gate_check (degraded: allow/deny only), check_command (degraded), audit_log (7 days/50 entries)	No — runs without key
Personal	$10/mo	Full gate_check + check_sql + check_http + request_approval + submit_receipt + add_rule (28 tools)	Yes (sovr_sk_...)
Starter	$300/mo	+ Kill-switch, budget tracking, compliance, monitoring (48 tools)	Yes
Pro	$2,000/mo	+ Cognitive analysis, model ops, regression testing (98 tools)	Yes
Enterprise	$15,000/mo	Full API access: multi-tenant, billing, data governance (272 tools)	Yes

For the complete method reference, see sovr.inc/docs/sdk.

Utilities

sha256(input: string): string

Built-in SHA-256 hashing for output fingerprinting. Uses Node.js crypto — no extra dependencies.

import { sha256 } from '@sovr/sdk';
const hash = sha256(JSON.stringify(result));

Error Handling

import { SOVRClient, SOVRError, AuthenticationError, RateLimitError } from '@sovr/sdk';

try {
  const result = await sovr.gateCheck({ action: 'deploy', resource: 'prod' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or missing API key
  } else if (error instanceof RateLimitError) {
    // Back off and retry
  } else if (error instanceof SOVRError) {
    console.error(`[${error.errorCode}] ${error.message}`);
  }
}

When to Use SDK vs MCP Proxy

Scenario	Use
AI agent with MCP support (Claude, Cursor, etc.)	sovr-mcp-proxy — zero code
Custom agent framework without MCP	@sovr/sdk
Express/Fastify middleware	@sovr/sdk
Business logic embedding gate-checks	@sovr/sdk
CI/CD pipeline checks	@sovr/sdk

License

Business Source License 1.1 (BSL-1.1) — see LICENSE for details.

Copyright (c) 2026 SOVR AI. All rights reserved.