init

docs/agents/handoffs/05-api-keys-fix.md

@@ -0,0 +1,63 @@
+# Agent
+
+Name: Agent 05 - API Keys And Access Control (fix round)
+
+Stage: API Keys And Access Control
+
+Date: 2026-04-14
+
+## Scope
+
+Fixed the validation findings for Agent 05 without expanding into the client API stage.
+
+Completed in this fix round:
+
+- added explicit anti-cache headers for the one-time raw API key reveal response so the secret-bearing HTML is marked non-cacheable;
+- changed the immediate post-create detail render to hydrate from the persisted API key record and persisted scope rows while still showing the raw key only on that one response;
+- extended HTTP integration coverage to verify:
+  - the creation response includes anti-cache headers;
+  - the creation response shows saved name, description, scope mode, permissions, and selected project or tag rules;
+  - the raw key is present on the creation response and absent on later detail loads.
+
+## Files Changed
+
+- `/Users/delete/projects/update_server/internal/http/admin_api_keys.go`
+- `/Users/delete/projects/update_server/internal/http/api_keys_integration_test.go`
+- `/Users/delete/projects/update_server/docs/agents/handoffs/05-api-keys-fix.md`
+
+## Database Changes
+
+- no schema or migration changes were required;
+- the existing API key hash and scope storage model remains unchanged.
+
+## API Or Route Changes
+
+- no routes were added or removed;
+- `POST /admin/api-keys` now returns the one-time reveal page with explicit anti-cache headers:
+  - `Cache-Control: no-store, private, max-age=0`
+  - `Pragma: no-cache`
+  - `Expires: 0`
+
+## Commands And Tests Run
+
+- `gofmt -w internal/http/admin_api_keys.go internal/http/api_keys_integration_test.go` - passed;
+- `GOCACHE=/tmp/go-build-agent05-fix GOMODCACHE=/tmp/go-mod-agent05-2 go test ./internal/http` - passed;
+- `GOCACHE=/tmp/go-build-agent05-fix-all GOMODCACHE=/tmp/go-mod-agent05-2 go test ./...` - passed;
+- `GOCACHE=/tmp/go-build-agent05-fix-build GOMODCACHE=/tmp/go-mod-agent05-2 go build -o /tmp/update-server-agent05-fix ./cmd/server` - passed;
+- `GOCACHE=/tmp/go-build-agent05-fix-build2 GOMODCACHE=/tmp/go-mod-agent05-2 go build -o /tmp/update-migrate-agent05-fix ./cmd/migrate` - passed.
+
+## Known Limitations
+
+- the one-time reveal still intentionally happens on the direct POST response rather than a redirect flow so the raw key never has to enter query strings or persistent storage;
+- CSRF protection is still not implemented for admin API key forms;
+- the client `/api/v1` endpoints still do not use the API key middleware yet; that remains for Agent 06.
+
+## Recommended Next Step
+
+Agent 06 should wire the existing API key middleware into the client `/api/v1` endpoints for accessible project listing, latest release lookup, and authenticated artifact download.
+
+## Notes For Validator
+
+- verify that the post-create response shows persisted saved values immediately, without requiring a manual refresh;
+- verify that the raw key appears only on the secret-bearing creation response and not on later `GET /admin/api-keys/{id}` detail loads;
+- verify the one-time reveal response includes the anti-cache headers listed above.