nitrostack 1.0.23 → 1.0.24

package/templates/typescript-oauth/OAUTH_SETUP.md

@@ -1,21 +1,21 @@
 # Complete OAuth 2.1 Setup Guide for NitroStack
 
-This guide shows you **exactly** how to set up OAuth 2.1 authentication from scratch, test it in NitroStack Studio, and deploy it to production.
+This guide shows you **exactly** how to set up OAuth 2.1 authentication from scratch with **zero issues**.
 
 ## 🎯 What You'll Learn
 
-- ✅ How to configure Auth0 (or other OAuth providers)
+- ✅ How to configure Auth0 correctly (avoiding common pitfalls)
 - ✅ How to set up your MCP server environment
 - ✅ How to test the complete OAuth flow in Studio
 - ✅ How to troubleshoot common issues
 
 ---
 
-## 🚀 Quick Start with Auth0 (5 Minutes)
+## 🚀 Quick Start with Auth0 (10 Minutes)
 
 ### Why Auth0?
 - ✅ **Free tier** (7,000 active users, no credit card)
-- ✅ **Fastest setup** (5 minutes)
+- ✅ **Fastest setup** (10 minutes)
 - ✅ **Best for testing** and learning
 - ✅ **Production-ready** when you need it
 
@@ -29,107 +29,175 @@ This guide shows you **exactly** how to set up OAuth 2.1 authentication from scr
 
 ---
 
-## Step 2: Create Auth0 Application
+## Step 2: Create Auth0 API (Protected Resource)
 
-This represents NitroStack Studio as an OAuth client.
+**⚠️ DO THIS FIRST!** The API represents your MCP server as a protected resource.
 
-1. Open **Auth0 Dashboard** → **Applications** → **Applications**
-2. Click **"Create Application"**
+1. Go to **Applications** → **APIs** in Auth0 Dashboard
+2. Click **"Create API"**
 3. **Settings:**
    ```
-   Name: NitroStack Studio
-   Application Type: Regular Web Application
+   Name: MCP Server API
+   Identifier: https://mcplocal
+   Signing Algorithm: RS256
    ```
+   
+   **⚠️ CRITICAL NOTES:**
+   - The **Identifier** can be any unique URI (doesn't need to be a real URL)
+   - For development, use `https://mcplocal` (simple and clear)
+   - For production, use your actual domain like `https://api.yourapp.com`
+   - This **MUST** match your `RESOURCE_URI` in `.env` **EXACTLY**
+   - **JWT Profile**: Select **RFC 9068** (OAuth 2.0 Access Token JWT Profile)
+   - **RBAC**: You can leave this **disabled** for basic OAuth (only needed for role-based permissions)
+
 4. Click **"Create"**
 
-5. Go to **Settings** tab and configure:
+5. Go to **Permissions** tab
+6. Add these scopes:
+   ```
+   Scope          Description
+   -----          -----------
+   read           Read access to resources
+   write          Write/modify resources
+   admin          Administrative operations
    ```
-   Allowed Callback URLs:
-   http://localhost:3000/auth/callback
 
-   Allowed Logout URLs:
-   http://localhost:3000
+7. Click **"Add"** for each scope
+8. **Save Changes**
+
+---
+
+## Step 3: Create Auth0 Application (OAuth Client)
 
-   Allowed Web Origins:
-   http://localhost:3000
+**⚠️ Application Type Matters!** This is where many users get stuck.
 
-   Grant Types:
-   ☑ Authorization Code
-   ☑ Refresh Token
+1. Go to **Applications** → **Applications**
+2. Click **"Create Application"**
+3. **Settings:**
+   ```
+   Name: MCP Server OAuth
+   Application Type: Regular Web Application  ← CRITICAL!
    ```
+   
+   **⚠️ WHY "Regular Web Application"?**
+   - ❌ **NOT** "Single Page Application" (SPA) - Won't show in API authorization
+   - ❌ **NOT** "Machine to Machine" - Different auth flow, not compatible with OpenAI Studio
+   - ✅ **YES** "Regular Web Application" - Supports confidential clients with client secret
 
-6. **Save Changes**
+4. Click **"Create"**
 
-7. **Copy these values** (you'll need them later):
-   - **Domain** (e.g., `dev-abc123.us.auth0.com`)
-   - **Client ID** (e.g., `aBc123XyZ...`)
-   - **Client Secret** (click "Reveal Auth0 Management API" to see it)
+5. Go to **Settings** tab and configure:
 
----
+   **Allowed Callback URLs** (supports both dev and prod):
+   ```
+   http://localhost:3005/auth/callback,http://localhost:3000/auth/callback
+   ```
+   
+   **Why both ports?**
+   - `3005`: Dev mode (DiscoveryHttpServer handles OAuth callbacks)
+   - `3000`: Prod mode (HttpServerTransport handles OAuth callbacks)
 
-## Step 3: Create Auth0 API
+   **Allowed Logout URLs**:
+   ```
+   http://localhost:3005,http://localhost:3000
+   ```
 
-This represents your MCP server as a protected resource.
+   **Allowed Web Origins**:
+   ```
+   http://localhost:3005,http://localhost:3000
+   ```
 
-1. Go to **Applications** → **APIs**
-2. Click **"Create API"**
-3. **Settings:**
+6. Scroll down to **Advanced Settings**
+7. Go to **Grant Types** tab:
    ```
-   Name: NitroStack MCP Server
-   Identifier: http://localhost:3002
-   Signing Algorithm: RS256
+   ✅ Authorization Code
+   ✅ Refresh Token
+   ❌ Implicit (disable - deprecated in OAuth 2.1)
+   ❌ Client Credentials (not needed for this use case)
    ```
-   **Important:** The Identifier MUST match your server's `RESOURCE_URI`
 
-4. Click **"Create"**
+8. Go to **OAuth** tab:
+   ```
+   ✅ OIDC Conformant: ON (enabled)
+   JsonWebToken Signature Algorithm: RS256
+   ```
 
-5. Go to **Permissions** tab
-6. Add these scopes:
+9. Go to **ID Token** tab:
    ```
-   Scope          Description
-   -----          -----------
-   read           Read access to resources
-   write          Write/modify resources
-   admin          Administrative operations
+   ❌ ID Token Encryption: NONE/Disabled
    ```
+   
+   **⚠️ CRITICAL:** If encryption is enabled, you'll receive JWE (encrypted) tokens instead of JWT tokens, which will fail validation!
 
-7. Click **"Add"** for each scope
+10. **Save Changes**
+
+11. **Copy these values** (you'll need them later):
+    - **Domain** (e.g., `dev-abc123.us.auth0.com`)
+    - **Client ID** (e.g., `aBc123XyZ...`)
+    - **Client Secret** (click "Show" to reveal it)
+
+---
+
+## Step 4: Link Application to API
+
+**⚠️ REQUIRED STEP!** Many users miss this.
+
+1. Go back to **Applications** → **APIs**
+2. Click on your **"MCP Server API"** (created in Step 2)
+3. Click the **"Machine to Machine Applications"** tab
+   
+   **Note:** Despite the confusing name, this tab shows which applications can access your API
+
+4. Find your **"MCP Server OAuth"** application in the list
+5. **Toggle the switch to "Authorized"** (should turn green)
+6. Click the **dropdown arrow** to expand permissions
+7. **Select all scopes** you want to grant (`read`, `write`, `admin`)
+8. Click **"Update"**
+
+**✅ Verification:** Your application should now show as "Authorized" with selected scopes
 
 ---
 
-## Step 4: Configure Your MCP Server
+## Step 5: Configure Your MCP Server
+
+### Copy and Edit `.env` File
 
-### Edit `.env` File
+```bash
+cp .env.example .env
+```
 
-Replace the values with your Auth0 settings from Steps 2 & 3:
+Edit `.env` with your Auth0 settings:
 
 ```bash
 # =============================================================================
 # REQUIRED: Server Configuration
 # =============================================================================
 
-# Your MCP server's public URL (matches API Identifier from Step 3)
-RESOURCE_URI=http://localhost:3002
+# ⚠️ MUST match Auth0 API Identifier from Step 2 EXACTLY
+RESOURCE_URI=https://mcplocal
 
-# Your Auth0 domain (from Step 2)
+# Your Auth0 domain from Step 3 (with https://)
 AUTH_SERVER_URL=https://dev-abc123.us.auth0.com
 
 # =============================================================================
 # OPTIONAL: Token Configuration
 # =============================================================================
 
-# Expected token audience (must match API Identifier)
-TOKEN_AUDIENCE=http://localhost:3002
+# Must match RESOURCE_URI
+TOKEN_AUDIENCE=https://mcplocal
 
-# Expected token issuer (Auth0 domain with trailing slash)
+# Auth0 domain with trailing slash!
 TOKEN_ISSUER=https://dev-abc123.us.auth0.com/
 ```
 
-**⚠️ Important:** Replace `dev-abc123` with YOUR actual Auth0 domain!
+**⚠️ Important:**
+- Replace `dev-abc123` with YOUR actual Auth0 domain
+- `RESOURCE_URI` must match Auth0 API Identifier **EXACTLY** (case-sensitive!)
+- `TOKEN_ISSUER` must have trailing slash `/`
 
 ---
 
-## Step 5: Start Your MCP Server
+## Step 6: Start Your MCP Server
 
 ```bash
 npm install
@@ -138,50 +206,59 @@ npm run dev
 
 **Expected Output:**
 ```
-🌐 HTTP MCP Server listening on http://0.0.0.0:3002/mcp
-🔐 OAuth 2.1 enabled
-   Resource URI: http://localhost:3002
-   Auth Servers: https://dev-abc123.us.auth0.com
-   Metadata: http://0.0.0.0:3002/.well-known/oauth-protected-resource
+🚀 OAuth discovery server running at http://localhost:3005
+NITRO_LOG::{"level":"info","message":"OAuthModule: Running in STDIO mode, starting DiscoveryHttpServer on port 3005"}
+NITRO_LOG::{"level":"info","message":"🔐 OAuth 2.1 enabled"}
+NITRO_LOG::{"level":"info","message":"   Resource URI: https://mcplocal"}
+NITRO_LOG::{"level":"info","message":"   Auth Servers: https://dev-abc123.us.auth0.com"}
 🚀 Server started successfully (DUAL: STDIO + HTTP)
 📡 MCP Protocol: STDIO (for Studio/Claude)
-🌐 OAuth Metadata: HTTP (port 3002)
+🌐 OAuth Metadata: HTTP (port 3005)
 ```
 
 **✅ Success!** Your server is running in DUAL mode:
 - **STDIO**: For MCP protocol communication (tools, chat)
-- **HTTP**: For OAuth metadata and discovery
+- **HTTP (3005)**: For OAuth metadata and discovery in dev mode
 
 ---
 
-## Step 6: Test OAuth Flow in NitroStack Studio
+## Step 7: Test OAuth Flow in NitroStack Studio
 
 ### Open Studio
 
 Navigate to **http://localhost:3000** in your browser
 
-### 6.1 Discover OAuth Server
+### 7.1 Discover OAuth Server
 
 1. Go to **Auth** → **OAuth 2.1** tab
-2. In the **"Discover Server Auth"** section:
+2. In the **"1. Discover Server Auth"** section:
    ```
-   Server URL: http://localhost:3002
+   Server URL: http://localhost:3005
    ```
+   **Note:** Port 3005 in dev mode (discovery server)
+
 3. Click **"Discover Auth Config"**
 
 **Expected Result:**
 ```
-✅ Discovery Successful
+✅ Discovery successful!
 
-Resource: http://localhost:3002
+Resource: https://mcplocal
 Authorization Servers: https://dev-abc123.us.auth0.com
 Scopes: read, write, admin
 ```
 
-### 6.2 Enter Client Credentials
+**✅ In Console, you should see:**
+```
+🎯 Setting audience parameter: https://mcplocal
+```
+
+**⚠️ This is CRITICAL!** The audience parameter tells Auth0 to issue a proper JWT access token for your API.
+
+### 7.2 Enter Client Credentials
 
 1. Scroll to **"2a. Use Existing Client"** section
-2. Enter your credentials from Step 2:
+2. Enter your credentials from Step 3:
    ```
    Client ID: [Your Auth0 Client ID]
    Client Secret: [Your Auth0 Client Secret]
@@ -193,14 +270,14 @@ Scopes: read, write, admin
 ✅ Client credentials saved!
 ```
 
-### 6.3 Start OAuth Flow
+### 7.3 Start OAuth Flow
 
 1. Scroll to **"3. Start OAuth Flow"** section
 2. Click **"Start Authorization Flow"**
 
 **What Happens:**
 1. ✅ You're redirected to Auth0 login page
-2. ✅ Login with your Auth0 account
+2. ✅ Login with your Auth0 account (or test user)
 3. ✅ You're asked to authorize the application
 4. ✅ After authorization, you're redirected back to Studio
 5. ✅ Studio exchanges the code for a JWT token
@@ -211,12 +288,31 @@ Scopes: read, write, admin
 ✅ Authorization successful! Redirecting...
 ```
 
-### 6.4 Test Protected Tools
+### 7.4 Verify Token Type (Debug Check)
+
+**In your MCP server logs, you should see:**
+```
+[DEBUG] Token header: {"alg":"RS256","typ":"at+jwt","kid":"..."}
+[DEBUG] Decoded payload: SUCCESS
+[DEBUG] Payload audience: https://mcplocal
+[DEBUG] Expected audience: https://mcplocal
+```
+
+**✅ Perfect!** You're getting **RS256 JWT tokens** (not encrypted JWE tokens)
+
+**❌ If you see this instead:**
+```
+[DEBUG] Token header: {"alg":"dir","enc":"A256GCM",...}
+[ERROR] Received JWE (encrypted) token instead of JWT!
+```
+
+**Fix:** Go back to Step 3 and disable ID Token Encryption in Application settings
+
+### 7.5 Test Protected Tools
 
 1. Go to **Tools** tab
-2. You should see all your MCP tools loaded
-3. Try a protected tool (e.g., `get_user_profile`, `list_resources`)
-4. Click **"Execute"**
+2. Try a protected tool (e.g., `get_user_profile`, `list_resources`)
+3. Click **"Execute"**
 
 **Expected Result:**
 ```json
@@ -224,7 +320,8 @@ Scopes: read, write, admin
   "success": true,
   "user": {
     "sub": "auth0|xxx",
-    "scopes": ["read", "write", "admin"]
+    "scopes": ["read", "write", "admin"],
+    "clientId": "..."
   }
 }
 ```
@@ -237,9 +334,10 @@ Scopes: read, write, admin
 
 ### Dual Transport Architecture
 
-NitroStack runs **two transports simultaneously**:
+NitroStack automatically runs **two transports simultaneously** when OAuth is enabled:
 
 ```
+Development Mode:
 ┌─────────────────────────────────────┐
 │   Your OAuth 2.1 MCP Server         │
 ├─────────────────────────────────────┤
@@ -249,87 +347,159 @@ NitroStack runs **two transports simultaneously**:
 │  ├─ Connected to Studio/Claude      │
 │  └─ stdin/stdout communication      │
 │                                     │
-│  🌐 HTTP Server (Port 3002)         │
+│  🌐 DiscoveryHttpServer (Port 3005) │
 │  ├─ OAuth Metadata Endpoints        │
 │  ├─ /.well-known/oauth-protected-   │
 │  │   resource                       │
+│  ├─ /auth/callback                  │
 │  └─ Discovery & Token Validation    │
 │                                     │
 └─────────────────────────────────────┘
+
+Production Mode:
+┌─────────────────────────────────────┐
+│   Your OAuth 2.1 MCP Server         │
+├─────────────────────────────────────┤
+│                                     │
+│  🌐 HttpServerTransport (Port 3000) │
+│  ├─ MCP Protocol (SSE)              │
+│  ├─ OAuth Metadata Endpoints        │
+│  ├─ /.well-known/oauth-protected-   │
+│  │   resource                       │
+│  ├─ /auth/callback                  │
+│  └─ All-in-one HTTP server          │
+│                                     │
+└─────────────────────────────────────┘
 ```
 
 ### OAuth Flow Sequence
 
 ```
-1. Studio → Discover     → Your MCP Server (HTTP)
+1. Studio → Discover     → Your MCP Server (HTTP :3005 in dev)
                           ↓
                       Returns OAuth metadata
+                      (includes resource URI for audience)
                           ↓
 2. Studio → Authorize    → Auth0 Login Page
-                          ↓
+   (with audience param)  ↓
                       User logs in
                           ↓
 3. Auth0 → Redirect      → Studio Callback (/auth/callback)
                           ↓
 4. Studio → Exchange     → Auth0 Token Endpoint
-                          ↓
-                      Receives JWT token
+   (code for token)       ↓
+                      Receives RS256 JWT access token
+                      (NOT encrypted JWE token!)
                           ↓
 5. Studio → Execute Tool → Your MCP Server (STDIO)
            (with JWT)    ↓
                       Tool validates token & executes
 ```
 
+**Key Point:** Studio now automatically includes the `audience` parameter when starting the OAuth flow, which ensures Auth0 issues proper JWT tokens.
+
 ---
 
 ## 🚨 Troubleshooting
 
-### "Discovery failed: Cannot read properties of undefined"
+### Issue: "Received JWE (encrypted) token instead of JWT!"
 
-**Cause:** Server URL is incorrect or server isn't running
+**Symptoms:**
+```
+[DEBUG] Token header: {"alg":"dir","enc":"A256GCM",...}
+[ERROR] Received JWE (encrypted) token instead of JWT!
+```
+
+**Root Cause:** One of these:
+1. ID Token Encryption is enabled in Application settings
+2. Application type is wrong (SPA instead of Regular Web App)
+3. Audience parameter not being sent (fixed in latest Studio version)
 
 **Fix:**
-1. Verify server is running: `lsof -i :3002`
-2. Check URL is exactly: `http://localhost:3002`
-3. Test metadata endpoint: `curl http://localhost:3002/.well-known/oauth-protected-resource`
+1. Go to Applications → Your Application → Settings → Advanced Settings
+2. Click **"ID Token"** tab
+3. Ensure **"ID Token Encryption"** is **Disabled** or **None**
+4. Click **"OAuth"** tab
+5. Ensure **"OIDC Conformant"** is **ON**
+6. **Save Changes**
+7. Clear Studio's saved token and re-authorize
 
-### "Token audience mismatch"
+### Issue: "Application doesn't show in API's Machine to Machine tab"
 
-**Cause:** `RESOURCE_URI` doesn't match Auth0 API Identifier
+**Root Cause:** Application type is "Single Page Application" instead of "Regular Web Application"
 
 **Fix:**
-1. In Auth0: Applications → APIs → Your API → Identifier
-2. In `.env`: `RESOURCE_URI` must match exactly
-3. In `.env`: `TOKEN_AUDIENCE` must match exactly
+1. Delete the current application
+2. Create a new one with type **"Regular Web Application"**
+3. Follow Step 3 again
+
+### Issue: "Token audience mismatch"
 
-### "Invalid token issuer"
+**Symptoms:**
+```
+OAuth token validation failed: Token audience mismatch. 
+Expected: https://mcplocal, Got: https://dev-abc123.us.auth0.com/api/v2/
+```
 
-**Cause:** `TOKEN_ISSUER` doesn't match token's `iss` claim
+**Root Cause:** `RESOURCE_URI` in `.env` doesn't match Auth0 API Identifier
+
+**Fix:**
+1. In Auth0: Applications → APIs → Your API → Settings → **Identifier**
+2. Copy the exact identifier (e.g., `https://mcplocal`)
+3. In `.env`: Set `RESOURCE_URI` to match **EXACTLY** (case-sensitive)
+4. In `.env`: Set `TOKEN_AUDIENCE` to match **EXACTLY**
+5. Restart your MCP server
+
+### Issue: "Discovery failed" or "Cannot read properties of undefined"
+
+**Root Cause:** Server URL is incorrect or server isn't running
+
+**Fix:**
+1. Verify server is running: Check for "🚀 OAuth discovery server running" in logs
+2. Check URL is exactly: `http://localhost:3005` (dev mode)
+3. Test metadata endpoint:
+   ```bash
+   curl http://localhost:3005/.well-known/oauth-protected-resource
+   ```
+   Should return:
+   ```json
+   {
+     "resource": "https://mcplocal",
+     "authorization_servers": ["https://dev-abc123.us.auth0.com"],
+     "scopes_supported": ["read", "write", "admin"]
+   }
+   ```
+
+### Issue: "Invalid token issuer"
+
+**Root Cause:** `TOKEN_ISSUER` doesn't match token's `iss` claim
 
 **Fix:**
 1. Check Auth0 domain in dashboard
 2. Add `https://` prefix
 3. Add trailing `/` 
-4. Example: `https://dev-abc123.us.auth0.com/`
+4. Example: `https://dev-abc123.us.auth0.com/` (note the slash!)
 
-### "Insufficient scope"
+### Issue: "Insufficient scope"
 
-**Cause:** Token doesn't have required scopes for the tool
+**Root Cause:** Token doesn't have required scopes for the tool
 
 **Fix:**
-1. In Auth0: Applications → APIs → Your API → Permissions
-2. Add the required scopes
-3. Re-authorize in Studio (logout and login again)
-4. New token will have updated scopes
+1. In Auth0: Applications → APIs → Your API → Machine to Machine Applications
+2. Find your application and ensure it's **Authorized**
+3. Click the dropdown and **select all required scopes**
+4. Click **"Update"**
+5. In Studio: Clear the saved token and re-authorize
+6. New token will have updated scopes
 
-### "Port 3002 already in use"
+### Issue: "Port 3005 already in use"
 
-**Cause:** Previous server instance still running
+**Root Cause:** Previous server instance still running
 
 **Fix:**
 ```bash
-# Kill process on port 3002
-lsof -ti :3002 | xargs kill -9
+# Kill process on port 3005
+lsof -ti :3005 | xargs kill -9
 
 # Restart server
 npm run dev
@@ -374,33 +544,49 @@ TOKEN_ISSUER=https://login.microsoftonline.com/YOUR-TENANT-ID/v2.0
 - [OAuth 2.1 Draft](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13)
 - [RFC 8707 - Resource Indicators](https://datatracker.ietf.org/doc/html/rfc8707)
 - [RFC 9728 - Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)
+- [OpenAI Apps SDK - Auth](https://developers.openai.com/apps-sdk/build/auth)
 
 ---
 
-## ✅ Checklist
+## ✅ Pre-Flight Checklist
 
 Before asking for help, verify:
 
-- [ ] Auth0 Application created with correct callback URLs
-- [ ] Auth0 API created with correct identifier
-- [ ] Scopes added to Auth0 API
-- [ ] `.env` file configured with correct values
-- [ ] Server starts successfully (check logs)
-- [ ] HTTP metadata endpoint accessible: `curl http://localhost:3002/.well-known/oauth-protected-resource`
-- [ ] Discovery works in Studio
+- [ ] Auth0 API created with **RS256** signing algorithm
+- [ ] Auth0 API **JWT Profile** set to **RFC 9068**
+- [ ] Auth0 Application type is **"Regular Web Application"** (not SPA or M2M)
+- [ ] Application has correct **callback URLs** (`http://localhost:3005/auth/callback`)
+- [ ] Application **Grant Types** include "Authorization Code" and "Refresh Token"
+- [ ] Application **ID Token Encryption** is **DISABLED**
+- [ ] Application is **Authorized** to access the API (Machine to Machine Applications tab)
+- [ ] Required **scopes** are granted to the application
+- [ ] `.env` file has `RESOURCE_URI` matching Auth0 API Identifier **EXACTLY**
+- [ ] `.env` file has `TOKEN_ISSUER` with **trailing slash** `/`
+- [ ] Server starts successfully (check logs for "🚀 OAuth discovery server running")
+- [ ] Discovery endpoint is accessible: `curl http://localhost:3005/.well-known/oauth-protected-resource`
+- [ ] Discovery works in Studio (shows resource, auth servers, scopes)
 - [ ] Client credentials saved in Studio
 - [ ] OAuth flow completes successfully
+- [ ] Server logs show **RS256 JWT tokens** (not JWE encrypted tokens)
 - [ ] JWT token stored in Studio (check Auth tab)
+- [ ] Protected tools execute successfully
 
 **If all checkboxes are ✅ and it still doesn't work,** check the troubleshooting section above!
 
 ---
 
-**Need Help?** Open an issue on [GitHub](https://github.com/yourrepo/nitrostack/issues) with:
-1. Your Auth0 configuration (hide secrets!)
-2. Server logs
-3. Browser console errors
-4. Steps you've tried
+## 🎓 What We Learned (Common Pitfalls)
+
+1. **Application Type Matters:** Must be "Regular Web Application", not SPA or M2M
+2. **Audience Parameter is Critical:** Without it, Auth0 returns encrypted tokens (fixed in Studio)
+3. **API Identifier Must Match:** `RESOURCE_URI` must **exactly** match Auth0 API Identifier
+4. **Encryption Must Be Disabled:** ID Token encryption breaks JWT validation
+5. **Trailing Slash Matters:** `TOKEN_ISSUER` must have trailing `/` for Auth0
+6. **Authorization Required:** Application must be explicitly authorized to access the API
+7. **Port Awareness:** Dev mode uses 3005, prod mode uses 3000
+
+---
 
-Happy coding! 🚀
+**Happy coding! 🚀**
 
+If you have issues, check the troubleshooting section above. Most problems are solved by verifying the checklist!