update_server/docs/agents/handoffs/06-client-api-ui.md

Agent

Name: Agent 06 - Client API And Admin UI

Stage: Client API And Admin UI

Date: 2026-04-15

Scope

Implemented the usable end-to-end product flow for admins and client applications on top of the existing project, release, and API key work from Agents 04 and 05.

Completed in this stage:

• added bearer-authenticated client endpoints under /api/v1 for:
  • listing accessible active projects;
  • looking up the latest active release for an accessible project;
  • fetching release metadata by release ID for an accessible project;
  • downloading private release artifacts by release ID after auth, permission, and scope checks;
• reused the existing API key middleware and scope-evaluation service so disabled or expired keys return 401, missing download permission returns 403, and inaccessible projects or releases return 404 to avoid leaking unauthorized resources;
• added project slug lookup and latest-active-release repository queries so client handlers can resolve project-scoped metadata cleanly from persisted release rows;
• added a safe artifact-open path on top of the existing private local storage so downloads stream from the artifact root instead of exposing raw filesystem paths or static URLs;
• updated the API index and the home or dashboard copy so the live client API is discoverable instead of still looking like a placeholder;
• added small admin UI improvements on project detail and API key detail pages that show the client API paths and a bearer-auth quick-start example after an admin uploads a release or creates a key;
• added integration coverage for the client flow, including auth failures, scope enforcement, latest-release selection, release metadata lookup, and authorized or unauthorized download behavior.

Files Changed

• /Users/delete/projects/update_server/internal/db/projects.go
• /Users/delete/projects/update_server/internal/db/releases.go
• /Users/delete/projects/update_server/internal/storage/local.go
• /Users/delete/projects/update_server/internal/releases/service.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/admin_common.go
• /Users/delete/projects/update_server/internal/http/admin_projects.go
• /Users/delete/projects/update_server/internal/http/view_data.go
• /Users/delete/projects/update_server/internal/http/client_api.go
• /Users/delete/projects/update_server/internal/http/client_api_integration_test.go
• /Users/delete/projects/update_server/internal/http/api_keys_integration_test.go
• /Users/delete/projects/update_server/internal/http/projects_integration_test.go
• /Users/delete/projects/update_server/web/templates/pages/project_detail.gohtml
• /Users/delete/projects/update_server/web/templates/pages/api_key_form.gohtml
• /Users/delete/projects/update_server/web/templates/pages/api_keys.gohtml
• /Users/delete/projects/update_server/web/static/app.css
• /Users/delete/projects/update_server/docs/agents/handoffs/06-client-api-ui.md

Database Changes

• no new migrations or schema changes were required;
• added repository queries against the existing projects and releases tables:
  • project lookup by slug;
  • latest active release lookup ordered by persisted created_at DESC, id DESC;
• continued using the existing API key scope tables and scope modes without redesign.

API Or Route Changes

• kept GET /api/v1 public and upgraded it from a placeholder to a real client API index;
• added protected client routes behind bearer API key auth plus can_download permission:
  • GET /api/v1/projects
  • GET /api/v1/projects/{projectSlug}/releases/latest
  • GET /api/v1/releases/{releaseID}
  • GET /api/v1/releases/{releaseID}/download
• resource access behavior for client routes:
  • missing, invalid, disabled, or expired API key -> 401
  • authenticated key without download permission -> 403
  • inaccessible or archived project or release -> 404
• admin UI additions:
  • project detail page now shows the relevant client API paths for that project and latest release;
  • API key detail page now shows a bearer-auth quick-start example plus the accessible project metadata paths.

Commands And Tests Run

• gofmt -w internal/db/projects.go internal/db/releases.go internal/storage/local.go internal/http/view_data.go internal/http/admin_common.go internal/http/admin_projects.go internal/http/router.go internal/http/handlers.go internal/http/client_api.go internal/releases/service.go internal/http/api_keys_integration_test.go internal/http/projects_integration_test.go internal/http/client_api_integration_test.go - passed
• GOCACHE=/tmp/go-build-agent06-http GOMODCACHE=/tmp/go-mod-agent06-http go test ./internal/http ./internal/releases ./internal/db ./internal/apikeys - initially failed in sandbox because module downloads could not resolve DNS, then passed after rerunning with approval
• GOCACHE=/tmp/go-build-agent06-all GOMODCACHE=/tmp/go-mod-agent06-http go test ./... - passed
• GOCACHE=/tmp/go-build-agent06-build GOMODCACHE=/tmp/go-mod-agent06-http go build -o /tmp/update-server-agent06 ./cmd/server - passed
• GOCACHE=/tmp/go-build-agent06-migrate GOMODCACHE=/tmp/go-mod-agent06-http go build -o /tmp/update-migrate-agent06 ./cmd/migrate - passed

Known Limitations

• “Latest” currently means the newest active persisted release by created_at and id, not semantic-version comparison;
• the optional client query parameters mentioned in the product spec (current_version, channel, platform, arch) are still not implemented;
• the client API does not yet expose full per-project release listing; this stage focused on the required list, latest-metadata, metadata-by-ID, and download flow;
• the admin quick-start example can show the real raw key only on the one-time create response; later detail views intentionally fall back to a placeholder token;
• broader hardening work such as CSRF completion, rate limiting, security headers, audit logging polish, and deployment proxy setup remains out of scope for this stage.

Recommended Next Step

Run the validation pass for Agent 06, then move to Agent 07 to implement the planned hardening and deployment-focused follow-up: CSRF, security headers, rate limiting, audit/logging polish, and deployment readiness around the now-working end-to-end product flow.

Notes For Validator

• verify that client routes require Authorization: Bearer <api_key> and that disabled or expired keys are rejected with 401;
• verify that client routes require can_download and return 403 when the key authenticates but lacks download permission;
• verify that unauthorized, archived, or out-of-scope projects and releases return 404 from metadata and download paths rather than leaking through a 403;
• verify that GET /api/v1/projects returns only active projects allowed by the key’s scope evaluation;
• verify that the latest-release endpoint selects the newest active persisted release row for the project;
• verify that the download endpoint streams bytes from private artifact storage and does not expose static URLs or raw filesystem paths;
• verify that the project detail and API key detail admin pages visibly expose the new client API quick-start information.