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
2 changes: 2 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,8 @@ model may have written:
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.
A YouTube or Vimeo address is sent to that site's oEmbed endpoint, which says
whether it has the video.
- 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
Expand Down
28 changes: 27 additions & 1 deletion design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,33 @@ text to the content check's rules, and `apps/skills` plays every example untrust
Echo360 address stays an address, as the editor
embeds it, and only where H5P.Video's own pattern for that host takes it, since an address none
matches goes to its HTML5 player, which cannot play a page: a Short or a live stream is written
as its video's watch address, and another form on those hosts is refused by name.
as its video's watch address, and another form on those hosts is refused by name. A YouTube or
Comment thread
alekswebnet marked this conversation as resolved.
Resolved
Vimeo address is asked of the host's oEmbed, which answers anyone, a page too (#218): an address
holds to its form only, and a made-up id built and showed a dead player. What a status means is
each host's own list (`answers` in `media.mjs`), as seen on real videos on 2026-11-20. YouTube:
400 for an id it never had and 404 for a video taken down, both a problem; 403 for a private
video, a note, since its owner can open it; 200 for one that asks a viewer's age; 401 was not
seen, is said to be embedding turned off, and is a note. Vimeo: 404 for no such video, a
private one, and an unlisted one given without the rest of its link, a problem that says so; a
video behind a password or let to some sites only answers 200 (Vimeo's help centre), and its
403 is Vimeo refusing the asker's network, so it says nothing.
- **Only the host's own answer counts.** A sandbox's proxy or a school's filter answers for the
host, and would otherwise refuse a build with no way round, or put a note on every video.
Both hosts send a status that is no video in a way of their own (`sends`): YouTube that
status's words alone ("Bad Request", "Forbidden", "Not Found", and "Unauthorized" expected
of the 401 that was not seen) under its JSON type, Vimeo a page of them ("404 Not Found",
`text/html`). A status that means something counts only when
it comes so, its own words and the host's type; a page of the box's own, the words under
another type as a small proxy sends them, or another status's words say nothing, as do any
other status, no network, and no answer in ten seconds, and the build goes on. A box that
copies both the words and the type would still be taken for the host: none was seen. If a
host changes how it answers, the check goes quiet, not wrong.
- **A host that does not answer costs ten seconds once.** Videos are asked one at a time, and
after the first with no answer that host is not asked again in that build; the other still
is. One video named twice is asked once. YouTube is asked by the video's watch address, since its oEmbed answers 404 for
the `/embed/` and `/v/` forms of a video it has.
- Panopto and Echo360 answer no one and are not asked. A read asks nothing. The tests never
ask: a setup file answers for both hosts (`tests/helpers/oembed.ts`).
`build.test.ts` holds each accepted form to the patterns in H5P.Video's scripts. A package with
media goes through the normalizer's `normalizeArchive`, stored and laid out to stream. An addon
whose pattern the text matches, H5P.MathDisplay for LaTeX, is carried as a site with it
Expand Down
9 changes: 7 additions & 2 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,11 @@ What `params` takes is what H5P's editor would let an author save in the same fo
and, where it gives one, its length, past which an Interactive Video's times are refused. The
package is then laid out to stream, media stored and an mp4's index first. A YouTube, Vimeo,
Panopto or Echo360 address stays where it is, if it is one H5P.Video plays: a Short's is taken
as its video's, and another address on those sites is refused. A download is given up once
as its video's, and another address on those sites is refused. A YouTube or Vimeo video is
asked of the site's oEmbed, which is sent the video's address: one the site has no video at is
refused, one YouTube says is private is a note, as is its 401, taken to mean that embedding is
turned off (not seen yet), and with no answer of the site's own in ten seconds, behind a proxy
that answers for it or with no network, the build goes on without one. A download is given up once
nothing has arrived for a minute, however long it runs.
- **Interface texts** (Check, Retry…): leave them out; they come from the libraries' translations,
and the command lists what stayed English. A source may still set one by name.
Expand Down Expand Up @@ -233,7 +237,8 @@ const { output, source: built, builtWith, manifest, content, libraries, install,
and throws a `SourceError` whose `problems` are `{ path, message }`; with `check` it builds and
writes no package and takes no output (`buildPackage(source, undefined, { check: true })`), though 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. For a build run
YouTube, Vimeo, Panopto or Echo360 stays an address, as in a build, a YouTube or Vimeo one asked
of the site with the same `fetch`. For a build run
on what a model wrote: `within` is a list of the folders the output and every local file the source
names must be inside, on their real paths, and its problems then name no path but the one the
source wrote. It does not cover a file named by web address, which is downloaded with the `fetch`
Expand Down
120 changes: 115 additions & 5 deletions packages/author/lib/media.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -47,23 +47,55 @@ const under = (host, domains) => domains.some((domain) => host === domain || hos
* an address by its own pattern for each host, and gives one no pattern matches to its HTML5
* player, which cannot play a page. So `plays` takes only addresses H5P.Video 1.6's pattern for
* the host takes as well, and any other address on the host (`on`, told by its name, with no
* pattern to backtrack through its labels) is refused, naming the form.
* @type {{ host: string, mime: string, plays: RegExp, on: (url: URL) => boolean, form: string }[]}
* pattern to backtrack through its labels) is refused, naming the form. `oembed` is where the
* host says whether it has the video, for the two hosts that answer anyone (#218), and `answers`
* what each status it answers there means, as seen on 2026-11-20: a problem (`gone`) or a note
* (`closed`), each with the words for it. A status not listed says nothing. `sends` is how the
* host itself sends such a status, its body and the type it gives it, by which its own answer is
* told from one a box in between gives for it (`#ask`).
* @type {{ host: string, mime: string, plays: RegExp, on: (url: URL) => boolean, form: string, oembed?: (address: string) => string, sends?: { type: string, body: (status: number) => string }, answers?: Record<number, { gone?: string, closed?: string }> }[]}
*/
const HOSTED = [
{
host: 'Vimeo',
mime: 'video/Vimeo',
plays: /^https?:\/\/(?:[\w-]+\.)*vimeo\.com\/(?:channels\/[A-Za-z_]+\/|groups\/[A-Za-z_]+\/videos\/)?\d/,
on: (url) => under(url.hostname, ['vimeo.com']),
form: 'https://vimeo.com/ and the video\'s number'
form: 'https://vimeo.com/ and the video\'s number',
// Every form it plays, a channel's and a group's too, and an unlisted video's with its hash.
oembed: (address) => `https://vimeo.com/api/oembed.json?url=${encodeURIComponent(address)}`,
// Its 404 is a page of the words alone.
sends: { type: 'text/html', body: (status) => `${status} ${STATUS_WORDS[status]}` },
// 404 for no such video, a private one, and an unlisted one asked of without the rest of its
// link (Vimeo's help centre). A video behind a password or let to some sites only answers
// 200, and a 403 is Vimeo refusing the asker's network, which says nothing of the video.
answers: {
404: { gone: 'has no video there that others can play: give https://vimeo.com/ and the number of a public video, or all of an unlisted video\'s link, which has more after the number' }
}
},
{
host: 'YouTube',
mime: 'video/YouTube',
plays: /^https?:\/\/(?:[\w-]+\.)*(?:youtube\.com\/(?:watch\?(?:[^#\s]*&)?v=|embed\/|v\/)|youtu\.be\/)[\w-]{11}/i,
on: (url) => under(url.hostname, ['youtube.com', 'youtube-nocookie.com', 'youtu.be']),
form: 'https://www.youtube.com/watch?v= and the video\'s id'
form: 'https://www.youtube.com/watch?v= and the video\'s id',
// Asked by its watch address: YouTube's oEmbed answers 404 for /embed/ and /v/ addresses of a
// video it has (2026-11-20).
oembed: (address) => {
const id = YOUTUBE_ID.exec(address)?.[1]
return id ? `https://www.youtube.com/oembed?format=json&url=${encodeURIComponent(`https://www.youtube.com/watch?v=${id}`)}` : ''
},
// The status's words alone, under the type of the answer it would have given.
sends: { type: 'application/json', body: (status) => STATUS_WORDS[status] },
// Seen: 400 for an id it never had, 404 for a video taken down, 403 for a private one, and
// 200 for one that asks a viewer's age. 401 was not seen: it is said to be a video whose
// owner has turned embedding off.
answers: {
400: { gone: 'has no video there: give https://www.youtube.com/watch?v= and the id of a public or unlisted video' },
404: { gone: 'has no video there any more: give https://www.youtube.com/watch?v= and the id of a public or unlisted video' },
403: { closed: 'says the video is private: nobody but its owner can play it until it is made public or unlisted' },
401: { closed: 'would not say the video may be embedded, which is taken to mean its owner has turned embedding off: play it where it will be used' }
}
},
{
host: 'Panopto',
Expand All @@ -81,6 +113,21 @@ const HOSTED = [
}
]

/** A YouTube video's id, in an address H5P.Video plays. */
const YOUTUBE_ID = /(?:[?&]v=|\/embed\/|\/v\/|youtu\.be\/)([\w-]{11})/i

/** How long a host may take to say whether it has a video, before the build goes on without it. */
const ASK_MS = 10_000

/**
* A status's words, which YouTube and Vimeo send alone with an answer that is no video ("Bad
* Request" under YouTube's JSON type, "404 Not Found" as Vimeo's page): each host's `sends`. A box
* between the build and the host, a sandbox's proxy or a school's filter, answers with a page of
* its own or under a type of its own, and so does Vimeo where it refuses the asker's network: none
* of those is the host speaking of the video.
*/
const STATUS_WORDS = /** @type {Record<number, string>} */ ({ 400: 'Bad Request', 401: 'Unauthorized', 403: 'Forbidden', 404: 'Not Found' })

/** A YouTube Short or live stream, by its video's id, which H5P.Video plays at the watch address. */
const YOUTUBE_SHORT = /^https?:\/\/(?:[\w-]+\.)*youtube\.com\/(?:shorts|live)\/([\w-]{11})(?![\w-])/i

Expand Down Expand Up @@ -263,6 +310,10 @@ export class MediaStore {
this.names = new Set()
/** @type {Map<string, number>} a video's or a recording's length in seconds, by its path in the package, where its index gave one */
this.lengths = new Map()
/** @type {Map<string, Promise<number>>} what a host answered of a video, by the address asked, so one video named twice is asked of once */
this.asked = new Map()
/** @type {Set<string>} the hosts that gave no answer at all, none of which is asked again in this build */
this.unanswered = new Set()
}

/**
Expand Down Expand Up @@ -293,7 +344,10 @@ export class MediaStore {
const short = YOUTUBE_SHORT.exec(source)
const address = short ? `https://www.youtube.com/watch?v=${short[1]}` : source
const hosted = HOSTED.find(({ plays }) => plays.test(address))
if (hosted) return { path: address, mime: hosted.mime, copyright }
if (hosted) {
await this.#there(hosted, address, source, `${at}.path`, report, note)
return { path: address, mime: hosted.mime, copyright }
}
const url = URL.canParse(address) ? new URL(address) : null
const other = url ? HOSTED.find(({ on }) => on(url)) : undefined
if (other) {
Expand Down Expand Up @@ -432,6 +486,62 @@ export class MediaStore {
return { from: found.file, extension, stem: name.slice(0, name.length - extension.length - 1) }
}

/**
* Whether a host has a video, asked of its oEmbed endpoint where it has one (#218): an address
* holds to its form only, so a made-up id built and showed a dead player. What an answer means
* is the host's own list (`answers`): a video that is not there is a problem, and one nobody
* else can play yet a note, since its owner can open it. Any other answer, one that is not the
* host's own (`#ask`), no network, or no answer in ten seconds says nothing either way, and the
* build goes on without it.
* @param {(typeof HOSTED)[number]} hosted
* @param {string} address as H5P.Video will play it
* @param {string} source as written
* @param {string} at
* @param {(path: string, message: string) => void} report
* @param {(path: string, message: string) => void} note
*/
async #there(hosted, address, source, at, report, note) {
const ask = hosted.oembed?.(address)
if (!ask || !hosted.answers) return
let answer = this.asked.get(ask)
if (!answer) {
// One at a time, and a host that does not answer costs its ten seconds once, not a video.
if (this.unanswered.has(hosted.host)) return
answer = this.#ask(ask, hosted)
this.asked.set(ask, answer)
}
const status = await answer
if (status === 0) this.unanswered.add(hosted.host)
const meaning = hosted.answers[status]
if (meaning?.gone) report(at, `${source}: ${hosted.host} ${meaning.gone} (it answered ${status})`)
else if (meaning?.closed) note(at, `${source}: ${hosted.host} ${meaning.closed} (it answered ${status})`)
}

/**
* The status a host's oEmbed endpoint answers; 0 where it does not answer in time, and -1 where
* a status that would say something of the video is not sent as the host sends it (`sends`):
* that status's own words and nothing else, under the host's type.
* @param {string} url
* @param {(typeof HOSTED)[number]} hosted
* @returns {Promise<number>}
*/
async #ask(url, hosted) {
try {
const response = await this.fetch(url, { signal: AbortSignal.timeout(ASK_MS) })
const { status } = response
if (!hosted.answers || !hosted.sends || !Object.hasOwn(hosted.answers, status)) {
await response.body?.cancel().catch(() => {})
return status
}
const type = (response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase()
const own = type === hosted.sends.type && (await response.text()).trim() === hosted.sends.body(status)
if (!own) await response.body?.cancel().catch(() => {})
return own ? status : -1
} catch {
return 0
}
}

/**
* A web address downloaded and kept, its type taken from its name or, failing that, from what
* the server says it is.
Expand Down
3 changes: 2 additions & 1 deletion packages/author/lib/node.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,8 @@ import { SourceError } from './source-error.mjs'
* list even of one; `check`, to build and write no package: no output is needed or looked at, and
* the result's `output` is empty, but a media file named by web address is still downloaded, to a
* temporary folder removed after, as the build checks it; a video on YouTube, Vimeo, Panopto or
* Echo360 stays an address, as in a build
* Echo360 stays an address, as in a build, a YouTube or Vimeo one asked of the site's oEmbed with
* `fetch` as a build asks it
* @typedef {{ output: string, source: import('./build.mjs').Source, files: string[], notes: Problem[] }} ReadResult
* `output`, the source's path; `files`, the media written beside it, by the paths the source
* names them by, from its folder; `notes`, what was left out or could not be read back as it is
Expand Down
Loading