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/webs/auth
npx convex dev

Then initialize the apps table (one time only):

# In another terminal, while convex dev is running
cd apps/webs/auth
npx convex run apps:initialize

# You should see output like:
# { "initialized": 5 }

3. Start the Auth Service

# Option 1: Run only the auth service
pnpm dev:auth

# Option 2: Run auth with core services
pnpm dev:core

# Option 3: Run all services including auth
pnpm dev:all

The auth service will be available at http://localhost:3030

Testing Scenarios

1. Basic Email Authentication

1. Navigate to http://localhost:3030
2. Enter your email address
3. Check your email for the 6-digit verification code
4. Enter the code to complete sign-in
5. You should be redirected to the dashboard

2. OAuth Authentication (GitHub/Google)

Note: OAuth requires proper configuration in the Convex dashboard first.

1. Navigate to http://localhost:3030
2. Click "Continue with GitHub" or "Continue with Google"
3. Authorize the application
4. You should be redirected back to the dashboard

3. Multi-App Authentication Flow

Test authentication from another app (e.g., local-test):

1. Update local-test app to use auth-client:

   cd apps/webs/local-test
   pnpm add @workspace/auth-client

2. Create auth configuration in local-test:

   // apps/webs/local-test/lib/auth.ts
   import { AuthClient } from "@workspace/auth-client"
   
   export const authClient = new AuthClient({
     authUrl: process.env.NEXT_PUBLIC_AUTH_URL || "http://localhost:3030",
     appId: "local-test",
     redirectPath: "/dashboard",
   })

3. Add middleware to protect routes:

   // apps/webs/local-test/middleware.ts
   import { NextResponse } from "next/server"
   import type { NextRequest } from "next/server"
   
   export function middleware(request: NextRequest) {
     const token = request.cookies.get("auth_token_local-test")
     
     if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
       const authUrl = new URL("http://localhost:3030")
       authUrl.searchParams.set("app", "local-test")
       authUrl.searchParams.set("return", request.url)
       
       return NextResponse.redirect(authUrl)
     }
     
     return NextResponse.next()
   }
   
   export const config = {
     matcher: ["/dashboard/:path*"],
   }

4. Test the flow:

   • Start local-test app: pnpm dev --filter=local-test
   • Navigate to http://localhost:3025/dashboard
   • You should be redirected to auth service
   • After authentication, you'll be redirected back to local-test

4. Session Validation

Test the session validation API:

# Get a session token first by signing in
# Then test validation
curl -X POST http://localhost:3030/api/session/validate \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_SESSION_TOKEN"}'

5. Session Refresh

Test token refresh:

curl -X POST http://localhost:3030/api/session/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "YOUR_REFRESH_TOKEN"}'

Debugging

Check Convex Logs

Monitor the auth Convex deployment logs:

1. Go to the Convex dashboard
2. Select the auth deployment (dependable-pika-747)
3. Check the Logs tab for any errors

Common Issues

1. "RESEND_API_KEY is not set"

   • Add the Resend API key to Convex environment variables

2. OAuth redirect errors

   • Verify OAuth callback URLs match exactly
   • Check OAuth app configuration in GitHub/Google

3. Session not persisting

   • Check browser cookies for auth tokens
   • Verify cookie domain settings

4. CORS errors

   • The auth service has CORS headers configured
   • Ensure you're using the correct URLs

Testing Checklist

• Email OTP sign-in works
• OAuth sign-in works (if configured)
• Dashboard shows user info correctly
• Session validation API returns correct data
• Token refresh works properly
• Multi-app redirect flow works
• Sessions are created in Convex
• Audit logs are recorded

Production Deployment

1. Deploy Convex functions:

   pnpm convex:auth:deploy

2. Deploy to Vercel:

   cd apps/webs/auth
   vercel --prod

3. Update DNS:

   • Point auth.do.dev to Vercel deployment

4. Update OAuth providers:

   • Add production callback URLs
   • Update environment variables

Integration with Other Apps

To integrate the auth service with other apps in the monorepo:

1. Add @workspace/auth-client dependency
2. Configure the auth client with correct URLs
3. Implement middleware for protected routes
4. Use authClient.validateSession() for API routes
5. Handle token storage and refresh

See the auth-client package README for detailed integration instructions.