# Business Rules — U3 HTTP Security Headers & CSP

---

## Decision Logic

```mermaid
graph TD
    start["Response starting"]
    exists{"Header already set<br/>by something else ?"}
    leave["Leave it untouched"]
    dev{"Environment is Development<br/>and header is HSTS ?"}
    skiphsts["Skip HSTS"]
    always{"Header is nosniff or HSTS ?"}
    apply["Apply"]
    html{"Content type is HTML ?"}
    skiphtml["Skip: not an HTML response"]

    start --> exists
    exists -->|yes| leave
    exists -->|no| dev
    dev -->|yes| skiphsts
    dev -->|no| always
    always -->|yes| apply
    always -->|no| html
    html -->|yes| apply
    html -->|no| skiphtml

    classDef entry fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
    classDef decision fill:#90cdf4,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef good fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    classDef neutral fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
    class start entry;
    class exists,dev,always,html decision;
    class apply good;
    class leave,skiphsts,skiphtml neutral;
```

Text alternative: an already-present header is never overwritten; HSTS is skipped in Development; `nosniff` and HSTS apply to every response while the remaining three apply only to HTML responses.

---

## Applicability Rules

| ID | Rule |
|---|---|
| **BR-U3-01** | `X-Content-Type-Options: nosniff` is applied to **every** response. |
| **BR-U3-02** | `Strict-Transport-Security` is applied to **every** response **except in Development**. |
| **BR-U3-03** | `Content-Security-Policy`, `X-Frame-Options` and `Referrer-Policy` are applied **only** to responses whose content type is HTML. |
| **BR-U3-04** | A header already present on the response is never overwritten. |
| **BR-U3-05** | Headers are written at response start, not before the pipeline continues, because the content type is unknown earlier. |
| **BR-U3-06** | The middleware is registered **before** static-file middleware, which short-circuits the pipeline. |
| **BR-U3-07** | Header application never throws into the response path. A configuration error is a startup failure, not a per-request one. |
| **BR-U3-08** | Every header except HSTS applies in Development, so a CSP violation surfaces during development. |
| **BR-U3-09** | Headers apply to error responses too — the middleware sits inside the exception handler. |

**Rationale for BR-U3-01**: `nosniff` exists to stop a browser guessing the type of a **non-HTML** resource. An uploaded `.txt` or `.svg` interpreted as HTML or JavaScript is the attack it prevents, so restricting it to HTML would remove it precisely where it works.

**Rationale for BR-U3-04**: a component that deliberately set a header — a download endpoint setting its own `Content-Disposition`-adjacent policy, for example — knows something this middleware does not. Overwriting would be silently destructive.

---

## Policy Content Rules

| ID | Rule |
|---|---|
| **BR-U3-10** | Exactly two policies exist, defined **in code**: `Strict` and `Relaxed`. |
| **BR-U3-11** | Path-to-policy assignment and allowed origins come from **configuration**, so a path or origin can be added without a code change. |
| **BR-U3-12** | `Strict` applies to `/admin`, `/api/v1` and `/health`. `Relaxed` is the default for everything else. |
| **BR-U3-13** | `Strict` sets `script-src 'self'` — **no `'unsafe-inline'` and no `'unsafe-eval'`**. This must not be relaxed. |
| **BR-U3-14** | `Strict` sets `style-src 'self' 'unsafe-inline'`. Documented exception, unavoidable — see below. |
| **BR-U3-15** | `Relaxed` is **enforcing**, not report-only, so SECURITY-04 is satisfied on every HTML-serving path. |
| **BR-U3-16** | `Relaxed` permits inline scripts and styles, and images, fonts and frames from any HTTPS origin — but **not** external script origins. |
| **BR-U3-17** | Both policies set `object-src 'none'` and `base-uri 'self'`. |
| **BR-U3-18** | Policy strings are composed once at startup and reused. |
| **BR-U3-19** | `X-Frame-Options` is `DENY` under `Strict` and `SAMEORIGIN` under `Relaxed`, with `frame-ancestors` set to match. |

**Rationale for BR-U3-14 — the one exception, and why it is not negotiable**: Radix UI positions dropdowns, dialogs and selects using inline `style` attributes whose values are recomputed per click, viewport and scroll position. CSP nonces apply only to `<style>` and `<script>` *elements*; inline `style` *attributes* are outside their scope entirely. The alternatives are `'unsafe-inline'` or `'unsafe-hashes'` with a hash per exact value — and the values are dynamic, so no finite set exists. No nonce- or hash-based variant leaves the admin UI functional.

The exception is bounded to `style-src`. Injected CSS can restyle a page; it cannot execute, because `script-src 'self'` still holds. The escalation path stays closed.

**Rationale for BR-U3-13**: this is the directive that matters. If it is ever relaxed, the value of the whole policy collapses — so it is stated as a rule rather than left as a default.

**Rationale for BR-U3-16**: "relaxed" must not mean "absent". Blocking external script origins keeps a genuine boundary while not surprising a website author with a broken layout. A third-party script requires adding its origin to configuration, which FR-09's contract documents.

---

## Startup Validation Rules

| ID | Rule |
|---|---|
| **BR-U3-20** | A configured policy name that is not a known policy causes startup to **fail**. No fallback. |
| **BR-U3-21** | Empty origin lists are a normal state. The policy simply becomes stricter. |
| **BR-U3-22** | When a Umami website ID is configured but its script origin is absent from the allowed origins, a **warning** is logged at startup naming the missing origin. |
| **BR-U3-23** | The permitted origins are logged at startup at informational level, so the log records what was actually allowed. |
| **BR-U3-24** | Headers can be disabled wholesale by configuration, for diagnosis. Disabling is logged as a warning. |

**Rationale for BR-U3-20** (fail closed, SECURITY-15): any fallback is either wrong or silently permissive. A typo in a path mapping should stop a deployment rather than quietly serve `/admin` under the relaxed policy.

**Rationale for BR-U3-22**: this catches a failure that is otherwise invisible — analytics configured, appearing to work, and silently blocked by the browser. Note it deliberately does **not** check for a Sentry origin: U4's tunnel keeps error reporting same-origin, so there is no Sentry origin to forget.

**Rationale for BR-U3-24**: a diagnostic escape hatch is worth having, but silently disabled security headers are worse than none, so switching them off announces itself.

---

## Error and Edge-Case Scenarios

| Scenario | Expected behaviour |
|---|---|
| Request for `/admin/dashboard`, HTML response | All five headers; `Strict` policy; `X-Frame-Options: DENY` |
| Request for `/admin/assets/app.js` | `nosniff` and HSTS only — not an HTML response |
| Request for `/`, website HTML | All five headers; `Relaxed` policy; `SAMEORIGIN` |
| Request for `/` on a fresh install, placeholder page | `Relaxed` policy. The placeholder's `<style>` block is permitted by `style-src 'unsafe-inline'` |
| Request for `/api/v1/Users`, JSON response | `nosniff` and HSTS only. `Strict` policy resolved but the CSP is not written to a JSON response |
| `503` from the availability gate, JSON `ProblemDetails` | `nosniff` and HSTS. The middleware sits before the gate, so the response still carries them |
| Unhandled exception, `ProblemDetails` response | Headers applied — the middleware is inside the exception handler |
| `304 Not Modified` | `nosniff` and HSTS. No body, so the HTML-only headers do not apply |
| Redirect from `/admin` to `/admin/` | `nosniff` and HSTS. A redirect has no HTML body |
| Running in Development | Every header except HSTS |
| No origins configured | Policies composed without them; stricter, and logged |
| Umami ID configured, origin missing | Warning at startup naming the origin |
| Configured policy name is `Stricct` | Startup fails with the unknown name |
| Headers disabled by configuration | No headers, and a warning logged |
| A downstream component already set `Referrer-Policy` | Its value is kept |

---

## Security Compliance for U3

| Rule | Status | Notes |
|---|---|---|
| SECURITY-04 | **Compliant** | All five headers present. HSTS `max-age` is one year with `includeSubDomains`. A CSP applies to **every** HTML-serving path, including the public website (BR-U3-15) — so no deviation is needed. `'unsafe-inline'` appears only in `style-src` under `Strict`, documented in BR-U3-14; `Relaxed` additionally permits inline scripts, documented in BR-U3-16 as a deliberate choice for content this repository does not author |
| SECURITY-09 | Compliant | No internal detail is exposed by any header |
| SECURITY-11 | **Improved** | Defence in depth: the CSP is a second layer behind output escaping, on both the admin UI and the website |
| SECURITY-15 | Compliant | Fails closed at startup on an unknown policy; never throws per request |

**No deviation recorded.** The earlier answer of "no CSP on the public website" was superseded by FU2 = C, which keeps SECURITY-04 satisfied outright rather than accepting a documented exception.