From f5170c83cdf139ae2c4b6d16e7a9640de694f4e1 Mon Sep 17 00:00:00 2001
From: Andreas Stefl <stefl.andreas@gmail.com>
Date: Thu, 20 Aug 2026 11:19:02 +0200
Subject: [PATCH 1/3] docs(wasm): say what csp the rendered output needs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"Self-contained" is true of the markup but not of what a page may load:
a frame inherits the embedding page's policy, so the embedder's CSP
governs the rendered document, and nothing said what that has to allow.
The failures are quiet — under `font-src 'self'` a pdf's `data:` fonts
are blocked, and because they carry the code points the text is painted
with, every glyph comes out as a replacement box instead of falling back
to a system face.

Measured across an odt, ods, docx and pdf rendered through the package:
`font-src data:`, `img-src data:`, `style-src 'unsafe-inline'` (blocks
and, more to the point, hundreds of `style` attributes, which a nonce
cannot cover) and `script-src 'unsafe-inline'`. Nothing is fetched from
another origin.

Closes #710

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XDs5aK3ZGSZsEvqUUwBBXU
---
 CHANGELOG.md   |  4 ++++
 wasm/README.md | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4cca131c..90e4ec64 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,6 +29,10 @@ The release run heads these entries with the version and opens a fresh
   the wasm module is linked with `-sDYNAMIC_EXECUTION=0`, so embind builds its
   invokers without `new Function`. `script-src 'self' 'wasm-unsafe-eval'` is
   now enough.
+- `wasm/README.md` says what Content-Security-Policy the rendered output needs,
+  and what each directive is for. An embedder inherits its own policy into the
+  frame, and the failures are quiet — a pdf whose `data:` fonts are blocked
+  renders as tofu rather than falling back.
 
 ## v6.9.0 - 2026-08-18
 
diff --git a/wasm/README.md b/wasm/README.md
index f5871123..aace1b4f 100644
--- a/wasm/README.md
+++ b/wasm/README.md
@@ -47,7 +47,10 @@ try {
 so it needs nothing fetched alongside it. A `blob:` iframe keeps the same
 origin, so the page can still reach `iframe.contentWindow.odr` to drive
 `search()`, `searchNext()` and `generateDiff()`, exactly as the Android and iOS
-apps do from their WebViews.
+apps do from their WebViews. Inline is not the same as unconditional: the frame
+inherits the embedding page's Content-Security-Policy, so a page that ships one
+has to allow what the document carries — see
+[Content-Security-Policy](#content-security-policy).
 
 Multi-page formats render one view at a time:
 
@@ -86,6 +89,46 @@ where `Symbol.dispose` is supported.
 - Rendering is synchronous and a large PDF takes seconds, so run the module in
   a Web Worker. Pass `doc.handle` across `postMessage`, never the `Document`.
 
+## Content-Security-Policy
+
+The rendered html is self-contained, but a frame created from an embedding page
+inherits that page's policy — so the *embedder's* CSP decides what the document
+may load, and the failures are quiet. Measured across an odt, ods, docx and pdf
+rendered by this package:
+
+| Directive | What in the output needs it | Seen in |
+|---|---|---|
+| `font-src data:` | embedded subset fonts | pdf (7 of 8 `@font-face`) |
+| `img-src data:` | embedded images | odt, docx, standalone images |
+| `style-src 'unsafe-inline'` | the document's own `<style>` blocks **and** its `style` attributes | every format (2–3 blocks, and up to hundreds of attributes) |
+| `script-src 'unsafe-inline'` | the document's own `<script>` blocks | every format but a standalone image (1–3) |
+
+Nothing is fetched from another origin, so no host ever has to be allow-listed.
+A policy that works, for a document loaded into a frame:
+
+```
+frame-src 'self' blob:; font-src 'self' data:; img-src 'self' data:;
+style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'
+```
+
+Worth knowing before tightening any of it:
+
+- **`font-src data:` is the one that costs the most time.** A pdf's text is
+  painted with the code points its embedded subset defines, so a blocked
+  `@font-face` does not fall back to a system face — every glyph comes out as a
+  replacement box. Office formats embed images rather than fonts, which makes
+  it easy to conclude the embed works.
+- **A blocked inline script is silent.** The layout is css, so the document
+  still looks right; only what the scripts provide — search, editing, the
+  spreadsheet and text-view behaviour — stops working.
+- **`style-src` cannot be narrowed to a nonce or a hash.** Most of the styling
+  is `style` attributes, which only `'unsafe-inline'` (or `'unsafe-hashes'`)
+  covers.
+- **Audio and video stay linked resources** rather than data urls, so a media
+  file needs `media-src` pointing wherever the resource was written.
+
+Loading the module itself is a separate question — see [Hosting](#hosting).
+
 ## Building
 
 Needs the Emscripten toolchain, via the conan profile in the repository:

From 4493319d3084c79e90d7d01de3bbbdcd2faf4c29 Mon Sep 17 00:00:00 2001
From: Andreas Stefl <stefl.andreas@gmail.com>
Date: Thu, 20 Aug 2026 11:58:51 +0200
Subject: [PATCH 2/3] docs(wasm): say what script-src 'unsafe-inline' also
 grants
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Recommending it without qualification was one-sided: it permits
`javascript:` urls too, and a document may carry one — odrcore filters a
pdf link action down to an allowlist of navigable schemes, but an odt or
docx hyperlink is only attribute-escaped. In a `blob:` frame, which is
same-origin with the embedder by design, such a link runs with the
embedder's origin.

The section now says so, and gives the way out for untrusted input:
`sandbox="allow-scripts"` without `allow-same-origin`, which keeps the
renderer's own scripts working inside the frame and gives up the
`contentWindow.odr` API. It also records why hashes or a nonce are not an
option here — `embed_shipped_resources`, which would leave no inline
script at all, is not bound in the wasm build.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XDs5aK3ZGSZsEvqUUwBBXU
---
 wasm/README.md | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/wasm/README.md b/wasm/README.md
index aace1b4f..7364a145 100644
--- a/wasm/README.md
+++ b/wasm/README.md
@@ -101,7 +101,7 @@ rendered by this package:
 | `font-src data:` | embedded subset fonts | pdf (7 of 8 `@font-face`) |
 | `img-src data:` | embedded images | odt, docx, standalone images |
 | `style-src 'unsafe-inline'` | the document's own `<style>` blocks **and** its `style` attributes | every format (2–3 blocks, and up to hundreds of attributes) |
-| `script-src 'unsafe-inline'` | the document's own `<script>` blocks | every format but a standalone image (1–3) |
+| `script-src 'unsafe-inline'` | the renderer's own js, written into every document | every format but a standalone image (1–3) |
 
 Nothing is fetched from another origin, so no host ever has to be allow-listed.
 A policy that works, for a document loaded into a frame:
@@ -111,7 +111,34 @@ frame-src 'self' blob:; font-src 'self' data:; img-src 'self' data:;
 style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'
 ```
 
-Worth knowing before tightening any of it:
+### `script-src 'unsafe-inline'` is not free
+
+It also permits **`javascript:` urls**, and a document may carry one: odrcore
+filters a pdf link action down to an allowlist of navigable schemes, but a
+hyperlink in an odt or a docx is only attribute-escaped, so a `javascript:`
+href reaches the page. In a `blob:` frame — same origin as the embedder, which
+is what lets the page call `iframe.contentWindow.odr` — such a link runs with
+the embedder's origin if the reader clicks it.
+
+That is fine for documents you trust and not for documents you do not. For
+untrusted input, sandbox the frame and give up the same-origin API:
+
+```html
+<iframe sandbox="allow-scripts" srcdoc="..."></iframe>
+```
+
+`allow-scripts` **without** `allow-same-origin` puts the document in an opaque
+origin: the renderer's own search and editing still work inside the frame, a
+`javascript:` link can no longer reach the embedding page, and
+`iframe.contentWindow` is out of reach from outside. Granting both together is
+the same as not sandboxing at all.
+
+There is no way to narrow this to hashes or a nonce from here: the package
+embeds the renderer's js in the document, and `HtmlConfig::embed_shipped_resources`
+— which links it as files instead, leaving no inline script at all — is not
+bound in this build.
+
+Worth knowing before tightening the rest:
 
 - **`font-src data:` is the one that costs the most time.** A pdf's text is
   painted with the code points its embedded subset defines, so a blocked
@@ -120,7 +147,9 @@ Worth knowing before tightening any of it:
   it easy to conclude the embed works.
 - **A blocked inline script is silent.** The layout is css, so the document
   still looks right; only what the scripts provide — search, editing, the
-  spreadsheet and text-view behaviour — stops working.
+  spreadsheet and text-view behaviour — stops working. Refusing
+  `script-src 'unsafe-inline'` outright is therefore a real option when the
+  document only has to be *read*.
 - **`style-src` cannot be narrowed to a nonce or a hash.** Most of the styling
   is `style` attributes, which only `'unsafe-inline'` (or `'unsafe-hashes'`)
   covers.

From e4e6976f077d5f735403d2d86bc27ba134cb569e Mon Sep 17 00:00:00 2001
From: Andreas Stefl <stefl.andreas@gmail.com>
Date: Thu, 20 Aug 2026 14:28:47 +0200
Subject: [PATCH 3/3] docs(wasm): trim the csp section

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015d5RcmsA777vwXiuafjx6k
---
 CHANGELOG.md   |  5 ++---
 wasm/README.md | 55 ++++++++++++++++++++++----------------------------
 2 files changed, 26 insertions(+), 34 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 90e4ec64..0ce82238 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,9 +30,8 @@ The release run heads these entries with the version and opens a fresh
   invokers without `new Function`. `script-src 'self' 'wasm-unsafe-eval'` is
   now enough.
 - `wasm/README.md` says what Content-Security-Policy the rendered output needs,
-  and what each directive is for. An embedder inherits its own policy into the
-  frame, and the failures are quiet — a pdf whose `data:` fonts are blocked
-  renders as tofu rather than falling back.
+  and what each directive is for. The failures are quiet: a pdf whose `data:`
+  fonts are blocked renders as tofu rather than falling back.
 
 ## v6.9.0 - 2026-08-18
 
diff --git a/wasm/README.md b/wasm/README.md
index 7364a145..64cdecf2 100644
--- a/wasm/README.md
+++ b/wasm/README.md
@@ -47,10 +47,9 @@ try {
 so it needs nothing fetched alongside it. A `blob:` iframe keeps the same
 origin, so the page can still reach `iframe.contentWindow.odr` to drive
 `search()`, `searchNext()` and `generateDiff()`, exactly as the Android and iOS
-apps do from their WebViews. Inline is not the same as unconditional: the frame
-inherits the embedding page's Content-Security-Policy, so a page that ships one
-has to allow what the document carries — see
-[Content-Security-Policy](#content-security-policy).
+apps do from their WebViews. The frame inherits the embedding page's
+Content-Security-Policy, so a page that ships one has to allow what the
+document carries — see [Content-Security-Policy](#content-security-policy).
 
 Multi-page formats render one view at a time:
 
@@ -91,10 +90,9 @@ where `Symbol.dispose` is supported.
 
 ## Content-Security-Policy
 
-The rendered html is self-contained, but a frame created from an embedding page
-inherits that page's policy — so the *embedder's* CSP decides what the document
-may load, and the failures are quiet. Measured across an odt, ods, docx and pdf
-rendered by this package:
+The rendered html is self-contained, but a frame inherits the embedding page's
+policy — so the *embedder's* CSP decides what the document may load, and the
+failures are quiet. Measured across an odt, ods, docx and pdf:
 
 | Directive | What in the output needs it | Seen in |
 |---|---|---|
@@ -103,8 +101,8 @@ rendered by this package:
 | `style-src 'unsafe-inline'` | the document's own `<style>` blocks **and** its `style` attributes | every format (2–3 blocks, and up to hundreds of attributes) |
 | `script-src 'unsafe-inline'` | the renderer's own js, written into every document | every format but a standalone image (1–3) |
 
-Nothing is fetched from another origin, so no host ever has to be allow-listed.
-A policy that works, for a document loaded into a frame:
+Nothing is fetched from another origin, so no host has to be allow-listed. A
+policy that works, for a document loaded into a frame:
 
 ```
 frame-src 'self' blob:; font-src 'self' data:; img-src 'self' data:;
@@ -115,41 +113,36 @@ style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'
 
 It also permits **`javascript:` urls**, and a document may carry one: odrcore
 filters a pdf link action down to an allowlist of navigable schemes, but a
-hyperlink in an odt or a docx is only attribute-escaped, so a `javascript:`
-href reaches the page. In a `blob:` frame — same origin as the embedder, which
-is what lets the page call `iframe.contentWindow.odr` — such a link runs with
-the embedder's origin if the reader clicks it.
+hyperlink in an odt or a docx is only attribute-escaped. In a `blob:` frame —
+same origin as the embedder, which is what lets the page call
+`iframe.contentWindow.odr` — such a link runs with the embedder's origin.
 
-That is fine for documents you trust and not for documents you do not. For
-untrusted input, sandbox the frame and give up the same-origin API:
+Fine for documents you trust. For untrusted input, sandbox the frame and give
+up the same-origin API:
 
 ```html
 <iframe sandbox="allow-scripts" srcdoc="..."></iframe>
 ```
 
 `allow-scripts` **without** `allow-same-origin` puts the document in an opaque
-origin: the renderer's own search and editing still work inside the frame, a
-`javascript:` link can no longer reach the embedding page, and
-`iframe.contentWindow` is out of reach from outside. Granting both together is
-the same as not sandboxing at all.
+origin: search and editing still work inside the frame, while a `javascript:`
+link can no longer reach the embedding page. Granting both together is the same
+as not sandboxing at all.
 
-There is no way to narrow this to hashes or a nonce from here: the package
-embeds the renderer's js in the document, and `HtmlConfig::embed_shipped_resources`
-— which links it as files instead, leaving no inline script at all — is not
-bound in this build.
+Narrowing to a hash or a nonce is not possible from here: the renderer's js is
+embedded in the document, and `HtmlConfig::embed_shipped_resources` — which
+links it as files instead — is not bound in this build.
 
 Worth knowing before tightening the rest:
 
-- **`font-src data:` is the one that costs the most time.** A pdf's text is
+- **`font-src data:` is the one that fails most confusingly.** A pdf's text is
   painted with the code points its embedded subset defines, so a blocked
   `@font-face` does not fall back to a system face — every glyph comes out as a
-  replacement box. Office formats embed images rather than fonts, which makes
-  it easy to conclude the embed works.
+  replacement box.
 - **A blocked inline script is silent.** The layout is css, so the document
-  still looks right; only what the scripts provide — search, editing, the
-  spreadsheet and text-view behaviour — stops working. Refusing
-  `script-src 'unsafe-inline'` outright is therefore a real option when the
-  document only has to be *read*.
+  still looks right; only search, editing and the spreadsheet and text-view
+  behaviour stop working. Refusing `script-src 'unsafe-inline'` is a real
+  option when the document only has to be *read*.
 - **`style-src` cannot be narrowed to a nonce or a hash.** Most of the styling
   is `style` attributes, which only `'unsafe-inline'` (or `'unsafe-hashes'`)
   covers.