# Security Guide

> Audience: administrators, developers, DevOps and support leads. This guide describes the required operating standard for the Proposal Management System. It must be followed alongside the organization's security policy.

## 1. Protect credentials and secrets

- Never commit `.env`, tokens, passwords, private keys, Pusher secrets, Gemini keys, payment identifiers, or production database credentials.
- A value committed to Git must be treated as exposed even if the repository is private. Rotate/revoke it at the provider first, then remove it from the repository.
- Keep `apps/backend/.env.example` as a template only: use empty placeholders such as `GEMINI_API_KEY=`; never use valid values.
- Store production secrets in the approved deployment secret manager or encrypted CI secret store. Give read access only to the service/account that needs it.
- Do not send secrets through chat, ticket attachments, browser URLs, screenshots, activity logs or frontend bundle variables.
- Rotate secrets on staff departure, suspected exposure, provider compromise, or the rotation schedule set by the security owner.

## 2. Account and access management

- Production user creation is an Admin-controlled process. Public self-registration must remain disabled unless a reviewed invite and approval workflow exists.
- Assign the smallest permission set necessary. Do not use the admin role as a convenience workaround.
- Review user, role, shift and category access at least quarterly and immediately after role changes or offboarding.
- Disable the account and revoke all Sanctum tokens immediately when a user leaves or should lose access.
- Ensure every protected API route uses both authentication and the active-user check, then the required permission.
- Protect lookup and upload endpoints too. “Read-only” data can expose client/account information, and uploads consume storage and provider cost.

## 3. Authentication standard

- Enforce a strong password policy and offer a secure password-reset flow.
- Apply rate limits to login, reset request/reset confirmation, file upload and AI/OCR endpoints.
- Return generic reset responses so a caller cannot determine whether an email address is registered.
- Use HTTPS for every production request. Do not terminate TLS only at an untrusted network boundary.
- Sanctum bearer tokens must be sent only in the `Authorization` header. Never put a token in a query parameter.
- Prefer token expiry, device/session identification, and a revoke-all-sessions option for sensitive incidents.

## 4. Data and file protection

- Client conversations, screenshots, proposal files, payment information and export files are confidential business data.
- Upload only necessary evidence. Redact unrelated personal data before upload whenever possible.
- Validate file type, actual MIME/content, size, extension and image dimensions. Store uploads outside executable paths; serve them through authorization-aware URLs where files are sensitive.
- Malware-scan uploaded files before users download them. SVG and office documents need extra caution because they can carry active content.
- Apply retention periods to screenshots, exports and deleted records. Use a documented legal/business exception process before retaining data longer.
- Encrypt backups and confirm restores using a scheduled non-production restore test.

## 5. Production configuration

- Set `APP_ENV=production`, `APP_DEBUG=false`, a non-debug log level, and a unique application key in production.
- Restrict `CORS_ALLOWED_ORIGINS` to the actual frontend origin(s); do not use `*` in production unless a security owner explicitly approves the risk.
- Expose only the reverse proxy publicly. MySQL, queues and admin ports must not be internet-accessible.
- Run containers/services with least privilege and keep base images and dependencies patched.
- Keep production environment files readable only by the deployment identity and service account.

## 6. External providers and AI/OCR

- Set connection/read timeouts, retries with exponential backoff, error handling and circuit breaking for Upwork, ERP, Gemini and Pusher calls.
- Queue slow extraction, scraping and export work. Protect expensive endpoints with rate limits and quotas.
- Log provider status, duration and cost metrics without logging source screenshots, prompts, client messages, tokens or keys.
- Human-review AI-extracted job/lead details before they change a business lifecycle status.
- Maintain a manual workflow for provider outage; do not make client work dependent on a single AI response.

## 7. Logging, monitoring and incident response

- Activity logs should record business actions with actor, time, target and safely-redacted context. They must not contain passwords, tokens or raw payment details.
- Send application errors and queue failures to monitored, access-controlled logging. Use correlation IDs to trace a request across frontend, API and worker.
- Alert on repeated login failures, abnormal upload volume, repeated authorization failures, 5xx spikes, queue failures, backup failures and unexpected provider cost.
- For a suspected credential leak: revoke/rotate the secret, identify affected systems, invalidate tokens if relevant, preserve evidence, deploy the fix, and document the incident timeline.
- For suspected unauthorized account use: disable the user, revoke tokens, review activity logs, reset credentials as needed, and notify the security owner.

## 8. Security release checklist

Before production deployment, verify:

- [ ] No secrets or `.env` files are included in Git changes.
- [ ] `APP_DEBUG=false`; CORS origin list is restricted.
- [ ] Database is not publicly exposed and backup exists.
- [ ] Migration and rollback plan are reviewed.
- [ ] API authorization tests pass for admin, valid user, disabled user and unauthorized user.
- [ ] File upload and export access are tested.
- [ ] Dependencies have been installed from lockfiles and scanned.
- [ ] Logs/alerts and provider keys are configured without exposing sensitive values.