# Security

## Access control

- **Sign-in:** Filament login with throttling and lockout. Every sign-in, failed sign-in and lockout is
  written to the audit log and `storage/logs/security-*.log`. If the e-mail field contains something that
  isn't an e-mail address (for example a password typed in the wrong box), it is stored as `(invalid)`.
- **Passwords:** at least 12 characters with mixed case, numbers and symbols. In production, passwords
  found in known data breaches are rejected (`PASSWORD_CHECK_UNCOMPROMISED`). Suspended accounts are
  signed out on their next request.
- **Roles and permissions:** 10 default roles. The full matrix is in
  [ROLES_AND_PERMISSIONS.md](ROLES_AND_PERMISSIONS.md), generated from the code. Users can't grant a
  permission they don't hold themselves.
- **Row-level visibility:** every contract query goes through `Contract::visibleTo()`. Users see only their
  own and assigned contracts, plus their department's or all contracts depending on their permissions.
  This applies to lists, reports, exports, the dashboard, the calendar, the audit log and downloads.
- **Financial amounts** require `contracts.view_financials`, and the history and audit views hide them
  otherwise.
- **Super Admin only, regardless of permissions:**
  - Permanent deletion of contracts.
  - Backups: an archive contains every secret and document.
  - The AI provider, AI API keys and turning AI on.
- **Organizations** are never permanently deleted.

## Data protection

- **Documents** are stored outside the web root. They are streamed only through signed, time-limited
  links, and the server checks the user's permission and contract visibility on each download.
- **Report files** can be downloaded only by the user who generated them.
- **Settings** (API tokens, keys) are stored encrypted in `system_settings`. They are write-only in the
  UI and never sent back to the browser.
- **Sessions** are stored in the database and encrypted at rest. Cookies are `HttpOnly`, `SameSite=Lax`,
  and `Secure` in production.
- **Backups** are AES-256 encrypted. See [BACKUP_RESTORE.md](BACKUP_RESTORE.md).
- **Uploads** are validated by real file content and extension. Files are renamed on storage (the logo
  always gets a server-chosen `.png`/`.jpg` name), and duplicates are detected by hash.
- **AI extraction** sends document content to the chosen provider only while the AI feature is on.
  With AI off, extraction runs entirely on your server.

## Audit log

The audit log records:
- Contract views, creation, edits (before and after values), status changes, archiving and restoring.
- Ownership transfers, deletions and permanent deletions.
- Financial changes, document and report downloads, report exports and e-mails.
- Role and permission changes, user creation and deletion.
- Settings changes and backup runs and downloads.

Values that look like secrets are masked (`••••••`). The app refuses to edit or delete audit entries. For
database-level protection, see [DEPLOYMENT.md](DEPLOYMENT.md) §3.

## Browser protection

Every response carries these headers:
- A same-origin Content-Security-Policy: no third-party scripts, `frame-ancestors 'self'` and
  `object-src 'none'`.
- `X-Frame-Options`, `X-Content-Type-Options: nosniff`, `Referrer-Policy`, `Permissions-Policy` and
  `Cross-Origin-Opener-Policy`.
- HSTS on HTTPS in production.

Filament/Livewire need `'unsafe-inline'`/`'unsafe-eval'` for scripts. The policy still blocks loading
scripts from any other origin, and Blade escapes all output.

## Logs

Logs are written daily under `storage/logs/`:

| Log | Kept for |
|---|---|
| `security` | 90 days |
| `backups` | 90 days |
| `queue` (every finally failed job) | 60 days |
| `email` | 60 days |
| `whatsapp` | 60 days |
| `telegram` | 60 days |
| `notifications` | 60 days |
| `reports` | 60 days |
| `ai` | 60 days |
| `ocr` | 60 days |
| `scheduler` | 60 days |
| `laravel` | 14 days |

Bot tokens and `key=value` secrets are redacted before anything is written to the queue log.

## Checks done in Phase 10

- `composer audit` and `npm audit`: no known vulnerabilities (2026-10-04).
- Security reviews after every phase. All high and medium findings are fixed; see the git history.
- Test suite: 549 tests, 81.8% code coverage. It includes tests for privilege escalation, visibility, the
  approval-bypass guard, download authorization and secret masking.

## Operating rules

1. Keep `APP_DEBUG=false` in production. System health shows a red line if it's on.
2. Rotate any credential that may have been exposed. Settings changes are audited.
3. Give people the lowest role that fits their work. Review users and roles every quarter (**Users** and
   **Roles & permissions**; filter the audit log by *User roles changed*).
4. Keep Ubuntu updates automatic, and run `composer audit` with each release.
5. Store `APP_KEY` and `BACKUP_ARCHIVE_PASSWORD` off the server.

## Reporting a problem

If you suspect unauthorized access:
1. Change the affected passwords, and in **Users** suspend the account. That signs it out everywhere.
2. Rotate the API keys in the Settings Center or **Delivery channels**.
3. Export the audit log for the period and review `storage/logs/security-*.log`.
4. If data may have been changed, follow [BACKUP_RESTORE.md](BACKUP_RESTORE.md) ("recover a single
   document or record").
