satellite-provider/_docs/02_tasks/done/AZ-487_jwt_validation_baseline.md

JWT validation baseline (HS256, JWT_SECRET, all endpoints)

Task: AZ-487_jwt_validation_baseline Name: JWT validation baseline Description: Add HS256 JWT validation to satellite-provider so every existing endpoint requires a valid token issued by the centralized Admin API; align with the suite-wide auth contract documented in suite/_docs/10_auth.md. Complexity: 2 points Dependencies: None (consumes the suite-level JWT contract suite/_docs/10_auth.md; no in-repo task dependency) Component: WebApi (SatelliteProvider.Api) Tracker: AZ-487 Epic: none (cross-cutting hardening; AZ-488 hard-depends on this)

Problem

Satellite-provider currently has zero authentication — every endpoint is open. The suite-level auth design (suite/_docs/10_auth.md) requires every .NET API instance in the suite to validate JWTs locally using a shared HMAC key supplied via the JWT_SECRET env var. The Security Audit (Step 14, cycle 1, _docs/05_security/owasp_review.md) flagged the absence of authentication as the largest hardening gap blocking public-network exposure. The next planned PBI (AZ-488 — UAV upload endpoint) cannot ship without the auth baseline because UAV uploads must carry an authenticated user identity.

Outcome

• Every existing HTTP endpoint (except possibly Swagger UI in non-Production) returns 401 Unauthorized when the request has no Authorization: Bearer … header, an expired token, or a token whose HMAC signature does not verify against the JWT_SECRET env var.
• Authenticated requests reach the existing handlers unchanged — no behavioral change for valid-token callers.
• A request's user identity is exposed to handlers via the standard HttpContext.User claims principal (sub, email, role, permissions[] per the suite contract).
• Swagger UI accepts a Bearer token via the standard "Authorize" button so manual testing keeps working.
• The JWT_SECRET env var is documented in appsettings.Development.json (with a clearly-fake dev value), docker-compose.yml, and (eventually) the deployment scripts.
• Existing 213 unit + 5 smoke tests continue to pass after test setup is updated to attach a valid dev token.

Scope

Included

• New ServiceCollection extension SatelliteProvider.Api.Authentication.AuthenticationServiceCollectionExtensions.AddSatelliteJwt(this IServiceCollection, IConfiguration):
  • Adds Microsoft.AspNetCore.Authentication.JwtBearer (use the same minor version as the existing Microsoft.AspNetCore.OpenApi package — currently 8.0.x; if a security upgrade is happening alongside, pin both consistently).
  • Configures AddAuthentication(JwtBearerDefaults.AuthenticationScheme).AddJwtBearer(options => …) with TokenValidationParameters:
    • ValidateIssuerSigningKey = true, IssuerSigningKey = SymmetricSecurityKey(Encoding.UTF8.GetBytes(JWT_SECRET))
    • ValidateLifetime = true, ClockSkew = TimeSpan.FromSeconds(30) (match suite default; document the choice in code)
    • ValidateIssuer = false, ValidateAudience = false (per suite doc — issuer/audience semantics are not specified yet)
    • RequireSignedTokens = true, RequireExpirationTime = true
  • Throws on startup if JWT_SECRET is missing or shorter than 32 bytes (HMAC-SHA256 minimum-secure key size).
• New ServiceCollection extension call wired into Program.cs: builder.Services.AddSatelliteJwt(builder.Configuration); followed by builder.Services.AddAuthorization(); and the matching app.UseAuthentication(); app.UseAuthorization(); middleware ordering (after UseCors, before endpoint routing).
• .RequireAuthorization() applied to every existing MapGet/MapPost in Program.cs:
  • GET /tiles/{z}/{x}/{y} (ServeTile)
  • GET /api/satellite/tiles/latlon (GetTileByLatLon)
  • GET /api/satellite/tiles/mgrs (GetSatelliteTilesByMgrs)
  • POST /api/satellite/upload (UploadImage — currently 501 stub)
  • POST /api/satellite/request (RequestRegion)
  • GET /api/satellite/region/{id} (GetRegionStatus)
  • POST /api/satellite/route (CreateRoute)
  • GET /api/satellite/route/{id} (GetRoute)
• Program.cs Swagger configuration extended with a SecurityDefinition("Bearer", ...) and a global SecurityRequirement so the "Authorize" button appears in Swagger UI.
• appsettings.json and appsettings.Development.json: add Jwt:Secret configuration key reading JWT_SECRET via the standard ASP.NET Core env-var binding. The dev file ships a 32+ byte placeholder secret clearly marked DEV-ONLY-DO-NOT-USE-IN-PROD.
• docker-compose.yml: add JWT_SECRET to the api service's environment block, sourcing from the host env (or a .env entry the operator supplies).
• .env.example (create if missing): include JWT_SECRET= line with comment.
• Test infrastructure update:
  • Add a small test helper SatelliteProvider.Tests.TestUtilities.JwtTokenFactory (or reuse if a similar one exists) that signs a valid dev token using the same secret used by the integration test environment.
  • Update scripts/run-tests.sh (or the relevant test setup) to ensure the integration test container starts with JWT_SECRET set and the test runner attaches a Bearer token to every request.
  • Update existing smoke tests' HTTP request setup to attach the test token by default.
• New unit tests:
  • AuthenticationServiceCollectionExtensionsTests: AddSatelliteJwt_RegistersJwtBearerScheme, AddSatelliteJwt_ThrowsOnMissingSecret, AddSatelliteJwt_ThrowsOnShortSecret.
  • Token factory: JwtTokenFactory_ProducesTokenAcceptedByValidationParameters.
• New integration tests:
  • JwtIntegrationTests.AnonymousRequest_To_AnyEndpoint_Returns401
  • JwtIntegrationTests.ExpiredToken_Returns401
  • JwtIntegrationTests.InvalidSignature_Returns401
  • JwtIntegrationTests.ValidToken_Returns200_OnHealthyEndpoint
• Documentation:
  • Update _docs/02_document/architecture.md § Architecture Vision to add an "Authentication & authorization" sub-section noting that satellite-provider validates JWTs issued by the centralized Admin API per the suite-level auth contract.
  • Update _docs/02_document/components/01_web_api/description.md to describe the JWT middleware ordering and where .RequireAuthorization() is applied.
  • Update _docs/02_document/modules/api_program.md to reflect the new middleware chain.
  • Reference (do not duplicate) suite/_docs/10_auth.md from this task spec and from the WebApi component description.

Excluded

• GET /users/me and PUT /users/me endpoints — explicitly not shipped (decision recorded in task discussion: nothing depends on them, the suite-level "hosted on every .NET API instance" policy is over-specified for satellite-provider).
• Permission-claim enforcement on the existing endpoints — they only require any valid token in this PBI. Per-endpoint permission checks land later (AZ-488 enforces permissions claim contains GPS for the upload endpoint).
• Refresh/logout endpoints — admin API only, per the suite contract.
• Issuer/audience claim validation — see Constraints below.
• Asymmetric (RS256 / ES256) signature support — out of scope; the suite contract specifies HMAC.
• JWKS endpoint fetching — not needed for HMAC.
• Rate limiting on 401 responses — separate hardening item from _docs/05_security/security_report.md.

Acceptance Criteria

AC-1: Anonymous request returns 401 Given the API is running with JWT_SECRET configured When any request to any endpoint (except Swagger metadata) is sent without an Authorization header Then the response is HTTP 401 Unauthorized.

AC-2: Expired token returns 401 Given a JWT signed with the configured secret but with exp in the past When the API receives a request carrying that token Then the response is HTTP 401 Unauthorized and the body identifies the failure reason at the WWW-Authenticate header level (no leakage of internal details in the response body).

AC-3: Invalid signature returns 401 Given a JWT whose payload has been tampered with so the HMAC signature no longer verifies When the API receives a request carrying that token Then the response is HTTP 401 Unauthorized.

AC-4: Valid token reaches the handler unchanged Given a JWT signed with the configured secret with exp in the future When the API receives a GET /api/satellite/tiles/latlon request carrying that token with valid query parameters Then the response is identical (status, headers other than Authorization-related, body) to the pre-AZ-487 behavior for the same request.

AC-5: Startup fails on missing or short secret Given JWT_SECRET is unset, empty, or shorter than 32 bytes When the API starts Then startup fails with a clear error message identifying the missing/invalid secret; the API does not bind to its port.

AC-6: HttpContext.User exposes claims Given a JWT containing claims sub, email, role, permissions When a handler reads HttpContext.User Then HttpContext.User.Identity.IsAuthenticated is true, the sub claim is present, and the permissions claim values are accessible via the standard claims API.

AC-7: Swagger UI works with the Authorize button Given the API is running in Development When the operator opens Swagger UI, clicks "Authorize", pastes a valid token, and triggers any endpoint Then the request is sent with the Bearer token and the response is whatever the handler would return for an authenticated request.

AC-8: All existing tests pass with the test token attached Given the test infrastructure attaches a valid dev-token to every test HTTP request When scripts/run-tests.sh --full runs Then all 213 unit tests + the existing 5 smoke scenarios + the new JWT integration tests pass.

Non-Functional Requirements

Performance

• JWT validation per request must add < 1 ms overhead (HMAC-SHA256 + claims parsing); no cryptographic operations beyond what JwtBearer does by default. No caching required.

Compatibility

• The HTTP contract change (every endpoint can now return 401) is documented in the architecture doc. No request/response schema field changes for valid-token callers.
• Existing callers (gps-denied-onboard, mission planner UI) MUST coordinate to attach the Bearer token they already hold from the admin API. This is a coordination cost flagged as a deployment risk in Risks below.

Reliability

• Missing/invalid JWT_SECRET is fail-fast at startup, never at first request — operators learn about the misconfiguration immediately, not on first user traffic.

Security

• Secret length validation enforces ≥ 32 bytes — RFC 2104 §3 minimum for HMAC-SHA256.
• RequireExpirationTime = true rejects tokens that omit exp (defense against forged "never-expires" tokens).
• ClockSkew = TimeSpan.FromSeconds(30) is the maximum drift; do not relax further without explicit security review.

Unit Tests

AC Ref	What to Test	Required Outcome
AC-5	AddSatelliteJwt with missing Jwt:Secret configuration	Startup throws a clear InvalidOperationException (or equivalent) naming the missing key
AC-5	AddSatelliteJwt with Jwt:Secret shorter than 32 bytes	Startup throws with a message identifying the minimum length requirement
AC-1, AC-3, AC-4	JwtTokenFactory test helper round-trip via TokenValidationParameters	Tokens minted by the helper validate; tampered tokens fail validation

Blackbox Tests

AC Ref	Initial Data/Conditions	What to Test	Expected Behavior	NFR References
AC-1	API running with valid JWT_SECRET	Send GET /api/satellite/tiles/latlon?... with NO Authorization header	HTTP 401	Compatibility
AC-2	API running with valid JWT_SECRET; expired token minted	Send GET /api/satellite/region/{id} with the expired token	HTTP 401	—
AC-3	API running with valid JWT_SECRET; tampered token	Send any request with the tampered token	HTTP 401	Security
AC-4	API running with valid JWT_SECRET; valid token	Send GET /api/satellite/tiles/latlon?Latitude=...&Longitude=...&ZoomLevel=18	HTTP 200 with the tile metadata response (identical to pre-AZ-487 behavior)	Performance
AC-7	API running in Development with Swagger UI accessible	Open Swagger, Authorize with a token, invoke an endpoint	Request includes Authorization: Bearer <token>, endpoint returns its normal response	—
AC-8	Full test environment	Run scripts/run-tests.sh --full	All tests pass	—

Constraints

• The suite contract suite/_docs/10_auth.md is authoritative for token shape and signing key distribution. This task implements the validator side; if the contract changes (e.g., admin migrates to RS256), this is a follow-up task.
• HMAC secret MUST come from the JWT_SECRET env var — never from a checked-in config file. The dev placeholder in appsettings.Development.json is acceptable because the file is committed and the placeholder is clearly fake; the JWT_SECRET env var (when set) overrides it.
• No new cross-component ProjectReference — JWT plumbing lives entirely in SatelliteProvider.Api.
• Issuer/audience claims are NOT validated in this PBI because the suite contract does not specify expected values. If the admin team confirms specific values later, add ValidateIssuer = true + ValidIssuer = <value> and same for audience as a small follow-up — not as part of this task.
• ClockSkew tightened from the JwtBearer default (5 minutes) to 30 seconds; document the reason in code (defense in depth — operators in mixed-clock environments may need to override, but the default should be tight).

Risks & Mitigation

Risk 1: Existing callers break the moment AZ-487 deploys

• Risk: gps-denied-onboard and mission planner UI currently call satellite-provider with no Authorization header. The instant .RequireAuthorization() lands, every existing call returns 401 — production-incident-grade breaking change.
• Mitigation:
  • Coordinate the deploy with gps-denied-onboard and UI teams BEFORE merge: confirm both already hold a valid JWT from the admin API and can attach it to outbound calls.
  • Stage the deploy: ship to dev only first, validate that suite e2e tests pass, then promote to stage/prod.
  • Feature flag option (rejected during planning): a compile-time/config flag to bypass auth was considered. Decision: NO bypass flag — auth bypasses tend to become permanent. Coordinate the rollout instead.

Risk 2: Test infrastructure leaks the dev secret

• Risk: Hard-coding the test secret in test source could let a careless copy-paste land it in production config.
• Mitigation:
  • Test secret is ≥ 32 bytes BUT clearly tagged TEST-ONLY- prefix.
  • Test secret is read from an env var (SATELLITE_TEST_JWT_SECRET) in the test runner, not hard-coded — same separation pattern as production.
  • .gitignore already excludes .env; ensure no .env.test file is added without scrubbing.

Risk 3: JwtBearer package version drift vs Microsoft.AspNetCore.OpenApi

• Risk: Picking a major version that mismatches the existing ASP.NET Core 8 packages introduces transitive-dependency conflicts at build time. The Security Audit also flagged a recommended bump of Microsoft.AspNetCore.OpenApi 8.0.21 → 8.0.25.
• Mitigation:
  • Pin Microsoft.AspNetCore.Authentication.JwtBearer to the same minor version family as the rest of the ASP.NET Core 8 packages already in the project.
  • If the OpenApi bump from _docs/05_security/security_report.md happens in this PBI, align JwtBearer to the same version. Otherwise pin to the existing 8.0.21 series.

Risk 4: HS256 secret rotation invalidates all live tokens

• Risk: The HMAC pattern means rotating JWT_SECRET invalidates every issued token across every API instance simultaneously — there's no overlap window unless the validator accepts both old and new secrets briefly.
• Mitigation:
  • Out of scope for this PBI — operationally the suite's current rotation policy is "all tokens become invalid; all clients re-login". Document this in the WebApi component description so operators know.
  • If multi-secret support is needed later (admin team adds RS256 + JWKS), it's a follow-up task.

Cross-component coordination

This PBI changes the HTTP contract observed by:

• gps-denied-onboard — must attach Bearer token to outbound calls; coordinate before merge.
• mission planner UI — same.
• Any other satellite-provider consumer not yet inventoried.

A smoke test in the suite-level e2e harness (suite/e2e/) MUST be updated alongside this PBI's deploy, OR temporarily skipped with an issue-tracked unskip task. Surface this to the suite repo owner during code review.