feat: Implementierung des Checkout-Logins mit E-Mail/Username-Support

docs/prp/13-backend-authentication.md

@@ -2,9 +2,61 @@
 
 ## Overview
 
-This document outlines the authentication requirements and implementation details for the Fotospiel tenant backend. The system uses OAuth2 with PKCE (Proof Key for Code Exchange) for secure authorization, providing tenant-specific access tokens for API operations.
+This document outlines the authentication requirements and implementation details for the Fotospiel tenant backend. The system uses OAuth2 with PKCE (Proof Key for Code Exchange) for secure authorization, providing tenant-specific access tokens for API operations. Additionally, session-based authentication is used for web interfaces like the checkout wizard, supporting both email and username login.
 
-## Authentication Flow
+## Session-Based Authentication (Web/Checkout)
+
+### Checkout Login Flow
+- **Endpoint**: `POST /checkout/login`
+- **Method**: POST
+- **Content-Type**: `application/json`
+- **Parameters**:
+  - `identifier`: Email or username (required, string)
+  - `password`: User's password (required, string)
+  - `remember`: Remember me flag (optional, boolean)
+  - `locale`: Language locale (optional, string, e.g., 'de')
+
+**Authentication Logic**:
+- Validate input using Laravel Validator.
+- Search for user by email or username using Eloquent query: `User::where('email', $identifier)->orWhere('username', $identifier)->first()`.
+- Verify password with `Hash::check()`.
+- If valid, log in user with `Auth::login($user, $remember)` and regenerate session.
+- Set `pending_purchase = true` if a package is selected (from session) and not already set, wrapped in DB transaction.
+- Return JSON response with user data for AJAX handling in frontend.
+
+**Response** (JSON, 200 OK):
+```json
+{
+  "user": {
+    "id": 1,
+    "email": "user@example.com",
+    "name": "John Doe",
+    "pending_purchase": true
+  },
+  "message": "Login erfolgreich"
+}
+```
+
+**Error Response** (JSON, 422 Unprocessable Entity):
+```json
+{
+  "errors": {
+    "identifier": ["Ungültige Anmeldedaten."]
+  }
+}
+```
+
+**Security**:
+- CSRF protection via `web` middleware.
+- Rate limiting recommended (add `throttle:6,1` middleware).
+- Password hashing with Laravel's `Hash` facade.
+- Session regeneration after login to prevent fixation attacks.
+
+### Integration with Standard Laravel Auth
+- Leverages `AuthenticatedSessionController` for core logic where possible, but custom handling for identifier flexibility and checkout context.
+- Compatible with Inertia.js for SPA responses.
+
+## OAuth2 Authentication (API)
 
 ### 1. Authorization Request
 - **Endpoint**: `GET /api/v1/oauth/authorize`
@@ -114,6 +166,7 @@ CREATE TABLE oauth_clients (
   updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
   CONSTRAINT oauth_clients_tenant_id_foreign FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE SET NULL
 );
+```
 ```sql
 CREATE TABLE oauth_clients (
   id VARCHAR(255) PRIMARY KEY,
@@ -159,6 +212,7 @@ CREATE TABLE refresh_tokens (
   revoked_at TIMESTAMP NULL,
   created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
 );
+```
 ```sql
 CREATE TABLE refresh_tokens (
   id VARCHAR(255) PRIMARY KEY,
@@ -201,6 +255,7 @@ CREATE TABLE tenant_tokens (
 | `/oauth/authorize` | GET | Authorization request | None |
 | `/oauth/token` | POST | Token exchange/refresh | None |
 | `/api/v1/tenant/me` | GET | Validate token | Bearer Token |
+| `/checkout/login` | POST | Session login for checkout (email/username) | None |
 
 ### Protected Endpoints
 All tenant API endpoints require `Authorization: Bearer {access_token}` header.
@@ -274,6 +329,13 @@ VITE_OAUTH_CLIENT_ID=tenant-admin-app
   "error": "insufficient_scope",
   "error_description": "Scope tenant:write required"
 }
+
+// 422 Unprocessable Entity (Checkout Login)
+{
+  "errors": {
+    "identifier": ["Ungültige Anmeldedaten."]
+  }
+}
 ```
 
 ## Implementation Notes
@@ -296,12 +358,14 @@ VITE_OAUTH_CLIENT_ID=tenant-admin-app
 - Authorization requests: 10/minute per IP
 - Token exchanges: 5/minute per IP
 - Token validation: 100/minute per tenant
+- Checkout login: 6/minute per IP (add throttle middleware)
 
 ### 5. Logging and Monitoring
 - Log all authentication attempts (success/failure)
 - Monitor token usage patterns
 - Alert on unusual activity (multiple failed attempts, token anomalies)
 - Track refresh token usage for security analysis
+- Log checkout login attempts with identifier type (email/username)
 
 ### 6. Database Cleanup
 - Cron job to remove expired authorization codes (daily)
@@ -315,18 +379,21 @@ VITE_OAUTH_CLIENT_ID=tenant-admin-app
 - State parameter security
 - Token signing and verification
 - Scope validation middleware
+- Checkout login with email and username
 
 ### Integration Tests
 - Complete OAuth2 flow (authorize → token → validate)
 - Token refresh cycle
 - Error scenarios (invalid code, expired tokens, state mismatch)
 - Concurrent access testing
+- Checkout login flow with pending_purchase
 
 ### Security Tests
 - CSRF protection validation
 - PKCE bypass attempts
 - Token replay attacks
 - Rate limiting enforcement
+- Username/email ambiguity handling
 
 ## Deployment Considerations
 
@@ -345,11 +412,6 @@ VITE_OAUTH_CLIENT_ID=tenant-admin-app
 - Monitor token expiry patterns
 - Alert on PKCE validation failures
 - Log all security-related events
+- Monitor checkout login success rates and identifier usage
 
-This implementation provides secure, scalable authentication for the Fotospiel tenant system, following OAuth2 best practices with PKCE for public clients.
-
-
-
-
-
-
+This implementation provides secure, scalable authentication for the Fotospiel tenant system, following OAuth2 best practices with PKCE for public clients and flexible session auth for web flows.