npm package: @sentinelx/sdk
Description: Pre-execution enforcement SDK for AI agents and automated systems
Author: SentinelXAI, Inc.
Latest version: 0.9.6

# @sentinelx/sdk

[![npm](https://img.shields.io/npm/v/@sentinelx/sdk)](https://npmjs.com/package/@sentinelx/sdk)
[![downloads](https://img.shields.io/npm/dw/@sentinelx/sdk)](https://npmjs.com/package/@sentinelx/sdk)
[![license](https://img.shields.io/npm/l/@sentinelx/sdk)](https://npmjs.com/package/@sentinelx/sdk)

Pre-execution enforcement for AI agents and automated systems.

SentinelX evaluates action admissibility at the commit boundary, before any irreversible action executes. Every decision returns a cryptographically sealed receipt.

---

## Install

```bash
npm install @sentinelx/sdk
```

---

## Quick Start

```js
import { SentinelX, AdmissibilityError } from "@sentinelx/sdk";

const sx = new SentinelX({ apiKey: process.env.SENTINELX_API_KEY });

// ADMISSIBLE — human oversight present, action may proceed
const receipt = await sx.enforce("ai.agent.action.execute", {
  agent_id:                 "agent_123",
  action_type:              "filesystem.delete",
  human_in_loop:            true,
  human_in_loop_required:   true,
  action_logged:            true,
  harmful_content_detected: false,
  action_within_scope:      true,
});

console.log(receipt.verdict);      // "ADMISSIBLE"
console.log(receipt.receipt_hash); // sha256 sealed receipt
```

```js
// INADMISSIBLE — human oversight missing, AdmissibilityError thrown
try {
  await sx.enforce("ai.agent.action.execute", {
    agent_id:                 "agent_123",
    action_type:              "filesystem.delete",
    human_in_loop:            false,
    human_in_loop_required:   true,
    action_logged:            true,
    harmful_content_detected: false,
    action_within_scope:      true,
  });
} catch (err) {
  if (err instanceof AdmissibilityError) {
    console.log(err.constraint);     // "AI_HUMAN_IN_LOOP_ENFORCED"
    console.log(err.violation_code); // "INV-026"
    console.log(err.summary);        // "Action blocked: human oversight required at action commitment"
    console.log(err.receipt_hash);   // sha256 sealed receipt — action never executed
  }
}
```

---

## How It Works

SentinelX sits at the commit boundary between your agent and execution. Before any irreversible action fires, the enforcement engine evaluates it against invariant constraints and returns a deterministic verdict with a provenance receipt.

- **ADMISSIBLE** → receipt returned, action may proceed
- **INADMISSIBLE** → `AdmissibilityError` thrown, nothing executes, receipt returned

The enforcement decision is made server-side. It cannot be bypassed client-side.

---

## API

### `new SentinelX(options)`

```js
const sx = new SentinelX({
  apiKey:    "sx_live_...",
  baseUrl:   "https://enforce.sentinelx.ai",
  timeout:   10000,
  sessionId: "session_abc",
});
```

### `sx.enforce(action, context, opts?)`

Evaluates action admissibility. Returns a receipt on ADMISSIBLE. Throws `AdmissibilityError` on INADMISSIBLE.

```js
const receipt = await sx.enforce("ai.agent.action.execute", context);
```

Options:
- `opts.observe: true` evaluates without throwing on INADMISSIBLE

### `sx.evaluate(action, context)`

Always returns the receipt. Never throws on INADMISSIBLE. Useful for logging pipelines.

```js
const receipt = await sx.evaluate("ai.agent.action.execute", context);
console.log(receipt.verdict);
```

### `sx.verifyReceipt(receipt)`

Recomputes the receipt hash client-side and confirms it matches the sealed `receipt_hash`. This verifies internal consistency and helps detect client-side modification.

```js
const valid = await sx.verifyReceipt(receipt);
```

### `sx.health()`

```js
const { ok, build } = await sx.health();
```

---

## AdmissibilityError

Thrown when an action is INADMISSIBLE. Contains the full enforcement receipt.

```js
err.verdict
err.constraint
err.violation_code
err.violations
err.summary
err.trace_id
err.request_hash
err.receipt_hash
err.inv_version
err.receipt
```

---

## SentinelXAgent

Named helpers for common action types.

```js
import { SentinelXAgent } from "@sentinelx/sdk";

const sx = new SentinelXAgent({ apiKey: process.env.SENTINELX_API_KEY });

await sx.enforceAgentAction({ agent_id, action_type, human_in_loop, ... });
await sx.enforceWireTransfer({ amount, mfa_verified, recipient_verified, ... });
await sx.enforceModelDeploy({ human_approval, model_tested, model_hash, ... });
await sx.enforceOTCommand({ device_id, operator_authorized, mfa_verified, ... });
await sx.enforceBreakerOpen({ operator_authorized, n_minus_1_verified, ... });
await sx.enforceSCADASetpoint({ device_id, parameter, operator_authorized, ... });
await sx.enforceAlgoTrade({ symbol, order_quantity, market_halted, ... });
```

---

## Receipt Shape

**ADMISSIBLE receipt (200):**

```json
{
  "verdict":         "ADMISSIBLE",
  "summary":         "Action admissible: ai.agent.action.execute passed all invariant constraints",
  "constraint":      null,
  "constraint_pack": "ai.agent.action.execute",
  "violation_code":  null,
  "violations":      [],
  "mode":            "observe",
  "envelope_class":  "demo",
  "trace_id":        "enf_6be116ac-74a",
  "request_hash":    "sha256:a1ab...",
  "receipt_hash":    "sha256:8955...",
  "inv_version":     "INV-2026-04-02",
  "latency_ms":      0
}
```

**INADMISSIBLE receipt (403):**

```json
{
  "type":            "https://enforce.sentinelx.ai/problems/admissibility-violation/human-oversight-required",
  "title":           "Human oversight required at action commitment",
  "status":          403,
  "detail":          "human_in_loop: false — human oversight required but not present",
  "verdict":         "INADMISSIBLE",
  "summary":         "Action blocked: human oversight required at action commitment",
  "constraint":      "AI_HUMAN_IN_LOOP_ENFORCED",
  "constraint_pack": "ai.agent.action.execute",
  "violation_code":  "INV-026",
  "violations": [
    {
      "primitive":  "ai.human_in_loop_enforced",
      "code":       "INV-026",
      "constraint": "AI_HUMAN_IN_LOOP_ENFORCED",
      "message":    "human_in_loop: false — human oversight required but not present"
    }
  ],
  "mode":            "observe",
  "envelope_class":  "demo",
  "trace_id":        "enf_0e7bdaaa-d9b",
  "request_hash":    "sha256:581c...",
  "receipt_hash":    "sha256:351d...",
  "inv_version":     "INV-2026-04-02",
  "latency_ms":      0
}
```

---

## Domain Coverage

SentinelX enforces actions across high-consequence domains where irreversible execution without constraint validation carries the highest operational risk.

| Domain | Example Actions |
|--------|----------------|
| AI/ML Agents | `ai.agent.action.execute`, `ai.agent.deactivate`, `ml.model.deploy.production` |
| Financial | `wire.transfer.execute`, `algo.trade.execute`, `treasury.disbursement.execute` |
| OT/SCADA | `scada.setpoint.change`, `ot.command.execute`, `breaker.open.execute` |
| Grid/Energy | `load.transfer.execute`, `der.curtailment.execute.batch`, `bess.thermal_limit.override` |
| Cyber/RMM | `rmm.script.execute`, `rmm.privilege.escalate`, `vpn.session.establish.exploit` |
| Mobility | `driver.payout.execute`, `surge.pricing.apply`, `account.suspend.execute` |
| Delivery | `order.refund.execute`, `dasher.tip.adjust`, `merchant.payout.execute` |
| Identity | `session.privilege.escalate`, `directory.credential.export` |
| Ransomware Defense | `historian.data.delete.bulk`, `hypervisor.encrypt.execute` |

Coverage expands continuously. See [sentinelx.ai](https://sentinelx.ai) for updates.

---

## Framework Alignment

SentinelX invariant packs address many of the same control concerns emerging in NIST CAISI discussions around agentic AI governance, including execution boundary enforcement for autonomous systems.

| Framework | Alignment |
|-----------|-----------|
| NIST SP 800-53 | Access Control (AC), Audit & Accountability (AU), Identification & Authentication (IA) |
| NIST AI RMF | Govern, Map, Measure, Manage — runtime enforcement at the action commitment layer |
| NERC CIP | CIP-005, CIP-007, CIP-010 — OT/grid action enforcement and change management |
| MITRE ATT&CK | Pre-execution blocking of techniques mapped to invariant primitives |
| IEC 62443 | Industrial automation and control system security zones and conduits |

---

## Troubleshooting

**Getting 400?** Missing, invalid, or structurally rejected request fields. Every enforce call requires `action` and `context`.

**Getting 401?** Invalid or missing API key.
```bash
curl -X POST https://enforce.sentinelx.ai/generate-key
```

**Getting 403 INADMISSIBLE?** An invariant constraint was violated. Check `err.violations`.

**Getting 429?** Rate limit exceeded. Generate your own key for higher limits.
```bash
curl -X POST https://enforce.sentinelx.ai/generate-key
```

---

## Get an API Key

Generate a test key for observe-mode evaluation:

```bash
curl -X POST https://enforce.sentinelx.ai/generate-key
```

A demo key for immediate testing is also available at [sentinelx.ai](https://sentinelx.ai).

---

## Links

- [sentinelx.ai](https://sentinelx.ai)

---

## License

Apache-2.0