AI_template/docs/backend/security.md

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.