[AUTH]: Make OAuth onboarding and role provisioning transactionally consistent

[grantfox-oss]

Context

Supabase authentication, the local User record, role selection, and role-specific Grantee/PayoutProvider records are created through separate requests and hooks. Retries, simultaneous tabs, or callback failures can leave partial identities and conflicting onboarding state.

Scope

• Define an explicit onboarding state model independent of inferred missing rows.
• Make local identity upsert idempotent across email/password and OAuth callbacks.
• Provision the selected role and role-specific record atomically.
• Prevent unauthorized role changes and define the supported role-change workflow.
• Handle email changes, provider linking, duplicate verified emails, and disabled users deliberately.
• Replace duplicated client initialization checks with one server-authoritative bootstrap endpoint.

Acceptance criteria

• Replaying OAuth callbacks or opening multiple tabs creates exactly one local identity.
• Users cannot reach the dashboard with an impossible partial role state.
• Role provisioning commits fully or rolls back fully.
• Identity collisions return a safe recoverable path without account takeover risk.
• Integration tests cover callback retry, concurrent selection, disabled user, and provider linking.
• The onboarding state diagram and recovery procedure are documented.

Relevant areas

OAuth verification/register routes, role-selection provider/hooks, auth context/services, User, Grantee, and PayoutProvider models.

[MoscowDev]

I’d love to take this issue on. I’ve worked on production-ready applications and collaborated extensively through GitHub workflows. I’ll dig into the current setup, implement a solid and reliable fix, and deliver a well-tested PR. My focus is on clean, maintainable code and fast, dependable delivery.

[Joyful12-tech]

Hello Maintainer,
I'd like to work on this issue. I'll implement the onboarding flow improvements, add integration tests, and submit a quality PR within 2 days.
Thank you!

[ebubeb683-ship-it]

I'd like to work on this issue.

[Glam26]

Hi! I'd like to contribute to this issue.

I'll begin with a root-cause analysis of the current behavior to ensure the implementation addresses the underlying problem rather than introducing a localized fix. Once implemented, I'll extend the existing test suite to cover regression scenarios and verify compatibility with the rest of the system before opening a PR.

[Yasir-TechGuy]

Please assign this issue to me

[grantfox-oss]

🦊 GrantFox — @Yasir-TechGuy has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #91)
2. Your PR will be reviewed by the Eduvault-stellar maintainers

Good luck! Track your progress on GrantFox.

[Yasir-TechGuy]

Before starting on this, I want to flag a mismatch: this issue describes Supabase-based OAuth
onboarding with User, Grantee, and PayoutProvider records, but I don't see any of these in the
codebase — this repo appears to be MongoDB-backed with wagmi/RainbowKit for wallet
integration, no Supabase, no Grantee or PayoutProvider models anywhere (confirmed via a full
repo grep).

Could you clarify where this auth/onboarding flow actually lives, or whether this issue was
filed against the wrong repo? Want to make sure I'm working against the right codebase before
starting.