Plugins
Packaging and signing
The .fkplugin archive format, the cargo xtask build commands, what an Ed25519 signature actually covers, and how signing works for real distribution.
The archive format#
A .fkplugin file is a ZIP with a deliberately narrow, closed shape. Core refuses anything outside
it, by exact reason, rather than silently ignoring the unexpected part.
Legal entries (matched by exact name, no others allowed):
| Entry | Tier |
|---|---|
plugin.json |
Both, required |
plugin.json.sig |
Both, optional (its absence just means "unsigned") |
plugin.wasm |
process only, required for that tier and forbidden on data. It must be a WebAssembly component. |
logo.svg or logo.png |
Both, at most one |
Size and shape caps:
| Cap | Value |
|---|---|
| Entries per archive | 4 |
| Whole archive, compressed (upload or catalog fetch) | 33 MiB |
| Total uncompressed | 48 MiB |
plugin.wasm |
32 MiB |
plugin.json |
256 KiB |
plugin.json.sig |
256 bytes |
| Logo | 64 KiB |
| Compression ratio, per entry | 100:1 |
Only the store (no compression) and deflate compression methods are accepted; no ZIP64, no data
descriptors, no encrypted entries, no symlinks, no directory entries, no archive comment, and no
more than one end-of-central-directory record. Entry names must be NFC, free of control characters
and path separators, and unique even case-folded. A logo is checked by its bytes: PNG by its magic
bytes, SVG must be XML rooted at <svg> with no <script>, no on*= attribute and no
javascript:. Every one of these has its own refusal code; build your archive with a plain, boring
zip writer that stores files, which is what cargo xtask package does.
Refusal codes#
The guards run in this order and the first failure refuses the whole archive, before anything touches the disk.
| Code | Refused because |
|---|---|
PLUGIN_BAD_MAGIC |
The bytes don't start with a ZIP local header. |
PLUGIN_TOO_LARGE |
The archive, an entry, or the total is over its cap, or an inflated size contradicts the central directory. |
PLUGIN_TRAILING_DATA |
A second end-of-central-directory record. |
PLUGIN_MALFORMED_ARCHIVE |
The central directory can't be parsed. |
PLUGIN_ARCHIVE_COMMENT |
The archive has a comment. |
PLUGIN_TOO_MANY_ENTRIES |
More than 4 entries. |
PLUGIN_CONTROL_CHAR, PLUGIN_NOT_NFC, PLUGIN_PATH_SEPARATOR, PLUGIN_ABSOLUTE_PATH |
An entry name breaks the naming rules above. |
PLUGIN_DIRECTORY_ENTRY, PLUGIN_SYMLINK |
An entry is a directory, or a Unix file type other than regular. |
PLUGIN_DUPLICATE_ENTRY |
A duplicate name, exact or case-folded, or two logos. |
PLUGIN_UNEXPECTED_ENTRY |
A name outside plugin.json, plugin.json.sig, plugin.wasm, logo.svg, logo.png. |
PLUGIN_ZIP64, PLUGIN_DATA_DESCRIPTOR, PLUGIN_ENCRYPTED, PLUGIN_COMPRESSION_METHOD |
An unsupported ZIP feature. |
PLUGIN_RATIO |
A compression ratio above 100, or content from zero compressed bytes. |
PLUGIN_MANIFEST_TOO_LARGE |
plugin.json over 256 KiB. |
PLUGIN_BAD_SIGNATURE |
plugin.json.sig doesn't decode to exactly 64 bytes. |
PLUGIN_BAD_LOGO |
The logo isn't a safe PNG or SVG. |
The manifest, tier and file-set refusals that follow are in the manifest reference.
Building with cargo xtask#
A plugin repository keeps a tiny xtask crate over the SDK's build feature (see
Your first plugin). It has three commands:
cargo xtask build [<crate dir>]
cargo xtask package [<crate dir>] [--key <hex seed file>] [--out <dir>] [--max-mib <n>]
cargo xtask verify <archive> [--key <hex public key file>] [--max-mib <n>]build runs cargo build --release --target wasm32-wasip2 and prints the path of the component.
package does the whole job:
- Builds the release component.
- Writes
plugin.jsonfromplugin.template.json: the template plusversion(fromCargo.toml) andfiles, the sha256 ofplugin.wasmand of the logo. You never hand-writefiles. - Writes
<id>-<version>.fkplugininto--out(default.) as a deterministic archive: store-only, a fixed DOS timestamp, no archive comment, entries in a fixed order (plugin.json,plugin.json.sigif signed,plugin.wasm, the logo), so two builds of the same input are byte-identical. - Verifies it before writing it: core's own archive inspector, the
fileshashes, the size budget (--max-mib, default 32) and that the component imports only thepluginworld and exports onlyguest.
Without --key the archive is unsigned:
dist/example.hello-0.1.0.fkpluginThat is exactly right for local iteration (see Your first plugin) and exactly wrong for anything you intend other people to install.
What a signature actually covers#
The Ed25519 signature is over the exact raw bytes of plugin.json, and nothing else. Not the
zip, not plugin.wasm. The other files are covered indirectly: a process manifest's files map
holds their sha256 hashes, and those hashes are checked against the real bytes at install and at
every load, so a plugin.wasm that doesn't match its declared hash is PLUGIN_HASH_MISMATCH (at
load, the plugin fails as tampered), a separate failure from a bad signature.
plugin.json.sigis the base64 text of the raw 64-byte signature. Surrounding whitespace is trimmed first, so a trailing newline is fine. It must decode to exactly 64 bytes, or the archive is refused withPLUGIN_BAD_SIGNATUREbefore the manifest is even parsed.- The signature is checked against the compiled-in official public keys on core's side (today
one key,
release-2026). There is no registry of third-party keys built into core: the only way an archive becomesofficialtrust is a signature that verifies against one of those keys. Everything else isunverified(a 64-byte signature that verifies against no official key, whoever made it) orunsigned(no signature at all). - A
processarchive that is notofficialis refused withPLUGIN_UNSIGNEDunless the admin setting Allow unsigned plugins (plugins.allow_unsigned) is on. That holds forunverifiedas well asunsigned. The setting gates installs, not loads: turning it back off leaves a plugin already installed running; uninstall it instead. Adataarchive installs with any trust level, after the admin ticks the acknowledgement on the consent sheet. - An upgrade over a package that was verified by a key must carry the same key
(
PLUGIN_SIGNER_CHANGED, 409).
Sign the archived plugin.json, never your source template. cargo xtask package writes
the manifest with serde_json's pretty printer, so the archived bytes differ from
plugin.template.json byte for byte. A signature made over any other bytes will never verify.
Signing for development#
--key <hex seed file> signs the archive with a development key: a file holding 64 hex
characters, the 32-byte Ed25519 seed (openssl rand -hex 32 > dev.key makes one).
cargo xtask package --key dev.key --out distA development key is not one core trusts, so the archive is unverified on a real server and still
needs Allow unsigned plugins. The flag exists to exercise a signed archive's shape end to end.
cargo xtask package --key also makes the verification step trust that key's public half.
Signing for distribution#
A plugin other people install carries the signature of the official release key, made by the
catalog's Package plugin workflow from the unsigned archive your repository's release publishes:
it checks the archive against the manifest the catalog maintainers reviewed, signs plugin.json
with the catalog key, and replaces the release asset with the signed .fkplugin. The private half
of that key lives only in the catalog repository's secrets. See Publishing
for the whole flow, and why a plugin published on its own is unverified.
Quick packaging checklist#
-
plugin.template.jsonhas theid,pluginApi,fliksrange andruntime: "wasm"you mean, andCargo.toml'sversionis the version you are releasing. -
cargo xtask packagepasses: it verifies the archive, the world and the size budget. - You did not hand-write
files, and you did not sign your template. - The component is built with
opt-level = "s", LTO andstrip = true, so it fits well under the 32 MiB cap (the real plugins gate CI at 12 MiB with--max-mib 12). - You imported the archive on a dev instance with Allow unsigned plugins on and it reached
Active(see Testing and debugging).