TruClaw — Biometric Guardrail for OpenClaw

Stop AI agents from executing dangerous actions without verified human authorization.

TruClaw integrates OpenClaw agents with the TruClaw iOS app to require biometric human verification for risky agent actions before they execute.

This allows developers and enterprises to safely run autonomous agents without risking unintended financial transactions, infrastructure changes, or other high-impact actions.

Demo

Short demo showing the flow:

1. A harmless check positions command executes normally
2. A sell order triggers an approval notification on the iPhone
3. The trade executes only after biometric verification in the TruClaw app

The Problem

AI agents with tool access can execute real-world actions:

• financial trades
• infrastructure changes
• database operations
• sending emails or messages

Without guardrails, a hallucination, prompt injection, or tool misuse could trigger these actions automatically.

TruClaw adds a strong safety primitive:

High-risk agent actions require biometric authorization on a trusted mobile device, backed by hardware attestation from the Secure Enclave.

TruClaw vs Native OpenClaw Approval

Why hardware attestation matters

When TruClaw authorizes an action, the approval is not just a message — it is a JWT signed by the iPhone's Secure Enclave. The Secure Enclave is a dedicated security processor that:

• generates and stores the signing key in hardware — the key never leaves the device
• binds the key to the specific iPhone — cannot be copied or exported
• requires a live biometric match to use the key

This means every TruClaw authorization produces cryptographic proof that:

1. A specific enrolled human was physically present
2. On a specific trusted device
3. At a specific point in time

No chat account compromise, no prompt injection, no replay attack can forge this.

How It Works

1. OpenClaw Agent detects a tool call
2. TruClaw Plugin intercepts via before_tool_call hook
3. Claude Haiku classifies the tool call as safe or dangerous
4. If dangerous → TruClaw Relay (Cloudflare Worker) sends push notification via Firebase Messaging
5. TruClaw iOS App receives the notification on your iPhone
6. User completes Face ID biometric match
7. iPhone Secure Enclave signs an authorization JWT — hardware-bound, tamper-proof
8. Plugin polls the relay, receives and verifies the JWT
9. isAbove21=true → action proceeds ✅ / isAbove21=false → action blocked ❌

Prerequisites

• OpenClaw 3.28+
• Node.js 18+
• Anthropic API key
• TruClaw iOS app installed on iPhone

Installation

1. Install TruClaw iOS app and enroll

Search "TruClaw" on the App Store. Complete one-time enrollment:

• Take a selfie
• Scan your Driver's License or Passport
• Green badge = enrolled

2. Clone and build

git clone https://github.com/sanjaymk908/trukyc-openclaw.git
mv trukyc-openclaw truclaw
cd truclaw
npm install
npm run build

3. Add plugin to ~/.openclaw/openclaw.json

"plugins": {
  "load": {
    "paths": [
      "/path/to/truclaw"
    ]
  },
  "entries": {
    "truclaw": {
      "enabled": true,
      "config": {}
    }
  }
}

4. Add environment variables

"env": {
  "TRUKYC_RELAY_URL": "https://trukyc-relay.trusources.workers.dev",
  "ANTHROPIC_API_KEY_TRUKYC": "your-anthropic-api-key"
}

5. Restart OpenClaw

openclaw gateway stop && sleep 3 && openclaw gateway install && sleep 5
openclaw plugins list | grep truclaw

6. Pair your iPhone

Send this in any OpenClaw channel (iMessage, Slack, Telegram, etc.): /trukyc-pair

Tap the pairing link on your iPhone — the TruClaw app opens and confirms pairing automatically.

FAQ

❓ Why doesn’t /trukyc-pair work in Slack or Discord?

Short answer: Slash commands are platform-native features and are not handled by OpenClaw’s message routing layer in Slack/Discord (especially in Socket Mode).

In Slack and Discord:

• /trukyc-pair is treated as a native slash command, not a normal message
• These require separate platform-specific configuration (e.g. Request URL, interactions endpoint)
• OpenClaw’s standard channel integrations (including Socket Mode) do not automatically intercept slash commands

👉 As a result, this will NOT work:

Example Interaction

Safe action — no approval needed

with trader skill check positions

Risky action — biometric required

with trader skill buy NVDA at $165

Flow:

1. Agent attempts trade
2. TruClaw intercepts the tool call
3. Push notification sent to iPhone
4. User opens TruClaw and completes Face ID
5. Secure Enclave signs authorization JWT
6. Plugin verifies JWT → trade executes ✅

If the user ignores the notification — times out after 5 minutes → blocked ❌ If Face ID fails — blocked ❌

Danger Classification

TruClaw uses Claude Haiku to classify every tool call in real time.

Flagged as dangerous:

• Shell commands that write, delete, or modify (rm, mv, cp)
• Network requests that send data (curl POST)
• Installing software (pip install, npm install)
• Sending messages, emails, or executing financial actions

Always safe (no challenge):

• Read-only shell commands (ls, cat, grep, find)
• Querying data or answering questions
• Git read operations (git status, git log, git diff)
• Explicitly safe tools: read, ls, list, session_status, memory_search

Security Properties

• Secure Enclave hardware attestation — every authorization is cryptographically signed by the iPhone's dedicated security processor
• Biometric binding — the signing key is device-bound and requires a live Face ID match to use
• Out-of-band approval — authorization happens on a separate trusted device, not the same channel as the agent
• Tamper-proof audit trail — signed JWTs with timestamp, device ID, and liveness score
• Prompt injection resistant — no chat-based command can forge a biometric authorization
• Enterprise compliance ready — hardware attestation maps to EU AI Act Article 14 (human oversight), NIST AI RMF, and SOC2 access control requirements

Privacy

• All face matching runs on-device using Apple's Vision framework
• No photos, selfies, or biometric data are stored or transmitted
• Only encrypted metadata (not images) stored in Secure Enclave
• Relay server stores only temporary session tokens (auto-deleted after 2 minutes)

License

MIT