Packaging, signing and publishing

Applies to: StablEdge Desktop 0.4.4

Plugins are distributed as .seplugin packages. The packager validates the manifest, computes the SHA-256 of every file in files, and signs the manifest when a publisher key is available. Do not rename an ordinary ZIP, write hashes by hand or fake a signature instead of using the packager.

Packaging in the desktop app

Plugin creation mode in the desktop app covers the whole loop:

1. Choose the source folder: pick the <plugin directory> that holds plugin.json and payload/.
2. Check the project: run every check on the manifest schema, sealed file set, icon, interface word lists and Skill files; a failure returns a structured error code.
3. Pack the project: write out the .seplugin.
4. Start the preview, or install into the preview environment: debug by installing directly, without distributing the package by hand.

In a chat the Agent can also call the host's plugin_pack tool to do the same thing, with source_dir (the source folder) and output_path (a path ending in .seplugin). To check without packing, point output_path at a temporary file.

What packaging checks

• The manifest matches the v3 schema, with no unknown contribution type, permission, worker or service.
• The entry files for the interface, Skills and worker exist.
• files is sealed and the hashes are right, with no duplicate ZIP entry, path escape or symbolic link.
• Package size, file count, single file size and unpacked size are all within limits.
• The icon is a 200×200 PNG no larger than 500 KiB.
• The interface word lists are well formed and the Skill files follow the specification.
• Permission combinations are valid (see combination rules).

Signing

The signature algorithm is Ed25519. What gets signed is a fixed domain separation prefix followed by the manifest, without the signature field, as JSON normalized by JCS; publisher_key_id is the SHA-256 of the publisher's public key.

• When packaging in the desktop app, the host signs with the publisher key on this machine. The private key stays on the machine and is never exported to a folder, an argument, a log or the Agent's context.
• Changing any file under payload/ after signing invalidates the hashes and the signature, so the package has to be packed again.
• Do not write signature or publisher_key_id into the manifest by hand; the two must appear as a pair and are produced by the packager.

Source and trust

An official signature says only where a plugin came from. It grants no permission automatically and does not approve a trusted worker or This-computer mode by itself. Some capabilities, ai_runtime among them, are open to the official source only.

Install process

1. You double-click the .seplugin, or choose Install plugin on the Plugins page, and the install preview opens.
2. The host unpacks the package into a temporary folder and checks the schema, platform, minimum version, file hashes and signature.
3. The install preview shows the source, required permissions, optional workspace permissions, declared network access, trusted workers, and the worker permissions granted after install.
4. Once you confirm, the host replaces the older version in one step and registers the plugin. A new plugin is disabled by default.

If the publisher changes during an upgrade, the install is refused with PLUGIN_PUBLISHER_CHANGED. A plugin's data (KV, Blob) is generally kept as long as plugin_id and workspace_id stay the same.

Global Worker service packages

A global Worker service uses a separate .seworker package. It must be installed and enabled first before a plugin that depends on it can resolve it, and a plugin cannot download or install a service itself.

Checklist before release

1. Check the package and confirm there are no errors.
2. In the install preview, confirm the source, permissions, network declarations and trusted workers are what you expect.
3. Enable the plugin, open the workspace, and confirm ready, KV reads and writes and snapshot publication all work.
4. If you declared drag and drop, test dropping files in; if you bound an Agent, test reads and actions and confirm the snapshot version goes up.
5. Test worker calls and cancellation.
6. Revoke permissions, disable and uninstall, and confirm the plugin handles it and leaves nothing behind.