@ezmcpz/security

Security modules for EZMCPZ including authentication, rate limiting, input validation, and access control.

Installation

npm install @ezmcpz/security
# or
pnpm add @ezmcpz/security

Modules

API Key Authentication

import { McpServer } from '@ezmcpz/core';
import { apiKeyAuth, generateApiKey, hashApiKey } from '@ezmcpz/security';

// Generate a new API key
const apiKey = generateApiKey(); // Returns a 64-character hex string
console.log('API Key:', apiKey);

// Hash the key for storage
const hash = await hashApiKey(apiKey);
console.log('Hash:', hash);

// Use in server
const server = new McpServer({ name: 'secure-server', version: '1.0.0' })
  .use(apiKeyAuth({
    keys: [
      { keyHash: hash, name: 'client1', enabled: true },
      { key: 'another-key', name: 'client2' } // Will be hashed automatically
    ],
    headerName: 'authorization',
    prefix: 'Bearer '
  }));

Rate Limiting

import { rateLimiter } from '@ezmcpz/security';

server.use(rateLimiter({
  maxPerMinute: 60,        // Max requests per minute
  maxPerHour: 1000,        // Max requests per hour
  maxConcurrent: 10,       // Max concurrent requests
  keyGenerator: (ctx) => ctx.clientId // Custom key generator
}));

Input Validation

import { inputValidator } from '@ezmcpz/security';

server.use(inputValidator({
  readOnlyMode: true,      // Block write operations
  maxInputLength: 1000000, // Max input size in bytes
  blockedKeywords: ['DANGEROUS', 'FORBIDDEN'],
  blockedPatterns: [/malicious/i],
  allowedOperations: ['SELECT', 'SHOW', 'DESCRIBE']
}));

Access Control

import { accessControl, rbac } from '@ezmcpz/security';

// Resource-based access control
server.use(accessControl({
  allowedResources: ['resource://public/*'],
  blockedResources: ['resource://private/*'],
  allowedTools: ['read_data', 'list_items'],
  blockedTools: ['delete_all'],
  customCheck: async (context) => {
    // Custom authorization logic
    return context.metadata.isAdmin === true;
  }
}));

// Role-based access control
server.use(rbac({
  admin: ['read', 'write', 'delete'],
  user: ['read', 'write'],
  guest: ['read']
}));

Complete Example

import { McpServer } from '@ezmcpz/core';
import { httpTransport } from '@ezmcpz/transport-http';
import {
  apiKeyAuth,
  rateLimiter,
  inputValidator,
  accessControl
} from '@ezmcpz/security';
import { z } from 'zod';

const server = new McpServer({
  name: 'secure-api',
  version: '1.0.0'
})
  // Security middleware (order matters!)
  .use(apiKeyAuth({
    keys: [
      { keyHash: process.env.API_KEY_HASH!, name: 'client1' }
    ]
  }))
  .use(rateLimiter({
    maxPerMinute: 60,
    maxConcurrent: 5
  }))
  .use(inputValidator({
    readOnlyMode: true,
    maxInputLength: 100000
  }))
  .use(accessControl({
    allowedTools: ['query_data', 'list_tables']
  }))
  // Tools
  .tool('query_data', {
    description: 'Query data',
    schema: z.object({ query: z.string() }),
    handler: async (args) => {
      return { result: 'data' };
    }
  })
  // Transport
  .use(httpTransport({ port: 3000 }));

await server.start();

Security Best Practices

1. Always use HTTPS in production
2. Store API key hashes, never plain keys
3. Enable rate limiting to prevent abuse
4. Validate all inputs before processing
5. Use access control to restrict resources
6. Log security events for auditing
7. Rotate API keys regularly
8. Use environment variables for secrets

Utilities

Generate API Key

import { generateApiKey } from '@ezmcpz/security';

const key = generateApiKey(32); // 32 bytes = 64 hex characters

Hash API Key

import { hashApiKey } from '@ezmcpz/security';

const hash = await hashApiKey('my-secret-key');

Verify API Key

import { verifyApiKey } from '@ezmcpz/security';

const isValid = await verifyApiKey('my-secret-key', hash);

Validate Identifier

import { validateIdentifier } from '@ezmcpz/security';

const result = validateIdentifier('table_name');
if (!result.valid) {
  console.error(result.error);
}

License

MIT