Skip to main content

​
The Harness

​
Why the Expanded Being Needs a Gate

​
The Problem

Kernel CLI gives AI full access to the operating system. It can press any button in any app, type arbitrary text, run AppleScript, read Safari history, take screenshots, and kill processes. Without a gate, an AI agent can do all of this the moment it is given access to the terminal. There is no “are you sure?” There is no permission dialog. The command runs and the action happens. This is brave mode — raw capability with no control layer. 
$ kernel-cli --help

┌──────────────────────────────────────────────────────────────────────────────┐
│  ⚠  BRAVE MODE                                                               │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  You are using kernel-cli directly. There is no permission gate.             │
│  Every command executes immediately — including write operations             │
│  like ax-press, type, click, key, and script.                                │
│                                                                              │
│  This means:                                                                 │
│  • AI agents can press any button in any app                                 │
│  • AI agents can type arbitrary text                                         │
│  • AI agents can run AppleScript with full OS access                         │
│  • No OTP, no token, no audit trail                                          │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

​
The Solution: Three Tiers

NIIA embeds kernel-cli as a Rust library crate and wraps it with a permission layer. The same code runs, but access is gated. 
┌─────────────────────────────────────────────────────────────────────────────────┐
│  OPEN — always allowed (structure only, no content)                             │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  niia observe windows          List window titles and positions                 │
│  niia observe process          Running processes and CPU/memory                 │
│  niia observe permissions      macOS permission status                          │
│  niia observe network          Network interfaces and DNS                       │
│  niia observe lsof :3000       Port and process mapping                         │
│  niia observe search "term"    Spotlight file name search                       │
│                                                                                 │
│  These expose structure — window list, process table, network config.           │
│  No personal content. No screen content. Always safe.                           │
│                                                                                 │
├─────────────────────────────────────────────────────────────────────────────────┤
│  GATED — requires OTP unlock (exposes screen content / personal data)           │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  niia observe snapshot         Windows + accessibility tree + clipboard         │
│  niia observe ax-tree          Full accessibility tree of any app               │
│  niia observe capture          Screenshot (full screen or region)               │
│  niia observe query safari     Browser history (SQLite)                         │
│  niia observe query notes      Apple Notes content                              │
│  niia observe defaults         App preferences and settings                     │
│  niia observe log              System logs                                      │
│                                                                                 │
│  These expose what is ON the screen — text fields, passwords, personal notes.   │
│  Requires the same OTP token as control commands.                               │
│                                                                                 │
├─────────────────────────────────────────────────────────────────────────────────┤
│  LOCKED — requires OTP unlock (writes to OS)                                    │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  niia control ax-press "OK"    Press button by accessibility title              │
│  niia control type "hello"     Type text into focused element                   │
│  niia control click 500 300    Click at coordinates                             │
│  niia control key "cmd+s"      Press key combination                            │
│  niia control script "..."     Run AppleScript/JXA                              │
│  niia control open "url://..."  Open URL scheme                                 │
│  niia control kill 1234        Kill process                                     │
│                                                                                 │
│  These change the state of the operating system.                                │
│  The most sensitive tier. Requires OTP unlock.                                  │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

​
The OTP Gate

The gate between locked and unlocked is an email OTP verified by the server, returning an Ed25519 signed token that the binary verifies offline.

​
Why OTP Is the Only Human-Proof Layer

Things AI can do:                 Things AI cannot do:
  ✅ Write code                     ❌ Read your email inbox
  ✅ Run terminal commands           ❌ Receive OTP on your phone
  ✅ Call APIs                       ❌ Access a separate device
  ✅ Write files to disk             ❌ Forge Ed25519 signatures
  ✅ Execute shell scripts
The OTP code is delivered to the human’s email — a channel that exists outside the AI’s context window, outside the terminal, outside the filesystem. The AI cannot intercept it, guess it, or forge the server’s response.

​
The Flow

$ niia control unlock --scope full --duration 1h

1. niia reads stored email from keychain
2. Server sends OTP to email
3. Human reads email, enters 6-digit code
4. Server verifies OTP, returns JWT
5. niia requests signed control token from gateway
   → Gateway verifies JWT
   → Gateway signs { scope, exp, device_id } with Ed25519 private key
   → Returns signed token
6. niia saves token locally
7. All subsequent observe-gated and control commands check this token
   → Ed25519 signature verified OFFLINE (public key embedded in binary)
   → Expiry checked against current time
   → No network needed after unlock

​
Why Ed25519 Instead of Just JWT

The OTP verify step returns a standard JWT. Why not use that directly? 
JWT only:
  Every niia control command → network call to verify → slow, offline impossible

Ed25519 token:
  Every niia control command → read local file → verify signature with
  embedded public key → instant, works offline, works on airplane
The Ed25519 token is a one-time conversion: JWT (online verification) → signed token (offline verification). After unlock, no network is needed until the token expires.

​
Separate Keys

The kernel control signing key is separate from all other signing keys: The kernel control signing key is a separate Ed25519 keypair from all other signing infrastructure. Different purpose, different key. If one is compromised, the other is unaffected.

​
What AI Cannot Do

Tested and verified: 
AI attempt: echo "fake" > ~/.niia/control-token
Result:     ❌ "Invalid token format (not signed JSON). Token may be forged."

AI attempt: echo '{"data":"...","signature":"AAAA..."}' > ~/.niia/control-token
Result:     ❌ "Signature verification FAILED — token may be forged or tampered."

AI attempt: Construct valid JSON with correct format but wrong signature
Result:     ❌ "Signature verification FAILED"

AI attempt: Call niia control unlock (requires OTP code)
Result:     ❌ Cannot enter OTP — code is in human's email
The private key exists only in the server-side secret store. It is not in the binary, not in the filesystem, not in any config file, not in the AI’s context.

​
The Pattern: OTP Gate as Primitive

The OTP flow is implemented as a reusable module (otp_gate.rs): 
// One function. Any purpose. Returns verified JWT.
let jwt = otp_gate::prompt("kernel-control")?;
let jwt = otp_gate::prompt("remote-admin")?;
let jwt = otp_gate::prompt("git-force-push")?;
The purpose string is sent as app_code to the OTP server. Different purposes can have different rate limits, different token lifetimes, different audit requirements — all without changing the client code. Any future feature that needs human proof can use this gate: 
kernel control  + OTP gate = harnessed OS control
remote admin    + OTP gate = harnessed remote access
destructive git + OTP gate = harnessed force-push
payment action  + OTP gate = harnessed transaction
The gate is the primitive. The harness is what you build with it.

​
Brave Mode vs Harnessed Mode

kernel-cli (brave):
  → No restrictions. Full OS access. Immediate execution.
  → For: developers who know what they're doing, local testing, scripts.
  → Warning displayed on every --help invocation.

niia observe/control (harnessed):
  → 3-tier permission. OTP required for sensitive operations.
  → For: AI agents, production use, shared machines, auditable access.
  → The same kernel code runs — but only after human proof.
The capability is identical. The access model is different. This is the pattern that Claude Code established for LLMs: the model has full capability, but the harness (permission system, hooks, CLAUDE.md rules) controls when and how that capability is exercised. NIIA applies the same pattern to operating system access — with the additional guarantee that the gate requires a cryptographic proof of human presence that no AI can forge.