Developer docs/Guides

Security model

• Addons run in a wasmtime sandbox. Memory, fuel and time are limited, and there is no ambient file, network or process access.
• Everything an addon can reach is declared in addon.json under capabilities and approved by an admin at install. The host checks each call against what was approved.
• Some capabilities are marked dangerous. The installer shows them prominently.
• Iframe UI needs a separate explicit approval. Frames are sandboxed and can only call the API paths listed in capabilities.bridge.
• Outbound HTTP only reaches the hosts listed in capabilities.http. Link-local and cloud metadata addresses are always refused.
• Hook payloads redact password fields, and the host restores any redacted value a hook tries to overwrite. Money fields can only change with money.modify.
• Package files are hashed (files map). Use pelty-cli addon hash after every change.

#Capabilities

Capabilities approved at install (from addon.json).

Source: crates/pelty-wasm/src/runtime.rs (Capabilities).

#Hook

A pre-event subscription: the host calls call("hook", {event, payload}) before the action and the addon may continue, cancel or modify it.

Source: crates/pelty-wasm/src/runtime.rs (Hook).

#Mixin

A mixin: wraps an approved host operation (an API route template such as POST /api/v1/client/orders). at: before (rewrite the input), after (rewrite the output within its schema), around (both, with shared state) or return (replace the output, same schema).

Source: crates/pelty-wasm/src/runtime.rs (Mixin).

#Route

An addon HTTP route. access: admin (needs permission), client (any signed-in user) or public.

Source: crates/pelty-wasm/src/runtime.rs (Route).

#Job

A background job op; every_secs > 0 also runs it on a schedule.

Source: crates/pelty-wasm/src/runtime.rs (Job).

#MoneyCaps

Source: crates/pelty-wasm/src/runtime.rs (MoneyCaps).

#DbCaps

Source: crates/pelty-wasm/src/runtime.rs (DbCaps).

#Dangerous capabilities

    /// Capabilities shown with a red warning at install; the admin must tick
    /// each one (`approve` list in the install request).
    pub fn dangerous(&self) -> Vec<&'static str> {
        let mut v = vec![];
        if self.iframe() {
            v.push("ui.iframe");
        }
        if self.iframe_same_origin() {
            v.push("ui.iframe.same_origin");
        }
        if self.http.iter().any(|h| h == "*") {
            v.push("http.any");
        }
        if self.http_private {
            v.push("http.private");
        }
        if self.money.modify {
            v.push("money.modify");
        }
        if !self.db.read.is_empty() {
            v.push("db.read");
        }
        if !self.db.write.is_empty() {
            v.push("db.write");
        }
        if self.db.sql {
            v.push("db.sql");
        }
        if self.fs {
            v.push("fs");
        }
        if !self.exec.is_empty() {
            v.push("exec");
        }
        if self.auth_provider {
            v.push("auth.provider");
        }
        if self.hooks.iter().any(|h| is_request_pattern(split_phase(&h.event).1)) {
            v.push("hooks.any");
        }
        if !self.mixins.is_empty() {
            v.push("mixins");
        }
        if self.mixins.iter().any(|m| m.at == "return" || m.at == "around") {
            v.push("mixins.return");
        }
        v
    }

#Package permissions

Coarse package permissions in addon.json permissions (shown at install):

• payments.process
• provisioning.manage
• domains.manage
• network.outbound
• db.migrate
• ui.extend

Addon kinds: provisioning, gateway, registrar, theme, plugin, captcha, sso, integration.