sentinel-agent-trust

TypeScript/Node.js client SDK for Sentinel AI — the identity & governance layer for AI agents: control, authorize, and audit autonomous agents before they touch your production APIs.

Zero runtime dependencies. Ed25519 signing and fetch are native in Node.js ≥ 18.

Sentinel is in private beta. For source access, a hosted sandbox organization key, or to collaborate: [email protected]

Install

npm install sentinel-agent-trust

Usage

import { AgentTrustClient, AgentPermissionDeniedError } from "sentinel-agent-trust";

const client = new AgentTrustClient({
  agentId: "agt_...",
  privateKey: process.env.SENTINEL_AGENT_PRIVATE_KEY!, // base64 Ed25519 seed
  gatewayUrl: "https://your-gateway.example.com",
});

try {
  await client.enforceAction("crm.refund.create", "crm://refunds", { amount: 90 });
  await crm.createRefund({ amount: 90 });        // authorized → do the real thing
} catch (err) {
  if (err instanceof AgentPermissionDeniedError) {
    // final denial: do NOT retry — branch (degrade, escalate to a human, give up)
    escalateToHuman(err.reason, err.requestId);
  } else {
    // infrastructure error: transient, retry with backoff
    throw err;
  }
}

Every request is signed with the agent's private Ed25519 key (never sent to the server) and carries a timestamp + nonce, so requests cannot be replayed.

Proxy mode

With proxy mode the request travels through the gateway, which authorizes it, injects the upstream credential (the agent never holds it) and forwards it — enforcement the agent cannot skip:

const resp = await client.proxyRequest("stripe", "POST", "v1/refunds", {
  payload: { charge: "ch_123", amount: 90 },
});
console.log(resp.status, await resp.json()); // the upstream's response

Method, path, query and body are all covered by the Ed25519 signature. Denials throw the same errors as enforceAction; a pending human approval throws AgentApprovalPendingError — retry the identical call after approval.

Generate a keypair

npx sentinel-keygen

Register the public key via POST /v1/agents; keep the private seed in a secret store.

License

Apache 2.0 — see LICENSE.