100 lines
7.2 KiB
Markdown
100 lines
7.2 KiB
Markdown
# 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.
|