@mantiq/social-auth 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@mantiq/social-auth",
+  "version": "0.1.0",
+  "description": "Social authentication — login with Google, GitHub, Facebook, Apple, and more via extensible providers",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/mantiqjs/mantiq/tree/main/packages/social-auth",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mantiqjs/mantiq.git",
+    "directory": "packages/social-auth"
+  },
+  "bugs": {
+    "url": "https://github.com/mantiqjs/mantiq/issues"
+  },
+  "keywords": ["mantiq", "social-auth", "oauth", "google", "github", "facebook", "apple", "login"],
+  "engines": { "bun": ">=1.1.0" },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": { ".": { "bun": "./src/index.ts", "default": "./src/index.ts" } },
+  "files": ["src/", "package.json", "README.md"],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --packages=external",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@mantiq/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0",
+    "@mantiq/core": "workspace:*"
+  }
+}

package/src/AbstractProvider.ts

@@ -0,0 +1,131 @@
+import type { OAuthProvider } from './contracts/OAuthProvider.ts'
+import type { OAuthUser } from './contracts/OAuthUser.ts'
+
+export interface ProviderConfig {
+  clientId: string
+  clientSecret: string
+  redirectUrl: string
+}
+
+/**
+ * Base class implementing the OAuth 2.0 authorization code flow.
+ *
+ * Subclasses must implement:
+ * - `getAuthUrl()` — the provider's authorization endpoint
+ * - `getTokenUrl()` — the provider's token exchange endpoint
+ * - `getUserByToken(token)` — fetch the raw user profile from the provider
+ * - `mapUserToObject(raw)` — normalize the raw profile into an OAuthUser
+ */
+export abstract class AbstractProvider implements OAuthProvider {
+  abstract readonly name: string
+
+  protected clientId: string
+  protected clientSecret: string
+  protected redirectUrl: string
+  protected _scopes: string[] = []
+  protected _params: Record<string, string> = {}
+  protected _stateless = false
+
+  constructor(config: ProviderConfig) {
+    this.clientId = config.clientId
+    this.clientSecret = config.clientSecret
+    this.redirectUrl = config.redirectUrl
+  }
+
+  // ── Abstract (provider-specific) ─────────────────────────────────────────
+
+  protected abstract getAuthUrl(): string
+  protected abstract getTokenUrl(): string
+  protected abstract getUserByToken(token: string): Promise<Record<string, any>>
+  protected abstract mapUserToObject(raw: Record<string, any>): OAuthUser
+
+  // ── OAuth 2.0 flow ───────────────────────────────────────────────────────
+
+  redirect(): Response {
+    const url = new URL(this.getAuthUrl())
+    url.searchParams.set('client_id', this.clientId)
+    url.searchParams.set('redirect_uri', this.redirectUrl)
+    url.searchParams.set('response_type', 'code')
+    url.searchParams.set('scope', this._scopes.join(' '))
+
+    if (!this._stateless) {
+      const state = crypto.randomUUID()
+      url.searchParams.set('state', state)
+    }
+
+    for (const [k, v] of Object.entries(this._params)) {
+      url.searchParams.set(k, v)
+    }
+
+    return Response.redirect(url.toString(), 302)
+  }
+
+  async user(request: any): Promise<OAuthUser> {
+    const code = typeof request?.query === 'function'
+      ? request.query('code')
+      : new URL(request.url).searchParams.get('code')
+
+    if (!code) {
+      throw new Error('Authorization code not found in callback')
+    }
+
+    const tokenData = await this.getAccessToken(code)
+    const rawUser = await this.getUserByToken(tokenData.access_token)
+    const oauthUser = this.mapUserToObject(rawUser)
+    oauthUser.token = tokenData.access_token
+    oauthUser.refreshToken = tokenData.refresh_token ?? null
+    oauthUser.expiresIn = tokenData.expires_in ?? null
+    return oauthUser
+  }
+
+  async userFromToken(accessToken: string): Promise<OAuthUser> {
+    const raw = await this.getUserByToken(accessToken)
+    const user = this.mapUserToObject(raw)
+    user.token = accessToken
+    return user
+  }
+
+  // ── Token exchange ───────────────────────────────────────────────────────
+
+  protected async getAccessToken(
+    code: string,
+  ): Promise<{ access_token: string; refresh_token?: string; expires_in?: number }> {
+    const res = 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.clientId,
+        client_secret: this.clientSecret,
+        code,
+        redirect_uri: this.redirectUrl,
+      }),
+    })
+
+    if (!res.ok) {
+      throw new Error(`Token exchange failed: ${res.status}`)
+    }
+
+    return res.json() as Promise<{ access_token: string; refresh_token?: string; expires_in?: number }>
+  }
+
+  // ── Fluent configuration ─────────────────────────────────────────────────
+
+  scopes(scopes: string[]): this {
+    this._scopes = scopes
+    return this
+  }
+
+  with(params: Record<string, string>): this {
+    Object.assign(this._params, params)
+    return this
+  }
+
+  stateless(): this {
+    this._stateless = true
+    return this
+  }
+}

package/src/SocialAuthManager.ts

@@ -0,0 +1,110 @@
+import type { OAuthProvider } from './contracts/OAuthProvider.ts'
+import type { ProviderConfig } from './AbstractProvider.ts'
+import { GoogleProvider } from './providers/GoogleProvider.ts'
+import { GitHubProvider } from './providers/GitHubProvider.ts'
+import { FacebookProvider } from './providers/FacebookProvider.ts'
+import { AppleProvider } from './providers/AppleProvider.ts'
+import { TwitterProvider } from './providers/TwitterProvider.ts'
+import { LinkedInProvider } from './providers/LinkedInProvider.ts'
+import { MicrosoftProvider } from './providers/MicrosoftProvider.ts'
+import { DiscordProvider } from './providers/DiscordProvider.ts'
+
+export interface SocialAuthConfig {
+  [provider: string]: ProviderConfig
+}
+
+/**
+ * Manager for social authentication providers.
+ *
+ * Lazily instantiates providers on first access and caches them.
+ * Supports all 8 built-in providers and custom providers via `extend()`.
+ *
+ * @example
+ * const manager = new SocialAuthManager(config)
+ * const github = manager.driver('github')
+ * return github.redirect()
+ */
+export class SocialAuthManager {
+  private readonly instances = new Map<string, OAuthProvider>()
+  private readonly customCreators = new Map<string, (config: ProviderConfig) => OAuthProvider>()
+
+  /** Built-in provider name → constructor mapping. */
+  private static readonly builtInProviders: Record<
+    string,
+    new (config: ProviderConfig) => OAuthProvider
+  > = {
+    google: GoogleProvider,
+    github: GitHubProvider,
+    facebook: FacebookProvider,
+    apple: AppleProvider,
+    twitter: TwitterProvider,
+    linkedin: LinkedInProvider,
+    microsoft: MicrosoftProvider,
+    discord: DiscordProvider,
+  }
+
+  constructor(private readonly config: SocialAuthConfig) {}
+
+  /**
+   * Get a provider instance by name (lazy init + cache).
+   */
+  driver(name: string): OAuthProvider {
+    if (!this.instances.has(name)) {
+      this.instances.set(name, this.createDriver(name))
+    }
+
+    return this.instances.get(name)!
+  }
+
+  /**
+   * Register a custom provider factory.
+   * Overrides built-in providers if the name matches.
+   */
+  extend(name: string, factory: (config: ProviderConfig) => OAuthProvider): void {
+    this.customCreators.set(name, factory)
+    // Clear cached instance so the new factory takes effect
+    this.instances.delete(name)
+  }
+
+  /**
+   * List all available provider names (built-in + custom + configured).
+   */
+  getProviders(): string[] {
+    const names = new Set<string>([
+      ...Object.keys(SocialAuthManager.builtInProviders),
+      ...this.customCreators.keys(),
+      ...Object.keys(this.config),
+    ])
+    return [...names]
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────
+
+  private createDriver(name: string): OAuthProvider {
+    // Custom creators take precedence — they may not need config
+    const custom = this.customCreators.get(name)
+    if (custom) {
+      const providerConfig = this.config[name] ?? {}
+      return custom(providerConfig as ProviderConfig)
+    }
+
+    const providerConfig = this.config[name]
+    if (!providerConfig) {
+      throw new Error(
+        `Social auth provider "${name}" is not configured. ` +
+          `Add it to your social-auth config file.`,
+      )
+    }
+
+    // Built-in providers
+    const ProviderClass = SocialAuthManager.builtInProviders[name]
+    if (ProviderClass) {
+      return new ProviderClass(providerConfig)
+    }
+
+    throw new Error(
+      `Unknown social auth provider "${name}". ` +
+        `Use extend() to register custom providers.`,
+    )
+  }
+}

package/src/SocialAuthServiceProvider.ts

@@ -0,0 +1,38 @@
+import { ServiceProvider } from '@mantiq/core'
+import { SocialAuthManager } from './SocialAuthManager.ts'
+import type { SocialAuthConfig } from './SocialAuthManager.ts'
+import { setSocialAuthManager } from './helpers/social-auth.ts'
+import { ConfigRepository } from '@mantiq/core'
+
+/**
+ * Registers the SocialAuthManager in the container and sets the global helper.
+ *
+ * Reads configuration from `config/social-auth.ts` (the `social-auth` config key).
+ *
+ * @example config/social-auth.ts
+ * export default {
+ *   github: {
+ *     clientId: env('GITHUB_CLIENT_ID'),
+ *     clientSecret: env('GITHUB_CLIENT_SECRET'),
+ *     redirectUrl: env('GITHUB_REDIRECT_URL'),
+ *   },
+ *   google: {
+ *     clientId: env('GOOGLE_CLIENT_ID'),
+ *     clientSecret: env('GOOGLE_CLIENT_SECRET'),
+ *     redirectUrl: env('GOOGLE_REDIRECT_URL'),
+ *   },
+ * }
+ */
+export class SocialAuthServiceProvider extends ServiceProvider {
+  override register(): void {
+    const configRepo = this.app.make(ConfigRepository)
+    const socialConfig = configRepo.get<SocialAuthConfig>('social-auth', {})
+
+    this.app.singleton(SocialAuthManager, () => {
+      return new SocialAuthManager(socialConfig)
+    })
+
+    // Set the global helper so socialAuth() works outside the container
+    setSocialAuthManager(this.app.make(SocialAuthManager))
+  }
+}

package/src/contracts/OAuthProvider.ts

@@ -0,0 +1,11 @@
+import type { OAuthUser } from './OAuthUser.ts'
+
+export interface OAuthProvider {
+  readonly name: string
+  redirect(): Response
+  user(request: any): Promise<OAuthUser>
+  userFromToken(accessToken: string): Promise<OAuthUser>
+  scopes(scopes: string[]): this
+  with(params: Record<string, string>): this
+  stateless(): this
+}

package/src/contracts/OAuthUser.ts

@@ -0,0 +1,10 @@
+export interface OAuthUser {
+  id: string
+  name: string | null
+  email: string | null
+  avatar: string | null
+  token: string
+  refreshToken: string | null
+  expiresIn: number | null
+  raw: Record<string, any>
+}

package/src/helpers/social-auth.ts

@@ -0,0 +1,32 @@
+import type { SocialAuthManager } from '../SocialAuthManager.ts'
+
+let _manager: SocialAuthManager | null = null
+
+/**
+ * Set the global SocialAuthManager instance.
+ * Called by SocialAuthServiceProvider during registration.
+ */
+export function setSocialAuthManager(manager: SocialAuthManager): void {
+  _manager = manager
+}
+
+/**
+ * Access the global SocialAuthManager from anywhere.
+ *
+ * @example
+ * const github = socialAuth().driver('github')
+ * return github.redirect()
+ *
+ * @example
+ * const user = await socialAuth().driver('github').user(request)
+ */
+export function socialAuth(): SocialAuthManager {
+  if (!_manager) {
+    throw new Error(
+      'SocialAuthManager has not been initialized. ' +
+        'Register SocialAuthServiceProvider in your application.',
+    )
+  }
+
+  return _manager
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// ── Contracts ────────────────────────────────────────────────────────────────
+export type { OAuthProvider } from './contracts/OAuthProvider.ts'
+export type { OAuthUser } from './contracts/OAuthUser.ts'
+
+// ── Abstract base ────────────────────────────────────────────────────────────
+export { AbstractProvider } from './AbstractProvider.ts'
+export type { ProviderConfig } from './AbstractProvider.ts'
+
+// ── Built-in providers ───────────────────────────────────────────────────────
+export { GoogleProvider } from './providers/GoogleProvider.ts'
+export { GitHubProvider } from './providers/GitHubProvider.ts'
+export { FacebookProvider } from './providers/FacebookProvider.ts'
+export { AppleProvider } from './providers/AppleProvider.ts'
+export { TwitterProvider } from './providers/TwitterProvider.ts'
+export { LinkedInProvider } from './providers/LinkedInProvider.ts'
+export { MicrosoftProvider } from './providers/MicrosoftProvider.ts'
+export { DiscordProvider } from './providers/DiscordProvider.ts'
+
+// ── Manager ──────────────────────────────────────────────────────────────────
+export { SocialAuthManager } from './SocialAuthManager.ts'
+export type { SocialAuthConfig } from './SocialAuthManager.ts'
+
+// ── Service provider ─────────────────────────────────────────────────────────
+export { SocialAuthServiceProvider } from './SocialAuthServiceProvider.ts'
+
+// ── Global helper ────────────────────────────────────────────────────────────
+export { socialAuth, setSocialAuthManager } from './helpers/social-auth.ts'

package/src/providers/AppleProvider.ts

@@ -0,0 +1,144 @@
+import { AbstractProvider } from '../AbstractProvider.ts'
+import type { OAuthUser } from '../contracts/OAuthUser.ts'
+
+/**
+ * Apple Sign In provider.
+ *
+ * Apple is unique among OAuth providers:
+ * - User info is embedded in the `id_token` JWT (there is no userinfo endpoint)
+ * - The callback uses `response_mode=form_post` (POST with form data)
+ * - The user's name is only sent on the FIRST authorization; subsequent logins
+ *   only include the id_token with sub + email
+ */
+export class AppleProvider extends AbstractProvider {
+  override readonly name = 'apple'
+
+  protected override _scopes: string[] = ['name', 'email']
+  protected override _params: Record<string, string> = {
+    response_mode: 'form_post',
+  }
+
+  protected override getAuthUrl(): string {
+    return 'https://appleid.apple.com/auth/authorize'
+  }
+
+  protected override getTokenUrl(): string {
+    return 'https://appleid.apple.com/auth/token'
+  }
+
+  /**
+   * Apple does not have a userinfo endpoint. User details come from the
+   * id_token JWT returned during the token exchange. We decode the JWT
+   * payload without verification (the token was just received over TLS
+   * from Apple's server).
+   */
+  protected override async getUserByToken(token: string): Promise<Record<string, any>> {
+    // The "token" here is actually the id_token from the token response.
+    // We store the full token response in _lastTokenResponse so we can
+    // decode the id_token.
+    return this.decodeIdToken(token)
+  }
+
+  protected override mapUserToObject(raw: Record<string, any>): OAuthUser {
+    return {
+      id: String(raw.sub),
+      name: raw.name ?? null,
+      email: raw.email ?? null,
+      avatar: null, // Apple does not provide avatar URLs
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      raw,
+    }
+  }
+
+  /**
+   * Override the user() method to extract user info from the id_token
+   * rather than calling a userinfo endpoint.
+   */
+  override async user(request: any): Promise<OAuthUser> {
+    const code = typeof request?.query === 'function'
+      ? request.query('code')
+      : this.extractCode(request)
+
+    if (!code) {
+      throw new Error('Authorization code not found in callback')
+    }
+
+    const tokenData = await this.getAccessToken(code)
+
+    // Apple returns an id_token alongside the access_token
+    const idToken = (tokenData as any).id_token
+    if (!idToken) {
+      throw new Error('Apple did not return an id_token')
+    }
+
+    const claims = this.decodeIdToken(idToken)
+
+    // On first authorization, Apple sends user info in the POST body
+    const userName = this.extractUserName(request)
+    if (userName) {
+      claims.name = userName
+    }
+
+    const oauthUser = this.mapUserToObject(claims)
+    oauthUser.token = tokenData.access_token
+    oauthUser.refreshToken = tokenData.refresh_token ?? null
+    oauthUser.expiresIn = tokenData.expires_in ?? null
+    return oauthUser
+  }
+
+  /**
+   * Decode a JWT id_token payload without signature verification.
+   * Apple's id_token contains: sub, email, email_verified, iss, aud, exp, iat.
+   */
+  private decodeIdToken(idToken: string): Record<string, any> {
+    const parts = idToken.split('.')
+    if (parts.length !== 3) {
+      throw new Error('Invalid id_token format')
+    }
+
+    const payload = parts[1]!
+    const decoded = atob(payload.replace(/-/g, '+').replace(/_/g, '/'))
+    return JSON.parse(decoded)
+  }
+
+  /**
+   * Extract the authorization code from a form_post callback.
+   */
+  private extractCode(request: any): string | null {
+    // Try URL search params first (GET)
+    try {
+      const url = new URL(request.url)
+      const code = url.searchParams.get('code')
+      if (code) return code
+    } catch {
+      // not a valid URL, ignore
+    }
+
+    // Try form body (POST with form_post response_mode)
+    if (request.body?.code) return request.body.code
+    if (request.formData?.code) return request.formData.code
+
+    return null
+  }
+
+  /**
+   * Apple sends the user's name only on first authorization, embedded in the
+   * POST body as a JSON string in the `user` field.
+   */
+  private extractUserName(request: any): string | null {
+    try {
+      const userJson = request.body?.user ?? request.formData?.user
+      if (!userJson) return null
+
+      const userData = typeof userJson === 'string' ? JSON.parse(userJson) : userJson
+      const firstName = userData.name?.firstName ?? ''
+      const lastName = userData.name?.lastName ?? ''
+      const fullName = `${firstName} ${lastName}`.trim()
+      return fullName || null
+    } catch {
+      return null
+    }
+  }
+}

package/src/providers/DiscordProvider.ts

@@ -0,0 +1,51 @@
+import { AbstractProvider } from '../AbstractProvider.ts'
+import type { OAuthUser } from '../contracts/OAuthUser.ts'
+
+/**
+ * Discord OAuth 2.0 provider.
+ *
+ * Fetches user info from Discord's /users/@me endpoint.
+ * Constructs avatar URL from the user's id and avatar hash.
+ */
+export class DiscordProvider extends AbstractProvider {
+  override readonly name = 'discord'
+
+  protected override _scopes: string[] = ['identify', 'email']
+
+  protected override getAuthUrl(): string {
+    return 'https://discord.com/api/oauth2/authorize'
+  }
+
+  protected override getTokenUrl(): string {
+    return 'https://discord.com/api/oauth2/token'
+  }
+
+  protected override async getUserByToken(token: string): Promise<Record<string, any>> {
+    const res = await fetch('https://discord.com/api/users/@me', {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+
+    if (!res.ok) {
+      throw new Error(`Failed to fetch Discord user: ${res.status}`)
+    }
+
+    return res.json() as Promise<Record<string, any>>
+  }
+
+  protected override mapUserToObject(raw: Record<string, any>): OAuthUser {
+    const avatarUrl = raw.avatar
+      ? `https://cdn.discordapp.com/avatars/${raw.id}/${raw.avatar}.png`
+      : null
+
+    return {
+      id: String(raw.id),
+      name: raw.username ?? null,
+      email: raw.email ?? null,
+      avatar: avatarUrl,
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      raw,
+    }
+  }
+}

package/src/providers/FacebookProvider.ts

@@ -0,0 +1,47 @@
+import { AbstractProvider } from '../AbstractProvider.ts'
+import type { OAuthUser } from '../contracts/OAuthUser.ts'
+
+/**
+ * Facebook OAuth 2.0 provider.
+ *
+ * Uses the Graph API v18.0 to fetch user info.
+ */
+export class FacebookProvider extends AbstractProvider {
+  override readonly name = 'facebook'
+
+  protected override _scopes: string[] = ['email']
+
+  protected override getAuthUrl(): string {
+    return 'https://www.facebook.com/v18.0/dialog/oauth'
+  }
+
+  protected override getTokenUrl(): string {
+    return 'https://graph.facebook.com/v18.0/oauth/access_token'
+  }
+
+  protected override async getUserByToken(token: string): Promise<Record<string, any>> {
+    const url = 'https://graph.facebook.com/v18.0/me?fields=id,name,email,picture.type(large)'
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+
+    if (!res.ok) {
+      throw new Error(`Failed to fetch Facebook user: ${res.status}`)
+    }
+
+    return res.json() as Promise<Record<string, any>>
+  }
+
+  protected override mapUserToObject(raw: Record<string, any>): OAuthUser {
+    return {
+      id: String(raw.id),
+      name: raw.name ?? null,
+      email: raw.email ?? null,
+      avatar: raw.picture?.data?.url ?? null,
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      raw,
+    }
+  }
+}

package/src/providers/GitHubProvider.ts

@@ -0,0 +1,80 @@
+import { AbstractProvider } from '../AbstractProvider.ts'
+import type { OAuthUser } from '../contracts/OAuthUser.ts'
+
+/**
+ * GitHub OAuth 2.0 provider.
+ *
+ * GitHub may not return the user's email in the main /user response if the
+ * email is set to private. In that case, we fetch GET /user/emails and pick
+ * the primary verified email.
+ */
+export class GitHubProvider extends AbstractProvider {
+  override readonly name = 'github'
+
+  protected override _scopes: string[] = ['user:email']
+
+  protected override getAuthUrl(): string {
+    return 'https://github.com/login/oauth/authorize'
+  }
+
+  protected override getTokenUrl(): string {
+    return 'https://github.com/login/oauth/access_token'
+  }
+
+  protected override async getUserByToken(token: string): Promise<Record<string, any>> {
+    const res = await fetch('https://api.github.com/user', {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json',
+      },
+    })
+
+    if (!res.ok) {
+      throw new Error(`Failed to fetch GitHub user: ${res.status}`)
+    }
+
+    const user = (await res.json()) as Record<string, any>
+
+    // GitHub may not include email if it's set to private — fetch from /user/emails
+    if (!user.email) {
+      user.email = await this.fetchPrimaryEmail(token)
+    }
+
+    return user
+  }
+
+  protected override mapUserToObject(raw: Record<string, any>): OAuthUser {
+    return {
+      id: String(raw.id),
+      name: raw.name ?? null,
+      email: raw.email ?? null,
+      avatar: raw.avatar_url ?? null,
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      raw,
+    }
+  }
+
+  /**
+   * Fetch the user's primary verified email from the /user/emails endpoint.
+   */
+  private async fetchPrimaryEmail(token: string): Promise<string | null> {
+    try {
+      const res = await fetch('https://api.github.com/user/emails', {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: 'application/json',
+        },
+      })
+
+      if (!res.ok) return null
+
+      const emails = (await res.json()) as Array<{ email: string; primary: boolean; verified: boolean }>
+      const primary = emails.find((e) => e.primary && e.verified)
+      return primary?.email ?? emails[0]?.email ?? null
+    } catch {
+      return null
+    }
+  }
+}

package/src/providers/GoogleProvider.ts

@@ -0,0 +1,47 @@
+import { AbstractProvider } from '../AbstractProvider.ts'
+import type { OAuthUser } from '../contracts/OAuthUser.ts'
+
+/**
+ * Google OAuth 2.0 provider.
+ *
+ * Uses the Google Identity v2 userinfo endpoint.
+ * Default scopes request OpenID Connect profile + email.
+ */
+export class GoogleProvider extends AbstractProvider {
+  override readonly name = 'google'
+
+  protected override _scopes: string[] = ['openid', 'email', 'profile']
+
+  protected override getAuthUrl(): string {
+    return 'https://accounts.google.com/o/oauth2/v2/auth'
+  }
+
+  protected override getTokenUrl(): string {
+    return 'https://oauth2.googleapis.com/token'
+  }
+
+  protected override async getUserByToken(token: string): Promise<Record<string, any>> {
+    const res = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+
+    if (!res.ok) {
+      throw new Error(`Failed to fetch Google user: ${res.status}`)
+    }
+
+    return res.json() as Promise<Record<string, any>>
+  }
+
+  protected override mapUserToObject(raw: Record<string, any>): OAuthUser {
+    return {
+      id: String(raw.sub ?? raw.id),
+      name: raw.name ?? null,
+      email: raw.email ?? null,
+      avatar: raw.picture ?? null,
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      raw,
+    }
+  }
+}

package/src/providers/LinkedInProvider.ts

@@ -0,0 +1,46 @@
+import { AbstractProvider } from '../AbstractProvider.ts'
+import type { OAuthUser } from '../contracts/OAuthUser.ts'
+
+/**
+ * LinkedIn OAuth 2.0 provider.
+ *
+ * Uses the OpenID Connect userinfo endpoint (v2 API).
+ */
+export class LinkedInProvider extends AbstractProvider {
+  override readonly name = 'linkedin'
+
+  protected override _scopes: string[] = ['openid', 'profile', 'email']
+
+  protected override getAuthUrl(): string {
+    return 'https://www.linkedin.com/oauth/v2/authorization'
+  }
+
+  protected override getTokenUrl(): string {
+    return 'https://www.linkedin.com/oauth/v2/accessToken'
+  }
+
+  protected override async getUserByToken(token: string): Promise<Record<string, any>> {
+    const res = await fetch('https://api.linkedin.com/v2/userinfo', {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+
+    if (!res.ok) {
+      throw new Error(`Failed to fetch LinkedIn user: ${res.status}`)
+    }
+
+    return res.json() as Promise<Record<string, any>>
+  }
+
+  protected override mapUserToObject(raw: Record<string, any>): OAuthUser {
+    return {
+      id: String(raw.sub),
+      name: raw.name ?? null,
+      email: raw.email ?? null,
+      avatar: raw.picture ?? null,
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      raw,
+    }
+  }
+}

package/src/providers/MicrosoftProvider.ts

@@ -0,0 +1,47 @@
+import { AbstractProvider } from '../AbstractProvider.ts'
+import type { OAuthUser } from '../contracts/OAuthUser.ts'
+
+/**
+ * Microsoft OAuth 2.0 provider.
+ *
+ * Uses the Microsoft Identity Platform (v2.0) with the /common tenant,
+ * which supports both personal Microsoft accounts and Azure AD accounts.
+ */
+export class MicrosoftProvider extends AbstractProvider {
+  override readonly name = 'microsoft'
+
+  protected override _scopes: string[] = ['openid', 'profile', 'email', 'User.Read']
+
+  protected override getAuthUrl(): string {
+    return 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize'
+  }
+
+  protected override getTokenUrl(): string {
+    return 'https://login.microsoftonline.com/common/oauth2/v2.0/token'
+  }
+
+  protected override async getUserByToken(token: string): Promise<Record<string, any>> {
+    const res = await fetch('https://graph.microsoft.com/v1.0/me', {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+
+    if (!res.ok) {
+      throw new Error(`Failed to fetch Microsoft user: ${res.status}`)
+    }
+
+    return res.json() as Promise<Record<string, any>>
+  }
+
+  protected override mapUserToObject(raw: Record<string, any>): OAuthUser {
+    return {
+      id: String(raw.id),
+      name: raw.displayName ?? null,
+      email: raw.mail ?? raw.userPrincipalName ?? null,
+      avatar: null, // Microsoft Graph photo requires a separate request
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      raw,
+    }
+  }
+}

package/src/providers/TwitterProvider.ts

@@ -0,0 +1,138 @@
+import { AbstractProvider } from '../AbstractProvider.ts'
+import type { OAuthUser } from '../contracts/OAuthUser.ts'
+
+/**
+ * Twitter (X) OAuth 2.0 provider with PKCE.
+ *
+ * Twitter's OAuth 2.0 implementation requires Proof Key for Code Exchange
+ * (PKCE). This provider generates a code_verifier and code_challenge for
+ * each authorization request.
+ */
+export class TwitterProvider extends AbstractProvider {
+  override readonly name = 'twitter'
+
+  protected override _scopes: string[] = ['users.read', 'tweet.read']
+
+  /**
+   * Stored PKCE code_verifier — needed during the token exchange to prove
+   * we are the same client that initiated the authorization request.
+   */
+  private _codeVerifier: string | null = null
+
+  protected override getAuthUrl(): string {
+    return 'https://twitter.com/i/oauth2/authorize'
+  }
+
+  protected override getTokenUrl(): string {
+    return 'https://api.twitter.com/2/oauth2/token'
+  }
+
+  protected override async getUserByToken(token: string): Promise<Record<string, any>> {
+    const res = await fetch(
+      'https://api.twitter.com/2/users/me?user.fields=profile_image_url',
+      {
+        headers: { Authorization: `Bearer ${token}` },
+      },
+    )
+
+    if (!res.ok) {
+      throw new Error(`Failed to fetch Twitter user: ${res.status}`)
+    }
+
+    return res.json() as Promise<Record<string, any>>
+  }
+
+  protected override mapUserToObject(raw: Record<string, any>): OAuthUser {
+    const data = raw.data ?? raw
+    return {
+      id: String(data.id),
+      name: data.name ?? null,
+      email: null, // Twitter does not provide email via this endpoint
+      avatar: data.profile_image_url ?? null,
+      token: '',
+      refreshToken: null,
+      expiresIn: null,
+      raw,
+    }
+  }
+
+  /**
+   * Override redirect to include PKCE parameters.
+   * Twitter requires code_challenge_method=S256.
+   */
+  override redirect(): Response {
+    this._codeVerifier = this.generateCodeVerifier()
+    const challenge = this.generateCodeChallenge(this._codeVerifier)
+
+    this.with({
+      code_challenge: challenge,
+      code_challenge_method: 'S256',
+    })
+
+    return super.redirect()
+  }
+
+  /**
+   * Override token exchange to include the code_verifier.
+   */
+  protected override async getAccessToken(
+    code: string,
+  ): Promise<{ access_token: string; refresh_token?: string; expires_in?: number }> {
+    const body: Record<string, string> = {
+      grant_type: 'authorization_code',
+      client_id: this.clientId,
+      code,
+      redirect_uri: this.redirectUrl,
+    }
+
+    if (this._codeVerifier) {
+      body.code_verifier = this._codeVerifier
+    }
+
+    const credentials = btoa(`${this.clientId}:${this.clientSecret}`)
+    const res = await fetch(this.getTokenUrl(), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+        Authorization: `Basic ${credentials}`,
+      },
+      body: new URLSearchParams(body),
+    })
+
+    if (!res.ok) {
+      throw new Error(`Token exchange failed: ${res.status}`)
+    }
+
+    return res.json() as Promise<{ access_token: string; refresh_token?: string; expires_in?: number }>
+  }
+
+  /**
+   * Generate a random code_verifier for PKCE.
+   * Must be between 43 and 128 characters (RFC 7636).
+   */
+  private generateCodeVerifier(): string {
+    const bytes = new Uint8Array(32)
+    crypto.getRandomValues(bytes)
+    return this.base64UrlEncode(bytes)
+  }
+
+  /**
+   * Generate a SHA-256 code_challenge from the code_verifier.
+   */
+  private generateCodeChallenge(verifier: string): string {
+    // Use synchronous approach: hash the verifier with SHA-256
+    const encoder = new TextEncoder()
+    const data = encoder.encode(verifier)
+    const hashBuffer = new Bun.CryptoHasher('sha256').update(data).digest()
+    return this.base64UrlEncode(new Uint8Array(hashBuffer))
+  }
+
+  /**
+   * Base64url encode bytes (no padding, URL-safe).
+   */
+  private base64UrlEncode(bytes: Uint8Array): string {
+    const base64 = btoa(String.fromCharCode(...bytes))
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+  }
+}