# Business Logic Model — U3 HTTP Security Headers & CSP

**Unit**: U3 HTTP Security Headers & CSP
**Requirements**: FR-18

---

## 1. Scope of the Logic

Normally these headers come from nginx or IIS configuration. NFR-01 forbids relying on server configuration, so the application must supply them itself — which turns a configuration file into request-processing logic with three decisions per response:

1. **Which policy** applies to this request path
2. **Which headers** apply to this response, based on its content type
3. **Whether** headers apply at all in this environment

---

## 2. Header Application Flow

```mermaid
graph TD
    req["Incoming request"]
    enabled{"Headers enabled ?"}
    skip["Continue without headers"]
    resolve["Resolve policy name<br/>from request path"]
    hook["Register response-start callback"]
    next["Continue pipeline"]
    start["Response starting"]
    always["Apply always-headers:<br/>X-Content-Type-Options<br/>plus HSTS outside Development"]
    ishtml{"Content type is HTML ?"}
    htmlonly["Apply HTML-only headers:<br/>Content-Security-Policy<br/>X-Frame-Options<br/>Referrer-Policy"]
    done["Response sent"]

    req --> enabled
    enabled -->|no| skip
    enabled -->|yes| resolve
    resolve --> hook
    hook --> next
    next --> start
    start --> always
    always --> ishtml
    ishtml -->|yes| htmlonly
    ishtml -->|no| done
    htmlonly --> done

    classDef entry fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
    classDef decision fill:#90cdf4,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef step fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    classDef neutral fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
    class req,start entry;
    class enabled,ishtml decision;
    class resolve,hook,next,always,htmlonly step;
    class skip,done neutral;
```

Text alternative: the policy for the path is resolved when the request arrives, but headers are written at response start — because the content type, which decides whether the HTML-only headers apply, is not known any earlier.

**Why the work is split across two moments**: path matching happens once per request, cheaply, before the pipeline continues. Content-type inspection can only happen at response start. Doing both at response start would repeat path matching on every static asset; doing both early would force an all-or-nothing choice on header scope.

**Why registration must precede static files**: static-file middleware short-circuits the pipeline. Anything registered after it never observes a static response — and static responses are exactly what the public website consists of.

---

## 3. Per-Header Scoping

Per FU1 = A, scope is decided per header rather than uniformly.

| Header | Applies to | Reason |
|---|---|---|
| `X-Content-Type-Options: nosniff` | **All** responses | Exists specifically to stop MIME-sniffing of non-HTML resources. Restricting it to HTML would remove it exactly where it does its job |
| `Strict-Transport-Security` | **All** responses, **outside Development only** | A host-level transport directive, not a page directive. A visitor whose first request is an asset would otherwise never receive it |
| `Content-Security-Policy` | HTML responses only | Meaningless on an image or a script file |
| `X-Frame-Options` | HTML responses only | Governs framing of documents |
| `Referrer-Policy` | HTML responses only | Governs navigation and resource referrers from a document |

**HSTS and Development** (Q3 = A): browsers remember HSTS per host, for a long time, and `localhost` is shared with every other local project. Sending it during development would affect unrelated work and is awkward to undo. Every other header **does** apply in Development, so a CSP violation surfaces while developing rather than in production.

---

## 4. Policy Selection

```mermaid
graph TD
    path["Request path"]
    admin{"Starts with /admin ?"}
    api{"Starts with /api/v1 ?"}
    health{"Is /health ?"}
    strict["Strict policy"]
    relaxed["Relaxed policy"]

    path --> admin
    admin -->|yes| strict
    admin -->|no| api
    api -->|yes| strict
    api -->|no| health
    health -->|yes| strict
    health -->|no| relaxed

    classDef entry fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
    classDef decision fill:#90cdf4,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef strictnode fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    classDef relaxednode fill:#fbd38d,stroke:#c05621,stroke-width:1px,color:#000;
    class path entry;
    class admin,api,health decision;
    class strict strictnode;
    class relaxed relaxednode;
```

Text alternative: paths under `/admin`, `/api/v1` and `/health` get the strict policy; everything else — the public website and the placeholder page — gets the relaxed policy.

The mapping itself is configuration (FU2 = A), so a path can be added without code changes. The two policies are defined in code, so a misconfiguration can misroute a path but cannot invent a broken policy.

---

## 5. What Each Policy Permits

### Strict — `/admin`, `/api/v1`, `/health`

| Directive | Value | Reason |
|---|---|---|
| `default-src` | `'self'` | Deny by default |
| `script-src` | `'self'` | **No `'unsafe-inline'`, no `'unsafe-eval'`.** This is where XSS risk actually lives, and it stays closed |
| `style-src` | `'self' 'unsafe-inline'` | Required — see below |
| `img-src` | `'self' data:` | `data:` covers inlined icons in the built bundle |
| `font-src` | `'self'` | Fonts ship with the bundle |
| `connect-src` | `'self'` + configured origins | Same-origin API. The Sentry tunnel (U4) keeps error reporting same-origin too |
| `frame-ancestors` | `'none'` | Matches `X-Frame-Options: DENY` for modern browsers |
| `base-uri` | `'self'` | Prevents base-tag injection redirecting relative URLs |
| `form-action` | `'self'` | Prevents form hijacking |
| `object-src` | `'none'` | No plugins |

**`style-src 'unsafe-inline'` — why it is unavoidable** (FU1 = A):

Radix UI positions dropdowns, dialogs and selects by writing inline `style` attributes such as `style="transform: translate(...)"`, recalculated per click, viewport and scroll position.

CSP nonces apply only to `<style>` and `<script>` **elements** — inline `style` **attributes** are outside their reach entirely. The only mechanisms that can permit them are `'unsafe-inline'`, or `'unsafe-hashes'` with a hash per exact attribute value, and those values are dynamic so no finite set exists. There is therefore no nonce- or hash-based variant that leaves the admin UI functional.

The exception is contained: it applies to `style-src` only. Injected CSS can restyle a page, but `script-src 'self'` still prevents execution of injected script, which is the actual escalation path.

### Relaxed — the public website

Per FU2 = C, the website receives an **enforcing** CSP rather than none, so SECURITY-04 is satisfied on every HTML-serving path.

| Directive | Value | Reason |
|---|---|---|
| `default-src` | `'self'` | Deny by default |
| `script-src` | `'self' 'unsafe-inline'` | A website author may use inline scripts and has never seen this policy |
| `style-src` | `'self' 'unsafe-inline'` | Same |
| `img-src` | `'self' data: https:` | Images from any HTTPS source — commonplace on a marketing site |
| `font-src` | `'self' data: https:` | Web fonts from any HTTPS source |
| `connect-src` | `'self'` + configured origins | Includes the Umami origin when configured |
| `frame-src` | `'self' https:` | Embeds such as maps and video |
| `frame-ancestors` | `'self'` | Matches `X-Frame-Options: SAMEORIGIN` |
| `base-uri` | `'self'` | Retained — cheap and breaks nothing |
| `object-src` | `'none'` | Retained |

**What "relaxed" deliberately still blocks**: an external `script-src`. A website author who needs a third-party script must have its origin added to configuration — which the website contract (FR-09) documents. That keeps the policy from being a rubber stamp while still not surprising anyone with a broken layout.

**Note on `'unsafe-inline'` and external scripts**: when a source list contains `'unsafe-inline'`, browsers honour it *and* the listed origins. Adding an origin therefore does not silently disable inline scripts.

---

## 6. Frame Options Per Policy

Per Q4 = A, this refines FR-18, which specified `DENY` globally without accounting for the public website:

| Path | `X-Frame-Options` | `frame-ancestors` |
|---|---|---|
| `/admin`, `/api/v1`, `/health` | `DENY` | `'none'` |
| Public website | `SAMEORIGIN` | `'self'` |

The admin UI stays maximally protected against click-jacking. A customer embedding one of their own pages in an iframe on their own site is not broken by a policy they never chose.

Both headers are emitted because they overlap rather than replace: `X-Frame-Options` covers older browsers, `frame-ancestors` is the modern equivalent and takes precedence where supported.

---

## 7. Startup Validation

```mermaid
graph TD
    boot["Startup"]
    unknown{"Every configured policy name<br/>is a known policy ?"}
    fail["Throw: process does not start"]
    build["Build both policy strings once"]
    monitoring{"Umami website ID configured<br/>but its origin missing from CSP ?"}
    warn["Log a warning naming the missing origin"]
    log["Log which origins are permitted"]
    ready["Ready to serve"]

    boot --> unknown
    unknown -->|no| fail
    unknown -->|yes| build
    build --> monitoring
    monitoring -->|yes| warn
    monitoring -->|no| log
    warn --> log
    log --> ready

    classDef entry fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
    classDef decision fill:#90cdf4,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef step fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    classDef warnnode fill:#fbd38d,stroke:#c05621,stroke-width:1px,color:#000;
    classDef bad fill:#fbb6ce,stroke:#b83280,stroke-width:1px,color:#000;
    class boot entry;
    class unknown,monitoring decision;
    class build,log,ready step;
    class warn warnnode;
    class fail bad;
```

Text alternative: an unknown policy name stops the process at startup rather than degrading per request, and a configured Umami website ID whose origin is missing from the CSP produces a warning — catching the case where analytics appears configured but is silently blocked.

**Why an unknown policy name is fatal** (fail closed, SECURITY-15): the alternative is falling back to something, and every fallback is either wrong or silently permissive. A typo in a path-policy mapping should stop a deployment, not quietly serve `/admin` under the relaxed policy.

**Why the monitoring warning covers Umami only** (Q5 = C): the question anticipated needing a Sentry ingest origin in `connect-src`. U4 Q1 = A chose a **tunnel through the API**, so browser error reports go to the application's own origin and `connect-src 'self'` already covers them. There is no Sentry origin to forget, so the warning would have nothing to check. Umami's script is still loaded from its own origin, so that check remains meaningful.

**Policies are built once at startup**, then reused. Composing a CSP per response would be wasteful on a workload that is mostly static files.

---

## 8. Interaction With the Placeholder Page

The built-in placeholder (U1) is served at `/`, so it receives the **relaxed** policy. It is a self-contained HTML document with a `<style>` block and no scripts, which the relaxed policy permits via `style-src 'unsafe-inline'`.

Worth stating because it is easy to overlook: the placeholder is the one HTML document this repository serves at the website path, so if the relaxed policy were ever tightened, it is the first thing that would break — and it would break on a fresh installation, which is the worst moment for a confusing failure.