@strav/social 0.4.30 → 1.0.0-alpha.22

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,149 @@
+/**
+ * `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.
+ */
+
+// biome-ignore lint/style/useImportType: PostgresDatabase value import for @inject() metadata.
+import { PostgresDatabase, quoteIdent, Repository, SchemaRegistry } from '@strav/database'
+// biome-ignore lint/style/useImportType: Cipher + EventBus value imports for @inject() metadata.
+import { Cipher, EventBus, inject, 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
+}
+
+@inject()
+export class TenantedSocialAccountRepository extends Repository<TenantedSocialAccount> {
+  static override readonly schema = tenantedSocialAccountSchema
+  static override readonly model = TenantedSocialAccount
+
+  // biome-ignore lint/complexity/noUselessConstructor: explicit constructor forces TS to emit `design:paramtypes` for @inject(). The fourth param is the Cipher for @encrypt token columns.
+  constructor(
+    db: PostgresDatabase,
+    events: EventBus,
+    registry?: SchemaRegistry,
+    cipher?: Cipher,
+  ) {
+    super(db, events, registry, cipher)
+  }
+
+  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 },
+)

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,
-    }
-  }
-}