sint-protocol

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 11 Open GitHub ↗

Open-source runtime security and governance for AI agents, MCP tools, robotics, industrial automation, and physical AI.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# SINT Protocol
[![CI](https://github.com/sint-ai/sint-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/sint-ai/sint-protocol/actions/workflows/ci.yml)
![Node.js](https://img.shields.io/badge/node-%3E%3D22-blue)
![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)
![License](https://img.shields.io/badge/license-Apache--2.0-blue)

[![Glama](https://glama.ai/mcp/servers/sint-ai/sint-protocol/badges/card.svg)](https://glama.ai/mcp/servers/sint-ai/sint-protocol)

**Open-source runtime security and governance for AI agents, MCP tools, robotics, industrial automation, and physical AI.**

**Mission Authority:** SINT also provides a hardware-agnostic authority and
evidence protocol for autonomous air, ground, maritime, and robotic systems. It
binds platform identity, mission scope, operator authorization, abort behavior,
and signed after-action evidence without selecting targets or generating
effects. See [`docs/mission-authority.md`](docs/mission-authority.md).

SINT Protocol is an open protocol and TypeScript reference stack that sits
between AI agent intent and real-world execution. Before a governed tool call,
robot command, industrial write, payment-like action, or actuator movement can
run, the request passes through `PolicyGateway.intercept()` for capability-token
authorization, T0-T3 approval tiering, physical constraint enforcement,
revocation checks, and tamper-evident evidence logging.

## What is SINT Protocol?

SINT is an AI agent security control plane for actions with real-world
consequence. It helps teams answer four questions before an autonomous system
acts:

- **Who is allowed to act?** Ed25519 capability tokens bind issuer, subject,
  resource, action, expiry, constraints, and delegation chain.
- **What constraints apply?** Velocity, force, geofence, budget, rate-limit, and
  consent constraints travel with the token instead of living in ad hoc config.
- **When is human review required?** T0-T3 approval tiers route low-risk actions
  automatically and escalate physical or irreversible actions to operators.
- **How do you prove what happened?** Every decision can be written to a
  SHA-256 hash-chained `EvidenceLedger` with portable proof receipts.

## Where SINT Fits

SINT is not a replacement for MCP, A2A, ROS 2, MAVLink, MQTT, OPC UA, Open-RMF,
or industrial robot tooling. It is the enforcement layer in front of those
systems:

- **MCP security:** authorize tool calls before an MCP server executes them.
- **Agent runtime governance:** add pre-tool authorization, typed deny/escalate
  outcomes, and evidence references to agent frameworks.
- **Robotics and drones:** enforce ROS 2, MAVLink, PX4, and fleet actions with
  physical constraints and e-stop semantics.
- **Industrial automation:** govern OPC UA, MQTT/Sparkplug, SRCI, simulator, and
  offline robot-program paths before PLC or robot actions touch equipment.
- **Consumer and regulated data:** apply consent, caregiver delegation,
  differential privacy, and audit exports for smart-home and health workflows.

## Latest Implementation Highlights

- **Installable MCP proxy:** `npx -y sint-mcp --stdio` runs the security-first
  multi-MCP proxy.
- **Industrial humanoid shipyard safety:** executable conformance fixtures now
  cover Persona-style shipyard humanoid welding, hot-work permits, fire watch,
  fume extraction, confined-space gas safety, bystander escalation,
  simulation-to-execution drift, material load envelopes, and unconditional
  e-stop rollback.
- **Shipyard bridge and evidence scaffolding:** ROS 2 weld-start profile
  helpers, OPC UA safety-signal mappings, Isaac Sim receipt stubs, and
  `sintctl shipyard evidence export` generate hash-chained JSONL evidence for
  supervisor review, remote survey support, and incident reconstruction.
- **Agent commerce governance:** the Economic Layer now includes a conformance
  profile for agent-to-agent task markets: task creation, bids, worker
  selection, benchmark-proof submission, settlement release, and x402-style
  payment permits.
- **Five-minute interceptor demo:** `pnpm run demo:interceptor-quickstart`
  shows `request -> decision -> receipt` and the fail-closed path.
- **Production gateway posture:** production mode requires durable stores,
  explicit authentication, readiness checks, and signature enforcement.
- **Industrial action pack:** `pnpm run demo:factory-action` and
  `pnpm run demo:industrial-pack` verify deny, escalate, approve, simulate, and
  receipt-chain flows before vendor adapter execution.
- **Autonomy supervisor:** `@pshkv/autonomy-supervisor` adds an authority lane
  for managed autonomy: `stable -> metacognitive_recovery ->
  assisted_recovery -> regulated_control`.
- **External evidence packets:** OWASP Agentic AI landscape, MITRE ATLAS
  candidate mappings, AAIF RFC-001 packet, NIST bundle, dependency review, and
  production-slice validation artifacts are published under `docs/`.

Academic and compliance grounding: SINT is designed with reference to IEC 62443
FR1-FR7, EU AI Act Article 13, and NIST AI RMF. The evaluation framework
references the ROSClaw empirical safety study
([arXiv:2603.26997](https://arxiv.org/abs/2603.26997)) and MCP security
analysis ([arXiv:2601.17549](https://arxiv.org/abs/2601.17549)).

```
Agent ──► SINT Bridge ──► Policy Gateway ──► Allow / Deny / Escalate
                               │
                       Evidence Ledger (SHA-256 hash-chained)
                               │
                    ProofReceipt (pluggable attestation)
```

## Install the MCP server

The installable server entrypoint is `sint-mcp`.

```bash
npx -y sint-mcp --stdio
npx -y sint-mcp --config ./sint-mcp.config.example.json --stdio
```

If you prefer containers, build and run the repo root `Dockerfile`:

```bash
docker build -t sint-mcp .
docker run --rm -i sint-mcp
```

## Try the interceptor flagship in 5 minutes

If you want the fastest builder-facing path into the SEP-1763 interceptor work:

```bash
pnpm install
pnpm run build
pnpm run demo:interceptor-quickstart
```

That walkthrough shows the full flagship loop in one terminal transcript:
- MCP-style request enters the interceptor
- SINT returns `allow` or `escalate`
- an audit receipt is generated for the allowed path
- execution fail-closes when a gate prerequisite is missing

Start here:
- [`docs/guides/sint-pdp-interceptor-quickstart.md`](docs/guides/sint-pdp-interceptor-quickstart.md)
- [`packages/sint-pdp-interceptor`](packages/sint-pdp-interceptor)

## Production-Ready Core

For production deployments, SINT now fails closed unless the gateway is started
with durable stores and explicit authentication:

```bash
SINT_ENV=production
SINT_STORE=postgres
SINT_CACHE=redis
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
SINT_API_KEY=...
SINT_REQUIRE_SIGNATURES=true
SINT_WS_ALLOW_QUERY_API_KEY=false
```

Use `/v1/ready` as the orchestration health gate; it verifies the configured
store and cache, while `/v1/health` only proves the process is alive.

Production references:
- [`docs/guides/gateway-production-hardening.md`](docs/guides/gateway-production-hardening.md)
- [`docs/guides/production-slice-verification.md`](docs/guides/production-slice-verification.md)
- [`docs/guides/docker-deployment.md`](docs/guides/docker-deployment.md)

## Why SINT?

AI agents now execute code, call tools, move money, operate robots, control
smart-home devices, and interact with industrial systems. The risk is no longer
only prompt quality; it is whether the runtime has a verifiable control point
between "the model decided" and "the world changed."

SINT makes that control point explicit. It turns agent execution into a governed
workflow with scoped authority, pre-action policy evaluation, operator review,
physical limits, revocation, and audit evidence.

### Capability Coverage

| Capability | **SINT Protocol** | Microsoft AGT | MCP Baseline | SROS2 |
|---|---|---|---|---|
| Physical constraint enforcement (velocity, force, geofence) | ✅ In token | ❌ | ❌ | ❌ |
| Tier-based human oversight (T0–T3) | ✅ 4-tier | ⚠️ Execution rings | ❌ | ❌ |
| Append-only hash-chained audit | ✅ SHA-256 | ⚠️ Logging | ❌ | ❌ |
| ROS 2 / MAVLink / industrial bridges | ✅ 12 bridges | ❌ Digital only | ❌ | ⚠️ ROS only |
| Consumer smart home governance | ✅ Home Assistant + Matter | ❌ | ❌ | ❌ |
| HIPAA + GDPR health data access | ✅ FHIR + HealthKit | ❌ | ❌ | ❌ |
| OWASP ASI01–ASI10 coverage | ✅ 10/10 Full | ✅ 10/10 | ❌ | ❌ |
| Economic routing + budgets | ✅ bridge-economy | ❌ | ❌ | ❌ |
| Swarm collective constraints | ✅ SwarmCoordinator | ❌ | ❌ | ❌ |
| E-stop / CircuitBreaker | ✅ EU AI Act Art. 14 | ✅ Kill switch | ❌ | ❌ |
| Caregiver delegation + consent | ✅ FHIR Consent tokens | ❌ | ❌ | ❌ |
| Differential privacy ledger | ✅ Per-query epsilon budget | ❌ | ❌ | ❌ |

SINT is designed for physical AI and regulated data workflows where actions can
be irreversible: robots, drones, smart homes, health fabric, industrial control,
and critical infrastructure. [Microsoft AGT](https://github.com/microsoft/agent-governance-toolkit)
focuses on digital/software governance patterns; SINT focuses on pre-action
enforcement across tool, robotics, and industrial execution boundaries.

**The empirical case for SINT:**
- **ROSClaw (IROS 2026):** Up to 4.8× spread in out-of-policy LLM action proposals across frontier models under identical safety envelopes. The 3.4× divergence between frontier backends is measurable, reproducible, and persistent.
- **MCP security (arXiv:2601.17549):** 10 documented real-world MCP breaches in under 8 months, including a CVSS 9.6 command injection affecting 437,000 downloads.
- **SROS2:** Formally demonstrated to contain 4 critical vulnerabilities at ACM CCS 2022, including access-control bypasses permitting arbitrary command injection.
- **Unitree BLE worm (September 2025):** Hardcoded crypto keys enabled wormable BLE/Wi-Fi command injection across robot fleets — precisely the scenario SINT's per-agent token scoping and real-time revocation prevent.

**Core guarantees:**
- No agent action ever bypasses the Policy Gateway (invariant I-G1: No Bypass)
- Every decision is recorded in a tamper-evident SHA-256 hash-chained ledger (invariant I-G3: Ledger Primacy)
- Physical constraints (velocity, force, geofence) are enforced at the protocol level — in the token, not in config
- Tier-gated verifiable compute hooks support provable-execution evidence on critical actions
- E-stop is universal across all non-terminal DFA states (invariant I-G2: E-stop Universality)
- Per-agent capability tokens with real-time revocation

## Quick Start

```bash
# Prerequisites: Node.js >= 22, pnpm >= 9
pnpm install
pnpm run build
pnpm run test        # full workspace test suite
```

### Start the Gateway Server

```bash
pnpm --filter @sint/gateway-server dev
# → http://localhost:3100/v1/health
# → http://localhost:3100/v1/ready
# → http://localhost:3100/v1/docs
```

### Start Production-Like Stacks (One Command)

```bash
pnpm run stack:dev
pnpm run stack:edge
pnpm run stack:prod-lite
pnpm run stack:gazebo-validation
pnpm run stack:isaac-sim-validation
```

Compose profiles:
- [`docker/compose/dev.yml`](docker/compose/dev.yml)
- [`docker/compose/edge.yml`](docker/compose/edge.yml)
- [`docker/compose/prod-lite.yml`](docker/compose/prod-lite.yml)
- [`docker/compose/gazebo-validation.yml`](docker/compose/gazebo-validation.yml)
- [`docker/compose/isaac-sim-validation.yml`](docker/compose/isaac-sim-validation.yml)

### Developer Docs Site (`docs.sint.gg`)

```bash
pnpm run docs:dev
pnpm run docs:build
pnpm run docs:preview
```

Docs source lives in [`docs/`](docs), VitePress config is in [`docs/.vitepress/config.mts`](docs/.vitepress/config.mts), and deployment is handled by [`docs-site.yml`](.github/workflows/docs-site.yml).

Deploy note:
- branch builds validate docs locally and in CI
- public `docs.sint.gg` deployment publishes from `main` under GitHub Pages environment rules

Community/adoption assets:
- [`docs/community/discord-launch-runbook.md`](docs/community/discord-launch-runbook.md)
- [`docs/community/aaif-rfc001-submission-packet.md`](docs/community/aaif-rfc001-submission-packet.md)
- [`docs/community/discord-launch-kit.md`](docs/community/discord-launch-kit.md)
- [`docs/community/external-contributor-onboarding.md`](docs/community/external-contributor-onboarding.md)
- [`docs/community/good-first-issues-board.md`](docs/community/good-first-issues-board.md)
- [`docs/community/open-source-collaboration-replies.md`](docs/community/open-source-collaboration-replies.md)
- [`docs/community/physical-ai-runtime-safety-working-group.md`](docs/community/physical-ai-runtime-safety-working-group.md)
- [`docs/community/owasp-agentic-landscape-submission.md`](docs/community/owasp-agentic-landscape-submission.md)
- [`docs/security-bulletins/2026-04.md`](docs/security-bulletins/2026-04.md)

### Run a Single Package

```bash
pnpm --filter @sint/gate-policy-gateway test
pnpm --filter @sint/bridge-mcp test
```

## Consumer Domains: Smart Home & Health

SINT extends far beyond industrial robotics. Two major consumer domains now have governance frameworks:

### Consumer Smart Home (Home Assistant + Matter)

AI agents accessing your smart home go through the Policy Gateway:

```typescript
import { HAInterceptor } from "@sint/bridge-homeassistant";

const interceptor = new HAInterceptor({
  policyGateway,
  homeAssistantHost: "homeassistant.local",
});

// Claude says: "unlock the front door"
const result = await interceptor.intercept({
  toolName: "call_service",
  toolInput: { domain: "lock", service: "unlock", entity_id: "lock.front_door" },
});
// → Escalates to T2_ACT (requires human approval)
// → Evidence Ledger records the decision and outcome
```

**Tier-appropriate defaults:**
- **T0 (OBSERVE)**: Security cameras, sensors (read-only, no facial recognition)
- **T1 (PREPARE)**: Lights, thermostats, media players (logged auto-allow)
- **T2 (ACT)**: Smart locks, garage doors, alarms (requires approval)
- **T3 (COMMIT)**: Create/modify automations (mandatory human review)

See [`packages/bridge-homeassistant`](packages/bridge-homeassistant) and [`packages/bridge-matter`](packages/bridge-matter).

### Health Fabric (FHIR + HealthKit/Health Connect)

Patient data accessed by AI agents goes through consent-based governance:

```typescript
import { createFHIRConsentToken } from "@sint/bridge-health";

// Patient grants AI agent 7-day read access to health observations
const consentToken = createFHIRConsentToken(
  "did:key:patient123",   // grantor (patient)
  "did:key:aiagent456",   // grantee (AI agent)
  ["Observation", "DiagnosticReport"],
  ["read"],
  new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
  { scope: "patient-privacy", purposeOfUse: ["TREAT"] }
);

await policyGateway.issueToken(consentToken);
```

**Civil liberties guarantees:**
- **On-device first**: Raw sensor data (heart rate, blood pressure) stays on device; only aggregates egress
- **Differential privacy**: Every query consumes an epsilon budget; exhausted budget = no more access
- **Caregiver delegation**: Elderly parent grants adult child 30-day, revocable access to health data
- **HIPAA + GDPR**: Consent tokens, user-owned keys, audit ledger export for patient access rights

See [`packages/bridge-health`](packages/bridge-health) and the [consumer smart home integration guide](docs/guides/consumer-smart-home-integration.md).

---

## SINT Operator Interface

A voice-first, HUD-based control surface for SINT operators. Every command flows through the Policy Gateway.

```bash
pnpm run stack:interface  # starts gateway + interface + postgres + redis
# Opens: http://localhost:3202
```

Features:
- **Voice input**: Web Speech API, zero external dependencies, real-time transcript
- **Command HUD**: three-panel approvals, action stream, and context view
- **Operator memory**: ledger-backed persistent context (`@sint/memory`)
- **Proactive notifications**: `sint__notify` runs as T2 and requires confirmation
- **T2/T3 approvals**: one-click approve/deny with timeout countdown

See [docs/guides/sint-interface.md](docs/guides/sint-interface.md) for full setup and usage.

## For AI Agents

If you are an AI agent (Claude, GPT, Gemini, Cursor, etc.) working in this repo, read **[AGENTS.md](AGENTS.md)** first. It covers key invariants, common mistakes, and entry points for the most common tasks. For deeper implementation details, see **[CLAUDE.md](CLAUDE.md)**.

## Architecture

```
┌──────────────────────────────────────────────────────────────┐
│  AI Agents / Foundation Models                               │
│  (Claude, GPT, Gemini, open-source)                         │
└──────────────────┬───────────────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────────────┐
│  SINT Bridge Layer (L1)                                      │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐  │
│  │ bridge-mcp │ │ bridge-ros2│ │ bridge-a2a │ │ bridge-  │  │
│  │ MCP tools  │ │ ROS topics │ │ Google A2A │ │ open-rmf │  │
│  └────────────┘ └────────────┘ └────────────┘ └──────────┘  │
│  ┌──────────────────────┐ ┌───────────────────────────────┐  │
│  │ bridge-mqtt-sparkplug│ │ bridge-opcua                  │  │
│  │ Industrial IoT       │ │ PLC / OT control plane bridge │  │
│  └──────────────────────┘ └───────────────────────────────┘  │
│  Per-resource state: UNREGISTERED→PENDING_AUTH→AUTHORIZED    │
│  →ACTIVE→SUSPENDED (real-time revocation without restart)    │
└──────────────────┬───────────────────────────────────────────┘
                   │ SintRequest (UUIDv7, Ed25519, resource, action, physicalContext)
┌──────────────────▼───────────────────────────────────────────┐
│  SINT Gate (L2) — THE choke point                           │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  PolicyGateway.intercept()                              │ │
│  │  1. Schema validation (Zod)                             │ │
│  │  2. Token validation (Ed25519 + expiry + revocation)    │ │
│  │  3. Resource scope check                                │ │
│  │  4. Per-token rate limiting (sliding window)            │ │
│  │  5. Physical constraint enforcement                     │ │
│  │  6. Forbidden action sequence detection                 │ │
│  │  7. Tier assignment: max(BaseTier, Δ_human, Δ_trust...) │ │
│  │  8. T2/T3 → escalate to approval queue                 │ │
│  │  9. T0/T1 + approved T2/T3 → allow                     │ │
│  │  10. Bill via EconomyPlugin (if configured)             │ │
│  └─────────────────────────────────────────────────────────┘ │
│                          ↓                                   │
│  EvidenceLedger (SHA-256 hash chain + ProofReceipt)        │
└──────────────────────────────────────────────────────────────┘
```

### APS vs SINT Primitives

| APS Concept | SINT Implementation |
|-------------|-------------------|
| Principal | `agentId` (Ed25519 public key) + W3C DID identity |
| Capability | `SintCapabilityToken` (Ed25519-signed, scoped, attenuatable) |
| Authority | `PolicyGateway.intercept()` — single choke point |
| Confinement | Per-token resource scope + physical constraints (velocity, force, geofence) |
| Revocation | `RevocationStore` + ConsentPass endpoint (real-time) |
| Audit | `EvidenceLedger` — append-only, SHA-256 hash-chained |

## Packages

### Gate (Security Core)

| Package | Description | Tests |
|---------|-------------|-------|
| [`@sint/core`](packages/core) | Types, Zod schemas, tier constants, formal DFA states | — |
| [`@sint/gate-capability-tokens`](packages/capability-tokens) | Ed25519 tokens, delegation, W3C DID identity | 55 |
| [`@sint/gate-policy-gateway`](packages/policy-gateway) | Authorization engine: tiers, constraints, rate limiting, M-of-N quorum | 256 |
| [`@sint/gate-evidence-ledger`](packages/evidence-ledger) | SHA-256 hash-chained append-only audit log with pluggable attestation | 45 |

### Bridges (15 bridges)

**Industrial & Robotics (9)**

| Package | Description | Tests |
|---------|-------------|-------|
| [`@sint/bridge-mcp`](packages/bridge-mcp) | MCP tool call interception and risk classification | 66 |
| [`@sint/bridge-ros2`](packages/bridge-ros2) | ROS 2 topic/service/action interception with physics extraction | 20 |
| [`@sint/bridge-a2a`](packages/bridge-a2a) | Google A2A Protocol bridge for multi-agent coordination | 38 |
| [`@sint/bridge-iot`](packages/bridge-iot) | Generic MQTT/CoAP edge IoT bridge with gateway session interception | 21 |
| [`@sint/bridge-mqtt-sparkplug`](packages/bridge-mqtt-sparkplug) | MQTT Sparkplug profile mapping with industrial command tiering defaults | 8 |
| [`@sint/bridge-opcua`](packages/bridge-opcua) | OPC UA node/method mapping with safety-critical write/call promotion | 6 |
| [`@sint/bridge-open-rmf`](packages/bridge-open-rmf) | Open-RMF fleet/facility mapping for warehouse dispatch workflows | 5 |
| [`@sint/bridge-grpc`](packages/bridge-grpc) | gRPC service/method profile mapping with default tier assignment | 5 |
| [`@sint/bridge-mavlink`](packages/bridge-mavlink) | MAVLink drone/UAV command bridge | 15 |

**Coordination & Economics (2)**

| Package | Description | Tests |
|---------|-------------|-------|
| [`@sint/bridge-economy`](packages/bridge-economy) | Economy bridge: balance, budget, trust, billing ports | 47 |
| [`@sint/bridge-swarm`](packages/bridge-swarm) | Multi-robot swarm coordination bridge | 9 |

**Consumer & Health (3) — Phase 1-5 Physical AI Governance**

| Package | Description | Tests |
|---------|-------------|-------|
| [`@sint/bridge-homeassistant`](packages/bridge-homeassistant) | Consumer smart home MCP interceptor with device profiles (locks, cameras, alarms, climate, vacuums) — Phase 1 | 36 |
| [`@sint/bridge-health`](packages/bridge-health) | FHIR R5 + HealthKit/Health Connect with differential privacy, consent tokens, and caregiver delegation — Phase 5 | — |
| [`@sint/bridge-matter`](packages/bridge-matter) | Matter protocol bridge for unified smart home device governance — Phase 2 | — |

Note: some consumer/health bridges are currently in “prototype API” state. CI may temporarily skip their `build`/`typecheck`/`test` scripts until their public interfaces are aligned with the `@sint/core` request/decision model.

**Reference Implementation (1)**

| Package | Description | Tests |
|---------|-------------|-------|
| [`@sint/sint-pdp-interceptor`](packages/sint-pdp-interceptor) | Reference SEP-1763 PDP adapter for MCP interceptor hosts backed by `PolicyGateway.intercept()` | 5 |

### Engine (AI Execution Layer)

| Package | Description | Tests |
|---------|-------------|-------|
| [`@sint/engine-system1`](packages/engine-system1) | Neural perception: sensor fusion, ONNX inference, anomaly detection | 42 |
| [`@sint/engine-system2`](packages/engine-system2) | Symbolic reasoning: behavior trees, task planning, System 1/2 arbitration | 86 |
| [`@sint/engine-hal`](packages/engine-hal) | Hardware Abstraction Layer: auto-detect hardware, select deployment profile | 26 |
| [`@sint/engine-capsule-sandbox`](packages/engine-capsule-sandbox) | WASM/TS capsule loading, validation, and sandboxed execution | 36 |
| [`@sint/avatar`](packages/avatar) | Avatar Layer (L5): behavioral identity profiles, CSML-driven tier escalation | 25 |

### Reference Capsules

| Package | Description | Tests |
|---------|-------------|-------|
| [`@sint/capsule-navigation`](capsules/navigation) | Waypoint following navigation reference capsule | 11 |
| [`@sint/capsule-inspection`](capsules/inspection) | Visual anomaly detection for manufacturing QA | 8 |
| [`@sint/capsule-pick-and-place`](capsules/pick-and-place) | Gripper control for pick-and-place tasks | 12 |

### Persistence

| Package | Description | Tests |
|---------|-------------|-------|
| [`@sint/persistence`](packages/persistence) | Storage interfaces + in-memory/PG/Redis implementations | 26 |
| [`@sint/persistence-postgres`](packages/persistence-postgres) | Production PostgreSQL adapters for ledger, revocation, and rate-limit durability | 14 |

### Apps & SDKs

| Package | Description | Tests |
|---------|-------------|-------|
| [`@sint/gateway-server`](apps/gateway-server) | Hono HTTP API with approvals, SSE streaming, A2A routes | — |
| [`sint-mcp`](apps/sint-mcp) | Security-first multi-MCP proxy server | — |
| [`@sint/interface`](apps/sint-interface) | Voice HUD and Conductor approvals for operator review | 25 |
| [`@sint/dashboard`](apps/dashboard) | Archived real-time approval dashboard with operator auth | 29 |
| [`@sint/client`](packages/client) | TypeScript SDK for the Gateway API (delegation, SSE) | — |
| [`@sint/sdk`](sdks/typescript) | Zero-dependency public TypeScript SDK aligned to gateway v0.2 contracts | 9 |
| [`@sint/conformance-tests`](packages/conformance-tests) | Security regression suite — all phases | — |

**Total: 49 repo packages, apps, examples, and capsules · CI-backed full-suite and conformance coverage**

> **Note:** Run `pnpm test` to get the current exact passing test count.

## Approval Tiers

Graduated authorization mapped to physical consequence severity:

| Tier | Name | DFA States | Auto-approved? | Example |
|------|------|------------|---------------|---------|
| **T0** | OBSERVE | → OBSERVING | Yes (logged) | Read sensor data, query database |
| **T1** | PREPARE | → PREPARING | Yes (audited) | Write file, save waypoint, stage plan |
| **T2** | ACT | ESCALATING → ACTING | Requires review | Move robot, operate gripper, publish `/cmd_vel` |
| **T3** | COMMIT | ESCALATING → COMMITTING | Requires human + optional M-of-N | Execute trade, novel environment entry, irreversible action |

Tier escalation triggers (Δ factors):
- `Δ_human`: Human presence sensor active in workspace → +1 tier
- `Δ_trust`: Agent trust score below threshold or recent failures → +1 tier
- `Δ_env`: Robot near physical boundary or unstructured environment → +1 tier
- `Δ_novelty`: Action outside validated distribution (novelty detector) → +1 tier

## Formal Specification

### Request Lifecycle DFA

SINT models every request as a deterministic finite automaton with 12 states:

```
IDLE → PENDING → POLICY_EVAL → PLANNING → OBSERVING/PREPARING/ACTING → COMMITTING → COMPLETED
                     ↓                              ↓
                ESCALATING                      ROLLEDBACK  (estop, execution failure)
                     ↓
                  FAILED     (approval denied, timeout)
```

The **ACTING** state is only reachable via POLICY_EVAL with a valid token. Physical actuation is structurally impossible without a valid capability token.

### Tier Assignment Function

```
Tier(r) = max(BaseTier(r), Δ_human(r), Δ_trust(r), Δ_env(r), Δ_novelty(r))
```

### Formal Invariants

| Invariant | Description |
|-----------|-------------|
| **I-T1** (Attenuation) | `scope(child_token) ⊆ scope(parent_token)` — delegation can only reduce permissions |
| **I-T2** (Unforgeability) | Capability tokens are Ed25519-signed; valid tokens are computationally unforgeable |
| **I-T3** (Physical Constraint Primacy) | Physical constraints (velocity, force, geofence) in a token cannot be weakened by any downstream layer |
| **I-G1** (No Bypass) | Physical actuation is only reachable from the ACTING DFA state, which is only reachable via POLICY_EVAL |
| **I-G2** (E-stop Universality) | The `estop` event transitions any non-terminal state to ROLLEDBACK unconditionally |
| **I-G3** (Ledger Primacy) | COMMITTING → COMPLETED requires `ledger_committed`; no action completes without a ledger record |

## Benchmark Results

PolicyGateway latency (measured on M3 MacBook Pro, pnpm run bench):

| Tier | p50 | p99 |
|------|-----|-----|
| T0 (OBSERVE) | ~1ms | ~3ms |
| T1 (PREPARE) | ~1ms | ~3ms |
| T2 (ACT) | ~1ms | ~3ms |
| T3 (COMMIT) | ~1ms | ~3ms |

The gateway adds sub-3ms overhead at p99 for all tiers. Run benchmarks: `pnpm run bench`.

ROS2 control-loop target benchmark:

| Path | SLA Target | Command |
|------|------------|---------|
| ROS2 command path (`/cmd_vel`) | `p99 < 10ms` | `pnpm run benchmark:ros2-loop` |

Industrial benchmark artifacts:
- [`docs/reports/industrial-benchmark-report.md`](docs/reports/industrial-benchmark-report.md)
- [`docs/reports/ros2-control-loop-benchmark.md`](docs/reports/ros2-control-loop-benchmark.md)

Compliance mapping assets:
- [`docs/compliance/tier-crosswalk-pack.md`](docs/compliance/tier-crosswalk-pack.md)

## Key Concepts

### Capability Tokens

Ed25519-signed capability tokens — the *only* authorization primitive. Unlike RBAC (ambient authority to principals), OCap requires explicit token presentation for every operation.

Token fields:
- **Resource scoping** — what the agent can access (`ros2:///cmd_vel`, `mcp://filesystem/*`, `a2a://agents.example.com/*`)
- **Action restriction** — what operations are allowed (`publish`, `call`, `subscribe`, `a2a.send`)
- **Physical constraints** — max velocity (m/s), max force (N), geofence polygon, time window, rate limit
- **Verifiable compute requirements** — optional proof type/verifier/freshness/public-input constraints for T2/T3 actions
- **Delegation chains** — max 3 hops, attenuation only (invariant I-T1)
- **Revocation** — instant invalidation via revocation store (ConsentPass endpoint)
- **W3C DID identity** — `did:key:z6Mk...` format for agent portability

### Evidence Ledger

Every policy decision is recorded in a SHA-256 hash-chained append-only log. Chain integrity: `ℓ_k.previousHash = SHA256(canonical(ℓ_{k-1}))`. A gap or hash mismatch constitutes tamper evidence.

For portable verification across bridges and external tooling, SINT now routes receipt and tool-definition signing through a shared deterministic canonical JSON serializer instead of relying on insertion-order-sensitive `JSON.stringify()` behavior.

For strong-tier flows, SINT can emit a linked bilateral receipt pair: a gate receipt before execution is allowed to proceed and a completion receipt once execution settles. The pair shares a stable `actionRef` and `linkageHash` so auditors can verify both authorization and outcome as one governed action.

**Retention policy:**

| Tier | Retention |
|------|-----------|
| T0 (OBSERVE) | 30 days |
| T1 (PREPARE) | 90 days |
| T2 (ACT) | 180 days |
| T3 (COMMIT) | 365 days (indefinite if legal hold) |

### CSML: Composite Safety-Model Latency

A deployment metric that fuses behavioral and physical safety dimensions:

```
CSML(m, p, t) = α·AR_m + β·BP_m + γ·SV_m - δ·CR_m + ε·𝟙[ledger_intact(t)]
```

CSML above a deployment threshold θ automatically escalates all subsequent requests from that model backend to the next tier.

## Compliance Mapping

### IEC 62443 FR1–FR7

| FR | Title | SINT Mechanism |
|----|-------|----------------|
| FR1 | Identification & Authentication | SintCapabilityToken with Ed25519 agent identity; W3C DID portability |
| FR2 | Use Control | Four-tier Approval Gate; `maxRepetitions` constraint; per-resource action allowlists |
| FR3 | System Integrity | SHA-256 hash-chained Evidence Ledger; ProofReceipt for T2/T3 (TEE attestation planned) |
| FR4 | Data Confidentiality | Zenoh TLS transport; capability scope prevents sensor access without explicit token |
| FR5 | Restricted Data Flow | Policy Gateway allowlists; `geofence` constraint; SINT Bridge per-topic DFA |
| FR6 | Timely Response | `safety.estop.triggered` event; E-stop universality invariant I-G2 |
| FR7 | Resource Availability | Per-token rate limiting; `maxRepetitions`; budget enforcement in capsule sandbox |

### EU AI Act Article 13

| Requirement | SINT Approach |
|-------------|---------------|
| Logging and traceability | SHA-256 hash-chained Evidence Ledger — tamper detection is cryptographic |
| Human oversight | Dynamic Consent + T3 approval gate — T3 actions cannot execute without recorded human approval |
| Risk management | Tier escalation based on real-time physical context (Δ_human, Δ_env, Δ_novelty) |

### Tier Crosswalk (NIST AI RMF / ISO 42001 / EU AI Act)

| SINT Tier | NIST AI RMF | ISO/IEC 42001 | EU AI Act |
|-----------|-------------|---------------|------------|
| T0 Observe | MAP + MEASURE + MANAGE monitoring controls | Clause 9 + Clause 8 controls | Article 12 + Article 13 |
| T1 Prepare | GOVERN + MANAGE controlled write path | Clause 8.1/8.2 operational risk treatment | Article 9 + Article 12 |
| T2 Act | MANAGE risk response with accountable oversight | Clause 8 + Clause 6 operational controls | Article 14 + Article 15 |
| T3 Commit | Highest-consequence GOVERN + MANAGE controls | Clause 8.3 + Clause 10 corrective governance | Article 14(4)(e) + Articles 9/12/15 |

Machine-readable crosswalk endpoint: `GET /v1/compliance/tier-crosswalk`

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/.well-known/sint.json` | Public protocol discovery (version, bridges, profiles, schemas) |
| `GET` | `/v1/health` | Health check |
| `POST` | `/v1/intercept` | Evaluate a single request |
| `POST` | `/v1/intercept/batch` | Evaluate multiple requests (207 Multi-Status) |
| `POST` | `/v1/tokens` | Issue a capability token |
| `POST` | `/v1/tokens/delegate` | Delegate (attenuate) a token |
| `POST` | `/v1/tokens/revoke` | Revoke a token |
| `GET` | `/v1/ledger` | Query audit ledger events |
| `GET` | `/v1/approvals/pending` | List pending approval requests |
| `POST` | `/v1/approvals/:id/resolve` | Approve or deny a request (M-of-N quorum) |
| `GET` | `/v1/approvals/events` | SSE stream for real-time approval events |
| `GET` | `/v1/approvals/ws` | WebSocket stream for low-latency approval events |
| `POST` | `/v1/a2a` | JSON-RPC 2.0 A2A protocol endpoint |
| `GET` | `/v1/metrics` | Prometheus metrics |
| `GET` | `/v1/openapi.json` | OpenAPI surface for gateway integration |
| `GET` | `/v1/compliance/tier-crosswalk` | SINT tier mapping to NIST AI RMF / ISO 42001 / EU AI Act controls |
| `POST` | `/v1/economy/route` | Cost-aware route selection with optional x402 pay-per-call quotes |

## Development Phases

### SINT Protocol Core (6 phases complete)

| Phase | Description | Tests |
|-------|-------------|-------|
| **Phase 1** (complete) | Security Wedge — capability tokens, PolicyGateway, EvidenceLedger | 425 |
| **Phase 2** (complete) | Engine Core — bridge-mcp, bridge-ros2, engine packages, persistence, gateway-server | +221 (646) |
| **Phase 3** (complete) | Economy Bridge — @sint/bridge-economy with port/adapter pattern, EconomyPlugin | +91 (737) |
| **Phase 4** (complete) | Standards Alignment — A2A bridge, rate limiting, M-of-N quorum, W3C DID identity | +78 |
| **Phase 5** (complete) | Protocol Surface v0.2 — discovery/OpenAPI/schema endpoints, industrial profiles | shipped |
| **Phase 6** (complete) | Engine layer — System1/2 engines, HAL, capsule sandbox, Avatar/CSML, reference capsules | shipped |

### Physical AI Governance Roadmap 2026–2029 (Phases 1–5 in progress)

Extending SINT to consumer, health, and critical infrastructure domains:

| Phase | Focus | Status | Examples |
|-------|-------|--------|----------|
| **Phase 1** | Consumer Smart Home (Q2–Q3 2026) | ✅ Complete | [`bridge-homeassistant`](packages/bridge-homeassistant) — Home Assistant MCP interceptor with 12 device classes (locks, cameras, alarms, climate, robot vacuums). Tier-appropriate defaults: locks/alarms→T2, lights/climate→T1, cameras→T0. |
| **Phase 2** | Matter Protocol Unification (Q3–Q4 2026) | ✅ Complete | [`bridge-matter`](packages/bridge-matter) — Unified smart home governance across Matter-certified devices. Device discovery, service profiles, and tier assignment. |
| **Phase 3** | Occupancy & Human Presence (2027) | 📋 Planned | `Δ_human` plugin: escalate robot vacuums to T2 when occupancy detected. Build on Phase 1 sensor fusion. |
| **Phase 4** | Critical Infrastructure (2027–2028) | 📋 Planned | Power grids, water systems, industrial facilities. Formalized risk models and emergency-mode escalation. |
| **Phase 5** | Health Fabric & Wellbeing (Q4 2026–Q1 2027) | ✅ Complete | [`bridge-health`](packages/bridge-health) — FHIR R5 consent governance, HealthKit/Health Connect on-device processing, differential privacy ledger, and caregiver delegation tokens. HIPAA + GDPR alignment. |

See [docs/roadmaps/PHYSICAL_AI_GOVERNANCE_2026-2029.md](docs/roadmaps/PHYSICAL_AI_GOVERNANCE_2026-2029.md) for full roadmap.

## Deployment

### Railway (Recommended)

```bash
brew install railway
railway login
./scripts/railway-setup.sh
railway variables --set SINT_STORE=postgres SINT_CACHE=redis SINT_API_KEY=$(openssl rand -hex 32)
railway up
```

### Docker Compose

```bash
docker-compose up
# Gateway:   http://localhost:3100
# Dashboard: http://localhost:3201
# Postgres:  localhost:5432
# Redis:     localhost:6379
```

## Tech Stack

- **Runtime:** Node.js 22+
- **Language:** TypeScript 5.7 (strict mode)
- **Monorepo:** pnpm workspaces + Turborepo
- **HTTP:** Hono
- **Validation:** Zod
- **Crypto:** @noble/ed25519, @noble/hashes (audited, zero-dependency)
- **MCP SDK:** @modelcontextprotocol/sdk
- **Dashboard:** React 19, Vite 6
- **Testing:** Vitest (run `pnpm test` for current count)
- **Infra:** Docker, PostgreSQL 16+, Redis 7, GitHub Actions CI, Railway

## Docs & Artifacts

- Protocol spec: [`docs/SINT_v0.2_SPEC.md`](docs/SINT_v0.2_SPEC.md)
- SIP governance: [`docs/SIPS.md`](docs/SIPS.md)
- Release notes: [`docs/RELEASE_NOTES_v0.2.md`](docs/RELEASE_NOTES_v0.2.md)
- Conformance matrix: [`docs/CONFORMANCE_CERTIFICATION_MATRIX_v0.2.md`](docs/CONFORMANCE_CERTIFICATION_MATRIX_v0.2.md)
- EU AI Act mapping: [`docs/compliance/eu-ai-act-mapping.md`](docs/compliance/eu-ai-act-mapping.md)
- ISO 13482 alignment: [`docs/compliance/iso-13482-alignment.md`](docs/compliance/iso-13482-alignment.md)
- Formal threat model: [`docs/security/formal-threat-model.md`](docs/security/formal-threat-model.md)
- MITRE ATLAS candidate mappings: [`docs/security/mitre-atlas-agent-technique-mappings.md`](docs/security/mitre-atlas-agent-technique-mappings.md)
- Getting started: [`docs/getting-started.md`](docs/getting-started.md)
- Deployment profiles: [`docs/profiles/`](docs/profiles/)
- Examples: [`examples/`](examples/) (hello-world, warehouse-amr, industrial-cell)
- Multi-language SDKs: [`sdks/`](sdks/) (TypeScript, Python, Go)
- Operator CLI: [`apps/sintctl/README.md`](apps/sintctl/README.md)
- Standalone certification tool guide: [`docs/guides/standalone-certification-tool.md`](docs/guides/standalone-certification-tool.md)
- Persistence baseline guide: [`docs/guides/persistence-baseline.md`](docs/guides/persistence-baseline.md)
- WebSocket approvals guide: [`docs/guides/websocket-approvals.md`](docs/guides/websocket-approvals.md)
- API docs site guide: [`docs/guides/api-documentation-site.md`](docs/guides/api-documentation-site.md)
- gRPC bridge guide: [`docs/guides/grpc-bridge-skeleton.md`](docs/guides/grpc-bridge-skeleton.md)
- AutoGen interop fixtures guide: [`docs/guides/autogen-interop-fixtures.md`](docs/guides/autogen-interop-fixtures.md)
- AgentSkill delegated authority fixtures guide: [`docs/guides/agentskill-authz-interop-fixtures.md`](docs/guides/agentskill-authz-interop-fixtures.md)
- Industrial humanoid shipyard safety pack: [`docs/guides/industrial-humanoid-shipyard-safety-pack.md`](docs/guides/industrial-humanoid-shipyard-safety-pack.md)
- Industrial humanoid shipyard sprint: [`docs/roadmaps/industrial-humanoid-shipyard-safety-sprint.md`](docs/roadmaps/industrial-humanoid-shipyard-safety-sprint.md)
- Shipyard humanoid evidence export sample: [`docs/reports/shipyard-humanoid-evidence-export.jsonl`](docs/reports/shipyard-humanoid-evidence-export.jsonl)
- action_ref identity/explainability profile: [`docs/specs/action-ref-identity-explainability-profile.md`](docs/specs/action-ref-identity-explainability-profile.md)
- Payment governance profile (Economic Layer v1): [`docs/specs/payment-governance-profile-v1.md`](docs/specs/payment-governance-profile-v1.md)
- Agent commerce governance profile: [`docs/specs/agent-commerce-governance-profile-v1.md`](docs/specs/agent-commerce-governance-profile-v1.md)
- OpenAI Agents SDK governance guide: [`docs/guides/openai-agents-sdk-integration.md`](docs/guides/openai-agents-sdk-integration.md)
- Cursor integration guide: [`docs/guides/cursor-integration.md`](docs/guides/cursor-integration.md)
- Benchmark report: [`docs/reports/industrial-benchmark-report.md`](docs/reports/industrial-benchmark-report.md)
- ROS2 loop benchmark report: [`docs/reports/ros2-control-loop-benchmark.md`](docs/reports/ros2-control-loop-benchmark.md)
- Hardware safety controller roadmap: [`docs/roadmaps/hardware-safety-controller-integration.md`](docs/roadmaps/hardware-safety-controller-integration.md)
- Hardware safety handshake fixture: [`packages/conformance-tests/fixtures/industrial/hardware-safety-handshake.v1.json`](packages/conformance-tests/fixtures/industrial/hardware-safety-handshake.v1.json)
- Physical AI runtime safety fixtures: [`packages/conformance-tests/fixtures/physical-ai/runtime-safety-fixtures.v0.1.json`](packages/conformance-tests/fixtures/physical-ai/runtime-safety-fixtures.v0.1.json)
- Physical AI runtime safety fixture schema: [`packages/conformance-tests/fixtures/physical-ai/runtime-safety-fixture.schema.json`](packages/conformance-tests/fixtures/physical-ai/runtime-safety-fixture.schema.json)
- Certification bundle summary: [`docs/reports/certification-bundle-summary.md`](docs/reports/certification-bundle-summary.md)
- NIST submission playbook: [`docs/guides/nist-submission-playbook.md`](docs/guides/nist-submission-playbook.md)
- NIST submission bundle report: [`docs/reports/nist-submission-bundle.md`](docs/reports/nist-submission-bundle.md)

**Physical AI Governance (Consumer, Health, Critical Infrastructure)**

- Physical AI Governance Roadmap 2026–2029: [`docs/roadmaps/PHYSICAL_AI_GOVERNANCE_2026-2029.md`](docs/roadmaps/PHYSICAL_AI_GOVERNANCE_2026-2029.md) — Complete phases 1–5 timeline and specifications
- Consumer smart home integration guide: [`docs/guides/consumer-smart-home-integration.md`](docs/guides/consumer-smart-home-integration.md) — Home Assistant + Matter setup and deployment
- Home Assistant bridge package: [`packages/bridge-homeassistant`](packages/bridge-homeassistant) — 12 device classes with tier-appropriate defaults and occupancy-aware escalation
- Matter protocol bridge: [`packages/bridge-matter`](packages/bridge-matter) — Unified smart home governance across Matter-certified devices
- Health fabric bridge: [`packages/bridge-health`](packages/bridge-health) — FHIR R5 consent governance, HealthKit/Health Connect mapping, differential privacy ledger, caregiver delegation
- Implementation status: [`docs/IMPLEMENTATION_STATUS.md`](docs/IMPLEMENTATION_STATUS.md) — Session completion report and artifact inventory
- Execution summary: [`EXECUTION_SUMMARY.md`](EXECUTION_SUMMARY.md) — Phase completion metrics and deliverables
- Master index: [`INDEX.md`](INDEX.md) — Complete documentation navigation

## Design Principles

1. **Single choke point** — Every agent action flows through `PolicyGateway.intercept()`; no bridge adapter makes authorization decisions independently
2. **Result\<T, E\> over exceptions** — All fallible operations return discriminated unions, never throw
3. **Attenuation only** — Delegated tokens can only reduce permissions, never escalate (I-T1)
4. **Append-only audit** — The evidence ledger is INSERT-only with SHA-256 hash chain integrity (I-G3)
5. **Physical safety first** — Velocity, force, and geofence constraints live *in the token*, not in external config
6. **Interface-first persistence** — Storage adapters implement clean interfaces; swap in-memory for Postgres/Redis
7. **Fail-open on infrastructure** — Economy/rate-limit infrastructure failures do not block the safety path
8. **E-stop universality** — The hardware E-stop bypasses all token checks and is unconditional (I-G2)

## References

- ROSClaw: Empirical safety analysis of LLM-controlled physical AI — [arXiv:2603.26997](https://arxiv.org/abs/2603.26997) (IROS 2026)
- MCP Security Analysis: Architectural vulnerabilities in the Model Context Protocol — [arXiv:2601.17549](https://arxiv.org/abs/2601.17549)
- IEC 62443: Industrial automation and control systems cybersecurity standard
- EU AI Act Article 13: Transparency requirements for AI systems
- NIST AI RMF: AI Risk Management Framework
- W3C DID Core: Decentralized Identifiers specification

## Roadmap

The active execution pages are:

- [Protocol overview](docs/protocol.md)
- [Active roadmap](docs/roadmap.md)
- [End-of-year 2026 execution plan](docs/roadmaps/end-of-year-2026-execution-plan.md)
- [AAIF resubmission 2026](docs/roadmaps/aaif-resubmission-2026.md)
- [Physical AI Governance 2026–2029](docs/roadmaps/PHYSICAL_AI_GOVERNANCE_2026-2029.md)

The current emphasis is straightforward:

- production-ready gateway behavior
- release and evidence discipline
- collaborator-facing integration artifacts
- stronger external adoption and maintainership signals

## License

Apache-2.0

sint-protocol

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README