diff --git a/content/faq/_index.md b/content/faq/_index.md index d520499..5ec42cb 100644 --- a/content/faq/_index.md +++ b/content/faq/_index.md @@ -58,6 +58,26 @@ Yes — that is a core feature. Each `` is independent, so a sin HTMLTrust degrades gracefully. Unsigned or unrecognized `` elements render as normal content. Only the verification features are unavailable. The page remains fully readable and functional. +## Why does a signed page show as *invalid* in the browser even when the signature is mathematically correct? + +This is a real, observed issue: HTMLTrust signs the **static HTML** that leaves the publishing pipeline, but the browser extension verifies against the **live DOM** — the state of the page after every script on the page has finished running. If anything inside a `` is mutated between page load and verification, the recomputed `content-hash` won't match the signed one, and the extension reports an invalid signature. + +We hit this on our own site initially: the Hugo Blox docs theme injects a `` into every `
` code block at runtime. The signer never saw the button, so the canonical text the verifier reads includes extra "Copy" tokens that aren't in the hash.
+
+Other common culprits:
+
+- Client-side syntax highlighters (Prism, highlight.js) that rewrite code blocks
+- Lazy-loading or share-button widgets that add nodes inside article content
+- Theme JS that decorates headings, callouts, or admonitions at runtime
+
+**What to do about it** — until the spec defines a mutation-skip marker, the practical workarounds are:
+
+1. Configure or patch the theme so it does **not** inject nodes inside `` descendants
+2. Pre-render any decoration server-side, so the signer hashes it
+3. Move runtime-injected decoration **outside** the signed region (as a sibling, not a child)
+
+This is being tracked as a spec open design question — see [Known Issue: Runtime DOM Mutation](https://github.com/HTMLTrust/htmltrust-spec#known-issue-runtime-dom-mutation-breaks-verification) in the spec README.
+
 ## What browsers are supported?
 
 A reference browser extension is available for **Chrome** (and Chromium-based browsers like Edge). Firefox and Safari support is planned. Eventually, the goal is native browser support via a W3C standard.