# Embedding the KodeMed Coding UI in a HIS iframe

How a browser-based hospital information system (HIS) embeds the KodeMed coding
UI in an `<iframe>` and keeps the coder's session alive **without reloading the
frame**.

> **Nothing here is enabled by default.** A deployment that does not set
> `KODEMED_EMBED_ALLOWED_ORIGINS` sends `X-Frame-Options: DENY` exactly as
> before and registers no `message` listener at all.

---

## 1. The problem this solves

Before this feature there were three ways to hand the UI a token, and none of
them worked for a browser-based HIS:

| Channel | Works cross-origin? | Refreshes? |
|---|---|---|
| `?token=…&refreshToken=…` on the iframe URL | yes | **no** — consumed once at load, then stripped from the URL (since #2098 the UI renews the token itself with the `refreshToken`, see below) |
| `window.__KODEMED_UPDATE_TOKEN__(token)` | **no** — same-origin policy | yes |
| WebView2 `PostWebMessage` | n/a | yes, but only inside the WebView2 desktop shell |

So a HIS could *start* a session but never *refresh* it. When the token
expired, the only recovery was reloading the iframe with a fresh `?token=`,
which destroys whatever the coder had on screen.

The `postMessage` channel below closes that gap. It mirrors the WebView2
contract exactly and feeds the same `updateDllToken()` code path, so there is
one token pipeline, not two.

---

## 2. Configuration (one key, both halves)

```bash
# installer/server/docker/.env  — then re-run setup.sh
KODEMED_EMBED_ALLOWED_ORIGINS="https://his.eoc.ch https://his-test.eoc.ch"
```

`setup.sh` validates every entry and then writes **both** halves from it, so
they cannot drift apart:

1. **`runtime-config.js`** gets `embedAllowedOrigins: ['https://his.eoc.ch', …]`
   — the allowlist for the postMessage channel.
2. **The Caddyfile** gets, on the CodingUI site *only*:
   ```
   -X-Frame-Options
   Content-Security-Policy "frame-ancestors 'self' https://his.eoc.ch https://his-test.eoc.ch"
   ```

Accepted values are **exact origins**: `scheme://host[:port]`, `http` or
`https`. A trailing slash and a default port are tolerated and normalised. Any
of the following **aborts the setup** rather than being silently dropped:

`*` · `https://*` · `https://*.eoc.ch` · `https://` · `his.eoc.ch` · `null` ·
`file://…` · `javascript:…` · anything with a path, query, fragment or
credentials.

### Why `-X-Frame-Options` is emitted too

`kodemed-ui`'s own nginx sends `X-Frame-Options: SAMEORIGIN`. A browser that
sees **both** `X-Frame-Options` and `frame-ancestors` may still honour the
former, so the UI origin must send `frame-ancestors` and nothing else. Caddy
strips the upstream header for us.

### Only the UI origin is relaxed

Server / DataServer / GrouperServer / docs / portal keep
`X-Frame-Options: DENY` (and, for the Server, Spring Security's
`frame-ancestors 'none'`) forever. Framing an API endpoint serves no purpose
and only adds clickjacking surface.

---

## 3. Message contract

All messages are plain JSON-serialisable objects with a `type` and an optional
`payload`. They travel over `window.postMessage`.

### HIS → KodeMed (inbound)

**`TOKEN_REFRESH`** — hand the UI a new access token.

```js
iframe.contentWindow.postMessage({
  type: 'TOKEN_REFRESH',
  payload: {
    token: '<new JWT access token>',
    expiresIn: 900            // optional, advisory only
  }
}, 'https://kodemed.hospital.ch');   // ALWAYS pass the exact target origin
```

* `payload.token` must be a **non-empty string**. Anything else is ignored.
* `expiresIn` is advisory; the UI reads the authoritative `exp` from the JWT.
* A token that is already expired, or not parseable, is rejected.

**`TOKEN_REFRESH_ERROR`** — tell the UI the refresh failed.

```js
iframe.contentWindow.postMessage({
  type: 'TOKEN_REFRESH_ERROR',
  payload: { error: 'idp unreachable' }   // optional, truncated to 200 chars in logs
}, 'https://kodemed.hospital.ch');
```

The UI logs it and, if the current token is already dead, shows the
session-expired banner. It never reloads or navigates by itself.

### KodeMed → HIS (outbound)

Both are posted **once per allowlisted origin**, each with that exact origin as
`targetOrigin` — never `'*'`. Neither ever carries token material.

**`KODEMED_EMBED_READY`** — sent once when the listener is live.

```json
{ "type": "KODEMED_EMBED_READY" }
```

Wait for this before posting your first `TOKEN_REFRESH`; a message posted
earlier is simply lost, and the iframe `load` event does not guarantee our
bundle has booted.

**`TOKEN_REFRESH_REQUEST`** — the UI is asking for a new token.

```json
{ "type": "TOKEN_REFRESH_REQUEST", "payload": { "expiresIn": 42 } }
```

Sent when the current token has ≤ 90 s left, at most once every 30 s. Respond
with a `TOKEN_REFRESH`. If you cannot, respond with `TOKEN_REFRESH_ERROR`.

### Minimal host implementation

```js
const KODEMED_ORIGIN = 'https://kodemed.hospital.ch';
const frame = document.getElementById('kodemed').contentWindow;

window.addEventListener('message', async (e) => {
  if (e.origin !== KODEMED_ORIGIN) return;     // exact match, always
  if (e.data?.type === 'KODEMED_EMBED_READY') {
    // listener is live — safe to push tokens from now on
    return;
  }
  if (e.data?.type === 'TOKEN_REFRESH_REQUEST') {
    try {
      const token = await mintKodeMedToken();
      frame.postMessage({ type: 'TOKEN_REFRESH', payload: { token } }, KODEMED_ORIGIN);
    } catch (err) {
      frame.postMessage(
        { type: 'TOKEN_REFRESH_ERROR', payload: { error: String(err) } },
        KODEMED_ORIGIN
      );
    }
  }
});
```

You may also push a `TOKEN_REFRESH` at any time without being asked; the UI
accepts unsolicited refreshes.

---

## 4. Security model

The origin check is the *entire* security of this channel, so it is deliberately
the dullest possible code:

* **Empty by default.** No `embedAllowedOrigins` ⇒ no listener is registered at
  all, and every origin check returns `false`.
* **Exact `===` on the full origin string.** No `startsWith`, no `includes`, no
  regex, no wildcards, no substring matching. `https://his.eoc.ch.evil.com`,
  `https://evilhis.eoc.ch`, `https://evil.com/https://his.eoc.ch` and
  `http://his.eoc.ch` all fail, because none of them is character-for-character
  equal to `https://his.eoc.ch`.
* **The opaque `"null"` origin is always rejected** — sandboxed iframes and
  `file://` documents report it, and accepting it would allowlist every
  sandboxed frame on the internet.
* **The allowlist is server-injected only.** It comes from
  `window.__KODEMED_CONFIG__` and is deliberately *not* part of the URL-param
  merge, so an attacker who frames the UI cannot append
  `?embedAllowedOrigins=https://evil.com` and allowlist themselves.
* **Shape validation before use.** A hostile frame can post a string, an array,
  `null`, or an object whose getters throw. Every field is type-checked before
  it is touched, and reading `event.data` is itself guarded.
* **Nothing leaks outward.** The token is never posted back, never echoed in an
  error, and only its *length* is logged. Rejections log the origin, never the
  payload.

---

## 5. When no refresh arrives

If the token expires and the host does not renew it, the UI shows a persistent
banner ("session has expired … your work is still on screen but cannot be
saved") with a **Request new session** button that re-sends
`TOKEN_REFRESH_REQUEST`. It deliberately does **not** reload or navigate — a
reload is precisely the data loss this feature exists to prevent.

### The UI renews a token it was given with a refresh token (#2098)

Opened with `?token=…&refreshToken=…` in a plain browser (an iframe or "open in a new
window"), the UI renews the access token itself, one minute before it expires, with
`grant_type=refresh_token` at the token endpoint of the configured IdP and for the client
that issued the token (its `azp` claim). Three conditions, each checked by the UI:

- the token's `iss` is the IdP the UI is configured for (`oauth2Url` + realm) - the
  refresh token is never sent anywhere else;
- the UI does not run inside the DLL's WebView2 (there the DLL renews the token);
- **the issuing client lists the Coding UI's origin as a Web Origin** in Keycloak, or the
  browser blocks the request (CORS). `kodemed-ui` already does; a HIS client of its own
  needs the UI origin added (`register-his-sample-client.sh --web-origin` for the sample).

A renewed token for another `sub` is refused. When the token cannot be renewed (refresh
token expired or revoked, CORS, IdP down) the UI says "Your sign-in expired and could not
be renewed. Changes are no longer saved." instead of only hiding the edit controls; a
`TOKEN_REFRESH` or a DLL push still clears it.

---

## 6. Deployment modes without Caddy

`setup.sh` can only apply the framing policy where it owns the edge. In
`--external-proxy` and `--single-domain` mode it prints the exact lines for you
to add to **the CodingUI host only**:

```nginx
add_header Content-Security-Policy "frame-ancestors 'self' https://his.eoc.ch" always;
proxy_hide_header X-Frame-Options;   # kodemed-ui sends SAMEORIGIN upstream
```

For Helm / OpenShift (`charts/kodemed/`) set the equivalent on the UI Ingress or
Route. `runtime-config.js` there is chart-managed — add `embedAllowedOrigins`
to the UI config the chart renders.

---

## 7. Related: `IntegrationProfile` (#496)

The Server already carries a per-profile `embed.csp_frame_ancestors` field and
serves the active union at the public endpoint `GET /api/v1/integration/csp`.
That drives the **Server's own** CSP (`DynamicCspHeaderWriter`) and exists so a
UI-side proxy can pull the same list.

Today the two are configured independently: `KODEMED_EMBED_ALLOWED_ORIGINS`
(install-time, drives the UI origin + the postMessage allowlist) and
`IntegrationProfile.embed.csp_frame_ancestors` (runtime, drives the API origin).
Keep them consistent. Unifying them — having `runtime-config.js` or the UI's
proxy read `/api/v1/integration/csp` — is a sensible follow-up but is
deliberately out of scope here, since it would make the browser-side allowlist
runtime-mutable by an admin API.