heliosproxy-plugin-pack

name	heliosproxy-plugin-pack
description	Use the `helios-plugin` CLI to pack, sign, inspect, and verify WASM plugin artefacts. OCI-style `.tar.gz` (manifest + .wasm + .sig). Generate Ed25519 keys with openssl. Use when the user says "pack a plugin", "sign WASM", "trust root", "helios-plugin", "OCI artefact".
allowed-tools	Bash(helios-plugin *), Bash(openssl *), Bash(tar *), Bash(sha256sum *), Bash(cargo *), Read
related	["heliosproxy-overview","heliosproxy-plugin-load","heliosproxy-plugin-catalog"]

Pack, sign, inspect plugins

Plugins ship as OCI-style .tar.gz artefacts containing a manifest.json, the plugin.wasm binary, and an optional plugin.sig (Ed25519). The helios-plugin CLI is the canonical tool for building, signing, and validating those artefacts.

When to use

• Building a fresh plugin from a Rust crate compiled to wasm32
• Signing an existing .wasm so the proxy's trust-root accepts it
• Inspecting a third-party .tar.gz before loading it
• Verifying a signature against a public key in CI

🟠 Mutating on disk (writes the artefact); 🔵 read-only on running proxy until the artefact is loaded (see heliosproxy-plugin-load).

Surfaces

Verb	Effect
helios-plugin pack	Build .tar.gz from .wasm + manifest fields
helios-plugin inspect	Print manifest, file list, SHA256s
helios-plugin verify	Check signature against a public key
openssl genpkey / openssl pkey	Generate / convert Ed25519 keys

The CLI binary lives in the sibling repo HDB-HeliosDB-Proxy-Plugins and installs alongside the proxy:

cargo install helios-plugin
helios-plugin --version

Recipes

Recipe 1: Generate an Ed25519 keypair

# Private key (keep secret)
openssl genpkey -algorithm Ed25519 -out plugin-publisher.key

# Public key (ship to operators as the trust root)
openssl pkey -in plugin-publisher.key -pubout -out plugin-publisher.pub

# View the public key as raw bytes (32) for embedding
openssl pkey -in plugin-publisher.pub -pubin -outform DER \
  | tail -c 32 | xxd -p -c 32

Both PEM and the trailing-32-bytes form are accepted by the proxy's [plugins].trust_root config — the loader auto-detects.

Recipe 2: Build a plugin from source (Rust → wasm)

git clone [e-mail]:HeliosDatabase/HeliosDB-Proxy-Plugins.git
cd HDB-HeliosDB-Proxy-Plugins
cargo build -p helios-plugin-cost-governor \
  --target wasm32-unknown-unknown --release

ls target/wasm32-unknown-unknown/release/
# helios_plugin_cost_governor.wasm   (≈120 KiB)

Note the underscore-vs-hyphen in the artefact name: cargo emits helios_plugin_cost_governor.wasm for crate helios-plugin-cost-governor.

Recipe 3: Pack + sign in one step

helios-plugin pack \
  --wasm   target/wasm32-unknown-unknown/release/helios_plugin_cost_governor.wasm \
  --name        helios-plugin-cost-governor \
  --version     0.1.0 \
  --description "Per-tenant cost / budget gate" \
  --hooks       pre_query,post_query \
  --license     Apache-2.0 \
  --sign-with   plugin-publisher.key \
  --output      cost-governor-0.1.0.tar.gz

Resulting .tar.gz layout:

manifest.json    — name, version, description, license, hooks, wasm_sha256, signature_sha256
plugin.wasm      — the compiled module
plugin.sig       — Ed25519 detached signature over plugin.wasm

Without --sign-with, the artefact has no plugin.sig and the proxy's trust_root policy decides whether to load (rejects by default; accepts when trust_root = "permissive").

Recipe 4: Inspect a foreign artefact before loading

helios-plugin inspect cost-governor-0.1.0.tar.gz

helios-plugin-cost-governor 0.1.0
  description: Per-tenant cost / budget gate
  license:     Apache-2.0
  hooks:       pre_query, post_query
  files:
    plugin.wasm  124904 bytes  sha256=8a3b1f...
    plugin.sig       64 bytes  sha256=f12a09...

The output is what the proxy logs at load time. If the file list includes anything beyond manifest.json, plugin.wasm, and plugin.sig, the loader rejects it.

Recipe 5: Verify a signature manually

helios-plugin verify cost-governor-0.1.0.tar.gz \
  --pubkey plugin-publisher.pub
# OK: signature valid for plugin-publisher.pub

Returns 0 on valid signature, non-zero on missing / mismatched. Useful in CI gates before publishing artefacts to a registry.

Recipe 6: Pack without signing (dev)

helios-plugin pack \
  --wasm  target/wasm32-unknown-unknown/release/my_plugin.wasm \
  --name  my-plugin \
  --version 0.0.1 \
  --hooks pre_query \
  --output my-plugin-dev.tar.gz

The proxy will refuse to load this unless [plugins].trust_root = "permissive" (dev-only) or trust_root = "" (no signature required).

Pitfalls

• tar.gz MUST contain only manifest.json, plugin.wasm, and optionally plugin.sig. Extra files cause the loader to reject. Don't tar -czf a directory with .DS_Store, Cargo.lock, etc.
• Signature is over plugin.wasm bytes only, not the full .tar.gz. So a signature is portable across re-packs as long as the .wasm doesn't change.
• PEM vs raw bytes for keys: the CLI handles both. The proxy's trust_root config accepts a path to a PEM file or a 64-char hex string. openssl pkey -in foo.pub -pubin -outform DER | tail -c 32 | xxd -p -c 32 produces the hex.
• Don't reuse signing keys across environments. One key per publisher per environment (dev, staging, prod). Compromise of one key doesn't taint others.
• Cargo emits underscore names, but plugin names in manifest.json should be hyphenated. Match the crate's declared name.
• --hooks must include exactly the export names the .wasm actually defines. Mismatch = the proxy loads but never invokes the hook. Verify with wasm-objdump -j Export your.wasm.

See also

• heliosproxy-plugin-load — drop the artefact into the proxy
• heliosproxy-plugin-catalog — what each first-party plugin does
• heliosproxy-config — [plugins].trust_root config
• Demo: demos/v0.4.0/05-plugin-signatures/ — sig demo
• Demo: demos/v0.4.0/06-plugin-oci/ — pack-and-load
• Demo: demos/v0.4.0/19-helios-plugin-cli/ — CLI walkthrough
• Sibling repo: https://github.com/HeliosDatabase/HeliosDB-Proxy-Plugins
• Code: src/plugins/loader.rs — verifier