Identity Socialstream Laravel Package

Product Decisions This Supports

• Social sign-in roadmap: Whether to ship "Sign in with Google/GitHub/Apple/etc." this sprint. This package is the glue between Laravel Socialite/Socialstream OAuth flows and Liberu's identity module, so the decision becomes "enable adapter + configure providers" instead of a bespoke OAuth integration per provider.
• Build vs. buy for identity linking: It replaces the custom callback handling, provider-token storage, and provider-to-user mapping you would otherwise write and maintain. Use it to collapse a multi-week integration estimate into days — but budget for vendor/fork risk (see below).
• Account linking and identity unification: Supports product rules for one-person-one-account: linking a social identity to an existing email/password account, unlinking, handling duplicate accounts created via different providers, and account recovery paths. These are policy decisions as much as technical ones.
• Onboarding funnel and conversion: Social login directly targets registration friction. This package makes it cheap to A/B test provider sets (Google-only vs. Google+GitHub) and measure signup completion rate and time-to-first-value.
• Consumer vs. enterprise segmentation: Social providers are a B2C/PLG motion. Adopting this clarifies that enterprise SSO (SAML/OIDC, SCIM provisioning, enforced MFA) remains a separate roadmap item rather than something this adapter covers.
• Data model and tenancy: Commits you to an identity-link table shape and link/unlink lifecycle. If Socialstream's team support matters, this influences multi-tenant membership and invitation decisions.
• Provider portfolio scope: Each additional provider is configuration, not new architecture — useful when deciding how broad the launch provider list should be.

When to Consider This Package

Consider it when:

• You are building on Laravel/PHP and already use, or plan to use, Laravel Socialite and Socialstream.
• Identity is (or will be) handled by the Liberu identity module; this adapter assumes those conventions.
• You need breadth of social providers quickly and want linking/unlinking behavior without writing per-provider glue.
• Your team is small enough to vendor or fork an MIT-licensed package and own a pinned version.
• Social login is a growth/onboarding feature, not a regulated security boundary.

Look elsewhere when:

• You are not on Laravel or not using Socialstream — the abstraction cost outweighs the benefit.
• You need enterprise SSO (SAML, SCIM, OIDC federation), enforced MFA policy, or audited access controls.
• You require compliance evidence, an SLA, or vendor support — an MIT package with a single maintainer does not provide it.
• Ecosystem maturity matters: 0 stars and 0 dependents means no community troubleshooting, few external bug reports, and no signal of production usage. Treat adoption risk as real.
• You need deep customization of token handling, refresh logic, or provider-specific edge cases that would fight the adapter's opinions.
• You cannot accept coupling to Liberu module conventions in your core user model.

How to Pitch It (Stakeholders)

For executives: Social sign-in is a measurable conversion lever — fewer abandoned signups, faster time-to-first-action. This package is a small MIT-licensed adapter that lets us ship it in days rather than building OAuth linking ourselves, at effectively zero license cost. The trade-off is maturity: it is a young, single-maintainer component with no visible downstream adoption, so we should treat it as a swappable part, not a platform commitment. Recommendation: pilot behind a feature flag, measure signup completion lift, and keep a fork/exit path. Low downside, clear upside.

For engineering: It is a thin provider adapter over Socialite/Socialstream that handles identity linking against the Liberu identity module. Integrate behind our own interface (e.g., an IdentityLinker contract) so the dependency never leaks into domain models — map its records into our user/identity schema. Pin the version, add contract and integration tests around link/unlink/duplicate-account cases, and watch upstream releases (cadence looks active). Assume we may need to fork; keep the diff surface small enough that forking stays a day's work, not a quarter's.