policy: prefix all SSH validation errors with "ssh"

Author: jek821

CHANGELOG.md

@@ -31,6 +31,7 @@ HTTP API directly.
 ### Changes
 
 - Expiring or deleting a non-existent pre-auth key now returns an error instead of silently succeeding [#3324](https://github.com/juanfont/headscale/pull/3324)
+- SSH policy validation errors now prefix their messages with `ssh:` so failures like `ssh: users must be specified` make it clear that the problem comes from an SSH rule violation [#3343](https://github.com/juanfont/headscale/pull/3343)
 
 ## 0.29.1 (2026-06-18)
 

hscontrol/policy/policy_test.go

@@ -1317,7 +1317,7 @@ func TestSSHPolicyRules(t *testing.T) {
 				]
 			}`,
 			expectErr:    true,
-			errorMessage: `"invalid" is not a valid action`,
+			errorMessage: `ssh: "invalid" is not a valid action`,
 		},
 		{
 			name:       "invalid-check-period",

hscontrol/policy/v2/types.go

@@ -41,17 +41,17 @@ var ErrUndefinedTagReference = errors.New("references undefined tag")
 var (
 	ErrSSHTagSourceToUserDest             = errors.New("tags in SSH source cannot access user-owned devices")
 	ErrSSHUserDestRequiresSameUser        = errors.New("user destination requires source to contain only that same user")
-	ErrSSHAutogroupSelfRequiresUserSource = errors.New("autogroup:self destination requires source to contain only users or groups, not tags or autogroup:tagged")
+	ErrSSHAutogroupSelfRequiresUserSource = errors.New("ssh: autogroup:self destination requires source to contain only users or groups, not tags or autogroup:tagged")
 	ErrSSHTagSourceToAutogroupMember      = errors.New("tags in SSH source cannot access autogroup:member (user-owned devices)")
 	ErrSSHWildcardDestination             = errors.New("wildcard (*) is not supported as SSH destination")
 	ErrSSHCheckPeriodAboveMax             = errors.New("is above the max (168h)")
 	ErrSSHCheckPeriodNegative             = errors.New("must be a positive duration")
-	ErrSSHCheckPeriodOnNonCheck           = errors.New("checkPeriod is only valid with action \"check\"")
+	ErrSSHCheckPeriodOnNonCheck           = errors.New("ssh: checkPeriod is only valid with action \"check\"")
 	ErrInvalidLocalpart                   = errors.New("invalid localpart format, must be localpart:*@<domain>")
-	ErrSSHUsersMustBeSpecified            = errors.New("users must be specified")
+	ErrSSHUsersMustBeSpecified            = errors.New("ssh: users must be specified")
 	ErrSSHUserInvalid                     = errors.New("is not valid")
-	ErrSSHAcceptEnvEmpty                  = errors.New("acceptEnv values cannot be empty")
-	ErrSSHActionMustBeSpecified           = errors.New("action must be specified")
+	ErrSSHAcceptEnvEmpty                  = errors.New("ssh: acceptEnv values cannot be empty")
+	ErrSSHActionMustBeSpecified           = errors.New("ssh: action must be specified")
 	ErrSSHActionInvalid                   = errors.New("is not a valid action")
 	ErrSSHDestinationHostAlias            = errors.New("invalid dst")
 	ErrTagNameMustStartWithLetter         = errors.New("tag names must start with a letter, after 'tag:'")
@@ -1639,7 +1639,7 @@ func (a *SSHAction) UnmarshalJSON(b []byte) error {
 	case "check":
 		*a = SSHActionCheck
 	default:
-		return fmt.Errorf("%q %w", str, ErrSSHActionInvalid)
+		return fmt.Errorf("ssh: %q %w", str, ErrSSHActionInvalid)
 	}
 
 	return nil
@@ -2177,7 +2177,7 @@ func validateSSHSrcDstCombination(sources SSHSrcAliases, destinations SSHDstAlia
 			}
 			// Rule: Username destination requires source to be that same single user only
 			if srcHasGroups || len(srcUsernames) != 1 || !srcUsernames[string(*v)] {
-				return fmt.Errorf("%w %q; use autogroup:self instead for same-user SSH access",
+				return fmt.Errorf("ssh: %w %q; use autogroup:self instead for same-user SSH access",
 					ErrSSHUserDestRequiresSameUser, *v)
 			}
 		case *AutoGroup:
@@ -2428,7 +2428,7 @@ func (p *Policy) validate() error {
 		for _, user := range ssh.Users {
 			switch user {
 			case "", "*":
-				errs = append(errs, fmt.Errorf("user %q %w", user, ErrSSHUserInvalid))
+				errs = append(errs, fmt.Errorf("ssh: user %q %w", user, ErrSSHUserInvalid))
 			}
 		}
 
@@ -2498,7 +2498,7 @@ func (p *Policy) validate() error {
 			case *Host:
 				// Hosts-table aliases are valid on ACL dst but
 				// rejected here for SSH dst.
-				errs = append(errs, fmt.Errorf("%w %q", ErrSSHDestinationHostAlias, string(*dst)))
+				errs = append(errs, fmt.Errorf("ssh: %w %q", ErrSSHDestinationHostAlias, string(*dst)))
 			}
 		}
 
@@ -2852,11 +2852,11 @@ func (p *SSHCheckPeriod) Validate() error {
 	}
 
 	if p.Duration < 0 {
-		return fmt.Errorf("checkPeriod %s %w", p.Duration, ErrSSHCheckPeriodNegative)
+		return fmt.Errorf("ssh: checkPeriod %s %w", p.Duration, ErrSSHCheckPeriodNegative)
 	}
 
 	if p.Duration > SSHCheckPeriodMax {
-		return fmt.Errorf("checkPeriod %s %w", p.Duration, ErrSSHCheckPeriodAboveMax)
+		return fmt.Errorf("ssh: checkPeriod %s %w", p.Duration, ErrSSHCheckPeriodAboveMax)
 	}
 
 	return nil

hscontrol/policy/v2/types_test.go

@@ -723,7 +723,7 @@ func TestUnmarshalPolicy(t *testing.T) {
   ]
 }
 `,
-			wantErr: `user "*" is not valid`,
+			wantErr: `ssh: user "*" is not valid`,
 		},
 		{
 			name: "ssh-with-check-period",
@@ -4763,25 +4763,25 @@ func TestSSHActionInvalidUnmarshal(t *testing.T) {
 			name:    "uppercase rejected",
 			input:   `"ACCEPT"`,
 			wantErr: ErrSSHActionInvalid,
-			wantMsg: `"ACCEPT" is not a valid action`,
+			wantMsg: `ssh: "ACCEPT" is not a valid action`,
 		},
 		{
 			name:    "mixedcase rejected",
 			input:   `"Accept"`,
 			wantErr: ErrSSHActionInvalid,
-			wantMsg: `"Accept" is not a valid action`,
+			wantMsg: `ssh: "Accept" is not a valid action`,
 		},
 		{
 			name:    "whitespace trimmed then mixedcase rejected",
 			input:   `" Accept"`,
 			wantErr: ErrSSHActionInvalid,
-			wantMsg: `"Accept" is not a valid action`,
+			wantMsg: `ssh: "Accept" is not a valid action`,
 		},
 		{
 			name:    "unknown action rejected",
 			input:   `"deny"`,
 			wantErr: ErrSSHActionInvalid,
-			wantMsg: `"deny" is not a valid action`,
+			wantMsg: `ssh: "deny" is not a valid action`,
 		},
 	}
 
@@ -4882,7 +4882,7 @@ func TestSSHUserTrimEndToEnd(t *testing.T) {
 		_, err := unmarshalPolicy([]byte(policy))
 		require.Error(t, err)
 		require.ErrorIs(t, err, ErrSSHUserInvalid)
-		require.Contains(t, err.Error(), `user "" is not valid`)
+		require.Contains(t, err.Error(), `ssh: user "" is not valid`)
 	})
 }
 
@@ -5022,14 +5022,14 @@ func TestSSHCheckPeriodInvalidDuration(t *testing.T) {
 }
 
 // TestSSHCheckPeriodNegativeMessage verifies the SaaS body for the
-// negative-duration case (`checkPeriod -1m0s must be a positive duration`).
+// negative-duration case (`ssh: checkPeriod -1m0s must be a positive duration`).
 func TestSSHCheckPeriodNegativeMessage(t *testing.T) {
 	p := SSHCheckPeriod{Duration: -time.Minute}
 
 	err := p.Validate()
 	require.Error(t, err)
 	require.ErrorIs(t, err, ErrSSHCheckPeriodNegative)
-	require.Contains(t, err.Error(), "checkPeriod -1m0s must be a positive duration")
+	require.Contains(t, err.Error(), "ssh: checkPeriod -1m0s must be a positive duration")
 }
 
 func TestUnmarshalGrants(t *testing.T) {