nitrostack 1.0.0

package/templates/typescript-oauth/README.md

@@ -0,0 +1,350 @@
+# OAuth 2.1 MCP Server Template
+
+Complete OAuth 2.1 authentication implementation for Model Context Protocol servers.
+
+## 🎯 What This Template Demonstrates
+
+- ✅ **OAuth 2.1** authentication (MCP & OpenAI Apps SDK compliant)
+- ✅ **Token Audience Binding** (RFC 8707) - Critical security feature
+- ✅ **Protected Resource Metadata** (RFC 9728) - Auto-discovery
+- ✅ **PKCE Support** (RFC 7636) - Already handled by NitroStack Studio
+- ✅ **Scope-based Access Control** - Fine-grained permissions
+- ✅ **Multi-Provider Support** - Works with Auth0, Okta, Keycloak, etc.
+
+## 🚀 Quick Start
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Setup Auth0 (Recommended for Quick Testing)
+
+#### Create Auth0 Application
+
+1. Go to [Auth0 Dashboard](https://manage.auth0.com/)
+2. **Applications** → **Create Application**
+3. Choose **"Regular Web Application"**
+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
+5. **Save** and copy:
+   - **Domain** (e.g., `dev-xxx.us.auth0.com`)
+   - **Client ID**
+   - **Client Secret**
+
+#### Create Auth0 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**
+
+### 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 Auth0 domain (with https://)
+AUTH_SERVER_URL=https://YOUR-TENANT.auth0.com
+
+# Token audience (same as RESOURCE_URI)
+TOKEN_AUDIENCE=http://localhost:3002
+
+# Token issuer (Auth0 domain with trailing slash)
+TOKEN_ISSUER=https://YOUR-TENANT.auth0.com/
+```
+
+**See `OAUTH_SETUP.md` for other providers** (Okta, Keycloak, Azure AD).
+
+### 4. Start the Server
+
+```bash
+npm run dev
+```
+
+You should see:
+```
+🌐 HTTP MCP Server listening on http://0.0.0.0:3002/mcp
+🔐 OAuth 2.1 enabled
+🚀 Server started successfully (DUAL: STDIO + HTTP)
+📡 MCP Protocol: STDIO (for Studio/Claude)
+🌐 OAuth Metadata: HTTP (port 3002)
+```
+
+**Note:** The server runs in **DUAL mode** - STDIO for MCP protocol + HTTP for OAuth metadata!
+
+### 5. Complete OAuth Flow in Studio
+
+#### Open NitroStack Studio
+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`
+3. Click **"Discover Auth Config"**
+4. ✅ Should show: **Discovery Successful**
+5. You'll see the discovered metadata (resource URI, auth server, scopes)
+
+#### Step 2: Enter Client Credentials  
+1. Scroll to **"2a. Use Existing Client"** section
+2. **Client ID**: Paste your Auth0 Client ID
+3. **Client Secret**: Paste your Auth0 Client Secret
+4. Click **"Save Client Credentials"**
+5. ✅ Should show: **Client credentials saved!**
+
+#### Step 3: Start OAuth Flow
+1. Click **"Start Authorization Flow"**
+2. ✅ You'll be redirected to Auth0 login page
+3. **Login** with your Auth0 account
+4. **Authorize** the application (grant requested scopes)
+5. ✅ You'll be redirected back to Studio with a JWT token!
+6. ✅ Token is automatically saved and ready to use
+
+#### Step 4: Test Protected Tools
+1. Go to **Tools** tab
+2. Try any protected tool (e.g., `get_user_profile`, `list_resources`)
+3. ✅ Your JWT token is automatically included in requests!
+4. Tools will show your authenticated user info
+
+**Congratulations! 🎉** Your OAuth 2.1 server is working!
+
+## 📋 Available Tools
+
+### Public Tools (No Auth)
+
+| Tool | Description |
+|------|-------------|
+| `get_server_info` | Get server information |
+
+### Protected Tools (OAuth Required)
+
+| Tool | Required Scopes | Description |
+|------|-----------------|-------------|
+| `get_user_profile` | _(any valid token)_ | Get authenticated user info |
+| `list_resources` | `read` | List available resources |
+| `create_resource` | `write` | Create a new resource |
+| `admin_statistics` | `read`, `admin` | Get admin statistics |
+
+## 🏗️ Project Structure
+
+```
+typescript-oauth/
+├── src/
+│   ├── guards/
+│   │   └── oauth.guard.ts          # OAuth token validation
+│   ├── modules/demo/
+│   │   ├── demo.module.ts
+│   │   └── demo.tools.ts           # Example tools
+│   ├── app.module.ts               # OAuthModule configuration
+│   └── index.ts                    # Entry point
+├── .env.example                    # Environment template
+├── OAUTH_SETUP.md                  # Provider setup guides
+└── README.md
+```
+
+## 🔐 OAuth 2.1 Implementation
+
+### OAuthModule Configuration
+
+```typescript
+// src/app.module.ts
+OAuthModule.forRoot({
+  resourceUri: process.env.RESOURCE_URI!,
+  authorizationServers: [process.env.AUTH_SERVER_URL!],
+  scopesSupported: ['read', 'write', 'admin'],
+  tokenIntrospectionEndpoint: process.env.INTROSPECTION_ENDPOINT,
+  audience: process.env.TOKEN_AUDIENCE,
+  issuer: process.env.TOKEN_ISSUER,
+})
+```
+
+### OAuth Guard
+
+```typescript
+// Protect a tool with OAuth
+@Tool({ name: 'protected_tool' })
+@UseGuards(OAuthGuard)
+async protectedTool() {
+  // Only accessible with valid OAuth token
+}
+```
+
+### Scope-Based Access
+
+```typescript
+// Require specific scopes
+@Tool({ name: 'admin_tool' })
+@UseGuards(OAuthGuard, createScopeGuard(['admin']))
+async adminTool() {
+  // Requires 'admin' scope
+}
+```
+
+## 🔑 Key Security Features
+
+### 1. Token Audience Binding (RFC 8707)
+
+**Critical for security!** Tokens are validated to ensure they were issued **specifically for your MCP server**.
+
+```typescript
+// Tokens MUST include your RESOURCE_URI in the audience claim
+{
+  "aud": "https://mcp.yourapp.com",  // ← Must match RESOURCE_URI
+  "sub": "user123",
+  "scope": "read write"
+}
+```
+
+### 2. No Token Passthrough
+
+**Never forward OAuth tokens to other services!** Each service must have its own token.
+
+```typescript
+// ❌ WRONG - Don't do this
+await upstreamAPI.call(headers: { Authorization: clientToken });
+
+// ✅ CORRECT - Use separate token
+const upstreamToken = await getTokenForUpstream();
+await upstreamAPI.call(headers: { Authorization: upstreamToken });
+```
+
+### 3. Scope Validation
+
+Fine-grained access control based on OAuth scopes:
+
+```typescript
+// Automatically validates scopes
+@UseGuards(OAuthGuard, createScopeGuard(['read', 'write']))
+```
+
+## 🧪 Testing with Studio
+
+### Step 1: Start OAuth Flow
+
+1. **Auth Tab** → **OAuth 2.1**
+2. Enter your MCP server URL
+3. Click **"Discover & Register"**
+
+### Step 2: Complete Authorization
+
+1. Studio redirects to your OAuth provider
+2. Login with your credentials
+3. Grant requested scopes
+4. Studio receives and stores the token
+
+### Step 3: Test Tools
+
+1. **Tools Tab** → Select a protected tool
+2. Execute - Token is automatically included!
+3. Try tools with different scope requirements
+
+## 📚 Standards Compliance
+
+This template implements:
+
+- ✅ **OAuth 2.1** ([draft-ietf-oauth-v2-1-13](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13))
+- ✅ **RFC 9728** - Protected Resource Metadata
+- ✅ **RFC 8414** - Authorization Server Metadata
+- ✅ **RFC 7591** - Dynamic Client Registration  
+- ✅ **RFC 8707** - Resource Indicators (Token Audience Binding)
+- ✅ **RFC 7636** - PKCE
+- ✅ **RFC 7662** - Token Introspection
+
+Compatible with:
+- ✅ [MCP Specification](https://modelcontextprotocol.io/specification/draft/basic/authorization)
+- ✅ [OpenAI Apps SDK](https://developers.openai.com/apps-sdk/build/auth)
+
+## 🔧 Configuration Options
+
+### Required
+
+- `RESOURCE_URI` - Your MCP server's public URL
+- `AUTH_SERVER_URL` - Your OAuth provider's base URL
+
+### Optional
+
+- `TOKEN_AUDIENCE` - Expected audience (defaults to RESOURCE_URI)
+- `TOKEN_ISSUER` - Expected issuer (recommended for security)
+- `INTROSPECTION_ENDPOINT` - For opaque token validation
+- `INTROSPECTION_CLIENT_ID` - Introspection client credentials
+- `INTROSPECTION_CLIENT_SECRET` - Introspection client secret
+
+## 🌐 Supported OAuth Providers
+
+This template works with any RFC-compliant OAuth 2.1 provider:
+
+- ✅ **Auth0** - Easiest for testing
+- ✅ **Okta** - Enterprise-ready
+- ✅ **Keycloak** - Self-hosted
+- ✅ **Azure AD / Entra ID**
+- ✅ **Google Identity Platform**
+- ✅ **Custom OAuth servers**
+
+**See `OAUTH_SETUP.md` for provider-specific configuration guides.**
+
+## 🚨 Common Issues
+
+### "OAuth token validation failed: Token audience mismatch"
+
+**Fix:** Ensure `TOKEN_AUDIENCE` in `.env` matches the audience claim in your tokens.
+
+```bash
+# .env
+TOKEN_AUDIENCE=https://mcp.yourapp.com
+
+# Token must have:
+{
+  "aud": "https://mcp.yourapp.com"  # ← Must match
+}
+```
+
+### "Missing required environment variables"
+
+**Fix:** Copy `.env.example` to `.env` and configure all required variables.
+
+```bash
+cp .env.example .env
+# Edit .env with your OAuth provider settings
+```
+
+### "Insufficient scope"
+
+**Fix:** Request the required scopes when authorizing in Studio:
+
+1. Auth Tab → OAuth 2.1
+2. Check required scopes for the tool
+3. Re-authorize with correct scopes
+
+## 📖 Learn More
+
+- [MCP OAuth Specification](https://modelcontextprotocol.io/specification/draft/basic/authorization)
+- [OpenAI Apps SDK Auth](https://developers.openai.com/apps-sdk/build/auth)
+- [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)
+- [OAUTH_SETUP.md](./OAUTH_SETUP.md) - Provider setup guides
+
+## 🎉 Ready to Build!
+
+This template provides a production-ready OAuth 2.1 implementation. Customize it for your needs:
+
+1. Add your own tools with appropriate scopes
+2. Integrate with your user database
+3. Add custom token validation logic
+4. Deploy with your chosen OAuth provider
+
+**Happy coding! 🚀**
+

package/templates/typescript-oauth/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "oauth-mcp-server",
+  "version": "1.0.0",
+  "description": "NitroStack server demonstrating OAuth 2.1 authentication",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "nitrostack dev",
+    "build": "nitrostack build",
+    "start": "nitrostack start",
+    "widget": "npm --prefix src/widgets"
+  },
+  "keywords": [
+    "mcp",
+    "nitrostack",
+    "oauth",
+    "oauth2.1",
+    "authentication"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "nitrostack": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}