@strav/social 0.4.30 → 1.0.0-alpha.22

package/src/ledger/social_account_repository.ts

@@ -0,0 +1,216 @@
+/**
+ * `SocialAccountRepository` — domain helpers on top of the
+ * generic CRUD surface. The four methods apps actually use:
+ *
+ *   - `connect({ userId, provider, profile, tokens })` — upsert
+ *     by `(provider, provider_user_id)` within the tenant scope.
+ *     Runs on every sign-in: a returning user's tokens get
+ *     refreshed; a first-time link inserts.
+ *
+ *   - `disconnect({ userId, provider })` — delete the link.
+ *     Apps invoke this when the user unlinks a provider; for
+ *     full token revocation, drivers' `revoke()` runs separately
+ *     (this method doesn't reach the provider).
+ *
+ *   - `findByUser(userId)` — list every linked provider for a
+ *     user. Apps render account-settings UIs from this.
+ *
+ *   - `findByProviderIdentity(provider, providerUserId)` — the
+ *     sign-in lookup: "we just verified an OAuth identity, who
+ *     does it belong to?" Returns the row including `user_id`
+ *     so the caller can hydrate the app's User.
+ *
+ * Tokens are encrypted via the Model's `@encrypt` decorators —
+ * Repository hydration handles it transparently. Apps must have
+ * an `EncryptionProvider` registered; otherwise the first
+ * encrypt/decrypt throws `ConfigError`.
+ */
+
+// biome-ignore lint/style/useImportType: PostgresDatabase + SchemaRegistry value imports 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 { SocialAccount } from './social_account.ts'
+import { socialAccountSchema } from './social_account_schema.ts'
+
+export interface ConnectInput {
+  /** App-side user id. */
+  userId: string
+  /** Provider-instance name (matches `social.use(name)`). Distinct from `profile.provider` when one driver is wired under multiple names. */
+  provider: string
+  profile: SocialProfile
+  tokens: OAuthTokens
+}
+
+export interface DisconnectInput {
+  userId: string
+  provider: string
+}
+
+@inject()
+export class SocialAccountRepository extends Repository<SocialAccount> {
+  static override readonly schema = socialAccountSchema
+  static override readonly model = SocialAccount
+
+  // 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 — apps must register EncryptionProvider before this repository resolves.
+  constructor(
+    db: PostgresDatabase,
+    events: EventBus,
+    registry?: SchemaRegistry,
+    cipher?: Cipher,
+  ) {
+    super(db, events, registry, cipher)
+  }
+
+  /**
+   * Upsert a social account by `(provider, provider_user_id)`.
+   * Insert on first link; update tokens + cached profile fields
+   * on subsequent sign-ins.
+   *
+   * No tenant scoping required — the default schema is
+   * non-tenanted. Apps that opted into the tenanted variant
+   * (`@strav/social/tenanted`) wrap calls in
+   * `TenantManager.withTenant(...)`; that variant ships its own
+   * Repository.
+   */
+  async connect(input: ConnectInput): Promise<SocialAccount> {
+    const existing = await this.findByProviderIdentity(
+      input.provider,
+      input.profile.id,
+    )
+    const now = new Date()
+
+    if (existing) {
+      // Cross-user link guard: if the existing row belongs to a
+      // different user, refuse — the app needs to resolve the
+      // conflict explicitly (typically "this Google account is
+      // already linked to another user").
+      if (existing.user_id !== input.userId) {
+        throw new SocialAccountAlreadyLinkedError({
+          provider: input.provider,
+          providerUserId: input.profile.id,
+          existingUserId: existing.user_id,
+          attemptedUserId: input.userId,
+        })
+      }
+      // Same user, returning sign-in: refresh tokens + cached
+      // profile fields via the standard Repository.update path
+      // (handles `@cast` / `@encrypt` round-trips for us).
+      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<SocialAccount>)
+    }
+
+    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<SocialAccount>)
+  }
+
+  /** Delete the link. No-op when nothing matches. */
+  async disconnect(input: DisconnectInput): Promise<void> {
+    const table = quoteIdent(socialAccountSchema.name)
+    await this.db.execute(
+      `DELETE FROM ${table} WHERE "user_id" = $1 AND "provider" = $2`,
+      [input.userId, input.provider],
+    )
+  }
+
+  /** Every social account linked to one user. */
+  async findByUser(userId: string): Promise<SocialAccount[]> {
+    const table = quoteIdent(socialAccountSchema.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)))
+  }
+
+  /** Single (user, provider) lookup. */
+  async findByUserAndProvider(
+    userId: string,
+    provider: string,
+  ): Promise<SocialAccount | null> {
+    const table = quoteIdent(socialAccountSchema.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]!)
+  }
+
+  /**
+   * The sign-in lookup: given an OAuth identity, find the user
+   * it belongs to. Returns the account row (which includes
+   * `user_id`) or `null` when no link exists.
+   */
+  async findByProviderIdentity(
+    provider: string,
+    providerUserId: string,
+  ): Promise<SocialAccount | null> {
+    const table = quoteIdent(socialAccountSchema.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]!)
+  }
+}
+
+/**
+ * Thrown when an OAuth identity is already linked to a DIFFERENT
+ * user than the caller is trying to attach it to. Apps catch this
+ * and surface a UI ("this Google account is already linked to
+ * <other_email>"). The framework refuses to silently move the
+ * link or fork the row.
+ */
+export class SocialAccountAlreadyLinkedError extends Error {
+  readonly provider: string
+  readonly providerUserId: string
+  readonly existingUserId: string
+  readonly attemptedUserId: string
+
+  constructor(info: {
+    provider: string
+    providerUserId: string
+    existingUserId: string
+    attemptedUserId: string
+  }) {
+    super(
+      `SocialAccount: provider "${info.provider}" identity "${info.providerUserId}" is already linked to user "${info.existingUserId}"; refusing to relink to "${info.attemptedUserId}".`,
+    )
+    this.name = 'SocialAccountAlreadyLinkedError'
+    this.provider = info.provider
+    this.providerUserId = info.providerUserId
+    this.existingUserId = info.existingUserId
+    this.attemptedUserId = info.attemptedUserId
+  }
+}

package/src/ledger/social_account_schema.ts

@@ -0,0 +1,75 @@
+/**
+ * `socialAccountSchema` — ledger of provider identities linked
+ * to app users. **Non-tenanted by default** (framework policy:
+ * multitenancy is opt-in). Apps that need per-tenant scoping
+ * import `tenantedSocialAccountSchema` from
+ * `@strav/social/tenanted` instead.
+ *
+ * Natural key is `(provider, provider_user_id)` — a given
+ * Google / Line / Facebook identity belongs to exactly one
+ * user. Composite uniqueness lives in the migration (the schema
+ * builder only exposes per-column `.unique()`).
+ *
+ * Tokens are encrypted-at-rest via `@strav/database`'s
+ * `t.encrypted(...)` column kind + `@encrypt` decorator on the
+ * Model. Apps must have an `EncryptionProvider` registered on
+ * the kernel container; otherwise the first repository call
+ * throws `ConfigError` at runtime.
+ *
+ * Why store tokens here at all: many apps need long-term
+ * offline access (Google `access_type=offline`) or to revoke
+ * later. Apps that only need "did this user sign in via X"
+ * set the encrypted columns to a sentinel via the Repository's
+ * upsert path and discard the real tokens after first use.
+ *
+ * Columns:
+ *
+ *   - `id`                 ULID PK.
+ *   - `user_id`            App-side user reference. Free-form
+ *                          string so apps with ULID / int / uuid
+ *                          PKs all fit.
+ *   - `provider`           Driver identifier (`'line'` /
+ *                          `'google'` / `'facebook'` / custom).
+ *   - `provider_user_id`   Provider-native subject id (Google
+ *                          `sub`, Line `userId`, Facebook `id`).
+ *   - `email`              Last known email — cached for app
+ *                          UI; canonical lookups go to the user.
+ *   - `name`               Last known display name.
+ *   - `avatar_url`         Last known avatar URL.
+ *   - `locale`             Last known locale (where the provider
+ *                          gives one; Line doesn't).
+ *   - `access_token`       Encrypted-at-rest.
+ *   - `refresh_token`      Encrypted-at-rest. Nullable (Facebook
+ *                          doesn't issue them).
+ *   - `id_token`           Encrypted-at-rest. Nullable (OIDC
+ *                          providers only).
+ *   - `expires_at`         When the access token expires.
+ *   - `scope`              Space-separated granted scope string.
+ *   - `metadata`           Free-form jsonb (provider extras).
+ *   - `created_at` / `updated_at`
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const socialAccountSchema = 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()
+  },
+)

package/src/line/index.ts

@@ -0,0 +1,12 @@
+// Public API of `@strav/social/line`.
+
+export {
+  LINE_ENDPOINTS,
+  type LineProviderConfig,
+} from './line_config.ts'
+export {
+  emailFromLineIdToken,
+  LineSocialDriver,
+  type LineDriverOptions,
+} from './line_driver.ts'
+export { LineSocialProvider } from './line_provider.ts'

package/src/line/line_config.ts

@@ -0,0 +1,47 @@
+/**
+ * Line-specific provider config. Apps put one of these inside
+ * `config.social.providers[name]` with `driver: 'line'`.
+ *
+ * Get credentials from https://developers.line.biz/console — a
+ * Line Login channel under a provider. The `email` scope
+ * additionally needs the "email permission" toggle to be enabled
+ * inside the channel (Line approval required for production).
+ */
+
+import type { ProviderConfig } from '../types.ts'
+
+export interface LineProviderConfig extends ProviderConfig {
+  driver: 'line'
+  /** Channel ID from the Line Developers console. */
+  clientId: string
+  /** Channel secret from the Line Developers console. */
+  clientSecret: string
+  /**
+   * Optional UI locale hint passed on every authorize URL —
+   * `'th-TH'`, `'ja-JP'`, `'en-US'`, … Apps that route by user
+   * locale override per-call via `authorize({ extra: { ui_locales } })`.
+   * Defaults to Line's autodetect.
+   */
+  uiLocales?: string
+  /** Override endpoints for testing — never set in production. */
+  endpoints?: {
+    authorize?: string
+    token?: string
+    profile?: string
+    revoke?: string
+    verify?: string
+  }
+  /**
+   * Custom `fetch` override (tests). Defaults to global `fetch`.
+   * The driver does no other I/O.
+   */
+  fetch?: typeof fetch
+}
+
+export const LINE_ENDPOINTS = {
+  authorize: 'https://access.line.me/oauth2/v2.1/authorize',
+  token: 'https://api.line.me/oauth2/v2.1/token',
+  profile: 'https://api.line.me/v2/profile',
+  revoke: 'https://api.line.me/oauth2/v2.1/revoke',
+  verify: 'https://api.line.me/oauth2/v2.1/verify',
+} as const

package/src/line/line_driver.ts

@@ -0,0 +1,310 @@
+/**
+ * `LineSocialDriver` — Line Login v2.1 implementation.
+ *
+ * Line is SEA-load-bearing: dominant chat + login in Thailand
+ * and Japan, growing across SEA more generally. Strav defaults
+ * to Line as the primary social adapter; Google + Facebook
+ * round out the international + global-reach options.
+ *
+ * Line specifics worth knowing:
+ *
+ *   - **Scopes**: `profile` (always free), `openid` (free —
+ *     returns an id_token), `email` (requires Line approval on
+ *     the channel, then granted per-user via the consent screen).
+ *   - **PKCE**: supported, not required.
+ *   - **Email**: only available by decoding the id_token JWT
+ *     when `openid email` was both requested AND granted. Line
+ *     does NOT include email on the `/v2/profile` REST response.
+ *   - **id_token verification**: the driver decodes JWT claims
+ *     for the `email` field but does NOT verify the JWS
+ *     signature. The token arrives over TLS direct from Line's
+ *     token endpoint, so the trust boundary is the same as the
+ *     access token. Apps that want signature verification
+ *     against Line's JWKS run it themselves or use the
+ *     `/oauth2/v2.1/verify` endpoint via `driver.client`.
+ *   - **No locale field on profile** — apps that need it pass
+ *     `ui_locales` on authorize and store the app-side choice
+ *     alongside the user record.
+ *
+ * Token / refresh / revoke all use the standard OAuth2 endpoints.
+ */
+
+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 { LINE_ENDPOINTS, type LineProviderConfig } from './line_config.ts'
+
+const PROVIDER = 'line'
+
+const CAPS: readonly SocialCapability[] = [
+  'openid', 'pkce.support',
+  'profile.id', 'profile.email', 'profile.emailVerified',
+  'profile.name', 'profile.avatar',
+  // No `profile.locale` — Line doesn't return locale on the profile API.
+  'tokens.exchange', 'tokens.refresh', 'tokens.revoke', 'tokens.introspect',
+  'scopes.discoverable',
+]
+
+const SCOPES: readonly string[] = ['openid', 'profile', 'email']
+
+export interface LineDriverOptions {
+  instanceName: string
+  config: LineProviderConfig
+}
+
+interface TokenResponse {
+  access_token: string
+  expires_in: number
+  id_token?: string
+  refresh_token?: string
+  scope?: string
+  token_type: string
+}
+
+interface ProfileResponse {
+  userId: string
+  displayName: string
+  pictureUrl?: string
+  statusMessage?: string
+}
+
+interface JwtPayload {
+  email?: string
+  email_verified?: boolean
+  name?: string
+  picture?: string
+  sub?: string
+  [k: string]: unknown
+}
+
+export class LineSocialDriver implements SocialDriver {
+  readonly name = PROVIDER
+  readonly instanceName: string
+  readonly capabilities: ReadonlySet<SocialCapability> = new Set(CAPS)
+  readonly availableScopes = SCOPES
+
+  private readonly config: LineProviderConfig
+  private readonly fetchFn: typeof fetch
+  private readonly endpoints: { authorize: string; token: string; profile: string; revoke: string; verify: string }
+
+  constructor(options: LineDriverOptions) {
+    this.instanceName = options.instanceName
+    this.config = options.config
+    this.fetchFn = options.config.fetch ?? fetch
+    this.endpoints = { ...LINE_ENDPOINTS, ...(options.config.endpoints ?? {}) }
+  }
+
+  async authorize(input: AuthorizeInput): Promise<AuthorizeResult> {
+    const state = input.state ?? randomState()
+    // PKCE: Line supports but doesn't require. We default to
+    // including it (defence in depth for callback hijacking on
+    // mobile + SPA flows; harmless on server-side flows). Apps
+    // that explicitly pass `codeVerifier: undefined` opt out by
+    // sending `extra.no_pkce: '1'`.
+    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 ?? ['profile']
+    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' } : {}),
+      ...(this.config.uiLocales ? { ui_locales: this.config.uiLocales } : {}),
+      ...(input.extra ?? {}),
+    })
+    // Don't leak the framework helper through to Line.
+    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(
+        `LineSocialDriver.exchange: token endpoint returned ${res.status}.`,
+        { context: { status: res.status, body: text } },
+      )
+    }
+    const json = (await res.json()) as TokenResponse
+    return this.toOAuthTokens(json)
+  }
+
+  async profile(accessToken: string): Promise<SocialProfile> {
+    const res = await this.fetchFn(this.endpoints.profile, {
+      headers: { authorization: `Bearer ${accessToken}` },
+    })
+    if (res.status === 401) {
+      throw new InvalidTokenError('LineSocialDriver.profile: access token rejected.')
+    }
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SocialProviderError(
+        `LineSocialDriver.profile: profile endpoint returned ${res.status}.`,
+        { provider: PROVIDER, operation: 'profile', context: { status: res.status, body: text } },
+      )
+    }
+    const p = (await res.json()) as ProfileResponse
+    return {
+      id: p.userId,
+      provider: PROVIDER,
+      ...(p.displayName ? { name: p.displayName } : {}),
+      ...(p.pictureUrl ? { avatarUrl: p.pictureUrl } : {}),
+      // Email is NOT on /v2/profile. Apps that need it decoded the
+      // id_token at exchange time and stored it on the user record.
+      metadata: p.statusMessage ? { statusMessage: p.statusMessage } : {},
+      raw: p,
+    }
+  }
+
+  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(
+        `LineSocialDriver.refresh: refresh token rejected.`,
+        { context: { status: res.status, body: text } },
+      )
+    }
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SocialProviderError(
+        `LineSocialDriver.refresh: token endpoint returned ${res.status}.`,
+        { provider: PROVIDER, operation: 'refresh', context: { status: res.status, body: text } },
+      )
+    }
+    return this.toOAuthTokens((await res.json()) as TokenResponse)
+  }
+
+  async revoke(token: string): Promise<void> {
+    const body = new URLSearchParams({
+      access_token: token,
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret,
+    })
+    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(
+        `LineSocialDriver.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
+    const tokens: OAuthTokens = {
+      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,
+    }
+    return tokens
+  }
+}
+
+/**
+ * Extract `email` from a Line id_token. Returns the email
+ * string when present, `null` when the id_token has no email
+ * claim (typical when `email` scope wasn't requested or
+ * granted), and throws when the token is structurally invalid.
+ *
+ * Apps that need the email at signup time decode the id_token
+ * right after `exchange()`. The framework deliberately keeps
+ * this as a side helper rather than auto-decoding inside
+ * `exchange()` — the OIDC id_token has many claims; surfacing
+ * email-only matches the most common app need, anything else
+ * stays on `tokens.idToken` for apps to parse themselves.
+ *
+ * **Security note**: this does NOT verify the JWS signature.
+ * The id_token arrives over TLS direct from Line's token
+ * endpoint in the same response as the access token; trusting
+ * the payload at that point has the same posture as trusting
+ * the access token. Apps that want full verification call
+ * Line's `/oauth2/v2.1/verify` endpoint with the id_token.
+ */
+export function emailFromLineIdToken(idToken: string): string | null {
+  const segments = idToken.split('.')
+  if (segments.length !== 3) {
+    throw new InvalidTokenError('emailFromLineIdToken: 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 {
+  // base64url → base64 → string
+  const pad = segment.length % 4
+  const padded = pad === 0 ? segment : `${segment}${'='.repeat(4 - pad)}`
+  const b64 = padded.replace(/-/g, '+').replace(/_/g, '/')
+  try {
+    const json = atob(b64)
+    return JSON.parse(json) as JwtPayload
+  } catch (cause) {
+    throw new InvalidTokenError('decodeJwtSegment: failed to parse JWT segment.', {
+      cause,
+    })
+  }
+}

package/src/line/line_provider.ts

@@ -0,0 +1,34 @@
+/**
+ * `LineSocialProvider` — `ServiceProvider` that registers the
+ * Line driver factory on the `SocialManager`.
+ *
+ * List AFTER `SocialProvider` in `bootstrap/providers.ts`. The
+ * factory is invoked lazily on first `social.use(name)`; misconfigured
+ * Line credentials surface on first use, not at boot. Apps that
+ * want fail-fast call `social.use('line')` from their own `boot()`.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { SocialConfigError } from '../social_error.ts'
+import { SocialManager } from '../social_manager.ts'
+import type { LineProviderConfig } from './line_config.ts'
+import { LineSocialDriver } from './line_driver.ts'
+
+export class LineSocialProvider extends ServiceProvider {
+  override readonly name = 'social-line'
+  override readonly dependencies = ['social']
+
+  override register(app: Application): void {
+    const manager = app.resolve(SocialManager)
+    manager.extend('line', ({ instanceName, config }) => {
+      const cfg = config as LineProviderConfig
+      if (!cfg.clientId || !cfg.clientSecret) {
+        throw new SocialConfigError(
+          `LineSocialProvider: \`clientId\` and \`clientSecret\` are required for provider "${instanceName}".`,
+          { context: { instanceName } },
+        )
+      }
+      return new LineSocialDriver({ instanceName, config: cfg })
+    })
+  }
+}