Skip to content

The open-source app everyone uses to manage agents at work

Harden `POST /plugins/install`: canonicalize `localPath` for all instances; bundled-only floor for managed instances (#10067)

Devin Foley0ef3b320c70d
diff --git a/server/src/__tests__/plugin-install-guard.test.ts b/server/src/__tests__/plugin-install-guard.test.ts
new file mode 100644
index 0000000000..db14e6b3d6
--- /dev/null
+++ b/server/src/__tests__/plugin-install-guard.test.ts
@@ -0,0 +1,161 @@
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+ canonicalizeLocalPluginPath,
+ isCloudManagedInstance,
+ isWithinBundledPluginRoot,
+} from "../services/plugin-install-guard.js";
+
+describe("isCloudManagedInstance", () => {
+ it("returns false when PAPERCLIP_MANAGED_CONFIG is absent", () => {
+ expect(isCloudManagedInstance({})).toBe(false);
+ expect(isCloudManagedInstance({ OTHER_VAR: "x" })).toBe(false);
+ });
+
+ it("returns true when PAPERCLIP_MANAGED_CONFIG is set to a cloud document", () => {
+ const doc = JSON.stringify({ v: 1, mode: "cloud", catalogVersion: "1", features: {}, plugins: { autoInstall: [] } });
+ expect(isCloudManagedInstance({ PAPERCLIP_MANAGED_CONFIG: doc })).toBe(true);
+ });
+
+ it("fails closed: blank or corrupted documents still count as cloud-managed", () => {
+ expect(isCloudManagedInstance({ PAPERCLIP_MANAGED_CONFIG: "" })).toBe(true);
+ expect(isCloudManagedInstance({ PAPERCLIP_MANAGED_CONFIG: " " })).toBe(true);
+ expect(isCloudManagedInstance({ PAPERCLIP_MANAGED_CONFIG: "{not json" })).toBe(true);
+ expect(isCloudManagedInstance({ PAPERCLIP_MANAGED_CONFIG: JSON.stringify({ mode: "self-hosted" }) })).toBe(true);
+ });
+});
+
+describe("canonicalizeLocalPluginPath", () => {
+ const cleanupPaths = new Set<string>();
+
+ afterEach(async () => {
+ for (const cleanupPath of cleanupPaths) {
+ await rm(cleanupPath, { recursive: true, force: true });
+ }
+ cleanupPaths.clear();
+ });
+
+ async function makeTempDir(prefix: string): Promise<string> {
+ const dir = await mkdtemp(path.join(os.tmpdir(), prefix));
+ cleanupPaths.add(dir);
+ return dir;
+ }
+
+ it("accepts an existing absolute directory path", async () => {
+ const dir = await makeTempDir("guard-abs-");
+ const result = await canonicalizeLocalPluginPath(dir);
+ expect(result).toEqual({ ok: true, canonicalPath: await realCanonical(dir) });
+ });
+
+ it("collapses traversal segments to the canonical path", async () => {
+ const dir = await makeTempDir("guard-traversal-");
+ const nested = path.join(dir, "a", "b");
+ await mkdir(nested, { recursive: true });
+ const traversal = path.join(dir, "a", "..", "a", "b", "..", "b");
+ const result = await canonicalizeLocalPluginPath(traversal);
+ expect(result).toEqual({ ok: true, canonicalPath: await realCanonical(nested) });
+ });
+
+ it("resolves symlinks to their target", async () => {
+ const dir = await makeTempDir("guard-symlink-");
+ const target = path.join(dir, "target");
+ await mkdir(target, { recursive: true });
+ const link = path.join(dir, "link");
+ await symlink(target, link, "dir");
+ const result = await canonicalizeLocalPluginPath(link);
+ expect(result).toEqual({ ok: true, canonicalPath: await realCanonical(target) });
+ });
+
+ it("rejects paths containing a null byte", async () => {
+ const result = await canonicalizeLocalPluginPath("/tmp/foo\0bar");
+ expect(result.ok).toBe(false);
+ if (!result.ok) expect(result.reason).toContain("null byte");
+ });
+
+ it("rejects nonexistent paths", async () => {
+ const dir = await makeTempDir("guard-missing-");
+ const result = await canonicalizeLocalPluginPath(path.join(dir, "does-not-exist"));
+ expect(result.ok).toBe(false);
+ if (!result.ok) expect(result.reason).toContain("does not exist");
+ });
+
+ it("rejects paths that resolve to a file rather than a directory", async () => {
+ const dir = await makeTempDir("guard-file-");
+ const file = path.join(dir, "plugin.txt");
+ await writeFile(file, "not a directory", "utf8");
+ const result = await canonicalizeLocalPluginPath(file);
+ expect(result.ok).toBe(false);
+ if (!result.ok) expect(result.reason).toContain("not a directory");
+ });
+});
+
+describe("isWithinBundledPluginRoot", () => {
+ const cleanupPaths = new Set<string>();
+
+ afterEach(async () => {
+ for (const cleanupPath of cleanupPaths) {
+ await rm(cleanupPath, { recursive: true, force: true });
+ }
+ cleanupPaths.clear();
+ });
+
+ async function makeCatalogFixture(): Promise<{ root: string; inside: string; outside: string }> {
+ const base = await mkdtemp(path.join(os.tmpdir(), "guard-catalog-"));
+ cleanupPaths.add(base);
+ const root = path.join(base, "packages", "plugins");
+ const inside = path.join(root, "plugin-good");
+ const outside = path.join(base, "elsewhere");
+ await mkdir(inside, { recursive: true });
+ await mkdir(outside, { recursive: true });
+ return { root, inside, outside };
+ }
+
+ it("accepts a directory inside the catalog root", async () => {
+ const { root, inside } = await makeCatalogFixture();
+ expect(await isWithinBundledPluginRoot(await realCanonical(inside), root)).toBe(true);
+ });
+
+ it("rejects a directory outside the catalog root", async () => {
+ const { root, outside } = await makeCatalogFixture();
+ expect(await isWithinBundledPluginRoot(await realCanonical(outside), root)).toBe(false);
+ });
+
+ it("rejects the catalog root itself", async () => {
+ const { root } = await makeCatalogFixture();
+ expect(await isWithinBundledPluginRoot(await realCanonical(root), root)).toBe(false);
+ });
+
+ it("rejects a sibling directory whose name shares the root as a string prefix", async () => {
+ const { root } = await makeCatalogFixture();
+ const sibling = `${root}-evil`;
+ await mkdir(sibling, { recursive: true });
+ expect(await isWithinBundledPluginRoot(await realCanonical(sibling), root)).toBe(false);
+ });
+
+ it("rejects a symlink target that escapes the catalog root once canonicalized", async () => {
+ const { root, outside } = await makeCatalogFixture();
+ const link = path.join(root, "sneaky");
+ await symlink(outside, link, "dir");
+ // The guard contract is that callers canonicalize first; the symlink's
+ // real path lands outside the root and must be rejected.
+ const canonical = await canonicalizeLocalPluginPath(link);
+ expect(canonical.ok).toBe(true);
+ if (canonical.ok) {
+ expect(await isWithinBundledPluginRoot(canonical.canonicalPath, root)).toBe(false);
+ }
+ });
+
+ it("fails closed when the catalog root does not exist", async () => {
+ const { inside } = await makeCatalogFixture();
+ expect(await isWithinBundledPluginRoot(await realCanonical(inside), "/nonexistent/catalog/root")).toBe(false);
+ });
+});
+
+/** realpath through the same lens the guard uses (macOS /tmp is a symlink). */
+async function realCanonical(target: string): Promise<string> {
+ const result = await canonicalizeLocalPluginPath(target);
+ if (!result.ok) throw new Error(`fixture path did not canonicalize: ${result.reason}`);
+ return result.canonicalPath;
+}
diff --git a/server/src/__tests__/plugin-install-route-security.test.ts b/server/src/__tests__/plugin-install-route-security.test.ts
new file mode 100644
index 0000000000..ff8ad17be4
--- /dev/null
+++ b/server/src/__tests__/plugin-install-route-security.test.ts
@@ -0,0 +1,386 @@
+/**
+ * Route-level coverage for the plugin install security floor:
+ *
+ * - Cloud-managed instances (PAPERCLIP_MANAGED_CONFIG present) may only
+ * install plugins whose source canonicalizes into the bundled plugin
+ * catalog root; npm installs and arbitrary local paths are rejected.
+ * - Every instance canonicalizes and validates `localPath` (traversal,
+ * symlink, and absolute-path handling) before the loader runs.
+ * - Self-hosted non-localPath install validation is unchanged.
+ */
+import express from "express";
+import { randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, realpath, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import request from "supertest";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { createDb, plugins } from "@paperclipai/db";
+import { pluginLoader, REPO_ROOT } from "../services/plugin-loader.js";
+import {
+ getEmbeddedPostgresTestSupport,
+ startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+
+const mockLifecycle = vi.hoisted(() => ({
+ load: vi.fn(),
+ upgrade: vi.fn(),
+ unload: vi.fn(),
+ enable: vi.fn(),
+ disable: vi.fn(),
+}));
+
+vi.mock("../services/plugin-lifecycle.js", () => ({
+ pluginLifecycleManager: () => mockLifecycle,
+}));
+
+vi.mock("../services/activity-log.js", () => ({
+ logActivity: vi.fn(),
+}));
+
+vi.mock("../services/live-events.js", () => ({
+ publishGlobalLiveEvent: vi.fn(),
+}));
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe.sequential : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+ console.warn(
+ `Skipping plugin install route security tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+ );
+}
+
+const CLOUD_MANAGED_CONFIG = JSON.stringify({
+ v: 1,
+ mode: "cloud",
+ catalogVersion: "2026.720.0",
+ features: {},
+ plugins: { autoInstall: [] },
+});
+
+const repoPluginRoot = path.join(REPO_ROOT, "packages", "plugins");
+
+type FixturePlugin = {
+ packageName: string;
+ pluginKey: string;
+ packageRoot: string;
+};
+
+/**
+ * Create a valid, already-built plugin package (dist written directly, so no
+ * pnpm auto-build runs during install) at an arbitrary directory.
+ */
+async function createBuiltPluginFixture(parentDir: string, nameSuffix: string): Promise<FixturePlugin> {
+ const slug = `plugin-install-guard-${nameSuffix}-${randomUUID().slice(0, 8)}`;
+ const packageName = `@paperclipai/${slug}`;
+ const pluginKey = `paperclip.${slug.replace(/^plugin-/, "").replace(/-/g, "_")}`;
+ const packageRoot = path.join(parentDir, slug);
+ const distDir = path.join(packageRoot, "dist");
+
+ await mkdir(distDir, { recursive: true });
+ await writeFile(
+ path.join(packageRoot, "package.json"),
+ JSON.stringify({
+ name: packageName,
+ version: "0.1.0",
+ private: true,
+ type: "module",
+ paperclipPlugin: {
+ manifest: "./dist/manifest.js",
+ worker: "./dist/worker.js",
+ },
+ }, null, 2),
+ "utf8",
+ );
+
+ const manifest = {
+ id: pluginKey,
+ apiVersion: 1,
+ version: "0.1.0",
+ displayName: "Install Guard Fixture",
+ description: "Plugin fixture for install-route security floor coverage.",
+ author: "Paperclip",
+ categories: ["automation"],
+ capabilities: ["companies.read"],
+ entrypoints: {
+ worker: "./dist/worker.js",
+ },
+ };
+ await writeFile(
+ path.join(distDir, "manifest.js"),
+ `export default ${JSON.stringify(manifest, null, 2)};\n`,
+ "utf8",
+ );
+ await writeFile(path.join(distDir, "worker.js"), "export {};\n", "utf8");
+
+ return { packageName, pluginKey, packageRoot };
+}
+
+async function createInstallApp(db: ReturnType<typeof createDb>) {
+ const [{ pluginRoutes }, { errorHandler }] = await Promise.all([
+ import("../routes/plugins.js"),
+ import("../middleware/index.js"),
+ ]);
+
+ const loader = pluginLoader(db, {
+ enableLocalFilesystem: false,
+ enableNpmDiscovery: false,
+ });
+
+ const app = express();
+ app.use(express.json());
+ app.use((req, _res, next) => {
+ req.actor = {
+ type: "board",
+ userId: "admin-1",
+ source: "session",
+ isInstanceAdmin: true,
+ companyIds: [],
+ } as typeof req.actor;
+ next();
+ });
+ app.use("/api", pluginRoutes(db as never, loader as never, {} as never, undefined, {} as never, {} as never));
+ app.use(errorHandler);
+ return app;
+}
+
+describeEmbeddedPostgres("plugin install route security floor", () => {
+ let db!: ReturnType<typeof createDb>;
+ let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+ const cleanupPaths = new Set<string>();
+ const originalManagedConfig = process.env["PAPERCLIP_MANAGED_CONFIG"];
+
+ beforeAll(async () => {
+ tempDb = await startEmbeddedPostgresTestDatabase("paperclip-plugin-install-guard-");
+ db = createDb(tempDb.connectionString);
+ }, 20_000);
+
+ afterEach(async () => {
+ vi.clearAllMocks();
+ await db.delete(plugins);
+ for (const cleanupPath of cleanupPaths) {
+ await rm(cleanupPath, { recursive: true, force: true });
+ }
+ cleanupPaths.clear();
+ if (originalManagedConfig === undefined) {
+ delete process.env["PAPERCLIP_MANAGED_CONFIG"];
+ } else {
+ process.env["PAPERCLIP_MANAGED_CONFIG"] = originalManagedConfig;
+ }
+ });
+
+ afterAll(async () => {
+ await tempDb?.cleanup();
+ }, 30_000);
+
+ describe("cloud-managed instances", () => {
+ it("rejects npm installs outright", async () => {
+ process.env["PAPERCLIP_MANAGED_CONFIG"] = CLOUD_MANAGED_CONFIG;
+ const app = await createInstallApp(db);
+
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: "paperclip-plugin-anything", version: "1.0.0" });
+
+ expect(res.status).toBe(403);
+ expect(res.body.error).toContain("npm installs are disabled on cloud-managed instances");
+ expect(mockLifecycle.load).not.toHaveBeenCalled();
+ });
+
+ it("rejects npm installs even when the managed config document is corrupted", async () => {
+ // The fail-closed startup parser refuses to boot a managed instance
+ // with a corrupted document, so boot with a valid one and corrupt it
+ // afterwards: the install floor must still hold because it keys off
+ // the variable's presence at request time, never its parsed content.
+ process.env["PAPERCLIP_MANAGED_CONFIG"] = CLOUD_MANAGED_CONFIG;
+ const app = await createInstallApp(db);
+ process.env["PAPERCLIP_MANAGED_CONFIG"] = "{definitely not json";
+
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: "paperclip-plugin-anything" });
+
+ expect(res.status).toBe(403);
+ expect(mockLifecycle.load).not.toHaveBeenCalled();
+ });
+
+ it("rejects localPath installs from outside the bundled catalog root", async () => {
+ process.env["PAPERCLIP_MANAGED_CONFIG"] = CLOUD_MANAGED_CONFIG;
+ const outsideDir = await mkdtemp(path.join(os.tmpdir(), "guard-outside-"));
+ cleanupPaths.add(outsideDir);
+ const fixture = await createBuiltPluginFixture(outsideDir, "outside");
+ const app = await createInstallApp(db);
+
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: fixture.packageRoot, isLocalPath: true });
+
+ expect(res.status).toBe(403);
+ expect(res.body.error).toContain("bundled plugin catalog");
+ expect(mockLifecycle.load).not.toHaveBeenCalled();
+ });
+
+ it("rejects localPath traversal that escapes the bundled catalog root", async () => {
+ process.env["PAPERCLIP_MANAGED_CONFIG"] = CLOUD_MANAGED_CONFIG;
+ const app = await createInstallApp(db);
+
+ // Starts under packages/plugins but canonicalizes to the repo's server
+ // directory — a real, readable directory outside the catalog.
+ const traversalPath = path.join(repoPluginRoot, "..", "..", "server");
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: traversalPath, isLocalPath: true });
+
+ expect(res.status).toBe(403);
+ expect(res.body.error).toContain("bundled plugin catalog");
+ expect(mockLifecycle.load).not.toHaveBeenCalled();
+ });
+
+ it("rejects a symlink inside the catalog root that points outside it", async () => {
+ process.env["PAPERCLIP_MANAGED_CONFIG"] = CLOUD_MANAGED_CONFIG;
+ const outsideDir = await mkdtemp(path.join(os.tmpdir(), "guard-symlink-target-"));
+ cleanupPaths.add(outsideDir);
+ const fixture = await createBuiltPluginFixture(outsideDir, "symlink-target");
+
+ const linkPath = path.join(repoPluginRoot, `guard-sneaky-link-${randomUUID().slice(0, 8)}`);
+ cleanupPaths.add(linkPath);
+ await symlink(fixture.packageRoot, linkPath, "dir");
+ const app = await createInstallApp(db);
+
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: linkPath, isLocalPath: true });
+
+ expect(res.status).toBe(403);
+ expect(res.body.error).toContain("bundled plugin catalog");
+ expect(mockLifecycle.load).not.toHaveBeenCalled();
+ });
+
+ it("allows installing a plugin from inside the bundled catalog root", async () => {
+ process.env["PAPERCLIP_MANAGED_CONFIG"] = CLOUD_MANAGED_CONFIG;
+ const fixture = await createBuiltPluginFixture(repoPluginRoot, "bundled");
+ cleanupPaths.add(fixture.packageRoot);
+ const app = await createInstallApp(db);
+
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: fixture.packageRoot, isLocalPath: true });
+
+ expect(res.status).toBe(200);
+ expect(res.body.packageName).toBe(fixture.packageName);
+ expect(res.body.pluginKey).toBe(fixture.pluginKey);
+ expect(mockLifecycle.load).toHaveBeenCalledTimes(1);
+ }, 30_000);
+ });
+
+ describe("all instances: localPath canonicalization", () => {
+ it("rejects a nonexistent localPath with a validation error", async () => {
+ const app = await createInstallApp(db);
+
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: "/nonexistent/plugin/dir", isLocalPath: true });
+
+ expect(res.status).toBe(400);
+ expect(res.body.error).toContain("Invalid localPath");
+ expect(res.body.error).toContain("does not exist");
+ expect(mockLifecycle.load).not.toHaveBeenCalled();
+ });
+
+ it("rejects a localPath containing a null byte", async () => {
+ const app = await createInstallApp(db);
+
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: "/tmp/foo\u0000bar", isLocalPath: true });
+
+ expect(res.status).toBe(400);
+ expect(res.body.error).toContain("Invalid localPath");
+ expect(res.body.error).toContain("null byte");
+ expect(mockLifecycle.load).not.toHaveBeenCalled();
+ });
+
+ it("rejects a localPath that resolves to a file", async () => {
+ const outsideDir = await mkdtemp(path.join(os.tmpdir(), "guard-file-"));
+ cleanupPaths.add(outsideDir);
+ const filePath = path.join(outsideDir, "plugin.tgz");
+ await writeFile(filePath, "not a directory", "utf8");
+ const app = await createInstallApp(db);
+
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: filePath, isLocalPath: true });
+
+ expect(res.status).toBe(400);
+ expect(res.body.error).toContain("Invalid localPath");
+ expect(res.body.error).toContain("not a directory");
+ expect(mockLifecycle.load).not.toHaveBeenCalled();
+ });
+
+ it("canonicalizes traversal segments before installing (self-hosted)", async () => {
+ const outsideDir = await mkdtemp(path.join(os.tmpdir(), "guard-traversal-"));
+ cleanupPaths.add(outsideDir);
+ const fixture = await createBuiltPluginFixture(outsideDir, "traversal");
+ const slug = path.basename(fixture.packageRoot);
+ const traversalPath = path.join(outsideDir, "..", path.basename(outsideDir), ".", slug);
+ const app = await createInstallApp(db);
+
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: traversalPath, isLocalPath: true });
+
+ expect(res.status).toBe(200);
+ expect(res.body.packageName).toBe(fixture.packageName);
+ expect(res.body.packagePath).toBe(await realpath(fixture.packageRoot));
+ expect(mockLifecycle.load).toHaveBeenCalledTimes(1);
+ }, 30_000);
+
+ it("resolves symlinked localPath installs to the real target (self-hosted)", async () => {
+ const outsideDir = await mkdtemp(path.join(os.tmpdir(), "guard-selfhosted-symlink-"));
+ cleanupPaths.add(outsideDir);
+ const fixture = await createBuiltPluginFixture(outsideDir, "symlinked");
+ const linkPath = path.join(outsideDir, "linked-plugin");
+ await symlink(fixture.packageRoot, linkPath, "dir");
+ const app = await createInstallApp(db);
+
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: linkPath, isLocalPath: true });
+
+ expect(res.status).toBe(200);
+ expect(res.body.packageName).toBe(fixture.packageName);
+ expect(res.body.packagePath).toBe(await realpath(fixture.packageRoot));
+ expect(mockLifecycle.load).toHaveBeenCalledTimes(1);
+ }, 30_000);
+ });
+
+ describe("self-hosted npm installs (behavior unchanged)", () => {
+ it("still rejects package names with invalid characters", async () => {
+ const app = await createInstallApp(db);
+
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: "bad<name>" });
+
+ expect(res.status).toBe(400);
+ expect(res.body.error).toBe("packageName contains invalid characters");
+ expect(mockLifecycle.load).not.toHaveBeenCalled();
+ });
+
+ it("does not apply the cloud floor when PAPERCLIP_MANAGED_CONFIG is absent", async () => {
+ const app = await createInstallApp(db);
+
+ // A well-formed npm package name passes route validation and reaches
+ // the loader (which fails here because npm cannot resolve the package
+ // in the test environment) — proving the 403 floor did not trigger.
+ const res = await request(app)
+ .post("/api/plugins/install")
+ .send({ packageName: `paperclip-plugin-guard-missing-${randomUUID().slice(0, 8)}` });
+
+ expect(res.status).toBe(400);
+ expect(res.body.error).toContain("npm install failed");
+ expect(mockLifecycle.load).not.toHaveBeenCalled();
+ }, 150_000);
+ });
+});
diff --git a/server/src/routes/plugins.ts b/server/src/routes/plugins.ts
index 566a200129..8db0353236 100644
--- a/server/src/routes/plugins.ts
+++ b/server/src/routes/plugins.ts
@@ -84,6 +84,11 @@ import {
import {
extractSecretRefBindingsFromConfig,
} from "../services/plugin-secrets-handler.js";
+import {
+ canonicalizeLocalPluginPath,
+ isCloudManagedInstance,
+ isWithinBundledPluginRoot,
+} from "../services/plugin-install-guard.js";
import { secretService } from "../services/secrets.js";
import { badRequest, forbidden, notFound, unauthorized, unprocessable } from "../errors.js";
@@ -1104,10 +1109,18 @@ export function pluginRoutes(
* 3. Registers in the database
* 4. Transitions to `ready` state if no new capability approval is needed
*
+ * Cloud-managed instances (identified by the harness-injected
+ * `PAPERCLIP_MANAGED_CONFIG` environment variable) enforce a positive
+ * allowlist: only local paths that canonicalize to a directory inside the
+ * bundled plugin catalog root may be installed. npm/registry installs and
+ * arbitrary local paths are rejected with `403`. Local paths are
+ * canonicalized and validated on every instance.
+ *
* Response: `PluginRecord`
*
* Errors:
* - `400` — validation failure or install error (package not found, bad manifest, etc.)
+ * - `403` — install source not permitted on a cloud-managed instance
* - `500` — installation succeeded but manifest is missing (indicates a loader bug)
*/
router.post("/plugins/install", async (req, res) => {
@@ -1143,9 +1156,39 @@ export function pluginRoutes(
return;
}
+ // Cloud install floor: on harness-managed instances only bundled-catalog
+ // sources are installable, regardless of actor privileges or flag state.
+ const cloudManaged = isCloudManagedInstance();
+ if (cloudManaged && !isLocalPath) {
+ res.status(403).json({
+ error:
+ "npm installs are disabled on cloud-managed instances; only plugins bundled with the application may be installed",
+ });
+ return;
+ }
+
+ // Canonicalize local install paths on every instance so traversal
+ // segments and symlinks cannot smuggle an aliased path past validation.
+ let canonicalLocalPath: string | undefined;
+ if (isLocalPath) {
+ const validated = await canonicalizeLocalPluginPath(trimmedPackage);
+ if (!validated.ok) {
+ res.status(400).json({ error: `Invalid localPath: ${validated.reason}` });
+ return;
+ }
+ if (cloudManaged && !(await isWithinBundledPluginRoot(validated.canonicalPath))) {
+ res.status(403).json({
+ error:
+ "cloud-managed instances may only install plugins from the bundled plugin catalog",
+ });
+ return;
+ }
+ canonicalLocalPath = validated.canonicalPath;
+ }
+
try {
- const installOptions = isLocalPath
- ? { localPath: trimmedPackage }
+ const installOptions = canonicalLocalPath !== undefined
+ ? { localPath: canonicalLocalPath }
: { packageName: trimmedPackage, version: version?.trim() };
const discovered = await loader.installPlugin(installOptions);
diff --git a/server/src/services/plugin-install-guard.ts b/server/src/services/plugin-install-guard.ts
new file mode 100644
index 0000000000..63497e3b4f
--- /dev/null
+++ b/server/src/services/plugin-install-guard.ts
@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Security guard for plugin install sources.
+ *
+ * Two related protections for `POST /api/plugins/install`:
+ *
+ * 1. **Cloud install floor.** Instances managed by the Paperclip Cloud
+ * harness receive a `PAPERCLIP_MANAGED_CONFIG` environment document that
+ * only the harness can inject. On such instances, plugin installation is
+ * a remote-code-execution surface on shared infrastructure, so the route
+ * enforces a positive allowlist: only install sources that canonicalize
+ * to a path inside the bundled plugin catalog root may be installed.
+ * npm/registry installs and arbitrary `localPath` installs are rejected.
+ *
+ * 2. **`localPath` canonicalization for every instance.** The install route
+ * historically skipped its package-name character check when
+ * `isLocalPath` was set, passing the raw request string straight to the
+ * loader. All local install paths are now canonicalized (absolute
+ * resolution + symlink/`..` normalization via `realpath`) and validated
+ * to be readable directories before the loader sees them.
+ *
+ * The floor is enforced in code at the route, independent of any feature
+ * flag or of the managed-config document's *content*: a corrupted flag
+ * document cannot widen the install surface because this module never reads
+ * the document body at all (see `isCloudManagedInstance`).
+ */
+
+import { realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { BUNDLED_LOCAL_PLUGIN_ROOT } from "./plugin-loader.js";
+
+/**
+ * Environment key carrying the harness-injected managed-instance document.
+ *
+ * The full document contract (`mode: "cloud"`, feature overlay, plugin
+ * auto-install list) is parsed fail-closed elsewhere at startup; this module
+ * only cares about the variable's presence.
+ */
+export const MANAGED_CONFIG_ENV_KEY = "PAPERCLIP_MANAGED_CONFIG";
+
+/**
+ * Whether this instance is managed by the Paperclip Cloud harness.
+ *
+ * Deliberately presence-based rather than content-based: the strict startup
+ * parser refuses to boot a managed instance with a malformed document, and
+ * absent env means self-hosted. Deciding the security floor on presence
+ * alone means a corrupted, truncated, or attacker-influenced document can
+ * never *disable* the floor — the failure mode is closed, not open.
+ *
+ * @param env - Raw environment map (injectable for tests; defaults to `process.env`)
+ */
+export function isCloudManagedInstance(
+ env: Record<string, string | undefined> = process.env,
+): boolean {
+ return env[MANAGED_CONFIG_ENV_KEY] !== undefined;
+}
+
+/** Result of canonicalizing a requested local plugin install path. */
+export type LocalPluginPathValidation =
+ | { ok: true; canonicalPath: string }
+ | { ok: false; reason: string };
+
+/**
+ * Canonicalize and validate a raw `localPath` install source.
+ *
+ * Resolves the request string to an absolute path, then to its real path —
+ * collapsing `..` traversal segments and resolving every symlink — and
+ * requires the result to be an existing directory. Downstream checks (the
+ * cloud catalog containment test, the loader itself) must only ever see the
+ * canonical form so that no alias of a path can reach a different decision
+ * than the path itself.
+ *
+ * @param rawPath - The unsanitized `packageName` value from the request body
+ */
+export async function canonicalizeLocalPluginPath(
+ rawPath: string,
+): Promise<LocalPluginPathValidation> {
+ if (rawPath.includes("\0")) {
+ return { ok: false, reason: "path contains a null byte" };
+ }
+
+ const absolutePath = path.resolve(rawPath);
+
+ let canonicalPath: string;
+ try {
+ canonicalPath = await realpath(absolutePath);
+ } catch {
+ return { ok: false, reason: `path does not exist: ${absolutePath}` };
+ }
+
+ try {
+ const stats = await stat(canonicalPath);
+ if (!stats.isDirectory()) {
+ return { ok: false, reason: `path is not a directory: ${canonicalPath}` };
+ }
+ } catch {
+ return { ok: false, reason: `path is not readable: ${canonicalPath}` };
+ }
+
+ return { ok: true, canonicalPath };
+}
+
+/**
+ * Whether a canonical path lies strictly inside the bundled plugin catalog
+ * root (`packages/plugins` in the application bundle).
+ *
+ * The catalog root itself is also canonicalized before comparison so a
+ * symlinked deployment layout cannot produce false negatives, and the
+ * containment test is segment-based (`path.relative`), never a string-prefix
+ * check. The root itself does not count as inside — an install source must
+ * be a package directory *within* the catalog.
+ *
+ * @param canonicalPath - A path already canonicalized by {@link canonicalizeLocalPluginPath}
+ * @param bundledRootOverride - Catalog root override for tests; defaults to
+ * {@link BUNDLED_LOCAL_PLUGIN_ROOT}
+ */
+export async function isWithinBundledPluginRoot(
+ canonicalPath: string,
+ bundledRootOverride?: string,
+): Promise<boolean> {
+ const bundledRoot = bundledRootOverride ?? BUNDLED_LOCAL_PLUGIN_ROOT;
+
+ let canonicalRoot: string;
+ try {
+ canonicalRoot = await realpath(bundledRoot);
+ } catch {
+ // No catalog root on disk means nothing is bundled; fail closed.
+ return false;
+ }
+
+ const relative = path.relative(canonicalRoot, canonicalPath);
+ return relative.length > 0 && !relative.startsWith("..") && !path.isAbsolute(relative);
+}