mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 04:21:24 +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>
111 lines
6.6 KiB
TypeScript
111 lines
6.6 KiB
TypeScript
import fs from "node:fs";
|
|
import path from "node:path";
|
|
import { isDeepStrictEqual } from "node:util";
|
|
import type { PaperclipPluginManifestV1, PluginRecord } from "@paperclipai/shared";
|
|
import type { ResolvedBundledPlugin } from "./bundled-plugins.js";
|
|
import { assertDistributionManifestCapabilities } from "./distribution-plugin-catalog.js";
|
|
|
|
export type BundledPluginRegistration = Pick<PluginRecord, "pluginKey" | "packageName" | "version" | "manifestJson">;
|
|
|
|
export interface BundledPluginPackageIdentity {
|
|
kind: "bundled_image";
|
|
catalogKey: string;
|
|
pluginKey: string;
|
|
packageName: string;
|
|
version: string;
|
|
digest?: string;
|
|
}
|
|
|
|
export type BundledPluginPackageInspection =
|
|
| { compatible: true; identity: BundledPluginPackageIdentity }
|
|
| { compatible: false; pluginKey: string; code: "incompatible_bundled_package" | "missing_manifest_evidence"; reason: string };
|
|
|
|
function containedEntrypoint(root: string, declared: unknown, directory: boolean): string {
|
|
const relative = typeof declared === "string" ? declared.replace(/^\.\//, "").replace(/\/$/, "") : "";
|
|
if (!relative || path.isAbsolute(relative) || path.win32.isAbsolute(relative) || relative.includes("\\") || relative.split("/").length > 32 || relative.split("/").some((part) => !part || part === "." || part === "..")) {
|
|
throw new Error("Bundled plugin entrypoint must stay inside its package");
|
|
}
|
|
const target = fs.realpathSync(path.join(root, relative));
|
|
const resolvedRelative = path.relative(root, target);
|
|
if (!resolvedRelative || resolvedRelative.startsWith("..") || path.isAbsolute(resolvedRelative)) {
|
|
throw new Error("Bundled plugin entrypoint escapes its package");
|
|
}
|
|
const stat = fs.statSync(target);
|
|
if (directory ? !stat.isDirectory() : !stat.isFile()) throw new Error("Bundled plugin entrypoint is not prebuilt");
|
|
return relative;
|
|
}
|
|
|
|
export function createBundledPluginPackageResolver(installs: readonly ResolvedBundledPlugin[]) {
|
|
const byKey = new Map(installs.map((install) => [install.pluginKey, install]));
|
|
|
|
function read(install: ResolvedBundledPlugin) {
|
|
const root = fs.realpathSync(install.localPath);
|
|
if (root !== path.resolve(install.localPath)) throw new Error("Bundled plugin package root changed after catalog resolution");
|
|
containedEntrypoint(root, "package.json", false);
|
|
const metadataPath = path.join(root, "package.json");
|
|
if (fs.statSync(metadataPath).size > 128 * 1024) throw new Error("Bundled plugin package metadata exceeds verification limits");
|
|
const pkg = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
|
|
if (typeof pkg.name !== "string" || typeof pkg.version !== "string" || !pkg.paperclipPlugin) {
|
|
throw new Error("Bundled plugin package identity or entrypoints are missing");
|
|
}
|
|
if (install.distribution && pkg.version !== install.distribution.version) throw new Error("Bundled plugin package version does not match the catalog");
|
|
const manifest = containedEntrypoint(root, pkg.paperclipPlugin.manifest, false);
|
|
const worker = containedEntrypoint(root, pkg.paperclipPlugin.worker, false);
|
|
const ui = pkg.paperclipPlugin.ui === undefined ? undefined : containedEntrypoint(root, pkg.paperclipPlugin.ui, true);
|
|
if (install.distribution && (worker !== install.distribution.entrypoints.worker || ui !== install.distribution.entrypoints.ui)) {
|
|
throw new Error("Bundled plugin entrypoints do not match the verified package");
|
|
}
|
|
return { root, pkg, manifest, worker, ui };
|
|
}
|
|
|
|
function assertManifest(install: ResolvedBundledPlugin, manifest: PaperclipPluginManifestV1, previousManifest?: PaperclipPluginManifestV1) {
|
|
const bundle = read(install);
|
|
if (manifest.id !== install.pluginKey || manifest.version !== bundle.pkg.version) throw new Error("Bundled plugin manifest identity/version does not match the image");
|
|
const worker = containedEntrypoint(bundle.root, manifest.entrypoints.worker, false);
|
|
const ui = manifest.entrypoints.ui === undefined ? undefined : containedEntrypoint(bundle.root, manifest.entrypoints.ui, true);
|
|
if (worker !== bundle.worker || ui !== bundle.ui) throw new Error("Bundled plugin manifest entrypoints do not match the image");
|
|
assertDistributionManifestCapabilities(manifest);
|
|
if (previousManifest) {
|
|
const approved = new Set(previousManifest.capabilities);
|
|
if (manifest.capabilities.some((capability) => !approved.has(capability))) throw new Error("Bundled plugin capabilities require approval");
|
|
}
|
|
return bundle;
|
|
}
|
|
|
|
function resolve(plugin: BundledPluginRegistration): string {
|
|
const install = byKey.get(plugin.pluginKey);
|
|
if (!install) throw new Error(`Bundled plugin is absent or not selected in this deployment: ${plugin.pluginKey}`);
|
|
const bundle = assertManifest(install, plugin.manifestJson);
|
|
if (plugin.packageName !== bundle.pkg.name || plugin.version !== bundle.pkg.version) throw new Error("Bundled plugin registration identity/version does not match the image");
|
|
return bundle.root;
|
|
}
|
|
|
|
return {
|
|
resolve,
|
|
inspect(plugin: BundledPluginRegistration, verifiedManifest?: PaperclipPluginManifestV1): BundledPluginPackageInspection {
|
|
try {
|
|
resolve(plugin);
|
|
const install = byKey.get(plugin.pluginKey)!;
|
|
if (!verifiedManifest) return { compatible: false, pluginKey: plugin.pluginKey, code: "missing_manifest_evidence", reason: "Image manifest evidence is required" };
|
|
assertManifest(install, verifiedManifest);
|
|
if (!isDeepStrictEqual(verifiedManifest, plugin.manifestJson)) throw new Error("Approved plugin manifest does not match the image");
|
|
return { compatible: true, identity: {
|
|
kind: "bundled_image", catalogKey: install.key, pluginKey: plugin.pluginKey,
|
|
packageName: plugin.packageName, version: plugin.version,
|
|
...(install.distribution ? { digest: install.distribution.digest } : {}),
|
|
} };
|
|
} catch (error) {
|
|
return { compatible: false, pluginKey: plugin.pluginKey, code: "incompatible_bundled_package", reason: error instanceof Error ? error.message : String(error) };
|
|
}
|
|
},
|
|
assertActivation(input: { pluginKey?: string; packageRoot: string; manifest?: PaperclipPluginManifestV1; previousManifest?: PaperclipPluginManifestV1 }) {
|
|
const install = input.pluginKey ? byKey.get(input.pluginKey) : installs.find((candidate) => candidate.localPath === input.packageRoot);
|
|
if (!install || path.resolve(input.packageRoot) !== install.localPath) throw new Error("Bundled plugin is absent or not selected in this deployment");
|
|
read(install);
|
|
if (!input.manifest) return;
|
|
assertManifest(install, input.manifest, input.previousManifest);
|
|
return install.distribution;
|
|
},
|
|
};
|
|
}
|