Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ packages/player/LICENSE
packages/normalize/LICENSE
packages/verify/LICENSE
packages/author/LICENSE
packages/mcp/LICENSE
# The h5p-author skill's text and build routes, which the author's `prepack` copies beside its type files (#178, #204).
packages/author/SKILL.md
packages/author/references/authoring.md
Expand Down
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ by assumption, and asks a page for what only a page can do through the frame:

## Where things are, and whose rules

A pnpm workspace of nine packages and two apps. [`design/layout.md`](design/layout.md) maps the
A pnpm workspace of ten packages and two apps. [`design/layout.md`](design/layout.md) maps the
folders; in `design/`, `src/…` and `scripts/…` mean the player's unless a file says otherwise.

| Part | What it is | Rules |
Expand All @@ -51,6 +51,7 @@ folders; in `design/`, `src/…` and `scripts/…` mean the player's unless a fi
| `packages/normalize/` | rewrites a package so it streams | [normalize](design/normalize.md) |
| `packages/verify/` | plays a package headless and reports | [verify](design/verify.md) |
| `packages/author/`, `skills/h5p-author/` | a playable package of any content type from a short source | [author](design/author.md) |
| `packages/mcp/` | the local MCP server: builds, checks and previews in an app with no shell | [mcp](design/mcp.md) |
| `packages/cmi5/` | the element as a cmi5 assignable unit | [cmi5](design/cmi5.md) |
| `packages/embed/`, `skills/h5p-to-scorm/` | the embed site for a player domain, and a package as a SCORM zip | [embed](design/embed.md), [scorm](design/scorm.md) |
| `packages/vscode/` | H5P Preview, the VS Code extension | [vscode](design/vscode.md) |
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,7 @@ esbuild, and the one-prompt install on Lovable;
| [`@missing-elements/h5p-verify`](https://github.com/missing-elements/h5p-offline-player/tree/main/packages/verify#readme) | Plays a package headless and reports whether it works, or opens it in your browser |
| [`@missing-elements/h5p-normalize`](https://github.com/missing-elements/h5p-offline-player/tree/main/packages/normalize#readme) | Rewrites a package so its video streams |
| [`@missing-elements/h5p-author`](https://github.com/missing-elements/h5p-offline-player/tree/main/packages/author#readme) | Builds a package of any content type from a short JSON source |
| [`@missing-elements/h5p-mcp`](https://github.com/missing-elements/h5p-offline-player/tree/main/packages/mcp#readme) | A local MCP server: an app such as Claude Desktop builds a package onto your disk, checks it and opens it in your browser |
| [`@missing-elements/h5p-cmi5`](https://github.com/missing-elements/h5p-offline-player/tree/main/packages/cmi5#readme) | Makes a page holding the element a cmi5 assignable unit |
| [H5P Preview](https://marketplace.visualstudio.com/items?itemName=MissingElements.h5p-preview) | Plays `.h5p` files in VS Code, and from [Open VSX](https://open-vsx.org/extension/MissingElements/h5p-preview) in Cursor and VSCodium |

Expand Down
22 changes: 21 additions & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ versions of the packages in this repository:
| `@missing-elements/h5p-embed` | Latest release and `main` |
| `@missing-elements/h5p-runtime` | Latest release and `main` |
| `@missing-elements/h5p-libraries` | Latest release and `main` |
| `@missing-elements/h5p-author` | Latest release and `main` |
| `@missing-elements/h5p-mcp` | Latest release and `main` |
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
| Demo and installable app | Deployment from `main` |

Older releases may receive a fix when practical, but users should upgrade to a
Expand Down Expand Up @@ -68,6 +70,20 @@ The relevant security boundary depends on how the player is deployed:
cannot make a package's own JavaScript safe when the package plays as it is;
that is what `untrusted` withholds.

The author package and the MCP server build packages from a source that a
model may have written:

- Given `within`, a build reads local files and writes its package only in
those folders, links followed. Given `publicFetch`, it refuses to download
from a web address on a local network, redirects included; it resolves a
name and then asks, so it guards against a mistaken or planted address, not
a hostile network. A video on YouTube, Vimeo, Panopto or Echo360 is not
downloaded: its address is kept, and the player loads it wherever it points.
- The MCP server always builds so, in the folders the person gave it, else the
app's roots, as they are given. Given none, it uses Desktop, Documents and
Downloads, and never the home folder whole. It never writes over a file, and
its preview serves one package on `127.0.0.1` until its tab is closed.

Reports are particularly helpful for issues such as:

- archive path traversal, package-to-package data exposure, or virtual-route
Expand All @@ -82,8 +98,12 @@ Reports are particularly helpful for issues such as:
- cross-origin request, redirect, or navigation-policy bypasses;
- denial of service that defeats documented streaming, size, storage, or
lifecycle safeguards;
- a build confined by `within` that reads or writes outside its folders or
writes over a file, `publicFetch` reaching a local network by an address it
should refuse, or the MCP server reaching a file outside its folders;
- vulnerabilities in the published player, runtime, library bundle, normalizer,
verifier, cmi5 package, embed site writer, demo, or installable app.
verifier, author package, MCP server, cmi5 package, embed site writer, demo,
or installable app.

A malicious H5P archive executing its own bundled JavaScript when it plays as
it is, is an expected property of H5P, not by itself a vulnerability. It
Expand Down
12 changes: 6 additions & 6 deletions design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -308,12 +308,12 @@ text to the content check's rules, and `apps/skills` plays every example untrust
- **A source's own fields are declared once, as `sourceSchema`** (#230). `sourceOf` takes the list
of fields from it, holds each field to it and says its message where the field was written; it is
the `Source` type, it takes no other field, as a build does not, and it is exported so that a
model can be shown the shape before writing a source. What one field cannot say alone stays in
`sourceOf`: the content type named loosely, a licence written with its version, a version for a
licence that takes none, and fields in the wrong place. Every problem of an author is said at
once, and an author written as a name alone is said with the object to write. It is zod/mini,
23 kB minified, since a build runs in a page too, where zod's chained API takes 93 kB; JSON
Schema is made where it is shown.
model can be shown the shape before writing a source, as the MCP server shows it for
`h5p_build`'s source. What one field cannot say alone stays in `sourceOf`: the content type
named loosely, a licence written with its version, a version for a licence that takes none, and
fields in the wrong place. Every problem of an author is said at once, and an author written as
a name alone is said with the object to write. It is zod/mini, 23 kB minified, since a build
runs in a page too, where zod's chained API takes 93 kB; JSON Schema is made where it is shown.
- **The skill is installed, and its page lists what step 3 fetches.** Claude and ChatGPT install
the skill as a zip, and Grok reads the zip attached to a message; reading it by its link was
dropped (missing-elements.github.io#42). Since the 0.10.0 pin the organisation's site serves the
Expand Down
4 changes: 3 additions & 1 deletion design/layout.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Layout

A pnpm workspace of nine packages and two apps. Eight packages are published to npm; the VS Code
A pnpm workspace of ten packages and two apps. Nine packages are published to npm; the VS Code
extension is a `.vsix`. Paths in `design/` are relative to their part: `src/…` and `scripts/…`
mean the player's unless a file says otherwise. `dist/`, `types/`, the player's `public/` and the
runtime's `index.js` are generated and not in git.
Expand Down Expand Up @@ -30,6 +30,8 @@ packages/verify/ a package played headless (lib/verify.mjs) and in a brows
packages/author/ a playable .h5p from a short source: lib/build.mjs both builds, node.mjs
Node's, generator.mjs content from semantics, check.mjs, outline.mjs,
types.mjs the editor widgets' rules; scripts/ the skill's sync and copy
packages/mcp/ the local MCP server: bin/h5p-mcp.mjs the command, lib/server.mjs its three
tools, lib/folders.mjs the folders it may use
packages/cmi5/ the element as a cmi5 AU: src/index.ts startCmi5, src/client.ts the protocol
packages/embed/ site/ the embed page and the SCORM page; lib/build.mjs the site,
lib/scorm*.mjs the SCORM zip in Node and in a page; scorm/ its launch page
Expand Down
66 changes: 66 additions & 0 deletions design/mcp.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# The MCP server

`packages/mcp` is `@missing-elements/h5p-mcp`, shown as **H5P Author MCP by Missing Elements**: a
local MCP server over standard input and output that builds a package onto the person's disk,
checks it, and opens it in their browser. It is for apps with no shell, Claude Desktop first; in an
app with a shell, the skill and `npx` build already. A remote server, for ChatGPT or Claude on the
web, is #210 and not this.

- **It holds no rules of its own.** The build, its checks, the outline and the confinement to
folders (`buildPackage`, `within`, `publicFetch`, `inside`) are h5p-author's; the check, the
preview and opening the browser (`verifyPackage`, `summarize`, `previewPackage`, `openBrowser`)
are h5p-verify's. A rule a tool needs goes into those packages first, exported, so the author
package and the verifier are published before a server that uses something new of theirs.
- **Three tools, and the skill's flow as the instructions.** `h5p_types` lists the pack's content
types, those with a type file marked, and the skill's brief; given a type, read as a build reads
one (`sourceType`, so "true false" works), it answers with the type's file, or with `schemaOf` for
a type with none. `h5p_build` builds a source and `h5p_preview` opens a package. The instructions
are the flow in a few lines: the type is the one question, its answer is read before the source is
written, then the build, where the file is and what the check found, and the preview offered.
Not `SKILL.md`, whose build routes do not apply here. An app sends the descriptions and the
instructions with every message, so they stay under about 1,500 tokens; `server.test.ts` holds
them under 6,000 characters.
- **`h5p_build` shows a source's own fields; the build checks them.** Its `source` carries the
fields of the author package's `sourceSchema` as JSON Schema properties (#230), so a model writes
the authors and the licence right before its first build: without them, Haiku wrote
`"authors": ["Unknown"]` in 2 of 3 runs that built, and with them in none of 9. Nothing is said
to be required or forbidden, and the field takes any object, since the build reads a source
written another way as it is meant and says every problem at once (#174), where the SDK, or an
app that holds a call to the schema, would refuse it unread.
- **The folders: `--allow`, else the app's roots, else Desktop, Documents and Downloads.** A folder
the person named when adding the server is their choice and comes first; the app's roots come
next, asked on every call, since they change; both are taken as given. The defaults are never
the home folder whole: one that is a link to the home folder, or to a folder holding it, is left
out. A build reads local files and writes its package only there (`within`), and refuses to
download from an address on a local network (`publicFetch`, a guard against a model's mistake or
a planted address, not a hostile network); the preview opens only a package there (`inside`). A
hosted video's address is no download: it is kept, and the player loads it wherever it points,
since Panopto is often an institution's own server on its own network.
- **A build never writes over a file.** With no `output`, the package is named from its title
(`fileStem`: the title's letters and digits, in any script, cut at 60 characters, and `-file`
after a name Windows keeps for a device, as `con`). A name that is taken, the package's or its
source's, by a file or by a link even to nowhere, gets the next number, and so does a taken
`output`, as the build itself refuses to write over a file. A name is held while its build runs,
so builds at once take names of their own. The answer names the path written. Beside the package
goes its source, `<name>.source.json`, which the build page opens to change and build again; it
is made new, never written over or through a link, and where it cannot be, the answer says so.
- **A build answers with the content, the check and a picture.** The build's line, its notes, the
outline (80 lines at most) and, with `verify`, the default, the verifier's summary of a check run
in a temporary folder, with its screenshot as an image. Where neither Chrome, Edge nor
Playwright's Chromium is found, the answer says "Not verified" and why. A source with problems
is refused, every problem by its path, and nothing is written.
- **The SDK is v2, and the package ships its source.** `@modelcontextprotocol/server` brings only
its core and zod, none of the HTTP frameworks v1 installed, so `bin/` and `lib/` are published as
written, with no bundle. `McpServer` on `StdioServerTransport` serves the 2025 protocol, which
every app speaks; protocol 2026-07-28 deprecates roots, so serving it would leave the folders to
`--allow` and the defaults. Standard output is the protocol's, so the command sends `console.log`
to standard error, and loads the server only after `--help` and `--version` have had their turn.
- **Tested as an app runs it.** `tests/server.test.ts` starts the command over standard input and
output with the SDK's own client, given one folder, and calls each tool: the list, a type by a
loose name and one with no file, a build checked in Chromium, a taken name and a link at one,
two builds at once, a source with a problem, an output outside the folder, a preview served and
one refused. Each test builds what it needs, so each runs alone. The test script first copies
the skill's type files into the author package, as the author's `prepack` does.

Not built yet: reading a package back to a source (step 3 of #219), the MCP registry's
`server.json` and Claude Desktop's one-click bundle.
3 changes: 2 additions & 1 deletion docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,8 @@ long as the player streams the result at least as well.

The command's options, its exit codes — 0 plays, 1 does not, 2 could not run; with `--preview`,
0 when the preview ends and 2 when it could not start — `report.json`, to
which fields may be added, and `verifyPackage()` and `summarize()`, with their types: `VerifyReport`
which fields may be added, and `verifyPackage()`, `summarize()`, `previewPackage()` and
`openBrowser()`, with their types: `VerifyReport`
is `report.json`'s shape, and gains fields the same way. The verifier is a step in other
people's pipelines, so a check that turns a pass into a fail comes in a minor, never a patch; a new
warning can come in any release.
Expand Down
4 changes: 3 additions & 1 deletion packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,9 @@ plain lines for a review, made when it is first read: what the author wrote, the
marked, slides, chapters and questions numbered, a scenario's links and a video's times written,
interface texts and settings left out. `outlineOf(libraries, content, { limit })` makes one from
what `loadLibraries` loaded for a content and the content, `{ type, params }`, as `checkContent`
takes them, cut at `limit` lines where one is given.
takes them, cut at `limit` lines where one is given. `await inside(path, folders)` is the
confinement `within` applies, for a tool beside the build that reads files of its own: whether a
path, links followed, is in one of the folders.

```js
import { readFile } from 'node:fs/promises'
Expand Down
2 changes: 1 addition & 1 deletion packages/author/lib/author.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ import { schemaLines, schemaMarkdown } from './schema.mjs'
import { LAYOUTS } from './types.mjs'

export * from './core.mjs'
export { buildPackage, openPack, publicFetch, writeBundle, writeBundles } from './node.mjs'
export { buildPackage, inside, openPack, publicFetch, writeBundle, writeBundles } from './node.mjs'

/**
* @typedef {import('./node.mjs').BuildResult} BuildResult
Expand Down
5 changes: 4 additions & 1 deletion packages/author/tests/package-types.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
// The package as a caller sees it, by its own name: through the `types` condition, so this checks the
// published declarations, not the source. `pnpm typecheck` writes them first.
import {
allowedTags, buildPackage, bundleLibraries, checkContent, ContentGenerator, contentTypes, GENERATED_START, loadLibraries, markupText, openPack, packageLibraries, plainText, schemaOf, SourceError,
allowedTags, buildPackage, bundleLibraries, checkContent, ContentGenerator, contentTypes, GENERATED_START, inside, loadLibraries, markupText, openPack, packageLibraries, plainText, schemaOf, SourceError,
sourceSchema, writeBundle, writeBundles,
type BuildResult, type BundleResult, type CheckedContent, type LibraryRecord, type LibrarySource, type PackageFiles, type Source, type TranslationReport
} from '@missing-elements/h5p-author'
Expand All @@ -26,6 +26,9 @@ export async function check(): Promise<[BuildResult, string, string]> {
const generator = new ContentGenerator(new Map(), { lenient: true, id: (count) => String(count) })
generator.problems.length = 0
void readSource
// A tool that confines what it reads to folders asks as a confined build does.
const confined: boolean = await inside('lesson/picture.png', ['lesson'])
void confined
return [built, await schemaOf('H5P.Blanks', { markdown: true }), GENERATED_START]
}

Expand Down
Loading
Loading