stack/docs/plans/2026-03-13-gateway-security-hardening.md

Gateway Security Hardening Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Finish the requested gateway security hardening fixes in the existing fix/gateway-security worktree and produce a PR-ready branch.

Architecture: Tighten NestJS gateway boundaries in-place by enforcing auth guards, session validation, ownership checks, DTO validation, and Fastify security defaults. Preserve the current module structure and existing ESM import conventions.

Tech Stack: NestJS 11, Fastify, Socket.IO, Better Auth, class-validator, Vitest, pnpm, TypeScript ESM

---

Task 1: Reconcile Security Tests

Files:

• Modify: apps/gateway/src/chat/__tests__/chat-security.test.ts
• Modify: apps/gateway/src/__tests__/resource-ownership.test.ts

Step 1: Write the failing test

• Encode the requested DTO constraints and socket-auth contract exactly.

Step 2: Run test to verify it fails

Run: pnpm --filter @mosaic/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts

Expected: FAIL on current DTO/helper mismatch.

Step 3: Write minimal implementation

• Update DTO/helper/controller code only where tests prove a gap.

Step 4: Run test to verify it passes

Run the same command and require green.

Task 2: Align Gateway Runtime Hardening

Files:

• Modify: apps/gateway/src/conversations/conversations.dto.ts
• Modify: apps/gateway/src/chat/chat.dto.ts
• Modify: apps/gateway/src/chat/chat.gateway-auth.ts
• Modify: apps/gateway/src/chat/chat.gateway.ts
• Modify: apps/gateway/src/main.ts
• Modify: apps/gateway/src/app.module.ts

Step 1: Verify remaining requested deltas

• Confirm code matches requested guard, rate limit, helmet, body limit, env validation, and CORS settings.

Step 2: Apply minimal patch

• Keep changes scoped to requested behavior only.

Step 3: Run targeted tests

Run: pnpm --filter @mosaic/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts

Expected: PASS.

Task 3: Verification, Review, and Delivery

Files:

• Create: docs/reports/code-review/gateway-security-20260313.md
• Create: docs/reports/qa/gateway-security-20260313.md
• Modify: docs/scratchpads/gateway-security-20260313.md

Step 1: Run baseline gates

Run:

pnpm typecheck
pnpm lint

Step 2: Perform manual code review

• Record correctness/security/testing/doc findings.

Step 3: Commit and publish

Run:

git add -A
git commit -m "fix(gateway): security hardening — auth guards, ownership checks, validation, rate limiting"
git push origin fix/gateway-security

Step 4: Open PR and notify

• Open PR titled fix(gateway): security hardening — auth guards, ownership checks, validation, rate limiting
• Run openclaw system event --text "PR ready: mosaic-mono-v1 fix/gateway-security — 7 security fixes" --mode now
• Remove worktree after PR is created.