Files
PaperClipAI/doc/plugins/DISTRIBUTION-PLUGINS.md
T
Devin FoleyandPaperclip 417802ca87 fix(plugins): refresh unchanged-version bundle descriptions (#22295)
Refresh known display descriptions in same-version bundled plugin registrations only when every behavioral field matches. Compare manifests in their persisted JSON form and await bundle reconciliation before final volume-free package qualification.

Verified 77 focused tests, server typechecking, and all 59 successful PR checks. Greptile 5/5 with no unresolved review comments.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-11-19 09:26:06 -08:00

175 lines
9.1 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.
Built-in Core plugins also refresh stored display descriptions at startup when
the installed version matches the image. This covers the plugin description,
environment-driver descriptions, and direct config-property help text. All other
manifest fields must match, including permissions, entrypoints, schema rules,
and default values. Pending approval and uninstall states retain their existing
behavior. This refresh updates metadata without restarting a worker. Volume-free
qualification still requires the complete stored manifest to match the image.
## 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.