# Security Hardening Epic (Q4 2025)

## Goal
Raise the baseline security posture across guest APIs, checkout, media storage, and identity flows so the platform can scale multi-tenant traffic with auditable, revocable access.

## Workstreams

1. **Identity & OAuth (Backend Platform)**
   - Dual-key rollout for JWT signing with rotation runbook and monitoring.
   - Refresh-token revocation tooling (per device/IP) and anomaly alerts.
   - Device fingerprint/subnet allowances documented and configurable.
   - **Tickets**
     - `SEC-IO-01` — Document PAT revocation/rotation playbook (Week 1). Include scripted revocation of stale tokens and guidance for forced re-login. (Replace legacy OAuth key rotation runbook).
     - `SEC-IO-02` — Build refresh-token management UI + audit logs (Week 2). *(Filament console + audit trail added 2025-10-23)*
     - `SEC-IO-03` — Implement subnet/device matching configuration & tests (Week 3).

2. **Guest Join Tokens (Guest Platform)**
   - Store hashed tokens with irreversible lookups; migrate legacy data.
   - Add per-token usage analytics, alerting on spikes or expiry churn.
   - Extend gallery/photo rate limits (token + IP) and surface breach telemetry in storage dashboards.
   - **Tickets**
    - `SEC-GT-01` — Hash join tokens + data migration script (Week 1).
    - `SEC-GT-02` — Implement token analytics + Grafana dashboard (Week 2). *(Logging + Filament summaries delivered 2025-10-23; monitoring dashboard still pending)*
    - `SEC-GT-03` — Tighten gallery/photo rate limits + alerting (Week 3).

3. **Public API Resilience (Core API)**
   - Serve signed asset URLs instead of raw storage paths; expire appropriately.
   - Document incident response runbooks and playbooks for abuse mitigation.
   - Add synthetic monitors for `/api/v1/gallery/*` and upload endpoints.
   - **Tickets**
     - `SEC-API-01` — Signed URL middleware + asset migration (Week 1).
     - `SEC-API-02` — Incident response playbook draft + review (Week 2). *(Runbook: `docs/deployment/public-api-incident-playbook.md`, added 2025-10-23)*
     - `SEC-API-03` — Synthetic monitoring + alert config (Week 3).

4. **Media Pipeline & Storage (Media Services)**
   - Integrate antivirus/EXIF scrubbers and streaming upload paths to avoid buffering.
   - Verify checksum integrity on hot → archive transfers with alert thresholds.
   - Surface storage target health (capacity, latency) in Super Admin dashboards.
   - **Tickets**
    - `SEC-MS-01` — AV + EXIF scrubber worker integration (Week 1). *(Job: `ProcessPhotoSecurityScan`, queue: `media-security`)*
    - `SEC-MS-02` — Streaming upload refactor + tests (Week 2). *(Requirements draft: `docs/todo/media-streaming-upload-refactor.md`, 2025-10-23)*
     - `SEC-MS-03` — Checksum validation + alert thresholds (Week 3).
     - `SEC-MS-04` — Storage health widget in Super Admin (Week 4).

5. **Payments & Webhooks (Billing)**
   - Link Paddle webhooks to checkout sessions with idempotency locks.
   - Add signature freshness validation + retry policies for provider outages.
   - Pipe failed capture events into credit ledger audits and operator alerts.
   - **Tickets**
     - `SEC-BILL-01` — Checkout session linkage + idempotency locks (Week 1).
     - `SEC-BILL-02` — Signature freshness + retry policy implementation (Week 2).
     - `SEC-BILL-03` — Failed capture notifications + ledger hook (Week 3).

6. **Frontend & CSP (Marketing Frontend)**
   - Replace `unsafe-inline` allowances with nonce/hash policies for Stripe + Matomo.
   - Gate analytics script injection behind consent with localised disclosures.
   - Broaden cookie banner layout to surface GDPR/legal copy clearly.
   - **Tickets**
     - `SEC-FE-01` — CSP nonce/hashing utility + rollout (Week 1).
     - `SEC-FE-02` — Consent-gated analytics loader refactor (Week 2).
     - `SEC-FE-03` — Cookie banner UX update + localisation (Week 3).

## Deliverables
- Updated docs (`docs/prp/09-security-compliance.md`, runbooks) with ownership & SLAs.
- Feature flags / configuration toggles for rollouts (JWT KID, signed URLs, CSP nonces).
- Monitoring dashboards + alerting coverage per workstream.
- Integration and Playwright coverage validating the hardened flows.
