diff --git a/.changeset/lua-http-put.md b/.changeset/lua-http-put.md new file mode 100644 index 000000000..6ca42fb33 --- /dev/null +++ b/.changeset/lua-http-put.md @@ -0,0 +1,9 @@ +--- +"ftw": patch +--- + +Lua drivers can now send `host.http_put(url, body, headers)`. It has the same +safety gates as `host.http_patch`: it needs `capabilities.http.allow_write`, +stays inside `allowed_hosts`, refuses redirects and cannot write during a +fingerprint probe. Some device APIs, such as the sonnenBatterie JSON API v2, +accept settings only through PUT. No existing driver changes behaviour. diff --git a/docs/writing-a-driver.md b/docs/writing-a-driver.md index a91d6e0e2..fda30f5ad 100644 --- a/docs/writing-a-driver.md +++ b/docs/writing-a-driver.md @@ -42,7 +42,7 @@ current host API and the source of truth for it. Today it registers: | Decoding | `decode_string`, `decode_i16`, `decode_i32_be`, `decode_i32_le`, `decode_u32_be`, `decode_u32_le` | | Modbus | `modbus_read`, `write`, `write_registers` (canonical); `modbus_write`, `modbus_write_multi` (legacy aliases) | | MQTT | `mqtt_pub`, `mqtt_sub`, `mqtt_publish`, `mqtt_subscribe`, `mqtt_messages` | -| HTTP | `http_get`, `http_post`, `http_patch`, `http_request`, `http_cookies_clear` | +| HTTP | `http_get`, `http_post`, `http_patch`, `http_put`, `http_request`, `http_cookies_clear` | | WebSocket | `ws_open`, `ws_send`, `ws_messages`, `ws_is_open`, `ws_close` | | Raw TCP | `tcp_open`, `tcp_recv`, `tcp_close`, `tcp_is_open` | | Serial | `serial_read` | @@ -56,9 +56,11 @@ reads `W` and `SoC_nom_fract` when `w` and `soc` are absent; when both are present the lowercase key wins. Both spellings are correct — prefer the canonical one in a new driver. -`http_patch` is the mutating verb and is gated twice: the plain `http` grant is -not enough, it also needs `capabilities.http.allow_write`. It refuses to follow -redirects, because Go re-issues a redirected `PATCH` as a body-less GET and a +`http_patch` and `http_put` are the mutating verbs and are gated twice: the +plain `http` grant is not enough, they also need +`capabilities.http.allow_write`. Both send `Content-Type: application/json` +unless the driver passes its own header. They refuse to follow redirects, +because Go re-issues a redirected `PATCH` or `PUT` as a body-less GET and a device write that never landed would otherwise report success. `http_request{method, url, headers, body}` is for a driver that has to sign in @@ -139,7 +141,7 @@ may omit the default hook because Core cannot dispatch commands to them. `driver_fingerprint(target)` is an optional passive setup probe. It must never reconfigure the device. The host denies mutating verbs (`modbus_write`, -`mqtt_pub`, `http_post`, `http_patch`, and POST through `http_request`) for that VM, including bundled drivers +`mqtt_pub`, `http_post`, `http_patch`, `http_put`, and POST through `http_request`) for that VM, including bundled drivers that may otherwise write. Call `host.set_make` and `host.set_sn` as soon as stable identity is known. diff --git a/go/internal/config/config.go b/go/internal/config/config.go index 0b8e473f0..ece559bef 100644 --- a/go/internal/config/config.go +++ b/go/internal/config/config.go @@ -1070,13 +1070,13 @@ type HTTPCapability struct { // for this driver only; when empty, standard verification against the // system roots applies (unchanged for every existing HTTP driver). TLSPinSHA256 string `yaml:"tls_pin_sha256,omitempty" json:"tls_pin_sha256,omitempty"` - // AllowWrite grants host.http_patch — the verb REST device APIs use for - // state-changing writes — as a separate, explicit operator decision, the - // HTTP twin of a read-only Modbus driver versus one allowed to write - // registers. Scope is exactly http_patch: http_get stays a read and - // http_post stays under the plain HTTP grant (existing drivers POST to - // query-style APIs), so granting HTTP for telemetry never implicitly - // grants the ability to mutate a device. Default off. + // AllowWrite grants host.http_patch and host.http_put — the verbs REST + // device APIs use for state-changing writes — as a separate, explicit + // operator decision, the HTTP twin of a read-only Modbus driver versus + // one allowed to write registers. Scope is exactly those verbs: http_get + // stays a read and http_post stays under the plain HTTP grant (existing + // drivers POST to query-style APIs), so granting HTTP for telemetry never + // implicitly grants the ability to mutate a device. Default off. AllowWrite bool `yaml:"allow_write,omitempty" json:"allow_write,omitempty"` } diff --git a/go/internal/drivers/host.go b/go/internal/drivers/host.go index ee5609a55..a653a960c 100644 --- a/go/internal/drivers/host.go +++ b/go/internal/drivers/host.go @@ -104,10 +104,10 @@ type HostEnv struct { // verification (unchanged default for all existing HTTP drivers). // Populated from driver config `capabilities.http.tls_pin_sha256`. HTTPTLSPinSHA256 string - // HTTPAllowWrite gates host.http_patch, and only http_patch — - // http_get stays a read and http_post stays under the plain HTTP - // capability (existing drivers POST to query-style APIs). http_patch - // returns an error string unless this is set, so granting HTTP for + // HTTPAllowWrite gates host.http_patch and host.http_put, and only + // those — http_get stays a read and http_post stays under the plain + // HTTP capability (existing drivers POST to query-style APIs). Both + // return an error string unless this is set, so granting HTTP for // telemetry never implicitly grants device mutation. Populated from // driver config `capabilities.http.allow_write`. HTTPAllowWrite bool @@ -449,8 +449,8 @@ func (h *HostEnv) WithSerial(s SerialCap) *HostEnv { h.Serial = s; return h } // WithHTTP enables the HTTP capability. func (h *HostEnv) WithHTTP() *HostEnv { h.HTTP = true; return h } -// WithHTTPAllowWrite grants the mutating HTTP verb host.http_patch. Scoped -// to http_patch only; http_get/http_post are unaffected. See +// WithHTTPAllowWrite grants the mutating HTTP verbs host.http_patch and +// host.http_put; http_get/http_post are unaffected. See // HostEnv.HTTPAllowWrite. func (h *HostEnv) WithHTTPAllowWrite() *HostEnv { h.HTTPAllowWrite = true; return h } diff --git a/go/internal/drivers/lua.go b/go/internal/drivers/lua.go index c629d8ad0..d460e40c9 100644 --- a/go/internal/drivers/lua.go +++ b/go/internal/drivers/lua.go @@ -22,7 +22,7 @@ // host.mqtt_sub / mqtt_subscribe, host.mqtt_pub / mqtt_publish, host.mqtt_messages // host.modbus_read, host.modbus_write / write, host.modbus_write_multi / write_registers // host.serial_read, host.aes_gcm_decrypt, host.json_decode, host.json_encode -// host.http_get, host.http_post, host.http_patch +// host.http_get, host.http_post, host.http_patch, host.http_put // host.ws_open, host.ws_send, host.ws_messages, host.ws_is_open, host.ws_close // host.tcp_open, host.tcp_recv, host.tcp_is_open, host.tcp_close // @@ -1216,12 +1216,12 @@ func registerHost(L *lua.LState, env *HostEnv) { if len(via) >= 10 { return fmt.Errorf("stopped after 10 redirects") } - // A redirected PATCH is unsafe: Go re-issues 301/302/303 as a - // body-less GET, so the device write silently never lands while the - // call still reports success. Refuse it — a write must reach the - // host it was checked against, or fail loudly. - if len(via) > 0 && via[0].Method == "PATCH" { - return fmt.Errorf("redirect not followed for PATCH (a redirected write cannot be verified)") + // A redirected PATCH or PUT is unsafe: Go re-issues 301/302/303 as + // a body-less GET, so the device write silently never lands while + // the call still reports success. Refuse it — a write must reach + // the host it was checked against, or fail loudly. + if len(via) > 0 && (via[0].Method == "PATCH" || via[0].Method == "PUT") { + return fmt.Errorf("redirect not followed for %s (a redirected write cannot be verified)", via[0].Method) } // The managed read-only OAuth exception authorizes one exact path. // A 307/308 must not carry its POST body to a device write endpoint. @@ -1402,60 +1402,70 @@ func registerHost(L *lua.LState, env *HostEnv) { // grant, so granting HTTP for telemetry never implicitly grants the ability // to mutate a device. Same allowlist, TLS pinning and 1MB response cap as // the other verbs. - host.RawSetString("http_patch", L.NewFunction(func(L *lua.LState) int { - if !env.HTTP { - L.Push(lua.LNil) - L.Push(lua.LString("http: capability not granted")) - return 2 - } - if !env.HTTPAllowWrite { - L.Push(lua.LNil) - L.Push(lua.LString("http: write not granted (set capabilities.http.allow_write)")) - return 2 - } - if err := env.allowWrite("http.patch"); err != nil { - L.Push(lua.LNil) - L.Push(lua.LString(err.Error())) - return 2 - } - url := L.CheckString(1) - if ok, reason := hostAllowed(url); !ok { - L.Push(lua.LNil) - L.Push(lua.LString("http: " + reason)) - return 2 - } - payload := L.CheckString(2) - // Keep the same ordering rule as POST: the registry actor must not send - // a default while this older mutating request can still finish normally. - req, err := net_http.NewRequest("PATCH", url, strings.NewReader(payload)) - if err != nil { - L.Push(lua.LNil) - L.Push(lua.LString(err.Error())) - return 2 - } - req.Header.Set("Content-Type", "application/json") - applyHeaders(req, L, 3) - resp, err := httpClient.Do(req) - if err != nil { - L.Push(lua.LNil) - L.Push(lua.LString(err.Error())) - return 2 - } - defer resp.Body.Close() - body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20)) - if err != nil { - L.Push(lua.LNil) - L.Push(lua.LString(err.Error())) - return 2 - } - if resp.StatusCode >= 400 { - L.Push(lua.LNil) - L.Push(lua.LString(fmt.Sprintf("HTTP %d: %s", resp.StatusCode, string(body)))) - return 2 + // + // host.http_put(url, body, headers?) is the same write under PUT, for + // device APIs that replace a resource instead of patching it (the + // sonnenBatterie JSON API v2 /configurations endpoint). It shares the + // allow_write gate and every other rule with http_patch. + httpWrite := func(method string) lua.LGFunction { + permission := "http." + strings.ToLower(method) + return func(L *lua.LState) int { + if !env.HTTP { + L.Push(lua.LNil) + L.Push(lua.LString("http: capability not granted")) + return 2 + } + if !env.HTTPAllowWrite { + L.Push(lua.LNil) + L.Push(lua.LString("http: write not granted (set capabilities.http.allow_write)")) + return 2 + } + if err := env.allowWrite(permission); err != nil { + L.Push(lua.LNil) + L.Push(lua.LString(err.Error())) + return 2 + } + url := L.CheckString(1) + if ok, reason := hostAllowed(url); !ok { + L.Push(lua.LNil) + L.Push(lua.LString("http: " + reason)) + return 2 + } + payload := L.CheckString(2) + // Keep the same ordering rule as POST: the registry actor must not send + // a default while this older mutating request can still finish normally. + req, err := net_http.NewRequest(method, url, strings.NewReader(payload)) + if err != nil { + L.Push(lua.LNil) + L.Push(lua.LString(err.Error())) + return 2 + } + req.Header.Set("Content-Type", "application/json") + applyHeaders(req, L, 3) + resp, err := httpClient.Do(req) + if err != nil { + L.Push(lua.LNil) + L.Push(lua.LString(err.Error())) + return 2 + } + defer resp.Body.Close() + body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20)) + if err != nil { + L.Push(lua.LNil) + L.Push(lua.LString(err.Error())) + return 2 + } + if resp.StatusCode >= 400 { + L.Push(lua.LNil) + L.Push(lua.LString(fmt.Sprintf("HTTP %d: %s", resp.StatusCode, string(body)))) + return 2 + } + L.Push(lua.LString(string(body))) + return 1 } - L.Push(lua.LString(string(body))) - return 1 - })) + } + host.RawSetString("http_patch", L.NewFunction(httpWrite("PATCH"))) + host.RawSetString("http_put", L.NewFunction(httpWrite("PUT"))) registerHTTPRequest(L, host, env, httpClient, hostAllowed) diff --git a/go/internal/drivers/lua_http_patch_test.go b/go/internal/drivers/lua_http_patch_test.go index ed592bd97..180a87c76 100644 --- a/go/internal/drivers/lua_http_patch_test.go +++ b/go/internal/drivers/lua_http_patch_test.go @@ -25,11 +25,18 @@ import ( // runHTTPDriverWithEnv. The specific denial gate is surfaced as a metric so // tests can assert WHICH gate fired, not just that something failed. func runPatchDriver(t *testing.T, env *HostEnv, targetURL string) (ok bool, deniedBy string) { + t.Helper() + return runHTTPWriteDriver(t, env, "http_patch", targetURL) +} + +// runHTTPWriteDriver runs the same one-shot driver through any mutating +// verb (host.http_patch or host.http_put). +func runHTTPWriteDriver(t *testing.T, env *HostEnv, fn, targetURL string) (ok bool, deniedBy string) { t.Helper() src := ` function driver_init() end function driver_poll() - local body, err = host.http_patch("` + targetURL + `", + local body, err = host.` + fn + `("` + targetURL + `", '[{"variableId":5202,"integerValue":3000}]', { Authorization = "Basic dTpw" }) if err then diff --git a/go/internal/drivers/lua_http_put_test.go b/go/internal/drivers/lua_http_put_test.go new file mode 100644 index 000000000..18f9c2286 --- /dev/null +++ b/go/internal/drivers/lua_http_put_test.go @@ -0,0 +1,212 @@ +package drivers + +import ( + "context" + "io" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "sync/atomic" + "testing" + + "github.com/srcfl/ftw/go/internal/telemetry" +) + +// host.http_put shares http_patch's gates. These tests pin the verb on the +// wire and that the write grant, not the plain HTTP grant, lets it out. The +// sonnenBatterie JSON API v2 is the first user: it changes its operating mode +// only through PUT /api/v2/configurations and answers PATCH and POST there +// with 404. + +func TestLuaHTTPPutSendsMethodBodyAndHeaders(t *testing.T) { + var gotMethod, gotBody, gotCT, gotAuth string + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + gotMethod = r.Method + b, _ := io.ReadAll(r.Body) + gotBody = string(b) + gotCT = r.Header.Get("Content-Type") + gotAuth = r.Header.Get("Authorization") + _, _ = w.Write([]byte(`{"EM_OperatingMode":"2"}`)) + })) + defer srv.Close() + + env := NewHostEnv("putter", telemetry.NewStore()).WithHTTP().WithHTTPAllowWrite() + ok, errText := runHTTPWriteDriver(t, env, "http_put", srv.URL+"/api/v2/configurations") + if !ok { + t.Fatalf("put failed: %s", errText) + } + if gotMethod != "PUT" { + t.Errorf("method = %q, want PUT", gotMethod) + } + if gotBody != `[{"variableId":5202,"integerValue":3000}]` { + t.Errorf("body = %q", gotBody) + } + if gotCT != "application/json" { + t.Errorf("content-type = %q", gotCT) + } + if gotAuth != "Basic dTpw" { + t.Errorf("authorization header not forwarded, got %q", gotAuth) + } +} + +// A driver may send a form body by naming its own Content-Type; the host's +// JSON default must not override it. +func TestLuaHTTPPutDriverContentTypeWins(t *testing.T) { + var gotMethod, gotBody, gotCT, gotToken string + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + gotMethod = r.Method + b, _ := io.ReadAll(r.Body) + gotBody = string(b) + gotCT = r.Header.Get("Content-Type") + gotToken = r.Header.Get("Auth-Token") + _, _ = w.Write([]byte(`{"EM_OperatingMode":"2"}`)) + })) + defer srv.Close() + + src := ` + function driver_init() end + function driver_poll() + local body, err = host.http_put("` + srv.URL + `/api/v2/configurations", + "EM_OperatingMode=2", + { ["Content-Type"] = "application/x-www-form-urlencoded", + ["Auth-Token"] = "tok" }) + if err then + host.log("info", "ERR:" .. tostring(err)) + else + host.emit_metric("put_ok", 1) + end + return 60000 + end + function driver_command() end + function driver_default_mode() end + ` + path := filepath.Join(t.TempDir(), "form.lua") + if err := os.WriteFile(path, []byte(src), 0644); err != nil { + t.Fatal(err) + } + env := NewHostEnv("form", telemetry.NewStore()).WithHTTP().WithHTTPAllowWrite() + d, err := NewLuaDriver(path, env) + if err != nil { + t.Fatalf("load driver: %v", err) + } + defer d.Cleanup() + if err := d.Init(context.Background(), nil); err != nil { + t.Fatalf("init: %v", err) + } + if _, err := d.Poll(context.Background()); err != nil { + t.Fatalf("poll: %v", err) + } + if v, _, found := env.Telemetry.LatestMetric("form", "put_ok"); !found || v != 1 { + t.Fatal("form PUT did not succeed") + } + if gotMethod != "PUT" || gotBody != "EM_OperatingMode=2" { + t.Errorf("got %s %q", gotMethod, gotBody) + } + if gotCT != "application/x-www-form-urlencoded" { + t.Errorf("content-type = %q, want the driver's form type", gotCT) + } + if gotToken != "tok" { + t.Errorf("Auth-Token = %q", gotToken) + } +} + +func TestLuaHTTPPutRequiresAllowWrite(t *testing.T) { + var hits atomic.Int64 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + hits.Add(1) + _, _ = w.Write([]byte(`ok`)) + })) + defer srv.Close() + + env := NewHostEnv("readonly", telemetry.NewStore()).WithHTTP() + ok, deniedBy := runHTTPWriteDriver(t, env, "http_put", srv.URL) + if ok { + t.Fatal("http_put succeeded without capabilities.http.allow_write") + } + if deniedBy != "denied_write_cap" { + t.Errorf("denied by %q, want the allow_write gate", deniedBy) + } + if hits.Load() != 0 { + t.Fatalf("server was reached %d times despite missing allow_write", hits.Load()) + } +} + +func TestLuaHTTPPutWithoutHTTPCapability(t *testing.T) { + var hits atomic.Int64 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + hits.Add(1) + })) + defer srv.Close() + + env := NewHostEnv("nohttp", telemetry.NewStore()).WithHTTPAllowWrite() + ok, deniedBy := runHTTPWriteDriver(t, env, "http_put", srv.URL) + if ok { + t.Fatal("http_put succeeded without the http capability") + } + if deniedBy != "denied_http_cap" { + t.Errorf("denied by %q, want the http capability gate", deniedBy) + } + if hits.Load() != 0 { + t.Fatalf("server was reached %d times", hits.Load()) + } +} + +func TestLuaHTTPPutRefusesRedirects(t *testing.T) { + var followUps atomic.Int64 + target := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + followUps.Add(1) + _, _ = w.Write([]byte(`ok`)) + })) + defer target.Close() + redirector := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + http.Redirect(w, r, target.URL, http.StatusFound) + })) + defer redirector.Close() + + env := NewHostEnv("redirected", telemetry.NewStore()).WithHTTP().WithHTTPAllowWrite() + ok, deniedBy := runHTTPWriteDriver(t, env, "http_put", redirector.URL) + if ok { + t.Fatal("a redirected PUT must not report success") + } + if deniedBy != "denied_redirect" { + t.Errorf("denied by %q, want the redirect refusal", deniedBy) + } + if followUps.Load() != 0 { + t.Fatalf("redirect target was reached %d times", followUps.Load()) + } +} + +func TestLuaHTTPPutRespectsAllowlist(t *testing.T) { + var hits atomic.Int64 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + hits.Add(1) + })) + defer srv.Close() + + env := NewHostEnv("fenced", telemetry.NewStore()).WithHTTP().WithHTTPAllowWrite(). + WithHTTPAllowedHosts([]string{"10.99.99.99"}) + if ok, _ := runHTTPWriteDriver(t, env, "http_put", srv.URL); ok { + t.Fatal("http_put escaped the allowed_hosts fence") + } + if hits.Load() != 0 { + t.Fatalf("server was reached %d times despite the allowlist", hits.Load()) + } +} + +func TestLuaHTTPPutBlockedInFingerprintProbe(t *testing.T) { + var hits atomic.Int64 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + hits.Add(1) + })) + defer srv.Close() + + env := NewHostEnv("probe", telemetry.NewStore()).WithHTTP().WithHTTPAllowWrite() + env.ProbeReadOnly = true + if ok, _ := runHTTPWriteDriver(t, env, "http_put", srv.URL); ok { + t.Fatal("http_put succeeded in a read-only probe") + } + if hits.Load() != 0 { + t.Fatalf("server was reached %d times from a read-only probe", hits.Load()) + } +}