mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +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>
167 lines
8.6 KiB
Markdown
167 lines
8.6 KiB
Markdown
# Plugins supplied by an application distribution
|
|
|
|
A downstream image can add prebuilt plugins without changing Paperclip's
|
|
built-in catalog. The operator owns the image and trusts its plugin code.
|
|
This is packaging and activation policy, not a sandbox or entitlement system.
|
|
Ordinary self-hosted images need no catalog and keep their existing behavior.
|
|
|
|
## Image layout
|
|
|
|
Use `distribution/catalog.json` beneath `PAPERCLIP_BUNDLED_PLUGIN_ROOT`
|
|
(default `/app/packages/plugins`). Each plugin has a stable directory below
|
|
`distribution/`, containing its `package.json`, compiled manifest, worker and
|
|
optional UI. Bundle runtime dependencies; startup never installs them.
|
|
|
|
```json
|
|
{
|
|
"schemaVersion": 1,
|
|
"plugins": [{
|
|
"key": "example-extension",
|
|
"pluginKey": "example.extension",
|
|
"version": "1.0.0",
|
|
"directory": "example-extension",
|
|
"digest": "sha256:<64 lowercase hex characters>"
|
|
}]
|
|
}
|
|
```
|
|
|
|
The digest covers a sorted depth-first file inventory. Each entry is
|
|
`[relativePosixPath, "sha256:" + sha256(fileBytes), permissionBits & 0777]`.
|
|
Hash the UTF-8 JSON serialization of the inventory and prefix it with
|
|
`sha256:`. The server's `distributionBundleDigest` implements this contract.
|
|
There are no symbolic links or special files. A bundle is limited to 10,000
|
|
files, 256 MiB and 32 directory levels. Catalog keys, plugin IDs and directory
|
|
names must be unique; a distribution cannot replace a built-in key or ID.
|
|
|
|
On startup, the host validates the catalog, hashes the bundle before importing
|
|
its executable manifest, and validates package version and confined prebuilt
|
|
entrypoints. Malformed catalogs and integrity failures stop startup. Deploy
|
|
the catalog and bundles atomically as part of the image; keep them read-only
|
|
in operation. This detects packaging errors but does not authenticate an
|
|
untrusted image builder. Image provenance and signatures remain deployment
|
|
responsibilities.
|
|
|
|
### Provider credentials
|
|
|
|
An image author can set `workerCredentialEnv` on a distribution catalog
|
|
entry to pass provider API keys from the host environment. For example,
|
|
`"workerCredentialEnv": ["EXAMPLE_API_KEY"]` lets the worker receive
|
|
`EXAMPLE_API_KEY` when the deployment sets it. List 1 to 16 distinct
|
|
uppercase environment variable names ending in `_API_KEY`, each at most
|
|
128 characters. Store the names in the catalog and set the values through
|
|
the deployment.
|
|
|
|
Core grants these variables to the selected, digest-verified worker when
|
|
it declares `environment.drivers.register`. This grant is available through
|
|
managed image activation. The ordinary `plugins.workerEnv` credential
|
|
restriction applies independently.
|
|
|
|
Before emitting this field, image builders can check for
|
|
`workerCredentialEnv` in the capability list at
|
|
`server/src/services/distribution-plugin-catalog-capabilities.json` in the
|
|
target Core source revision. Older versions reject the unknown catalog field.
|
|
|
|
## Selection, upgrades and rollback
|
|
|
|
Managed instances select a distribution key through the existing
|
|
`plugins.autoInstall` list. Existing install, capability validation, API
|
|
compatibility, worker and health mechanisms apply. A worker or install failure
|
|
is recorded as a plugin error without taking down the application.
|
|
|
|
A managed instance can also give a selected plugin process variables through
|
|
`plugins.workerEnv`. The document holds variable names, not values. The deployment
|
|
sets the values in the server's process environment:
|
|
|
|
```json
|
|
{ "plugins": {
|
|
"autoInstall": ["example-extension"],
|
|
"workerEnv": { "example-extension": ["EXAMPLE_ORIGIN", "EXAMPLE_CAPABILITY"] }
|
|
} }
|
|
```
|
|
|
|
Each key must be in `autoInstall`. Startup fails if a name looks like a host
|
|
credential, such as one with `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `DATABASE` or
|
|
`JWT` as a word, or if it controls how the worker loads code, such as
|
|
`NODE_OPTIONS`. Give a granted variable a name for its own use, not a reused host
|
|
variable. Only the plugin with that catalog key receives the variables. A managed
|
|
instance runs a selected plugin only from the current image, so an install from
|
|
another source does not start.
|
|
|
|
A grant does not give access to any company. To let a plugin serve a company with
|
|
no saved configuration, name the company in `plugins.enabledCompanies`:
|
|
|
|
```json
|
|
{ "plugins": {
|
|
"autoInstall": ["example-extension"],
|
|
"enabledCompanies": { "example-extension": ["<company-uuid>"] }
|
|
} }
|
|
```
|
|
|
|
The plugin then receives resource lifecycle events for that company and can use
|
|
project instance secrets there. A company can still disable the plugin. This does
|
|
not give access for background worker calls. Those still need a saved company
|
|
configuration. Core reads the list from the document on each use and does not save
|
|
it, so a database restore cannot bring back access that the document removed.
|
|
|
|
The catalog alone does not auto-enable plugins on self-hosted instances.
|
|
Operators can explicitly install catalog entries through the normal plugin
|
|
CLI. The package's manifest ID and version must match the catalog.
|
|
The manifest's worker and optional UI entrypoints must match the verified
|
|
`package.json` declarations and stay inside the bundle.
|
|
|
|
At boot, selected distribution entries adopt the current image's package path
|
|
even when a previous npm or local install has the same version. Reconciliation
|
|
keeps the registry ID, configuration and stored state. With unchanged permissions,
|
|
operator-disabled status is retained. A replacement that adds capabilities is
|
|
saved atomically in `upgrade_pending`, even for same-version bundles. It cannot
|
|
activate until an operator reviews the manifest and enables it through the normal
|
|
plugin lifecycle. Invalid capability declarations are rejected before persistence.
|
|
Runtime refreshes also reject unapproved capability additions before starting code.
|
|
Rolling back an unapproved replacement refreshes the displayed manifest but
|
|
retains `upgrade_pending`. Review the rollback manifest and explicitly enable it
|
|
to resume. A smaller capability set alone cannot prove prior approval: it may
|
|
retain an unapproved permission, and the plugin may originally have been disabled.
|
|
Ordinary upgrades/downgrades of an approved, ready plugin continue automatically.
|
|
|
|
Keep each key's directory stable across releases. The activation guard also
|
|
covers persisted installs: a plugin removed from the image catalog, or no
|
|
longer selected in managed configuration, cannot activate on restart. Its
|
|
stored image path remains the source marker if the directory disappears; package
|
|
resolution cannot substitute an npm copy. Keep the catalog root stable as well.
|
|
An explicit operator reinstall changes a package's source; editing database rows
|
|
or replacing the catalog root is outside this image-selection contract. Plugin
|
|
database records remain for rollback. Plugin data migrations must themselves
|
|
support the intended rollback window; removing a bundle does not undo them.
|
|
|
|
A deployment controller must generate `plugins.autoInstall` from the **target
|
|
image's** catalog. A union of catalogs from different releases is insufficient:
|
|
an older image rejects a key it does not know. Before reverting to a host
|
|
version that predates this catalog contract, disable the distribution plugins
|
|
and remove their keys from configuration. Such older hosts do not have the
|
|
new activation guard.
|
|
|
|
## Persistent application UI
|
|
|
|
The `appShellOverlay` slot requires `ui.action.register`. It receives the usual
|
|
`PluginWidgetProps` context. It mounts once in both application shells and
|
|
survives route navigation. It is disposed when the account or selected company
|
|
changes, during onboarding, and on sign-out. It is not mounted on login pages.
|
|
Local-trusted mode has no login requirement: its sessionless board may mount
|
|
overlays, but transitions to or from an account still dispose the prior state.
|
|
|
|
The host positions contributions above the mobile navigation and stacks them
|
|
at the bottom right. Each plugin owns its launcher, panel, keyboard handling,
|
|
focus restoration, accessible labels and request cancellation. Use a bounded,
|
|
responsive panel. This slot is not a launcher placement zone and does not
|
|
replace modal/launcher APIs. Errors remain inside the existing plugin mount
|
|
error boundary.
|
|
|
|
UI code is trusted browser code. Host context is display context, never proof
|
|
of server authorization. A distribution backend must independently validate
|
|
the signed-in session and enforce company, tenant and user access rules for
|
|
every read and mutation. Keep provider secrets out of plugin UI and manifests.
|
|
The service worker's offline cache accepts only same-origin, hashed build assets
|
|
under `/assets/`. It does not store or replay application HTML, extension routes
|
|
or API data. This policy remains in effect after worker restarts and does not read
|
|
the arbitrary-response caches created by older workers.
|