nitrostack 1.0.0 → 1.0.2

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

@@ -0,0 +1,123 @@
+import { Injectable, ToolDecorator as Tool, UseGuards, z, ExecutionContext } from 'nitrostack';
+import { MultiAuthGuard, DualAuthGuard } from '../../guards/multi-auth.guard.js';
+
+/**
+ * Multi-Auth Demo Tools
+ * 
+ * Demonstrates advanced authentication patterns:
+ * 1. Tools that accept EITHER JWT OR API key
+ * 2. Tools that require BOTH JWT AND API key
+ */
+
+@Injectable()
+export class MultiAuthTools {
+  
+  /**
+   * FLEXIBLE AUTH - Accepts JWT OR API key
+   * Users can authenticate with either method
+   */
+  @Tool({
+    name: 'get_flexible_data',
+    description: 'Get data using JWT token OR API key (either works)',
+    inputSchema: z.object({
+      query: z.string().describe('Search query'),
+    }),
+  })
+  @UseGuards(MultiAuthGuard)
+  async getFlexibleData(args: { query: string }, context?: ExecutionContext) {
+    const authMethod = (context?.metadata as any)?._authMethod || 'unknown';
+    const subject = context?.auth?.subject || 'unknown';
+    
+    return {
+      message: `Data retrieved successfully using ${authMethod}`,
+      authInfo: {
+        method: authMethod,
+        subject: subject,
+        flexibleAuth: true,
+      },
+      query: args.query,
+      results: [
+        { id: 1, title: 'Result 1', data: 'Sample data 1' },
+        { id: 2, title: 'Result 2', data: 'Sample data 2' },
+        { id: 3, title: 'Result 3', data: 'Sample data 3' },
+      ],
+      hint: 'This tool accepts either JWT token or API key. Try it with different auth methods!',
+    };
+  }
+
+  /**
+   * DUAL AUTH - Requires BOTH JWT AND API key
+   * For highly sensitive operations
+   */
+  @Tool({
+    name: 'perform_critical_action',
+    description: 'Perform critical action (requires BOTH JWT token AND API key)',
+    inputSchema: z.object({
+      actionType: z.enum(['delete_account', 'transfer_funds', 'change_permissions']).describe('Type of critical action'),
+      confirmation: z.boolean().describe('Confirmation (must be true)'),
+    }),
+  })
+  @UseGuards(DualAuthGuard)
+  async performCriticalAction(
+    args: { actionType: string; confirmation: boolean },
+    context?: ExecutionContext
+  ) {
+    if (!args.confirmation) {
+      throw new Error('Confirmation required for critical actions');
+    }
+    
+    const subject = context?.auth?.subject || 'unknown';
+    
+    return {
+      message: `Critical action "${args.actionType}" executed successfully`,
+      security: {
+        authMethod: 'JWT + API Key (Dual Authentication)',
+        subject: subject,
+        verified: true,
+        timestamp: new Date().toISOString(),
+      },
+      action: {
+        type: args.actionType,
+        status: 'completed',
+        confirmed: args.confirmation,
+      },
+      warning: '⚠️ This action required dual authentication for security',
+    };
+  }
+
+  /**
+   * AUTH INFO - Check which auth methods are active
+   * Uses flexible auth to demonstrate detection
+   */
+  @Tool({
+    name: 'check_auth_methods',
+    description: 'Check which authentication methods are currently active',
+    inputSchema: z.object({}),
+  })
+  @UseGuards(MultiAuthGuard)
+  async checkAuthMethods(args: {}, context?: ExecutionContext) {
+    const hasJWT = !!(context?.metadata?._jwt || context?.metadata?.authorization);
+    const hasAPIKey = !!(context?.metadata?.apiKey || context?.metadata?.['x-api-key']);
+    const authMethod = (context?.metadata as any)?._authMethod || 'unknown';
+    
+    return {
+      message: 'Authentication methods detected',
+      activeAuth: {
+        method: authMethod,
+        jwt: hasJWT,
+        apiKey: hasAPIKey,
+        both: hasJWT && hasAPIKey,
+      },
+      subject: context?.auth?.subject || 'unknown',
+      scopes: context?.auth?.scopes || [],
+      recommendations: {
+        jwtOnly: hasJWT && !hasAPIKey ? '✓ Using JWT authentication' : null,
+        apiKeyOnly: !hasJWT && hasAPIKey ? '✓ Using API key authentication' : null,
+        both: hasJWT && hasAPIKey ? '✓ Using dual authentication (most secure!)' : null,
+        none: !hasJWT && !hasAPIKey ? '⚠️ No authentication detected (this should not happen)' : null,
+      },
+      hint: 'Set JWT token and/or API key in Studio Auth tab to see different combinations',
+    };
+  }
+}
+

package/templates/typescript-auth-api-key/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);
+

package/templates/typescript-auth-api-key/src/widgets/app/calculator-result/page.tsx

@@ -0,0 +1,134 @@
+'use client';
+
+import { withToolData } from 'nitrostack/widgets';
+
+/**
+ * Widget Metadata (stored in widget-manifest.json)
+ * 
+ * This widget displays calculation results with operation details.
+ * 
+ * Examples defined in manifest:
+ * - Addition: 5 + 3 = 8
+ * - Multiplication: 6 × 7 = 42
+ * - Division: 20 ÷ 4 = 5
+ * 
+ * Frontend developers: Edit widget-manifest.json to update examples
+ */
+
+interface CalculatorData {
+  operation: string;
+  a: number;
+  b: number;
+  result: number;
+  expression: string;
+}
+
+function CalculatorResult({ data }: { data: CalculatorData }) {
+  const getOperationColor = (op: string) => {
+    const colors: Record<string, string> = {
+      add: '#10b981',
+      subtract: '#f59e0b',
+      multiply: '#3b82f6',
+      divide: '#8b5cf6'
+    };
+    return colors[op] || '#6b7280';
+  };
+
+  const getOperationIcon = (op: string) => {
+    const icons: Record<string, string> = {
+      add: '➕',
+      subtract: '➖',
+      multiply: '✖️',
+      divide: '➗'
+    };
+    return icons[op] || '🔢';
+  };
+
+  const color = getOperationColor(data.operation);
+
+  return (
+    <div style={{
+      padding: '24px',
+      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+      borderRadius: '16px',
+      color: 'white',
+      maxWidth: '400px',
+      boxShadow: '0 10px 30px rgba(0,0,0,0.2)'
+    }}>
+      <div style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: '12px',
+        marginBottom: '20px'
+      }}>
+        <span style={{ fontSize: '32px' }}>
+          {getOperationIcon(data.operation)}
+        </span>
+        <div>
+          <h3 style={{ margin: 0, fontSize: '18px', opacity: 0.9 }}>
+            Calculator Result
+          </h3>
+          <p style={{ margin: '4px 0 0 0', fontSize: '14px', opacity: 0.7 }}>
+            {data.operation.charAt(0).toUpperCase() + data.operation.slice(1)}
+          </p>
+        </div>
+      </div>
+
+      <div style={{
+        background: 'rgba(255, 255, 255, 0.15)',
+        borderRadius: '12px',
+        padding: '20px',
+        backdropFilter: 'blur(10px)',
+        marginBottom: '16px'
+      }}>
+        <div style={{
+          fontSize: '28px',
+          fontWeight: 'bold',
+          textAlign: 'center',
+          marginBottom: '12px',
+          fontFamily: 'monospace'
+        }}>
+          {data.expression}
+        </div>
+        
+        <div style={{
+          display: 'flex',
+          justifyContent: 'space-around',
+          fontSize: '14px',
+          opacity: 0.9,
+          marginTop: '16px'
+        }}>
+          <div style={{ textAlign: 'center' }}>
+            <div style={{ fontSize: '12px', opacity: 0.7 }}>First</div>
+            <div style={{ fontWeight: 'bold', fontSize: '20px' }}>{data.a}</div>
+          </div>
+          <div style={{ textAlign: 'center' }}>
+            <div style={{ fontSize: '12px', opacity: 0.7 }}>Second</div>
+            <div style={{ fontWeight: 'bold', fontSize: '20px' }}>{data.b}</div>
+          </div>
+          <div style={{ textAlign: 'center' }}>
+            <div style={{ fontSize: '12px', opacity: 0.7 }}>Result</div>
+            <div style={{ 
+              fontWeight: 'bold', 
+              fontSize: '24px',
+              color: '#fbbf24'
+            }}>
+              {data.result}
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div style={{
+        fontSize: '12px',
+        textAlign: 'center',
+        opacity: 0.7
+      }}>
+        ✨ NitroStack Calculator
+      </div>
+    </div>
+  );
+}
+
+export default withToolData(CalculatorResult);
+

package/templates/typescript-auth-api-key/src/widgets/app/layout.tsx

@@ -0,0 +1,14 @@
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body style={{ margin: 0, padding: 0, fontFamily: 'system-ui, sans-serif' }}>
+        {children}
+      </body>
+    </html>
+  );
+}
+

package/templates/typescript-auth-api-key/src/widgets/next.config.js

@@ -0,0 +1,37 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  transpilePackages: ['nitrostack'],
+  
+  // Development optimizations to prevent cache corruption
+  ...(process.env.NODE_ENV === 'development' && {
+    // Use memory cache instead of filesystem cache in dev to avoid stale chunks
+    webpack: (config, { isServer }) => {
+      // Disable persistent caching in development to prevent chunk reference errors
+      if (config.cache && config.cache.type === 'filesystem') {
+        config.cache = {
+          type: 'memory',
+        };
+      }
+      
+      // Improve cache busting for new files
+      if (!isServer) {
+        config.cache = false; // Disable cache completely on client in dev
+      }
+      
+      return config;
+    },
+    
+    // Disable build activity indicator which can cause issues
+    devIndicators: {
+      buildActivity: false,
+      buildActivityPosition: 'bottom-right',
+    },
+    
+    // Faster dev server
+    compress: false,
+  }),
+};
+
+export default nextConfig;
+

package/templates/typescript-auth-api-key/src/widgets/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "calculator-widgets",
+  "version": "1.0.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p 3001",
+    "build": "next build",
+    "start": "next start -p 3001"
+  },
+  "dependencies": {
+    "next": "^14.2.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "nitrostack": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "typescript": "^5"
+  }
+}
+

package/templates/typescript-auth-api-key/src/widgets/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+

package/templates/typescript-auth-api-key/src/widgets/widget-manifest.json

@@ -0,0 +1,48 @@
+{
+  "version": "1.0.0",
+  "widgets": [
+    {
+      "uri": "/calculator-result",
+      "name": "Calculator Result",
+      "description": "Displays the result of a calculation with operation details",
+      "examples": [
+        {
+          "name": "Addition Example",
+          "description": "Shows the result of adding 5 + 3",
+          "data": {
+            "operation": "add",
+            "a": 5,
+            "b": 3,
+            "result": 8,
+            "expression": "5 + 3 = 8"
+          }
+        },
+        {
+          "name": "Multiplication Example",
+          "description": "Shows the result of multiplying 6 × 7",
+          "data": {
+            "operation": "multiply",
+            "a": 6,
+            "b": 7,
+            "result": 42,
+            "expression": "6 × 7 = 42"
+          }
+        },
+        {
+          "name": "Division Example",
+          "description": "Shows the result of dividing 20 ÷ 4",
+          "data": {
+            "operation": "divide",
+            "a": 20,
+            "b": 4,
+            "result": 5,
+            "expression": "20 ÷ 4 = 5"
+          }
+        }
+      ],
+      "tags": ["calculator", "math", "result"]
+    }
+  ],
+  "generatedAt": "2025-01-01T00:00:00.000Z"
+}
+

package/templates/typescript-auth-api-key/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/widgets"]
+}
+

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

@@ -0,0 +1,91 @@
+# OAuth 2.1 MCP Server Configuration
+
+# =============================================================================
+# REQUIRED: Server Configuration
+# =============================================================================
+
+# Your MCP server's public URL (used for token audience binding - RFC 8707)
+# This MUST match the URL where your MCP server is accessible
+# Example: https://mcp.yourapp.com or http://localhost:3000 for development
+RESOURCE_URI=https://mcp.example.com
+
+# Your OAuth 2.1 authorization server URL
+# This is the base URL of your OAuth provider (Auth0, Okta, Keycloak, etc.)
+# Example for Auth0: https://your-tenant.auth0.com
+# Example for Okta: https://your-domain.okta.com
+AUTH_SERVER_URL=https://auth.example.com
+
+# =============================================================================
+# OPTIONAL: Token Configuration
+# =============================================================================
+
+# Expected token audience (defaults to RESOURCE_URI if not set)
+# This MUST match the audience claim in access tokens
+TOKEN_AUDIENCE=https://mcp.example.com
+
+# Expected token issuer (recommended for security)
+# This MUST match the issuer claim in access tokens
+# Example for Auth0: https://your-tenant.auth0.com/
+# Example for Okta: https://your-domain.okta.com/oauth2/default
+TOKEN_ISSUER=https://auth.example.com/
+
+# =============================================================================
+# OPTIONAL: Token Introspection (for opaque tokens)
+# =============================================================================
+
+# If your OAuth provider issues opaque tokens (not JWTs), configure these:
+
+# Token introspection endpoint (RFC 7662)
+# Example for Auth0: https://your-tenant.auth0.com/oauth/token/introspection
+# Example for Okta: https://your-domain.okta.com/oauth2/default/v1/introspect
+# INTROSPECTION_ENDPOINT=https://auth.example.com/oauth/introspect
+
+# Client credentials for introspection
+# These are separate from your MCP client credentials
+# INTROSPECTION_CLIENT_ID=your-introspection-client-id
+# INTROSPECTION_CLIENT_SECRET=your-introspection-client-secret
+
+# =============================================================================
+# Provider-Specific Examples
+# =============================================================================
+
+# --- Auth0 Example ---
+# RESOURCE_URI=https://mcp.yourapp.com
+# AUTH_SERVER_URL=https://your-tenant.auth0.com
+# TOKEN_AUDIENCE=https://mcp.yourapp.com
+# TOKEN_ISSUER=https://your-tenant.auth0.com/
+
+# --- Okta Example ---
+# RESOURCE_URI=https://mcp.yourapp.com
+# AUTH_SERVER_URL=https://your-domain.okta.com/oauth2/default
+# TOKEN_AUDIENCE=api://mcp.yourapp.com
+# TOKEN_ISSUER=https://your-domain.okta.com/oauth2/default
+
+# --- Keycloak Example ---
+# RESOURCE_URI=https://mcp.yourapp.com
+# AUTH_SERVER_URL=https://keycloak.yourapp.com/realms/your-realm
+# TOKEN_AUDIENCE=mcp-server
+# TOKEN_ISSUER=https://keycloak.yourapp.com/realms/your-realm
+
+# =============================================================================
+# Setup Instructions
+# =============================================================================
+# 
+# 1. Copy this file to .env:
+#    cp .env.example .env
+# 
+# 2. Configure your OAuth provider (see OAUTH_SETUP.md)
+# 
+# 3. Update the values above with your provider's URLs
+# 
+# 4. Start the server:
+#    npm run dev
+# 
+# 5. Configure OAuth in HyperMCP Studio:
+#    - Open Studio (http://localhost:3000)
+#    - Go to Auth → OAuth 2.1 tab
+#    - Click "Discover & Register"
+#    - Complete the OAuth flow
+# 
+# For detailed setup guides for each provider, see OAUTH_SETUP.md
+