mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 13:01:05 +01:00
## Thinking Path > - Paperclip manages AI agents for work. > - Application images can ship plugins that provide task environments. > - Paperclip starts plugin workers with a restricted process environment. > - An image author can know which provider credentials an image-bundled worker needs. > - The image catalog already identifies selected bundles and verifies their content. > - This change adds a way for the image catalog to declare the provider keys that a verified worker receives. ## Linked Issues or Issue Description **What existing behavior does this improve?** Image-bundled environment drivers can use the worker credential delivery already available to built-in providers. **Current behavior** The host provides fixed credential forwarding for certain built-in providers. **Proposed behavior** A verified image bundle can receive provider API keys declared on its own catalog entry. **Reason and benefit** Image authors can scope deployment credentials to the verified worker that needs them. ## What Changed - Add an optional provider credential declaration to the image-owned distribution catalog. - Scope forwarding to the verified worker for the selected bundle. - Publish distribution catalog support for image builders. ## Verification - The new loader regression failed before the change because the old catalog rejected the credential declaration. - Ran six focused Vitest suites for bundled activation, package identity, distribution catalog validation, worker environment, and managed configuration. 166 tests passed and one existing test was skipped. - Ran `pnpm --filter @paperclipai/server typecheck`. It passed. - Reviewed the diff for secret values and personal information. Test keys are synthetic. - A downstream image build fixture exercised the catalog reader, bundle verification, and worker environment together. The supported build passed only the declared provider key to the verified worker. The build for an older target omitted the declaration. - Local verification used embedded PostgreSQL and prebuilt fixtures. ## Risks - Deploy images with catalog credential declarations only to Core versions that support the field. Older hosts reject unknown catalog fields. - The image author controls which verified bundle receives each provider API key. ## Model Used - Implementation: GPT-6.1 Sol (`gpt-6.1-sol`), delegated through Codex. Independent Codex review and verification. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs - [x] I have described the issue in the PR - [x] I have used public references - [x] My branch name describes the change - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented risks - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing>
130 lines
9.5 KiB
TypeScript
130 lines
9.5 KiB
TypeScript
import { mkdtempSync, mkdirSync, rmSync, writeFileSync, symlinkSync, realpathSync } from "node:fs";
|
|
import os from "node:os";
|
|
import path from "node:path";
|
|
import { afterEach, describe, expect, it } from "vitest";
|
|
import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
|
|
import { distributionBundleDigest, distributionPluginActivationGuard, readDistributionPluginCatalog } from "../services/distribution-plugin-catalog.js";
|
|
import { BUNDLED_PLUGIN_CATALOG, resolveBundledPluginInstalls } from "../services/bundled-plugins.js";
|
|
|
|
const roots: string[] = [];
|
|
afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
|
|
function fixture() {
|
|
const root = realpathSync(mkdtempSync(path.join(os.tmpdir(), "distribution-plugin-"))); roots.push(root);
|
|
const localPath = path.join(root, "distribution", "acme.widget");
|
|
mkdirSync(path.join(localPath, "dist", "ui"), { recursive: true });
|
|
writeFileSync(path.join(localPath, "package.json"), JSON.stringify({ name: "@acme/plugin-widget", version: "1.0.0", paperclipPlugin: { manifest: "./dist/manifest.js", worker: "./dist/worker.js", ui: "./dist/ui/" } }));
|
|
writeFileSync(path.join(localPath, "dist", "manifest.js"), "export default {};");
|
|
writeFileSync(path.join(localPath, "dist", "worker.js"), "export default {};");
|
|
const entry = { key: "acme.widget", pluginKey: "acme.widget", version: "1.0.0", directory: "acme.widget", digest: distributionBundleDigest(localPath) };
|
|
const save = (plugins: unknown[] = [entry]) => writeFileSync(path.join(root, "distribution", "catalog.json"), JSON.stringify({ schemaVersion: 1, plugins }));
|
|
save(); return { root, localPath, entry, save };
|
|
}
|
|
describe("image-owned plugin catalogs", () => {
|
|
it("preserves images without a distribution catalog", () => {
|
|
expect(readDistributionPluginCatalog("/nonexistent/catalog", BUNDLED_PLUGIN_CATALOG)).toEqual([]);
|
|
});
|
|
it("resolves selected private bundles alongside built-ins after verifying their bytes", () => {
|
|
const { root, localPath } = fixture();
|
|
const installs = resolveBundledPluginInstalls(["daytona", "acme.widget"], { catalogRoot: root, env: {}, enforceCatalogRoot: true });
|
|
expect(installs.map(({ key }) => key)).toEqual(["daytona", "acme.widget"]);
|
|
expect(installs[1]?.localPath).toBe(localPath);
|
|
});
|
|
it("accepts only bounded and distinct provider API key names as worker credentials", () => {
|
|
const { root, entry, save } = fixture();
|
|
save([{ ...entry, workerCredentialEnv: ["EXAMPLE_API_KEY", "SECOND_API_KEY"] }]);
|
|
expect(readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG)[0]?.workerCredentialEnv)
|
|
.toEqual(["EXAMPLE_API_KEY", "SECOND_API_KEY"]);
|
|
for (const invalid of [
|
|
[], ["NODE_OPTIONS"], ["DATABASE_URL"], ["example_API_KEY"], ["EXAMPLE_API_KEY=value"],
|
|
["EXAMPLE_API_KEY", "EXAMPLE_API_KEY"], Array.from({ length: 17 }, (_, i) => `EXAMPLE_${i}_API_KEY`),
|
|
]) {
|
|
save([{ ...entry, workerCredentialEnv: invalid }]);
|
|
expect(() => readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG)).toThrow(/workerCredentialEnv/);
|
|
}
|
|
});
|
|
it("rejects tampered bundle bytes before importing manifest code", () => {
|
|
const { root, localPath } = fixture();
|
|
writeFileSync(path.join(localPath, "dist", "manifest.js"), "throw new Error('must never execute');");
|
|
expect(() => readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG)).toThrow(/digest mismatch/);
|
|
});
|
|
it("rejects duplicate keys, plugin identities and built-in replacement", () => {
|
|
const { root, entry, save } = fixture();
|
|
for (const plugins of [[entry, entry], [{ ...entry, key: "daytona" }], [{ ...entry, pluginKey: "paperclip.daytona-sandbox-provider" }]]) {
|
|
save(plugins);
|
|
expect(() => readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG)).toThrow(/Duplicate or built-in/);
|
|
}
|
|
});
|
|
it("rejects traversal, symlinked artifacts and unbuilt entrypoints", () => {
|
|
const { root, entry, localPath, save } = fixture();
|
|
save([{ ...entry, directory: "../elsewhere" }]);
|
|
expect(() => readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG)).toThrow();
|
|
save(); symlinkSync(os.tmpdir(), path.join(localPath, "outside"));
|
|
expect(() => readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG)).toThrow(/symlinks/);
|
|
rmSync(path.join(localPath, "outside")); rmSync(path.join(localPath, "dist", "worker.js"));
|
|
save([{ ...entry, digest: distributionBundleDigest(localPath) }]);
|
|
expect(() => readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG)).toThrow();
|
|
});
|
|
it("blocks a persisted plugin after deselection/removal while preserving ordinary plugins", () => {
|
|
const { root, localPath } = fixture();
|
|
const entries = readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG);
|
|
const input = { pluginKey: "acme.widget", packageRoot: localPath };
|
|
expect(() => distributionPluginActivationGuard(root, entries, ["acme.widget"])(input)).not.toThrow();
|
|
expect(() => distributionPluginActivationGuard(root, entries, ["acme.widget"])({ packageRoot: localPath })).not.toThrow();
|
|
expect(() => distributionPluginActivationGuard(root, entries, [])({ packageRoot: localPath })).toThrow(/not selected/);
|
|
expect(() => distributionPluginActivationGuard(root, entries, [])(input)).toThrow(/not selected/);
|
|
expect(() => distributionPluginActivationGuard(root, [], [])(input)).toThrow(/absent/);
|
|
expect(() => distributionPluginActivationGuard(root, [], [])({ ...input, packageRoot: path.join(root, "node_modules/acme"), installedPackagePath: localPath })).toThrow(/absent/);
|
|
expect(() => distributionPluginActivationGuard(root, [], [])({ pluginKey: "ordinary.plugin", packageRoot: path.join(root, "ordinary") })).not.toThrow();
|
|
});
|
|
it("rejects dangling catalog symlinks instead of treating them as absent", () => {
|
|
const { root } = fixture();
|
|
const file = path.join(root, "distribution", "catalog.json");
|
|
rmSync(file); symlinkSync(path.join(root, "missing"), file);
|
|
expect(() => readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG)).toThrow(/Invalid distribution catalog/);
|
|
});
|
|
it("requires catalog identity and version before activating imported manifests", () => {
|
|
const { root, localPath } = fixture();
|
|
const entries = readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG);
|
|
const guard = distributionPluginActivationGuard(root, entries, ["acme.widget"]);
|
|
for (const manifest of [{ id: "other.plugin", version: "1.0.0" }, { id: "acme.widget", version: "2.0.0" }]) {
|
|
expect(() => guard({ pluginKey: "acme.widget", packageRoot: localPath, manifest: manifest as PaperclipPluginManifestV1 })).toThrow(/identity\/version/);
|
|
}
|
|
});
|
|
|
|
it("binds runtime worker and UI entrypoints to the digest-verified package declarations", () => {
|
|
const { root, localPath } = fixture();
|
|
const entries = readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG);
|
|
const guard = distributionPluginActivationGuard(root, entries, ["acme.widget"]);
|
|
const manifest = { id: "acme.widget", version: "1.0.0", capabilities: [], entrypoints: { worker: "dist/worker.js", ui: "./dist/ui" } } as unknown as PaperclipPluginManifestV1;
|
|
expect(() => guard({ packageRoot: localPath, manifest })).not.toThrow();
|
|
for (const name of ["worker", "ui"] as const) {
|
|
for (const value of ["/outside/worker.js", "../outside", "dist/../worker.js", "C:/outside", "dist\\worker.js", "dist/other", "", undefined]) {
|
|
const invalid = { ...manifest, entrypoints: { ...manifest.entrypoints, [name]: value } } as PaperclipPluginManifestV1;
|
|
expect(() => guard({ packageRoot: localPath, manifest: invalid })).toThrow(/entrypoint/);
|
|
}
|
|
}
|
|
});
|
|
|
|
it("accepts worker-only bundles but rejects a UI path absent from verified metadata", () => {
|
|
const { root, localPath, entry, save } = fixture();
|
|
writeFileSync(path.join(localPath, "package.json"), JSON.stringify({ version: "1.0.0", paperclipPlugin: { manifest: "./dist/manifest.js", worker: "./dist/worker.js" } }));
|
|
save([{ ...entry, digest: distributionBundleDigest(localPath) }]);
|
|
const guard = distributionPluginActivationGuard(root, readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG), null);
|
|
const manifest = { id: "acme.widget", version: "1.0.0", capabilities: [], entrypoints: { worker: "./dist/worker.js" } } as unknown as PaperclipPluginManifestV1;
|
|
expect(() => guard({ packageRoot: localPath, manifest })).not.toThrow();
|
|
manifest.entrypoints.ui = "./dist/ui";
|
|
expect(() => guard({ packageRoot: localPath, manifest })).toThrow(/verified package/);
|
|
});
|
|
|
|
it("rejects inconsistent capabilities and unapproved runtime refreshes", () => {
|
|
const { root, localPath } = fixture();
|
|
const guard = distributionPluginActivationGuard(root, readDistributionPluginCatalog(root, BUNDLED_PLUGIN_CATALOG), null);
|
|
const previousManifest = { id: "acme.widget", version: "1.0.0", capabilities: [], entrypoints: { worker: "./dist/worker.js", ui: "./dist/ui" } } as unknown as PaperclipPluginManifestV1;
|
|
const manifest = { ...previousManifest, capabilities: ["issues.read" as const] };
|
|
expect(() => guard({ packageRoot: localPath, manifest, previousManifest })).toThrow(/require approval/);
|
|
expect(() => guard({ packageRoot: localPath, manifest, previousManifest: manifest })).not.toThrow();
|
|
previousManifest.ui = { slots: [{ type: "appShellOverlay", id: "overlay", displayName: "Overlay", exportName: "Overlay" }] };
|
|
expect(() => guard({ packageRoot: localPath, manifest: previousManifest })).toThrow(/missing required capabilities: ui.action.register/);
|
|
});
|
|
});
|