# Security hardening and operations

## Mandatory production controls

- Replace `LaravelEnvelopeEncryption` with an AWS KMS, GCP KMS, Azure Key Vault, or HSM-backed implementation. Production fails closed unless `GATEWAY_ALLOW_LOCAL_ENCRYPTION=false` is explicitly overridden for non-production use.
- Keep database and Redis on private networks. Enforce TLS, least-privilege database roles, encrypted backups, PITR, and tested restoration.
- Put the API behind a managed WAF/load balancer. Permit provider webhook source ranges where the provider publishes stable ranges, but never rely on IP allowlisting instead of signatures.
- Run separate cloud projects/accounts and separate wallets, credentials, databases, Redis clusters, and signing infrastructure for sandbox and live.
- Never put seed phrases or private keys in Laravel, the database, source control, logs, ordinary environment files, job payloads, or error tracking.

## Observability metrics

Instrument these names in the selected metrics backend:

- `payment_detection_latency_seconds`
- `confirming_payments_stuck`
- `provider_webhook_verification_failures`
- `merchant_webhook_failure_rate`
- `queue_lag_seconds`
- `ledger_posting_failures`
- `reconciliation_difference_atomic`
- `payout_broadcast_unknown`
- `provider_error_rate`

The included operations jobs and database tables provide collection points. Connect them to OpenTelemetry/Prometheus, CloudWatch, Datadog, or another production backend.

## Database immutability

The MySQL 8.4 migration installs triggers that reject `UPDATE` and `DELETE` on ledger entries and deletion of ledger transactions. Corrections must be posted as reversal transactions. Use a separate migration/owner role for schema changes so the normal application role cannot disable triggers.

## Recommended CI gates

1. Pint formatting check.
2. Larastan/PHPStan at level 8 or higher.
3. Pest/PHPUnit unit, feature, concurrency and property tests.
4. Composer dependency audit.
5. Semgrep or equivalent SAST.
6. Gitleaks secret scanning.
7. Trivy image and filesystem scanning.
8. OpenAPI lint and contract tests.
9. External penetration test before mainnet.
