Add ADR-029/030, implementation tasks, and spec updates for admin socket removal

Security review #005 identified critical vulnerabilities in the Unix domain
socket admin API (C1 symlink race, C2 no auth, C3 info leak, W1-W7, S1-S6).
ADR-028 (already accepted) replaces the socket with an authenticated HTTP
admin API on the health check port. This commit adds the remaining spec work:

- ADR-029: Config file TOCTOU mitigation (mtime check on reload)
- ADR-030: Store cli_allow_wildcard_bind in ConfigReloadHandle for consistent
  reload validation
- Implementation tasks for the admin HTTP migration (fix/admin-http-api),
  TOCTOU fix (fix/config-reload-toctou), and wildcard flag fix
  (fix/wildcard-flag-reload)
- Updated review #005 status to resolved with per-finding disposition
- Resolved OQ-16: POST for state-changing admin endpoints, GET for read-only
- Updated all architecture docs to reference new ADRs, use admin_key_path
  instead of admin_socket_path, and reflect POST method for /admin/reload
This commit is contained in:
2026-06-15 05:19:42 +00:00
parent 9096ec5873
commit 161049a17d
21 changed files with 1210 additions and 119 deletions

View File

@@ -0,0 +1,80 @@
---
id: fix/agents-md-project-structure
name: Update AGENTS.md project structure and common modifications after admin refactor
status: open
depends_on: [fix/admin-http-api]
scope: narrow
risk: low
impact: docs
level: documentation
review_findings: []
adr: [028]
---
## Description
After the admin socket → HTTP API migration, `AGENTS.md` needs updates to
reflect the new project structure, config format, and operational procedures.
### Changes Required
**Project Structure section** — Update to reflect new admin module layout:
```
src/
├── admin/
│ ├── auth.rs # Bearer token auth middleware (subtle, SHA-256)
│ ├── handler.rs # HTTP handlers for /admin/reload, /status, /rotate-key
│ └── mod.rs # Re-exports
```
Remove:
```
│ ├── socket.rs # REMOVED — was Unix domain socket admin API
```
**Key Architecture Concepts section** — Update the admin socket description:
- Replace "Unix domain socket (`admin_socket_path`)" with "Authenticated HTTP
admin API (`admin_key_path`) on health check port"
- Note that admin endpoints require Bearer token auth
- Note that `admin_key_path` empty string = disabled (returns 404)
**Config Format section** — Update:
- Replace `admin_socket_path` references with `admin_key_path`
- Note that `admin_key_path` default is `/etc/reverse-proxy/admin-key`
- Add key file format info (plaintext, one line, read once at startup)
**Common Modifications section** — Replace:
```bash
# Before (Unix socket)
echo "reload" | socat - UNIX-CONNECT:/run/reverse-proxy/admin.sock
# After (HTTP with Bearer token)
curl -H "Authorization: Bearer $ADMIN_KEY" http://127.0.0.1:9900/admin/reload
curl -H "Authorization: Bearer $ADMIN_KEY" http://127.0.0.1:9900/admin/status
```
**Build & Run section** — No changes needed (build commands unchanged).
**Testing section** — Note that admin tests now use HTTP (reqwest) instead of
Unix socket (tokio::net::UnixStream).
## Acceptance Criteria
- [ ] Project structure shows `auth.rs` and `handler.rs`, not `socket.rs`
- [ ] Key architecture concepts mention `admin_key_path` and Bearer token auth
- [ ] Config format section mentions `admin_key_path`
- [ ] Common modifications section uses `curl` examples, not `socat`
- [ ] No references to `admin_socket_path` remain in AGENTS.md
## References
- AGENTS.md — current project structure and common modifications
- docs/architecture/decisions/028-admin-http-api.md — ADR-028
## Notes
> Depends on `fix/admin-http-api` being complete so the new file names are
> accurate.
## Summary
> To be filled on completion