@strav/social 1.0.0-alpha.38 → 1.0.0-alpha.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/social",
-  "version": "1.0.0-alpha.38",
+  "version": "1.0.0-alpha.40",
   "description": "Strav social-login module — provider-agnostic OAuth/OIDC client. Normalized profile + token DTOs, state + PKCE helpers, capability gating, multi-provider routing. Line / Google / Facebook adapters ship as subpath imports (`@strav/social/line`, `@strav/social/google`, `@strav/social/facebook`).",
   "type": "module",
   "main": "./src/index.ts",
@@ -10,6 +10,7 @@
     "./line": "./src/drivers/line/index.ts",
     "./google": "./src/drivers/google/index.ts",
     "./facebook": "./src/drivers/facebook/index.ts",
+    "./oauth2": "./src/drivers/oauth2/index.ts",
     "./tenanted": "./src/tenanted/index.ts"
   },
   "files": [
@@ -23,9 +24,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/database": "1.0.0-alpha.38",
-    "@strav/http": "1.0.0-alpha.38",
-    "@strav/kernel": "1.0.0-alpha.38"
+    "@strav/database": "1.0.0-alpha.40",
+    "@strav/http": "1.0.0-alpha.40",
+    "@strav/kernel": "1.0.0-alpha.40"
   },
   "peerDependencies": {
     "@types/bun": ">=1.3.14"

package/src/drivers/google/google_driver.ts

@@ -33,6 +33,8 @@
  */
 
 import type { OAuthTokens, SocialProfile } from '../../dto/index.ts'
+import { mapOidcUserInfo } from '../../dto/oidc_user_info.ts'
+import { decodeJwtClaims } from '../../jwt.ts'
 import type { SocialCapability } from '../../social_capabilities.ts'
 import type {
   AuthorizeInput,
@@ -85,13 +87,7 @@ interface UserInfoResponse {
   family_name?: string
   picture?: string
   locale?: string
-}
-
-interface JwtPayload {
-  email?: string
-  email_verified?: boolean
-  sub?: string
-  [k: string]: unknown
+  [claim: string]: unknown
 }
 
 /**
@@ -243,20 +239,7 @@ export class GoogleSocialDriver implements SocialDriver {
       )
     }
     const u = (await res.json()) as UserInfoResponse
-    return {
-      id: u.sub,
-      provider: PROVIDER,
-      ...(u.email ? { email: u.email } : {}),
-      ...(u.email_verified !== undefined ? { emailVerified: u.email_verified } : {}),
-      ...(u.name ? { name: u.name } : {}),
-      ...(u.picture ? { avatarUrl: u.picture } : {}),
-      ...(u.locale ? { locale: u.locale } : {}),
-      metadata: {
-        ...(u.given_name ? { givenName: u.given_name } : {}),
-        ...(u.family_name ? { familyName: u.family_name } : {}),
-      },
-      raw: u,
-    }
+    return mapOidcUserInfo(u, { provider: PROVIDER })
   }
 
   async refresh(input: RefreshInput): Promise<OAuthTokens> {
@@ -448,25 +431,6 @@ export class GoogleSocialDriver implements SocialDriver {
  * is discarded immediately after exchange).
  */
 export function emailFromGoogleIdToken(idToken: string): string | null {
-  const segments = idToken.split('.')
-  if (segments.length !== 3) {
-    throw new InvalidTokenError(
-      'emailFromGoogleIdToken: id_token does not have 3 segments.',
-    )
-  }
-  const payload = decodeJwtSegment(segments[1]!)
-  return typeof payload.email === 'string' ? payload.email : null
-}
-
-function decodeJwtSegment(segment: string): JwtPayload {
-  const pad = segment.length % 4
-  const padded = pad === 0 ? segment : `${segment}${'='.repeat(4 - pad)}`
-  const b64 = padded.replace(/-/g, '+').replace(/_/g, '/')
-  try {
-    return JSON.parse(atob(b64)) as JwtPayload
-  } catch (cause) {
-    throw new InvalidTokenError('decodeJwtSegment: failed to parse JWT segment.', {
-      cause,
-    })
-  }
+  const claims = decodeJwtClaims(idToken)
+  return typeof claims.email === 'string' ? claims.email : null
 }

package/src/drivers/line/line_driver.ts

@@ -30,6 +30,7 @@
  */
 
 import type { OAuthTokens, SocialProfile } from '../../dto/index.ts'
+import { decodeJwtClaims } from '../../jwt.ts'
 import type { SocialCapability } from '../../social_capabilities.ts'
 import type {
   AuthorizeInput,
@@ -81,15 +82,6 @@ interface ProfileResponse {
   statusMessage?: string
 }
 
-interface JwtPayload {
-  email?: string
-  email_verified?: boolean
-  name?: string
-  picture?: string
-  sub?: string
-  [k: string]: unknown
-}
-
 export class LineSocialDriver implements SocialDriver {
   readonly name = PROVIDER
   readonly instanceName: string
@@ -286,25 +278,6 @@ export class LineSocialDriver implements SocialDriver {
  * Line's `/oauth2/v2.1/verify` endpoint with the id_token.
  */
 export function emailFromLineIdToken(idToken: string): string | null {
-  const segments = idToken.split('.')
-  if (segments.length !== 3) {
-    throw new InvalidTokenError('emailFromLineIdToken: id_token does not have 3 segments.')
-  }
-  const payload = decodeJwtSegment(segments[1]!)
-  return typeof payload.email === 'string' ? payload.email : null
-}
-
-function decodeJwtSegment(segment: string): JwtPayload {
-  // base64url → base64 → string
-  const pad = segment.length % 4
-  const padded = pad === 0 ? segment : `${segment}${'='.repeat(4 - pad)}`
-  const b64 = padded.replace(/-/g, '+').replace(/_/g, '/')
-  try {
-    const json = atob(b64)
-    return JSON.parse(json) as JwtPayload
-  } catch (cause) {
-    throw new InvalidTokenError('decodeJwtSegment: failed to parse JWT segment.', {
-      cause,
-    })
-  }
+  const claims = decodeJwtClaims(idToken)
+  return typeof claims.email === 'string' ? claims.email : null
 }

package/src/drivers/oauth2/index.ts

@@ -0,0 +1,16 @@
+// `@strav/social/oauth2` — generic OAuth2/OIDC driver.
+
+export type {
+  OAuth2Capabilities,
+  OAuth2DriverConfig,
+  OAuth2Endpoints,
+  OAuth2HttpMethod,
+  OAuth2Pkce,
+  OAuth2ProfileSpec,
+  OAuth2ScopesSpec,
+} from './oauth2_config.ts'
+export {
+  OAuth2SocialDriver,
+  type OAuth2DriverOptions,
+} from './oauth2_driver.ts'
+export { OAuth2SocialProvider } from './oauth2_provider.ts'

package/src/drivers/oauth2/oauth2_config.ts

@@ -0,0 +1,102 @@
+/**
+ * `OAuth2DriverConfig` — config shape for the generic OAuth2/OIDC driver.
+ *
+ * The provider is fully data-driven: endpoints + a profile mapper + the
+ * usual capability flags. Apps add a new provider (GitHub, Discord,
+ * Microsoft, Slack, Twitter/X, GitLab, …) in a few lines of config instead
+ * of writing a new driver file.
+ */
+
+import type { ProviderConfig } from '../../types.ts'
+import type { SocialProfile } from '../../dto/social_profile.ts'
+
+export interface OAuth2Endpoints {
+  authorize: string
+  token: string
+  /**
+   * URL fetched by `driver.profile(accessToken)`. Required unless
+   * `profile.source === 'idToken'` — in which case the driver maps from
+   * the `id_token` JWT instead.
+   */
+  userInfo?: string
+  revoke?: string
+  introspect?: string
+}
+
+export type OAuth2HttpMethod = 'GET' | 'POST'
+
+export interface OAuth2ProfileSpec {
+  /**
+   * Where the profile comes from:
+   *   - `'userInfo'` — call `endpoints.userInfo` with the access token (OIDC default)
+   *   - `'idToken'`  — decode the OIDC `id_token` JWT (no network call)
+   */
+  source?: 'userInfo' | 'idToken'
+  /** HTTP method for the userInfo call. Default `'GET'`. */
+  method?: OAuth2HttpMethod
+  /**
+   * How to authenticate the userInfo call.
+   *   - `'bearer'` (default) — `Authorization: Bearer <token>`
+   *   - `'queryToken'` — `?access_token=<token>`
+   *   - `'noneSigned'` — no auth header; only for endpoints that accept the id_token in the body
+   */
+  auth?: 'bearer' | 'queryToken' | 'noneSigned'
+  /**
+   * Extra query params appended to the userInfo URL. Useful for providers
+   * that require `?fields=...` selection (e.g. Facebook Graph, GitHub).
+   */
+  query?: Record<string, string>
+  /** Extra request headers. */
+  headers?: Record<string, string>
+  /**
+   * Translate the raw response into the framework's `SocialProfile`. When
+   * omitted, the driver uses `mapOidcUserInfo({ provider })` — works for
+   * any OIDC `/userinfo` shape.
+   */
+  map?: (raw: unknown) => SocialProfile
+}
+
+export interface OAuth2ScopesSpec {
+  /** Scopes sent on `authorize()` when the caller doesn't pass `scopes`. */
+  default?: readonly string[]
+  /** Scopes the driver claims to support, surfaced via `driver.availableScopes`. */
+  available?: readonly string[]
+  /** Delimiter between scopes in the authorize URL. Default `' '`. Facebook uses `,`. */
+  delimiter?: string
+}
+
+export interface OAuth2Pkce {
+  /** PKCE mode: `'off'` / `'support'` (default — on unless `extra.no_pkce='1'`) / `'required'`. */
+  mode?: 'off' | 'support' | 'required'
+}
+
+export interface OAuth2Capabilities {
+  refresh?: boolean
+  revoke?: boolean
+  introspect?: boolean
+  openid?: boolean
+}
+
+/**
+ * Full config shape. Apps include this under
+ * `config.social.providers[name]` with `driver: 'oauth2'`.
+ */
+export interface OAuth2DriverConfig extends ProviderConfig {
+  driver: 'oauth2'
+  clientId: string
+  clientSecret: string
+  endpoints: OAuth2Endpoints
+  scopes?: OAuth2ScopesSpec
+  pkce?: OAuth2Pkce
+  profile?: OAuth2ProfileSpec
+  capabilities?: OAuth2Capabilities
+  /**
+   * Extra query parameters merged into the authorize URL. Useful for
+   * provider-specific opts like `access_type=offline`, `prompt=consent`.
+   */
+  authorizeExtra?: Record<string, string>
+  /** Auth style for the token endpoint: `'body'` (default) or `'basic'`. */
+  clientAuth?: 'body' | 'basic'
+  /** Injectable for tests. */
+  fetch?: typeof fetch
+}

package/src/drivers/oauth2/oauth2_driver.ts

@@ -0,0 +1,341 @@
+/**
+ * `OAuth2SocialDriver` — config-driven OAuth2/OIDC driver.
+ *
+ * Implements the full `SocialDriver` contract from endpoints + a small
+ * `OAuth2ProfileSpec`. Drop-in replacement for hand-written drivers when
+ * the provider speaks vanilla OAuth2 — GitHub, Discord, Microsoft, Slack,
+ * GitLab, Twitch, LinkedIn, etc.
+ *
+ * Defaults are OIDC-shaped:
+ *   - PKCE: `support` (on by default, opt-out via `extra.no_pkce='1'`)
+ *   - profile source: `userInfo` (Bearer auth, JSON response)
+ *   - profile mapping: `mapOidcUserInfo({ provider })`
+ *
+ * Override per-provider in config — see `OAuth2DriverConfig`.
+ */
+
+import type { OAuthTokens, SocialProfile } from '../../dto/index.ts'
+import { mapOidcUserInfo, type OidcUserInfo } from '../../dto/oidc_user_info.ts'
+import { decodeJwtClaims } from '../../jwt.ts'
+import { codeChallengeFor, randomCodeVerifier, randomState } from '../../pkce.ts'
+import type { SocialCapability } from '../../social_capabilities.ts'
+import type {
+  AuthorizeInput,
+  AuthorizeResult,
+  ExchangeInput,
+  RefreshInput,
+  SocialDriver,
+} from '../../social_driver.ts'
+import {
+  InvalidTokenError,
+  OAuthExchangeError,
+  ProviderUnsupportedError,
+  SocialConfigError,
+  SocialProviderError,
+  StateMismatchError,
+} from '../../social_error.ts'
+import type { OAuth2DriverConfig } from './oauth2_config.ts'
+
+export interface OAuth2DriverOptions {
+  instanceName: string
+  /** App-chosen name surfaced via `driver.name` (default `'oauth2'`). */
+  providerName?: string
+  config: OAuth2DriverConfig
+}
+
+interface TokenResponse {
+  access_token: string
+  expires_in?: number
+  id_token?: string
+  refresh_token?: string
+  scope?: string
+  token_type?: string
+}
+
+export class OAuth2SocialDriver implements SocialDriver {
+  readonly name: string
+  readonly instanceName: string
+  readonly capabilities: ReadonlySet<SocialCapability>
+  readonly availableScopes: readonly string[]
+
+  private readonly config: OAuth2DriverConfig
+  private readonly fetchFn: typeof fetch
+  private readonly scopeDelimiter: string
+
+  constructor(options: OAuth2DriverOptions) {
+    this.instanceName = options.instanceName
+    // Surface the configured provider name everywhere — falls back to the
+    // generic `'oauth2'` only when no provider name was supplied.
+    this.name = options.providerName ?? 'oauth2'
+    this.config = options.config
+    this.fetchFn = options.config.fetch ?? fetch
+    this.scopeDelimiter = options.config.scopes?.delimiter ?? ' '
+    this.availableScopes = options.config.scopes?.available ?? options.config.scopes?.default ?? []
+    this.capabilities = new Set(this.computeCapabilities())
+
+    if (!this.config.endpoints.authorize || !this.config.endpoints.token) {
+      throw new SocialConfigError(
+        `OAuth2SocialDriver: provider "${this.instanceName}" is missing the authorize or token endpoint.`,
+      )
+    }
+  }
+
+  async authorize(input: AuthorizeInput): Promise<AuthorizeResult> {
+    const state = input.state ?? randomState()
+    const pkceMode = this.config.pkce?.mode ?? 'support'
+
+    const optOut = input.extra?.['no_pkce'] === '1'
+    const wantsPkce = pkceMode === 'required' || (pkceMode === 'support' && !optOut)
+    const codeVerifier = wantsPkce ? input.codeVerifier ?? randomCodeVerifier() : undefined
+    if (pkceMode === 'required' && !codeVerifier) {
+      throw new SocialConfigError(
+        `OAuth2SocialDriver: provider "${this.instanceName}" requires PKCE but no code verifier was generated.`,
+      )
+    }
+    const challenge = codeVerifier ? await codeChallengeFor(codeVerifier) : undefined
+
+    const scopes = input.scopes ?? this.config.scopes?.default ?? []
+    const params = new URLSearchParams({
+      response_type: 'code',
+      client_id: this.config.clientId,
+      redirect_uri: input.redirectUri,
+      state,
+      ...(scopes.length > 0 ? { scope: scopes.join(this.scopeDelimiter) } : {}),
+      ...(challenge ? { code_challenge: challenge, code_challenge_method: 'S256' } : {}),
+      ...(this.config.authorizeExtra ?? {}),
+      ...(input.extra ?? {}),
+    })
+    // Strip the framework's PKCE opt-out flag — it must not leak upstream.
+    params.delete('no_pkce')
+
+    return {
+      url: `${this.config.endpoints.authorize}?${params.toString()}`,
+      state,
+      ...(codeVerifier ? { codeVerifier } : {}),
+    }
+  }
+
+  async exchange(input: ExchangeInput): Promise<OAuthTokens> {
+    if (input.expectedState !== undefined && input.state !== input.expectedState) {
+      throw new StateMismatchError()
+    }
+    const body = new URLSearchParams({
+      grant_type: 'authorization_code',
+      code: input.code,
+      redirect_uri: input.redirectUri,
+      ...(input.codeVerifier ? { code_verifier: input.codeVerifier } : {}),
+    })
+    const res = await this.tokenRequest(body)
+    if (!res.ok) {
+      const text = await res.text()
+      throw new OAuthExchangeError(
+        `OAuth2SocialDriver(${this.name}).exchange: token endpoint returned ${res.status}.`,
+        { context: { status: res.status, body: text } },
+      )
+    }
+    return this.toOAuthTokens((await res.json()) as TokenResponse)
+  }
+
+  async profile(accessToken: string): Promise<SocialProfile> {
+    const spec = this.config.profile ?? {}
+    if (spec.source === 'idToken') {
+      throw new SocialConfigError(
+        `OAuth2SocialDriver(${this.name}).profile: profile.source='idToken' requires calling profileFromIdToken(idToken) instead.`,
+      )
+    }
+    const url = this.config.endpoints.userInfo
+    if (!url) {
+      throw new SocialConfigError(
+        `OAuth2SocialDriver(${this.name}).profile: endpoints.userInfo is not configured.`,
+      )
+    }
+    const method = spec.method ?? 'GET'
+    const auth = spec.auth ?? 'bearer'
+    const finalUrl = this.appendQuery(url, {
+      ...(spec.query ?? {}),
+      ...(auth === 'queryToken' ? { access_token: accessToken } : {}),
+    })
+    const headers: Record<string, string> = { ...(spec.headers ?? {}) }
+    if (auth === 'bearer') headers['authorization'] = `Bearer ${accessToken}`
+
+    const res = await this.fetchFn(finalUrl, { method, headers })
+    if (res.status === 401) {
+      throw new InvalidTokenError(
+        `OAuth2SocialDriver(${this.name}).profile: access token rejected.`,
+      )
+    }
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SocialProviderError(
+        `OAuth2SocialDriver(${this.name}).profile: userinfo endpoint returned ${res.status}.`,
+        {
+          provider: this.name,
+          operation: 'profile',
+          context: { status: res.status, body: text },
+        },
+      )
+    }
+    const raw = await res.json()
+    return this.mapProfile(raw, spec.map)
+  }
+
+  /**
+   * Decode the OIDC id_token and map its claims into a `SocialProfile`.
+   * Use this on providers configured with `profile.source: 'idToken'` —
+   * common when the provider issues a short-lived access token whose only
+   * job is the userinfo call you don't want to make.
+   */
+  profileFromIdToken(idToken: string): SocialProfile {
+    const claims = decodeJwtClaims(idToken)
+    const spec = this.config.profile ?? {}
+    return this.mapProfile(claims, spec.map)
+  }
+
+  async refresh(input: RefreshInput): Promise<OAuthTokens> {
+    if (!this.capabilities.has('tokens.refresh')) {
+      throw new ProviderUnsupportedError(this.name, 'tokens.refresh')
+    }
+    const body = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: input.refreshToken,
+      ...(input.scopes ? { scope: input.scopes.join(this.scopeDelimiter) } : {}),
+    })
+    const res = await this.tokenRequest(body)
+    if (res.status === 400 || res.status === 401) {
+      const text = await res.text()
+      throw new InvalidTokenError(
+        `OAuth2SocialDriver(${this.name}).refresh: refresh token rejected.`,
+        { context: { status: res.status, body: text } },
+      )
+    }
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SocialProviderError(
+        `OAuth2SocialDriver(${this.name}).refresh: token endpoint returned ${res.status}.`,
+        {
+          provider: this.name,
+          operation: 'refresh',
+          context: { status: res.status, body: text },
+        },
+      )
+    }
+    const tokens = this.toOAuthTokens((await res.json()) as TokenResponse)
+    // Many providers omit the refresh token on rotation — preserve the
+    // caller's current one so they don't lose offline access.
+    if (!tokens.refreshToken) tokens.refreshToken = input.refreshToken
+    return tokens
+  }
+
+  async revoke(token: string): Promise<void> {
+    if (!this.capabilities.has('tokens.revoke')) {
+      throw new ProviderUnsupportedError(this.name, 'tokens.revoke')
+    }
+    const url = this.config.endpoints.revoke
+    if (!url) {
+      throw new SocialConfigError(
+        `OAuth2SocialDriver(${this.name}).revoke: endpoints.revoke is not configured.`,
+      )
+    }
+    const body = new URLSearchParams({ token })
+    const headers: Record<string, string> = {
+      'content-type': 'application/x-www-form-urlencoded',
+    }
+    if (this.config.clientAuth === 'basic') {
+      headers['authorization'] = this.basicAuthHeader()
+    } else {
+      body.set('client_id', this.config.clientId)
+      body.set('client_secret', this.config.clientSecret)
+    }
+    const res = await this.fetchFn(url, { method: 'POST', headers, body })
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SocialProviderError(
+        `OAuth2SocialDriver(${this.name}).revoke: revoke endpoint returned ${res.status}.`,
+        {
+          provider: this.name,
+          operation: 'revoke',
+          context: { status: res.status, body: text },
+        },
+      )
+    }
+  }
+
+  // ─── Internals ────────────────────────────────────────────────────────
+
+  private mapProfile(
+    raw: unknown,
+    override: ((raw: unknown) => SocialProfile) | undefined,
+  ): SocialProfile {
+    if (override) return override(raw)
+    return mapOidcUserInfo(raw as OidcUserInfo, { provider: this.name })
+  }
+
+  private async tokenRequest(body: URLSearchParams): Promise<Response> {
+    const headers: Record<string, string> = {
+      'content-type': 'application/x-www-form-urlencoded',
+      accept: 'application/json',
+    }
+    if (this.config.clientAuth === 'basic') {
+      headers['authorization'] = this.basicAuthHeader()
+    } else {
+      body.set('client_id', this.config.clientId)
+      body.set('client_secret', this.config.clientSecret)
+    }
+    return this.fetchFn(this.config.endpoints.token, { method: 'POST', headers, body })
+  }
+
+  private basicAuthHeader(): string {
+    const cred = `${this.config.clientId}:${this.config.clientSecret}`
+    return `Basic ${btoa(cred)}`
+  }
+
+  private computeCapabilities(): SocialCapability[] {
+    const out: SocialCapability[] = ['tokens.exchange']
+    const caps = this.config.capabilities ?? {}
+    const pkce = this.config.pkce?.mode ?? 'support'
+    if (pkce === 'support') out.push('pkce.support')
+    if (pkce === 'required') {
+      out.push('pkce.support')
+      out.push('pkce.required')
+    }
+    if (caps.openid) out.push('openid')
+    if (caps.refresh !== false) out.push('tokens.refresh') // default on
+    if (caps.revoke && this.config.endpoints.revoke) out.push('tokens.revoke')
+    if (caps.introspect && this.config.endpoints.introspect) out.push('tokens.introspect')
+
+    // Optimistic profile capabilities — apps should narrow with their own
+    // mapper if the provider truly can't fulfil one of these claims. The
+    // generic driver can't introspect the userinfo schema, so it advertises
+    // the OIDC defaults and trusts callers to override.
+    if (this.config.endpoints.userInfo || this.config.profile?.source === 'idToken') {
+      out.push('profile.id', 'profile.email', 'profile.emailVerified', 'profile.name')
+      out.push('profile.avatar', 'profile.locale')
+    }
+    if (this.config.scopes?.available && this.config.scopes.available.length > 0) {
+      out.push('scopes.discoverable')
+    }
+    return out
+  }
+
+  private appendQuery(url: string, params: Record<string, string>): string {
+    const entries = Object.entries(params)
+    if (entries.length === 0) return url
+    const u = new URL(url)
+    for (const [k, v] of entries) u.searchParams.set(k, v)
+    return u.toString()
+  }
+
+  private toOAuthTokens(t: TokenResponse): OAuthTokens {
+    const expiresAt =
+      typeof t.expires_in === 'number' ? new Date(Date.now() + t.expires_in * 1000) : undefined
+    return {
+      accessToken: t.access_token,
+      ...(t.refresh_token ? { refreshToken: t.refresh_token } : {}),
+      ...(t.id_token ? { idToken: t.id_token } : {}),
+      ...(expiresAt ? { expiresAt } : {}),
+      ...(t.scope ? { scope: t.scope } : {}),
+      tokenType: t.token_type ?? 'Bearer',
+      raw: t,
+    }
+  }
+}

package/src/drivers/oauth2/oauth2_provider.ts

@@ -0,0 +1,26 @@
+/**
+ * `OAuth2SocialProvider` — registers the `'oauth2'` driver factory on
+ * `SocialManager`. Apps add this to `bootstrap/providers.ts` once and
+ * then configure any number of providers under that driver in
+ * `config.social.providers`.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { SocialManager } from '../../social_manager.ts'
+import type { OAuth2DriverConfig } from './oauth2_config.ts'
+import { OAuth2SocialDriver } from './oauth2_driver.ts'
+
+export class OAuth2SocialProvider extends ServiceProvider {
+  override readonly name = 'social.oauth2'
+  override readonly dependencies = ['social']
+
+  override register(app: Application): void {
+    app.resolve(SocialManager).extend('oauth2', ({ instanceName, config }) => {
+      return new OAuth2SocialDriver({
+        instanceName,
+        providerName: instanceName,
+        config: config as OAuth2DriverConfig,
+      })
+    })
+  }
+}

package/src/dto/index.ts

@@ -1,4 +1,9 @@
 /** Barrel for the social DTOs. */
 
 export type { OAuthTokens } from './oauth_tokens.ts'
+export {
+  mapOidcUserInfo,
+  type MapOidcUserInfoOptions,
+  type OidcUserInfo,
+} from './oidc_user_info.ts'
 export type { SocialProfile } from './social_profile.ts'

package/src/dto/oidc_user_info.ts

@@ -0,0 +1,84 @@
+/**
+ * `mapOidcUserInfo` — translate an OIDC `/userinfo` response (or any
+ * provider that happens to use OIDC-standard claim names) into the
+ * framework's normalised `SocialProfile`.
+ *
+ * Used by the Google driver and the generic OAuth2/OIDC driver. Apps with
+ * non-OIDC providers (GitHub uses `id` + `avatar_url`, X uses `data.id`,
+ * etc.) supply a provider-specific mapper via the driver config —
+ * see `OAuth2DriverConfig.profile.map`.
+ *
+ * Claim mapping (in priority order — first present wins):
+ *
+ *   id            ← `sub`
+ *   email         ← `email`
+ *   emailVerified ← `email_verified`
+ *   name          ← `name` ‖ `given_name + family_name`
+ *   avatarUrl     ← `picture`
+ *   locale        ← `locale`
+ *
+ * Unmapped claims survive on `metadata` (`given_name` / `family_name`
+ * specifically — they're often useful and not part of the top-level
+ * normalised shape).
+ */
+
+import type { SocialProfile } from './social_profile.ts'
+
+export interface OidcUserInfo {
+  sub?: string
+  email?: string
+  email_verified?: boolean
+  name?: string
+  given_name?: string
+  family_name?: string
+  picture?: string
+  locale?: string
+  [claim: string]: unknown
+}
+
+export interface MapOidcUserInfoOptions {
+  /** Provider name to stamp onto `profile.provider`. */
+  provider: string
+  /**
+   * Override the id source. Default `sub`. Used when a provider returns
+   * its native user id under a different key (e.g. `id`).
+   */
+  idClaim?: string
+}
+
+export function mapOidcUserInfo(
+  raw: OidcUserInfo,
+  options: MapOidcUserInfoOptions,
+): SocialProfile {
+  const idClaim = options.idClaim ?? 'sub'
+  const idValue = raw[idClaim]
+  if (typeof idValue !== 'string' || idValue.length === 0) {
+    throw new Error(
+      `mapOidcUserInfo: missing "${idClaim}" claim on userinfo response for "${options.provider}".`,
+    )
+  }
+
+  const name = raw.name ?? joinName(raw.given_name, raw.family_name)
+  const metadata: Record<string, unknown> = {}
+  if (raw.given_name) metadata['givenName'] = raw.given_name
+  if (raw.family_name) metadata['familyName'] = raw.family_name
+
+  const profile: SocialProfile = {
+    id: idValue,
+    provider: options.provider,
+    metadata,
+    raw,
+  }
+  if (raw.email) profile.email = raw.email
+  if (raw.email_verified !== undefined) profile.emailVerified = raw.email_verified
+  if (name) profile.name = name
+  if (raw.picture) profile.avatarUrl = raw.picture
+  if (raw.locale) profile.locale = raw.locale
+  return profile
+}
+
+function joinName(given?: string, family?: string): string | undefined {
+  const parts = [given, family].filter((p): p is string => Boolean(p))
+  if (parts.length === 0) return undefined
+  return parts.join(' ')
+}

package/src/index.ts

@@ -19,6 +19,7 @@
 //     unique + user_id index
 
 export type * from './dto/index.ts'
+export { mapOidcUserInfo } from './dto/oidc_user_info.ts'
 export { MockDriver, type MockDriverOptions, unsupported } from './drivers/index.ts'
 export {
   applySocialAccountMigration,
@@ -30,6 +31,11 @@ export {
   SocialAccountRepository,
   socialAccountSchema,
 } from './ledger/index.ts'
+export {
+  decodeJwtClaims,
+  emailFromIdToken,
+  type JwtClaims,
+} from './jwt.ts'
 export {
   codeChallengeFor,
   randomCodeVerifier,

package/src/jwt.ts

@@ -0,0 +1,69 @@
+/**
+ * Minimal JWT helpers — decode-only.
+ *
+ * Used across drivers (Google + Line today, plus the generic OIDC driver)
+ * to pull claims out of `id_token` JWTs. **Does not** verify the JWS
+ * signature: the token arrives over TLS direct from the provider's token
+ * endpoint in the same response as the access token, so the trust boundary
+ * is identical. Apps with stricter posture verify against the provider's
+ * JWKS or call the provider's `tokeninfo` / `verify` endpoint.
+ */
+
+import { InvalidTokenError } from './social_error.ts'
+
+export interface JwtClaims {
+  /** Subject — the provider's user id. */
+  sub?: string
+  /** Issuer URL. */
+  iss?: string
+  /** Audience — typically the client id. */
+  aud?: string | readonly string[]
+  /** Issued-at and expiration in seconds since the epoch. */
+  iat?: number
+  exp?: number
+  email?: string
+  email_verified?: boolean
+  name?: string
+  picture?: string
+  locale?: string
+  [claim: string]: unknown
+}
+
+/**
+ * Decode every claim segment of a `<header>.<payload>.<signature>` JWT.
+ * Throws `InvalidTokenError` on structural problems (wrong segment count,
+ * unparsable base64url, unparsable JSON).
+ */
+export function decodeJwtClaims(idToken: string): JwtClaims {
+  const segments = idToken.split('.')
+  if (segments.length !== 3) {
+    throw new InvalidTokenError('decodeJwtClaims: id_token does not have 3 segments.')
+  }
+  return decodeJwtSegment(segments[1] ?? '')
+}
+
+/**
+ * Convenience for the common "did the provider include email?" path.
+ * Returns the string when present, `null` when the claim is missing,
+ * throws when the token itself is malformed.
+ */
+export function emailFromIdToken(idToken: string): string | null {
+  const claims = decodeJwtClaims(idToken)
+  return typeof claims.email === 'string' ? claims.email : null
+}
+
+function decodeJwtSegment(segment: string): JwtClaims {
+  if (segment.length === 0) {
+    throw new InvalidTokenError('decodeJwtClaims: payload segment is empty.')
+  }
+  const pad = segment.length % 4
+  const padded = pad === 0 ? segment : `${segment}${'='.repeat(4 - pad)}`
+  const b64 = padded.replace(/-/g, '+').replace(/_/g, '/')
+  try {
+    return JSON.parse(atob(b64)) as JwtClaims
+  } catch (cause) {
+    throw new InvalidTokenError('decodeJwtClaims: failed to parse JWT segment.', {
+      cause,
+    })
+  }
+}

package/src/social_manager.ts

@@ -27,6 +27,7 @@ import type {
   SocialDriverFactory,
 } from './social_driver.ts'
 import type { OAuthTokens, SocialProfile } from './dto/index.ts'
+import type { SocialCapability } from './social_capabilities.ts'
 import {
   SocialConfigError,
   UnknownProviderError,
@@ -92,6 +93,16 @@ export class SocialManager {
     this.drivers.set(instanceName, driver)
   }
 
+  /**
+   * Shorthand for `manager.use(name).capabilities.has(capability)`. Lets UI
+   * code gate buttons / scope pickers without spelling out the driver
+   * resolution. Throws `UnknownProviderError` if the provider is not
+   * configured.
+   */
+  supports(name: string, capability: SocialCapability): boolean {
+    return this.use(name).capabilities.has(capability)
+  }
+
   // ─── Resource accessors (route to the default driver) ────────────────
 
   authorize(input: AuthorizeInput): Promise<AuthorizeResult> {