nitrostack 1.0.54 → 1.0.56

package/templates/typescript-auth-api-key/README.md

@@ -1,485 +0,0 @@
-# API Key Authentication MCP Server
-
-A complete example of building an MCP server with **API key authentication** using NitroStack.
-
-## 🎯 What You'll Learn
-
-- ✅ How to add API key authentication to your MCP server
-- ✅ How to create public and protected tools
-- ✅ How to use `ApiKeyModule` and `ApiKeyGuard`
-- ✅ How to test API key auth in NitroStack Studio
-- ✅ How to combine JWT and API key authentication (multi-auth)
-
-## 🔑 Test API Keys
-
-This template provides **test API keys** for immediate testing:
-
-```
-sk_test_public_demo_key_12345
-sk_test_admin_demo_key_67890
-```
-
-⚠️ **Important**: These are demo keys only. Never use them in production!
-
-## 📦 Installation
-
-```bash
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Run in development mode
-npm run dev
-```
-
-## 🚀 Quick Start
-
-### 1. Start the Server
-
-```bash
-npm run build
-nitrostack dev
-```
-
-The server will start with API key authentication enabled in dual transport mode (STDIO + HTTP on port 3002).
-
-> 💡 **Dual Transport**: Your server exposes tools via both STDIO (for direct connections) and HTTP (for remote access on port 3002). Switch between transports in Studio → Settings.
-
-### 2. Open NitroStack Studio
-
-Navigate to `http://localhost:3000` (Studio should auto-open)
-
-### 3. Set Your API Key
-
-1. Go to **Auth** tab in Studio
-2. Find the **API Key** section
-3. Paste one of the test keys:
-   ```
-   sk_test_public_demo_key_12345
-   ```
-4. Click **Set Key**
-
-### 4. Test the Tools
-
-#### Try a Public Tool (No Auth Required)
-1. Go to **Tools** tab
-2. Select `get_public_info`
-3. Enter any topic
-4. Execute ✓ - Works without API key!
-
-#### Try a Protected Tool (Auth Required)
-1. Select `get_protected_data`
-2. Choose data type: `user`, `account`, or `settings`
-3. Execute ✓ - Works with valid API key!
-4. Try clearing your API key → You'll get an authentication error
-
-## 🏗️ Project Structure
-
-```
-typescript-auth-api-key/
-├── src/
-│   ├── guards/
-│   │   └── apikey.guard.ts      # API key validation guard
-│   ├── modules/
-│   │   └── demo/
-│   │       ├── demo.module.ts   # Demo module
-│   │       └── demo.tools.ts    # Example tools
-│   ├── app.module.ts            # Root module
-│   └── index.ts                 # Main entry point (ApiKeyModule setup)
-├── .env                         # Test API keys
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-## 🛡️ How API Key Auth Works
-
-### 1. Configure ApiKeyModule
-
-In `src/index.ts`:
-
-```typescript
-const app = await McpApplicationFactory.create(AppModule, {
-  // Enable API key authentication
-  apiKey: ApiKeyModule.forRoot({
-    keysEnvPrefix: 'API_KEY',  // Reads API_KEY_1, API_KEY_2, etc.
-    headerName: 'x-api-key',
-    metadataField: 'apiKey',
-  }),
-});
-```
-
-### 2. Create an API Key Guard
-
-In `src/guards/apikey.guard.ts`:
-
-```typescript
-export class ApiKeyGuard implements Guard {
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    const apiKey = context.metadata?.apiKey;
-    
-    if (!apiKey) {
-      throw new Error('API key required');
-    }
-    
-    const isValid = await ApiKeyModule.validate(apiKey);
-    
-    if (!isValid) {
-      throw new Error('Invalid API key');
-    }
-    
-    context.auth = {
-      subject: `apikey_${apiKey.substring(0, 12)}`,
-      scopes: ['*'],
-    };
-    
-    return true;
-  }
-}
-```
-
-### 3. Protect Your Tools
-
-```typescript
-@Injectable()
-export class DemoTools {
-  
-  // PUBLIC: Anyone can call
-  @Tool({ name: 'get_public_info' })
-  async getPublicInfo() {
-    return { data: 'public' };
-  }
-  
-  // PROTECTED: Requires API key
-  @Tool({ name: 'get_protected_data' })
-  @UseGuards(ApiKeyGuard)  // 🔒 Protected!
-  async getProtectedData() {
-    return { data: 'protected' };
-  }
-}
-```
-
-## 🔐 API Key Management
-
-### Environment Variables
-
-API keys are loaded from environment variables:
-
-```bash
-# .env
-API_KEY_1=sk_test_public_demo_key_12345
-API_KEY_2=sk_test_admin_demo_key_67890
-API_KEY_3=your_custom_key_here
-```
-
-The `ApiKeyModule` automatically reads all `API_KEY_*` variables.
-
-### Studio Integration
-
-NitroStack Studio provides a **dedicated API Key UI**:
-
-1. **Auth Tab** → **API Key** section
-2. Enter your API key
-3. It's automatically included in all tool calls
-4. Persists across page refreshes
-5. Clear button to reset
-
-### How Keys Are Sent
-
-When you execute a tool in Studio, the API key is sent in the `_meta` field:
-
-```javascript
-{
-  args: { /* your tool arguments */ },
-  _meta: {
-    apiKey: "sk_test_public_demo_key_12345",
-    "x-api-key": "sk_test_public_demo_key_12345"
-  }
-}
-```
-
-The guard extracts it and validates it.
-
-## 🔄 Multi-Auth Example (JWT + API Key)
-
-You can use **both JWT and API key** authentication together!
-
-### Example: JWT Guard + API Key Guard
-
-```typescript
-// Guard that accepts EITHER JWT OR API Key
-export class MultiAuthGuard implements Guard {
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    // Try JWT first
-    const jwt = context.metadata?._jwt || context.metadata?.authorization;
-    if (jwt) {
-      // Validate JWT...
-      return true;
-    }
-    
-    // Try API key
-    const apiKey = context.metadata?.apiKey;
-    if (apiKey) {
-      const isValid = await ApiKeyModule.validate(apiKey);
-      return isValid;
-    }
-    
-    throw new Error('Either JWT or API key required');
-  }
-}
-
-// Use on a tool
-@Tool({ name: 'multi_auth_tool' })
-@UseGuards(MultiAuthGuard)
-async multiAuthTool() {
-  // Accessible with JWT OR API key
-}
-```
-
-### Example: Both Required
-
-```typescript
-@Tool({ name: 'double_auth_tool' })
-@UseGuards(JWTGuard, ApiKeyGuard)  // Both required!
-async doubleAuthTool() {
-  // Requires BOTH JWT token AND API key
-}
-```
-
-## 🧪 Testing Your Tools
-
-### In NitroStack Studio
-
-1. **Set API Key** in Auth tab
-2. Navigate to **Tools** tab
-3. Test public tools (work without key)
-4. Test protected tools (work with key)
-5. Test `check_api_key_status` to verify your setup
-
-### Programmatically (TypeScript Client)
-
-```typescript
-import { McpClient } from 'nitrostack';
-
-const client = new McpClient({
-  transport: 'stdio',
-  command: 'node',
-  args: ['dist/index.js'],
-});
-
-await client.connect();
-
-// Call protected tool with API key
-const result = await client.callTool('get_protected_data', {
-  dataType: 'user',
-  _meta: {
-    apiKey: 'sk_test_public_demo_key_12345'
-  }
-});
-
-console.log(result);
-```
-
-### In Claude Desktop or Cline
-
-Add to your MCP settings:
-
-```json
-{
-  "mcpServers": {
-    "api-key-auth": {
-      "command": "node",
-      "args": ["/path/to/dist/index.js"],
-      "env": {
-        "API_KEY_1": "sk_test_public_demo_key_12345"
-      }
-    }
-  }
-}
-```
-
-## 🔒 Production Best Practices
-
-### 1. Use Hashed Keys
-
-```typescript
-apiKey: ApiKeyModule.forRoot({
-  keysEnvPrefix: 'API_KEY',
-  hashed: true,  // Store keys as SHA-256 hashes
-})
-```
-
-Then hash your keys before storing:
-
-```typescript
-import { ApiKeyModule } from 'nitrostack';
-
-const apiKey = 'sk_prod_real_secret_key';
-const hashed = ApiKeyModule.hashKey(apiKey);
-console.log('Store this in .env:', hashed);
-// API_KEY_1=<hash>
-```
-
-### 2. Use Strong Keys
-
-```typescript
-import { ApiKeyModule } from 'nitrostack';
-
-// Generate cryptographically secure keys
-const newKey = ApiKeyModule.generateKey('sk'); 
-console.log(newKey);
-// sk_vK8mQ2xPnL...
-```
-
-### 3. Store Keys Securely
-
-- ✅ Use environment variables
-- ✅ Use secret management (AWS Secrets Manager, Vault, etc.)
-- ❌ Never commit keys to git
-- ❌ Never hardcode keys in source
-
-### 4. Custom Validation
-
-```typescript
-apiKey: ApiKeyModule.forRoot({
-  keysEnvPrefix: 'API_KEY',
-  customValidation: async (key) => {
-    // Check against database, rate limits, expiration, etc.
-    const keyRecord = await db.apiKeys.findOne({ key });
-    return keyRecord && !keyRecord.expired;
-  },
-})
-```
-
-## 📚 Available Tools
-
-### Public Tools (No Auth)
-
-#### `get_public_info`
-Get public information without authentication.
-
-**Arguments:**
-- `topic` (string): The topic to get information about
-
-**Example:**
-```json
-{
-  "topic": "weather"
-}
-```
-
-### Protected Tools (API Key Required)
-
-#### `get_protected_data`
-Retrieve protected data (requires API key).
-
-**Arguments:**
-- `dataType` (enum): `user`, `account`, or `settings`
-
-**Example:**
-```json
-{
-  "dataType": "user"
-}
-```
-
-#### `perform_protected_action`
-Perform a protected action (requires API key).
-
-**Arguments:**
-- `action` (enum): `create`, `update`, or `delete`
-- `resourceType` (string): Type of resource
-- `resourceId` (string, optional): Resource ID for update/delete
-
-**Example:**
-```json
-{
-  "action": "create",
-  "resourceType": "post"
-}
-```
-
-#### `check_api_key_status`
-Verify your API key is working correctly.
-
-**Arguments:** None
-
-## 🐛 Troubleshooting
-
-### "API key required" Error
-
-**Solution**: Set your API key in Studio Auth tab:
-1. Go to **Auth** tab
-2. Find **API Key** section  
-3. Paste: `sk_test_public_demo_key_12345`
-4. Click **Set Key**
-
-### "Invalid API key" Error
-
-**Causes:**
-- Wrong key format
-- Key not in `.env` file
-- Environment variables not loaded
-
-**Solution:**
-1. Check `.env` has the key
-2. Restart the dev server: `npm run dev`
-3. Verify key in Studio matches `.env`
-
-### Public Tools Not Working
-
-Public tools should work without authentication. If they fail:
-1. Check server logs for errors
-2. Ensure no guards are accidentally applied
-3. Test in Studio Tools tab
-
-## 🎓 Next Steps
-
-1. ✅ Explore the code in `src/`
-2. ✅ Add your own protected tools
-3. ✅ Combine with JWT auth (see `typescript-auth` template)
-4. ✅ Add custom validation logic
-5. ✅ Deploy to production with secure keys
-
-## 📖 Related Resources
-
-- **NitroStack Docs**: Full documentation
-- **typescript-auth Template**: JWT authentication example
-- **typescript-starter Template**: Basic MCP server
-- **ApiKeyModule API**: Core API key functionality
-
-## 💡 Tips
-
-- 🔑 Use `sk_` prefix for secret keys (standard convention)
-- 🔐 Enable hashing in production
-- 🎯 Mix public and protected tools in the same server
-- 🔄 Support multiple auth methods (JWT + API Key)
-- 📊 Add logging to track API key usage
-
-## ❓ FAQ
-
-**Q: Can I use both JWT and API key auth?**  
-A: Yes! See the Multi-Auth Example section above.
-
-**Q: How do I rotate API keys?**  
-A: Add new keys to `.env`, deploy, then remove old keys after clients update.
-
-**Q: Can I have per-key permissions?**  
-A: Yes! Use `customValidation` to check permissions in your database.
-
-**Q: Is this production-ready?**  
-A: Yes, but enable `hashed: true` and use secure key storage.
-
-**Q: How do I integrate with my existing auth system?**  
-A: Use `customValidation` to validate against your auth API/database.
-
----
-
-## 🎉 You're Ready!
-
-You now have a fully functional MCP server with API key authentication. Try it out, modify it, and build something amazing!
-
-**Happy coding! 🚀**
-

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

@@ -1,21 +0,0 @@
-{
-  "name": "typescript-auth-api-key",
-  "version": "1.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "nitrostack dev",
-    "build": "nitrostack build",
-    "start": "npm run build && nitrostack start",
-    "start:prod": "nitrostack start",
-    "widget": "npm --prefix src/widgets"
-  },
-  "dependencies": {
-    "dotenv": "^16.4.5",
-    "nitrostack": "^1",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "typescript": "^5.3.3"
-  }
-}

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

@@ -1,38 +0,0 @@
-import { McpApp, Module, ApiKeyModule } from 'nitrostack';
-import { DemoModule } from './modules/demo/demo.module.js';
-
-/**
- * App Module - Root module for the API Key Auth MCP Server
- * 
- * This module demonstrates how to build an MCP server with API key authentication.
- */
-@McpApp({
-  module: AppModule,
-  server: {
-    name: 'API Key Auth MCP Server',
-    version: '1.0.0',
-  },
-  logging: {
-    level: 'info',
-  },
-})
-@Module({
-  name: 'app',
-  description: 'Root application module with API key authentication',
-  imports: [
-    // Enable API key authentication
-    ApiKeyModule.forRoot({
-      keysEnvPrefix: 'API_KEY',  // Reads API_KEY_1, API_KEY_2, etc.
-      headerName: 'x-api-key',
-      metadataField: 'apiKey',
-      hashed: false,  // Set to true in production
-    }),
-    
-    // Feature modules
-    DemoModule,
-  ],
-  controllers: [],
-  providers: [],
-})
-export class AppModule {}
-

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

@@ -1,47 +0,0 @@
-import { Guard, ExecutionContext, ApiKeyModule, ApiKeyMetadata } from 'nitrostack';
-
-/**
- * API Key Guard
- * 
- * Validates API keys for tool access.
- * Keys are extracted from context.metadata.apiKey or context.metadata['x-api-key']
- * 
- * Usage:
- * ```typescript
- * @Tool({
- *   name: 'protected_tool',
- *   description: 'A protected tool that requires API key'
- * })
- * @UseGuards(ApiKeyGuard)
- * async protectedTool() {
- *   // Only accessible with valid API key
- * }
- * ```
- */
-export class ApiKeyGuard implements Guard {
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    // Extract API key from metadata (sent by Studio or client)
-    const apiKey = context.metadata?.apiKey || context.metadata?.['x-api-key'];
-    
-    if (!apiKey) {
-      throw new Error('API key required. Please set your API key in the Studio Auth tab (OAuth 2.1 page).');
-    }
-    
-    // Validate API key using ApiKeyModule
-    const isValid = await ApiKeyModule.validate(apiKey as string);
-    
-    if (!isValid) {
-      throw new Error('Invalid API key. Please check your API key in the Studio Auth tab.');
-    }
-    
-    // Populate context.auth with API key metadata
-    context.auth = {
-      subject: `apikey_${(apiKey as string).substring(0, 12)}`,
-      scopes: ['*'], // API keys typically have full access
-    };
-    
-    return true;
-  }
-}
-
-