@strav/social 0.4.30 → 1.0.0-alpha.22

package/src/google/google_driver.ts

@@ -0,0 +1,317 @@
+/**
+ * `GoogleSocialDriver` — Google Sign-In (OAuth 2.0 + OIDC) via
+ * the standard Web application client type.
+ *
+ * Notes worth knowing:
+ *
+ *   - **Scopes**: `openid` (id_token), `profile`, `email`.
+ *     Google accepts both short (`'email'`) and fully-qualified
+ *     (`'https://www.googleapis.com/auth/userinfo.email'`) forms;
+ *     we use the short forms.
+ *
+ *   - **PKCE**: supported. Mandatory for `installed` / SPA
+ *     client types; optional for `Web application`. The driver
+ *     defaults PKCE on as defence in depth (matches Line + the
+ *     OAuth 2.1 trajectory).
+ *
+ *   - **Refresh tokens**: Google only issues `refresh_token` on
+ *     `access_type=offline`. The driver defaults to including
+ *     it. A `refresh_token` is returned ONLY on the user's
+ *     first consent unless `prompt=consent` forces re-consent.
+ *     Apps re-establishing offline access after revocation pass
+ *     `extra: { prompt: 'consent' }`.
+ *
+ *   - **id_token**: returned when `openid` is in the requested
+ *     scope set. Decoding helper provided for `email` extraction,
+ *     mirroring `emailFromLineIdToken`. Signature verification
+ *     deferred to apps (use Google's `tokeninfo` endpoint or a
+ *     JWT library + Google's JWKS).
+ *
+ *   - **`hd` (hosted domain)**: Google Workspace constraint —
+ *     pass `extra: { hd: 'example.com' }` on authorize to limit
+ *     consent to one Workspace domain.
+ */
+
+import type { OAuthTokens, SocialProfile } from '../dto/index.ts'
+import type { SocialCapability } from '../social_capabilities.ts'
+import type {
+  AuthorizeInput,
+  AuthorizeResult,
+  ExchangeInput,
+  RefreshInput,
+  SocialDriver,
+} from '../social_driver.ts'
+import {
+  InvalidTokenError,
+  OAuthExchangeError,
+  SocialProviderError,
+  StateMismatchError,
+} from '../social_error.ts'
+import { codeChallengeFor, randomCodeVerifier, randomState } from '../pkce.ts'
+import { GOOGLE_ENDPOINTS, type GoogleProviderConfig } from './google_config.ts'
+
+const PROVIDER = 'google'
+
+const CAPS: readonly SocialCapability[] = [
+  'openid', 'pkce.support',
+  'profile.id', 'profile.email', 'profile.emailVerified',
+  'profile.name', 'profile.avatar', 'profile.locale',
+  'tokens.exchange', 'tokens.refresh', 'tokens.revoke', 'tokens.introspect',
+  'scopes.discoverable',
+]
+
+const SCOPES: readonly string[] = ['openid', 'profile', 'email']
+
+export interface GoogleDriverOptions {
+  instanceName: string
+  config: GoogleProviderConfig
+}
+
+interface TokenResponse {
+  access_token: string
+  expires_in: number
+  id_token?: string
+  refresh_token?: string
+  scope?: string
+  token_type: string
+}
+
+interface UserInfoResponse {
+  sub: string
+  email?: string
+  email_verified?: boolean
+  name?: string
+  given_name?: string
+  family_name?: string
+  picture?: string
+  locale?: string
+}
+
+interface JwtPayload {
+  email?: string
+  email_verified?: boolean
+  sub?: string
+  [k: string]: unknown
+}
+
+export class GoogleSocialDriver implements SocialDriver {
+  readonly name = PROVIDER
+  readonly instanceName: string
+  readonly capabilities: ReadonlySet<SocialCapability> = new Set(CAPS)
+  readonly availableScopes = SCOPES
+
+  private readonly config: GoogleProviderConfig
+  private readonly fetchFn: typeof fetch
+  private readonly endpoints: {
+    authorize: string
+    token: string
+    userInfo: string
+    revoke: string
+    tokenInfo: string
+  }
+
+  constructor(options: GoogleDriverOptions) {
+    this.instanceName = options.instanceName
+    this.config = options.config
+    this.fetchFn = options.config.fetch ?? fetch
+    this.endpoints = { ...GOOGLE_ENDPOINTS, ...(options.config.endpoints ?? {}) }
+  }
+
+  async authorize(input: AuthorizeInput): Promise<AuthorizeResult> {
+    const state = input.state ?? randomState()
+    const optOut = input.extra?.no_pkce === '1'
+    const codeVerifier = optOut
+      ? undefined
+      : input.codeVerifier ?? randomCodeVerifier()
+    const challenge = codeVerifier ? await codeChallengeFor(codeVerifier) : undefined
+
+    const scopes = input.scopes ?? ['openid', 'profile', 'email']
+    const offline = this.config.offlineAccess !== false
+
+    const params = new URLSearchParams({
+      response_type: 'code',
+      client_id: this.config.clientId,
+      redirect_uri: input.redirectUri,
+      scope: scopes.join(' '),
+      state,
+      ...(challenge ? { code_challenge: challenge, code_challenge_method: 'S256' } : {}),
+      ...(offline ? { access_type: 'offline' } : {}),
+      // `include_granted_scopes=true` makes Google merge previous
+      // grants rather than replace — apps that progressively
+      // request scopes appreciate it; safe-by-default.
+      include_granted_scopes: 'true',
+      ...(input.extra ?? {}),
+    })
+    params.delete('no_pkce')
+
+    return {
+      url: `${this.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,
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret,
+      ...(input.codeVerifier ? { code_verifier: input.codeVerifier } : {}),
+    })
+    const res = await this.fetchFn(this.endpoints.token, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body,
+    })
+    if (!res.ok) {
+      const text = await res.text()
+      throw new OAuthExchangeError(
+        `GoogleSocialDriver.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 res = await this.fetchFn(this.endpoints.userInfo, {
+      headers: { authorization: `Bearer ${accessToken}` },
+    })
+    if (res.status === 401) {
+      throw new InvalidTokenError('GoogleSocialDriver.profile: access token rejected.')
+    }
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SocialProviderError(
+        `GoogleSocialDriver.profile: userinfo endpoint returned ${res.status}.`,
+        { provider: PROVIDER, operation: 'profile', context: { status: res.status, body: text } },
+      )
+    }
+    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,
+    }
+  }
+
+  async refresh(input: RefreshInput): Promise<OAuthTokens> {
+    const body = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: input.refreshToken,
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret,
+    })
+    const res = await this.fetchFn(this.endpoints.token, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body,
+    })
+    if (res.status === 400 || res.status === 401) {
+      const text = await res.text()
+      throw new InvalidTokenError(
+        `GoogleSocialDriver.refresh: refresh token rejected.`,
+        { context: { status: res.status, body: text } },
+      )
+    }
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SocialProviderError(
+        `GoogleSocialDriver.refresh: token endpoint returned ${res.status}.`,
+        { provider: PROVIDER, operation: 'refresh', context: { status: res.status, body: text } },
+      )
+    }
+    // Google does NOT rotate refresh tokens; preserve the caller's
+    // current refresh token if the response omits it.
+    const json = (await res.json()) as TokenResponse
+    const tokens = this.toOAuthTokens(json)
+    if (!tokens.refreshToken) tokens.refreshToken = input.refreshToken
+    return tokens
+  }
+
+  async revoke(token: string): Promise<void> {
+    // Google's revoke endpoint takes the token as a query
+    // parameter OR a form body; we POST form for consistency
+    // with the rest of the driver.
+    const body = new URLSearchParams({ token })
+    const res = await this.fetchFn(this.endpoints.revoke, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body,
+    })
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SocialProviderError(
+        `GoogleSocialDriver.revoke: revoke endpoint returned ${res.status}.`,
+        { provider: PROVIDER, operation: 'revoke', context: { status: res.status, body: text } },
+      )
+    }
+  }
+
+  // ─── Internals ────────────────────────────────────────────────────────
+
+  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,
+    }
+  }
+}
+
+/**
+ * Extract the `email` claim from a Google id_token (JWT). Same
+ * semantics as `emailFromLineIdToken` — decode-only, no JWS
+ * signature verification. Apps with stricter posture verify via
+ * Google's `tokeninfo?id_token=...` endpoint.
+ *
+ * Google's userinfo endpoint also returns `email` + `email_verified`,
+ * so most apps don't need this helper — it's here for paths that
+ * skip userinfo (e.g. server-only signin where the access token
+ * 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,
+    })
+  }
+}

package/src/google/google_provider.ts

@@ -0,0 +1,33 @@
+/**
+ * `GoogleSocialProvider` — `ServiceProvider` that registers the
+ * Google driver factory on the `SocialManager`.
+ *
+ * Listed AFTER `SocialProvider` in `bootstrap/providers.ts`. The
+ * factory is invoked lazily on first `social.use(name)`;
+ * misconfigured credentials surface on first use.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { SocialConfigError } from '../social_error.ts'
+import { SocialManager } from '../social_manager.ts'
+import type { GoogleProviderConfig } from './google_config.ts'
+import { GoogleSocialDriver } from './google_driver.ts'
+
+export class GoogleSocialProvider extends ServiceProvider {
+  override readonly name = 'social-google'
+  override readonly dependencies = ['social']
+
+  override register(app: Application): void {
+    const manager = app.resolve(SocialManager)
+    manager.extend('google', ({ instanceName, config }) => {
+      const cfg = config as GoogleProviderConfig
+      if (!cfg.clientId || !cfg.clientSecret) {
+        throw new SocialConfigError(
+          `GoogleSocialProvider: \`clientId\` and \`clientSecret\` are required for provider "${instanceName}".`,
+          { context: { instanceName } },
+        )
+      }
+      return new GoogleSocialDriver({ instanceName, config: cfg })
+    })
+  }
+}

package/src/google/index.ts

@@ -0,0 +1,12 @@
+// Public API of `@strav/social/google`.
+
+export {
+  GOOGLE_ENDPOINTS,
+  type GoogleProviderConfig,
+} from './google_config.ts'
+export {
+  emailFromGoogleIdToken,
+  GoogleSocialDriver,
+  type GoogleDriverOptions,
+} from './google_driver.ts'
+export { GoogleSocialProvider } from './google_provider.ts'

package/src/index.ts

@@ -1,15 +1,62 @@
-export { default, default as SocialManager } from './social_manager.ts'
+// Public API of `@strav/social`.
+//
+// V1: provider-agnostic OAuth/OIDC client — normalized profile +
+// token DTOs + multi-provider routing + state + PKCE helpers.
+// Composes with `@strav/kernel` for the container and
+// `@strav/http` (no direct import; for the eventual route helpers).
+//
+// Drivers ship as subpath imports:
+//   `@strav/social/line`, `@strav/social/google`,
+//   `@strav/social/facebook`. The `MockDriver` in `./drivers`
+//   is for tests + as the reference contract.
+//
+// Account-linking schema lives in `./ledger/`:
+//   - `social_account` tenanted table (tokens encrypted via
+//     kernel's cipher)
+//   - `SocialAccountRepository` with connect / disconnect /
+//     find{ByUser,ByProviderIdentity} helpers
+//   - `applySocialAccountMigration` for the table + composite
+//     unique + user_id index
 
-// Provider
-export { default as SocialProvider } from './social_provider.ts'
-export { default as SocialAccount } from './social_account.ts'
-export { social } from './helpers.ts'
-export { AbstractProvider, SocialError } from './abstract_provider.ts'
-export { GoogleProvider } from './providers/google_provider.ts'
-export { GitHubProvider } from './providers/github_provider.ts'
-export { DiscordProvider } from './providers/discord_provider.ts'
-export { FacebookProvider } from './providers/facebook_provider.ts'
-export { LinkedInProvider } from './providers/linkedin_provider.ts'
-export { LineProvider } from './providers/line_provider.ts'
-export type { SocialUser, SocialConfig, ProviderConfig, TokenResponse } from './types.ts'
-export type { SocialAccountData } from './social_account.ts'
+export type * from './dto/index.ts'
+export { MockDriver, type MockDriverOptions, unsupported } from './drivers/index.ts'
+export {
+  applySocialAccountMigration,
+  type ApplySocialAccountMigrationOptions,
+  type ConnectInput,
+  type DisconnectInput,
+  SocialAccount,
+  SocialAccountAlreadyLinkedError,
+  SocialAccountRepository,
+  socialAccountSchema,
+} from './ledger/index.ts'
+export {
+  codeChallengeFor,
+  randomCodeVerifier,
+  randomState,
+} from './pkce.ts'
+export type { SocialCapability } from './social_capabilities.ts'
+export type {
+  AuthorizeInput,
+  AuthorizeResult,
+  ExchangeInput,
+  RefreshInput,
+  SocialDriver,
+  SocialDriverFactory,
+} from './social_driver.ts'
+export {
+  InvalidTokenError,
+  OAuthExchangeError,
+  ProviderUnsupportedError,
+  SocialConfigError,
+  SocialError,
+  SocialProviderError,
+  StateMismatchError,
+  UnknownProviderError,
+} from './social_error.ts'
+export {
+  SocialManager,
+  type SocialManagerOptions,
+} from './social_manager.ts'
+export { SocialProvider } from './social_provider.ts'
+export type { ProviderConfig, SocialConfig } from './types.ts'

package/src/ledger/apply_social_account_migration.ts

@@ -0,0 +1,66 @@
+/**
+ * `applySocialAccountMigration` — emit DDL for the
+ * `social_account` table plus its composite unique constraints
+ * and the `user_id` lookup index.
+ *
+ * Non-tenanted by default (framework policy: multitenancy is
+ * opt-in). Apps that need per-tenant scoping use
+ * `applyTenantedSocialAccountMigration` from
+ * `@strav/social/tenanted` instead.
+ *
+ * Apps drop one call into their migration:
+ *
+ * ```ts
+ * export const migration: Migration = {
+ *   name: '20260601000000_create_social_account',
+ *   async up(db) {
+ *     await applySocialAccountMigration(db, { registry })
+ *   },
+ *   async down(db) {
+ *     await db.execute(emitDropTable(socialAccountSchema.name).sql)
+ *   },
+ * }
+ * ```
+ */
+
+import {
+  emitCreateTable,
+  type DatabaseExecutor,
+  type SchemaRegistry,
+} from '@strav/database'
+import { socialAccountSchema } from './social_account_schema.ts'
+
+export interface ApplySocialAccountMigrationOptions {
+  /** Required for `emitCreateTable` to resolve relations. */
+  registry: SchemaRegistry
+}
+
+export async function applySocialAccountMigration(
+  db: DatabaseExecutor,
+  options: ApplySocialAccountMigrationOptions,
+): Promise<void> {
+  const { registry } = options
+
+  await db.execute(emitCreateTable(socialAccountSchema, { registry }).sql)
+
+  // Provider-identity uniqueness — one Google / Line / Facebook
+  // identity belongs to exactly one user. The sign-in lookup
+  // (`findByProviderIdentity`) leans on this index.
+  await db.execute(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "idx_social_account_provider_identity"
+     ON "${socialAccountSchema.name}" ("provider", "provider_user_id")`,
+  )
+
+  // Per-user-per-provider uniqueness — a single user can only
+  // link one account per provider.
+  await db.execute(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "idx_social_account_user_provider"
+     ON "${socialAccountSchema.name}" ("user_id", "provider")`,
+  )
+
+  // "All accounts for user" lookup — account-settings UI.
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_social_account_user"
+     ON "${socialAccountSchema.name}" ("user_id")`,
+  )
+}

package/src/ledger/index.ts

@@ -0,0 +1,12 @@
+export {
+  applySocialAccountMigration,
+  type ApplySocialAccountMigrationOptions,
+} from './apply_social_account_migration.ts'
+export { SocialAccount } from './social_account.ts'
+export { socialAccountSchema } from './social_account_schema.ts'
+export {
+  type ConnectInput,
+  type DisconnectInput,
+  SocialAccountAlreadyLinkedError,
+  SocialAccountRepository,
+} from './social_account_repository.ts'

package/src/ledger/social_account.ts

@@ -0,0 +1,32 @@
+/**
+ * `SocialAccount` — typed row of the linked-provider ledger.
+ *
+ * `@encrypt` on the token fields tells the Repository to wrap
+ * them through the registered `EncryptionProvider` on
+ * write/read. In memory they are plain strings; on disk they
+ * are bytea.
+ */
+
+import { encrypt, Model } from '@strav/database'
+import { socialAccountSchema } from './social_account_schema.ts'
+
+export class SocialAccount extends Model {
+  static override readonly schema = socialAccountSchema
+
+  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
+}