reverse-proxy/tasks/fix/agents-md-project-structure.md at 161049a17dcee154785db804953e5adf60f1ed64

Files

glm-5.1 161049a17d 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

2026-06-15 05:19:42 +00:00

2.6 KiB

Raw Blame History

id, name, status, depends_on, scope, risk, impact, level, review_findings, adr

name

status

depends_on

scope

risk

impact

level

review_findings

adr

fix/agents-md-project-structure

Update AGENTS.md project structure and common modifications after admin refactor

open

fix/admin-http-api

narrow

low

docs

documentation

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:

# 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

2.6 KiB Raw Blame History