🔌 halpradio Plugins & Official Registry

Official curated WebAssembly plugin registry and community extensions for halpradio 📻

---

🌟 Overview

halpradio features a military-grade, capability-based WebAssembly (Wasm) Plugin Architecture powered by tetratelabs/wazero (pure Go, zero Cgo dependencies).

Plugins allow developers to extend halpradio with custom integrations (e.g. smart light synchronizers, Discord/Slack webhooks, Last.fm scrobblers, hardware dials, and custom visualizers) while running in an isolated virtual machine with zero unauthorized access to your host filesystem, processes, or network.

---

📦 Official Curated Plugins

Plugin	Version	Permissions	Description
Webhook Broadcaster	1.0.0	Network, Storage, Events	Broadcasts now-playing tracks to Discord, Slack, or Home Assistant webhooks in real-time.
Scrobble Logger & Stats	1.0.0	Storage, Events (Offline)	Tracks total play counts, station listening history, and triggers milestone celebrations!

---

🛡️ Security & Sandboxing Architecture

1. Default-Deny Isolation:
   • WebAssembly guests have zero access to host sockets, filesystem, or OS environment variables by default.
2. Granular Manifest Permissions (manifest.yaml):
   • network: Whitelist of permitted domains or CIDRs (e.g. api.discord.com, 192.168.1.0/24).
   • storage: Sandboxed plugin-specific directory only (~/.config/halpradio/plugins_data/<plugin-id>/).
   • events: Specific lifecycle events (on_track_change, on_playback_change, on_timer_tick).
3. Interactive User Approval:
   • Users are prompted with an explicit permission review screen before an untrusted plugin can execute.
4. Cryptographic Verification:
   • SHA-256 integrity checksums are validated before executing any downloaded binary.

---

🚀 Using Plugins in halpradio

1. In-App Plugin Manager

• Press P (or <space>P) anywhere in halpradio to open the Plugin & Extension Manager.
• Switch to [2] 🌐 Official Registry using Tab or 2.
• Select a plugin and press Enter or i to install.
• Press y to review and approve permissions.

2. CLI Plugin Management

# List installed and available plugins
halpradio plugin list

# Install a plugin from the official registry
halpradio plugin install webhook-broadcaster

# Enable or disable a plugin
halpradio plugin enable webhook-broadcaster
halpradio plugin disable webhook-broadcaster

# Update installed plugins
halpradio plugin update --all

# Remove a plugin
halpradio plugin remove webhook-broadcaster

---

🧑‍💻 Developing a Plugin

1. Quickstart with Go

You can build a plugin using standard Go (1.21+):

# Clone the starter template
cp -r templates/go-plugin-starter my-plugin
cd my-plugin

# Compile to WebAssembly targeting wasip1
make build

2. Manifest Definition (manifest.yaml)

id: "my-plugin"
name: "My Custom Plugin"
version: "1.0.0"
author: "developer_name"
description: "A short description of what your plugin does."
homepage: "https://github.com/developer/my-plugin"
wasm_file: "plugin.wasm"
permissions:
  network:
    - "api.my-service.com"
  storage:
    - "local"
  events:
    - "on_track_change"
    - "on_playback_change"

3. Implementing Lifecycle Hooks (main.go)

package main

import (
	"fmt"
	"unsafe"
	"github.com/halpworld/halpradio-plugins/sdk/go/halpradiosdk"
)

func main() {}

//export on_track_change
func onTrackChange(ptr uint32, length uint32) uint32 {
	data := unsafe.Slice((*byte)(unsafe.Pointer(uintptr(ptr))), length)
	payload, _ := halpradiosdk.ParseTrackChange(data)

	halpradiosdk.Log(halpradiosdk.LogLevelInfo, fmt.Sprintf("Now Playing: %s - %s", payload.Artist, payload.Title))
	halpradiosdk.Flash(fmt.Sprintf("🎵 %s", payload.Title))
	return 0
}

4. Host API Reference

The halpradio runtime exposes the following host functions to guests:

Host Function	Signature	Capability Required
halpradio.log	(level, ptr, len)	None
halpradio.ui_notify	(title_ptr, title_len, msg_ptr, msg_len)	None
halpradio.ui_flash	(msg_ptr, msg_len)	None
halpradio.storage_get	(key_ptr, key_len, out_ptr, max_len) -> uint32	storage: ["local"]
halpradio.storage_set	(key_ptr, key_len, val_ptr, val_len) -> uint32	storage: ["local"]
halpradio.http_fetch	(url_ptr, url_len, method_ptr, method_len, body_ptr, body_len, out_ptr, max_len) -> uint32	network: ["domain"]

---

🤝 Submitting Your Plugin to the Registry

1. Fork this repository.
2. Create a folder under plugins/<your-plugin-id>/ containing your manifest.yaml, source code, Makefile, README.md, and compiled plugin.wasm.
3. Add your plugin entry to registry.json with description, tags, download URL, and SHA256 checksum.
4. Open a Pull Request! Our CI pipeline will build your plugin and verify security checks automatically.

---

📜 License

MIT License. Created with ❤️ for halpradio.