🧪 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>

adr/0019-postgresql-integration.md

@@ -206,9 +206,10 @@ The PostgreSQL integration follows established DanceLessonsCoach patterns:
    - Add PostgreSQL-specific connection management
 
 3. **Docker Setup:**
-   - Create `docker-compose.yml` with PostgreSQL service
+   - Create `docker-compose.yml` with PostgreSQL 16 service (current stable version)
    - Add initialization scripts for development
    - Configure health checks and monitoring
+   - Use Alpine-based image for smaller footprint
 
 4. **Configuration:**
    - Add `DatabaseConfig` to existing config structure
@@ -235,17 +236,33 @@ The PostgreSQL integration follows established DanceLessonsCoach patterns:
 #### Phase 3: Testing & Validation
 
 1. **BDD Test Integration:**
-   - Temporary test database setup using testcontainers
+   - Updated test server configuration with PostgreSQL settings
-   - Clean database between scenarios
+   - Automatic PostgreSQL container startup in test script
-   - Test data isolation and transaction management
+   - Health checks for database readiness before tests
+   - **Separate BDD test database** (`dance_lessons_coach_bdd_test`)
+   - Complete isolation from development/production databases
 
-2. **Unit & Integration Tests:**
+2. **Test Script Enhancement:**
+   - `scripts/run-bdd-tests.sh` now starts PostgreSQL if needed
+   - **Automatic BDD database creation** using `createdb` command
+   - Checks for existing BDD database before creating
+   - Waits for database readiness before running tests
+   - Proper error handling and timeout management
+   - Reuses existing container if already running
+
+3. **Database Isolation Strategy:**
+   - **Development**: `dance_lessons_coach` (config.yaml)
+   - **BDD Tests**: `dance_lessons_coach_bdd_test` (automatically created)
+   - **Production**: Custom name per environment
+   - **Manual Testing**: Developers can use development database
+
+3. **Unit & Integration Tests:**
    - Repository method testing with PostgreSQL
    - Transaction and error case testing
    - Performance benchmarks
    - Connection failure scenarios
 
-3. **Graceful Shutdown Testing:**
+4. **Graceful Shutdown Testing:**
    - Database connection cleanup during shutdown
    - Readiness endpoint behavior during shutdown
    - Connection pool behavior under stress
@@ -520,7 +537,41 @@ The implementation maintains full backward compatibility:
 4. Should we add database connection health metrics?
 5. What query timeout should we set for production?
 
-## BDD Testing Strategy
+## Database Cleanup Strategy
+
+### Decision: Raw SQL Cleanup Between Scenarios
+
+**Approach:** Use raw SQL DELETE statements with `SET CONSTRAINTS ALL DEFERRED` to clean up database between test scenarios
+
+**Rationale:**
+- **Black Box Principle:** BDD tests should not depend on implementation details
+- **Foreign Key Safety:** `SET CONSTRAINTS ALL DEFERRED` allows proper handling of constraints (PostgreSQL docs: https://www.postgresql.org/docs/current/sql-set-constraints.html)
+- **Migration Compatibility:** Works regardless of schema changes
+- **Transaction Safety:** Uses explicit transactions with proper rollback handling
+
+**Alternatives Considered:**
+1. **Repository-based cleanup** - Rejected: Violates black box principle
+2. **Transaction rollback** - Rejected: Complex with nested transactions
+3. **Recreate database** - Rejected: Too slow for frequent test runs
+4. **Separate test database** - Chosen: Combined with SQL cleanup
+
+### Implementation Details
+
+**Cleanup Process:**
+1. **Disable constraints temporarily:** `SET CONSTRAINTS ALL DEFERRED`
+2. **Query all tables:** From `information_schema.tables`
+3. **Delete in reverse order:** Handle foreign key dependencies
+4. **Reset sequences:** `ALTER SEQUENCE ... RESTART WITH 1`
+
+**Execution Timing:**
+- **AfterSuite:** Full cleanup after all scenarios
+- **Between Scenarios:** Individual scenario cleanup (future enhancement)
+
+**Benefits:**
+- ✅ **Fast execution:** Milliseconds vs seconds for recreation
+- ✅ **Reliable:** Handles schema changes automatically
+- ✅ **Isolated:** Each test gets clean state
+- ✅ **Maintainable:** No dependency on ORM or repositories
 
 ### Temporary Database Approach
 
@@ -638,7 +689,8 @@ func AfterScenario(ctx context.Context, sc *godog.Scenario, err error) (context.
 ## References
 
 - [GORM Documentation](https://gorm.io/)
-- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
+- [PostgreSQL 16 Documentation](https://www.postgresql.org/docs/16/)
+- [PostgreSQL Latest Version](https://www.postgresql.org/)
 - [GORM + PostgreSQL Guide](https://gorm.io/docs/connecting_to_the_database.html#PostgreSQL)
 - [Database Connection Pooling](https://www.alexedwards.net/blog/configuring-sqldb)
 

config.yaml

@@ -55,4 +55,36 @@ telemetry:
     
     # Sampling ratio (0.0 to 1.0, default: 1.0)
     # Only used with traceidratio and parentbased_traceidratio samplers
-    ratio: 1.0
+    ratio: 1.0
+
+# Database configuration (PostgreSQL)
+database:
+  # PostgreSQL host address (default: "localhost")
+  host: "localhost"
+  
+  # PostgreSQL port (default: 5432)
+  port: 5432
+  
+  # PostgreSQL username (default: "postgres")
+  user: "postgres"
+  
+  # PostgreSQL password (default: "postgres")
+  # Change this for production!
+  password: "postgres"
+  
+  # Database name (default: "dance_lessons_coach")
+  name: "dance_lessons_coach"
+  
+  # SSL mode (default: "disable")
+  # Options: "disable", "allow", "prefer", "require", "verify-ca", "verify-full"
+  ssl_mode: "disable"
+  
+  # Maximum number of open connections (default: 25)
+  max_open_conns: 25
+  
+  # Maximum number of idle connections (default: 5)
+  max_idle_conns: 5
+  
+  # Maximum lifetime of connections (default: "1h")
+  # Format: number + unit (s, m, h)
+  conn_max_lifetime: 1h

docker-compose.yml

@@ -0,0 +1,40 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: dance-lessons-coach-postgres
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: dance_lessons_coach
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+  # Application service (for reference)
+  # app:
+  #   build: .
+  #   container_name: dance-lessons-coach-app
+  #   ports:
+  #     - "8080:8080"
+  #   environment:
+  #     - DLC_DATABASE_HOST=postgres
+  #     - DLC_DATABASE_PORT=5432
+  #     - DLC_DATABASE_USER=postgres
+  #     - DLC_DATABASE_PASSWORD=postgres
+  #     - DLC_DATABASE_NAME=dance_lessons_coach
+  #     - DLC_DATABASE_SSL_MODE=disable
+  #   depends_on:
+  #     postgres:
+  #       condition: service_healthy
+  #   restart: unless-stopped
+
+volumes:
+  postgres_data:
+    driver: local

features/user_authentication.feature

@@ -127,4 +127,26 @@ Feature: User Authentication
     And I should receive a valid JWT token
     When I validate the received JWT token
     Then the token should be valid
-    And it should contain the correct user ID
+    And it should contain the correct user ID
+
+  Scenario: Authentication with expired JWT token
+    Given the server is running
+    And a user "expireduser" exists with password "testpass123"
+    When I authenticate with username "expireduser" and password "testpass123"
+    Then the authentication should be successful
+    And I should receive a valid JWT token
+    When I use an expired JWT token for authentication
+    Then the authentication should fail
+    And the response should contain error "invalid_token"
+
+  Scenario: Authentication with JWT token signed with wrong secret
+    Given the server is running
+    When I use a JWT token signed with wrong secret for authentication
+    Then the authentication should fail
+    And the response should contain error "invalid_token"
+
+  Scenario: Authentication with malformed JWT token
+    Given the server is running
+    When I use a malformed JWT token for authentication
+    Then the authentication should fail
+    And the response should contain error "invalid_token"

go.mod

@@ -9,6 +9,7 @@ require (
 	github.com/go-playground/universal-translator v0.18.1
 	github.com/go-playground/validator/v10 v10.30.2
 	github.com/golang-jwt/jwt/v5 v5.3.1
+	github.com/lib/pq v1.12.3
 	github.com/rs/zerolog v1.35.0
 	github.com/spf13/cobra v1.8.0
 	github.com/spf13/viper v1.21.0
@@ -21,6 +22,7 @@ require (
 	go.opentelemetry.io/otel/sdk v1.43.0
 	go.opentelemetry.io/otel/trace v1.43.0
 	golang.org/x/crypto v0.49.0
+	gorm.io/driver/postgres v1.6.0
 	gorm.io/driver/sqlite v1.6.0
 	gorm.io/gorm v1.31.1
 )
@@ -49,6 +51,10 @@ require (
 	github.com/hashicorp/go-memdb v1.3.5 // indirect
 	github.com/hashicorp/golang-lru v1.0.2 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/pgx/v5 v5.6.0 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/josharian/intern v1.0.0 // indirect

go.sum

@@ -81,6 +81,14 @@ github.com/hashicorp/golang-lru v1.0.2 h1:dV3g9Z/unq5DpblPpw+Oqcv4dU/1omnb4Ok8iP
 github.com/hashicorp/golang-lru v1.0.2/go.mod h1:iADmTwqILo4mZ8BN3D2Q6+9jd8WM5uGBxy+E8yxSoD4=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.6.0 h1:SWJzexBzPL5jb0GEsrPMLIsi/3jOo7RHlzTjcAeDrPY=
+github.com/jackc/pgx/v5 v5.6.0/go.mod h1:DNZ/vlrUnhWCoFGxHAG8U2ljioxukquj7utPDgtQdTw=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
 github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
 github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
@@ -97,6 +105,8 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/lib/pq v1.12.3 h1:tTWxr2YLKwIvK90ZXEw8GP7UFHtcbTtty8zsI+YjrfQ=
+github.com/lib/pq v1.12.3/go.mod h1:/p+8NSbOcwzAEI7wiMXFlgydTwcgTr3OSKMsD2BitpA=
 github.com/mailru/easyjson v0.0.0-20190614124828-94de47d64c63/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
 github.com/mailru/easyjson v0.0.0-20190626092158-b2ccc519800e/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
 github.com/mailru/easyjson v0.7.6 h1:8yTIVnZgCoiM1TgqoeTl+LfU5Jg6/xL3QhGQnimLYnA=
@@ -139,6 +149,7 @@ github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSS
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
@@ -220,6 +231,8 @@ gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C
 gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gorm.io/driver/postgres v1.6.0 h1:2dxzU8xJ+ivvqTRph34QX+WrRaJlmfyPqXmoGVjMBa4=
+gorm.io/driver/postgres v1.6.0/go.mod h1:vUw0mrGgrTK+uPHEhAdV4sfFELrByKVGnaVRkXDhtWo=
 gorm.io/driver/sqlite v1.6.0 h1:WHRRrIiulaPiPFmDcod6prc4l2VGVWHz80KspNsxSfQ=
 gorm.io/driver/sqlite v1.6.0/go.mod h1:AO9V1qIQddBESngQUKWL9yoH93HIeA1X6V633rBwyT8=
 gorm.io/gorm v1.31.1 h1:7CA8FTFz/gRfgqgpeKIBcervUn3xSyPUmr6B2WXJ7kg=

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)
+	// Greet steps
-	ctx.Step(`^I request the default greeting$`, sc.iRequestTheDefaultGreeting)
+	ctx.Step(`^I request a greeting for "([^"]*)"$`, sc.greetSteps.iRequestAGreetingFor)
-	ctx.Step(`^I request the health endpoint$`, sc.iRequestTheHealthEndpoint)
+	ctx.Step(`^I request the default greeting$`, sc.greetSteps.iRequestTheDefaultGreeting)
-	ctx.Step(`^the response should be "{\\"([^"]*)":\\"([^"]*)"}"$`, sc.theResponseShouldBe)
+	ctx.Step(`^I send a POST request to v2 greet with name "([^"]*)"$`, sc.greetSteps.iSendPOSTRequestToV2GreetWithName)
-	ctx.Step(`^the server is running$`, sc.theServerIsRunning)
+	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.theServerIsRunningWithV2Enabled)
+	ctx.Step(`^the server is running with v2 enabled$`, sc.greetSteps.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)
 
-	// User Authentication Steps
+	// Health steps
-	ctx.Step(`^a user "([^"]*)" exists with password "([^"]*)"$`, sc.aUserExistsWithPassword)
+	ctx.Step(`^I request the health endpoint$`, sc.healthSteps.iRequestTheHealthEndpoint)
-	ctx.Step(`^I authenticate with username "([^"]*)" and password "([^"]*)"$`, sc.iAuthenticateWithUsernameAndPassword)
+	ctx.Step(`^the server is running$`, sc.healthSteps.theServerIsRunning)
-	ctx.Step(`^the authentication should be successful$`, sc.theAuthenticationShouldBeSuccessful)
+
-	ctx.Step(`^I should receive a valid JWT token$`, sc.iShouldReceiveAValidJWTToken)
+	// Auth steps
-	ctx.Step(`^the authentication should fail$`, sc.theAuthenticationShouldFail)
+	ctx.Step(`^a user "([^"]*)" exists with password "([^"]*)"$`, sc.authSteps.aUserExistsWithPassword)
-	ctx.Step(`^I authenticate as admin with master password "([^"]*)"$`, sc.iAuthenticateAsAdminWithMasterPassword)
+	ctx.Step(`^I authenticate with username "([^"]*)" and password "([^"]*)"$`, sc.authSteps.iAuthenticateWithUsernameAndPassword)
-	ctx.Step(`^the token should contain admin claims$`, sc.theTokenShouldContainAdminClaims)
+	ctx.Step(`^the authentication should be successful$`, sc.authSteps.theAuthenticationShouldBeSuccessful)
-	ctx.Step(`^I register a new user "([^"]*)" with password "([^"]*)"$`, sc.iRegisterANewUserWithPassword)
+	ctx.Step(`^I should receive a valid JWT token$`, sc.authSteps.iShouldReceiveAValidJWTToken)
-	ctx.Step(`^the registration should be successful$`, sc.theRegistrationShouldBeSuccessful)
+	ctx.Step(`^the authentication should fail$`, sc.authSteps.theAuthenticationShouldFail)
-	ctx.Step(`^I should be able to authenticate with the new credentials$`, sc.iShouldBeAbleToAuthenticateWithTheNewCredentials)
+	ctx.Step(`^I authenticate as admin with master password "([^"]*)"$`, sc.authSteps.iAuthenticateAsAdminWithMasterPassword)
-	ctx.Step(`^I am authenticated as admin$`, sc.iAmAuthenticatedAsAdmin)
+	ctx.Step(`^the token should contain admin claims$`, sc.authSteps.theTokenShouldContainAdminClaims)
-	ctx.Step(`^I request password reset for user "([^"]*)"$`, sc.iRequestPasswordResetForUser)
+	ctx.Step(`^I register a new user "([^"]*)" with password "([^"]*)"$`, sc.authSteps.iRegisterANewUserWithPassword)
-	ctx.Step(`^the password reset should be allowed$`, sc.thePasswordResetShouldBeAllowed)
+	ctx.Step(`^the registration should be successful$`, sc.authSteps.theRegistrationShouldBeSuccessful)
-	ctx.Step(`^the user should be flagged for password reset$`, sc.theUserShouldBeFlaggedForPasswordReset)
+	ctx.Step(`^I should be able to authenticate with the new credentials$`, sc.authSteps.iShouldBeAbleToAuthenticateWithTheNewCredentials)
-	ctx.Step(`^I complete password reset for "([^"]*)" with new password "([^"]*)"$`, sc.iCompletePasswordResetForWithNewPassword)
+	ctx.Step(`^I am authenticated as admin$`, sc.authSteps.iAmAuthenticatedAsAdmin)
-	ctx.Step(`^I should be able to authenticate with the new password$`, sc.iShouldBeAbleToAuthenticateWithTheNewPassword)
+	ctx.Step(`^I request password reset for user "([^"]*)"$`, sc.authSteps.iRequestPasswordResetForUser)
-	ctx.Step(`^a user "([^"]*)" exists and is flagged for password reset$`, sc.aUserExistsAndIsFlaggedForPasswordReset)
+	ctx.Step(`^the password reset should be allowed$`, sc.authSteps.thePasswordResetShouldBeAllowed)
-	ctx.Step(`^the password reset should be successful$`, sc.thePasswordResetShouldBeSuccessful)
+	ctx.Step(`^the user should be flagged for password reset$`, sc.authSteps.theUserShouldBeFlaggedForPasswordReset)
-	ctx.Step(`^the password reset should fail$`, sc.thePasswordResetShouldFail)
+	ctx.Step(`^I complete password reset for "([^"]*)" with new password "([^"]*)"$`, sc.authSteps.iCompletePasswordResetForWithNewPassword)
-	ctx.Step(`^the status code should be (\d+)$`, sc.theStatusCodeShouldBe)
+	ctx.Step(`^I should be able to authenticate with the new password$`, sc.authSteps.iShouldBeAbleToAuthenticateWithTheNewPassword)
-	ctx.Step(`^I validate the received JWT token$`, sc.iValidateTheReceivedJWTToken)
+	ctx.Step(`^a user "([^"]*)" exists and is flagged for password reset$`, sc.authSteps.aUserExistsAndIsFlaggedForPasswordReset)
-	ctx.Step(`^the token should be valid$`, sc.theTokenShouldBeValid)
+	ctx.Step(`^the password reset should be successful$`, sc.authSteps.thePasswordResetShouldBeSuccessful)
-	ctx.Step(`^it should contain the correct user ID$`, sc.itShouldContainTheCorrectUserID)
+	ctx.Step(`^the password reset should fail$`, sc.authSteps.thePasswordResetShouldFail)
-	ctx.Step(`^I should receive a different JWT token$`, sc.iShouldReceiveADifferentJWTToken)
+	ctx.Step(`^the registration should fail$`, sc.authSteps.theRegistrationShouldFail)
-	ctx.Step(`^I authenticate with username "([^"]*)" and password "([^"]*)" again$`, sc.iAuthenticateWithUsernameAndPasswordAgain)
+	ctx.Step(`^the authentication should fail with validation error$`, sc.authSteps.theAuthenticationShouldFailWithValidationError)
-	ctx.Step(`^the registration should fail$`, sc.theRegistrationShouldFail)
+
-	ctx.Step(`^the authentication should fail with validation error$`, sc.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)
-func (sc *StepContext) iRequestAGreetingFor(name string) error {
+	ctx.Step(`^I use a malformed JWT token for authentication$`, sc.authSteps.iUseAMalformedJWTTokenForAuthentication)
-	return sc.client.Request("GET", fmt.Sprintf("/api/v1/greet/%s", name), nil)
+
-}
+	// JWT validation steps
-
+	ctx.Step(`^I validate the received JWT token$`, sc.authSteps.iValidateTheReceivedJWTToken)
-func (sc *StepContext) iRequestTheDefaultGreeting() error {
+	ctx.Step(`^the token should be valid$`, sc.authSteps.theTokenShouldBeValid)
-	return sc.client.Request("GET", "/api/v1/greet/", nil)
+	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)
-func (sc *StepContext) iRequestTheHealthEndpoint() error {
+
-	return sc.client.Request("GET", "/api/health", nil)
+	// Common steps
-}
+	ctx.Step(`^the response should be "{\"([^"]*)\":\"([^"]*)"}"$`, sc.commonSteps.theResponseShouldBe)
-
+	ctx.Step(`^the response should contain error "([^"]*)"$`, sc.commonSteps.theResponseShouldContainError)
-func (sc *StepContext) theResponseShouldBe(arg1, arg2 string) error {
+	ctx.Step(`^the status code should be (\d+)$`, sc.commonSteps.theStatusCodeShouldBe)
-	// 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
 }

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
+	// Create user repository using PostgreSQL
-	dbPath := "file::memory:?cache=shared"
+	repo, err := user.NewPostgresRepository(cfg)
-
-	// Create user repository
-	repo, err := user.NewSQLiteRepository(dbPath, 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)
+}

scripts/run-bdd-tests.sh

@@ -8,6 +8,56 @@ set -e
 echo "🧪 Running BDD Tests..."
 cd /Users/gabrielradureau/Work/Vibe/DanceLessonsCoach
 
+# Check if PostgreSQL container is running, start it if not
+echo "🐋 Checking PostgreSQL container..."
+if ! docker ps --format '{{.Names}}' | grep -q "^dance-lessons-coach-postgres$"; then
+    echo "🐋 Starting PostgreSQL container..."
+    docker compose up -d postgres
+    
+    # Wait for PostgreSQL to be ready
+    echo "⏳ Waiting for PostgreSQL to be ready..."
+    max_attempts=30
+    attempt=0
+    while [ $attempt -lt $max_attempts ]; do
+        if docker exec dance-lessons-coach-postgres pg_isready -U postgres 2>/dev/null; then
+            echo "✅ PostgreSQL is ready!"
+            break
+        fi
+        attempt=$((attempt + 1))
+        sleep 1
+    done
+    
+    if [ $attempt -eq $max_attempts ]; then
+        echo "❌ PostgreSQL failed to start"
+        exit 1
+    fi
+    
+    # Create BDD test database (separate from development database)
+    echo "📦 Creating BDD test database..."
+    if docker exec dance-lessons-coach-postgres createdb -U postgres dance_lessons_coach_bdd_test; then
+        echo "✅ BDD test database created successfully!"
+    else
+        echo "❌ Failed to create BDD test database"
+        exit 1
+    fi
+else
+    echo "✅ PostgreSQL container is already running"
+    
+    # Check if BDD test database exists, create if not
+    echo "📦 Checking BDD test database..."
+    if docker exec dance-lessons-coach-postgres psql -U postgres -lqt | cut -d \| -f 1 | grep -qw "dance_lessons_coach_bdd_test"; then
+        echo "✅ BDD test database already exists"
+    else
+        echo "📦 Creating BDD test database..."
+        if docker exec dance-lessons-coach-postgres createdb -U postgres dance_lessons_coach_bdd_test; then
+            echo "✅ BDD test database created successfully!"
+        else
+            echo "❌ Failed to create BDD test database"
+            exit 1
+        fi
+    fi
+fi
+
 # Run the BDD tests
 test_output=$(go test ./features/... -v 2>&1)
 test_exit_code=$?