# Subrouter authority S1

This module builds and installs the credential-empty, loopback-only Subrouter authority from the exact pinned upstream source. S1 adds server-enforced exact routes, route-scoped hashed proxy grants, bounded self-status, and protected local administration. It does not onboard an account, inspect a native credential, expose a remote listener, or make a provider call.

## Safety boundary

- Never copy, inspect, restore, print, or test a native Claude/Codex credential here.
- The service runs as the non-login `overdeck-subrouter` user with an isolated HOME/XDG tree and `ProtectHome=yes`.
- Authority mode disables native discovery/migration, active-account synchronization, account import, automatic switching, and transcripts.
- Proxy keys are generated directly into a new mode-0600 file; only their SHA-256 hashes are stored.
- A route grant reaches only `/r/<route-id>/<provider-path>` and `/r/<route-id>/_subrouter/status`. It cannot reach administration.
- Tests and installed proof use synthetic unavailable account identifiers and a transport-refusing fixture only.

## Verify

All Go, vet, and build work is remote-only through the registered buildbox wrapper. There is no workstation fallback.

```bash
modules/subrouter/bin/verify-candidate focused
modules/subrouter/bin/verify-candidate static
RUN_ID="$(date +%s)-$$"; TMP_ROOT="${XDG_CACHE_HOME:-$HOME/.cache}/overdeck/tests/subrouter-pytest/$RUN_ID"; mkdir -p "$TMP_ROOT"; python3 -m pytest modules/subrouter/tests/ -q --basetemp "$TMP_ROOT"
modules/subrouter/bin/verify-candidate full
modules/subrouter/bin/verify-candidate path
```

`path` prints one immutable content-addressed candidate only when its binary, logs, exact phase records, current module inputs, pinned archive, and patch all match.

## Protected local administration

Run administration only through `deck-sudo` and then as the installed `overdeck-subrouter` identity, which owns the protected state and marker. Do not place identifiers or key paths in shared logs or receipts.

```text
deck-sudo /usr/sbin/runuser --user overdeck-subrouter -- /usr/bin/env -i HOME=/var/lib/overdeck/subrouter/state/home XDG_CONFIG_HOME=/var/lib/overdeck/subrouter/state/config XDG_CACHE_HOME=/var/lib/overdeck/subrouter/state/cache XDG_STATE_HOME=/var/lib/overdeck/subrouter/state/state SUBROUTER_STATE_DIR=/var/lib/overdeck/subrouter/state /var/lib/overdeck/subrouter/current/bin/subrouter authority-route create|disable|status --state-dir /var/lib/overdeck/subrouter/state ...
deck-sudo /usr/sbin/runuser --user overdeck-subrouter -- /usr/bin/env -i HOME=/var/lib/overdeck/subrouter/state/home XDG_CONFIG_HOME=/var/lib/overdeck/subrouter/state/config XDG_CACHE_HOME=/var/lib/overdeck/subrouter/state/cache XDG_STATE_HOME=/var/lib/overdeck/subrouter/state/state SUBROUTER_STATE_DIR=/var/lib/overdeck/subrouter/state /var/lib/overdeck/subrouter/current/bin/subrouter authority-grant create --state-dir /var/lib/overdeck/subrouter/state --route-id <id> --audience workstation --expires-at <RFC3339> --proxy-key-file <new-protected-path>
deck-sudo /usr/sbin/runuser --user overdeck-subrouter -- /usr/bin/env -i HOME=/var/lib/overdeck/subrouter/state/home XDG_CONFIG_HOME=/var/lib/overdeck/subrouter/state/config XDG_CACHE_HOME=/var/lib/overdeck/subrouter/state/cache XDG_STATE_HOME=/var/lib/overdeck/subrouter/state/state SUBROUTER_STATE_DIR=/var/lib/overdeck/subrouter/state /var/lib/overdeck/subrouter/current/bin/subrouter authority-grant revoke --state-dir /var/lib/overdeck/subrouter/state --grant-id <id>
deck-sudo /usr/sbin/runuser --user overdeck-subrouter -- /usr/bin/env -i HOME=/var/lib/overdeck/subrouter/state/home XDG_CONFIG_HOME=/var/lib/overdeck/subrouter/state/config XDG_CACHE_HOME=/var/lib/overdeck/subrouter/state/cache XDG_STATE_HOME=/var/lib/overdeck/subrouter/state/state SUBROUTER_STATE_DIR=/var/lib/overdeck/subrouter/state /var/lib/overdeck/subrouter/current/bin/subrouter authority-proof --state-dir /var/lib/overdeck/subrouter/state --origin http://127.0.0.1:31415 --proxy-key-file <new-run-owned-protected-path>
```

Commands refuse relative or symlinked state/key paths, permissive key parents, occupied destinations, non-loopback proof origins, and missing mode-0600 local administration material. Route, account, tenant, grant, key/hash, and full path values are not printed.

## Install and inspect

```bash
CANDIDATE="$(modules/subrouter/bin/verify-candidate path)"
deck-sudo modules/subrouter/bin/install-candidate "$CANDIDATE"
deck-sudo /usr/sbin/runuser --user overdeck-subrouter -- /usr/bin/env -i OVERDECK_SUBROUTER_SERVICE_IDENTITY=overdeck-subrouter /var/lib/overdeck/subrouter/current/bin/subrouter authority-status --state-dir /var/lib/overdeck/subrouter/state
```

The installer creates the protected administration marker atomically, preserves the schema-compatible authority state, stages a normalized immutable release, switches `current` atomically, waits for loopback readiness, and restores the previous unit/link on failure. Reinstalling one digest is idempotent. Rollback changes executable bytes only and never restores credential state.

## Owner proof

The installed synthetic server proof transaction creates no provider credential and cleans up its unavailable-account fixture, route, grants, and run-owned key file on success or failure. Its successful output is exactly:

```text
Exact dark route: PASS
Proxy grant scope: PASS
Admin isolation: PASS
Provider credentials: 0
```

This command does not claim to verify client behavior. The Systray lane independently supplies `Gateway-only home: PASS` and `Native launch unchanged: PASS`; only the supported composite owner proof may combine those two independently verified claims with the four server lines above.