delete/update_server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
update_server/docs/agents/handoffs/03-auth.md
delete b15b95781c init
2026-06-10 20:51:17 +03:00

5.4 KiB
Raw Blame History

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.