glm-5.1
161049a17d
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
80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
---
|
|
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 |