feat: Social/OAuth authentication (restify:social)

[denisdobra10]

Restify Social Auth (OAuth)

Adds social login (GitHub, Google, GitLab, Atlassian/Jira, …) to Restify, built on Laravel Socialite and mirroring the existing Route::restifyAuth() macro + restify:auth publish flow.

Why

On almost every app built on Restify we re-implement the same "Connect with GitHub/Atlassian" plumbing by hand: install Socialite, write redirect + callback controllers, a table for linked accounts, find-or-create-user logic, then issue a Sanctum token. This makes it a one-command, config-driven package feature instead — apps add credentials and run a command rather than rebuilding the wiring each project.

One command, fully scaffolded

php artisan restify:social --providers=github,atlassian --install

• publishes a social_accounts migration (one user ↔ many linked providers)
• appends Route::restifySocialAuth(); to routes/api.php
• writes the provider blocks into config/services.php (idempotent, valid PHP)
• appends {PROVIDER}_CLIENT_ID/SECRET/REDIRECT_URI to .env and .env.example with the redirect pre-filled to ${APP_URL}/api/auth/social/{provider}/callback
• --install runs composer require socialiteproviders/{provider} for community drivers (atlassian, jira, …)

The only manual step left is the irreducible one: registering the OAuth app on the provider's dashboard to obtain the client id/secret.

Escape hatches: --no-routes, --no-env, --no-services, --publish.

Endpoints

Two per provider (SPA / API-token flow, same token shape as restifyAuth login):

GET  /api/auth/social/{provider}/redirect   ->  { "url": "https://github.com/login/oauth/authorize?..." }
GET  /api/auth/social/{provider}/callback   ->  find-or-create user, link account, return Sanctum token

Fully overridable

1. Config (restify.auth.social) — providers, scopes, token name, stateless, optional redirect_url
2. Runtime hook — Restify::resolveSocialUserUsing(fn ($provider, $oauthUser, $request) => ...)
3. Swap classes via config — resolver / model / controllers
4. Publish & own — restify:social --publish copies controllers + resolver into the app

$user->socialAccounts, $user->hasSocialProvider('github') via the HasSocialAccounts trait.

Why it's good for the package

• Removes recurring per-project boilerplate — social login becomes a feature, not a recipe
• One consistent, tested implementation instead of N hand-rolled variants
• Correct multi-provider account linking out of the box ("Connect GitHub and Atlassian")
• Stays lean — Socialite is an optional suggest dependency; non-social installs are unaffected
• Feels native — same macro + publish pattern, same token shape, config under restify.auth.social

Notes

• Core drivers (github, google, gitlab, bitbucket…) ship with Socialite; community ones (atlassian, jira…) need a socialiteproviders/* package — --install handles it, otherwise the command tells you which.
• The file-mutation logic (.env / services.php) lives in pure, idempotent static helpers with unit coverage.
• Tested: HTTP flow (redirect, create+link+token, link-by-email, resolver override) + command helpers. Full suite green (458 passing).

[what-the-diff]

PR Summary

• Introducing a Social Authentication Feature
  Introduced a social authentication feature using Laravel Socialite. As part of the implementation, we have added a command to scaffold social authentication that sets up routes, migrations and potentially controller stubs. This also includes a markdown file SOCIAL_AUTH.md detailing this new functionality.

• Dependency and Configuration Updates
  Updated our dependency management file, composer.json, to include the necessary software for handling social authentication. This was accompanied by updates to our configuration file to properly set-up social authentication, including defining specific options for individual social media providers.

• New Table for Social Accounts
  A database migration file is added to create a social_accounts table, storing linked accounts from various providers. This allows us to better manage social media linked accounts.

• Implementing Core Functionality in Controllers
  Created controller files for managing the redirection and callback processes for social authentication. These include SocialRedirectController and SocialCallbackController, respectively handling authorisation URL redirection and callback logic for social login.

• Added New Model and Class Definitions
  Introduced a SocialAccount model that represents provider accounts linked to users. We have added necessary namespaces and class definitions that allow implementation of new functionalities in the existing codebase structure. We've also extended the Restify class to handle resolving of users via social media.

• Added New Trait and Updated Service Provider
  A new Trait is introduced to manage linked social accounts easily with user models. A new method also has been implemented in the application service provider to define API routes for the new social authentication.

• Provision of Test Suite
  A suite of tests have been added to ensure proper functioning of the social authentication feature, which includes checks for user linking and token issuance.

• Enhanced User Retrieval with SocialUserResolver
  Created a class - SocialUserResolver. Its purpose is to manage how users are retrieved or created based on their social provider data. This helps in smooth linking between application users and social users.