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:
80
tasks/fix/agents-md-project-structure.md
Normal file
80
tasks/fix/agents-md-project-structure.md
Normal 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
|
||||
Reference in New Issue
Block a user