nitrostack 1.0.0

package/templates/typescript-oauth/OAUTH_SETUP.md

@@ -0,0 +1,406 @@
+# 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.
+
+## 🎯 What You'll Learn
+
+- ✅ How to configure Auth0 (or other OAuth providers)
+- ✅ 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)
+
+### Why Auth0?
+- ✅ **Free tier** (7,000 active users, no credit card)
+- ✅ **Fastest setup** (5 minutes)
+- ✅ **Best for testing** and learning
+- ✅ **Production-ready** when you need it
+
+---
+
+## Step 1: Create Auth0 Account
+
+1. Go to **[auth0.com/signup](https://auth0.com/signup)**
+2. Sign up for free (choose "Personal" plan)
+3. Complete email verification
+
+---
+
+## Step 2: Create Auth0 Application
+
+This represents NitroStack Studio as an OAuth client.
+
+1. Open **Auth0 Dashboard** → **Applications** → **Applications**
+2. Click **"Create Application"**
+3. **Settings:**
+   ```
+   Name: NitroStack Studio
+   Application Type: Regular Web Application
+   ```
+4. Click **"Create"**
+
+5. Go to **Settings** tab and configure:
+   ```
+   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
+   ```
+
+6. **Save Changes**
+
+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)
+
+---
+
+## Step 3: Create Auth0 API
+
+This represents your MCP server as a protected resource.
+
+1. Go to **Applications** → **APIs**
+2. Click **"Create API"**
+3. **Settings:**
+   ```
+   Name: NitroStack MCP Server
+   Identifier: http://localhost:3002
+   Signing Algorithm: RS256
+   ```
+   **Important:** The Identifier MUST match your server's `RESOURCE_URI`
+
+4. Click **"Create"**
+
+5. Go to **Permissions** tab
+6. Add these scopes:
+   ```
+   Scope          Description
+   -----          -----------
+   read           Read access to resources
+   write          Write/modify resources
+   admin          Administrative operations
+   ```
+
+7. Click **"Add"** for each scope
+
+---
+
+## Step 4: Configure Your MCP Server
+
+### Edit `.env` File
+
+Replace the values with your Auth0 settings from Steps 2 & 3:
+
+```bash
+# =============================================================================
+# REQUIRED: Server Configuration
+# =============================================================================
+
+# Your MCP server's public URL (matches API Identifier from Step 3)
+RESOURCE_URI=http://localhost:3002
+
+# Your Auth0 domain (from Step 2)
+AUTH_SERVER_URL=https://dev-abc123.us.auth0.com
+
+# =============================================================================
+# OPTIONAL: Token Configuration
+# =============================================================================
+
+# Expected token audience (must match API Identifier)
+TOKEN_AUDIENCE=http://localhost:3002
+
+# Expected token issuer (Auth0 domain with trailing slash)
+TOKEN_ISSUER=https://dev-abc123.us.auth0.com/
+```
+
+**⚠️ Important:** Replace `dev-abc123` with YOUR actual Auth0 domain!
+
+---
+
+## Step 5: Start Your MCP Server
+
+```bash
+npm install
+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
+🚀 Server started successfully (DUAL: STDIO + HTTP)
+📡 MCP Protocol: STDIO (for Studio/Claude)
+🌐 OAuth Metadata: HTTP (port 3002)
+```
+
+**✅ Success!** Your server is running in DUAL mode:
+- **STDIO**: For MCP protocol communication (tools, chat)
+- **HTTP**: For OAuth metadata and discovery
+
+---
+
+## Step 6: Test OAuth Flow in NitroStack Studio
+
+### Open Studio
+
+Navigate to **http://localhost:3000** in your browser
+
+### 6.1 Discover OAuth Server
+
+1. Go to **Auth** → **OAuth 2.1** tab
+2. In the **"Discover Server Auth"** section:
+   ```
+   Server URL: http://localhost:3002
+   ```
+3. Click **"Discover Auth Config"**
+
+**Expected Result:**
+```
+✅ Discovery Successful
+
+Resource: http://localhost:3002
+Authorization Servers: https://dev-abc123.us.auth0.com
+Scopes: read, write, admin
+```
+
+### 6.2 Enter Client Credentials
+
+1. Scroll to **"2a. Use Existing Client"** section
+2. Enter your credentials from Step 2:
+   ```
+   Client ID: [Your Auth0 Client ID]
+   Client Secret: [Your Auth0 Client Secret]
+   ```
+3. Click **"Save Client Credentials"**
+
+**Expected Result:**
+```
+✅ Client credentials saved!
+```
+
+### 6.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
+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
+6. ✅ Token is automatically saved!
+
+**Expected Result:**
+```
+✅ Authorization successful! Redirecting...
+```
+
+### 6.4 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"**
+
+**Expected Result:**
+```json
+{
+  "success": true,
+  "user": {
+    "sub": "auth0|xxx",
+    "scopes": ["read", "write", "admin"]
+  }
+}
+```
+
+**🎉 Congratulations!** Your OAuth 2.1 server is fully working!
+
+---
+
+## 🔍 How It Works
+
+### Dual Transport Architecture
+
+NitroStack runs **two transports simultaneously**:
+
+```
+┌─────────────────────────────────────┐
+│   Your OAuth 2.1 MCP Server         │
+├─────────────────────────────────────┤
+│                                     │
+│  📡 STDIO Transport                 │
+│  ├─ MCP Protocol (tools, chat)      │
+│  ├─ Connected to Studio/Claude      │
+│  └─ stdin/stdout communication      │
+│                                     │
+│  🌐 HTTP Server (Port 3002)         │
+│  ├─ OAuth Metadata Endpoints        │
+│  ├─ /.well-known/oauth-protected-   │
+│  │   resource                       │
+│  └─ Discovery & Token Validation    │
+│                                     │
+└─────────────────────────────────────┘
+```
+
+### OAuth Flow Sequence
+
+```
+1. Studio → Discover     → Your MCP Server (HTTP)
+                          ↓
+                      Returns OAuth metadata
+                          ↓
+2. Studio → Authorize    → Auth0 Login Page
+                          ↓
+                      User logs in
+                          ↓
+3. Auth0 → Redirect      → Studio Callback (/auth/callback)
+                          ↓
+4. Studio → Exchange     → Auth0 Token Endpoint
+                          ↓
+                      Receives JWT token
+                          ↓
+5. Studio → Execute Tool → Your MCP Server (STDIO)
+           (with JWT)    ↓
+                      Tool validates token & executes
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### "Discovery failed: Cannot read properties of undefined"
+
+**Cause:** Server URL is incorrect or server isn't running
+
+**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`
+
+### "Token audience mismatch"
+
+**Cause:** `RESOURCE_URI` doesn't match Auth0 API Identifier
+
+**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
+
+### "Invalid token issuer"
+
+**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/`
+
+### "Insufficient scope"
+
+**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
+
+### "Port 3002 already in use"
+
+**Cause:** Previous server instance still running
+
+**Fix:**
+```bash
+# Kill process on port 3002
+lsof -ti :3002 | xargs kill -9
+
+# Restart server
+npm run dev
+```
+
+---
+
+## 🌐 Other OAuth Providers
+
+### Okta
+
+```bash
+RESOURCE_URI=https://mcp.yourapp.com
+AUTH_SERVER_URL=https://your-domain.okta.com/oauth2/default
+TOKEN_AUDIENCE=api://mcp.yourapp.com
+TOKEN_ISSUER=https://your-domain.okta.com/oauth2/default
+```
+
+### Keycloak
+
+```bash
+RESOURCE_URI=https://mcp.yourapp.com
+AUTH_SERVER_URL=https://keycloak.yourapp.com/realms/your-realm
+TOKEN_AUDIENCE=mcp-server
+TOKEN_ISSUER=https://keycloak.yourapp.com/realms/your-realm
+```
+
+### Azure AD / Entra ID
+
+```bash
+RESOURCE_URI=https://mcp.yourapp.com
+AUTH_SERVER_URL=https://login.microsoftonline.com/YOUR-TENANT-ID/v2.0
+TOKEN_AUDIENCE=api://YOUR-APP-ID
+TOKEN_ISSUER=https://login.microsoftonline.com/YOUR-TENANT-ID/v2.0
+```
+
+---
+
+## 📚 Learn More
+
+- [MCP OAuth Specification](https://modelcontextprotocol.io/specification/draft/basic/authorization)
+- [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)
+
+---
+
+## ✅ 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
+- [ ] Client credentials saved in Studio
+- [ ] OAuth flow completes successfully
+- [ ] JWT token stored in Studio (check Auth tab)
+
+**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
+
+Happy coding! 🚀
+