sentnelops-node

Node.js SDK for SentnelOps — register AI agents as first-class identities, drive their lifecycle (draft → approved → active → suspended → decommissioned), check tool calls against the policy engine before executing them, and verify agent JWTs in your own MCP servers. Ships with a sentnelops CLI that covers the same surface.

Zero runtime dependencies: the SDK uses the global fetch (Node 18+) and node:crypto, nothing else. Full TypeScript types included.

What is SentnelOps

SentnelOps is an AI agent runtime governance platform. It acts as an MCP firewall between AI agents (Claude Code, Cursor, custom agents) and the systems they access, giving every agent an identity, enforcing YAML policies on every tool call before it executes, and producing an audit-ready evidence trail.

This SDK is the developer surface for the Agent Identity Registry side of that platform: it talks to the SentnelOps API to register agents, manage their lifecycle and tokens, and ask the same policy engine that powers server-side enforcement for advisory verdicts from your own code.

Architecture

 you / your CI                              your AI agent
+--------------------+                     +--------------------+
| AIRClient  or  CLI |                     | agent (holds JWT)  |
+--------------------+                     +--------------------+
     | SNOPS_API_KEY                             | agent token
     | HTTPS                                     | MCP calls
     v                                           v
+-----------------------------+  same     +---------------+     +-------------+
| SentnelOps API              | policy    | MCP proxy     |---->| MCP servers |
| /agents, lifecycle,         |<--------->| (enforcement) |     +-------------+
| /policy/check, /audit       |  engine   +---------------+
+-----------------------------+
                                self-hosted only: your MCP server can call
                                verifyToken(token, secret) to validate the
                                calling agent locally, no network round trip

The SDK's isPermitted / require checks are the advisory, client-side complement to the server-side MCP proxy; both evaluate the same policy engine, but the proxy is the authoritative enforcement point.

Install

The package is not published to npm yet. Install it from GitHub (the prepare script builds dist/ on install):

npm install git+https://github.com/sentnelops/sentnelops-node.git

Requires Node.js 18+ (for the global fetch). Installing also puts the sentnelops CLI on your path (npx sentnelops).

10-minute quickstart

0. Authenticate

Get an org API key (snops_key_...) by registering at https://platform.sentnelops.com/register — it is shown exactly once.

export SNOPS_API_KEY=snops_key_...
export SNOPS_BASE_URL=https://api.sentnelops.com   # optional; this is the default.
                                                   # Point at your own deployment when self-hosting.

Or pass options in code:

import { AIRClient } from "sentnelops";

const client = new AIRClient({
  apiKey: "snops_key_...",  // falls back to SNOPS_API_KEY
  baseUrl: undefined,       // falls back to SNOPS_BASE_URL, then the hosted API
  timeoutMs: 10_000,        // per-request timeout
});

No cleanup required — the client uses the global fetch; there is no connection pool to close.

1. Register, approve, activate

Dev and staging agents start active immediately. Production agents start in draft and must clear two gates before policy will permit their calls — approval by a different person than the creator (segregation of duties), then activation. Condensed from examples/register-and-activate.ts:

import { AIRClient, PermissionDeniedError } from "sentnelops";

const client = new AIRClient();

// 1. Register — the token is shown EXACTLY ONCE; store it in a secret manager.
const agent = await client.register({
  name: "prod-billing",
  owner: "finance-team",
  environment: "production",       // production | staging | dev
  createdBy: "[email protected]",
  allowedMcp: ["stripe-mcp"],
  deniedMcp: ["payroll-mcp"],      // deny wins
  riskLevel: "high",               // high => 30-day review cadence
});
console.log(agent.id, agent.status); // "agt_...", "draft"
console.log(agent.token);            // never retrievable again — rotate to replace

// 2. Approve — MUST be a different identity than createdBy, or the API answers
//    403 with errorCode "segregation_of_duties".
await client.approve(agent.id, {
  approvedBy: "[email protected]",
  note: "scope reviewed: stripe-mcp only",
});

// 3. Activate — approval cannot be skipped.
await client.activate(agent.id, { actor: "[email protected]" });

// The whole story is on the append-only audit trail, newest first.
console.log(await client.audit(agent.id));

2. Gate a dangerous code path on policy

require asks the policy engine for a verdict and throws PolicyViolation on deny, so the risky code below it only runs when policy says yes. Condensed from examples/policy-gate.ts:

import { AIRClient, PolicyViolation } from "sentnelops";

const client = new AIRClient();

try {
  const decision = await client.require(agentId, "aws-prod", "ec2.terminate");
  console.log(`permitted (${decision.reason})`);
  // ... the actual dangerous work goes here ...
} catch (err) {
  if (err instanceof PolicyViolation) {
    // Fail safe: log the full decision and do NOT do the thing.
    console.error(`blocked by policy: ${err.message}`);
    console.error(`matched rule: ${err.decision?.policyRule}`);
  } else throw err;
}

Prefer a verdict without an exception? client.isPermitted(agentId, mcpServer, tool?) returns a typed Decision (permitted, reason, policyRule?). The CLI equivalent, sentnelops check, exits 2 on deny so it can gate CI.

3. Verify calling agents in a self-hosted MCP server

If you self-host SentnelOps and your MCP server shares the signing secret, it can validate agent JWTs locally — no network round trip, no API key. HS256 only; any other alg (including none) is rejected. Condensed from examples/verify-caller.ts:

import { AIRClient, InvalidTokenError, type TokenClaims } from "sentnelops";
// also exported standalone: import { verifyToken } from "sentnelops";

function handleMcpRequest(authorizationHeader: string): TokenClaims {
  const token = authorizationHeader.replace(/^Bearer /, "").trim();
  const claims = AIRClient.verifyToken(
    token,
    process.env.SNOPS_SIGNING_SECRET!,
    "sentnelops.com",   // default issuer; override if your deployment differs
  );
  console.log(`verified caller: agent ${claims.sub}`);  // sub = agent id
  return claims;
}
// InvalidTokenError => reject the call (401): bad signature, wrong alg/issuer, expiry.

Hosted-platform users don't need this: the hosted proxy validates agent tokens before your MCP server ever sees the call.

4. Same thing from the terminal

sentnelops register --name prod-billing --owner finance-team \
    --env production --allowed-mcp stripe-mcp --risk-level high
sentnelops approve agt_01j9x4m2e8 --by [email protected]
sentnelops activate agt_01j9x4m2e8 --actor [email protected]
sentnelops check agt_01j9x4m2e8 stripe-mcp --tool refund.create
# PERMITTED: agent scope allows stripe-mcp; tool rule matched  [rule: stripe.refunds]

API overview

Everything is exported from the package root. The client class is AIRClient (Agent Identity Registry); SentnelOps is an alias for it.

AIRClient methods

Method	What it does
register(params)	Create an agent and mint its JWT; returns the record plus one-time token
get(agentId)	Fetch one agent
list(params?)	List agents with filters (environment, status, riskLevel, owner, limit, offset)
update(agentId, params)	Change mutable fields (owner, riskLevel, allowedMcp, deniedMcp) — never status
approve(agentId, { approvedBy, note? })	draft → approved; approver must differ from creator
activate(agentId, { actor })	approved → active
suspend(agentId, { actor, reason })	active → suspended; reason mandatory, scope frozen
reactivate(agentId, { actor })	suspended → active, only while the suspension is < 30 days old
decommission(agentId, { actor })	Terminal; revokes every token, keeps history
rotate(agentId, { actor })	Revoke current tokens, mint a new one (returned once)
markReviewed(agentId, { actor })	Record an access review; next one scheduled by risk level (30/90/180 days)
audit(agentId)	The agent's append-only audit trail, newest first
isPermitted(agentId, mcpServer, tool?)	Ask the policy engine for a Decision
require(agentId, mcpServer, tool?)	Like isPermitted, but throws PolicyViolation on deny
AIRClient.verifyToken(token, secret, issuer?)	Static; verify an agent JWT (HS256) locally — also exported as verifyToken

Errors are typed, one class per failure mode, all subclassing SentnelOpsError and carrying statusCode / errorCode: AuthenticationError (401), PermissionDeniedError (403, e.g. errorCode === "segregation_of_duties"), NotFoundError (404), LifecycleError (409), ValidationError (422), RateLimitedError (429, with retryAfter), APIError (other non-2xx), plus client-side PolicyViolation and InvalidTokenError. See docs/errors.md.

CLI commands

Command	What it does
sentnelops register	Register an agent (token printed once)
sentnelops list	List agents with filters
sentnelops show <agent-id>	One agent, as JSON
sentnelops audit <agent-id>	Audit trail, newest first
sentnelops approve <agent-id> --by <who>	Approve a draft agent (SoD enforced)
sentnelops activate <agent-id>	approved → active
sentnelops suspend <agent-id> --reason <text>	Suspend (reason required)
sentnelops reactivate <agent-id>	Reactivate a < 30-day suspension
sentnelops decommission <agent-id>	Terminal; revoke all tokens
sentnelops rotate <agent-id>	Revoke tokens, print a new one once
sentnelops check <agent-id> <mcp-server> [--tool <name>]	Policy verdict; exits 2 on deny

Environment: SNOPS_API_KEY (required), SNOPS_BASE_URL (optional, defaults to https://api.sentnelops.com).

Documentation

Doc	What's in it
Getting started	Install, auth, first agent end-to-end
Agent identity	The identity model, one-time tokens, rotation, verifyToken
Lifecycle	The state machine, transitions, and their errors
Policy checks	isPermitted, require, Decision, advisory vs. enforcement
Errors	Every error class and what to do about it
CLI	Every subcommand with examples

Runnable examples live in examples/.

Learn more

• SentnelOps: https://sentnelops.com
• What is AI agent runtime governance: https://sentnelops.com/learn/ai-agent-runtime-governance
• Add policy enforcement to an MCP server: https://sentnelops.com/learn/add-policy-enforcement-to-mcp-server
• Platform quickstart: https://sentnelops.com/docs/quickstart
• Sibling SDKs: sentnelops-python, sentnelops-go

License

MIT — see LICENSE.