@strav/social 0.4.30 → 1.0.0-alpha.22

package/src/pkce.ts

@@ -0,0 +1,63 @@
+/**
+ * PKCE (Proof Key for Code Exchange) helpers — RFC 7636.
+ *
+ * For public clients (mobile, SPA, even server-side apps that
+ * can't keep a "client secret" truly secret), PKCE makes the
+ * authorization code worthless to an attacker who intercepts it
+ * mid-flight. Google requires PKCE on all new flows; Line supports
+ * it; Facebook ignores it.
+ *
+ * Flow:
+ *
+ *   1. `randomCodeVerifier()` → high-entropy random string.
+ *      Apps store this against the user's session for the
+ *      callback step.
+ *   2. `codeChallengeFor(verifier)` → base64url(sha256(verifier)).
+ *      Drivers include this on the authorize URL as
+ *      `code_challenge` + `code_challenge_method=S256`.
+ *   3. On callback, apps pass the stored verifier into
+ *      `driver.exchange({...codeVerifier})`. The provider
+ *      hashes it again and rejects the exchange if the hashes
+ *      don't match.
+ *
+ * Plain (S256-only) implementation — we never emit `method=plain`.
+ */
+
+const VERIFIER_LENGTH = 64 // RFC allows 43–128; 64 is comfortably above floor.
+
+/**
+ * Cryptographically-strong random verifier (URL-safe alphabet).
+ * 64 chars at 6 bits/char ≈ 384 bits of entropy.
+ */
+export function randomCodeVerifier(): string {
+  const bytes = new Uint8Array(VERIFIER_LENGTH)
+  crypto.getRandomValues(bytes)
+  return base64UrlEncode(bytes).slice(0, VERIFIER_LENGTH)
+}
+
+/** SHA-256 → base64url. The challenge the provider stores until callback. */
+export async function codeChallengeFor(verifier: string): Promise<string> {
+  const buf = new TextEncoder().encode(verifier)
+  const hash = await crypto.subtle.digest('SHA-256', buf)
+  return base64UrlEncode(new Uint8Array(hash))
+}
+
+/**
+ * Random state — opaque CSRF token apps include on the
+ * authorize URL and verify on the callback. Drivers expose the
+ * verification helper (`assertStateMatches`) so apps don't
+ * have to roll the comparison themselves.
+ */
+export function randomState(): string {
+  const bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+  return base64UrlEncode(bytes)
+}
+
+function base64UrlEncode(bytes: Uint8Array): string {
+  // btoa needs a binary string; Bun + browsers + Node 18+ all
+  // handle this idiom identically.
+  let s = ''
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]!)
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}

package/src/social_capabilities.ts

@@ -0,0 +1,35 @@
+/**
+ * `SocialCapability` — feature flags every driver declares.
+ *
+ * Apps that build account-connect UI check these to gate buttons
+ * / scopes / refresh-token flows. Drivers omit a flag when they
+ * can't fulfil it faithfully — partial / surprising behaviour is
+ * worse than `ProviderUnsupportedError`.
+ *
+ * Granularity is intentionally fine: e.g. Facebook supports
+ * `tokens.refresh` only for long-lived tokens issued by the Pages
+ * API path, so v1 marks it unsupported; Line supports it
+ * uniformly.
+ */
+
+export type SocialCapability =
+  // OIDC vs plain OAuth2
+  | 'openid' // returns an id_token + nonce flow
+  | 'pkce.support' // accepts PKCE (codeChallenge / codeVerifier)
+  | 'pkce.required' // mandates PKCE (Google)
+  // Profile data we can normalize
+  | 'profile.id'
+  | 'profile.email'
+  | 'profile.emailVerified'
+  | 'profile.name'
+  | 'profile.avatar'
+  | 'profile.locale'
+  // Token operations
+  | 'tokens.exchange'
+  | 'tokens.refresh'
+  | 'tokens.revoke'
+  | 'tokens.introspect'
+  // Scopes — each driver exposes its supported list separately
+  // via `driver.availableScopes`, but the flag here gates
+  // "scope picker UI" generation.
+  | 'scopes.discoverable'

package/src/social_driver.ts

@@ -0,0 +1,105 @@
+/**
+ * `SocialDriver` — the driver contract every adapter implements.
+ *
+ * One driver represents a configured provider instance
+ * (`config.social.providers[name]`). The manager holds one
+ * driver per configured name and routes calls into it.
+ *
+ * Methods drivers don't support throw `ProviderUnsupportedError`
+ * synchronously. The driver's `capabilities` set declares the
+ * supported feature set — apps that branch on capability avoid
+ * the throw by checking first.
+ */
+
+import type { OAuthTokens, SocialProfile } from './dto/index.ts'
+import type { SocialCapability } from './social_capabilities.ts'
+
+export interface AuthorizeInput {
+  /**
+   * Where the provider redirects after consent. Must match
+   * what's registered in the provider's developer console.
+   */
+  redirectUri: string
+  /**
+   * OAuth scope list. Drivers expose `availableScopes` for
+   * apps that want to render a picker; apps usually hard-code
+   * `['profile', 'email']` or `['openid', 'profile', 'email']`.
+   */
+  scopes?: readonly string[]
+  /**
+   * Override the CSRF state. When omitted, the driver generates
+   * one via `randomState()`. Apps that already have a
+   * session-bound nonce (and want to use it as state) pass it
+   * here.
+   */
+  state?: string
+  /**
+   * Override the PKCE code verifier. When omitted AND the driver
+   * supports/requires PKCE, the driver generates one and returns
+   * it on the result. Apps store the returned verifier against
+   * the session for the callback step.
+   */
+  codeVerifier?: string
+  /**
+   * Provider-specific extra query parameters (e.g. `prompt`,
+   * `access_type`, `bot_prompt` for Line). The driver merges
+   * these into the authorize URL after the standard params.
+   */
+  extra?: Record<string, string>
+}
+
+export interface AuthorizeResult {
+  /** The full URL the app redirects the customer to. */
+  url: string
+  state: string
+  /** Set when the driver issued / accepted a PKCE verifier. Apps persist this against the session. */
+  codeVerifier?: string
+}
+
+export interface ExchangeInput {
+  code: string
+  redirectUri: string
+  /** Pass the state value the app stored at authorize-time. The driver verifies it matches `expectedState` (which the app provides on the callback). */
+  state?: string
+  /** Expected state — `state` from the AuthorizeResult the app stored. */
+  expectedState?: string
+  /** PKCE verifier — required by drivers that declared `pkce.required`. */
+  codeVerifier?: string
+}
+
+export interface RefreshInput {
+  refreshToken: string
+  /** Optional narrowed scope list. Most providers ignore this. */
+  scopes?: readonly string[]
+}
+
+export interface SocialDriver {
+  /** Driver identifier — `'line'` / `'google'` / `'facebook'`. */
+  readonly name: string
+  /** App-chosen instance name (`config.social.providers[name]`). */
+  readonly instanceName: string
+  readonly capabilities: ReadonlySet<SocialCapability>
+  /** Provider-supported scope list. Apps render pickers from this; drivers reject unknown scopes at authorize time. */
+  readonly availableScopes: readonly string[]
+
+  /** Build the authorize URL + emit state / PKCE artefacts the app stores. */
+  authorize(input: AuthorizeInput): Promise<AuthorizeResult>
+
+  /** Exchange the callback code for tokens. Verifies state when both `state` and `expectedState` are provided. */
+  exchange(input: ExchangeInput): Promise<OAuthTokens>
+
+  /** Fetch the normalized user profile using a valid access token. */
+  profile(accessToken: string): Promise<SocialProfile>
+
+  /** Trade a refresh token for a fresh access token. Drivers without the `tokens.refresh` capability throw. */
+  refresh(input: RefreshInput): Promise<OAuthTokens>
+
+  /** Revoke a token. Drivers without `tokens.revoke` throw. */
+  revoke(token: string): Promise<void>
+}
+
+/** Factory the manager invokes per configured provider. */
+export type SocialDriverFactory = (config: {
+  instanceName: string
+  config: Record<string, unknown> & { driver: string }
+}) => SocialDriver

package/src/social_error.ts

@@ -0,0 +1,155 @@
+/**
+ * `SocialError` hierarchy — typed wrappers for OAuth/OIDC
+ * failures. Provider-native errors are preserved on `.cause`
+ * so apps can `instanceof` the vendor exception for retry /
+ * recovery logic; the wrapper gives the framework a consistent
+ * `StravError` to render through the standard exception handler.
+ *
+ * Subclasses:
+ *
+ *   - `SocialConfigError` — boot-time misconfiguration
+ *     (missing client id / secret / redirect uri).
+ *
+ *   - `UnknownProviderError` — `social.use(name)` for a name
+ *     not configured.
+ *
+ *   - `ProviderUnsupportedError` — driver doesn't implement the
+ *     requested operation (Facebook driver lacks
+ *     `tokens.refresh` for example).
+ *
+ *   - `StateMismatchError` — `state` returned on the callback
+ *     doesn't match what `authorize()` issued. Strong signal
+ *     of CSRF or a misrouted callback.
+ *
+ *   - `OAuthExchangeError` — provider rejected the authorization
+ *     code (expired, already used, wrong client).
+ *
+ *   - `InvalidTokenError` — provider rejected the access /
+ *     refresh token (expired, revoked, scope-mismatched).
+ *
+ *   - `SocialProviderError` — generic wrapper for vendor
+ *     exceptions that don't map to a more specific subclass.
+ *     `cause` preserved.
+ */
+
+import { StravError } from '@strav/kernel'
+
+export class SocialError extends StravError {
+  constructor(
+    message: string,
+    options: {
+      code?: string
+      status?: number
+      context?: Record<string, unknown>
+      cause?: unknown
+    } = {},
+  ) {
+    super(
+      message,
+      { code: options.code ?? 'social.error', status: options.status ?? 500 },
+      {
+        ...(options.context ? { context: options.context } : {}),
+        ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      },
+    )
+  }
+}
+
+export class SocialConfigError extends SocialError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'social.config',
+      status: 500,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}
+
+export class UnknownProviderError extends SocialError {
+  constructor(name: string, available: readonly string[]) {
+    super(
+      `Social provider "${name}" is not configured. Available: ${available.join(', ') || '<none>'}.`,
+      {
+        code: 'social.unknown_provider',
+        status: 400,
+        context: { requested: name, available },
+      },
+    )
+  }
+}
+
+export class ProviderUnsupportedError extends SocialError {
+  constructor(provider: string, operation: string, options: { reason?: string } = {}) {
+    const trailer = options.reason ? ` ${options.reason}` : ''
+    super(
+      `Social provider "${provider}" does not support "${operation}".${trailer}`,
+      {
+        code: 'social.provider_unsupported',
+        status: 400,
+        context: {
+          provider,
+          operation,
+          ...(options.reason ? { reason: options.reason } : {}),
+        },
+      },
+    )
+  }
+}
+
+export class StateMismatchError extends SocialError {
+  constructor(message = 'Social OAuth callback state mismatch — possible CSRF or misrouted callback.') {
+    super(message, { code: 'social.state_mismatch', status: 400 })
+  }
+}
+
+export class OAuthExchangeError extends SocialError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'social.oauth_exchange',
+      status: 400,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}
+
+export class InvalidTokenError extends SocialError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'social.invalid_token',
+      status: 401,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}
+
+export class SocialProviderError extends SocialError {
+  constructor(
+    message: string,
+    options: {
+      provider: string
+      operation: string
+      context?: Record<string, unknown>
+      cause?: unknown
+      status?: number
+    },
+  ) {
+    super(message, {
+      code: 'social.provider_error',
+      status: options.status ?? 502,
+      context: {
+        provider: options.provider,
+        operation: options.operation,
+        ...(options.context ?? {}),
+      },
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}

package/src/social_manager.ts

@@ -1,98 +1,116 @@
-import { inject, Configuration, ConfigurationError } from '@strav/kernel'
-import { Database, toSnakeCase } from '@strav/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'
-import { LineProvider } from './providers/line_provider.ts'
+/**
+ * `SocialManager` — the facade apps use for social-login flows.
+ *
+ * Three concept clusters:
+ *
+ *   - **Drivers.** Apps declare providers in
+ *     `config.social.providers`. The manager constructs each
+ *     driver lazily on first `use(name)` call + memoizes.
+ *     Custom drivers register via `manager.extend(name, factory)`.
+ *
+ *   - **Resource accessors** (`authorize`, `exchange`, `profile`,
+ *     `refresh`, `revoke`) — route to the default driver. Apps
+ *     that route by region call `social.use('asia').authorize(...)`.
+ *
+ *   - **Capabilities.** `driver.capabilities` exposes the
+ *     feature set — apps that build provider-aware UI (e.g.
+ *     "only show refresh button if the driver supports it")
+ *     read from there.
+ */
 
-@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>()
+import type {
+  AuthorizeInput,
+  AuthorizeResult,
+  ExchangeInput,
+  RefreshInput,
+  SocialDriver,
+  SocialDriverFactory,
+} from './social_driver.ts'
+import type { OAuthTokens, SocialProfile } from './dto/index.ts'
+import {
+  SocialConfigError,
+  UnknownProviderError,
+} from './social_error.ts'
+import type { ProviderConfig, SocialConfig } from './types.ts'
 
-  constructor(db: Database, config: Configuration) {
-    SocialManager._db = db
+export interface SocialManagerOptions {
+  config: SocialConfig
+}
 
-    const userKey = config.get('social.userKey', 'id') as string
-    SocialManager._userFkColumn = `user_${toSnakeCase(userKey)}`
+export class SocialManager {
+  readonly config: SocialConfig
+  private readonly drivers = new Map<string, SocialDriver>()
+  private readonly extensions = new Map<string, SocialDriverFactory>()
 
-    SocialManager._config = {
-      userKey,
-      providers: config.get('social.providers', {}) as Record<string, ProviderConfig>,
+  constructor(options: SocialManagerOptions) {
+    const { config } = options
+    if (!config.providers[config.default]) {
+      throw new SocialConfigError(
+        `SocialManager: default provider "${config.default}" is not configured.`,
+        {
+          context: {
+            default: config.default,
+            available: Object.keys(config.providers),
+          },
+        },
+      )
     }
+    this.config = config
   }
 
-  static get db(): Database {
-    if (!SocialManager._db) {
-      throw new ConfigurationError(
-        'SocialManager not configured. Resolve it through the container first.'
+  use(name?: string): SocialDriver {
+    const key = name ?? this.config.default
+    const cached = this.drivers.get(key)
+    if (cached) return cached
+
+    const cfg = this.config.providers[key]
+    if (!cfg) {
+      throw new UnknownProviderError(key, Object.keys(this.config.providers))
+    }
+    const ext = this.extensions.get(cfg.driver)
+    if (!ext) {
+      throw new SocialConfigError(
+        `SocialManager: unknown driver "${cfg.driver}" for provider "${key}". Register it via \`manager.extend("${cfg.driver}", factory)\` or install the matching adapter package.`,
+        { context: { driver: cfg.driver, available: [...this.extensions.keys()] } },
       )
     }
-    return SocialManager._db
+    const driver = ext({
+      instanceName: key,
+      config: cfg as ProviderConfig & { driver: string },
+    })
+    this.drivers.set(key, driver)
+    return driver
   }
 
-  static get config(): SocialConfig {
-    if (!SocialManager._config) {
-      throw new ConfigurationError(
-        'SocialManager not configured. Resolve it through the container first.'
-      )
-    }
-    return SocialManager._config
+  /** Register a driver factory. Adapter packages call this from their ServiceProvider. */
+  extend(driverName: string, factory: SocialDriverFactory): void {
+    this.extensions.set(driverName, factory)
   }
 
-  /** The FK column name on the social_account table (e.g. `user_id`, `user_uid`). */
-  static get userFkColumn(): string {
-    return SocialManager._userFkColumn ?? 'user_id'
+  /** Hand-wire a driver instance (tests / one-offs). */
+  useDriver(instanceName: string, driver: SocialDriver): void {
+    this.drivers.set(instanceName, driver)
   }
 
-  /**
-   * 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.`)
-    }
+  // ─── Resource accessors (route to the default driver) ────────────────
 
-    const driverName = providerConfig.driver ?? name
+  authorize(input: AuthorizeInput): Promise<AuthorizeResult> {
+    return this.use().authorize(input)
+  }
 
-    const extension = SocialManager._extensions.get(driverName)
-    if (extension) return extension(providerConfig)
+  exchange(input: ExchangeInput): Promise<OAuthTokens> {
+    return this.use().exchange(input)
+  }
 
-    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)
-      case 'line':
-        return new LineProvider(providerConfig)
-      default:
-        throw new ConfigurationError(
-          `Unknown social driver "${driverName}". Register it with SocialManager.extend().`
-        )
-    }
+  profile(accessToken: string): Promise<SocialProfile> {
+    return this.use().profile(accessToken)
   }
 
-  /** Register a custom provider factory. */
-  static extend(name: string, factory: (config: ProviderConfig) => AbstractProvider): void {
-    SocialManager._extensions.set(name, factory)
+  refresh(input: RefreshInput): Promise<OAuthTokens> {
+    return this.use().refresh(input)
   }
 
-  /** Clear all custom extensions (useful for testing). */
-  static reset(): void {
-    SocialManager._extensions.clear()
+  revoke(token: string): Promise<void> {
+    return this.use().revoke(token)
   }
 }

package/src/social_provider.ts

@@ -1,16 +1,50 @@
-import { ServiceProvider } from '@strav/kernel'
-import type { Application } from '@strav/kernel'
-import SocialManager from './social_manager.ts'
+/**
+ * `SocialProvider` — `ServiceProvider` that wires
+ * `SocialManager` into the container from `config.social`.
+ *
+ * Adapter packages register their driver factories via their
+ * own ServiceProvider (e.g. `LineSocialProvider`) listed AFTER
+ * this one in `bootstrap/providers.ts`. The adapter's
+ * `register()` calls `manager.extend('line', factory)`; this
+ * provider's `boot()` eagerly resolves the manager so config
+ * errors surface at boot, not on first call.
+ *
+ * Driver instances are constructed lazily on first
+ * `social.use(name)` call.
+ */
 
-export default class SocialProvider extends ServiceProvider {
-  readonly name = 'social'
-  override readonly dependencies = ['database']
+import {
+  type Application,
+  ConfigRepository,
+  ServiceProvider,
+} from '@strav/kernel'
+import { SocialConfigError } from './social_error.ts'
+import { SocialManager } from './social_manager.ts'
+import type { SocialConfig } from './types.ts'
+
+export class SocialProvider extends ServiceProvider {
+  override readonly name = 'social'
+  override readonly dependencies = ['config']
 
   override register(app: Application): void {
-    app.singleton(SocialManager)
+    app.singleton(SocialManager, (c) => {
+      const raw = c.resolve(ConfigRepository).get('social') as SocialConfig | undefined
+      if (!raw) {
+        throw new SocialConfigError(
+          'SocialProvider: `config.social` is missing. Add `config/social.ts` with at least one provider.',
+        )
+      }
+      if (!raw.providers || Object.keys(raw.providers).length === 0) {
+        throw new SocialConfigError(
+          'SocialProvider: `config.social.providers` is empty. Configure at least one provider.',
+        )
+      }
+      return new SocialManager({ config: raw })
+    })
   }
 
   override boot(app: Application): void {
+    // Force-resolve so config errors surface at boot, not on first call.
     app.resolve(SocialManager)
   }
 }

package/src/tenanted/apply_tenanted_social_account_migration.ts

@@ -0,0 +1,45 @@
+/**
+ * `applyTenantedSocialAccountMigration` — DDL for the opt-in
+ * tenanted variant of the social-account ledger.
+ *
+ * Composite unique becomes `(tenant_id, provider,
+ * provider_user_id)` — the same Google account can be linked
+ * once per tenant. The `user_id` index serves the "all
+ * accounts for user" lookup.
+ */
+
+import {
+  emitCreateTable,
+  type DatabaseExecutor,
+  type SchemaRegistry,
+} from '@strav/database'
+import { tenantedSocialAccountSchema } from './tenanted_social_account_schema.ts'
+
+export interface ApplyTenantedSocialAccountMigrationOptions {
+  /** Required for `emitCreateTable` to resolve the tenant FK ref. */
+  registry: SchemaRegistry
+}
+
+export async function applyTenantedSocialAccountMigration(
+  db: DatabaseExecutor,
+  options: ApplyTenantedSocialAccountMigrationOptions,
+): Promise<void> {
+  const { registry } = options
+
+  await db.execute(emitCreateTable(tenantedSocialAccountSchema, { registry }).sql)
+
+  await db.execute(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "idx_social_account_tenant_identity"
+     ON "${tenantedSocialAccountSchema.name}" ("tenant_id", "provider", "provider_user_id")`,
+  )
+
+  await db.execute(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "idx_social_account_user_provider"
+     ON "${tenantedSocialAccountSchema.name}" ("user_id", "provider")`,
+  )
+
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_social_account_user"
+     ON "${tenantedSocialAccountSchema.name}" ("user_id")`,
+  )
+}

package/src/tenanted/index.ts

@@ -0,0 +1,18 @@
+// Public API of `@strav/social/tenanted` — the opt-in
+// tenant-scoped variant of the social-account ledger.
+//
+// Apps that need per-tenant social accounts import from here.
+// Default single-tenant apps stay on `@strav/social` and never
+// pay for the extra column / RLS / `withTenant` wrapping.
+
+export {
+  applyTenantedSocialAccountMigration,
+  type ApplyTenantedSocialAccountMigrationOptions,
+} from './apply_tenanted_social_account_migration.ts'
+export { TenantedSocialAccount } from './tenanted_social_account.ts'
+export {
+  type ConnectInput,
+  type DisconnectInput,
+  TenantedSocialAccountRepository,
+} from './tenanted_social_account_repository.ts'
+export { tenantedSocialAccountSchema } from './tenanted_social_account_schema.ts'