dd0c/products/SECURITY-ARCHITECTURE-PLAN.md

ARCHITECTURE SPEC & IMPLEMENTATION PLAN

Project: dd0c DevOps SaaS Platform Author: Dr. Quinn, BMad Master Problem Solver Date: 2026-03-02

1. ROOT CAUSE ANALYSIS

We have systematically analyzed the 10 adversarial review findings and grouped them by their structural root causes.

Group A: Middleware & Request Pipeline Integrity (Issues 1, 7, 8, 9, 10)

• Root Cause: The authentication middleware is implemented as a global app.addHook('onRequest') using brittle string manipulation (.startsWith()) to bypass public routes. Fastify’s strength lies in its plugin encapsulation model, which is completely bypassed here. Furthermore, foundational web security controls (CORS scoping, Rate Limiting, Request Validation via schema) are missing, and JWT verification lacks algorithm strictness, opening the door to algorithm confusion.

Group B: Tenant Isolation & Data Security (Issues 2, 3)

• Root Cause: The system's multi-tenancy model is incomplete.
  • Data Leakage Risk: The Postgres pool object is exported directly from db.ts. Even though withTenant() exists to enforce Row-Level Security (RLS) via SET LOCAL, exporting pool means developers can inadvertently bypass RLS by calling pool.query() directly.
  • Product Gap: The data model strictly creates a 1:1 mapping between a new signup and a new tenant. There is no relational entity (e.g., tenant_invites) to securely map a new user to an existing tenant, breaking the "built for teams" promise.

Group C: Infrastructure Configuration Secrets (Issues 5, 6)

• Root Cause: Infrastructure-as-Code (Docker Compose) is being used as a secrets manager. All 5 services authenticate to Postgres using the root dd0c superuser, and secrets (JWT_SECRET, passwords) are hardcoded into the compose YAML. If one service is compromised (e.g., via SQLi), the attacker gains root access to all databases.

Group D: Architectural Reliability Constraints (Issue 4)

• Root Cause: Webhooks operate synchronously on containers configured to scale-to-zero. External providers (PagerDuty, Datadog) have strict timeout thresholds (typically 5-10s). Fly.io container cold-starts often exceed these thresholds, causing providers to drop payloads before the container can awaken and process the request.

---

2. ARCHITECTURE DECISIONS

Considering the constraints of a solo founder, a current NAS deployment with a path to Fly.io, and the need to preserve existing tests, we will adopt the following architectural standards:

1. Fastify Plugin Encapsulation (Fixes #1, #10): We will stop using global hooks. Public routes (health, webhooks) will be registered on the main app instance. Authenticated routes will be registered inside an encapsulated Fastify plugin where the auth hook is applied safely without string checking. We will use @fastify/type-provider-zod for built-in, strict request schema validation.
2. Strict Data Access Module (Fixes #3): The db.ts file will no longer export the raw pool. It will export a db object containing exactly two methods: withTenant<T>(tenantId, callback) for business logic, and systemQuery<T>(query) explicitly marked and audited for system-level background tasks.
3. Config-Driven Secrets & Least Privilege DB Roles (Fixes #5, #6): docker-compose.yml will be scrubbed of secrets. Secrets will be loaded via a .env file. We will update 01-init-db.sh to create service-specific PostgreSQL users with access only to their respective databases.
4. Invite-Based Onboarding (Fixes #2): We will introduce a tenant_invites table. The signup flow will be modified: if a user signs up with a valid invite token, they bypass tenant creation and are appended to the existing tenant with the defined role.
5. Decoupled Webhook Ingestion (Fixes #4): To support scale-to-zero without losing webhooks, we will leverage the already-running Upstash Redis instance. Webhooks will hit a lightweight, non-scaling ingestion function (or the Rust route-proxy which is always on) that simply LPUSHes payloads to Redis. The main Node services can safely wake up, BRPOP from the queue, and process asynchronously.

---

3. IMPLEMENTATION PLAN

This plan is phased. Existing tests MUST be run (./integration-test.sh) after each phase.

Phase 1: Security Critical (Do this before production)

Task 1.1: Fastify Auth Encapsulation

• Change: Modify shared/auth.ts and 03-alert-intelligence/src/auth/middleware.ts. Remove app.addHook('onRequest'). Export a Fastify plugin export const requireAuth = fp(async (fastify) => { fastify.addHook(...) }).
• Change: In index.ts, register public routes first. Then register the requireAuth plugin, then register protected routes.
• Effort: Medium
• Risk if deferred: High (Auth bypass easily discoverable by automated scanners).

Task 1.2: Hardened JWT Validation

• Change: In auth/middleware.ts, update jwt.verify(token, jwtSecret) to jwt.verify(token, jwtSecret, { algorithms: ['HS256'] }).
• Effort: Small

Task 1.3: Restrict Database Pool Access

• Change: In saas/src/data/db.ts (and shared equivalents), remove export const pool. Wrap queries in a strictly exported systemQuery function, and enforce withTenant for the rest. Update all services relying on pool.query() to use the new paradigm.
• Effort: Medium
• Risk if deferred: Critical (Any developer mistake results in massive cross-tenant data leakage).

Phase 2: Architecture (Structural Readiness)

Task 2.1: Secrets Management & DB Roles

• Change: Update docker-compose.yml to use variable substitution (e.g., ${POSTGRES_PASSWORD}). Provide an .env.example.
• Change: Update docker-init-db.sh to execute CREATE USER dd0c_alert WITH PASSWORD '...'; GRANT ALL ON DATABASE dd0c_alert TO dd0c_alert;. Update services to use their designated credentials.
• Effort: Medium
• Dependencies: None.

Task 2.2: Rate Limiting, CORS, and Zod Integration

• Change: Install @fastify/rate-limit. Apply a strict limit (e.g., 5 requests/min) to /api/v1/auth/*.
• Change: In config/index.ts, enforce CORS_ORIGIN using Zod regex (e.g., ^https?://.*\.dd0c\.localhost$).
• Change: Integrate @fastify/type-provider-zod into route definitions to reject bad payloads at the Fastify schema level.
• Effort: Medium

Phase 3: Product (Feature Blockers)

Task 3.1: Team Invite Flow

• Change: Create a new migration for tenant_invites (id, tenant_id, email, token, role, expires_at).
• Change: Add POST /api/v1/auth/invite (generates token) and update POST /api/v1/auth/signup to accept an optional invite_token.
• Effort: Large
• Dependencies: Database migrations.

Task 3.2: Async Webhook Ingestion

• Change: Shift webhook endpoints to simply validate signatures and LPUSH the raw payload to Redis.
• Change: Create a background worker loop in the Node service that uses BRPOP to pull and process webhooks. (Alternatively, route webhooks through the constantly-running Rust proxy).
• Effort: Large
• Risk if deferred: Medium (External webhook timeouts on Fly.io scale-to-zero).

---

4. TESTING STRATEGY

To verify fixes without breaking the 27 integration tests:

1. Auth Bypass: Write a new test in the smoke suite that attempts to hit /api/v1/auth/login-hack and /webhooks/../api/protected. Expect 404 Not Found or 401 Unauthorized.
2. RLS Protection: After restricting pool, run ./integration-test.sh. Any query that was improperly bypassing withTenant will cause TypeScript compilation to fail (since pool.query is no longer available), ensuring safe refactoring.
3. DB Roles: Spin up a clean docker-compose environment. Use a Postgres client to verify that dd0c_alert user cannot run SELECT * FROM dd0c_route.users.
4. Webhooks: Simulate a Fly.io cold start by pausing the dd0c-alert container, firing a webhook to the ingestion endpoint, and verifying the payload is queued in Redis and processed upon container resume.
5. Invite Flow: Add a multi-user flow to integration-test.sh asserting User B can be invited by User A and both can query the same tenant_id records.