From 8eb5f19dd70a13be395b5b18445906824757c64a Mon Sep 17 00:00:00 2001
From: Aleksandr Shevchuk <alekswebnet@gmail.com>
Date: Wed, 14 Oct 2026 09:39:52 +0300
Subject: [PATCH 1/2] docs: say what the player does, and a guide for packages
 you did not make

The README now opens with what the player does beyond playing a package:
streaming, validation, results for audits, offline and languages, the tools,
and the testing, each linking to its guide. docs/untrusted.md gathers what
`untrusted` withholds, the content check and how it was compared with
H5P's PHP validator, handling a refusal with `carried`, and the checks every
package gets; the CSP and libraries guides point to it.

Closes #26.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md         |   3 +-
 README.md         |  27 +++++++++++++
 docs/frame-csp.md |   7 +---
 docs/libraries.md |   3 +-
 docs/untrusted.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 134 insertions(+), 7 deletions(-)
 create mode 100644 docs/untrusted.md

diff --git a/AGENTS.md b/AGENTS.md
index 1b00c58..54afa4a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -197,7 +197,8 @@ README.md                 what npm shows; ACCESSIBILITY.md, SECURITY.md, CONTRIB
                           CODE_OF_CONDUCT.md beside it
 
 docs/                     the README's longer sections, one file each: streaming video, libraries, the
-                          frame's CSP, the revision on statements, resume, the verifier, cmi5, development,
+                          frame's CSP, packages you did not make (`untrusted` and the content check), the
+                          revision on statements, resume, the verifier, cmi5, development,
                           troubleshooting, single-worker hosts and upgrades, coming from h5p-standalone,
                           privacy (what is stored and sent, for a host's notice); the README links
                           them by absolute URL because npm renders the same file; suggestions-review.md
diff --git a/README.md b/README.md
index 818caae..dc582ac 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,31 @@ no extraction step, no third-party service between your learners and your conten
 <h5p-player src="https://host.example/course.h5p"></h5p-player>
 ```
 
+## What it does
+
+- **Plays the packages people have.** Large ones stream: a video starts before the archive has
+  arrived, and a host without `Range` support still gets an early start. An export without its
+  libraries, as h5p.com and h5p.org make them, plays against a
+  [library pack](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/libraries.md) of every content type the H5P hub serves, and content
+  written for an older library version is upgraded first.
+- **Validates what it plays.** With `untrusted`, none of a package's own code runs, and its content
+  is checked field by field against each library's definitions by a port of H5P's own validator.
+  Every package's entry names and libraries are checked before it starts. See
+  [Packages you did not make](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/untrusted.md).
+- **Gives results you can audit.** Every xAPI statement names the
+  [build it came from](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/revision.md), `finished` is the content's own result,
+  [cmi5](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/cmi5.md) launches it from an LMS, and [resume](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/resume.md) keeps the
+  learner's place.
+- **Works offline, in the learner's language.** The installable app plays with no network, on iOS
+  too, and H5P's own buttons follow `lang` in more than fifty languages. The player sends nothing
+  anywhere; [privacy](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/privacy.md) lists what it keeps on the device.
+- **Comes with tools for pipelines.** [`h5p-verify`](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/verify.md) plays a package headless
+  and says whether it works, [`h5p-normalize`](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/streaming-video.md) rewrites one so its
+  video streams, and [`h5p-embed`](https://github.com/missing-elements/h5p-offline-player/tree/main/packages/embed#readme)
+  writes the embed site. The [agent skills](#agent-skills) cover all three.
+- **Is tested where it runs.** CI runs the browser tests in Chromium, Firefox and WebKit, and plays
+  every content type in the library pack, untrusted and trusted, on each change and every week.
+
 ## Which setup
 
 An H5P package is JavaScript, and the player runs it on the origin that serves the frame.
@@ -36,6 +61,7 @@ library pack, and its content is checked against each library's field definition
 shown, as the H5P CMS plugins check an author's upload. Installed with `untrusted`, a package is
 as contained as in an H5P plugin on the same site, and Embed adds a separate origin on top. A
 package that needs a newer library than the pack has is refused until the pack catches up.
+[Packages you did not make](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/untrusted.md) has the details.
 
 Both need the page on `https://` or `localhost`, and CORS headers on the package host. `Range`
 support is optional: without it the archive is downloaded once and played from the cache.
@@ -162,6 +188,7 @@ is an example.
 
 ## Guides
 
+- [Packages you did not make](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/untrusted.md) — `untrusted` and the content check
 - [Video that cannot stream](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/streaming-video.md) — `preload` and the normalizer
 - [Packages without libraries](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/libraries.md) — the library bundle and the hub
 - [The frame's CSP](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/frame-csp.md) — `allow-origins`, and what `untrusted` narrows
diff --git a/docs/frame-csp.md b/docs/frame-csp.md
index 8b5fa64..44f01c3 100644
--- a/docs/frame-csp.md
+++ b/docs/frame-csp.md
@@ -40,8 +40,5 @@ The policy refuses inline scripts and handlers in every case, since its scripts
 `<script>` in a content field never runs, nor does an `onerror` or a `javascript:` link. Markup
 needs no script to do harm, though: a form asking for a password, a frame, a style laid over the
 page. With `untrusted` the runtime therefore checks the content against each library's
-`semantics.json` before it is shown, as the H5P CMS plugins do: text keeps only the tags its field
-allows, with attributes written anew, and anything the definitions do not name is removed. Content
-whose main library has no `semantics.json` does not play. The check is in the runtime package,
-and the worker serves an untrusted package's `content.json` only to a runtime that does it, 0.2 or
-later.
+`semantics.json` before it is shown, as the H5P CMS plugins do; [Packages you did not
+make](untrusted.md) describes the check.
diff --git a/docs/libraries.md b/docs/libraries.md
index e88b642..5cd3cc4 100644
--- a/docs/libraries.md
+++ b/docs/libraries.md
@@ -51,4 +51,5 @@ With `untrusted`, a package's own library folders are ignored and its libraries
 refused, and when it carries that library itself, the error's `missingLibraries.carried` is
 `true`: playing it without `untrusted` would run its own copy, which is your decision to make.
 The content is then checked against the `semantics.json` of the libraries the sources serve, so
-those files have to be in the bundle; the pack has them.
+those files have to be in the bundle; the pack has them. [Packages you did not make](untrusted.md)
+has the rest.
diff --git a/docs/untrusted.md b/docs/untrusted.md
new file mode 100644
index 0000000..6b7aba8
--- /dev/null
+++ b/docs/untrusted.md
@@ -0,0 +1,101 @@
+# Packages you did not make
+
+An H5P package is code as well as content: its library folders hold the JavaScript that draws it.
+Played as it is, that code runs on your site's origin, where it can read your page's storage and
+cookies. `untrusted` plays a package as data instead, which is how the H5P plugins for Moodle,
+WordPress and Drupal treat an author's upload:
+
+```html
+<h5p-player src="https://elsewhere.example/course.h5p" untrusted></h5p-player>
+```
+
+## What is withheld
+
+- **The package's own library folders.** The libraries come from `libraries` (`pack` unless you
+  name another source), which is code you chose. See [Packages without libraries](libraries.md).
+- **Every file in `content/` that is not one of H5P's own content types.** Images, audio, video,
+  fonts, office documents, subtitles and JSON are served. Scripts, stylesheets, HTML, SVG and XML
+  are not.
+- **Running any file as a script.** Every file is served with `X-Content-Type-Options: nosniff`,
+  whatever its name.
+- **Your whole origin in the script policy.** The frame's policy names exact script paths instead;
+  [The frame's CSP](frame-csp.md) lists them.
+
+## The content check
+
+Before the runtime reads the content, it checks every field against the `semantics.json` of the
+library the field belongs to. This is a port of `H5PContentValidator`, the check the H5P plugins
+run on every save:
+
+- text keeps only the tags its field allows, with their attributes written anew;
+- plain text is escaped;
+- numbers are held to their range, and choices to their options;
+- sub-content must be a library its field names;
+- anything the semantics do not name is removed.
+
+The check matters even with every library folder withheld. Markup needs no script to do harm: a
+form asking for a password, a frame, a style laid over the page, a tracking image. And content
+types put field values into class names and selectors without escaping them, so a field's type
+matters too.
+
+Content whose main library has no `semantics.json` does not play. The pack carries every
+library's semantics; a bundle of your own has to carry them too.
+
+The port was run side by side with the PHP original on 98 cases:
+- 78 XSS vectors, through a formatted field and a plain one;
+- every field type;
+- the content of real packages.
+
+96 came out identical. The other two are edge cases where the port keeps a cleaner shape: a
+multi-select with an invalid option removed, and a number clamped to a maximum the semantics
+write as a string. Real content came
+through unchanged, apart from empty lists and one unknown translation key, which the PHP original
+removes too.
+
+The check fails closed. The Service Worker hands an untrusted package's content only to a runtime
+that runs the check, 0.2 or later. An older runtime plays nothing.
+
+## When a package is refused
+
+A package that needs a library your sources do not have is refused with `bad-archive`, naming the
+missing libraries. Usually it is a library newer than the pack, which a later pack release will
+carry.
+
+If the package carries that library itself, `missingLibraries.carried` is `true`. Playing it
+without `untrusted` would run the package's own copy. That is a decision for your site, so ask
+the visitor, naming the package's host:
+
+```js
+player.addEventListener('error', (e) => {
+  const missing = e.detail.missingLibraries
+  if (missing?.carried && player.untrusted && userAgreesToRunCodeFrom(new URL(player.src, location.href).host)) {
+    const src = player.src
+    player.untrusted = false
+    player.removeAttribute('src')
+    player.src = src
+  }
+})
+```
+
+## Checks every package gets
+
+With or without `untrusted`:
+
+- **Entry names.** An entry whose name is not a plain relative path, such as `../index.html`, is
+  rejected, and the rest of the package still plays.
+- **Libraries.** A package must carry, or get from `libraries`, every library it declares and every
+  library those depend on. Otherwise it is refused with the missing ones named, before the
+  content starts.
+
+## What it does not cover
+
+- **The libraries are your code.** The pack, or a bundle you name, runs as your site.
+- **Firefox.** The exact script paths narrow less there. Firefox checks a script the Service Worker
+  builds against the worker's own URL, so the worker's URL has to be in the policy, and with it
+  every answer the worker gives. The package's folders are still withheld, and `nosniff` still
+  holds.
+- **Your origin.** `untrusted` keeps a package's code off your origin, but its content still plays
+  there. For a site with signed-in users, [Embed](https://github.com/missing-elements/h5p-offline-player#embed)
+  puts the player on a separate domain as well.
+- **Correctness.** The check is about safety. Whether a package works at all is what
+  [`h5p-verify`](verify.md) answers.

From a360ee1620d9c46146518ab45d37138f4825dabc Mon Sep 17 00:00:00 2001
From: Aleksandr Shevchuk <alekswebnet@gmail.com>
Date: Wed, 14 Oct 2026 10:12:42 +0300
Subject: [PATCH 2/2] docs: results stay on the page; the plugins check before
 showing content

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md         | 5 +++--
 docs/untrusted.md | 5 ++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index dc582ac..20fd42f 100644
--- a/README.md
+++ b/README.md
@@ -33,8 +33,9 @@ no extraction step, no third-party service between your learners and your conten
   [cmi5](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/cmi5.md) launches it from an LMS, and [resume](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/resume.md) keeps the
   learner's place.
 - **Works offline, in the learner's language.** The installable app plays with no network, on iOS
-  too, and H5P's own buttons follow `lang` in more than fifty languages. The player sends nothing
-  anywhere; [privacy](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/privacy.md) lists what it keeps on the device.
+  too, and H5P's own buttons follow `lang` in more than fifty languages. Results stay on your page
+  unless your code sends them; [privacy](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/privacy.md)
+  lists what the player fetches, and what it keeps on the device.
 - **Comes with tools for pipelines.** [`h5p-verify`](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/verify.md) plays a package headless
   and says whether it works, [`h5p-normalize`](https://github.com/missing-elements/h5p-offline-player/blob/main/docs/streaming-video.md) rewrites one so its
   video streams, and [`h5p-embed`](https://github.com/missing-elements/h5p-offline-player/tree/main/packages/embed#readme)
diff --git a/docs/untrusted.md b/docs/untrusted.md
index 6b7aba8..e6b2a84 100644
--- a/docs/untrusted.md
+++ b/docs/untrusted.md
@@ -25,7 +25,7 @@ WordPress and Drupal treat an author's upload:
 
 Before the runtime reads the content, it checks every field against the `semantics.json` of the
 library the field belongs to. This is a port of `H5PContentValidator`, the check the H5P plugins
-run on every save:
+run before they show content:
 
 - text keeps only the tags its field allows, with their attributes written anew;
 - plain text is escaped;
@@ -48,8 +48,7 @@ The port was run side by side with the PHP original on 98 cases:
 
 96 came out identical. The other two are edge cases where the port keeps a cleaner shape: a
 multi-select with an invalid option removed, and a number clamped to a maximum the semantics
-write as a string. Real content came
-through unchanged, apart from empty lists and one unknown translation key, which the PHP original
+write as a string. Real content came through unchanged, apart from empty lists and one unknown translation key, which the PHP original
 removes too.
 
 The check fails closed. The Service Worker hands an untrusted package's content only to a runtime