docs.do.dev
Internal DocumentationArchived DocumentationDo dev legacyAuthentication

Auth Service Testing Guide

This guide explains how to implement and test the auth.do.dev unified authentication service.

Prerequisites

  1. Environment Variables: Ensure the auth Convex deployment variables are in your root .env.local:

    # Auth Convex Deployment
CONVEX_DEPLOYMENT_AUTH="dev:dependable-pika-747"
NEXT_PUBLIC_CONVEX_URL_AUTH="https://dependable-pika-747.convex.cloud"

  2. Convex Environment Variables: Set these in the Convex dashboard for the auth deployment:

    # Email provider
RESEND_API_KEY=re_xxxxxxxxxxxx
AUTH_RESEND_FROM=auth@notifications.do.dev

# OAuth providers (optional for initial testing)
AUTH_GITHUB_ID=xxxxxxxxxxxx
AUTH_GITHUB_SECRET=xxxxxxxxxxxx
AUTH_GOOGLE_ID=xxxxxxxxxxxx.apps.googleusercontent.com
AUTH_GOOGLE_SECRET=xxxxxxxxxxxx

# JWT Secret
JWT_SECRET=your-random-jwt-secret-string

Development Setup

1. Install Dependencies

# From root directory
pnpm install

2. Initialize the Auth Database

Start the auth Convex development server to initialize the schema:

# Option 1: Run auth service with its Convex backend
pnpm convex:auth:dev

# Option 2: In a separate terminal, run just the auth Convex
cd apps/auth
npx convex dev

This will:

  • Initialize the database schema
  • Generate TypeScript types
  • Start the Convex development server

3. Create the Auth App Structure

The auth app should be created in apps/auth/ with this structure:

apps/auth/
├── app/
│   ├── api/
│   │   └── auth/
│   │       ├── validate/route.ts
│   │       ├── refresh/route.ts
│   │       └── oauth/
│   │           ├── google/route.ts
│   │           └── github/route.ts
│   ├── login/page.tsx
│   ├── verify/page.tsx
│   └── layout.tsx
├── components/
│   ├── auth-form.tsx
│   ├── verify-code.tsx
│   └── oauth-buttons.tsx
├── convex/
│   ├── schema.ts
│   ├── auth.ts
│   └── _generated/
└── lib/
    └── utils.ts

4. Start Development Servers

You'll need multiple terminal windows:

# Terminal 1: Auth Convex backend
cd apps/auth
npx convex dev

# Terminal 2: Auth Next.js app
cd apps/auth
pnpm dev --port 3001

# Terminal 3: Main dodev app (for testing integration)
cd apps/dodev
pnpm dev --port 3005

Testing Flows

1. Email OTP Authentication

Test Setup

  1. Ensure Resend API key is configured in Convex environment
  2. Navigate to http://localhost:3001/login?app=dodev&return=http://localhost:3005/dashboard

Test Steps

  1. Enter Email: Enter a valid email address
  2. Check Email: Look for OTP code in your email
  3. Verify Code: Enter the 6-digit code
  4. Check Redirect: Should redirect to the return URL with auth token

Expected Behavior

  • Email sent within 30 seconds
  • Code valid for 10 minutes
  • Successful verification creates session
  • Redirect includes auth token in cookie or URL

2. OAuth Authentication

Google OAuth Test

  1. Configure Google OAuth credentials in Convex
  2. Navigate to auth page with Google button
  3. Click "Continue with Google"
  4. Complete Google OAuth flow
  5. Verify redirect to return URL

GitHub OAuth Test

  1. Configure GitHub OAuth credentials in Convex
  2. Navigate to auth page with GitHub button
  3. Click "Continue with GitHub"
  4. Complete GitHub OAuth flow
  5. Verify redirect to return URL

3. Session Validation

Test the Validation API

# Get a valid token from login flow, then test validation
curl -X POST http://localhost:3001/api/auth/validate \
  -H "Content-Type: application/json" \
  -d '{"token": "your-session-token"}'

Expected Response

{
  "valid": true,
  "user": {
    "id": "user-id",
    "email": "user@example.com",
    "name": "User Name"
  },
  "session": {
    "appId": "dodev",
    "expiresAt": 1234567890000
  }
}

4. Integration Testing with dodev App

Setup Integration

  1. Install the auth client package:

    cd apps/dodev
pnpm add @workspace/auth-client

  2. Add the auth client hook to dodev:

    // apps/dodev/hooks/use-auth.ts
import { useUnifiedAuth } from '@workspace/auth-client'

export function useAuth() {
  return useUnifiedAuth()
}

  3. Test the integration:

    # Start both services
cd apps/auth && pnpm dev --port 3001 &
cd apps/dodev && pnpm dev --port 3005 &

Integration Test Flow

  1. Visit http://localhost:3005 (dodev app)
  2. Click login/signup button
  3. Should redirect to http://localhost:3001/login?app=dodev&return=http://localhost:3005/dashboard
  4. Complete auth flow
  5. Should redirect back to dodev with valid session

Error Testing

1. Invalid Tokens

# Test with invalid token
curl -X POST http://localhost:3001/api/auth/validate \
  -H "Content-Type: application/json" \
  -d '{"token": "invalid-token"}'

# Expected: 401 Unauthorized

2. Expired Tokens

  1. Create a session
  2. Wait for token to expire (or manually expire in database)
  3. Test validation - should return invalid

3. Invalid OTP Codes

  1. Start email flow
  2. Enter incorrect OTP code
  3. Should show error message
  4. Allow retry up to 3 times

4. Rate Limiting

  1. Attempt multiple rapid login attempts
  2. Should be rate limited after threshold
  3. Should return appropriate error message

Debugging

Common Issues

"Convex deployment not found"

# Check deployment configuration
cd apps/auth
cat .env.local | grep CONVEX
npx convex dashboard

"Email not sending"

# Check Resend configuration
npx convex env list
# Look for RESEND_API_KEY and AUTH_RESEND_FROM

"OAuth redirect mismatch"

  1. Check OAuth app configuration in Google/GitHub
  2. Ensure redirect URLs match exactly
  3. Check for port mismatches in development

Logging

Enable detailed logging for debugging:

// In Convex functions, add logging
console.log("Auth attempt:", { email, timestamp: Date.now() });

View logs in Convex dashboard or terminal where npx convex dev is running.

Production Deployment

1. Environment Configuration

Set production environment variables in:

  • Convex dashboard for the auth deployment
  • Vercel for the auth Next.js app

2. Domain Setup

  1. Configure auth.do.dev DNS
  2. Set up SSL certificate
  3. Update OAuth app redirect URLs

3. Monitoring

Set up monitoring for:

  • Auth success/failure rates
  • Email delivery rates
  • OAuth flow completion rates
  • Session validation rates

Security Checklist

Development

  • Use HTTPS in development (mkcert recommended)
  • Never commit secrets to version control
  • Use secure JWT secrets (32+ characters)
  • Implement proper CORS policies

Production

  • Use production OAuth credentials
  • Enable webhook signature verification
  • Implement rate limiting
  • Set up monitoring and alerting
  • Use production email domain
  • Implement proper session management

Next Steps

  1. Complete Implementation: Finish auth app based on design document
  2. Integration Testing: Test with all target apps (dodev, promptnow, etc.)
  3. Performance Testing: Load test with multiple concurrent users
  4. Security Audit: Review implementation for security issues
  5. Documentation: Update API documentation
  6. Migration: Plan migration from existing auth systems

AUTH SERVICE IMPLEMENTATION

Previous Page

CLEAR AUTH DATA

Next Page

On this page

Auth Service Testing GuidePrerequisitesDevelopment Setup1. Install Dependencies2. Initialize the Auth Database3. Create the Auth App Structure4. Start Development ServersTesting Flows1. Email OTP AuthenticationTest SetupTest StepsExpected Behavior2. OAuth AuthenticationGoogle OAuth TestGitHub OAuth Test3. Session ValidationTest the Validation APIExpected Response4. Integration Testing with dodev AppSetup IntegrationIntegration Test FlowError Testing1. Invalid Tokens2. Expired Tokens3. Invalid OTP Codes4. Rate LimitingDebuggingCommon Issues"Convex deployment not found""Email not sending""OAuth redirect mismatch"LoggingProduction Deployment1. Environment Configuration2. Domain Setup3. MonitoringSecurity ChecklistDevelopmentProductionNext Steps