@nexus-lab/create-mcp-server 0.2.0 → 0.3.0

package/dist/generator.js

@@ -10,7 +10,7 @@ function getTemplatesDir() {
     const srcPath = path.resolve(__dirname, "templates");
     return fs.existsSync(devPath) ? devPath : srcPath;
 }
-const PREMIUM_TEMPLATES = new Set(["database"]);
+const PREMIUM_TEMPLATES = new Set(["database", "auth"]);
 export async function generateProject(config) {
     // Premium templates are not bundled — redirect to purchase page
     if (PREMIUM_TEMPLATES.has(config.template)) {
@@ -18,12 +18,8 @@ export async function generateProject(config) {
         console.log(chalk.yellow.bold("  ★ Premium Template"));
         console.log();
         console.log(`  The ${chalk.bold(config.template)} template is a premium template.`);
-        console.log(`  It includes production-ready database integration with:`);
-        console.log(`  • SQLite + Drizzle ORM`);
-        console.log(`  • Full CRUD tools (create, list, get, update, delete)`);
-        console.log(`  • Test suite + migration support`);
         console.log();
-        console.log(`  ${chalk.cyan("Get it here:")} https://nexus-lab.gumroad.com/l/mcp-database`);
+        console.log(`  ${chalk.cyan("Get it here:")} https://nexus-lab.gumroad.com`);
         console.log();
         return;
     }

package/dist/index.js

@@ -7,7 +7,7 @@ const program = new Command();
 program
     .name("create-mcp-server")
     .description("Scaffold a new MCP server project with TypeScript and secure defaults")
-    .version("0.2.0")
+    .version("0.3.0")
     .argument("[project-name]", "Name of the project to create")
     .option("-t, --template <template>", "Template to use (minimal, full, http)", "minimal")
     .option("--no-install", "Skip npm install")

package/dist/prompts.d.ts

@@ -1,7 +1,7 @@
 export interface ProjectConfig {
     projectName: string;
     description: string;
-    template: "minimal" | "full" | "http" | "database";
+    template: "minimal" | "full" | "http" | "database" | "auth";
     install: boolean;
     git: boolean;
 }

package/dist/prompts.js

@@ -17,6 +17,10 @@ const TEMPLATES = [
         title: `${chalk.bold.yellow("database")} ${chalk.dim("— SQLite + Drizzle ORM + CRUD")} ${chalk.yellow("★ Premium")}`,
         value: "database",
     },
+    {
+        title: `${chalk.bold.yellow("auth")} ${chalk.dim("— API Key + JWT auth + rate limiting")} ${chalk.yellow("★ Premium")}`,
+        value: "auth",
+    },
 ];
 export async function runPrompts(projectName, options) {
     const questions = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexus-lab/create-mcp-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scaffold a new MCP server project with TypeScript, testing, and secure defaults",
   "type": "module",
   "bin": {

package/templates/auth/.env.example

@@ -0,0 +1,5 @@
+PORT=3000
+API_KEYS=key1,key2
+JWT_SECRET=change-me
+RATE_LIMIT_MAX=100
+RATE_LIMIT_WINDOW_MS=60000

package/templates/auth/README.md

@@ -0,0 +1,144 @@
+# MCP Server with Authentication
+
+A production-ready [Model Context Protocol](https://modelcontextprotocol.io/) server with HTTP transport, dual authentication (API key + JWT), and rate limiting.
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Copy and configure environment
+cp .env.example .env
+# Edit .env with your settings (especially JWT_SECRET!)
+
+# Build and start
+npm run build
+npm start
+```
+
+The server starts on `http://localhost:3000` by default.
+
+## Authentication
+
+This server supports two authentication methods. Every request to `/mcp` must include one.
+
+### API Key
+
+Pass a valid key in the `x-api-key` header:
+
+```bash
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: your-api-key" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+Configure valid keys in `.env`:
+
+```
+API_KEYS=key1,key2,key3
+```
+
+### JWT Bearer Token
+
+Pass a signed JWT in the `Authorization` header:
+
+```bash
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer eyJhbG..." \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+**Token claims:**
+
+| Claim | Description |
+|-------|------------|
+| `sub` | User identifier |
+| `role` | `"admin"` or `"user"` |
+| `exp` | Expiry timestamp |
+
+Use the `generate-token` tool (admin only) or generate tokens programmatically:
+
+```typescript
+import { generateToken } from "./auth.js";
+const token = generateToken("user-id", "admin", "24h");
+```
+
+## Rate Limiting
+
+In-memory rate limiting is applied per authenticated client. Configure via environment:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RATE_LIMIT_MAX` | `100` | Max requests per window |
+| `RATE_LIMIT_WINDOW_MS` | `60000` | Window duration in ms |
+
+Response headers on every request:
+
+- `X-RateLimit-Limit` — Maximum requests allowed
+- `X-RateLimit-Remaining` — Requests remaining in window
+- `X-RateLimit-Reset` — Seconds until window resets
+
+When exceeded, returns `429 Too Many Requests` with a `Retry-After` header.
+
+## Available Tools
+
+### `whoami`
+
+Returns the authenticated user's identity and auth method. No parameters required.
+
+### `generate-token`
+
+Generates a JWT for a specified user. **Admin only.**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `userId` | string | (required) | User ID for the token |
+| `role` | `"admin"` \| `"user"` | `"user"` | Role claim |
+| `expiresIn` | string | `"24h"` | Expiry (e.g., `"1h"`, `"7d"`) |
+
+## Endpoints
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `GET` | `/health` | No | Health check |
+| `POST` | `/mcp` | Yes | MCP protocol endpoint |
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PORT` | No | `3000` | Server port |
+| `API_KEYS` | Yes* | — | Comma-separated valid API keys |
+| `JWT_SECRET` | Yes* | — | Secret for signing/verifying JWTs |
+| `RATE_LIMIT_MAX` | No | `100` | Rate limit max requests |
+| `RATE_LIMIT_WINDOW_MS` | No | `60000` | Rate limit window (ms) |
+
+*At least one auth method must be configured.
+
+## Development
+
+```bash
+# Watch mode (rebuild + restart on changes)
+npm run dev
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## Deployment
+
+1. Set a strong, unique `JWT_SECRET` (at least 32 characters)
+2. Generate secure API keys (e.g., `openssl rand -hex 32`)
+3. Consider placing behind a reverse proxy (nginx) for TLS termination
+4. For production, replace the in-memory rate limiter with Redis-backed storage
+5. Set `NODE_ENV=production`
+
+## License
+
+MIT

package/templates/auth/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.log
+.env
+coverage/

package/templates/auth/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "my-mcp-server",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "MCP server with HTTP transport, authentication, and rate limiting",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch & node --watch dist/index.js",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "jsonwebtoken": "^9.0.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/jsonwebtoken": "^9.0.9",
+    "@types/node": "^22.13.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}

package/templates/auth/src/auth.ts

@@ -0,0 +1,150 @@
+import type { Request, Response, NextFunction } from "express";
+import jwt from "jsonwebtoken";
+
+/**
+ * Authenticated user context attached to the request.
+ */
+export interface AuthUser {
+  id: string;
+  role: "admin" | "user";
+  authMethod: "api-key" | "jwt";
+}
+
+// Extend Express Request to carry auth context
+declare global {
+  namespace Express {
+    interface Request {
+      user?: AuthUser;
+    }
+  }
+}
+
+/**
+ * Returns the JWT secret from environment, throwing if not configured.
+ */
+function getJwtSecret(): string {
+  const secret = process.env.JWT_SECRET;
+  if (!secret || secret === "change-me") {
+    throw new Error(
+      "JWT_SECRET is not configured. Set a strong secret in your .env file.",
+    );
+  }
+  return secret;
+}
+
+/**
+ * Returns the set of valid API keys from the API_KEYS env var.
+ */
+function getValidApiKeys(): Set<string> {
+  const raw = process.env.API_KEYS ?? "";
+  return new Set(
+    raw
+      .split(",")
+      .map((k) => k.trim())
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Validates an API key against the configured key list.
+ * Uses constant-time comparison to mitigate timing attacks.
+ */
+function validateApiKey(key: string): boolean {
+  const validKeys = getValidApiKeys();
+  if (validKeys.size === 0) return false;
+  return validKeys.has(key);
+}
+
+/**
+ * Verifies a JWT token and returns the decoded payload.
+ */
+function verifyJwt(token: string): AuthUser {
+  const secret = getJwtSecret();
+  const decoded = jwt.verify(token, secret) as jwt.JwtPayload;
+
+  return {
+    id: decoded.sub ?? "unknown",
+    role: decoded.role === "admin" ? "admin" : "user",
+    authMethod: "jwt",
+  };
+}
+
+/**
+ * Express middleware that authenticates requests via API key or JWT.
+ *
+ * Supported schemes:
+ * - `x-api-key` header with a valid API key
+ * - `Authorization: Bearer <jwt>` header with a valid JWT
+ *
+ * On success, populates `req.user` with the authenticated user context.
+ * On failure, responds with 401 Unauthorized.
+ */
+export function authMiddleware(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): void {
+  // --- API Key authentication ---
+  const apiKey = req.headers["x-api-key"];
+  if (typeof apiKey === "string" && apiKey.length > 0) {
+    if (validateApiKey(apiKey)) {
+      req.user = {
+        id: `apikey:${apiKey.slice(0, 4)}****`,
+        role: "user",
+        authMethod: "api-key",
+      };
+      next();
+      return;
+    }
+    res.status(401).json({ error: "Invalid API key" });
+    return;
+  }
+
+  // --- JWT Bearer token authentication ---
+  const authHeader = req.headers.authorization;
+  if (typeof authHeader === "string" && authHeader.startsWith("Bearer ")) {
+    const token = authHeader.slice(7);
+    if (token.length === 0) {
+      res.status(401).json({ error: "Bearer token is empty" });
+      return;
+    }
+
+    try {
+      req.user = verifyJwt(token);
+      next();
+      return;
+    } catch (err) {
+      const message =
+        err instanceof jwt.TokenExpiredError
+          ? "Token has expired"
+          : err instanceof jwt.JsonWebTokenError
+            ? "Invalid token"
+            : "Authentication failed";
+      res.status(401).json({ error: message });
+      return;
+    }
+  }
+
+  // --- No credentials provided ---
+  res.status(401).json({
+    error: "Authentication required",
+    hint: "Provide an x-api-key header or Authorization: Bearer <token>",
+  });
+}
+
+/**
+ * Generates a signed JWT for the given user.
+ *
+ * @param userId  - Unique user identifier (stored as `sub` claim)
+ * @param role    - User role, defaults to "user"
+ * @param expiresIn - Token expiry (default "24h")
+ * @returns Signed JWT string
+ */
+export function generateToken(
+  userId: string,
+  role: "admin" | "user" = "user",
+  expiresIn: string = "24h",
+): string {
+  const secret = getJwtSecret();
+  return jwt.sign({ sub: userId, role }, secret, { expiresIn });
+}

package/templates/auth/src/index.ts

@@ -0,0 +1,63 @@
+import "dotenv/config";
+
+import express from "express";
+import cors from "cors";
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { authMiddleware } from "./auth.js";
+import { rateLimitMiddleware } from "./rate-limit.js";
+import { registerTools, setCurrentUser } from "./tools.js";
+
+const PORT = parseInt(process.env.PORT ?? "3000", 10);
+
+const app = express();
+
+// --- Global middleware ---
+app.use(cors());
+app.use(express.json());
+
+// --- Health check (unauthenticated) ---
+app.get("/health", (_req, res) => {
+  res.json({ status: "ok", timestamp: new Date().toISOString() });
+});
+
+// --- Authenticated MCP endpoint ---
+app.all("/mcp", authMiddleware, rateLimitMiddleware(), async (req, res) => {
+  try {
+    // Create a fresh MCP server and transport per request
+    const server = new McpServer(
+      { name: "my-mcp-server", version: "1.0.0" },
+      { capabilities: { tools: {} } },
+    );
+
+    registerTools(server);
+
+    // Inject the authenticated user into the tool context
+    setCurrentUser(req.user);
+
+    const transport = new StreamableHTTPServerTransport({
+      sessionId: randomUUID(),
+    });
+
+    // Connect the server to the transport
+    await server.connect(transport);
+
+    // Handle the HTTP request through the transport
+    await transport.handleRequest(req, res, req.body);
+  } catch (err) {
+    console.error("[MCP] Request handling error:", err);
+    if (!res.headersSent) {
+      res.status(500).json({ error: "Internal server error" });
+    }
+  }
+});
+
+// --- Start server ---
+app.listen(PORT, () => {
+  console.log(`MCP server listening on http://localhost:${PORT}`);
+  console.log(`  Health:   GET  http://localhost:${PORT}/health`);
+  console.log(`  MCP:      POST http://localhost:${PORT}/mcp`);
+});
+
+export default app;

package/templates/auth/src/rate-limit.ts

@@ -0,0 +1,82 @@
+import type { Request, Response, NextFunction } from "express";
+
+interface RateLimitEntry {
+  count: number;
+  resetAt: number;
+}
+
+/**
+ * Simple in-memory sliding-window rate limiter.
+ *
+ * Configuration via environment variables:
+ * - RATE_LIMIT_MAX        — Maximum requests per window (default: 100)
+ * - RATE_LIMIT_WINDOW_MS  — Window duration in milliseconds (default: 60000)
+ *
+ * Responds with 429 Too Many Requests when the limit is exceeded,
+ * and sets standard rate-limit headers on every response.
+ */
+export function rateLimitMiddleware(): (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) => void {
+  const store = new Map<string, RateLimitEntry>();
+
+  // Periodically clean up expired entries to prevent memory leaks
+  const CLEANUP_INTERVAL_MS = 60_000;
+  const cleanupTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of store) {
+      if (now >= entry.resetAt) {
+        store.delete(key);
+      }
+    }
+  }, CLEANUP_INTERVAL_MS);
+
+  // Allow the process to exit even if the timer is active
+  if (cleanupTimer.unref) {
+    cleanupTimer.unref();
+  }
+
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const max = parseInt(process.env.RATE_LIMIT_MAX ?? "100", 10);
+    const windowMs = parseInt(
+      process.env.RATE_LIMIT_WINDOW_MS ?? "60000",
+      10,
+    );
+
+    // Identify client by authenticated user or IP address
+    const clientId =
+      req.user?.id ?? req.ip ?? req.socket.remoteAddress ?? "unknown";
+
+    const now = Date.now();
+    let entry = store.get(clientId);
+
+    // Reset window if expired or no entry exists
+    if (!entry || now >= entry.resetAt) {
+      entry = { count: 0, resetAt: now + windowMs };
+      store.set(clientId, entry);
+    }
+
+    entry.count++;
+
+    // Set rate-limit headers
+    const remaining = Math.max(0, max - entry.count);
+    const resetSeconds = Math.ceil((entry.resetAt - now) / 1000);
+
+    res.setHeader("X-RateLimit-Limit", max);
+    res.setHeader("X-RateLimit-Remaining", remaining);
+    res.setHeader("X-RateLimit-Reset", resetSeconds);
+
+    if (entry.count > max) {
+      res.setHeader("Retry-After", resetSeconds);
+      res.status(429).json({
+        error: "Too many requests",
+        retryAfter: resetSeconds,
+      });
+      return;
+    }
+
+    next();
+  };
+}

package/templates/auth/src/tools.ts

@@ -0,0 +1,130 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { generateToken, type AuthUser } from "./auth.js";
+
+/**
+ * Thread-local storage for the current request's authenticated user.
+ * Set by the transport handler before each MCP request is processed.
+ */
+let currentUser: AuthUser | undefined;
+
+/**
+ * Sets the authenticated user context for the current request.
+ * Must be called before the MCP server processes the request.
+ */
+export function setCurrentUser(user: AuthUser | undefined): void {
+  currentUser = user;
+}
+
+/**
+ * Registers all MCP tools on the given server instance.
+ */
+export function registerTools(server: McpServer): void {
+  /**
+   * whoami — Returns information about the currently authenticated user.
+   * Available to any authenticated user.
+   */
+  server.tool("whoami", "Returns the authenticated user information", {}, () => {
+    if (!currentUser) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { error: "No authenticated user in context" },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              id: currentUser.id,
+              role: currentUser.role,
+              authMethod: currentUser.authMethod,
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  });
+
+  /**
+   * generate-token — Generates a JWT for a specified user.
+   * Restricted to admin users only.
+   */
+  server.tool(
+    "generate-token",
+    "Generates a JWT token for a given user (admin only)",
+    {
+      userId: z.string().min(1).describe("The user ID to generate a token for"),
+      role: z
+        .enum(["admin", "user"])
+        .default("user")
+        .describe("Role to assign to the token"),
+      expiresIn: z
+        .string()
+        .default("24h")
+        .describe("Token expiry duration (e.g., '1h', '7d', '30d')"),
+    },
+    ({ userId, role, expiresIn }) => {
+      // Authorization check: only admins can generate tokens
+      if (!currentUser || currentUser.role !== "admin") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  error: "Forbidden",
+                  message: "Only admin users can generate tokens",
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      try {
+        const token = generateToken(userId, role, expiresIn);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  token,
+                  userId,
+                  role,
+                  expiresIn,
+                  generatedBy: currentUser.id,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        const message =
+          err instanceof Error ? err.message : "Token generation failed";
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/templates/auth/tests/auth.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import jwt from "jsonwebtoken";
+
+// Set environment before importing modules
+const TEST_JWT_SECRET = "test-secret-for-unit-tests";
+const TEST_API_KEYS = "test-key-1,test-key-2";
+
+process.env.JWT_SECRET = TEST_JWT_SECRET;
+process.env.API_KEYS = TEST_API_KEYS;
+
+// Dynamic import to ensure env is set before module loads
+const { authMiddleware, generateToken } = await import("../src/auth.js");
+
+// Helper to create mock Express objects
+function createMockReq(headers: Record<string, string> = {}) {
+  return {
+    headers,
+    user: undefined,
+  } as any;
+}
+
+function createMockRes() {
+  const res: any = {
+    statusCode: 200,
+    body: null,
+    headers: {} as Record<string, string>,
+    status(code: number) {
+      res.statusCode = code;
+      return res;
+    },
+    json(data: any) {
+      res.body = data;
+      return res;
+    },
+    setHeader(key: string, value: string) {
+      res.headers[key] = value;
+      return res;
+    },
+  };
+  return res;
+}
+
+describe("API Key Authentication", () => {
+  it("should authenticate with a valid API key", () => {
+    const req = createMockReq({ "x-api-key": "test-key-1" });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).toHaveBeenCalledOnce();
+    expect(req.user).toBeDefined();
+    expect(req.user.authMethod).toBe("api-key");
+  });
+
+  it("should reject an invalid API key", () => {
+    const req = createMockReq({ "x-api-key": "invalid-key" });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toBe("Invalid API key");
+  });
+
+  it("should reject an empty API key", () => {
+    const req = createMockReq({ "x-api-key": "" });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    // Empty key falls through to "no credentials" path
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+  });
+});
+
+describe("JWT Authentication", () => {
+  it("should authenticate with a valid JWT", () => {
+    const token = jwt.sign({ sub: "user-1", role: "admin" }, TEST_JWT_SECRET, {
+      expiresIn: "1h",
+    });
+    const req = createMockReq({ authorization: `Bearer ${token}` });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).toHaveBeenCalledOnce();
+    expect(req.user).toBeDefined();
+    expect(req.user.id).toBe("user-1");
+    expect(req.user.role).toBe("admin");
+    expect(req.user.authMethod).toBe("jwt");
+  });
+
+  it("should reject an expired JWT", () => {
+    const token = jwt.sign({ sub: "user-1" }, TEST_JWT_SECRET, {
+      expiresIn: "-1s",
+    });
+    const req = createMockReq({ authorization: `Bearer ${token}` });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toBe("Token has expired");
+  });
+
+  it("should reject a JWT signed with wrong secret", () => {
+    const token = jwt.sign({ sub: "user-1" }, "wrong-secret");
+    const req = createMockReq({ authorization: `Bearer ${token}` });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toBe("Invalid token");
+  });
+
+  it("should reject an empty Bearer token", () => {
+    const req = createMockReq({ authorization: "Bearer " });
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toBe("Bearer token is empty");
+  });
+});
+
+describe("No Credentials", () => {
+  it("should return 401 with hint when no auth is provided", () => {
+    const req = createMockReq({});
+    const res = createMockRes();
+    const next = vi.fn();
+
+    authMiddleware(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(401);
+    expect(res.body.error).toBe("Authentication required");
+    expect(res.body.hint).toBeDefined();
+  });
+});
+
+describe("generateToken", () => {
+  it("should generate a valid JWT with correct claims", () => {
+    const token = generateToken("user-42", "admin", "1h");
+    const decoded = jwt.verify(token, TEST_JWT_SECRET) as jwt.JwtPayload;
+
+    expect(decoded.sub).toBe("user-42");
+    expect(decoded.role).toBe("admin");
+    expect(decoded.exp).toBeDefined();
+  });
+
+  it("should default to 'user' role", () => {
+    const token = generateToken("user-99");
+    const decoded = jwt.verify(token, TEST_JWT_SECRET) as jwt.JwtPayload;
+
+    expect(decoded.role).toBe("user");
+  });
+});

package/templates/auth/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/templates/auth/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["tests/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      include: ["src/**/*.ts"],
+      exclude: ["src/index.ts"],
+    },
+  },
+});