@strav/social 0.4.31 → 1.0.0-alpha.22

package/package.json

@@ -1,27 +1,34 @@
 {
   "name": "@strav/social",
-  "version": "0.4.31",
+  "version": "1.0.0-alpha.22",
+  "description": "Strav social-login module — provider-agnostic OAuth/OIDC client. Normalized profile + token DTOs, state + PKCE helpers, capability gating, multi-provider routing. Line / Google / Facebook adapters ship as subpath imports (`@strav/social/line`, `@strav/social/google`, `@strav/social/facebook`).",
   "type": "module",
-  "description": "OAuth social authentication for the Strav framework",
-  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./*": "./src/*.ts"
+    "./line": "./src/line/index.ts",
+    "./google": "./src/google/index.ts",
+    "./facebook": "./src/facebook/index.ts",
+    "./tenanted": "./src/tenanted/index.ts"
   },
   "files": [
-    "src/",
-    "stubs/",
-    "package.json",
-    "tsconfig.json",
-    "CHANGELOG.md"
+    "src",
+    "README.md"
   ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/database": "1.0.0-alpha.22",
+    "@strav/http": "1.0.0-alpha.22",
+    "@strav/kernel": "1.0.0-alpha.22"
+  },
   "peerDependencies": {
-    "@strav/kernel": "0.4.31",
-    "@strav/http": "0.4.31",
-    "@strav/database": "0.4.31"
+    "@types/bun": ">=1.3.14"
   },
-  "scripts": {
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
-  }
+  "devDependencies": null
 }

package/src/drivers/index.ts

@@ -0,0 +1,2 @@
+export { MockDriver, type MockDriverOptions } from './mock_driver.ts'
+export { unsupported } from './unsupported.ts'

package/src/drivers/mock_driver.ts

@@ -0,0 +1,170 @@
+/**
+ * `MockDriver` — in-memory reference implementation. Used by
+ * unit tests + as the canonical contract example for new
+ * adapters.
+ *
+ * Round-trips tokens + profiles through plain Maps. PKCE +
+ * state verification mirror what real drivers enforce so apps
+ * exercising the full flow against the mock catch bugs in
+ * their state handling before they hit a real provider.
+ *
+ * Capabilities: full by default — every flag declared. Tests
+ * that exercise `ProviderUnsupportedError` paths construct the
+ * mock with a narrowed `capabilities` set.
+ */
+
+import { ulid } from '@strav/kernel'
+import {
+  InvalidTokenError,
+  OAuthExchangeError,
+  StateMismatchError,
+} from '../social_error.ts'
+import type { OAuthTokens, SocialProfile } from '../dto/index.ts'
+import type { SocialCapability } from '../social_capabilities.ts'
+import { codeChallengeFor, randomCodeVerifier, randomState } from '../pkce.ts'
+import type {
+  AuthorizeInput,
+  AuthorizeResult,
+  ExchangeInput,
+  RefreshInput,
+  SocialDriver,
+} from '../social_driver.ts'
+
+const ALL_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',
+]
+
+export interface MockDriverOptions {
+  instanceName?: string
+  capabilities?: ReadonlySet<SocialCapability>
+  /** Profile returned by `profile(accessToken)` calls. Tests override to assert specific shapes. */
+  profileFor?(accessToken: string): SocialProfile
+}
+
+interface PendingFlow {
+  state: string
+  codeVerifier?: string
+  scopes: readonly string[]
+  redirectUri: string
+}
+
+export class MockDriver implements SocialDriver {
+  readonly name = 'mock'
+  readonly instanceName: string
+  readonly capabilities: ReadonlySet<SocialCapability>
+  readonly availableScopes: readonly string[] = ['openid', 'profile', 'email']
+
+  private readonly pending = new Map<string, PendingFlow>()
+  private readonly issuedTokens = new Map<string, { code: string; refreshToken: string }>()
+  private readonly profileForFn: (accessToken: string) => SocialProfile
+
+  constructor(options: MockDriverOptions = {}) {
+    this.instanceName = options.instanceName ?? 'mock'
+    this.capabilities = options.capabilities ?? new Set(ALL_CAPS)
+    this.profileForFn =
+      options.profileFor ??
+      ((token: string): SocialProfile => ({
+        id: `mock_${token.slice(0, 8)}`,
+        provider: this.name,
+        email: `${token.slice(0, 6)}@mock.test`,
+        emailVerified: true,
+        name: 'Mock User',
+        avatarUrl: 'https://mock.test/avatar.png',
+        locale: 'en',
+        metadata: {},
+        raw: { mock: true },
+      }))
+  }
+
+  async authorize(input: AuthorizeInput): Promise<AuthorizeResult> {
+    const state = input.state ?? randomState()
+    const codeVerifier =
+      input.codeVerifier ??
+      (this.capabilities.has('pkce.support') ? randomCodeVerifier() : undefined)
+    const challenge = codeVerifier ? await codeChallengeFor(codeVerifier) : undefined
+    this.pending.set(state, {
+      state,
+      ...(codeVerifier ? { codeVerifier } : {}),
+      scopes: input.scopes ?? ['profile'],
+      redirectUri: input.redirectUri,
+    })
+    const params = new URLSearchParams({
+      response_type: 'code',
+      client_id: 'mock_client',
+      redirect_uri: input.redirectUri,
+      scope: (input.scopes ?? ['profile']).join(' '),
+      state,
+      ...(challenge ? { code_challenge: challenge, code_challenge_method: 'S256' } : {}),
+      ...(input.extra ?? {}),
+    })
+    return {
+      url: `https://mock.test/oauth/authorize?${params.toString()}`,
+      state,
+      ...(codeVerifier ? { codeVerifier } : {}),
+    }
+  }
+
+  async exchange(input: ExchangeInput): Promise<OAuthTokens> {
+    if (input.expectedState !== undefined && input.state !== input.expectedState) {
+      throw new StateMismatchError()
+    }
+    const flow = input.state ? this.pending.get(input.state) : undefined
+    if (!flow) {
+      throw new OAuthExchangeError('MockDriver: no pending authorize for this state.')
+    }
+    if (flow.codeVerifier && flow.codeVerifier !== input.codeVerifier) {
+      throw new OAuthExchangeError('MockDriver: PKCE verifier mismatch.')
+    }
+    this.pending.delete(input.state!)
+    const accessToken = `mock_at_${ulid()}`
+    const refreshToken = `mock_rt_${ulid()}`
+    this.issuedTokens.set(accessToken, { code: input.code, refreshToken })
+    return {
+      accessToken,
+      refreshToken,
+      ...(flow.scopes.includes('openid') ? { idToken: `mock_id_${ulid()}` } : {}),
+      expiresAt: new Date(Date.now() + 3600 * 1000),
+      scope: flow.scopes.join(' '),
+      tokenType: 'Bearer',
+      raw: { mock: true, code: input.code },
+    }
+  }
+
+  async profile(accessToken: string): Promise<SocialProfile> {
+    if (!this.issuedTokens.has(accessToken)) {
+      throw new InvalidTokenError(`MockDriver.profile: unknown access token.`)
+    }
+    return this.profileForFn(accessToken)
+  }
+
+  async refresh(input: RefreshInput): Promise<OAuthTokens> {
+    // Find the access token whose refresh token matches.
+    const found = [...this.issuedTokens.entries()].find(
+      ([, v]) => v.refreshToken === input.refreshToken,
+    )
+    if (!found) {
+      throw new InvalidTokenError('MockDriver.refresh: unknown refresh token.')
+    }
+    // Rotate.
+    this.issuedTokens.delete(found[0])
+    const accessToken = `mock_at_${ulid()}`
+    const newRefresh = `mock_rt_${ulid()}`
+    this.issuedTokens.set(accessToken, { code: found[1].code, refreshToken: newRefresh })
+    return {
+      accessToken,
+      refreshToken: newRefresh,
+      expiresAt: new Date(Date.now() + 3600 * 1000),
+      scope: (input.scopes ?? []).join(' '),
+      tokenType: 'Bearer',
+      raw: { mock: true },
+    }
+  }
+
+  async revoke(token: string): Promise<void> {
+    this.issuedTokens.delete(token)
+  }
+}

package/src/drivers/unsupported.ts

@@ -0,0 +1,17 @@
+/**
+ * `unsupported(provider, operation, reason?)` — drivers stub
+ * out methods they can't fulfil. Returns a function that
+ * throws `ProviderUnsupportedError` synchronously.
+ */
+
+import { ProviderUnsupportedError } from '../social_error.ts'
+
+export function unsupported(
+  provider: string,
+  operation: string,
+  reason?: string,
+): (...args: unknown[]) => never {
+  return () => {
+    throw new ProviderUnsupportedError(provider, operation, reason ? { reason } : {})
+  }
+}

package/src/dto/index.ts

@@ -0,0 +1,4 @@
+/** Barrel for the social DTOs. */
+
+export type { OAuthTokens } from './oauth_tokens.ts'
+export type { SocialProfile } from './social_profile.ts'

package/src/dto/oauth_tokens.ts

@@ -0,0 +1,26 @@
+/**
+ * `OAuthTokens` — normalized token payload from a successful
+ * code exchange or refresh. Apps persist these against their
+ * user record (encrypted via `@strav/kernel`'s cipher).
+ *
+ * `idToken` is set only for OIDC providers (Google, Line as
+ * OpenID Connect). Plain-OAuth2 providers (Facebook) leave it
+ * undefined.
+ *
+ * `expiresAt` is provider-derived (`expires_in` seconds → wall
+ * clock). Drivers compute it at exchange time so apps don't
+ * need to track when the call was made.
+ */
+
+export interface OAuthTokens {
+  accessToken: string
+  /** Available only when the user granted offline access (Google) or the provider issues refresh tokens by default (Line). */
+  refreshToken?: string
+  /** OIDC id_token (JWT). Present on `openid` flows. Apps that already trust the access token usually ignore this. */
+  idToken?: string
+  expiresAt?: Date
+  /** Space-separated scope string the provider granted (may be narrower than what was requested). */
+  scope?: string
+  tokenType: string
+  raw: unknown
+}

package/src/dto/social_profile.ts

@@ -0,0 +1,37 @@
+/**
+ * `SocialProfile` — normalized user-info shape across providers.
+ * The native provider object is on `.raw`; apps reach there for
+ * fields the framework doesn't normalize (Line's `pictureUrl`
+ * vs Google's `picture` collapse to `avatarUrl`; Line's
+ * `displayName` collapses to `name`).
+ *
+ * Provider divergence the framework intentionally surfaces:
+ *
+ *   - `email` is optional. Line gives it only when the `email`
+ *     scope is requested AND the user accepts; Facebook gives it
+ *     only if the app is approved for `email`. Apps that need it
+ *     check capability AND check `profile.email`.
+ *
+ *   - `emailVerified` is true only when the provider asserts it.
+ *     Google + Line always assert; Facebook never does — apps
+ *     verify themselves.
+ *
+ *   - `id` is the provider-native subject id. Globally unique
+ *     within the provider's namespace, not across providers.
+ *     The `(provider, id)` pair is what `social_account` rows
+ *     key on (slice 8.5).
+ */
+
+export interface SocialProfile {
+  /** Provider-native user id (`sub` in OIDC, `userId` in Line, `id` in Facebook). */
+  id: string
+  /** Driver name — `'line'` / `'google'` / `'facebook'`. */
+  provider: string
+  email?: string
+  emailVerified?: boolean
+  name?: string
+  avatarUrl?: string
+  locale?: string
+  metadata: Record<string, unknown>
+  raw: unknown
+}

package/src/facebook/facebook_config.ts

@@ -0,0 +1,68 @@
+/**
+ * Facebook-specific provider config. Apps put one of these
+ * inside `config.social.providers[name]` with `driver: 'facebook'`.
+ *
+ * Get credentials from https://developers.facebook.com → My
+ * Apps → "Facebook Login" product → Settings. The `email` scope
+ * needs Meta App Review approval before it works for users
+ * outside the developer team — set up the review path before
+ * going to production.
+ */
+
+import type { ProviderConfig } from '../types.ts'
+
+export interface FacebookProviderConfig extends ProviderConfig {
+  driver: 'facebook'
+  clientId: string
+  clientSecret: string
+  /**
+   * Graph API version. Default `'v18.0'`. Apps that need
+   * a specific feature pin it explicitly; otherwise the default
+   * gets bumped at the next driver release.
+   */
+  graphVersion?: string
+  /**
+   * Profile field list — passed as `?fields=...` on `/me`.
+   * Default covers `id,name,email,first_name,last_name,picture,locale`.
+   * Apps that need extra fields (e.g. `birthday`, `gender`) override.
+   */
+  profileFields?: readonly string[]
+  /** Override endpoints for testing — never set in production. */
+  endpoints?: {
+    authorize?: string
+    token?: string
+    me?: string
+    permissions?: string
+    debugToken?: string
+  }
+  fetch?: typeof fetch
+}
+
+const GRAPH = 'https://graph.facebook.com'
+const DEFAULT_VERSION = 'v18.0'
+
+export function facebookEndpoints(version = DEFAULT_VERSION): {
+  authorize: string
+  token: string
+  me: string
+  permissions: string
+  debugToken: string
+} {
+  return {
+    authorize: `https://www.facebook.com/${version}/dialog/oauth`,
+    token: `${GRAPH}/${version}/oauth/access_token`,
+    me: `${GRAPH}/${version}/me`,
+    permissions: `${GRAPH}/${version}/me/permissions`,
+    debugToken: `${GRAPH}/${version}/debug_token`,
+  }
+}
+
+export const DEFAULT_FACEBOOK_PROFILE_FIELDS: readonly string[] = [
+  'id',
+  'name',
+  'email',
+  'first_name',
+  'last_name',
+  'picture.type(large)',
+  'locale',
+]