# Security Architecture

## Principles

1. Least privilege per role and service token scope.
2. Secrets only in environment / secret stores — never in git.
3. Tenant isolation on every business query.
4. Auditable business actions (audit log).
5. TLS at the edge for all public hosts.

## Authentication Surfaces

| Surface | Mechanism |
| --- | --- |
| Platform / tenant staff | Keycloak OIDC JWT (RS256) |
| Local OTP (Core) | HS256 JWT after SMS verify |
| Service-to-service | Internal service token (hashed at rest) |
| Public tenant site | Unauthenticated read of public theme/site data only |

## Token Rules

- Frontend sends `Authorization: Bearer <token>`.
- Services validate via shared JWT helpers (`shared/auth/jwt.py`).
- Internal tokens carry scopes; callers must hold required scope.

## Edge

Nginx enforces HTTPS for platform hosts; tenant hosts redirect to HTTPS when SSL map marks them ready. ACME challenge paths remain HTTP.

## Data Protection

- Passwords only in Keycloak (not Core).
- OTP codes are short-lived (`OTP_EXPIRE_SECONDS`).
- Token hashes stored for internal service tokens — raw tokens never persisted.

## Related Documents

- [Identity Architecture](identity-architecture.md)
- [Authorization Architecture](authorization-architecture.md)
- [ADR-004](adr/ADR-004.md) · [ADR-005](adr/ADR-005.md) · [ADR-009](adr/ADR-009.md)
- [SSL](../deployment/ssl.md)