[GH-ISSUE #273] Auth: Add auth doctor command for diagnosing configuration issues #89

New issue

Closed

opened 2026-02-26 21:33:18 +03:00 by kerem · 1 comment

kerem commented

2026-02-26 21:33:18 +03:00

Owner

Originally created by @rudrankriyam on GitHub (Jan 28, 2026).
Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/273

Problem

When users encounter authentication issues, debugging requires understanding multiple interacting systems: keychain availability, config file state, environment variables, file permissions, and credential validity. Users often struggle to identify the root cause because there is no single command that provides a comprehensive diagnostic view of the authentication configuration.

Proposed Solution

Add a new auth doctor subcommand that performs a comprehensive health check of the authentication configuration, similar to brew doctor or flutter doctor.

Command signature:

asc auth doctor [--fix]

The command should check:

Storage backend status
- Is system keychain available?
- Is config file present and readable?
- Config file permissions check
Credential inventory
- List all configured profiles
- Check for incomplete profiles (missing key ID, issuer ID, or key path)
- Check for duplicate profiles
Private key health
- Do referenced key files exist?
- Are key file permissions secure (0600)?
- Can keys be parsed as valid PEM?
- Are keys the correct type (ECDSA P-256)?
Environment variable status
- Which ASC_* environment variables are set?
- Do environment variables conflict with stored credentials?
Potential issues
- Credentials in config file when keychain is available (less secure)
- Key files with overly permissive permissions
- Orphaned temp key files in /tmp

Example output:

Auth Doctor

Storage:
  [OK] System keychain is available
  [OK] Config file exists at ~/.asc/config.json
  [WARN] Config file contains credentials (consider migrating to keychain)

Profiles:
  [OK] default - complete
  [OK] work - complete
  [WARN] staging - missing private key path

Private Keys:
  [OK] /path/to/default.p8 - valid ECDSA key, permissions 0600
  [OK] /path/to/work.p8 - valid ECDSA key, permissions 0600
  [FAIL] /path/to/staging.p8 - file not found

Environment:
  [INFO] ASC_KEY_ID is set
  [WARN] ASC_KEY_ID conflicts with default profile key ID

Recommendations:
  1. Set private key path for staging profile: asc auth login --profile staging
  2. Consider clearing ASC_KEY_ID or using --profile to avoid conflicts
  3. Run 'asc auth migrate' to move config credentials to keychain

Found 2 warnings and 1 error.

With --fix flag, automatically fix issues where possible:

Fix file permissions on key files
Remove orphaned temp files
Migrate credentials from config to keychain

Implementation Location

cmd/auth.go - Add the new doctor subcommand
internal/auth/doctor.go (new file) - Diagnostic check logic

Acceptance Criteria

auth doctor performs all documented checks
Clear output with OK/WARN/FAIL indicators
Actionable recommendations for each issue found
--fix flag auto-repairs fixable issues with user confirmation
Returns non-zero exit code if errors are found
Add tests for each diagnostic check

Originally created by @rudrankriyam on GitHub (Jan 28, 2026). Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/273 ## Problem When users encounter authentication issues, debugging requires understanding multiple interacting systems: keychain availability, config file state, environment variables, file permissions, and credential validity. Users often struggle to identify the root cause because there is no single command that provides a comprehensive diagnostic view of the authentication configuration. ## Proposed Solution Add a new `auth doctor` subcommand that performs a comprehensive health check of the authentication configuration, similar to `brew doctor` or `flutter doctor`. Command signature: ``` asc auth doctor [--fix] ``` The command should check: 1. Storage backend status - Is system keychain available? - Is config file present and readable? - Config file permissions check 2. Credential inventory - List all configured profiles - Check for incomplete profiles (missing key ID, issuer ID, or key path) - Check for duplicate profiles 3. Private key health - Do referenced key files exist? - Are key file permissions secure (0600)? - Can keys be parsed as valid PEM? - Are keys the correct type (ECDSA P-256)? 4. Environment variable status - Which ASC_* environment variables are set? - Do environment variables conflict with stored credentials? 5. Potential issues - Credentials in config file when keychain is available (less secure) - Key files with overly permissive permissions - Orphaned temp key files in /tmp Example output: ``` Auth Doctor Storage: [OK] System keychain is available [OK] Config file exists at ~/.asc/config.json [WARN] Config file contains credentials (consider migrating to keychain) Profiles: [OK] default - complete [OK] work - complete [WARN] staging - missing private key path Private Keys: [OK] /path/to/default.p8 - valid ECDSA key, permissions 0600 [OK] /path/to/work.p8 - valid ECDSA key, permissions 0600 [FAIL] /path/to/staging.p8 - file not found Environment: [INFO] ASC_KEY_ID is set [WARN] ASC_KEY_ID conflicts with default profile key ID Recommendations: 1. Set private key path for staging profile: asc auth login --profile staging 2. Consider clearing ASC_KEY_ID or using --profile to avoid conflicts 3. Run 'asc auth migrate' to move config credentials to keychain Found 2 warnings and 1 error. ``` With `--fix` flag, automatically fix issues where possible: - Fix file permissions on key files - Remove orphaned temp files - Migrate credentials from config to keychain ## Implementation Location - `cmd/auth.go` - Add the new doctor subcommand - `internal/auth/doctor.go` (new file) - Diagnostic check logic ## Acceptance Criteria - `auth doctor` performs all documented checks - Clear output with OK/WARN/FAIL indicators - Actionable recommendations for each issue found - `--fix` flag auto-repairs fixable issues with user confirmation - Returns non-zero exit code if errors are found - Add tests for each diagnostic check