@stravigor/socialite 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+### Added
+
+- Initial release with OAuth 2.0 social authentication
+- Built-in providers: Google, GitHub, Discord
+- `SocialiteManager` with driver-based architecture and custom provider extensibility
+- Session-based CSRF state verification with `stateless()` opt-out
+- `socialite` helper for fluent API access
+- `AbstractProvider` base class for building custom providers

package/package.json

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

package/src/abstract_provider.ts

@@ -0,0 +1,173 @@
+import type Context from '@stravigor/core/http/context'
+import type Session from '@stravigor/core/session/session'
+import { randomHex } from '@stravigor/core/helpers/crypto'
+import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
+import type { ProviderConfig, SocialiteUser, TokenResponse } from './types.ts'
+
+const STATE_KEY = 'socialite_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>): SocialiteUser
+
+  // ---------------------------------------------------------------------------
+  // 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<SocialiteUser> {
+    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 SocialiteError('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 SocialiteError(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<SocialiteUser> {
+    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 SocialiteError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SocialiteError'
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,13 @@
+import type { AbstractProvider } from './abstract_provider.ts'
+import SocialiteManager from './socialite_manager.ts'
+import type { ProviderConfig } from './types.ts'
+
+export const socialite = {
+  driver(name: string): AbstractProvider {
+    return SocialiteManager.driver(name)
+  },
+
+  extend(name: string, factory: (config: ProviderConfig) => AbstractProvider): void {
+    SocialiteManager.extend(name, factory)
+  },
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { default, default as SocialiteManager } from './socialite_manager.ts'
+export { socialite } from './helpers.ts'
+export { AbstractProvider, SocialiteError } 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 type { SocialiteUser, SocialiteConfig, ProviderConfig, TokenResponse } from './types.ts'

package/src/providers/discord_provider.ts

@@ -0,0 +1,54 @@
+import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
+import { AbstractProvider } from '../abstract_provider.ts'
+import type { SocialiteUser } 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>): SocialiteUser {
+    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/github_provider.ts

@@ -0,0 +1,66 @@
+import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
+import { AbstractProvider } from '../abstract_provider.ts'
+import type { SocialiteUser } 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-Socialite',
+    }
+
+    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>): SocialiteUser {
+    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/core/exceptions/errors'
+import { AbstractProvider } from '../abstract_provider.ts'
+import type { SocialiteUser } 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>): SocialiteUser {
+    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/socialite_manager.ts

@@ -0,0 +1,68 @@
+import { inject } from '@stravigor/core/core'
+import type Configuration from '@stravigor/core/config/configuration'
+import { ConfigurationError } from '@stravigor/core/exceptions/errors'
+import type { AbstractProvider } from './abstract_provider.ts'
+import type { ProviderConfig, SocialiteConfig } from './types.ts'
+import { GoogleProvider } from './providers/google_provider.ts'
+import { GitHubProvider } from './providers/github_provider.ts'
+import { DiscordProvider } from './providers/discord_provider.ts'
+
+@inject
+export default class SocialiteManager {
+  private static _config: SocialiteConfig
+  private static _extensions = new Map<string, (config: ProviderConfig) => AbstractProvider>()
+
+  constructor(config: Configuration) {
+    SocialiteManager._config = {
+      providers: config.get('socialite.providers', {}) as Record<string, ProviderConfig>,
+    }
+  }
+
+  static get config(): SocialiteConfig {
+    if (!SocialiteManager._config) {
+      throw new ConfigurationError(
+        'SocialiteManager not configured. Resolve it through the container first.'
+      )
+    }
+    return SocialiteManager._config
+  }
+
+  /**
+   * 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 = SocialiteManager._config?.providers[name]
+    if (!providerConfig) {
+      throw new ConfigurationError(`Socialite provider "${name}" is not configured.`)
+    }
+
+    const driverName = providerConfig.driver ?? name
+
+    const extension = SocialiteManager._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)
+      default:
+        throw new ConfigurationError(
+          `Unknown socialite driver "${driverName}". Register it with SocialiteManager.extend().`
+        )
+    }
+  }
+
+  /** Register a custom provider factory. */
+  static extend(name: string, factory: (config: ProviderConfig) => AbstractProvider): void {
+    SocialiteManager._extensions.set(name, factory)
+  }
+
+  /** Clear all custom extensions (useful for testing). */
+  static reset(): void {
+    SocialiteManager._extensions.clear()
+  }
+}

package/src/types.ts

@@ -0,0 +1,31 @@
+export interface SocialiteUser {
+  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 SocialiteConfig {
+  providers: Record<string, ProviderConfig>
+}
+
+export interface TokenResponse {
+  accessToken: string
+  refreshToken: string | null
+  expiresIn: number | null
+  scope: string | null
+}

package/tsconfig.json

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