nitrostack 1.0.0

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

@@ -0,0 +1,483 @@
+# 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.
+
+### 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-lock.json

@@ -0,0 +1,124 @@
+{
+  "name": "api-key-auth-mcp-server",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "api-key-auth-mcp-server",
+      "version": "1.0.0",
+      "license": "MIT",
+      "dependencies": {
+        "nitrostack": "file:../../",
+        "zod": "^3.23.8"
+      },
+      "devDependencies": {
+        "@types/node": "^20",
+        "typescript": "^5"
+      }
+    },
+    "../..": {
+      "version": "1.0.0",
+      "license": "MIT",
+      "dependencies": {
+        "@google/generative-ai": "^0.24.1",
+        "@modelcontextprotocol/sdk": "^1.0.4",
+        "bcryptjs": "^2.4.3",
+        "better-sqlite3": "^11.8.1",
+        "chokidar": "^3.6.0",
+        "commander": "^12.1.0",
+        "cors": "^2.8.5",
+        "dotenv": "^17.2.3",
+        "express": "^4.21.2",
+        "fs-extra": "^11.3.2",
+        "http-proxy-middleware": "^3.0.3",
+        "inquirer": "^12.10.0",
+        "jose": "^6.1.0",
+        "jsonwebtoken": "^9.0.2",
+        "open": "^10.2.0",
+        "openai": "^6.5.0",
+        "ora": "^9.0.0",
+        "reflect-metadata": "^0.2.1",
+        "uuid": "^11.0.5",
+        "winston": "^3.17.0",
+        "ws": "^8.18.3",
+        "zod": "^3.24.1",
+        "zod-to-json-schema": "^3.24.6"
+      },
+      "bin": {
+        "nitrostack": "dist/cli/index.js"
+      },
+      "devDependencies": {
+        "@types/bcryptjs": "^2.4.6",
+        "@types/better-sqlite3": "^7.6.12",
+        "@types/cors": "^2.8.19",
+        "@types/express": "^5.0.0",
+        "@types/fs-extra": "^11.0.4",
+        "@types/jest": "^29.5.14",
+        "@types/jsonwebtoken": "^9.0.7",
+        "@types/node": "^22.10.5",
+        "@types/react": "^19.2.2",
+        "@types/uuid": "^10.0.0",
+        "@types/ws": "^8.18.1",
+        "jest": "^29.7.0",
+        "ts-jest": "^29.2.5",
+        "typescript": "^5.7.2"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "20.19.23",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.23.tgz",
+      "integrity": "sha512-yIdlVVVHXpmqRhtyovZAcSy0MiPcYWGkoO4CGe/+jpP0hmNuihm4XhHbADpK++MsiLHP5MVlv+bcgdF99kSiFQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/nitrostack": {
+      "resolved": "../..",
+      "link": true
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/zod": {
+      "version": "3.25.76",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
+      "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,29 @@
+{
+  "name": "api-key-auth-mcp-server",
+  "version": "1.0.0",
+  "description": "NitroStack server demonstrating API key authentication",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "nitrostack dev",
+    "build": "nitrostack build",
+    "start": "nitrostack start",
+    "widget": "npm --prefix src/widgets"
+  },
+  "keywords": [
+    "mcp",
+    "nitrostack",
+    "api-key",
+    "authentication"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "nitrostack": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}