# Trinity Break-Glass Implementation Plan

## Current State
- Mr Anderson host: Adner Windows machine via WSL Ubuntu-22.04
- OpenClaw version: 2026.5.7
- Gateway service: `openclaw-gateway.service`
- Gateway status: running under user systemd
- Service file: `~/.config/systemd/user/openclaw-gateway.service`
- Gateway bind: `127.0.0.1:18789`
- Current log path observed: `/tmp/openclaw/openclaw-2026-05-11.log`

## Decision
Implement a narrow SSH-based break-glass path first.

This is the best first move because it is:
- fast to deploy
- easy to audit
- reversible
- materially safer than broad SSH or shared admin access

## Target Design
Trinity gets a dedicated recovery identity that can do only four things:
- status
- logs
- restart
- verify

No interactive shell.
No workspace browsing.
No access to private context files.
No config changes.
No updates.

## Phase 1: Access Boundary
### 1. Create dedicated local account
Create a dedicated Linux account on the WSL host:
- username: `trinity-operator`
- no password login
- SSH key only
- no sudo by default

### 2. Restrict login behavior
In `authorized_keys`, restrict Trinity’s key with:
- forced command
- no port forwarding
- no agent forwarding
- no X11 forwarding
- no PTY

Example shape:
```text
command="/usr/local/bin/mr-anderson-recovery",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-ed25519 AAAA...
```

### 3. Restrict network path
Allow inbound access only from Trinity’s Tailscale identity.
If using Tailscale SSH or ACLs, scope the policy to:
- source: Trinity VPS
- destination: Mr Anderson host
- port: SSH only

## Phase 2: Recovery Wrapper
Create `/usr/local/bin/mr-anderson-recovery`.

### Allowed verbs
- `status`
- `logs`
- `restart`
- `verify`

### Behavior
#### `status`
Return:
- `openclaw gateway status`
- `systemctl --user is-active openclaw-gateway.service`

#### `logs`
Return only recent relevant logs, for example:
- `journalctl --user -u openclaw-gateway.service -n 150 --no-pager`
- optionally fallback to `/tmp/openclaw/...` if needed

#### `restart`
Run only:
- `systemctl --user restart openclaw-gateway.service`

Then wait briefly and return status.

#### `verify`
Run:
- `systemctl --user is-active openclaw-gateway.service`
- `openclaw gateway status`

Success condition:
- service active
- gateway probe ok

### Input validation
- reject empty commands
- reject unknown verbs
- reject extra shell tokens
- do not pass raw user input into shell

## Phase 3: Minimal Privilege Mechanics
The one tricky part is user systemd scope.

Because the gateway runs as Adner’s user service, Trinity should not get broad rights over Adner’s account.

### Recommended control pattern
Use a root-owned wrapper that allows only one precise restart/status/log path for `openclaw-gateway.service`.

Safer options:
1. `sudoers` rule allowing only a specific root-owned helper script
2. polkit rule limited to that one service action

Recommendation:
- use a root-owned helper script plus narrowly scoped sudoers entry

Example concept:
- `/usr/local/bin/mr-anderson-recovery-root`
- only this script may be run via sudo by `trinity-operator`
- the script internally runs fixed commands against `openclaw-gateway.service`

Do not grant general sudo.

## Phase 4: Audit
Write every invocation to a dedicated log, for example:
- `/var/log/mr-anderson-recovery.log`

Log fields:
- timestamp
- source user
- source IP/Tailscale identity if available
- verb requested
- success/failure
- short reason

## Phase 5: Test Plan
### Test 1: Status path
- Trinity invokes `status`
- confirms service name and current health

### Test 2: Logs path
- Trinity invokes `logs`
- confirms only recovery-relevant logs are returned

### Test 3: Restart path
- intentionally restart service during a safe window
- confirm service returns healthy

### Test 4: Denied action test
- attempt unsupported verb like `shell` or `cat MEMORY.md`
- confirm hard failure

### Test 5: Outage simulation
- stop or break the service in a controlled way
- Trinity performs status -> logs -> restart -> verify
- Adner confirms recovery quality and audit trail

## Operational Policy
### Trinity may do without asking
- status
- logs
- restart
- verify

### Trinity must not do without explicit Adner approval
- config edits
- OpenClaw updates
- plugin updates
- service-file changes
- secret rotation
- reading workspace files outside recovery logs

## Risks
### Main risk
Privilege creep.
If you solve this lazily with normal SSH plus sudo, Trinity effectively gets broad host administration.

### Control
Keep the surface command-based, not shell-based.

## Recommendation
Approve and implement Phase 1 through Phase 5 exactly in that order.

Do not start with shared SSH or general admin access.
That would solve the immediate problem but create a larger governance problem.

## Ownership
- Adner: approve access model
- Mr Anderson: draft scripts and exact sudoers/ACL shape
- Trinity: execute only bounded recovery actions

## Next Move
If approved, the next build artifact should be:
1. recovery wrapper script
2. root helper script
3. sudoers snippet
4. authorized_keys forced-command entry
5. outage test checklist