[PPSC-563] feat(auth): remove auth-endpoint flag (#98)

* [PPSC-563] feat(auth): remove auth-endpoint flag and add region support

Simplify CLI authentication by removing the --auth-endpoint flag entirely.
Auth now routes through moose's proxy endpoint automatically, with the base
URL derived from the --dev flag or hardcoded production endpoint.

Changes:
- Replace AuthEndpoint config with BaseURL (derived from getAPIBaseURL)
- Update auth client endpoint from /api/v1/authenticate to /api/v1/auth/token
- Remove --auth-endpoint flag and ARMIS_AUTH_ENDPOINT environment variable
- Add region claim support to JWT parsing for deployment-aware routing
- Rename endpoint → baseURL in NewAuthClient for semantic clarity
- Update error messages to reflect base URL terminology
- Update all tests and documentation

This simplifies the auth flow by removing a user-configurable endpoint,
reducing attack surface and improving UX when configuring authentication.

* fix(auth): check os.Setenv/Unsetenv error returns in tests

* fix(docs): address PR review comments on auth documentation

- Update NewAuthProvider comment to say "base URL" instead of "endpoint"
- Document ARMIS_API_URL in FEATURES.md and CLAUDE.md env var sections

* feat(auth): add region caching with retry and shared cache utility

Add region caching to optimize JWT authentication by persisting the
discovered region to disk and reusing it on subsequent CLI invocations.

Key changes:
- Add --region flag for explicit region override (bypasses auto-discovery)
- Implement file-based region cache (~/.cache/armis-cli/region-cache.json)
- Add automatic retry without region hint when cached region auth fails
- Memoize cached region in AuthProvider to avoid repeated disk I/O
- Extract shared cache directory utility (util.GetCacheDir/GetCacheFilePath)
- Add comprehensive tests for region cache (client ID mismatch, corrupt
  JSON, permissions, etc.)

Region selection priority:
1. --region flag - explicit override
2. Cached region - from previous successful auth
3. Auto-discovery - server tries regions until one succeeds

Addresses review findings:
- F1: No tests for region cache → 249 lines of tests added
- F2: No retry on stale cache → Retry logic with usingCachedHint flag
- F3: Redundant writes → Skip if region unchanged
- F4: Repeated disk I/O → Memoization via cachedRegion/regionLoaded
- F5: Duplicated cache constant → Extracted to util.CacheDirName

* fix(test): make cache tests Windows-compatible

- Skip file permissions test on Windows (Unix permissions not supported)
- Use filepath.Join for platform-agnostic path separators in test assertions

* fix(util): prevent path traversal in GetCacheFilePath (CWE-22)

Address PR review comments from Copilot:

- Reject absolute paths and path separators in cache filename parameter
  to prevent filepath.Join from discarding the cache directory
- Add containment check to ensure result stays within cache directory
- Fix incorrect test assumptions about filepath.Join behavior
- Use temp directory in TestPackageLevelFunctions to avoid modifying
  real user cache during tests
- Document ARMIS_REGION environment variable in FEATURES.md and CLAUDE.md

* fix(util): harden cache path validation and add region retry test

Address follow-up PR review comments:

- Reject empty, whitespace-only, ".", and ".." filenames in GetCacheFilePath
  to prevent returning directory path instead of file path
- Replace strings.HasPrefix with filepath.Rel for robust path containment
  check (handles case-insensitivity and path separator edge cases)
- Add TestAuthProvider_CachedRegionRetryOnFailure to cover region-caching
  retry logic when auth fails with stale cached region
- Fix CLAUDE.md: ARMIS_REGION is for region-aware authentication,
  not API URL selection

* fix(auth): add Bearer prefix to JWT Authorization header

The CLI was sending raw JWT tokens without the "Bearer" prefix,
but the backend middleware expects "Authorization: Bearer <token>"
per RFC 6750. This caused 401 errors when using JWT authentication.

Changes:
- auth.go: Return "Bearer " + token for JWT auth
- client.go: Update comments to match actual behavior
- auth_test.go: Update tests to expect Bearer prefix

* fix(auth): address PR review comments for region cache and retry logic

- Fix test containment assertion to use filepath.Rel instead of
  strings.HasPrefix for robust path-boundary checking
- Bound RegionCache.Load file reads with 4KB size limit to prevent
  memory exhaustion from corrupted cache files
- Add typed AuthError with HTTP status code to enable selective retry:
  only retry on region-specific rejections (not 401/transport errors)
- Add deprecation warning when ARMIS_AUTH_ENDPOINT env var is set,
  directing users to ARMIS_API_URL or --region
- Update CI docs to recommend JWT auth credentials

Author: yiftach-armis

CLAUDE.md

@@ -43,7 +43,7 @@ go test -v ./internal/output/... -run TestHumanFormatter
 
 ### Core Packages
 
-- `internal/auth/` - Authentication provider supporting two modes. JWT (priority): client credentials exchange at `/api/v1/authenticate`, auto-refresh 5min before expiry, tenant ID extracted from `customer_id` JWT claim. Basic (fallback): static token + explicit tenant ID. Implements `AuthHeaderProvider` interface used by the API client.
+- `internal/auth/` - Authentication provider supporting two modes. JWT (priority): client credentials exchange at `/api/v1/auth/token`, auto-refresh 5min before expiry, tenant ID extracted from `customer_id` JWT claim. Basic (fallback): static token + explicit tenant ID. Implements `AuthHeaderProvider` interface used by the API client.
 - `internal/api/` - API client for Armis Cloud. Two HTTP clients: one for general calls (60s timeout), one for uploads (streaming, no timeout, no retry). Functional options pattern (`WithHTTPClient()`, `WithUploadHTTPClient()`, `WithAllowLocalURLs()`). Upload uses `io.Pipe` streaming to avoid OOM on large files. Enforces HTTPS, validates presigned S3 URLs against SSRF.
 - `internal/model/` - Data structures: `Finding` (23 fields), `ScanResult`, `Summary`, `Fix`, `FindingValidation` (with taint/reachability analysis), API response types (`NormalizedFinding`, pagination).
 - `internal/output/` - Output formatters (human, json, sarif, junit) implementing the `Formatter` interface. `styles.go` defines ~50 lipgloss styles using Tailwind CSS color palette. `icons.go` defines Unicode constants (severity dots, box-drawing chars). `SyncColors()` switches between full-color and plain styles based on `cli.ColorsEnabled()`.
@@ -83,9 +83,10 @@ go test -v ./internal/output/... -run TestHumanFormatter
 
 - `ARMIS_CLIENT_ID` - Client ID for JWT authentication (recommended)
 - `ARMIS_CLIENT_SECRET` - Client secret for JWT authentication
-- `ARMIS_AUTH_ENDPOINT` - JWT authentication service endpoint URL
 - `ARMIS_API_TOKEN` - API token for Basic authentication (fallback)
 - `ARMIS_TENANT_ID` - Tenant identifier (required only with Basic auth; JWT extracts it from token)
+- `ARMIS_API_URL` - Override base URL for Armis API (advanced; defaults based on --dev flag)
+- `ARMIS_REGION` - Override Armis cloud region (equivalent to `--region`; used for region-aware authentication)
 - `ARMIS_FORMAT` - Default output format
 - `ARMIS_PAGE_LIMIT` - Results pagination size
 - `ARMIS_THEME` - Terminal background theme: auto, dark, light (default: auto)

docs/CI-INTEGRATION.md

@@ -697,7 +697,7 @@ Configure `ARMIS_API_TOKEN` and `ARMIS_TENANT_ID` as [secured repository variabl
 #### "authentication required"
 
 - No valid authentication credentials were provided
-- Set `ARMIS_API_TOKEN` and `ARMIS_TENANT_ID` environment variables or secrets
+- Set `ARMIS_CLIENT_ID` and `ARMIS_CLIENT_SECRET` for JWT auth (recommended), or `ARMIS_API_TOKEN` and `ARMIS_TENANT_ID` for legacy auth
 
 #### "tenant ID required"
 

docs/FEATURES.md

@@ -294,9 +294,10 @@ armis-cli scan repo . \
 |----------|-------------|
 | `ARMIS_CLIENT_ID` | Client ID for JWT authentication |
 | `ARMIS_CLIENT_SECRET` | Client secret for JWT authentication |
-| `ARMIS_AUTH_ENDPOINT` | Authentication service endpoint URL |
 | `ARMIS_API_TOKEN` | API token for Basic authentication |
 | `ARMIS_TENANT_ID` | Tenant identifier (required for Basic auth only) |
+| `ARMIS_API_URL` | Override base URL for Armis API and authentication (advanced) |
+| `ARMIS_REGION` | Authentication region override (advanced; corresponds to `--region` flag) |
 
 **General:**
 

internal/api/client.go

@@ -216,12 +216,9 @@ func (c *Client) IsDebug() bool {
 // request URL uses HTTPS (or localhost for testing). This prevents credential
 // exposure over insecure channels.
 //
-// For JWT auth: sends raw JWT token (no "Bearer" prefix)
+// For JWT auth: sends "Bearer <token>" per RFC 6750
 // For Basic auth: sends "Basic <token>" per RFC 7617
 //
-// NOTE: The backend expects raw JWT tokens without the "Bearer" prefix.
-// This is unconventional but matches the backend API contract.
-//
 // SECURITY NOTE: The localhost/127.0.0.1 exception is intentional for local
 // development and testing environments where HTTPS certificates are not available.
 // Production deployments must always use HTTPS.

internal/auth/auth.go

@@ -7,7 +7,9 @@ import (
 	"context"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"fmt"
+	"net/http"
 	"strings"
 	"sync"
 	"time"
@@ -18,7 +20,8 @@ type AuthConfig struct {
 	// JWT auth credentials
 	ClientID     string
 	ClientSecret string //nolint:gosec // G117: This is a config field name, not a secret value
-	AuthEndpoint string // Full URL to the authentication service
+	BaseURL      string // Moose API base URL (dev or prod)
+	Region       string // Optional region override - bypasses auto-discovery if set
 
 	// Legacy Basic auth
 	Token    string
@@ -33,21 +36,24 @@ type JWTCredentials struct {
 	Token     string
 	TenantID  string // Extracted from customer_id claim
 	ExpiresAt time.Time
+	Region    string // Deployment region (e.g., "us1", "eu1", "au1")
 }
 
 // AuthProvider manages authentication tokens with automatic refresh.
 // It supports both JWT authentication and legacy Basic authentication.
 // For JWT auth, tokens are automatically refreshed when within 5 minutes of expiry.
 type AuthProvider struct {
-	config      AuthConfig
-	credentials *JWTCredentials
-	authClient  *AuthClient
-	mu          sync.RWMutex
-	isLegacy    bool // true if using Basic auth (--token)
+	config       AuthConfig
+	credentials  *JWTCredentials
+	authClient   *AuthClient
+	mu           sync.RWMutex
+	isLegacy     bool   // true if using Basic auth (--token)
+	cachedRegion string // memoized region from disk cache (loaded once)
+	regionLoaded bool   // true if cachedRegion has been loaded from disk
 }
 
 // NewAuthProvider creates an AuthProvider from configuration.
-// If ClientID and ClientSecret are set, uses JWT auth with the specified endpoint.
+// If ClientID and ClientSecret are set, uses JWT auth with the specified base URL.
 // Otherwise falls back to legacy Basic auth with Token.
 func NewAuthProvider(config AuthConfig) (*AuthProvider, error) {
 	p := &AuthProvider{
@@ -64,12 +70,12 @@ func NewAuthProvider(config AuthConfig) (*AuthProvider, error) {
 
 	// Determine auth mode: JWT credentials take priority
 	if config.ClientID != "" && config.ClientSecret != "" {
-		// JWT auth
+		// JWT auth via moose
 		p.isLegacy = false
-		if config.AuthEndpoint == "" {
-			return nil, fmt.Errorf("--auth-endpoint is required when using client credentials")
+		if config.BaseURL == "" {
+			return nil, fmt.Errorf("base URL is required for JWT authentication")
 		}
-		authClient, err := NewAuthClient(config.AuthEndpoint, config.Debug)
+		authClient, err := NewAuthClient(config.BaseURL, config.Debug)
 		if err != nil {
 			return nil, fmt.Errorf("failed to create auth client: %w", err)
 		}
@@ -86,14 +92,14 @@ func NewAuthProvider(config AuthConfig) (*AuthProvider, error) {
 			return nil, fmt.Errorf("tenant ID required: use --tenant-id flag or ARMIS_TENANT_ID environment variable")
 		}
 	} else {
-		return nil, fmt.Errorf("authentication required: use --token flag or ARMIS_API_TOKEN environment variable")
+		return nil, fmt.Errorf("authentication required: set ARMIS_CLIENT_ID and ARMIS_CLIENT_SECRET for JWT auth, or ARMIS_API_TOKEN for legacy auth")
 	}
 
 	return p, nil
 }
 
 // GetAuthorizationHeader returns the Authorization header value.
-// For JWT auth: the raw JWT token (no "Bearer" prefix - backend expects raw JWT)
+// For JWT auth: "Bearer <token>" per RFC 6750
 // For Basic auth: "Basic <token>" per RFC 7617
 func (p *AuthProvider) GetAuthorizationHeader(ctx context.Context) (string, error) {
 	if p.isLegacy {
@@ -108,8 +114,8 @@ func (p *AuthProvider) GetAuthorizationHeader(ctx context.Context) (string, erro
 
 	p.mu.RLock()
 	defer p.mu.RUnlock()
-	// Raw JWT token (no Bearer prefix) - backend expects raw JWT per API contract
-	return p.credentials.Token, nil
+	// Bearer token per RFC 6750
+	return "Bearer " + p.credentials.Token, nil
 }
 
 // GetTenantID returns the tenant ID for API requests.
@@ -129,6 +135,23 @@ func (p *AuthProvider) GetTenantID(ctx context.Context) (string, error) {
 	return p.credentials.TenantID, nil
 }
 
+// GetRegion returns the deployment region from the JWT token.
+// For JWT auth: extracted from region claim (may be empty for older tokens)
+// For Basic auth: returns empty string (no region available)
+func (p *AuthProvider) GetRegion(ctx context.Context) (string, error) {
+	if p.isLegacy {
+		return "", nil // Legacy auth doesn't have region
+	}
+
+	if err := p.refreshIfNeeded(ctx); err != nil {
+		return "", fmt.Errorf("failed to refresh token: %w", err)
+	}
+
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return p.credentials.Region, nil
+}
+
 // IsLegacy returns true if using legacy Basic auth.
 func (p *AuthProvider) IsLegacy() bool {
 	return p.isLegacy
@@ -160,6 +183,16 @@ func (p *AuthProvider) GetRawToken(ctx context.Context) (string, error) {
 
 // exchangeCredentials exchanges client credentials for a JWT token.
 // Uses double-checked locking to prevent thundering herd of concurrent refreshes.
+// Leverages region caching to avoid auto-discovery overhead on subsequent requests.
+//
+// Region selection priority:
+//  1. --region flag (config.Region) - explicit override, bypasses cache and discovery
+//  2. Cached region - from previous successful auth for this client_id
+//  3. Auto-discovery - server tries regions until one succeeds
+//
+// Retry behavior: If auth fails with a cached region hint (not explicit --region),
+// the cache is cleared and auth is retried without the hint. This handles stale
+// cache gracefully without requiring user to re-run the command.
 func (p *AuthProvider) exchangeCredentials(ctx context.Context) error {
 	p.mu.Lock()
 	defer p.mu.Unlock()
@@ -169,21 +202,62 @@ func (p *AuthProvider) exchangeCredentials(ctx context.Context) error {
 		return nil
 	}
 
-	token, err := p.authClient.Authenticate(ctx, p.config.ClientID, p.config.ClientSecret)
+	// Load cached region once per process (memoize to avoid repeated disk I/O)
+	if !p.regionLoaded {
+		if region, ok := loadCachedRegion(p.config.ClientID); ok {
+			p.cachedRegion = region
+		}
+		p.regionLoaded = true
+	}
+
+	// Determine region hint - explicit flag takes priority over cache
+	var regionHint *string
+	var usingCachedHint bool
+	if p.config.Region != "" {
+		// Explicit --region flag - don't retry on failure (user error)
+		regionHint = &p.config.Region
+	} else if p.cachedRegion != "" {
+		// Cached region - will retry without hint on failure
+		regionHint = &p.cachedRegion
+		usingCachedHint = true
+	}
+
+	result, err := p.authClient.Authenticate(ctx, p.config.ClientID, p.config.ClientSecret, regionHint)
 	if err != nil {
-		return err
+		// If auth failed with a cached region hint, retry only for region-specific rejections.
+		// Skip retry for: transport errors (not *AuthError), 401 (bad credentials).
+		// This avoids double requests on network failures and prevents wiping correct cache entries.
+		var authErr *AuthError
+		if usingCachedHint && errors.As(err, &authErr) && authErr.StatusCode != http.StatusUnauthorized {
+			clearCachedRegion()
+			p.cachedRegion = ""
+			// Retry without region hint - let server auto-discover
+			result, err = p.authClient.Authenticate(ctx, p.config.ClientID, p.config.ClientSecret, nil)
+			if err != nil {
+				return err
+			}
+		} else {
+			return err
+		}
+	}
+
+	// Cache the discovered region for future requests (skip if unchanged)
+	if result.Region != "" && result.Region != p.cachedRegion {
+		saveCachedRegion(p.config.ClientID, result.Region)
+		p.cachedRegion = result.Region
 	}
 
 	// Parse JWT to extract claims
-	claims, err := parseJWTClaims(token)
+	claims, err := parseJWTClaims(result.Token)
 	if err != nil {
 		return fmt.Errorf("failed to parse JWT: %w", err)
 	}
 
 	p.credentials = &JWTCredentials{
-		Token:     token,
+		Token:     result.Token,
 		TenantID:  claims.CustomerID,
 		ExpiresAt: claims.ExpiresAt,
+		Region:    claims.Region,
 	}
 
 	return nil
@@ -207,6 +281,7 @@ func (p *AuthProvider) refreshIfNeeded(ctx context.Context) error {
 type jwtClaims struct {
 	CustomerID string // maps to tenant_id
 	ExpiresAt  time.Time
+	Region     string // deployment region (optional)
 }
 
 // parseJWTClaims extracts claims from a JWT without signature verification.
@@ -233,7 +308,8 @@ func parseJWTClaims(token string) (*jwtClaims, error) {
 
 	var data struct {
 		CustomerID string  `json:"customer_id"`
-		Exp        float64 `json:"exp"` // float64 to handle servers that return fractional timestamps
+		Exp        float64 `json:"exp"`    // float64 to handle servers that return fractional timestamps
+		Region     string  `json:"region"` // optional deployment region
 	}
 	if err := json.Unmarshal(payload, &data); err != nil {
 		return nil, fmt.Errorf("failed to parse JWT payload: %w", err)
@@ -252,5 +328,6 @@ func parseJWTClaims(token string) (*jwtClaims, error) {
 	return &jwtClaims{
 		CustomerID: data.CustomerID,
 		ExpiresAt:  time.Unix(expSec, 0),
+		Region:     data.Region, // may be empty for backward compatibility
 	}, nil
 }