chore: tighten CORS configuration and enhance validation checks

- Updated CORS settings in the environment configuration to prevent wildcard origins in production and staging environments, allowing only explicit origins or an empty value for mobile-only APIs.
- Added validation logic to ensure that CORS_ORIGINS is not set to '*' in production or staging, raising an error if this condition is met.
- Introduced a new property to manage CORS credentials based on the origins list.
- Enhanced deployment scripts to check for CORS configuration compliance, ensuring safer API deployment practices.

Author: CephasTechOrg

backend/.env.example

@@ -37,8 +37,10 @@ AUTH_MOCK_OTP_CODE=123456
 
 # ── CORS ──────────────────────────────────────────────────────
 CORS_ORIGINS=*
-# On Render set to comma-separated allowed origins, e.g.:
-#   CORS_ORIGINS=https://yourapp.com,https://api.yourapp.com
+# Local dev: * is fine. On Render (production/staging) the API refuses to boot
+# with CORS_ORIGINS=* — use empty for mobile-only, or explicit origins for web:
+#   CORS_ORIGINS=
+#   CORS_ORIGINS=https://yourapp.com,https://admin.yourapp.com
 
 # ── Arkesel SMS ───────────────────────────────────────────────
 ARKESEL_BASE_URL=https://sms.arkesel.com

backend/app/core/config.py

@@ -75,6 +75,11 @@ def cors_origin_list(self) -> list[str]:
             return ["*"]
         return [o.strip() for o in raw.split(",") if o.strip()]
 
+    @property
+    def cors_allow_credentials(self) -> bool:
+        """Browsers reject credentials with a wildcard origin."""
+        return self.cors_origin_list != ["*"]
+
 
 @lru_cache
 def get_settings() -> Settings:

backend/app/core/security_headers.py

@@ -0,0 +1,35 @@
+"""Attach standard HTTP security headers to every response."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+_PRODUCTION_ENVS = frozenset({"production", "staging"})
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, *, app_env: str) -> None:
+        super().__init__(app)
+        self._app_env = app_env.strip().lower()
+
+    async def dispatch(
+        self, request: Request, call_next: Callable[[Request], Awaitable[Response]]
+    ) -> Response:
+        response = await call_next(request)
+        response.headers.setdefault("X-Content-Type-Options", "nosniff")
+        response.headers.setdefault("X-Frame-Options", "DENY")
+        response.headers.setdefault("Referrer-Policy", "strict-origin-when-cross-origin")
+        response.headers.setdefault(
+            "Permissions-Policy",
+            "geolocation=(), microphone=(), camera=()",
+        )
+        if self._app_env in _PRODUCTION_ENVS or request.url.scheme == "https":
+            response.headers.setdefault(
+                "Strict-Transport-Security",
+                "max-age=31536000; includeSubDomains",
+            )
+        return response

backend/app/core/startup_checks.py

@@ -38,5 +38,13 @@ def validate_settings_or_raise(settings: Settings) -> None:
         )
         raise ProductionConfigError(msg)
 
+    if settings.cors_origin_list == ["*"]:
+        msg = (
+            "CORS_ORIGINS must not be '*' in production or staging. "
+            "Use an empty value for mobile-only APIs, or a comma-separated "
+            "list of explicit browser origins."
+        )
+        raise ProductionConfigError(msg)
+
 
 __all__ = ["ProductionConfigError", "validate_settings_or_raise"]

backend/app/main.py

@@ -9,6 +9,7 @@
 from app.api.router import api_router
 from app.core.config import get_settings
 from app.core.logging import configure_logging
+from app.core.security_headers import SecurityHeadersMiddleware
 from app.core.startup_checks import validate_settings_or_raise
 
 
@@ -24,10 +25,11 @@ def create_app() -> FastAPI:
     settings = get_settings()
     app = FastAPI(title=settings.app_name, lifespan=lifespan)
 
+    app.add_middleware(SecurityHeadersMiddleware, app_env=settings.app_env)
     app.add_middleware(
         CORSMiddleware,
         allow_origins=settings.cors_origin_list,
-        allow_credentials=True,
+        allow_credentials=settings.cors_allow_credentials,
         allow_methods=["*"],
         allow_headers=["*"],
     )

backend/app/tests/test_security_headers.py

@@ -0,0 +1,16 @@
+"""Security headers middleware smoke tests."""
+
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+client = TestClient(app)
+
+
+def test_health_includes_security_headers() -> None:
+    r = client.get("/health")
+    assert r.status_code == 200
+    assert r.headers.get("X-Content-Type-Options") == "nosniff"
+    assert r.headers.get("X-Frame-Options") == "DENY"
+    assert r.headers.get("Referrer-Policy") == "strict-origin-when-cross-origin"
+    assert "geolocation=()" in (r.headers.get("Permissions-Policy") or "")

backend/app/tests/test_startup_checks.py

@@ -69,3 +69,39 @@ def test_staging_rejects_default_secret_but_allows_mock_otp() -> None:
             auth_mock_otp_code="123456",
         )
     )
+
+
+def test_production_rejects_wildcard_cors() -> None:
+    with pytest.raises(ProductionConfigError, match="CORS_ORIGINS"):
+        validate_settings_or_raise(
+            Settings(
+                app_env="production",
+                secret_key="production-secret-key-value",
+                auth_mock_otp_code=None,
+                payment_config_encryption_key="payment-encryption-key",
+                cors_origins="*",
+            )
+        )
+
+
+def test_staging_rejects_wildcard_cors() -> None:
+    with pytest.raises(ProductionConfigError, match="CORS_ORIGINS"):
+        validate_settings_or_raise(
+            Settings(
+                app_env="staging",
+                secret_key="staging-secret-key-value",
+                cors_origins="*",
+            )
+        )
+
+
+def test_production_allows_empty_cors_for_mobile_only() -> None:
+    validate_settings_or_raise(
+        Settings(
+            app_env="production",
+            secret_key="production-secret-key-value",
+            auth_mock_otp_code=None,
+            payment_config_encryption_key="payment-encryption-key",
+            cors_origins="",
+        )
+    )

backend/scripts/check_deploy_env.py

@@ -62,13 +62,14 @@ def main() -> int:
         else:
             _ok("PAYSTACK_SECRET_KEY_LIVE is set")
 
-        cors = settings.cors_origins
-        if "*" in cors:
-            _warn("CORS_ORIGINS includes '*' — tighten before any browser client.")
-        elif cors:
-            _ok(f"CORS_ORIGINS configured ({len(cors)} origin(s))")
+        cors = settings.cors_origins.strip()
+        if cors == "*":
+            print("  FAIL  CORS_ORIGINS is '*' — boot check rejects this in production.")
+            return 1
+        if cors:
+            _ok(f"CORS_ORIGINS configured ({len(settings.cors_origin_list)} origin(s))")
         else:
-            _warn("CORS_ORIGINS empty — OK for mobile-only; set if web clients exist.")
+            _ok("CORS_ORIGINS empty — mobile-only API (no browser CORS)")
 
     print("\nManual steps (cannot verify from env alone):")
     print("  • Run: alembic upgrade head  (migrations 020–023)")

docs/audits/CODEBASE_AUDIT.md

@@ -3,7 +3,7 @@
 **Product:** SikaBoafo (BizTrackGh) — offline-first merchant OS for Ghana  
 **Stack:** Flutter · FastAPI · PostgreSQL · Paystack  
 **Last reviewed:** May 2026  
-**Test snapshot:** Backend 157/157 pytest pass · Mobile tests pass
+**Test snapshot:** Backend 161/161 pytest pass · Mobile tests pass
 
 This is the **single audit document** for the repo. Use it to see what is wrong, what was already fixed, and what to tackle next. Older notes (e.g. root `debt_payment_flow_audit.md`) are folded in here; prefer **this file** for planning work.
 
@@ -107,12 +107,11 @@ When you fix an item, change its status here and tick the checklist box.
 
 | Field | Value |
 |-------|--------|
-| **Status** | `open` |
-| **Severity** | Medium (when web clients exist) |
-| **What's happening** | `cors_origins` defaults to `*` with `allow_credentials=True`. |
-| **Why it matters** | Fine for mobile-only MVP; risky if you add a browser admin or web app. |
-| **Where** | `backend/app/main.py`, `backend/app/core/config.py` |
-| **Fix** | Set explicit origins per environment in Render/env. |
+| **Status** | `done` |
+| **Severity** | — |
+| **What's happening** | Boot check rejects `CORS_ORIGINS=*` in **production** and **staging**; empty list allowed for mobile-only. Local dev keeps `*`. |
+| **Fix applied** | `startup_checks.py`; `cors_allow_credentials=False` when wildcard; `.env.example` + deploy script updated. |
+| **Where** | `backend/app/main.py`, `backend/app/core/config.py`, `backend/app/core/startup_checks.py` |
 
 ### AUTH-08 · No API-wide rate limiting (sync done — AUTH-08b)
 
@@ -446,10 +445,10 @@ When you fix an item, change its status here and tick the checklist box.
 
 | Field | Value |
 |-------|--------|
-| **Status** | `open` |
-| **Severity** | Low |
-| **What's happening** | FastAPI app does not set security headers middleware. |
-| **Fix** | Add middleware or terminate at CDN/load balancer. |
+| **Status** | `done` |
+| **Severity** | — |
+| **What's happening** | `SecurityHeadersMiddleware` sets `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`; HSTS on production/staging and HTTPS requests. |
+| **Fix applied** | `backend/app/core/security_headers.py`, wired in `main.py`. |
 
 ### OPS-03 · Webhook endpoint public by design
 
@@ -527,7 +526,7 @@ Items marked *(boot)* are enforced at API startup in production/staging — stil
 # Master Checklist C — Do better (quality & growth)
 
 - [ ] **AUTH-04** — Migrate JWT to maintained library (`PyJWT`)
-- [ ] **AUTH-07** — Tighten CORS per environment
+- [x] **AUTH-07** — Tighten CORS per environment
 - [ ] **SYNC-01** — Incremental server pull / sync cursors
 - [x] **SYNC-03** — UI to review/retry **dead** sync queue rows
 - [ ] **MOB-02** — Refactor large debt/payment widgets for testability
@@ -536,7 +535,7 @@ Items marked *(boot)* are enforced at API startup in production/staging — stil
 - [ ] **ARCH-02** — Wire Redis for sessions/rate limits or remove from architecture docs
 - [ ] **ARCH-03** — Admin console or remove from public architecture
 - [ ] **REPO-01** — Clean scratch artifacts from main branch
-- [ ] **OPS-02** — Security headers at edge or in FastAPI
+- [x] **OPS-02** — Security headers at edge or in FastAPI
 
 ---
 
@@ -550,7 +549,7 @@ Items marked *(boot)* are enforced at API startup in production/staging — stil
 | AUTH-04 | Custom JWT | open |
 | AUTH-05 | Mock OTP in prod | done |
 | AUTH-06 | Default secret key | done |
-| AUTH-07 | CORS `*` | open |
+| AUTH-07 | CORS `*` | done |
 | AUTH-08 | OTP + sync rate limits | done |
 | AUTH-08b | Sync rate limit | done |
 | PAY-01 | PaymentService size | done |
@@ -581,7 +580,7 @@ Items marked *(boot)* are enforced at API startup in production/staging — stil
 | ARCH-03 | Admin stub | open |
 | ARCH-04 | Thin routers | done |
 | OPS-01 | Prod checklist | partial |
-| OPS-02 | Security headers | open |
+| OPS-02 | Security headers | done |
 | OPS-03 | Webhook HMAC | done |
 | REPO-01 | Scratch files | open |
 | REPO-02 | Audit consolidation | done |
@@ -601,8 +600,9 @@ Items marked *(boot)* are enforced at API startup in production/staging — stil
 9. ~~**DEBT-03** — Cancel invalidates pending Paystack payment (regression test)~~ ✓ done  
 10. ~~**DEBT-09** — Block online pay until debt synced + clear messaging~~ ✓ done  
 11. ~~**SYNC-02** — Merchant-visible conflict resolution~~ ✓ done  
+12. ~~**OPS-02 + AUTH-07** — Security headers + production CORS hardening~~ ✓ done  
 
-**Next suggested:** MOB-02 (widget refactors), OPS-02 (security headers), or SYNC-01 (incremental pull).
+**Next suggested:** REPO-01 (scratch cleanup), MOB-02 (widget refactors), or SYNC-01 (incremental pull).
 
 ---
 
@@ -611,6 +611,7 @@ Items marked *(boot)* are enforced at API startup in production/staging — stil
 | Path | Notes |
 |------|--------|
 | `docs/operations/PRODUCTION_DEPLOY_CHECKLIST.md` | OPS-01 deploy runbook |
+| `backend/app/core/security_headers.py` | OPS-02 response headers |
 | `backend/scripts/check_deploy_env.py` | OPS-01 pre-flight env validation |
 | `debt_payment_flow_audit.md` (repo root) | Historical debt audit — see header for pointer here |
 | `docs/auth/pin-and-otp-flow.md` | Auth flow design |