feat: add auth error handling

[facundo-herodevs]

Authentication & Authorization Error Handling for CLI

Summary

This PR implements comprehensive authentication and authorization error handling for the CLI, aligning with the eol-api's GraphQL error codes and providing user-friendly error messages.

Key Changes

• API Error Handling: New ApiError class extracts auth error codes from GraphQL extensions.code
• Auth Service Enhancement: New requireAccessTokenForScan() function with automatic token validation
• User-Friendly Messages: Clear error messages with instructions to run hd auth login
• Analytics Tracking: All auth failures tracked with specific error codes via Amplitude

Authentication Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                           CLI SCAN FLOW                                      │
└─────────────────────────────────────────────────────────────────────────────┘

┌──────────────┐
│ User runs    │
│ hd scan eol  │
└──────┬───────┘
       │
       ▼
┌──────────────┐     No      ┌─────────────────────────────────────┐
│ Auth enabled?│────────────▶│ Skip auth, proceed to scan          │
│ (ENABLE_AUTH)│             └─────────────────────────────────────┘
└──────┬───────┘
       │ Yes
       ▼
┌──────────────┐     No      ┌─────────────────────────────────────┐
│ Has access   │────────────▶│ AuthError: NOT_LOGGED_IN            │
│ token?       │             │ "Please log in... run hd auth login"│
└──────┬───────┘             └─────────────────────────────────────┘
       │ Yes
       ▼
┌──────────────┐     No      ┌─────────────────────────────────────┐
│ Token        │────────────▶│ Use existing token                  │
│ expired?     │             └──────────────┬──────────────────────┘
└──────┬───────┘                            │
       │ Yes                                │
       ▼                                    │
┌──────────────┐     No      ┌─────────────────────────────────────┐
│ Has refresh  │────────────▶│ AuthError: SESSION_EXPIRED          │
│ token?       │             │ "Session no longer valid..."        │
└──────┬───────┘             └─────────────────────────────────────┘
       │ Yes
       ▼
┌──────────────┐    Fail     ┌─────────────────────────────────────┐
│ Refresh      │────────────▶│ AuthError: SESSION_EXPIRED          │
│ tokens       │             │ "Session no longer valid..."        │
└──────┬───────┘             └─────────────────────────────────────┘
       │ Success
       ▼
┌──────────────┐
│ Use new      │
│ access token │
└──────┬───────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────────┐
│                     GRAPHQL API REQUEST                           │
│              Authorization: Bearer <access_token>                 │
└──────────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────────┐
│                        API RESPONSE                               │
├──────────────┬───────────────┬───────────────┬───────────────────┤
│   Success    │ SESSION_EXP/  │ UNAUTHENTI-   │    FORBIDDEN      │
│   (data)     │ INVALID_TOKEN │    CATED      │                   │
└──────┬───────┴───────┬───────┴───────┬───────┴───────┬───────────┘
       │               │               │               │
       ▼               ▼               ▼               ▼
┌──────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Display      │ │ "Session no │ │ "Please log │ │ "You do not │
│ scan results │ │  longer     │ │  in to      │ │  have       │
│              │ │  valid..."  │ │  perform a  │ │  permission │
└──────────────┘ │ Run:        │ │  scan..."   │ │  to perform │
                 │ hd auth     │ │ Run:        │ │  this       │
                 │   login     │ │ hd auth     │ │  action."   │
                 └─────────────┘ │   login     │ └─────────────┘
                                 └─────────────┘

Error Handling Summary

GraphQL Error Codes (from eol-api)

Code	CLI Message	Exit Code
SESSION_EXPIRED	"Your session is no longer valid. To re-authenticate, run hd auth login."	1
INVALID_TOKEN	"Your session is no longer valid. To re-authenticate, run hd auth login."	1
UNAUTHENTICATED	"Please log in to perform a scan. To authenticate, run hd auth login."	1
FORBIDDEN	"You do not have permission to perform this action."	1

Local Auth Errors (pre-request validation)

Code	CLI Message	Trigger
NOT_LOGGED_IN	"Please log in to perform a scan. To authenticate, run hd auth login."	No stored tokens
SESSION_EXPIRED	"Your session is no longer valid. To re-authenticate, run hd auth login."	Refresh failed or no refresh token

Backward Compatibility

All changes are guarded behind ENABLE_AUTH environment variable:

• When ENABLE_AUTH=false (default): No auth checks, app behavior unchanged
• When ENABLE_AUTH=true: Full auth flow with token refresh and error handling

Analytics

All auth failures are tracked via Amplitude with:

• command: The CLI command executed
• command_flags: Flags passed to the command
• scan_failure_reason: The specific error code (SESSION_EXPIRED, INVALID_TOKEN, UNAUTHENTICATED, FORBIDDEN)

Related PRs

• eol-report-card: Authentication & Authorization Error Handling (same error codes)
• eol-api: GraphQL error codes in extensions.code

Closes https://github.com/neverendingsupport/data-and-integrations/issues/408