Plugins
Publishing
Releasing through the official catalog, hosting your own, compatibility across core versions, and how updates and revocation reach an installed plugin.
What a catalog is#
A catalog is a signed HTTPS document (catalog.json, plus a detached signature at
catalog.json.sig) listing plugins and, for each, the versions available to install: their
pluginApi, their fliks compatibility range, a download URL and a sha256. A source is a URL
an admin has added under Settings > Plugins > ⋮ > Manage sources; there can be
several, the official catalog is simply the one seeded by default. Core refuses bytes whose hash
doesn't match what a catalog's version entry declares.
Core offers a version only when it can install it: its pluginApi is supported, its fliks range
matches the running version (unless the admin ignores the required Fliks version), and it has a
verifiable archive, meaning a non-empty zipUrl and a sha256 of 64 lowercase hex digits that is
not the all-zero placeholder. A plugin with no such version shows No installable version.
The official catalog#
The official catalog lives at github.com/fliks-app/fliks-plugin-catalog.
It is the one place archives get the official trust level, because its key is Fliks's official
release key (release-2026, the key core has compiled in). Releasing a process plugin through it
takes four steps:
Release the plugin from its own repository. Pushing a tag
v<version>, equal to the crate version, runs the repository's CI.fk-plugin-notifyandfk-plugin-downloadboth run the full test suite andcargo xtask package, then create a release carrying one asset, the unsigned<id>-<version>.fkpluginthatpackagebuilt and verified.Open a PR on the catalog with two new files, both reviewed.
plugins/<id>/src/plugin.jsonis the manifest inside that archive, with thefileshashes that pin every byte the catalog key will sign.plugins/<id>/versions/<version>.jsondescribes the version:json{ "id": "fliks.notify", "name": "Notify", "description": "Forwards Fliks domain events to an admin-configured HTTPS webhook, with bounded retry.", "author": "Fliks", "kind": "process", "version": "1.0.0", "pluginApi": 3, "fliks": ">=6.0.0 <7.0.0", "zipUrl": "https://github.com/fliks-app/fk-plugin-notify/releases/download/v1.0.0/fliks.notify-1.0.0.fkplugin", "sha256": "0000000000000000000000000000000000000000000000000000000000000000" }Never edit a version file that already exists: a published version's metadata is immutable, so anything that changes ships as a new version.
name,description,authorandkindmust be identical across every version of the same id.id,version,kind,pluginApiandfliksmust equal the manifest's.flikscarries a mandatory upper bound, andpluginApimust have a row in the catalog'sCOMPATIBILITY.md. For aprocessplugin ofpluginApi2 or later thezipUrlmust be an asset of afliks-apprepository'sv<version>release, named<id>-<version>.fkplugin. Thesha256stays zeroed, which keeps the version out of the published catalog until step 4.CI checks the PR, cheaply. The catalog's
validate-pr.ymlruns its script tests, a PR-shape check (no existing version file modified or deleted), the schema, theCOMPATIBILITY.mdrow, thefliksupper bound, and that rebuildingcatalog.jsontwice gives identical bytes. None of these downloads your archive, so check it yourself first withcargo xtask verify.A maintainer merges, then runs
Package pluginwith the plugin id and version. It downloads the archive from the release and refuses it unless it is a store-only zip ofplugin.json,plugin.wasmand a logo whoseplugin.jsonis byte-identical to the committed one. It checks the manifest,filesand logo as the host does at install, signs with the catalog key, replaces the asset on the same release with the signed archive and records its sha256 in the version file. The catalog'spublish.ymlthen regeneratescatalog.json, signs it, verifies the signature and republishes it on GitHub Pages.
A data plugin owned by the org keeps its source in plugins/<id>/src/ of the catalog repository,
and the same workflow builds, signs and commits its archive there.
The signed archive is what installs as official; the sha256 and the signature remain the install
gate. Auto-update only ever takes official versions, so this path is also the only one that
reaches installed servers without an admin.
Hosting your own catalog#
A catalog is just a document shape and a signature, both of which core already knows how to read:
- Serve
catalog.jsonover HTTPS:{ "plugins": [ { id, name, description, author, kind, logo?, versions: [ { version, pluginApi, fliks, zipUrl, sha256 } ] } ], "denyList"?: [...] }.zipUrlmust behttps://, andsha256the lowercase hex sha256 of the exact archive bytes. - Sign it: Ed25519, over the document's exact raw bytes (no reformatting after signing), the
signature published as base64 text at
<your-catalog-url>.sig. This is mandatory: core refuses a catalog whose signature is missing or doesn't verify (the source shows abad-signaturerefresh error), and the URL must behttps://. The catalog repository'sscripts/sign-catalog.mjsis a working example; it reads the private key from an environment variable as base64 PKCS#8 DER. - In Fliks, Settings > Plugins > ⋮ > Manage sources, add the catalog's URL together
with the base64 of your Ed25519 public key (the raw 32 bytes, the same one-line format as the
catalog repository's
keys/*.pubfiles) as the source's pinned key. Without a pinned key, core verifies the catalog against its own official keys only, so a self-signed catalog would be refused.
Pinning your own key on a source only verifies that catalog document itself. It does not make
the plugin archives it lists official: that trust level is reserved for a signature that
verifies against Fliks's own compiled-in release key. An archive from your own catalog, however
you sign it, installs as unverified or unsigned, always behind the consent step, and is never
picked up by automatic updates. A process plugin from such a catalog installs only on a server
whose admin turned on Allow unsigned plugins. The same holds for revocation: a denyList in
your catalog can't revoke any installed package (see below).
The catalog URL and the first archive URL are the admin's own choice and take no address guard, so a self-hosted catalog on a private network works. A redirect on the archive download is followed only from https to https, at most 5 hops, so GitHub release assets install; a hop to the archive URL's own host is trusted like the first, and a hop to any other host goes through core's outbound guard. The sha256 in the signed catalog stays the gate: a redirect cannot change what installs.
Compatibility#
Two independent axes, checked at three separate points (when a catalog is filtered, when an archive is inspected on install, and again whenever the plugin is registered):
| Axis | What it means | Enforced how |
|---|---|---|
pluginApi |
The contract revision your plugin is written against. | An exact match against one of core's SUPPORTED_PLUGIN_API_VERSIONS, never bypassable by any admin setting. |
fliks |
The core versions your plugin has been checked against. | A semver range match against the running core version (prerelease stripped). Bypassable with the admin setting Ignore the required Fliks version, since unlike pluginApi this one is a judgment call about actual runtime behaviour, not a hard protocol difference. |
The host links one WIT package version per pluginApi value, so any change to a record or a
function, an added field included, is a new pluginApi. Core accepts only the values in
SUPPORTED_PLUGIN_API_VERSIONS, with no transition window: today it is [3], and the catalog's
COMPATIBILITY.md maps 3 to core >=6.0.0 <7.0.0 (0, 1 and 2 are retired rows). A plugin
declaring a value core doesn't accept is installed but failed with incompatible-api, and
recovers when an auto-update installs a version that declares 3.
Updates#
Covered in full in Architecture: a daily refresh, an
auto-update pass right after it that only ever takes official-signed versions, and a manual
update that's just an inspect-then-confirm of any other version. A plugin disabled before an
upgrade stays disabled after it; a downgrade is allowed and only produces a log warning, not a
refusal.
Revocation#
A catalog document may carry a denyList: entries of { pluginId, version?, sha256?, reason }.
Omitting version denies every version of that plugin id; adding sha256 narrows an entry to one
exact build rather than every archive ever published under that version string. A malformed entry
is dropped rather than failing the whole, already signature-verified, refresh.
Revocation authority is signing authority. An entry only revokes a package whose
verifiedByKeyId equals the key that verified the deny-list's own catalog document. Core records a
verifiedByKeyId only for an archive that verifies against one of its compiled-in official keys,
so in practice only a catalog signed by the official key can revoke anything: a source pinned to
its own key can publish a denyList, but no installed package is ever tied to that key, so it
matches nothing. An unsigned or unverified package is revocable by nobody, because nobody core
knows vouched for it in the first place.
A denied version cannot be installed (PLUGIN_DENIED, 403, carrying the publisher's reason), and
cannot register at boot or on hot-reload either, with its own revoked failure reason. Like an
untrusted package, a revoked one is not treated as "installed but not running": its routes are
torn down entirely rather than answering 503, a revocation withdraws the authority to run at all,
it isn't reporting an outage.
Latency: a catalog refresh that lands a new entry stops every matching installed plugin and marks
it failed with the publisher's reason right there, the daily cycle or an immediate manual
refresh, never waiting for a reboot.
Key rotation#
For your own catalog's signing key:
- Generate a new Ed25519 keypair somewhere with access to your CI secrets, or a throwaway CI job.
- Keep the new public key next to every previous one you've ever used, never replacing a file, so anything a retired key signed stays verifiable.
- Put the new private key into whatever secret store your signing workflow reads from.
- Re-sign the catalog with the new key, and update the pinned key on each server's source: changing a source's key clears its cached catalog, and the next refresh verifies against the new key.
- If a key is ever compromised, publish that fact out of band (a release note, a pinned issue);
there's no
denyList-style mechanism for revoking a key itself, only for revoking specific packages a key signed.
The official release key is compiled into core and never removed: a signature made with a retired key keeps verifying for as long as the archive it signed might still be installed anywhere.