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
License
MIT — see LICENSE.
