Use the reviewed authentication contract
Driver App authentication combines configured credential branches, server authentication, a Driver-role gate, and local session persistence. Treat those as separate decisions: a successful credential response is not automatically a valid Driver session, and locally restored session state is not fresh server authorization.
This is a source-defined public responsibility contract. It does not certify the running authentication service, a provider, or runtime success.
Availability
The reviewed Login screen enables email and cellphone password presentation and passes the Driver role as its allowed standard-login role. Project configuration can also expose OTP, device-code, provider-specific, CAPTCHA, or other alternate branches. Alternate branches do not uniformly repeat the same Driver-role gate and must not be called equivalent without separate acceptance.
The reviewed signed-out navigation registers Home, Login, and Forgot. It does not register Driver signup, and it has no reviewed inbound deep-link mapping.
Prerequisites
- A configured Driver App build and supported Driver account workflow.
- Current authentication configuration for the intended branch.
- Explicit Driver-role enforcement on every branch that can create local session state.
- Secure handling of credentials, OTP values, provider results, tokens, notification identity, and locally stored account data.
- Separate server authorization on every request after authentication.
Responsibility boundaries
| Boundary | Responsibility | Limit |
|---|---|---|
| Login UI | Present configured credential/OTP/provider controls and local validation/loading/error states. | Visibility does not prove provider or server availability. |
| Authentication controller | Build the selected credential shape, call the matching source contract, and interpret the response. | Branches can differ in role checks and cleanup. |
| Driver role gate | Admit only the reviewed Driver role into the standard local-session path. | Not uniformly established for alternate branches. |
| Rejected-role cleanup | Request server logout for a returned non-Driver session before showing permission error. | Logout/cleanup can fail or partially settle. |
| Session provider | Save/remove local token, user and optional device state; expose auth/loading. | Local storage is not server validation or revocation. |
| Root navigation | Select signed-out or authenticated branch from local session/readiness state. | Navigation is not authorization for a task. |
| API | Authenticate credentials and authorize every subsequent read/mutation. | Running artifact relation remains unconfirmed. |
| OTP/CAPTCHA/provider | Own generation, verification, challenges and external results. | Provider completion does not prove Driver role. |
Inputs and result
| Input/branch | Client result | Required check | Failure/partial boundary |
|---|---|---|---|
| Email/cellphone + password | Standard authentication response | Driver role before local login | Error, wrong role, cleanup failure, missing session |
| OTP | Generated/verified one-time credential result | Repeat Driver-role and session policy | Some verification paths can set local session without the standard role block |
| Device code | Device-code credential and optional local persistence | Driver role, device ownership and revocation | UI exposure differs from controller capability |
| Provider-specific login | Provider/server result | Driver role and provider identity | Availability and role parity unproven |
| CAPTCHA | Challenge value added before selected request | Challenge validity and provider result | Missing/incomplete config can block or distort another branch |
| Notification identity | Optional token/app data included during authentication | Notification ownership and privacy | Login success does not prove push registration/delivery |
| Local session restore | Stored token/user/device returned to providers | Reauthorize each API request | Stale/disabled/wrong-role state can persist until later checks |
| Forgot flow | Local form can show a link-sent state before request settlement | Observe final success/error separately | UI transition is not delivery or reset completion |
Security and privacy
- Never log or expose credentials, OTP, CAPTCHA values, tokens, provider IDs, notification identity, account records, or device codes.
- Apply the Driver-role gate before every branch writes local session state.
- Treat rejected-role logout, provider cleanup, token revocation and local cleanup as separate results.
- Do not inject tokens, navigate directly to authenticated routes, or use saved state as authorization evidence.
- Clear prior-account and late-request state before admitting another account.
Limits and failure states
| State | Meaning | Maintainer response |
|---|---|---|
| Configured branch hidden | UI/config does not admit it. | Do not expose controller-only capability. |
| Authentication error | Selected server/provider contract returned or threw failure. | Keep session signed out and surface sanitized error. |
| Wrong role | Standard branch rejected returned account. | Require complete server/local cleanup; no authenticated navigation. |
| Alternate branch success-looking | Provider/OTP returned an account/session. | Verify Driver-role parity before local login. |
| Local session restored | Saved data became available. | Reauthorize every read/action; do not call it fresh. |
| Disabled/missing local user | Session consistency check can request local logout. | Server state and cleanup remain separate. |
| Forgot link-sent state | Local recovery UI advanced. | Await actual request/result; no email-delivery claim. |
Troubleshooting
| Symptom | Inspect | Safe diagnostic |
|---|---|---|
| Expected sign-in option is missing | Current configuration and UI exposure | Do not invoke a controller-only branch. |
| Non-Driver account appears accepted | Branch-specific role enforcement and local session write | Stop authenticated work and follow secure cleanup/escalation. |
| Wrong-role error appears but state is unclear | Server logout, local session and navigation results separately | Do not reuse returned tokens or force navigation. |
| App opens authenticated from saved state | Session hydration and per-request authorization | Treat stored state as provisional until current requests authorize. |
| Recovery says link sent too early | Local transition versus request settlement | Wait for final error/success; do not repeat or claim delivery. |
Re-review this contract whenever a login branch, role gate, CAPTCHA/provider, notification identity, session storage, rejected-role cleanup, recovery state or Root auth selection changes.
Related guides: Open Driver App and reach sign in · Sign in as a driver · Sign-in options · Reset a password · Authenticated bootstrap