feat(tracking): add auth event tracking

cmd/config/init.go

@@ -245,6 +245,9 @@ func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileNa
 func configInitRun(opts *ConfigInitOptions) error {
 	f := opts.Factory
 
+	keychain.SuppressKeychainReadErrorTracking(true)
+	defer keychain.SuppressKeychainReadErrorTracking(false)
+
 	// Read secret from stdin if --app-secret-stdin is set
 	if opts.AppSecretStdin {
 		scanner := bufio.NewScanner(f.IOStreams.In)

cmd/error_auth_hint.go

@@ -4,14 +4,18 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"strings"
+	"time"
 
 	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/tracking"
 	"github.com/larksuite/cli/shortcuts"
 	shortcutcommon "github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
@@ -20,10 +24,14 @@
 // enrichMissingScopeError preserves the original need_user_authorization
 // message and appends a scope hint when the current command declares the
 // required scopes locally.
+// It also logs the auth failure reason using tracking.LogAuthError.
 func enrichMissingScopeError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	if exitErr == nil || exitErr.Detail == nil {
 		return
 	}
+
+	logAuthFailureReason(exitErr)
+
 	if !internalauth.IsNeedUserAuthorizationError(exitErr) {
 		return
 	}
@@ -41,6 +49,97 @@
 	exitErr.Detail.Hint += "\n" + scopeHint
 }
 
+// logSecurityPolicyError logs a security policy error using tracking.LogAuthError.
+func logSecurityPolicyError(spErr *internalauth.SecurityPolicyError) {
+	codeStr := securityPolicyCodeString(spErr.Code)
+	errMsg := fmt.Sprintf("reason=security_policy code=%s message=%q", codeStr, spErr.Message)
+	tracking.LogAuthError(tracking.AuthComponentAuth, tracking.AuthOpSecurityPolicy, fmt.Errorf(errMsg))
+}
+
+// logRawAuthFailure logs auth-related failures for Raw errors (e.g. from `api` command).
+// This preserves the original API error detail while still logging auth failures.
+func logRawAuthFailure(exitErr *output.ExitError) {
+	if exitErr.Detail == nil {
+		return
+	}
+
+	if exitErr.Detail.Type == "permission" {
+		errMsg := fmt.Sprintf("reason=permission_denied code=%d message=%q", exitErr.Detail.Code, exitErr.Detail.Message)
+		tracking.LogAuthError(tracking.AuthComponentAuth, tracking.AuthOpPermissionDenied, fmt.Errorf(errMsg))
+		return
+	}
+
+	if exitErr.Detail.Type == "auth" {
+		errMsg := fmt.Sprintf("reason=auth_error message=%q", exitErr.Detail.Message)
+		tracking.LogAuthError(tracking.AuthComponentAuth, tracking.AuthOpAuthError, fmt.Errorf(errMsg))
+	}
+}
+
+// logAuthFailureReason extracts authorization-related errors from exitErr and logs
+// the failure reason using tracking.LogAuthError.
+func logAuthFailureReason(exitErr *output.ExitError) {
+	if exitErr.Detail == nil {
+		return
+	}
+
+	// Handle NeedAuthorizationError first
+	var needAuthErr *internalauth.NeedAuthorizationError
+	if errors.As(exitErr.Err, &needAuthErr) {
+		errMsg := buildAuthFailureErrorMessage(needAuthErr)
+		tracking.LogAuthError(tracking.AuthComponentAuth, tracking.AuthOpNeedAuthorization, fmt.Errorf(errMsg))
+		return
+	}
+
+	// Handle TokenUnavailableError
+	var unavailableErr *credential.TokenUnavailableError
+	if errors.As(exitErr.Err, &unavailableErr) {
+		errMsg := fmt.Sprintf("reason=no_token source=%s type=%s", unavailableErr.Source, unavailableErr.Type)
+		tracking.LogAuthError(tracking.AuthComponentAuth, tracking.AuthOpTokenUnavailable, fmt.Errorf(errMsg))
+		return
+	}
+
+	// Handle general auth errors (type "auth")
+	if exitErr.Detail.Type == "auth" {
+		errMsg := fmt.Sprintf("reason=auth_error message=%q", exitErr.Detail.Message)
+		tracking.LogAuthError(tracking.AuthComponentAuth, tracking.AuthOpAuthError, fmt.Errorf(errMsg))
+	}
+}
+
+// buildAuthFailureErrorMessage constructs a detailed error message for auth failure logging.
+func buildAuthFailureErrorMessage(err *internalauth.NeedAuthorizationError) string {
+	if err == nil {
+		return "unknown auth failure"
+	}
+
+	var parts []string
+	parts = append(parts, fmt.Sprintf("user=%s", err.UserOpenId))
+
+	switch err.Reason {
+	case internalauth.ReasonNoToken:
+		parts = append(parts, "reason=no_token")
+	case internalauth.ReasonTokenExpired:
+		parts = append(parts, "reason=token_expired")
+	case internalauth.ReasonRefreshExpired:
+		parts = append(parts, "reason=refresh_expired")
+		if err.GrantedAt > 0 {
+			grantedTime := time.UnixMilli(err.GrantedAt).Format(time.RFC3339)
+			parts = append(parts, fmt.Sprintf("refresh_token_granted_at=%s", grantedTime))
+		}
+	case internalauth.ReasonRefreshFailed:
+		parts = append(parts, "reason=refresh_failed")
+		if err.GrantedAt > 0 {
+			grantedTime := time.UnixMilli(err.GrantedAt).Format(time.RFC3339)
+			parts = append(parts, fmt.Sprintf("refresh_token_granted_at=%s", grantedTime))
+		}
+	case internalauth.ReasonPermissionDenied:
+		parts = append(parts, "reason=permission_denied")
+	default:
+		parts = append(parts, fmt.Sprintf("reason=%s", err.Reason))
+	}
+
+	return strings.Join(parts, " ")
+}
+
 // resolveDeclaredScopesForCurrentCommand returns the scopes declared by the
 // current command for the resolved identity, checking shortcuts first and then
 // service methods from local registry metadata.

cmd/root.go

@@ -26,6 +26,7 @@
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/internal/skillscheck"
+	"github.com/larksuite/cli/internal/tracking"
 	"github.com/larksuite/cli/internal/update"
 	"github.com/spf13/cobra"
 )
@@ -207,15 +208,18 @@
 	// that differs from the standard ErrDetail, so it's handled separately.
 	var spErr *internalauth.SecurityPolicyError
 	if errors.As(err, &spErr) {
+		logSecurityPolicyError(spErr)
 		writeSecurityPolicyError(errOut, spErr)
 		return 1
 	}
 
 	// All other structured errors normalize to ExitError.
 	if exitErr := asExitError(err); exitErr != nil {
-		if !exitErr.Raw {
+		if exitErr.Raw {
 			// Raw errors (e.g. from `api` command) preserve the original API
-			// error detail; skip enrichment which would clear it.
+			// error detail; skip enrichment but still log auth failures.
+			logRawAuthFailure(exitErr)
+		} else {
 			enrichMissingScopeError(f, exitErr)
 			enrichPermissionError(f, exitErr)
 		}
@@ -235,27 +239,37 @@
 	if errors.As(err, &cfgErr) {
 		return output.ErrWithHint(cfgErr.Code, cfgErr.Type, cfgErr.Message, cfgErr.Hint)
 	}
+
+	var needAuthErr *internalauth.NeedAuthorizationError
+	if errors.As(err, &needAuthErr) {
+		return output.ErrAuth("authentication required: %s", err)
+	}
+
 	var exitErr *output.ExitError
 	if errors.As(err, &exitErr) {
 		return exitErr
 	}
 	return nil
 }
 
+// securityPolicyCodeString maps a security policy numeric code to a human-readable string.
+func securityPolicyCodeString(code int) string {
+	switch code {
+	case internalauth.LarkErrBlockByPolicyTryAuth:
+		return "challenge_required"
+	case internalauth.LarkErrBlockByPolicy:
+		return "access_denied"
+	default:
+		return strconv.Itoa(code)
+	}
+}
+
 // writeSecurityPolicyError writes the security-policy-specific JSON envelope to w.
 // This format intentionally differs from the standard ErrDetail envelope:
 // it uses string codes ("challenge_required"/"access_denied") and extra fields
 // (retryable, challenge_url) for machine-readable policy error handling.
 func writeSecurityPolicyError(w io.Writer, spErr *internalauth.SecurityPolicyError) {
-	var codeStr string
-	switch spErr.Code {
-	case internalauth.LarkErrBlockByPolicyTryAuth:
-		codeStr = "challenge_required"
-	case internalauth.LarkErrBlockByPolicy:
-		codeStr = "access_denied"
-	default:
-		codeStr = strconv.Itoa(spErr.Code)
-	}
+	codeStr := securityPolicyCodeString(spErr.Code)
 
 	errData := map[string]interface{}{
 		"type":      "auth_error",
@@ -423,6 +437,8 @@
 	isBot := f.ResolvedIdentity.IsBot()
 
 	larkCode := exitErr.Detail.Code
+
+	var reason internalauth.NeedAuthorizationReason
 	switch larkCode {
 	case output.LarkErrUserScopeInsufficient, output.LarkErrUserNotAuthorized:
 		// User has not authorized the scope → re-authorize
@@ -433,12 +449,14 @@
 			exitErr.Detail.Hint = fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", recommended)
 		}
 		exitErr.Detail.ConsoleURL = consoleURL
+		reason = internalauth.ReasonPermissionDenied
 
 	case output.LarkErrAppScopeNotEnabled:
 		// App has not enabled the API scope → admin console
 		exitErr.Detail.Message = fmt.Sprintf("App scope not enabled: required scope %s [%d]", recommended, larkCode)
 		exitErr.Detail.Hint = "enable the scope in developer console (see console_url)"
 		exitErr.Detail.ConsoleURL = consoleURL
+		reason = internalauth.ReasonPermissionDenied
 
 	default:
 		// Other permission errors (matched by keyword)
@@ -450,6 +468,13 @@
 				"enable scope in console (see console_url), or run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", recommended)
 		}
 		exitErr.Detail.ConsoleURL = consoleURL
+		reason = internalauth.ReasonPermissionDenied
+	}
+
+	// Log permission error
+	if reason != "" {
+		errMsg := fmt.Sprintf("user=%s reason=%s scopes=%v", cfg.UserOpenId, reason, scopes)
+		tracking.LogAuthError(tracking.AuthComponentAuth, tracking.AuthOpPermissionDenied, fmt.Errorf(errMsg))
 	}
 }
 

internal/auth/app_registration.go

@@ -66,7 +66,7 @@
 		return nil, err
 	}
 	defer resp.Body.Close()
-	logHTTPResponse(resp)
+	logAuthResponse(responsePath(resp), resp.StatusCode, resp.Header.Get("x-tt-logid"))
 
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
@@ -163,7 +163,7 @@
 			currentInterval = minInt(currentInterval+1, maxPollInterval)
 			continue
 		}
-		logHTTPResponse(resp)
+		logAuthResponse(responsePath(resp), resp.StatusCode, resp.Header.Get("x-tt-logid"))
 
 		body, err := io.ReadAll(resp.Body)
 		resp.Body.Close()

internal/auth/auth_response_log.go

@@ -6,36 +6,28 @@
 import (
 	"net/http"
 
-	"github.com/larksuite/cli/internal/keychain"
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+	"github.com/larksuite/cli/internal/tracking"
 )
 
-// logHTTPResponse logs the HTTP response details for an authentication request.
-// It extracts the request path, status code, and x-tt-logid from the given HTTP response.
-func logHTTPResponse(resp *http.Response) {
-	if resp == nil {
-		return
+func logAuthResponse(path string, statusCode int, logID string) {
+	if path == "" {
+		path = "missing"
 	}
 
-	path := "missing"
-	if resp.Request != nil && resp.Request.URL != nil {
-		path = resp.Request.URL.Path
+	if shouldSkipAuthResponseLog(path, statusCode) {
+		return
 	}
 
-	keychain.LogAuthResponse(path, resp.StatusCode, resp.Header.Get("x-tt-logid"))
+	tracking.LogAuthResponse(path, statusCode, logID)
 }
 
-// logSDKResponse logs the SDK response details for an authentication request.
-// It extracts the status code and x-tt-logid from the given API response object.
-func logSDKResponse(path string, apiResp *larkcore.ApiResp) {
-	if path == "" {
-		path = "missing"
-	}
-
-	if apiResp == nil {
-		keychain.LogAuthResponse(path, 0, "")
-		return
+func responsePath(resp *http.Response) string {
+	if resp != nil && resp.Request != nil && resp.Request.URL != nil {
+		return resp.Request.URL.Path
 	}
+	return "missing"
+}
 
-	keychain.LogAuthResponse(path, apiResp.StatusCode, apiResp.Header.Get("x-tt-logid"))
+func shouldSkipAuthResponseLog(path string, statusCode int) bool {
+	return path == "missing" || statusCode == 400
 }

internal/auth/device_flow.go

@@ -93,7 +93,7 @@
 		return nil, err
 	}
 	defer resp.Body.Close()
-	logHTTPResponse(resp)
+	logAuthResponse(responsePath(resp), resp.StatusCode, resp.Header.Get("x-tt-logid"))
 
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
@@ -184,7 +184,7 @@
 			currentInterval = minInt(currentInterval+1, maxPollInterval)
 			continue
 		}
-		logHTTPResponse(resp)
+		logAuthResponse(responsePath(resp), resp.StatusCode, resp.Header.Get("x-tt-logid"))
 
 		body, err := io.ReadAll(resp.Body)
 		resp.Body.Close()