Files
PaperClipAI/server/src/services/distribution-plugin-catalog.ts
T
Nicky LeachandPaperclip 2168f50741 Forward provider credentials from verified image catalogs (#21186)
## 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>
2026-11-12 20:53:08 +00:00

169 lines
9.2 KiB
TypeScript

import fs from "node:fs";
import path from "node:path";
import { createHash } from "node:crypto";
import { z } from "zod";
import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
import { pluginCapabilityValidator } from "./plugin-capability-validator.js";
const segment = z.string().regex(/^[a-z][a-z0-9.-]{0,99}$/);
const workerCredentialEnv = z.array(z.string().max(128).regex(/^[A-Z][A-Z0-9_]*_API_KEY$/))
.min(1).max(16).refine((names) => new Set(names).size === names.length, "Worker credential names must be distinct");
export const distributionPluginCatalogSchema = z.object({
schemaVersion: z.literal(1),
plugins: z.array(z.object({
key: segment,
pluginKey: segment,
version: z.string().regex(/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?(?:\+[a-zA-Z0-9.-]+)?$/),
directory: segment,
digest: z.string().regex(/^sha256:[a-f0-9]{64}$/),
workerCredentialEnv: workerCredentialEnv.optional(),
}).strict()).max(100),
}).strict();
export type DistributionPlugin = z.infer<typeof distributionPluginCatalogSchema>["plugins"][number] & {
localPath: string;
/** Normalized paths from the digest-verified package metadata. */
entrypoints: { worker: string; ui?: string };
};
function bundleEntrypoint(declared: unknown): string {
const relative = typeof declared === "string" ? declared.replace(/^\.\//, "").replace(/\/$/, "") : "";
if (!relative || path.posix.isAbsolute(relative) || path.win32.isAbsolute(relative) || relative.includes("\\") || relative.split("/").some((part) => !part || part === "." || part === "..")) {
throw new Error("Distribution entrypoint must stay inside its bundle");
}
return relative;
}
export function assertDistributionManifestCapabilities(manifest: PaperclipPluginManifestV1): void {
const result = pluginCapabilityValidator().validateManifestCapabilities(manifest);
if (!result.allowed) {
throw new Error(`Distribution manifest is missing required capabilities: ${result.missing.join(", ")}`);
}
}
export function distributionPluginsRoot(catalogRoot: string): string {
// Match canonical paths persisted by local-path installs (for example,
// macOS /tmp -> /private/tmp), without permitting a symlinked catalog itself.
try { return path.join(fs.realpathSync(catalogRoot), "distribution"); }
catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
return path.resolve(catalogRoot, "distribution");
}
}
/** Guard all activation paths, including persisted installs after a rollback. */
export function distributionPluginActivationGuard(
catalogRoot: string,
entries: readonly DistributionPlugin[],
selectedKeys: readonly string[] | null,
) {
const root = distributionPluginsRoot(catalogRoot);
return (input: { pluginKey?: string; packageRoot: string; installedPackagePath?: string | null; manifest?: PaperclipPluginManifestV1; previousManifest?: PaperclipPluginManifestV1 }) => {
let packageRoot: string;
try { packageRoot = fs.realpathSync(input.packageRoot); }
catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
packageRoot = path.resolve(input.packageRoot);
}
const entry = entries.find((candidate) => input.pluginKey ? candidate.pluginKey === input.pluginKey : candidate.localPath === packageRoot);
const relative = path.relative(root, packageRoot);
const inside = relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
// A missing image directory can make package resolution fall back to npm.
// Retain the persisted image-path provenance even when that directory no
// longer exists; the resolved fallback is not an ordinary installation.
const installedRelative = input.installedPackagePath ? path.relative(root, path.resolve(input.installedPackagePath)) : null;
const installedInside = installedRelative !== null && (installedRelative === "" || (!installedRelative.startsWith("..") && !path.isAbsolute(installedRelative)));
if (!inside && !installedInside && !entry) return;
if (!entry || (selectedKeys !== null && !selectedKeys.includes(entry.key)) || packageRoot !== entry.localPath) {
throw new Error("Distribution plugin is absent or not selected in this deployment");
}
if (input.manifest && (input.manifest.id !== entry.pluginKey || input.manifest.version !== entry.version)) {
throw new Error("Distribution manifest does not match its catalog identity/version");
}
if (input.manifest) {
assertDistributionManifestCapabilities(input.manifest);
if (input.previousManifest) {
const approved = new Set(input.previousManifest.capabilities);
const added = input.manifest.capabilities.filter((capability) => !approved.has(capability));
if (added.length) throw new Error(`Distribution plugin capabilities require approval: ${added.join(", ")}`);
}
const worker = bundleEntrypoint(input.manifest.entrypoints.worker);
const ui = input.manifest.entrypoints.ui === undefined ? undefined : bundleEntrypoint(input.manifest.entrypoints.ui);
if (worker !== entry.entrypoints.worker || ui !== entry.entrypoints.ui) {
throw new Error("Distribution manifest entrypoints do not match the verified package");
}
}
};
}
/** Same portable file inventory used by image builders: path, SHA-256, mode. */
export function distributionBundleDigest(root: string): string {
const inventory: Array<[string, string, number]> = [];
let bytesRead = 0;
const hash = (value: Buffer | string) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
function walk(directory: string, relative = "") {
if (relative.split("/").length > 32) throw new Error("Distribution bundle exceeds directory depth limit");
for (const name of fs.readdirSync(directory).sort()) {
const relativePath = relative ? `${relative}/${name}` : name;
const file = path.join(directory, name);
const stat = fs.lstatSync(file);
if (stat.isSymbolicLink()) throw new Error("Distribution bundles cannot contain symlinks");
if (stat.isDirectory()) walk(file, relativePath);
else if (stat.isFile()) {
bytesRead += stat.size;
if (bytesRead > 256 * 1024 * 1024 || inventory.length >= 10_000) throw new Error("Distribution bundle exceeds verification limits");
inventory.push([relativePath, hash(fs.readFileSync(file)), stat.mode & 0o777]);
} else throw new Error("Distribution bundles contain only regular files and directories");
}
}
walk(root);
if (!inventory.length) throw new Error("Distribution bundle is empty");
return hash(JSON.stringify(inventory));
}
/**
* Optional, image-owned extension catalog. No URLs, executable configuration,
* runtime dependency installation, or replacement of a built-in entry.
* Validate bytes before importing any manifest code.
*/
export function readDistributionPluginCatalog(
catalogRoot: string,
builtins: readonly { key: string; pluginKey: string }[],
): DistributionPlugin[] {
const root = distributionPluginsRoot(catalogRoot);
const file = path.join(root, "catalog.json");
const rootStat = fs.lstatSync(root, { throwIfNoEntry: false });
if (!rootStat) return [];
if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) throw new Error("Distribution catalog root must be a regular directory, not a symlink");
const stat = fs.lstatSync(file, { throwIfNoEntry: false });
if (!stat) return [];
if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 128 * 1024) throw new Error("Invalid distribution catalog file");
const catalog = distributionPluginCatalogSchema.parse(JSON.parse(fs.readFileSync(file, "utf8")));
const keys = new Set(builtins.map((entry) => entry.key));
const pluginKeys = new Set(builtins.map((entry) => entry.pluginKey));
const directories = new Set<string>();
return catalog.plugins.map((entry) => {
if (keys.has(entry.key) || pluginKeys.has(entry.pluginKey) || directories.has(entry.directory)) {
throw new Error("Duplicate or built-in distribution plugin identity");
}
keys.add(entry.key); pluginKeys.add(entry.pluginKey); directories.add(entry.directory);
const localPath = path.join(root, entry.directory);
const info = fs.lstatSync(localPath);
if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Invalid distribution bundle directory");
if (distributionBundleDigest(localPath) !== entry.digest) throw new Error(`Distribution bundle digest mismatch: ${entry.key}`);
const pkg = JSON.parse(fs.readFileSync(path.join(localPath, "package.json"), "utf8"));
if (pkg.version !== entry.version || !pkg.paperclipPlugin) throw new Error("Distribution package version or entrypoints missing");
for (const name of ["manifest", "worker", "ui"] as const) {
const declared = pkg.paperclipPlugin[name];
if (name === "ui" && declared === undefined) continue;
const relative = bundleEntrypoint(declared);
const target = fs.statSync(path.join(localPath, relative));
if (name === "ui" ? !target.isDirectory() : !target.isFile()) throw new Error("Distribution entrypoint is not prebuilt");
}
return { ...entry, localPath, entrypoints: {
worker: bundleEntrypoint(pkg.paperclipPlugin.worker),
...(pkg.paperclipPlugin.ui === undefined ? {} : { ui: bundleEntrypoint(pkg.paperclipPlugin.ui) }),
} };
});
}