nitrostack 1.0.0 → 1.0.1

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

@@ -0,0 +1,89 @@
+import { McpApp, Module, OAuthModule } from 'nitrostack';
+import { DemoModule } from './modules/demo/demo.module.js';
+
+/**
+ * App Module - Root module for the OAuth 2.1 MCP Server
+ * 
+ * This module demonstrates OAuth 2.1 authentication according to:
+ * - MCP Specification: https://modelcontextprotocol.io/specification/draft/basic/authorization
+ * - OpenAI Apps SDK Requirements: https://developers.openai.com/apps-sdk/build/auth
+ * 
+ * OAuth 2.1 Standards Compliance:
+ * - OAuth 2.1 (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
+ */
+@McpApp({
+  module: AppModule,
+  server: {
+    name: 'OAuth 2.1 MCP Server',
+    version: '1.0.0',
+  },
+  logging: {
+    level: 'info',
+  },
+})
+@Module({
+  name: 'app',
+  description: 'Root application module with OAuth 2.1 authentication',
+  imports: [
+    // 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://mcp.example.com',
+      
+      // Authorization Server(s) - The OAuth provider URL(s)
+      // Supports multiple auth servers for federation scenarios
+      authorizationServers: [
+        process.env.AUTH_SERVER_URL || 'https://auth.example.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 demo, accept all valid tokens
+        return true;
+      },
+    }),
+    
+    // Feature modules
+    DemoModule,
+  ],
+  controllers: [],
+  providers: [],
+})
+export class AppModule {}
+

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

@@ -0,0 +1,127 @@
+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/index.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { McpApplicationFactory } from 'nitrostack';
+import { AppModule } from './app.module.js';
+
+/**
+ * OAuth 2.1 MCP Server
+ * 
+ * Demonstrates OAuth 2.1 authentication for Model Context Protocol servers.
+ * 
+ * Compliant with:
+ * - MCP Specification: https://modelcontextprotocol.io/specification/draft/basic/authorization
+ * - OpenAI Apps SDK: https://developers.openai.com/apps-sdk/build/auth
+ * 
+ * Standards:
+ * - OAuth 2.1 (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:
+ * - Auth0
+ * - Okta
+ * - Keycloak
+ * - Any RFC-compliant OAuth 2.1 provider
+ */
+
+async function bootstrap() {
+  try {
+    console.error('🔐 Starting OAuth 2.1 MCP Server...\n');
+    
+    // Validate required environment variables
+    const requiredEnvVars = ['RESOURCE_URI', 'AUTH_SERVER_URL'];
+    const missing = requiredEnvVars.filter(v => !process.env[v]);
+    
+    if (missing.length > 0) {
+      console.error('❌ Missing required environment variables:');
+      missing.forEach(v => console.error(`   - ${v}`));
+      console.error('\n💡 Copy .env.example to .env and configure your OAuth provider');
+      console.error('   See OAUTH_SETUP.md for provider-specific setup guides\n');
+      process.exit(1);
+    }
+    
+    // Create the MCP application
+    const app = 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 MCP server with HTTP transport (auto-configured by OAuthModule)
+    const transportType = (app as any)._transportType || 'stdio';
+    const transportOptions = (app as any)._transportOptions;
+    
+    await app.start(transportType, transportOptions);
+    
+    console.error('🚀 Server started successfully!');
+    console.error('   Open NitroStack Studio to test OAuth 2.1 flow');
+    console.error('   Configure OAuth in Studio → Auth → OAuth 2.1 tab\n');
+    
+  } catch (error) {
+    console.error('❌ Failed to start server:', error);
+    console.error('\n💡 Check your OAuth configuration in .env');
+    console.error('   See OAUTH_SETUP.md for troubleshooting\n');
+    process.exit(1);
+  }
+}
+
+bootstrap();
+

package/templates/typescript-oauth/src/modules/demo/demo.module.ts

@@ -0,0 +1,16 @@
+import { Module } from 'nitrostack';
+import { DemoTools } from './demo.tools.js';
+
+/**
+ * Demo Module
+ * 
+ * Contains example tools demonstrating OAuth 2.1 authentication
+ */
+@Module({
+  name: 'demo',
+  description: 'Demo module with OAuth 2.1 authentication examples',
+  controllers: [DemoTools],
+})
+export class DemoModule {}
+
+

package/templates/typescript-oauth/src/modules/demo/demo.tools.ts

@@ -0,0 +1,190 @@
+import { Injectable, ToolDecorator as Tool, UseGuards, z, ExecutionContext } from 'nitrostack';
+import { OAuthGuard, createScopeGuard } from '../../guards/oauth.guard.js';
+
+/**
+ * Demo Tools Module
+ * 
+ * Demonstrates OAuth 2.1 authentication with:
+ * 1. Public tools (no authentication)
+ * 2. Protected tools (OAuth token required)
+ * 3. Scoped tools (specific permissions required)
+ */
+
+@Injectable()
+export class DemoTools {
+  
+  /**
+   * PUBLIC TOOL - No authentication required
+   * Anyone can call this tool without OAuth
+   */
+  @Tool({
+    name: 'get_server_info',
+    description: 'Get public server information (no authentication required)',
+    inputSchema: z.object({}),
+  })
+  async getServerInfo() {
+    return {
+      name: 'OAuth 2.1 MCP Server',
+      version: '1.0.0',
+      description: 'Demonstrates OAuth 2.1 authentication for MCP',
+      authentication: {
+        type: 'OAuth 2.1',
+        compliant: [
+          'OAuth 2.1 (draft-ietf-oauth-v2-1-13)',
+          'RFC 9728 - Protected Resource Metadata',
+          'RFC 8707 - Resource Indicators (Token Audience Binding)',
+          'RFC 7636 - PKCE',
+        ],
+        compatibleWith: ['OpenAI Apps SDK', 'Any RFC-compliant OAuth provider'],
+      },
+      availableTools: {
+        public: ['get_server_info'],
+        protected: ['get_user_profile', 'list_resources', 'create_resource'],
+      },
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * PROTECTED TOOL - OAuth token required
+   * Basic authentication, no specific scopes needed
+   */
+  @Tool({
+    name: 'get_user_profile',
+    description: 'Get authenticated user profile (requires OAuth token)',
+    inputSchema: z.object({}),
+  })
+  @UseGuards(OAuthGuard)
+  async getUserProfile(args: {}, context?: ExecutionContext) {
+    const userId = context?.auth?.subject;
+    const scopes = context?.auth?.scopes || [];
+    const clientId = context?.auth?.clientId;
+    
+    return {
+      message: 'User profile retrieved successfully',
+      user: {
+        id: userId,
+        authenticatedVia: 'OAuth 2.1',
+        scopes: scopes,
+        clientId: clientId,
+      },
+      timestamp: new Date().toISOString(),
+      note: 'This is a demo. In production, you would fetch real user data from your database.',
+    };
+  }
+
+  /**
+   * SCOPED TOOL - Requires 'read' scope
+   * Demonstrates fine-grained access control
+   */
+  @Tool({
+    name: 'list_resources',
+    description: 'List available resources (requires OAuth token with "read" scope)',
+    inputSchema: z.object({
+      category: z.enum(['documents', 'images', 'videos', 'all']).default('all').describe('Resource category'),
+      limit: z.number().min(1).max(100).default(10).describe('Maximum number of resources to return'),
+    }),
+  })
+  @UseGuards(OAuthGuard, createScopeGuard(['read']))
+  async listResources(
+    args: { category: string; limit: number },
+    context?: ExecutionContext
+  ) {
+    const userId = context?.auth?.subject;
+    
+    // Generate demo resources
+    const resources = Array.from({ length: args.limit }, (_, i) => ({
+      id: `resource_${i + 1}`,
+      name: `${args.category === 'all' ? 'Sample' : args.category} Resource ${i + 1}`,
+      type: args.category === 'all' ? ['document', 'image', 'video'][i % 3] : args.category,
+      owner: userId,
+      createdAt: new Date(Date.now() - Math.random() * 30 * 24 * 60 * 60 * 1000).toISOString(),
+    }));
+    
+    return {
+      message: 'Resources listed successfully',
+      category: args.category,
+      count: resources.length,
+      resources: resources,
+      requiredScope: 'read',
+      authenticatedUser: userId,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * SCOPED TOOL - Requires 'write' scope
+   * Demonstrates write operations with OAuth
+   */
+  @Tool({
+    name: 'create_resource',
+    description: 'Create a new resource (requires OAuth token with "write" scope)',
+    inputSchema: z.object({
+      name: z.string().describe('Resource name'),
+      type: z.enum(['document', 'image', 'video']).describe('Resource type'),
+      content: z.string().optional().describe('Resource content or description'),
+    }),
+  })
+  @UseGuards(OAuthGuard, createScopeGuard(['write']))
+  async createResource(
+    args: { name: string; type: string; content?: string },
+    context?: ExecutionContext
+  ) {
+    const userId = context?.auth?.subject;
+    const resourceId = `resource_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+    
+    return {
+      message: 'Resource created successfully',
+      resource: {
+        id: resourceId,
+        name: args.name,
+        type: args.type,
+        content: args.content || 'No content provided',
+        owner: userId,
+        createdAt: new Date().toISOString(),
+      },
+      requiredScope: 'write',
+      authenticatedUser: userId,
+      note: 'This is a demo. In production, this would persist to your database.',
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * MULTI-SCOPE TOOL - Requires both 'read' and 'admin' scopes
+   * Demonstrates multiple scope requirements
+   */
+  @Tool({
+    name: 'admin_statistics',
+    description: 'Get administrative statistics (requires OAuth token with "read" and "admin" scopes)',
+    inputSchema: z.object({
+      timeRange: z.enum(['24h', '7d', '30d', '90d']).default('7d').describe('Time range for statistics'),
+    }),
+  })
+  @UseGuards(OAuthGuard, createScopeGuard(['read', 'admin']))
+  async getAdminStatistics(
+    args: { timeRange: string },
+    context?: ExecutionContext
+  ) {
+    const userId = context?.auth?.subject;
+    const scopes = context?.auth?.scopes || [];
+    
+    return {
+      message: 'Admin statistics retrieved successfully',
+      timeRange: args.timeRange,
+      statistics: {
+        totalUsers: Math.floor(Math.random() * 10000),
+        totalResources: Math.floor(Math.random() * 50000),
+        apiCalls: Math.floor(Math.random() * 1000000),
+        activeTokens: Math.floor(Math.random() * 5000),
+      },
+      requiredScopes: ['read', 'admin'],
+      authenticatedUser: userId,
+      userScopes: scopes,
+      timestamp: new Date().toISOString(),
+      note: 'This tool requires elevated permissions. Only users with admin scope can access this data.',
+    };
+  }
+}
+
+

package/templates/typescript-oauth/src/widgets/app/calculator-operations/page.tsx

@@ -0,0 +1,133 @@
+'use client';
+
+import { withToolData } from 'nitrostack/widgets';
+
+/**
+ * Widget Metadata (stored in widget-manifest.json)
+ * 
+ * This widget lists all available calculator operations.
+ * 
+ * Example includes all four operations: add, subtract, multiply, divide
+ * 
+ * Frontend developers: Edit widget-manifest.json to update examples
+ */
+
+interface Operation {
+  name: string;
+  symbol: string;
+  description: string;
+  example: string;
+}
+
+interface OperationsData {
+  operations: Operation[];
+}
+
+function CalculatorOperations({ data }: { data: OperationsData }) {
+  const getOperationColor = (name: string) => {
+    const colors: Record<string, string> = {
+      add: '#10b981',
+      subtract: '#f59e0b',
+      multiply: '#3b82f6',
+      divide: '#8b5cf6'
+    };
+    return colors[name] || '#6b7280';
+  };
+
+  return (
+    <div style={{
+      padding: '24px',
+      background: 'linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%)',
+      borderRadius: '16px',
+      maxWidth: '500px'
+    }}>
+      <h3 style={{
+        margin: '0 0 20px 0',
+        fontSize: '24px',
+        color: '#1f2937',
+        display: 'flex',
+        alignItems: 'center',
+        gap: '12px'
+      }}>
+        <span style={{ fontSize: '32px' }}>🔢</span>
+        Calculator Operations
+      </h3>
+
+      <div style={{ display: 'grid', gap: '12px' }}>
+        {data.operations.map((op) => (
+          <div
+            key={op.name}
+            style={{
+              background: 'white',
+              borderRadius: '12px',
+              padding: '16px',
+              boxShadow: '0 2px 8px rgba(0,0,0,0.1)',
+              borderLeft: `4px solid ${getOperationColor(op.name)}`
+            }}
+          >
+            <div style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: '12px',
+              marginBottom: '8px'
+            }}>
+              <div style={{
+                width: '40px',
+                height: '40px',
+                borderRadius: '10px',
+                background: getOperationColor(op.name),
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                color: 'white',
+                fontSize: '24px',
+                fontWeight: 'bold'
+              }}>
+                {op.symbol}
+              </div>
+              <div>
+                <div style={{
+                  fontSize: '16px',
+                  fontWeight: 'bold',
+                  color: '#1f2937',
+                  textTransform: 'capitalize'
+                }}>
+                  {op.name}
+                </div>
+                <div style={{
+                  fontSize: '14px',
+                  color: '#6b7280'
+                }}>
+                  {op.description}
+                </div>
+              </div>
+            </div>
+            <div style={{
+              marginTop: '12px',
+              padding: '8px 12px',
+              background: '#f9fafb',
+              borderRadius: '8px',
+              fontFamily: 'monospace',
+              fontSize: '14px',
+              color: '#374151'
+            }}>
+              {op.example}
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <div style={{
+        marginTop: '16px',
+        textAlign: 'center',
+        fontSize: '12px',
+        color: '#6b7280'
+      }}>
+        ✨ Use the 'calculate' tool to perform these operations
+      </div>
+    </div>
+  );
+}
+
+export default withToolData(CalculatorOperations);
+