@strav/social 0.3.32 → 0.3.33

package/README.md

@@ -57,7 +57,6 @@ r.get('/auth/github/callback', async ctx => {
 ```ts
 social.driver('github').scopes(['repo', 'gist']).redirect(ctx)
 social.driver('google').with({ hd: 'example.com' }).redirect(ctx)
-social.driver('google').stateless().redirect(ctx)
 const user = await social.driver('google').userFromToken(accessToken)
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/social",
-  "version": "0.3.32",
+  "version": "0.3.33",
   "type": "module",
   "description": "OAuth social authentication for the Strav framework",
   "license": "MIT",
@@ -16,9 +16,9 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "@strav/kernel": "0.3.32",
-    "@strav/http": "0.3.32",
-    "@strav/database": "0.3.32"
+    "@strav/kernel": "0.3.33",
+    "@strav/http": "0.3.33",
+    "@strav/database": "0.3.33"
   },
   "scripts": {
     "test": "bun test tests/",

package/src/abstract_provider.ts

@@ -1,5 +1,5 @@
 import type { Context, Session } from '@strav/http'
-import { randomHex, ExternalServiceError } from '@strav/kernel'
+import { randomHex, ExternalServiceError, scrubProviderError } from '@strav/kernel'
 import type { ProviderConfig, SocialUser, TokenResponse } from './types.ts'
 
 const STATE_KEY = 'social_state'
@@ -9,7 +9,6 @@ export abstract class AbstractProvider {
 
   protected config: ProviderConfig
   protected _scopes: string[]
-  protected _stateless = false
   protected _parameters: Record<string, string> = {}
 
   constructor(config: ProviderConfig) {
@@ -41,11 +40,6 @@ export abstract class AbstractProvider {
     return this
   }
 
-  stateless(): this {
-    this._stateless = true
-    return this
-  }
-
   with(params: Record<string, string>): this {
     this._parameters = { ...this._parameters, ...params }
     return this
@@ -56,31 +50,25 @@ export abstract class AbstractProvider {
   // ---------------------------------------------------------------------------
 
   redirect(ctx: Context): Response {
-    let state: string | undefined
-
-    if (!this._stateless) {
-      state = randomHex(32)
-      const session = ctx.get<Session>('session')
-      session.set(STATE_KEY, state)
-    }
+    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> {
-    if (!this._stateless) {
-      const session = ctx.get<Session>('session')
-      const expectedState = session.get<string>(STATE_KEY)
-      const returnedState = ctx.query.get('state')
+    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)
+    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')
@@ -117,25 +105,49 @@ export abstract class AbstractProvider {
   // 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: {
-        'Content-Type': 'application/x-www-form-urlencoded',
-        Accept: 'application/json',
-      },
-      body: new URLSearchParams({
-        grant_type: 'authorization_code',
-        client_id: this.config.clientId,
-        client_secret: this.config.clientSecret,
-        code,
-        redirect_uri: this.config.redirectUrl,
-      }),
+      headers,
+      body: new URLSearchParams(body),
     })
 
     if (!response.ok) {
       const text = await response.text()
-      throw new ExternalServiceError(this.name, response.status, text)
+      throw new ExternalServiceError(this.name, response.status, scrubProviderError(text))
     }
 
     const data = (await response.json()) as Record<string, unknown>
@@ -148,17 +160,16 @@ export abstract class AbstractProvider {
     }
   }
 
-  protected buildAuthUrl(state?: string): string {
+  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,
     })
 
-    if (state) params.set('state', state)
-
     return `${this.getAuthUrl()}?${params.toString()}`
   }
 }

package/src/providers/discord_provider.ts

@@ -1,4 +1,4 @@
-import { ExternalServiceError } from '@strav/kernel'
+import { ExternalServiceError, scrubProviderError } from '@strav/kernel'
 import { AbstractProvider } from '../abstract_provider.ts'
 import type { SocialUser } from '../types.ts'
 
@@ -23,7 +23,11 @@ export class DiscordProvider extends AbstractProvider {
     })
 
     if (!response.ok) {
-      throw new ExternalServiceError('Discord', response.status, await response.text())
+      throw new ExternalServiceError(
+        'Discord',
+        response.status,
+        scrubProviderError(await response.text())
+      )
     }
 
     return (await response.json()) as Record<string, unknown>
@@ -42,6 +46,7 @@ export class DiscordProvider extends AbstractProvider {
       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: '',

package/src/providers/facebook_provider.ts

@@ -1,4 +1,4 @@
-import { ExternalServiceError } from '@strav/kernel'
+import { ExternalServiceError, scrubProviderError } from '@strav/kernel'
 import { AbstractProvider } from '../abstract_provider.ts'
 import type { SocialUser } from '../types.ts'
 
@@ -11,6 +11,16 @@ export class FacebookProvider extends AbstractProvider {
     return ['email', 'public_profile']
   }
 
+  /**
+   * Facebook's Graph API token endpoint reads `client_secret` from the
+   * request body (its docs don't advertise HTTP Basic support reliably),
+   * so default to `'post'` here. Apps can still override via
+   * `ProviderConfig.tokenEndpointAuthMethod`.
+   */
+  protected override defaultTokenEndpointAuthMethod(): 'basic' | 'post' {
+    return 'post'
+  }
+
   protected getAuthUrl(): string {
     return `https://www.facebook.com/${API_VERSION}/dialog/oauth`
   }
@@ -26,7 +36,11 @@ export class FacebookProvider extends AbstractProvider {
     )
 
     if (!response.ok) {
-      throw new ExternalServiceError('Facebook', response.status, await response.text())
+      throw new ExternalServiceError(
+        'Facebook',
+        response.status,
+        scrubProviderError(await response.text())
+      )
     }
 
     return (await response.json()) as Record<string, unknown>
@@ -34,11 +48,15 @@ export class FacebookProvider extends AbstractProvider {
 
   protected mapUserToObject(data: Record<string, unknown>): SocialUser {
     const picture = data.picture as { data?: { url?: string } } | undefined
+    const email = (data.email as string) ?? null
 
     return {
       id: data.id as string,
       name: (data.name as string) ?? null,
-      email: (data.email as string) ?? null,
+      email,
+      // Facebook's Graph API only returns the user's verified primary email;
+      // an unverified address is omitted from the response entirely.
+      emailVerified: email !== null,
       avatar: picture?.data?.url ?? null,
       nickname: null,
       token: '',

package/src/providers/github_provider.ts

@@ -1,4 +1,4 @@
-import { ExternalServiceError } from '@strav/kernel'
+import { ExternalServiceError, scrubProviderError } from '@strav/kernel'
 import { AbstractProvider } from '../abstract_provider.ts'
 import type { SocialUser } from '../types.ts'
 
@@ -30,7 +30,11 @@ export class GitHubProvider extends AbstractProvider {
     ])
 
     if (!userResponse.ok) {
-      throw new ExternalServiceError('GitHub', userResponse.status, await userResponse.text())
+      throw new ExternalServiceError(
+        'GitHub',
+        userResponse.status,
+        scrubProviderError(await userResponse.text())
+      )
     }
 
     const user = (await userResponse.json()) as Record<string, unknown>
@@ -50,10 +54,15 @@ export class GitHubProvider extends AbstractProvider {
   }
 
   protected mapUserToObject(data: Record<string, unknown>): SocialUser {
+    const email = (data.email as string) ?? null
     return {
       id: String(data.id),
       name: (data.name as string) ?? null,
-      email: (data.email as string) ?? null,
+      email,
+      // GitHub only exposes verified emails: the profile `email` is required
+      // to be a verified address, and the fallback path in getUserByToken
+      // filters /user/emails for `verified === true`.
+      emailVerified: email !== null,
       avatar: (data.avatar_url as string) ?? null,
       nickname: (data.login as string) ?? null,
       token: '',

package/src/providers/google_provider.ts

@@ -1,4 +1,4 @@
-import { ExternalServiceError } from '@strav/kernel'
+import { ExternalServiceError, scrubProviderError } from '@strav/kernel'
 import { AbstractProvider } from '../abstract_provider.ts'
 import type { SocialUser } from '../types.ts'
 
@@ -23,7 +23,11 @@ export class GoogleProvider extends AbstractProvider {
     })
 
     if (!response.ok) {
-      throw new ExternalServiceError('Google', response.status, await response.text())
+      throw new ExternalServiceError(
+        'Google',
+        response.status,
+        scrubProviderError(await response.text())
+      )
     }
 
     return (await response.json()) as Record<string, unknown>
@@ -34,6 +38,7 @@ export class GoogleProvider extends AbstractProvider {
       id: data.sub as string,
       name: (data.name as string) ?? null,
       email: (data.email as string) ?? null,
+      emailVerified: data.email_verified === true,
       avatar: (data.picture as string) ?? null,
       nickname: null,
       token: '',

package/src/providers/linkedin_provider.ts

@@ -1,4 +1,4 @@
-import { ExternalServiceError } from '@strav/kernel'
+import { ExternalServiceError, scrubProviderError } from '@strav/kernel'
 import { AbstractProvider } from '../abstract_provider.ts'
 import type { SocialUser } from '../types.ts'
 
@@ -23,7 +23,11 @@ export class LinkedInProvider extends AbstractProvider {
     })
 
     if (!response.ok) {
-      throw new ExternalServiceError('LinkedIn', response.status, await response.text())
+      throw new ExternalServiceError(
+        'LinkedIn',
+        response.status,
+        scrubProviderError(await response.text())
+      )
     }
 
     return (await response.json()) as Record<string, unknown>
@@ -34,6 +38,7 @@ export class LinkedInProvider extends AbstractProvider {
       id: data.sub as string,
       name: (data.name as string) ?? null,
       email: (data.email as string) ?? null,
+      emailVerified: data.email_verified === true,
       avatar: (data.picture as string) ?? null,
       nickname: null,
       token: '',

package/src/social_account.ts

@@ -1,7 +1,29 @@
+import { EncryptionManager, Emitter } from '@strav/kernel'
 import { extractUserId } from '@strav/database'
 import SocialManager from './social_manager.ts'
 import type { SocialUser } from './types.ts'
 
+const ENC_PREFIX = 'enc:v1:'
+
+/**
+ * Encrypt an OAuth token before persisting it. The `enc:v1:` prefix is the
+ * sentinel that lets reads distinguish encrypted values from legacy
+ * plaintext rows that predate the encryption-at-rest migration.
+ */
+function encryptToken(plain: string): string {
+  return ENC_PREFIX + EncryptionManager.encrypt(plain)
+}
+
+/**
+ * Decrypt a stored token. Values without the `enc:v1:` prefix are assumed
+ * to be legacy plaintext (predate encryption-at-rest); they are returned
+ * as-is and re-encrypted on next write.
+ */
+function decryptToken(stored: string): string {
+  if (!stored.startsWith(ENC_PREFIX)) return stored
+  return EncryptionManager.decrypt(stored.slice(ENC_PREFIX.length))
+}
+
 /** The DB record for a social account link. */
 export interface SocialAccountData {
   id: number
@@ -66,7 +88,9 @@ export default class SocialAccount {
   }
 
   /**
-   * Create a new social account link.
+   * Create a new social account link. Emits `social_account:linked`
+   * after a successful insert so apps can wire `@strav/audit` (or any
+   * other observability sink) without forcing a hard dependency.
    */
   static async create(data: {
     user: unknown
@@ -86,17 +110,31 @@ export default class SocialAccount {
         userId,
         data.provider,
         data.providerId,
-        data.token,
-        data.refreshToken ?? null,
+        encryptToken(data.token),
+        data.refreshToken != null ? encryptToken(data.refreshToken) : null,
         data.expiresAt ?? null,
       ]
     )
-    return SocialAccount.hydrate(rows[0] as Record<string, unknown>)
+    const account = SocialAccount.hydrate(rows[0] as Record<string, unknown>)
+    void Emitter.emit('social_account:linked', {
+      accountId: account.id,
+      userId: account.userId,
+      provider: account.provider,
+      providerId: account.providerId,
+    }).catch(() => {})
+    return account
   }
 
   /**
-   * Find an existing social account by provider or create a new one.
-   * If the account already exists, its tokens are updated.
+   * Find an existing social account by `(provider, providerId)` or create a
+   * new one. If the account already exists, its tokens are updated.
+   *
+   * SECURITY: This function does NOT validate the email. If the caller is
+   * passing in an existing application `user` that was located by
+   * `socialUser.email`, the caller MUST first verify
+   * `socialUser.emailVerified === true`. Linking by an unverified
+   * provider email is a known account-takeover vector — see the
+   * "Verified-email gate" section in this package's CLAUDE.md.
    */
   static async findOrCreate(
     provider: string,
@@ -131,7 +169,10 @@ export default class SocialAccount {
   }
 
   /**
-   * Update OAuth tokens for an existing social account.
+   * Update OAuth tokens for an existing social account. Tokens are
+   * encrypted at rest — pass plaintext values; the column stores ciphertext.
+   * Emits `social_account:tokens_updated` so an audit hook can record the
+   * token swap.
    */
   static async updateTokens(
     id: number,
@@ -139,21 +180,32 @@ export default class SocialAccount {
     refreshToken: string | null,
     expiresAt: Date | null
   ): Promise<void> {
+    const encryptedToken = encryptToken(token)
+    const encryptedRefresh = refreshToken != null ? encryptToken(refreshToken) : null
     await SocialAccount.sql`
       UPDATE "social_account"
-      SET "token" = ${token},
-          "refresh_token" = ${refreshToken},
+      SET "token" = ${encryptedToken},
+          "refresh_token" = ${encryptedRefresh},
           "expires_at" = ${expiresAt},
           "updated_at" = NOW()
       WHERE "id" = ${id}
     `
+    void Emitter.emit('social_account:tokens_updated', {
+      accountId: id,
+      hasRefreshToken: refreshToken != null,
+      expiresAt,
+    }).catch(() => {})
   }
 
-  /** Delete a social account by its database ID. */
+  /**
+   * Delete a social account by its database ID. Emits
+   * `social_account:unlinked` for the audit trail.
+   */
   static async delete(id: number): Promise<void> {
     await SocialAccount.sql`
       DELETE FROM "social_account" WHERE "id" = ${id}
     `
+    void Emitter.emit('social_account:unlinked', { accountId: id }).catch(() => {})
   }
 
   /** Delete all social accounts for a user. */
@@ -161,6 +213,7 @@ export default class SocialAccount {
     const userId = extractUserId(user)
     const fk = SocialAccount.fk
     await SocialAccount.sql.unsafe(`DELETE FROM "social_account" WHERE "${fk}" = $1`, [userId])
+    void Emitter.emit('social_account:unlinked_all', { userId }).catch(() => {})
   }
 
   // ---------------------------------------------------------------------------
@@ -169,13 +222,14 @@ export default class SocialAccount {
 
   private static hydrate(row: Record<string, unknown>): SocialAccountData {
     const fk = SocialAccount.fk
+    const rawRefresh = (row.refresh_token as string) ?? null
     return {
       id: row.id as number,
       userId: row[fk] as string | number,
       provider: row.provider as string,
       providerId: row.provider_id as string,
-      token: row.token as string,
-      refreshToken: (row.refresh_token as string) ?? null,
+      token: decryptToken(row.token as string),
+      refreshToken: rawRefresh != null ? decryptToken(rawRefresh) : null,
       expiresAt: (row.expires_at as Date) ?? null,
       createdAt: row.created_at as Date,
       updatedAt: row.updated_at as Date,

package/src/types.ts

@@ -2,6 +2,14 @@ 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
@@ -17,6 +25,15 @@ export interface ProviderConfig {
   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'
 }
 
 export interface SocialConfig {