@strav/social 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.1
+
+### Added
+
+- Facebook provider (Graph API v21.0)
+- LinkedIn provider (OpenID Connect userinfo endpoint)
+
+## 0.1.0
+
+### Added
+
+- Initial release with OAuth 2.0 social authentication
+- Built-in providers: Google, GitHub, Discord
+- `SocialManager` with driver-based architecture and custom provider extensibility
+- Session-based CSRF state verification with `stateless()` opt-out
+- `social` helper for fluent API access
+- `AbstractProvider` base class for building custom providers

package/README.md

@@ -0,0 +1,79 @@
+# @stravigor/social
+
+OAuth social authentication for the [Strav](https://www.npmjs.com/package/@stravigor/core) framework. Sign in with Google, GitHub, Discord, Facebook, and LinkedIn using a fluent, driver-based API.
+
+## Install
+
+```bash
+bun add @stravigor/social
+bun strav install social
+```
+
+Requires `@stravigor/core` as a peer dependency.
+
+## Setup
+
+```ts
+import { SocialProvider } from '@stravigor/social'
+
+app.use(new SocialProvider())
+```
+
+## Usage
+
+```ts
+import { social } from '@stravigor/social'
+
+// Redirect to provider
+r.get('/auth/github', ctx => {
+  return social.driver('github').redirect(ctx)
+})
+
+// Handle callback
+r.get('/auth/github/callback', async ctx => {
+  const githubUser = await social.driver('github').user(ctx)
+
+  // githubUser.id, .name, .email, .avatar, .nickname, .token
+  let user = await User.findBy('email', githubUser.email)
+  if (!user) {
+    user = await User.create({ name: githubUser.name, email: githubUser.email })
+  }
+
+  await social.findOrCreate('github', githubUser, user)
+  // authenticate session...
+})
+```
+
+## Providers
+
+- **Google** — OpenID Connect with Workspace domain restriction
+- **GitHub** — User profile with verified email fallback
+- **Discord** — Profile with computed avatar URLs
+- **Facebook** — Graph API v21.0
+- **LinkedIn** — OpenID Connect userinfo
+
+## Fluent API
+
+```ts
+social.driver('github').scopes(['repo', 'gist']).redirect(ctx)
+social.driver('google').with({ hd: 'example.com' }).redirect(ctx)
+social.driver('google').stateless().redirect(ctx)
+const user = await social.driver('google').userFromToken(accessToken)
+```
+
+## Custom Providers
+
+```ts
+import { AbstractProvider, social } from '@stravigor/social'
+
+class SpotifyProvider extends AbstractProvider { /* ... */ }
+social.extend('spotify', config => new SpotifyProvider(config))
+```
+
+## Documentation
+
+See the full [Social guide](../../guides/social.md).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@strav/social",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OAuth social authentication for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src/",
+    "stubs/",
+    "package.json",
+    "tsconfig.json",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@strav/kernel": "0.1.0",
+    "@strav/http": "0.1.0",
+    "@strav/database": "0.1.0"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/abstract_provider.ts

@@ -0,0 +1,171 @@
+import type { Context, Session } from '@stravigor/http'
+import { randomHex, ExternalServiceError } from '@stravigor/kernel'
+import type { ProviderConfig, SocialUser, TokenResponse } from './types.ts'
+
+const STATE_KEY = 'social_state'
+
+export abstract class AbstractProvider {
+  abstract readonly name: string
+
+  protected config: ProviderConfig
+  protected _scopes: string[]
+  protected _stateless = false
+  protected _parameters: Record<string, string> = {}
+
+  constructor(config: ProviderConfig) {
+    this.config = config
+    this._scopes = config.scopes ?? this.getDefaultScopes()
+  }
+
+  // ---------------------------------------------------------------------------
+  // Template methods — each provider implements these
+  // ---------------------------------------------------------------------------
+
+  protected abstract getDefaultScopes(): string[]
+  protected abstract getAuthUrl(): string
+  protected abstract getTokenUrl(): string
+  protected abstract getUserByToken(token: string): Promise<Record<string, unknown>>
+  protected abstract mapUserToObject(data: Record<string, unknown>): SocialUser
+
+  // ---------------------------------------------------------------------------
+  // Fluent API
+  // ---------------------------------------------------------------------------
+
+  scopes(scopes: string[]): this {
+    this._scopes = [...new Set([...this._scopes, ...scopes])]
+    return this
+  }
+
+  setScopes(scopes: string[]): this {
+    this._scopes = scopes
+    return this
+  }
+
+  stateless(): this {
+    this._stateless = true
+    return this
+  }
+
+  with(params: Record<string, string>): this {
+    this._parameters = { ...this._parameters, ...params }
+    return this
+  }
+
+  // ---------------------------------------------------------------------------
+  // OAuth flow
+  // ---------------------------------------------------------------------------
+
+  redirect(ctx: Context): Response {
+    let state: string | undefined
+
+    if (!this._stateless) {
+      state = randomHex(32)
+      const session = ctx.get<Session>('session')
+      session.set(STATE_KEY, state)
+    }
+
+    const url = this.buildAuthUrl(state)
+    return ctx.redirect(url)
+  }
+
+  async user(ctx: Context): Promise<SocialUser> {
+    if (!this._stateless) {
+      const session = ctx.get<Session>('session')
+      const expectedState = session.get<string>(STATE_KEY)
+      const returnedState = ctx.query.get('state')
+
+      if (!expectedState || expectedState !== returnedState) {
+        throw new SocialError('Invalid state parameter. Possible CSRF attack.')
+      }
+
+      session.forget(STATE_KEY)
+    }
+
+    const code = ctx.query.get('code')
+    if (!code) {
+      const error = ctx.query.get('error')
+      throw new SocialError(error ? `OAuth error: ${error}` : 'Missing authorization code.')
+    }
+
+    const token = await this.getAccessToken(code)
+    const data = await this.getUserByToken(token.accessToken)
+    const user = this.mapUserToObject(data)
+
+    user.token = token.accessToken
+    user.refreshToken = token.refreshToken
+    user.expiresIn = token.expiresIn
+    user.approvedScopes = token.scope ? token.scope.split(/[\s,]+/) : this._scopes
+    user.raw = data
+
+    return user
+  }
+
+  async userFromToken(token: string): Promise<SocialUser> {
+    const data = await this.getUserByToken(token)
+    const user = this.mapUserToObject(data)
+
+    user.token = token
+    user.refreshToken = null
+    user.expiresIn = null
+    user.approvedScopes = this._scopes
+    user.raw = data
+
+    return user
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  protected async getAccessToken(code: string): Promise<TokenResponse> {
+    const response = await fetch(this.getTokenUrl(), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+      },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+        code,
+        redirect_uri: this.config.redirectUrl,
+      }),
+    })
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new ExternalServiceError(this.name, response.status, text)
+    }
+
+    const data = (await response.json()) as Record<string, unknown>
+
+    return {
+      accessToken: data.access_token as string,
+      refreshToken: (data.refresh_token as string) ?? null,
+      expiresIn: (data.expires_in as number) ?? null,
+      scope: (data.scope as string) ?? null,
+    }
+  }
+
+  protected buildAuthUrl(state?: string): string {
+    const params = new URLSearchParams({
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUrl,
+      response_type: 'code',
+      scope: this._scopes.join(' '),
+      ...this._parameters,
+    })
+
+    if (state) params.set('state', state)
+
+    return `${this.getAuthUrl()}?${params.toString()}`
+  }
+}
+
+export class SocialError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SocialError'
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,31 @@
+import type { AbstractProvider } from './abstract_provider.ts'
+import SocialAccount from './social_account.ts'
+import SocialManager from './social_manager.ts'
+import type { ProviderConfig, SocialUser } from './types.ts'
+import type { SocialAccountData } from './social_account.ts'
+
+export const social = {
+  driver(name: string): AbstractProvider {
+    return SocialManager.driver(name)
+  },
+
+  extend(name: string, factory: (config: ProviderConfig) => AbstractProvider): void {
+    SocialManager.extend(name, factory)
+  },
+
+  /**
+   * Find an existing social account by provider or create a new one.
+   * If the account already exists, its tokens are updated.
+   *
+   * @example
+   * const socialUser = await social.driver('google').user(ctx)
+   * const { account, created } = await social.findOrCreate('google', socialUser, user)
+   */
+  findOrCreate(
+    provider: string,
+    socialUser: SocialUser,
+    user: unknown
+  ): Promise<{ account: SocialAccountData; created: boolean }> {
+    return SocialAccount.findOrCreate(provider, socialUser, user)
+  },
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { default, default as SocialManager } from './social_manager.ts'
+
+// Provider
+export { default as SocialProvider } from './social_provider.ts'
+export { default as SocialAccount } from './social_account.ts'
+export { social } from './helpers.ts'
+export { AbstractProvider, SocialError } from './abstract_provider.ts'
+export { GoogleProvider } from './providers/google_provider.ts'
+export { GitHubProvider } from './providers/github_provider.ts'
+export { DiscordProvider } from './providers/discord_provider.ts'
+export { FacebookProvider } from './providers/facebook_provider.ts'
+export { LinkedInProvider } from './providers/linkedin_provider.ts'
+export type { SocialUser, SocialConfig, ProviderConfig, TokenResponse } from './types.ts'
+export type { SocialAccountData } from './social_account.ts'

package/src/providers/discord_provider.ts

@@ -0,0 +1,54 @@
+import { ExternalServiceError } from '@stravigor/kernel'
+import { AbstractProvider } from '../abstract_provider.ts'
+import type { SocialUser } from '../types.ts'
+
+export class DiscordProvider extends AbstractProvider {
+  readonly name = 'Discord'
+
+  protected getDefaultScopes(): string[] {
+    return ['identify', 'email']
+  }
+
+  protected getAuthUrl(): string {
+    return 'https://discord.com/api/oauth2/authorize'
+  }
+
+  protected getTokenUrl(): string {
+    return 'https://discord.com/api/oauth2/token'
+  }
+
+  protected async getUserByToken(token: string): Promise<Record<string, unknown>> {
+    const response = await fetch('https://discord.com/api/v10/users/@me', {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+
+    if (!response.ok) {
+      throw new ExternalServiceError('Discord', response.status, await response.text())
+    }
+
+    return (await response.json()) as Record<string, unknown>
+  }
+
+  protected mapUserToObject(data: Record<string, unknown>): SocialUser {
+    let avatar: string | null = null
+    if (data.avatar) {
+      avatar = `https://cdn.discordapp.com/avatars/${data.id}/${data.avatar}.png`
+    } else if (data.id) {
+      const index = Number((BigInt(data.id as string) >> 22n) % 6n)
+      avatar = `https://cdn.discordapp.com/embed/avatars/${index}.png`
+    }
+
+    return {
+      id: data.id as string,
+      name: (data.global_name as string) ?? null,
+      email: (data.email as string) ?? null,
+      avatar,
+      nickname: (data.username as string) ?? null,
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      approvedScopes: [],
+      raw: data,
+    }
+  }
+}

package/src/providers/facebook_provider.ts

@@ -0,0 +1,51 @@
+import { ExternalServiceError } from '@stravigor/kernel'
+import { AbstractProvider } from '../abstract_provider.ts'
+import type { SocialUser } from '../types.ts'
+
+const API_VERSION = 'v21.0'
+
+export class FacebookProvider extends AbstractProvider {
+  readonly name = 'Facebook'
+
+  protected getDefaultScopes(): string[] {
+    return ['email', 'public_profile']
+  }
+
+  protected getAuthUrl(): string {
+    return `https://www.facebook.com/${API_VERSION}/dialog/oauth`
+  }
+
+  protected getTokenUrl(): string {
+    return `https://graph.facebook.com/${API_VERSION}/oauth/access_token`
+  }
+
+  protected async getUserByToken(token: string): Promise<Record<string, unknown>> {
+    const fields = 'id,name,email,picture.type(large)'
+    const response = await fetch(
+      `https://graph.facebook.com/${API_VERSION}/me?fields=${fields}&access_token=${token}`
+    )
+
+    if (!response.ok) {
+      throw new ExternalServiceError('Facebook', response.status, await response.text())
+    }
+
+    return (await response.json()) as Record<string, unknown>
+  }
+
+  protected mapUserToObject(data: Record<string, unknown>): SocialUser {
+    const picture = data.picture as { data?: { url?: string } } | undefined
+
+    return {
+      id: data.id as string,
+      name: (data.name as string) ?? null,
+      email: (data.email as string) ?? null,
+      avatar: picture?.data?.url ?? null,
+      nickname: null,
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      approvedScopes: [],
+      raw: data,
+    }
+  }
+}

package/src/providers/github_provider.ts

@@ -0,0 +1,66 @@
+import { ExternalServiceError } from '@stravigor/kernel'
+import { AbstractProvider } from '../abstract_provider.ts'
+import type { SocialUser } from '../types.ts'
+
+export class GitHubProvider extends AbstractProvider {
+  readonly name = 'GitHub'
+
+  protected getDefaultScopes(): string[] {
+    return ['read:user', 'user:email']
+  }
+
+  protected getAuthUrl(): string {
+    return 'https://github.com/login/oauth/authorize'
+  }
+
+  protected getTokenUrl(): string {
+    return 'https://github.com/login/oauth/access_token'
+  }
+
+  protected async getUserByToken(token: string): Promise<Record<string, unknown>> {
+    const headers = {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/json',
+      'User-Agent': 'Strav-Social',
+    }
+
+    const [userResponse, emailsResponse] = await Promise.all([
+      fetch('https://api.github.com/user', { headers }),
+      fetch('https://api.github.com/user/emails', { headers }),
+    ])
+
+    if (!userResponse.ok) {
+      throw new ExternalServiceError('GitHub', userResponse.status, await userResponse.text())
+    }
+
+    const user = (await userResponse.json()) as Record<string, unknown>
+
+    // If the user's profile email is private, fall back to the primary verified email
+    if (!user.email && emailsResponse.ok) {
+      const emails = (await emailsResponse.json()) as Array<{
+        email: string
+        primary: boolean
+        verified: boolean
+      }>
+      const primary = emails.find(e => e.primary && e.verified)
+      if (primary) user.email = primary.email
+    }
+
+    return user
+  }
+
+  protected mapUserToObject(data: Record<string, unknown>): SocialUser {
+    return {
+      id: String(data.id),
+      name: (data.name as string) ?? null,
+      email: (data.email as string) ?? null,
+      avatar: (data.avatar_url as string) ?? null,
+      nickname: (data.login as string) ?? null,
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      approvedScopes: [],
+      raw: data,
+    }
+  }
+}

package/src/providers/google_provider.ts

@@ -0,0 +1,46 @@
+import { ExternalServiceError } from '@stravigor/kernel'
+import { AbstractProvider } from '../abstract_provider.ts'
+import type { SocialUser } from '../types.ts'
+
+export class GoogleProvider extends AbstractProvider {
+  readonly name = 'Google'
+
+  protected getDefaultScopes(): string[] {
+    return ['openid', 'email', 'profile']
+  }
+
+  protected getAuthUrl(): string {
+    return 'https://accounts.google.com/o/oauth2/v2/auth'
+  }
+
+  protected getTokenUrl(): string {
+    return 'https://oauth2.googleapis.com/token'
+  }
+
+  protected async getUserByToken(token: string): Promise<Record<string, unknown>> {
+    const response = await fetch('https://www.googleapis.com/oauth2/v3/userinfo', {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+
+    if (!response.ok) {
+      throw new ExternalServiceError('Google', response.status, await response.text())
+    }
+
+    return (await response.json()) as Record<string, unknown>
+  }
+
+  protected mapUserToObject(data: Record<string, unknown>): SocialUser {
+    return {
+      id: data.sub as string,
+      name: (data.name as string) ?? null,
+      email: (data.email as string) ?? null,
+      avatar: (data.picture as string) ?? null,
+      nickname: null,
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      approvedScopes: [],
+      raw: data,
+    }
+  }
+}

package/src/providers/linkedin_provider.ts

@@ -0,0 +1,46 @@
+import { ExternalServiceError } from '@stravigor/kernel'
+import { AbstractProvider } from '../abstract_provider.ts'
+import type { SocialUser } from '../types.ts'
+
+export class LinkedInProvider extends AbstractProvider {
+  readonly name = 'LinkedIn'
+
+  protected getDefaultScopes(): string[] {
+    return ['openid', 'profile', 'email']
+  }
+
+  protected getAuthUrl(): string {
+    return 'https://www.linkedin.com/oauth/v2/authorization'
+  }
+
+  protected getTokenUrl(): string {
+    return 'https://www.linkedin.com/oauth/v2/accessToken'
+  }
+
+  protected async getUserByToken(token: string): Promise<Record<string, unknown>> {
+    const response = await fetch('https://api.linkedin.com/v2/userinfo', {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+
+    if (!response.ok) {
+      throw new ExternalServiceError('LinkedIn', response.status, await response.text())
+    }
+
+    return (await response.json()) as Record<string, unknown>
+  }
+
+  protected mapUserToObject(data: Record<string, unknown>): SocialUser {
+    return {
+      id: data.sub as string,
+      name: (data.name as string) ?? null,
+      email: (data.email as string) ?? null,
+      avatar: (data.picture as string) ?? null,
+      nickname: null,
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      approvedScopes: [],
+      raw: data,
+    }
+  }
+}

package/src/schema.ts

@@ -0,0 +1,13 @@
+import { defineSchema, t, Archetype } from '@stravigor/database'
+
+export const schema = defineSchema('social_account', {
+  archetype: Archetype.Component,
+  parents: ['user'],
+  fields: {
+    provider: t.varchar(50).required().index(),
+    providerId: t.varchar(255).required().index(),
+    token: t.text().required().sensitive(),
+    refreshToken: t.text().nullable().sensitive(),
+    expiresAt: t.timestamptz().nullable(),
+  },
+})

package/src/social_account.ts

@@ -0,0 +1,184 @@
+import { extractUserId } from '@stravigor/database'
+import SocialManager from './social_manager.ts'
+import type { SocialUser } from './types.ts'
+
+/** The DB record for a social account link. */
+export interface SocialAccountData {
+  id: number
+  userId: string | number
+  provider: string
+  providerId: string
+  token: string
+  refreshToken: string | null
+  expiresAt: Date | null
+  createdAt: Date
+  updatedAt: Date
+}
+
+/**
+ * Static helper for managing social account records.
+ *
+ * Follows the same pattern as AccessToken: all methods are static,
+ * database access goes through the parent manager (SocialManager.db).
+ *
+ * @example
+ * const account = await SocialAccount.findByProvider('github', '12345')
+ * const accounts = await SocialAccount.findByUser(user)
+ * const created = await SocialAccount.create({ user, provider: 'google', ... })
+ */
+export default class SocialAccount {
+  private static get sql() {
+    return SocialManager.db.sql
+  }
+
+  private static get fk() {
+    return SocialManager.userFkColumn
+  }
+
+  /**
+   * Find a social account by provider name and provider-specific user ID.
+   * This is the primary lookup used during OAuth callback.
+   */
+  static async findByProvider(
+    provider: string,
+    providerId: string
+  ): Promise<SocialAccountData | null> {
+    const rows = await SocialAccount.sql`
+      SELECT * FROM "social_account"
+      WHERE "provider" = ${provider}
+        AND "provider_id" = ${providerId}
+      LIMIT 1
+    `
+    return rows.length > 0 ? SocialAccount.hydrate(rows[0] as Record<string, unknown>) : null
+  }
+
+  /**
+   * Find all social accounts linked to a user.
+   */
+  static async findByUser(user: unknown): Promise<SocialAccountData[]> {
+    const userId = extractUserId(user)
+    const fk = SocialAccount.fk
+    const rows = await SocialAccount.sql.unsafe(
+      `SELECT * FROM "social_account" WHERE "${fk}" = $1 ORDER BY "created_at" ASC`,
+      [userId]
+    )
+    return rows.map((r: any) => SocialAccount.hydrate(r))
+  }
+
+  /**
+   * Create a new social account link.
+   */
+  static async create(data: {
+    user: unknown
+    provider: string
+    providerId: string
+    token: string
+    refreshToken?: string | null
+    expiresAt?: Date | null
+  }): Promise<SocialAccountData> {
+    const userId = extractUserId(data.user)
+    const fk = SocialAccount.fk
+    const rows = await SocialAccount.sql.unsafe(
+      `INSERT INTO "social_account" ("${fk}", "provider", "provider_id", "token", "refresh_token", "expires_at")
+       VALUES ($1, $2, $3, $4, $5, $6)
+       RETURNING *`,
+      [
+        userId,
+        data.provider,
+        data.providerId,
+        data.token,
+        data.refreshToken ?? null,
+        data.expiresAt ?? null,
+      ]
+    )
+    return SocialAccount.hydrate(rows[0] as Record<string, unknown>)
+  }
+
+  /**
+   * Find an existing social account by provider or create a new one.
+   * If the account already exists, its tokens are updated.
+   */
+  static async findOrCreate(
+    provider: string,
+    socialUser: SocialUser,
+    user: unknown
+  ): Promise<{ account: SocialAccountData; created: boolean }> {
+    const existing = await SocialAccount.findByProvider(provider, socialUser.id)
+    if (existing) {
+      await SocialAccount.updateTokens(
+        existing.id,
+        socialUser.token,
+        socialUser.refreshToken,
+        socialUser.expiresIn ? new Date(Date.now() + socialUser.expiresIn * 1000) : null
+      )
+      existing.token = socialUser.token
+      existing.refreshToken = socialUser.refreshToken
+      existing.expiresAt = socialUser.expiresIn
+        ? new Date(Date.now() + socialUser.expiresIn * 1000)
+        : null
+      return { account: existing, created: false }
+    }
+
+    const account = await SocialAccount.create({
+      user,
+      provider,
+      providerId: socialUser.id,
+      token: socialUser.token,
+      refreshToken: socialUser.refreshToken,
+      expiresAt: socialUser.expiresIn ? new Date(Date.now() + socialUser.expiresIn * 1000) : null,
+    })
+    return { account, created: true }
+  }
+
+  /**
+   * Update OAuth tokens for an existing social account.
+   */
+  static async updateTokens(
+    id: number,
+    token: string,
+    refreshToken: string | null,
+    expiresAt: Date | null
+  ): Promise<void> {
+    await SocialAccount.sql`
+      UPDATE "social_account"
+      SET "token" = ${token},
+          "refresh_token" = ${refreshToken},
+          "expires_at" = ${expiresAt},
+          "updated_at" = NOW()
+      WHERE "id" = ${id}
+    `
+  }
+
+  /** Delete a social account by its database ID. */
+  static async delete(id: number): Promise<void> {
+    await SocialAccount.sql`
+      DELETE FROM "social_account" WHERE "id" = ${id}
+    `
+  }
+
+  /** Delete all social accounts for a user. */
+  static async deleteByUser(user: unknown): Promise<void> {
+    const userId = extractUserId(user)
+    const fk = SocialAccount.fk
+    await SocialAccount.sql.unsafe(`DELETE FROM "social_account" WHERE "${fk}" = $1`, [userId])
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private static hydrate(row: Record<string, unknown>): SocialAccountData {
+    const fk = SocialAccount.fk
+    return {
+      id: row.id as number,
+      userId: row[fk] as string | number,
+      provider: row.provider as string,
+      providerId: row.provider_id as string,
+      token: row.token as string,
+      refreshToken: (row.refresh_token as string) ?? null,
+      expiresAt: (row.expires_at as Date) ?? null,
+      createdAt: row.created_at as Date,
+      updatedAt: row.updated_at as Date,
+    }
+  }
+}

package/src/social_manager.ts

@@ -0,0 +1,95 @@
+import { inject, Configuration, ConfigurationError } from '@stravigor/kernel'
+import { Database, toSnakeCase } from '@stravigor/database'
+import type { AbstractProvider } from './abstract_provider.ts'
+import type { ProviderConfig, SocialConfig } from './types.ts'
+import { GoogleProvider } from './providers/google_provider.ts'
+import { GitHubProvider } from './providers/github_provider.ts'
+import { DiscordProvider } from './providers/discord_provider.ts'
+import { FacebookProvider } from './providers/facebook_provider.ts'
+import { LinkedInProvider } from './providers/linkedin_provider.ts'
+
+@inject
+export default class SocialManager {
+  private static _db: Database
+  private static _config: SocialConfig
+  private static _userFkColumn: string
+  private static _extensions = new Map<string, (config: ProviderConfig) => AbstractProvider>()
+
+  constructor(db: Database, config: Configuration) {
+    SocialManager._db = db
+
+    const userKey = config.get('social.userKey', 'id') as string
+    SocialManager._userFkColumn = `user_${toSnakeCase(userKey)}`
+
+    SocialManager._config = {
+      userKey,
+      providers: config.get('social.providers', {}) as Record<string, ProviderConfig>,
+    }
+  }
+
+  static get db(): Database {
+    if (!SocialManager._db) {
+      throw new ConfigurationError(
+        'SocialManager not configured. Resolve it through the container first.'
+      )
+    }
+    return SocialManager._db
+  }
+
+  static get config(): SocialConfig {
+    if (!SocialManager._config) {
+      throw new ConfigurationError(
+        'SocialManager not configured. Resolve it through the container first.'
+      )
+    }
+    return SocialManager._config
+  }
+
+  /** The FK column name on the social_account table (e.g. `user_id`, `user_uid`). */
+  static get userFkColumn(): string {
+    return SocialManager._userFkColumn ?? 'user_id'
+  }
+
+  /**
+   * Get a fresh provider instance by name.
+   * Returns a new instance each call because fluent methods mutate state.
+   */
+  static driver(name: string): AbstractProvider {
+    const providerConfig = SocialManager._config?.providers[name]
+    if (!providerConfig) {
+      throw new ConfigurationError(`Social provider "${name}" is not configured.`)
+    }
+
+    const driverName = providerConfig.driver ?? name
+
+    const extension = SocialManager._extensions.get(driverName)
+    if (extension) return extension(providerConfig)
+
+    switch (driverName) {
+      case 'google':
+        return new GoogleProvider(providerConfig)
+      case 'github':
+        return new GitHubProvider(providerConfig)
+      case 'discord':
+        return new DiscordProvider(providerConfig)
+      case 'facebook':
+        return new FacebookProvider(providerConfig)
+      case 'linkedin':
+        return new LinkedInProvider(providerConfig)
+      default:
+        throw new ConfigurationError(
+          `Unknown social driver "${driverName}". Register it with SocialManager.extend().`
+        )
+    }
+  }
+
+  /** Register a custom provider factory. */
+  static extend(name: string, factory: (config: ProviderConfig) => AbstractProvider): void {
+    SocialManager._extensions.set(name, factory)
+  }
+
+  /** Clear all custom extensions (useful for testing). */
+  static reset(): void {
+    SocialManager._extensions.clear()
+  }
+}

package/src/social_provider.ts

@@ -0,0 +1,16 @@
+import { ServiceProvider } from '@stravigor/kernel'
+import type { Application } from '@stravigor/kernel'
+import SocialManager from './social_manager.ts'
+
+export default class SocialProvider extends ServiceProvider {
+  readonly name = 'social'
+  override readonly dependencies = ['database']
+
+  override register(app: Application): void {
+    app.singleton(SocialManager)
+  }
+
+  override boot(app: Application): void {
+    app.resolve(SocialManager)
+  }
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+export interface SocialUser {
+  id: string
+  name: string | null
+  email: string | null
+  avatar: string | null
+  nickname: string | null
+  token: string
+  refreshToken: string | null
+  expiresIn: number | null
+  approvedScopes: string[]
+  raw: Record<string, unknown>
+}
+
+export interface ProviderConfig {
+  driver?: string
+  clientId: string
+  clientSecret: string
+  redirectUrl: string
+  scopes?: string[]
+}
+
+export interface SocialConfig {
+  userKey: string
+  providers: Record<string, ProviderConfig>
+}
+
+export interface TokenResponse {
+  accessToken: string
+  refreshToken: string | null
+  expiresIn: number | null
+  scope: string | null
+}

package/stubs/config/social.ts

@@ -0,0 +1,22 @@
+import { env } from '@stravigor/kernel'
+
+export default {
+  userKey: 'id',
+  providers: {
+    // google: {
+    //   clientId: env('GOOGLE_CLIENT_ID', ''),
+    //   clientSecret: env('GOOGLE_CLIENT_SECRET', ''),
+    //   redirectUrl: env('GOOGLE_REDIRECT_URL', 'http://localhost:3000/auth/google/callback'),
+    // },
+    // github: {
+    //   clientId: env('GITHUB_CLIENT_ID', ''),
+    //   clientSecret: env('GITHUB_CLIENT_SECRET', ''),
+    //   redirectUrl: env('GITHUB_REDIRECT_URL', 'http://localhost:3000/auth/github/callback'),
+    // },
+    // discord: {
+    //   clientId: env('DISCORD_CLIENT_ID', ''),
+    //   clientSecret: env('DISCORD_CLIENT_SECRET', ''),
+    //   redirectUrl: env('DISCORD_REDIRECT_URL', 'http://localhost:3000/auth/discord/callback'),
+    // },
+  },
+}

package/stubs/schemas/social_account.ts

@@ -0,0 +1,13 @@
+import { defineSchema, t, Archetype } from '@stravigor/database'
+
+export default defineSchema('social_account', {
+  archetype: Archetype.Component,
+  parents: ['user'],
+  fields: {
+    provider: t.varchar(50).required().index(),
+    providerId: t.varchar(255).required().index(),
+    token: t.text().required().sensitive(),
+    refreshToken: t.text().nullable().sensitive(),
+    expiresAt: t.timestamptz().nullable(),
+  },
+})

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "tests"]
+}