6.4 TLS Enforcement

Sprint Key: 6-4-tls-enforcement (the sprint-status entry key) Epic: 6 PRD: mobile-oidc

---

Story 6.4: TLS Enforcement

Status: ready-for-dev

Story

As a mobile app, I want valid TLS certificate validation enforced on all network connections, So that the app never connects to servers with invalid or self-signed certificates.

Acceptance Criteria

1. Given main.dart currently contains a badCertificateCallback override, When the removal is complete, Then the badCertificateCallback is removed from main.dart (FR23)

2. Given a debug build needs to work with self-signed certificates, When the app runs in debug mode (kDebugMode), Then a conditional bypass can be enabled for development — documented in the dev workflow

3. Given the app runs in release mode, When any HTTPS connection is made to a server with an invalid certificate, Then the connection is rejected — no bypass (FR23)

4. Given flutter analyze runs, When the codebase is checked, Then no TLS bypass code is detected in release paths

Tasks / Subtasks

• 1. Remove MyHttpOverrides class and HttpOverrides.global assignment (AC: #1 (closed), #3 (closed), #4 (closed))

  • 1.1 Delete the entire MyHttpOverrides class (lines 40-47 in main.dart)
  • 1.2 Delete the HttpOverrides.global = MyHttpOverrides(); assignment and its if (!kIsWeb) guard (lines 54-56 in main.dart)
  • 1.3 Add conditional debug-only bypass using kDebugMode — if debug builds against self-signed certs are needed
  • 1.4 If adding the debug-only bypass, rename class to _DebugHttpOverrides and add a clear comment
  • 1.5 Remove the now-unused import 'dart:io' ONLY if no other code in main.dart uses dart:io

• 2. Verify no other TLS bypass code exists in the codebase (AC: #4 (closed))

  • 2.1 grep -rn "badCertificateCallback" lib/ test/ — expect results ONLY in the debug-only override (if kept)
  • 2.2 grep -rn "HttpOverrides" lib/ test/ — expect results ONLY in the debug-only override (if kept)
  • 2.3 grep -rn "SecurityContext" lib/ test/ — expect results ONLY in the debug-only override (if kept)
  • 2.4 Verify that network_error_classifier.dart only catches TlsException for error classification

• 3. Verify build and tests (AC: #4 (closed))

  • 3.1 Run flutter analyze — zero errors
  • 3.2 Run flutter test — all tests pass
  • 3.3 Run flutter pub get — no resolution errors

• 4. Verify release safety (AC: #3 (closed))

  • 4.1 grep -rn "badCertificateCallback" lib/ — any hit must be inside a kDebugMode guard
  • 4.2 Confirm kDebugMode is a const bool — compile-time constant, tree-shaken in release

Dev Notes

CRITICAL: This Is a Small, Surgical Story

This story has a single file to modify (main.dart) and a single code block to change (the MyHttpOverrides class + its assignment). Do NOT over-engineer it.

Recommended approach: Keep a kDebugMode-guarded debug-only bypass. Rationale:

• Developers working against local/self-signed Keycloak instances need this
• kDebugMode is a Dart compile-time constant — the entire block is eliminated from release binaries
• The architecture document explicitly mentions: "This may break development against self-signed certs — dev workflow adjustment needed"

Files Being Modified

File	Action	What Changes	What Must Be Preserved
lib/main.dart	MODIFY	Remove MyHttpOverrides class, optionally add kDebugMode-guarded debug bypass	All existing functionality — ProviderScope, AppLinks, OIDC config, MyApp, MainScreen, _BinderTab

References

• [Source: epics.md#Story 6.4] — Full acceptance criteria
• [Source: architecture.md#Technical Constraints] — badCertificateCallback must be removed
• [Source: architecture.md#Enforcement Guidelines] — Never add badCertificateCallback back