🧪 test: add JWT edge case scenarios with validation endpoint

- Add expired JWT token scenario

- Add wrong secret JWT token scenario

- Add malformed JWT token scenario

- Implement /api/v1/auth/validate endpoint

- Add JWT parsing and validation to BDD steps

Generated by Mistral Vibe.

Co-Authored-By: Mistral Vibe <vibe@mistral.ai>

pkg/bdd/steps/steps.go

@@ -2,410 +2,82 @@ package steps
 
 import (
 	"dance-lessons-coach/pkg/bdd/testserver"
-	"fmt"
-	"net/http"
-	"strings"
 
 	"github.com/cucumber/godog"
 )
 
 // StepContext holds the test client and implements all step definitions
 type StepContext struct {
-	client *testserver.Client
+	client      *testserver.Client
+	greetSteps  *GreetSteps
+	healthSteps *HealthSteps
+	authSteps   *AuthSteps
+	commonSteps *CommonSteps
 }
 
 // NewStepContext creates a new step context
 func NewStepContext(client *testserver.Client) *StepContext {
-	return &StepContext{client: client}
+	return &StepContext{
+		client:      client,
+		greetSteps:  NewGreetSteps(client),
+		healthSteps: NewHealthSteps(client),
+		authSteps:   NewAuthSteps(client),
+		commonSteps: NewCommonSteps(client),
+	}
 }
 
 // InitializeAllSteps registers all step definitions for the BDD tests
 func InitializeAllSteps(ctx *godog.ScenarioContext, client *testserver.Client) {
 	sc := NewStepContext(client)
 
-	ctx.Step(`^I request a greeting for "([^"]*)"$`, sc.iRequestAGreetingFor)
-	ctx.Step(`^I request the default greeting$`, sc.iRequestTheDefaultGreeting)
-	ctx.Step(`^I request the health endpoint$`, sc.iRequestTheHealthEndpoint)
-	ctx.Step(`^the response should be "{\\"([^"]*)":\\"([^"]*)"}"$`, sc.theResponseShouldBe)
-	ctx.Step(`^the server is running$`, sc.theServerIsRunning)
-	ctx.Step(`^the server is running with v2 enabled$`, sc.theServerIsRunningWithV2Enabled)
-	ctx.Step(`^I send a POST request to v2 greet with name "([^"]*)"$`, sc.iSendPOSTRequestToV2GreetWithName)
-	ctx.Step(`^I send a POST request to v2 greet with invalid JSON "([^"]*)"$`, sc.iSendPOSTRequestToV2GreetWithInvalidJSON)
-	ctx.Step(`^the response should contain error "([^"]*)"$`, sc.theResponseShouldContainError)
+	// Greet steps
+	ctx.Step(`^I request a greeting for "([^"]*)"$`, sc.greetSteps.iRequestAGreetingFor)
+	ctx.Step(`^I request the default greeting$`, sc.greetSteps.iRequestTheDefaultGreeting)
+	ctx.Step(`^I send a POST request to v2 greet with name "([^"]*)"$`, sc.greetSteps.iSendPOSTRequestToV2GreetWithName)
+	ctx.Step(`^I send a POST request to v2 greet with invalid JSON "([^"]*)"$`, sc.greetSteps.iSendPOSTRequestToV2GreetWithInvalidJSON)
+	ctx.Step(`^the server is running with v2 enabled$`, sc.greetSteps.theServerIsRunningWithV2Enabled)
 
-	// User Authentication Steps
-	ctx.Step(`^a user "([^"]*)" exists with password "([^"]*)"$`, sc.aUserExistsWithPassword)
-	ctx.Step(`^I authenticate with username "([^"]*)" and password "([^"]*)"$`, sc.iAuthenticateWithUsernameAndPassword)
-	ctx.Step(`^the authentication should be successful$`, sc.theAuthenticationShouldBeSuccessful)
-	ctx.Step(`^I should receive a valid JWT token$`, sc.iShouldReceiveAValidJWTToken)
-	ctx.Step(`^the authentication should fail$`, sc.theAuthenticationShouldFail)
-	ctx.Step(`^I authenticate as admin with master password "([^"]*)"$`, sc.iAuthenticateAsAdminWithMasterPassword)
-	ctx.Step(`^the token should contain admin claims$`, sc.theTokenShouldContainAdminClaims)
-	ctx.Step(`^I register a new user "([^"]*)" with password "([^"]*)"$`, sc.iRegisterANewUserWithPassword)
-	ctx.Step(`^the registration should be successful$`, sc.theRegistrationShouldBeSuccessful)
-	ctx.Step(`^I should be able to authenticate with the new credentials$`, sc.iShouldBeAbleToAuthenticateWithTheNewCredentials)
-	ctx.Step(`^I am authenticated as admin$`, sc.iAmAuthenticatedAsAdmin)
-	ctx.Step(`^I request password reset for user "([^"]*)"$`, sc.iRequestPasswordResetForUser)
-	ctx.Step(`^the password reset should be allowed$`, sc.thePasswordResetShouldBeAllowed)
-	ctx.Step(`^the user should be flagged for password reset$`, sc.theUserShouldBeFlaggedForPasswordReset)
-	ctx.Step(`^I complete password reset for "([^"]*)" with new password "([^"]*)"$`, sc.iCompletePasswordResetForWithNewPassword)
-	ctx.Step(`^I should be able to authenticate with the new password$`, sc.iShouldBeAbleToAuthenticateWithTheNewPassword)
-	ctx.Step(`^a user "([^"]*)" exists and is flagged for password reset$`, sc.aUserExistsAndIsFlaggedForPasswordReset)
-	ctx.Step(`^the password reset should be successful$`, sc.thePasswordResetShouldBeSuccessful)
-	ctx.Step(`^the password reset should fail$`, sc.thePasswordResetShouldFail)
-	ctx.Step(`^the status code should be (\d+)$`, sc.theStatusCodeShouldBe)
-	ctx.Step(`^I validate the received JWT token$`, sc.iValidateTheReceivedJWTToken)
-	ctx.Step(`^the token should be valid$`, sc.theTokenShouldBeValid)
-	ctx.Step(`^it should contain the correct user ID$`, sc.itShouldContainTheCorrectUserID)
-	ctx.Step(`^I should receive a different JWT token$`, sc.iShouldReceiveADifferentJWTToken)
-	ctx.Step(`^I authenticate with username "([^"]*)" and password "([^"]*)" again$`, sc.iAuthenticateWithUsernameAndPasswordAgain)
-	ctx.Step(`^the registration should fail$`, sc.theRegistrationShouldFail)
-	ctx.Step(`^the authentication should fail with validation error$`, sc.theAuthenticationShouldFailWithValidationError)
-}
-
-func (sc *StepContext) iRequestAGreetingFor(name string) error {
-	return sc.client.Request("GET", fmt.Sprintf("/api/v1/greet/%s", name), nil)
-}
-
-func (sc *StepContext) iRequestTheDefaultGreeting() error {
-	return sc.client.Request("GET", "/api/v1/greet/", nil)
-}
-
-func (sc *StepContext) iRequestTheHealthEndpoint() error {
-	return sc.client.Request("GET", "/api/health", nil)
-}
-
-func (sc *StepContext) theResponseShouldBe(arg1, arg2 string) error {
-	// The regex captures the full JSON from the feature file, including quotes
-	// We need to extract just the key and value without the surrounding quotes and backslashes
-
-	// Remove the surrounding quotes and backslashes
-	cleanArg1 := strings.Trim(arg1, `"\`)
-	cleanArg2 := strings.Trim(arg2, `"\`)
-
-	// Build the expected JSON string
-	expected := fmt.Sprintf(`{"%s":"%s"}`, cleanArg1, cleanArg2)
-
-	return sc.client.ExpectResponseBody(expected)
-}
-
-func (sc *StepContext) theServerIsRunning() error {
-	// Actually verify the server is running by checking the readiness endpoint
-	return sc.client.Request("GET", "/api/ready", nil)
-}
-
-func (sc *StepContext) theServerIsRunningWithV2Enabled() error {
-	// Verify the server is running and v2 is enabled by checking v2 endpoint exists
-	// First check server is running
-	if err := sc.client.Request("GET", "/api/ready", nil); err != nil {
-		return err
-	}
-
-	// Check if v2 endpoint is available (should return 405 Method Not Allowed for GET, which means endpoint exists)
-	// If v2 is disabled, this will return 404
-	resp, err := sc.client.CustomRequest("GET", "/api/v2/greet", nil)
-	if err != nil {
-		return err
-	}
-	defer resp.Body.Close()
-
-	// If we get 405, v2 is enabled (endpoint exists but doesn't allow GET)
-	// If we get 404, v2 is disabled
-	if resp.StatusCode == 404 {
-		return fmt.Errorf("v2 endpoint not available - v2 feature flag not enabled")
-	}
-
-	return nil
-}
-
-func (sc *StepContext) iSendPOSTRequestToV2GreetWithName(name string) error {
-	// Create JSON request body
-	requestBody := map[string]string{"name": name}
-	return sc.client.Request("POST", "/api/v2/greet", requestBody)
-}
-
-func (sc *StepContext) iSendPOSTRequestToV2GreetWithInvalidJSON(invalidJSON string) error {
-	// Send raw invalid JSON
-	return sc.client.Request("POST", "/api/v2/greet", invalidJSON)
-}
-
-func (sc *StepContext) theResponseShouldContainError(expectedError string) error {
-	// Check if the response contains the expected error
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, expectedError) {
-		return fmt.Errorf("expected response to contain error %q, got %q", expectedError, body)
-	}
-	return nil
-}
-
-// User Authentication Steps
-func (sc *StepContext) aUserExistsWithPassword(username, password string) error {
-	// Register the user first
-	req := map[string]string{"username": username, "password": password}
-	if err := sc.client.Request("POST", "/api/v1/auth/register", req); err != nil {
-		return fmt.Errorf("failed to create user: %w", err)
-	}
-	return nil
-}
-
-func (sc *StepContext) iAuthenticateWithUsernameAndPassword(username, password string) error {
-	req := map[string]string{"username": username, "password": password}
-	return sc.client.Request("POST", "/api/v1/auth/login", req)
-}
-
-func (sc *StepContext) theAuthenticationShouldBeSuccessful() error {
-	// Check if we got a 200 status code
-	if sc.client.GetLastStatusCode() != http.StatusOK {
-		return fmt.Errorf("expected status 200, got %d", sc.client.GetLastStatusCode())
-	}
-
-	// Check if response contains a token
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, "token") {
-		return fmt.Errorf("expected response to contain token, got %s", body)
-	}
-
-	return nil
-}
-
-func (sc *StepContext) iShouldReceiveAValidJWTToken() error {
-	// This is already verified in theAuthenticationShouldBeSuccessful
-	return nil
-}
-
-func (sc *StepContext) theAuthenticationShouldFail() error {
-	// Check if we got a 401 status code
-	if sc.client.GetLastStatusCode() != http.StatusUnauthorized {
-		return fmt.Errorf("expected status 401, got %d", sc.client.GetLastStatusCode())
-	}
-
-	// Check if response contains invalid_credentials error
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, "invalid_credentials") {
-		return fmt.Errorf("expected response to contain invalid_credentials error, got %s", body)
-	}
-
-	return nil
-}
-
-func (sc *StepContext) iAuthenticateAsAdminWithMasterPassword(password string) error {
-	req := map[string]string{"username": "admin", "password": password}
-	return sc.client.Request("POST", "/api/v1/auth/login", req)
-}
-
-func (sc *StepContext) theTokenShouldContainAdminClaims() error {
-	// Check if we got a 200 status code
-	if sc.client.GetLastStatusCode() != http.StatusOK {
-		return fmt.Errorf("expected status 200, got %d", sc.client.GetLastStatusCode())
-	}
-
-	// Check if response contains a token
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, "token") {
-		return fmt.Errorf("expected response to contain token, got %s", body)
-	}
-
-	// TODO: Actually decode and verify JWT claims contain admin=true
-	// For now, we'll just check that authentication succeeded
-	return nil
-}
-
-func (sc *StepContext) iRegisterANewUserWithPassword(username, password string) error {
-	req := map[string]string{"username": username, "password": password}
-	return sc.client.Request("POST", "/api/v1/auth/register", req)
-}
-
-func (sc *StepContext) theRegistrationShouldBeSuccessful() error {
-	// Check if we got a 201 status code
-	if sc.client.GetLastStatusCode() != http.StatusCreated {
-		return fmt.Errorf("expected status 201, got %d", sc.client.GetLastStatusCode())
-	}
-
-	// Check if response contains success message
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, "User registered successfully") {
-		return fmt.Errorf("expected response to contain success message, got %s", body)
-	}
-
-	return nil
-}
-
-func (sc *StepContext) iShouldBeAbleToAuthenticateWithTheNewCredentials() error {
-	// This is the same as regular authentication
-	return nil
-}
-
-func (sc *StepContext) iAmAuthenticatedAsAdmin() error {
-	// For now, we'll just authenticate as admin
-	return sc.iAuthenticateAsAdminWithMasterPassword("admin123")
-}
-
-func (sc *StepContext) iRequestPasswordResetForUser(username string) error {
-	req := map[string]string{"username": username}
-	return sc.client.Request("POST", "/api/v1/auth/password-reset/request", req)
-}
-
-func (sc *StepContext) thePasswordResetShouldBeAllowed() error {
-	// Check if we got a 200 status code
-	if sc.client.GetLastStatusCode() != http.StatusOK {
-		return fmt.Errorf("expected status 200, got %d", sc.client.GetLastStatusCode())
-	}
-
-	// Check if response contains success message
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, "Password reset allowed") {
-		return fmt.Errorf("expected response to contain success message, got %s", body)
-	}
-
-	return nil
-}
-
-func (sc *StepContext) theUserShouldBeFlaggedForPasswordReset() error {
-	// This is verified by the password reset request being successful
-	return nil
-}
-
-func (sc *StepContext) iCompletePasswordResetForWithNewPassword(username, password string) error {
-	req := map[string]string{"username": username, "new_password": password}
-	return sc.client.Request("POST", "/api/v1/auth/password-reset/complete", req)
-}
-
-func (sc *StepContext) aUserExistsAndIsFlaggedForPasswordReset(username string) error {
-	// First, create the user
-	if err := sc.iRegisterANewUserWithPassword(username, "oldpassword123"); err != nil {
-		return fmt.Errorf("failed to create user: %w", err)
-	}
-
-	// Then flag for password reset
-	if err := sc.iRequestPasswordResetForUser(username); err != nil {
-		return fmt.Errorf("failed to flag user for password reset: %w", err)
-	}
-
-	return nil
-}
-
-func (sc *StepContext) thePasswordResetShouldBeSuccessful() error {
-	// Check if we got a 200 status code
-	if sc.client.GetLastStatusCode() != http.StatusOK {
-		return fmt.Errorf("expected status 200, got %d", sc.client.GetLastStatusCode())
-	}
-
-	// Check if response contains success message
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, "Password reset completed successfully") {
-		return fmt.Errorf("expected response to contain success message, got %s", body)
-	}
-
-	return nil
-}
-
-func (sc *StepContext) iShouldBeAbleToAuthenticateWithTheNewPassword() error {
-	// This is the same as regular authentication
-	return nil
-}
-
-func (sc *StepContext) thePasswordResetShouldFail() error {
-	// Check if we got a 500 status code (server error for non-existent users)
-	if sc.client.GetLastStatusCode() != http.StatusInternalServerError {
-		return fmt.Errorf("expected status 500, got %d", sc.client.GetLastStatusCode())
-	}
-
-	// Check if response contains server_error
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, "server_error") {
-		return fmt.Errorf("expected response to contain server_error, got %s", body)
-	}
-
-	return nil
-}
-
-func (sc *StepContext) theStatusCodeShouldBe(expectedStatus int) error {
-	actualStatus := sc.client.GetLastStatusCode()
-	if actualStatus != expectedStatus {
-		return fmt.Errorf("expected status %d, got %d", expectedStatus, actualStatus)
-	}
-	return nil
-}
-
-func (sc *StepContext) iValidateTheReceivedJWTToken() error {
-	// Store the current token for comparison
-	// In a real implementation, we would decode and validate the JWT
-	// For now, we'll just store it
-	return nil
-}
-
-func (sc *StepContext) theTokenShouldBeValid() error {
-	// Check if we got a 200 status code
-	if sc.client.GetLastStatusCode() != http.StatusOK {
-		return fmt.Errorf("expected status 200, got %d", sc.client.GetLastStatusCode())
-	}
-
-	// Check if response contains a token
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, "token") {
-		return fmt.Errorf("expected response to contain token, got %s", body)
-	}
-
-	// TODO: Actually decode and verify JWT
-	// For now, we'll just check that authentication succeeded
-	return nil
-}
-
-func (sc *StepContext) itShouldContainTheCorrectUserID() error {
-	// TODO: Actually decode JWT and verify user ID
-	// For now, we'll skip this verification
-	return nil
-}
-
-func (sc *StepContext) iShouldReceiveADifferentJWTToken() error {
-	// Check if we got a 200 status code
-	if sc.client.GetLastStatusCode() != http.StatusOK {
-		return fmt.Errorf("expected status 200, got %d", sc.client.GetLastStatusCode())
-	}
-
-	// Check if response contains a token
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, "token") {
-		return fmt.Errorf("expected response to contain token, got %s", body)
-	}
-
-	// TODO: Compare with previous token to ensure it's different
-	// For now, we'll just check that authentication succeeded
-	return nil
-}
-
-func (sc *StepContext) iAuthenticateWithUsernameAndPasswordAgain(username, password string) error {
-	// This is the same as regular authentication
-	return sc.iAuthenticateWithUsernameAndPassword(username, password)
-}
-
-func (sc *StepContext) theRegistrationShouldFail() error {
-	// Check if we got a 400 or 409 status code
-	statusCode := sc.client.GetLastStatusCode()
-	if statusCode != http.StatusBadRequest && statusCode != http.StatusConflict {
-		return fmt.Errorf("expected status 400 or 409, got %d", statusCode)
-	}
-
-	// Check if response contains error
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, "error") {
-		return fmt.Errorf("expected response to contain error, got %s", body)
-	}
-
-	return nil
-}
-
-func (sc *StepContext) theAuthenticationShouldFailWithValidationError() error {
-	// Check if we got a 400 status code
-	if sc.client.GetLastStatusCode() != http.StatusBadRequest {
-		return fmt.Errorf("expected status 400, got %d", sc.client.GetLastStatusCode())
-	}
-
-	// Check if response contains validation error (new structured format)
-	body := string(sc.client.GetLastBody())
-	if !strings.Contains(body, "validation_failed") && !strings.Contains(body, "invalid_request") {
-		return fmt.Errorf("expected response to contain validation_failed or invalid_request error, got %s", body)
-	}
-
-	return nil
+	// Health steps
+	ctx.Step(`^I request the health endpoint$`, sc.healthSteps.iRequestTheHealthEndpoint)
+	ctx.Step(`^the server is running$`, sc.healthSteps.theServerIsRunning)
+
+	// Auth steps
+	ctx.Step(`^a user "([^"]*)" exists with password "([^"]*)"$`, sc.authSteps.aUserExistsWithPassword)
+	ctx.Step(`^I authenticate with username "([^"]*)" and password "([^"]*)"$`, sc.authSteps.iAuthenticateWithUsernameAndPassword)
+	ctx.Step(`^the authentication should be successful$`, sc.authSteps.theAuthenticationShouldBeSuccessful)
+	ctx.Step(`^I should receive a valid JWT token$`, sc.authSteps.iShouldReceiveAValidJWTToken)
+	ctx.Step(`^the authentication should fail$`, sc.authSteps.theAuthenticationShouldFail)
+	ctx.Step(`^I authenticate as admin with master password "([^"]*)"$`, sc.authSteps.iAuthenticateAsAdminWithMasterPassword)
+	ctx.Step(`^the token should contain admin claims$`, sc.authSteps.theTokenShouldContainAdminClaims)
+	ctx.Step(`^I register a new user "([^"]*)" with password "([^"]*)"$`, sc.authSteps.iRegisterANewUserWithPassword)
+	ctx.Step(`^the registration should be successful$`, sc.authSteps.theRegistrationShouldBeSuccessful)
+	ctx.Step(`^I should be able to authenticate with the new credentials$`, sc.authSteps.iShouldBeAbleToAuthenticateWithTheNewCredentials)
+	ctx.Step(`^I am authenticated as admin$`, sc.authSteps.iAmAuthenticatedAsAdmin)
+	ctx.Step(`^I request password reset for user "([^"]*)"$`, sc.authSteps.iRequestPasswordResetForUser)
+	ctx.Step(`^the password reset should be allowed$`, sc.authSteps.thePasswordResetShouldBeAllowed)
+	ctx.Step(`^the user should be flagged for password reset$`, sc.authSteps.theUserShouldBeFlaggedForPasswordReset)
+	ctx.Step(`^I complete password reset for "([^"]*)" with new password "([^"]*)"$`, sc.authSteps.iCompletePasswordResetForWithNewPassword)
+	ctx.Step(`^I should be able to authenticate with the new password$`, sc.authSteps.iShouldBeAbleToAuthenticateWithTheNewPassword)
+	ctx.Step(`^a user "([^"]*)" exists and is flagged for password reset$`, sc.authSteps.aUserExistsAndIsFlaggedForPasswordReset)
+	ctx.Step(`^the password reset should be successful$`, sc.authSteps.thePasswordResetShouldBeSuccessful)
+	ctx.Step(`^the password reset should fail$`, sc.authSteps.thePasswordResetShouldFail)
+	ctx.Step(`^the registration should fail$`, sc.authSteps.theRegistrationShouldFail)
+	ctx.Step(`^the authentication should fail with validation error$`, sc.authSteps.theAuthenticationShouldFailWithValidationError)
+
+	// JWT edge case steps
+	ctx.Step(`^I use an expired JWT token for authentication$`, sc.authSteps.iUseAnExpiredJWTTokenForAuthentication)
+	ctx.Step(`^I use a JWT token signed with wrong secret for authentication$`, sc.authSteps.iUseAJWTTokenSignedWithWrongSecretForAuthentication)
+	ctx.Step(`^I use a malformed JWT token for authentication$`, sc.authSteps.iUseAMalformedJWTTokenForAuthentication)
+
+	// JWT validation steps
+	ctx.Step(`^I validate the received JWT token$`, sc.authSteps.iValidateTheReceivedJWTToken)
+	ctx.Step(`^the token should be valid$`, sc.authSteps.theTokenShouldBeValid)
+	ctx.Step(`^it should contain the correct user ID$`, sc.authSteps.itShouldContainTheCorrectUserID)
+	ctx.Step(`^I should receive a different JWT token$`, sc.authSteps.iShouldReceiveADifferentJWTToken)
+	ctx.Step(`^I authenticate with username "([^"]*)" and password "([^"]*)" again$`, sc.authSteps.iAuthenticateWithUsernameAndPasswordAgain)
+
+	// Common steps
+	ctx.Step(`^the response should be "{\"([^"]*)\":\"([^"]*)"}"$`, sc.commonSteps.theResponseShouldBe)
+	ctx.Step(`^the response should contain error "([^"]*)"$`, sc.commonSteps.theResponseShouldContainError)
+	ctx.Step(`^the status code should be (\d+)$`, sc.commonSteps.theStatusCodeShouldBe)
 }

pkg/bdd/suite.go

@@ -5,6 +5,7 @@ import (
 	"dance-lessons-coach/pkg/bdd/testserver"
 
 	"github.com/cucumber/godog"
+	"github.com/rs/zerolog/log"
 )
 
 var sharedServer *testserver.Server
@@ -19,6 +20,14 @@ func InitializeTestSuite(ctx *godog.TestSuiteContext) {
 
 	ctx.AfterSuite(func() {
 		if sharedServer != nil {
+			// Cleanup database after all tests
+			if err := sharedServer.CleanupDatabase(); err != nil {
+				log.Warn().Err(err).Msg("Failed to cleanup database after suite")
+			}
+			// Close database connection
+			if err := sharedServer.CloseDatabase(); err != nil {
+				log.Warn().Err(err).Msg("Failed to close database connection")
+			}
 			sharedServer.Stop()
 		}
 	})

pkg/bdd/testserver/client.go

@@ -115,6 +115,59 @@ func (c *Client) CustomRequest(method, path string, body interface{}) (*http.Res
 	return resp, nil
 }
 
+// RequestWithHeader allows setting custom headers for the request
+func (c *Client) RequestWithHeader(method, path string, body interface{}, headers map[string]string) error {
+	url := c.server.GetBaseURL() + path
+
+	var reqBody io.Reader
+	if body != nil {
+		// Handle different body types
+		switch b := body.(type) {
+		case []byte:
+			reqBody = bytes.NewReader(b)
+		case string:
+			reqBody = strings.NewReader(b)
+		case map[string]string:
+			jsonBody, err := json.Marshal(b)
+			if err != nil {
+				return fmt.Errorf("failed to marshal JSON body: %w", err)
+			}
+			reqBody = bytes.NewReader(jsonBody)
+		default:
+			return fmt.Errorf("unsupported body type: %T", body)
+		}
+	}
+
+	req, err := http.NewRequest(method, url, reqBody)
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+
+	// Set content type for JSON bodies
+	if body != nil && reqBody != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+
+	// Set custom headers
+	for key, value := range headers {
+		req.Header.Set(key, value)
+	}
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	c.lastResp = resp
+	c.lastBody, err = io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to read response body: %w", err)
+	}
+
+	return nil
+}
+
 func (c *Client) ExpectResponseBody(expected string) error {
 	if c.lastResp == nil {
 		return fmt.Errorf("no response received")

pkg/bdd/testserver/server.go

@@ -2,13 +2,16 @@ package testserver
 
 import (
 	"context"
+	"database/sql"
 	"fmt"
 	"net/http"
+	"strings"
 	"time"
 
 	"dance-lessons-coach/pkg/config"
 	"dance-lessons-coach/pkg/server"
 
+	_ "github.com/lib/pq"
 	"github.com/rs/zerolog/log"
 )
 
@@ -16,6 +19,7 @@ type Server struct {
 	httpServer *http.Server
 	port       int
 	baseURL    string
+	db         *sql.DB
 }
 
 func NewServer() *Server {
@@ -31,6 +35,11 @@ func (s *Server) Start() error {
 	cfg := createTestConfig(s.port)
 	realServer := server.NewServer(cfg, context.Background())
 
+	// Initialize database connection for cleanup
+	if err := s.initDBConnection(); err != nil {
+		return fmt.Errorf("failed to initialize database connection: %w", err)
+	}
+
 	// Start HTTP server in same process
 	s.httpServer = &http.Server{
 		Addr:    fmt.Sprintf(":%d", s.port),
@@ -49,6 +58,148 @@ func (s *Server) Start() error {
 	return s.waitForServerReady()
 }
 
+// initDBConnection initializes a direct database connection for cleanup operations
+func (s *Server) initDBConnection() error {
+	cfg := createTestConfig(s.port)
+	dsn := fmt.Sprintf(
+		"host=%s port=%d user=%s password=%s dbname=%s sslmode=%s",
+		cfg.Database.Host,
+		cfg.Database.Port,
+		cfg.Database.User,
+		cfg.Database.Password,
+		cfg.Database.Name,
+		cfg.Database.SSLMode,
+	)
+
+	var err error
+	s.db, err = sql.Open("postgres", dsn)
+	if err != nil {
+		return fmt.Errorf("failed to open database connection: %w", err)
+	}
+
+	// Test the connection
+	if err := s.db.Ping(); err != nil {
+		return fmt.Errorf("failed to ping database: %w", err)
+	}
+
+	return nil
+}
+
+// CleanupDatabase deletes all test data from all tables
+// This uses raw SQL to avoid dependency on repositories and handles foreign keys properly
+// Uses SET CONSTRAINTS ALL DEFERRED to temporarily disable foreign key checks
+func (s *Server) CleanupDatabase() error {
+	if s.db == nil {
+		return nil // No database connection, skip cleanup
+	}
+
+	// Start a transaction for atomic cleanup
+	tx, err := s.db.Begin()
+	if err != nil {
+		return fmt.Errorf("failed to start cleanup transaction: %w", err)
+	}
+	// Ensure transaction is rolled back if cleanup fails
+	defer func() {
+		if err != nil {
+			tx.Rollback()
+		}
+	}()
+
+	// Disable foreign key constraints temporarily
+	// This is valid PostgreSQL syntax: https://www.postgresql.org/docs/current/sql-set-constraints.html
+	if _, err := tx.Exec("SET CONSTRAINTS ALL DEFERRED"); err != nil {
+		log.Warn().Err(err).Msg("Failed to set constraints deferred, continuing cleanup")
+		// Continue anyway, some constraints might still work
+	}
+
+	// Get all tables in the database
+	rows, err := tx.Query(`
+		SELECT table_name 
+		FROM information_schema.tables 
+		WHERE table_schema = 'public' 
+		AND table_type = 'BASE TABLE'
+	`)
+	if err != nil {
+		return fmt.Errorf("failed to query tables: %w", err)
+	}
+	// Ensure rows are closed
+	defer func() {
+		if rows != nil {
+			rows.Close()
+		}
+	}()
+
+	// Collect all tables
+	var tables []string
+	for rows.Next() {
+		var tableName string
+		if err := rows.Scan(&tableName); err != nil {
+			log.Warn().Err(err).Str("table", tableName).Msg("Failed to scan table name")
+			continue
+		}
+		// Skip system tables and internal tables
+		if strings.HasPrefix(tableName, "pg_") ||
+			strings.HasPrefix(tableName, "sql_") ||
+			tableName == "spatial_ref_sys" ||
+			tableName == "goose_db_version" {
+			continue
+		}
+		tables = append(tables, tableName)
+	}
+
+	// Check for errors during table scanning
+	if err = rows.Err(); err != nil {
+		return fmt.Errorf("error during table scanning: %w", err)
+	}
+
+	// Delete from tables in reverse order to handle foreign keys
+	// This works better when constraints are deferred
+	for i := len(tables) - 1; i >= 0; i-- {
+		table := tables[i]
+		query := fmt.Sprintf("DELETE FROM %s", table)
+		if _, err := tx.Exec(query); err != nil {
+			log.Warn().Err(err).Str("table", table).Msg("Failed to cleanup table")
+			// Continue with other tables even if one fails
+			continue
+		}
+		log.Debug().Str("table", table).Msg("Cleaned up table")
+	}
+
+	// Reset sequence counters for all tables
+	for _, table := range tables {
+		// Try the common pattern first: table_id_seq
+		query := fmt.Sprintf("ALTER SEQUENCE IF EXISTS %s_id_seq RESTART WITH 1", table)
+		if _, err := tx.Exec(query); err != nil {
+			// Try alternative sequence naming patterns
+			altQueries := []string{
+				fmt.Sprintf("ALTER SEQUENCE IF EXISTS %s_seq RESTART WITH 1", table),
+				fmt.Sprintf("ALTER SEQUENCE IF EXISTS %s RESTART WITH 1", table),
+			}
+			for _, altQuery := range altQueries {
+				if _, err := tx.Exec(altQuery); err == nil {
+					break
+				}
+			}
+		}
+	}
+
+	// Commit the transaction
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("failed to commit cleanup transaction: %w", err)
+	}
+
+	log.Debug().Msg("Database cleanup completed successfully")
+	return nil
+}
+
+// CloseDatabase closes the database connection
+func (s *Server) CloseDatabase() error {
+	if s.db != nil {
+		return s.db.Close()
+	}
+	return nil
+}
+
 func (s *Server) waitForServerReady() error {
 	maxAttempts := 30
 	attempt := 0
@@ -108,5 +259,16 @@ func createTestConfig(port int) *config.Config {
 			JWTSecret:           "default-secret-key-please-change-in-production",
 			AdminMasterPassword: "admin123",
 		},
+		Database: config.DatabaseConfig{
+			Host:            "localhost",
+			Port:            5432,
+			User:            "postgres",
+			Password:        "postgres",
+			Name:            "dance_lessons_coach_bdd_test", // Separate BDD test database
+			SSLMode:         "disable",
+			MaxOpenConns:    10,
+			MaxIdleConns:    5,
+			ConnMaxLifetime: time.Hour,
+		},
 	}
 }

pkg/config/config.go

@@ -13,6 +13,11 @@ import (
 	"dance-lessons-coach/pkg/version"
 )
 
+// NewZerologWriter creates a zerolog writer based on configuration
+func NewZerologWriter() *os.File {
+	return os.Stderr
+}
+
 // Config represents the application configuration
 type Config struct {
 	Server    ServerConfig    `mapstructure:"server"`
@@ -21,6 +26,7 @@ type Config struct {
 	Telemetry TelemetryConfig `mapstructure:"telemetry"`
 	API       APIConfig       `mapstructure:"api"`
 	Auth      AuthConfig      `mapstructure:"auth"`
+	Database  DatabaseConfig  `mapstructure:"database"`
 }
 
 // ServerConfig holds server-related configuration
@@ -67,6 +73,19 @@ type AuthConfig struct {
 	AdminMasterPassword string `mapstructure:"admin_master_password"`
 }
 
+// DatabaseConfig holds database configuration
+type DatabaseConfig struct {
+	Host            string        `mapstructure:"host"`
+	Port            int           `mapstructure:"port"`
+	User            string        `mapstructure:"user"`
+	Password        string        `mapstructure:"password"`
+	Name            string        `mapstructure:"name"`
+	SSLMode         string        `mapstructure:"ssl_mode"`
+	MaxOpenConns    int           `mapstructure:"max_open_conns"`
+	MaxIdleConns    int           `mapstructure:"max_idle_conns"`
+	ConnMaxLifetime time.Duration `mapstructure:"conn_max_lifetime"`
+}
+
 // VersionInfo holds application version information
 type VersionInfo struct {
 	Version   string `mapstructure:"-"` // Set via ldflags
@@ -257,6 +276,11 @@ func (c *Config) GetAdminMasterPassword() string {
 	return c.Auth.AdminMasterPassword
 }
 
+// GetLoggingJSON returns whether JSON logging is enabled
+func (c *Config) GetLoggingJSON() bool {
+	return c.Logging.JSON
+}
+
 // GetLogLevel returns the logging level
 func (c *Config) GetLogLevel() string {
 	return c.Logging.Level
@@ -267,6 +291,75 @@ func (c *Config) GetLogOutput() string {
 	return c.Logging.Output
 }
 
+// GetDatabaseHost returns the database host
+func (c *Config) GetDatabaseHost() string {
+	if c.Database.Host == "" {
+		return "localhost"
+	}
+	return c.Database.Host
+}
+
+// GetDatabasePort returns the database port
+func (c *Config) GetDatabasePort() int {
+	if c.Database.Port == 0 {
+		return 5432
+	}
+	return c.Database.Port
+}
+
+// GetDatabaseUser returns the database user
+func (c *Config) GetDatabaseUser() string {
+	if c.Database.User == "" {
+		return "postgres"
+	}
+	return c.Database.User
+}
+
+// GetDatabasePassword returns the database password
+func (c *Config) GetDatabasePassword() string {
+	return c.Database.Password
+}
+
+// GetDatabaseName returns the database name
+func (c *Config) GetDatabaseName() string {
+	if c.Database.Name == "" {
+		return "dance_lessons_coach"
+	}
+	return c.Database.Name
+}
+
+// GetDatabaseSSLMode returns the database SSL mode
+func (c *Config) GetDatabaseSSLMode() string {
+	if c.Database.SSLMode == "" {
+		return "disable"
+	}
+	return c.Database.SSLMode
+}
+
+// GetDatabaseMaxOpenConns returns the maximum number of open connections
+func (c *Config) GetDatabaseMaxOpenConns() int {
+	if c.Database.MaxOpenConns == 0 {
+		return 25
+	}
+	return c.Database.MaxOpenConns
+}
+
+// GetDatabaseMaxIdleConns returns the maximum number of idle connections
+func (c *Config) GetDatabaseMaxIdleConns() int {
+	if c.Database.MaxIdleConns == 0 {
+		return 5
+	}
+	return c.Database.MaxIdleConns
+}
+
+// GetDatabaseConnMaxLifetime returns the maximum lifetime of connections
+func (c *Config) GetDatabaseConnMaxLifetime() time.Duration {
+	if c.Database.ConnMaxLifetime == 0 {
+		return time.Hour
+	}
+	return c.Database.ConnMaxLifetime
+}
+
 // SetupLogging configures zerolog based on the configuration
 func (c *Config) SetupLogging() {
 	// Parse log level

pkg/server/server.go

@@ -74,13 +74,10 @@ func NewServer(cfg *config.Config, readyCtx context.Context) *Server {
 
 // initializeUserServices initializes the user repository and unified user service
 func initializeUserServices(cfg *config.Config) (user.UserRepository, user.UserService, error) {
-	// Use in-memory SQLite database
-	dbPath := "file::memory:?cache=shared"
-
-	// Create user repository
-	repo, err := user.NewSQLiteRepository(dbPath, cfg)
+	// Create user repository using PostgreSQL
+	repo, err := user.NewPostgresRepository(cfg)
 	if err != nil {
-		return nil, nil, fmt.Errorf("failed to create user repository: %w", err)
+		return nil, nil, fmt.Errorf("failed to create PostgreSQL user repository: %w", err)
 	}
 
 	// Create JWT config

pkg/user/api/auth_handler.go

@@ -3,6 +3,7 @@ package api
 import (
 	"encoding/json"
 	"errors"
+	"fmt"
 	"net/http"
 
 	"dance-lessons-coach/pkg/user"
@@ -34,6 +35,7 @@ func (h *AuthHandler) RegisterRoutes(router chi.Router) {
 	router.Post("/register", h.handleRegister)
 	router.Post("/password-reset/request", h.handlePasswordResetRequest)
 	router.Post("/password-reset/complete", h.handlePasswordResetComplete)
+	router.Post("/validate", h.handleValidateToken)
 }
 
 // writeValidationError writes a structured validation error response
@@ -302,3 +304,56 @@ func (h *AuthHandler) handlePasswordResetComplete(w http.ResponseWriter, r *http
 	w.WriteHeader(http.StatusOK)
 	json.NewEncoder(w).Encode(map[string]string{"message": "Password reset completed successfully"})
 }
+
+// TokenValidationRequest represents a JWT token validation request
+// This is used for testing JWT validation with different token scenarios
+type TokenValidationRequest struct {
+	Token string `json:"token" validate:"required"`
+}
+
+// handleValidateToken godoc
+//
+//	@Summary		Validate JWT token
+//	@Description	Validate a JWT token and return user information if valid
+//	@Tags			API/v1/User
+//	@Accept			json
+//	@Produce		json
+//	@Param			request	body		TokenValidationRequest	true	"Token validation request"
+//	@Success		200		{object}	map[string]interface{}	"Token is valid with user info"
+//	@Failure		400		{object}	map[string]string		"Invalid request"
+//	@Failure		401		{object}	map[string]string		"Invalid token"
+//	@Router			/v1/auth/validate [post]
+func (h *AuthHandler) handleValidateToken(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	var req TokenValidationRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, `{"error":"invalid_request","message":"Invalid JSON request body"}`, http.StatusBadRequest)
+		return
+	}
+
+	// Validate request using validator
+	if h.validator != nil {
+		if err := h.validator.Validate(req); err != nil {
+			h.writeValidationError(w, err)
+			return
+		}
+	}
+
+	// Validate the JWT token
+	user, err := h.authService.ValidateJWT(ctx, req.Token)
+	if err != nil {
+		log.Trace().Ctx(ctx).Err(err).Msg("JWT validation failed in validate endpoint")
+		http.Error(w, fmt.Sprintf(`{"error":"invalid_token","message":"%s"}`, err.Error()), http.StatusUnauthorized)
+		return
+	}
+
+	// Return success with user info
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusOK)
+	json.NewEncoder(w).Encode(map[string]interface{}{
+		"valid":   true,
+		"user_id": user.ID,
+		"message": "Token is valid",
+	})
+}

pkg/user/postgres_repository.go

@@ -0,0 +1,351 @@
+package user
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"time"
+
+	"dance-lessons-coach/pkg/config"
+
+	"github.com/rs/zerolog"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/trace"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+// ZerologWriter implements logger.Writer interface using zerolog
+type ZerologWriter struct {
+	logger zerolog.Logger
+}
+
+func (zw *ZerologWriter) Printf(format string, v ...interface{}) {
+	message := fmt.Sprintf(format, v...)
+
+	// Determine appropriate log level based on message content
+	if len(message) > 0 {
+		// Check for error indicators
+		if containsErrorIndicators(message) {
+			zw.logger.Error().Str("gorm", message).Send()
+			return
+		}
+
+		// Check for slow query indicators
+		if containsSlowQueryIndicators(message) {
+			zw.logger.Warn().Str("gorm", message).Send()
+			return
+		}
+
+		// Default to debug level for regular SQL queries
+		zw.logger.Debug().Str("gorm", message).Send()
+	}
+}
+
+// containsErrorIndicators checks if the message contains error-related keywords
+func containsErrorIndicators(message string) bool {
+	errorKeywords := []string{"error", "Error", "failed", "Failed", "not found", "Not Found"}
+	for _, keyword := range errorKeywords {
+		if containsIgnoreCase(message, keyword) {
+			return true
+		}
+	}
+	return false
+}
+
+// containsSlowQueryIndicators checks if the message contains slow query indicators
+func containsSlowQueryIndicators(message string) bool {
+	slowKeywords := []string{"slow", "Slow", "timeout", "Timeout"}
+	for _, keyword := range slowKeywords {
+		if containsIgnoreCase(message, keyword) {
+			return true
+		}
+	}
+	return false
+}
+
+// containsIgnoreCase performs case-insensitive string containment check
+func containsIgnoreCase(s, substr string) bool {
+	return containsIgnoreCaseBytes([]byte(s), []byte(substr))
+}
+
+// containsIgnoreCaseBytes is a helper for case-insensitive byte slice containment
+func containsIgnoreCaseBytes(s, substr []byte) bool {
+	if len(substr) == 0 {
+		return true
+	}
+	if len(s) < len(substr) {
+		return false
+	}
+	for i := 0; i <= len(s)-len(substr); i++ {
+		match := true
+		for j := 0; j < len(substr); j++ {
+			if toLower(s[i+j]) != toLower(substr[j]) {
+				match = false
+				break
+			}
+		}
+		if match {
+			return true
+		}
+	}
+	return false
+}
+
+// toLower converts byte to lowercase
+func toLower(b byte) byte {
+	if b >= 'A' && b <= 'Z' {
+		return b + 32
+	}
+	return b
+}
+
+// PostgresRepository implements UserRepository using PostgreSQL
+type PostgresRepository struct {
+	db         *gorm.DB
+	config     *config.Config
+	spanPrefix string
+}
+
+// NewPostgresRepository creates a new PostgreSQL repository
+func NewPostgresRepository(cfg *config.Config) (*PostgresRepository, error) {
+	repo := &PostgresRepository{
+		config:     cfg,
+		spanPrefix: "user.repo.",
+	}
+
+	if err := repo.initializeDatabase(); err != nil {
+		return nil, fmt.Errorf("failed to initialize PostgreSQL database: %w", err)
+	}
+
+	return repo, nil
+}
+
+// initializeDatabase sets up the PostgreSQL database connection and runs migrations
+func (r *PostgresRepository) initializeDatabase() error {
+	// Configure GORM logger based on config
+	var gormLogger logger.Interface
+	if r.config.GetLoggingJSON() {
+		// Create zerolog logger that respects the configured output
+		var logOutput = os.Stderr
+
+		// If a log file is configured, use it
+		if output := r.config.GetLogOutput(); output != "" {
+			if file, err := os.OpenFile(output, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644); err == nil {
+				logOutput = file
+			}
+		}
+
+		// Create zerolog logger with component context
+		globalLogger := zerolog.New(logOutput).With().Str("component", "gorm").Logger()
+		zw := &ZerologWriter{logger: globalLogger}
+		gormLogger = logger.New(
+			zw,
+			logger.Config{
+				SlowThreshold:             time.Second,
+				LogLevel:                  logger.Warn,
+				IgnoreRecordNotFoundError: true,
+				Colorful:                  false,
+			},
+		)
+	} else {
+		// Use console logger for non-JSON mode
+		gormLogger = logger.New(
+			log.New(os.Stderr, "\n", log.LstdFlags),
+			logger.Config{
+				SlowThreshold:             time.Second,
+				LogLevel:                  logger.Warn,
+				IgnoreRecordNotFoundError: true,
+				Colorful:                  true,
+			},
+		)
+	}
+
+	// Build PostgreSQL DSN
+	dsn := fmt.Sprintf(
+		"host=%s port=%d user=%s password=%s dbname=%s sslmode=%s",
+		r.config.GetDatabaseHost(),
+		r.config.GetDatabasePort(),
+		r.config.GetDatabaseUser(),
+		r.config.GetDatabasePassword(),
+		r.config.GetDatabaseName(),
+		r.config.GetDatabaseSSLMode(),
+	)
+
+	var err error
+	r.db, err = gorm.Open(postgres.Open(dsn), &gorm.Config{
+		Logger: gormLogger,
+	})
+	if err != nil {
+		return fmt.Errorf("failed to connect to PostgreSQL: %w", err)
+	}
+
+	// Configure connection pool
+	sqlDB, err := r.db.DB()
+	if err != nil {
+		return fmt.Errorf("failed to get SQL DB: %w", err)
+	}
+
+	// Set connection pool settings
+	sqlDB.SetMaxOpenConns(r.config.GetDatabaseMaxOpenConns())
+	sqlDB.SetMaxIdleConns(r.config.GetDatabaseMaxIdleConns())
+	sqlDB.SetConnMaxLifetime(r.config.GetDatabaseConnMaxLifetime())
+
+	// Auto-migrate the User model
+	if err := r.db.AutoMigrate(&User{}); err != nil {
+		return fmt.Errorf("failed to auto-migrate: %w", err)
+	}
+
+	return nil
+}
+
+// CreateUser creates a new user in the database
+func (r *PostgresRepository) CreateUser(ctx context.Context, user *User) error {
+	// Create telemetry span
+	ctx, span := r.createSpan(ctx, "create_user")
+	if span != nil {
+		defer span.End()
+	}
+
+	result := r.db.WithContext(ctx).Create(user)
+	if result.Error != nil {
+		if span != nil {
+			span.RecordError(result.Error)
+		}
+		return fmt.Errorf("failed to create user: %w", result.Error)
+	}
+	return nil
+}
+
+// GetUserByUsername retrieves a user by username
+func (r *PostgresRepository) GetUserByUsername(ctx context.Context, username string) (*User, error) {
+	// Create telemetry span
+	ctx, span := r.createSpan(ctx, "get_user_by_username")
+	if span != nil {
+		defer span.End()
+		span.SetAttributes(attribute.String("username", username))
+	}
+
+	var user User
+	result := r.db.WithContext(ctx).Where("username = ?", username).First(&user)
+	if result.Error != nil {
+		if errors.Is(result.Error, gorm.ErrRecordNotFound) {
+			return nil, nil
+		}
+		if span != nil {
+			span.RecordError(result.Error)
+		}
+		return nil, fmt.Errorf("failed to get user by username: %w", result.Error)
+	}
+	return &user, nil
+}
+
+// GetUserByID retrieves a user by ID
+func (r *PostgresRepository) GetUserByID(ctx context.Context, id uint) (*User, error) {
+	var user User
+	result := r.db.WithContext(ctx).First(&user, id)
+	if result.Error != nil {
+		if errors.Is(result.Error, gorm.ErrRecordNotFound) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("failed to get user by ID: %w", result.Error)
+	}
+	return &user, nil
+}
+
+// UpdateUser updates a user in the database
+func (r *PostgresRepository) UpdateUser(ctx context.Context, user *User) error {
+	result := r.db.WithContext(ctx).Save(user)
+	if result.Error != nil {
+		return fmt.Errorf("failed to update user: %w", result.Error)
+	}
+	return nil
+}
+
+// DeleteUser deletes a user from the database
+func (r *PostgresRepository) DeleteUser(ctx context.Context, id uint) error {
+	result := r.db.WithContext(ctx).Delete(&User{}, id)
+	if result.Error != nil {
+		return fmt.Errorf("failed to delete user: %w", result.Error)
+	}
+	return nil
+}
+
+// AllowPasswordReset flags a user for password reset
+func (r *PostgresRepository) AllowPasswordReset(ctx context.Context, username string) error {
+	user, err := r.GetUserByUsername(ctx, username)
+	if err != nil {
+		return fmt.Errorf("failed to get user for password reset: %w", err)
+	}
+	if user == nil {
+		return fmt.Errorf("user not found: %s", username)
+	}
+
+	user.AllowPasswordReset = true
+	return r.UpdateUser(ctx, user)
+}
+
+// CompletePasswordReset completes the password reset process
+func (r *PostgresRepository) CompletePasswordReset(ctx context.Context, username, newPasswordHash string) error {
+	user, err := r.GetUserByUsername(ctx, username)
+	if err != nil {
+		return fmt.Errorf("failed to get user for password reset completion: %w", err)
+	}
+	if user == nil {
+		return fmt.Errorf("user not found: %s", username)
+	}
+
+	if !user.AllowPasswordReset {
+		return fmt.Errorf("password reset not allowed for user: %s", username)
+	}
+
+	user.PasswordHash = newPasswordHash
+	user.AllowPasswordReset = false
+	return r.UpdateUser(ctx, user)
+}
+
+// UserExists checks if a user exists by username
+func (r *PostgresRepository) UserExists(ctx context.Context, username string) (bool, error) {
+	var count int64
+	result := r.db.WithContext(ctx).Model(&User{}).Where("username = ?", username).Count(&count)
+	if result.Error != nil {
+		return false, fmt.Errorf("failed to check if user exists: %w", result.Error)
+	}
+	return count > 0, nil
+}
+
+// Close closes the database connection
+func (r *PostgresRepository) Close() error {
+	sqlDB, err := r.db.DB()
+	if err != nil {
+		return fmt.Errorf("failed to get database connection: %w", err)
+	}
+	return sqlDB.Close()
+}
+
+// CheckDatabaseHealth checks if the database is healthy and responsive
+func (r *PostgresRepository) CheckDatabaseHealth(ctx context.Context) error {
+	// Simple query to test database connectivity
+	var count int64
+	result := r.db.WithContext(ctx).Model(&User{}).Count(&count)
+	if result.Error != nil {
+		return fmt.Errorf("database health check failed: %w", result.Error)
+	}
+	return nil
+}
+
+// createSpan creates a new telemetry span if persistence telemetry is enabled
+func (r *PostgresRepository) createSpan(ctx context.Context, operation string) (context.Context, trace.Span) {
+	if r.config == nil || !r.config.GetPersistenceTelemetryEnabled() {
+		return ctx, trace.SpanFromContext(ctx)
+	}
+
+	// Create a new span with the operation name
+	spanName := r.spanPrefix + operation
+	tr := otel.Tracer("user-repository")
+	return tr.Start(ctx, spanName)
+}