feat: when a vault refuses, what to check: PIM, the owner, or the network

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

internal/provider/azure/convert.go

@@ -11,6 +11,7 @@ import (
 	"fmt"
 	"math/big"
 	"net/http"
+	"regexp"
 	"strings"
 
 	"github.com/Azure/azure-sdk-for-go/sdk/azcore"
@@ -282,10 +283,17 @@ func cleanError(err error) error {
 	return &serviceError{status: re.StatusCode, msg: shortenDenied(msg), err: err}
 }
 
+var policyDenied = regexp.MustCompile(`does not have (\w+ \w+) permission on key vault`)
+
 // shortenDenied reduces Key Vault's RBAC denial, which runs to several
 // sentences plus caller and resource IDs, to its first sentence and the
 // missing action.
 func shortenDenied(msg string) string {
+	// Access policies: "The user, group or application 'appid=…;oid=…'
+	// does not have secrets list permission on key vault 'kv;location=…'".
+	if m := policyDenied.FindStringSubmatch(msg); m != nil {
+		return "no " + m[1] + " permission in the vault's access policies"
+	}
 	const marker = "Action: '"
 	i := strings.Index(msg, marker)
 	if i < 0 {
@@ -314,7 +322,21 @@ func (e *serviceError) Error() string {
 	if e.msg != "" {
 		s += ": " + e.msg
 	}
+	if e.status == http.StatusForbidden {
+		s += "\n" + deniedHint(e.msg)
+	}
 	return s
 }
 
+// deniedHint is what to check when Key Vault refuses: the network, for
+// its firewall's refusals, else access. On a line of its own, after the
+// message.
+func deniedHint(msg string) string {
+	if strings.Contains(msg, "Client address is not authorized") || strings.Contains(msg, "network access") ||
+		strings.Contains(msg, "private link") {
+		return "Check: are you on a network the vault lets in (VPN, office)? Its firewall limits where it can be reached from."
+	}
+	return "Check: have you activated your role or group in PIM? Has the vault's owner given you access (a Key Vault role, or its access policies)?"
+}
+
 func (e *serviceError) Unwrap() error { return e.err }