Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix(http): reject unknown JSON request fields (PIN-306)

Luigi Agosti99b327c0a446
diff --git a/docs/endpoints.md b/docs/endpoints.md
index 69d5a618..b2e440ec 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -883,7 +883,9 @@ POST /instances/{id}/tab
Notes:
-- `/instances/start` and `/instances/launch` use `mode`, not `headless`
+- `/instances/start` and `/instances/launch` use `profileId` for either an existing
+ profile ID or name, and `mode`, not `headless`. Request bodies reject unrecognised
+ fields with a 400 that names the offending key and the accepted shape.
- `/instances/launch` is a sibling endpoint of `/instances/start` (separate handler `handleLaunchByName`), kept for the launch-by-profile workflow; `name` on the body is no longer supported, profiles must already exist
- instance responses include both `mode` and `headless`
- instance start surfaces accept `securityPolicy.allowedDomains` for additive instance-scoped IDPI/domain allowlist overrides
diff --git a/internal/handlers/record_handlers.go b/internal/handlers/record_handlers.go
index e6bdd018..19661b5e 100644
--- a/internal/handlers/record_handlers.go
+++ b/internal/handlers/record_handlers.go
@@ -1,7 +1,9 @@
package handlers
import (
+ "errors"
"fmt"
+ "io"
"log/slog"
"net/http"
"os"
@@ -112,7 +114,10 @@ func (h *Handlers) HandleRecordStop(w http.ResponseWriter, r *http.Request) {
var req struct {
Discard bool `json:"discard"`
}
- _ = httpx.DecodeJSONBody(w, r, 0, &req)
+ if err := httpx.DecodeJSONBody(w, r, 0, &req); err != nil && !errors.Is(err, io.EOF) {
+ httpx.Error(w, httpx.StatusForJSONDecodeError(err), err)
+ return
+ }
var outputPath string
if !req.Discard {
diff --git a/internal/httpx/httpx.go b/internal/httpx/httpx.go
index dec6d717..ce609adc 100644
--- a/internal/httpx/httpx.go
+++ b/internal/httpx/httpx.go
@@ -9,6 +9,9 @@ import (
"log/slog"
"net"
"net/http"
+ "reflect"
+ "sort"
+ "strings"
"time"
"github.com/pinchtab/pinchtab/internal/sanitize"
@@ -163,7 +166,60 @@ func DecodeJSONBody(w http.ResponseWriter, r *http.Request, maxBytes int64, dst
if maxBytes <= 0 {
maxBytes = DefaultMaxJSONBodyBytes
}
- return json.NewDecoder(http.MaxBytesReader(w, r.Body, maxBytes)).Decode(dst)
+ decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, maxBytes))
+ decoder.DisallowUnknownFields()
+ if err := decoder.Decode(dst); err != nil {
+ return clarifyUnknownJSONField(err, dst)
+ }
+ return nil
+}
+
+func clarifyUnknownJSONField(err error, dst any) error {
+ if !strings.HasPrefix(err.Error(), "json: unknown field ") {
+ return err
+ }
+ fields := jsonFieldNames(reflect.TypeOf(dst))
+ if len(fields) == 0 {
+ return err
+ }
+ return fmt.Errorf("%w; expected one of: %s", err, strings.Join(fields, ", "))
+}
+
+func jsonFieldNames(typ reflect.Type) []string {
+ for typ != nil && typ.Kind() == reflect.Pointer {
+ typ = typ.Elem()
+ }
+ if typ == nil || typ.Kind() != reflect.Struct {
+ return nil
+ }
+
+ seen := make(map[string]struct{})
+ for i := 0; i < typ.NumField(); i++ {
+ field := typ.Field(i)
+ if field.Anonymous && field.Tag.Get("json") == "" {
+ for _, name := range jsonFieldNames(field.Type) {
+ seen[name] = struct{}{}
+ }
+ continue
+ }
+ name := strings.Split(field.Tag.Get("json"), ",")[0]
+ if name == "-" {
+ continue
+ }
+ if name == "" {
+ name = field.Name
+ }
+ if field.IsExported() {
+ seen[name] = struct{}{}
+ }
+ }
+
+ fields := make([]string, 0, len(seen))
+ for name := range seen {
+ fields = append(fields, name)
+ }
+ sort.Strings(fields)
+ return fields
}
func StatusForJSONDecodeError(err error) int {
diff --git a/internal/httpx/httpx_test.go b/internal/httpx/httpx_test.go
index a11a06ff..9f04a039 100644
--- a/internal/httpx/httpx_test.go
+++ b/internal/httpx/httpx_test.go
@@ -91,6 +91,23 @@ func TestStatusForJSONDecodeError(t *testing.T) {
}
}
+func TestDecodeJSONBodyRejectsUnknownFieldsAndNamesTheExpectedShape(t *testing.T) {
+ var dst struct {
+ ProfileID string `json:"profileId"`
+ Mode string `json:"mode"`
+ }
+ req := httptest.NewRequest(http.MethodPost, "/instances/start", strings.NewReader(`{"profile":"work"}`))
+ err := DecodeJSONBody(httptest.NewRecorder(), req, 0, &dst)
+ if err == nil {
+ t.Fatal("DecodeJSONBody accepted an unknown request field")
+ }
+ for _, want := range []string{`unknown field "profile"`, "expected one of: mode, profileId"} {
+ if !strings.Contains(err.Error(), want) {
+ t.Fatalf("error %q does not contain %q", err, want)
+ }
+ }
+}
+
func TestProblem(t *testing.T) {
w := httptest.NewRecorder()
Problem(w, http.StatusBadGateway, "backend_unavailable", "backend \x1b[31m unavailable", true, map[string]any{"service": "bridge"})
diff --git a/internal/orchestrator/handlers_instances.go b/internal/orchestrator/handlers_instances.go
index c857a2c4..9f2aad94 100644
--- a/internal/orchestrator/handlers_instances.go
+++ b/internal/orchestrator/handlers_instances.go
@@ -53,7 +53,7 @@ func (o *Orchestrator) handleLaunchByName(w http.ResponseWriter, r *http.Request
if r.ContentLength > 0 {
if err := httpx.DecodeJSONBody(w, r, 0, &req); err != nil {
- httpx.Error(w, httpx.StatusForJSONDecodeError(err), fmt.Errorf("invalid JSON"))
+ httpx.Error(w, httpx.StatusForJSONDecodeError(err), err)
return
}
}
@@ -230,7 +230,7 @@ func (o *Orchestrator) handleStartInstance(w http.ResponseWriter, r *http.Reques
if r.ContentLength > 0 {
if err := httpx.DecodeJSONBody(w, r, 0, &req); err != nil {
- httpx.Error(w, httpx.StatusForJSONDecodeError(err), fmt.Errorf("invalid JSON"))
+ httpx.Error(w, httpx.StatusForJSONDecodeError(err), err)
return
}
}
@@ -369,7 +369,7 @@ func (o *Orchestrator) handleAttachInstance(w http.ResponseWriter, r *http.Reque
}
if err := httpx.DecodeJSONBody(w, r, 0, &req); err != nil {
- httpx.Error(w, httpx.StatusForJSONDecodeError(err), fmt.Errorf("invalid JSON"))
+ httpx.Error(w, httpx.StatusForJSONDecodeError(err), err)
return
}
@@ -425,7 +425,7 @@ func (o *Orchestrator) handleAttachBridge(w http.ResponseWriter, r *http.Request
}
if err := httpx.DecodeJSONBody(w, r, 0, &req); err != nil {
- httpx.Error(w, httpx.StatusForJSONDecodeError(err), fmt.Errorf("invalid JSON"))
+ httpx.Error(w, httpx.StatusForJSONDecodeError(err), err)
return
}
if req.BaseURL == "" {
diff --git a/internal/orchestrator/handlers_instances_test.go b/internal/orchestrator/handlers_instances_test.go
index 84e659c5..7efb0388 100644
--- a/internal/orchestrator/handlers_instances_test.go
+++ b/internal/orchestrator/handlers_instances_test.go
@@ -31,6 +31,37 @@ func TestHandleLaunchByNameRejectsNameField(t *testing.T) {
}
}
+func TestInstanceStartEndpointsRejectUnknownProfileKeysWithoutLaunching(t *testing.T) {
+ for _, path := range []string{"/instances/start", "/instances/launch"} {
+ for _, key := range []string{"profile", "profileName"} {
+ t.Run(path+"/"+key, func(t *testing.T) {
+ runner := &mockRunner{portAvail: true}
+ o := NewOrchestratorWithRunner(t.TempDir(), runner)
+ req := httptest.NewRequest(http.MethodPost, path, strings.NewReader(fmt.Sprintf(`{"%s":"work"}`, key)))
+ w := httptest.NewRecorder()
+
+ if path == "/instances/start" {
+ o.handleStartInstance(w, req)
+ } else {
+ o.handleLaunchByName(w, req)
+ }
+
+ if w.Code != http.StatusBadRequest {
+ t.Fatalf("status = %d, want 400: %s", w.Code, w.Body.String())
+ }
+ for _, want := range []string{`unknown field \"` + key + `\"`, "profileId"} {
+ if !strings.Contains(w.Body.String(), want) {
+ t.Fatalf("body %q does not contain %q", w.Body.String(), want)
+ }
+ }
+ if runner.runCalled || len(o.List()) != 0 {
+ t.Fatal("an invalid profile key started an instance")
+ }
+ })
+ }
+ }
+}
+
func TestHandleLaunchByNameAliasesStartSemantics(t *testing.T) {
old := processAliveFunc
processAliveFunc = func(pid int) bool { return pid > 0 }
diff --git a/internal/orchestrator/handlers_profiles.go b/internal/orchestrator/handlers_profiles.go
index dbec433b..206d2c3c 100644
--- a/internal/orchestrator/handlers_profiles.go
+++ b/internal/orchestrator/handlers_profiles.go
@@ -39,7 +39,7 @@ func (o *Orchestrator) handleStartByID(w http.ResponseWriter, r *http.Request) {
}
if r.ContentLength > 0 {
if err := httpx.DecodeJSONBody(w, r, 0, &req); err != nil {
- httpx.Error(w, httpx.StatusForJSONDecodeError(err), fmt.Errorf("invalid JSON"))
+ httpx.Error(w, httpx.StatusForJSONDecodeError(err), err)
return
}
}
diff --git a/internal/orchestrator/handlers_tabs.go b/internal/orchestrator/handlers_tabs.go
index 4aab5155..8633a0e0 100644
--- a/internal/orchestrator/handlers_tabs.go
+++ b/internal/orchestrator/handlers_tabs.go
@@ -35,7 +35,7 @@ func (o *Orchestrator) handleInstanceTabOpen(w http.ResponseWriter, r *http.Requ
}
if r.ContentLength > 0 {
if err := httpx.DecodeJSONBody(w, r, 0, &req); err != nil {
- httpx.Error(w, httpx.StatusForJSONDecodeError(err), fmt.Errorf("invalid JSON"))
+ httpx.Error(w, httpx.StatusForJSONDecodeError(err), err)
return
}
}
diff --git a/internal/profiles/handlers.go b/internal/profiles/handlers.go
index b214ff14..0acb0318 100644
--- a/internal/profiles/handlers.go
+++ b/internal/profiles/handlers.go
@@ -371,7 +371,7 @@ func (pm *ProfileManager) handleUpdateByID(w http.ResponseWriter, r *http.Reques
Description *string `json:"description"`
}
if err := httpx.DecodeJSONBody(w, r, 0, &req); err != nil {
- httpx.Error(w, httpx.StatusForJSONDecodeError(err), fmt.Errorf("invalid JSON"))
+ httpx.Error(w, httpx.StatusForJSONDecodeError(err), err)
return
}