[Roadmap][auth] Build cross-platform authentication, profiles, and store-ready account UX

[artiphishle]

Goal

Build one production-grade, adapter-neutral authentication and account architecture for generated Ankhorage apps across Web, iOS and Android.

The roadmap starts with the currently working Supabase/Google browser OAuth path, removes the remaining Web transport and infrastructure defects, then generalizes the platform, profile, form and account layers without coupling generated apps to Supabase, Google or Expo-specific UI.

The first supported provider setup remains deliberately small:

Google OAuth client type: Web application
Credentials: Web Client ID + Web Client Secret
Transport: brokered OAuth through the configured Auth backend

Web uses a full-page PKCE redirect. Native apps initially use the secure system authentication browser and an app deep link. Native Google/Apple SDK transports are optional later capabilities, not a second Auth architecture.

---

Relationship to [adm]

Existing authoring roadmap: #115

This roadmap does not replace [adm].

Priority:

1. complete [auth 1] through [auth 3] before continuing implementation of new [adm] work;
2. [auth 4] and [auth 5] establish the platform foundation before Store/native-auth work;
3. independent [adm] work may resume after the current OAuth foundation is stable;
4. [auth 6] and [auth 7] must complete before generated profile/account authoring depends on those contracts;
5. [auth 8] and [auth 9] are later native/store phases and do not block unrelated authoring work.

The completed [adm 1] remains the current Studio selection/AppBar baseline.

---

Core architecture

Keep these concerns distinct:

Provider transport
  -> Web full-page redirect
  -> Native system authentication browser
  -> optional later native Google/Apple SDK

Auth backend adapter
  -> Supabase Auth today
  -> other adapters later

Normalized Auth domain
  -> AuthUser
  -> AuthSession
  -> UserProfile
  -> account actions

UI/runtime
  -> auth/profile bindings
  -> generic forms
  -> generated profile/account surfaces

The UI must never know whether the backend is Supabase, Auth0, Cognito or another future adapter.

Secrets remain server-side/trusted. Public client IDs and platform identifiers are configuration, not secrets.

---

Hard rules for all [auth] issues

1. Respect this roadmap first and the AGENTS.md file of every touched repository.
2. No compatibility wrappers, legacy parallel flows, duplicate session/profile models or temporary provider-specific UI architecture.
3. Preserve strict TypeScript: no any, ts-ignore, eslint-disable workaround or weakened validation.
4. Canonical ownership stays in the owning package; Studio must not duplicate Contracts, Auth adapter behavior, Infra generation, Runtime execution or ZORA form logic.
5. Release boundaries pause cross-repository implementation. Do not bridge incompatible package versions with temporary code.
6. Child issue titles use [auth N] {title} and link this roadmap.
7. Every child issue includes a Previous roadmap step section.
8. Repository impact is listed when multiple repositories are involved.
9. Use meaningful implementation phases and behavior-focused tests.
10. Never expose client secrets, service-role credentials, callback authorization codes or tokens in browser-readable admin state/logging.
11. Web/local wildcard redirect rules must never silently become production redirect policy.
12. Delete obsolete flows after the replacement is complete.
13. Native provider SDKs remain optional transport capabilities; the normalized Auth and account contracts must not fork by provider/platform.
14. Passwords are write-only account operations, never readable profile/session fields.
15. Provider metadata may initialize a profile according to an explicit merge policy but must not overwrite user-owned edits on every login.

---

Roadmap order

[auth 1] Replace Web OAuth popup transport with full-page PKCE redirect

• remove Web use of openAuthSessionAsync;
• preserve native system-browser behavior;
• eliminate Chrome COOP window.closed errors;
• complete login through the existing callback route and neutral adapter contract.

[auth 2] Reconcile dynamic GoTrue redirects and Auth runtime rollout

• generate project-specific gateway callback URIs;
• generate local/deployed/native redirect allowlists;
• restart and await Auth deployment after Secret/Config changes;
• surface deferred/failed OAuth credential reconciliation honestly.

[auth 3] Make OAuth attempts recoverable and add complete callback coverage

• persist timestamps/expiry;
• recover stale pending/completing attempts automatically;
• deterministic cancel/error cleanup;
• behavior and browser-level coverage for the complete Web callback lifecycle.

[auth 4] Model platform/environment targets and platform-aware OAuth administration

• canonical Web/iOS/Android target configuration;
• stable bundle/application IDs and schemes;
• local/preview/production environment overlays;
• dashboard requests only credentials/settings required by enabled targets;
• ankh doctor readiness validation.

[auth 5] Support brokered browser OAuth on iOS and Android

• same Auth backend and Web OAuth credentials;
• secure system browser;
• generated app deep links;
• shared PKCE completion contract;
• real development-build smoke coverage.

[auth 6] Complete adapter-neutral identity, profile, account and binding contracts

• normalize identity/profile fields;
• separate identity, editable profile and account actions;
• add canonical auth/profile binding sources;
• define profile initialization/merge policy;
• add account operations such as update profile, change email/password and delete account as capabilities.

[auth 7] Build generic forms and generated profile/account UI

• provider-neutral Form contracts/runtime;
• ZORA renderer and reusable field metadata;
• generated profile route, account menu/avatar and configured fields;
• bind initial values/actions to canonical Auth/Profile sources;
• password/email operations remain dedicated account actions.

[auth 8] Add optional native Google and Apple transports

• capability-driven native ID-token/assertion transport;
• generated dependencies/config plugins only when enabled;
• Supabase implementation behind the neutral Auth adapter;
• no impact on providers that continue using browser OAuth.

[auth 9] Complete Store-ready account lifecycle and validation

• Sign in with Apple policy readiness where applicable;
• in-app account deletion and required external deletion path support;
• revocation/linking/re-authentication behavior;
• signing identifiers/fingerprints and deployment validation;
• iOS/Android/Web test matrix and Store-readiness diagnostics.

---

Credential direction

Initial browser-brokered Google configuration:

Google -> Auth backend callback
  exact project/environment gateway callback

Auth backend -> generated app
  Web current origin callback
  deployed Web callback
  native app-scheme callback

For the initial universal browser approach, one Google Web Client ID and Secret can serve Web/iOS/Android for one app/environment because the Auth backend is the Google OAuth client.

Later native transports may add public iOS and Android Client IDs. They do not add trusted native client secrets.

---

Definition of Done

The roadmap is complete when:

• Web OAuth has no popup/COOP transport errors;
• OAuth infrastructure changes reliably reach the running Auth service;
• stale attempts recover without manual Local Storage cleanup;
• Web/iOS/Android targets and environments are canonical and validated;
• brokered OAuth works on all three platforms;
• Auth adapters return one normalized identity/profile/account model;
• forms and generated profile/account UI consume neutral bindings/actions;
• optional native Google/Apple transports integrate as capabilities;
• account deletion and Store validation are production-ready;
• all touched packages have behavior-focused tests, changesets and full validation;
• no provider-specific business/UI logic leaks across package boundaries.

[artiphishle]

Created child issues

• [auth 1] [auth 1] Replace Web OAuth popup transport with full-page PKCE redirect #189 — Replace Web OAuth popup transport with full-page PKCE redirect
• [auth 2] [auth 2] Reconcile dynamic GoTrue redirects and Auth runtime rollout #190 — Reconcile dynamic GoTrue redirects and Auth runtime rollout
• [auth 3] [auth 3] Make OAuth attempts recoverable and add complete callback coverage #191 — Make OAuth attempts recoverable and add complete callback coverage
• [auth 4] [auth 4] Model platform/environment targets and platform-aware OAuth administration #192 — Model platform/environment targets and platform-aware OAuth administration
• [auth 5] [auth 5] Support brokered browser OAuth on iOS and Android #193 — Support brokered browser OAuth on iOS and Android
• [auth 6] [auth 6] Complete adapter-neutral identity, profile, account and binding contracts #194 — Complete adapter-neutral identity, profile, account and binding contracts
• [auth 7] [auth 7] Build generic forms and generated profile/account UI #195 — Build generic forms and generated profile/account UI
• [auth 8] [auth 8] Add optional native Google and Apple transports #196 — Add optional native Google and Apple transports
• [auth 9] [auth 9] Complete Store-ready account lifecycle and validation #197 — Complete Store-ready account lifecycle and validation

Execution priority relative to [adm]

1. Implement [auth 1], [auth 2], [auth 3] now as the blocking OAuth stabilization lane.
2. Resume independent [adm] work after [auth 1]–[auth 3] are complete and released through all dependency boundaries.
3. Complete [auth 4] before [auth 5], because native deep links and callback policy depend on canonical target identities.
4. Complete [auth 6] before [auth 7], because generated forms/profile UI must consume stable adapter-neutral profile/account/binding contracts.
5. [auth 8] and [auth 9] are later native/Store phases and do not block unrelated [adm] items.

Do not merge child scopes merely to reduce issue count; release boundaries and canonical package ownership remain explicit.