Merge Add JWKS support, OIDC compliance, and scalability enhancements pull request #7 from mjunaidca/auth-server

feat(auth): Add JWKS support, OIDC compliance, and scalability enhancements

Author: mjunaidca

.claude/skills/engineering/better-auth-setup/SKILL.md

@@ -20,6 +20,10 @@
         "@playwright/mcp@latest"
       ],
       "env": {}
+    },
+    "better-auth": {
+      "type": "http",
+      "url": "https://mcp.chonkie.ai/better-auth/better-auth-builder/mcp"
     }
   }
 }

.mcp.json

@@ -0,0 +1,37 @@
+# Database (Neon Postgres)
+DATABASE_URL=postgresql://user:[email protected]/dbname?sslmode=require
+
+# Better Auth
+BETTER_AUTH_SECRET=your-secret-key-minimum-32-characters-long
+BETTER_AUTH_URL=http://localhost:3001
+
+# CORS - Allowed origins (comma-separated)
+ALLOWED_ORIGINS=http://localhost:3000,https://your-production-domain.com
+
+# Auth server URL (for client-side)
+NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3001
+
+# OAuth: Pre-configured public client callback URL (for production)
+# Default: http://localhost:3000/auth/callback (development)
+# ROBOLEARN_INTERFACE_CALLBACK_URL=https://your-production-domain.com/auth/callback
+
+# Email Configuration (choose one provider)
+# Common: FROM address used by all providers
+# [email protected]
+
+# Option 1: Google SMTP (free tier: 500/day)
+# Get app password: Google Account > Security > 2-Step Verification > App passwords
+# SMTP_HOST=smtp.gmail.com
+# SMTP_PORT=587
+# [email protected]
+# SMTP_PASS=your-16-char-app-password
+# SMTP_SECURE=false
+
+# Option 2: Resend (free tier: 100/day)
+# RESEND_API_KEY=re_xxxxxxxxx
+# [email protected]
+
+# Note: If both are configured, SMTP is used first (priority)
+
+# Node environment
+NODE_ENV=development

auth-server/.env.example

@@ -0,0 +1,29 @@
+# Dependencies
+node_modules/
+
+# Next.js
+.next/
+out/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Debug
+npm-debug.log*
+
+# TypeScript
+*.tsbuildinfo
+
+# Drizzle
+drizzle/meta/
+.vercel

auth-server/.gitignore

@@ -0,0 +1,148 @@
+# RoboLearn Auth Server
+
+OAuth 2.1 / OIDC authentication server using Better Auth.
+
+## Setup
+
+```bash
+cd auth-server
+npm install
+cp .env.example .env.local
+# Edit .env.local with your values
+npm run db:push
+# Seed the trusted public client (see below)
+npm run dev  # http://localhost:3001
+```
+
+### Seed Trusted Public Client
+
+After running `db:push`, you **must** seed the trusted public client (`robolearn-public-client`) in your database. This client is pre-configured in the code but needs to exist in the database for OAuth flows to work.
+
+**Option 1: Run SQL directly (recommended)**
+
+Execute this SQL in your database (via psql, pgAdmin, or your database tool):
+
+```sql
+INSERT INTO oauth_application (
+  id,
+  client_id,
+  client_secret,
+  name,
+  redirect_urls,
+  type,
+  disabled,
+  metadata,
+  created_at,
+  updated_at
+) VALUES (
+  'robolearn-public-client-id',
+  'robolearn-public-client',
+  NULL, -- No secret for public client (PKCE only)
+  'RoboLearn Public Client',
+  'http://localhost:3000/auth/callback,https://robolearn.github.io/auth/callback', -- Comma-separated: dev + prod URLs
+  'public',
+  false,
+  '{"token_endpoint_auth_method":"none","grant_types":["authorization_code","refresh_token"]}',
+  NOW(),
+  NOW()
+)
+ON CONFLICT (client_id) DO UPDATE SET
+  name = EXCLUDED.name,
+  redirect_urls = EXCLUDED.redirect_urls,
+  type = EXCLUDED.type,
+  disabled = EXCLUDED.disabled,
+  metadata = EXCLUDED.metadata,
+  updated_at = NOW();
+```
+
+**Option 2: Use the seed script**
+
+If you have `DATABASE_URL` set in `.env.local`:
+
+```bash
+npx tsx scripts/seed-public-client.ts
+```
+
+**Option 3: Use the API endpoint (admin only)**
+
+If you're logged in as admin:
+
+```bash
+curl -X POST http://localhost:3001/api/admin/seed-public-client \
+  -H "Cookie: your-session-cookie"
+```
+
+## Environment Variables
+
+```env
+# Required
+DATABASE_URL=postgresql://user:[email protected]/db?sslmode=require
+BETTER_AUTH_SECRET=your-32-char-secret  # openssl rand -base64 32
+BETTER_AUTH_URL=http://localhost:3001
+ALLOWED_ORIGINS=http://localhost:3000
+NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3001
+
+# Optional: Email verification
+# Option 1: Resend (free tier: 100/day)
+# RESEND_API_KEY=re_xxxxxxxxx
+# [email protected]
+
+# Option 2: SMTP (Gmail, custom SMTP, etc.)
+# SMTP_HOST=smtp.gmail.com
+# SMTP_PORT=587
+# [email protected]
+# SMTP_PASS=app-password
+# [email protected]
+# [email protected]
+
+# Optional: Production OAuth client callback URL
+# ROBOLEARN_INTERFACE_CALLBACK_URL=https://yourdomain.com/auth/callback
+```
+
+## Features
+
+- OAuth 2.1 with PKCE (no client secrets in browser)
+- JWKS (JSON Web Key Set) for client-side token verification
+- Dynamic client registration (`POST /api/auth/oauth2/register`)
+- Optional email verification via Resend or SMTP
+- Role-based access (admin/user)
+- 7-day sessions with auto-refresh
+
+## Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/.well-known/openid-configuration` | OIDC discovery document |
+| `/api/auth/jwks` | JWKS public keys for token verification |
+| `/api/auth/oauth2/authorize` | Start OAuth flow |
+| `/api/auth/oauth2/token` | Exchange code for tokens |
+| `/api/auth/oauth2/userinfo` | Get user info |
+| `/api/auth/oauth2/register` | Register new OAuth client |
+
+## Register New OAuth Client
+
+```bash
+curl -X POST http://localhost:3001/api/auth/oauth2/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_name": "My App",
+    "redirect_uris": ["http://localhost:4000/callback"],
+    "token_endpoint_auth_method": "none"
+  }'
+```
+
+Returns `client_id` to use in your OAuth flow.
+
+## Create Admin User
+
+```sql
+-- After signing up via UI:
+UPDATE "user" SET role = 'admin' WHERE email = '[email protected]';
+```
+
+## Deploy to Vercel
+
+1. Push to GitHub
+2. Import in Vercel, set root to `auth-server`
+3. Add environment variables
+4. Deploy