Truclaw Biometric

Biometric guardrail for OpenClaw. Intercepts dangerous tool calls and requires Face ID verification via TruClaw iOS app before execution. Biometric processin...

TruClaw — Biometric AI Guardrail

TruClaw stops your OpenClaw agent from executing dangerous actions without verified human authorization. When a sensitive tool call is detected — deleting files, sending messages, running shell commands — TruClaw sends a push notification to your iPhone. Complete Face ID to authorize. Ignore it to block.

Every authorization is backed by a Secure Enclave-signed JWT — hardware attestation that cryptographically proves a live human authorized the action on a specific trusted device. No chat account compromise, no prompt injection, no replay attack can forge this.

---

Privacy and cloud usage — what runs where

Component	Where it runs
Face matching and biometric processing	On-device only — Apple Vision framework
Biometric data (photos, face vectors)	Never leaves your iPhone
Danger classification (Claude Haiku)	Anthropic API — tool name and args only, no personal data
Push delivery	Cloudflare Worker relay + Firebase Messaging — session token only, no personal data
JWT signing	iPhone Secure Enclave — key never leaves device
Relay source code	Fully open: https://github.com/sanjaymk908/trukyc-openclaw/tree/main/cloudflare-worker

The relay handles two things only: forwarding FCM push notifications to your iPhone, and temporarily storing the signed JWT (auto-deleted after 2 minutes) for the plugin to pick up. It never sees biometric data, photos, or personal information.

You can self-host the relay on your own Cloudflare account using the included source code if you prefer not to use the shared relay endpoint.

---

Security transparency

• Plugin source: https://github.com/sanjaymk908/trukyc-openclaw/tree/main/
• Relay source: https://github.com/sanjaymk908/trukyc-openclaw/tree/main/cloudflare-worker
• The plugin runs in a privileged before_tool_call hook — review the source before installing
• The relay domain is trukyc-relay.trusources.workers.dev (Cloudflare Workers, owned by plugin author)
• Self-hosting the relay is supported and documented in the README

---

Requirements

• OpenClaw 3.28+
• TruClaw iOS app (search "TruClaw" on App Store)
• Anthropic API key (for Claude Haiku danger classification — tool names and args only)
• TRUKYC_RELAY_URL (default shared relay provided, self-hosting supported)

---

Setup (3 steps)

Step 1 — Install TruClaw iOS app

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

• Take a selfie
• Scan your Driver's License or Passport
• Green badge confirms successful enrollment

Your biometric profile is stored encrypted in your iPhone Secure Enclave. No photos or biometric data leave your device at any point.

Step 2 — Install and configure plugin

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

Add to ~/.openclaw/openclaw.json plugins section: "plugins": { "load": { "paths": ["/path/to/truclaw"] }, "entries": { "truclaw": { "enabled": true, "config": {} } } }

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

Restart OpenClaw: openclaw gateway stop && sleep 3 && openclaw gateway install && sleep 5 openclaw plugins list | grep trukyc

Step 3 — Pair your iPhone

Run in any OpenClaw channel: /trukyc-pair

A QR code appears. Scan it with the TruClaw iOS app. Done.

---

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 sends push notification via Firebase Messaging
5. TruClaw iOS App receives notification on your iPhone
6. User completes Face ID biometric match
7. iPhone Secure Enclave signs authorization JWT — hardware-bound, tamper-proof
8. Plugin polls relay, receives and verifies JWT
9. isAbove21=true → action proceeds / isAbove21=false → action blocked

---

TruClaw vs native OpenClaw approval

	OpenClaw /approve	TruClaw Biometric
Authorization method	Text command in chat	Face ID on iPhone
Proof of human	None	Secure Enclave hardware attestation
Spoofable	Yes — compromised account approves	No — requires physical device + live biometric
Audit trail	Chat message	Signed JWT with timestamp and device ID
Enterprise compliance	No cryptographic proof	Hardware-attested human proof

---

What gets flagged as dangerous

• Shell commands that write, delete, or modify (rm, mv, cp)
• Network requests that send data (curl POST, wget)
• Installing software (pip install, npm install)
• Sending messages or emails
• Financial operations, killing processes, modifying permissions

What passes through safely

• 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

---

Self-hosting the relay

If you prefer not to use the shared relay endpoint, deploy your own: cd trukyc-openclaw/cloudflare-worker wrangler deploy worker.js

Then update TRUKYC_RELAY_URL in openclaw.json to your own worker URL. Full instructions: https://github.com/sanjaymk908/trukyc-openclaw/tree/main/cloudflare-worker