Documentation

Environment Setup

Configure environment variables for @warpy-auth-sdk/core.

Required Environment Variables

@warpy-auth-sdk/core requires several environment variables to function properly. Here's a complete reference for all supported variables.

Core Configuration

AUTH_SECRET

Required: JWT signing secret for session tokens and CSRF protection.

AUTH_SECRET=your-secret-key-min-32-chars-long-replace-this-in-production

Security Requirements

  • Must be at least 32 characters long
  • Use a cryptographically secure random string
  • Never commit to version control
  • Use different secrets for development and production

Generate a Secure Secret

You can generate a secure secret using Node.js:

// Generate a secure secret
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Google OAuth Configuration

Required for Google OAuth authentication:

# Google OAuth credentials
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/api/auth/callback/google

Setting Up Google OAuth

  1. Go to the Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Google+ API
  4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
  5. Set the application type to "Web application"
  6. Add authorized redirect URIs:
    • Development: http://localhost:3000/api/auth/callback/google
    • Production: https://yourdomain.com/api/auth/callback/google
  7. Copy the Client ID and Client Secret to your environment variables

Email Configuration

Required for email magic link authentication:

# SMTP configuration for email magic links
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=noreply@yourdomain.com

Gmail Setup

  1. Enable 2-factor authentication on your Gmail account
  2. Generate an App Password:
    • Go to Google Account settings
    • Security → 2-Step Verification → App passwords
    • Generate a password for "Mail"
  3. Use the app password as SMTP_PASS

Custom SMTP Server

For production, consider using dedicated email services:

  • SendGrid: smtp.sendgrid.net:587
  • Mailgun: smtp.mailgun.org:587
  • AWS SES: email-smtp.us-east-1.amazonaws.com:587
  • Postmark: smtp.postmarkapp.com:587

Database Configuration (Optional)

For session persistence with database adapters:

# PostgreSQL with Prisma
DATABASE_URL="postgresql://username:password@localhost:5432/auth_db"

# MySQL with Prisma
DATABASE_URL="mysql://username:password@localhost:3306/auth_db"

# SQLite (development)
DATABASE_URL="file:./dev.db"

MCP Configuration (Optional)

For AI agent authentication features:

# Enable MCP features
MCP_ENABLED=true

# Agent token expiration (default: 15m)
MCP_TOKEN_EXPIRES_IN=15m

# Allowed agent scopes (comma-separated)
MCP_ALLOWED_SCOPES=debug,read,write

Production Environment Variables

For production deployment, ensure you have:

# Production environment
NODE_ENV=production
AUTH_SECRET=your-production-secret-here
GOOGLE_CLIENT_ID=your-production-client-id
GOOGLE_CLIENT_SECRET=your-production-client-secret
GOOGLE_REDIRECT_URI=https://yourdomain.com/api/auth/callback/google

# Production SMTP
SMTP_HOST=your-production-smtp-host
SMTP_PORT=587
SMTP_USER=your-production-email
SMTP_PASS=your-production-password
SMTP_FROM=noreply@yourdomain.com

# Production database
DATABASE_URL=your-production-database-url

Best Practices

  • Use different OAuth applications for development and production
  • Rotate secrets regularly in production
  • Use environment-specific redirect URIs
  • Monitor for exposed secrets in logs
  • Use secret management services for production

Environment Validation

You can validate your environment variables at startup:

// lib/env.ts
export function validateEnv() {
  const required = [
    'AUTH_SECRET',
    'GOOGLE_CLIENT_ID',
    'GOOGLE_CLIENT_SECRET',
    'GOOGLE_REDIRECT_URI'
  ];

  const missing = required.filter(key => !process.env[key]);
  
  if (missing.length > 0) {
    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
  }

  if (process.env.AUTH_SECRET!.length < 32) {
    throw new Error('AUTH_SECRET must be at least 32 characters long');
  }
}

// Call this in your app startup
validateEnv();

Development vs Production

Use different configurations for development and production:

Development (.env.local)

# Development environment
AUTH_SECRET=dev-secret-key-32-chars-minimum-length
GOOGLE_CLIENT_ID=your-dev-client-id
GOOGLE_CLIENT_SECRET=your-dev-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/api/auth/callback/google
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-dev-email@gmail.com
SMTP_PASS=your-dev-app-password

Production (Environment Variables)

In production, set environment variables through your hosting platform:

  • Vercel: Project Settings → Environment Variables
  • Netlify: Site Settings → Environment Variables
  • Railway: Project → Variables
  • Heroku: Settings → Config Vars

Best Practices

  • Use different OAuth applications for development and production
  • Rotate secrets regularly in production
  • Use environment-specific redirect URIs
  • Monitor for exposed secrets in logs
  • Use secret management services for production

Next Steps

Once you have your environment variables configured, you can proceed to implement your first authentication flow.

QuickstartFirst Auth Flow
Environment Setup | @warpy-auth-sdk/core