feat(author): confine a build to folders, build with nothing written, the content as text

Merged
AL
2d ago
+1187-163

Closes #220. Step 1 of #219's plan: what a local MCP server needs from the author package.

What it adds

  • within, a buildPackage option: a list of the folders the output and every local file a source names must be inside, judged on real paths, so .. and links out are refused. A path outside gets the same answer whether or not a file is there, a file that cannot be read is a problem of the source's, and a confined build's problems name no absolute path. One folder given as a string is refused, not read letter by letter.
  • check, and h5p-author build --check <source>: builds and writes no package, with the same checks as a build, and takes no output (buildPackage(source, undefined, { check: true })). A media file named by web address is still downloaded, to a temporary folder removed after; a video on YouTube, Vimeo, Panopto or Echo360 stays an address, as in a build.
  • publicFetch, used where it is passed as fetch: refuses every network that is not the public internet, on every redirect, through net.BlockList (IPv4 written as IPv6, NAT64 and 6to4 forms, the documentation ranges, and the IPv6 ranges no web host is on). A name that does not resolve is refused in the words a local one is, so a refusal names no local host. It drops Authorization, Proxy-Authorization and Cookie on a redirect to another origin, as fetch does; the signal stops a DNS lookup, and an aborted request asks no resolver at all. It guards against a model's mistake or a planted address, not a hostile network: DNS rebinding is out of scope.
  • outline on every build result, and outlineOf(libraries, content, { limit }), in checkContent's order: the content as plain lines for a review, read through the libraries' semantics. Authored text only, with interface texts and settings left out in any language (what the editor does not draw, and texts a type's own widget sets); right answers marked; score ranges; slides, chapters, questions and a scenario's content numbered, without the titles the build gave; a scenario's links and scores; a video's interaction and bookmark times. It is made only when read, and whole unless a limit is given.
  • stripTags and decodeEntities in text.mjs, shared by the generator, the layouts, schema and the outline; tags are read as the content check splits markup. The type files are unchanged (sync-skill --check: 0 out of date).

Review rounds

  • Review: [::ffff:127.0.0.1] reached loopback; CodeQL alert #46; the first outline dropped numeric answers, hid True/False's answer and showed interface texts; a file named ..notes.png was refused; the redirect guard was untested; the README wording.
  • Self-review: confined builds' messages told which files exist outside the folders and named absolute paths; NAT64 and 6to4 forms; login headers on a redirect to another site; check still needed the output's folder; the outline ran inside every build; the score-range rule was a guess; a DNS lookup could not be stopped; the outline ran text together and showed no slides, links or times.
  • cubic, third round: the documentation ranges; an aborted request still asked the resolver; an encoded private-use character could pass for a break in the outline, and a lone \r was not one; labels holding entities; the README's import; the design note's wording. Declined, with the reason in each thread: the two file-race P1s (a process that can write in the user's folders already acts as the user; recorded in design/author.md) and decoding &amp; in plain fields.
  • cubic, fourth round: the documentation ranges' NAT64 and 6to4 forms are tested; the README's confined-build example defines its folder and runs as written.
  • Second self-review: within given as a string confined nothing; an unreadable file failed a build with its absolute path and passed a check; the quote-aware tag reader ran a link's tag into the text after it (a regression from main); the outline showed settings in four types (Game Map, Find the Hotspot, Find Multiple Hotspots, Virtual Tour), split words at inline tags, doubled a label's colon, wrote the build's own question titles and an unnamed bookmark, and stopped at 400 lines; outlineOf took its arguments in the opposite order to checkContent and answered a wrong shape with nothing; check needed an output; the docs (the design note's count, the layout map, what a check downloads); IPv6 ranges; refusals that told which local names exist.
  • cubic, fifth round: the docs said a check downloads every file named by web address; a video on YouTube, Vimeo, Panopto or Echo360 stays an address.
  • cubic, sixth round: the Service Worker's rule, moved from AGENTS.md, named frame-document.ts for a relay that lives in the runtime's frame-boot.ts; it now names the relay, the element's handler, and the broadcast to every controlled window when no client can answer.

Also here, the owner's commit: AGENTS.md cut from 150 lines to a 97-line index, and the Service Worker's statelessness rule, which lived only there, moved to design/serving.md.

Tests

Author 216/216 with the browser test, apps/skills author-verify and author-playback 73/73, both typechecks clean. New tests in tests/confine.test.ts and tests/text.test.ts, at least one per fix. Every type file's example outlined before and after the last round: only the intended lines changed.

Not here: moving the types table out of SKILL.md (the server reads it where it is), and read (step 3). The version bump to 0.11.0 is the owner's.