update_server/docs/agents/handoffs/03-auth.md

Agent

Name: Agent 03 - Authentication And Admin Sessions

Stage: Authentication And Admin Sessions

Date: 2026-04-14

Scope

Implemented admin authentication and session management on top of the existing users and sessions tables.

Completed in this stage:

• added auth-related config for bootstrap credentials, session cookie naming, session TTL, and secure-cookie detection from APP_BASE_URL;
• implemented bcrypt password hashing and verification in a dedicated internal/auth service;
• added admin bootstrap logic that creates the first active admin user from ADMIN_EMAIL and ADMIN_PASSWORD when no active admin exists yet;
• implemented user/session repository methods for bootstrap lookup, login, session lookup, session touch, and logout invalidation;
• added secure random session token generation with SHA-256 hashed token storage in SQLite;
• wired login and logout handlers plus authenticated session middleware into the existing chi route-group structure;
• protected the /admin route group with session and role checks;
• replaced the placeholder admin page with a protected authenticated dashboard and added a server-rendered login form;
• added tests for bootstrap behavior and the login/protected-route/logout flow.

Files Changed

• /Users/delete/projects/update_server/go.mod
• /Users/delete/projects/update_server/go.sum
• /Users/delete/projects/update_server/internal/app/app.go
• /Users/delete/projects/update_server/internal/config/config.go
• /Users/delete/projects/update_server/internal/auth/context.go
• /Users/delete/projects/update_server/internal/auth/password.go
• /Users/delete/projects/update_server/internal/auth/service.go
• /Users/delete/projects/update_server/internal/auth/service_test.go
• /Users/delete/projects/update_server/internal/db/errors.go
• /Users/delete/projects/update_server/internal/db/models.go
• /Users/delete/projects/update_server/internal/db/time.go
• /Users/delete/projects/update_server/internal/db/users.go
• /Users/delete/projects/update_server/internal/db/sessions.go
• /Users/delete/projects/update_server/internal/http/router.go
• /Users/delete/projects/update_server/internal/http/render.go
• /Users/delete/projects/update_server/internal/http/handlers.go
• /Users/delete/projects/update_server/internal/http/auth_handlers.go
• /Users/delete/projects/update_server/internal/http/auth_middleware.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/home.gohtml
• /Users/delete/projects/update_server/web/templates/pages/admin.gohtml
• /Users/delete/projects/update_server/web/templates/pages/login.gohtml
• /Users/delete/projects/update_server/web/static/app.css

Database Changes

• no schema or migration changes were required in this stage;
• the existing users and sessions tables from Agent 02 are now actively used for bootstrap, login, session lookup, and logout invalidation;
• session tokens continue to be stored hashed only;
• user last_login_at and session last_seen_at are now updated by runtime auth flows.

API Or Route Changes

• added GET /admin/login for the server-rendered login form;
• added POST /admin/login to authenticate an admin user and issue a session cookie;
• added POST /admin/logout to invalidate the current session and clear the cookie;
• changed /admin from a public placeholder to a protected route group guarded by session middleware and admin-role checks;
• retained the existing /api/v1 route scaffold unchanged.

Commands And Tests Run

• gofmt -w ./cmd ./internal - passed;
• GOCACHE=/tmp/go-build-auth GOMODCACHE=/tmp/go-mod-auth go mod tidy - initially failed in the sandbox due network/DNS restrictions, then passed after rerunning with approval;
• GOCACHE=/tmp/go-build-auth GOMODCACHE=/tmp/go-mod-auth go test ./... - passed;
• GOCACHE=/tmp/go-build-auth GOMODCACHE=/tmp/go-mod-auth go build -o /tmp/update-server-auth ./cmd/server - passed;
• GOCACHE=/tmp/go-build-auth GOMODCACHE=/tmp/go-mod-auth go build -o /tmp/update-migrate-auth ./cmd/migrate - passed.

Known Limitations

• CSRF protection is not implemented yet for admin forms; this remains for the hardening stage;
• login rate limiting is not implemented yet;
• bootstrap is environment-driven only in this stage; there is no separate one-time bootstrap CLI yet;
• if no active admin exists and the configured ADMIN_EMAIL already belongs to a non-admin user, bootstrap currently logs a warning and leaves that conflict for an operator to resolve;
• there is no admin user-management UI yet beyond the initial bootstrap/login foundation.

Recommended Next Step

Agent 04 should build project, tag, and release management on top of the now-protected /admin route group, reusing the authenticated session context instead of adding a parallel auth path.

Notes For Validator

• verify that POST /admin/login creates a DB-backed session and stores only the token hash in SQLite, not the raw cookie value;
• verify that /admin redirects when unauthenticated and succeeds when the issued session cookie is replayed;
• verify that POST /admin/logout invalidates the existing session record so the old cookie no longer grants access;
• verify bootstrap behavior both when ADMIN_EMAIL and ADMIN_PASSWORD are present and when they are absent.