Skip to content

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

fix: unknown config keys are never reported because FileConfig's custom UnmarshalJSON defeats DisallowUnknownFields (PIN-079)

Luigi Agostida19b985fafb
diff --git a/internal/config/config_load.go b/internal/config/config_load.go
index 74b6fad8..3dc0276c 100644
--- a/internal/config/config_load.go
+++ b/internal/config/config_load.go
@@ -1,7 +1,6 @@
package config
import (
- "bytes"
"encoding/json"
"fmt"
"log/slog"
@@ -48,9 +47,10 @@ type parsedConfigFile struct {
ReadErr error // os.ReadFile error (incl. not-exist); nil when Found
Legacy bool
FC *FileConfig
- ParseErr error // json unmarshal error (legacy or nested)
- UnknownFields error // non-fatal: unrecognized nested fields
- ValidationErrs []error // non-fatal: ValidateFileConfig
+ ParseErr error // json unmarshal error (legacy or nested)
+ UnknownFields error // non-fatal: unrecognized nested fields
+ UnknownKeys []string // the dotted paths behind UnknownFields
+ ValidationErrs []error // non-fatal: ValidateFileConfig
}
func resolveConfigPath() (path, defaultPath string, envOverride bool) {
@@ -96,10 +96,9 @@ func readAndParseConfigFile() parsedConfigFile {
return res
}
res.FC = fc
- dec := json.NewDecoder(bytes.NewReader(data))
- dec.DisallowUnknownFields()
- if ufErr := dec.Decode(&FileConfig{}); ufErr != nil {
- res.UnknownFields = ufErr
+ if keys := UnknownFileConfigKeys(data); len(keys) > 0 {
+ res.UnknownKeys = keys
+ res.UnknownFields = &UnknownConfigKeysError{Keys: keys}
}
}
if res.FC != nil {
@@ -350,6 +349,7 @@ type ConfigFileStatus struct {
EnvOverride bool
Found bool
ParseErr error
+ UnknownKeys []string
}
// InspectConfigFile reports config-file load status with no side effects.
@@ -361,6 +361,7 @@ func InspectConfigFile() ConfigFileStatus {
EnvOverride: res.EnvOverride,
Found: res.Found,
ParseErr: res.ParseErr,
+ UnknownKeys: res.UnknownKeys,
}
}
diff --git a/internal/config/config_unknown_keys.go b/internal/config/config_unknown_keys.go
new file mode 100644
index 00000000..f12e665a
--- /dev/null
+++ b/internal/config/config_unknown_keys.go
@@ -0,0 +1,179 @@
+package config
+
+import (
+ "encoding/json"
+ "fmt"
+ "reflect"
+ "sort"
+ "strings"
+)
+
+// UnknownConfigKeysError names every key in a config file that no struct tag
+// declares. It carries the paths so callers can list them rather than re-parse a
+// message.
+type UnknownConfigKeysError struct {
+ Keys []string
+}
+
+func (e *UnknownConfigKeysError) Error() string {
+ if len(e.Keys) == 1 {
+ return fmt.Sprintf("unrecognized config key %q", e.Keys[0])
+ }
+ return fmt.Sprintf("unrecognized config keys %s", strings.Join(e.Keys, ", "))
+}
+
+// UnknownFileConfigKeys reports the dotted paths in a config document that
+// FileConfig does not declare — "server.porte", "bogusSection".
+//
+// It walks the document against the struct types instead of using
+// json.Decoder.DisallowUnknownFields, for two reasons the alternative cannot
+// meet: FileConfig has a custom UnmarshalJSON, which makes the decoder's strict
+// setting a no-op for the whole document, and a strict decode stops at the FIRST
+// unknown field, so it can never name more than one. Reporting a path rather
+// than a leaf matters too — "allowedDomains" alone is ambiguous, since it is
+// declared in one section and not another.
+func UnknownFileConfigKeys(data []byte) []string {
+ var root map[string]json.RawMessage
+ if err := json.Unmarshal(data, &root); err != nil {
+ return nil
+ }
+ keys := collectUnknownKeys("", root, reflect.TypeOf(FileConfig{}), aliasFileConfigPaths())
+ sort.Strings(keys)
+ return keys
+}
+
+func collectUnknownKeys(prefix string, raw map[string]json.RawMessage, structType reflect.Type, exempt map[string]bool) []string {
+ var unknown []string
+ for name, value := range raw {
+ path := name
+ if prefix != "" {
+ path = prefix + "." + name
+ }
+ field, ok := jsonFieldByName(structType, name)
+ if !ok {
+ if !exempt[path] {
+ unknown = append(unknown, path)
+ }
+ continue
+ }
+ unknown = append(unknown, collectUnknownKeysUnder(path, value, field.Type, exempt)...)
+ }
+ return unknown
+}
+
+// collectUnknownKeysUnder recurses into a declared field's value. A map-typed
+// field accepts arbitrary keys (browser targets, the retired browsers.config),
+// so its keys are never unknown while its VALUES are still checked against the
+// element type.
+func collectUnknownKeysUnder(path string, value json.RawMessage, fieldType reflect.Type, exempt map[string]bool) []string {
+ fieldType = derefType(fieldType)
+ switch fieldType.Kind() {
+ case reflect.Struct:
+ nested, ok := decodeObject(value)
+ if !ok {
+ return nil
+ }
+ return collectUnknownKeys(path, nested, fieldType, exempt)
+ case reflect.Map:
+ entries, ok := decodeObject(value)
+ if !ok {
+ return nil
+ }
+ var unknown []string
+ for key, entry := range entries {
+ unknown = append(unknown, collectUnknownKeysUnder(path+"."+key, entry, fieldType.Elem(), exempt)...)
+ }
+ return unknown
+ default:
+ return nil
+ }
+}
+
+func decodeObject(value json.RawMessage) (map[string]json.RawMessage, bool) {
+ var object map[string]json.RawMessage
+ if err := json.Unmarshal(value, &object); err != nil || object == nil {
+ return nil, false
+ }
+ return object, true
+}
+
+// jsonFieldByName resolves a document key to a struct field the way
+// encoding/json does: exact json tag first, then a case-insensitive match.
+func jsonFieldByName(structType reflect.Type, name string) (reflect.StructField, bool) {
+ if structType.Kind() != reflect.Struct {
+ return reflect.StructField{}, false
+ }
+ var fallback reflect.StructField
+ found := false
+ for i := 0; i < structType.NumField(); i++ {
+ field := structType.Field(i)
+ if field.PkgPath != "" {
+ continue
+ }
+ tag := jsonTagName(field)
+ if tag == "-" {
+ continue
+ }
+ if tag == name {
+ return field, true
+ }
+ if !found && strings.EqualFold(tag, name) {
+ fallback, found = field, true
+ }
+ }
+ return fallback, found
+}
+
+func jsonTagName(field reflect.StructField) string {
+ tag := field.Tag.Get("json")
+ if tag == "" {
+ return field.Name
+ }
+ name, _, _ := strings.Cut(tag, ",")
+ if name == "" {
+ return field.Name
+ }
+ return name
+}
+
+func derefType(t reflect.Type) reflect.Type {
+ for t.Kind() == reflect.Pointer {
+ t = t.Elem()
+ }
+ return t
+}
+
+// aliasFileConfigPaths lists the keys a config file may legitimately carry that
+// FileConfig does not declare, derived from the raw types
+// NormalizeFileConfigAliasesFromJSON reads. Deriving them rather than listing
+// them is the point: an alias added to the normaliser is exempt here without a
+// second edit, and today's alias — security.idpi.allowedDomains — is otherwise
+// reported as a typo on every config that uses it.
+func aliasFileConfigPaths() map[string]bool {
+ exempt := map[string]bool{}
+ for _, path := range declaredPaths("", reflect.TypeOf(aliasRawConfig{})) {
+ exempt[path] = true
+ }
+ return exempt
+}
+
+func declaredPaths(prefix string, structType reflect.Type) []string {
+ structType = derefType(structType)
+ if structType.Kind() != reflect.Struct {
+ return nil
+ }
+ var paths []string
+ for i := 0; i < structType.NumField(); i++ {
+ field := structType.Field(i)
+ if field.PkgPath != "" || jsonTagName(field) == "-" {
+ continue
+ }
+ path := jsonTagName(field)
+ if prefix != "" {
+ path = prefix + "." + path
+ }
+ paths = append(paths, path)
+ paths = append(paths, declaredPaths(path, field.Type)...)
+ }
+ return paths
+}
diff --git a/internal/config/config_unknown_keys_test.go b/internal/config/config_unknown_keys_test.go
new file mode 100644
index 00000000..45ddc5b5
--- /dev/null
+++ b/internal/config/config_unknown_keys_test.go
@@ -0,0 +1,226 @@
+package config
+
+import (
+ "log/slog"
+ "os"
+ "path/filepath"
+ "reflect"
+ "strings"
+ "testing"
+)
+
+func writeConfigFixture(t *testing.T, body string) string {
+ t.Helper()
+ path := filepath.Join(t.TempDir(), "config.json")
+ if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ t.Setenv("PINCHTAB_CONFIG", path)
+ return path
+}
+
+func hasString(values []string, want string) bool {
+ for _, value := range values {
+ if value == want {
+ return true
+ }
+ }
+ return false
+}
+
+// The detection this replaces was dead code: encoding/json hands the whole
+// document to FileConfig's custom UnmarshalJSON, so DisallowUnknownFields never
+// applied. A strict decode also stops at the first unknown field, which is why
+// the walk must report a LIST, and reports paths rather than leaves — a bare
+// "allowedDomains" is declared in one section and not another.
+func TestUnknownFileConfigKeysNamesEveryUnknownKeyByPath(t *testing.T) {
+ keys := UnknownFileConfigKeys([]byte(`{
+ "server": {"porte": "18901", "token": "tok-sim-user-1234567890"},
+ "bogusSection": {"a": 1},
+ "browser": {"profilesDir": "/tmp/p"}
+ }`))
+
+ for _, want := range []string{"server.porte", "bogusSection", "browser.profilesDir"} {
+ if !hasString(keys, want) {
+ t.Errorf("unknown keys %v missing %q", keys, want)
+ }
+ }
+ if len(keys) != 3 {
+ t.Errorf("unknown keys = %v, want exactly the three unknown ones", keys)
+ }
+}
+
+func TestUnknownFileConfigKeysAcceptsADocumentOfDeclaredKeys(t *testing.T) {
+ keys := UnknownFileConfigKeys([]byte(`{
+ "$schema": "https://pinchtab.com/schema.json",
+ "server": {"port": "9867", "token": "tok-sim-user-1234567890", "logLevel": "debug"},
+ "security": {"allowedDomains": ["example.com"], "idpi": {"enabled": true}},
+ "profiles": {"baseDir": "/tmp/profiles"},
+ "autoSolver": {"enabled": true, "solvers": ["cloudflare"]},
+ "browser": {"targets": {"my-chrome": {"provider": "chrome", "binary": "/usr/bin/chrome"}}}
+ }`))
+
+ if len(keys) != 0 {
+ t.Errorf("a config of declared keys reported %v as unknown", keys)
+ }
+}
+
+// browser.targets keys are operator-chosen, so a target name can never be an
+// unknown key — but a misspelled field INSIDE one still must be.
+func TestUnknownFileConfigKeysTreatsMapKeysAsOpenAndStillChecksTheirValues(t *testing.T) {
+ keys := UnknownFileConfigKeys([]byte(`{"browser": {"targets": {"anything-goes": {"binarie": "/usr/bin/chrome"}}}}`))
+
+ if hasString(keys, "browser.targets.anything-goes") {
+ t.Errorf("an operator-named target was reported as unknown: %v", keys)
+ }
+ if !hasString(keys, "browser.targets.anything-goes.binarie") {
+ t.Errorf("unknown keys %v missing the misspelled field inside the target", keys)
+ }
+}
+
+// The one supported alias no FileConfig field declares. A strict pass reports it
+// as a typo on every config that uses it, so the exemption is the false positive
+// this change would otherwise ship — and it is derived from the very types
+// NormalizeFileConfigAliasesFromJSON reads, so the two cannot drift.
+func TestSupportedAliasIsNotReportedAsUnknown(t *testing.T) {
+ doc := []byte(`{"security": {"idpi": {"allowedDomains": ["example.com"]}}}`)
+
+ if keys := UnknownFileConfigKeys(doc); len(keys) != 0 {
+ t.Errorf("the supported security.idpi.allowedDomains alias was reported as unknown: %v", keys)
+ }
+
+ fc := &FileConfig{}
+ NormalizeFileConfigAliasesFromJSON(fc, doc)
+ if len(fc.Security.AllowedDomains) != 1 || fc.Security.AllowedDomains[0] != "example.com" {
+ t.Fatalf("the alias no longer normalises to security.allowedDomains (%v); the exemption above would then be excusing a key nothing honours", fc.Security.AllowedDomains)
+ }
+}
+
+// The exemptions must stay DERIVED from the types NormalizeFileConfigAliasesFromJSON
+// reads, not restated as a literal beside them: an alias added to the normaliser
+// would then still be reported as a typo. Replacing the derivation with a
+// hand-written list reds this the moment the two disagree.
+func TestAliasExemptionsAreDerivedFromTheNormalisersOwnTypes(t *testing.T) {
+ exempt := aliasFileConfigPaths()
+ if len(exempt) == 0 {
+ t.Fatal("no alias paths derived; the exemption set is empty and this test guards nothing")
+ }
+
+ declared := declaredPaths("", reflect.TypeOf(aliasRawConfig{}))
+ if len(declared) != len(exempt) {
+ t.Errorf("exempt set %v does not match the alias types' declared paths %v", exempt, declared)
+ }
+ for _, path := range declared {
+ if !exempt[path] {
+ t.Errorf("alias type declares %q but the walk does not exempt it", path)
+ }
+ }
+ if !exempt["security.idpi.allowedDomains"] {
+ t.Errorf("the alias that no FileConfig field declares is missing from the derived set: %v", exempt)
+ }
+}
+
+func TestLoadConfigReportsUnknownKeysAsAWarnDiagnostic(t *testing.T) {
+ writeConfigFixture(t, `{"server":{"port":"18901","porte":"18901","token":"tok-sim-user-1234567890"},"bogusSection":{"a":1}}`)
+
+ cfg, diags, err := LoadConfig()
+ if err != nil {
+ t.Fatalf("LoadConfig: %v", err)
+ }
+ if cfg.Port != "18901" {
+ t.Fatalf("the declared keys must still load: port = %q", cfg.Port)
+ }
+
+ var found *LoadDiagnostic
+ for i := range diags {
+ if strings.Contains(diags[i].Message, "unrecognized fields") {
+ found = &diags[i]
+ }
+ }
+ if found == nil {
+ t.Fatalf("no unrecognized-fields diagnostic among %d diagnostics", len(diags))
+ }
+ if found.Level != slog.LevelWarn {
+ t.Errorf("diagnostic level = %v, want %v", found.Level, slog.LevelWarn)
+ }
+ rendered := renderDiagnosticAttrs(found.Attrs)
+ for _, want := range []string{"server.porte", "bogusSection"} {
+ if !strings.Contains(rendered, want) {
+ t.Errorf("diagnostic attrs %q do not name %q", rendered, want)
+ }
+ }
+}
+
+func renderDiagnosticAttrs(attrs []any) string {
+ var parts []string
+ for _, attr := range attrs {
+ if err, ok := attr.(error); ok {
+ parts = append(parts, err.Error())
+ continue
+ }
+ if text, ok := attr.(string); ok {
+ parts = append(parts, text)
+ }
+ }
+ return strings.Join(parts, " ")
+}
+
+// InspectConfigFile is what doctor reads, and it used to drop the unknown-key
+// result readAndParseConfigFile had already computed.
+func TestInspectConfigFileCarriesUnknownKeys(t *testing.T) {
+ writeConfigFixture(t, `{"server":{"porte":"18901","token":"tok-sim-user-1234567890"},"bogusSection":{"a":1}}`)
+
+ status := InspectConfigFile()
+ if !status.Found {
+ t.Fatal("fixture config not found")
+ }
+ if len(status.UnknownKeys) != 2 {
+ t.Fatalf("status.UnknownKeys = %v, want both unknown keys", status.UnknownKeys)
+ }
+ for _, want := range []string{"server.porte", "bogusSection"} {
+ if !hasString(status.UnknownKeys, want) {
+ t.Errorf("status.UnknownKeys %v missing %q", status.UnknownKeys, want)
+ }
+ }
+}
+
+// The error text is what the warning renders, so it must carry the paths.
+func TestUnknownConfigKeysErrorNamesThePaths(t *testing.T) {
+ one := (&UnknownConfigKeysError{Keys: []string{"server.porte"}}).Error()
+ if !strings.Contains(one, "server.porte") {
+ t.Errorf("single-key error = %q", one)
+ }
+ many := (&UnknownConfigKeysError{Keys: []string{"server.porte", "bogusSection"}}).Error()
+ if !strings.Contains(many, "server.porte") || !strings.Contains(many, "bogusSection") {
+ t.Errorf("multi-key error = %q", many)
+ }
+}
+
+// The walk checks the document against FileConfig's own tags, which is only the
+// right key set while FileConfig's UnmarshalJSON decodes a defined-type shadow of
+// ITSELF. This package also carries fileConfigJSON, a separate shape used for
+// WRITING; if the reader ever switched to that, the walk would start reporting
+// keys the loader honours and accepting keys it ignores.
+func TestReaderDecodesAFileConfigShadowSoTheWalkChecksTheRightKeys(t *testing.T) {
+ src, err := os.ReadFile("config_file_marshal.go")
+ if err != nil {
+ t.Fatal(err)
+ }
+ body := string(src)
+ start := strings.Index(body, "func (fc *FileConfig) UnmarshalJSON(")
+ if start < 0 {
+ t.Fatal("FileConfig.UnmarshalJSON not found; the unknown-key walk's premise cannot be checked")
+ }
+ end := strings.Index(body[start:], "\n}\n")
+ if end < 0 {
+ t.Fatal("could not delimit UnmarshalJSON")
+ }
+ unmarshaler := body[start : start+end]
+
+ if !strings.Contains(unmarshaler, "type rawFileConfig FileConfig") {
+ t.Error("UnmarshalJSON no longer decodes a defined-type shadow of FileConfig; UnknownFileConfigKeys walks FileConfig's tags and must be pointed at whatever shape the reader now uses")
+ }
+ if strings.Contains(unmarshaler, "fileConfigJSON") {
+ t.Error("UnmarshalJSON decodes the write-side fileConfigJSON shape; the unknown-key walk reads FileConfig's tags, so the two key sets can now disagree")
+ }
+}
diff --git a/internal/config/fileio.go b/internal/config/fileio.go
index d29e15f6..e7091dbb 100644
--- a/internal/config/fileio.go
+++ b/internal/config/fileio.go
@@ -253,23 +253,30 @@ func loadLegacyFileConfig(data []byte) (*FileConfig, error) {
return fc, nil
}
+// aliasRaw* are the config keys this normaliser accepts. They are package types
+// rather than function-local ones so the unknown-key walk can derive its
+// exemptions from them: security.idpi.allowedDomains is a supported alias that
+// no FileConfig field declares, and a strict pass reports it as a typo unless
+// the exemption comes from this same declaration.
+type aliasRawIDPI struct {
+ AllowedDomains *[]string `json:"allowedDomains"`
+}
+
+type aliasRawSecurity struct {
+ AllowedDomains *[]string `json:"allowedDomains"`
+ IDPI *aliasRawIDPI `json:"idpi"`
+}
+
+type aliasRawConfig struct {
+ Security *aliasRawSecurity `json:"security"`
+}
+
func NormalizeFileConfigAliasesFromJSON(fc *FileConfig, data []byte) {
if fc == nil {
return
}
- type rawIDPI struct {
- AllowedDomains *[]string `json:"allowedDomains"`
- }
- type rawSecurity struct {
- AllowedDomains *[]string `json:"allowedDomains"`
- IDPI *rawIDPI `json:"idpi"`
- }
- type rawConfig struct {
- Security *rawSecurity `json:"security"`
- }
-
- var raw rawConfig
+ var raw aliasRawConfig
if err := json.Unmarshal(data, &raw); err != nil || raw.Security == nil {
return
}
diff --git a/internal/doctor/checks_system.go b/internal/doctor/checks_system.go
index 6484c2ed..06db7f06 100644
--- a/internal/doctor/checks_system.go
+++ b/internal/doctor/checks_system.go
@@ -3,6 +3,7 @@ package doctor
import (
"context"
"fmt"
+ "strings"
"github.com/pinchtab/pinchtab/internal/config"
)
@@ -25,6 +26,15 @@ func checkConfigFile(_ context.Context, _ *config.RuntimeConfig) CheckResult {
Err: status.ParseErr,
}
}
+ // A typo in a config key loads fine and yields a working server with silently
+ // wrong settings, so "loaded" alone is not a clean bill of health: name the
+ // keys that were ignored.
+ if len(status.UnknownKeys) > 0 {
+ return CheckResult{
+ Status: StatusWarn,
+ Detail: fmt.Sprintf("%s (loaded) — unrecognized keys ignored: %s", status.Path, strings.Join(status.UnknownKeys, ", ")),
+ }
+ }
return CheckResult{
Status: StatusPass,
Detail: status.Path + " (loaded)",
diff --git a/internal/doctor/checks_system_test.go b/internal/doctor/checks_system_test.go
index a52a28ff..f4acaebb 100644
--- a/internal/doctor/checks_system_test.go
+++ b/internal/doctor/checks_system_test.go
@@ -86,6 +86,44 @@ func TestConfigFile_Missing(t *testing.T) {
}
}
+// A config whose keys are typos loads cleanly, so doctor used to call it OK and
+// send the user away — the very reason the server was running on a port they had
+// not set. It must name what it ignored.
+func TestConfigFile_UnknownKeysWarnAndAreNamed(t *testing.T) {
+ dir := t.TempDir()
+ path := filepath.Join(dir, "config.json")
+ body := `{"server":{"porte":"18901","token":"tok-sim-user-1234567890"},"bogusSection":{"a":1}}`
+ if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ t.Setenv("PINCHTAB_CONFIG", path)
+
+ r := checkConfigFile(context.Background(), nil)
+ if r.Status != StatusWarn {
+ t.Fatalf("status = %v want warn; detail=%q", r.Status, r.Detail)
+ }
+ for _, want := range []string{"server.porte", "bogusSection"} {
+ if !strings.Contains(r.Detail, want) {
+ t.Errorf("detail %q should name the unrecognized key %q", r.Detail, want)
+ }
+ }
+}
+
+// The supported alias must not turn every config that uses it into a warning.
+func TestConfigFile_SupportedAliasStaysPassing(t *testing.T) {
+ dir := t.TempDir()
+ path := filepath.Join(dir, "config.json")
+ if err := os.WriteFile(path, []byte(`{"security":{"idpi":{"allowedDomains":["example.com"]}}}`), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ t.Setenv("PINCHTAB_CONFIG", path)
+
+ r := checkConfigFile(context.Background(), nil)
+ if r.Status != StatusPass {
+ t.Fatalf("status = %v want pass; detail=%q", r.Status, r.Detail)
+ }
+}
+
func TestConfigFile_ParseError(t *testing.T) {
dir := t.TempDir()
path := filepath.Join(dir, "config.json")