---
title: "WASM Plugins"
---

# WASM Plugins

HeliosProxy includes a WebAssembly plugin runtime behind the `wasm-plugins` Cargo feature (it pulls `wasmtime`, so it is off unless enabled). The first-party plugins, the `helios-plugin` CLI, and the `helios-plugin-abi` crate live in a separate repository.

A plugin's runtime configuration can also be pushed from outside the sandbox over the admin API — see [`/admin/kv/<plugin>/<key>`](/docs/proxy/admin-api/) — so budgets, region maps, mask rules and allowlists can be changed without a restart. Writes are bounded by the `[plugins]` `kv_max_*` caps documented in [Configuration](/docs/proxy/configuration/).

**Source on GitHub**: [`HeliosDB-Proxy-Plugins`](https://github.com/HeliosDatabase/HeliosDB-Proxy-Plugins)

## First-party plugins (8)

| Plugin | Purpose |
|---|---|
| [`cost-governor`](https://github.com/HeliosDatabase/HeliosDB-Proxy-Plugins/tree/main/cost-governor) | Per-tenant query cost budgets (minute / hour / day) |
| [`ai-classifier`](https://github.com/HeliosDatabase/HeliosDB-Proxy-Plugins/tree/main/ai-classifier) | Detects LLM-generated SQL via `application_name` + markers |
| [`token-budget`](https://github.com/HeliosDatabase/HeliosDB-Proxy-Plugins/tree/main/token-budget) | Per-(agent, model) cost gating for AI traffic |
| [`llm-guardrail`](https://github.com/HeliosDatabase/HeliosDB-Proxy-Plugins/tree/main/llm-guardrail) | Refuses dangerous SQL from AI traffic (DROP, missing WHERE, etc.) |
| [`pgvector-router`](https://github.com/HeliosDatabase/HeliosDB-Proxy-Plugins/tree/main/pgvector-router) | Routes pgvector top-K queries to a tagged vector replica |
| [`column-mask`](https://github.com/HeliosDatabase/HeliosDB-Proxy-Plugins/tree/main/column-mask) | Per-role column masking via SQL rewriting |
| [`audit-chain`](https://github.com/HeliosDatabase/HeliosDB-Proxy-Plugins/tree/main/audit-chain) | Hash-chained tamper-evident audit log |
| [`residency-router`](https://github.com/HeliosDatabase/HeliosDB-Proxy-Plugins/tree/main/residency-router) | Per-user data-residency routing |

## `helios-plugin` CLI

Pack, inspect, and verify WASM plugin artefacts as portable `.tar.gz`:

```bash
helios-plugin pack    --wasm <path> --name X --version 1.0 \
                      --hooks pre_query,post_query [--sig <path>] \
                      --out <path>
helios-plugin inspect <artefact.tar.gz>
helios-plugin verify  <artefact.tar.gz> --trust-root <dir>
```

Same Ed25519 trust-root format as the proxy loader. Interoperates with `openssl`/`signify`.

## Authoring a plugin

```rust
// my-plugin/src/lib.rs
use helios_plugin_abi::*;

#[hook(PreQuery)]
fn check_query(ctx: &HookContext) -> PreQueryResult {
    if ctx.sql.to_uppercase().contains("DROP TABLE") {
        return PreQueryResult::Block { reason: "DROP forbidden".into() };
    }
    PreQueryResult::Continue
}
```

Compile with `cargo build --release --target wasm32-wasi`. Sign and pack:

```bash
cargo helios-plugin sign --key signing.pem --input target/wasm32-wasi/release/my_plugin.wasm
helios-plugin pack --wasm target/wasm32-wasi/release/my_plugin.wasm --out my-plugin-1.0.0.tar.gz \
                   --name my-plugin --version 1.0.0 --hooks pre_query
```

Push to any OCI registry:

```bash
oras push registry.example.com/my-org/my-plugin:1.0.0 my-plugin-1.0.0.tar.gz
```

Reference in `proxy.toml`:

```toml
[[plugins]]
name        = "my-plugin"
source      = "oci://registry.example.com/my-org/my-plugin:1.0.0"
hooks       = ["pre_query"]
verify_with = "/etc/heliosproxy/plugin-keys"
```

## Host imports

The `helios-plugin-abi` crate provides safe Rust wrappers for the host imports:

| Wrapper | Host import | Purpose |
|---|---|---|
| `kv_read(key)` / `kv_write(key, val)` / `kv_remove(key)` | `env.kv_*` | Per-plugin namespaced KV store |
| `sha256_digest_hex(input)` | `env.sha256_hex` | Real SHA-256 (the host runs the audited `sha2` crate) |

Plugin KV namespaces are isolated by construction — Plugin A cannot read Plugin B's keys, even with a malicious key.