docs/security-notes.md

# Security Notes

This is a **reference starter**, not a production system. Use these notes to harden before deploying.

## What is already safe-by-default

- **Tenant isolation**: the `tenant_id` column isolates data. The search query enforces `tenant_id = X OR visibility = public`.
- **Public vs restricted**: `restricted` items never leak to other tenants unless explicitly requested.
- **Trust classes**: retrieval can be gated by `max_rank` so low-trust content is excluded.
- **Retrieval logging**: every search is logged with filters and result IDs for audit.
- **No private credentials**: the repo contains no tokens, hostnames, or internal paths.
- **Synthetic data only**: all seed data is public-safe and fabricated.

## What you must add for production

1. **Authentication / authorization**
   - Add OAuth2, API keys, or mutual TLS.
   - Bind `tenant_id` to the authenticated user; never accept it from the request body.
   - Enable Postgres Row-Level Security (RLS) and tie policies to application-level user IDs.

2. **Input validation**
   - Limit `content` size (e.g. 100 KB) to prevent storage abuse.
   - Sanitize `metadata` JSON to reject unexpected keys.
   - Rate-limit writes per tenant.

3. **Network security**
   - Do not expose Postgres port `5432` to the internet.
   - Run the API and DB in a private VPC or behind a reverse proxy.
   - Use TLS for all client↔API and API↔Postgres connections.

4. **Secrets management**
   - Rotate `POSTGRES_PASSWORD` immediately; store it in a secrets manager (e.g. HashiCorp Vault, AWS Secrets Manager).
   - Never commit `.env` files with real passwords.

5. **Observability**
   - Alert on abnormal retrieval patterns (e.g. tenant A querying tenant B data).
   - Monitor `retrieval_logs` for signs of probing or data exfiltration.

6. **Backup and encryption**
   - Encrypt Postgres volumes at rest.
   - Schedule automated backups and test restores.

## Known limitations

- No authentication layer is included (by design, to keep the starter runnable).
- Placeholder embeddings are not semantically meaningful; swap in a real model before any serious use.
- HNSW index parameters (`m=16`, `ef_construction=64`) are starter defaults; tune for your data size and recall requirements.