feat: add comments and cleanup unused imports across codebase

api/auth/auth.go

@@ -31,6 +31,7 @@ func NewService(db db.Querier) *Service {
 	return &Service{db: db}
 }
 
+// generateToken creates a cryptographically random base64-encoded token
 func generateToken(size int) (string, error) {
 	b := make([]byte, size)
 	if _, err := rand.Read(b); err != nil {
@@ -39,6 +40,7 @@ func generateToken(size int) (string, error) {
 	return base64.URLEncoding.EncodeToString(b), nil
 }
 
+// generateSessionToken creates a 32-byte session token
 func generateSessionToken() (string, error) {
 	return generateToken(32)
 }
@@ -84,7 +86,7 @@ func (s *Service) ValidateSession(ctx context.Context, sessionID string) (*db.Us
 	}
 
 	if time.Now().After(session.ExpiresAt) {
-		_ = s.db.DeleteSession(ctx, sessionID)
+		_ = s.db.DeleteSession(ctx, sessionID) // clean up expired session
 		return nil, ErrNotAuthenticated
 	}
 
@@ -96,6 +98,7 @@ func (s *Service) ValidateSession(ctx context.Context, sessionID string) (*db.Us
 	return &user, nil
 }
 
+// SetSessionCookie sets an http-only, secure session cookie
 func SetSessionCookie(w http.ResponseWriter, sessionID string, expiresAt time.Time) {
 	secure := os.Getenv("ENV") == "production" || os.Getenv("FORCE_SECURE_COOKIES") == "true"
 	http.SetCookie(w, &http.Cookie{
@@ -113,11 +116,12 @@ func (s *Service) Logout(ctx context.Context, sessionID string) error {
 	return s.db.DeleteSession(ctx, sessionID)
 }
 
+// ClearSessionCookie invalidates the session cookie
 func ClearSessionCookie(w http.ResponseWriter) {
 	http.SetCookie(w, &http.Cookie{
 		Name:     "session_id",
 		Value:    "",
-		Expires:  time.Unix(0, 0),
+		Expires:  time.Unix(0, 0), // epoch to expire immediately
 		MaxAge:   -1,
 		HttpOnly: true,
 		Path:     "/",

api/auth/handler.go

@@ -17,6 +17,7 @@ func NewHandler(authService *Service) *Handler {
 	return &Handler{authService: authService}
 }
 
+// rateLimitErrorFromQuery checks for rate limit errors in the query string
 func rateLimitErrorFromQuery(r *http.Request) string {
 	if r.URL.Query().Get("error") == "rate_limited" {
 		return rateLimitFormError
@@ -24,6 +25,7 @@ func rateLimitErrorFromQuery(r *http.Request) string {
 	return ""
 }
 
+// HandleLoginPage renders the login form
 func (h *Handler) HandleLoginPage(w http.ResponseWriter, r *http.Request) {
 	if err := templates.GetRenderer().ExecuteTemplate(r.Context(), w, "login.gohtml", map[string]any{
 		"CurrentPath": r.URL.Path,
@@ -32,6 +34,7 @@ func (h *Handler) HandleLoginPage(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+// HandleLogin validates credentials and creates a session on success
 func (h *Handler) HandleLogin(w http.ResponseWriter, r *http.Request) {
 	if err := r.ParseForm(); err != nil {
 		templates.GetRenderer().ExecuteTemplate(r.Context(), w, "login.gohtml", map[string]any{
@@ -69,6 +72,7 @@ func (h *Handler) HandleLogin(w http.ResponseWriter, r *http.Request) {
 	http.Redirect(w, r, "/", http.StatusSeeOther)
 }
 
+// HandleLogout destroys the session and clears the cookie
 func (h *Handler) HandleLogout(w http.ResponseWriter, r *http.Request) {
 	cookie, err := r.Cookie("session_id")
 	if err == nil {