From 30dfdda3ed4117cbb55343a4d18b7e000e53758d Mon Sep 17 00:00:00 2001 From: KingKDot Date: Mon, 22 Jun 2026 10:52:27 -0500 Subject: [PATCH] plugins 2.0 update --- .gitignore | 2 + .../cmd/agent/handlers/plugin_load.go | 2 + Overlord-Client/cmd/agent/plugins/manager.go | 12 +- Overlord-Client/cmd/agent/plugins/types.go | 73 ++- .../cmd/agent/plugins/wasm_runtime.go | 511 ++++++++++++++++++ .../cmd/agent/plugins/wasm_runtime_test.go | 41 ++ Overlord-Client/go.mod | 3 +- Overlord-Client/go.sum | 6 +- Overlord-Server/public/assets/main.js | 88 ++- Overlord-Server/public/assets/plugins.js | 145 ++++- Overlord-Server/src/main-server.ts | 9 +- Overlord-Server/src/protocol.ts | 14 + .../src/server/plugin-state-bundle.test.ts | 72 ++- .../src/server/plugin-state-bundle.ts | 246 ++++++++- .../src/server/routes/plugin-routes.ts | 88 ++- plugins/PLUGINS.md | 329 ++++++++--- .../build.bat} | 3 +- .../{build-plugin-c.sh => sample-c/build.sh} | 2 +- .../build.bat} | 3 +- .../build.sh} | 2 +- plugins/sample-go/README.md | 7 +- .../{build-plugin.bat => sample-go/build.bat} | 5 +- .../{build-plugin.sh => sample-go/build.sh} | 5 +- .../build.bat} | 3 +- .../build.sh} | 2 +- plugins/sample-ts-fullstack/README.md | 9 + plugins/sample-ts-fullstack/build.bat | 60 ++ .../sample-ts-fullstack.css | 3 + .../sample-ts-fullstack.html | 11 + plugins/sample-ts-fullstack/src/server.ts | 41 ++ plugins/sample-ts-fullstack/src/shared.ts | 10 + plugins/sample-ts-fullstack/src/ui.ts | 39 ++ plugins/sample-wasm-hostinfo/README.md | 5 + plugins/sample-wasm-hostinfo/build.bat | 55 ++ plugins/sample-wasm-hostinfo/native/main.go | 93 ++++ .../sample-wasm-hostinfo.css | 22 + .../sample-wasm-hostinfo.html | 12 + .../sample-wasm-hostinfo.js | 93 ++++ plugins/sample-wasm-platform-note/README.md | 11 + plugins/sample-wasm-platform-note/build.bat | 76 +++ .../native/Cargo.lock | 7 + .../native/Cargo.toml | 8 + .../native/src/lib.rs | 131 +++++ .../native/target/.rustc_info.json | 1 + .../native/target/CACHEDIR.TAG | 3 + .../native/target/wasm32-wasip1/CACHEDIR.TAG | 3 + .../sample-wasm-platform-note.css | 22 + .../sample-wasm-platform-note.html | 12 + .../sample-wasm-platform-note.js | 93 ++++ plugins/sample-wasm/README.md | 9 + plugins/sample-wasm/build.bat | 60 ++ plugins/sample-wasm/native/sample_wasm.c | 69 +++ plugins/sample-wasm/sample-wasm.css | 3 + plugins/sample-wasm/sample-wasm.html | 6 + plugins/sample-wasm/sample-wasm.js | 22 + 55 files changed, 2534 insertions(+), 128 deletions(-) create mode 100644 Overlord-Client/cmd/agent/plugins/wasm_runtime.go create mode 100644 Overlord-Client/cmd/agent/plugins/wasm_runtime_test.go rename plugins/{build-plugin-c.bat => sample-c/build.bat} (98%) rename plugins/{build-plugin-c.sh => sample-c/build.sh} (98%) rename plugins/{build-plugin-cpp.bat => sample-cpp/build.bat} (98%) rename plugins/{build-plugin-cpp.sh => sample-cpp/build.sh} (98%) rename plugins/{build-plugin.bat => sample-go/build.bat} (95%) rename plugins/{build-plugin.sh => sample-go/build.sh} (90%) rename plugins/{build-plugin-rust.bat => sample-rust/build.bat} (98%) rename plugins/{build-plugin-rust.sh => sample-rust/build.sh} (98%) create mode 100644 plugins/sample-ts-fullstack/README.md create mode 100644 plugins/sample-ts-fullstack/build.bat create mode 100644 plugins/sample-ts-fullstack/sample-ts-fullstack.css create mode 100644 plugins/sample-ts-fullstack/sample-ts-fullstack.html create mode 100644 plugins/sample-ts-fullstack/src/server.ts create mode 100644 plugins/sample-ts-fullstack/src/shared.ts create mode 100644 plugins/sample-ts-fullstack/src/ui.ts create mode 100644 plugins/sample-wasm-hostinfo/README.md create mode 100644 plugins/sample-wasm-hostinfo/build.bat create mode 100644 plugins/sample-wasm-hostinfo/native/main.go create mode 100644 plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.css create mode 100644 plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.html create mode 100644 plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.js create mode 100644 plugins/sample-wasm-platform-note/README.md create mode 100644 plugins/sample-wasm-platform-note/build.bat create mode 100644 plugins/sample-wasm-platform-note/native/Cargo.lock create mode 100644 plugins/sample-wasm-platform-note/native/Cargo.toml create mode 100644 plugins/sample-wasm-platform-note/native/src/lib.rs create mode 100644 plugins/sample-wasm-platform-note/native/target/.rustc_info.json create mode 100644 plugins/sample-wasm-platform-note/native/target/CACHEDIR.TAG create mode 100644 plugins/sample-wasm-platform-note/native/target/wasm32-wasip1/CACHEDIR.TAG create mode 100644 plugins/sample-wasm-platform-note/sample-wasm-platform-note.css create mode 100644 plugins/sample-wasm-platform-note/sample-wasm-platform-note.html create mode 100644 plugins/sample-wasm-platform-note/sample-wasm-platform-note.js create mode 100644 plugins/sample-wasm/README.md create mode 100644 plugins/sample-wasm/build.bat create mode 100644 plugins/sample-wasm/native/sample_wasm.c create mode 100644 plugins/sample-wasm/sample-wasm.css create mode 100644 plugins/sample-wasm/sample-wasm.html create mode 100644 plugins/sample-wasm/sample-wasm.js diff --git a/.gitignore b/.gitignore index 5ba66fd..82b3d1e 100644 --- a/.gitignore +++ b/.gitignore @@ -513,3 +513,5 @@ FodyWeavers.xsd *.exp *.lib save.txt +*.wasm +Albedo/* \ No newline at end of file diff --git a/Overlord-Client/cmd/agent/handlers/plugin_load.go b/Overlord-Client/cmd/agent/handlers/plugin_load.go index 3d05d09..366af5b 100644 --- a/Overlord-Client/cmd/agent/handlers/plugin_load.go +++ b/Overlord-Client/cmd/agent/handlers/plugin_load.go @@ -7,6 +7,7 @@ import ( "errors" "fmt" "io" + "log" "net/http" "net/url" "os" @@ -89,6 +90,7 @@ func HandlePluginLoadHTTP(ctx context.Context, env *agentRuntime.Env, cmdID stri } if err := env.Plugins.Load(ctx, manifest, binary); err != nil { + log.Printf("[plugin] load failed %s: %v", manifest.ID, err) _ = wire.WriteMsg(ctx, env.Conn, wire.PluginEvent{Type: "plugin_event", PluginID: manifest.ID, Event: "error", Error: err.Error()}) return wire.WriteMsg(ctx, env.Conn, wire.CommandResult{Type: "command_result", CommandID: cmdID, OK: false, Message: err.Error()}) } diff --git a/Overlord-Client/cmd/agent/plugins/manager.go b/Overlord-Client/cmd/agent/plugins/manager.go index 4d246c1..f78a698 100644 --- a/Overlord-Client/cmd/agent/plugins/manager.go +++ b/Overlord-Client/cmd/agent/plugins/manager.go @@ -21,7 +21,7 @@ type Manager struct { type pluginInstance struct { id string manifest PluginManifest - native NativePlugin + native PluginRuntime } func NewManager(writer wire.Writer, host HostInfo) *Manager { @@ -49,7 +49,13 @@ func (m *Manager) Load(ctx context.Context, manifest PluginManifest, binary []by } m.mu.Unlock() - np, err := loadNativePlugin(binary) + var np PluginRuntime + var err error + if manifest.RuntimeKind == "wasm" || manifest.WASM != "" { + np, err = loadWASMPlugin(ctx, manifest, binary) + } else { + np, err = loadNativePlugin(binary) + } if err != nil { return err } @@ -107,7 +113,7 @@ func (m *Manager) Load(ctx context.Context, manifest PluginManifest, binary []by rt := np.Runtime() freeable := rt != "go" - log.Printf("[plugin] loaded %s (native, runtime=%s, freeable=%v)", pluginID, rt, freeable) + log.Printf("[plugin] loaded %s (runtime=%s, freeable=%v)", pluginID, rt, freeable) return nil } diff --git a/Overlord-Client/cmd/agent/plugins/types.go b/Overlord-Client/cmd/agent/plugins/types.go index 810863e..66a6af6 100644 --- a/Overlord-Client/cmd/agent/plugins/types.go +++ b/Overlord-Client/cmd/agent/plugins/types.go @@ -11,14 +11,28 @@ type PluginAssets struct { type PluginManifest struct { ID string `msgpack:"id" json:"id"` Name string `msgpack:"name" json:"name"` + APIVersion int `msgpack:"apiVersion,omitempty" json:"apiVersion,omitempty"` + RuntimeKind string `msgpack:"runtime,omitempty" json:"runtime,omitempty"` Version string `msgpack:"version,omitempty" json:"version,omitempty"` Description string `msgpack:"description,omitempty" json:"description,omitempty"` Binary string `msgpack:"binary,omitempty" json:"binary,omitempty"` Binaries map[string]string `msgpack:"binaries,omitempty" json:"binaries,omitempty"` + WASM string `msgpack:"wasm,omitempty" json:"wasm,omitempty"` + Needs PluginNeeds `msgpack:"needs,omitempty" json:"needs,omitempty"` Entry string `msgpack:"entry,omitempty" json:"entry,omitempty"` Assets PluginAssets `msgpack:"assets,omitempty" json:"assets,omitempty"` } +type PluginNeeds struct { + Files []PluginFileNeed `msgpack:"files,omitempty" json:"files,omitempty"` +} + +type PluginFileNeed struct { + Bucket string `msgpack:"bucket" json:"bucket"` + Access []string `msgpack:"access" json:"access"` + Reason string `msgpack:"reason,omitempty" json:"reason,omitempty"` +} + type PluginMessage struct { Type string `msgpack:"type"` Event string `msgpack:"event,omitempty"` @@ -33,7 +47,7 @@ type HostInfo struct { Version string `msgpack:"version" json:"version"` } -type NativePlugin interface { +type PluginRuntime interface { Load(send func(event string, payload []byte), hostInfo []byte) error Event(event string, payload []byte) error @@ -45,13 +59,18 @@ type NativePlugin interface { Runtime() string } +type NativePlugin = PluginRuntime + func ManifestFromMap(m map[string]interface{}) (PluginManifest, error) { manifest := PluginManifest{} manifest.ID = stringVal(m["id"]) manifest.Name = stringVal(m["name"]) + manifest.APIVersion = intVal(m["apiVersion"]) + manifest.RuntimeKind = stringVal(m["runtime"]) manifest.Version = stringVal(m["version"]) manifest.Description = stringVal(m["description"]) manifest.Binary = stringVal(m["binary"]) + manifest.WASM = stringVal(m["wasm"]) manifest.Entry = stringVal(m["entry"]) if binariesRaw, ok := m["binaries"].(map[string]interface{}); ok { @@ -70,6 +89,27 @@ func ManifestFromMap(m map[string]interface{}) (PluginManifest, error) { JS: stringVal(assetsRaw["js"]), } } + if needsRaw, ok := m["needs"].(map[string]interface{}); ok { + if filesRaw, ok := needsRaw["files"].([]interface{}); ok { + for _, item := range filesRaw { + fileRaw, ok := item.(map[string]interface{}) + if !ok { + continue + } + need := PluginFileNeed{Bucket: stringVal(fileRaw["bucket"]), Reason: stringVal(fileRaw["reason"])} + if accessRaw, ok := fileRaw["access"].([]interface{}); ok { + for _, v := range accessRaw { + if s, ok := v.(string); ok && s != "" { + need.Access = append(need.Access, s) + } + } + } + if need.Bucket != "" && len(need.Access) > 0 { + manifest.Needs.Files = append(manifest.Needs.Files, need) + } + } + } + } if manifest.ID == "" { return PluginManifest{}, errors.New("missing plugin id") @@ -84,3 +124,34 @@ func stringVal(v interface{}) string { s, _ := v.(string) return s } + +func intVal(v interface{}) int { + switch n := v.(type) { + case int: + return n + case int8: + return int(n) + case int16: + return int(n) + case int32: + return int(n) + case int64: + return int(n) + case uint: + return int(n) + case uint8: + return int(n) + case uint16: + return int(n) + case uint32: + return int(n) + case uint64: + return int(n) + case float32: + return int(n) + case float64: + return int(n) + default: + return 0 + } +} diff --git a/Overlord-Client/cmd/agent/plugins/wasm_runtime.go b/Overlord-Client/cmd/agent/plugins/wasm_runtime.go new file mode 100644 index 0000000..d2cf6e7 --- /dev/null +++ b/Overlord-Client/cmd/agent/plugins/wasm_runtime.go @@ -0,0 +1,511 @@ +package plugins + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "strings" + "sync" + + "github.com/tetratelabs/wazero" + "github.com/tetratelabs/wazero/api" + "github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1" +) + +const maxWASMFileReadBytes = 32 * 1024 * 1024 + +type wasmPlugin struct { + ctx context.Context + cancel context.CancelFunc + runtime wazero.Runtime + module api.Module + manifest PluginManifest + hostInfo []byte + send func(string, []byte) + mu sync.Mutex + acl map[string]map[string]bool +} + +func loadWASMPlugin(parent context.Context, manifest PluginManifest, data []byte) (PluginRuntime, error) { + if len(data) == 0 { + return nil, errors.New("empty wasm plugin module") + } + ctx, cancel := context.WithCancel(parent) + rt := wazero.NewRuntime(ctx) + wp := &wasmPlugin{ + ctx: ctx, + cancel: cancel, + runtime: rt, + manifest: manifest, + acl: buildFileACL(manifest.Needs), + } + + wasi_snapshot_preview1.MustInstantiate(ctx, rt) + if err := wp.instantiateHostModule("env"); err != nil { + cancel() + _ = rt.Close(ctx) + return nil, err + } + if err := wp.instantiateHostModule("overlord"); err != nil { + cancel() + _ = rt.Close(ctx) + return nil, err + } + + mod, err := rt.InstantiateWithConfig(ctx, data, wazero.NewModuleConfig(). + WithName(manifest.ID). + WithStartFunctions("_initialize")) + if err != nil { + cancel() + _ = rt.Close(ctx) + return nil, fmt.Errorf("wasm instantiate: %w", err) + } + wp.module = mod + return wp, nil +} + +func (p *wasmPlugin) instantiateHostModule(name string) error { + builder := p.runtime.NewHostModuleBuilder(name) + export := func(name string, params []api.ValueType, results []api.ValueType, fn api.GoModuleFunc) { + builder.NewFunctionBuilder().WithGoModuleFunction(fn, params, results).Export(name) + } + + export("overlord_emit", + []api.ValueType{api.ValueTypeI32, api.ValueTypeI32, api.ValueTypeI32, api.ValueTypeI32}, + []api.ValueType{api.ValueTypeI32}, + func(ctx context.Context, mod api.Module, stack []uint64) { + event, ok := readWASMBytes(mod, uint32(stack[0]), uint32(stack[1])) + if !ok { + stack[0] = wasmStatus(statusInvalid) + return + } + payload, ok := readWASMBytes(mod, uint32(stack[2]), uint32(stack[3])) + if !ok { + stack[0] = wasmStatus(statusInvalid) + return + } + if p.send != nil { + p.send(string(event), payload) + } + stack[0] = 0 + }) + export("overlord_host_info", + []api.ValueType{api.ValueTypeI32, api.ValueTypeI32}, + []api.ValueType{api.ValueTypeI32}, + func(ctx context.Context, mod api.Module, stack []uint64) { + stack[0] = wasmStatus(writeWASMOutput(mod, uint32(stack[0]), uint32(stack[1]), p.hostInfo)) + }) + + export("overlord_fs_stat", fsReadParams(), []api.ValueType{api.ValueTypeI32}, p.fsStat) + export("overlord_fs_list", fsReadParams(), []api.ValueType{api.ValueTypeI32}, p.fsList) + export("overlord_fs_read", fsReadParams(), []api.ValueType{api.ValueTypeI32}, p.fsRead) + export("overlord_fs_write", + []api.ValueType{api.ValueTypeI32, api.ValueTypeI32, api.ValueTypeI32, api.ValueTypeI32, api.ValueTypeI32, api.ValueTypeI32}, + []api.ValueType{api.ValueTypeI32}, + p.fsWrite) + export("overlord_fs_delete", + []api.ValueType{api.ValueTypeI32, api.ValueTypeI32, api.ValueTypeI32, api.ValueTypeI32}, + []api.ValueType{api.ValueTypeI32}, + p.fsDelete) + export("overlord_fs_mkdir", + []api.ValueType{api.ValueTypeI32, api.ValueTypeI32, api.ValueTypeI32, api.ValueTypeI32}, + []api.ValueType{api.ValueTypeI32}, + p.fsMkdir) + + _, err := builder.Instantiate(p.ctx) + return err +} + +func fsReadParams() []api.ValueType { + return []api.ValueType{ + api.ValueTypeI32, api.ValueTypeI32, // bucket + api.ValueTypeI32, api.ValueTypeI32, // path + api.ValueTypeI32, api.ValueTypeI32, // output buffer + } +} + +func (p *wasmPlugin) Load(send func(string, []byte), hostInfo []byte) error { + p.mu.Lock() + defer p.mu.Unlock() + p.send = send + p.hostInfo = append(p.hostInfo[:0], hostInfo...) + return p.callBytes("overlord_on_load", hostInfo) +} + +func (p *wasmPlugin) Event(event string, payload []byte) error { + p.mu.Lock() + defer p.mu.Unlock() + eventPtr, err := p.writeGuestBytes([]byte(event)) + if err != nil { + return err + } + payloadPtr, err := p.writeGuestBytes(payload) + if err != nil { + p.freeGuestBytes(eventPtr, uint32(len(event))) + return err + } + fn := p.module.ExportedFunction("overlord_on_event") + if fn == nil { + p.freeGuestBytes(eventPtr, uint32(len(event))) + p.freeGuestBytes(payloadPtr, uint32(len(payload))) + return errors.New("missing export: overlord_on_event") + } + results, err := fn.Call(p.ctx, uint64(eventPtr), uint64(len(event)), uint64(payloadPtr), uint64(len(payload))) + p.freeGuestBytes(eventPtr, uint32(len(event))) + p.freeGuestBytes(payloadPtr, uint32(len(payload))) + if err != nil { + return err + } + if len(results) > 0 && int32(uint32(results[0])) != 0 { + return fmt.Errorf("overlord_on_event returned %d", int32(uint32(results[0]))) + } + return nil +} + +func (p *wasmPlugin) Unload() { + p.mu.Lock() + defer p.mu.Unlock() + if p.module == nil { + return + } + if fn := p.module.ExportedFunction("overlord_on_unload"); fn != nil { + _, _ = fn.Call(p.ctx) + } +} + +func (p *wasmPlugin) Close() error { + p.Unload() + p.cancel() + if p.runtime != nil { + return p.runtime.Close(context.Background()) + } + return nil +} + +func (p *wasmPlugin) Runtime() string { + return "wasm" +} + +func (p *wasmPlugin) callBytes(export string, data []byte) error { + ptr, err := p.writeGuestBytes(data) + if err != nil { + return err + } + defer p.freeGuestBytes(ptr, uint32(len(data))) + fn := p.module.ExportedFunction(export) + if fn == nil { + return fmt.Errorf("missing export: %s", export) + } + results, err := fn.Call(p.ctx, uint64(ptr), uint64(len(data))) + if err != nil { + return err + } + if len(results) > 0 && int32(uint32(results[0])) != 0 { + return fmt.Errorf("%s returned %d", export, int32(uint32(results[0]))) + } + return nil +} + +func (p *wasmPlugin) writeGuestBytes(data []byte) (uint32, error) { + alloc := p.module.ExportedFunction("overlord_alloc") + if alloc == nil { + return 0, errors.New("missing export: overlord_alloc") + } + results, err := alloc.Call(p.ctx, uint64(len(data))) + if err != nil { + return 0, err + } + if len(results) == 0 || uint32(results[0]) == 0 { + return 0, errors.New("overlord_alloc returned null") + } + ptr := uint32(results[0]) + if len(data) > 0 && !p.module.Memory().Write(ptr, data) { + p.freeGuestBytes(ptr, uint32(len(data))) + return 0, errors.New("wasm memory write failed") + } + return ptr, nil +} + +func (p *wasmPlugin) freeGuestBytes(ptr uint32, size uint32) { + if ptr == 0 { + return + } + if free := p.module.ExportedFunction("overlord_free"); free != nil { + _, _ = free.Call(p.ctx, uint64(ptr), uint64(size)) + } +} + +type wasmFileStat struct { + Path string `json:"path"` + IsDir bool `json:"isDir"` + Size int64 `json:"size"` + ModTime int64 `json:"modTime"` + Mode string `json:"mode"` +} + +func (p *wasmPlugin) fsStat(ctx context.Context, mod api.Module, stack []uint64) { + target, status := p.resolveFromStack(mod, stack, "read") + if status != statusOK { + stack[0] = wasmStatus(status) + return + } + st, err := os.Stat(target) + if err != nil { + stack[0] = wasmStatus(statusNotFound) + return + } + info := wasmFileStat{Path: target, IsDir: st.IsDir(), Size: st.Size(), ModTime: st.ModTime().UnixMilli(), Mode: st.Mode().String()} + p.writeJSONResult(mod, stack, info) +} + +func (p *wasmPlugin) fsList(ctx context.Context, mod api.Module, stack []uint64) { + target, status := p.resolveFromStack(mod, stack, "list") + if status != statusOK { + stack[0] = wasmStatus(status) + return + } + entries, err := os.ReadDir(target) + if err != nil { + stack[0] = wasmStatus(statusIO) + return + } + out := make([]wasmFileStat, 0, len(entries)) + for _, ent := range entries { + st, err := ent.Info() + if err != nil { + continue + } + out = append(out, wasmFileStat{Path: ent.Name(), IsDir: ent.IsDir(), Size: st.Size(), ModTime: st.ModTime().UnixMilli(), Mode: st.Mode().String()}) + } + p.writeJSONResult(mod, stack, out) +} + +func (p *wasmPlugin) fsRead(ctx context.Context, mod api.Module, stack []uint64) { + target, status := p.resolveFromStack(mod, stack, "read") + if status != statusOK { + stack[0] = wasmStatus(status) + return + } + st, err := os.Stat(target) + if err != nil || st.IsDir() { + stack[0] = wasmStatus(statusNotFound) + return + } + if st.Size() > maxWASMFileReadBytes { + stack[0] = wasmStatus(statusTooLarge) + return + } + data, err := os.ReadFile(target) + if err != nil { + stack[0] = wasmStatus(statusIO) + return + } + stack[0] = wasmStatus(writeWASMOutput(mod, uint32(stack[4]), uint32(stack[5]), data)) +} + +func (p *wasmPlugin) fsWrite(ctx context.Context, mod api.Module, stack []uint64) { + target, status := p.resolvePath(mod, uint32(stack[0]), uint32(stack[1]), uint32(stack[2]), uint32(stack[3]), "write") + if status != statusOK { + stack[0] = wasmStatus(status) + return + } + data, ok := readWASMBytes(mod, uint32(stack[4]), uint32(stack[5])) + if !ok { + stack[0] = wasmStatus(statusInvalid) + return + } + if err := os.MkdirAll(filepath.Dir(target), 0o700); err != nil { + stack[0] = wasmStatus(statusIO) + return + } + if err := os.WriteFile(target, data, 0o600); err != nil { + stack[0] = wasmStatus(statusIO) + return + } + stack[0] = 0 +} + +func (p *wasmPlugin) fsDelete(ctx context.Context, mod api.Module, stack []uint64) { + target, status := p.resolvePath(mod, uint32(stack[0]), uint32(stack[1]), uint32(stack[2]), uint32(stack[3]), "delete") + if status != statusOK { + stack[0] = wasmStatus(status) + return + } + if err := os.RemoveAll(target); err != nil { + stack[0] = wasmStatus(statusIO) + return + } + stack[0] = 0 +} + +func (p *wasmPlugin) fsMkdir(ctx context.Context, mod api.Module, stack []uint64) { + target, status := p.resolvePath(mod, uint32(stack[0]), uint32(stack[1]), uint32(stack[2]), uint32(stack[3]), "mkdir") + if status != statusOK { + stack[0] = wasmStatus(status) + return + } + if err := os.MkdirAll(target, 0o700); err != nil { + stack[0] = wasmStatus(statusIO) + return + } + stack[0] = 0 +} + +func (p *wasmPlugin) resolveFromStack(mod api.Module, stack []uint64, op string) (string, int32) { + return p.resolvePath(mod, uint32(stack[0]), uint32(stack[1]), uint32(stack[2]), uint32(stack[3]), op) +} + +func (p *wasmPlugin) resolvePath(mod api.Module, bucketPtr, bucketLen, pathPtr, pathLen uint32, op string) (string, int32) { + bucketBytes, ok := readWASMBytes(mod, bucketPtr, bucketLen) + if !ok { + return "", statusInvalid + } + pathBytes, ok := readWASMBytes(mod, pathPtr, pathLen) + if !ok { + return "", statusInvalid + } + bucket := string(bucketBytes) + rel := string(pathBytes) + if !p.acl[bucket][op] { + return "", statusDenied + } + return resolvePluginBucketPath(p.manifest.ID, bucket, rel) +} + +func resolvePluginBucketPath(pluginID, bucket, rel string) (string, int32) { + if strings.ContainsRune(rel, 0) { + return "", statusInvalid + } + if bucket == "fullDisk" { + if rel == "" { + if filepath.Separator == '\\' { + return filepath.VolumeName(os.TempDir()) + string(filepath.Separator), statusOK + } + return string(filepath.Separator), statusOK + } + if !filepath.IsAbs(rel) { + if filepath.Separator == '\\' { + rel = filepath.VolumeName(os.TempDir()) + string(filepath.Separator) + rel + } else { + rel = string(filepath.Separator) + rel + } + } + return filepath.Clean(rel), statusOK + } + root, ok := bucketRoot(pluginID, bucket) + if !ok { + return "", statusDenied + } + if filepath.IsAbs(rel) || strings.HasPrefix(rel, string(filepath.Separator)) || strings.HasPrefix(rel, "/") || strings.HasPrefix(rel, `\`) { + return "", statusDenied + } + cleanRel := strings.TrimPrefix(filepath.Clean(string(filepath.Separator)+rel), string(filepath.Separator)) + target := filepath.Join(root, cleanRel) + resolvedRoot, err := filepath.Abs(root) + if err != nil { + return "", statusIO + } + resolvedTarget, err := filepath.Abs(target) + if err != nil { + return "", statusIO + } + r, err := filepath.Rel(resolvedRoot, resolvedTarget) + if err != nil || r == ".." || strings.HasPrefix(r, ".."+string(filepath.Separator)) { + return "", statusDenied + } + return resolvedTarget, statusOK +} + +func bucketRoot(pluginID, bucket string) (string, bool) { + home, _ := os.UserHomeDir() + switch bucket { + case "home": + return home, home != "" + case "desktop": + return filepath.Join(home, "Desktop"), home != "" + case "documents": + return filepath.Join(home, "Documents"), home != "" + case "downloads": + return filepath.Join(home, "Downloads"), home != "" + case "temp": + return os.TempDir(), true + case "appData": + dir, err := os.UserConfigDir() + if err != nil { + return "", false + } + return filepath.Join(dir, "Overlord"), true + case "pluginData": + dir, err := os.UserConfigDir() + if err != nil { + return "", false + } + root := filepath.Join(dir, "Overlord", "plugins", pluginID) + _ = os.MkdirAll(root, 0o700) + return root, true + default: + return "", false + } +} + +func buildFileACL(needs PluginNeeds) map[string]map[string]bool { + acl := map[string]map[string]bool{} + for _, need := range needs.Files { + if acl[need.Bucket] == nil { + acl[need.Bucket] = map[string]bool{} + } + for _, op := range need.Access { + acl[need.Bucket][op] = true + } + } + return acl +} + +func (p *wasmPlugin) writeJSONResult(mod api.Module, stack []uint64, v interface{}) { + data, err := json.Marshal(v) + if err != nil { + stack[0] = wasmStatus(statusIO) + return + } + stack[0] = wasmStatus(writeWASMOutput(mod, uint32(stack[4]), uint32(stack[5]), data)) +} + +func readWASMBytes(mod api.Module, ptr, size uint32) ([]byte, bool) { + if size == 0 { + return nil, true + } + data, ok := mod.Memory().Read(ptr, size) + if !ok { + return nil, false + } + out := make([]byte, len(data)) + copy(out, data) + return out, true +} + +func writeWASMOutput(mod api.Module, ptr, size uint32, data []byte) int32 { + if uint32(len(data)) > size { + return statusTooSmall + } + if len(data) > 0 && !mod.Memory().Write(ptr, data) { + return statusInvalid + } + return int32(len(data)) +} + +const ( + statusOK int32 = 0 + statusDenied int32 = -1 + statusInvalid int32 = -2 + statusNotFound int32 = -3 + statusTooSmall int32 = -4 + statusTooLarge int32 = -5 + statusIO int32 = -6 +) + +func wasmStatus(status int32) uint64 { + return uint64(uint32(status)) +} diff --git a/Overlord-Client/cmd/agent/plugins/wasm_runtime_test.go b/Overlord-Client/cmd/agent/plugins/wasm_runtime_test.go new file mode 100644 index 0000000..87d2f3f --- /dev/null +++ b/Overlord-Client/cmd/agent/plugins/wasm_runtime_test.go @@ -0,0 +1,41 @@ +package plugins + +import ( + "path/filepath" + "strings" + "testing" +) + +func TestBuildFileACL(t *testing.T) { + acl := buildFileACL(PluginNeeds{Files: []PluginFileNeed{ + {Bucket: "downloads", Access: []string{"read", "list"}}, + }}) + if !acl["downloads"]["read"] || !acl["downloads"]["list"] { + t.Fatalf("expected read/list permissions: %#v", acl) + } + if acl["downloads"]["write"] { + t.Fatalf("did not expect write permission") + } +} + +func TestWriteWASMOutputStatusCodes(t *testing.T) { + status := statusTooSmall + if wasmStatus(statusTooSmall) != uint64(uint32(status)) { + t.Fatalf("negative status should be encoded as wasm i32") + } +} + +func TestResolvePluginBucketPathRejectsTraversal(t *testing.T) { + target, status := resolvePluginBucketPath("demo", "pluginData", ".."+string(filepath.Separator)+"escape.txt") + if status != statusOK { + t.Fatalf("expected cleaned pluginData path, got status %d", status) + } + if strings.Contains(target, "..") { + t.Fatalf("expected traversal to be cleaned, got %q", target) + } + + _, status = resolvePluginBucketPath("demo", "downloads", string(filepath.Separator)+"absolute.txt") + if status != statusDenied { + t.Fatalf("expected absolute path to be denied for scoped bucket, got %d", status) + } +} diff --git a/Overlord-Client/go.mod b/Overlord-Client/go.mod index c65ed7d..399880e 100644 --- a/Overlord-Client/go.mod +++ b/Overlord-Client/go.mod @@ -19,8 +19,9 @@ require ( github.com/jezek/xgb v1.1.1 github.com/pion/rtcp v1.2.15 github.com/pion/webrtc/v4 v4.0.7 + github.com/tetratelabs/wazero v1.12.0 golang.org/x/crypto v0.49.0 - golang.org/x/sys v0.42.0 + golang.org/x/sys v0.44.0 ) require ( diff --git a/Overlord-Client/go.sum b/Overlord-Client/go.sum index f9e4cf4..0b8cb8f 100644 --- a/Overlord-Client/go.sum +++ b/Overlord-Client/go.sum @@ -77,6 +77,8 @@ github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXl github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= +github.com/tetratelabs/wazero v1.12.0 h1:DuWcpNu/FzgEXgGBDp8J1Spc+CWOvvtvVyjKlaZopYU= +github.com/tetratelabs/wazero v1.12.0/go.mod h1:LvKtzl2RqO4gyF27BiXU+nKAjcV8f38U+kP/q2vgxh0= github.com/vmihailenco/msgpack/v5 v5.4.1 h1:cQriyiUvjTwOHg8QZaPihLWeRAAVoCpE00IUPn0Bjt8= github.com/vmihailenco/msgpack/v5 v5.4.1/go.mod h1:GaZTsDaehaPpQVyxrf5mtQlH+pc21PIudVV/E3rRQok= github.com/vmihailenco/tagparser/v2 v2.0.0 h1:y09buUbR+b5aycVFQs/g70pqKVZNBmxwAhO7/IwNM9g= @@ -89,8 +91,8 @@ golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo= golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y= golang.org/x/sys v0.0.0-20201018230417-eeed37f84f13/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo= -golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= +golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ= +golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo= gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= diff --git a/Overlord-Server/public/assets/main.js b/Overlord-Server/public/assets/main.js index 2f8a039..c2e360f 100644 --- a/Overlord-Server/public/assets/main.js +++ b/Overlord-Server/public/assets/main.js @@ -616,8 +616,13 @@ function showPluginConfirmModal(pluginId, clientId, sigInfo) { body: JSON.stringify({ confirmed: true }), }); if (!res.ok) { - const text = await res.text(); - alert(`Plugin load failed: ${text}`); + const data = await res.json().catch(() => null); + if (data?.error === "needs_approval_required") { + modal.remove(); + showPluginNeedsModal(pluginId, clientId, data.needs, data.needsHash); + return; + } + alert(`Plugin load failed: ${data?.error || res.statusText}`); } else { window.open(`/plugins/${pluginId}?clientId=${clientId}`, "_blank", "noopener"); } @@ -630,6 +635,79 @@ function showPluginConfirmModal(pluginId, clientId, sigInfo) { input.focus(); } +function escapePluginHtml(value) { + return String(value) + .replace(/&/g, "&") + .replace(//g, ">") + .replace(/"/g, """); +} + +function pluginNeedLines(needs) { + const files = Array.isArray(needs?.files) ? needs.files : []; + return files.map((need) => { + const access = Array.isArray(need.access) ? need.access.join(", ") : ""; + const reason = need.reason ? ` - ${need.reason}` : ""; + return `${need.bucket}: ${access}${reason}`; + }); +} + +function showPluginNeedsModal(pluginId, clientId, needs, needsHash) { + document.getElementById("plugin-needs-modal")?.remove(); + const lines = pluginNeedLines(needs); + const modal = document.createElement("div"); + modal.id = "plugin-needs-modal"; + modal.className = "fixed inset-0 z-50 flex items-center justify-center bg-black/60 backdrop-blur-sm"; + modal.innerHTML = ` +
+
+
+ +
+
+

Approve Plugin Needs

+

${escapePluginHtml(pluginId)}

+
+
+

This plugin declares filesystem bridges that must be approved before loading.

+
+ ${lines.length ? lines.map((line) => `
${escapePluginHtml(line)}
`).join("") : '
No filesystem needs declared.
'} +
+ ${needsHash ? `

Needs hash: ${escapePluginHtml(needsHash.slice(0, 16))}...

` : ""} +
+ + +
+
+ `; + document.body.appendChild(modal); + document.getElementById("plugin-needs-cancel")?.addEventListener("click", () => modal.remove()); + modal.addEventListener("click", (e) => { if (e.target === modal) modal.remove(); }); + document.getElementById("plugin-needs-approve")?.addEventListener("click", async () => { + const approveBtn = document.getElementById("plugin-needs-approve"); + approveBtn.disabled = true; + approveBtn.textContent = "Approving..."; + const approve = await fetch(`/api/plugins/${pluginId}/needs/approve`, { method: "POST" }); + if (!approve.ok) { + alert("Needs approval failed"); + modal.remove(); + return; + } + const res = await fetch(`/api/clients/${clientId}/plugins/${pluginId}/load`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ confirmed: true }), + }); + if (!res.ok) { + const data = await res.json().catch(() => null); + alert(`Plugin load failed: ${data?.error || res.statusText}`); + } else { + window.open(`/plugins/${pluginId}?clientId=${clientId}`, "_blank", "noopener"); + } + modal.remove(); + }); +} + function renderPluginMenu(plugins) { const section = document.getElementById("plugin-section"); const container = document.getElementById("plugin-menu"); @@ -1708,7 +1786,11 @@ menu.addEventListener("click", async (e) => { if (res.status === 428) { const data = await res.json(); closeMenu(clearContext); - showPluginConfirmModal(pluginId, savedClientId, data.signature); + if (data.error === "needs_approval_required") { + showPluginNeedsModal(pluginId, savedClientId, data.needs, data.needsHash); + } else { + showPluginConfirmModal(pluginId, savedClientId, data.signature); + } return; } diff --git a/Overlord-Server/public/assets/plugins.js b/Overlord-Server/public/assets/plugins.js index f90c1bf..73508c8 100644 --- a/Overlord-Server/public/assets/plugins.js +++ b/Overlord-Server/public/assets/plugins.js @@ -96,6 +96,16 @@ function getTrustBadge(sig) { return { icon: "fa-shield-halved", color: "text-orange-400 border-orange-600 bg-orange-900/30", label: "Unsigned", tooltip: "This plugin is not signed" }; } +function describeNeeds(needs) { + const files = Array.isArray(needs?.files) ? needs.files : []; + if (!files.length) return []; + return files.map((need) => { + const access = Array.isArray(need.access) ? need.access.join(", ") : ""; + const reason = need.reason ? ` - ${need.reason}` : ""; + return `${need.bucket}: ${access}${reason}`; + }); +} + function renderPlugins(plugins) { pluginList.innerHTML = ""; if (!plugins.length) { @@ -123,6 +133,23 @@ function renderPlugins(plugins) { trustBadge.title = badge.tooltip; titleRow.appendChild(trustBadge); + const runtimeBadge = document.createElement("span"); + const isWasm = plugin.runtime === "wasm"; + const isV2 = Number(plugin.apiVersion || 1) >= 2; + runtimeBadge.className = `inline-flex items-center gap-1 text-[10px] uppercase tracking-wider px-2 py-0.5 rounded-full border ${ + isWasm + ? "text-cyan-300 border-cyan-700 bg-cyan-950/40" + : isV2 + ? "text-emerald-300 border-emerald-700 bg-emerald-950/40" + : "text-slate-300 border-slate-700 bg-slate-900/60" + }`; + runtimeBadge.innerHTML = isWasm + ? ' WASM 2.0' + : isV2 + ? ' Plugin 2.0' + : ' Native Legacy'; + titleRow.appendChild(runtimeBadge); + const subtitle = document.createElement("div"); subtitle.className = "text-sm text-slate-400"; subtitle.textContent = `${plugin.id}${plugin.version ? ` • v${plugin.version}` : ""}`; @@ -137,6 +164,19 @@ function renderPlugins(plugins) { meta.appendChild(titleRow); meta.appendChild(subtitle); + const needLines = describeNeeds(plugin.needs); + if (needLines.length) { + const needsBox = document.createElement("div"); + needsBox.className = "mt-2 text-xs text-slate-300 space-y-1"; + needsBox.innerHTML = ` +
+ + ${plugin.needsApproved ? "Needs approved" : "Needs approval before load"} +
+ ${needLines.map((line) => `
${escapeHtml(line)}
`).join("")} + `; + meta.appendChild(needsBox); + } const actions = document.createElement("div"); actions.className = "flex items-center gap-2"; @@ -159,6 +199,13 @@ function renderPlugins(plugins) { }); if (!res.ok) { const data = await res.json().catch(() => null); + if (data && data.error === "needs_approval_required") { + showNeedsApprovalModal(plugin, data.needs, data.needsHash, async () => { + await setPluginEnabled(plugin, wantEnabled, true); + await refresh(); + }); + return; + } if (data && data.error === "confirmation_required") { showPluginEnableConfirmModal(plugin, data.signature); return; @@ -202,14 +249,37 @@ function renderPlugins(plugins) { }), }); if (!res.ok) { - const text = await res.text(); - setStatus(`Auto-load toggle failed: ${text}`, true); + const data = await res.json().catch(() => null); + if (data && data.error === "needs_approval_required") { + showNeedsApprovalModal(plugin, data.needs, data.needsHash, async () => { + await fetch(`/api/plugins/${plugin.id}/autoload`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + autoLoad: !plugin.autoLoad, + autoStartEvents: plugin.autoStartEvents || [], + }), + }); + await refresh(); + }); + return; + } + setStatus(`Auto-load toggle failed: ${data?.error || res.statusText}`, true); return; } await refresh(); }); } + if (needLines.length && !plugin.needsApproved) { + const approveBtn = document.createElement("button"); + approveBtn.className = + "inline-flex items-center gap-2 px-3 py-2 rounded-lg bg-amber-900/40 border border-amber-700/60 hover:bg-amber-800/60 text-amber-100"; + approveBtn.innerHTML = ' Approve needs'; + approveBtn.addEventListener("click", () => showNeedsApprovalModal(plugin, plugin.needs, plugin.needsHash, refresh)); + actions.appendChild(approveBtn); + } + const removeBtn = document.createElement("button"); removeBtn.className = "inline-flex items-center gap-2 px-3 py-2 rounded-lg bg-red-900/40 border border-red-700/60 hover:bg-red-800/60 text-red-100"; @@ -241,6 +311,65 @@ function renderPlugins(plugins) { } } +function escapeHtml(value) { + return String(value) + .replace(/&/g, "&") + .replace(//g, ">") + .replace(/"/g, """); +} + +async function setPluginEnabled(plugin, enabled, confirmed = false) { + return fetch(`/api/plugins/${plugin.id}/enable`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ enabled, confirmed }), + }); +} + +function showNeedsApprovalModal(plugin, needs, needsHash, afterApprove) { + document.getElementById("plugin-needs-approval-modal")?.remove(); + const needLines = describeNeeds(needs); + const overlay = document.createElement("div"); + overlay.id = "plugin-needs-approval-modal"; + overlay.className = "fixed inset-0 z-50 flex items-center justify-center bg-black/60 backdrop-blur-sm"; + overlay.innerHTML = ` +
+
+ +

Approve Plugin Needs

+
+

${escapeHtml(plugin.name || plugin.id)} is asking for filesystem bridges before it can be sent to clients.

+
+ ${needLines.length ? needLines.map((line) => `
${escapeHtml(line)}
`).join("") : '
No filesystem needs declared.
'} +
+ ${needsHash ? `

Needs hash: ${escapeHtml(needsHash.slice(0, 16))}...

` : ""} +
+ + +
+
+ `; + document.body.appendChild(overlay); + document.getElementById("plugin-needs-cancel")?.addEventListener("click", () => overlay.remove()); + overlay.addEventListener("click", (e) => { if (e.target === overlay) overlay.remove(); }); + document.getElementById("plugin-needs-ok")?.addEventListener("click", async () => { + const okBtn = document.getElementById("plugin-needs-ok"); + okBtn.disabled = true; + okBtn.textContent = "Approving..."; + const res = await fetch(`/api/plugins/${plugin.id}/needs/approve`, { method: "POST" }); + if (!res.ok) { + const text = await res.text(); + setStatus(`Needs approval failed: ${text}`, true); + overlay.remove(); + return; + } + overlay.remove(); + setStatus("Plugin needs approved."); + if (typeof afterApprove === "function") await afterApprove(); + }); +} + function showPluginEnableConfirmModal(plugin, sigInfo) { document.getElementById("plugin-enable-confirm-modal")?.remove(); @@ -302,8 +431,16 @@ function showPluginEnableConfirmModal(plugin, sigInfo) { body: JSON.stringify({ enabled: true, confirmed: true }), }); if (!res.ok) { - const text = await res.text(); - setStatus(`Enable failed: ${text}`, true); + const data = await res.json().catch(() => null); + if (data && data.error === "needs_approval_required") { + overlay.remove(); + showNeedsApprovalModal(plugin, data.needs, data.needsHash, async () => { + await setPluginEnabled(plugin, true, true); + await refresh(); + }); + return; + } + setStatus(`Enable failed: ${data?.error || res.statusText}`, true); } } catch { setStatus("Enable failed", true); diff --git a/Overlord-Server/src/main-server.ts b/Overlord-Server/src/main-server.ts index 5a2918c..a03d63f 100644 --- a/Overlord-Server/src/main-server.ts +++ b/Overlord-Server/src/main-server.ts @@ -73,6 +73,7 @@ import { savePluginStateToDisk, sendPluginBundle, dispatchAutoLoadPlugins, + arePluginNeedsApproved, } from "./server/plugin-state-bundle"; import { createPluginRuntime } from "./server/plugin-runtime/runtime"; import { @@ -276,7 +277,7 @@ const MAX_HTTP_BODY_BYTES = parseMaxHttpBodyBytes(); const pluginLoadedByClient = new Map>(); const pendingPluginEvents = new Map>(); const pluginLoadingByClient = new Map>(); -let pluginState = { enabled: {} as Record, lastError: {} as Record, autoLoad: {} as Record, autoStartEvents: {} as Record> }; +let pluginState = { enabled: {} as Record, lastError: {} as Record, autoLoad: {} as Record, autoStartEvents: {} as Record>, approvedNeeds: {} as Record }; const savePluginState = () => savePluginStateToDisk(PLUGIN_ROOT, PLUGIN_STATE_PATH, pluginState); const loadPluginState = async () => { @@ -633,6 +634,12 @@ async function startServer() { notificationPluginHandlers.markPluginLoading, notificationPluginHandlers.enqueuePluginEvent, loadPluginBundle, + async (pluginId: string) => { + const manifests = await listPluginManifests(); + const manifest = manifests.find((p) => p.id === pluginId); + if (!manifest) return false; + return arePluginNeedsApproved(pluginState, pluginId, manifest.needs); + }, ).catch((err) => { logger.warn(`[plugin-autoload] dispatch error for ${info.id}: ${(err as Error).message}`); }); diff --git a/Overlord-Server/src/protocol.ts b/Overlord-Server/src/protocol.ts index 49e63b5..4aadcb2 100644 --- a/Overlord-Server/src/protocol.ts +++ b/Overlord-Server/src/protocol.ts @@ -334,10 +334,14 @@ export type ScriptResult = { export type PluginManifest = { id: string; name: string; + apiVersion?: number; + runtime?: "native" | "wasm" | string; version?: string; description?: string; binary?: string; binaries?: Record; + wasm?: string; + needs?: PluginNeeds; entry?: string; assets?: { html?: string; @@ -351,6 +355,16 @@ export type PluginManifest = { hasServer?: boolean; }; +export type PluginFileNeed = { + bucket: "home" | "desktop" | "documents" | "downloads" | "temp" | "appData" | "pluginData" | "fullDisk" | string; + access: Array<"read" | "write" | "list" | "delete" | "mkdir" | string>; + reason?: string; +}; + +export type PluginNeeds = { + files?: PluginFileNeed[]; +}; + export type PluginSignatureInfo = { signed: boolean; trusted: boolean; diff --git a/Overlord-Server/src/server/plugin-state-bundle.test.ts b/Overlord-Server/src/server/plugin-state-bundle.test.ts index 4211ca5..e844048 100644 --- a/Overlord-Server/src/server/plugin-state-bundle.test.ts +++ b/Overlord-Server/src/server/plugin-state-bundle.test.ts @@ -1,8 +1,14 @@ import { afterEach, describe, expect, test } from "bun:test"; -import { mkdtemp, mkdir, rm, writeFile } from "fs/promises"; +import { mkdtemp, mkdir, readFile, rm, writeFile } from "fs/promises"; import { tmpdir } from "os"; import { join } from "path"; -import { loadPluginBundle } from "./plugin-state-bundle"; +import { + arePluginNeedsApproved, + compilePluginTypeScript, + computePluginNeedsHash, + loadPluginBundle, + type PluginState, +} from "./plugin-state-bundle"; let tempRoots: string[] = []; @@ -37,4 +43,66 @@ describe("loadPluginBundle", () => { expect(bundle.binaryPath).toBe(join(pluginDir, "sample-c-windows-amd64.dll")); expect(bundle.size).toBe("test-binary".length); }); + + test("loads wasm manifest independently of client platform", async () => { + const root = await createTempRoot(); + const pluginDir = join(root, "wasm-demo"); + await mkdir(pluginDir, { recursive: true }); + await writeFile(join(pluginDir, "plugin.wasm"), Buffer.from([0x00, 0x61, 0x73, 0x6d])); + await writeFile( + join(pluginDir, "manifest.json"), + JSON.stringify({ + id: "wasm-demo", + name: "WASM Demo", + apiVersion: 2, + runtime: "wasm", + wasm: "plugin.wasm", + needs: { files: [{ bucket: "downloads", access: ["list", "read"], reason: "Import files" }] }, + }), + ); + + const bundle = await loadPluginBundle(root, "wasm-demo", async () => {}, "Windows 11", "amd64"); + + expect(bundle.manifest.apiVersion).toBe(2); + expect(bundle.manifest.runtime).toBe("wasm"); + expect(bundle.manifest.wasm).toBe("plugin.wasm"); + expect(bundle.binaryPath).toBe(join(root, "wasm-demo", "plugin.wasm")); + expect(bundle.size).toBe(4); + }); + + test("computes stable need hashes and invalidates changed approvals", () => { + const state: PluginState = { + enabled: {}, + lastError: {}, + autoLoad: {}, + autoStartEvents: {}, + approvedNeeds: {}, + }; + const needs = { files: [{ bucket: "downloads", access: ["read", "list"] }] }; + const sameNeedsDifferentOrder = { files: [{ bucket: "downloads", access: ["list", "read"] }] }; + const changedNeeds = { files: [{ bucket: "downloads", access: ["read", "write"] }] }; + const hash = computePluginNeedsHash(needs); + + expect(hash).toBe(computePluginNeedsHash(sameNeedsDifferentOrder)); + expect(hash).not.toBe(computePluginNeedsHash(changedNeeds)); + expect(arePluginNeedsApproved(state, "demo", needs)).toBe(false); + state.approvedNeeds.demo = hash; + expect(arePluginNeedsApproved(state, "demo", sameNeedsDifferentOrder)).toBe(true); + expect(arePluginNeedsApproved(state, "demo", changedNeeds)).toBe(false); + }); + + test("compiles TypeScript entrypoints with local imports", async () => { + const root = await createTempRoot(); + await mkdir(join(root, "src"), { recursive: true }); + await writeFile(join(root, "src", "shared.ts"), "export const message = 'hello-ts';\n"); + await writeFile(join(root, "src", "ui.ts"), "import { message } from './shared'; document.body.dataset.sample = message;\n"); + await writeFile(join(root, "src", "server.ts"), "import { message } from './shared'; export default { rpc: { ping() { return { message }; } } };\n"); + await compilePluginTypeScript(join(root, "src", "ui.ts"), join(root, "assets", "sample-ts.js"), "browser", "sample-ts"); + await compilePluginTypeScript(join(root, "src", "server.ts"), join(root, "server.js"), "bun", "sample-ts"); + + const uiJs = await readFile(join(root, "assets", "sample-ts.js"), "utf-8"); + const serverJs = await readFile(join(root, "server.js"), "utf-8"); + expect(uiJs).toContain("hello-ts"); + expect(serverJs).toContain("hello-ts"); + }); }); diff --git a/Overlord-Server/src/server/plugin-state-bundle.ts b/Overlord-Server/src/server/plugin-state-bundle.ts index 4d68e43..55297bc 100644 --- a/Overlord-Server/src/server/plugin-state-bundle.ts +++ b/Overlord-Server/src/server/plugin-state-bundle.ts @@ -1,19 +1,21 @@ import fs from "fs/promises"; import path from "path"; -import AdmZip from "adm-zip"; +import { createHash } from "crypto"; import { v4 as uuidv4 } from "uuid"; import type { ClientInfo } from "../types"; -import { logger } from "../logger"; -import { encodeMessage, type PluginManifest, type PluginSignatureInfo } from "../protocol"; -import { verifyPluginSignature, getOrVerifySignature } from "./plugin-signature"; +import type { PluginFileNeed, PluginManifest, PluginNeeds, PluginSignatureInfo } from "../protocol"; export type PluginState = { enabled: Record; lastError: Record; autoLoad: Record; autoStartEvents: Record>; + approvedNeeds: Record; }; +const FILE_BUCKETS = new Set(["home", "desktop", "documents", "downloads", "temp", "appData", "pluginData", "fullDisk"]); +const FILE_ACCESS = new Set(["read", "write", "list", "delete", "mkdir"]); + export async function loadPluginStateFromDisk(pluginStatePath: string): Promise { try { const raw = await fs.readFile(pluginStatePath, "utf-8"); @@ -23,9 +25,10 @@ export async function loadPluginStateFromDisk(pluginStatePath: string): Promise< lastError: parsed.lastError || {}, autoLoad: parsed.autoLoad || {}, autoStartEvents: parsed.autoStartEvents || {}, + approvedNeeds: parsed.approvedNeeds || {}, }; } catch { - return { enabled: {}, lastError: {}, autoLoad: {}, autoStartEvents: {} }; + return { enabled: {}, lastError: {}, autoLoad: {}, autoStartEvents: {}, approvedNeeds: {} }; } } @@ -75,6 +78,7 @@ export async function ensurePluginExtracted( const assetsDir = path.join(pluginDir, "assets"); await fs.mkdir(assetsDir, { recursive: true }); + const AdmZip = await loadAdmZip(); const zip = new AdmZip(zipPath); const entries = zip.getEntries(); @@ -97,14 +101,19 @@ export async function ensurePluginExtracted( let jsEntry: Buffer | null = null; let serverEntry: Buffer | null = null; let configEntry: Buffer | null = null; + let wasmEntry: { filename: string; data: Buffer } | null = null; + const sourceEntries: Map = new Map(); const nativeBinaries: Map = new Map(); for (const entry of entries) { if (entry.isDirectory) continue; + const normalizedEntry = normalizeBundlePath(entry.entryName); const base = path.basename(entry.entryName); const lower = base.toLowerCase(); if (lower.endsWith(".so") || lower.endsWith(".dll") || lower.endsWith(".dylib")) { nativeBinaries.set(base, entry.getData()); + } else if (lower.endsWith(".wasm")) { + wasmEntry = { filename: base, data: entry.getData() }; } else if (lower === "server.js") { serverEntry = entry.getData(); } else if (lower.endsWith(".html")) { @@ -116,10 +125,28 @@ export async function ensurePluginExtracted( } else if (lower === "config.json") { configEntry = entry.getData(); } + if (normalizedEntry && isPluginSourcePath(normalizedEntry)) { + sourceEntries.set(normalizedEntry, entry.getData()); + } } - if (!htmlEntry || !cssEntry || !jsEntry) { - throw new Error(`Invalid plugin bundle: ${safeId} (missing .html, .css, or .js)`); + let extraConfig: any = {}; + if (configEntry) { + try { + extraConfig = JSON.parse(configEntry.toString("utf-8")); + } catch (err) { + warnPlugin(`[plugin] invalid config.json in bundle ${safeId}, ignoring: ${err}`); + } + } + + const uiTsEntry = getConfiguredSourceEntry(extraConfig, ["uiEntry", "ui.entry", "build.ui", "build.uiEntry"], sourceEntries) + || (sourceEntries.has("src/ui.ts") ? "src/ui.ts" : "") + || (sourceEntries.has("src/index.ts") ? "src/index.ts" : ""); + const serverTsEntry = getConfiguredSourceEntry(extraConfig, ["serverEntry", "server.entry", "build.server", "build.serverEntry"], sourceEntries) + || (sourceEntries.has("src/server.ts") ? "src/server.ts" : ""); + + if (!htmlEntry || !cssEntry || (!jsEntry && !uiTsEntry)) { + throw new Error(`Invalid plugin bundle: ${safeId} (missing .html, .css, and either .js or src/ui.ts)`); } const binariesMap: Record = {}; @@ -130,13 +157,35 @@ export async function ensurePluginExtracted( binariesMap[platformKey] = filename; } } + if (wasmEntry) { + await fs.writeFile(path.join(pluginDir, wasmEntry.filename), wasmEntry.data); + binariesMap["wasm32-wasi"] = wasmEntry.filename; + } + + if (sourceEntries.size > 0) { + await fs.rm(path.join(pluginDir, "src"), { recursive: true, force: true }); + for (const [relPath, data] of sourceEntries) { + const target = resolveInside(pluginDir, relPath); + if (!target) { + throw new Error(`Invalid plugin bundle: ${safeId} (unsafe source path)`); + } + await fs.mkdir(path.dirname(target), { recursive: true }); + await fs.writeFile(target, data); + } + } await fs.writeFile(path.join(assetsDir, `${safeId}.html`), htmlEntry); await fs.writeFile(path.join(assetsDir, `${safeId}.css`), cssEntry); - await fs.writeFile(path.join(assetsDir, `${safeId}.js`), jsEntry); + if (uiTsEntry) { + await compilePluginTypeScript(path.join(pluginDir, uiTsEntry), path.join(assetsDir, `${safeId}.js`), "browser", safeId); + } else if (jsEntry) { + await fs.writeFile(path.join(assetsDir, `${safeId}.js`), jsEntry); + } const serverScriptPath = path.join(pluginDir, "server.js"); - if (serverEntry) { + if (serverTsEntry) { + await compilePluginTypeScript(path.join(pluginDir, serverTsEntry), serverScriptPath, "bun", safeId); + } else if (serverEntry) { await fs.writeFile(serverScriptPath, serverEntry); } else { // A previous extraction may have left a stale server.js — drop it so the @@ -144,20 +193,17 @@ export async function ensurePluginExtracted( try { await fs.rm(serverScriptPath, { force: true }); } catch {} } - let extraConfig: any = {}; - if (configEntry) { - try { - extraConfig = JSON.parse(configEntry.toString("utf-8")); - } catch (err) { - logger.warn(`[plugin] invalid config.json in bundle ${safeId}, ignoring: ${err}`); - } - } - + const runtime = normalizePluginRuntime(extraConfig.runtime, wasmEntry !== null); + const needs = normalizePluginNeeds(extraConfig.needs); const manifest: PluginManifest = { id: safeId, name: extraConfig.name || safeId, + apiVersion: Number(extraConfig.apiVersion) === 2 || runtime === "wasm" ? 2 : 1, + runtime, version: extraConfig.version || "1.0.0", description: extraConfig.description, + ...(runtime === "wasm" && { wasm: String(extraConfig.wasm || wasmEntry?.filename || binariesMap["wasm32-wasi"] || "") }), + ...(needs && { needs }), binaries: binariesMap, entry: `${safeId}.html`, assets: { @@ -166,16 +212,17 @@ export async function ensurePluginExtracted( js: `${safeId}.js`, }, ...(extraConfig.navbar && { navbar: extraConfig.navbar }), - hasServer: serverEntry !== null, + hasServer: serverEntry !== null || !!serverTsEntry, }; await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2)); try { + const { verifyPluginSignature } = await import("./plugin-signature"); const sigInfo = await verifyPluginSignature(zipPath); const sigInfoPath = path.join(pluginDir, "signature-info.json"); await fs.writeFile(sigInfoPath, JSON.stringify(sigInfo, null, 2)); } catch (err) { - logger.warn(`[plugin] failed to verify signature for ${safeId}: ${(err as Error).message}`); + warnPlugin(`[plugin] failed to verify signature for ${safeId}: ${(err as Error).message}`); } } @@ -191,7 +238,7 @@ export async function syncPluginBundles( try { await ensureExtracted(pluginId); } catch (err) { - logger.warn(`[plugin] failed to extract ${pluginId}: ${(err as Error).message}`); + warnPlugin(`[plugin] failed to extract ${pluginId}: ${(err as Error).message}`); } } } @@ -199,6 +246,7 @@ export async function syncPluginBundles( export type PluginManifestWithSignature = PluginManifest & { signature?: PluginSignatureInfo; + needsHash?: string; }; export async function listPluginManifests( @@ -222,8 +270,9 @@ export async function listPluginManifests( if (pluginState.enabled[id] === undefined) { pluginState.enabled[id] = true; } + const { getOrVerifySignature } = await import("./plugin-signature"); const sigInfo = await getOrVerifySignature(pluginRoot, id); - manifests.push({ ...manifest, id, name, signature: sigInfo }); + manifests.push({ ...manifest, id, name, signature: sigInfo, needsHash: computePluginNeedsHash(manifest.needs) }); } catch {} } await saveState(); @@ -254,6 +303,19 @@ export async function loadPluginBundle( manifest.id = manifest.id || pluginId; manifest.name = manifest.name || pluginId; + if (manifest.runtime === "wasm" || manifest.wasm || manifest.binaries?.["wasm32-wasi"]) { + const wasmName = manifest.wasm || manifest.binaries?.["wasm32-wasi"]; + if (!wasmName) { + throw new Error(`No WASM module configured for ${pluginId}`); + } + const binaryPath = path.join(dir, wasmName); + const stat = await fs.stat(binaryPath); + return { manifest: { ...manifest, runtime: "wasm", apiVersion: 2 }, binaryPath, size: stat.size }; + } + + manifest.runtime = manifest.runtime || "native"; + manifest.apiVersion = manifest.apiVersion || 1; + const hasBinaries = manifest.binaries && Object.keys(manifest.binaries).length > 0; if (!hasBinaries) { return { manifest, binaryPath: null, size: 0 }; @@ -366,6 +428,7 @@ export function sendPluginBundle( bundle: PluginBundle, ): void { if (!bundle.binaryPath) return; + const { encodeMessage } = require("../protocol"); const pullId = uuidv4(); const expiresAt = Date.now() + PLUGIN_PULL_TTL_MS; @@ -405,6 +468,7 @@ export async function dispatchAutoLoadPlugins( markPluginLoading: (clientId: string, pluginId: string) => void, enqueuePluginEvent: (clientId: string, pluginId: string, event: string, payload: any) => void, loadBundle: (pluginId: string, clientOS?: string, clientArch?: string) => Promise, + needsApproved: (pluginId: string) => Promise = async () => true, ): Promise { const autoLoadIds = Object.entries(pluginState.autoLoad) .filter(([id, enabled]) => enabled && pluginState.enabled[id] !== false) @@ -416,6 +480,10 @@ export async function dispatchAutoLoadPlugins( } try { + if (!(await needsApproved(pluginId))) { + warnPlugin(`[plugin-autoload] skipped ${pluginId} for ${client.id}: plugin needs approval`); + continue; + } const bundle = await loadBundle(pluginId, client.os, client.arch); markPluginLoading(client.id, pluginId); sendPluginBundle(client, bundle); @@ -427,14 +495,134 @@ export async function dispatchAutoLoadPlugins( } } - logger.info(`[plugin-autoload] dispatched ${pluginId} to ${client.id}`); + infoPlugin(`[plugin-autoload] dispatched ${pluginId} to ${client.id}`); } catch (err) { - logger.warn(`[plugin-autoload] failed to load ${pluginId} for ${client.id}: ${(err as Error).message}`); + warnPlugin(`[plugin-autoload] failed to load ${pluginId} for ${client.id}: ${(err as Error).message}`); } } } -export function detectPluginIdFromZip(zip: AdmZip): string | null { +function warnPlugin(message: string): void { + console.warn(message); +} + +function infoPlugin(message: string): void { + console.log(message); +} + +function normalizeBundlePath(entryName: string): string | null { + if (!entryName || entryName.includes("\0")) return null; + const normalized = entryName.replace(/\\/g, "/").replace(/^\/+/, ""); + const parts = normalized.split("/").filter(Boolean); + if (parts.some((part) => part === "." || part === "..")) return null; + return parts.join("/"); +} + +function isPluginSourcePath(relPath: string): boolean { + if (!relPath.startsWith("src/")) return false; + const lower = relPath.toLowerCase(); + return ( + lower.endsWith(".ts") || + lower.endsWith(".tsx") || + lower.endsWith(".js") || + lower.endsWith(".jsx") || + lower.endsWith(".json") || + lower.endsWith(".d.ts") + ); +} + +function resolveInside(root: string, relPath: string): string | null { + const resolvedRoot = path.resolve(root); + const resolvedTarget = path.resolve(resolvedRoot, relPath); + const prefix = resolvedRoot.endsWith(path.sep) ? resolvedRoot : `${resolvedRoot}${path.sep}`; + if (resolvedTarget !== resolvedRoot && !resolvedTarget.startsWith(prefix)) return null; + return resolvedTarget; +} + +function getConfiguredSourceEntry(config: any, candidates: string[], sourceEntries: Map): string { + for (const candidate of candidates) { + const value = getPathValue(config, candidate); + if (typeof value !== "string") continue; + const normalized = normalizeBundlePath(value); + if (!normalized || !isPluginSourcePath(normalized)) continue; + if (!sourceEntries.has(normalized)) { + throw new Error(`Configured TypeScript entry not found: ${normalized}`); + } + return normalized; + } + return ""; +} + +function getPathValue(obj: any, dotted: string): unknown { + let cur = obj; + for (const part of dotted.split(".")) { + if (!cur || typeof cur !== "object") return undefined; + cur = cur[part]; + } + return cur; +} + +export async function compilePluginTypeScript(entryPath: string, outFile: string, target: "browser" | "bun", pluginId: string): Promise { + const result = await Bun.build({ + entrypoints: [entryPath], + target, + format: "esm", + minify: false, + sourcemap: "none", + write: false, + }); + if (!result.success) { + const logs = result.logs.map((log) => log.message).join("; "); + throw new Error(`TypeScript build failed for ${pluginId}: ${logs || "unknown error"}`); + } + const output = result.outputs.find((out) => out.path.endsWith(".js")) || result.outputs[0]; + if (!output) { + throw new Error(`TypeScript build failed for ${pluginId}: no JavaScript output`); + } + await fs.mkdir(path.dirname(outFile), { recursive: true }); + await fs.writeFile(outFile, await output.text()); +} + +export function computePluginNeedsHash(needs: PluginNeeds | undefined): string { + const normalized = normalizePluginNeeds(needs); + if (!normalized || !normalized.files || normalized.files.length === 0) return ""; + return createHash("sha256").update(JSON.stringify(normalized)).digest("hex"); +} + +export function arePluginNeedsApproved(pluginState: PluginState, pluginId: string, needs: PluginNeeds | undefined): boolean { + const hash = computePluginNeedsHash(needs); + return !hash || pluginState.approvedNeeds[pluginId] === hash; +} + +export function normalizePluginNeeds(raw: any): PluginNeeds | undefined { + if (!raw || typeof raw !== "object") return undefined; + const filesRaw = Array.isArray(raw.files) ? raw.files : []; + const files: PluginFileNeed[] = []; + for (const item of filesRaw) { + if (!item || typeof item !== "object") continue; + const bucket = typeof item.bucket === "string" ? item.bucket.trim() : ""; + if (!FILE_BUCKETS.has(bucket)) continue; + const accessRaw = Array.isArray(item.access) ? item.access : []; + const access = Array.from(new Set(accessRaw.filter((a: any) => typeof a === "string" && FILE_ACCESS.has(a)))); + if (access.length === 0) continue; + files.push({ + bucket, + access: access.sort(), + ...(typeof item.reason === "string" && item.reason.trim() ? { reason: item.reason.trim().slice(0, 500) } : {}), + }); + } + files.sort((a, b) => `${a.bucket}:${a.access.join(",")}`.localeCompare(`${b.bucket}:${b.access.join(",")}`)); + return files.length > 0 ? { files } : undefined; +} + +function normalizePluginRuntime(runtime: any, hasWasm: boolean): "native" | "wasm" | "server" { + const value = typeof runtime === "string" ? runtime.trim().toLowerCase() : ""; + if (value === "wasm" || hasWasm) return "wasm"; + if (value === "server") return "server"; + return "native"; +} + +export function detectPluginIdFromZip(zip: any): string | null { const entries = zip.getEntries(); for (const entry of entries) { if (entry.isDirectory) continue; @@ -457,6 +645,14 @@ export function detectPluginIdFromZip(zip: AdmZip): string | null { return null; } +async function loadAdmZip(): Promise { + try { + return require("adm-zip"); + } catch { + return require(path.join(process.cwd(), "node_modules", "adm-zip", "adm-zip.js")); + } +} + function derivePlatformKey(filename: string): string { const match = filename.match(/-(linux|darwin|windows|freebsd)-(amd64|arm64|arm|386)\.(so|dll|dylib)$/i); if (match) { diff --git a/Overlord-Server/src/server/routes/plugin-routes.ts b/Overlord-Server/src/server/routes/plugin-routes.ts index c2bd539..ef9a654 100644 --- a/Overlord-Server/src/server/routes/plugin-routes.ts +++ b/Overlord-Server/src/server/routes/plugin-routes.ts @@ -12,7 +12,7 @@ import { encodeMessage, type PluginSignatureInfo } from "../../protocol"; import { getConfig, updatePluginsConfig } from "../../config"; import { getOrVerifySignature, BUILTIN_TRUSTED_KEYS } from "../plugin-signature"; import type { PluginRuntime } from "../plugin-runtime/runtime"; -import { getPluginPull, deletePluginPull, detectPluginIdFromZip } from "../plugin-state-bundle"; +import { arePluginNeedsApproved, computePluginNeedsHash, getPluginPull, deletePluginPull, detectPluginIdFromZip } from "../plugin-state-bundle"; import { isAuthorizedAgentRequest } from "../agent-auth"; import { logger } from "../../logger"; @@ -21,6 +21,11 @@ type PluginManifest = { name: string; signature?: PluginSignatureInfo; hasServer?: boolean; + apiVersion?: number; + runtime?: string; + wasm?: string; + needs?: any; + needsHash?: string; }; type PluginBundle = { @@ -34,6 +39,7 @@ type PluginState = { lastError: Record; autoLoad: Record; autoStartEvents: Record>; + approvedNeeds: Record; }; type PluginRouteDeps = { @@ -72,6 +78,34 @@ export async function handlePluginRoutes( return null; } + async function loadManifest(pluginId: string): Promise { + await deps.ensurePluginExtracted(pluginId); + const raw = await fs.readFile(path.join(deps.PLUGIN_ROOT, pluginId, "manifest.json"), "utf-8"); + const manifest = JSON.parse(raw) as PluginManifest; + manifest.id = manifest.id || pluginId; + manifest.name = manifest.name || pluginId; + manifest.needsHash = computePluginNeedsHash(manifest.needs); + return manifest; + } + + function needsApproved(manifest: PluginManifest): boolean { + return arePluginNeedsApproved(deps.pluginState, manifest.id, manifest.needs); + } + + async function requireNeedsApproval(pluginId: string): Promise { + const manifest = await loadManifest(pluginId); + if (needsApproved(manifest)) return null; + return Response.json( + { + ok: false, + error: "needs_approval_required", + needs: manifest.needs || {}, + needsHash: manifest.needsHash || "", + }, + { status: 428 }, + ); + } + if (req.method === "GET" && url.pathname.startsWith("/api/plugins/pull/")) { const agentToken = getConfig().auth.agentToken; if (!isAuthorizedAgentRequest(req, url, agentToken)) { @@ -137,6 +171,11 @@ export async function handlePluginRoutes( autoLoad: deps.pluginState.autoLoad[p.id] === true, autoStartEvents: deps.pluginState.autoStartEvents[p.id] || [], signature: p.signature || { signed: false, trusted: false, valid: false }, + runtime: p.runtime || "native", + apiVersion: p.apiVersion || 1, + needs: p.needs || {}, + needsHash: p.needsHash || computePluginNeedsHash(p.needs), + needsApproved: arePluginNeedsApproved(deps.pluginState, p.id, p.needs), hasServer: p.hasServer === true || deps.pluginRuntime.hasServerCode(p.id), serverRunning: deps.pluginRuntime.isRunning(p.id), })); @@ -229,6 +268,11 @@ export async function handlePluginRoutes( enabled: deps.pluginState.enabled[manifest.id] !== false, lastError: deps.pluginState.lastError[manifest.id] || "", signature: manifest.signature || { signed: false, trusted: false, valid: false }, + runtime: manifest.runtime || "native", + apiVersion: manifest.apiVersion || 1, + needs: manifest.needs || {}, + needsHash: manifest.needsHash || computePluginNeedsHash(manifest.needs), + needsApproved: arePluginNeedsApproved(deps.pluginState, manifest.id, manifest.needs), })); return Response.json({ plugins }); } @@ -312,8 +356,10 @@ export async function handlePluginRoutes( const sigInfo = await getOrVerifySignature(deps.PLUGIN_ROOT, pluginId); + const uploadedManifest = await loadManifest(pluginId); + if (deps.pluginState.enabled[pluginId] === undefined) { - deps.pluginState.enabled[pluginId] = sigInfo.trusted === true; + deps.pluginState.enabled[pluginId] = sigInfo.trusted === true && needsApproved(uploadedManifest); await deps.savePluginState(); } @@ -364,6 +410,8 @@ export async function handlePluginRoutes( ); } } + const needsResponse = await requireNeedsApproval(pluginId); + if (needsResponse) return needsResponse; } deps.pluginState.enabled[pluginId] = enabled; @@ -410,6 +458,10 @@ export async function handlePluginRoutes( { status: 400 }, ); } + if (autoLoad) { + const needsResponse = await requireNeedsApproval(pluginId); + if (needsResponse) return needsResponse; + } deps.pluginState.autoLoad[pluginId] = autoLoad; @@ -444,6 +496,33 @@ export async function handlePluginRoutes( }); } + const pluginNeedsApproveMatch = url.pathname.match(/^\/api\/plugins\/(.+)\/needs\/approve$/); + if (req.method === "POST" && pluginNeedsApproveMatch) { + const user = await authenticateRequest(req); + if (!user) return new Response("Unauthorized", { status: 401 }); + try { + requirePermission(user, "plugins:manage"); + } catch (error) { + if (error instanceof Response) return error; + return new Response("Forbidden", { status: 403 }); + } + let pluginId = ""; + try { + pluginId = deps.sanitizePluginId(pluginNeedsApproveMatch[1]); + } catch { + return new Response("Invalid plugin id", { status: 400 }); + } + const manifest = await loadManifest(pluginId); + const needsHash = manifest.needsHash || ""; + if (!needsHash) { + delete deps.pluginState.approvedNeeds[pluginId]; + } else { + deps.pluginState.approvedNeeds[pluginId] = needsHash; + } + await deps.savePluginState(); + return Response.json({ ok: true, id: pluginId, needsHash, needsApproved: true }); + } + function resolveDataPath(pluginId: string, relPath: string): string | null { const dataDir = path.join(deps.PLUGIN_ROOT, pluginId, "data"); const target = path.resolve(dataDir, relPath); @@ -755,6 +834,7 @@ export async function handlePluginRoutes( delete deps.pluginState.lastError[pluginId]; delete deps.pluginState.autoLoad[pluginId]; delete deps.pluginState.autoStartEvents[pluginId]; + delete deps.pluginState.approvedNeeds[pluginId]; await deps.savePluginState(); if (deps.pluginRuntime.isRunning(pluginId)) { @@ -821,6 +901,8 @@ export async function handlePluginRoutes( try { const bundle = await deps.loadPluginBundle(pluginId, target.os, target.arch); + const needsResponse = await requireNeedsApproval(pluginId); + if (needsResponse) return needsResponse; deps.markPluginLoading(targetId, pluginId); deps.sendPluginBundle(target, bundle); metrics.recordCommand("plugin_load"); @@ -902,6 +984,8 @@ export async function handlePluginRoutes( } if (!deps.isPluginLoaded(targetId, pluginId)) { + const needsResponse = await requireNeedsApproval(pluginId); + if (needsResponse) return needsResponse; deps.enqueuePluginEvent(targetId, pluginId, event, payload); if (!deps.isPluginLoading(targetId, pluginId)) { try { diff --git a/plugins/PLUGINS.md b/plugins/PLUGINS.md index 90bd495..6d00dfd 100644 --- a/plugins/PLUGINS.md +++ b/plugins/PLUGINS.md @@ -1,10 +1,92 @@ # Overlord Plugins -This document explains how to build Overlord plugins using the **native plugin system**. Plugins run as native shared libraries (`.so` on Linux, `.dylib` on macOS, in-memory DLL on Windows), giving them full access to system APIs. +This document explains how to build Overlord plugins. **Plugin 2.0** uses WebAssembly modules for agent-side code and permissioned host bridges. The legacy native plugin system still works, but native plugins are now considered v1. -Plugins can be written in **any language** that can produce a C-ABI shared library: **Go**, **C**, **C++**, **Rust**, or anything else that compiles to native code. +Plugin UI and server-side logic can be written in JavaScript or TypeScript. Agent-side Plugin 2.0 code is a single WASM module that can be built from C, Rust, Zig, TinyGo, AssemblyScript, or any other toolchain that can target WASI-style WebAssembly. Legacy v1 agent plugins can still be written as native shared libraries. -> TL;DR: A plugin is a zip with platform-specific binaries (`.so`/`.dll`/`.dylib`) plus `.html`, `.css`, `.js`. Upload it in the Plugins page or drop it in Overlord-Server/plugins. Optionally include a `server.js` for a per-plugin server runtime with a private SQLite DB, an RPC API, and live broadcasts to open UIs (see [section 11](#11-server-side-plugin-runtime)). +> TL;DR: A Plugin 2.0 bundle is a zip with `config.json`, `.html`, `.css`, and either `.js` or TypeScript under `src/`. If it needs agent-side code, include one `.wasm` module. Upload it in the Plugins page or drop it in `Overlord-Server/plugins`. The server shows declared `needs` before a WASM plugin can be sent to a client. + +## Plugin 2.0: WASM runtime + +WASM plugins run inside the agent through a sandboxed runtime. They cannot access files directly; instead they declare broad file needs in `config.json`, and the agent exposes only those approved bridge operations. + +```json +{ + "name": "My WASM Plugin", + "version": "1.0.0", + "apiVersion": 2, + "runtime": "wasm", + "wasm": "my-plugin.wasm", + "needs": { + "files": [ + { "bucket": "pluginData", "access": ["read", "write", "list", "mkdir"], "reason": "Store plugin state" }, + { "bucket": "downloads", "access": ["list"], "reason": "Let the user pick downloaded files" } + ] + } +} +``` + +Supported file buckets are `home`, `desktop`, `documents`, `downloads`, `temp`, `appData`, `pluginData`, and `fullDisk`. Supported operations are `read`, `write`, `list`, `delete`, and `mkdir`. Approval is tracked by a stable hash of the normalized needs; changing needs requires approval again. + +Required exports: + +| Export | Signature | +|--------|-----------| +| `overlord_alloc` | `ptr(uint32 size)` | +| `overlord_free` | `void(ptr, uint32 size)` | +| `overlord_on_load` | `int32(ptr hostInfo, uint32 hostInfoLen)` | +| `overlord_on_event` | `int32(ptr event, uint32 eventLen, ptr payload, uint32 payloadLen)` | +| `overlord_on_unload` | `void()` | + +Host imports are available from both `env` and `overlord` modules: + +| Import | Behavior | +|--------|----------| +| `overlord_emit(event, eventLen, payload, payloadLen)` | Sends an event back through the normal plugin event channel. | +| `overlord_host_info(out, outLen)` | Writes HostInfo JSON into `out`; includes `clientId`, `os`, `arch`, and `version`. | +| `overlord_fs_stat(bucket, bucketLen, path, pathLen, out, outLen)` | Writes JSON file metadata into `out`. | +| `overlord_fs_list(bucket, bucketLen, path, pathLen, out, outLen)` | Writes a JSON directory listing into `out`. | +| `overlord_fs_read(bucket, bucketLen, path, pathLen, out, outLen)` | Writes file bytes into `out`, max 32 MB. | +| `overlord_fs_write(bucket, bucketLen, path, pathLen, data, dataLen)` | Writes bytes to a bucket-relative path. | +| `overlord_fs_delete(bucket, bucketLen, path, pathLen)` | Deletes a bucket-relative file or directory. | +| `overlord_fs_mkdir(bucket, bucketLen, path, pathLen)` | Creates a bucket-relative directory. | + +Bridge functions return non-negative byte counts or `0` on success. Negative return codes mean denied, invalid path/memory, not found, output buffer too small, file too large, or I/O failure. + +See `plugins/sample-wasm` for a C/WASI example, `plugins/sample-wasm-hostinfo` for a TinyGo example, and `plugins/sample-wasm-platform-note` for a Rust example. + +## TypeScript UI and server logic + +Plugin bundles can ship TypeScript source for browser UI logic and the optional server runtime. The server compiles these files during extraction, so the uploaded zip can stay clean and source-oriented. + +Default layout: + +``` +sample-ts-fullstack.zip + ├─ config.json + ├─ sample-ts-fullstack.html + ├─ sample-ts-fullstack.css + └─ src/ + ├─ ui.ts + ├─ server.ts + └─ shared.ts +``` + +`src/ui.ts` is compiled to `assets/.js`. `src/server.ts` is compiled to `server.js`. Both entrypoints can import other local files, so plugin authors can split code across multiple TypeScript modules instead of maintaining one large JavaScript file. This is only for browser UI and server-side plugin runtime logic; agent-side WASM is still supplied as a prebuilt `.wasm` file. + +You can override entrypoints in `config.json`: + +```json +{ + "apiVersion": 2, + "uiEntry": "src/browser/main.ts", + "serverEntry": "src/backend/index.ts" +} +``` + +Only files under `src/` are copied for compilation. Extraction does not run `npm install`, download packages, or execute arbitrary build scripts; use relative imports and APIs already available in the browser or the Overlord plugin server runtime. + +See `plugins/sample-ts-fullstack` for a multi-file TypeScript UI/backend example. ## 1) How plugins are structured @@ -16,47 +98,84 @@ A plugin bundle is a zip file named after the plugin ID: .zip ``` -Inside the zip (root level), you need: - -- **Platform-specific binaries** named `--.` -- **Web assets**: `.html`, `.css`, `.js` - -Example for plugin ID `sample`: +For a Plugin 2.0 source-oriented bundle, the root normally contains: ``` -sample.zip - ├─ sample-linux-amd64.so - ├─ sample-linux-arm64.so - ├─ sample-darwin-arm64.dylib - ├─ sample-windows-amd64.dll - ├─ sample.html - ├─ sample.css - ├─ sample.js - ├─ server.js (optional — server-side runtime, see section 11) - └─ config.json (optional — enables navbar & metadata) +.zip + ├─ config.json + ├─ .html + ├─ .css + ├─ .js (optional when src/ui.ts exists) + ├─ .wasm (optional agent-side WASM module) + └─ src/ (optional TypeScript/JavaScript source) + ├─ ui.ts (compiled to assets/.js) + ├─ server.ts (compiled to server.js) + └─ shared.ts +``` + +For a legacy native v1 bundle, include platform-specific binaries named `--.` plus web assets. + +Plugin 2.0 example for plugin ID `sample-wasm`: + +``` +sample-wasm.zip + ├─ config.json + ├─ sample-wasm.html + ├─ sample-wasm.css + ├─ sample-wasm.wasm + └─ src/ + ├─ ui.ts + └─ server.ts ``` When the server extracts the zip: ``` -Overlord-Server/plugins/sample/ - ├─ sample-linux-amd64.so - ├─ sample-linux-arm64.so - ├─ sample-darwin-arm64.dylib - ├─ sample-windows-amd64.dll - ├─ server.js (optional — picked up by the plugin runtime) +Overlord-Server/plugins/sample-wasm/ + ├─ sample-wasm.wasm + ├─ server.js (compiled from src/server.ts when present) ├─ manifest.json (auto-generated, merged with config.json) + ├─ src/ (copied source files) ├─ data/ │ └─ plugin.db (auto-created when server.js is present) └─ assets/ - ├─ sample.html - ├─ sample.css - └─ sample.js + ├─ sample-wasm.html + ├─ sample-wasm.css + └─ sample-wasm.js (compiled from src/ui.ts or copied from root JS) ``` -### Architecture validation +### Runtime selection -The server matches binaries to clients by OS and architecture. Binary filenames **must** follow the naming convention `--.`: +`config.json` controls the runtime style: + +```json +{ + "apiVersion": 2, + "runtime": "wasm", + "wasm": "sample-wasm.wasm" +} +``` + +Use `runtime: "wasm"` when the plugin has an agent-side WASM module. Use `runtime: "server"` for UI/server-only Plugin 2.0 bundles. Legacy native bundles omit `apiVersion`/`runtime` or use `runtime: "native"`. + +### WASM architecture behavior + +WASM plugins are universal: the same `.wasm` file is sent to Windows, Linux, and macOS clients on any supported architecture. To branch by client platform, read HostInfo either from `overlord_on_load(hostInfo, hostInfoLen)` or by calling `overlord_host_info(out, outLen)`. + +Example HostInfo: + +```json +{ + "clientId": "abc123", + "os": "windows", + "arch": "amd64", + "version": "1.0.0" +} +``` + +### Legacy native architecture validation + +Legacy native v1 binaries are still matched to clients by OS and architecture. Binary filenames **must** follow the naming convention `--.`: | OS | Arch | Example filename | |----------|---------|------------------------------| @@ -67,7 +186,7 @@ The server matches binaries to clients by OS and architecture. Binary filenames | darwin | amd64 | `sample-darwin-amd64.dylib` | | darwin | arm64 | `sample-darwin-arm64.dylib` | -The server will **never** send an x64 binary to an ARM client (or vice versa). If no binary matches the client's platform, loading is skipped with an error. +The server will **never** send an x64 native binary to an ARM client (or vice versa). If no native binary matches the client's platform, loading is skipped with an error. ### Manifest fields @@ -77,13 +196,18 @@ The auto-generated manifest (merged with `config.json` if present): { "id": "sample", "name": "Sample Plugin", + "apiVersion": 2, + "runtime": "wasm", "version": "1.0.0", "description": "An example plugin", + "wasm": "sample.wasm", + "needs": { + "files": [ + { "bucket": "pluginData", "access": ["read", "write"], "reason": "Store plugin state" } + ] + }, "binaries": { - "linux-amd64": "sample-linux-amd64.so", - "linux-arm64": "sample-linux-arm64.so", - "darwin-arm64": "sample-darwin-arm64.dylib", - "windows-amd64": "sample-windows-amd64.dll" + "wasm32-wasi": "sample.wasm" }, "entry": "sample.html", "assets": { @@ -98,7 +222,7 @@ The auto-generated manifest (merged with `config.json` if present): } ``` -The `navbar` field is only present when a `config.json` is included in the bundle. +The `navbar`, `needs`, `wasm`, and TypeScript entrypoint fields are present only when declared or inferred from the bundle. ### Global Nav Bar Plugins (`config.json`) @@ -125,9 +249,11 @@ When the server extracts the bundle: > **Important:** `config.json` must be in the **root** of the zip (not inside a subfolder). The build scripts automatically include it if it exists at the plugin source root. The manifest is re-generated on every extraction (triggered when the zip is newer than `manifest.json`), so keep `config.json` in the zip to avoid losing the navbar registration on re-upload. -## 2) Plugin ABI (all languages) +## 2) Legacy native plugin ABI -Every plugin — regardless of language — must export **C-callable functions** with specific signatures. The ABI differs slightly between Windows and Unix. +This section applies only to legacy v1 native agent plugins. Plugin 2.0 WASM modules use the `overlord_*` ABI described above. + +Every native plugin must export **C-callable functions** with specific signatures. The ABI differs slightly between Windows and Unix. ### Required exports @@ -199,7 +325,18 @@ The `hostInfo` buffer passed to `PluginOnLoad` is JSON: - **Linux** — Shared libraries are loaded in memory via `memfd_create` + `dlopen` on `/proc/self/fd/`. No files touch disk. - **macOS** — Shared libraries are written to a temp file, `dlopen`'d, then the temp file is deleted. -## 3) Sample plugins by language +## 3) Sample plugins + +Current Plugin 2.0 samples: + +| Sample | Purpose | +|--------|---------| +| `sample-wasm` | C/WASI file bridge sample using `pluginData`, `downloads`, and `overlord_host_info`. | +| `sample-wasm-hostinfo` | TinyGo sample that queries HostInfo from a universal WASM module. | +| `sample-wasm-platform-note` | Rust sample that branches by `os`/`arch` inside one WASM module and writes a platform-specific note. | +| `sample-ts-fullstack` | TypeScript UI plus TypeScript server runtime with shared local modules. | + +Legacy native samples remain available: ### Go (`sample-go/`) @@ -390,18 +527,20 @@ cargo build --release --target=x86_64-pc-windows-msvc cargo build --release --target=aarch64-unknown-linux-gnu ``` -## 4) Build scripts & cross-compilation +## 4) Legacy native build scripts & cross-compilation -Each language has `.bat` (Windows) and `.sh` (Unix) build scripts. All scripts support the `BUILD_TARGETS` environment variable to compile for multiple platforms in one invocation. +This section applies to legacy native v1 plugins. Plugin 2.0 WASM modules are universal and do not need one binary per OS/architecture, though you still need a WASM toolchain such as WASI clang, Rust `wasm32-wasip1`, Zig, TinyGo, or AssemblyScript. + +Each legacy native sample keeps its `.bat` (Windows) and `.sh` (Unix) build scripts in the plugin's own directory. All scripts support the `BUILD_TARGETS` environment variable to compile for multiple platforms in one invocation. ### Available build scripts | Language | Windows | Unix | |----------|--------------------------|-------------------------| -| Go | `build-plugin.bat` | `build-plugin.sh` | -| C | `build-plugin-c.bat` | `build-plugin-c.sh` | -| C++ | `build-plugin-cpp.bat` | `build-plugin-cpp.sh` | -| Rust | `build-plugin-rust.bat` | `build-plugin-rust.sh` | +| Go | `sample-go/build.bat` | `sample-go/build.sh` | +| C | `sample-c/build.bat` | `sample-c/build.sh` | +| C++ | `sample-cpp/build.bat` | `sample-cpp/build.sh` | +| Rust | `sample-rust/build.bat` | `sample-rust/build.sh` | ### Usage @@ -409,25 +548,26 @@ All scripts default to building for the host platform only: ```bash # Build for current platform -./build-plugin-c.sh +cd sample-c +./build.sh # Build for multiple targets -BUILD_TARGETS="linux-amd64 linux-arm64 windows-amd64" ./build-plugin-c.sh +BUILD_TARGETS="linux-amd64 linux-arm64 windows-amd64" ./build.sh # Custom plugin directory -./build-plugin-c.sh /path/to/my-plugin +./build.sh /path/to/my-plugin ``` ```bat REM Build for current platform -build-plugin-c.bat +sample-c\build.bat REM Build for multiple targets set BUILD_TARGETS=windows-amd64 windows-arm64 -build-plugin-c.bat +sample-c\build.bat REM Custom plugin directory -build-plugin-c.bat C:\path\to\my-plugin +sample-c\build.bat C:\path\to\my-plugin ``` ### Cross-compilation @@ -460,8 +600,8 @@ On Windows `.bat` scripts, MSVC (`cl`) is tried first with the appropriate `/lin On Unix `.sh` scripts, override the compiler with `CC=` (C) or `CXX=` (C++): ```bash -CC=zig-cc BUILD_TARGETS="linux-arm64" ./build-plugin-c.sh -CXX=zig-c++ BUILD_TARGETS="linux-arm64" ./build-plugin-cpp.sh +CC=zig-cc BUILD_TARGETS="linux-arm64" ./sample-c/build.sh +CXX=zig-c++ BUILD_TARGETS="linux-arm64" ./sample-cpp/build.sh ``` ### Installing cross-compiler toolchains @@ -487,6 +627,50 @@ brew install FiloSottile/musl-cross/musl-cross rustup target add aarch64-apple-darwin x86_64-apple-darwin ``` +### WASM build examples + +Plugin 2.0 samples keep their Windows builders in their own plugin directories: + +| Script | Purpose | +|--------|---------| +| `sample-wasm/build.bat` | Builds and packages `sample-wasm`. | +| `sample-wasm-hostinfo/build.bat` | Builds and packages `sample-wasm-hostinfo`. | +| `sample-wasm-platform-note/build.bat` | Builds and packages `sample-wasm-platform-note`. | +| `sample-ts-fullstack/build.bat` | Packages the TypeScript UI/server sample; the server compiles TypeScript during extraction. | + +Usage: + +```bat +REM Per-sample Plugin 2.0 build +sample-ts-fullstack\build.bat +sample-wasm\build.bat +``` + +The sample WASM plugins intentionally use different source languages: + +| Sample | Source language | Toolchain | +|--------|-----------------|-----------| +| `sample-wasm` | C | WASI-capable `clang` | +| `sample-wasm-hostinfo` | Go | TinyGo 0.41.0+ with `-target=wasi` | +| `sample-wasm-platform-note` | Rust | Rust target `wasm32-wasip1` | + +A minimal manual C/WASI build for `sample-wasm` looks like: + +```bash +clang --target=wasm32-wasi -O2 \ + -Wl,--no-entry \ + -Wl,--export=overlord_alloc \ + -Wl,--export=overlord_free \ + -Wl,--export=overlord_on_load \ + -Wl,--export=overlord_on_event \ + -Wl,--export=overlord_on_unload \ + -o sample-wasm.wasm native/sample_wasm.c +``` + +The generated `.wasm` goes at the root of the plugin zip and is referenced by `config.json`. + +For the TinyGo sample, install TinyGo 0.41.0 or newer and run `sample-wasm-hostinfo\build.bat`. For the Rust sample, install the target with `rustup target add wasm32-wasip1`, then run `sample-wasm-platform-note\build.bat`. + ## 5) Install & open a plugin ### Install / upload @@ -508,7 +692,7 @@ For **global nav bar plugins** (those registered via `config.json`), the UI open /plugins/ ``` -The server reads your `.html`, extracts the body content, and renders it inside the standard Overlord layout. Your CSS and JS are loaded from `/plugins//assets/`. +The server reads your `.html`, extracts the body content, and renders it inside the standard Overlord layout. Your CSS and generated/copied JS are loaded from `/plugins//assets/`. To get the `clientId` in your JS (for per-client plugins): @@ -529,7 +713,9 @@ const onlineIds = items.filter(c => c.online).map(c => c.id); Overlord plugins have **two parts**: 1. **UI (HTML/CSS/JS)** — Runs in the browser, calls server APIs. -2. **Native module** — Runs in the agent (client) process as a loaded shared library. +2. **Optional agent module** — Plugin 2.0 uses WASM; legacy v1 uses native shared libraries. + +Plugins can also include optional **server-side logic** through `server.js` or compiled `src/server.ts`. That code runs in the server plugin worker and exposes RPC/broadcast APIs to the UI. ### UI → agent (plugin event) @@ -545,13 +731,13 @@ POST /api/clients//plugins//event If the plugin is not loaded yet, the server will load it on the client, queue the event, and deliver it once ready. -### Agent → plugin (direct function call) +### Agent → plugin -The agent calls your `OnEvent(event, payload)` function directly with JSON-encoded data. No stdin/stdout pipes, no msgpack — just a direct function call. +For WASM plugins, the agent calls `overlord_on_event(eventPtr, eventLen, payloadPtr, payloadLen)`. For legacy native plugins, the agent calls `PluginOnEvent(event, payload)`. In both cases the payload is JSON-encoded data from the UI/server. -### Plugin → agent (callback) +### Plugin → agent/server events -Your plugin sends events back to the host using the callback received during `OnLoad`: +WASM plugins send events with `overlord_emit(event, eventLen, payload, payloadLen)`. Legacy native plugins use the callback received during `PluginOnLoad`. **Go:** ```go @@ -582,7 +768,16 @@ The agent sends these events to the server: ## 7) What can plugins do? -Since plugins run as native code, they can: +WASM Plugin 2.0 agent modules are sandboxed. They can: + +- Receive UI/server events. +- Send events back through `overlord_emit`. +- Read HostInfo (`clientId`, `os`, `arch`, `version`). +- Use declared file bridges after the user approves the plugin's `needs`. + +WASM modules cannot directly access arbitrary files, processes, network sockets, or OS APIs unless Overlord exposes an explicit host bridge. + +Legacy native v1 plugins run as native code and can: - Call any system API (file I/O, network, processes, etc.) - Use any library available to their language @@ -590,7 +785,7 @@ Since plugins run as native code, they can: - Access hardware - Do anything a normal native program can do -Plugins have the same capabilities as the agent itself. +Legacy native plugins have the same capabilities as the agent itself. | Language | Can be fully unloaded? | Runtime overhead | |----------|----------------------|------------------| @@ -647,9 +842,10 @@ If you want defensive scoping anyway, wrap your plugin JS in an IIFE so top-leve ### Plugin management -- `GET /api/plugins` — list installed plugins (includes `autoLoad` and `autoStartEvents` per plugin) +- `GET /api/plugins` — list installed plugins, including `runtime`, `apiVersion`, `needs`, `needsHash`, `needsApproved`, `autoLoad`, and `autoStartEvents` - `POST /api/plugins/upload` — upload zip - `POST /api/plugins//enable` — enable/disable +- `POST /api/plugins//needs/approve` — approve the currently declared Plugin 2.0 needs hash - `POST /api/plugins//autoload` — configure auto-load on client connect - `DELETE /api/plugins/` — remove (preserves `data/` directory) @@ -775,10 +971,11 @@ Content-Type: application/json ### Notes - Auto-load respects the `enabled` flag — disabled plugins are never auto-loaded +- Auto-load for plugins with declared `needs` is blocked until those needs are approved - Auto-load state is persisted in `.plugin-state.json` and survives server restarts - Deleting a plugin also removes its auto-load configuration -- The server selects the correct binary for each client's OS/architecture automatically -- If a plugin binary isn't available for a client's platform, the auto-load silently skips that client +- WASM plugins use one universal module for every OS/architecture +- Legacy native plugins still require a compatible binary for each target platform; if one is unavailable, auto-load skips that client ## 10) Server-side plugin data directory @@ -1197,11 +1394,11 @@ Set the `PLUGIN_SIGN_KEY` environment variable to automatically sign plugins dur ```bash # Unix -PLUGIN_SIGN_KEY=path/to/my-signing-key.key ./build-plugin.sh +PLUGIN_SIGN_KEY=path/to/my-signing-key.key ./sample-go/build.sh # Windows set PLUGIN_SIGN_KEY=path\to\my-signing-key.key -build-plugin.bat +sample-go\build.bat ``` ### How Signing Works diff --git a/plugins/build-plugin-c.bat b/plugins/sample-c/build.bat similarity index 98% rename from plugins/build-plugin-c.bat rename to plugins/sample-c/build.bat index 12e74bc..edd819b 100644 --- a/plugins/build-plugin-c.bat +++ b/plugins/sample-c/build.bat @@ -1,8 +1,7 @@ @echo off setlocal enabledelayedexpansion -set "ROOT=%~dp0" -set "PLUGIN_DIR=%ROOT%sample-c" +set "PLUGIN_DIR=%~dp0." if not "%~1"=="" set "PLUGIN_DIR=%~1" set "NATIVE_DIR=%PLUGIN_DIR%\native" diff --git a/plugins/build-plugin-c.sh b/plugins/sample-c/build.sh similarity index 98% rename from plugins/build-plugin-c.sh rename to plugins/sample-c/build.sh index 43326df..c705145 100644 --- a/plugins/build-plugin-c.sh +++ b/plugins/sample-c/build.sh @@ -2,7 +2,7 @@ set -euo pipefail ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PLUGIN_DIR="${1:-${ROOT_DIR}/sample-c}" +PLUGIN_DIR="${1:-${ROOT_DIR}}" NATIVE_DIR="${PLUGIN_DIR}/native" PLUGIN_NAME="sample-c" ZIP_OUT="${PLUGIN_DIR}/${PLUGIN_NAME}.zip" diff --git a/plugins/build-plugin-cpp.bat b/plugins/sample-cpp/build.bat similarity index 98% rename from plugins/build-plugin-cpp.bat rename to plugins/sample-cpp/build.bat index 2d9ee68..2ac2276 100644 --- a/plugins/build-plugin-cpp.bat +++ b/plugins/sample-cpp/build.bat @@ -1,8 +1,7 @@ @echo off setlocal enabledelayedexpansion -set "ROOT=%~dp0" -set "PLUGIN_DIR=%ROOT%sample-cpp" +set "PLUGIN_DIR=%~dp0." if not "%~1"=="" set "PLUGIN_DIR=%~1" set "NATIVE_DIR=%PLUGIN_DIR%\native" diff --git a/plugins/build-plugin-cpp.sh b/plugins/sample-cpp/build.sh similarity index 98% rename from plugins/build-plugin-cpp.sh rename to plugins/sample-cpp/build.sh index c84f101..faaf6c9 100644 --- a/plugins/build-plugin-cpp.sh +++ b/plugins/sample-cpp/build.sh @@ -2,7 +2,7 @@ set -euo pipefail ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PLUGIN_DIR="${1:-${ROOT_DIR}/sample-cpp}" +PLUGIN_DIR="${1:-${ROOT_DIR}}" NATIVE_DIR="${PLUGIN_DIR}/native" PLUGIN_NAME="sample-cpp" ZIP_OUT="${PLUGIN_DIR}/${PLUGIN_NAME}.zip" diff --git a/plugins/sample-go/README.md b/plugins/sample-go/README.md index 70a2643..0818912 100644 --- a/plugins/sample-go/README.md +++ b/plugins/sample-go/README.md @@ -16,13 +16,14 @@ Use the provided build scripts: ```bash # Linux/macOS -./build-plugin.sh +cd sample-go +./build.sh # Multiple targets -BUILD_TARGETS="linux-amd64 linux-arm64 darwin-arm64" ./build-plugin.sh +BUILD_TARGETS="linux-amd64 linux-arm64 darwin-arm64" ./build.sh # Windows -build-plugin.bat +sample-go\build.bat ``` ## Create the zip diff --git a/plugins/build-plugin.bat b/plugins/sample-go/build.bat similarity index 95% rename from plugins/build-plugin.bat rename to plugins/sample-go/build.bat index fa27c90..99495a0 100644 --- a/plugins/build-plugin.bat +++ b/plugins/sample-go/build.bat @@ -1,8 +1,7 @@ @echo off setlocal enabledelayedexpansion -set "ROOT=%~dp0" -set "PLUGIN_DIR=%ROOT%sample-go" +set "PLUGIN_DIR=%~dp0." if not "%~1"=="" set "PLUGIN_DIR=%~1" set "NATIVE_DIR=%PLUGIN_DIR%\native" @@ -92,7 +91,7 @@ if defined PLUGIN_SIGN_KEY ( where bun >nul 2>&1 if not errorlevel 1 ( echo [sign] Signing plugin with key: %PLUGIN_SIGN_KEY% - bun run "%ROOT%Overlord-Server\scripts\plugin-sign.ts" --key "%PLUGIN_SIGN_KEY%" "%ZIP_OUT%" + bun run "%~dp0..\..\Overlord-Server\scripts\plugin-sign.ts" --key "%PLUGIN_SIGN_KEY%" "%ZIP_OUT%" ) else ( echo [warn] bun not found, skipping plugin signing ) diff --git a/plugins/build-plugin.sh b/plugins/sample-go/build.sh similarity index 90% rename from plugins/build-plugin.sh rename to plugins/sample-go/build.sh index 20f0ae8..889126d 100644 --- a/plugins/build-plugin.sh +++ b/plugins/sample-go/build.sh @@ -2,7 +2,7 @@ set -euo pipefail ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PLUGIN_DIR="${1:-${ROOT_DIR}/sample-go}" +PLUGIN_DIR="${1:-${ROOT_DIR}}" NATIVE_DIR="${PLUGIN_DIR}/native" PLUGIN_NAME="sample" ZIP_OUT="${PLUGIN_DIR}/${PLUGIN_NAME}.zip" @@ -69,10 +69,9 @@ fi # Optional: sign the plugin if PLUGIN_SIGN_KEY is set if [[ -n "${PLUGIN_SIGN_KEY:-}" ]]; then - SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" if command -v bun >/dev/null 2>&1; then echo "[sign] Signing plugin with key: ${PLUGIN_SIGN_KEY}" - bun run "${SCRIPT_DIR}/Overlord-Server/scripts/plugin-sign.ts" --key "${PLUGIN_SIGN_KEY}" "${ZIP_OUT}" + bun run "${ROOT_DIR}/../../Overlord-Server/scripts/plugin-sign.ts" --key "${PLUGIN_SIGN_KEY}" "${ZIP_OUT}" else echo "[warn] bun not found, skipping plugin signing" >&2 fi diff --git a/plugins/build-plugin-rust.bat b/plugins/sample-rust/build.bat similarity index 98% rename from plugins/build-plugin-rust.bat rename to plugins/sample-rust/build.bat index 0896c0f..1182267 100644 --- a/plugins/build-plugin-rust.bat +++ b/plugins/sample-rust/build.bat @@ -1,8 +1,7 @@ @echo off setlocal enabledelayedexpansion -set "ROOT=%~dp0" -set "PLUGIN_DIR=%ROOT%sample-rust" +set "PLUGIN_DIR=%~dp0." if not "%~1"=="" set "PLUGIN_DIR=%~1" set "NATIVE_DIR=%PLUGIN_DIR%\native" diff --git a/plugins/build-plugin-rust.sh b/plugins/sample-rust/build.sh similarity index 98% rename from plugins/build-plugin-rust.sh rename to plugins/sample-rust/build.sh index c22d254..d1acade 100644 --- a/plugins/build-plugin-rust.sh +++ b/plugins/sample-rust/build.sh @@ -2,7 +2,7 @@ set -euo pipefail ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PLUGIN_DIR="${1:-${ROOT_DIR}/sample-rust}" +PLUGIN_DIR="${1:-${ROOT_DIR}}" NATIVE_DIR="${PLUGIN_DIR}/native" PLUGIN_NAME="sample-rust" ZIP_OUT="${PLUGIN_DIR}/${PLUGIN_NAME}.zip" diff --git a/plugins/sample-ts-fullstack/README.md b/plugins/sample-ts-fullstack/README.md new file mode 100644 index 0000000..6f34394 --- /dev/null +++ b/plugins/sample-ts-fullstack/README.md @@ -0,0 +1,9 @@ +# Sample TS Fullstack Plugin + +This sample intentionally ships TypeScript source instead of generated JavaScript. + +The server extracts the bundle, compiles `src/ui.ts` to `assets/sample-ts-fullstack.js`, and compiles `src/server.ts` to `server.js`. Both entrypoints import `src/shared.ts`, demonstrating that plugin authors can split logic across multiple TypeScript files. + +No package install is performed during plugin extraction; use relative imports or APIs already available in the browser/server runtime. + +On Windows, run this sample's local `build.bat` to create `sample-ts-fullstack.zip`. The batch file packages the TypeScript sources cleanly; compilation still happens on the server during extraction. diff --git a/plugins/sample-ts-fullstack/build.bat b/plugins/sample-ts-fullstack/build.bat new file mode 100644 index 0000000..1614f8f --- /dev/null +++ b/plugins/sample-ts-fullstack/build.bat @@ -0,0 +1,60 @@ +@echo off +setlocal enabledelayedexpansion + +set "PLUGIN_DIR=%~dp0" +set "PLUGIN_NAME=sample-ts-fullstack" + +set "NATIVE_DIR=%PLUGIN_DIR%\native" +set "WASM_OUT=%PLUGIN_DIR%\%PLUGIN_NAME%.wasm" +set "ZIP_OUT=%PLUGIN_DIR%\%PLUGIN_NAME%.zip" + +if not exist "%PLUGIN_DIR%\config.json" ( + echo [error] config.json not found in %PLUGIN_DIR% + exit /b 1 +) + +set "WASM_SOURCE=" +if exist "%NATIVE_DIR%" ( + for %%S in ("%NATIVE_DIR%\*.c") do ( + if not defined WASM_SOURCE set "WASM_SOURCE=%%~fS" + ) +) + +if defined WASM_SOURCE ( + where clang >nul 2>&1 + if errorlevel 1 ( + echo [error] clang was not found. Install a WASI-capable clang or provide %WASM_OUT% yourself. + exit /b 1 + ) + + echo [build] clang --target=wasm32-wasi -O2 "!WASM_SOURCE!" ^> "%WASM_OUT%" + clang --target=wasm32-wasi -O2 -Wl,--no-entry -Wl,--allow-undefined -Wl,--export=overlord_alloc -Wl,--export=overlord_free -Wl,--export=overlord_on_load -Wl,--export=overlord_on_event -Wl,--export=overlord_on_unload -o "%WASM_OUT%" "!WASM_SOURCE!" + if errorlevel 1 ( + echo [error] WASM build failed + exit /b 1 + ) +) + +if exist "%ZIP_OUT%" del /f /q "%ZIP_OUT%" + +pushd "%PLUGIN_DIR%" +powershell -NoProfile -ExecutionPolicy Bypass -Command "$zip = '%ZIP_OUT%'; $items = @(); foreach ($file in @('config.json', '%PLUGIN_NAME%.html', '%PLUGIN_NAME%.css', '%PLUGIN_NAME%.js', '%PLUGIN_NAME%.wasm', 'server.js')) { if (Test-Path -LiteralPath $file -PathType Leaf) { $items += $file } }; foreach ($dir in @('src', 'assets')) { if (Test-Path -LiteralPath $dir -PathType Container) { $items += $dir } }; if ($items.Count -eq 0) { throw 'No plugin files found to package' }; Compress-Archive -Path $items -DestinationPath $zip -Force" +set "ZIP_STATUS=%ERRORLEVEL%" +popd +if not "%ZIP_STATUS%"=="0" exit /b %ZIP_STATUS% +if errorlevel 1 ( + echo [error] zip failed + exit /b 1 +) + +if defined PLUGIN_SIGN_KEY ( + where bun >nul 2>&1 + if not errorlevel 1 ( + echo [sign] Signing plugin with key: %PLUGIN_SIGN_KEY% + bun run "%~dp0..\..\Overlord-Server\scripts\plugin-sign.ts" --key "%PLUGIN_SIGN_KEY%" "%ZIP_OUT%" + ) else ( + echo [warn] bun not found, skipping plugin signing + ) +) + +echo [ok] %ZIP_OUT% diff --git a/plugins/sample-ts-fullstack/sample-ts-fullstack.css b/plugins/sample-ts-fullstack/sample-ts-fullstack.css new file mode 100644 index 0000000..1de0329 --- /dev/null +++ b/plugins/sample-ts-fullstack/sample-ts-fullstack.css @@ -0,0 +1,3 @@ +#sample-ts-output { + min-height: 9rem; +} diff --git a/plugins/sample-ts-fullstack/sample-ts-fullstack.html b/plugins/sample-ts-fullstack/sample-ts-fullstack.html new file mode 100644 index 0000000..142c7b9 --- /dev/null +++ b/plugins/sample-ts-fullstack/sample-ts-fullstack.html @@ -0,0 +1,11 @@ +
+
+

Sample TS Fullstack

+

Multiple TypeScript files compiled by the server at plugin extraction time.

+
+
+ + +
+ 

+

diff --git a/plugins/sample-ts-fullstack/src/server.ts b/plugins/sample-ts-fullstack/src/server.ts
new file mode 100644
index 0000000..d99a925
--- /dev/null
+++ b/plugins/sample-ts-fullstack/src/server.ts
@@ -0,0 +1,41 @@
+import type { RpcResponse } from "./shared";
+
+type PluginContext = {
+  db: {
+    exec(sql: string): void;
+    prepare(sql: string): {
+      get(...args: unknown[]): any;
+      run(...args: unknown[]): any;
+    };
+  };
+  log: { info(message: string): void };
+};
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function response(message: string, count?: number): RpcResponse {
+  return { message, count, at: now() };
+}
+
+export default {
+  setup(ctx: PluginContext) {
+    ctx.db.exec("CREATE TABLE IF NOT EXISTS counter (id INTEGER PRIMARY KEY CHECK (id = 1), value INTEGER NOT NULL)");
+    ctx.db.prepare("INSERT OR IGNORE INTO counter (id, value) VALUES (1, 0)").run();
+    ctx.log.info("sample-ts-fullstack ready");
+  },
+
+  rpc: {
+    ping(): RpcResponse {
+      return response("hello from TypeScript server");
+    },
+
+    increment(ctx: PluginContext, params: unknown): RpcResponse {
+      const by = typeof (params as any)?.by === "number" ? Math.trunc((params as any).by) : 1;
+      ctx.db.prepare("UPDATE counter SET value = value + ? WHERE id = 1").run(by);
+      const row = ctx.db.prepare("SELECT value FROM counter WHERE id = 1").get();
+      return response("counter updated", Number(row?.value || 0));
+    },
+  },
+};
diff --git a/plugins/sample-ts-fullstack/src/shared.ts b/plugins/sample-ts-fullstack/src/shared.ts
new file mode 100644
index 0000000..5d1eecd
--- /dev/null
+++ b/plugins/sample-ts-fullstack/src/shared.ts
@@ -0,0 +1,10 @@
+export type RpcResponse = {
+  message: string;
+  count?: number;
+  at: string;
+};
+
+export function formatLine(label: string, value: RpcResponse): string {
+  const count = typeof value.count === "number" ? ` count=${value.count}` : "";
+  return `${label}: ${value.message}${count} at ${value.at}`;
+}
diff --git a/plugins/sample-ts-fullstack/src/ui.ts b/plugins/sample-ts-fullstack/src/ui.ts
new file mode 100644
index 0000000..24c99dd
--- /dev/null
+++ b/plugins/sample-ts-fullstack/src/ui.ts
@@ -0,0 +1,39 @@
+import { formatLine, type RpcResponse } from "./shared";
+
+const output = document.getElementById("sample-ts-output");
+const pingButton = document.getElementById("sample-ts-ping");
+const countButton = document.getElementById("sample-ts-count");
+
+function append(message: string) {
+  if (!output) return;
+  output.textContent = `${message}\n${output.textContent || ""}`;
+}
+
+async function rpc(method: string, params?: unknown): Promise {
+  const res = await fetch("/api/plugins/sample-ts-fullstack/rpc", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ method, params }),
+  });
+  const body = await res.json();
+  if (!res.ok || body.ok === false) {
+    throw new Error(body.error || res.statusText);
+  }
+  return body.result as RpcResponse;
+}
+
+pingButton?.addEventListener("click", async () => {
+  try {
+    append(formatLine("ping", await rpc("ping")));
+  } catch (err) {
+    append(`ping failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+});
+
+countButton?.addEventListener("click", async () => {
+  try {
+    append(formatLine("increment", await rpc("increment", { by: 1 })));
+  } catch (err) {
+    append(`increment failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+});
diff --git a/plugins/sample-wasm-hostinfo/README.md b/plugins/sample-wasm-hostinfo/README.md
new file mode 100644
index 0000000..fd4640f
--- /dev/null
+++ b/plugins/sample-wasm-hostinfo/README.md
@@ -0,0 +1,5 @@
+# Sample WASM HostInfo Plugin
+
+This Plugin 2.0 sample is written in Go for TinyGo. It demonstrates how a universal WASM module can read HostInfo and emit it back to the UI.
+
+On Windows, install TinyGo 0.41.0 or newer, then run this sample's local `build.bat`. TinyGo 0.41.0 added Go 1.26 support. The builder runs `tinygo build -target=wasi`, writes `sample-wasm-hostinfo.wasm`, and creates `sample-wasm-hostinfo.zip`.
diff --git a/plugins/sample-wasm-hostinfo/build.bat b/plugins/sample-wasm-hostinfo/build.bat
new file mode 100644
index 0000000..7be4707
--- /dev/null
+++ b/plugins/sample-wasm-hostinfo/build.bat
@@ -0,0 +1,55 @@
+@echo off
+setlocal enabledelayedexpansion
+
+set "PLUGIN_DIR=%~dp0"
+set "PLUGIN_NAME=sample-wasm-hostinfo"
+
+set "NATIVE_DIR=%PLUGIN_DIR%\native"
+set "WASM_OUT=%PLUGIN_DIR%\%PLUGIN_NAME%.wasm"
+set "ZIP_OUT=%PLUGIN_DIR%\%PLUGIN_NAME%.zip"
+
+if not exist "%PLUGIN_DIR%\config.json" (
+  echo [error] config.json not found in %PLUGIN_DIR%
+  exit /b 1
+)
+
+set "WASM_SOURCE=%NATIVE_DIR%\main.go"
+
+if exist "%WASM_SOURCE%" (
+  where tinygo >nul 2>&1
+  if errorlevel 1 (
+    echo [error] tinygo was not found. Install TinyGo or provide %WASM_OUT% yourself.
+    exit /b 1
+  )
+
+  echo [build] tinygo build -target=wasi -opt=2 -no-debug -o "%WASM_OUT%" "%WASM_SOURCE%"
+  tinygo build -target=wasi -opt=2 -no-debug -o "%WASM_OUT%" "%WASM_SOURCE%"
+  if errorlevel 1 (
+    echo [error] WASM build failed
+    exit /b 1
+  )
+)
+
+if exist "%ZIP_OUT%" del /f /q "%ZIP_OUT%"
+
+pushd "%PLUGIN_DIR%"
+powershell -NoProfile -ExecutionPolicy Bypass -Command "$zip = '%ZIP_OUT%'; $items = @(); foreach ($file in @('config.json', '%PLUGIN_NAME%.html', '%PLUGIN_NAME%.css', '%PLUGIN_NAME%.js', '%PLUGIN_NAME%.wasm', 'server.js')) { if (Test-Path -LiteralPath $file -PathType Leaf) { $items += $file } }; foreach ($dir in @('src', 'assets')) { if (Test-Path -LiteralPath $dir -PathType Container) { $items += $dir } }; if ($items.Count -eq 0) { throw 'No plugin files found to package' }; Compress-Archive -Path $items -DestinationPath $zip -Force"
+set "ZIP_STATUS=%ERRORLEVEL%"
+popd
+if not "%ZIP_STATUS%"=="0" exit /b %ZIP_STATUS%
+if errorlevel 1 (
+  echo [error] zip failed
+  exit /b 1
+)
+
+if defined PLUGIN_SIGN_KEY (
+  where bun >nul 2>&1
+  if not errorlevel 1 (
+    echo [sign] Signing plugin with key: %PLUGIN_SIGN_KEY%
+    bun run "%~dp0..\..\Overlord-Server\scripts\plugin-sign.ts" --key "%PLUGIN_SIGN_KEY%" "%ZIP_OUT%"
+  ) else (
+    echo [warn] bun not found, skipping plugin signing
+  )
+)
+
+echo [ok] %ZIP_OUT%
diff --git a/plugins/sample-wasm-hostinfo/native/main.go b/plugins/sample-wasm-hostinfo/native/main.go
new file mode 100644
index 0000000..d66ec4f
--- /dev/null
+++ b/plugins/sample-wasm-hostinfo/native/main.go
@@ -0,0 +1,93 @@
+package main
+
+import "unsafe"
+
+//go:wasmimport env overlord_emit
+func overlordEmit(eventPtr, eventLen, payloadPtr, payloadLen uint32) int32
+
+//go:wasmimport env overlord_host_info
+func overlordHostInfo(outPtr, outLen uint32) int32
+
+var heap = make([]byte, 64*1024)
+var heapOffset uint32 = 8
+
+var hostInfo [1024]byte
+var hostInfoLen uint32
+
+//go:export overlord_alloc
+func overlordAlloc(size uint32) uint32 {
+	if size == 0 {
+		size = 1
+	}
+	ptr := (heapOffset + 7) &^ 7
+	next := ptr + size
+	if next >= uint32(len(heap)) {
+		return 0
+	}
+	heapOffset = next
+	return uint32(uintptr(unsafe.Pointer(&heap[ptr])))
+}
+
+//go:export overlord_free
+func overlordFree(ptr, size uint32) {
+	_, _ = ptr, size
+}
+
+//go:export overlord_on_load
+func overlordOnLoad(hostPtr, hostLen uint32) int32 {
+	n := hostLen
+	if n > uint32(len(hostInfo)) {
+		n = uint32(len(hostInfo))
+	}
+	copy(hostInfo[:n], bytesAt(hostPtr, n))
+	hostInfoLen = n
+	emit("ready", hostInfo[:hostInfoLen])
+	return 0
+}
+
+//go:export overlord_on_event
+func overlordOnEvent(eventPtr, eventLen, payloadPtr, payloadLen uint32) int32 {
+	_, _ = payloadPtr, payloadLen
+	event := string(bytesAt(eventPtr, eventLen))
+	if event != "query_host" {
+		return 0
+	}
+
+	var buf [1024]byte
+	n := overlordHostInfo(uint32(uintptr(unsafe.Pointer(&buf[0]))), uint32(len(buf)))
+	if n < 0 {
+		emitString("host_info", `{"error":"host info buffer too small"}`)
+		return 0
+	}
+	emit("host_info", buf[:uint32(n)])
+	return 0
+}
+
+//go:export overlord_on_unload
+func overlordOnUnload() {}
+
+func emitString(event string, payload string) {
+	emit(event, []byte(payload))
+}
+
+func emit(event string, payload []byte) {
+	eventBytes := []byte(event)
+	var eventPtr uint32
+	var payloadPtr uint32
+	if len(eventBytes) > 0 {
+		eventPtr = uint32(uintptr(unsafe.Pointer(&eventBytes[0])))
+	}
+	if len(payload) > 0 {
+		payloadPtr = uint32(uintptr(unsafe.Pointer(&payload[0])))
+	}
+	overlordEmit(eventPtr, uint32(len(eventBytes)), payloadPtr, uint32(len(payload)))
+}
+
+func bytesAt(ptr, length uint32) []byte {
+	if length == 0 {
+		return nil
+	}
+	return unsafe.Slice((*byte)(unsafe.Pointer(uintptr(ptr))), length)
+}
+
+func main() {}
diff --git a/plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.css b/plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.css
new file mode 100644
index 0000000..7203fb6
--- /dev/null
+++ b/plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.css
@@ -0,0 +1,22 @@
+#sample-wasm-hostinfo-output {
+  min-height: 8rem;
+}
+
+.sample-wasm-hostinfo-field {
+  border: 1px solid rgba(8, 145, 178, 0.45);
+  background: rgba(8, 47, 73, 0.28);
+  padding: 0.75rem;
+}
+
+.sample-wasm-hostinfo-field span {
+  display: block;
+  color: rgb(148, 163, 184);
+  font-size: 0.75rem;
+}
+
+.sample-wasm-hostinfo-field strong {
+  display: block;
+  color: rgb(224, 242, 254);
+  font-size: 0.95rem;
+  overflow-wrap: anywhere;
+}
diff --git a/plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.html b/plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.html
new file mode 100644
index 0000000..3a469d7
--- /dev/null
+++ b/plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.html
@@ -0,0 +1,12 @@
+

+  
Sample WASM Host Info

+  
+  
Waiting for host info

+  

+    
Client-

+    
Version-

+    
OS-

+    
Arch-

+  

+  

+

diff --git a/plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.js b/plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.js
new file mode 100644
index 0000000..ce71590
--- /dev/null
+++ b/plugins/sample-wasm-hostinfo/sample-wasm-hostinfo.js
@@ -0,0 +1,93 @@
+(() => {
+  const out = document.getElementById("sample-wasm-hostinfo-output");
+  const btn = document.getElementById("sample-wasm-hostinfo-run");
+  const status = document.getElementById("sample-wasm-hostinfo-status");
+  const fields = {
+    clientId: document.getElementById("sample-wasm-hostinfo-client"),
+    version: document.getElementById("sample-wasm-hostinfo-version"),
+    os: document.getElementById("sample-wasm-hostinfo-os"),
+    arch: document.getElementById("sample-wasm-hostinfo-arch"),
+  };
+  const clientId = new URLSearchParams(window.location.search).get("clientId");
+  const pluginId = "sample-wasm-hostinfo";
+  let polling = false;
+
+  function log(message) {
+    if (out) out.textContent = `${message}\n${out.textContent || ""}`;
+  }
+
+  function setStatus(message) {
+    if (status) status.textContent = message;
+  }
+
+  function parsePayload(payload) {
+    if (payload == null) return {};
+    if (typeof payload === "string") {
+      try { return JSON.parse(payload); } catch (_) { return { raw: payload }; }
+    }
+    return payload;
+  }
+
+  function renderHostInfo(payload) {
+    const info = parsePayload(payload);
+    if (info.error) {
+      setStatus(info.error);
+      log(JSON.stringify(info, null, 2));
+      return;
+    }
+    if (fields.clientId) fields.clientId.textContent = info.clientId || "-";
+    if (fields.version) fields.version.textContent = info.version || "-";
+    if (fields.os) fields.os.textContent = info.os || "-";
+    if (fields.arch) fields.arch.textContent = info.arch || "-";
+    setStatus("Host info received");
+    log(JSON.stringify(info, null, 2));
+  }
+
+  function handlePluginEvent(event, payload) {
+    if (event === "ready" || event === "host_info") renderHostInfo(payload);
+  }
+
+  window.addEventListener("message", (e) => {
+    if (!e.data || e.data.type !== "plugin_event") return;
+    if (e.data.pluginId && e.data.pluginId !== pluginId) return;
+    handlePluginEvent(e.data.event, e.data.payload);
+  });
+
+  async function pollEvents() {
+    if (!clientId || polling) return;
+    polling = true;
+    try {
+      const res = await fetch(`/api/clients/${encodeURIComponent(clientId)}/plugins/${pluginId}/events`, {
+        headers: { Accept: "application/json" },
+      });
+      if (res.ok) {
+        const data = await res.json();
+        if (data.events) data.events.forEach((e) => handlePluginEvent(e.event, e.payload));
+      }
+    } catch (_) {
+      // Polling is best-effort; the next interval can recover.
+    } finally {
+      polling = false;
+    }
+  }
+
+  btn?.addEventListener("click", async () => {
+    if (!clientId) {
+      setStatus("Open this plugin from a client row so clientId is present.");
+      return;
+    }
+    setStatus("Requesting host info");
+    const res = await fetch(`/api/clients/${encodeURIComponent(clientId)}/plugins/sample-wasm-hostinfo/event`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ event: "query_host", payload: {} }),
+    });
+    if (!res.ok) setStatus(`Send failed: ${res.status}`);
+    setTimeout(pollEvents, 250);
+  });
+
+  if (clientId) {
+    setInterval(pollEvents, 1500);
+    setTimeout(pollEvents, 300);
+  }
+})();
diff --git a/plugins/sample-wasm-platform-note/README.md b/plugins/sample-wasm-platform-note/README.md
new file mode 100644
index 0000000..6540877
--- /dev/null
+++ b/plugins/sample-wasm-platform-note/README.md
@@ -0,0 +1,11 @@
+# Sample WASM Platform Note Plugin
+
+This Plugin 2.0 sample is written in Rust. It reads HostInfo, branches on `os` and `arch`, and writes a small note into the approved `pluginData` bucket.
+
+On Windows, install the Rust WASI target first:
+
+```bat
+rustup target add wasm32-wasip1
+```
+
+Then run this sample's local `build.bat`. The builder runs Cargo, writes `sample-wasm-platform-note.wasm`, and creates `sample-wasm-platform-note.zip`.
diff --git a/plugins/sample-wasm-platform-note/build.bat b/plugins/sample-wasm-platform-note/build.bat
new file mode 100644
index 0000000..c4d4cd3
--- /dev/null
+++ b/plugins/sample-wasm-platform-note/build.bat
@@ -0,0 +1,76 @@
+@echo off
+setlocal enabledelayedexpansion
+
+set "PLUGIN_DIR=%~dp0"
+set "PLUGIN_NAME=sample-wasm-platform-note"
+
+set "NATIVE_DIR=%PLUGIN_DIR%\native"
+set "WASM_OUT=%PLUGIN_DIR%\%PLUGIN_NAME%.wasm"
+set "ZIP_OUT=%PLUGIN_DIR%\%PLUGIN_NAME%.zip"
+
+if not exist "%PLUGIN_DIR%\config.json" (
+  echo [error] config.json not found in %PLUGIN_DIR%
+  exit /b 1
+)
+
+set "RUST_MANIFEST=%NATIVE_DIR%\Cargo.toml"
+
+if exist "%RUST_MANIFEST%" (
+  where cargo >nul 2>&1
+  if errorlevel 1 (
+    echo [error] cargo was not found. Install Rust or provide %WASM_OUT% yourself.
+    exit /b 1
+  )
+
+  where rustup >nul 2>&1
+  if errorlevel 1 (
+    echo [error] rustup was not found. Install the Rust target manually: rustup target add wasm32-wasip1
+    exit /b 1
+  )
+
+  rustup target list --installed | findstr /x "wasm32-wasip1" >nul 2>&1
+  if errorlevel 1 (
+    echo [setup] Installing Rust target wasm32-wasip1
+    rustup target add wasm32-wasip1
+    if errorlevel 1 (
+      echo [error] Could not install wasm32-wasip1. Run this manually: rustup target add wasm32-wasip1
+      exit /b 1
+    )
+  )
+
+  echo [build] cargo build --manifest-path "%RUST_MANIFEST%" --release --target wasm32-wasip1
+  cargo build --manifest-path "%RUST_MANIFEST%" --release --target wasm32-wasip1
+  if errorlevel 1 (
+    echo [error] WASM build failed
+    exit /b 1
+  )
+  copy /Y "%NATIVE_DIR%\target\wasm32-wasip1\release\sample_wasm_platform_note.wasm" "%WASM_OUT%" >nul
+  if errorlevel 1 (
+    echo [error] could not copy built WASM to %WASM_OUT%
+    exit /b 1
+  )
+)
+
+if exist "%ZIP_OUT%" del /f /q "%ZIP_OUT%"
+
+pushd "%PLUGIN_DIR%"
+powershell -NoProfile -ExecutionPolicy Bypass -Command "$zip = '%ZIP_OUT%'; $items = @(); foreach ($file in @('config.json', '%PLUGIN_NAME%.html', '%PLUGIN_NAME%.css', '%PLUGIN_NAME%.js', '%PLUGIN_NAME%.wasm', 'server.js')) { if (Test-Path -LiteralPath $file -PathType Leaf) { $items += $file } }; foreach ($dir in @('src', 'assets')) { if (Test-Path -LiteralPath $dir -PathType Container) { $items += $dir } }; if ($items.Count -eq 0) { throw 'No plugin files found to package' }; Compress-Archive -Path $items -DestinationPath $zip -Force"
+set "ZIP_STATUS=%ERRORLEVEL%"
+popd
+if not "%ZIP_STATUS%"=="0" exit /b %ZIP_STATUS%
+if errorlevel 1 (
+  echo [error] zip failed
+  exit /b 1
+)
+
+if defined PLUGIN_SIGN_KEY (
+  where bun >nul 2>&1
+  if not errorlevel 1 (
+    echo [sign] Signing plugin with key: %PLUGIN_SIGN_KEY%
+    bun run "%~dp0..\..\Overlord-Server\scripts\plugin-sign.ts" --key "%PLUGIN_SIGN_KEY%" "%ZIP_OUT%"
+  ) else (
+    echo [warn] bun not found, skipping plugin signing
+  )
+)
+
+echo [ok] %ZIP_OUT%
diff --git a/plugins/sample-wasm-platform-note/native/Cargo.lock b/plugins/sample-wasm-platform-note/native/Cargo.lock
new file mode 100644
index 0000000..75539ad
--- /dev/null
+++ b/plugins/sample-wasm-platform-note/native/Cargo.lock
@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "sample_wasm_platform_note"
+version = "0.1.0"
diff --git a/plugins/sample-wasm-platform-note/native/Cargo.toml b/plugins/sample-wasm-platform-note/native/Cargo.toml
new file mode 100644
index 0000000..3c336d2
--- /dev/null
+++ b/plugins/sample-wasm-platform-note/native/Cargo.toml
@@ -0,0 +1,8 @@
+[package]
+name = "sample_wasm_platform_note"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+path = "src/lib.rs"
diff --git a/plugins/sample-wasm-platform-note/native/src/lib.rs b/plugins/sample-wasm-platform-note/native/src/lib.rs
new file mode 100644
index 0000000..b684f15
--- /dev/null
+++ b/plugins/sample-wasm-platform-note/native/src/lib.rs
@@ -0,0 +1,131 @@
+use std::alloc::{alloc, dealloc, Layout};
+use std::ptr;
+use std::slice;
+use std::str;
+
+extern "C" {
+    fn overlord_emit(event: *const u8, event_len: i32, payload: *const u8, payload_len: i32) -> i32;
+    fn overlord_host_info(out: *mut u8, out_len: i32) -> i32;
+    fn overlord_fs_mkdir(bucket: *const u8, bucket_len: i32, path: *const u8, path_len: i32) -> i32;
+    fn overlord_fs_write(
+        bucket: *const u8,
+        bucket_len: i32,
+        path: *const u8,
+        path_len: i32,
+        data: *const u8,
+        data_len: i32,
+    ) -> i32;
+}
+
+#[no_mangle]
+pub extern "C" fn overlord_alloc(size: u32) -> *mut u8 {
+    let size = size.max(1) as usize;
+    let layout = Layout::from_size_align(size, 8).unwrap();
+    unsafe { alloc(layout) }
+}
+
+#[no_mangle]
+pub extern "C" fn overlord_free(ptr: *mut u8, size: u32) {
+    if ptr.is_null() {
+        return;
+    }
+    let layout = Layout::from_size_align((size.max(1)) as usize, 8).unwrap();
+    unsafe { dealloc(ptr, layout) };
+}
+
+#[no_mangle]
+pub extern "C" fn overlord_on_load(_host: *const u8, _host_len: u32) -> i32 {
+    emit("ready", br#"{"sample":"platform-note"}"#);
+    0
+}
+
+#[no_mangle]
+pub extern "C" fn overlord_on_event(
+    event: *const u8,
+    event_len: u32,
+    _payload: *const u8,
+    _payload_len: u32,
+) -> i32 {
+    let event = unsafe { slice::from_raw_parts(event, event_len as usize) };
+    if event != b"write_note" {
+        return 0;
+    }
+
+    let mut host = [0u8; 1024];
+    let host_len = unsafe { overlord_host_info(host.as_mut_ptr(), host.len() as i32) };
+    let host = if host_len > 0 {
+        str::from_utf8(&host[..host_len as usize]).unwrap_or("")
+    } else {
+        ""
+    };
+
+    let os = if host.contains(r#""os":"windows""#) {
+        "windows"
+    } else if host.contains(r#""os":"darwin""#) {
+        "darwin"
+    } else if host.contains(r#""os":"linux""#) {
+        "linux"
+    } else {
+        "unknown"
+    };
+
+    let arch = if host.contains(r#""arch":"arm64""#) {
+        "arm64"
+    } else if host.contains(r#""arch":"amd64""#) {
+        "amd64"
+    } else if host.contains(r#""arch":"386""#) {
+        "386"
+    } else {
+        "unknown"
+    };
+
+    let bucket = "pluginData";
+    let dir = "platform";
+    let file = format!("platform/{os}-{arch}.txt");
+    let note = format!("single WASM plugin running on os={os} arch={arch}\n");
+
+    let mkdir_result = unsafe {
+        overlord_fs_mkdir(
+            bucket.as_ptr(),
+            bucket.len() as i32,
+            dir.as_ptr(),
+            dir.len() as i32,
+        )
+    };
+    let write_result = unsafe {
+        overlord_fs_write(
+            bucket.as_ptr(),
+            bucket.len() as i32,
+            file.as_ptr(),
+            file.len() as i32,
+            note.as_ptr(),
+            note.len() as i32,
+        )
+    };
+
+    let response = format!(
+        r#"{{"os":"{os}","arch":"{arch}","mkdir":{mkdir_result},"write":{write_result}}}"#
+    );
+    emit("platform_note", response.as_bytes());
+    0
+}
+
+#[no_mangle]
+pub extern "C" fn overlord_on_unload() {}
+
+fn emit(event: &str, payload: &[u8]) {
+    unsafe {
+        overlord_emit(
+            event.as_ptr(),
+            event.len() as i32,
+            payload.as_ptr(),
+            payload.len() as i32,
+        );
+    }
+}
+
+#[no_mangle]
+pub extern "C" fn memset(dest: *mut u8, value: i32, len: usize) -> *mut u8 {
+    unsafe { ptr::write_bytes(dest, value as u8, len) };
+    dest
+}
diff --git a/plugins/sample-wasm-platform-note/native/target/.rustc_info.json b/plugins/sample-wasm-platform-note/native/target/.rustc_info.json
new file mode 100644
index 0000000..b3d198b
--- /dev/null
+++ b/plugins/sample-wasm-platform-note/native/target/.rustc_info.json
@@ -0,0 +1 @@
+{"rustc_fingerprint":2568544898921049753,"outputs":{"7971740275564407648":{"success":true,"status":"","code":0,"stdout":"___.exe\nlib___.rlib\n___.dll\n___.dll\n___.lib\n___.dll\nC:\\Users\\this1\\.rustup\\toolchains\\stable-x86_64-pc-windows-msvc\npacked\n___\ndebug_assertions\npanic=\"unwind\"\nproc_macro\ntarget_abi=\"\"\ntarget_arch=\"x86_64\"\ntarget_endian=\"little\"\ntarget_env=\"msvc\"\ntarget_family=\"windows\"\ntarget_feature=\"cmpxchg16b\"\ntarget_feature=\"fxsr\"\ntarget_feature=\"sse\"\ntarget_feature=\"sse2\"\ntarget_feature=\"sse3\"\ntarget_has_atomic=\"128\"\ntarget_has_atomic=\"16\"\ntarget_has_atomic=\"32\"\ntarget_has_atomic=\"64\"\ntarget_has_atomic=\"8\"\ntarget_has_atomic=\"ptr\"\ntarget_os=\"windows\"\ntarget_pointer_width=\"64\"\ntarget_vendor=\"pc\"\nwindows\n","stderr":""},"5946400966674136012":{"success":true,"status":"","code":0,"stdout":"___.wasm\nlib___.rlib\n___.wasm\nlib___.a\nC:\\Users\\this1\\.rustup\\toolchains\\stable-x86_64-pc-windows-msvc\noff\n___\ndebug_assertions\npanic=\"abort\"\nproc_macro\ntarget_abi=\"\"\ntarget_arch=\"wasm32\"\ntarget_endian=\"little\"\ntarget_env=\"p1\"\ntarget_family=\"wasm\"\ntarget_feature=\"bulk-memory\"\ntarget_feature=\"multivalue\"\ntarget_feature=\"mutable-globals\"\ntarget_feature=\"nontrapping-fptoint\"\ntarget_feature=\"reference-types\"\ntarget_feature=\"sign-ext\"\ntarget_has_atomic=\"16\"\ntarget_has_atomic=\"32\"\ntarget_has_atomic=\"64\"\ntarget_has_atomic=\"8\"\ntarget_has_atomic=\"ptr\"\ntarget_os=\"wasi\"\ntarget_pointer_width=\"32\"\ntarget_vendor=\"unknown\"\n","stderr":"warning: dropping unsupported crate type `dylib` for target `wasm32-wasip1`\n\nwarning: dropping unsupported crate type `proc-macro` for target `wasm32-wasip1`\n\nwarning: 2 warnings emitted\n\n"},"17747080675513052775":{"success":true,"status":"","code":0,"stdout":"rustc 1.94.0 (4a4ef493e 2026-03-02)\nbinary: rustc\ncommit-hash: 4a4ef493e3a1488c6e321570238084b38948f6db\ncommit-date: 2026-03-02\nhost: x86_64-pc-windows-msvc\nrelease: 1.94.0\nLLVM version: 21.1.8\n","stderr":""}},"successes":{}}
\ No newline at end of file
diff --git a/plugins/sample-wasm-platform-note/native/target/CACHEDIR.TAG b/plugins/sample-wasm-platform-note/native/target/CACHEDIR.TAG
new file mode 100644
index 0000000..20d7c31
--- /dev/null
+++ b/plugins/sample-wasm-platform-note/native/target/CACHEDIR.TAG
@@ -0,0 +1,3 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by cargo.
+# For information about cache directory tags see https://bford.info/cachedir/
diff --git a/plugins/sample-wasm-platform-note/native/target/wasm32-wasip1/CACHEDIR.TAG b/plugins/sample-wasm-platform-note/native/target/wasm32-wasip1/CACHEDIR.TAG
new file mode 100644
index 0000000..20d7c31
--- /dev/null
+++ b/plugins/sample-wasm-platform-note/native/target/wasm32-wasip1/CACHEDIR.TAG
@@ -0,0 +1,3 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by cargo.
+# For information about cache directory tags see https://bford.info/cachedir/
diff --git a/plugins/sample-wasm-platform-note/sample-wasm-platform-note.css b/plugins/sample-wasm-platform-note/sample-wasm-platform-note.css
new file mode 100644
index 0000000..f2c9af3
--- /dev/null
+++ b/plugins/sample-wasm-platform-note/sample-wasm-platform-note.css
@@ -0,0 +1,22 @@
+#sample-wasm-platform-note-output {
+  min-height: 8rem;
+}
+
+.sample-wasm-platform-note-field {
+  border: 1px solid rgba(5, 150, 105, 0.45);
+  background: rgba(6, 78, 59, 0.25);
+  padding: 0.75rem;
+}
+
+.sample-wasm-platform-note-field span {
+  display: block;
+  color: rgb(148, 163, 184);
+  font-size: 0.75rem;
+}
+
+.sample-wasm-platform-note-field strong {
+  display: block;
+  color: rgb(209, 250, 229);
+  font-size: 0.95rem;
+  overflow-wrap: anywhere;
+}
diff --git a/plugins/sample-wasm-platform-note/sample-wasm-platform-note.html b/plugins/sample-wasm-platform-note/sample-wasm-platform-note.html
new file mode 100644
index 0000000..b07572a
--- /dev/null
+++ b/plugins/sample-wasm-platform-note/sample-wasm-platform-note.html
@@ -0,0 +1,12 @@
+

+  
Sample WASM Platform Note

+  
+  
Waiting to write platform note

+  

+    
OS-

+    
Arch-

+    
mkdir-

+    
write-

+  

+  

+

diff --git a/plugins/sample-wasm-platform-note/sample-wasm-platform-note.js b/plugins/sample-wasm-platform-note/sample-wasm-platform-note.js
new file mode 100644
index 0000000..7d9289b
--- /dev/null
+++ b/plugins/sample-wasm-platform-note/sample-wasm-platform-note.js
@@ -0,0 +1,93 @@
+(() => {
+  const out = document.getElementById("sample-wasm-platform-note-output");
+  const btn = document.getElementById("sample-wasm-platform-note-run");
+  const status = document.getElementById("sample-wasm-platform-note-status");
+  const fields = {
+    os: document.getElementById("sample-wasm-platform-note-os"),
+    arch: document.getElementById("sample-wasm-platform-note-arch"),
+    mkdir: document.getElementById("sample-wasm-platform-note-mkdir"),
+    write: document.getElementById("sample-wasm-platform-note-write"),
+  };
+  const clientId = new URLSearchParams(window.location.search).get("clientId");
+  const pluginId = "sample-wasm-platform-note";
+  let polling = false;
+
+  function log(message) {
+    if (out) out.textContent = `${message}\n${out.textContent || ""}`;
+  }
+
+  function setStatus(message) {
+    if (status) status.textContent = message;
+  }
+
+  function parsePayload(payload) {
+    if (payload == null) return {};
+    if (typeof payload === "string") {
+      try { return JSON.parse(payload); } catch (_) { return { raw: payload }; }
+    }
+    return payload;
+  }
+
+  function renderPlatformNote(payload) {
+    const info = parsePayload(payload);
+    if (fields.os) fields.os.textContent = info.os || "-";
+    if (fields.arch) fields.arch.textContent = info.arch || "-";
+    if (fields.mkdir) fields.mkdir.textContent = String(info.mkdir ?? "-");
+    if (fields.write) fields.write.textContent = String(info.write ?? "-");
+    setStatus(info.write === 0 ? "Platform note written" : "Platform note result received");
+    log(JSON.stringify(info, null, 2));
+  }
+
+  function handlePluginEvent(event, payload) {
+    if (event === "ready") {
+      setStatus("Plugin loaded");
+      log(JSON.stringify(parsePayload(payload), null, 2));
+      return;
+    }
+    if (event === "platform_note") renderPlatformNote(payload);
+  }
+
+  window.addEventListener("message", (e) => {
+    if (!e.data || e.data.type !== "plugin_event") return;
+    if (e.data.pluginId && e.data.pluginId !== pluginId) return;
+    handlePluginEvent(e.data.event, e.data.payload);
+  });
+
+  async function pollEvents() {
+    if (!clientId || polling) return;
+    polling = true;
+    try {
+      const res = await fetch(`/api/clients/${encodeURIComponent(clientId)}/plugins/${pluginId}/events`, {
+        headers: { Accept: "application/json" },
+      });
+      if (res.ok) {
+        const data = await res.json();
+        if (data.events) data.events.forEach((e) => handlePluginEvent(e.event, e.payload));
+      }
+    } catch (_) {
+      // Polling is best-effort; the next interval can recover.
+    } finally {
+      polling = false;
+    }
+  }
+
+  btn?.addEventListener("click", async () => {
+    if (!clientId) {
+      setStatus("Open this plugin from a client row so clientId is present.");
+      return;
+    }
+    setStatus("Writing platform note");
+    const res = await fetch(`/api/clients/${encodeURIComponent(clientId)}/plugins/sample-wasm-platform-note/event`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ event: "write_note", payload: {} }),
+    });
+    if (!res.ok) setStatus(`Send failed: ${res.status}`);
+    setTimeout(pollEvents, 250);
+  });
+
+  if (clientId) {
+    setInterval(pollEvents, 1500);
+    setTimeout(pollEvents, 300);
+  }
+})();
diff --git a/plugins/sample-wasm/README.md b/plugins/sample-wasm/README.md
new file mode 100644
index 0000000..4457d75
--- /dev/null
+++ b/plugins/sample-wasm/README.md
@@ -0,0 +1,9 @@
+# Sample WASM Plugin
+
+This is a Plugin 2.0 sample. It declares broad file needs in `config.json`, then uses the agent WASM host imports to write to `pluginData` and list `downloads`.
+
+On Windows, run this sample's local `build.bat`. The builder uses a WASI-capable `clang` to compile `native/sample_wasm.c`, writes `sample-wasm.wasm`, and creates `sample-wasm.zip`.
+
+You can also build `native/sample_wasm.c` manually with a WASI-capable clang, copy the resulting `sample-wasm.wasm` into this folder, then zip the folder contents.
+
+The server will show the declared needs before the module can be sent to an agent.
diff --git a/plugins/sample-wasm/build.bat b/plugins/sample-wasm/build.bat
new file mode 100644
index 0000000..076c095
--- /dev/null
+++ b/plugins/sample-wasm/build.bat
@@ -0,0 +1,60 @@
+@echo off
+setlocal enabledelayedexpansion
+
+set "PLUGIN_DIR=%~dp0"
+set "PLUGIN_NAME=sample-wasm"
+
+set "NATIVE_DIR=%PLUGIN_DIR%\native"
+set "WASM_OUT=%PLUGIN_DIR%\%PLUGIN_NAME%.wasm"
+set "ZIP_OUT=%PLUGIN_DIR%\%PLUGIN_NAME%.zip"
+
+if not exist "%PLUGIN_DIR%\config.json" (
+  echo [error] config.json not found in %PLUGIN_DIR%
+  exit /b 1
+)
+
+set "WASM_SOURCE="
+if exist "%NATIVE_DIR%" (
+  for %%S in ("%NATIVE_DIR%\*.c") do (
+    if not defined WASM_SOURCE set "WASM_SOURCE=%%~fS"
+  )
+)
+
+if defined WASM_SOURCE (
+  where clang >nul 2>&1
+  if errorlevel 1 (
+    echo [error] clang was not found. Install a WASI-capable clang or provide %WASM_OUT% yourself.
+    exit /b 1
+  )
+
+  echo [build] clang --target=wasm32-wasi -O2 "!WASM_SOURCE!" ^> "%WASM_OUT%"
+  clang --target=wasm32-wasi -O2 -Wl,--no-entry -Wl,--allow-undefined -Wl,--export=overlord_alloc -Wl,--export=overlord_free -Wl,--export=overlord_on_load -Wl,--export=overlord_on_event -Wl,--export=overlord_on_unload -o "%WASM_OUT%" "!WASM_SOURCE!"
+  if errorlevel 1 (
+    echo [error] WASM build failed
+    exit /b 1
+  )
+)
+
+if exist "%ZIP_OUT%" del /f /q "%ZIP_OUT%"
+
+pushd "%PLUGIN_DIR%"
+powershell -NoProfile -ExecutionPolicy Bypass -Command "$zip = '%ZIP_OUT%'; $items = @(); foreach ($file in @('config.json', '%PLUGIN_NAME%.html', '%PLUGIN_NAME%.css', '%PLUGIN_NAME%.js', '%PLUGIN_NAME%.wasm', 'server.js')) { if (Test-Path -LiteralPath $file -PathType Leaf) { $items += $file } }; foreach ($dir in @('src', 'assets')) { if (Test-Path -LiteralPath $dir -PathType Container) { $items += $dir } }; if ($items.Count -eq 0) { throw 'No plugin files found to package' }; Compress-Archive -Path $items -DestinationPath $zip -Force"
+set "ZIP_STATUS=%ERRORLEVEL%"
+popd
+if not "%ZIP_STATUS%"=="0" exit /b %ZIP_STATUS%
+if errorlevel 1 (
+  echo [error] zip failed
+  exit /b 1
+)
+
+if defined PLUGIN_SIGN_KEY (
+  where bun >nul 2>&1
+  if not errorlevel 1 (
+    echo [sign] Signing plugin with key: %PLUGIN_SIGN_KEY%
+    bun run "%~dp0..\..\Overlord-Server\scripts\plugin-sign.ts" --key "%PLUGIN_SIGN_KEY%" "%ZIP_OUT%"
+  ) else (
+    echo [warn] bun not found, skipping plugin signing
+  )
+)
+
+echo [ok] %ZIP_OUT%
diff --git a/plugins/sample-wasm/native/sample_wasm.c b/plugins/sample-wasm/native/sample_wasm.c
new file mode 100644
index 0000000..c372b11
--- /dev/null
+++ b/plugins/sample-wasm/native/sample_wasm.c
@@ -0,0 +1,69 @@
+// Build with a WASI-capable clang:
+// clang --target=wasm32-wasi -O2 -Wl,--no-entry -Wl,--export=overlord_alloc \
+//   -Wl,--export=overlord_free -Wl,--export=overlord_on_load \
+//   -Wl,--export=overlord_on_event -Wl,--export=overlord_on_unload \
+//   -o sample-wasm.wasm sample_wasm.c
+
+#include 
+#include 
+#include 
+#include 
+
+__attribute__((import_module("env"), import_name("overlord_emit")))
+extern int32_t overlord_emit(const char *event, int32_t event_len, const char *payload, int32_t payload_len);
+
+__attribute__((import_module("env"), import_name("overlord_host_info")))
+extern int32_t overlord_host_info(uint8_t *out, int32_t out_len);
+
+__attribute__((import_module("env"), import_name("overlord_fs_mkdir")))
+extern int32_t overlord_fs_mkdir(const char *bucket, int32_t bucket_len, const char *path, int32_t path_len);
+
+__attribute__((import_module("env"), import_name("overlord_fs_write")))
+extern int32_t overlord_fs_write(const char *bucket, int32_t bucket_len, const char *path, int32_t path_len, const uint8_t *data, int32_t data_len);
+
+__attribute__((import_module("env"), import_name("overlord_fs_list")))
+extern int32_t overlord_fs_list(const char *bucket, int32_t bucket_len, const char *path, int32_t path_len, uint8_t *out, int32_t out_len);
+
+void *overlord_alloc(uint32_t size) {
+  return malloc(size ? size : 1);
+}
+
+void overlord_free(void *ptr, uint32_t size) {
+  (void)size;
+  free(ptr);
+}
+
+int32_t overlord_on_load(const char *host_info, int32_t host_info_len) {
+  const char *event = "ready";
+  overlord_emit(event, 5, host_info, host_info_len);
+  return 0;
+}
+
+int32_t overlord_on_event(const char *event, int32_t event_len, const char *payload, int32_t payload_len) {
+  (void)payload;
+  (void)payload_len;
+  if (event_len != 10 || memcmp(event, "run_sample", 10) != 0) return 0;
+
+  const char *plugin_data = "pluginData";
+  const char *downloads = "downloads";
+  const char *dir = "notes";
+  const char *file = "notes/sample.txt";
+  const char *note = "sample wasm plugin wrote this file\n";
+
+  int32_t mkdir_result = overlord_fs_mkdir(plugin_data, 10, dir, 5);
+  int32_t write_result = overlord_fs_write(plugin_data, 10, file, 16, (const uint8_t *)note, (int32_t)strlen(note));
+
+  uint8_t list_buf[4096];
+  int32_t list_result = overlord_fs_list(downloads, 9, "", 0, list_buf, sizeof(list_buf));
+  uint8_t host_buf[1024];
+  int32_t host_result = overlord_host_info(host_buf, sizeof(host_buf));
+
+  char response[256];
+  int n = snprintf(response, sizeof(response),
+    "{\"mkdir\":%d,\"write\":%d,\"downloadsListBytes\":%d,\"hostInfoBytes\":%d}",
+    mkdir_result, write_result, list_result, host_result);
+  overlord_emit("sample_result", 13, response, n);
+  return 0;
+}
+
+void overlord_on_unload(void) {}
diff --git a/plugins/sample-wasm/sample-wasm.css b/plugins/sample-wasm/sample-wasm.css
new file mode 100644
index 0000000..fd00383
--- /dev/null
+++ b/plugins/sample-wasm/sample-wasm.css
@@ -0,0 +1,3 @@
+#sample-wasm-output {
+  min-height: 7rem;
+}
diff --git a/plugins/sample-wasm/sample-wasm.html b/plugins/sample-wasm/sample-wasm.html
new file mode 100644
index 0000000..a3bad1d
--- /dev/null
+++ b/plugins/sample-wasm/sample-wasm.html
@@ -0,0 +1,6 @@
+

+  
Sample WASM

+  
Plugin 2.0 runtime smoke test.

+  
+  

+

diff --git a/plugins/sample-wasm/sample-wasm.js b/plugins/sample-wasm/sample-wasm.js
new file mode 100644
index 0000000..44a1d1c
--- /dev/null
+++ b/plugins/sample-wasm/sample-wasm.js
@@ -0,0 +1,22 @@
+(() => {
+  const out = document.getElementById("sample-wasm-output");
+  const btn = document.getElementById("sample-wasm-run");
+  const clientId = new URLSearchParams(window.location.search).get("clientId");
+
+  function log(message) {
+    if (out) out.textContent = `${new Date().toLocaleTimeString()} ${message}\n${out.textContent || ""}`;
+  }
+
+  btn?.addEventListener("click", async () => {
+    if (!clientId) {
+      log("Open this plugin from a client row so clientId is present.");
+      return;
+    }
+    const res = await fetch(`/api/clients/${encodeURIComponent(clientId)}/plugins/sample-wasm/event`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ event: "run_sample", payload: { note: "hello from UI" } }),
+    });
+    log(res.ok ? "sent run_sample" : `send failed: ${res.status}`);
+  });
+})();