@strav/social 0.4.31 → 1.0.0-alpha.24

package/src/types.ts

@@ -1,49 +1,21 @@
-export interface SocialUser {
-  id: string
-  name: string | null
-  email: string | null
-  /**
-   * Whether the provider asserts the email has been verified by the user.
-   *
-   * Callers MUST check this before using `email` to match an existing
-   * application user — linking by an unverified email is a known account-
-   * takeover vector. See packages/social/CLAUDE.md ("Verified-email gate").
-   */
-  emailVerified: boolean
-  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[]
-  /**
-   * How to authenticate with the provider's token endpoint. Default
-   * `'basic'` (HTTP Basic auth — RFC 6749 §2.3.1, MUST-support, keeps
-   * `client_secret` out of body-logging surfaces). `'post'` falls back
-   * to `client_secret` in the request body for providers that don't
-   * accept Basic (e.g. Facebook). The `social` package picks the right
-   * default per provider but you can override here if needed.
-   */
-  tokenEndpointAuthMethod?: 'basic' | 'post'
-}
+/**
+ * `@strav/social` — runtime config shape.
+ *
+ * Multi-provider by default — apps register one entry per
+ * provider they want available (e.g. `line`, `google`,
+ * `facebook`). The driver field discriminates the adapter; the
+ * rest is driver-specific (`clientId`, `clientSecret`, …).
+ */
 
 export interface SocialConfig {
-  userKey: string
+  /** Default routing target for unqualified `social.*` calls. Keyed into `providers`. */
+  default: string
   providers: Record<string, ProviderConfig>
 }
 
-export interface TokenResponse {
-  accessToken: string
-  refreshToken: string | null
-  expiresIn: number | null
-  scope: string | null
+export interface ProviderConfig {
+  /** Driver identifier — must match a built-in (`'line'` / `'google'` / `'facebook'`) or a name registered via `manager.extend(name, factory)`. */
+  driver: string
+  /** Driver-specific fields — see each adapter's `*Config`. */
+  [key: string]: unknown
 }

package/CHANGELOG.md

@@ -1,19 +0,0 @@
-# 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

@@ -1,78 +0,0 @@
-# @strav/social
-
-OAuth social authentication for the [Strav](https://www.npmjs.com/package/@strav/core) framework. Sign in with Google, GitHub, Discord, Facebook, and LinkedIn using a fluent, driver-based API.
-
-## Install
-
-```bash
-bun add @strav/social
-bun strav install social
-```
-
-Requires `@strav/core` as a peer dependency.
-
-## Setup
-
-```ts
-import { SocialProvider } from '@strav/social'
-
-app.use(new SocialProvider())
-```
-
-## Usage
-
-```ts
-import { social } from '@strav/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)
-const user = await social.driver('google').userFromToken(accessToken)
-```
-
-## Custom Providers
-
-```ts
-import { AbstractProvider, social } from '@strav/social'
-
-class SpotifyProvider extends AbstractProvider { /* ... */ }
-social.extend('spotify', config => new SpotifyProvider(config))
-```
-
-## Documentation
-
-See the full [Social guide](../../guides/social.md).
-
-## License
-
-MIT

package/src/abstract_provider.ts

@@ -1,182 +0,0 @@
-import type { Context, Session } from '@strav/http'
-import { randomHex, ExternalServiceError, scrubProviderError } from '@strav/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 _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
-  }
-
-  with(params: Record<string, string>): this {
-    this._parameters = { ...this._parameters, ...params }
-    return this
-  }
-
-  // ---------------------------------------------------------------------------
-  // OAuth flow
-  // ---------------------------------------------------------------------------
-
-  redirect(ctx: Context): Response {
-    const 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> {
-    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
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Per-provider override of the default token-endpoint auth method.
-   * Override this in subclasses for providers that require a non-`basic`
-   * default (e.g. Facebook prefers `post`).
-   */
-  protected defaultTokenEndpointAuthMethod(): 'basic' | 'post' {
-    return 'basic'
-  }
-
-  protected async getAccessToken(code: string): Promise<TokenResponse> {
-    const method = this.config.tokenEndpointAuthMethod ?? this.defaultTokenEndpointAuthMethod()
-
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/x-www-form-urlencoded',
-      Accept: 'application/json',
-    }
-
-    const body: Record<string, string> = {
-      grant_type: 'authorization_code',
-      client_id: this.config.clientId,
-      code,
-      redirect_uri: this.config.redirectUrl,
-    }
-
-    if (method === 'basic') {
-      // RFC 6749 §2.3.1 — MUST-support form. Keeps client_secret out of
-      // body-logging surfaces.
-      const credentials = `${this.config.clientId}:${this.config.clientSecret}`
-      headers.Authorization = `Basic ${Buffer.from(credentials, 'utf8').toString('base64')}`
-    } else {
-      // Fallback for providers that only accept secret-in-body.
-      body.client_secret = this.config.clientSecret
-    }
-
-    const response = await fetch(this.getTokenUrl(), {
-      method: 'POST',
-      headers,
-      body: new URLSearchParams(body),
-    })
-
-    if (!response.ok) {
-      const text = await response.text()
-      throw new ExternalServiceError(this.name, response.status, scrubProviderError(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(' '),
-      state,
-      ...this._parameters,
-    })
-
-    return `${this.getAuthUrl()}?${params.toString()}`
-  }
-}
-
-export class SocialError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'SocialError'
-  }
-}

package/src/helpers.ts

@@ -1,31 +0,0 @@
-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/providers/discord_provider.ts

@@ -1,59 +0,0 @@
-import { ExternalServiceError, scrubProviderError } from '@strav/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,
-        scrubProviderError(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,
-      emailVerified: data.verified === true,
-      avatar,
-      nickname: (data.username as string) ?? null,
-      token: '',
-      refreshToken: null,
-      expiresIn: null,
-      approvedScopes: [],
-      raw: data,
-    }
-  }
-}

package/src/providers/facebook_provider.ts

@@ -1,69 +0,0 @@
-import { ExternalServiceError, scrubProviderError } from '@strav/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']
-  }
-
-  /**
-   * Facebook's Graph API token endpoint reads `client_secret` from the
-   * request body (its docs don't advertise HTTP Basic support reliably),
-   * so default to `'post'` here. Apps can still override via
-   * `ProviderConfig.tokenEndpointAuthMethod`.
-   */
-  protected override defaultTokenEndpointAuthMethod(): 'basic' | 'post' {
-    return 'post'
-  }
-
-  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,
-        scrubProviderError(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
-    const email = (data.email as string) ?? null
-
-    return {
-      id: data.id as string,
-      name: (data.name as string) ?? null,
-      email,
-      // Facebook's Graph API only returns the user's verified primary email;
-      // an unverified address is omitted from the response entirely.
-      emailVerified: email !== null,
-      avatar: picture?.data?.url ?? null,
-      nickname: null,
-      token: '',
-      refreshToken: null,
-      expiresIn: null,
-      approvedScopes: [],
-      raw: data,
-    }
-  }
-}

package/src/providers/github_provider.ts

@@ -1,75 +0,0 @@
-import { ExternalServiceError, scrubProviderError } from '@strav/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,
-        scrubProviderError(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 {
-    const email = (data.email as string) ?? null
-    return {
-      id: String(data.id),
-      name: (data.name as string) ?? null,
-      email,
-      // GitHub only exposes verified emails: the profile `email` is required
-      // to be a verified address, and the fallback path in getUserByToken
-      // filters /user/emails for `verified === true`.
-      emailVerified: email !== 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

@@ -1,51 +0,0 @@
-import { ExternalServiceError, scrubProviderError } from '@strav/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,
-        scrubProviderError(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,
-      emailVerified: data.email_verified === true,
-      avatar: (data.picture as string) ?? null,
-      nickname: null,
-      token: '',
-      refreshToken: null,
-      expiresIn: null,
-      approvedScopes: [],
-      raw: data,
-    }
-  }
-}