Mobayilo Social Login - Implementation Plan

Mobayilo Social Login - Implementation Plan

Last Updated: 2026-02-21
Program Status: Google phase implemented on development with local tests green; X phase now prioritized before Facebook

1. Goal

Deliver secure social sign-in for web auth without breaking existing magic-link login:

• Google first (complete implementation + test coverage + validation)
• X (x.com) second
• Facebook third
• preserve current account, balance, call attribution, and role boundaries

2. Scope and Principles

• No one-shot rollout across all providers.
• Keep passwordless login fully available during all phases.
• User social login only in initial rollout; CompanySeat remains magic-link.
• Enforce account-takeover protections before convenience linking.
• Advance to next provider only after current provider test checklist is green.

3. Phase Overview (Progress View)

Phase	Status	Focus
Phase 0	✅ Complete	Auth architecture audit + integration design
Phase 1	✅ Implemented (local validation complete)	Google OAuth implementation + tests + rollout checks
Phase 2	🚧 In Progress	X OAuth implementation + tests + rollout checks
Phase 3	⏳ Planned	Facebook OAuth implementation + tests + rollout checks
Phase 4	⏳ Planned	Optional provider-linking UX and post-rollout hardening

4. Implementation Strategy

4.1 Core Auth Wiring (shared across providers)

Planned deliverables:

• Add Devise OmniAuth wiring for User scope.
• Add callback controller/service for identity resolution and safe linking.
• Keep existing Users::SessionsController magic-link flow unchanged.
• Keep current_account resolution unchanged to avoid billing/call regressions.

Planned schema:

• oauth_identities table:
  • user_id
  • provider
  • uid
  • email
  • email_verified
  • name
  • avatar_url
  • raw_info (jsonb)
  • last_sign_in_at
• Unique indexes:
  • (provider, uid)
  • (user_id, provider)

Security baseline:

• Require OAuth state validation.
• Link by (provider, uid) first; only fallback-link by verified email.
• Reject ambiguous email matches.
• Never infer access from domain alone.
• Never escalate role/account kind from provider profile data.

4.2 Provider Rollout Policy (strict sequencing)

• Phase 1: Google only.
• Phase 2 starts only after Phase 1 checklist is fully green.
• Phase 3 starts only after Phase 2 checklist is fully green.
• If provider-specific risk appears, pause that provider without blocking existing auth.

5. Phase-by-Phase Plan

5.1 Phase 1: Google OAuth (First Provider)

Objective:

• deliver end-to-end Google sign-in safely.

Planned deliverables:

• Add Google provider config and callback route.
• Add Google sign-in button to login UI.
• Support:
  • existing linked user sign-in
  • verified-email link to existing user
  • new user onboarding path (individual user)
• Add explicit fallback path to magic-link when linking cannot be trusted.

Test checklist (Phase 1):

• Existing linked Google identity signs in correctly.
• Verified email match links to exactly one existing user.
• Unverified email does not auto-link.
• Claimed company domains and company users fall back to magic-link rules.
• Existing passwordless sign-in still works unchanged.
• Session/account/call attribution remains correct after Google sign-in (deep call-flow regression pass pending).
• Controller/model/integration tests pass for Google flows.
• Regression tests cover conflict and takeover-prevention cases.

Exit criteria:

• Google login is production-safe and fully tested; no auth regression detected.

5.2 Phase 2: X OAuth (Second Provider)

Objective:

• add X sign-in with provider-specific email constraints handled safely.

Planned deliverables:

• Add X provider config and callback route.
• Add X sign-in button to login UI.
• Handle missing email returns by falling back to trusted verification path (magic-link).

Test checklist (Phase 2):

• X linked identity sign-in works.
• Missing/unverified X email does not trigger unsafe auto-linking.
• Fallback verification flow is clear and functional.
• Google + passwordless flows remain green.
• Regression suite (all providers implemented so far) passes.

Exit criteria:

• X sign-in is live with no unsafe linking behavior and no auth regressions.

5.3 Phase 3: Facebook OAuth (Third Provider)

Objective:

• add Facebook using the same hardened identity flow.

Planned deliverables:

• Add Facebook provider config and callback route.
• Add Facebook sign-in button to login UI.
• Reuse shared identity-linking service and guardrails.

Test checklist (Phase 3):

• Facebook linked identity sign-in works.
• Verified email linking behavior matches Google policy.
• Provider conflict behavior is explicit and safe.
• Google/X/passwordless flows remain green.
• Full auth regression suite passes.

Exit criteria:

• Facebook sign-in added without regressions to Google/X/passwordless auth.

5.4 Phase 4: Optional Hardening and UX Improvements

Objective:

• improve account linking UX and supportability after provider rollout.

Planned deliverables:

• provider management UI in Settings (link/unlink where safe).
• audit logging for identity link/unlink actions.
• support runbook updates for provider conflicts and recovery.

6. Dependencies to Prepare

• Google app credentials and callback URL.
• Facebook app credentials and callback URL.
• X app credentials and callback URL.
• provider email/permission settings confirmed before each phase.
• production HTTPS callback domains confirmed.

7. Quality Gates (Per Provider Phase)

• model/service/controller tests for auth callbacks and linking logic.
• regression checks for existing passwordless flows.
• documented rollout decision before enabling next provider.
• PROJECT_STATUS.md updated after each phase completion.

8. Recommended Execution Order From Today

1. Implement Phase 1 (Google) completely.
2. Run and pass full Phase 1 test checklist.
3. Validate no regressions in passwordless/account flows.
4. Begin Phase 2 (X) after Phase 1 is fully closed.
5. Begin Phase 3 (Facebook) only after Phase 2 is fully closed.