Maestro auth bootstrap: pick a mechanism for authenticated KYC/Buy/Sell flows

[TaprootFreak]

Context

#543 (Tier 3 Maestro scale-out) blocks 27 of 31 new flows on this decision. Onboarding flows start from cold-boot; KYC / Buy / Sell / Transaction-History / Support / Settings-User-Data flows need an authenticated session + DFX JWT + (for KYC) a known KYC state on the backend. No existing Maestro flow touches the API.

This issue picks the auth-bootstrap mechanism and delivers it as a reusable Maestro fixture.

Options

Option A — Debug-auth shortcut flow

Reuse the existing /debugAuth route (lib/screens/debug_auth/debug_auth_page.dart, kDebugMode-gated at router_config.dart:90-95). Maestro walks: cold-boot → tap "Address + Signature" card on welcome → enter test wallet address → emit DebugAuthCompleteEvent → land at dashboard with seeded JWT.

• Pros: Zero new infrastructure; route already exists.
• Cons: Requires kDebugMode build flag honored in CI (Maestro tests already run debug builds, so should work — verify); seeds a wallet without persisting through WalletService.createDebugWallet's full path; backend still needs a real or stubbed user.

Option B — Fake DFX-API base URL

Point the app at a recorded-response fixture server (e.g. localhost:8089 running a static JSON server) during Maestro runs. Set apiHost via --dart-define=API_HOST=... (requires the env-flag mechanism that doesn't exist today; tied to the /debugAuth env-flag issue).

• Pros: Deterministic, no backend dependency; same fixtures across flows.
• Cons: New plumbing; fixtures need to be authored and maintained as the API evolves.

Option C — Dedicated test backend instance

Provision a real DFX-API DEV instance with pre-provisioned users at known KYC states.

• Pros: Highest fidelity; flushes real regressions.
• Cons: Operational cost; test users need ongoing curation; KYC providers (Sumsub) may rate-limit or block test traffic.

Deliverable

1. Decision: A / B / C
2. The chosen mechanism implemented as a reusable Maestro flow snippet (e.g. .maestro/handbook/_setup-authenticated.yaml) that other flows include via runFlow
3. Documentation in docs/testing.md under "Tier 3" explaining how to use it
4. Validation by porting one existing-but-unauthenticated flow to use it (e.g. 27-buy-asset-selection.yaml)

Acceptance criteria

• A single Maestro snippet bootstraps an authenticated session
• The snippet is reusable across 27 KYC/Buy/Sell/etc flows in Tier 3: extend Maestro handbook to cover every user-facing feature #543 without per-flow customization
• CI cost is bounded (no per-flow backend round-trip)
• Documented in docs/testing.md

Estimated effort

Option	Days
A — debug-auth Maestro snippet	1.0
B — fixture server + env-flag wiring + snippet	3.0
C — backend provisioning + snippet	2.0 + ops cost

Decision itself: 0.5 day. Total including decision + implementation: 1.5-3.5 engineer-days.

Related

• Tier 3: extend Maestro handbook to cover every user-facing feature #543 — Tier 3 Maestro scale-out (blocks 27 flows on this)
• Meta: complete test coverage across every tier and surface #550 — meta-tracker (Phase 4 dependency)
• lib/screens/debug_auth/debug_auth_page.dart
• docs/testing.md — Tier 3 section