nitrostack 1.0.0 → 1.0.2

package/templates/typescript-auth-api-key/src/guards/multi-auth.guard.ts

@@ -0,0 +1,157 @@
+import { Guard, ExecutionContext, ApiKeyModule } from 'nitrostack';
+
+/**
+ * Multi-Auth Guard
+ * 
+ * Accepts EITHER JWT token OR API key authentication.
+ * This demonstrates how to support multiple authentication methods in a single tool.
+ * 
+ * Use Cases:
+ * - Tools that can be accessed by users (JWT) or services (API key)
+ * - Migration from one auth method to another
+ * - Supporting legacy clients
+ * 
+ * Usage:
+ * ```typescript
+ * @Tool({
+ *   name: 'flexible_auth_tool',
+ *   description: 'Works with JWT or API key'
+ * })
+ * @UseGuards(MultiAuthGuard)
+ * async flexibleTool() {
+ *   // Accessible with EITHER JWT OR API key
+ * }
+ * ```
+ */
+export class MultiAuthGuard implements Guard {
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    let authenticated = false;
+    let authMethod = 'none';
+    
+    // Try JWT authentication first
+    const jwtToken = context.metadata?._jwt;
+    const authHeader = context.metadata?.authorization;
+    
+    if (jwtToken || authHeader) {
+      // For this demo, we accept any JWT token
+      // In production, you'd validate it with JWTModule
+      const token = jwtToken || authHeader?.toString().replace('Bearer ', '');
+      if (token) {
+        context.auth = {
+          subject: 'jwt_user',
+          scopes: ['read', 'write'],
+        };
+        authenticated = true;
+        authMethod = 'JWT';
+      }
+    }
+    
+    // If JWT didn't work, try API key
+    if (!authenticated) {
+      const apiKey = context.metadata?.apiKey || context.metadata?.['x-api-key'];
+      
+      if (apiKey) {
+        const isValid = await ApiKeyModule.validate(apiKey as string);
+        
+        if (isValid) {
+          context.auth = {
+            subject: `apikey_${(apiKey as string).substring(0, 12)}`,
+            scopes: ['*'],
+          };
+          authenticated = true;
+          authMethod = 'API Key';
+        }
+      }
+    }
+    
+    if (!authenticated) {
+      throw new Error(
+        'Authentication required. Please provide either:\n' +
+        '  1. JWT token (in Studio: Auth → JWT Token)\n' +
+        '  2. API key (in Studio: Auth → API Key)'
+      );
+    }
+    
+    // Store auth method in context for debugging/logging
+    if (!context.metadata) {
+      (context as any).metadata = {};
+    }
+    (context.metadata as any)._authMethod = authMethod;
+    
+    return true;
+  }
+}
+
+/**
+ * Dual-Auth Guard
+ * 
+ * Requires BOTH JWT token AND API key authentication.
+ * This is for highly sensitive operations that need multiple authentication factors.
+ * 
+ * Use Cases:
+ * - Financial transactions
+ * - Account deletion
+ * - Admin operations
+ * - Critical data access
+ * 
+ * Usage:
+ * ```typescript
+ * @Tool({
+ *   name: 'critical_operation',
+ *   description: 'Requires both JWT and API key'
+ * })
+ * @UseGuards(DualAuthGuard)
+ * async criticalOperation() {
+ *   // Only accessible with BOTH JWT AND API key
+ * }
+ * ```
+ */
+export class DualAuthGuard implements Guard {
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const errors: string[] = [];
+    
+    // Check JWT token
+    const jwtToken = context.metadata?._jwt;
+    const authHeader = context.metadata?.authorization;
+    const hasJWT = !!(jwtToken || authHeader);
+    
+    if (!hasJWT) {
+      errors.push('JWT token is required (set in Studio: Auth → JWT Token)');
+    }
+    
+    // Check API key
+    const apiKey = context.metadata?.apiKey || context.metadata?.['x-api-key'];
+    
+    if (!apiKey) {
+      errors.push('API key is required (set in Studio: Auth → API Key)');
+    } else {
+      const isValidKey = await ApiKeyModule.validate(apiKey as string);
+      if (!isValidKey) {
+        errors.push('Invalid API key');
+      }
+    }
+    
+    if (errors.length > 0) {
+      throw new Error(
+        'Dual authentication required:\n' +
+        errors.map(e => `  - ${e}`).join('\n')
+      );
+    }
+    
+    // Both auth methods present and valid
+    context.auth = {
+      subject: 'dual_auth_user',
+      scopes: ['*'], // Full access with dual auth
+    };
+    
+    // Store auth info
+    if (!context.metadata) {
+      (context as any).metadata = {};
+    }
+    (context.metadata as any)._authMethod = 'JWT + API Key';
+    
+    return true;
+  }
+}
+
+

package/templates/typescript-auth-api-key/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-auth-api-key/src/index.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { McpApplicationFactory } from 'nitrostack';
+import { AppModule } from './app.module.js';
+
+/**
+ * API Key Authentication MCP Server
+ * 
+ * This template demonstrates how to build an MCP server with API key authentication.
+ * 
+ * Features:
+ * - Public tools (no authentication)
+ * - Protected tools (API key required)
+ * - Easy integration with NitroStack Studio
+ * - Environment-based key management
+ * 
+ * Test API Keys (provided in .env):
+ * - sk_test_public_demo_key_12345
+ * - sk_test_admin_demo_key_67890
+ */
+
+async function bootstrap() {
+  try {
+    console.error('🔑 Starting API Key Auth MCP Server...\n');
+    
+    // Create the MCP application
+    const app = await McpApplicationFactory.create(AppModule);
+    
+    console.error('✅ API Key Module configured');
+    console.error('   - Keys loaded from environment variables (API_KEY_*)');
+    console.error('   - Protected tools require valid API key');
+    console.error('   - Public tools accessible without authentication\n');
+
+    // Start the MCP server
+    await app.start();
+    
+    console.error('🚀 Server started successfully!');
+    console.error('   Open NitroStack Studio to test the server');
+    console.error('   Set your API key in Studio → Auth → API Key section\n');
+    
+  } catch (error) {
+    console.error('❌ Failed to start server:', error);
+    process.exit(1);
+  }
+}
+
+bootstrap();
+

package/templates/typescript-auth-api-key/src/modules/calculator/calculator.module.ts

@@ -0,0 +1,12 @@
+import { Module } from 'nitrostack';
+import { CalculatorTools } from './calculator.tools.js';
+import { CalculatorResources } from './calculator.resources.js';
+import { CalculatorPrompts } from './calculator.prompts.js';
+
+@Module({
+  name: 'calculator',
+  description: 'Basic arithmetic calculator',
+  controllers: [CalculatorTools, CalculatorResources, CalculatorPrompts]
+})
+export class CalculatorModule {}
+

package/templates/typescript-auth-api-key/src/modules/calculator/calculator.prompts.ts

@@ -0,0 +1,73 @@
+import { PromptDecorator as Prompt, ExecutionContext } from 'nitrostack';
+
+export class CalculatorPrompts {
+  @Prompt({
+    name: 'calculator_help',
+    description: 'Get help with calculator operations',
+    arguments: [
+      {
+        name: 'operation',
+        description: 'The operation to get help with (optional)',
+        required: false
+      }
+    ]
+  })
+  async getHelp(args: any, ctx: ExecutionContext) {
+    ctx.logger.info('Generating calculator help prompt');
+
+    const operation = args.operation;
+
+    if (operation) {
+      // Help for specific operation
+      const helpText = this.getOperationHelp(operation);
+      return [
+        {
+          role: 'user' as const,
+          content: `How do I use the ${operation} operation in the calculator?`
+        },
+        {
+          role: 'assistant' as const,
+          content: helpText
+        }
+      ];
+    }
+
+    // General help
+    return [
+      {
+        role: 'user' as const,
+        content: 'How do I use the calculator?'
+      },
+      {
+        role: 'assistant' as const,
+        content: `The calculator supports four basic operations:
+
+1. **Addition** - Add two numbers together
+   Example: calculate(operation="add", a=5, b=3) = 8
+
+2. **Subtraction** - Subtract one number from another
+   Example: calculate(operation="subtract", a=10, b=4) = 6
+
+3. **Multiplication** - Multiply two numbers
+   Example: calculate(operation="multiply", a=6, b=7) = 42
+
+4. **Division** - Divide one number by another
+   Example: calculate(operation="divide", a=20, b=5) = 4
+
+Just call the 'calculate' tool with the operation and two numbers!`
+      }
+    ];
+  }
+
+  private getOperationHelp(operation: string): string {
+    const helps: Record<string, string> = {
+      add: 'Use addition to sum two numbers. Call calculate(operation="add", a=5, b=3) to get 8.',
+      subtract: 'Use subtraction to find the difference. Call calculate(operation="subtract", a=10, b=4) to get 6.',
+      multiply: 'Use multiplication to find the product. Call calculate(operation="multiply", a=6, b=7) to get 42.',
+      divide: 'Use division to find the quotient. Call calculate(operation="divide", a=20, b=5) to get 4. Note: Cannot divide by zero!'
+    };
+
+    return helps[operation] || 'Unknown operation. Available operations: add, subtract, multiply, divide.';
+  }
+}
+

package/templates/typescript-auth-api-key/src/modules/calculator/calculator.resources.ts

@@ -0,0 +1,60 @@
+import { ResourceDecorator as Resource, Widget, ExecutionContext } from 'nitrostack';
+
+export class CalculatorResources {
+  @Resource({
+    uri: 'calculator://operations',
+    name: 'Calculator Operations',
+    description: 'List of available calculator operations',
+    mimeType: 'application/json',
+    examples: {
+      response: {
+        operations: [
+          { name: 'add', symbol: '+', description: 'Addition' },
+          { name: 'subtract', symbol: '-', description: 'Subtraction' },
+          { name: 'multiply', symbol: '×', description: 'Multiplication' },
+          { name: 'divide', symbol: '÷', description: 'Division' }
+        ]
+      }
+    }
+  })
+  @Widget('calculator-operations')
+  async getOperations(uri: string, ctx: ExecutionContext) {
+    ctx.logger.info('Fetching calculator operations');
+
+    const operations = [
+      {
+        name: 'add',
+        symbol: '+',
+        description: 'Addition',
+        example: '5 + 3 = 8'
+      },
+      {
+        name: 'subtract',
+        symbol: '-',
+        description: 'Subtraction',
+        example: '10 - 4 = 6'
+      },
+      {
+        name: 'multiply',
+        symbol: '×',
+        description: 'Multiplication',
+        example: '6 × 7 = 42'
+      },
+      {
+        name: 'divide',
+        symbol: '÷',
+        description: 'Division',
+        example: '20 ÷ 5 = 4'
+      }
+    ];
+
+    return {
+      contents: [{
+        uri,
+        mimeType: 'application/json',
+        text: JSON.stringify({ operations }, null, 2)
+      }]
+    };
+  }
+}
+

package/templates/typescript-auth-api-key/src/modules/calculator/calculator.tools.ts

@@ -0,0 +1,71 @@
+import { ToolDecorator as Tool, Widget, ExecutionContext, z } from 'nitrostack';
+
+export class CalculatorTools {
+  @Tool({
+    name: 'calculate',
+    description: 'Perform basic arithmetic calculations',
+    inputSchema: z.object({
+      operation: z.enum(['add', 'subtract', 'multiply', 'divide']).describe('The operation to perform'),
+      a: z.number().describe('First number'),
+      b: z.number().describe('Second number')
+    }),
+    examples: {
+      request: {
+        operation: 'add',
+        a: 5,
+        b: 3
+      },
+      response: {
+        operation: 'add',
+        a: 5,
+        b: 3,
+        result: 8,
+        expression: '5 + 3 = 8'
+      }
+    }
+  })
+  @Widget('calculator-result')
+  async calculate(input: any, ctx: ExecutionContext) {
+    ctx.logger.info('Performing calculation', { 
+      operation: input.operation, 
+      a: input.a, 
+      b: input.b 
+    });
+
+    let result: number;
+    let symbol: string;
+
+    switch (input.operation) {
+      case 'add':
+        result = input.a + input.b;
+        symbol = '+';
+        break;
+      case 'subtract':
+        result = input.a - input.b;
+        symbol = '-';
+        break;
+      case 'multiply':
+        result = input.a * input.b;
+        symbol = '×';
+        break;
+      case 'divide':
+        if (input.b === 0) {
+          throw new Error('Cannot divide by zero');
+        }
+        result = input.a / input.b;
+        symbol = '÷';
+        break;
+      default:
+        throw new Error('Invalid operation');
+    }
+
+    return {
+      operation: input.operation,
+      a: input.a,
+      b: input.b,
+      result,
+      expression: `${input.a} ${symbol} ${input.b} = ${result}`
+    };
+  }
+}
+

package/templates/typescript-auth-api-key/src/modules/demo/demo.module.ts

@@ -0,0 +1,18 @@
+import { Module } from 'nitrostack';
+import { DemoTools } from './demo.tools.js';
+import { MultiAuthTools } from './multi-auth.tools.js';
+
+/**
+ * Demo Module
+ * 
+ * Contains example tools demonstrating:
+ * - API key authentication
+ * - Multi-auth patterns (JWT + API Key)
+ */
+@Module({
+  name: 'demo',
+  description: 'Demo module with API key authentication examples',
+  controllers: [DemoTools, MultiAuthTools],
+})
+export class DemoModule {}
+

package/templates/typescript-auth-api-key/src/modules/demo/demo.tools.ts

@@ -0,0 +1,155 @@
+import { Injectable, ToolDecorator as Tool, UseGuards, z, ExecutionContext } from 'nitrostack';
+import { ApiKeyGuard } from '../../guards/apikey.guard.js';
+
+/**
+ * Demo Tools Module
+ * 
+ * Demonstrates:
+ * 1. Public tools (no authentication required)
+ * 2. Protected tools (API key required)
+ * 3. Multi-auth scenarios
+ */
+
+@Injectable()
+export class DemoTools {
+  
+  /**
+   * PUBLIC TOOL - No authentication required
+   * Anyone can call this tool without an API key
+   */
+  @Tool({
+    name: 'get_public_info',
+    description: 'Get public information (no authentication required)',
+    inputSchema: z.object({
+      topic: z.string().describe('The topic to get information about'),
+    }),
+  })
+  async getPublicInfo(args: { topic: string }) {
+    return {
+      message: `Public information about ${args.topic}`,
+      data: {
+        topic: args.topic,
+        info: 'This is public information that anyone can access without authentication.',
+        timestamp: new Date().toISOString(),
+        authRequired: false,
+      },
+    };
+  }
+
+  /**
+   * PROTECTED TOOL - API key required
+   * Only accessible with a valid API key
+   */
+  @Tool({
+    name: 'get_protected_data',
+    description: 'Get protected data (requires API key authentication)',
+    inputSchema: z.object({
+      dataType: z.enum(['user', 'account', 'settings']).describe('Type of protected data to retrieve'),
+    }),
+  })
+  @UseGuards(ApiKeyGuard)
+  async getProtectedData(args: { dataType: string }, context?: ExecutionContext) {
+    // Access auth information populated by the guard
+    const apiKeySubject = context?.auth?.subject || 'unknown';
+    
+    return {
+      message: `Protected ${args.dataType} data accessed successfully`,
+      data: {
+        dataType: args.dataType,
+        accessedBy: apiKeySubject,
+        timestamp: new Date().toISOString(),
+        protectedInfo: `This is sensitive ${args.dataType} data that requires API key authentication.`,
+        // In real apps, you'd fetch actual data from a database
+        sampleData: {
+          user: { id: 1, name: 'John Doe', role: 'admin' },
+          account: { id: 'acc_123', balance: 1000, currency: 'USD' },
+          settings: { theme: 'dark', notifications: true, language: 'en' },
+        }[args.dataType],
+      },
+    };
+  }
+
+  /**
+   * PROTECTED TOOL - API key required
+   * Performs an action that requires authentication
+   */
+  @Tool({
+    name: 'perform_protected_action',
+    description: 'Perform a protected action (requires API key authentication)',
+    inputSchema: z.object({
+      action: z.enum(['create', 'update', 'delete']).describe('The action to perform'),
+      resourceType: z.string().describe('Type of resource (e.g., "user", "post", "file")'),
+      resourceId: z.string().optional().describe('Resource ID (for update/delete)'),
+    }),
+  })
+  @UseGuards(ApiKeyGuard)
+  async performProtectedAction(
+    args: { action: string; resourceType: string; resourceId?: string },
+    context?: ExecutionContext
+  ) {
+    const apiKeySubject = context?.auth?.subject || 'unknown';
+    
+    let result;
+    switch (args.action) {
+      case 'create':
+        result = {
+          status: 'success',
+          message: `Created new ${args.resourceType}`,
+          resourceId: `${args.resourceType}_${Date.now()}`,
+        };
+        break;
+      case 'update':
+        result = {
+          status: 'success',
+          message: `Updated ${args.resourceType} ${args.resourceId}`,
+          resourceId: args.resourceId,
+        };
+        break;
+      case 'delete':
+        result = {
+          status: 'success',
+          message: `Deleted ${args.resourceType} ${args.resourceId}`,
+          resourceId: args.resourceId,
+        };
+        break;
+      default:
+        result = { status: 'error', message: 'Invalid action' };
+    }
+    
+    return {
+      message: `Action performed by ${apiKeySubject}`,
+      action: args.action,
+      resourceType: args.resourceType,
+      timestamp: new Date().toISOString(),
+      result,
+    };
+  }
+
+  /**
+   * UTILITY TOOL - Check API key status
+   * Helps developers test their API key configuration
+   */
+  @Tool({
+    name: 'check_api_key_status',
+    description: 'Check if your API key is valid and working (requires API key)',
+    inputSchema: z.object({}),
+  })
+  @UseGuards(ApiKeyGuard)
+  async checkApiKeyStatus(args: {}, context?: ExecutionContext) {
+    const apiKeySubject = context?.auth?.subject || 'unknown';
+    const scopes = context?.auth?.scopes || [];
+    
+    return {
+      message: 'API key is valid and working! ✓',
+      status: 'authenticated',
+      apiKeyInfo: {
+        subject: apiKeySubject,
+        scopes: scopes,
+        hasFullAccess: scopes.includes('*'),
+      },
+      timestamp: new Date().toISOString(),
+      hint: 'Your API key is properly configured in the Studio Auth tab.',
+    };
+  }
+}
+