[AZ-PENDING-1] [AZ-PENDING-2] Step 4 close-out: verification + docs

Phase 6 smoke (Docker, _docs/04_refactoring/01-testability-refactoring/
smoke-compose.yml):
  - Annotations app boots clean under ASPNETCORE_ENVIRONMENT=E2ETest.
  - /health 200 OK; /annotations with bearer returns 401 with the
    JWT library's own malformed-token rejection.
  - 0 IDX20108 occurrences in logs (C01 verified).
  - 0 IPAddress.Parse FormatException occurrences; FailsafeProducer
    reaches the broker via Docker DNS (C02 verified).
  - Full smoke report in verification.md.

Phase 7 docs:
  - architecture.md: retire Open Risks §6 (testability blocker
    resolved). Update the constraints block to describe the
    ASPNETCORE_ENVIRONMENT-gated RequireHttps behavior.
  - components/06_platform/description.md: one-liner on JwtExtensions
    JWKS gating.
  - components/02_annotations-realtime-sync/description.md: one-liner
    on FailsafeProducer host resolution accepting literal IP or DNS.
  - tests/test-data.md: refresh the JWKS URL configuration section to
    point at the resolved implementation instead of the open risk.

Task housekeeping:
  - _docs/02_tasks/todo/01_*.md -> done/
  - _docs/02_tasks/todo/02_*.md -> done/
  - _docs/_autodev_state.md: advance to Step 5 (Refactor Backlog Triage).

Tracker IDs remain placeholders pending Atlassian MCP availability —
real IDs to be assigned per
_docs/_process_leftovers/2026-05-14_testability-tracker.md.

Co-authored-by: Cursor <cursoragent@cursor.com>

_docs/02_document/architecture.md

@@ -81,7 +81,7 @@ Azaion.Annotations is a single .NET 10 ASP.NET Core service in the Azaion suite
 
 **Key constraints (evidenced in code/config)**:
 - `DATABASE_URL` is **required** at startup — `ConfigurationResolver.ResolveRequiredOrThrow` throws if not set. The string is auto-converted from `postgresql://user:pass@host:port/db` URI form to Linq2DB's `Host=…;Username=…` form by `Program.ConvertPostgresUrl`.
-- JWT verification is **required** at startup — `JWT_ISSUER`, `JWT_AUDIENCE`, and `JWT_JWKS_URL` are all resolved by `ConfigurationResolver.ResolveRequiredOrThrow`. There is no insecure fallback. The JWKS URL must be HTTPS (`HttpDocumentRetriever { RequireHttps = true }`).
+- JWT verification is **required** at startup — `JWT_ISSUER`, `JWT_AUDIENCE`, and `JWT_JWKS_URL` are all resolved by `ConfigurationResolver.ResolveRequiredOrThrow`. There is no insecure fallback. The JWKS URL is fetched with `HttpDocumentRetriever`, whose `RequireHttps` flag is gated on `ASPNETCORE_ENVIRONMENT`: HTTPS is required for any value other than `E2ETest` (Development, Staging, Production, and unset all enforce HTTPS); only `E2ETest` relaxes the flag to support the in-cluster mock issuer documented in `tests/environment.md`. The relaxation is gated in source (`src/Auth/JwtExtensions.cs`), not in config.
 - Default directory roots are `/data/{videos,images,labels,results,thumbnails,gps_sat,gps_route}` (migrator `directory_settings` defaults) → operator must mount or override at the DB level via `PUT /settings/directories`.
 - CORS is **environment-gated**: `CorsConfigurationValidator.EnsureSafeForEnvironment` refuses to start in `Production` when `CorsConfig:AllowedOrigins` is empty unless `CorsConfig:AllowAnyOrigin=true` is set explicitly. ADR-006 was retired together with the wide-open default.
 
@@ -374,7 +374,7 @@ These are residual risks that still need attention from later autodev steps (Tes
 3. **`UserId` body field vs JWT `NameIdentifier`** drift (suite spec lists `UserId` on `POST /annotations`; code uses JWT subject). Reconcile in the suite spec.
 4. **No automated tests**: addressed by autodev Phase A Steps 3–7 (Test Spec → Implement Tests → Run Tests).
 5. **`FailsafeProducer.cs:138` swallows `IOException` on image read silently** (`catch { }`). Direct `coderule.mdc` violation. Symptom in product: a missing or unreadable image yields a stream message with `image = null` and no log/metric — the gap is invisible to operators. Track on Refactor Backlog (RB-05).
-6. **JWKS HTTPS-only retrieval blocks containerised test harnesses** that would otherwise serve a static JWKS over plain HTTP. Tests must either run a TLS-terminating sidecar in the test compose stack or rely on test-only configuration that relaxes `RequireHttps`. Not a production risk; a Step 4 (Code Testability Revision) item.
+6. ~~**JWKS HTTPS-only retrieval blocks containerised test harnesses**~~ — **RESOLVED 2026-05-14** by Step 4 (Code Testability Revision). `JwtExtensions.AddJwtAuth` now gates `HttpDocumentRetriever.RequireHttps` on `ASPNETCORE_ENVIRONMENT == "E2ETest"` (case-insensitive). Production / Staging / Development / unset all retain HTTPS-required behavior; only the `E2ETest` value relaxes the flag. Verified via the smoke harness in `_docs/04_refactoring/01-testability-refactoring/verification.md`. See `_docs/04_refactoring/01-testability-refactoring/testability_changes_summary.md` (item C01) for the full change log.
 
 ## Refactor Backlog
 

_docs/02_document/components/02_annotations-realtime-sync/description.md

@@ -13,7 +13,7 @@
 ## 2. Internal interfaces
 
 - `AnnotationEventService` — in-process `Channel<AnnotationEventDto>`; `PublishAsync` / `Reader`.
-- `FailsafeProducer` + `RabbitMqConfig` — stream client, MessagePack payloads, drains `annotations_queue_records`.
+- `FailsafeProducer` + `RabbitMqConfig` — stream client, MessagePack payloads, drains `annotations_queue_records`. `RABBITMQ_HOST` accepts both literal IPv4/IPv6 (used as-is via `IPAddress.TryParse`) and DNS hostnames (resolved through `Dns.GetHostAddressesAsync` — required for Docker/Kubernetes service-name connectivity).
 - **HTTP:** `AnnotationsController.Events` — `text/event-stream` subscription (same controller file as REST component; **doc ownership** here for SSE).
 
 ## 3. External API / integration

_docs/02_document/components/06_platform/description.md

@@ -15,7 +15,7 @@
 - `src/Enums/*`
 - `src/Database/*` (`AppDataConnection`, `DatabaseMigrator`, entities)
 - `ErrorHandlingMiddleware`, `PathResolver`, `PaginatedResponse`, `ErrorResponse`, `GlobalUsings.cs`
-- `JwtExtensions` (JWKS verifier), `ConfigurationResolver`, `CorsConfigurationValidator`
+- `JwtExtensions` (JWKS verifier; `HttpDocumentRetriever.RequireHttps` is gated on `ASPNETCORE_ENVIRONMENT` — HTTPS-required for every value except `E2ETest`), `ConfigurationResolver`, `CorsConfigurationValidator`
 - `Program.cs`
 
 ## 3. External API

_docs/02_document/tests/test-data.md

@@ -90,7 +90,7 @@ The generated data still satisfies Phase 3 quantifiability: every generated inpu
 Annotations is verifier-only — there is no `/auth/login` to call from a test. The harness reproduces the production model in miniature:
 
 1. **Key pair** — a fresh ES256 key pair is generated when the test stack starts (`docker compose up`). The private key is mounted into the runner container; the public key is mounted into a tiny **mock issuer** sidecar that serves `/.well-known/jwks.json` over HTTP **inside the docker-compose network**.
-2. **JWKS URL configuration** — the SUT is started with `JWT_ISSUER=https://e2e-issuer.test`, `JWT_AUDIENCE=annotations-e2e`, and `JWT_JWKS_URL=http://e2e-issuer:8080/.well-known/jwks.json`. The HTTPS-only constraint of `HttpDocumentRetriever { RequireHttps = true }` is relaxed for tests by either (a) overriding `RequireHttps=false` via test-only configuration, or (b) running a TLS-terminating proxy in front of the issuer. Option (a) is preferred for simplicity; the relaxation is gated on `ASPNETCORE_ENVIRONMENT=E2ETest` and never applied in production builds. (This is the testability item flagged in `architecture.md` Open Risks §6.)
+2. **JWKS URL configuration** — the SUT is started with `JWT_ISSUER=https://e2e-issuer.test`, `JWT_AUDIENCE=annotations-e2e`, and `JWT_JWKS_URL=http://e2e-issuer:8080/.well-known/jwks.json`. The HTTPS-only constraint of `HttpDocumentRetriever.RequireHttps` is relaxed in source: `JwtExtensions.AddJwtAuth` sets `RequireHttps = false` if and only if `ASPNETCORE_ENVIRONMENT == "E2ETest"` (case-insensitive). Any other value — including unset, `Development`, `Staging`, `Production` — keeps HTTPS required. This is the resolved form of `architecture.md` Open Risks §6 (see also `_docs/04_refactoring/01-testability-refactoring/testability_changes_summary.md` item C01).
 3. **Token minting** — the runner exposes a per-test helper `mintToken(claim: "ANN" | "DATASET" | "ADM", overrides?)` that builds an ES256 JWT from the in-process private key with the configured `iss`/`aud`, `exp = now + 5m`, a per-role deterministic `sub` GUID, and the requested policy claim. `overrides` lets a test produce expired / wrong-iss / wrong-aud / forged-`alg=HS256` variants for the security suite.
 4. **No persisted users** — there is no `users` table in this service. Each test mints exactly the token it needs.