Documentation

Providers Overview

Understanding the provider architecture in @warpy-auth-sdk/core.

What are Providers?

Providers in @warpy-auth-sdk/core are factory functions that return configuration objects for different authentication methods. They abstract the complexity of OAuth flows, email magic links, and other authentication mechanisms into simple, reusable functions.

Provider Architecture

The provider system is designed to be:

  • Modular: Import only the providers you need
  • Extensible: Easy to create custom providers
  • Type-safe: Full TypeScript support
  • Consistent: Unified API across all providers

Built-in Providers

@warpy-auth-sdk/core comes with several built-in providers:

OAuth Providers

All OAuth providers use PKCE by default with the S256 method and secure HttpOnly cookie storage for verifiers. You can override via pkce option: "S256" | "plain" | false.

  • Google — OpenID Connect scopes, profile and email
  • GitHub — Handles private emails via /user/emails
  • GitLab — Supports self‑hosted via domain option
  • LinkedIn — OpenID Connect userinfo endpoint
  • Microsoft / Azure AD — Multi‑tenant via tenant
  • Spotify — Email and profile scopes
  • Discord — identify and email scopes
  • Twitch — Requires Client-Id header for user API
  • Epic Games — Basic profile support
  • Custom OAuth — Any OAuth 2.0 provider

Email Providers

  • Magic Links: Passwordless authentication via email

Custom Providers

  • Credentials: Username/password authentication (coming soon)
  • Custom OAuth: Any OAuth 2.0 provider

Provider Interface

All providers implement a common interface:

Provider

Base type for all authentication providers

type Provider = OAuthProvider | EmailProvider | CustomProvider

OAuth Provider

OAuthProvider

Configuration for OAuth 2.0 providers

interface OAuthProvider { type: 'oauth'; clientId: string; clientSecret: string; authorizeUrl: string; tokenUrl: string; userInfoUrl: string; scope?: string[]; getUser: (token: string) => Promise<User>; }

Email Provider

EmailProvider

Configuration for email magic link providers

interface EmailProvider { type: 'email'; server: string; from: string; auth?: { user: string; pass: string; }; sendMagicLink: (email: string, token: string) => Promise<void>; verifyToken: (token: string) => Promise<boolean>; }

Using Providers

Providers are used in your authentication configuration:

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

// Google OAuth provider
const googleProvider = google({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  redirectUri: process.env.GOOGLE_REDIRECT_URI!,
});

// Email magic link provider
const emailProvider = email({
  server: 'smtp.gmail.com:587',
  from: 'noreply@yourdomain.com',
  auth: {
    user: process.env.SMTP_USER!,
    pass: process.env.SMTP_PASS!,
  },
});

// Use in authentication config
const authConfig = {
  secret: process.env.AUTH_SECRET!,
  provider: googleProvider, // or emailProvider
};

Provider Lifecycle

Understanding how providers work in the authentication flow:

  1. Configuration: Provider is created with configuration options
  2. Authorization: User is redirected to provider's authorization URL
  3. Callback: Provider handles the callback and exchanges code for token
  4. User Info: Provider fetches user information using the access token
  5. Session: User data is used to create a session

Creating Custom Providers

You can create custom providers for any OAuth 2.0 or custom authentication system:

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

function customOAuth(options: {
  clientId: string;
  clientSecret: string;
  redirectUri: string;
  authorizeUrl: string;
  tokenUrl: string;
  userInfoUrl: string;
  scope?: string[];
}): OAuthProvider {
  return {
    type: 'oauth',
    ...options,
    async getUser(token: string) {
      const response = await fetch(options.userInfoUrl, {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      });
      const user = await response.json();
      return {
        id: user.id,
        email: user.email,
        name: user.name,
        picture: user.avatar_url,
      };
    },
  };
}

// Use your custom provider
const customProvider = customOAuth({
  clientId: process.env.CUSTOM_CLIENT_ID!,
  clientSecret: process.env.CUSTOM_CLIENT_SECRET!,
  redirectUri: process.env.CUSTOM_REDIRECT_URI!,
  authorizeUrl: 'https://api.custom.com/oauth/authorize',
  tokenUrl: 'https://api.custom.com/oauth/token',
  userInfoUrl: 'https://api.custom.com/user',
  scope: ['read', 'write'],
});

Provider Configuration

Each provider has specific configuration requirements:

OAuth Providers

  • clientId: OAuth client identifier
  • clientSecret: OAuth client secret
  • redirectUri: Callback URL for OAuth flow
  • scope: OAuth scopes (optional)

Email Providers

  • server: SMTP server configuration
  • from: Sender email address
  • auth: SMTP authentication credentials

Best Practices

  • Use environment variables for all sensitive configuration
  • Validate provider configuration at startup
  • Handle provider-specific errors gracefully
  • Test providers in development before production

Provider Security

Security considerations for providers:

  • HTTPS Only: Always use HTTPS in production
  • State Parameter: OAuth providers use CSRF protection
  • Token Validation: All tokens are validated before use
  • Scope Limitation: Request only necessary OAuth scopes

Next Steps

Now that you understand the provider architecture, you can explore specific providers:

Google OAuth