@missing-elements/h5p-embed 0.6.2 → 0.7.0

package/README.md

@@ -47,14 +47,27 @@ npx @missing-elements/h5p-embed h5p-player \
 
 ## Hosting
 
-| Host | Policy and caching |
+Any static host, over https, at a domain's root or under a path. The page carries its own
+policy in a `<meta>` tag, so it is protected wherever it is served. The headers — the same
+policy with `frame-ancestors`, and the caching — are written beside it in the form each kind of
+host reads; use the one yours does and ignore the rest:
+
+| Host | File |
+|---|---|
+| A server of your own — Hetzner, IONOS, OVH, Scaleway, a university's machine | `Caddyfile` (run it as it is; Caddy fetches the certificate), `nginx.conf` (include it in the server block), `.htaccess` (Apache with `mod_headers`) |
+| Netlify, Cloudflare Pages | `_headers` |
+| Vercel | `vercel.json` |
+| GitHub Pages, S3 and other object storage | none can set headers: the page's `<meta>` policy applies, `--ancestors` does not, and `h5p-sw.js` is cached by the host's default |
+
+The headers themselves, for a host not listed:
+
+| Path | Headers |
 |---|---|
-| Netlify, Cloudflare Pages | `_headers`, written beside the page |
-| Vercel | `vercel.json`, written beside the page |
-| GitHub Pages, S3, nginx, others | a `<meta>` policy in the page; `--ancestors` needs a `Content-Security-Policy: frame-ancestors …` header set on the server |
+| every path | `Content-Security-Policy` (the policy the command prints, with `frame-ancestors` from `--ancestors`), `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin` |
+| `/h5p-sw.js` | `Cache-Control: no-cache`, so an update reaches learners on their next visit |
+| `/frame-assets/*`, `/resizer.js`, `/libraries.h5p` | `Cache-Control: public, max-age=3600, stale-while-revalidate=86400` |
 
-It works at a domain's root or under a path, over https. Serve `h5p-sw.js` with
-`Cache-Control: no-cache`. To update, run the command again with `--force` and redeploy.
+To update, run the command again with `--force` and redeploy.
 
 ## The address
 

package/bin/h5p-embed.mjs

@@ -84,8 +84,10 @@ subdomain of your site — then embed a package:
           style="width: 100%; border: 0"></iframe>
   <script src="https://<player domain>/resizer.js"></script>
 
-_headers (Netlify, Cloudflare Pages) and vercel.json (Vercel) carry the policy and the caching.
-Other hosts, GitHub Pages among them, get the policy from the page itself${site.ancestors ? ', without --ancestors,\nwhich only a header can carry' : ''}.`)
+The page carries its policy; the headers beside it are written for five kinds of host:
+Caddyfile, nginx.conf and .htaccess for a server of your own, _headers for Netlify and
+Cloudflare Pages, vercel.json for Vercel. Object storage and GitHub Pages serve the page's own
+policy and no headers${site.ancestors ? ' — there --ancestors has no effect, since only a header\ncan carry it' : ''}.`)
 } catch (error) {
   if (error instanceof EmbedError) {
     console.error(`h5p-embed: ${error.message}`)

package/lib/build.mjs

@@ -52,7 +52,7 @@ export function parseOrigin(value) {
 }
 
 /** Where the element's `libraries="pack"` fetches from when a site carries no copy of its own. */
-export const PACK_CDN_ORIGIN = 'https://cdn.jsdelivr.net'
+const PACK_CDN_ORIGIN = 'https://cdn.jsdelivr.net'
 
 /**
  * A `libraries` value for addresses that name none, checked against the site it goes into: the
@@ -168,11 +168,87 @@ function vercelConfig(rules) {
   ) + '\n'
 }
 
+/*
+ * The three server formats below are for a host of one's own — the European hosts a data
+ * protection officer accepts have no `_headers` convention, and a university's Apache or an
+ * nginx on a Hetzner box is where the embed page usually ends up. Each is written from the same
+ * rules as the two files above, so they cannot disagree. Values are quoted with double quotes
+ * in every format, which is safe because the policy carries only single quotes.
+ */
+
+/** The rule for every path, and the ones for a single path or prefix. */
+function splitRules(rules) {
+  const all = rules.find((rule) => rule.path === '/*')
+  return { all, specific: rules.filter((rule) => rule !== all) }
+}
+
+/** Caddy's `Caddyfile`: a site block to run as it is, or to paste into one. */
+function caddyfile(rules) {
+  const { all, specific } = splitRules(rules)
+  const lines = [
+    '# Written by h5p-embed. Replace the domain and the root, then `caddy run` beside this file,',
+    '# or paste the block into your Caddyfile. Caddy fetches the certificate itself.',
+    'h5p-player.example.net {',
+    '\troot * /srv/h5p-player',
+    '\tfile_server',
+    ...Object.entries(all.headers).map(([key, value]) => `\theader ${key} "${value}"`),
+    ...specific.flatMap(({ path, headers }) => Object.entries(headers).map(([key, value]) => `\theader ${path} ${key} "${value}"`)),
+    '}'
+  ]
+  return lines.join('\n') + '\n'
+}
+
+/**
+ * nginx: a file to `include` inside the `server` block that serves the folder. nginx's
+ * `add_header` in a `location` replaces every `add_header` inherited from the server level
+ * rather than adding to it, so each location repeats the headers that apply everywhere.
+ */
+function nginxConf(rules) {
+  const { all, specific } = splitRules(rules)
+  const header = ([key, value]) => `add_header ${key} "${value}" always;`
+  const matcher = (path) => (path.endsWith('/*') ? `^~ ${path.slice(0, -1)}` : `= ${path}`)
+  const lines = [
+    '# Written by h5p-embed. Include this file inside the server block that serves the folder:',
+    '#   server { listen 443 ssl; server_name h5p-player.example.net; root /srv/h5p-player; include /srv/h5p-player/nginx.conf; }',
+    '# A location repeats the headers set for every path: in nginx an add_header inside a location',
+    '# replaces the inherited ones instead of adding to them.',
+    ...Object.entries(all.headers).map(header),
+    ...specific.map(
+      ({ path, headers }) =>
+        `location ${matcher(path)} {\n${[...Object.entries(all.headers), ...Object.entries(headers)].map((entry) => `\t${header(entry)}`).join('\n')}\n}`
+    )
+  ]
+  return lines.join('\n') + '\n'
+}
+
+/** Apache's `.htaccess`, for a folder under a vhost that allows it. */
+function htaccess(rules) {
+  const { all, specific } = splitRules(rules)
+  const header = ([key, value]) => `Header always set ${key} "${value}"`
+  const block = ({ path, headers }) => {
+    const body = Object.entries(headers).map((entry) => `\t${header(entry)}`).join('\n')
+    // <Files> matches a name in any directory; a prefix needs the request URI, with no anchor at
+    // the start, so that the site works under a path as well as at a root.
+    return path.endsWith('/*')
+      ? `<If "%{REQUEST_URI} =~ m#${path.slice(0, -1)}#">\n${body}\n</If>`
+      : `<Files "${path.slice(1)}">\n${body}\n</Files>`
+  }
+  const lines = [
+    '# Written by h5p-embed. Needs mod_headers, and AllowOverride FileInfo on the folder; or paste',
+    '# the directives into the virtual host.',
+    ...Object.entries(all.headers).map(header),
+    ...specific.map(block)
+  ]
+  return lines.join('\n') + '\n'
+}
+
 function notice({ version, libraries }) {
   return `This folder is the H5P embed page, written by @missing-elements/h5p-embed.
 
   index.html, main.js, embed.js, embed.css, resizer.js, config.js
                     the embed page and the sizing script: MIT
+  Caddyfile, nginx.conf, .htaccess, _headers, vercel.json
+                    the same headers for five kinds of host; use the one yours reads
   h5p-player.js, h5p-sw.js, h5p-jobs.js
                     @missing-elements/h5p-offline-player ${version}: MIT. The two workers also
                     carry zip.js, BSD-3-Clause, its licence in each file's header.
@@ -259,6 +335,9 @@ export async function buildSite({ out, libraries = true, packages = null, ancest
   const rules = headerRules(csp)
   await writeFile(join(target, '_headers'), netlifyHeaders(rules))
   await writeFile(join(target, 'vercel.json'), vercelConfig(rules))
+  await writeFile(join(target, 'Caddyfile'), caddyfile(rules))
+  await writeFile(join(target, 'nginx.conf'), nginxConf(rules))
+  await writeFile(join(target, '.htaccess'), htaccess(rules))
   await writeFile(join(target, 'NOTICE.txt'), notice({ version, libraries: Boolean(pack) }))
 
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@missing-elements/h5p-embed",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Self-hosted H5P embeds: writes the H5P embed page as a static site for a player domain of your own, then any site frames it with an iframe and one script line. No H5P server, no third-party service; optional allowlists for package hosts and embedding sites.",
   "license": "MIT",
   "repository": {
@@ -43,14 +43,14 @@
     "cli"
   ],
   "dependencies": {
-    "@missing-elements/h5p-runtime": "^0.2.3",
     "@missing-elements/h5p-libraries": "^0.2.0",
-    "@missing-elements/h5p-offline-player": "^0.9.3"
+    "@missing-elements/h5p-offline-player": "^0.9.5",
+    "@missing-elements/h5p-runtime": "^0.2.4"
   },
   "devDependencies": {
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "@zip.js/zip.js": "^2.23.0",
-    "playwright": "^1.50.0",
+    "playwright": "^1.64.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.3"
   },

package/site/embed.js

@@ -75,7 +75,11 @@ export function startEmbed({ librariesPack = null, packages = null, defaultLibra
 
   /* ---------------------------------------------------------------- sizing, upward */
 
-  /** The parent hears about the height in the shape h5p-resizer.js expects. Nothing in it is secret. */
+  /**
+   * A message to the page that frames this one: the height in the shape h5p-resizer.js expects,
+   * and `report`, `error` and `xapi` in this page's own. To any parent unless a target is named,
+   * since nothing in the height is secret; the xAPI relay names the origin that opted in.
+   */
   const post = (message, target = '*') => {
     if (framed) window.parent.postMessage(message, target)
   }