Merged in feature/eula.part1 (pull request #206)

eula support * eula support * docs
2026-01-22 18:17:27 +00:00
parent c10fa98d0a
commit 63c12a2f44
38 changed files with 15646 additions and 230 deletions
@@ -188,4 +188,72 @@ This ensures stable execution in resource-constrained environments like CI.
 Some tests may use build tags to control execution:
 - Tests requiring external services (like Permit.io PDP) may be tagged
 - Use `-tags=tagname` with `go test` commands to include tagged tests
- CI typically excludes integration tests that require external dependencies
+- CI typically excludes integration tests that require external dependencies
+
+## Test User Header Injection (DISABLE_AUTH Mode)
+
+When running the service with `DISABLE_AUTH=true`, a special middleware (`TestUserMiddleware`) activates that allows injecting user identity via HTTP headers. This enables testing of user-authenticated endpoints without requiring real JWT authentication.
+
+### How It Works
+
+The `TestUserMiddleware` (located in `internal/cognitoauth/test_middleware.go`):
+1. Only activates when `DISABLE_AUTH=true` environment variable is set
+2. Checks for the `X-Test-User-Subject` header on each request
+3. If present, injects user identity into the request context
+4. Handlers can then retrieve user info via `GetUserSubject()` and `GetUserInfo()`
+
+### Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `X-Test-User-Subject` | Yes | The user's subject ID (Cognito sub claim) |
+| `X-Test-User-Email` | No | The user's email (defaults to `<subject>@test.local`) |
+
+### Example Usage
+
+```bash
+# Start the service with DISABLE_AUTH=true (default for local compose)
+task compose:refresh
+
+# Call user-authenticated endpoint with test user headers
+curl -X GET http://localhost:8080/eula/status \
+  -H "X-Test-User-Subject: test-user-123" \
+  -H "X-Test-User-Email: testuser@example.com"
+
+# User agrees to EULA
+curl -X POST http://localhost:8080/eula/agree \
+  -H "X-Test-User-Subject: test-user-123" \
+  -H "X-Test-User-Email: testuser@example.com"
+```
+
+### Integration Test Scripts
+
+Three integration test scripts are available for EULA functionality:
+
+1. **Complete EULA Tests** (`test/text_eula_all_integration_test.sh`) **(Recommended)**
+   - Comprehensive test suite combining admin and user EULA testing
+   - Tests full EULA lifecycle: version management, user agreements, version upgrades, compliance
+   - 24 test steps across 9 phases
+   - Uses both admin endpoints (system user) and user endpoints (header injection)
+
+2. **Admin EULA Tests** (`test/text_eula_admin_integration_test.sh`)
+   - Tests admin-only endpoints: create, activate, update, list EULA versions
+   - Uses system user (no headers needed with DISABLE_AUTH=true)
+
+3. **User EULA Tests** (`test/text_eula_user_integration_test.sh`)
+   - Tests user-authenticated endpoints: `/eula/status`, `/eula/agree`
+   - Uses `X-Test-User-Subject` header to inject test user identity
+   - Tests multiple users and idempotency
+
+```bash
+# Run complete EULA integration tests (recommended)
+./test/text_eula_all_integration_test.sh http://localhost:8080
+
+# Run individual test suites
+./test/text_eula_admin_integration_test.sh http://localhost:8080
+./test/text_eula_user_integration_test.sh http://localhost:8080
+```
+
+### Security Note
+
+The `TestUserMiddleware` is **only active when `DISABLE_AUTH=true`**. In production environments where `DISABLE_AUTH` is not set or is `false`, this middleware does nothing and the headers are ignored. The real authentication middleware handles all requests normally.