@nitrostack/cli 1.0.0

package/templates/typescript-oauth/README.md

@@ -0,0 +1,263 @@
+# ✈️ NitroStack Flight Booking
+
+A production-ready NitroStack template showcasing real-time flight search and booking with **Duffel API** integration. Search flights, view details, select seats, and book - all through beautiful interactive widgets.
+
+## ✨ Features
+
+### 🔌 **Duffel API Integration**
+- Real-time flight search across 300+ airlines
+- Live pricing and availability
+- Seat selection with cabin maps
+- Booking and order management
+
+### 🎨 **Interactive Widgets**
+- **Airport Search** - Autocomplete airport selection
+- **Flight Search Results** - Compare flights with prices
+- **Flight Details** - Comprehensive flight information
+- **Seat Selection** - Visual cabin map with seat picker
+- **Order Summary** - Complete booking overview
+- **Payment Confirmation** - Secure payment flow
+
+### 🛠️ **MCP Tools**
+- `search_airports` - Find airports by name/code
+- `search_flights` - Search available flights
+- `show_flight_details` - Detailed flight information
+- `select_seats` - Interactive seat selection
+- `create_booking` - Book flights
+- `get_order` - Retrieve booking details
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+```bash
+# Install NitroStack CLI globally
+npm install -g nitrostack
+
+# Or use npx
+npx nitrostack --version
+```
+
+### 1. Create Your Project
+
+```bash
+# Create a new project
+nitrostack init my-flight-app --template typescript-oauth
+cd my-flight-app
+
+# Install all dependencies (root + widgets)
+nitrostack install
+```
+
+### 2. Get Your Duffel API Key (Free)
+
+[Duffel](https://duffel.com/) provides a free API for flight search and booking:
+
+1. **Sign up** at [duffel.com](https://duffel.com/) (click "Start now" - it's free!)
+2. Create a free account (no credit card required)
+3. Go to your **Dashboard** → **Developers** → **Access tokens**
+4. Click **"Create token"** to generate your API key
+5. Copy the token (starts with `duffel_test_` for sandbox)
+
+> 💡 **Tip**: The test mode (`duffel_test_*` tokens) gives you access to realistic mock data for development. Production tokens (`duffel_live_*`) connect to real airlines.
+
+### 3. Configure Environment
+
+Copy the example environment file and add your Duffel API key:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and update:
+
+```env
+# Duffel API Configuration
+DUFFEL_API_KEY=duffel_test_your_api_key_here
+```
+
+### 4. Run Development Server
+
+```bash
+npm run dev
+```
+
+This starts:
+- **MCP Server** - Hot reloads on code changes
+- **Studio** on http://localhost:3000 - Visual testing environment  
+- **Widget Dev Server** on http://localhost:3001 - Hot module replacement
+
+### 5. Test in Studio
+
+Try these prompts in Studio chat:
+- "Search flights from London to New York for next week"
+- "Show me flight details"
+- "I want to select seats"
+- "Show me flights from JFK to LAX"
+
+## 📁 Project Structure
+
+```
+typescript-oauth/
+├── src/
+│   ├── index.ts                 # Main server entry
+│   ├── app.module.ts            # App module
+│   ├── services/
+│   │   └── duffel.service.ts    # Duffel API client
+│   └── modules/
+│       └── flights/
+│           ├── flights.module.ts    # Module definition
+│           ├── flights.tools.ts     # Search & display tools
+│           ├── flights.prompts.ts   # AI prompts
+│           ├── flights.resources.ts # Static resources
+│           └── booking.tools.ts     # Booking tools
+│   └── widgets/
+│       ├── app/
+│       │   ├── airport-search/      # Airport autocomplete
+│       │   ├── flight-search-results/ # Results list
+│       │   ├── flight-details/      # Flight info
+│       │   ├── seat-selection/      # Seat picker
+│       │   ├── order-summary/       # Booking summary
+│       │   └── payment-confirmation/ # Payment widget
+├── .env.example                 # Environment template
+├── OAUTH_SETUP.md              # OAuth configuration guide
+├── package.json
+└── README.md
+```
+
+## 🔧 Commands
+
+```bash
+# Installation
+npm install              # Install all dependencies (root + widgets)
+nitrostack install       # Same as above
+
+# Development
+npm run dev              # Start dev server with Studio
+npm run build            # Build TypeScript and widgets for production
+npm start                # Run production server
+
+# Upgrade
+npm run upgrade          # Upgrade nitrostack to latest version
+
+# Widget Management
+npm run widget <command> # Run npm command in widgets directory
+npm run widget add <pkg> # Add a widget dependency
+```
+
+## 🔐 OAuth Setup (Optional)
+
+This template includes OAuth 2.1 authentication support. If you want to protect your MCP server with authentication:
+
+1. Read the detailed guide: **[OAUTH_SETUP.md](./OAUTH_SETUP.md)**
+2. Configure Auth0 (or your OAuth provider)
+3. Update your `.env` with OAuth credentials
+
+> **Note**: OAuth is optional for local development. The template works without it using Duffel's test API.
+
+## 📊 Duffel API Features
+
+### Test Mode vs Live Mode
+
+| Feature | Test Mode (`duffel_test_*`) | Live Mode (`duffel_live_*`) |
+|---------|----------------------------|----------------------------|
+| API Access | ✅ Full access | ✅ Full access |
+| Pricing | Mock data | Real prices |
+| Bookings | Simulated | Real bookings |
+| Credit Card | Not charged | Charged |
+| Rate Limits | Generous | Production limits |
+
+### Supported Airlines
+
+Duffel provides access to 300+ airlines including:
+- Major carriers (British Airways, Lufthansa, Emirates, etc.)
+- Low-cost carriers (Ryanair, EasyJet, Spirit, etc.)
+- Regional airlines
+
+### API Capabilities
+
+- **Search**: Real-time availability and pricing
+- **Ancillaries**: Seats, bags, meals
+- **Booking**: Create and manage orders
+- **Changes**: Modify existing bookings
+- **Cancellations**: Cancel and refund
+
+## 🎨 Widget Features
+
+### Airport Search Widget
+- Autocomplete with IATA codes
+- City and airport name search
+- Recent searches
+
+### Flight Search Results Widget
+- Compare multiple flights
+- Filter by stops, price, time
+- Sort options
+- Airline logos
+
+### Flight Details Widget
+- Complete itinerary
+- Fare breakdown
+- Baggage allowance
+- Flight duration and stops
+
+### Seat Selection Widget
+- Visual cabin map
+- Seat categories (standard, extra legroom, etc.)
+- Price per seat
+- Real-time availability
+
+## 🛠️ Customization
+
+### Adding New Airlines
+
+Duffel handles airline integrations automatically. You don't need to configure individual airlines.
+
+### Modifying Search Parameters
+
+Edit `src/modules/flights/flights.tools.ts` to customize:
+- Default passenger counts
+- Cabin class options
+- Date ranges
+- Result limits
+
+### Styling Widgets
+
+Each widget in `src/widgets/app/` can be customized:
+- Edit page.tsx for layout
+- Add custom CSS
+- Modify component styles
+
+## 📚 Resources
+
+### Duffel Documentation
+- [Duffel API Docs](https://duffel.com/docs/api)
+- [Duffel SDK (Node.js)](https://github.com/duffel/duffel-api-javascript)
+- [Duffel Postman Collection](https://duffel.com/docs/postman)
+
+### NitroStack Documentation
+- [NitroStack Docs](https://nitrostack.ai/docs)
+- [Widget Development Guide](https://nitrostack.ai/docs/widgets)
+
+## 💡 Tips
+
+- **Use Test Mode**: Start with `duffel_test_*` tokens for development
+- **Check Rate Limits**: Duffel has rate limits - cache searches when possible
+- **Error Handling**: The template includes comprehensive error handling
+- **Responsive Design**: Widgets are mobile-friendly out of the box
+
+## 📚 Next Steps
+
+- Try the **Starter Template** - Learn NitroStack basics
+- Try the **Pizza Shop Template** - Interactive maps with Mapbox
+- Read the [Duffel Getting Started Guide](https://duffel.com/docs/guides/getting-started)
+
+## License
+
+MIT
+
+---
+
+**Built with ❤️ using NitroStack + Duffel API**
+
+Need help? Check [Duffel Support](https://duffel.com/docs) or [NitroStack Docs](https://nitrostack.ai/docs)

package/templates/typescript-oauth/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "nitrostack-flight-booking",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "NitroStack Flight Booking - Real-time flight search and booking with Duffel API integration",
+  "scripts": {
+    "dev": "nitrostack-cli dev",
+    "build": "nitrostack-cli build",
+    "start": "npm run build && nitrostack-cli start",
+    "start:prod": "nitrostack-cli start",
+    "upgrade": "nitrostack-cli upgrade",
+    "install:all": "nitrostack-cli install",
+    "widget": "npm --prefix src/widgets"
+  },
+  "dependencies": {
+    "nitrostack": "^1",
+    "zod": "^3.22.4",
+    "dotenv": "^16.3.1",
+    "@duffel/api": "^4.21.0",
+    "axios": "^1.7.9",
+    "date-fns": "^4.1.0"
+  },
+  "devDependencies": {
+    "@nitrostack/cli": "^1",
+    "typescript": "^5.3.3"
+  },
+  "author": ""
+}

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

@@ -0,0 +1,92 @@
+import { McpApp, Module, ConfigModule, OAuthModule } from 'nitrostack';
+import { FlightsModule } from './modules/flights/flights.module.js';
+import { SystemHealthCheck } from './health/system.health.js';
+
+/**
+ * Root Application Module
+ * 
+ * This is the main module that bootstraps the MCP server.
+ * It registers all feature modules and health checks.
+ * 
+ * OAuth 2.1 Authentication:
+ * - Configured with Auth0 as the authorization server
+ * - Supports read, write, and admin scopes
+ * - Validates tokens with audience binding (RFC 8707)
+ * 
+ * Flight Booking System:
+ * - Powered by Duffel API
+ * - Professional flight search and booking capabilities
+ * - Comprehensive widgets for search results and flight details
+ */
+@McpApp({
+  module: AppModule,
+  server: {
+    name: 'airline-ticketing-server',
+    version: '1.0.0'
+  },
+  logging: {
+    level: 'info'
+  }
+})
+@Module({
+  name: 'app',
+  description: 'Airline ticketing MCP server with OAuth 2.1 authentication and Duffel integration',
+  imports: [
+    ConfigModule.forRoot(),
+
+    // Enable OAuth 2.1 authentication
+    OAuthModule.forRoot({
+      // 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
+      resourceUri: process.env.RESOURCE_URI || 'https://mcplocal',
+
+      // Authorization Server(s) - The OAuth provider URL(s)
+      // Supports multiple auth servers for federation scenarios
+      authorizationServers: [
+        process.env.AUTH_SERVER_URL || 'https://dev-5dt0utuk31h13tjm.us.auth0.com',
+      ],
+
+      // Supported scopes for this MCP server
+      // Define what permissions your server supports
+      scopesSupported: [
+        'read',        // Read access to resources
+        'write',       // Write/modify resources
+        'admin',       // Administrative operations
+      ],
+
+      // Token Introspection (RFC 7662) - For opaque tokens
+      // If your OAuth provider issues opaque tokens (not JWTs),
+      // you MUST configure introspection to validate them
+      tokenIntrospectionEndpoint: process.env.INTROSPECTION_ENDPOINT,
+      tokenIntrospectionClientId: process.env.INTROSPECTION_CLIENT_ID,
+      tokenIntrospectionClientSecret: process.env.INTROSPECTION_CLIENT_SECRET,
+
+      // Expected audience (defaults to resourceUri if not provided)
+      // MUST match the audience claim in tokens (RFC 8707)
+      audience: process.env.TOKEN_AUDIENCE,
+
+      // Expected issuer (optional but recommended)
+      // If provided, tokens must be from this issuer
+      issuer: process.env.TOKEN_ISSUER,
+
+      // Custom validation (optional)
+      // Add any additional validation logic beyond spec requirements
+      customValidation: async (tokenPayload) => {
+        // Example: Check if user is active in your database
+        // const user = await db.users.findOne({ id: tokenPayload.sub });
+        // return user?.active === true;
+
+        // For now, accept all valid tokens
+        return true;
+      },
+    }),
+
+    FlightsModule
+  ],
+  providers: [
+    // Health Checks
+    SystemHealthCheck,
+  ]
+})
+export class AppModule { }

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

@@ -0,0 +1,126 @@
+import { Guard, ExecutionContext, OAuthModule, OAuthTokenPayload } from 'nitrostack';
+
+/**
+ * OAuth Guard
+ * 
+ * Validates OAuth 2.1 access tokens according to MCP specification.
+ * 
+ * Performs:
+ * - Token validation (introspection or JWT validation)
+ * - Audience binding (RFC 8707) - CRITICAL for security
+ * - Scope validation
+ * - Expiration checking
+ * 
+ * Compatible with:
+ * - OpenAI Apps SDK
+ * - Any RFC-compliant OAuth 2.1 provider
+ * 
+ * Usage:
+ * ```typescript
+ * @Tool({
+ *   name: 'protected_resource',
+ *   description: 'A protected tool'
+ * })
+ * @UseGuards(OAuthGuard)
+ * async protectedTool() {
+ *   // Only accessible with valid OAuth token
+ * }
+ * ```
+ */
+export class OAuthGuard implements Guard {
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    // Extract token from metadata (sent by Studio or OAuth client)
+    const authHeader = context.metadata?.authorization as string;
+    const metaToken = context.metadata?._oauth || context.metadata?.token;
+    
+    let token: string | null = null;
+    
+    // Try Bearer token format first
+    if (authHeader?.startsWith('Bearer ')) {
+      token = authHeader.substring(7);
+    } else if (metaToken) {
+      token = metaToken as string;
+    }
+    
+    if (!token) {
+      throw new Error(
+        'OAuth token required. Please authenticate in Studio (Auth → OAuth 2.1 tab) ' +
+        'or provide token in Authorization header: "Bearer <token>"'
+      );
+    }
+    
+    // Validate token using OAuthModule
+    const result = await OAuthModule.validateToken(token);
+    
+    if (!result.valid) {
+      throw new Error(`OAuth token validation failed: ${result.error}`);
+    }
+    
+    // Extract scopes from token payload
+    const payload = result.payload as OAuthTokenPayload;
+    const scopes = this.extractScopes(payload);
+    
+    // Populate context.auth with OAuth token information
+    context.auth = {
+      subject: payload.sub,
+      scopes: scopes,
+      clientId: payload.client_id,
+      tokenPayload: payload,
+    };
+    
+    return true;
+  }
+  
+  /**
+   * Extract scopes from token payload
+   * Handles both "scope" (space-separated string) and "scopes" (array) formats
+   */
+  private extractScopes(payload: OAuthTokenPayload): string[] {
+    if (payload.scopes && Array.isArray(payload.scopes)) {
+      return payload.scopes;
+    }
+    
+    if (payload.scope && typeof payload.scope === 'string') {
+      return payload.scope.split(' ').filter(s => s.length > 0);
+    }
+    
+    return [];
+  }
+}
+
+/**
+ * Scope Guard
+ * 
+ * Validates that the OAuth token has required scopes.
+ * Use this in addition to OAuthGuard for fine-grained access control.
+ * 
+ * Usage:
+ * ```typescript
+ * @Tool({ name: 'admin_action' })
+ * @UseGuards(OAuthGuard, createScopeGuard(['admin', 'write']))
+ * async adminAction() {
+ *   // Requires OAuth token with 'admin' AND 'write' scopes
+ * }
+ * ```
+ */
+export function createScopeGuard(requiredScopes: string[]): new () => Guard {
+  return class ScopeGuard implements Guard {
+    async canActivate(context: ExecutionContext): Promise<boolean> {
+      const userScopes = context.auth?.scopes || [];
+      
+      const missingScopes = requiredScopes.filter(
+        scope => !userScopes.includes(scope)
+      );
+      
+      if (missingScopes.length > 0) {
+        throw new Error(
+          `Insufficient scope. Required: ${requiredScopes.join(', ')}. ` +
+          `Missing: ${missingScopes.join(', ')}`
+        );
+      }
+      
+      return true;
+    }
+  };
+}
+

package/templates/typescript-oauth/src/health/system.health.ts

@@ -0,0 +1,55 @@
+import { HealthCheck, HealthCheckInterface, HealthCheckResult } from 'nitrostack';
+
+/**
+ * System Health Check
+ * 
+ * Monitors system resources and uptime
+ */
+@HealthCheck({ 
+  name: 'system', 
+  description: 'System resource and uptime check',
+  interval: 30 // Check every 30 seconds
+})
+export class SystemHealthCheck implements HealthCheckInterface {
+  private startTime: number;
+
+  constructor() {
+    this.startTime = Date.now();
+  }
+
+  async check(): Promise<HealthCheckResult> {
+    try {
+      const memoryUsage = process.memoryUsage();
+      const uptime = Date.now() - this.startTime;
+      const uptimeSeconds = Math.floor(uptime / 1000);
+      
+      // Convert memory to MB
+      const memoryUsedMB = Math.round(memoryUsage.heapUsed / 1024 / 1024);
+      const memoryTotalMB = Math.round(memoryUsage.heapTotal / 1024 / 1024);
+      
+      // Consider unhealthy if memory usage is > 90%
+      const memoryPercent = (memoryUsage.heapUsed / memoryUsage.heapTotal) * 100;
+      const isHealthy = memoryPercent < 90;
+      
+      return {
+        status: isHealthy ? 'up' : 'degraded',
+        message: isHealthy 
+          ? 'System is healthy' 
+          : 'High memory usage detected',
+        details: {
+          uptime: `${uptimeSeconds}s`,
+          memory: `${memoryUsedMB}MB / ${memoryTotalMB}MB (${Math.round(memoryPercent)}%)`,
+          pid: process.pid,
+          nodeVersion: process.version,
+        },
+      };
+    } catch (error: any) {
+      return {
+        status: 'down',
+        message: 'System health check failed',
+        details: error.message,
+      };
+    }
+  }
+}
+

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

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Calculator MCP Server with OAuth 2.1 Authentication
+ * 
+ * Main entry point for the MCP server.
+ * Uses the @McpApp decorator pattern for clean, NestJS-style architecture.
+ * 
+ * OAuth 2.1 Compliance:
+ * - MCP Specification: https://modelcontextprotocol.io/specification/draft/basic/authorization
+ * - OpenAI Apps SDK: https://developers.openai.com/apps-sdk/build/auth
+ * - RFC 9728 - Protected Resource Metadata
+ * - RFC 8707 - Resource Indicators (Token Audience Binding)
+ * 
+ * Transport Configuration:
+ * - Development (NODE_ENV=development): STDIO only
+ * - Production (NODE_ENV=production): Dual transport (STDIO + HTTP SSE)
+ * - With OAuth: Dual mode (STDIO + HTTP for metadata endpoints)
+ */
+
+import 'dotenv/config';
+import { McpApplicationFactory } from 'nitrostack';
+import { AppModule } from './app.module.js';
+
+/**
+ * Bootstrap the application
+ */
+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);
+    }
+
+    // Create the MCP application
+    const server = await McpApplicationFactory.create(AppModule);
+
+    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`);
+
+    // Start the server
+    await server.start();
+
+  } catch (error) {
+    console.error('❌ Failed to start server:', error);
+    console.error('\\n💡 Check your OAuth configuration in .env\\n');
+    process.exit(1);
+  }
+}
+
+// Start the application
+bootstrap();