High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
package config
import (
"fmt"
"net"
"os"
"path/filepath"
"regexp"
"slices"
"strconv"
"strings"
"github.com/pinchtab/pinchtab/internal/autosolver/catalog"
"github.com/pinchtab/pinchtab/internal/browsers"
"github.com/pinchtab/pinchtab/internal/config/geo"
"github.com/pinchtab/pinchtab/internal/safelog"
"github.com/pinchtab/pinchtab/internal/session"
)
// validateAgentSessionMode gates sessions.agent.mode. "required" is refused
// rather than accepted-and-ignored: it names a real posture — the session
// credential as the only accepted agent credential — that this server does not
// enforce, and an operator who sets it believes they have session-only auth while
// the bearer token and the dashboard cookie still authenticate. Refusing is
// operator-visible and small-radius (the default is preferred, so only an explicit
// setter is hit) and it replaces a silent security misapprehension with a loud one.
func validateAgentSessionMode(mode string) []error {
switch session.NormalizeMode(mode) {
case "", session.ModeOff, session.ModePreferred:
return nil
case session.ModeRequired:
return []error{ValidationError{
Field: "sessions.agent.mode",
Message: fmt.Sprintf("%q is not implemented: the server bearer token and the dashboard cookie still authenticate, so this value cannot deliver the session-only auth it names (must be off or preferred)", session.ModeRequired),
FatalAtLoad: true,
}}
default:
return []error{ValidationError{
Field: "sessions.agent.mode",
Message: fmt.Sprintf("invalid value %q (must be off or preferred)", mode),
FatalAtLoad: true,
}}
}
}
type ValidationError struct {
Field string
Message string
// FatalAtLoad stops the process at load instead of warning past the problem.
// Membership is an explicit opt-in with a reason per field, so the class stays
// readable in the type rather than being re-decided from a message:
//
// sessions.agent.mode — an auth posture. A value the server cannot interpret
// would otherwise be read as the default and leave agent sessions serving,
// which is the misapprehension refusing it exists to end. Choosing a posture
// on the operator's behalf is what a load must not do.
//
// It is the only member. Every other validation error warns at load and gates
// only the write paths, which is what keeps an inert key from aborting a server.
FatalAtLoad bool
}
func (e ValidationError) Error() string {
return fmt.Sprintf("%s: %s", e.Field, e.Message)
}
// ValidateFileConfig returns the GATING problems in a FileConfig: values that are wrong,
// out of range, or no longer supported. Every caller that decides whether a write may
// proceed gates on this, so anything returned here blocks a save — off a TTY that means an
// agent's write is refused, which is correct for an invalid port and wrong for a key that
// merely does nothing.
//
// Advisories live in FileConfigAdvisories instead. Two severities rather than one is the
// whole point: a diagnostic about an inert key used to ride this list and abort every
// later config write, including writes to unrelated keys.
func ValidateFileConfig(fc *FileConfig) []error {
var errs []error
if fc.Server.Port != "" {
if err := validatePort(fc.Server.Port, "server.port"); err != nil {
errs = append(errs, err)
}
}
if fc.Server.Bind != "" {
if err := validateBind(fc.Server.Bind, "server.bind"); err != nil {
errs = append(errs, err)
}
}
if fc.Server.LogLevel != "" {
if _, err := safelog.ParseLevel(fc.Server.LogLevel); err != nil {
errs = append(errs, ValidationError{Field: "server.logLevel", Message: err.Error()})
}
}
if fc.Server.NetworkBufferSize != nil {
if *fc.Server.NetworkBufferSize < 1 || *fc.Server.NetworkBufferSize > MaxNetworkBufferSize {
errs = append(errs, ValidationError{
Field: "server.networkBufferSize",
Message: fmt.Sprintf("must be between 1 and %d (got %d)", MaxNetworkBufferSize, *fc.Server.NetworkBufferSize),
})
}
}
if fc.Server.RetainNetworkBodyMaxBytes != nil {
if *fc.Server.RetainNetworkBodyMaxBytes < 0 || *fc.Server.RetainNetworkBodyMaxBytes > MaxRetainNetworkBodyMaxBytes {
errs = append(errs, ValidationError{
Field: "server.retainNetworkBodyMaxBytes",
Message: fmt.Sprintf("must be between 0 and %d (got %d)", MaxRetainNetworkBodyMaxBytes, *fc.Server.RetainNetworkBodyMaxBytes),
})
}
}
if fc.Server.Engine != "" {
errs = append(errs, fmt.Errorf("server.engine is no longer supported; use browsers.default instead"))
}
if fc.Browser.Provider != "" {
errs = append(errs, fmt.Errorf("browser.provider is no longer supported; use browsers.default instead (e.g. \"browsers\": {\"default\": %q})", fc.Browser.Provider))
}
errs = append(errs, validateCloakBrowserConfig(fc.Browser.Cloak)...)
errs = append(errs, ValidateBrowserProxy("browser.proxy", fc.Browser.Proxy)...)
errs = append(errs, ValidateBrowserTargets(fc.Browser)...)
errs = append(errs, validateBrowsersBlock(*fc)...)
if fc.MultiInstance.InstancePortStart != nil && fc.MultiInstance.InstancePortEnd != nil {
if *fc.MultiInstance.InstancePortStart > *fc.MultiInstance.InstancePortEnd {
errs = append(errs, ValidationError{
Field: "multiInstance.instancePortStart/End",
Message: fmt.Sprintf("start port (%d) must be <= end port (%d)", *fc.MultiInstance.InstancePortStart, *fc.MultiInstance.InstancePortEnd),
})
}
}
if fc.MultiInstance.Restart.MaxRestarts != nil {
if *fc.MultiInstance.Restart.MaxRestarts < -1 {
errs = append(errs, ValidationError{
Field: "multiInstance.restart.maxRestarts",
Message: fmt.Sprintf("must be >= 0 or -1 for unlimited (got %d)", *fc.MultiInstance.Restart.MaxRestarts),
})
}
}
if fc.MultiInstance.Restart.InitBackoffSec != nil && *fc.MultiInstance.Restart.InitBackoffSec < 1 {
errs = append(errs, ValidationError{
Field: "multiInstance.restart.initBackoffSec",
Message: fmt.Sprintf("must be >= 1 (got %d)", *fc.MultiInstance.Restart.InitBackoffSec),
})
}
if fc.MultiInstance.Restart.MaxBackoffSec != nil && *fc.MultiInstance.Restart.MaxBackoffSec < 1 {
errs = append(errs, ValidationError{
Field: "multiInstance.restart.maxBackoffSec",
Message: fmt.Sprintf("must be >= 1 (got %d)", *fc.MultiInstance.Restart.MaxBackoffSec),
})
}
if fc.MultiInstance.Restart.StableAfterSec != nil && *fc.MultiInstance.Restart.StableAfterSec < 1 {
errs = append(errs, ValidationError{
Field: "multiInstance.restart.stableAfterSec",
Message: fmt.Sprintf("must be >= 1 (got %d)", *fc.MultiInstance.Restart.StableAfterSec),
})
}
if fc.MultiInstance.Restart.InitBackoffSec != nil && fc.MultiInstance.Restart.MaxBackoffSec != nil &&
*fc.MultiInstance.Restart.InitBackoffSec > *fc.MultiInstance.Restart.MaxBackoffSec {
errs = append(errs, ValidationError{
Field: "multiInstance.restart.initBackoffSec/maxBackoffSec",
Message: fmt.Sprintf("init backoff (%d) must be <= max backoff (%d)", *fc.MultiInstance.Restart.InitBackoffSec, *fc.MultiInstance.Restart.MaxBackoffSec),
})
}
if fc.InstanceDefaults.Headless != nil && fc.InstanceDefaults.Mode != "" {
errs = append(errs, ValidationError{
Field: "instanceDefaults.headless",
Message: fmt.Sprintf("both headless and mode are set; mode %q takes precedence", fc.InstanceDefaults.Mode),
})
}
if fc.InstanceDefaults.Mode != "" && fc.InstanceDefaults.Mode != "headless" && fc.InstanceDefaults.Mode != "headed" {
errs = append(errs, ValidationError{
Field: "instanceDefaults.mode",
Message: fmt.Sprintf("invalid value %q (must be headless or headed)", fc.InstanceDefaults.Mode),
})
}
if fc.InstanceDefaults.StealthLevel != "" {
if !isValidStealthLevel(fc.InstanceDefaults.StealthLevel) {
errs = append(errs, ValidationError{
Field: "instanceDefaults.stealthLevel",
Message: fmt.Sprintf("invalid value %q (must be light, medium, or full)", fc.InstanceDefaults.StealthLevel),
})
}
}
if fc.InstanceDefaults.TabEvictionPolicy != "" {
if !isValidEvictionPolicy(fc.InstanceDefaults.TabEvictionPolicy) {
errs = append(errs, ValidationError{
Field: "instanceDefaults.tabEvictionPolicy",
Message: fmt.Sprintf("invalid value %q (must be reject, close_oldest, or close_lru)", fc.InstanceDefaults.TabEvictionPolicy),
})
}
}
if tp := fc.InstanceDefaults.TabPolicy; tp != nil {
if tp.Eviction != "" && !isValidEvictionPolicy(tp.Eviction) {
errs = append(errs, ValidationError{
Field: "instanceDefaults.tabPolicy.eviction",
Message: fmt.Sprintf("invalid value %q (must be reject, close_oldest, or close_lru)", tp.Eviction),
})
}
if tp.Lifecycle != "" && !isValidLifecyclePolicy(tp.Lifecycle) {
errs = append(errs, ValidationError{
Field: "instanceDefaults.tabPolicy.lifecycle",
Message: fmt.Sprintf("invalid value %q (must be keep, close_idle, or freeze_idle)", tp.Lifecycle),
})
}
if tp.CloseDelaySec != nil && *tp.CloseDelaySec < 0 {
errs = append(errs, ValidationError{
Field: "instanceDefaults.tabPolicy.closeDelaySec",
Message: fmt.Sprintf("must be >= 0 (got %d)", *tp.CloseDelaySec),
})
}
}
if fc.InstanceDefaults.MaxTabs != nil && *fc.InstanceDefaults.MaxTabs < 1 {
errs = append(errs, ValidationError{
Field: "instanceDefaults.maxTabs",
Message: fmt.Sprintf("must be >= 1 (got %d)", *fc.InstanceDefaults.MaxTabs),
})
}
if fc.InstanceDefaults.MaxParallelTabs != nil && *fc.InstanceDefaults.MaxParallelTabs < 0 {
errs = append(errs, ValidationError{
Field: "instanceDefaults.maxParallelTabs",
Message: fmt.Sprintf("must be >= 0 (got %d)", *fc.InstanceDefaults.MaxParallelTabs),
})
}
if fc.MultiInstance.Strategy != "" {
if !isValidStrategy(fc.MultiInstance.Strategy) {
errs = append(errs, ValidationError{
Field: "multiInstance.strategy",
Message: fmt.Sprintf("invalid value %q (must be simple, explicit, simple-autorestart, or always-on)", fc.MultiInstance.Strategy),
})
}
}
if fc.MultiInstance.AllocationPolicy != "" {
if !isValidAllocationPolicy(fc.MultiInstance.AllocationPolicy) {
errs = append(errs, ValidationError{
Field: "multiInstance.allocationPolicy",
Message: fmt.Sprintf("invalid value %q (must be fcfs, round_robin, or random)", fc.MultiInstance.AllocationPolicy),
})
}
}
for _, scheme := range fc.Security.Attach.AllowSchemes {
if !isValidAttachScheme(scheme) {
errs = append(errs, ValidationError{
Field: "security.attach.allowSchemes",
Message: fmt.Sprintf("invalid value %q (must be ws, wss, http, or https)", scheme),
})
}
}
if fc.Browser.BrowserExtraFlags != "" {
errs = append(errs, validateBrowserExtraFlags(fc.Browser.BrowserExtraFlags)...)
}
errs = append(errs, validateIDPIConfig(fc.Security.EffectiveIDPI(), effectiveSecurityAllowedDomains(fc.Security))...)
errs = append(errs, validateAllowedDomainList("security.downloadAllowedDomains", fc.Security.DownloadAllowedDomains)...)
errs = append(errs, validateTrustedCIDRList("security.trustedProxyCIDRs", fc.Security.TrustedProxyCIDRs)...)
errs = append(errs, validateTrustedCIDRList("security.trustedResolveCIDRs", fc.Security.TrustedResolveCIDRs)...)
errs = append(errs, validatePositiveIntLimit("security.downloadMaxBytes", fc.Security.DownloadMaxBytes, MaxDownloadMaxBytes)...)
errs = append(errs, validatePositiveIntLimit("security.memorySnapshotMaxBytes", fc.Security.MemorySnapshotMaxBytes, MaxMemorySnapshotMaxBytes)...)
errs = append(errs, validatePositiveIntLimit("security.uploadMaxRequestBytes", fc.Security.UploadMaxRequestBytes, MaxUploadMaxRequestBytes)...)
errs = append(errs, validatePositiveIntLimit("security.uploadMaxFiles", fc.Security.UploadMaxFiles, MaxUploadMaxFiles)...)
errs = append(errs, validatePositiveIntLimit("security.uploadMaxFileBytes", fc.Security.UploadMaxFileBytes, MaxUploadMaxFileBytes)...)
errs = append(errs, validatePositiveIntLimit("security.uploadMaxTotalBytes", fc.Security.UploadMaxTotalBytes, MaxUploadMaxTotalBytes)...)
if fc.Security.UploadMaxFileBytes != nil && fc.Security.UploadMaxTotalBytes != nil &&
*fc.Security.UploadMaxFileBytes > *fc.Security.UploadMaxTotalBytes {
errs = append(errs, ValidationError{
Field: "security.uploadMaxFileBytes/uploadMaxTotalBytes",
Message: fmt.Sprintf("uploadMaxFileBytes (%d) must be <= uploadMaxTotalBytes (%d)", *fc.Security.UploadMaxFileBytes, *fc.Security.UploadMaxTotalBytes),
})
}
if fc.Timeouts.ActionSec < 0 {
errs = append(errs, ValidationError{
Field: "timeouts.actionSec",
Message: fmt.Sprintf("must be >= 0 (got %d)", fc.Timeouts.ActionSec),
})
}
if fc.Timeouts.NavigateSec < 0 {
errs = append(errs, ValidationError{
Field: "timeouts.navigateSec",
Message: fmt.Sprintf("must be >= 0 (got %d)", fc.Timeouts.NavigateSec),
})
}
if fc.Timeouts.ShutdownSec < 0 {
errs = append(errs, ValidationError{
Field: "timeouts.shutdownSec",
Message: fmt.Sprintf("must be >= 0 (got %d)", fc.Timeouts.ShutdownSec),
})
}
if fc.Timeouts.WaitNavMs < 0 {
errs = append(errs, ValidationError{
Field: "timeouts.waitNavMs",
Message: fmt.Sprintf("must be >= 0 (got %d)", fc.Timeouts.WaitNavMs),
})
}
if fc.AutoSolver.MaxAttempts != nil && *fc.AutoSolver.MaxAttempts < 1 {
errs = append(errs, ValidationError{
Field: "autoSolver.maxAttempts",
Message: fmt.Sprintf("must be >= 1 (got %d)", *fc.AutoSolver.MaxAttempts),
})
}
if fc.AutoSolver.SolverTimeoutSec != nil && *fc.AutoSolver.SolverTimeoutSec <= 0 {
errs = append(errs, ValidationError{
Field: "autoSolver.solverTimeoutSec",
Message: fmt.Sprintf("must be > 0 (got %d)", *fc.AutoSolver.SolverTimeoutSec),
})
}
if fc.AutoSolver.RetryBaseDelayMs != nil && *fc.AutoSolver.RetryBaseDelayMs < 0 {
errs = append(errs, ValidationError{
Field: "autoSolver.retryBaseDelayMs",
Message: fmt.Sprintf("must be >= 0 (got %d)", *fc.AutoSolver.RetryBaseDelayMs),
})
}
if fc.AutoSolver.RetryMaxDelayMs != nil && *fc.AutoSolver.RetryMaxDelayMs < 0 {
errs = append(errs, ValidationError{
Field: "autoSolver.retryMaxDelayMs",
Message: fmt.Sprintf("must be >= 0 (got %d)", *fc.AutoSolver.RetryMaxDelayMs),
})
}
if fc.AutoSolver.RetryBaseDelayMs != nil && fc.AutoSolver.RetryMaxDelayMs != nil &&
*fc.AutoSolver.RetryBaseDelayMs > *fc.AutoSolver.RetryMaxDelayMs {
errs = append(errs, ValidationError{
Field: "autoSolver.retryBaseDelayMs/retryMaxDelayMs",
Message: fmt.Sprintf("retry base delay (%d) must be <= retry max delay (%d)", *fc.AutoSolver.RetryBaseDelayMs, *fc.AutoSolver.RetryMaxDelayMs),
})
}
for _, solverName := range fc.AutoSolver.Solvers {
if strings.TrimSpace(solverName) == "" {
errs = append(errs, ValidationError{
Field: "autoSolver.solvers",
Message: "solver names must not be empty",
})
break
}
}
// An unmatched name does not fail at run time, it changes which solvers run:
// one typo alongside good names silently drops that solver, and a list of
// only typos silently runs every solver instead.
for i, solverName := range fc.AutoSolver.Solvers {
name := strings.TrimSpace(solverName)
if name == "" || catalog.IsKnown(name) {
continue
}
errs = append(errs, ValidationError{
Field: fmt.Sprintf("autoSolver.solvers[%d]", i),
Message: fmt.Sprintf("unknown solver %q (known: %v)", name, catalog.Names()),
})
}
if fc.Observability.Activity.SessionIdleSec != nil && *fc.Observability.Activity.SessionIdleSec < 0 {
errs = append(errs, ValidationError{
Field: "observability.activity.sessionIdleSec",
Message: fmt.Sprintf("must be >= 0 (got %d)", *fc.Observability.Activity.SessionIdleSec),
})
}
if fc.Observability.Activity.RetentionDays != nil && *fc.Observability.Activity.RetentionDays <= 0 {
errs = append(errs, ValidationError{
Field: "observability.activity.retentionDays",
Message: fmt.Sprintf("must be > 0 (got %d)", *fc.Observability.Activity.RetentionDays),
})
}
errs = append(errs, validateAgentSessionMode(fc.Sessions.Agent.Mode)...)
if fc.Sessions.Dashboard.IdleTimeoutSec != nil && *fc.Sessions.Dashboard.IdleTimeoutSec <= 0 {
errs = append(errs, ValidationError{
Field: "sessions.dashboard.idleTimeoutSec",
Message: fmt.Sprintf("must be > 0 (got %d)", *fc.Sessions.Dashboard.IdleTimeoutSec),
})
}
if fc.Sessions.Dashboard.MaxLifetimeSec != nil && *fc.Sessions.Dashboard.MaxLifetimeSec <= 0 {
errs = append(errs, ValidationError{
Field: "sessions.dashboard.maxLifetimeSec",
Message: fmt.Sprintf("must be > 0 (got %d)", *fc.Sessions.Dashboard.MaxLifetimeSec),
})
}
if fc.Sessions.Dashboard.ElevationWindowSec != nil && *fc.Sessions.Dashboard.ElevationWindowSec <= 0 {
errs = append(errs, ValidationError{
Field: "sessions.dashboard.elevationWindowSec",
Message: fmt.Sprintf("must be > 0 (got %d)", *fc.Sessions.Dashboard.ElevationWindowSec),
})
}
if fc.Sessions.Dashboard.IdleTimeoutSec != nil && fc.Sessions.Dashboard.MaxLifetimeSec != nil &&
*fc.Sessions.Dashboard.IdleTimeoutSec > *fc.Sessions.Dashboard.MaxLifetimeSec {
errs = append(errs, ValidationError{
Field: "sessions.dashboard.idleTimeoutSec/maxLifetimeSec",
Message: fmt.Sprintf("idle timeout (%d) must be <= max lifetime (%d)", *fc.Sessions.Dashboard.IdleTimeoutSec, *fc.Sessions.Dashboard.MaxLifetimeSec),
})
}
return errs
}
func validatePort(port string, field string) error {
p, err := strconv.Atoi(port)
if err != nil {
return ValidationError{
Field: field,
Message: fmt.Sprintf("invalid port %q (must be a number)", port),
}
}
if p < 1 || p > 65535 {
return ValidationError{
Field: field,
Message: fmt.Sprintf("port %d out of range (must be 1-65535)", p),
}
}
return nil
}
func validateBind(bind string, field string) error {
validBinds := map[string]bool{
"127.0.0.1": true,
"0.0.0.0": true,
"localhost": true,
"::1": true,
"::": true,
}
if validBinds[bind] {
return nil
}
// Intentionally loose — the OS will reject truly invalid addresses.
return nil
}
var cloakFingerprintSeedRegex = regexp.MustCompile(`^[A-Za-z0-9._:-]{1,128}$`)
func validateCloakBrowserConfig(cloak CloakBrowserConfig) []error {
return validateCloakBrowserConfigAt("browser.cloak", cloak)
}
func validateCloakBrowserConfigAt(fieldPrefix string, cloak CloakBrowserConfig) []error {
var errs []error
if cloak.Platform != "" && !isValidCloakPlatform(cloak.Platform) {
errs = append(errs, ValidationError{
Field: fieldPrefix + ".platform",
Message: fmt.Sprintf("invalid value %q (must be windows, macos, or linux)", cloak.Platform),
})
}
if cloak.StorageQuotaMB != nil && *cloak.StorageQuotaMB < 0 {
errs = append(errs, ValidationError{
Field: fieldPrefix + ".storageQuotaMB",
Message: fmt.Sprintf("must be >= 0 (got %d)", *cloak.StorageQuotaMB),
})
}
if seed := strings.TrimSpace(cloak.FingerprintSeed); seed != "" && !cloakFingerprintSeedRegex.MatchString(seed) {
errs = append(errs, ValidationError{
Field: fieldPrefix + ".fingerprintSeed",
Message: "must be 1-128 characters of letters, numbers, dot, underscore, colon, or hyphen",
})
}
if err := geo.Validate(geo.Info{Timezone: cloak.Timezone, Locale: cloak.Locale}); err != nil {
errs = append(errs, ValidationError{
Field: fieldPrefix,
Message: err.Error(),
})
}
if ip := strings.TrimSpace(cloak.WebRTCIP); ip != "" && !strings.EqualFold(ip, "auto") && net.ParseIP(ip) == nil {
errs = append(errs, ValidationError{
Field: fieldPrefix + ".webrtcIP",
Message: fmt.Sprintf("webrtcIP %q must be \"auto\" or a valid IP address", cloak.WebRTCIP),
})
}
if dir := strings.TrimSpace(cloak.FontsDir); dir != "" {
clean := filepath.Clean(dir)
if clean != dir {
errs = append(errs, ValidationError{
Field: fieldPrefix + ".fontsDir",
Message: fmt.Sprintf("must be a clean path (got %q, clean form is %q)", dir, clean),
})
} else if st, err := os.Stat(dir); err != nil {
errs = append(errs, ValidationError{
Field: fieldPrefix + ".fontsDir",
Message: fmt.Sprintf("must be an existing directory: %v", err),
})
} else if !st.IsDir() {
errs = append(errs, ValidationError{
Field: fieldPrefix + ".fontsDir",
Message: "must be an existing directory",
})
}
}
return errs
}
// Enumerated config option sets are defined exactly once here; both the
// isValid* membership checks and the exported Valid*() lists derive from these
// slices so the two can't drift apart.
var (
cloakPlatforms = []string{"windows", "macos", "linux"}
stealthLevels = []string{"light", "medium", "full"}
evictionPolicies = []string{"reject", "close_oldest", "close_lru"}
lifecyclePolicies = []string{"keep", "close_idle", "freeze_idle"}
strategies = []string{"simple", "explicit", "simple-autorestart", "always-on", "no-instance"}
allocationPolicies = []string{"fcfs", "round_robin", "random"}
attachSchemes = []string{"ws", "wss", "http", "https"}
)
func isValidCloakPlatform(platform string) bool {
return slices.Contains(cloakPlatforms, strings.ToLower(strings.TrimSpace(platform)))
}
func isValidStealthLevel(level string) bool {
return slices.Contains(stealthLevels, level)
}
func isValidEvictionPolicy(policy string) bool {
return slices.Contains(evictionPolicies, policy)
}
func isValidLifecyclePolicy(policy string) bool {
return slices.Contains(lifecyclePolicies, policy)
}
func IdleTabLifecycle(policy string) bool {
return policy == "close_idle" || policy == "freeze_idle"
}
func ValidLifecyclePolicies() []string {
return slices.Clone(lifecyclePolicies)
}
func isValidStrategy(strategy string) bool {
return slices.Contains(strategies, strategy)
}
func isValidAllocationPolicy(policy string) bool {
return slices.Contains(allocationPolicies, policy)
}
func isValidAttachScheme(scheme string) bool {
return slices.Contains(attachSchemes, scheme)
}
func ValidStealthLevels() []string {
return slices.Clone(stealthLevels)
}
func ValidEvictionPolicies() []string {
return slices.Clone(evictionPolicies)
}
func ValidStrategies() []string {
return slices.Clone(strategies)
}
// validateIDPIConfig validates the security.idpi sub-section.
// Validation is skipped when IDPI is disabled; a zero-value IDPIConfig is always valid.
func validateIDPIConfig(cfg IDPIConfig, allowedDomains []string) []error {
if !cfg.Enabled {
return nil
}
errs := validateAllowedDomainList("security.allowedDomains", allowedDomains)
for _, p := range cfg.CustomPatterns {
if strings.TrimSpace(p) == "" {
errs = append(errs, ValidationError{
Field: "security.idpi.customPatterns",
Message: "custom pattern must not be empty or whitespace-only",
})
}
}
if cfg.ScanTimeoutSec < 0 {
errs = append(errs, ValidationError{
Field: "security.idpi.scanTimeoutSec",
Message: "scanTimeoutSec must not be negative",
})
}
return errs
}
func validateAllowedDomainList(field string, domains []string) []error {
var errs []error
for _, domain := range domains {
trimmed := strings.TrimSpace(domain)
if trimmed == "" {
errs = append(errs, ValidationError{
Field: field,
Message: "domain pattern must not be empty or whitespace-only",
})
continue
}
if strings.ContainsAny(trimmed, " \t") {
errs = append(errs, ValidationError{
Field: field,
Message: fmt.Sprintf("domain pattern %q must not contain whitespace", trimmed),
})
}
if strings.HasPrefix(trimmed, "file://") {
errs = append(errs, ValidationError{
Field: field,
Message: fmt.Sprintf("domain pattern %q must not use the file:// scheme; use a hostname", trimmed),
})
}
}
return errs
}
func validateTrustedCIDRList(field string, items []string) []error {
var errs []error
for _, item := range items {
trimmed := strings.TrimSpace(item)
if trimmed == "" {
errs = append(errs, ValidationError{
Field: field,
Message: "entry must not be empty or whitespace-only",
})
continue
}
if strings.Contains(trimmed, "/") {
if _, _, err := net.ParseCIDR(trimmed); err != nil {
errs = append(errs, ValidationError{
Field: field,
Message: fmt.Sprintf("entry %q must be a valid CIDR or IP address", trimmed),
})
}
continue
}
if net.ParseIP(trimmed) == nil {
errs = append(errs, ValidationError{
Field: field,
Message: fmt.Sprintf("entry %q must be a valid CIDR or IP address", trimmed),
})
}
}
return errs
}
func validatePositiveIntLimit(field string, value *int, max int) []error {
if value == nil {
return nil
}
if *value < 1 || *value > max {
return []error{ValidationError{
Field: field,
Message: fmt.Sprintf("must be between 1 and %d (got %d)", max, *value),
}}
}
return nil
}
func ValidAllocationPolicies() []string {
return slices.Clone(allocationPolicies)
}
func ValidAttachSchemes() []string {
return slices.Clone(attachSchemes)
}
func validateBrowsersBlock(fc FileConfig) []error {
bc := fc.Browsers
if bc.Default == "" && len(bc.Available) == 0 && len(bc.Config) == 0 {
return nil
}
var errs []error
// Validate default is a known browser. The registry is keyed by lowercase
// IDs; trim+lowercase like target validation does so "Cloak" validates
// the same everywhere.
if bc.Default != "" {
if _, ok := browsers.Get(strings.ToLower(strings.TrimSpace(bc.Default))); !ok {
errs = append(errs, fmt.Errorf("browsers.default: unknown browser %q (known: %v)", bc.Default, browsers.IDs()))
}
}
for i, name := range bc.Available {
if _, ok := browsers.Get(strings.ToLower(strings.TrimSpace(name))); !ok {
errs = append(errs, fmt.Errorf("browsers.available[%d]: unknown browser %q (known: %v)", i, name, browsers.IDs()))
}
}
if bc.Default != "" && len(bc.Available) > 0 {
found := false
wantDefault := strings.ToLower(strings.TrimSpace(bc.Default))
for _, name := range bc.Available {
if strings.ToLower(strings.TrimSpace(name)) == wantDefault {
found = true
break
}
}
if !found {
errs = append(errs, fmt.Errorf("browsers.default %q is not in browsers.available %v", bc.Default, bc.Available))
}
}
// browsers.config was accepted but never applied anywhere; reject it with
// guidance (mirroring the browser.provider retirement) rather than letting
// the overrides be silently ignored.
if len(bc.Config) > 0 {
errs = append(errs, fmt.Errorf("browsers.config is no longer supported; use browser.targets.<name> instead (e.g. \"browser\": {\"targets\": {\"cloak\": {\"binary\": \"/opt/cloak/bin\"}}})"))
}
return errs
}
// FileConfigAdvisories reports what a config file says that has no effect. These are
// REPORTED, never gating: nothing here means the file is unsafe to load or the next write
// is unsafe to make, so blocking a save on one would refuse work for no reason.
//
// A diagnostic belongs here only when the value is inert — PinchTab reads something else,
// or nothing — and the reader has nothing to fix. Anything the user could get wrong, and
// anything PinchTab will act on, stays in ValidateFileConfig where it gates.
//
// observability.activity.stateDir the path is derived from server.stateDir; the loader
// never reads this key, and `config set` refuses it
func FileConfigAdvisories(fc *FileConfig) []string {
if fc == nil {
return nil
}
var advisories []string
if strings.TrimSpace(fc.Observability.Activity.StateDir) != "" {
advisories = append(advisories, ActivityStateDirAdvisory)
}
advisories = append(advisories, proxyServerAdvisories(fc)...)
return advisories
}
// proxyServerAdvisories reports every proxy block that holds something but no server.
// Target proxies are walked too: their blocks were never dropped at save, so a
// serverless one has always been kept and silently unused — the same state this card's
// defect produced for browser.proxy, one level down.
func proxyServerAdvisories(fc *FileConfig) []string {
var advisories []string
if !fc.Browser.Proxy.IsZero() && fc.Browser.Proxy.HasNoServer() {
advisories = append(advisories, ProxyServerRequiredAdvisory("browser.proxy"))
}
for _, name := range SortedBrowserTargetNames(fc.Browser.Targets) {
target := fc.Browser.Targets[name]
if !target.Proxy.IsZero() && target.Proxy.HasNoServer() {
advisories = append(advisories, ProxyServerRequiredAdvisory(fmt.Sprintf("browser.targets.%s.proxy", name)))
}
}
return advisories
}