Skip to content

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.md
index 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.ts
index 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.ts
index 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 asked
diff --git a/packages/server/src/services/plugin-download.ts b/packages/server/src/services/plugin-download.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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", () => {