Skip to content

Commit ac66c9f

Browse files
HMAKT99HMAKT99
authored
Merge pull request #1 from HMAKT99/feature/openclaw-skill
Add OpenClaw skill for TouchBridge
2 parents 07263a9 + 2233cea commit ac66c9f

2 files changed

Lines changed: 184 additions & 0 deletions

File tree

‎skills/touchbridge/SKILL.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
name: touchbridge
3+
description: Authenticate sudo and macOS system prompts using your phone's biometric (Face ID/fingerprint) instead of typing passwords. Perfect for Mac Mini, Mac Studio, Mac Pro, and MacBook Neo base users without Touch ID.
4+
homepage: https://github.com/HMAKT99/UnTouchID
5+
metadata:
6+
{
7+
"openclaw":
8+
{
9+
"emoji": "🔐",
10+
"requires": { "bins": ["touchbridged", "touchbridge-test"] },
11+
"install":
12+
[
13+
{
14+
"id": "source",
15+
"kind": "shell",
16+
"command": "git clone https://github.com/HMAKT99/UnTouchID.git /tmp/touchbridge-install && cd /tmp/touchbridge-install && cd daemon && swift build -c release && cd .. && make -C pam && sudo bash scripts/install.sh",
17+
"bins": ["touchbridged", "touchbridge-test"],
18+
"label": "Build and install from source (recommended)",
19+
},
20+
{
21+
"id": "pkg",
22+
"kind": "pkg",
23+
"url": "https://github.com/HMAKT99/UnTouchID/releases/download/v0.1.0-alpha/TouchBridge-0.1.0.pkg",
24+
"sha256": "370b8f0ab32c23216f16de19c8487633301be2810b9fa8793e3ac093f7699f9e",
25+
"bins": ["touchbridged", "touchbridge-test"],
26+
"label": "Install TouchBridge (.pkg) — verify with: shasum -a 256 TouchBridge-0.1.0.pkg",
27+
},
28+
],
29+
},
30+
}
31+
---
32+
33+
# TouchBridge
34+
35+
Use your phone's fingerprint or Face ID to authenticate `sudo`, screensaver unlock, and other macOS auth prompts — instead of typing your password.
36+
37+
Free, open source alternative to Apple's $199 Touch ID keyboard. Works with iPhone, Android, Apple Watch, Wear OS, or any browser.
38+
39+
## References
40+
41+
- `references/setup.md` (install + pairing + testing)
42+
43+
## Workflow
44+
45+
1. Check if TouchBridge is installed: `which touchbridged`.
46+
2. If not installed: **build from source** (recommended — user can audit the code):
47+
```bash
48+
git clone https://github.com/HMAKT99/UnTouchID.git
49+
cd UnTouchID && cd daemon && swift build -c release && cd ..
50+
make -C pam
51+
sudo bash scripts/install.sh
52+
```
53+
Alternatively, download the .pkg from the GitHub release and verify its checksum:
54+
```bash
55+
shasum -a 256 TouchBridge-0.1.0.pkg
56+
# Expected: 370b8f0ab32c23216f16de19c8487633301be2810b9fa8793e3ac093f7699f9e
57+
spctl -a -t install TouchBridge-0.1.0.pkg # verify notarisation
58+
```
59+
3. Check daemon status: `ls ~/Library/Application\ Support/TouchBridge/daemon.sock`.
60+
4. Start the daemon:
61+
- **Production** (requires paired phone): `touchbridged serve` or `touchbridged serve --web`
62+
- **Testing only** — ⚠️ REQUIRES EXPLICIT USER CONFIRMATION before running:
63+
`touchbridged serve --simulator`
64+
This mode auto-approves ALL sudo requests with no biometric check. Never use in production. Always ask the user before enabling this mode.
65+
66+
### For sudo commands
67+
68+
TouchBridge automatically handles `sudo` authentication when installed. The PAM module intercepts the auth request and routes it to the daemon, which prompts the user's phone.
69+
70+
If the phone is unreachable, sudo falls through to the normal password prompt — the user is never locked out.
71+
72+
### Modes
73+
74+
- `touchbridged serve` — production mode with paired iPhone/Android via BLE
75+
- `touchbridged serve --web` — any phone via browser URL (no app install needed)
76+
- `touchbridged serve --interactive` — approve/deny in terminal
77+
- `touchbridged serve --simulator` — ⚠️ TESTING ONLY — auto-approves all sudo. Never enable without explicit user consent.
78+
79+
### Configuration
80+
81+
```bash
82+
touchbridge-test config show # view policy
83+
touchbridge-test config set --timeout 20 # change auth timeout
84+
touchbridge-test logs # view recent auth events
85+
touchbridge-test list-devices # show paired devices
86+
```
87+
88+
## Guardrails
89+
90+
- **Never enable `--simulator` mode without explicit user confirmation.** This mode auto-approves all sudo requests and is a critical security risk if left running in production.
91+
- Never type or log the user's macOS password — TouchBridge replaces password entry entirely.
92+
- If `touchbridged` is not running, sudo falls through to password — never block the user.
93+
- Never modify `/etc/pam.d/sudo` directly — use the install script which creates backups.
94+
- When installing via .pkg, always verify the SHA-256 checksum before running.
95+
- The build-from-source path is the recommended install method — users can audit the code before running it.

‎skills/touchbridge/references/setup.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# TouchBridge Setup Reference
2+
3+
## Install from Source (Recommended)
4+
5+
Building from source lets you audit the code before running it.
6+
7+
```bash
8+
git clone https://github.com/HMAKT99/UnTouchID.git
9+
cd UnTouchID
10+
11+
# Review the install script before running:
12+
cat scripts/install.sh
13+
14+
# Build
15+
cd daemon && swift build -c release && cd ..
16+
make -C pam
17+
18+
# Install (will ask for admin password, shows diff before patching PAM)
19+
sudo bash scripts/install.sh
20+
```
21+
22+
## Install from .pkg (Alternative)
23+
24+
If you prefer the pre-built installer, **verify the checksum first**:
25+
26+
```bash
27+
# Download
28+
curl -L -o /tmp/TouchBridge.pkg https://github.com/HMAKT99/UnTouchID/releases/download/v0.1.0-alpha/TouchBridge-0.1.0.pkg
29+
30+
# Verify integrity — must match this hash:
31+
shasum -a 256 /tmp/TouchBridge.pkg
32+
# Expected: 370b8f0ab32c23216f16de19c8487633301be2810b9fa8793e3ac093f7699f9e
33+
34+
# Verify code signing (if notarised):
35+
spctl -a -t install /tmp/TouchBridge.pkg
36+
37+
# Install
38+
open /tmp/TouchBridge.pkg
39+
```
40+
41+
## Production Use — Phone Auth
42+
43+
```bash
44+
# Option A: Any phone via browser (no app install)
45+
touchbridged serve --web
46+
47+
# Option B: Paired iPhone/Android via BLE
48+
touchbridged serve
49+
```
50+
51+
```bash
52+
# Test sudo
53+
sudo echo test
54+
# → Phone prompts biometric → approve → sudo succeeds
55+
```
56+
57+
## Testing Only — Simulator
58+
59+
⚠️ **WARNING: Simulator mode auto-approves ALL sudo requests without any biometric check. Never use in production. Only use for testing in a controlled environment.**
60+
61+
```bash
62+
# Only for testing — requires explicit user consent
63+
touchbridged serve --simulator
64+
65+
# In another terminal
66+
sudo echo 'TouchBridge works!'
67+
# → Auto-approved, no phone needed
68+
```
69+
70+
## Pair iPhone or Android
71+
72+
```bash
73+
touchbridge-test pair
74+
# Shows pairing JSON → enter in companion app
75+
```
76+
77+
## View auth history
78+
79+
```bash
80+
touchbridge-test logs
81+
touchbridge-test logs --surface pam_sudo --count 20
82+
```
83+
84+
## Uninstall
85+
86+
```bash
87+
sudo bash scripts/uninstall.sh
88+
# Restores original PAM config, removes daemon
89+
```

0 commit comments

Comments
 (0)