CapaKraken/docs/security-architecture.md

# Security Architecture — CapaKraken

> Version: 1.0 | Date: 2026-03-27

---

## 1. Authentication

- **Auth.js v5** (NextAuth) with Credentials provider
- **Password hashing**: Argon2id via `@node-rs/argon2` (memory cost 65536, time cost 3)
- **Multi-Factor Authentication**: TOTP (RFC 6238) via `otpauth` library
  - Configurable per user (enable/disable via admin or self-service)
  - 30-second window, SHA-1, 6-digit codes with 1-step tolerance
- **Rate limiting**: 5 login attempts per 15 minutes per email address (in-memory sliding window)
- **Session strategy**: JWT with server-side validation
  - Absolute timeout: 8 hours (configurable via `sessionMaxAge`)
  - Idle timeout: 30 minutes (configurable via `sessionIdleTimeout`)
- **Concurrent session limit**: configurable `maxConcurrentSessions` (default 3), kick-oldest strategy
- **Login/logout audit**: all authentication events (success, failure, rate-limit, invalid TOTP, logout) are recorded in the audit log

## 2. Authorization

### Role-Based Access Control (RBAC)

Five-level role hierarchy:

| Role | Level | Capabilities |
|------|-------|-------------|
| ADMIN | 5 | Full system access, user management, system settings |
| MANAGER | 4 | Project management, resource allocation, vacation approval |
| CONTROLLER | 3 | Financial views, budget management, reporting |
| USER | 2 | Self-service (own vacations, own resource profile) |
| VIEWER | 1 | Read-only access to permitted areas |

### Per-User Permission Overrides

- `permissionOverrides` JSONB field on User model
- `resolvePermissions(role, overrides)` computes effective permissions
- `requirePermission(ctx, key)` enforced on every tRPC procedure
- Granular `PermissionKey` enum covering all domain actions

### tRPC Middleware Stack

```
publicProcedure
  -> protectedProcedure (requires authenticated session)
    -> controllerProcedure (ADMIN + MANAGER + CONTROLLER)
      -> managerProcedure (ADMIN + MANAGER)
        -> adminProcedure (ADMIN only)
```

## 3. Data Protection

### Database Security

- **PostgreSQL** with TLS in production
- **Prisma ORM**: parameterized queries by default — no SQL injection risk
- Database not exposed to the internet (Docker internal network only)
- All monetary values stored as integer cents (no floating-point precision issues)

### Data at Rest

- Passwords: Argon2id hash (never stored in plaintext)
- TOTP secrets: stored in DB (encrypted at-rest via PostgreSQL TDE when available)
- API keys (Azure OpenAI, Gemini, SMTP): stored in `SystemSettings` table, accessible only to ADMIN role

### Anonymization

- Configurable global anonymization for VIEWER role
- Resource names, emails replaced with deterministic pseudonyms (seeded hash)
- Anonymization domain and mode configurable in SystemSettings

## 4. Session Management

- **Server-side JWT** with `SameSite=Strict` cookies
- `httpOnly` cookies prevent XSS-based session theft
- `secure` flag enforced in production (HTTPS only)
- CSRF protection via Auth.js built-in CSRF token
- Configurable session timeouts (absolute + idle) via SystemSettings
- Active session registry with concurrent session limit enforcement

## 5. Input Validation

- **Zod schemas** on every tRPC procedure input
- Strict TypeScript (`strict: true`, `exactOptionalPropertyTypes: true`)
- Blueprint dynamic fields validated at runtime against stored Zod schema definitions
- File uploads validated by:
  - MIME type whitelist (`image/png`, `image/jpeg`, `image/webp`, `image/tiff`, `image/bmp`)
  - Size limit (10 MB client-side, 4 MB server-side after compression)
  - Magic byte verification (actual file content matched against declared MIME)

## 6. Audit Logging

### Activity History System

- Centralized `createAuditEntry()` function (fire-and-forget, never blocks)
- Covers 29+ of 36 tRPC routers
- Logged fields: `entityType`, `entityId`, `action`, `userId`, `changes` (JSONB with before/after/diff), `source`, `summary`
- Authentication events: login success/failure, logout, rate limiting, MFA failures

### External API Call Logging

- All OpenAI/Azure/Gemini API calls logged via `loggedAiCall()` wrapper
- Structured Pino logs: `{ provider, model, promptLength, responseTimeMs }`
- Failed calls logged at `warn` level with error details

### tRPC Request Logging

- Every tRPC call logged with request ID, user ID, path, duration
- Slow calls (>500ms) logged at `warn` level

## 7. HTTP Security Headers

Configured in `next.config.ts`:

| Header | Value |
|--------|-------|
| Strict-Transport-Security | `max-age=63072000; includeSubDomains; preload` |
| Content-Security-Policy | Restrictive CSP with nonce-based script-src |
| X-Frame-Options | `DENY` |
| X-Content-Type-Options | `nosniff` |
| X-XSS-Protection | `1; mode=block` |
| Referrer-Policy | `strict-origin-when-cross-origin` |
| Permissions-Policy | Camera, microphone, geolocation disabled |

## 8. Rate Limiting

- **Per-IP rate limiting**: via middleware on all API routes
- **Per-user rate limiting**: configurable per-procedure
- **Auth-specific rate limiting**: 5 attempts / 15 min per email (in-memory sliding window)
- **AI API call rate limits**: upstream provider limits surfaced as user-friendly errors

## 9. Error Handling

- **Sentry** integration for production error tracking
- **Pino** structured logging (JSON in production, pretty-print in development)
- tRPC errors mapped to appropriate HTTP status codes
- AI API errors translated to human-readable messages via `parseAiError()` / `parseGeminiError()`
- Internal errors never leak stack traces to the client

## 10. Dependency Security

- **Dependabot** configured for automated dependency updates
- `pnpm audit` as part of CI pipeline
- Lockfile integrity verified on install

## 11. Network Architecture

```
Browser -> Next.js (port 3100) -> tRPC -> Prisma -> PostgreSQL (port 5433)
                                       -> Redis (port 6380, SSE pub/sub)
                                       -> Azure OpenAI / Gemini (external HTTPS)
                                       -> SMTP (email notifications)
```

- PostgreSQL and Redis accessible only within Docker network
- External API calls (AI, SMTP) over TLS
- No direct database access from the internet

## 12. Database Security

### Authentication and Access

- PostgreSQL uses password-based authentication (`capakraken` user with strong password)
- Connection restricted to the Docker internal network (port 5433 on host, 5432 inside container)
- No direct internet access to the database — all queries routed through Prisma ORM via the application layer
- Application uses a single database user; no shared or anonymous access

### Query Safety

- **Prisma ORM** enforces parameterized queries by default — no raw SQL concatenation
- All user inputs validated by Zod schemas before reaching the data layer
- JSONB fields (blueprints, skill matrices, permission overrides) are type-checked at the application boundary

### Recommendations for Production Hardening

1. **Enable PostgreSQL SSL/TLS**: Set `ssl: true` in the Prisma connection string and configure `postgresql.conf` with `ssl = on`, `ssl_cert_file`, `ssl_key_file`
2. **Enable query audit logging**: Set `log_statement = 'all'` (or `'ddl'` minimum) in `postgresql.conf` to capture all executed statements for forensic review
3. **Restrict connections by IP**: Configure `pg_hba.conf` to accept connections only from the application container's subnet (e.g., `172.18.0.0/16`)
4. **Use separate database roles**: Create a read-only role for reporting queries and a migration-only role for schema changes, limiting the default application role to DML operations
5. **Enable connection pooling**: Use PgBouncer in production to limit maximum connections and prevent resource exhaustion attacks
6. **Backup encryption**: Ensure `pg_dump` backups are encrypted at rest (GPG or filesystem-level encryption)

### Redis Security

- Redis instance runs without authentication in development (Docker-internal only)
- **Production recommendation**: Enable `requirepass` in Redis configuration and set `REDIS_URL` to include the password (`redis://:password@host:port`)
- Redis is used only for SSE pub/sub (no sensitive data persisted)

## 13. Proactive Monitoring

### Health Check Cron (`/api/cron/health-check`)

- Verifies PostgreSQL and Redis connectivity on each invocation
- On failure: creates CRITICAL in-app notifications for all ADMIN users
- Designed to be triggered by external cron (e.g., `curl` every 5 minutes)
- Protected by `CRON_SECRET` Bearer token

### Security Audit Cron (`/api/cron/security-audit`)

- Scans installed dependency versions against known minimum safe versions
- Alerts ADMIN users when high-severity outdated packages are detected
- Complements Dependabot with an in-app awareness layer

### nginx Hardening

- Reference configuration: `docs/nginx-hardening.conf`
- Covers: server token removal, rate limiting (auth: 1r/s, API: 10r/s), SSL hardening (TLS 1.2+), OCSP stapling
- Security headers applied at nginx level as a defense-in-depth backup to Next.js headers