# Multiple white-label accounts — agreed design

> Enablement update: the user authorized opening login on 2026-09-11. Broker and
> App defaults now enable it; old Code entry remains disabled. Earlier closed-state
> notes below are historical. The user requested an initially empty, database-backed
> company directory editable by Super Admins in Setting > App Companies. Production registry/deployment and App distribution
> must still be verified; see `../company-accounts-deployment.md`.


Supersedes the first-login and switching UX of `2026-09-10-company-entry.md`.
The mentor's flow is the accepted product requirement. This work stays local;
no push, production rollout or App Store release. Both new login feature flags
are OFF by default. The obsolete Code endpoints have a separate OFF-by-default
flag and must stay off for the new password-verified discovery flow.

## Flow and privacy

- First launch shows an account-entry page. Sign in opens email/password entry.
- App POSTs credentials once to the trusted central broker. The broker privately
  reads the current company-to-HTTPS-origin configuration and authenticates with
  every enabled deployment. A bounded pool of five requests avoids one slow
  company blocking all successful responses; each request has a five-second cap.
- Only successful identities and their tokens reach the device. No public
  company-list endpoint. App contains the broker origin, not customer origins.
  Adding a customer requires server configuration, not an App Store release.
- By accepting this design, credentials are submitted to each participating
  trusted customer backend. They are not persisted by the broker or App. No
  email-only membership inference; different passwords need separate sign-ins.
- Rows display email and company. A user selects a row after a fresh sign-in,
  even if it is the only match. Later launches auto-enter a sole saved identity,
  or a valid default identity; otherwise show the saved list.
- Repeated login updates matching company/account UUIDs and appends new matches.
  Failed matches/timeouts never delete existing saved accounts. Partial failures
  show generic retry guidance without exposing failed customer names or counts.
- Multiple emails at one company and cloned UUIDs across companies remain distinct.
  Defaults bind to a company/account identity, not email alone.
- Switch returns to the list and keeps logins. Active recording must be stopped
  before switching. Sign out removes only that identity; sign out all removes all.
  Neither action deletes local recording files. Removing the default clears it.
- Background uploads choose their original saved account owner, independent of
  the currently displayed company or default. Signed-out work stays for recovery.

## Upgrade and scope

Keep the original backend's local account UUIDs and legacy credential namespace.
Import an existing valid login when enabling this feature, without requiring a
password. Old builds did not save email; that migrated row says Existing account
until the next successful sync fills its email. The previously implemented Code
screens remain dormant; this version does not use a code/link to change accounts.

The broker is not a shared user database and does not change agency authorization.
Agency login and refresh continue to check active staff and an agent record.

## Implementation and acceptance

1. Disabled-by-default central broker, private config, strict origins, no redirects,
   per-email/global limits, bounded failures and credential-safe instrumentation.
2. Secure identity catalog, per-origin/account credentials, merge/default/logout,
   legacy migration, list/login gate and awaited runtime teardown on switching.
3. Owner-based background lookup, tests for cloned UUIDs and multiple emails,
   authentication privacy and failures, launch/list/default/switch behavior.
4. Run PHP tests, Flutter tests/analyze and platform verification/build checks.
   Commit task changes only and cherry-pick backend commits to local dev-chen.

Real two-backend accounts, signed-device recording/switch tests and deployment
configuration remain rollout checks; passing mocks does not claim live verification.

## Local completion — 2026-09-11

Implemented the broker, multi-account login/list/default flow, origin/account
credential namespaces, legacy migration, owner-based background lookup and
awaited account-switch teardown. Code entry and broker flags are separately OFF
by default. Ordinary mobile builds retain the original single-backend login.

Backend validation: 50 tests / 293 assertions, PHP formatting and diff checks.
Mobile validation: full 436-test suite, follow-up focused regression checks,
static analysis, enabled-feature Android arm64 debug build and iOS arm64
simulator build. The only PHP warning is the pre-existing XML schema deprecation.
See the mobile `docs/validation/COMPANY-ACCOUNTS-2026-09-11.md` for exact scope.

Backend commits are integrated into local dev-chen only. App work stays isolated
on codex/company-entry; original ongoing recording/WhatsApp work is untouched.
No push, server configuration, production deployment, or store release occurred.
Real-backend and signed physical-device acceptance remains a later rollout step.