@nitrostack/cli 1.0.12 → 1.0.14

package/templates/typescript-oauth/.env.example

@@ -2,30 +2,87 @@
 NITRO_LOG_LEVEL=info
 NITROSTACK_APP_MODE=openai
 
-# OAuth 2.1 MCP Server Configuration
+# Server Transport Configuration (Optional)
 # =============================================================================
-# TRANSPORT MODE (AUTO-CONFIGURED)
+# MCP_TRANSPORT_TYPE: Toggles transport mode. Values: stdio | http | dual.
+# Defaults to 'stdio' in development and 'dual' in production/NODE_ENV=production.
 # =============================================================================
-# When OAuth is configured, the server automatically runs in DUAL mode:
-# - STDIO: For MCP proto¯col communication with Studio/Claude
-# - HTTP: For OAuth metadata endpoints (/.well-known/oauth-protected-resource)
-# Both transports run simultaneously on different channels.
+# MCP_TRANSPORT_TYPE=dual
+# PORT=3000
+# HOST=localhost
+# ENABLE_CORS=true
+
+# Streamable HTTP Session Limits (Optional)
 # =============================================================================
-# REQUIRED: Server Configuration
+# Bounds memory against unauthenticated initialize floods. Defaults: 1000 sessions,
+# 30-minute idle timeout. Only applies when running in http or dual transport mode.
 # =============================================================================
+# MCP_MAX_SESSIONS=1000
+# MCP_SESSION_TIMEOUT_MS=1800000
+
+# OAuth 2.1 MCP Server Configuration
+# =============================================================================
+# Enforcement Gate (Optional)
 # =============================================================================
-# Auth0 Configuration
+# OAUTH_REQUIRED controls whether authentication is enforced.
+#   - Unset / false (default): auth is NOT enforced. The server runs out-of-the-box
+#     and protected endpoints are reachable without a token. Best for local dev.
+#   - true: auth is enforced (fail-closed). If neither JWKS_URI nor
+#     INTROSPECTION_ENDPOINT is configured, the server STILL starts and logs a
+#     clear warning, but rejects all protected requests until a verifier is set.
+# Set this to true (and configure a verifier below) before deploying.
+# =============================================================================
+# OAUTH_REQUIRED=true
+
+# =============================================================================
+# REQUIRED: Server Configuration
 # =============================================================================
-# After creating your API and Application in Auth0, fill in these values:
 # Your Auth0 API Identifier (from APIs → MCP Server → Identifier)
 # This MUST match exactly what you set when creating the API
-# This MUST match exactly what you set when creating the API
 RESOURCE_URI=https://mcplocal
-# Your Auth0 tenant domain (authorization server)
+
+# Your Auth0 tenant domain (authorization server URL)
 AUTH_SERVER_URL=https://dev-5dt0utuk315713tjm.us.auth0.com
-# Expected token audience (should match RESOURCE_URI)
+
+# Cryptographic JWKS Signature Verification (Recommended)
+# =============================================================================
+# If configured, the SDK cryptographically verifies token signatures using JWKS keys.
+# Token validation is SECURE BY DEFAULT (fail-closed): if neither JWKS_URI nor an
+# introspection endpoint (below) is configured, ALL tokens are rejected. Configure
+# one of them for a working server.
+# NOTE: Unsigned/signature-less token decoding is disabled by default and is only
+# available via the in-code `allowInsecureTokenDecode: true` option in
+# OAuthModule.forRoot(...) — intended for local development only, never production.
+# =============================================================================
+# JWKS_URI=https://dev-5dt0utuk315713tjm.us.auth0.com/.well-known/jwks.json
+
+# Expected token validation audience (should match RESOURCE_URI)
 TOKEN_AUDIENCE=https://mcplocal
-# Expected token issuer (your Auth0 tenant domain with trailing slash)
+
+# Expected token validation issuer (your authorization server tenant domain)
 TOKEN_ISSUER=https://dev-5dt0utuk315713tjm.us.auth0.com
 
-DUFFEL_API_KEY=your-duffel-api-key
+# Token Introspection Configuration (Alternative to JWKS signature verification)
+# =============================================================================
+# INTROSPECTION_ENDPOINT=https://dev-5dt0utuk315713tjm.us.auth0.com/oauth/introspect
+# INTROSPECTION_CLIENT_ID=your-introspection-client-id
+# INTROSPECTION_CLIENT_SECRET=your-introspection-client-secret
+
+# OAuth Discovery Settings (Optional)
+# =============================================================================
+# OAUTH_DISCOVERY_PORT=3005
+# OAUTH_DISCOVERY_AUTO_RETRY=true
+# MCP_SERVER_PORT=3000
+
+# Dynamic Client Registration (Optional / disabled by default)
+# =============================================================================
+# Set to 'true' to expose the /oauth/v2/register endpoint. It only serves the
+# statically configured client below; without OAUTH_CLIENT_ID it stays disabled.
+# =============================================================================
+# OAUTH_ENABLE_CLIENT_REGISTRATION=true
+# OAUTH_CLIENT_ID=your-client-id
+# OAUTH_CLIENT_SECRET=your-client-secret
+
+# Duffel API Integration (Required for Flight Search & Booking)
+# =============================================================================
+DUFFEL_API_KEY=your-duffel-api-key

package/templates/typescript-oauth/src/app.module.ts

@@ -36,6 +36,13 @@ import { SystemHealthCheck } from './health/system.health.js';
 
     // Enable OAuth 2.1 authentication
     OAuthModule.forRoot({
+      // Whether OAuth is enforced. Defaults to false (dev-friendly): the server
+      // runs out-of-the-box and protected endpoints are reachable without a token.
+      // Set OAUTH_REQUIRED=true to enforce auth (fail-closed). When enforced but no
+      // verifier (JWKS_URI / INTROSPECTION_ENDPOINT) is configured, the server still
+      // starts and warns, but rejects protected requests until one is configured.
+      required: process.env.OAUTH_REQUIRED === 'true',
+
       // Resource URI - YOUR MCP server's public URL
       // This is used for token audience binding (RFC 8707)
       // CRITICAL: Tokens must be issued specifically for this URI

package/templates/typescript-oauth/src/guards/oauth.guard.ts

@@ -41,6 +41,25 @@ export class OAuthGuard implements Guard {
     } else if (metaToken) {
       token = metaToken as string;
     }
+
+    // Enforcement gate: when OAuth is not required (OAUTH_REQUIRED not "true"),
+    // do not reject. Best-effort: if a valid token happens to be present, attach
+    // its identity; otherwise allow the request through unauthenticated.
+    if (!OAuthModule.isAuthRequired()) {
+      if (token) {
+        const result = await OAuthModule.validateToken(token);
+        if (result.valid) {
+          const payload = result.payload as OAuthTokenPayload;
+          context.auth = {
+            subject: payload.sub,
+            scopes: this.extractScopes(payload),
+            clientId: payload.client_id,
+            tokenPayload: payload,
+          };
+        }
+      }
+      return true;
+    }
     
     if (!token) {
       throw new Error(

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

@@ -28,26 +28,24 @@ async function bootstrap() {
   try {
     console.error('🔐 Starting Calculator MCP Server with OAuth 2.1...\\n');
 
-    // Validate required environment variables for OAuth
-    const requiredEnvVars = ['RESOURCE_URI', 'AUTH_SERVER_URL'];
-    const missing = requiredEnvVars.filter(v => !process.env[v]);
-
-    if (missing.length > 0) {
-      console.error('❌ Missing required OAuth environment variables:');
-      missing.forEach(v => console.error(`   - ${v}`));
-      console.error('\\n💡 Copy .env.example to .env and configure your OAuth provider');
-      console.error('   Or check the test-oauth/.env for reference\\n');
-      process.exit(1);
+    // Validate required environment variables for OAuth, set defaults if missing
+    if (!process.env.RESOURCE_URI || !process.env.AUTH_SERVER_URL) {
+      console.error('⚠️  Warning: Missing RESOURCE_URI or AUTH_SERVER_URL environment variables.');
+      console.error('   Defaulting to local test endpoints. Copy .env.example to .env to configure.\n');
+      process.env.RESOURCE_URI = process.env.RESOURCE_URI || 'http://localhost:3000';
+      process.env.AUTH_SERVER_URL = process.env.AUTH_SERVER_URL || 'http://localhost:8080/auth';
     }
 
     // Create the MCP application
     const server = await McpApplicationFactory.create(AppModule);
 
+    const authEnforced = process.env.OAUTH_REQUIRED === 'true';
     console.error('✅ OAuth 2.1 Module configured');
     console.error(`   Resource URI: ${process.env.RESOURCE_URI}`);
     console.error(`   Auth Server: ${process.env.AUTH_SERVER_URL}`);
     console.error(`   Scopes: read, write, admin`);
-    console.error(`   Audience: ${process.env.TOKEN_AUDIENCE || process.env.RESOURCE_URI}\\n`);
+    console.error(`   Audience: ${process.env.TOKEN_AUDIENCE || process.env.RESOURCE_URI}`);
+    console.error(`   Enforcement: ${authEnforced ? 'ON (OAUTH_REQUIRED=true)' : 'OFF (dev mode — set OAUTH_REQUIRED=true to enforce)'}\\n`);
 
     // Start the server
     await server.start();

package/templates/typescript-oauth/src/modules/flights/flights.prompts.ts

@@ -79,8 +79,26 @@ Respond to EXACTLY what the user asked - nothing more.`;
         ]
     })
     async flightComparison(input: any, ctx: ExecutionContext) {
+        let ids: string[] = [];
+        if (Array.isArray(input.offerIds)) {
+            ids = input.offerIds;
+        } else if (typeof input.offerIds === 'string') {
+            const trimmed = input.offerIds.trim();
+            if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    ids = Array.isArray(parsed) ? parsed : [parsed];
+                } catch {
+                    ids = trimmed.split(',').map((s: string) => s.trim());
+                }
+            } else {
+                ids = trimmed.split(',').map((s: string) => s.trim());
+            }
+        }
+        ids = ids.filter(Boolean);
+
         const offers = await Promise.all(
-            input.offerIds.map((id: string) => this.duffelService.getOffer(id))
+            ids.map((id: string) => this.duffelService.getOffer(id))
         );
 
         const comparisonData = offers.map((offer: any) => {

package/templates/typescript-oauth/src/services/duffel.service.ts

@@ -12,9 +12,11 @@ export class DuffelService {
     private duffel: Duffel;
 
     constructor() {
-        const apiKey = process.env.DUFFEL_API_KEY;
+        let apiKey = process.env.DUFFEL_API_KEY;
         if (!apiKey) {
-            throw new Error('DUFFEL_API_KEY environment variable is required');
+            console.error('⚠️  Warning: DUFFEL_API_KEY environment variable is missing.');
+            console.error('   Running with a dummy key for testing/dry-run mode.\n');
+            apiKey = 'duffel_test_dummy_key';
         }
 
         this.duffel = new Duffel({

package/templates/typescript-pizzaz/.env.example

@@ -2,6 +2,16 @@
 NITRO_LOG_LEVEL=info
 NITROSTACK_APP_MODE=openai
 
+# Server Transport Configuration (Optional)
+# =============================================================================
+# MCP_TRANSPORT_TYPE: Toggles transport mode. Values: stdio | http | dual.
+# Defaults to 'stdio' in development and 'dual' in production/NODE_ENV=production.
+# =============================================================================
+# MCP_TRANSPORT_TYPE=stdio
+# PORT=3000
+# HOST=localhost
+# ENABLE_CORS=true
+
 # Mapbox Configuration (Optional)
 # =============================================================================
 # The map widget uses Mapbox GL for interactive maps. 

package/templates/typescript-starter/.env.example

@@ -1,3 +1,13 @@
 # NitroStack Configuration
 NITRO_LOG_LEVEL=info
 NITROSTACK_APP_MODE=openai
+
+# Server Transport Configuration (Optional)
+# =============================================================================
+# MCP_TRANSPORT_TYPE: Toggles transport mode. Values: stdio | http | dual.
+# Defaults to 'stdio' in development and 'dual' in production/NODE_ENV=production.
+# =============================================================================
+# MCP_TRANSPORT_TYPE=stdio
+# PORT=3000
+# HOST=localhost
+# ENABLE_CORS=true