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

Agent

Name: Agent 05 - API Keys And Access Control

Stage: API Keys And Access Control

Date: 2026-04-14

Scope

Implemented the API key lifecycle and access-control stage on top of the existing authenticated admin workspace and the project or tag model from Agent 04.

Completed in this stage:

• added a dedicated internal/apikeys service for secure API key generation, SHA-256 hashing, lookup, lifecycle checks, and project scope evaluation;
• implemented full API key repository support for create, update, list, revoke or activate, last-used tracking, project and tag rule storage, and effective access queries;
• added minimal protected admin pages for API key list, creation, detail, update, and revoke or activate actions;
• implemented one-time raw key reveal behavior by showing the generated key only in the immediate creation response while persisting only the short prefix and hash;
• added permission and project-scope middleware helpers for future /api/v1 client routes using bearer authentication;
• added integration and unit coverage for hashed storage, expired or revoked key rejection, all five scope modes, scope transitions, middleware enforcement, and admin key management flow.

Files Changed

• /Users/delete/projects/update_server/internal/app/app.go
• /Users/delete/projects/update_server/internal/db/models.go
• /Users/delete/projects/update_server/internal/db/apikeys.go
• /Users/delete/projects/update_server/internal/apikeys/context.go
• /Users/delete/projects/update_server/internal/apikeys/service.go
• /Users/delete/projects/update_server/internal/apikeys/service_test.go
• /Users/delete/projects/update_server/internal/http/router.go
• /Users/delete/projects/update_server/internal/http/handlers.go
• /Users/delete/projects/update_server/internal/http/view_data.go
• /Users/delete/projects/update_server/internal/http/admin_api_keys.go
• /Users/delete/projects/update_server/internal/http/api_key_middleware.go
• /Users/delete/projects/update_server/internal/http/api_key_middleware_test.go
• /Users/delete/projects/update_server/internal/http/api_keys_integration_test.go
• /Users/delete/projects/update_server/internal/http/auth_integration_test.go
• /Users/delete/projects/update_server/web/templates/layouts/base.gohtml
• /Users/delete/projects/update_server/web/templates/pages/api_keys.gohtml
• /Users/delete/projects/update_server/web/templates/pages/api_key_form.gohtml
• /Users/delete/projects/update_server/web/static/app.css
• /Users/delete/projects/update_server/docs/agents/handoffs/05-api-keys.md

Database Changes

• no new migrations were required because the existing api_keys, api_key_project_access, and api_key_tag_access tables already existed from Agent 02 and the scope guard triggers already existed from migration 0003_api_key_scope_guards.sql;
• the new repository code now actively uses those tables and trigger rules for key lifecycle, project allow or deny lists, and tag allow or deny lists;
• API keys are stored with a short visible key_prefix and a hashed key_hash; the raw key is never persisted.

API Or Route Changes

• added protected admin routes:
  • GET /admin/api-keys
  • GET /admin/api-keys/new
  • POST /admin/api-keys
  • GET /admin/api-keys/{apiKeyID}
  • POST /admin/api-keys/{apiKeyID}
  • POST /admin/api-keys/{apiKeyID}/activate
• added reusable middleware helpers for future client API routes:
  • requireAPIKey
  • requireAPIKeyPermission
  • requireAPIKeyProjectAccess
• kept /api/v1 client endpoints themselves out of scope for this stage so Agent 06 can wire them onto the new middleware and access-resolution layer.

Commands And Tests Run

• gofmt -w internal/app/app.go internal/db/models.go internal/db/apikeys.go internal/apikeys/context.go internal/apikeys/service.go internal/http/router.go internal/http/handlers.go internal/http/view_data.go internal/http/admin_api_keys.go internal/http/api_key_middleware.go internal/http/auth_integration_test.go internal/apikeys/service_test.go internal/http/api_key_middleware_test.go internal/http/api_keys_integration_test.go - passed;
• GOCACHE=/tmp/go-build-agent05-2 GOMODCACHE=/tmp/go-mod-agent05-2 go test ./... - passed after downloading dependencies with approval;
• GOCACHE=/tmp/go-build-agent05-build GOMODCACHE=/tmp/go-mod-agent05-2 go build -o /tmp/update-server-agent05 ./cmd/server - passed;
• GOCACHE=/tmp/go-build-agent05-build2 GOMODCACHE=/tmp/go-mod-agent05-2 go build -o /tmp/update-migrate-agent05 ./cmd/migrate - passed.

Known Limitations

• CSRF protection is still not implemented for admin forms, including the new API key creation, update, and revoke or activate actions;
• the admin API key UI is intentionally minimal and functional rather than polished;
• the one-time reveal happens on the direct POST response instead of a PRG redirect because the raw key must not be placed into query strings or persistent storage;
• no live client /api/v1 endpoints use the new middleware yet; the groundwork is ready but the actual project list, latest-release, and download endpoints remain for Agent 06;
• expiration input currently accepts either empty, YYYY-MM-DD, or full RFC3339 UTC text rather than a more polished timezone-aware widget.

Recommended Next Step

Agent 06 should wire the new requireAPIKey, requireAPIKeyPermission, and requireAPIKeyProjectAccess middleware into the client /api/v1 endpoints for accessible-project listing, latest release lookup, and authenticated artifact download.

Notes For Validator

• verify that only key_prefix and key_hash are stored in SQLite and that the raw key appears only in the immediate creation response;
• verify that revoked or expired keys are rejected by requireAPIKey with 401 and that missing permissions or blocked project scope return 403;
• verify effective access resolution across all five scope modes, especially that archived projects do not appear in accessible-project results;
• verify scope transitions clear the incompatible access rows so the existing migration guards continue to succeed;
• verify the admin detail page preview matches the effective active project set for the key.