Documentation

Provider API

Provider API reference for OAuth, email, and two-factor authentication.

OAuth Providers

All OAuth providers follow a consistent pattern and support PKCE (Proof Key for Code Exchange) with S256 enabled by default for enhanced security.

google

Google OAuth 2.0 provider with OpenID Connect

google(options: GoogleProviderOptions): OAuthProviderConfig

Parameters

clientIdstringrequired

Google OAuth client ID from Google Cloud Console

clientSecretstringrequired

Google OAuth client secret

redirectUristringrequired

OAuth callback URL (must match Google Console config)

scopestring[]

OAuth scopes to request

pkce"S256" | "plain" | false

PKCE method (default: "S256")

Returns

OAuthProviderConfig

Example

import { google } from '@warpy-auth-sdk/core';

const provider = google({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/google',
  scope: ['openid', 'email', 'profile'], // Optional, these are defaults
  pkce: 'S256', // Optional, S256 is default
});

facebook

Facebook OAuth 2.0 provider

facebook(options: FacebookProviderOptions): OAuthProviderConfig

Parameters

clientIdstringrequired

Facebook App ID

clientSecretstringrequired

Facebook App Secret

redirectUristringrequired

OAuth callback URL

scopestring[]

OAuth scopes (default: ["email", "public_profile"])

pkce"S256" | "plain" | false

PKCE method (default: "S256")

Returns

OAuthProviderConfig

Example

import { facebook } from '@warpy-auth-sdk/core';

const provider = facebook({
  clientId: process.env.FACEBOOK_CLIENT_ID!,
  clientSecret: process.env.FACEBOOK_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/facebook',
});

github

GitHub OAuth 2.0 provider with private email handling

github(options: GitHubProviderOptions): OAuthProviderConfig

Parameters

clientIdstringrequired

GitHub OAuth App client ID

clientSecretstringrequired

GitHub OAuth App client secret

redirectUristringrequired

OAuth callback URL

scopestring[]

OAuth scopes (default: ["user:email"])

pkce"S256" | "plain" | false

PKCE method (default: "S256")

Returns

OAuthProviderConfig

Example

import { github } from '@warpy-auth-sdk/core';

const provider = github({
  clientId: process.env.GITHUB_CLIENT_ID!,
  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/github',
  scope: ['user:email'], // Optional, includes private emails
});

gitlab

GitLab OAuth 2.0 provider with self-hosted support

gitlab(options: GitLabProviderOptions): OAuthProviderConfig

Parameters

clientIdstringrequired

GitLab OAuth application ID

clientSecretstringrequired

GitLab OAuth application secret

redirectUristringrequired

OAuth callback URL

baseUrlstring

GitLab instance URL (default: "https://gitlab.com")

scopestring[]

OAuth scopes (default: ["read_user"])

pkce"S256" | "plain" | false

PKCE method (default: "S256")

Returns

OAuthProviderConfig

Example

import { gitlab } from '@warpy-auth-sdk/core';

// GitLab.com
const provider = gitlab({
  clientId: process.env.GITLAB_CLIENT_ID!,
  clientSecret: process.env.GITLAB_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/gitlab',
});

// Self-hosted GitLab
const selfHosted = gitlab({
  clientId: process.env.GITLAB_CLIENT_ID!,
  clientSecret: process.env.GITLAB_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/gitlab',
  baseUrl: 'https://gitlab.company.com',
});

linkedin

LinkedIn OAuth 2.0 provider with OpenID Connect

linkedin(options: LinkedInProviderOptions): OAuthProviderConfig

Parameters

clientIdstringrequired

LinkedIn App client ID

clientSecretstringrequired

LinkedIn App client secret

redirectUristringrequired

OAuth callback URL

scopestring[]

OAuth scopes (default: ["openid", "profile", "email"])

pkce"S256" | "plain" | false

PKCE method (default: "S256")

Returns

OAuthProviderConfig

Example

import { linkedin } from '@warpy-auth-sdk/core';

const provider = linkedin({
  clientId: process.env.LINKEDIN_CLIENT_ID!,
  clientSecret: process.env.LINKEDIN_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/linkedin',
});

microsoft

Microsoft/Azure AD OAuth 2.0 provider with multi-tenant support

microsoft(options: MicrosoftProviderOptions): OAuthProviderConfig

Parameters

clientIdstringrequired

Azure AD application (client) ID

clientSecretstringrequired

Azure AD client secret

redirectUristringrequired

OAuth callback URL

tenantstring

Azure AD tenant ID or "common"/"organizations" (default: "common")

scopestring[]

OAuth scopes (default: ["openid", "profile", "email"])

pkce"S256" | "plain" | false

PKCE method (default: "S256")

Returns

OAuthProviderConfig

Example

import { microsoft } from '@warpy-auth-sdk/core';

// Multi-tenant (any Microsoft account)
const provider = microsoft({
  clientId: process.env.MICROSOFT_CLIENT_ID!,
  clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/microsoft',
  tenant: 'common', // Optional, 'common' is default
});

// Single-tenant (specific organization)
const singleTenant = microsoft({
  clientId: process.env.MICROSOFT_CLIENT_ID!,
  clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/microsoft',
  tenant: 'your-tenant-id',
});

spotify

Spotify OAuth 2.0 provider

spotify(options: SpotifyProviderOptions): OAuthProviderConfig

Parameters

clientIdstringrequired

Spotify App client ID

clientSecretstringrequired

Spotify App client secret

redirectUristringrequired

OAuth callback URL

scopestring[]

OAuth scopes (default: ["user-read-email"])

pkce"S256" | "plain" | false

PKCE method (default: "S256")

Returns

OAuthProviderConfig

Example

import { spotify } from '@warpy-auth-sdk/core';

const provider = spotify({
  clientId: process.env.SPOTIFY_CLIENT_ID!,
  clientSecret: process.env.SPOTIFY_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/spotify',
  scope: ['user-read-email', 'user-read-private'],
});

discord

Discord OAuth 2.0 provider

discord(options: DiscordProviderOptions): OAuthProviderConfig

Parameters

clientIdstringrequired

Discord App client ID

clientSecretstringrequired

Discord App client secret

redirectUristringrequired

OAuth callback URL

scopestring[]

OAuth scopes (default: ["identify", "email"])

pkce"S256" | "plain" | false

PKCE method (default: "S256")

Returns

OAuthProviderConfig

Example

import { discord } from '@warpy-auth-sdk/core';

const provider = discord({
  clientId: process.env.DISCORD_CLIENT_ID!,
  clientSecret: process.env.DISCORD_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/discord',
});

twitch

Twitch OAuth 2.0 provider

twitch(options: TwitchProviderOptions): OAuthProviderConfig

Parameters

clientIdstringrequired

Twitch App client ID

clientSecretstringrequired

Twitch App client secret

redirectUristringrequired

OAuth callback URL

scopestring[]

OAuth scopes (default: ["user:read:email"])

pkce"S256" | "plain" | false

PKCE method (default: "S256")

Returns

OAuthProviderConfig

Example

import { twitch } from '@warpy-auth-sdk/core';

const provider = twitch({
  clientId: process.env.TWITCH_CLIENT_ID!,
  clientSecret: process.env.TWITCH_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/twitch',
});

epic

Epic Games OAuth 2.0 provider

epic(options: EpicProviderOptions): OAuthProviderConfig

Parameters

clientIdstringrequired

Epic Games client ID

clientSecretstringrequired

Epic Games client secret

redirectUristringrequired

OAuth callback URL

scopestring[]

OAuth scopes (default: ["basic_profile"])

pkce"S256" | "plain" | false

PKCE method (default: "S256")

Returns

OAuthProviderConfig

Example

import { epic } from '@warpy-auth-sdk/core';

const provider = epic({
  clientId: process.env.EPIC_CLIENT_ID!,
  clientSecret: process.env.EPIC_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/epic',
});

custom

Custom OAuth 2.0 provider with configurable endpoints and user mapping

custom(options: CustomOAuthProviderOptions): OAuthProviderConfig

Parameters

clientIdstringrequired

OAuth client ID

clientSecretstringrequired

OAuth client secret

redirectUristringrequired

OAuth callback URL

authorizeUrlstringrequired

Authorization endpoint URL

tokenUrlstringrequired

Token endpoint URL

userInfoUrlstringrequired

User info endpoint URL

scopestring[]

OAuth scopes

pkce"S256" | "plain" | false

PKCE method (default: "S256")

mapUser(userInfo: any) => UserProfile

Function to map provider user info to standard UserProfile

Returns

OAuthProviderConfig

Example

import { custom } from '@warpy-auth-sdk/core';

const provider = custom({
  clientId: process.env.CUSTOM_CLIENT_ID!,
  clientSecret: process.env.CUSTOM_CLIENT_SECRET!,
  redirectUri: 'https://example.com/api/auth/callback/custom',
  authorizeUrl: 'https://auth.example.com/oauth/authorize',
  tokenUrl: 'https://auth.example.com/oauth/token',
  userInfoUrl: 'https://auth.example.com/oauth/userinfo',
  scope: ['openid', 'email', 'profile'],
  mapUser: (userInfo) => ({
    id: userInfo.sub || userInfo.id,
    email: userInfo.email,
    name: userInfo.name || userInfo.displayName,
    picture: userInfo.picture || userInfo.avatar,
  }),
});

Email Magic Link Provider

The email provider sends magic links for passwordless authentication. Supports both Nodemailer (SMTP) and Resend email services with React Email templates.

email

Email magic link provider with React Email templates

email(options: EmailProviderOptions): EmailProviderConfig

Parameters

fromstringrequired

From email address

serviceEmailServiceConfigrequired

Email service configuration (Nodemailer or Resend)

templateCustomEmailTemplate

Custom React Email template (optional)

appNamestring

App name for default template (default: "Your App")

companyNamestring

Company name for default template (default: "Your Company")

expirationMinutesnumber

Token expiration in minutes (default: 15)

Returns

EmailProviderConfig

Example

import { email } from '@warpy-auth-sdk/core';

// With Resend
const provider = email({
  from: 'noreply@example.com',
  service: {
    type: 'resend',
    apiKey: process.env.RESEND_API_KEY!,
  },
  appName: 'MyApp',
  companyName: 'Acme Inc',
  expirationMinutes: 15,
});

// With Nodemailer (SMTP)
const nodemailerProvider = email({
  from: 'noreply@example.com',
  service: {
    type: 'nodemailer',
    server: 'smtp.gmail.com:587',
    auth: {
      user: 'user@gmail.com',
      pass: process.env.SMTP_PASSWORD!,
    },
  },
});

// With custom template
const customProvider = email({
  from: 'noreply@example.com',
  service: { type: 'resend', apiKey: process.env.RESEND_API_KEY! },
  template: {
    component: ({ magicLink }) => (
      <MyCustomEmail magicLink={magicLink} />
    ),
    subject: 'Custom Sign In',
  },
});

Two-Factor Email Provider

The two-factor provider sends 6-digit verification codes via email for enhanced security. Supports the same email services as the magic link provider.

twofa

Two-factor email authentication provider with 6-digit codes

twofa(options: TwoFactorProviderOptions): TwoFactorProviderConfig

Parameters

fromstringrequired

From email address

serviceEmailServiceConfigrequired

Email service configuration (Nodemailer or Resend)

templateCustomTwoFactorTemplate

Custom React Email template (optional)

appNamestring

App name for default template (default: "Your App")

companyNamestring

Company name for default template (default: "Your Company")

expirationMinutesnumber

Code expiration in minutes (default: 5)

Returns

TwoFactorProviderConfig

Example

import { twofa } from '@warpy-auth-sdk/core';

const provider = twofa({
  from: 'noreply@example.com',
  service: {
    type: 'resend',
    apiKey: process.env.RESEND_API_KEY!,
  },
  appName: 'MyApp',
  companyName: 'Acme Inc',
  expirationMinutes: 5, // Code valid for 5 minutes
});

Provider Type Definitions

// OAuth Provider
interface OAuthProviderConfig {
  type: "oauth";
  clientId: string;
  clientSecret: string;
  authorizeUrl: string;
  tokenUrl: string;
  userInfoUrl: string;
  redirectUri: string;
  scope?: string[];
  pkce?: "S256" | "plain" | false;
  getUser: (accessToken: string) => Promise<UserProfile>;
}

// Email Provider
interface EmailProviderConfig {
  type: "email";
  server: string;
  from: string;
  sendMagicLink: (email: string, url: string) => Promise<void>;
  verify: (token: string) => Promise<{ email: string; userId?: string } | null>;
}

// Two-Factor Provider
interface TwoFactorProviderConfig {
  type: "twofa";
  from: string;
  sendCode: (email: string) => Promise<{ identifier: string; expiresIn: number }>;
  verifyCode: (identifier: string, code: string) => Promise<{ email: string; userId?: string } | null>;
}

// User Profile (returned by all providers)
interface UserProfile {
  id: string;
  email: string;
  name?: string;
  picture?: string;
}

// Email Service Configuration
type EmailServiceConfig =
  | { type: 'resend'; apiKey: string }
  | { type: 'nodemailer'; server: string; auth: { user: string; pass: string } };

PKCE Support

Enhanced OAuth Security

All OAuth providers support PKCE (Proof Key for Code Exchange) with S256 enabled by default. PKCE prevents authorization code interception attacks and is recommended for all OAuth flows.

  • S256: SHA-256 challenge (default, most secure)
  • plain: Plain text verifier (legacy servers only)
  • false: Disable PKCE (not recommended)

Provider Configuration Examples

// OAuth with PKCE (recommended) import { google, facebook, github } from '@warpy-auth-sdk/core'; const googleProvider = google({ clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET!, redirectUri: 'https://example.com/api/auth/callback/google', pkce: 'S256', // Default, can be omitted }); // Email magic links import { email } from '@warpy-auth-sdk/core'; const emailProvider = email({ from: 'noreply@example.com', service: { type: 'resend', apiKey: process.env.RESEND_API_KEY!, }, appName: 'MyApp', expirationMinutes: 15, }); // Two-factor authentication import { twofa } from '@warpy-auth-sdk/core'; const twofaProvider = twofa({ from: 'noreply@example.com', service: { type: 'resend', apiKey: process.env.RESEND_API_KEY!, }, appName: 'MyApp', expirationMinutes: 5, });

Important Notes

  • Store OAuth secrets securely in environment variables
  • Redirect URIs must match exactly in provider console configuration
  • Email providers require server runtime (Node.js) for email sending
  • Two-factor codes are single-use and expire after the configured time
  • Custom OAuth providers require manual user info mapping
Adapter API
Provider API | @warpy-auth-sdk/core