@strav/social 0.4.31 → 1.0.0-alpha.24

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'

package/src/tenanted/tenanted_social_account.ts

@@ -0,0 +1,30 @@
+/**
+ * `TenantedSocialAccount` — typed row of the opt-in tenanted
+ * ledger. Identical to `SocialAccount` except its `static schema`
+ * points at the tenanted variant, so the Repository runs against
+ * the right DDL + RLS policy.
+ */
+
+import { encrypt, Model } from '@strav/database'
+import { tenantedSocialAccountSchema } from './tenanted_social_account_schema.ts'
+
+export class TenantedSocialAccount extends Model {
+  static override readonly schema = tenantedSocialAccountSchema
+
+  id!: string
+  user_id!: string
+  provider!: string
+  provider_user_id!: string
+  email!: string | null
+  name!: string | null
+  avatar_url!: string | null
+  locale!: string | null
+  @encrypt access_token!: string
+  @encrypt refresh_token!: string | null
+  @encrypt id_token!: string | null
+  expires_at!: Date | null
+  scope!: string | null
+  metadata!: Record<string, unknown>
+  created_at!: Date
+  updated_at!: Date
+}

package/src/tenanted/tenanted_social_account_repository.ts

@@ -0,0 +1,136 @@
+/**
+ * `TenantedSocialAccountRepository` — same surface as
+ * `SocialAccountRepository`, scoped to the tenanted schema.
+ * Callers MUST be inside a `TenantManager.withTenant(...)`
+ * scope; the INSERT relies on the session's `app.tenant_id`
+ * setting (RLS).
+ *
+ * The implementation deliberately mirrors the non-tenanted
+ * Repository line-for-line — minor code duplication is worth
+ * it to keep both variants narrowly scoped + avoid runtime
+ * branching on a tenancy flag.
+ */
+
+import { quoteIdent, Repository } from '@strav/database'
+import { ulid } from '@strav/kernel'
+import type { OAuthTokens, SocialProfile } from '../dto/index.ts'
+import { SocialAccountAlreadyLinkedError } from '../ledger/social_account_repository.ts'
+import { TenantedSocialAccount } from './tenanted_social_account.ts'
+import { tenantedSocialAccountSchema } from './tenanted_social_account_schema.ts'
+
+export interface ConnectInput {
+  userId: string
+  provider: string
+  profile: SocialProfile
+  tokens: OAuthTokens
+}
+
+export interface DisconnectInput {
+  userId: string
+  provider: string
+}
+
+export class TenantedSocialAccountRepository extends Repository<TenantedSocialAccount> {
+  static override readonly schema = tenantedSocialAccountSchema
+  static override readonly model = TenantedSocialAccount
+
+  async connect(input: ConnectInput): Promise<TenantedSocialAccount> {
+    const existing = await this.findByProviderIdentity(
+      input.provider,
+      input.profile.id,
+    )
+    const now = new Date()
+
+    if (existing) {
+      if (existing.user_id !== input.userId) {
+        throw new SocialAccountAlreadyLinkedError({
+          provider: input.provider,
+          providerUserId: input.profile.id,
+          existingUserId: existing.user_id,
+          attemptedUserId: input.userId,
+        })
+      }
+      return this.update(existing, {
+        email: input.profile.email ?? null,
+        name: input.profile.name ?? null,
+        avatar_url: input.profile.avatarUrl ?? null,
+        locale: input.profile.locale ?? null,
+        access_token: input.tokens.accessToken,
+        refresh_token: input.tokens.refreshToken ?? null,
+        id_token: input.tokens.idToken ?? null,
+        expires_at: input.tokens.expiresAt ?? null,
+        scope: input.tokens.scope ?? null,
+        updated_at: now,
+      } as Partial<TenantedSocialAccount>)
+    }
+
+    return this.create({
+      id: ulid(),
+      user_id: input.userId,
+      provider: input.provider,
+      provider_user_id: input.profile.id,
+      email: input.profile.email ?? null,
+      name: input.profile.name ?? null,
+      avatar_url: input.profile.avatarUrl ?? null,
+      locale: input.profile.locale ?? null,
+      access_token: input.tokens.accessToken,
+      refresh_token: input.tokens.refreshToken ?? null,
+      id_token: input.tokens.idToken ?? null,
+      expires_at: input.tokens.expiresAt ?? null,
+      scope: input.tokens.scope ?? null,
+      metadata: {},
+      created_at: now,
+      updated_at: now,
+    } as Partial<TenantedSocialAccount>)
+  }
+
+  async disconnect(input: DisconnectInput): Promise<void> {
+    const table = quoteIdent(tenantedSocialAccountSchema.name)
+    await this.db.execute(
+      `DELETE FROM ${table} WHERE "user_id" = $1 AND "provider" = $2`,
+      [input.userId, input.provider],
+    )
+  }
+
+  async findByUser(userId: string): Promise<TenantedSocialAccount[]> {
+    const table = quoteIdent(tenantedSocialAccountSchema.name)
+    const rows = await this.db.query<Record<string, unknown>>(
+      `SELECT * FROM ${table} WHERE "user_id" = $1 ORDER BY "created_at"`,
+      [userId],
+    )
+    return Promise.all(rows.map((r) => this.hydrate(r)))
+  }
+
+  async findByUserAndProvider(
+    userId: string,
+    provider: string,
+  ): Promise<TenantedSocialAccount | null> {
+    const table = quoteIdent(tenantedSocialAccountSchema.name)
+    const rows = await this.db.query<Record<string, unknown>>(
+      `SELECT * FROM ${table} WHERE "user_id" = $1 AND "provider" = $2 LIMIT 1`,
+      [userId, provider],
+    )
+    if (rows.length === 0) return null
+    return this.hydrate(rows[0]!)
+  }
+
+  /**
+   * Sign-in lookup. Scoped by RLS to the current tenant — the
+   * same provider identity can exist in two tenants without
+   * collision; this query only sees the one in scope.
+   */
+  async findByProviderIdentity(
+    provider: string,
+    providerUserId: string,
+  ): Promise<TenantedSocialAccount | null> {
+    const table = quoteIdent(tenantedSocialAccountSchema.name)
+    const rows = await this.db.query<Record<string, unknown>>(
+      `SELECT * FROM ${table}
+       WHERE "provider" = $1 AND "provider_user_id" = $2
+       LIMIT 1`,
+      [provider, providerUserId],
+    )
+    if (rows.length === 0) return null
+    return this.hydrate(rows[0]!)
+  }
+}

package/src/tenanted/tenanted_social_account_schema.ts

@@ -0,0 +1,44 @@
+/**
+ * `tenantedSocialAccountSchema` — opt-in tenant-scoped variant
+ * of the social-account ledger. Imported from
+ * `@strav/social/tenanted` so apps that don't need
+ * multitenancy don't pay for it.
+ *
+ * Same columns as the default `socialAccountSchema`, with
+ * `tenanted: true` so `@strav/database` injects the
+ * `tenant_id` FK + RLS policy. Composite unique becomes
+ * `(tenant_id, provider, provider_user_id)` — the same Google
+ * account can be linked across distinct tenants (one per
+ * tenant), but only once per tenant.
+ *
+ * Apps register this schema instead of (or alongside, under a
+ * different name) the default. The matching `Model` +
+ * `Repository` + `applyTenantedSocialAccountMigration` ship
+ * here too so the wiring stays consistent.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const tenantedSocialAccountSchema = defineSchema(
+  'social_account',
+  Archetype.Entity,
+  (t) => {
+    t.id()
+    t.string('user_id').max(64).notNull()
+    t.string('provider').max(64).notNull()
+    t.string('provider_user_id').max(255).notNull()
+    t.string('email').max(320).nullable()
+    t.string('name').max(255).nullable()
+    t.string('avatar_url').max(1024).nullable()
+    t.string('locale').max(16).nullable()
+    t.encrypted('access_token').notNull()
+    t.encrypted('refresh_token').nullable()
+    t.encrypted('id_token').nullable()
+    t.timestamp('expires_at').nullable()
+    t.string('scope').max(512).nullable()
+    t.json('metadata').notNull().default({})
+    t.timestamp('created_at').notNull()
+    t.timestamp('updated_at').notNull()
+  },
+  { tenanted: true },
+)