docs: document runtime DOM mutation breaking verification#2
Merged
Conversation
HTMLTrust signs the static HTML that leaves the publishing pipeline.
Browser verifiers, however, read the live DOM — i.e. after every
script on the page has finished running. If a script mutates content
inside a <signed-section> at runtime (theme-injected copy buttons,
client-side syntax highlighters, lazy-loaders, share widgets), the
verifier's recomputed content-hash will not match the signed one,
and the signature is reported as invalid even though it is
cryptographically correct.
Adds a "Known Issue: Runtime DOM Mutation Breaks Verification"
section to the spec README documenting:
- Concrete cases observed (most recently: Hugo Blox docs theme
injecting <button class="copy-button">Copy</button> into every
<pre> block, which the signer never saw)
- Mitigations available today (don't inject into signed regions,
pre-render decoration server-side, move decoration outside the
signed region, or verify against pristine HTML rather than DOM)
- Open spec question: Stage 1 canonicalization likely needs an
explicit "skip-on-mutation-marker" mechanism (e.g.,
data-htmltrust-ignore="true" on a subtree) plus authoring and
verifier guidance.
This is tracked as an active open design question.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
jt55401
force-pushed
the
docs/runtime-dom-mutation-known-issue
branch
from
837eff5 to
6759527
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a Known Issue section to the spec README documenting a real, general challenge for any content-signing protocol that targets browser-side verification:
<signed-section>between page load and verification, the recomputed hash won't match → invalidWe hit this on the project website itself: the Hugo Blox docs theme injects a copy button into every
<pre>block at runtime. The signer never saw the button; the verifier did.Documents:
data-htmltrust-ignoremutation-skip marker)Also referenced from the website FAQ (separate PR).
🤖 Generated with Claude Code