@eltonssouza/development-utility-kit 0.10.0

package/.claude/stacks/node/express-5.md

@@ -0,0 +1,538 @@
+---
+stack: node/express-5
+versions_covered: "5.0.x — 5.2.x"
+last_validated: 2026-05-28
+validated_against: "reference pack — Node 22 LTS + Express 5.0 + Prisma 5.20 + Jest 29"
+status: active
+pack_owner: "@elton"
+security_review: 2026-05-28
+next_review_due: 2027-05-28
+---
+
+# Node 22+ + Express 5.x
+
+Canonical knowledge pack for Node.js HTTP services on Express 5.x. Express 5 (released October 2024, after years of beta) brings async error handling as a first-class behavior, Node 18+ floor, modern route matching, and various breaking changes from Express 4. For new projects that want a heavier opinion (DI, validation, OpenAPI), consider NestJS instead — this pack assumes plain Express with TypeScript and explicit DDD layering.
+
+## 1. When to use this pack
+
+- Project declares `Primary stack: Node 22+ + Express 5.x + TypeScript` in `## Project Identity`.
+- `package.json` declares `"express": "^5.0.0"` and `"node": ">=22"`.
+- Service is API-first (REST), small-to-medium throughput, team prefers explicit code over framework magic.
+- For SSR with React/Vue or full framework with DI: Next.js, NestJS, or Fastify+plugins are better fits.
+- For high-throughput edge: Hono / Fastify outperform Express. Use this pack if Express's middleware ecosystem is the deciding factor.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| Node.js | 22 LTS (min) / 24 (latest) | Native `--watch`, native `node:test`, native `fetch` — use them |
+| TypeScript | 5.6.x+ | strict mode mandatory; `noUncheckedIndexedAccess: true` |
+| Express | 5.0.x — 5.2.x | Async route handlers handle errors automatically; major param matching changes from 4.x |
+| ORM | Prisma 5.20+ (recommended) OR TypeORM 0.3.20+ | Prisma's typed client + migrations is the cleanest single-tool option |
+| Validation | Zod 3.23+ | TypeScript-first; infer types from schema; use everywhere |
+| Build | `tsc` for compilation OR `tsx` for dev OR esbuild for prod bundles | `tsx watch` for dev; `tsc --noEmit && esbuild` for prod |
+| Package manager | pnpm 9.x (recommended) OR npm 10.x | pnpm is faster + safer (strict deps) |
+| Tests | Jest 29.x OR Vitest 2.x + Supertest 7.x + Testcontainers Node 10.x | NEVER SQLite if prod is Postgres |
+| Mutation | Stryker 8.x | Target ≥70% on `domain/` + `application/` |
+| Coverage | Jest `--coverage` (V8 provider) | Target ≥85% lines, ≥80% branches |
+| Static analysis | `eslint` v9 (flat config) + `@typescript-eslint` + `prettier` | `--max-warnings 0` |
+| Security scan | `npm audit --omit=dev` + `snyk test` (optional) | 0 CVE with CVSS ≥7.0 |
+| Observability | OpenTelemetry SDK + `@opentelemetry/instrumentation-express` | W3C Trace Context; auto-instruments routes + Prisma + http |
+| Logger | `pino` 9.x | High performance JSON; structured by default |
+| Config | `zod` for env validation at startup | Crash fast on bad env |
+| Process manager | `pm2` or container runtime | Cluster mode only when needed; Node 22 handles concurrency well single-process |
+
+## 3. Project structure (DDD-flavored Express)
+
+```
+service/
+├── package.json
+├── pnpm-lock.yaml
+├── tsconfig.json
+├── eslint.config.js              # flat config
+├── prisma/
+│   ├── schema.prisma
+│   └── migrations/
+├── .env.example
+├── src/
+│   ├── domain/                   # pure TS; no Express, no Prisma
+│   │   ├── product/
+│   │   │   ├── entity.ts
+│   │   │   ├── repository.ts     # interface
+│   │   │   └── service.ts
+│   │   └── shared/
+│   ├── application/              # use cases (1 class per use case)
+│   │   ├── product/
+│   │   │   ├── createProduct.ts
+│   │   │   ├── listProducts.ts
+│   │   │   └── dto.ts
+│   │   └── shared/
+│   ├── infrastructure/           # Prisma, fetch wrappers
+│   │   ├── db/
+│   │   │   └── prisma.ts         # PrismaClient singleton
+│   │   ├── product/
+│   │   │   └── repository.ts     # adapter for domain interface
+│   │   └── http/
+│   │       └── upstreamClient.ts
+│   ├── api/                      # Express routes + middleware
+│   │   ├── product/
+│   │   │   ├── router.ts
+│   │   │   ├── handlers.ts
+│   │   │   └── schemas.ts        # Zod schemas (req/res)
+│   │   └── shared/
+│   │       ├── errorHandler.ts   # RFC 9457 ProblemDetails
+│   │       └── middleware.ts
+│   ├── config/
+│   │   └── env.ts                # Zod-validated env
+│   └── server.ts                 # Express app + listen
+└── tests/
+    ├── unit/
+    ├── integration/
+    └── e2e/
+```
+
+**Rule**: `domain/` and `application/` contain **zero Express and zero Prisma imports**. They are pure TS testable without HTTP or DB. `infrastructure/` is the only layer importing `@prisma/client`. `api/` is the only layer importing `express`.
+
+## 4. Code patterns
+
+### Domain entity (no Prisma, no Express)
+
+```typescript
+// src/domain/product/entity.ts
+export class Product {
+  constructor(
+    public readonly id: string,           // UUID
+    public readonly name: string,
+    public readonly priceCents: bigint,   // bigint for money — never number
+    public readonly stock: number,
+    public readonly createdAt: Date,
+  ) {}
+
+  reserve(qty: number): Product {
+    if (qty <= 0) throw new Error("qty must be positive");
+    if (qty > this.stock) throw new Error("insufficient stock");
+    return new Product(this.id, this.name, this.priceCents, this.stock - qty, this.createdAt);
+  }
+}
+```
+
+**Rule**: money in `bigint` (or `Decimal` from prisma) — never `number` (IEEE 754 loses precision). Domain methods take and return value types. Immutability by constructor + `readonly`.
+
+### Domain port + infrastructure adapter (Prisma)
+
+```typescript
+// src/domain/product/repository.ts
+import type { Product } from "./entity";
+
+export interface ProductRepository {
+  get(id: string): Promise<Product | null>;
+  save(product: Product): Promise<void>;
+}
+```
+
+```typescript
+// src/infrastructure/product/repository.ts
+import type { PrismaClient, Product as ProductRow } from "@prisma/client";
+import type { ProductRepository } from "@/domain/product/repository";
+import { Product } from "@/domain/product/entity";
+
+export class PrismaProductRepository implements ProductRepository {
+  constructor(private readonly prisma: PrismaClient) {}
+
+  async get(id: string): Promise<Product | null> {
+    const row = await this.prisma.product.findUnique({ where: { id } });
+    return row ? this.toDomain(row) : null;
+  }
+
+  async save(p: Product): Promise<void> {
+    await this.prisma.product.upsert({
+      where: { id: p.id },
+      create: { id: p.id, name: p.name, priceCents: p.priceCents, stock: p.stock },
+      update: { name: p.name, priceCents: p.priceCents, stock: p.stock },
+    });
+  }
+
+  private toDomain(row: ProductRow): Product {
+    return new Product(row.id, row.name, row.priceCents, row.stock, row.createdAt);
+  }
+}
+```
+
+**Rule**: domain `ProductRepository` is an interface in `domain/`. Implementation imports Prisma. Use cases depend on the interface. UUID primary key.
+
+### Zod schemas + handler (Express 5 async routes)
+
+```typescript
+// src/api/product/schemas.ts
+import { z } from "zod";
+
+export const createProductRequest = z.object({
+  name: z.string().min(1).max(120),
+  priceCents: z.coerce.bigint().positive(),
+  stock: z.number().int().min(0),
+}).strict();   // strict() rejects unknown keys
+
+export type CreateProductRequest = z.infer<typeof createProductRequest>;
+
+export const productResponse = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  priceCents: z.bigint(),
+  stock: z.number(),
+  createdAt: z.date(),
+});
+
+export type ProductResponse = z.infer<typeof productResponse>;
+```
+
+```typescript
+// src/api/product/handlers.ts
+import type { Request, Response } from "express";
+import { createProductRequest } from "./schemas";
+import type { CreateProductUseCase } from "@/application/product/createProduct";
+
+export class ProductHandlers {
+  constructor(private readonly createUC: CreateProductUseCase) {}
+
+  // Express 5: async errors propagate to error middleware automatically
+  create = async (req: Request, res: Response) => {
+    const parsed = createProductRequest.parse(req.body); // throws ZodError on invalid
+    const product = await this.createUC.execute(parsed);
+    res.status(201).json({
+      id: product.id,
+      name: product.name,
+      priceCents: product.priceCents.toString(),
+      stock: product.stock,
+      createdAt: product.createdAt,
+    });
+  };
+}
+```
+
+**Rule**: Zod schemas are the API contract. `parse()` throws on invalid; error middleware catches and returns RFC 9457. `strict()` rejects unknown keys (silent acceptance = footgun).
+
+### Router + middleware chain
+
+```typescript
+// src/api/product/router.ts
+import { Router } from "express";
+import type { ProductHandlers } from "./handlers";
+
+export function productRouter(h: ProductHandlers): Router {
+  const r = Router();
+  r.post("/", h.create);
+  return r;
+}
+```
+
+```typescript
+// src/server.ts
+import express from "express";
+import helmet from "helmet";
+import compression from "compression";
+import cors from "cors";
+import pinoHttp from "pino-http";
+import { productRouter } from "@/api/product/router";
+import { errorHandler } from "@/api/shared/errorHandler";
+import { config } from "@/config/env";
+
+const app = express();
+app.disable("x-powered-by");
+app.use(helmet());
+app.use(compression());
+app.use(cors({ origin: config.CORS_ORIGINS, credentials: true }));
+app.use(express.json({ limit: "100kb" }));
+app.use(pinoHttp({ logger }));
+
+app.use("/api/v1/products", productRouter(deps.productHandlers));
+
+// Centralized error handler — Express 5 catches async errors here
+app.use(errorHandler);
+
+app.listen(config.PORT, () => {
+  logger.info({ port: config.PORT }, "server up");
+});
+```
+
+**Rule**: `helmet()` before any routes. `express.json({ limit: "100kb" })` always — no default = DoS via large payload. `app.disable("x-powered-by")` — small but free hardening.
+
+### Error handler (RFC 9457 ProblemDetails)
+
+```typescript
+// src/api/shared/errorHandler.ts
+import type { ErrorRequestHandler } from "express";
+import { ZodError } from "zod";
+
+export const errorHandler: ErrorRequestHandler = (err, req, res, _next) => {
+  if (err instanceof ZodError) {
+    res.status(422).json({
+      type: "https://example.com/errors/validation",
+      title: "Validation failed",
+      status: 422,
+      instance: req.originalUrl,
+      errors: err.errors,
+    });
+    return;
+  }
+  // log full error server-side
+  req.log?.error({ err }, "unhandled error");
+  res.status(500).json({
+    type: "about:blank",
+    title: "Internal Server Error",
+    status: 500,
+    instance: req.originalUrl,
+  });
+};
+```
+
+**Rule**: error handler must be the LAST middleware. Express 5 routes catch async errors and pass to this middleware automatically (huge improvement over Express 4 where every async route needed try/catch or `express-async-errors`).
+
+## 5. Testing
+
+### Unit (Jest, no Express/DB)
+
+```typescript
+// src/domain/product/entity.test.ts
+import { Product } from "./entity";
+
+describe("Product.reserve", () => {
+  const make = (stock: number) =>
+    new Product("id-1", "x", 990n, stock, new Date());
+
+  it("decreases stock", () => {
+    expect(make(10).reserve(3).stock).toBe(7);
+  });
+
+  it("refuses zero", () => {
+    expect(() => make(10).reserve(0)).toThrow();
+  });
+
+  it("refuses excess", () => {
+    expect(() => make(10).reserve(11)).toThrow();
+  });
+});
+```
+
+### Integration (Supertest + Testcontainers Postgres)
+
+```typescript
+// tests/integration/product.test.ts
+import request from "supertest";
+import { PostgreSqlContainer } from "@testcontainers/postgresql";
+import { buildApp } from "@/server";
+
+describe("POST /api/v1/products", () => {
+  let pg: any;
+  let app: any;
+
+  beforeAll(async () => {
+    pg = await new PostgreSqlContainer("postgres:16-alpine").start();
+    process.env.DATABASE_URL = pg.getConnectionUri();
+    app = await buildApp();
+  });
+
+  afterAll(async () => {
+    await pg.stop();
+  });
+
+  it("creates a product", async () => {
+    const r = await request(app)
+      .post("/api/v1/products")
+      .send({ name: "widget", priceCents: "990", stock: 100 });
+    expect(r.status).toBe(201);
+    expect(r.body.name).toBe("widget");
+  });
+});
+```
+
+**Rule**: Testcontainers Postgres for integration tests. NEVER SQLite if prod is Postgres.
+
+### Mutation (Stryker)
+
+```bash
+npx stryker run
+# stryker.conf.mjs targets src/domain and src/application
+# Target: mutation score >= 70%
+```
+
+## 6. Build & run commands
+
+```bash
+# Setup
+pnpm install
+
+# Generate Prisma client (after schema change)
+pnpm prisma generate
+
+# Migrations
+pnpm prisma migrate dev --name add_products      # dev: creates + applies
+pnpm prisma migrate deploy                       # prod: only applies
+
+# Run dev (with auto-reload via tsx)
+pnpm dev                                         # tsx watch src/server.ts
+
+# Run prod (after build)
+pnpm build                                       # tsc → dist/
+pnpm start                                       # node dist/server.js
+
+# Tests
+pnpm test                                        # jest
+pnpm test:unit                                   # unit only
+pnpm test --coverage                             # with coverage
+pnpm test:watch
+
+# Mutation
+pnpm stryker run
+
+# Lint + format
+pnpm lint                                        # eslint
+pnpm format                                      # prettier --write
+pnpm typecheck                                   # tsc --noEmit
+
+# Security scan
+pnpm audit --omit=dev
+pnpm dlx snyk test                               # optional, if Snyk account
+```
+
+## 7. Security (per ADR-007 + ADR-027 — MANDATORY section)
+
+### 7.1 Authentication & Authorization
+
+- **JWT**: `jsonwebtoken` 9.x. RS256 preferred multi-service; HS256 single-service. Validate `iss`, `aud`, `exp`. `kid` rotation.
+- **OAuth2 / OIDC**: `openid-client` or hosted IdP (Auth0 / Keycloak / Cognito).
+- **Sessions**: `express-session` + Redis store. Secure cookie flags: `httpOnly`, `secure`, `sameSite: "lax"`.
+- **Password hashing**: `bcrypt` cost 12 minimum OR `argon2` (preferred). NEVER plain `crypto.createHash("sha256")`.
+- **API keys**: `crypto.randomBytes(32).toString("base64url")`; hash before storage.
+- **Authorization**: middleware that decodes JWT, attaches `req.user`, then per-route role check. Object-level checks inside the use case.
+
+### 7.2 CORS
+
+```typescript
+app.use(cors({
+  origin: ["https://app.example.com"],   // NEVER "*" in prod
+  credentials: true,
+  methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+  allowedHeaders: ["Authorization", "Content-Type"],
+}));
+```
+
+### 7.3 Validation & input sanitization
+
+- **SQL injection**: Prisma parameterizes everything. NEVER `$queryRawUnsafe` with template strings; use `$queryRaw` with the tagged template literal (Prisma parameterizes).
+- **NoSQL injection**: if using MongoDB, never accept raw `$where`/`$regex` from user input.
+- **Zod everywhere**: every route body, query, params validated. `.strict()` to reject unknown keys.
+- **JSON body limit**: `express.json({ limit: "100kb" })` — default is 100kb, but be explicit. Larger uploads should be multipart.
+- **Path traversal**: `path.resolve` + check inside an allowed base before opening any file.
+- **Prototype pollution**: never `Object.assign(target, JSON.parse(userInput))` — Zod schemas prevent this naturally.
+
+### 7.4 Secrets management
+
+```typescript
+// src/config/env.ts
+import { z } from "zod";
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(["development", "test", "production"]),
+  PORT: z.coerce.number().int().positive().default(3000),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  CORS_ORIGINS: z.string().transform((s) => s.split(",")),
+});
+
+export const config = envSchema.parse(process.env);   // throws on bad env
+```
+
+- `.env` gitignored; `.env.example` committed.
+- Crash on missing/invalid env at startup. Never `process.env.FOO ?? "fallback"` — silent fallback masks misconfiguration.
+- Prefer Secrets Manager (AWS / GCP / Vault) in prod.
+
+### 7.5 Rate limiting
+
+```typescript
+import rateLimit from "express-rate-limit";
+
+const authLimiter = rateLimit({
+  windowMs: 60_000,
+  max: 5,
+  standardHeaders: true,
+  legacyHeaders: false,
+});
+
+app.use("/api/v1/auth", authLimiter);
+```
+
+- `5/min` on `/auth/login`, `/auth/signup`, `/auth/password-reset`.
+- `100/min` on regular GETs.
+- Behind reverse proxy: `app.set("trust proxy", 1)` and `keyGenerator: (req) => req.ip` carefully — only trust the proxy IP.
+
+### 7.6 OWASP Top 10 mapping
+
+| OWASP | Mitigation in Node 22 + Express 5 |
+|---|---|
+| A01 Broken Access Control | JWT middleware + per-route role check; object-level check in use case; default-deny |
+| A02 Cryptographic Failures | bcrypt cost 12 or argon2; TLS at proxy; HSTS via `helmet({ hsts: { maxAge: 31536000 } })`; JWT RS256 with key rotation |
+| A03 Injection | Prisma parameterization; Zod validation on every input; never `$queryRawUnsafe` |
+| A04 Insecure Design | DDD layering enforced (`domain/` no Express/Prisma); use case = single async method per class; ADRs document deviations |
+| A05 Security Misconfiguration | `helmet()`; `app.disable("x-powered-by")`; `express.json({ limit: "100kb" })`; CORS allowlist explicit; `NODE_ENV=production` |
+| A06 Vulnerable Components | `pnpm audit` in CI; `renovate` for `package.json` bumps; lockfile committed |
+| A07 Auth Failures | rate-limit on auth endpoints; argon2/bcrypt; account lock via Redis counter; MFA via `otplib` |
+| A08 Data Integrity | `pnpm install --frozen-lockfile` in CI; SBOM via `cyclonedx-npm`; package-lock signature verification on critical deps |
+| A09 Logging Failures | `pino` structured JSON; correlation ID via `cls-rtracer` or AsyncLocalStorage; **NEVER** log `req.body` raw (PII) |
+| A10 SSRF | Centralized fetch wrapper with allowlist of outbound hosts; reject `localhost`, link-local (`169.254.0.0/16`), private CIDRs by default |
+
+### 7.7 LGPD / GDPR / compliance specifics
+
+- **PII tagging**: convention via Prisma comments (`/// @pii`) + a custom lint that checks string fields named Email/CPF/Document have it.
+- **Soft delete**: Prisma middleware that intercepts `delete` and rewrites as `update { deletedAt: new Date() }`. NEVER hard delete user-owned data.
+- **Data subject access (Art 15)**: `GET /api/v1/me/export` returns user data as ZIP.
+- **Erasure (Art 17)**: `DELETE /api/v1/me` redacts PII fields while preserving FKs.
+- **Encryption at rest**: PostgreSQL TDE (cloud-managed) or column-level via `prisma-field-encryption` for sensitive fields.
+
+## 8. Anti-patterns (block in code-review)
+
+| ❌ Bad | ✅ Good | Why |
+|---|---|---|
+| `app.use(express.json())` without `limit` | `app.use(express.json({ limit: "100kb" }))` | Default works but explicit is safer; large limit = DoS |
+| Async route without error handling in Express 4 style (`(req, res) => { foo().then(...) }`) | Express 5 async route — automatic error forwarding | Express 5 handles it; manual try/catch noise removed |
+| `number` for money | `bigint` (cents) or Prisma `Decimal` | IEEE 754 precision loss is real |
+| `process.env.FOO ?? "fallback"` | Zod-validated env, crash on missing | Silent fallback masks misconfig |
+| Returning Prisma row directly from handler | DTO with explicit serialization | API contract leaks data model |
+| `$queryRawUnsafe(`...${userInput}...`)` | `$queryRaw\`...${userInput}...\`` (tagged template) | Prisma parameterizes only the tagged version |
+| `Object.assign(user, req.body)` | Zod parse + explicit field copy | Prototype pollution + mass assignment |
+| `JSON.stringify(err)` in error response | RFC 9457 ProblemDetails with controlled fields | Leaks stack traces / DB internals to client |
+| `console.log` in prod | `pino` structured JSON logger | console.log loses metadata + slow |
+| `setTimeout(() => doWork(), 0)` instead of `setImmediate` or worker thread | Worker threads or queue for CPU-bound work | Event loop blocking under load |
+| `Buffer.from(input, "base64")` without validation | Validate input is base64 first; catch + 400 | Malformed input crashes or returns garbage |
+| Default `eslint` config without strict TS | `@typescript-eslint` strict + `--max-warnings 0` | Type safety must be enforced |
+
+## 9. Migration hints — Express 4 → 5
+
+Breaking changes worth flagging when `migrator` agent runs Express 4 → 5:
+
+- **Node 18 minimum** (Express 5); recommend Node 22 LTS.
+- **Async error handling**: async route handlers that throw now reach the error middleware automatically. Remove `express-async-errors` package and any manual `next(err)` in catch blocks — they still work but are redundant.
+- **`req.param()` removed**: use `req.params.id` / `req.query.id` / `req.body.id` explicitly.
+- **`res.redirect("back")` removed**: use `res.redirect(req.get("Referrer") || "/")`.
+- **Path matching changed**: regex routes need re-validation. `:param?` optional syntax may behave differently. Test all routes.
+- **`path-to-regexp` v8**: stricter parsing. Routes like `/user/:id(\\d+)` may need adjustment.
+- **`req.query` is now `null` if empty** (vs `{}` in v4). Defensive access: `req.query?.foo`.
+- **Body parsers**: `express.json` and `express.urlencoded` no longer accept charsets via `type` option without explicit configuration.
+- **`res.json` returns `this`**: chainable, but `await res.json(...)` may behave subtly differently if you depended on the old void return.
+
+Hand off to `migrator` with: current Express version, route count, list of routes using regex patterns, list of middleware using deprecated APIs.
+
+## 10. References
+
+- [Express 5 migration guide](https://expressjs.com/en/guide/migrating-5.html)
+- [Express docs](https://expressjs.com/en/api.html)
+- [Prisma docs](https://www.prisma.io/docs)
+- [Zod docs](https://zod.dev/)
+- [pino](https://github.com/pinojs/pino)
+- [helmet docs](https://helmetjs.github.io/)
+- [Testcontainers Node](https://node.testcontainers.org/)
+- [Stryker mutation](https://stryker-mutator.io/docs/stryker-js/introduction/)
+- [OWASP Node.js Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html)
+- ADR-007 (Senior+ gate thresholds — coverage ≥85%, mutation ≥70%)
+- ADR-026 (Generic agents + stack packs architecture)
+- ADR-027 (Pack governance — frontmatter + security mandatory + CODEOWNERS + annual review)
+- ADR-029 (Canonical pack format — this document follows it)