nitrostack 1.0.23 → 1.0.24

package/templates/typescript-oauth/README.md

@@ -21,53 +21,72 @@ npm install
 
 ### 2. Setup Auth0 (Recommended for Quick Testing)
 
+**⚠️ IMPORTANT:** Follow the steps in **exact order** to avoid common issues!
+
+#### Create Auth0 API (Do This First!)
+
+1. Auth0 Dashboard → **Applications** → **APIs** → **Create API**
+2. **Settings:**
+   - **Name**: `MCP Server API`
+   - **Identifier**: `https://mcplocal` (your RESOURCE_URI - can be any unique URI)
+   - **Signing Algorithm**: **RS256**
+   - **JWT Profile**: **RFC 9068** (OAuth 2.0 Access Token JWT Profile)
+3. **Permissions** tab → **Add Scopes:**
+   - `read` - Read access to resources
+   - `write` - Write/modify resources  
+   - `admin` - Administrative operations
+4. **Save**
+
 #### Create Auth0 Application
 
 1. Go to [Auth0 Dashboard](https://manage.auth0.com/)
 2. **Applications** → **Create Application**
-3. Choose **"Regular Web Application"**
+3. Choose **"Regular Web Application"** ← **CRITICAL!** (Not SPA or M2M)
 4. **Application Settings:**
-   - **Name**: `NitroStack OAuth Server`
-   - **Allowed Callback URLs**: `http://localhost:3000/auth/callback`
-   - **Allowed Logout URLs**: `http://localhost:3000`
-   - **Allowed Web Origins**: `http://localhost:3000`
-   - **Grant Types**: Authorization Code, Refresh Token
+   - **Name**: `MCP Server OAuth`
+   - **Allowed Callback URLs**: `http://localhost:3005/auth/callback,http://localhost:3000/auth/callback`
+   - **Allowed Logout URLs**: `http://localhost:3005,http://localhost:3000`
+   - **Allowed Web Origins**: `http://localhost:3005,http://localhost:3000`
+   - **Advanced Settings → Grant Types**: 
+     - ✅ Authorization Code
+     - ✅ Refresh Token
+     - ❌ Implicit (disable)
+   - **Advanced Settings → ID Token Tab**:
+     - ❌ ID Token Encryption: **DISABLED** or **NONE**
 5. **Save** and copy:
    - **Domain** (e.g., `dev-xxx.us.auth0.com`)
    - **Client ID**
    - **Client Secret**
 
-#### Create Auth0 API
+#### Link Application to API
 
-1. Auth0 Dashboard → **Applications** → **APIs** → **Create API**
-2. **Settings:**
-   - **Name**: `NitroStack MCP API`
-   - **Identifier**: `http://localhost:3002` (your RESOURCE_URI)
-   - **Signing Algorithm**: RS256
-3. **Permissions** tab → **Add Scopes:**
-   - `read` - Read access to resources
-   - `write` - Write/modify resources  
-   - `admin` - Administrative operations
-4. **Save**
+1. Go to **Applications** → **APIs** → **MCP Server API**
+2. Click **"Machine to Machine Applications"** tab
+3. Find your `MCP Server OAuth` application
+4. Toggle to **"Authorized"** (green)
+5. Expand and select all scopes (`read`, `write`, `admin`)
+6. Click **"Update"**
 
 ### 3. Configure Environment Variables
 
 Edit `.env` with your Auth0 settings:
 
 ```bash
-# Your MCP server's resource URI (matches API Identifier in Auth0)
-RESOURCE_URI=http://localhost:3002
+# Your MCP server's resource URI (MUST match Auth0 API Identifier EXACTLY)
+RESOURCE_URI=https://mcplocal
 
 # Your Auth0 domain (with https://)
 AUTH_SERVER_URL=https://YOUR-TENANT.auth0.com
 
-# Token audience (same as RESOURCE_URI)
-TOKEN_AUDIENCE=http://localhost:3002
+# Token audience (MUST match RESOURCE_URI)
+TOKEN_AUDIENCE=https://mcplocal
 
-# Token issuer (Auth0 domain with trailing slash)
+# Token issuer (Auth0 domain with trailing slash - don't forget the /)
 TOKEN_ISSUER=https://YOUR-TENANT.auth0.com/
 ```
 
+**⚠️ Replace `YOUR-TENANT` with your actual Auth0 domain!**
+
 **See `OAUTH_SETUP.md` for other providers** (Okta, Keycloak, Azure AD).
 
 ### 4. Start the Server
@@ -78,14 +97,19 @@ npm run dev
 
 You should see:
 ```
-🌐 HTTP MCP Server listening on http://0.0.0.0:3002/mcp
-🔐 OAuth 2.1 enabled
+🚀 OAuth discovery server running at http://localhost: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://YOUR-TENANT.auth0.com"}
 🚀 Server started successfully (DUAL: STDIO + HTTP)
 📡 MCP Protocol: STDIO (for Studio/Claude)
-🌐 OAuth Metadata: HTTP (port 3002)
+🌐 OAuth Metadata: HTTP (port 3005)
 ```
 
-**Note:** The server runs in **DUAL mode** - STDIO for MCP protocol + HTTP for OAuth metadata!
+**Note:** The server runs in **DUAL mode**:
+- **STDIO**: For MCP protocol communication
+- **HTTP (port 3005)**: For OAuth discovery in dev mode
+- **HTTP (port 3000)**: For OAuth discovery in prod mode
 
 ### 5. Complete OAuth Flow in Studio
 
@@ -94,10 +118,11 @@ Navigate to `http://localhost:3000`
 
 #### Step 1: Discover OAuth Server
 1. Go to **Auth → OAuth 2.1** tab
-2. Enter Server URL: `http://localhost:3002`
+2. Enter Server URL: `http://localhost:3005` (dev mode uses port 3005)
 3. Click **"Discover Auth Config"**
 4. ✅ Should show: **Discovery Successful**
 5. You'll see the discovered metadata (resource URI, auth server, scopes)
+6. ✅ Check browser console for: `🎯 Setting audience parameter: https://mcplocal`
 
 #### Step 2: Enter Client Credentials  
 1. Scroll to **"2a. Use Existing Client"** section
@@ -298,20 +323,39 @@ This template works with any RFC-compliant OAuth 2.1 provider:
 
 ## 🚨 Common Issues
 
+### "Received JWE (encrypted) token instead of JWT!"
+
+**Symptoms:** Server logs show:
+```
+[DEBUG] Token header: {"alg":"dir","enc":"A256GCM",...}
+[ERROR] Received JWE (encrypted) token instead of JWT!
+```
+
+**Fix:** 
+1. Go to Applications → Your Application → Settings → Advanced Settings
+2. Click "ID Token" tab
+3. Disable "ID Token Encryption" or set to "None"
+4. Save and re-authorize in Studio
+
 ### "OAuth token validation failed: Token audience mismatch"
 
-**Fix:** Ensure `TOKEN_AUDIENCE` in `.env` matches the audience claim in your tokens.
+**Fix:** Ensure `RESOURCE_URI` and `TOKEN_AUDIENCE` in `.env` match the Auth0 API Identifier **EXACTLY**.
 
 ```bash
 # .env
-TOKEN_AUDIENCE=https://mcp.yourapp.com
+RESOURCE_URI=https://mcplocal
+TOKEN_AUDIENCE=https://mcplocal
 
-# Token must have:
+# Token will have:
 {
-  "aud": "https://mcp.yourapp.com"  # ← Must match
+  "aud": "https://mcplocal"  # ← Must match exactly
 }
 ```
 
+### "Application doesn't show in API's Machine to Machine tab"
+
+**Fix:** Application type must be "Regular Web Application", not "Single Page Application". Delete and recreate the application with correct type.
+
 ### "Missing required environment variables"
 
 **Fix:** Copy `.env.example` to `.env` and configure all required variables.

package/templates/typescript-oauth/package.json

@@ -6,10 +6,12 @@
   "scripts": {
     "dev": "nitrostack dev",
     "build": "nitrostack build",
-    "start": "nitrostack start",
+    "start": "npm run build && nitrostack start",
+    "start:prod": "nitrostack start",
     "widget": "npm --prefix src/widgets"
   },
   "dependencies": {
+    "dotenv": "^16.4.5",
     "nitrostack": "^1",
     "zod": "^3.23.8"
   },

package/templates/typescript-oauth/src/index.ts

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
+import { config } from 'dotenv';
 import { McpApplicationFactory } from 'nitrostack';
 import { AppModule } from './app.module.js';
 
+// Load environment variables from .env file
+config();
+
 /**
  * OAuth 2.1 MCP Server
  * 
@@ -56,33 +60,8 @@ async function bootstrap() {
     console.error(`   Scopes: read, write, admin`);
     console.error(`   Audience: ${process.env.TOKEN_AUDIENCE || process.env.RESOURCE_URI}\n`);
 
-    // Determine transport based on environment
-    const isDevelopment = process.env.NODE_ENV === 'development' || !process.env.NODE_ENV;
-    
-    if (isDevelopment) {
-      // Development: STDIO only (for local testing)
-      await app.start('stdio');
-      console.error('🚀 Server running in DEVELOPMENT mode (STDIO only)');
-      console.error('   Use MCP Inspector for testing OAuth flows\n');
-    } else {
-      // Production: Dual transport (STDIO + HTTP SSE)
-      // OAuth servers typically need HTTP transport for token validation
-      const port = parseInt(process.env.PORT || '3002');
-      const host = process.env.HOST || '0.0.0.0';
-      
-    await app.start('dual', {
-      port,
-      host,
-      endpoint: '/mcp',
-      enableCors: process.env.ENABLE_CORS !== 'false', // Enable by default, disable with ENABLE_CORS=false
-    });
-      
-      console.error('🚀 Server running in PRODUCTION mode (DUAL)');
-      console.error(`   📡 STDIO: Ready for direct connections`);
-      console.error(`   🌐 HTTP SSE: http://${host}:${port}/mcp`);
-      console.error('   Open NitroStack Studio to test OAuth 2.1 flow');
-      console.error('   Configure OAuth in Studio → Auth → OAuth 2.1 tab\n');
-    }
+    // Start the server
+    await app.start();
     
   } catch (error) {
     console.error('❌ Failed to start server:', error);

package/templates/typescript-starter/package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "dev": "nitrostack dev",
     "build": "nitrostack build",
-    "start": "nitrostack start",
+    "start": "npm run build && nitrostack start",
+    "start:prod": "nitrostack start",
     "widget": "npm --prefix src/widgets"
   },
   "dependencies": {

package/templates/typescript-starter/src/index.ts

@@ -9,39 +9,20 @@
  * - Production (NODE_ENV=production): Dual transport (STDIO + HTTP SSE)
  */
 
+import { config } from 'dotenv';
 import { McpApplicationFactory } from 'nitrostack';
 import { AppModule } from './app.module.js';
 
+// Load environment variables from .env file
+config();
+
 /**
  * Bootstrap the application
  */
 async function bootstrap() {
-  // Create the MCP server from AppModule
+  // Create and start the MCP server
   const server = await McpApplicationFactory.create(AppModule);
-  
-  // Determine transport based on environment
-  const isDevelopment = process.env.NODE_ENV === 'development' || !process.env.NODE_ENV;
-  
-  if (isDevelopment) {
-    // Development: STDIO only (for local testing with MCP Inspector, Claude Desktop)
-    await server.start('stdio');
-    console.error('🚀 Server running in DEVELOPMENT mode (STDIO only)');
-  } else {
-    // Production: Dual transport (STDIO + HTTP SSE)
-    const port = parseInt(process.env.PORT || '3000');
-    const host = process.env.HOST || 'localhost';
-    
-    await server.start('dual', {
-      port,
-      host,
-      endpoint: '/mcp',
-      enableCors: process.env.ENABLE_CORS !== 'false', // Enable by default, disable with ENABLE_CORS=false
-    });
-    
-    console.error('🚀 Server running in PRODUCTION mode (DUAL)');
-    console.error(`   📡 STDIO: Ready for direct connections`);
-    console.error(`   🌐 HTTP SSE: http://${host}:${port}/mcp`);
-  }
+  await server.start();
 }
 
 // Start the application