A local-first multi-agent app development platform, built on PenguinHarness
feat(server,web): 插件导入支持 npm 包(tgz 解码 + registry 解析 + 校验和)
lmliheng7302ff5e09b6
diff --git a/FORK-PROGRESS.md b/FORK-PROGRESS.mdindex e562f29a..142f3f77 100644--- a/FORK-PROGRESS.md+++ b/FORK-PROGRESS.md@@ -733,3 +733,56 @@ systemctl enable --now penguin-server遗留:`qq-webui-proxy.service` 与 napcat 容器仍按旧路径工作(靠符号链接)。要彻底改成`/root/.adelie/data`,得同时改那个单元并重建容器(会重连 QQ,这次没做)。++## 插件从 npm 导入(2026-10-05,用户点单)++### 问了什么++「插件那里能不能支持 npm,把我的 penguin harness 插件仓库转移到 npm,然后 npm 导入插件,可以吗。」++### 先答事实(都核过)++- 插件本来就是 npm 包:每个 `plugins/<name>/` 带 `package.json`(`@penguinharness/<name>`,+ `files: [plugin.json, icon.svg, skills, hooks, LICENSE]`),仓库的发布流水线每发一版就把它们推上 npm+ (`.github/workflows/release.yml` 里 `for dir in plugins/*/` + `pnpm publish --access public`)。+ registry 上 `@penguinharness/{use-firecrawl,goal,data-analysis,agent-company}` 等已有 0.2.9–0.2.13。+- **导入侧先前只认 zip**:`POST /api/plugins/download` 走 `normalizePluginUrl` + fflate 的 `unzipSync`,+ 填一个 npm 名字只会被当成普通链接去抓。所以「能不能」= 能,但要写代码。++### 这一轮做的++- 新 `packages/server/src/services/tar-archive.ts`:同步、只在内存里的 tar 读取器 —— ustar `prefix`、+ pax `x` 扩展头、GNU `L` 长名、base-256 size、成员校验和;目录/链接/设备成员跳过且不跟随路径。+ `gunzipBounded` 用 `zlib.gunzipSync` 的 `maxOutputLength` 兜住解压炸弹(64MB),`untarBounded` 复用+ `skill-import-limits` 那套 caps(200 文件 / 单文件 5MB / 合计 20MB),成员路径逐个查绝对路径、反斜杠与 `..`。+- `packages/server/src/services/plugin-download.ts`:`parseNpmPluginSpec`(`npm:@scope/name[@版本]`、+ npmjs.com 包页、registry packument 地址、裸包名)+ `resolvePluginSource`(npm → 抓 packument,+ 取版本与 `dist.tarball`,把 `dist.integrity` 一并带上)+ `fetchPluginArchive` 校验 SRI。+ 非 npm 输入照旧走 `normalizePluginUrl`;`.tgz` 直链也会由来名推名字。+- `packages/server/src/http/routes/plugins.ts`:`parsePluginArchive` 按 magic bytes 分流 zip / gzip-tar,+ 根定位、命名、caps、路径校验全部共用一份;npm 包按去掉 scope 的包名安装+ (`@scope/use-firecrawl` → `use-firecrawl`),tarball 那层 `package/` 不当名字(没给 name 就 400)。+ 新错误码 `npm_package_not_found` / `npm_version_not_found` / `npm_registry_failed` / `integrity_failed`。+- 网页端:下载框的 label/hint/placeholder/描述、导入规则第 1–4 条、`importErrors` 两个语言都补 npm 形态;+ `pluginNameFromUrl` 认 npm 说明符与 npmjs.com 包页(覆盖确认里那行名字)。++### 验证++- `pnpm --filter @prismshadow/penguin-server test`:180 文件 / 2592 通过 / 2 跳过;+ `packages/web`:236 文件 / 2891 通过 / 2 跳过;`pnpm typecheck` 全包 Done;`pnpm lint` 0;+ `pnpm format:check` 干净。+- 新测 `packages/server/test/plugin-npm-import.test.ts`(18 例):手写 ustar/pax tarball 的解析、+ 路径穿越与截断、解压炸弹、caps、说明符解析、路由端到端(stub 注册表 + tarball)。+ `packages/web/test/plugin-import.test.ts` 加了两例 npm 命名。+- 真网络:registry 上真的 `@penguinharness/[email protected]` tarball 过了 `parsePluginArchive`+ (4 个文件 + `package.json`,都在 `package/` 下);`resolvePluginSource("npm:@penguinharness/goal")`+ 与 npmjs.com 包页都解析到 `…/goal-0.2.13.tgz` 并带回 `sha512-…`;不存在的包回 `404 npm_package_not_found`。++### 没做(卡在这两点,等拍板)++- **没有发 npm**:台账纪律里「不发 npm」还在;且 `@penguinharness` 的 maintainer 是 `hiyouga`+ (registry maintainers 字段),`lmliheng` 的 token 发不上去。要发得先定 scope —— `@lmliheng` 名下 0 个包,+ 可发;改名有两种做法:改仓库里 19 个 `package.json` 的 `name`(会牵到 `packages/cli`、`packages/server`+ 的 `workspace:*` 依赖与 core 的 `PLUGIN_PKG_PREFIX`,`packages/core/src/plugins/index.ts`),+ 或者只在发布时把包名换成自有 scope 临时发。+- 运行时生效要重装/重建服务端(现在跑的是 `/root/.adelie` 那份 0.2.3)。diff --git a/packages/server/src/api/types.ts b/packages/server/src/api/types.tsindex cf6fec79..99ee00f6 100644--- a/packages/server/src/api/types.ts+++ b/packages/server/src/api/types.ts@@ -3887,15 +3887,23 @@ export interface PluginUploadRequest {}/**- * POST /api/plugins/download: the same import, fetched server-side from a URL. Accepts a zip- * archive, a GitHub repository URL (`https://github.com/<owner>/<repo>`, the default branch) or- * a GitHub tree URL (`…/tree/<ref>/<subdir>` — `subdir` picks the plugin root inside the- * archive), and answers the same errors as the upload route above, plus 400 `unsupported_url`- * (not an http(s) URL, or a GitHub page that is not a repository or tree), 400 `blocked_url`- * (a loopback, private or link-local host) and 400 `download_failed` (the request or its- * status). Admin-only.+ * POST /api/plugins/download: the same import, fetched server-side from a URL or from npm. Accepts+ * a zip archive or a `.tgz`, a GitHub repository URL (`https://github.com/<owner>/<repo>`, the+ * default branch), a GitHub tree URL (`…/tree/<ref>/<subdir>` — `subdir` picks the plugin root+ * inside the archive), or an npm package (`@scope/name[@version]`, `npm:@scope/name`, the package+ * page on npmjs.com; without a version, whatever `latest` is when the request runs). Answers the+ * same errors as the upload route above, plus 400 `unsupported_url` (not an http(s) URL, or a+ * GitHub page that is not a repository or tree), 400 `blocked_url` (a loopback, private or+ * link-local host), 400 `download_failed` (the request or its status), 404 `npm_package_not_found`+ * / 404 `npm_version_not_found`, 400 `npm_registry_failed` (the registry could not be read) and 400+ * `integrity_failed` (the bytes are not what the registry published). Admin-only.*/export interface PluginDownloadRequest {+ /**+ * The plugin's address, or its npm package name. Named `url` because that is what it usually is;+ * everything npm takes (`npm:` specifiers, a bare `@scope/name`, npmjs.com and registry URLs) is+ * read as a package name by the server.+ */url: string;/** Overrides the derived plugin name. */name?: string;diff --git a/packages/server/src/http/routes/plugins.ts b/packages/server/src/http/routes/plugins.tsindex b55d4daa..e4612000 100644--- a/packages/server/src/http/routes/plugins.ts+++ b/packages/server/src/http/routes/plugins.ts@@ -4,7 +4,7 @@* GET /api/plugins # the built-in library by category (any logged-in user)* GET /api/plugins/directory # the user plugin directory (any logged-in user)* POST /api/plugins/upload # install a plugin from an uploaded zip (admin)- * POST /api/plugins/download # install a plugin fetched from a URL (admin)+ * POST /api/plugins/download # install a plugin fetched from a URL or npm (admin)* GET /api/plugins/:plugin/files # the files a library plugin ships, for the detail view's browser* GET /api/plugins/:plugin/archive # export a plugin as a zip (any logged-in user)* DELETE /api/plugins/:plugin # uninstall a user plugin (admin)@@ -95,9 +95,10 @@ import {} from "../../services/plugin-library.js";import {fetchPluginArchive,- normalizePluginUrl,pluginArchiveTooLarge,+ resolvePluginSource,} from "../../services/plugin-download.js";+import { gunzipBounded, isGzip, tarEntryNames, untarBounded } from "../../services/tar-archive.js";import { assertSafeEntryPath, MAX_ARCHIVE_BYTES } from "./skills.js";import { unzipBounded } from "../../services/skill-import-limits.js";@@ -190,51 +191,77 @@ function pluginRootIn(paths: readonly string[], subdir: string): string {/*** Decodes an uploaded or downloaded archive into the files of one plugin. Everything a client- * supplies is checked here, before a byte is written: the zip's declared sizes through- * `unzipBounded` (which is where the caps have to be enforced — see that module), every entry- * path against zip-slip, the plugin root's ambiguity, and the name against the plugin-name- * rule. Directories the archive declares are skipped: the paths of the files recreate them.+ * supplies is checked here, before a byte is written: the declared sizes through `unzipBounded` /+ * `untarBounded` (which is where the caps have to be enforced — see those modules), every entry+ * path against traversal, the plugin root's ambiguity, and the name against the plugin-name rule.+ * Directories the archive declares are skipped: the paths of the files recreate them.+ *+ * Two formats reach this function, and it does not care which: a zip (an operator's upload, a+ * GitHub archive, an exported plugin) and the gzipped tar npm publishes (see+ * services/plugin-download.ts). The signature bytes decide, and everything after that — the root,+ * the caps, the naming — is the same question about the same kind of content.*/export function parsePluginArchive(archive: Buffer,options: { name?: string; subdir?: string } = {},): ParsedPluginArchive {// Two passes, because an archive is not necessarily a plugin: a GitHub tree download is a- // whole repository with one plugin somewhere inside it. The first pass reads the central- // directory alone — every entry name, nothing inflated — to find the plugin root; the second- // inflates that root's files only. So the caps bound the PLUGIN (200 files, 5MB each, 20MB+ // whole repository with one plugin somewhere inside it. The first pass reads the entry names+ // alone — a zip's central directory, a tar's headers — to find the plugin root; the second+ // unpacks that root's files only. So the caps bound the PLUGIN (200 files, 5MB each, 20MB// total, the same numbers an upload of a single plugin gets) instead of failing on the// repository that happens to be wrapped around it, and a hundred-megabyte checkout is never// expanded to serve a thirty-file plugin.const bytes = new Uint8Array(archive);+ const tarball = isGzip(bytes);+ // A tarball is gunzipped first, and that happens before any of the above: its headers are only+ // reachable through the compression, so its own module bounds what one may inflate to.+ const opened = tarball ? gunzipBounded(bytes) : bytes;let names: string[];try {- names = entryNames(bytes);- } catch {- throw badRequest("The archive is not a valid zip file.");+ names = tarball ? tarEntryNames(opened) : entryNames(bytes);+ } catch (err) {+ if (err instanceof HttpError) throw err;+ throw badRequest(+ tarball ? "The archive is not a valid npm tarball." : "The archive is not a valid zip file.",+ );}if (names.length === 0) throw badRequest("The archive contains no files.");const root = pluginRootIn(names, options.subdir ?? "");const prefix = root === "" ? "" : `${root}/`;let entries: Record<string, Uint8Array>;try {- entries = unzipBounded(bytes, (name) => prefix === "" || name.startsWith(prefix));+ entries = tarball+ ? untarBounded(opened, (name) => prefix === "" || name.startsWith(prefix))+ : unzipBounded(bytes, (name) => prefix === "" || name.startsWith(prefix));} catch (err) {- // The caps arrive as 400s of their own; anything else means the bytes are not a zip.+ // The caps arrive as 400s of their own; anything else means the bytes are not that format.if (err instanceof HttpError) throw err;- throw badRequest("The archive is not a valid zip file.");+ throw badRequest(+ tarball ? "The archive is not a valid npm tarball." : "The archive is not a valid zip file.",+ );}const rootFiles: Record<string, Uint8Array> = {};for (const [entry, data] of Object.entries(entries)) {if (entry.endsWith("/")) continue;- assertSafeEntryPath(entry);+ // The tar reader checked its own member paths as it walked them — the walk is what chooses the+ // root, so it cannot be deferred; a zip's central directory carries them unchecked, and this+ // is where they are checked.+ if (!tarball) assertSafeEntryPath(entry);rootFiles[entry.slice(prefix.length)] = data;}- // The archive's own layout names the plugin unless the request says otherwise; an archive- // with plugin.json at its root has no directory to take a name from.- const name = options.name ?? (root === "" ? undefined : path.basename(root));+ // The archive's own layout names the plugin unless the request says otherwise. Two layouts+ // cannot: plugin.json at the archive's root, and a tarball — which npm wraps in a `package/`+ // directory that names the publisher's package format rather than anybody's plugin.+ const named =+ tarball && root === "package" ? undefined : root === "" ? undefined : path.basename(root);+ const name = options.name ?? named;if (name === undefined) {- throw badRequest("name is required when the archive carries plugin.json at its root.");+ throw badRequest(+ tarball+ ? "name is required for a tarball: npm wraps every package in a `package/` directory, which names the format rather than the plugin."+ : "name is required when the archive carries plugin.json at its root.",+ );}if (!PLUGIN_NAME_PATTERN.test(name)) {throw new HttpError(400, "invalid_plugin", `Not a valid plugin name: ${name}`);@@ -328,16 +355,19 @@ export function pluginLibraryRoutes(deps: PluginsRouteDeps): Hono<AppEnv> {);});- // Install one plugin from a URL the operator names (admin). The whole download runs- // server-side: the server is what has the network position to reach it, and the archive is- // validated by the same parser the upload route uses, whichever way the bytes arrived.+ // Install one plugin from what the operator names (admin): an address, or an npm package+ // (`@scope/name[@version]`, or the `npm:` spelling — see resolvePluginSource). The whole+ // download runs server-side: the server is what has the network position to reach it, and the+ // archive is validated by the same parser the upload route uses, whichever way the bytes+ // arrived. An npm name costs two requests (the packument, then the tarball it points at); the+ // checksum the packument carries comes back with the source and is verified on the bytes.app.post("/download", async (c) => {requireAdmin(c);const body = await readJson(c);const url = requireString(body, "url", { minLen: 1, maxLen: 2048 });const requestedName = optionalString(body, "name", { maxLen: 128 });const requestedSubdir = optionalString(body, "subdir", { maxLen: 512 });- const source = normalizePluginUrl(url);+ const source = await resolvePluginSource(url);const archive = await fetchPluginArchive(source);if (archive.byteLength === 0) throw badRequest("The download is empty.");// What the request says wins over what the URL suggests: a name is what the operator askeddiff --git a/packages/server/src/services/plugin-download.ts b/packages/server/src/services/plugin-download.tsindex 15f8af12..295bb704 100644--- a/packages/server/src/services/plugin-download.ts+++ b/packages/server/src/services/plugin-download.ts@@ -1,12 +1,20 @@/**- * Remote plugin download: turns a URL an operator typed into the archive to install. Two- * separate concerns, in one place because the route needs both and neither is a route:- * `normalizePluginUrl` reads the URL (and rewrites the two GitHub shapes into the archive URL- * they stand for), `fetchPluginArchive` performs the one outbound request and bounds it.+ * Remote plugin download: turns what an operator typed — a URL, or the name of an npm package —+ * into the archive to install. Three concerns, in one place because the route needs all of them+ * and none is a route: `normalizePluginUrl` reads a URL (and rewrites the two GitHub shapes into+ * the archive URL they stand for), `parseNpmPluginSpec`/`resolvePluginSource` read an npm package+ * name (and rewrite it into its tarball, asking the registry which one `latest` is today), and+ * `fetchPluginArchive` performs the one outbound request and bounds it.*- * A plugin archive is a zip whose contents carry `plugin.json` somewhere; where exactly is the- * installer's question (http/routes/plugins.ts), not this module's — a plain zip URL is passed- * through untouched.+ * A plugin archive is a zip, or a published npm package's `.tgz`, whose contents carry+ * `plugin.json` somewhere; where exactly, and in which of the two formats, is the installer's+ * question (http/routes/plugins.ts + services/tar-archive.ts), not this module's — a plain+ * download link is passed through untouched.+ *+ * Why npm at all: every plugin in the library IS an npm package (`@penguinharness/<name>`, see+ * plugins/README.md), so an operator publishes theirs there and installs it here by name, without+ * a repository checkout or a zip to hand around. That is what the registry lookup below is for —+ * a name and an optional version in, the tarball npm serves for them out.** Safety: the URL is a server-side request an administrator controls, so it is not a* user-supplied fetch — but a redirect or a typo could still aim the server at its own network.@@ -16,6 +24,7 @@* caught here, which is the right trade for an admin-only endpoint on a self-hosted server and* would not be for one reachable by every user.*/+import { createHash, timingSafeEqual } from "node:crypto";import { isIP } from "node:net";import { HttpError } from "../http/errors.js";import { badRequest } from "../http/validate.js";@@ -35,14 +44,20 @@ export const MAX_PLUGIN_ARCHIVE_BYTES = 32 * 1024 * 1024;*/const DOWNLOAD_TIMEOUT_MS = 60_000;-/** A URL, read: what to fetch, which subdirectory inside the archive is the plugin, and the name the URL itself suggests. */+/** A source, read: what to fetch, which subdirectory inside the archive is the plugin, and the name that source suggests. */export interface PluginArchiveSource {- /** The URL to fetch (the GitHub archive URL when the input was a repository page). */+ /** The URL to fetch (the GitHub archive URL when the input was a repository page, the tarball when it was an npm package). */fetchUrl: string;/** Path inside the archive under which the plugin root must live ("" = anywhere, the shallowest plugin root wins). */subdir: string;- /** The name the URL suggests (a GitHub repository, a tree URL's directory); undefined when only the archive's own layout can say. */+ /** The name the source suggests (a GitHub repository, a tree URL's directory, an npm package's own name); undefined when only the archive's own layout can say. */name?: string;+ /**+ * The checksum the source published for this archive (Subresource Integrity, as npm's+ * `dist.integrity` is written: `<algorithm>-<base64>`), checked after the download. Present only+ * when a registry named the tarball — an operator's own URL makes no claim to verify.+ */+ integrity?: string;}/**@@ -70,9 +85,10 @@ export function normalizePluginUrl(raw: string): PluginArchiveSource {const host = url.hostname.toLowerCase().replace(/^www\./, "");if (host !== "github.com") {- // A plain link: fetched as given. The file name suggests a name only when it is a zip.+ // A plain link: fetched as given. The file name suggests a name only when it is an archive+ // (a zip, or the `.tgz` npm publishes) — any other link names nothing by itself.const file = url.pathname.split("/").filter(Boolean).pop() ?? "";- const suggested = file.toLowerCase().endsWith(".zip") ? file.slice(0, -4) : undefined;+ const suggested = archiveStem(file);return { fetchUrl: url.toString(), subdir: "", ...(suggested ? { name: suggested } : {}) };}@@ -105,6 +121,226 @@ export function normalizePluginUrl(raw: string): PluginArchiveSource {};}+/** The one npm registry this reads: npm's own. A mirror would be a second constant, not a setting to guess at. */+const NPM_REGISTRY = "https://registry.npmjs.org";++/** An npm package name: `name` or `@scope/name`, in the character set npm allows. */+const NPM_NAME = /^(?:@[A-Za-z0-9._~!*'()-]+\/)?[A-Za-z0-9._~!*'()-]+$/;+/** A version or a dist-tag (`latest`, `next`): what can be looked up in a packument directly. A range cannot. */+const NPM_VERSION = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;++/** Which npm package an import names, and which of its versions (absent = whatever `latest` is today). */+export interface NpmPluginSpec {+ name: string;+ version?: string;+}++/**+ * The npm package a piece of operator input names, or null when it names none. Accepted:+ * - `npm:<name>[@<version>]` — the explicit spelling, and the only one a bare name cannot be+ * confused with;+ * - `https://www.npmjs.com/package/<name>[/v/<version>]` — the page an npm search ends on;+ * - a bare `<name>[@<version>]`, the shortest thing an operator can type.+ *+ * A version is an exact version or a dist-tag, not a range: resolving a range would mean carrying+ * a semver resolver into the server for a feature whose answer the operator usually knows. Anything+ * that fails these patterns is null, which the callers turn into "that is not a plugin address".+ */+export function parseNpmPluginSpec(raw: string): NpmPluginSpec | null {+ const trimmed = raw.trim();+ if (trimmed === "") return null;+ if (trimmed.toLowerCase().startsWith("npm:")) {+ return parseNpmName(trimmed.slice("npm:".length).trim());+ }+ if (/^https?:\/\//i.test(trimmed)) {+ let url: URL;+ try {+ url = new URL(trimmed);+ } catch {+ return null;+ }+ const host = url.hostname.toLowerCase().replace(/^www\./, "");+ if (host === "npmjs.com") {+ const segments = url.pathname.split("/").filter(Boolean).map(decodeURIComponent);+ if (segments[0] !== "package") return null;+ // `…/package/@scope/name/v/1.2.3`: the name is one segment unless it is scoped.+ const scoped = segments[1] === undefined ? undefined : segments[1].startsWith("@");+ const name = scoped ? `${segments[1]}/${segments[2] ?? ""}` : segments[1];+ if (name === undefined || name.endsWith("/")) return null;+ const marker = scoped ? 3 : 2;+ const version = segments[marker] === "v" ? segments[marker + 1] : undefined;+ return parseNpmName(version === undefined ? name : `${name}@${version}`);+ }+ if (host === "registry.npmjs.org") {+ // The packument URL itself: `/@scope%2Fname`, or `/name` — what `npm view` would call. The+ // scope's slash is percent-encoded INSIDE the name, so the path is decoded before it is+ // split: decoding each segment separately would leave a name with a slash in one segment.+ const rest = decodeURIComponent(url.pathname.replace(/^\//, ""));+ const segments = rest.split("/");+ if (segments[0] === undefined || segments[0] === "") return null;+ const scoped = segments[0].startsWith("@");+ const name = scoped ? `${segments[0]}/${segments[1] ?? ""}` : segments[0];+ // A version in the path would answer with a single version's manifest rather than the+ // package's versions, which is not what this reader asks the registry for.+ if (name.endsWith("/") || segments.length > (scoped ? 2 : 1)) return null;+ return parseNpmName(name);+ }+ return null;+ }+ return parseNpmName(trimmed);+}++/** `name[@version]` → the pair, or null when either half breaks npm's own rules. */+function parseNpmName(spec: string): NpmPluginSpec | null {+ if (spec === "") return null;+ // The `@` of a scope is the FIRST character, so only a later one separates a version.+ const at = spec.lastIndexOf("@");+ const name = at > 0 ? spec.slice(0, at) : spec;+ const version = at > 0 ? spec.slice(at + 1) : undefined;+ if (name.length > 214 || !NPM_NAME.test(name)) return null;+ if (version !== undefined && !NPM_VERSION.test(version)) return null;+ return version === undefined ? { name } : { name, version };+}++/**+ * What an operator typed, as the archive to fetch — the one entry point the route uses.+ *+ * An npm name (see parseNpmPluginSpec) is resolved against the registry, which needs a request of+ * its own: the tarball URL is a function of the version, and `latest` is only known there. Anything+ * else is read as a URL, exactly as before. `fetchImpl`/`timeoutMs` are injectable so the two+ * requests can be tested without a network.+ */+export async function resolvePluginSource(+ raw: string,+ options: { fetchImpl?: typeof fetch; timeoutMs?: number } = {},+): Promise<PluginArchiveSource> {+ const spec = parseNpmPluginSpec(raw);+ if (spec === null) return normalizePluginUrl(raw);+ const found = await fetchPackument(spec, options);+ const entry = pickVersion(spec, found);+ const tarball = entry.tarball;+ let url: URL;+ try {+ url = new URL(tarball);+ } catch {+ throw new HttpError(400, "download_failed", "The registry named an unreadable tarball URL.");+ }+ if (url.protocol !== "http:" && url.protocol !== "https:") {+ throw new HttpError(400, "download_failed", "The registry named an unsupported tarball URL.");+ }+ assertHostAllowed(url);+ return {+ fetchUrl: url.toString(),+ subdir: "",+ // The package's own name, minus the scope: the scope names a publisher, and the plugin is+ // installed under the name its own repository gives it (`@scope/use-firecrawl` → `use-firecrawl`).+ name: spec.name.slice(spec.name.startsWith("@") ? spec.name.indexOf("/") + 1 : 0),+ ...(entry.integrity !== undefined ? { integrity: entry.integrity } : {}),+ };+}++/** One version of a package, as the registry describes it. */+interface NpmVersionEntry {+ tarball: string;+ integrity?: string;+}++/** The packument of one package, or the refusal that says why it could not be read. */+async function fetchPackument(+ spec: NpmPluginSpec,+ options: { fetchImpl?: typeof fetch; timeoutMs?: number },+): Promise<Record<string, unknown>> {+ const doFetch = options.fetchImpl ?? fetch;+ // npm's own encoding of a scoped name: the `@` stays, the scope's slash is percent-encoded.+ const encoded = spec.name.startsWith("@")+ ? `@${encodeURIComponent(spec.name.slice(1))}`+ : encodeURIComponent(spec.name);+ const url = `${NPM_REGISTRY}/${encoded}`;+ let res: Response;+ try {+ res = await doFetch(url, {+ method: "GET",+ redirect: "follow",+ // The abbreviated document: dist-tags and each version's dist, which is all this reads, and a+ // fraction of the full packument for a package with a long history.+ headers: { accept: "application/vnd.npm.install-v1+json, application/json" },+ signal: AbortSignal.timeout(options.timeoutMs ?? DOWNLOAD_TIMEOUT_MS),+ });+ } catch (err) {+ throw new HttpError(400, "npm_registry_failed", `Could not reach npm: ${message(err)}`);+ }+ if (res.url) assertHostAllowed(new URL(res.url));+ if (res.status === 404) {+ throw new HttpError(404, "npm_package_not_found", `npm has no package ${spec.name}.`);+ }+ if (!res.ok) {+ await res.body?.cancel().catch(() => undefined);+ throw new HttpError(+ 400,+ "npm_registry_failed",+ `npm answered HTTP ${res.status} for ${spec.name}.`,+ );+ }+ try {+ const data: unknown = await res.json();+ if (typeof data !== "object" || data === null) throw new Error("not an object");+ return data as Record<string, unknown>;+ } catch {+ throw new HttpError(+ 400,+ "npm_registry_failed",+ `npm returned no usable data for ${spec.name}.`,+ );+ }+}++/**+ * The version to install: the one asked for, or `latest`. Both are DIRECT lookups — the packument+ * is read as a map of versions with a `dist-tags` table beside it, so neither needs a resolver and+ * a range (which NPM_VERSION already refused) has no meaning here.+ */+function pickVersion(spec: NpmPluginSpec, packument: Record<string, unknown>): NpmVersionEntry {+ const versions = packument["versions"];+ const table =+ typeof versions === "object" && versions !== null ? (versions as Record<string, unknown>) : {};+ const distTags = packument["dist-tags"];+ const tags =+ typeof distTags === "object" && distTags !== null ? (distTags as Record<string, unknown>) : {};+ const version = spec.version ?? (typeof tags["latest"] === "string" ? tags["latest"] : undefined);+ if (version === undefined) {+ throw new HttpError(404, "npm_version_not_found", `${spec.name} has no published version.`);+ }+ const entry = table[version];+ if (typeof entry !== "object" || entry === null) {+ throw new HttpError(+ 404,+ "npm_version_not_found",+ `npm has no version ${version} of ${spec.name}; use an exact version or a dist-tag.`,+ );+ }+ const dist = (entry as Record<string, unknown>)["dist"];+ const tarball =+ typeof dist === "object" && dist !== null+ ? (dist as Record<string, unknown>)["tarball"]+ : undefined;+ if (typeof tarball !== "string" || tarball === "") {+ throw new HttpError(404, "npm_version_not_found", `${spec.name}@${version} has no tarball.`);+ }+ const integrity = (dist as Record<string, unknown>)["integrity"];+ const entryOut: NpmVersionEntry = { tarball };+ if (typeof integrity === "string" && integrity !== "") entryOut.integrity = integrity;+ return entryOut;+}++/** The file name of an archive link without its extension (`thing.zip`/`thing.tgz` → `thing`), or undefined for a link that names no archive. */+function archiveStem(file: string): string | undefined {+ const lower = file.toLowerCase();+ for (const suffix of [".tar.gz", ".tgz", ".zip"]) {+ if (lower.endsWith(suffix)) return file.slice(0, -suffix.length);+ }+ return undefined;+}+/** Refuses a host that can only be the server's own network (see the module header). */export function isBlockedHost(hostname: string): boolean {const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");@@ -190,7 +426,35 @@ export async function fetchPluginArchive(await res.body?.cancel().catch(() => undefined);throw pluginArchiveTooLarge(MAX_PLUGIN_ARCHIVE_BYTES);}- return readBounded(res);+ const archive = await readBounded(res);+ if (source.integrity !== undefined) checkIntegrity(source.integrity, archive);+ return archive;+}++/** `<algorithm>-<base64>`, the Subresource Integrity form npm's `dist.integrity` uses. */+const INTEGRITY_PATTERN = /^(sha512|sha384|sha256|sha1)-([A-Za-z0-9+/]+={0,2})$/;++/**+ * Checks the downloaded bytes against the checksum the registry published beside the tarball.+ *+ * HTTPS already authenticates the transfer, so what this adds is the other half: the BYTES the+ * registry vouched for are the bytes that got parsed. A redirect to a mirror, a truncated body+ * that a proxy still called complete, or a registry whose CDN serves something else — all end+ * here rather than in a plugin directory. An algorithm this does not know is passed over rather+ * than guessed at (the digest would be the wrong length and always differ).+ */+function checkIntegrity(integrity: string, archive: Buffer): void {+ const parts = INTEGRITY_PATTERN.exec(integrity);+ if (parts === null) return;+ const expected = Buffer.from(parts[2]!, "base64");+ const actual = createHash(parts[1]!).update(archive).digest();+ if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {+ throw new HttpError(+ 400,+ "integrity_failed",+ "The downloaded archive does not match the checksum the registry published for it.",+ );+ }}/** Reads the body, refusing the moment it passes the cap rather than after buffering it all. */diff --git a/packages/server/src/services/tar-archive.ts b/packages/server/src/services/tar-archive.tsnew file mode 100644index 00000000..269e80d4--- /dev/null+++ b/packages/server/src/services/tar-archive.ts@@ -0,0 +1,269 @@+/**+ * The npm tarball reader: one of the two archive formats a plugin can arrive in, beside the zip+ * the rest of the import path has always taken (see plugin-download.ts for where a `.tgz` comes+ * from and http/routes/plugins.ts for what is done with it).+ *+ * A tarball is a gzipped tar, and there is no sync reader for one in the dependencies — `tar` is+ * a streaming package, and the plugin parser is a pure synchronous function (it is unit-tested+ * that way and called that way by both import routes), so the header walk lives here instead.+ * Only what an npm package needs is implemented: ustar names, the `prefix` field, pax extended+ * headers and GNU long names, base-256 sizes, and regular files. Links, devices and sparse+ * members are skipped rather than followed — a plugin is a directory of files.+ *+ * Two caps, and one set of numbers for the content: `gunzipBounded` bounds the INFLATED size+ * before a byte of tar is read (the compressed archive is already bounded at 32MB by the download+ * path, but gzip is a ratio, and 32MB of zeros is tens of gigabytes of tar), and `untarBounded`+ * applies the plugin limits the zip reader applies (skill-import-limits.ts), on the sizes the+ * headers declare — the same reason they are read there rather than counted afterwards.+ */+import { gunzipSync } from "node:zlib";+import { HttpError } from "../http/errors.js";+import { badRequest } from "../http/validate.js";+import { MAX_ARCHIVE_FILES, MAX_FILE_BYTES, MAX_TOTAL_BYTES } from "./skill-import-limits.js";++/** The tar block every member starts on. */+const BLOCK = 512;++/**+ * How large a tarball may be once gunzipped, before any of it is parsed. Generous next to the+ * archives the path accepts (the largest shipped plugin is under 200KB packed, the download cap is+ * 32MB) and small enough to bound one request's memory: what this refuses is a decompression bomb,+ * not a large package.+ */+export const MAX_INFLATED_TARBALL_BYTES = 64 * 1024 * 1024;++/** Whether these bytes are gzipped — the one signature that says "tarball" rather than "zip". */+export function isGzip(archive: Uint8Array): boolean {+ return archive[0] === 0x1f && archive[1] === 0x8b;+}++/**+ * Gunzips a tarball, refusing one that inflates past the cap instead of allocating it. The+ * compression bomb is the whole point: 32MB of plausible-looking upload can expand to gigabytes,+ * and the header walk below would only get to see that after it is already in memory.+ */+export function gunzipBounded(archive: Uint8Array): Uint8Array {+ try {+ return gunzipSync(archive, { maxOutputLength: MAX_INFLATED_TARBALL_BYTES });+ } catch (err) {+ // zlib's own answer to the cap (ERR_BUFFER_TOO_LARGE) is the one refusal that is about size+ // rather than about the bytes; everything else is a corrupt or non-gzip body.+ if (err instanceof Error && (err as NodeJS.ErrnoException).code === "ERR_BUFFER_TOO_LARGE") {+ throw new HttpError(+ 413,+ "plugin_too_large",+ `The npm tarball unpacks to more than ${MAX_INFLATED_TARBALL_BYTES / (1024 * 1024)}MB.`,+ );+ }+ throw badRequest("The archive is not a valid npm tarball.");+ }+}++/** One regular-file member of a tar, as its header declares it. */+interface TarMember {+ name: string;+ /** The size the header claims; the walker has already checked the archive holds that much. */+ size: number;+ /** Where the member's bytes start in the archive. */+ dataOffset: number;+}++/**+ * Every regular-file member of a tar, in archive order, reading headers alone — the tar equivalent+ * of the zip central-directory scan `entryNames` does, and what makes the two-pass import cheap:+ * locating the plugin root costs a walk, not a copy.+ *+ * Throws (a 400) on structural damage — a bad checksum, a truncated member, an entry path that+ * would land outside a directory (see checkEntryName) — rather than skipping it: half an archive+ * is not a smaller archive, and the caller's answer to any of these is the same.+ */+export function tarMembers(archive: Uint8Array): TarMember[] {+ const members: TarMember[] = [];+ // Set by the pax/GNU header immediately BEFORE the member it describes, and cleared by that+ // member whichever branch takes it: an extended header applies to exactly one entry.+ let pendingName: string | undefined;+ let pendingSize: number | undefined;+ let offset = 0;+ while (offset + BLOCK <= archive.byteLength) {+ const header = archive.subarray(offset, offset + BLOCK);+ // Two zero blocks end a tar; a single one is the padding some writers leave. Either way the+ // rest of the archive is padding, and what came before it is the whole archive.+ if (isZeroBlock(header)) break;+ checkChecksum(header, offset);+ const type = String.fromCharCode(header[156] ?? 0);+ const isFile = type === "0" || type === "\0";+ // A file's size is what the header says, unless a pax record corrected it (the octal field is+ // what past-GB sizes cannot be written into); every other header describes its own data.+ const size = (isFile ? pendingSize : undefined) ?? readNumber(header, 124, 12) ?? 0;+ if (offset + BLOCK + size > archive.byteLength) {+ throw badRequest("The npm tarball is truncated.");+ }+ const data = archive.subarray(offset + BLOCK, offset + BLOCK + size);+ const padded = Math.ceil(size / BLOCK) * BLOCK;++ if (type === "x" || type === "X") {+ // A pax extended header: "length key=value\n" records, applied to the next member.+ const records = parsePax(data);+ pendingName = records.get("path") ?? pendingName;+ const paxSize = records.get("size");+ if (paxSize !== undefined) {+ const parsed = Number(paxSize);+ if (!Number.isSafeInteger(parsed) || parsed < 0) {+ throw badRequest("The npm tarball declares an unusable member size.");+ }+ pendingSize = parsed;+ }+ } else if (type === "L") {+ // GNU long name: the member's own name, in the data of this header.+ pendingName = text(data).replace(/\0+$/, "");+ } else if (isFile) {+ const name = pendingName ?? joinPrefix(header);+ checkEntryName(name);+ members.push({ name, size, dataOffset: offset + BLOCK });+ pendingName = undefined;+ pendingSize = undefined;+ } else {+ // Directories, links, devices, sparse members: nothing a plugin is made of, and nothing to+ // follow — a tar may describe a link whose target is outside the archive entirely.+ pendingName = undefined;+ pendingSize = undefined;+ }+ offset += BLOCK + padded;+ }+ return members;+}++/** Every member name, in archive order (the tar half of what pluginRootIn reads). */+export function tarEntryNames(archive: Uint8Array): string[] {+ return tarMembers(archive).map((member) => member.name);+}++/**+ * `tarMembers` with the plugin caps enforced and the wanted members copied out — the tar+ * counterpart of `unzipBounded`, and bounded the same way: against the sizes the headers declare,+ * before a byte is copied. `wanted` is asked before the counting, so a tarball holding a whole+ * package beside the plugin is bounded on the plugin (see that function's note).+ *+ * Members are copied, not viewed: the returned buffers outlive this call and are written to disk+ * by the installer, and a view onto the caller's download would keep the whole archive alive.+ */+export function untarBounded(+ archive: Uint8Array,+ wanted: (name: string) => boolean = () => true,+): Record<string, Uint8Array> {+ const files: Record<string, Uint8Array> = {};+ let count = 0;+ let declared = 0;+ for (const member of tarMembers(archive)) {+ if (!wanted(member.name)) continue;+ count += 1;+ if (count > MAX_ARCHIVE_FILES) {+ throw badRequest(`The tar archive exceeds the ${MAX_ARCHIVE_FILES}-file limit.`);+ }+ if (member.size > MAX_FILE_BYTES) {+ throw badRequest(`Tar member exceeds the 5MB uncompressed limit: ${member.name}`);+ }+ declared += member.size;+ if (declared > MAX_TOTAL_BYTES) {+ throw badRequest("The tar archive exceeds the 20MB uncompressed limit.");+ }+ files[member.name] = archive.slice(member.dataOffset, member.dataOffset + member.size);+ }+ return files;+}++/** Whether a 512-byte block is all zeroes (the end-of-archive marker). */+function isZeroBlock(header: Uint8Array): boolean {+ for (const byte of header) {+ if (byte !== 0) return false;+ }+ return true;+}++/**+ * Verifies the header's checksum: the sum of its bytes with the checksum field itself read as+ * spaces. Cheap (512 bytes) and the one integrity check a tar carries — a corrupt download is+ * caught here rather than as a nonsense member list.+ */+function checkChecksum(header: Uint8Array, offset: number): void {+ const declared = readNumber(header, 148, 8);+ if (declared === undefined) throw badRequest("The npm tarball member has no checksum.");+ let sum = 0;+ for (let i = 0; i < BLOCK; i += 1) {+ // The checksum field (bytes 148-155) contributes as if it were spaces.+ sum += i >= 148 && i < 156 ? 0x20 : (header[i] ?? 0);+ }+ if (sum !== declared) {+ throw badRequest(`The npm tarball member at byte ${offset} is corrupt.`);+ }+}++/**+ * The member's name: the ustar `prefix` field in front of `name` when both are present, which is+ * how a path longer than 100 bytes is stored without a pax header.+ */+function joinPrefix(header: Uint8Array): string {+ const name = text(header.subarray(0, 100));+ const prefix = text(header.subarray(345, 500));+ return prefix === "" ? name : `${prefix}/${name}`;+}++/** A NUL-terminated field, read as UTF-8 (npm writes UTF-8 names; tar's own default is ASCII). */+function text(bytes: Uint8Array): string {+ const end = bytes.indexOf(0);+ return Buffer.from(end === -1 ? bytes : bytes.subarray(0, end)).toString("utf8");+}++/**+ * A numeric header field: octal ASCII, or base-256 for the GNU/POSIX binary form (values past+ * what octal fits, marked by the high bit of the first byte).+ */+function readNumber(header: Uint8Array, offset: number, length: number): number | undefined {+ const first = header[offset] ?? 0;+ if ((first & 0x80) !== 0) {+ let value = first & 0x7f;+ for (let i = 1; i < length; i += 1) {+ value = value * 256 + (header[offset + i] ?? 0);+ }+ return Number.isSafeInteger(value) ? value : undefined;+ }+ const raw = text(header.subarray(offset, offset + length)).trim();+ if (raw === "") return 0;+ const value = Number.parseInt(raw, 8);+ return Number.isFinite(value) && value >= 0 ? value : undefined;+}++/** The records of a pax extended header: `"<length> <key>=<value>\n"`, length counting the whole record. */+function parsePax(data: Uint8Array): Map<string, string> {+ const records = new Map<string, string>();+ const raw = Buffer.from(data).toString("utf8");+ let offset = 0;+ while (offset < raw.length) {+ const space = raw.indexOf(" ", offset);+ if (space === -1) break;+ const length = Number.parseInt(raw.slice(offset, space), 10);+ // A record that does not fit the buffer it claims to be in is the end of the usable part.+ if (!Number.isFinite(length) || length <= 0 || offset + length > raw.length) break;+ const record = raw.slice(space + 1, offset + length - 1);+ const equals = record.indexOf("=");+ if (equals !== -1) records.set(record.slice(0, equals), record.slice(equals + 1));+ offset += length;+ }+ return records;+}++/**+ * The one entry-path rule, the tar side of `assertSafeEntryPath`: no absolute path, no backslash+ * and no ".." segment. Enforced on EVERY member rather than on the chosen plugin root alone (which+ * is where the zip reader runs it), because a tar's member list is what the plugin root is chosen+ * FROM — a root found under a `..` would otherwise be trusted for one step.+ */+function checkEntryName(name: string): void {+ if (name.includes("\\")) throw badRequest(`Invalid tar entry path (backslash): ${name}`);+ if (name.startsWith("/") || /^[A-Za-z]:/.test(name)) {+ throw badRequest(`Invalid tar entry path (absolute): ${name}`);+ }+ if (name.split("/").some((segment) => segment === "..")) {+ throw badRequest(`Invalid tar entry path (traversal): ${name}`);+ }+}diff --git a/packages/server/test/plugin-npm-import.test.ts b/packages/server/test/plugin-npm-import.test.tsnew file mode 100644index 00000000..9125e551--- /dev/null+++ b/packages/server/test/plugin-npm-import.test.ts@@ -0,0 +1,428 @@+/**+ * The npm half of the plugin import: an operator names an npm package instead of a URL, and what+ * arrives is a gzipped tar rather than a zip.+ *+ * Three things are pinned here. First the tar reader (services/tar-archive.ts), against archives+ * built byte by byte in this file — a real `npm pack` tarball is a ustar one, so the header walk,+ * the checksum, the `package/` wrapper and a pax long name are exactly what has to work. Second+ * the reader of the specifier itself, which decides what counts as an npm name at all. Third the+ * route end to end, with the registry and the tarball both answered by a stubbed `fetch`: the+ * plugin has to land under the package's own (unscoped) name, and every way the registry can+ * refuse — no such package, no such version, bytes that do not match the published checksum — has+ * to come back as its own code rather than as a generic failure.+ */+import { createHash } from "node:crypto";+import path from "node:path";+import { gzipSync } from "node:zlib";+import { strToU8, zipSync } from "fflate";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import type { PluginImportResponse, PluginLibraryResponse } from "../src/api/types.js";+import { parsePluginArchive } from "../src/http/routes/plugins.js";+import { parseNpmPluginSpec, resolvePluginSource } from "../src/services/plugin-download.js";+import { apiClient, createTestApp, loginAdmin } from "./helpers.js";+import type { TestApp } from "./helpers.js";++/** A minimal valid plugin: manifest, icon and one skill (the loader requires the SKILL.md frontmatter name). */+function pluginFiles(version = "2026.09.01.1"): Record<string, string> {+ return {+ "plugin.json": `${JSON.stringify(+ {+ description: "A plugin published to npm.",+ short_description: "From npm.",+ version,+ category: "software-development",+ },+ null,+ 2,+ )}\n`,+ "icon.svg": '<svg xmlns="http://www.w3.org/2000/svg"></svg>\n',+ "skills/from-npm/SKILL.md":+ "---\nname: from-npm\ndescription: A skill the plugin ships.\n---\n\nBody.\n",+ };+}++const BLOCK = 512;++/** One octal header field: `length` bytes, NUL-terminated, as ustar writes them. */+function octalField(value: number, length: number): string {+ return value.toString(8).padStart(length - 1, "0") + "\0";+}++/** One 512-byte ustar header, checksum included — the format `npm pack` writes. */+function tarHeader(name: string, size: number, type: string): Uint8Array {+ const block = new Uint8Array(BLOCK);+ const put = (text: string, offset: number, length: number) => {+ const bytes = Buffer.from(text, "utf8");+ if (bytes.byteLength > length) throw new Error(`test tar field overflow: ${text}`);+ block.set(bytes, offset);+ };+ put(name, 0, 100);+ put(octalField(0o644, 8), 100, 8);+ put(octalField(0, 8), 108, 8);+ put(octalField(0, 8), 116, 8);+ put(octalField(size, 12), 124, 12);+ put(octalField(0, 12), 136, 12);+ put(" ", 148, 8);+ put(type, 156, 1);+ put("ustar\0", 257, 6);+ put("00", 263, 2);+ let sum = 0;+ for (const byte of block) sum += byte;+ put(`${sum.toString(8).padStart(6, "0")}\0 `, 148, 8);+ return block;+}++/** A pax extended record: `"<length> <key>=<value>\n"`, the length counting the whole record. */+function paxRecord(key: string, value: string): Buffer {+ const body = ` ${key}=${value}\n`;+ let total = body.length + 1;+ while (String(total).length + body.length !== total) total = String(total).length + body.length;+ return Buffer.from(`${total}${body}`, "utf8");+}++/** One member, as the blocks it occupies: a pax header first when the name outgrows ustar's field. */+function tarMember(name: string, content: string): Uint8Array[] {+ const data = strToU8(content);+ const padded = data.byteLength % BLOCK === 0 ? 0 : BLOCK - (data.byteLength % BLOCK);+ const blocks: Uint8Array[] = [];+ let headerName = name;+ if (Buffer.byteLength(name, "utf8") > 100) {+ const record = paxRecord("path", name);+ blocks.push(+ tarHeader("PaxHeader/ignored", record.byteLength, "x"),+ record,+ new Uint8Array(BLOCK - record.byteLength),+ );+ headerName = name.slice(0, 99);+ }+ blocks.push(tarHeader(headerName, data.byteLength, "0"), data, new Uint8Array(padded));+ return blocks;+}++/** A tar of the given files, ended the way every tar is (two zero blocks). */+function tar(files: Record<string, string>): Buffer {+ const blocks: Uint8Array[] = [];+ for (const [name, content] of Object.entries(files)) blocks.push(...tarMember(name, content));+ blocks.push(new Uint8Array(BLOCK), new Uint8Array(BLOCK));+ return Buffer.concat(blocks);+}++/** The same, gzipped: what the registry serves. */+function tgz(files: Record<string, string>): Buffer {+ return gzipSync(tar(files));+}++/** The files of `pluginFiles()`, as npm packages them: inside `package/`. */+function npmFiles(version = "2026.09.01.1"): Record<string, string> {+ const inner: Record<string, string> = {};+ for (const [rel, text] of Object.entries(pluginFiles(version))) inner[`package/${rel}`] = text;+ return inner;+}++/** A zip of the given files, for the upload half of the route. */+function zip(files: Record<string, string>): Buffer {+ const entries: Record<string, Uint8Array> = {};+ for (const [rel, text] of Object.entries(files)) entries[rel] = strToU8(text);+ return Buffer.from(zipSync(entries));+}++const readErrorCode = async (res: Response): Promise<string> =>+ ((await res.json()) as { error: { code: string } }).error.code;++/** The `sha512-…` form the registry publishes, for the stubs below. */+function integrityOf(bytes: Uint8Array): string {+ return `sha512-${createHash("sha512").update(bytes).digest("base64")}`;+}++describe("parsePluginArchive, on a tarball", () => {+ it("unpacks the package npm wraps in `package/`, under the name the request gives", () => {+ const parsed = parsePluginArchive(tgz(npmFiles()), { name: "from-npm" });+ expect(parsed.name).toBe("from-npm");+ expect(Object.keys(parsed.files).sort()).toEqual([+ "icon.svg",+ "plugin.json",+ "skills/from-npm/SKILL.md",+ ]);+ expect(Buffer.from(parsed.files["plugin.json"]!).toString("utf8")).toContain(+ "A plugin published to npm.",+ );+ });++ it("refuses a tarball that names nothing, because `package/` is the format and not the plugin", () => {+ // The same files as a zip would name the plugin `package`; npm's own wrapper must not.+ expect(() => parsePluginArchive(tgz(npmFiles()))).toThrow(/name is required for a tarball/);+ });++ it("reads a member whose path only a pax extended header carries", () => {+ const long = `${"nested/".repeat(20)}SKILL.md`;+ const files = npmFiles();+ files[`package/extra/${long}`] = "---\nname: deep\ndescription: Deep.\n---\n";+ const parsed = parsePluginArchive(tgz(files), { name: "deep" });+ expect(Object.keys(parsed.files)).toContain(`extra/${long}`);+ });++ it("takes the plugin root out of a tarball that also holds other plugins, by the same rule as a zip", () => {+ const files: Record<string, string> = {};+ for (const [rel, text] of Object.entries(pluginFiles())) {+ files[`package/plugins/one/${rel}`] = text;+ files[`package/plugins/two/${rel}`] = text;+ }+ const parsed = parsePluginArchive(tgz(files), { name: "one", subdir: "plugins/one" });+ expect(Object.keys(parsed.files)).toContain("plugin.json");+ });++ it("refuses a traversing member path, a truncated tarball and one that is not a tar", () => {+ expect(() => parsePluginArchive(tgz({ "package/../escape.txt": "no" }), { name: "x" })).toThrow(+ /Invalid tar entry path/,+ );+ // A member whose header promises more bytes than the archive holds: 4KB of content, cut short.+ const truncated = tar({ "package/notes.txt": "x".repeat(4096) }).subarray(0, 700);+ expect(() => parsePluginArchive(gzipSync(truncated), { name: "x" })).toThrow(/truncated/);+ // Gzip that is not a tar at all: no members, so there is no plugin to find.+ expect(() => parsePluginArchive(gzipSync(Buffer.from("just text")), { name: "x" })).toThrow(+ /no files|no plugin.json/,+ );+ });++ it("refuses a tarball that unpacks past the inflated cap instead of allocating it", () => {+ // What the cap is for: 80MB of zeroes compresses to a few kilobytes, so the compressed size+ // says nothing about what parsing it would cost.+ const bomb = gzipSync(Buffer.alloc(80 * 1024 * 1024));+ expect(() => parsePluginArchive(bomb, { name: "bomb" })).toThrow(/unpacks to more than 64MB/);+ });++ it("applies the plugin file caps to a tarball's members", () => {+ const files = npmFiles();+ for (let i = 0; i < 200; i += 1) {+ files[`package/skills/extra-${i}/SKILL.md`] = `---\nname: extra-${i}\ndescription: F.\n---\n`;+ }+ expect(() => parsePluginArchive(tgz(files), { name: "crowded" })).toThrow(/200-file limit/);+ });++ it("still reads a zip, byte for byte as before", () => {+ const inner: Record<string, string> = {};+ for (const [rel, text] of Object.entries(pluginFiles())) inner[`zipped/${rel}`] = text;+ const parsed = parsePluginArchive(zip(inner));+ expect(parsed.name).toBe("zipped");+ expect(Object.keys(parsed.files).sort()).toEqual([+ "icon.svg",+ "plugin.json",+ "skills/from-npm/SKILL.md",+ ]);+ });+});++describe("parseNpmPluginSpec", () => {+ it("reads the explicit spelling, with and without a version", () => {+ expect(parseNpmPluginSpec("npm:@penguinharness/use-firecrawl")).toEqual({+ name: "@penguinharness/use-firecrawl",+ });+ expect(parseNpmPluginSpec("npm:[email protected]")).toEqual({+ name: "use-firecrawl",+ version: "0.2.13",+ });+ expect(parseNpmPluginSpec("NPM:@scope/name@latest")).toEqual({+ name: "@scope/name",+ version: "latest",+ });+ });++ it("reads a bare package name, and the npmjs.com page a search ends on", () => {+ expect(parseNpmPluginSpec("@lmliheng/data-analysis")).toEqual({+ name: "@lmliheng/data-analysis",+ });+ expect(parseNpmPluginSpec("data-analysis")).toEqual({ name: "data-analysis" });+ expect(parseNpmPluginSpec("[email protected]")).toEqual({+ name: "data-analysis",+ version: "2026.9.14.1",+ });+ expect(parseNpmPluginSpec("https://www.npmjs.com/package/@penguinharness/goal")).toEqual({+ name: "@penguinharness/goal",+ });+ expect(parseNpmPluginSpec("https://www.npmjs.com/package/goal/v/0.2.13")).toEqual({+ name: "goal",+ version: "0.2.13",+ });+ expect(parseNpmPluginSpec("https://registry.npmjs.org/@penguinharness%2Fgoal")).toEqual({+ name: "@penguinharness/goal",+ });+ });++ it("reads nothing else — a GitHub page, a version range and a sentence stay addresses", () => {+ expect(parseNpmPluginSpec("https://github.com/o/r")).toBeNull();+ expect(parseNpmPluginSpec("https://example.com/thing.zip")).toBeNull();+ expect(parseNpmPluginSpec("https://www.npmjs.com/settings/tokens")).toBeNull();+ // A range is not a version and not an address: the caller answers 400 unsupported_url, which+ // is the honest answer — this server does not resolve ranges.+ expect(parseNpmPluginSpec("@scope/name@^1.0.0")).toBeNull();+ expect(parseNpmPluginSpec("not a url")).toBeNull();+ expect(parseNpmPluginSpec(" ")).toBeNull();+ });+});++describe("resolvePluginSource", () => {+ const packument = (integrity?: string) => ({+ "dist-tags": { latest: "0.2.13" },+ versions: {+ "0.2.13": {+ dist: {+ tarball: "https://registry.npmjs.org/@scope/name/-/name-0.2.13.tgz",+ ...(integrity !== undefined ? { integrity } : {}),+ },+ },+ },+ });++ it("asks the registry for the package, then names its tarball and the unscoped package name", async () => {+ const calls: string[] = [];+ const fetchImpl = (async (input: Parameters<typeof fetch>[0]) => {+ calls.push(String(input));+ return new Response(JSON.stringify(packument()), { status: 200 });+ }) as typeof fetch;+ const source = await resolvePluginSource("npm:@scope/name", { fetchImpl });+ expect(calls).toEqual(["https://registry.npmjs.org/@scope%2Fname"]);+ expect(source).toEqual({+ fetchUrl: "https://registry.npmjs.org/@scope/name/-/name-0.2.13.tgz",+ subdir: "",+ name: "name",+ });+ });++ it("carries the published checksum along, and the version that was asked for", async () => {+ let asked = "";+ const fetchImpl = (async (input: Parameters<typeof fetch>[0]) => {+ asked = String(input);+ return new Response(JSON.stringify(packument("sha512-abc")), { status: 200 });+ }) as typeof fetch;+ const source = await resolvePluginSource("[email protected]", { fetchImpl });+ expect(asked).toBe("https://registry.npmjs.org/name");+ expect(source.integrity).toBe("sha512-abc");+ expect(source.name).toBe("name");+ });++ it("answers 404 when npm has no such package, and 404 when it has no such version", async () => {+ const missing = (async () =>+ new Response("Not found", { status: 404 })) as unknown as typeof fetch;+ await expect(resolvePluginSource("npm:@scope/absent", { fetchImpl: missing })).rejects.toThrow(+ /npm has no package/,+ );+ const known = (async () =>+ new Response(JSON.stringify(packument()), { status: 200 })) as typeof fetch;+ await expect(resolvePluginSource("[email protected]", { fetchImpl: known })).rejects.toThrow(+ /no version 9.9.9/,+ );+ });++ it("leaves every non-npm address to the URL reader", async () => {+ const source = await resolvePluginSource("https://github.com/o/r/tree/main/plugins/x");+ expect(source).toEqual({+ fetchUrl: "https://github.com/o/r/archive/main.zip",+ subdir: "plugins/x",+ name: "x",+ });+ // A tarball link names itself like a zip does.+ expect(await resolvePluginSource("https://example.com/plugins/thing.tgz")).toEqual({+ fetchUrl: "https://example.com/plugins/thing.tgz",+ subdir: "",+ name: "thing",+ });+ });+});++describe("the download route, importing from npm", () => {+ let t: TestApp;+ let admin: ReturnType<typeof apiClient>;+ let prevHome: string | undefined;++ beforeEach(async () => {+ t = await createTestApp();+ prevHome = process.env.PENGUIN_HOME;+ process.env.PENGUIN_HOME = t.root;+ admin = apiClient(t.app, (await loginAdmin(t.app)).cookie);+ });+ afterEach(async () => {+ vi.unstubAllGlobals();+ if (prevHome === undefined) delete process.env.PENGUIN_HOME;+ else process.env.PENGUIN_HOME = prevHome;+ await t.cleanup();+ });++ /** A stubbed registry and CDN: the packument URL answers the document, the `.tgz` URL the tarball. */+ const stubRegistry = (options: { integrity?: string; calls?: string[] } = {}) => {+ const tarball = tgz(npmFiles());+ vi.stubGlobal("fetch", async (input: Parameters<typeof fetch>[0]) => {+ const url = String(input);+ options.calls?.push(url);+ if (url.endsWith(".tgz")) return new Response(new Uint8Array(tarball), { status: 200 });+ return new Response(+ JSON.stringify({+ "dist-tags": { latest: "0.2.13" },+ versions: {+ "0.2.13": {+ dist: {+ tarball: "https://registry.npmjs.org/@lmliheng/from-npm/-/from-npm-0.2.13.tgz",+ integrity: options.integrity ?? integrityOf(tarball),+ },+ },+ },+ }),+ { status: 200 },+ );+ });+ };++ const libraryNames = async (): Promise<string[]> => {+ const res = await admin.get("/api/plugins");+ const body = (await res.json()) as PluginLibraryResponse;+ return body.groups.flatMap((g) => g.plugins.map((p) => p.name)).sort();+ };++ it("installs the package's tarball under its unscoped name, files and all", async () => {+ const calls: string[] = [];+ stubRegistry({ calls });+ const res = await admin.post("/api/plugins/download", { url: "@lmliheng/from-npm" });+ expect(res.status).toBe(201);+ const body = (await res.json()) as PluginImportResponse;+ expect(body.plugin).toMatchObject({ name: "from-npm", source: "user" });+ expect(body.path).toBe(path.join(t.root, "plugins", "from-npm"));+ expect(calls).toEqual([+ "https://registry.npmjs.org/@lmliheng%2Ffrom-npm",+ "https://registry.npmjs.org/@lmliheng/from-npm/-/from-npm-0.2.13.tgz",+ ]);+ expect(await libraryNames()).toContain("from-npm");+ const files = (await (await admin.get("/api/plugins/from-npm/files")).json()) as {+ files: Record<string, string>;+ };+ expect(Object.keys(files.files)).toContain("skills/from-npm/SKILL.md");+ });++ it("refuses a tarball whose bytes are not the ones the registry published", async () => {+ // The checksum of OTHER bytes: what a redirected or substituted tarball looks like.+ stubRegistry({ integrity: integrityOf(Buffer.from("tampered")) });+ const res = await admin.post("/api/plugins/download", { url: "npm:from-npm" });+ expect(res.status).toBe(400);+ expect(await readErrorCode(res)).toBe("integrity_failed");+ expect(await libraryNames()).not.toContain("from-npm");+ });++ it("answers npm's own refusals with their own codes, and writes nothing on the way", async () => {+ vi.stubGlobal("fetch", async () => new Response("{}", { status: 404 }));+ const absent = await admin.post("/api/plugins/download", { url: "npm:@lmliheng/absent" });+ expect(absent.status).toBe(404);+ expect(await readErrorCode(absent)).toBe("npm_package_not_found");++ vi.stubGlobal("fetch", async () => new Response("this is not json", { status: 200 }));+ const unreadable = await admin.post("/api/plugins/download", { url: "npm:@lmliheng/odd" });+ expect(unreadable.status).toBe(400);+ expect(await readErrorCode(unreadable)).toBe("npm_registry_failed");++ vi.stubGlobal("fetch", async () => {+ throw new Error("getaddrinfo ENOTFOUND registry.npmjs.org");+ });+ const offline = await admin.post("/api/plugins/download", { url: "npm:@lmliheng/offline" });+ expect(offline.status).toBe(400);+ expect(await readErrorCode(offline)).toBe("npm_registry_failed");++ expect(await libraryNames()).not.toContain("absent");+ });+});diff --git a/packages/web/src/api/endpoints.ts b/packages/web/src/api/endpoints.tsindex 1f504098..f44f8400 100644--- a/packages/web/src/api/endpoints.ts+++ b/packages/web/src/api/endpoints.ts@@ -1574,10 +1574,13 @@ export const importPluginArchive = (body: PluginUploadRequest) =>apiFetch<PluginImportResponse>("/api/plugins/upload", { method: "POST", body });/**- * The same import, fetched server-side from a URL: a zip link, a GitHub repository- * (`https://github.com/<owner>/<repo>`, default branch) or a GitHub tree URL- * (`…/tree/<ref>/<subdir>`, whose subdirectory is the plugin root). Same 409 `plugin_exists`- * as the upload, and the same admin-only gate.+ * The same import, fetched server-side from an address or an npm package: a zip or `.tgz` link, a+ * GitHub repository (`https://github.com/<owner>/<repo>`, default branch), a GitHub tree URL+ * (`…/tree/<ref>/<subdir>`, whose subdirectory is the plugin root), or a package name+ * (`@scope/name[@version]`, `npm:@scope/name`, an npmjs.com package page) — installed under the+ * package's own name, without its scope. Same 409 `plugin_exists` as the upload, the same+ * admin-only gate, and its own codes for what npm can answer (404 `npm_package_not_found`,+ * 404 `npm_version_not_found`, 400 `npm_registry_failed`, 400 `integrity_failed`).*/export const importPluginFromUrl = (body: PluginDownloadRequest) =>apiFetch<PluginImportResponse>("/api/plugins/download", { method: "POST", body });diff --git a/packages/web/src/features/plugins/plugin-import.ts b/packages/web/src/features/plugins/plugin-import.tsindex cd1a9865..968cce5d 100644--- a/packages/web/src/features/plugins/plugin-import.ts+++ b/packages/web/src/features/plugins/plugin-import.ts@@ -71,18 +71,23 @@ export function pluginNameBody(name: string): { name?: string } {* The plugin name a URL names, for the overwrite confirmation's copy — the name the server* would derive, read off the address the user pasted.*+ * - an npm package (a bare `@scope/name`, an `npm:` specifier, an npmjs.com package page) names+ * the package WITHOUT its scope: the scope names a publisher, and the plugin is installed+ * under the name the package publishes under (`@acme/use-firecrawl` → `use-firecrawl`);* - `https://github.com/<owner>/<repo>` names the repo (a trailing `.git` included: the address* bar hands one back when it was copied from the clone button);* - `…/tree/<ref>/<subdir…>` names the plugin root, i.e. the LAST segment of the subdirectory —* the subdirectory IS the plugin (see the route's shallowest-plugin.json rule), and the ref* in front of it names a commit rather than anything the user will recognize;- * - anything else names its last segment with a `.zip` suffix dropped: a direct link to the- * archive.+ * - anything else names its last segment with an archive suffix dropped: a direct link to the+ * zip or npm tarball.** Query and fragment are stripped first: neither names anything, and a pasted address usually* ends in a trailing slash, which would otherwise leave an empty last segment.*/export function pluginNameFromUrl(url: string): string {+ const npm = pluginNameFromNpm(url);+ if (npm !== undefined) return npm;const segments = url.trim().replace(/[?#].*$/, "")@@ -94,8 +99,55 @@ export function pluginNameFromUrl(url: string): string {if (tree !== -1 && segments.length <= tree + 2) return segments[tree - 1] ?? "";const last = segments[segments.length - 1] ?? "";// A tree URL points at a directory, so its last segment is already the name; everywhere else- // the last segment is a file (`plugin.zip`) or a repo (`plugin.git`).- return tree === -1 ? last.replace(/\.(zip|git)$/i, "") : last;+ // the last segment is a file (`plugin.zip`, `plugin.tgz`) or a repo (`plugin.git`).+ return tree === -1 ? last.replace(/\.(zip|tgz|tar\.gz|git)$/i, "") : last;+}++/** An npm package name: `name` or `@scope/name`, in the character set npm allows (the server's own reader, copied). */+const NPM_PACKAGE_NAME = /^(?:@[A-Za-z0-9._~!*'()-]+\/)?[A-Za-z0-9._~!*'()-]+$/;++/**+ * The unscoped package name this text names as an npm package, or undefined when it names none —+ * a client copy of the server's reader (services/plugin-download.ts), here for the same reason as+ * the name pattern above: the web resolves the server's wire types, never its source, and both+ * sides have to read the same input the same way for the confirmation to name the right plugin.+ *+ * The version is dropped because it is not part of the folder; the scope is dropped because the+ * plugin is installed under the package's own name (the server's rule, and the reason importing+ * `@acme/data-analysis` installs `data-analysis`).+ */+function pluginNameFromNpm(text: string): string | undefined {+ const trimmed = text.trim();+ let spec = trimmed;+ if (/^npm:/i.test(trimmed)) {+ spec = trimmed.slice("npm:".length).trim();+ } else if (/^https?:\/\//i.test(trimmed)) {+ // Only npmjs.com's PACKAGE page is a package: an account or search page names none, and+ // another host's `/package/…` path is that site's business (the server fetches it as a link).+ if (!/^https?:\/\/(?:www\.)?npmjs\.com\/package\//i.test(trimmed)) return undefined;+ const parts = trimmed+ .replace(/[?#].*$/, "")+ .split("/")+ .filter(Boolean);+ const marker = parts.indexOf("package");+ const first = marker === -1 ? undefined : parts[marker + 1];+ if (first === undefined) return undefined;+ const scoped = first.startsWith("@");+ const name = scoped ? `${first}/${parts[marker + 2] ?? ""}` : first;+ if (name.endsWith("/") || !NPM_PACKAGE_NAME.test(name)) return undefined;+ return unscopedName(name);+ }+ // `name@version` / `@scope/name@version`: the scope's own `@` is the first character, so only a+ // later one separates a version.+ const at = spec.lastIndexOf("@");+ const name = at > 0 ? spec.slice(0, at) : spec;+ if (!NPM_PACKAGE_NAME.test(name)) return undefined;+ return unscopedName(name);+}++/** `@scope/name` → `name` (the folder a plugin is installed under). */+function unscopedName(name: string): string {+ return name.startsWith("@") ? name.slice(name.indexOf("/") + 1) : name;}/** The name inside the 409 the plugin routes answer with: "A user plugin named <name> is already installed." */diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.tsindex 424b88c1..0c40c59c 100644--- a/packages/web/src/lib/strings-en.ts+++ b/packages/web/src/lib/strings-en.ts@@ -2136,10 +2136,10 @@ export const en: Strings = {*/importRulesTitle: "Plugin import rules",importRules: [- "The source is a local zip, or a URL: a direct zip link, a GitHub repository (its default branch), or a directory inside one (\u2026/tree/<ref>/<subdir>).",- "The archive must be a zip carrying plugin.json; the plugin root is the shallowest directory holding one, and two of them at the same depth are refused.",- "The name is taken in this order: what you type here \u2192 the name the URL carries (a directory URL's last segment, a repository URL's repository name, a zip link's file name) \u2192 the plugin root's directory name; letters, digits, underscores and hyphens only. Importing from a repository URL therefore installs it under the repository's name.",- "Caps: an uploaded zip is at most 14 MB and a downloaded archive 32 MB; after unpacking, only the plugin root counts \u2014 200 files, 5 MB each, 20 MB in total.",+ "The source is a local zip, or an address or npm package: a direct zip link, a GitHub repository (its default branch), a directory inside one (\u2026/tree/<ref>/<subdir>), or an npm package (@scope/name, @scope/[email protected], npm:@scope/name \u2014 no version means `latest`).",+ "The archive must be a zip carrying plugin.json, or an npm tgz (the tarball the registry serves for that version, checked against the checksum it published); the plugin root is the shallowest directory holding plugin.json, and two of them at the same depth are refused.",+ "The name is taken in this order: what you type here \u2192 the name the source carries (a directory URL's last segment, a repository URL's repository name, an archive link's file name, an npm package's name without its scope) \u2192 the plugin root's directory name; letters, digits, underscores and hyphens only. Importing from a repository URL therefore installs it under the repository's name.",+ "Caps: an uploaded zip is at most 14 MB, a downloaded archive 32 MB and an npm tarball 64 MB once unpacked; after unpacking, only the plugin root counts \u2014 200 files, 5 MB each, 20 MB in total.","A name a built-in plugin already holds cannot be imported (pick another); a user plugin of the same name is confirmed first, and overwriting replaces every one of its files.",],/**@@ -2187,13 +2187,14 @@ export const en: Strings = {/** Sits under the field, and holds the submit back, while the typed name breaks the rule the server applies to the directory a plugin is installed into. */pluginNameInvalid: "Letters, digits, underscores and hyphens only (^[A-Za-z0-9_-]+$).",/** Remote download dialog. */- downloadTitle: "Download a plugin from a URL",- downloadUrlLabel: "Plugin URL",+ downloadTitle: "Download a plugin from a URL or npm",+ downloadUrlLabel: "Plugin URL or npm package name",downloadUrlHint:- "A direct zip link, or a GitHub repository URL (https://github.com/<owner>/<repo>, default branch) or a directory inside one (\u2026/tree/<ref>/<subdir>)",- downloadUrlPlaceholder: "https://github.com/<owner>/<repo> or https://\u2026/plugin.zip",+ "A direct zip/tgz link, a GitHub repository URL (https://github.com/<owner>/<repo>, default branch) or a directory inside one (\u2026/tree/<ref>/<subdir>), or an npm package (@scope/name, @scope/[email protected], npm:@scope/name \u2014 no version means `latest`)",+ downloadUrlPlaceholder:+ "@scope/name, https://github.com/<owner>/<repo> or https://\u2026/plugin.zip",downloadDesc:- "The archive must carry plugin.json; for a GitHub repository or directory URL the shallowest directory containing plugin.json becomes the plugin root.",+ "The archive must carry plugin.json; for a GitHub repository or directory URL the shallowest directory containing plugin.json becomes the plugin root; for an npm package the server fetches the tarball of that version from the registry and checks the checksum it published.",downloadAction: "Download and import",/** "User" badge on a card whose plugin comes from the user plugin directory rather than the build. */userBadge: "User",@@ -2222,9 +2223,15 @@ export const en: Strings = {plugin_builtin:"A built-in plugin cannot be overwritten or deleted (import it under another name).",unsupported_url:- "That URL is not supported: use a direct zip link, or a GitHub repository or directory URL.",+ "That address is not supported: use a direct zip/tgz link, a GitHub repository or directory URL, or an npm package name.",blocked_url: "That URL was refused (an internal address, or one that is not allowed).",download_failed: "The download failed \u2014 check that the URL is reachable.",+ npm_package_not_found: "npm has no such package.",+ npm_version_not_found:+ "npm has no such version; use an exact version or a dist-tag (such as latest).",+ npm_registry_failed: "Could not read npm \u2014 try again in a moment.",+ integrity_failed:+ "The archive that came back does not match the checksum the registry published; the import was refused.",invalid_plugin: "The archive carries no valid plugin.json.",plugin_too_large: "The plugin archive exceeds the server's size limit.",},diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.tsindex 3182e707..792f33f9 100644--- a/packages/web/src/lib/strings.ts+++ b/packages/web/src/lib/strings.ts@@ -2173,15 +2173,15 @@ export const zh = {* The import rules, shown as one numbered block at the foot of BOTH dialogs: they are the* shape a plugin has to arrive in, not the property of one source, and a reader who opened* the wrong dialog should still learn them. Ordered, because the name is decided by a- * precedence the reader has to walk (typed → URL → the archive's own layout), and that order- * is the trap a repository URL sets: it carries the repository's name.+ * precedence the reader has to walk (typed → the source's own name → the archive's own+ * layout), and that order is the trap a repository URL sets: it carries the repository's name.*/importRulesTitle: "插件导入规则",importRules: [- "来源是本地 zip,或一个地址——zip 直链、GitHub 仓库地址(取默认分支)、仓库内目录地址(…/tree/<分支>/<子目录>)。",- "压缩包必须是含 plugin.json 的 zip;插件根取归档里最浅一层含 plugin.json 的目录,同一层出现多个则拒绝。",- "插件名依次取:你填的名字 → 地址自带的名字(目录地址取末段目录名、仓库地址取仓库名、zip 链接取文件名)→ 插件根的目录名;只能用字母、数字、下划线和中划线。所以从仓库地址导入会装成仓库名。",- "上传的 zip 不超过 14 MB,远程归档不超过 32 MB;解包后只统计插件根之下:200 个文件、单文件 5 MB、合计 20 MB。",+ "来源是本地 zip,或一个地址/npm 包——zip 直链、GitHub 仓库地址(取默认分支)、仓库内目录地址(…/tree/<分支>/<子目录>)、npm 包名(@scope/名称、@scope/名称@1.2.3、npm:@scope/名称;不写版本就取 latest)。",+ "压缩包必须是含 plugin.json 的 zip,或 npm 的 tgz(从 registry 取对应版本的 tarball 并校验其校验和);插件根取归档里最浅一层含 plugin.json 的目录,同一层出现多个则拒绝。",+ "插件名依次取:你填的名字 → 来源自带的名字(目录地址取末段目录名、仓库地址取仓库名、压缩包链接取文件名、npm 包取去掉 scope 的包名)→ 插件根的目录名;只能用字母、数字、下划线和中划线。所以从仓库地址导入会装成仓库名。",+ "上传的 zip 不超过 14 MB,远程归档不超过 32 MB,npm 的 tgz 解压后不超过 64 MB;解包后只统计插件根之下:200 个文件、单文件 5 MB、合计 20 MB。","内置插件占用的名字不能导入(换个名字);同名用户插件会先问一次是否覆盖,覆盖即替换其全部文件。",],/**@@ -2229,13 +2229,14 @@ export const zh = {/** Sits under the field, and holds the submit back, while the typed name breaks the rule the server applies to the directory a plugin is installed into. */pluginNameInvalid: "只能用字母、数字、下划线和中划线(^[A-Za-z0-9_-]+$)。",/** Remote download dialog. */- downloadTitle: "远程下载插件",- downloadUrlLabel: "插件地址",+ downloadTitle: "从地址或 npm 下载插件",+ downloadUrlLabel: "插件地址或 npm 包名",downloadUrlHint:- "zip 直链,或 GitHub 仓库地址(https://github.com/<owner>/<repo>,取默认分支)与仓库内目录地址(…/tree/<ref>/<subdir>)",- downloadUrlPlaceholder: "https://github.com/<owner>/<repo> 或 https://…/plugin.zip",+ "zip/tgz 直链,GitHub 仓库地址(https://github.com/<owner>/<repo>,取默认分支)与仓库内目录地址(…/tree/<ref>/<subdir>),或 npm 包(@scope/name、@scope/[email protected]、npm:@scope/name;不写版本则取 latest)",+ downloadUrlPlaceholder:+ "@scope/name、https://github.com/<owner>/<repo> 或 https://…/plugin.zip",downloadDesc:- "压缩包需带有 plugin.json;GitHub 仓库或目录地址会自动选取最浅一层含 plugin.json 的目录作为插件根。",+ "压缩包需带有 plugin.json;GitHub 仓库或目录地址会自动选取最浅一层含 plugin.json 的目录作为插件根;npm 包由服务端向 registry 取该版本的 tarball,并核对它公布的校验和。",downloadAction: "下载并导入",/** "User" badge on a card whose plugin comes from the user plugin directory rather than the build. */userBadge: "用户",@@ -2261,9 +2262,13 @@ export const zh = {importErrors: {plugin_exists: "已存在同名用户插件。",plugin_builtin: "内置插件不能被覆盖或删除(导入同名插件请另起一个名字)。",- unsupported_url: "该地址不受支持:请填 zip 直链,或 GitHub 仓库/目录地址。",+ unsupported_url: "该地址不受支持:请填 zip/tgz 直链、GitHub 仓库/目录地址,或 npm 包名。",blocked_url: "该地址被拒绝(内网或其他不允许的地址)。",download_failed: "下载失败,请确认该地址可以访问。",+ npm_package_not_found: "npm 上没有这个包。",+ npm_version_not_found: "npm 上没有这个版本;请填确切版本号或 dist-tag(如 latest)。",+ npm_registry_failed: "读取 npm 失败,请稍后重试。",+ integrity_failed: "下载到的压缩包与 registry 公布的校验和不一致,已拒绝导入。",invalid_plugin: "压缩包里没有合法的 plugin.json。",plugin_too_large: "插件包超过了服务端的大小上限。",},diff --git a/packages/web/test/plugin-import.test.ts b/packages/web/test/plugin-import.test.tsindex 2e376691..f48b6dfa 100644--- a/packages/web/test/plugin-import.test.ts+++ b/packages/web/test/plugin-import.test.ts@@ -64,6 +64,35 @@ describe("pluginNameFromUrl", () => {expect(pluginNameFromUrl("https://example.com/x.zip?token=abc#frag")).toBe("x");expect(pluginNameFromUrl("https://github.com/acme/my-plugin/")).toBe("my-plugin");});++ it("names an npm package without its scope, whichever way the package is written", () => {+ // The server installs under the package's own name — the scope is the publisher, and the+ // package's directory (which is what carries plugin.json) is `package/` in every tarball.+ expect(pluginNameFromUrl("@acme/data-analysis")).toBe("data-analysis");+ expect(pluginNameFromUrl("@acme/[email protected]")).toBe("data-analysis");+ expect(pluginNameFromUrl("npm:@acme/data-analysis")).toBe("data-analysis");+ expect(pluginNameFromUrl("data-analysis")).toBe("data-analysis");+ expect(pluginNameFromUrl("npm:[email protected]")).toBe("use-firecrawl");+ expect(pluginNameFromUrl("https://www.npmjs.com/package/@acme/data-analysis")).toBe(+ "data-analysis",+ );+ expect(pluginNameFromUrl("https://www.npmjs.com/package/data-analysis/v/0.2.13")).toBe(+ "data-analysis",+ );+ });++ it("keeps a repository and a package apart, and leaves the shape of an archive link alone", () => {+ // The name rule is a precedence the confirmation has to reproduce: a GitHub URL is still a+ // repository's name, an npmjs.com page that is not a package page names nothing, and another+ // host's `/package/` path is that host's business.+ expect(pluginNameFromUrl("https://github.com/acme/my-plugin")).toBe("my-plugin");+ expect(pluginNameFromUrl("https://www.npmjs.com/settings/acme/tokens")).toBe("tokens");+ expect(pluginNameFromUrl("https://example.com/package/thing.zip")).toBe("thing");+ // A tarball link is named like a zip: the file stem, both suffixes dropped.+ expect(pluginNameFromUrl("https://example.com/releases/use-firecrawl-0.2.13.tgz")).toBe(+ "use-firecrawl-0.2.13",+ );+ });});describe("pluginNameInvalid", () => {