Document OAuth client interfaces and test/prod environment setup

epic-bankid-vipps-login-api-clients-task-008 — Write developer documentation covering the public interfaces of the Vipps API Client, BankID Provider Client, and Deep Link Handler. Include how to configure test vs. production environments (environment variables, build flavors), how to register OAuth redirect URIs with both Vipps and BankID developer portals, the typed error model reference, and how to inject test doubles in unit and integration tests. This documentation is critical for the service layer team consuming these components.

medium priority low complexity documentation pending documentor Tier 3

Acceptance Criteria

Documentation file exists at docs/auth/oauth-clients.md and is committed to the repository

Public Dart interface for VippsApiClient is fully documented with parameter types, return types, and thrown exceptions for every public method

Public Dart interface for BankIdProviderClient is fully documented with parameter types, return types, and thrown exceptions for every public method

Public Dart interface for DeepLinkHandler is documented with supported URI schemes and callback contract

Step-by-step guide explains how to configure test vs. production environment via Flutter build flavors (--dart-define or flavor-specific config files)

Documentation lists all required environment variables/constants: Vipps client_id, Vipps client_secret, BankID client_id, redirect URI scheme, environment flag

Guide explains how to register OAuth redirect URIs in both the Vipps Developer Portal and BankID merchant portal, including screenshots or CLI commands where possible

Typed error model is documented: every AuthException subclass is listed with its meaning, when it is thrown, and how the service layer should handle it

Section on test doubles explains how to inject a FakeVippsApiClient and FakeBankIdProviderClient via Riverpod provider overrides in widget tests and integration tests

At least one end-to-end example code snippet per client showing a complete flow (initiate → redirect → callback → token)

A reviewer from the service layer team confirms the documentation is sufficient to start consuming the components without additional explanation

Technical Requirements

frameworks

Flutter

Riverpod

flutter_test

apis

Vipps Login API (test and production endpoints)

BankID OIDC/OAuth2 endpoints (test and production)

data models

AuthException hierarchy

OAuthToken

VippsLoginResult

BankIdVerificationResult

performance requirements

Documentation must be parseable as standard Markdown by GitHub and pub.dev

Code snippets must be syntactically valid Dart and compilable without modification

security requirements

No real credentials, client secrets, or tokens may appear in documentation examples — use placeholder values

Document that client_secret must never be stored in source control or shipped in the app binary

Explicitly state that test credentials must not be used in production builds

Execution Context

Execution Tier

Tier 3

Tier 3 - 413 tasks

Can start after Tier 2 completes

View Full Execution Plan

Implementation Notes

Write the documentation as a single Markdown file with clear section headers for: (1) Architecture overview diagram showing how VippsApiClient, BankIdProviderClient, and DeepLinkHandler relate to each other and to the service layer; (2) Interface reference — copy the actual Dart abstract class or interface signatures directly into the doc with dartdoc-style comments explaining each parameter; (3) Environment configuration — show the exact --dart-define keys and their names, and how they map to build flavors in flutter run and CI; (4) Portal registration — cover Vipps Developer Portal redirect URI registration (must match the URI scheme registered in AndroidManifest.xml and Info.plist) and BankID merchant portal callback URL; (5) Error handling reference table; (6) Test double injection pattern using Riverpod's ProviderContainer overrides. Keep the tone terse and technical. Avoid restating what the code does — focus on what a consumer needs to know to use it safely. Cross-reference task-007's implementation so readers can navigate to source.

Testing Requirements

No automated tests for this task. Manual review acceptance test: a developer unfamiliar with the OAuth clients must be able to wire up a Riverpod provider override using the FakeVippsApiClient in a new widget test file, following only the documentation, without asking for help. Reviewer sign-off is required before the task is closed.

Component

BankID Provider Client

infrastructure high

Dependencies (1)

Write integration tests for the Vipps API Client, BankID Provider Client, and Deep Link Handler using test-environment credentials and mock HTTP adapters. Cover the happy path (successful token exchange, userinfo retrieval, assertion validation), error paths (network failure, expired tokens, invalid state parameter, BankID session timeout), and provider routing in the deep link handler. Verify that typed errors propagate correctly to the service layer boundary and that no raw HTTP details leak upward. epic-bankid-vipps-login-api-clients-task-007

Epic Risks (3)

high impact high prob dependency

Norway has multiple BankID broker providers (e.g., Signicat, Criipto, Nets) with different integration contracts, pricing, and WebView behavior. If the broker is not selected and contractually agreed before implementation begins, the BankIDProviderClient may need to be rewritten after initial build.

Mitigation & Contingency

Mitigation: Define a minimal broker interface abstraction (session initiation, WebView URL generation, assertion validation) before writing any provider-specific code. Confirm broker selection with Norse Digital Products before starting this epic.

Contingency: If the broker changes after implementation, the abstraction layer allows replacing the provider-specific implementation behind the same interface with a targeted rewrite rather than a full redesign.

high impact medium prob technical

Android deep link handling with custom URI schemes can conflict with existing app links (HTTPS-based) or fail silently on certain Android versions if the intent filter is misconfigured, causing OAuth callbacks to never reach the app and leaving users stranded on the Vipps or BankID page.

Mitigation & Contingency

Mitigation: Use HTTPS app links (Android App Links) rather than custom URI schemes where possible, as they are more reliable on modern Android. Test deep link receipt on Android 12+ explicitly during development, as this version changed intent flag requirements.

Contingency: Implement a polling fallback for Vipps (check auth status on app foreground) as a secondary callback mechanism if deep link receipt fails on specific Android configurations.

medium impact medium prob dependency

Vipps Login has a separate test environment (mt2.vipps.no) that requires distinct test merchant credentials which must be applied for separately. If test credentials are delayed, integration testing of the VippsApiClient cannot proceed, blocking the entire authentication flow.

Mitigation & Contingency

Mitigation: Apply for Vipps test merchant credentials at the start of the project sprint, not when implementation begins. Use Vipps' publicly documented mock token responses for unit tests to decouple unit testing from live credentials.

Contingency: Implement the VippsApiClient with full mock injection support so all service-layer tests can run against a stub client while waiting for official test credentials.

Quick Links

All Tasks Execution Plan