A local-first multi-agent app development platform, built on PenguinHarness
/**
* The plugin directory routes — local upload, remote download, the directory listing, export
* and delete — and the two pure readers behind them (the archive parser and the URL reader).
*
* Two things are the point here. First, what an import must refuse: an archive with no plugin
* in it, one carrying two, an entry path that would land outside the plugin directory, and a
* name the build already ships (which the loader would go on serving). Second, who may do it:
* the user plugin directory is installation-level — every Project reads it and its hook scripts
* run with the server's rights — so these routes are the admin's, like installing to a machine,
* not a Project owner's.
*
* The tests pin PENGUIN_HOME at the app's temp root, because that is the production invariant
* being relied on: the server's data root and the library's plugin root are one directory.
*/
import path from "node:path";
import { strToU8, zipSync } from "fflate";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type {
PluginDirectoryResponse,
PluginImportResponse,
PluginLibraryResponse,
} from "../src/api/types.js";
import { parsePluginArchive } from "../src/http/routes/plugins.js";
import { isBlockedHost, normalizePluginUrl } from "../src/services/plugin-download.js";
import { apiClient, createTestApp, loginAdmin, provisionUser } 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 that arrived from outside the build.",
short_description: "Imported plugin.",
version,
category: "software-development",
},
null,
2,
)}\n`,
"icon.svg": '<svg xmlns="http://www.w3.org/2000/svg"></svg>\n',
"skills/imported-skill/SKILL.md":
"---\nname: imported-skill\ndescription: A skill the plugin ships.\n---\n\nBody.\n",
};
}
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;
describe("parsePluginArchive", () => {
it("takes the archive's own directory as the plugin root and its name", () => {
const inner: Record<string, string> = {};
for (const [rel, text] of Object.entries(pluginFiles())) inner[`imported/${rel}`] = text;
const parsed = parsePluginArchive(zip(inner));
expect(parsed.name).toBe("imported");
expect(Object.keys(parsed.files).sort()).toEqual([
"icon.svg",
"plugin.json",
"skills/imported-skill/SKILL.md",
]);
});
it("needs a name when plugin.json sits at the archive root, and takes the one it is given", () => {
expect(() => parsePluginArchive(zip(pluginFiles()))).toThrow(/name is required/);
const parsed = parsePluginArchive(zip(pluginFiles()), { name: "named-by-request" });
expect(parsed.name).toBe("named-by-request");
});
it("locates the plugin under the subdirectory a tree URL names, ignoring the host's wrapper directory", () => {
// The shape a GitHub tree archive has: everything wrapped in `<repo>-<ref>/`, with the
// plugin (and other plugins, and everything else) below it.
const inner: Record<string, string> = {};
for (const [rel, text] of Object.entries(pluginFiles())) {
inner[`penguin-harness-local/plugins/imported/${rel}`] = text;
}
for (const [rel, text] of Object.entries(pluginFiles())) {
inner[`penguin-harness-local/plugins/other/${rel}`] = text;
}
const parsed = parsePluginArchive(zip(inner), { subdir: "plugins/imported" });
expect(parsed.name).toBe("imported");
expect(Object.keys(parsed.files).sort()).toEqual([
"icon.svg",
"plugin.json",
"skills/imported-skill/SKILL.md",
]);
});
it("reads one plugin out of a repository archive, without the repository's own limits applying", () => {
// A checkout is not a plugin: 400 unrelated files around a 3-file plugin must neither fail
// the 200-file cap nor be inflated — the caps bound the plugin that comes out (`wanted`).
const inner: Record<string, string> = {};
for (const [rel, text] of Object.entries(pluginFiles())) {
inner[`penguin-harness-main/plugins/wanted/${rel}`] = text;
}
for (let i = 0; i < 400; i += 1) {
inner[`penguin-harness-main/docs/page-${i}.md`] = `# page ${i}\n`;
}
const parsed = parsePluginArchive(zip(inner), { subdir: "plugins/wanted" });
expect(parsed.name).toBe("wanted");
expect(Object.keys(parsed.files).sort()).toEqual([
"icon.svg",
"plugin.json",
"skills/imported-skill/SKILL.md",
]);
// The same archive read as a whole still refuses: two directories carry plugin.json only
// in the plugin case above, so here it is the plugin's own file count that has to fail.
const crowded: Record<string, string> = {};
for (const [rel, text] of Object.entries(pluginFiles())) crowded[`crowded/${rel}`] = text;
for (let i = 0; i < 200; i += 1) {
crowded[`crowded/skills/extra-${i}/SKILL.md`] =
`---\nname: extra-${i}\ndescription: Filler.\n---\n`;
}
expect(() => parsePluginArchive(zip(crowded))).toThrow(/200-file limit/);
});
it("refuses an archive that carries two plugins side by side", () => {
const inner: Record<string, string> = {};
for (const [rel, text] of Object.entries(pluginFiles())) {
inner[`one/${rel}`] = text;
inner[`two/${rel}`] = text;
}
expect(() => parsePluginArchive(zip(inner))).toThrow(/more than one plugin/);
});
it("refuses an archive with no plugin, an empty archive, and a zip-slip entry path", () => {
expect(() => parsePluginArchive(zip({ "readme.md": "nothing here" }))).toThrow(
/no plugin.json/,
);
expect(() => parsePluginArchive(zip({}))).toThrow(/no files/);
const escaping = { ...pluginFiles(), "../outside.txt": "not inside" };
expect(() => parsePluginArchive(zip({ ...escaping }))).toThrow(/Invalid zip entry path/);
});
it("refuses bytes that are not a zip at all", () => {
expect(() => parsePluginArchive(Buffer.from("not a zip"))).toThrow(/not a valid zip/);
});
it("refuses a plugin name the loader would never accept", () => {
const inner: Record<string, string> = {};
for (const [rel, text] of Object.entries(pluginFiles())) inner[`../evil/${rel}`] = text;
// The entry path is checked first (zip-slip) — a name check is what the request's own
// `name` field goes through.
expect(() => parsePluginArchive(zip(pluginFiles()), { name: "../evil" })).toThrow(
/Not a valid plugin name/,
);
});
});
describe("normalizePluginUrl", () => {
it("turns a GitHub repository page into its default-branch archive", () => {
expect(normalizePluginUrl("https://github.com/Prism-Shadow/penguin-harness")).toEqual({
fetchUrl: "https://github.com/Prism-Shadow/penguin-harness/archive/HEAD.zip",
subdir: "",
name: "penguin-harness",
});
});
it("turns a GitHub tree URL into that ref's archive plus the subdirectory to look in", () => {
expect(normalizePluginUrl("https://github.com/o/r/tree/main/plugins/humanizer")).toEqual({
fetchUrl: "https://github.com/o/r/archive/main.zip",
subdir: "plugins/humanizer",
name: "humanizer",
});
expect(normalizePluginUrl("https://github.com/o/r/tree/v1.2.3")).toEqual({
fetchUrl: "https://github.com/o/r/archive/v1.2.3.zip",
subdir: "",
name: "r",
});
});
it("passes a plain download link through, suggesting a name only when it is a zip", () => {
expect(normalizePluginUrl("https://example.com/plugins/thing.zip")).toEqual({
fetchUrl: "https://example.com/plugins/thing.zip",
subdir: "",
name: "thing",
});
expect(normalizePluginUrl("https://example.com/download?id=7")).toEqual({
fetchUrl: "https://example.com/download?id=7",
subdir: "",
});
});
it("refuses a protocol or a host that is the server's own network", () => {
expect(() => normalizePluginUrl("ftp://example.com/thing.zip")).toThrow(/http\(s\)/);
expect(() => normalizePluginUrl("not a url")).toThrow(/absolute http\(s\) URL/);
for (const url of [
"http://localhost:8080/thing.zip",
"http://127.0.0.1/thing.zip",
"http://10.0.0.5/thing.zip",
"http://192.168.1.7/thing.zip",
"http://169.254.169.254/latest/meta-data",
"http://[::1]/thing.zip",
"http://box.internal/thing.zip",
]) {
expect(() => normalizePluginUrl(url), url).toThrow(/local or private host/);
}
// The literal-host guard, stated as a table: public addresses and names pass.
expect(isBlockedHost("github.com")).toBe(false);
expect(isBlockedHost("8.8.8.8")).toBe(false);
});
});
describe("the plugin directory routes", () => {
let t: TestApp;
let admin: ReturnType<typeof apiClient>;
let member: 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);
member = apiClient(t.app, (await provisionUser(t.app, "plain_member")).cookie);
});
afterEach(async () => {
vi.unstubAllGlobals();
if (prevHome === undefined) delete process.env.PENGUIN_HOME;
else process.env.PENGUIN_HOME = prevHome;
await t.cleanup();
});
const upload = (files: Record<string, string>, body: Record<string, unknown> = {}) =>
admin.post("/api/plugins/upload", {
dataBase64: zip(files).toString("base64"),
...body,
});
const libraryNames = async (client = admin): Promise<string[]> => {
const res = await client.get("/api/plugins");
const body = (await res.json()) as PluginLibraryResponse;
return body.groups.flatMap((g) => g.plugins.map((p) => p.name)).sort();
};
it("installs an uploaded plugin into the library, lists the directory and deletes it again", async () => {
const res = await upload(pluginFiles(), { name: "imported" });
expect(res.status).toBe(201);
const body = (await res.json()) as PluginImportResponse;
expect(body.plugin).toMatchObject({
name: "imported",
source: "user",
version: "2026.09.01.1",
});
expect(body.path).toBe(path.join(t.root, "plugins", "imported"));
// On disk under the data root, and in the library every other surface reads.
expect(await libraryNames()).toContain("imported");
const dir = (await (
await admin.get("/api/plugins/directory")
).json()) as PluginDirectoryResponse;
expect(dir).toEqual({ path: path.join(t.root, "plugins"), plugins: ["imported"] });
const files = (await (await admin.get("/api/plugins/imported/files")).json()) as {
files: Record<string, string>;
};
expect(Object.keys(files.files)).toContain("skills/imported-skill/SKILL.md");
expect((await admin.delete("/api/plugins/imported")).status).toBe(204);
expect(await libraryNames()).not.toContain("imported");
// Gone from disk too — the delete is the directory, not a tombstone.
expect((await admin.get("/api/plugins/imported/files")).status).toBe(404);
expect((await admin.delete("/api/plugins/imported")).status).toBe(404);
});
it("answers one code for an archive past the cap, uploaded or downloaded alike", async () => {
const res = await admin.post("/api/plugins/upload", {
dataBase64: Buffer.alloc(15 * 1024 * 1024).toString("base64"),
name: "oversize",
});
expect(res.status).toBe(413);
expect(await readErrorCode(res)).toBe("plugin_too_large");
// Nothing was written on the way to the refusal.
const dir = (await (
await admin.get("/api/plugins/directory")
).json()) as PluginDirectoryResponse;
expect(dir.plugins).toEqual([]);
});
it("keeps the import to admins", async () => {
const res = await upload(pluginFiles(), { name: "imported" });
expect(res.status).toBe(201);
expect(
(
await member.post("/api/plugins/upload", {
dataBase64: zip(pluginFiles()).toString("base64"),
name: "by-member",
})
).status,
).toBe(403);
expect((await member.delete("/api/plugins/imported")).status).toBe(403);
// Reading stays open: the library listing and the directory line are not an admin's screen.
expect((await member.get("/api/plugins")).status).toBe(200);
expect((await member.get("/api/plugins/directory")).status).toBe(200);
});
it("refuses a name the build already ships, and asks before overwriting a user plugin", async () => {
const builtin = await upload(pluginFiles(), { name: "goal" });
expect(builtin.status).toBe(409);
expect(await readErrorCode(builtin)).toBe("plugin_builtin");
expect((await upload(pluginFiles(), { name: "imported" })).status).toBe(201);
const again = await upload(pluginFiles("2026.09.02.1"), { name: "imported" });
expect(again.status).toBe(409);
expect(await readErrorCode(again)).toBe("plugin_exists");
const overwritten = await upload(pluginFiles("2026.09.02.1"), {
name: "imported",
overwrite: true,
});
expect(overwritten.status).toBe(201);
expect(((await overwritten.json()) as PluginImportResponse).plugin.version).toBe(
"2026.09.02.1",
);
});
it("exports a plugin as an archive that imports back", async () => {
await upload(pluginFiles(), { name: "imported" });
const res = await admin.get("/api/plugins/imported/archive");
expect(res.status).toBe(200);
expect(res.headers.get("content-type")).toBe("application/zip");
expect(res.headers.get("content-disposition")).toContain("imported-v2026.09.01.1.zip");
const archive = Buffer.from(await res.arrayBuffer());
// The archive carries the plugin as the library holds it, so it re-imports under a new name.
const parsed = parsePluginArchive(archive, { name: "imported-again" });
expect(Object.keys(parsed.files).sort()).toEqual([
"icon.svg",
"plugin.json",
"skills/imported-skill/SKILL.md",
]);
const again = await admin.post("/api/plugins/upload", {
dataBase64: archive.toString("base64"),
name: "imported-again",
});
expect(again.status).toBe(201);
expect(await libraryNames()).toEqual(expect.arrayContaining(["imported", "imported-again"]));
});
it("downloads an archive from a URL, and refuses one the host will not serve", async () => {
const calls: string[] = [];
// What that archive really looks like: the repository wrapped in `<repo>-<ref>/`.
const fromGitHub: Record<string, string> = {};
for (const [rel, text] of Object.entries(pluginFiles())) {
fromGitHub[`penguin-harness-main/plugins/from-github/${rel}`] = text;
}
vi.stubGlobal("fetch", async (input: Parameters<typeof fetch>[0]) => {
calls.push(String(input));
return new Response(new Uint8Array(zip(fromGitHub)), { status: 200 });
});
const res = await admin.post("/api/plugins/download", {
url: "https://github.com/Prism-Shadow/penguin-harness/tree/main/plugins/from-github",
});
expect(res.status).toBe(201);
// The GitHub page became the archive it stands for, and the tree's directory named the plugin.
expect(calls).toEqual(["https://github.com/Prism-Shadow/penguin-harness/archive/main.zip"]);
expect(((await res.json()) as PluginImportResponse).plugin.name).toBe("from-github");
vi.stubGlobal("fetch", async () => new Response("nope", { status: 404 }));
const failed = await admin.post("/api/plugins/download", { url: "https://example.com/x.zip" });
expect(failed.status).toBe(400);
expect(await readErrorCode(failed)).toBe("download_failed");
vi.stubGlobal("fetch", async () => {
throw new Error("getaddrinfo ENOTFOUND");
});
const unreachable = await admin.post("/api/plugins/download", {
url: "https://example.com/x.zip",
});
expect(unreachable.status).toBe(400);
expect(await readErrorCode(unreachable)).toBe("download_failed");
// Past the cap, refused while streaming rather than after buffering it whole.
vi.stubGlobal(
"fetch",
async () =>
new Response("x", { status: 200, headers: { "content-length": String(64 * 1024 * 1024) } }),
);
const tooBig = await admin.post("/api/plugins/download", {
url: "https://example.com/big.zip",
});
expect(tooBig.status).toBe(413);
expect(await readErrorCode(tooBig)).toBe("plugin_too_large");
// What is fetched whole is often a repository, so the download cap is larger than the upload
// one: 20MB is past the base64 body limit and inside this one, and what the route says about
// it is "not a zip" — the body is a zip's problem, not its size.
vi.stubGlobal(
"fetch",
async () => new Response(Buffer.alloc(20 * 1024 * 1024, 0x7a), { status: 200 }),
);
const repositorySized = await admin.post("/api/plugins/download", {
url: "https://example.com/repo.zip",
});
expect(repositorySized.status).toBe(400);
expect(await readErrorCode(repositorySized)).toBe("bad_request");
});
it("refuses a URL aimed at the server's own network before fetching anything", async () => {
const fetchSpy = vi.fn();
vi.stubGlobal("fetch", fetchSpy);
const res = await admin.post("/api/plugins/download", { url: "http://127.0.0.1:7364/x.zip" });
expect(res.status).toBe(400);
expect(await readErrorCode(res)).toBe("blocked_url");
expect(fetchSpy).not.toHaveBeenCalled();
});
});