# Security review checklist (pre-merge)

Use this checklist before merging features that touch **auth, data, background processing, exports, or integrations**. It aligns with `PROJECT_RULES.md` (Form Requests, Policies, modular boundaries).

Completing the checklist is the responsibility of the **author** and **reviewer**; exceptions require written rationale in the PR.

---

## Tenant isolation

- [ ] All queries on tenant-scoped models respect **`TenantContext`** / `BelongsToTenant` / explicit `tenant_id` filters where appropriate.
- [ ] No route resolves resources **only** by primary key without tenant guard (ID guessing attacks).
- [ ] Admin / cross-tenant paths are **explicitly** authorized (`Gate`, policies, middleware) and audited.

---

## Authorization

- [ ] Every new **mutating** HTTP action uses **Form Request** validation (no ad-hoc `$request->validate()` in controllers).
- [ ] Policies or gates exist for new abilities; **deny by default** for sensitive modules (HR, payroll, exports).
- [ ] API token routes enforce **scopes**; session routes enforce **permissions** consistently.

---

## Download security

- [ ] File downloads use **authorization** on the owning model (employee document, export artifact, etc.).
- [ ] No **path traversal** or user-controlled absolute paths.
- [ ] Responses set sensible **cache** and **content-disposition** headers where downloads are sensitive.

---

## Queue safety

- [ ] Jobs set **`TenantContext`** (or equivalent explicit tenant id) before tenant-scoped work.
- [ ] Jobs are **safe to retry** (idempotency or dedupe keys where duplicates cause financial/legal impact).
- [ ] Failures persist enough context to **debug** without leaking secrets in logs.

---

## Retry safety (HTTP integrations & webhooks)

- [ ] Outbound retries use **bounded** backoff and **dead-letter** semantics where implemented.
- [ ] Inbound idempotency uses **persistent** keys for financial or biometric ingestion — not cache-only.
- [ ] Signature / timestamp rules documented when adding new **signed** channels.

---

## Auditability

- [ ] Security-sensitive and compliance-sensitive actions emit **audit** or **API audit** records with actor, tenant, target, and correlation id where available.
- [ ] Integration events remain **immutable** once stored (`docs/governance/event-contracts.md`).

---

## Secrets & configuration

- [ ] No secrets committed; `.env` / vault patterns followed.
- [ ] New config keys documented with safe defaults.

---

## References

- `docs/governance/schema-evolution.md`
- `docs/governance/incident-response.md`
- `docs/governance/compliance-readiness.md`