RTQ — Risk-Adaptive Capability Security Runtime

RTQ is a security-focused capability-security runtime for Node.js, TypeScript, Model Context Protocol (MCP) servers, and mobile approval hosts. Security-critical packages declare zero third-party npm runtime dependencies. It turns "can this agent/tool do this?" into an evidence-backed security pipeline:

Command → Capability (registered) → Risk (authoritative) → Policy (default-deny)
       → Clarification (missing critical params) → Approval (human/device)
       → Authorization Ticket (signed, single-use, bound) → Execution (OS-sandboxed)
       → Audit (structured, redacted)

---

📥 Downloads & Live Metrics

Published npm Packages

---

💡 Why RTQ Was Created

While developing Aartiq, a disproportionate amount of engineering time was spent repeatedly implementing OS-level sandboxing, capability scoping, fine-grained permission gating, and challenge-response authorization from scratch.

RTQ was created to solve this problem for developers everywhere — packaging a security-focused capability security runtime into a clean suite of reusable packages. Developed and validated through automated security testing, RTQ allows developers to integrate capability security, OS-enforced sandboxing, Model Context Protocol (MCP) policy enforcement, and mobile QR challenge-response approvals into their applications without having to build security infrastructure from scratch.

---

🔬 System Capabilities & Limits

To provide full transparency, RTQ clearly delineates what is implemented, what is verified in CI, and what is outside its current scope:

✅ Implemented

• Capability Registry: Explicit capability registration with schema validation.
• Authoritative Risk Engine: Structural risk evaluation where caller-supplied risk claims can only raise, never lower, calculated risk.
• Declarative Default-Deny Policy: Missing or unlisted rules evaluate to denial.
• HMAC-Signed Single-Use Tickets: Ticket redemption state is managed by a process-local, atomic ticket store.
• OS Sandbox Adapters: Wrappers for macOS Seatbelt (sandbox-exec), Linux bubblewrap (bwrap), and Windows AppContainer + Job Objects.
• Redacted Audit Logging: Automatic sanitization of secrets in security logs.
• QR / Mobile Approval Protocol: Single-use challenge-response protocol with zero PIN transmission.

🧪 Verified in CI

• 12 Automated Security Invariants: Rigorous test suites asserting invariants INV-01 through INV-12.
• Cross-Platform Enforcement: Automated sandbox execution tests on macOS, Linux, and Windows runners.
• Cross-Language Protocol Vectors: Node.js vs Dart byte-exact challenge signature validation.
• 430+ Unit & Integration Tests: Comprehensive test coverage across all 12 monorepo packages.

⚠️ Scope & Evidence Limits

• Process-Local Ticket Store: Ticket single-use redemption is currently enforced in process-local memory. Distributed multi-node replay protection requires a distributed shared ticket store backend.
• No Formal Security Proof: Automated CI testing establishes empirical verification, not formal mathematical proof.
• Platform Key Storage: Mobile keypairs use platform secure storage (flutter_secure_storage utilizing Android Keystore / iOS Keychain where supported by OS and hardware capabilities).
• Host Trusted Computing Base (TCB): RTQ governs authorization, ticket verification, and process containment. The internal logic of registered execution handlers (e.g. system.execute) remains part of the host application's trusted computing base.
• No Independent Third-Party Audit: RTQ is an open-source alpha security runtime that has not undergone an independent third-party security audit.

---

🚀 Quick Start & Usage Guide

1. Installation

Install the main façade package in your project:

npm install @rtq/security

Or install the RTQ CLI globally:

npm install -g @rtq/cli

2. Runtime Capability & Policy Enforcement

import { createRTQ } from "@rtq/security";

// Initialize runtime with signing key from environment
const rtq = createRTQ({
  signingKey: process.env.RTQ_SIGNING_KEY!,
});

// Step 1: Explicitly register capabilities (no ambient execution)
rtq.registerCapability({
  name: "files.read",
  version: 1,
  description: "Read a file inside the workspace",
  inputSchema: {
    type: "object",
    properties: { path: { type: "string" } },
    required: ["path"],
    additionalProperties: false,
  },
  risk: { base: "low" },
  execute: async (ctx, input) => ({ ok: true, data: { path: input.path } }),
});

// Step 2: Register policy (default-deny: unlisted capabilities are denied)
rtq.registerPolicy({
  kind: "allow",
  capability: "files.read",
  reason: "Allow workspace file reads",
});

// Step 3: Authorize operation (receives cryptographically signed ticket)
const auth = await rtq.authorize({
  capability: "files.read",
  version: 1,
  input: { path: "/workspace/report.md" },
});

if (auth.decision === "allowed") {
  // Step 4: Execute inside OS sandbox with single-use ticket
  const outcome = await rtq.execute(auth.ticketId);
  console.log("Result:", outcome.result);
} else if (auth.decision === "approval_required") {
  console.log(
    "Human/Mobile approval required. Challenge ID:",
    auth.challengeId,
  );
}

3. Using the Security CLI

The @rtq/cli package provides actionable security inspection and testing commands:

# Inspect registered capabilities
RTQ_SIGNING_KEY=secret npx rtq capabilities --config settings/config.js

# Test policy enforcement against a candidate command
RTQ_SIGNING_KEY=secret npx rtq policy check command.json --config settings/config.js --origin remote

# Run real OS-level sandbox enforcement checks
npx rtq sandbox test

# Verify an authorization ticket signature
RTQ_SIGNING_KEY=secret npx rtq verify signature --ticket ticket.json

# Run environment and platform security diagnostics
npx rtq diagnostics

4. Model Context Protocol (MCP) Gateway Integration

Protect MCP servers with RTQ's security gateway:

import { createMCPGateway } from "@rtq/mcp";

const gateway = createMCPGateway({
  signingKey: process.env.RTQ_SIGNING_KEY!,
  enforceSandboxing: true,
});

// Register MCP tool mapping to capability
// Note: RTQ enforces authorization & sandboxing, but handler safety remains part of host TCB
gateway.registerToolCapability({
  toolName: "execute_script",
  capabilityName: "system.execute",
  version: 1,
});

5. Mobile Approval App (Android Flutter App)

For high-risk operations requiring user verification:

1. Download the Android APK: Download v0.1.0 APK.
2. Install on Android device (Android 12+, Java 17/Dart 3.11 target).
3. Scan QR Challenge: When RTQ returns approval_required, it renders a single-use QR challenge.
4. Local Ed25519 Signing: The mobile app verifies the challenge locally and signs the approval using device platform secure storage (flutter_secure_storage utilizing Android Keystore / iOS Keychain where supported).

---

🧪 Testing & Verification

npm run typecheck     # Whole-repo TypeScript validation
npm run format:check  # Code formatting validation
npm run build         # Build all 12 packages
npm test              # Run 430+ unit, contract & security tests

---

📄 License

Apache-2.0. See LICENSE and NOTICE. RTQ is an original implementation created by Latestinssan.