# Backend: Security (Template)

---
**Phase:** Phase 0 (Planning)  
**Status:** Draft — finalize in Phase 1  
**Owner:** Backend Architect, Security  
**References:**
- `/docs/backend/architecture.md`
- `/docs/backend/payment-flow.md`
- `/docs/backend/api-design.md`
---

## 1. Goals
- Protect sensitive data and ensure tenant isolation.
- Secure integrations (webhooks/OAuth) and billing.
- Maintain auditability for all automated and manual actions.

## 2. Authentication & Authorization
- Use managed auth (Clerk/Auth.js or equivalent) with secure sessions/tokens.
- Enforce tenant-scoped RBAC; validate tenant context on every request.
- Rate limit auth endpoints; protect refresh flows.

## 3. Data Protection
- TLS everywhere; secure headers.
- Least-privilege DB roles; encrypt secrets at rest; rotate keys.
- Avoid logging sensitive payloads (bank data, webhook bodies, LLM prompts/responses beyond trace references).
- Store `reasoning_trace` JSONB with care; avoid PII in traces.

## 4. Integrations & Webhooks
- Verify signatures for all inbound webhooks (external providers, payment provider); reject invalid; log with trace IDs.
- Idempotent processing with event ID dedupe; dead-letter queue for failures.
- Expose webhook URLs only over HTTPS; regenerate secrets on rotation.

## 5. Payments (provider‑agnostic)
- Use provider‑hosted Checkout/Portal; never handle raw card data.
- Store minimal billing identifiers (customer/subscription IDs, status, timestamps, plan/price).
- Enforce access based on subscription state; deny actions when inactive.

## 6. LLM Safety
- All LLM calls go through a single helper; centralize redaction, logging, and parameter control.
- Strip/obfuscate sensitive fields before sending to LLM; log only references in traces.
- Detailed LLM safety and `reasoning_trace` policy live in `/docs/llm/safety.md`.

### 6.1 AI‑Specific Threats & Controls (summary)
These apply to any archetype that uses LLMs or RAG.

- **Prompt injection / jailbreak**
  - Treat all user input and retrieved content as **untrusted**.
  - Delimit untrusted blocks explicitly and never allow them to override system constraints.
  - Detect injection patterns; on suspicion → refuse or route to human review.
- **Outbound‑data policy**
  - Use **allowlists** for what may be sent to the model.
  - Mandatory redaction pipeline before every LLM call (PII/PHI/PCI/secrets).
  - Never send cross‑tenant data; never send raw billing/auth secrets.
- **Output validation**
  - Validate model outputs against strict schemas (types, enums, bounds).
  - Reject/repair invalid outputs; fall back to safe defaults or human checkpoints for high‑risk actions.
  - For agentic tools: validate tool arguments and enforce per‑tool scopes.
- **Trusted vs untrusted context (RAG)**
  - Retrieved documents are untrusted unless curated.
  - Keep retrieval tenant‑scoped; record only doc IDs in traces.
  - If grounding is required and context is insufficient → ask user or defer.

## 7. Audit & Events
- Log domain events to `EventLog` with `source_agent`; include user ID, tenant, timestamps, and relevant context.
- Provide read-only `/api/events` with pagination and filtering; protect by tenant/role.

## 8. Common Controls
- OWASP Top 10 coverage (SQLi, XSS, CSRF, IDOR, SSRF, etc.).
- Input validation on all external inputs; use allowlists for redirects/URLs.
- Backup/restore plan and monitoring/alerting for infra and queues.