From 75fed052e3dcb5cd876729863bc5e292aaca022c Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Thu, 5 Nov 2026 21:51:04 -0800 Subject: [PATCH 1/5] Plug-in Library: a package downloads only release assets of its repository A catalog release's url was checked only for its host: any https:// URL on GitHub's hosts was downloaded, from any repository and any path, including a raw file on a branch or a path with dot segments that curl resolves to another repository. library.install, library.update and library.preview now refuse a url that isn't https://github.com///releases/download//. When the package's repo is a https://github.com// URL, the asset must be in that repository (owner and name compared without case). Dot segments, also percent-encoded, empty segments, backslashes, queries and fragments are refused. file:// releases from a local catalog are read as before, and the SHA-256 and size checks are unchanged. A catalog other than the community one is still read only when library.refresh names it (https:// on GitHub's hosts, or a local file://). docs/plugins.md, docs/publishing-plugins.md and the library.install params text describe the rules. --- crates/engine/src/system/library.rs | 98 ++++++++++++++++++++++++++++- crates/host/tests/it/library.rs | 32 ++++++++++ docs/plugins.md | 6 +- docs/publishing-plugins.md | 2 +- 4 files changed, 134 insertions(+), 4 deletions(-) diff --git a/crates/engine/src/system/library.rs b/crates/engine/src/system/library.rs index 750ed600a..0e55c8acb 100644 --- a/crates/engine/src/system/library.rs +++ b/crates/engine/src/system/library.rs @@ -255,6 +255,58 @@ fn release_problem(r: &Release) -> Option { None } +/// An owner or repository name on GitHub: letters, digits, `.`, `-`, `_`, and not `.` or `..`. +fn valid_repo_part(p: &str) -> bool { + !p.is_empty() && p != "." && p != ".." && p.bytes().all(|b| b.is_ascii_alphanumeric() || b"._-".contains(&b)) +} + +/// The rest of `s` after `prefix`, ignoring ASCII case. +fn strip_prefix_ignore_case<'a>(s: &'a str, prefix: &str) -> Option<&'a str> { + let head = s.get(..prefix.len())?; + head.eq_ignore_ascii_case(prefix).then(|| s.get(prefix.len()..)).flatten() +} + +/// `(owner, name)` in lower case of a `https://github.com//` repository URL (an +/// optional trailing `/` or `.git`); `None` for anything else. +fn github_repo(repo: &str) -> Option<(String, String)> { + let rest = strip_prefix_ignore_case(repo.trim(), "https://github.com/")?; + let rest = rest.strip_suffix('/').unwrap_or(rest); + let rest = rest.strip_suffix(".git").unwrap_or(rest); + let mut parts = rest.split('/'); + let (owner, name) = (parts.next()?, parts.next()?); + (parts.next().is_none() && valid_repo_part(owner) && valid_repo_part(name)).then(|| (owner.to_ascii_lowercase(), name.to_ascii_lowercase())) +} + +/// Why an `https://` release URL can't be used, if it can't: it must be a release asset, +/// `https://github.com///releases/download//`, and when the package's +/// `repo` is a GitHub repository URL, `/` must be that repository. +fn release_url_problem(repo: &str, url: &str) -> Option { + let not_asset = || Some(format!("`{url}` isn't a release asset (https://github.com///releases/download//)")); + let Some(rest) = strip_prefix_ignore_case(url, "https://github.com/") else { return not_asset() }; + if rest.contains(['?', '#', '\\']) { + return not_asset(); + } + let parts: Vec<&str> = rest.split('/').collect(); + // `.` and `..` (also percent-encoded) would move the download to another path. + let dot_segment = |p: &&str| { + let p = p.to_ascii_lowercase().replace("%2e", "."); + p == "." || p == ".." + }; + if parts.len() < 6 || parts.iter().any(|p| p.is_empty() || dot_segment(p)) { + return not_asset(); + } + let (Some(owner), Some(name), Some(releases), Some(download)) = (parts.first(), parts.get(1), parts.get(2), parts.get(3)) else { return not_asset() }; + if !valid_repo_part(owner) || !valid_repo_part(name) || *releases != "releases" || *download != "download" { + return not_asset(); + } + match github_repo(repo) { + Some((o, n)) if o != owner.to_ascii_lowercase() || n != name.to_ascii_lowercase() => { + Some(format!("`{url}` isn't a release asset of the package's repository {}", repo.trim())) + } + _ => None, + } +} + /// Read a catalog: packages and releases that are malformed are left out (and reported), so one /// bad entry doesn't hide the others. pub fn parse_catalog(bytes: &[u8]) -> std::result::Result<(Catalog, Vec), String> { @@ -799,7 +851,11 @@ fn pick(s: &Session, c: &str, p: &Value) -> Result<(String, Package, Release)> { ), )); } - source(&rel.url, Some(&url)).map_err(|e| bad(c, e))?; + if let Source::Https(u) = source(&rel.url, Some(&url)).map_err(|e| bad(c, e))? + && let Some(why) = release_url_problem(&pkg.repo, &u) + { + return Err(bad(c, why)); + } Ok((url, pkg, rel)) } @@ -1049,7 +1105,7 @@ pub fn specs() -> Vec { "Install Plug-in", [], None, - "{id, version?, wait?} — downloads the release, checks its SHA-256 against the catalog, loads it", + "{id, version?, wait?} — downloads the release (a GitHub release asset, in the package's repo when it names one), checks its SHA-256 against the catalog, loads it", always, install ), @@ -1132,6 +1188,44 @@ mod tests { assert!(latest_compatible(&Package::default()).is_none()); } + #[test] + fn release_urls_are_assets_of_the_declared_repository() { + let asset = "https://github.com/Me/Glow/releases/download/v1.0.0/glow.wasm"; + for repo in ["https://github.com/me/glow", "https://github.com/Me/Glow/", "https://GitHub.com/me/glow.git", "", "https://gitlab.com/me/glow"] { + assert_eq!(release_url_problem(repo, asset), None, "{repo}"); + } + assert_eq!(release_url_problem("", "https://github.com/a/b/releases/download/tags/v1/x.wasm"), None, "a tag with a slash"); + assert!( + release_url_problem("https://github.com/me/glow", "https://github.com/me/other/releases/download/v1/x.wasm") + .unwrap() + .contains("package's repository") + ); + assert!(release_url_problem("https://github.com/me/glow", "https://github.com/you/glow/releases/download/v1/x.wasm").is_some()); + for no in [ + "https://raw.githubusercontent.com/me/glow/main/x.wasm", + "https://objects.githubusercontent.com/x.wasm", + "https://github.com/me/glow/blob/main/x.wasm", + "https://github.com/me/glow/releases/download/v1", + "https://github.com/me/glow/releases/download//x.wasm", + "https://github.com/me/glow/releases/download/v1/x.wasm?x=1", + "https://github.com/me/glow/releases/download/v1/x.wasm#x", + "https://github.com/me/glow/releases/download/../../../you/evil/releases/download/v1/x.wasm", + "https://github.com/me/glow/releases/download/%2e%2e/%2E./x/y/x.wasm", + "https://github.com/me/glow/releases/download/./v1/x.wasm", + "https://github.com/me/glow/releases/download/v1\\x.wasm", + "https://github.com/m e/glow/releases/download/v1/x.wasm", + "https://github.com/../glow/releases/download/v1/x.wasm", + "https://github.com.evil.com/me/glow/releases/download/v1/x.wasm", + ] { + assert!(release_url_problem("https://github.com/me/glow", no).is_some(), "{no}"); + assert!(release_url_problem("", no).is_some(), "{no}"); + } + assert_eq!(github_repo("https://github.com/Me/Glow.git"), Some(("me".into(), "glow".into()))); + for no in ["https://github.com/me", "https://github.com/me/glow/tree/main", "http://github.com/me/glow", "me/glow"] { + assert_eq!(github_repo(no), None, "{no}"); + } + } + #[test] fn catalogs_leave_out_bad_entries() { let good = "a".repeat(64); diff --git a/crates/host/tests/it/library.rs b/crates/host/tests/it/library.rs index 4cd94ecdd..f5bd613cc 100644 --- a/crates/host/tests/it/library.rs +++ b/crates/host/tests/it/library.rs @@ -156,6 +156,38 @@ fn a_wrong_checksum_or_a_bad_module_installs_nothing() { let _ = std::fs::remove_dir_all(&dir); } +#[test] +fn downloads_are_release_assets_of_the_package_repository() { + let dir = tmp("assets"); + let sum = "0".repeat(64); + let pkg = + |id: &str, repo: &str, url: &str| json!({"id": id, "name": id, "repo": repo, "versions": [{"version": "1", "api": 1, "url": url, "sha256": sum}]}); + let catalog = write_catalog( + &dir, + json!([ + pkg("org.test.other", "https://github.com/me/glow", "https://github.com/someone/else/releases/download/v1/glow.wasm"), + pkg("org.test.raw", "https://github.com/me/glow", "https://raw.githubusercontent.com/me/glow/main/glow.wasm"), + pkg("org.test.page", "", "https://github.com/me/glow/blob/main/glow.wasm"), + pkg("org.test.dots", "https://github.com/me/glow", "https://github.com/me/glow/releases/download/%2e%2e/%2E%2E/x/y/glow.wasm"), + ]), + ); + let mut s = session(&dir); + s.execute("library.refresh", json!({"catalog": catalog, "wait": true})).unwrap(); + for (id, why) in [ + ("org.test.other", "isn't a release asset of the package's repository https://github.com/me/glow"), + ("org.test.raw", "isn't a release asset"), + ("org.test.page", "isn't a release asset"), + ("org.test.dots", "isn't a release asset"), + ] { + for c in ["library.install", "library.preview"] { + let e = s.execute(c, json!({"id": id, "wait": true})).unwrap_err().to_string(); + assert!(e.contains(why), "{c} {id}: {e}"); + } + } + assert!(!dir.join("Plug-ins").join("Library").join("installed.json").exists()); + let _ = std::fs::remove_dir_all(&dir); +} + #[test] fn installed_packages_load_at_start_and_changed_files_are_refused() { let dir = tmp("startup"); diff --git a/docs/plugins.md b/docs/plugins.md index 3fd8cf944..99b91874f 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -374,7 +374,11 @@ package can't read files, open the network or crash the app. Install (`library.install`) downloads the package's `.wasm`, checks its SHA-256 (and its size, when the catalog gives one) against the catalog and loads it. Downloads use the system's `curl`, `https://` only and starting on GitHub's hosts (redirects stay on `https://`; the SHA-256 check - is what guarantees the file). + is what guarantees the file). A package's `url` must be a release asset + (`https://github.com///releases/download/…`), in the package's `repo` when that is + a GitHub repository URL. A catalog other than the community one is read only when + `library.refresh {catalog}` names it: an `index.json` on GitHub's hosts over `https://`, or a + local `file://` path. * **Where it goes.** `/Library///.wasm` (the `Plug-ins` folder next to the settings), listed in `Library/installed.json`. Installed packages load at start-up, each checked against the SHA-256 it was installed with. The catalog last fetched is kept as diff --git a/docs/publishing-plugins.md b/docs/publishing-plugins.md index bd76c3ab5..c94f9e2a8 100644 --- a/docs/publishing-plugins.md +++ b/docs/publishing-plugins.md @@ -193,7 +193,7 @@ Release fields (one per entry in `versions`): | `version` | yes | Dotted numbers only, at most 32 characters: `1.0.0`, `1.2`. No `v` and no suffixes such as `-beta`. | | `api` | yes | The plug-in API the module implements: `1`. | | `minApp` | no | The oldest EffectCraft version the release needs (`0.17.0`). Leave it out if any version with this API works. | -| `url` | yes | The release asset's `https://` URL on GitHub. | +| `url` | yes | The release asset's `https://` URL on GitHub: `https://github.com///releases/download//`. When `repo` is a `https://github.com//` URL, the asset must be in that repository. Install and Preview refuse any other `https://` URL. | | `sha256` | yes | The file's SHA-256, 64 hex digits. | | `size` | no, but reviewed | The file's size in bytes. When it is given, a download of another size is refused. | | `effects` | yes | The effect ids the module registers (its manifest's `id`). EffectCraft uses them to find the package that provides an effect a project needs. | From 5dfcadd09bbca14eb53ec52694995eac4199f1be Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Thu, 5 Nov 2026 23:24:20 -0800 Subject: [PATCH 2/5] Plug-in Library: a package with an unreadable repo URL downloads nothing When a package names a `repo` that isn't a GitHub repository URL (`https://github.com//`, a trailing `/` or `.git` allowed, or a folder in one, `.../tree//`), Install, Update and Preview now refuse its release URLs with an error naming the package. Before, such a `repo` skipped the repository check and any GitHub release asset was downloaded. A package without a `repo` keeps any repository's release asset. The example catalog's schema now holds `repo` and release `url` to the same forms, and `scripts/validate.sh` checks that every release is an asset of the package's `repo` before it downloads anything. --- crates/engine/src/system/library.rs | 100 ++++++++++++++++---- crates/host/tests/it/library.rs | 6 ++ docs/plugins.md | 6 +- docs/publishing-plugins.md | 4 +- examples/plugin-catalog/schema.json | 8 +- examples/plugin-catalog/scripts/validate.sh | 22 ++++- 6 files changed, 117 insertions(+), 29 deletions(-) diff --git a/crates/engine/src/system/library.rs b/crates/engine/src/system/library.rs index 0e55c8acb..d1eaaf0bd 100644 --- a/crates/engine/src/system/library.rs +++ b/crates/engine/src/system/library.rs @@ -266,20 +266,33 @@ fn strip_prefix_ignore_case<'a>(s: &'a str, prefix: &str) -> Option<&'a str> { head.eq_ignore_ascii_case(prefix).then(|| s.get(prefix.len()..)).flatten() } +/// A `.` or `..` path segment, also percent-encoded. +fn dot_segment(p: &str) -> bool { + let p = p.to_ascii_lowercase().replace("%2e", "."); + p == "." || p == ".." +} + /// `(owner, name)` in lower case of a `https://github.com//` repository URL (an -/// optional trailing `/` or `.git`); `None` for anything else. +/// optional trailing `/` or `.git`) or of a folder in one, `https://github.com///tree//`; +/// `None` for anything else. fn github_repo(repo: &str) -> Option<(String, String)> { let rest = strip_prefix_ignore_case(repo.trim(), "https://github.com/")?; + if rest.contains(['?', '#', '\\']) { + return None; + } let rest = rest.strip_suffix('/').unwrap_or(rest); - let rest = rest.strip_suffix(".git").unwrap_or(rest); - let mut parts = rest.split('/'); - let (owner, name) = (parts.next()?, parts.next()?); - (parts.next().is_none() && valid_repo_part(owner) && valid_repo_part(name)).then(|| (owner.to_ascii_lowercase(), name.to_ascii_lowercase())) + let parts: Vec<&str> = rest.split('/').collect(); + let (owner, name) = match parts.as_slice() { + [owner, name] => (*owner, name.strip_suffix(".git").unwrap_or(name)), + [owner, name, "tree", folder @ ..] if !folder.is_empty() && folder.iter().all(|p| !p.is_empty() && !dot_segment(p)) => (*owner, *name), + _ => return None, + }; + (valid_repo_part(owner) && valid_repo_part(name)).then(|| (owner.to_ascii_lowercase(), name.to_ascii_lowercase())) } /// Why an `https://` release URL can't be used, if it can't: it must be a release asset, -/// `https://github.com///releases/download//`, and when the package's -/// `repo` is a GitHub repository URL, `/` must be that repository. +/// `https://github.com///releases/download//`, and when the package +/// names a `repo`, that must be a GitHub repository URL (see [`github_repo`]) of `/`. fn release_url_problem(repo: &str, url: &str) -> Option { let not_asset = || Some(format!("`{url}` isn't a release asset (https://github.com///releases/download//)")); let Some(rest) = strip_prefix_ignore_case(url, "https://github.com/") else { return not_asset() }; @@ -287,11 +300,9 @@ fn release_url_problem(repo: &str, url: &str) -> Option { return not_asset(); } let parts: Vec<&str> = rest.split('/').collect(); - // `.` and `..` (also percent-encoded) would move the download to another path. - let dot_segment = |p: &&str| { - let p = p.to_ascii_lowercase().replace("%2e", "."); - p == "." || p == ".." - }; + // At least six segments, not exactly six: a tag may contain `/` (`release/v1`), and its assets are + // then at `releases/download/release/v1/`. `.` and `..` (also percent-encoded) would move + // the download to another path. if parts.len() < 6 || parts.iter().any(|p| p.is_empty() || dot_segment(p)) { return not_asset(); } @@ -299,11 +310,16 @@ fn release_url_problem(repo: &str, url: &str) -> Option { if !valid_repo_part(owner) || !valid_repo_part(name) || *releases != "releases" || *download != "download" { return not_asset(); } + let repo = repo.trim(); + if repo.is_empty() { + return None; + } match github_repo(repo) { - Some((o, n)) if o != owner.to_ascii_lowercase() || n != name.to_ascii_lowercase() => { - Some(format!("`{url}` isn't a release asset of the package's repository {}", repo.trim())) - } - _ => None, + Some((o, n)) if o == owner.to_ascii_lowercase() && n == name.to_ascii_lowercase() => None, + Some(_) => Some(format!("`{url}` isn't a release asset of the package's repository {repo}")), + None => Some(format!( + "the package's `repo` {repo} isn't a GitHub repository URL (https://github.com//), so `{url}` can't be checked against it" + )), } } @@ -854,7 +870,7 @@ fn pick(s: &Session, c: &str, p: &Value) -> Result<(String, Package, Release)> { if let Source::Https(u) = source(&rel.url, Some(&url)).map_err(|e| bad(c, e))? && let Some(why) = release_url_problem(&pkg.repo, &u) { - return Err(bad(c, why)); + return Err(bad(c, format!("{}: {why}", pkg.name))); } Ok((url, pkg, rel)) } @@ -1191,7 +1207,7 @@ mod tests { #[test] fn release_urls_are_assets_of_the_declared_repository() { let asset = "https://github.com/Me/Glow/releases/download/v1.0.0/glow.wasm"; - for repo in ["https://github.com/me/glow", "https://github.com/Me/Glow/", "https://GitHub.com/me/glow.git", "", "https://gitlab.com/me/glow"] { + for repo in ["https://github.com/me/glow", "https://github.com/Me/Glow/", "https://GitHub.com/me/glow.git", ""] { assert_eq!(release_url_problem(repo, asset), None, "{repo}"); } assert_eq!(release_url_problem("", "https://github.com/a/b/releases/download/tags/v1/x.wasm"), None, "a tag with a slash"); @@ -1221,11 +1237,57 @@ mod tests { assert!(release_url_problem("", no).is_some(), "{no}"); } assert_eq!(github_repo("https://github.com/Me/Glow.git"), Some(("me".into(), "glow".into()))); - for no in ["https://github.com/me", "https://github.com/me/glow/tree/main", "http://github.com/me/glow", "me/glow"] { + assert_eq!(github_repo("https://github.com/Me/Glow/tree/main/plugins/glow"), Some(("me".into(), "glow".into()))); + for no in ["https://github.com/me", "https://github.com/me/glow/tree", "http://github.com/me/glow", "me/glow"] { assert_eq!(github_repo(no), None, "{no}"); } } + #[test] + fn a_repo_that_isnt_a_github_repository_url_refuses_every_release() { + let asset = "https://github.com/me/glow/releases/download/v1/glow.wasm"; + for repo in [ + "https://github.com/me/glow", + "https://github.com/me/glow/", + "https://github.com/me/glow.git", + "https://github.com/me/glow.git/", + " https://github.com/ME/glow ", + "https://github.com/me/glow/tree/main", + "https://github.com/me/glow/tree/main/plugins/glow/", + "", + " ", + ] { + assert_eq!(release_url_problem(repo, asset), None, "{repo:?}"); + } + let elsewhere = release_url_problem("https://github.com/me/glow/tree/main", "https://github.com/you/evil/releases/download/v1/glow.wasm"); + assert!(elsewhere.as_deref().is_some_and(|w| w.contains("package's repository")), "{elsewhere:?}"); + for repo in [ + "https://github.com/me/glow/tree", + "https://github.com/me/glow/tree/", + "https://github.com/me/glow/tree//x", + "https://github.com/me/glow/tree/main/../../you/evil", + "https://github.com/me/glow/tree/main/%2e%2e", + "https://github.com/me/glow/blob/main/README.md", + "https://github.com/me/glow.git/x", + "https://github.com/me/glow/releases", + "https://github.com/me/glow//", + "https://github.com/me", + "https://github.com/me/", + "http://github.com/me/glow", + "github.com/me/glow", + "me/glow", + "https://www.github.com/me/glow", + "https://gitlab.com/me/glow", + "https://github.com/me/glow?tab=readme", + "https://github.com/me/glow#readme", + "https://github.com/me/gl ow", + "https://github.com/me/..", + ] { + let why = release_url_problem(repo, asset); + assert!(why.as_deref().is_some_and(|w| w.contains("isn't a GitHub repository URL")), "{repo:?}: {why:?}"); + } + } + #[test] fn catalogs_leave_out_bad_entries() { let good = "a".repeat(64); diff --git a/crates/host/tests/it/library.rs b/crates/host/tests/it/library.rs index f5bd613cc..35cbf74a7 100644 --- a/crates/host/tests/it/library.rs +++ b/crates/host/tests/it/library.rs @@ -169,6 +169,9 @@ fn downloads_are_release_assets_of_the_package_repository() { pkg("org.test.raw", "https://github.com/me/glow", "https://raw.githubusercontent.com/me/glow/main/glow.wasm"), pkg("org.test.page", "", "https://github.com/me/glow/blob/main/glow.wasm"), pkg("org.test.dots", "https://github.com/me/glow", "https://github.com/me/glow/releases/download/%2e%2e/%2E%2E/x/y/glow.wasm"), + pkg("org.test.tree", "https://github.com/me/glow/tree/main", "https://github.com/someone/else/releases/download/v1/glow.wasm"), + pkg("org.test.http", "http://github.com/me/glow", "https://github.com/me/glow/releases/download/v1/glow.wasm"), + pkg("org.test.blob", "https://github.com/me/glow/blob/main/README.md", "https://github.com/me/glow/releases/download/v1/glow.wasm"), ]), ); let mut s = session(&dir); @@ -178,6 +181,9 @@ fn downloads_are_release_assets_of_the_package_repository() { ("org.test.raw", "isn't a release asset"), ("org.test.page", "isn't a release asset"), ("org.test.dots", "isn't a release asset"), + ("org.test.tree", "isn't a release asset of the package's repository https://github.com/me/glow/tree/main"), + ("org.test.http", "org.test.http: the package's `repo` http://github.com/me/glow isn't a GitHub repository URL"), + ("org.test.blob", "org.test.blob: the package's `repo` https://github.com/me/glow/blob/main/README.md isn't a GitHub repository URL"), ] { for c in ["library.install", "library.preview"] { let e = s.execute(c, json!({"id": id, "wait": true})).unwrap_err().to_string(); diff --git a/docs/plugins.md b/docs/plugins.md index 99b91874f..5302b0b3c 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -375,8 +375,10 @@ package can't read files, open the network or crash the app. catalog gives one) against the catalog and loads it. Downloads use the system's `curl`, `https://` only and starting on GitHub's hosts (redirects stay on `https://`; the SHA-256 check is what guarantees the file). A package's `url` must be a release asset - (`https://github.com///releases/download/…`), in the package's `repo` when that is - a GitHub repository URL. A catalog other than the community one is read only when + (`https://github.com///releases/download/…`). When the package names a `repo`, the + asset must be in that repository. A `repo` that isn't `https://github.com//` (with + an optional trailing `/` or `.git`) or a folder in one (`https://github.com///tree//…`) + makes Install and Preview refuse every release of the package. A catalog other than the community one is read only when `library.refresh {catalog}` names it: an `index.json` on GitHub's hosts over `https://`, or a local `file://` path. * **Where it goes.** `/Library///.wasm` (the `Plug-ins` folder next to diff --git a/docs/publishing-plugins.md b/docs/publishing-plugins.md index c94f9e2a8..c28554f14 100644 --- a/docs/publishing-plugins.md +++ b/docs/publishing-plugins.md @@ -181,7 +181,7 @@ Package fields: | `author` | no | You, or your group. | | `description` | no, but reviewed | One or two plain sentences that say what the effect does. | | `license` | no, but reviewed | The licence's SPDX id (`MIT`, `Apache-2.0`, `MIT OR Apache-2.0`…). | -| `repo` | no, but reviewed | The public source repository. The details' "Open on GitHub" opens it. | +| `repo` | no, but reviewed | The public source repository, as `https://github.com//` (a trailing `/` or `.git` is allowed), or a folder in it, `https://github.com///tree//`. The details' "Open on GitHub" opens it. When `repo` is given in any other form, Install and Preview refuse every release of the package. | | `tags` | no | Lower-case words for the tag filter (`blur`, `stylize`, `light`, `distort`…). Reuse tags the catalog already has. | | `preview.video` | no | An `https://` link to a short demo video on YouTube, Vimeo or GitHub. "Watch video" opens it in the browser. A link that isn't `https://` (or is longer than 500 characters) is left out. The live preview doesn't need it. | | `versions` | yes | One entry per release, newest or oldest first. | @@ -193,7 +193,7 @@ Release fields (one per entry in `versions`): | `version` | yes | Dotted numbers only, at most 32 characters: `1.0.0`, `1.2`. No `v` and no suffixes such as `-beta`. | | `api` | yes | The plug-in API the module implements: `1`. | | `minApp` | no | The oldest EffectCraft version the release needs (`0.17.0`). Leave it out if any version with this API works. | -| `url` | yes | The release asset's `https://` URL on GitHub: `https://github.com///releases/download//`. When `repo` is a `https://github.com//` URL, the asset must be in that repository. Install and Preview refuse any other `https://` URL. | +| `url` | yes | The release asset's `https://` URL on GitHub: `https://github.com///releases/download//`. When the package has a `repo`, the asset must be in that repository. Install and Preview refuse any other `https://` URL. | | `sha256` | yes | The file's SHA-256, 64 hex digits. | | `size` | no, but reviewed | The file's size in bytes. When it is given, a download of another size is refused. | | `effects` | yes | The effect ids the module registers (its manifest's `id`). EffectCraft uses them to find the package that provides an effect a project needs. | diff --git a/examples/plugin-catalog/schema.json b/examples/plugin-catalog/schema.json index a2d30676b..5fe914d86 100644 --- a/examples/plugin-catalog/schema.json +++ b/examples/plugin-catalog/schema.json @@ -12,9 +12,9 @@ }, "$defs": { "version": {"type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)*$"}, - "github_url": { + "release_url": { "type": "string", - "pattern": "^https://(github\\.com|raw\\.githubusercontent\\.com|objects\\.githubusercontent\\.com|release-assets\\.githubusercontent\\.com)/[^\\s]+$" + "pattern": "^(?!.*/(\\.|%2[eE]){1,2}(/|$))https://[Gg][Ii][Tt][Hh][Uu][Bb]\\.[Cc][Oo][Mm]/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+/releases/download/[^/?#\\\\\\s]+(/[^/?#\\\\\\s]+)+$" }, "package": { "type": "object", @@ -26,7 +26,7 @@ "author": {"type": "string"}, "description": {"type": "string"}, "license": {"type": "string"}, - "repo": {"type": "string", "pattern": "^https://"}, + "repo": {"type": "string", "pattern": "^(?!.*/(\\.|%2[eE]){1,2}(/|$))[Hh][Tt][Tt][Pp][Ss]://[Gg][Ii][Tt][Hh][Uu][Bb]\\.[Cc][Oo][Mm]/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+(/tree(/[^/?#\\\\\\s]+)+)?/?$"}, "tags": {"type": "array", "items": {"type": "string"}}, "preview": { "type": "object", @@ -44,7 +44,7 @@ "version": {"$ref": "#/$defs/version"}, "api": {"type": "integer", "minimum": 0, "maximum": 4294967295}, "minApp": {"$ref": "#/$defs/version"}, - "url": {"$ref": "#/$defs/github_url"}, + "url": {"$ref": "#/$defs/release_url"}, "sha256": {"type": "string", "pattern": "^[0-9a-fA-F]{64}$"}, "size": {"type": "integer", "minimum": 1, "maximum": 67108864}, "effects": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "^(?!ec\\.)[A-Za-z0-9._-]+$"}} diff --git a/examples/plugin-catalog/scripts/validate.sh b/examples/plugin-catalog/scripts/validate.sh index 40e37de7f..60686330a 100644 --- a/examples/plugin-catalog/scripts/validate.sh +++ b/examples/plugin-catalog/scripts/validate.sh @@ -42,7 +42,25 @@ dups=$(jq -r '.packages[].id' "$catalog" | sort | uniq -d) [ -z "$dups" ] || fail "duplicate package ids: $dups" echo "ok" -echo "== 3. downloads" +echo "== 3. release URLs" +# When a package has a `repo`, every release must be an asset of that repository, as Install and +# Preview require (the loader step installs from file:// copies, which skip this check). +bad=$(jq -r ' + # Only the scheme, host, owner and name compare without case; the `.git` suffix is lower case. + def repo_of: + (capture("^(?[^/]+//[^/]+)/(?[A-Za-z0-9._-]+)/(?[A-Za-z0-9._-]+?)(\\.git)?/?$") + // capture("^(?[^/]+//[^/]+)/(?[A-Za-z0-9._-]+)/(?[A-Za-z0-9._-]+)/tree/[^?#]+$") + | select(.h | ascii_downcase == "https://github.com") | "\(.o)/\(.n)" | ascii_downcase) // "?"; + .packages[] | . as $pkg | ((.repo // "") | gsub("^\\s+|\\s+$"; "")) as $repo + | select($repo != "") | ($repo | repo_of) as $want + | .versions[] | select(.url | startswith("file://") | not) + | ((.url | ascii_downcase | capture("^https://github\\.com/(?[^/]+)/(?[^/]+)/releases/download/") | "\(.o)/\(.n)") // "?") as $got + | select($want == "?" or $got != $want) + | "\($pkg.id) \(.version): \(.url) is not a release asset of \($repo)"' "$catalog") +[ -z "$bad" ] || fail "release URLs outside the package's repo:"$'\n'"$bad" +echo "ok" + +echo "== 4. downloads" # The checked files are what the loader step installs: a copy of the catalog names them by file://. local_catalog=$(jq '.' "$catalog") while IFS=$'\t' read -r p r id version url sha size; do @@ -58,7 +76,7 @@ done < <(jq -r '.packages | to_entries[] | .key as $p | .value as $pkg | $pkg.ve | [$p, .key, $pkg.id, .value.version, .value.url, .value.sha256, (.value.size // "")] | @tsv' "$catalog") echo "ok" -echo "== 4. load with EffectCraft" +echo "== 5. load with EffectCraft" if [ -z "${EFFECTCRAFT_CLI:-}" ]; then echo "skipped (set EFFECTCRAFT_CLI to an effectcraft-cli build)" exit 0 From 400187f9d91b4b2e9b6995f5afb19b4bba053390 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Thu, 5 Nov 2026 23:59:53 -0800 Subject: [PATCH 3/5] Plug-in Library: the catalog validator refuses dot and empty folder segments in repo `scripts/validate.sh` now reads a `repo` folder URL (`https://github.com///tree//`) as EffectCraft does: an empty, `.` or `..` segment (also percent-encoded), or a `?`, `#` or `\`, makes the `repo` unreadable, and every release of the package is reported. A `.` or `..` owner or name is refused too. The check now matches the app when the schema step is skipped. --- examples/plugin-catalog/scripts/validate.sh | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/examples/plugin-catalog/scripts/validate.sh b/examples/plugin-catalog/scripts/validate.sh index 60686330a..6e57e05ce 100644 --- a/examples/plugin-catalog/scripts/validate.sh +++ b/examples/plugin-catalog/scripts/validate.sh @@ -46,11 +46,15 @@ echo "== 3. release URLs" # When a package has a `repo`, every release must be an asset of that repository, as Install and # Preview require (the loader step installs from file:// copies, which skip this check). bad=$(jq -r ' + # A path segment EffectCraft refuses: empty, `.` or `..` (also percent-encoded). + def bad_segment: . == "" or (ascii_downcase | gsub("%2e"; ".") | . == "." or . == ".."); # Only the scheme, host, owner and name compare without case; the `.git` suffix is lower case. def repo_of: (capture("^(?[^/]+//[^/]+)/(?[A-Za-z0-9._-]+)/(?[A-Za-z0-9._-]+?)(\\.git)?/?$") - // capture("^(?[^/]+//[^/]+)/(?[A-Za-z0-9._-]+)/(?[A-Za-z0-9._-]+)/tree/[^?#]+$") - | select(.h | ascii_downcase == "https://github.com") | "\(.o)/\(.n)" | ascii_downcase) // "?"; + // (capture("^(?[^/]+//[^/]+)/(?[A-Za-z0-9._-]+)/(?[A-Za-z0-9._-]+)/tree/(?[^?#\\\\]+?)/?$") + | select(.f | split("/") | any(bad_segment) | not)) + | select((.h | ascii_downcase) == "https://github.com" and (.o | bad_segment | not) and (.n | bad_segment | not)) + | "\(.o)/\(.n)" | ascii_downcase) // "?"; .packages[] | . as $pkg | ((.repo // "") | gsub("^\\s+|\\s+$"; "")) as $repo | select($repo != "") | ($repo | repo_of) as $want | .versions[] | select(.url | startswith("file://") | not) From cc90ad0c3b2f36c5ade8b4d9620f6e5afba0bf32 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Fri, 6 Nov 2026 00:32:31 -0800 Subject: [PATCH 4/5] Plug-in Library: the catalog validator checks every remote release URL in full scripts/validate.sh now refuses any release URL other than a local file:// path that isn't a release asset (https://github.com///releases/download// with no query, fragment, backslash, or empty, . or .. segment), for packages without a repo too, as Install and Preview do. docs/plugins.md says the release URL rules don't apply to file:// releases from a local catalog. --- docs/plugins.md | 4 ++- examples/plugin-catalog/scripts/validate.sh | 28 +++++++++++++++------ 2 files changed, 24 insertions(+), 8 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index 5302b0b3c..cc4f164aa 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -378,7 +378,9 @@ package can't read files, open the network or crash the app. (`https://github.com///releases/download/…`). When the package names a `repo`, the asset must be in that repository. A `repo` that isn't `https://github.com//` (with an optional trailing `/` or `.git`) or a folder in one (`https://github.com///tree//…`) - makes Install and Preview refuse every release of the package. A catalog other than the community one is read only when + makes Install and Preview refuse every `https://` release of the package. These rules don't apply + to a release whose `url` is a local `file://` path, which only a local catalog may name (to test + an entry before its release is published). A catalog other than the community one is read only when `library.refresh {catalog}` names it: an `index.json` on GitHub's hosts over `https://`, or a local `file://` path. * **Where it goes.** `/Library///.wasm` (the `Plug-ins` folder next to diff --git a/examples/plugin-catalog/scripts/validate.sh b/examples/plugin-catalog/scripts/validate.sh index 6e57e05ce..4a0d196fc 100644 --- a/examples/plugin-catalog/scripts/validate.sh +++ b/examples/plugin-catalog/scripts/validate.sh @@ -43,11 +43,24 @@ dups=$(jq -r '.packages[].id' "$catalog" | sort | uniq -d) echo "ok" echo "== 3. release URLs" -# When a package has a `repo`, every release must be an asset of that repository, as Install and -# Preview require (the loader step installs from file:// copies, which skip this check). +# Every release that isn't a local file:// path must be a release asset, and when its package has +# a `repo`, an asset of that repository, as Install and Preview require (the loader step installs +# from file:// copies, which skip this check). bad=$(jq -r ' # A path segment EffectCraft refuses: empty, `.` or `..` (also percent-encoded). def bad_segment: . == "" or (ascii_downcase | gsub("%2e"; ".") | . == "." or . == ".."); + # "owner/name" in lower case of a release asset, + # https://github.com///releases/download// (a tag may contain `/`), with + # no query, fragment, backslash, or empty, `.` or `..` segment; "?" for anything else. + def asset_of: + if startswith("https://") and (.[8:19] | ascii_downcase) == "github.com/" then + .[19:] as $rest + | ($rest | split("/")) as $p + | if ($rest | test("[?#\\\\]")) or ($p | length) < 6 or ($p | any(bad_segment)) + or ($p[0] | test("^[A-Za-z0-9._-]+$") | not) or ($p[1] | test("^[A-Za-z0-9._-]+$") | not) + or $p[2] != "releases" or $p[3] != "download" + then "?" else "\($p[0])/\($p[1])" | ascii_downcase end + else "?" end; # Only the scheme, host, owner and name compare without case; the `.git` suffix is lower case. def repo_of: (capture("^(?[^/]+//[^/]+)/(?[A-Za-z0-9._-]+)/(?[A-Za-z0-9._-]+?)(\\.git)?/?$") @@ -56,12 +69,13 @@ bad=$(jq -r ' | select((.h | ascii_downcase) == "https://github.com" and (.o | bad_segment | not) and (.n | bad_segment | not)) | "\(.o)/\(.n)" | ascii_downcase) // "?"; .packages[] | . as $pkg | ((.repo // "") | gsub("^\\s+|\\s+$"; "")) as $repo - | select($repo != "") | ($repo | repo_of) as $want + | (if $repo == "" then "" else $repo | repo_of end) as $want | .versions[] | select(.url | startswith("file://") | not) - | ((.url | ascii_downcase | capture("^https://github\\.com/(?[^/]+)/(?[^/]+)/releases/download/") | "\(.o)/\(.n)") // "?") as $got - | select($want == "?" or $got != $want) - | "\($pkg.id) \(.version): \(.url) is not a release asset of \($repo)"' "$catalog") -[ -z "$bad" ] || fail "release URLs outside the package's repo:"$'\n'"$bad" + | (.url | asset_of) as $got + | if $got == "?" then "\($pkg.id) \(.version): \(.url) is not a release asset (https://github.com///releases/download//)" + elif $want != "" and ($want == "?" or $got != $want) then "\($pkg.id) \(.version): \(.url) is not a release asset of \($repo)" + else empty end' "$catalog") +[ -z "$bad" ] || fail "release URLs that Install and Preview refuse:"$'\n'"$bad" echo "ok" echo "== 4. downloads" From 36dc209badfdbab2fa99f44e130798e3c35277ef Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Fri, 6 Nov 2026 00:49:16 -0800 Subject: [PATCH 5/5] Plug-in Library: release and repo URLs with white space are refused Install and Preview, the catalog schema and scripts/validate.sh now refuse a release URL or repo folder that contains white space in any segment, the tag and file name included: any Unicode white space character, and U+FEFF. Before, the app accepted a space or tab in a tag, file name or repo folder that the schema refused. --- crates/engine/src/system/library.rs | 19 +++++++++++++++++-- examples/plugin-catalog/schema.json | 4 ++-- examples/plugin-catalog/scripts/validate.sh | 9 ++++++--- 3 files changed, 25 insertions(+), 7 deletions(-) diff --git a/crates/engine/src/system/library.rs b/crates/engine/src/system/library.rs index d1eaaf0bd..8fb147e53 100644 --- a/crates/engine/src/system/library.rs +++ b/crates/engine/src/system/library.rs @@ -272,12 +272,18 @@ fn dot_segment(p: &str) -> bool { p == "." || p == ".." } +/// A character a release or repository URL may not contain: `?`, `#`, `\`, Unicode white space, +/// or U+FEFF (the catalog schema's `\s` matches it too). +fn bad_url_char(c: char) -> bool { + matches!(c, '?' | '#' | '\\' | '\u{feff}') || c.is_whitespace() +} + /// `(owner, name)` in lower case of a `https://github.com//` repository URL (an /// optional trailing `/` or `.git`) or of a folder in one, `https://github.com///tree//`; /// `None` for anything else. fn github_repo(repo: &str) -> Option<(String, String)> { let rest = strip_prefix_ignore_case(repo.trim(), "https://github.com/")?; - if rest.contains(['?', '#', '\\']) { + if rest.contains(bad_url_char) { return None; } let rest = rest.strip_suffix('/').unwrap_or(rest); @@ -296,7 +302,7 @@ fn github_repo(repo: &str) -> Option<(String, String)> { fn release_url_problem(repo: &str, url: &str) -> Option { let not_asset = || Some(format!("`{url}` isn't a release asset (https://github.com///releases/download//)")); let Some(rest) = strip_prefix_ignore_case(url, "https://github.com/") else { return not_asset() }; - if rest.contains(['?', '#', '\\']) { + if rest.contains(bad_url_char) { return not_asset(); } let parts: Vec<&str> = rest.split('/').collect(); @@ -1230,6 +1236,12 @@ mod tests { "https://github.com/me/glow/releases/download/./v1/x.wasm", "https://github.com/me/glow/releases/download/v1\\x.wasm", "https://github.com/m e/glow/releases/download/v1/x.wasm", + "https://github.com/me/glow/releases/download/v 1/x.wasm", + "https://github.com/me/glow/releases/download/v1/x\t.wasm", + "https://github.com/me/glow/releases/download/v1/x.wasm\n", + "https://github.com/me/glow/releases/download/v1\u{a0}/x.wasm", + "https://github.com/me/glow/releases/download/v1/\u{85}x.wasm", + "https://github.com/me/glow/releases/download/v1/x\u{feff}.wasm", "https://github.com/../glow/releases/download/v1/x.wasm", "https://github.com.evil.com/me/glow/releases/download/v1/x.wasm", ] { @@ -1281,6 +1293,9 @@ mod tests { "https://github.com/me/glow?tab=readme", "https://github.com/me/glow#readme", "https://github.com/me/gl ow", + "https://github.com/me/glow/tree/main/my plug-in", + "https://github.com/me/glow/tree/ma\tin", + "https://github.com/me/glow/tree/main/x\u{feff}", "https://github.com/me/..", ] { let why = release_url_problem(repo, asset); diff --git a/examples/plugin-catalog/schema.json b/examples/plugin-catalog/schema.json index 5fe914d86..c31d57fea 100644 --- a/examples/plugin-catalog/schema.json +++ b/examples/plugin-catalog/schema.json @@ -14,7 +14,7 @@ "version": {"type": "string", "maxLength": 32, "pattern": "^[0-9]+(\\.[0-9]+)*$"}, "release_url": { "type": "string", - "pattern": "^(?!.*/(\\.|%2[eE]){1,2}(/|$))https://[Gg][Ii][Tt][Hh][Uu][Bb]\\.[Cc][Oo][Mm]/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+/releases/download/[^/?#\\\\\\s]+(/[^/?#\\\\\\s]+)+$" + "pattern": "^(?!.*/(\\.|%2[eE]){1,2}(/|$))https://[Gg][Ii][Tt][Hh][Uu][Bb]\\.[Cc][Oo][Mm]/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+/releases/download/[^/?#\\\\\\s\\u0085]+(/[^/?#\\\\\\s\\u0085]+)+$" }, "package": { "type": "object", @@ -26,7 +26,7 @@ "author": {"type": "string"}, "description": {"type": "string"}, "license": {"type": "string"}, - "repo": {"type": "string", "pattern": "^(?!.*/(\\.|%2[eE]){1,2}(/|$))[Hh][Tt][Tt][Pp][Ss]://[Gg][Ii][Tt][Hh][Uu][Bb]\\.[Cc][Oo][Mm]/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+(/tree(/[^/?#\\\\\\s]+)+)?/?$"}, + "repo": {"type": "string", "pattern": "^(?!.*/(\\.|%2[eE]){1,2}(/|$))[Hh][Tt][Tt][Pp][Ss]://[Gg][Ii][Tt][Hh][Uu][Bb]\\.[Cc][Oo][Mm]/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+(/tree(/[^/?#\\\\\\s\\u0085]+)+)?/?$"}, "tags": {"type": "array", "items": {"type": "string"}}, "preview": { "type": "object", diff --git a/examples/plugin-catalog/scripts/validate.sh b/examples/plugin-catalog/scripts/validate.sh index 4a0d196fc..711b69394 100644 --- a/examples/plugin-catalog/scripts/validate.sh +++ b/examples/plugin-catalog/scripts/validate.sh @@ -49,25 +49,28 @@ echo "== 3. release URLs" bad=$(jq -r ' # A path segment EffectCraft refuses: empty, `.` or `..` (also percent-encoded). def bad_segment: . == "" or (ascii_downcase | gsub("%2e"; ".") | . == "." or . == ".."); + # A `?`, `#`, `\` or white space character (Unicode, and U+FEFF), which EffectCraft refuses in a URL. + def bad_char: test("[?#\\\\\t\n\u000b\f\r \u0085   - 

   ]"); # "owner/name" in lower case of a release asset, # https://github.com///releases/download// (a tag may contain `/`), with - # no query, fragment, backslash, or empty, `.` or `..` segment; "?" for anything else. + # no query, fragment, backslash, white space, or empty, `.` or `..` segment; "?" for anything else. def asset_of: if startswith("https://") and (.[8:19] | ascii_downcase) == "github.com/" then .[19:] as $rest | ($rest | split("/")) as $p - | if ($rest | test("[?#\\\\]")) or ($p | length) < 6 or ($p | any(bad_segment)) + | if ($rest | bad_char) or ($p | length) < 6 or ($p | any(bad_segment)) or ($p[0] | test("^[A-Za-z0-9._-]+$") | not) or ($p[1] | test("^[A-Za-z0-9._-]+$") | not) or $p[2] != "releases" or $p[3] != "download" then "?" else "\($p[0])/\($p[1])" | ascii_downcase end else "?" end; # Only the scheme, host, owner and name compare without case; the `.git` suffix is lower case. def repo_of: + if bad_char then "?" else (capture("^(?[^/]+//[^/]+)/(?[A-Za-z0-9._-]+)/(?[A-Za-z0-9._-]+?)(\\.git)?/?$") // (capture("^(?[^/]+//[^/]+)/(?[A-Za-z0-9._-]+)/(?[A-Za-z0-9._-]+)/tree/(?[^?#\\\\]+?)/?$") | select(.f | split("/") | any(bad_segment) | not)) | select((.h | ascii_downcase) == "https://github.com" and (.o | bad_segment | not) and (.n | bad_segment | not)) - | "\(.o)/\(.n)" | ascii_downcase) // "?"; + | "\(.o)/\(.n)" | ascii_downcase) // "?" end; .packages[] | . as $pkg | ((.repo // "") | gsub("^\\s+|\\s+$"; "")) as $repo | (if $repo == "" then "" else $repo | repo_of end) as $want | .versions[] | select(.url | startswith("file://") | not)