feat: add credential cache management with --clear-cache command

- Added --clear-cache flag to credential-process for clearing stored credentials
- Implemented smart clearing that replaces credentials with expired dummies to avoid macOS keychain permission prompts
- Enhanced OTEL helper to use credential-process, preventing direct keychain access
- Fixed OTEL helper to fail cleanly instead of returning default user attributes
- Added automatic credential clearing on authentication failures
- Updated documentation with troubleshooting guidance

This feature enables users to easily clear cached credentials when switching
accounts or resolving authentication issues, while maintaining a smooth
experience without repeated OS permission prompts.

Author: schuettc

README.md

@@ -324,6 +324,18 @@ The optional CloudWatch dashboard provides:
 - **Performance Metrics**: Response times and error rates
 - **User Activity**: Active users and authentication patterns
 
+## Troubleshooting
+
+### Clearing Cached Credentials
+
+To force re-authentication:
+
+```bash
+~/claude-code-with-bedrock/credential-process --clear-cache
+```
+
+Note: This replaces credentials with expired dummies rather than deleting them, which prevents macOS from repeatedly asking for keychain permissions.
+
 ## CLI Commands
 
 The guidance includes a comprehensive CLI tool (`ccwb`) for deployment and management:

assets/docs/LOCAL_TESTING.md

@@ -78,8 +78,8 @@ Understanding how authentication works helps you support users effectively. The
 To force a fresh authentication and observe the complete flow:
 
 ```bash
-# Clear any cached credentials
-rm -rf ~/claude-code-with-bedrock/cache/*
+# Clear any cached credentials (this replaces them with expired dummies to preserve keychain permissions)
+~/claude-code-with-bedrock/credential-process --clear-cache
 
 # Trigger authentication
 aws sts get-caller-identity --profile ClaudeCode
@@ -167,3 +167,27 @@ claude
 ```
 
 Claude Code automatically uses the AWS profile for authentication. Behind the scenes, it calls the credential process whenever it needs to access Bedrock, with all authentication handled transparently.
+
+### Important: AWS Credential Precedence
+
+When testing, be aware that AWS CLI uses the following credential precedence order:
+
+1. **Environment variables** (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`) - highest priority
+2. Command line options
+3. Environment variable `AWS_PROFILE`
+4. Credential process from AWS config
+5. Config file credentials
+6. Instance metadata
+
+If you have AWS credentials in environment variables (e.g., from other tools like Isengard), they will override the ClaudeCode profile. To ensure you're using the Claude Code authentication:
+
+```bash
+# Clear any existing AWS credentials from environment
+unset AWS_ACCESS_KEY_ID
+unset AWS_SECRET_ACCESS_KEY
+unset AWS_SESSION_TOKEN
+
+# Then use the ClaudeCode profile
+export AWS_PROFILE=ClaudeCode
+aws sts get-caller-identity
+```

source/claude_code_with_bedrock/cli/commands/cleanup.py

@@ -5,6 +5,7 @@
 
 import os
 import shutil
+import subprocess
 from pathlib import Path
 from cleo.commands.command import Command
 from cleo.helpers import option
@@ -28,13 +29,26 @@ class CleanupCommand(Command):
             description="AWS profile name to remove (default: ClaudeCode)",
             flag=False,
             default="ClaudeCode"
+        ),
+        option(
+            "credentials-only",
+            description="Only clear cached credentials without removing other components",
+            flag=True
         )
     ]
 
     def handle(self) -> int:
         """Execute the cleanup command."""
         console = Console()
 
+        profile_name = self.option("profile")
+        force = self.option("force")
+        credentials_only = self.option("credentials-only")
+        
+        # Handle credentials-only mode
+        if credentials_only:
+            return self._clear_credentials_only(console, profile_name, force)
+        
         # Show what will be cleaned
         console.print(Panel.fit(
             "[bold yellow]Authentication Cleanup[/bold yellow]\n\n"
@@ -43,9 +57,6 @@ def handle(self) -> int:
             padding=(1, 2)
         ))
 
-        profile_name = self.option("profile")
-        force = self.option("force")
-        
         # List items to be removed
         items_to_remove = []
 
@@ -152,4 +163,61 @@ def handle(self) -> int:
         console.print("• Run 'ccwb package' to create a new distribution")
         console.print("• Run 'ccwb test' to reinstall and test")
 
+        return 0
+    
+    def _clear_credentials_only(self, console, profile_name, force):
+        """Clear only cached credentials without removing other components."""
+        console.print(Panel.fit(
+            "[bold cyan]Clear Cached Credentials[/bold cyan]\n\n"
+            f"This will clear cached credentials for profile: {profile_name}",
+            border_style="cyan",
+            padding=(1, 2)
+        ))
+        
+        # Check if credential-process exists
+        credential_process = Path.home() / "claude-code-with-bedrock" / "credential-process"
+        
+        if not credential_process.exists():
+            console.print("[yellow]Credential process not found. Nothing to clear.[/yellow]")
+            return 0
+        
+        # Confirm clearing
+        if not force:
+            if not Confirm.ask("\n[bold yellow]Clear cached credentials?[/bold yellow]"):
+                console.print("\n[yellow]Operation cancelled.[/yellow]")
+                return 0
+        
+        # Run the credential process with --clear-cache flag
+        console.print("\n[bold]Clearing cached credentials...[/bold]")
+        
+        try:
+            result = subprocess.run(
+                [str(credential_process), "--profile", profile_name, "--clear-cache"],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            
+            if result.returncode == 0:
+                if result.stderr:
+                    # Parse the output to show what was cleared
+                    for line in result.stderr.split('\n'):
+                        if line.strip():
+                            console.print(f"  {line}")
+                console.print("\n[green]✓ Cached credentials cleared successfully![/green]")
+            else:
+                console.print(f"[red]Failed to clear credentials: {result.stderr}[/red]")
+                return 1
+                
+        except subprocess.TimeoutExpired:
+            console.print("[red]Operation timed out[/red]")
+            return 1
+        except Exception as e:
+            console.print(f"[red]Error clearing credentials: {e}[/red]")
+            return 1
+        
+        console.print("\n[bold]Next steps:[/bold]")
+        console.print("• The next AWS command will trigger re-authentication")
+        console.print("• Use 'export AWS_PROFILE=ClaudeCode' to set the profile")
+        
         return 0

source/claude_code_with_bedrock/cli/commands/package.py

@@ -727,6 +727,8 @@ def _create_installer(self, output_dir: Path, profile, built_executables, built_
 echo "  export AWS_PROFILE=ClaudeCode"
 echo "  aws sts get-caller-identity"
 echo
+echo "Note: Authentication will automatically open your browser when needed."
+echo
 '''
 
         installer_path = output_dir / "install.sh"
@@ -776,6 +778,20 @@ def _create_documentation(self, output_dir: Path, profile, timestamp: str):
 - Check that port 8400 is available for the callback
 - Contact your IT administrator for help
 
+### Authentication Behavior
+
+The system handles authentication automatically:
+- Your browser will open when authentication is needed
+- Credentials are cached securely to avoid repeated logins
+- Bad credentials are automatically cleared and re-authenticated
+
+To manually clear cached credentials (if needed):
+```bash
+~/claude-code-with-bedrock/credential-process --clear-cache
+```
+
+This will force re-authentication on your next AWS command.
+
 ### Browser doesn't open
 Check that you're not in an SSH session. The browser needs to open on your local machine.
 

source/cognito_auth/__main__.py

@@ -193,8 +193,14 @@ def get_cached_credentials(self):
                     return None
 
                 creds = json.loads(creds_json)
+                
+                # Check for dummy/cleared credentials first
+                # These are set when credentials are cleared to maintain keychain permissions
+                if creds.get("AccessKeyId") == "EXPIRED":
+                    self._debug_print("Found cleared dummy credentials, need re-authentication")
+                    return None
 
-                # Validate expiration
+                # Validate expiration for real credentials
                 exp_str = creds.get("Expiration")
                 if exp_str:
                     exp_time = datetime.fromisoformat(exp_str.replace("Z", "+00:00"))
@@ -220,8 +226,13 @@ def get_cached_credentials(self):
             try:
                 with open(session_file, "r") as f:
                     creds = json.load(f)
+                
+                # Check for dummy/cleared credentials first
+                if creds.get("AccessKeyId") == "EXPIRED":
+                    self._debug_print("Found cleared dummy credentials in session file, need re-authentication")
+                    return None
 
-                # Validate expiration
+                # Validate expiration for real credentials
                 exp_str = creds.get("Expiration")
                 if exp_str:
                     exp_time = datetime.fromisoformat(exp_str.replace("Z", "+00:00"))
@@ -260,6 +271,66 @@ def save_credentials(self, credentials):
 
             # Set restrictive permissions
             session_file.chmod(0o600)
+    
+    def clear_cached_credentials(self):
+        """Clear all cached credentials for this profile"""
+        cleared_items = []
+        
+        # Clear from keyring by replacing with expired credentials
+        # This maintains keychain access permissions on macOS
+        try:
+            if keyring.get_password("claude-code-with-bedrock", f"{self.profile}-credentials"):
+                # Replace with expired dummy credential instead of deleting
+                # This prevents macOS from asking for "Always Allow" again
+                expired_credential = json.dumps({
+                    "Version": 1,
+                    "AccessKeyId": "EXPIRED",
+                    "SecretAccessKey": "EXPIRED",
+                    "SessionToken": "EXPIRED",
+                    "Expiration": "2000-01-01T00:00:00Z"  # Far past date
+                })
+                keyring.set_password("claude-code-with-bedrock", f"{self.profile}-credentials", expired_credential)
+                cleared_items.append("keyring credentials")
+        except Exception as e:
+            self._debug_print(f"Could not clear keyring credentials: {e}")
+        
+        # Clear monitoring token from keyring  
+        try:
+            if keyring.get_password("claude-code-with-bedrock", f"{self.profile}-monitoring"):
+                # Replace with expired dummy token
+                expired_token = json.dumps({
+                    "token": "EXPIRED",
+                    "expires": 0,  # Expired timestamp
+                    "email": "",
+                    "profile": self.profile
+                })
+                keyring.set_password("claude-code-with-bedrock", f"{self.profile}-monitoring", expired_token)
+                cleared_items.append("keyring monitoring token")
+        except Exception as e:
+            self._debug_print(f"Could not clear keyring monitoring token: {e}")
+        
+        # Clear session files
+        session_dir = Path.home() / ".claude-code-session"
+        if session_dir.exists():
+            session_file = session_dir / f"{self.profile}-session.json"
+            monitoring_file = session_dir / f"{self.profile}-monitoring.json"
+            
+            if session_file.exists():
+                session_file.unlink()
+                cleared_items.append("session file")
+            
+            if monitoring_file.exists():
+                monitoring_file.unlink()
+                cleared_items.append("monitoring token file")
+            
+            # Remove directory if empty
+            try:
+                if not any(session_dir.iterdir()):
+                    session_dir.rmdir()
+            except Exception:
+                pass
+        
+        return cleared_items
 
     def save_monitoring_token(self, id_token, token_claims):
         """Save ID token for monitoring authentication"""
@@ -620,6 +691,23 @@ def get_aws_credentials(self, id_token, token_claims):
             return formatted_creds
 
         except Exception as e:
+            # Check if this is a credential error that suggests bad cached credentials
+            error_str = str(e)
+            if any(err in error_str for err in [
+                "InvalidParameterException",
+                "NotAuthorizedException", 
+                "ValidationError",
+                "Invalid AccessKeyId",
+                "Token is not from a supported provider"
+            ]):
+                self._debug_print("Detected invalid credentials, clearing cache...")
+                self.clear_cached_credentials()
+                # Add helpful message for user
+                raise Exception(
+                    f"Authentication failed - cached credentials were invalid and have been cleared.\n"
+                    f"Please try again to re-authenticate.\n"
+                    f"Original error: {error_str}"
+                )
             raise Exception(f"Failed to get AWS credentials: {str(e)}")
 
     def _wait_for_auth_completion(self, timeout=60):
@@ -752,19 +840,49 @@ def main():
     parser.add_argument(
         "--get-monitoring-token", action="store_true", help="Get cached monitoring token instead of AWS credentials"
     )
+    parser.add_argument(
+        "--clear-cache", action="store_true", help="Clear cached credentials and force re-authentication"
+    )
 
     args = parser.parse_args()
 
     auth = MultiProviderAuth(profile=args.profile)
 
+    # Handle cache clearing request
+    if args.clear_cache:
+        cleared = auth.clear_cached_credentials()
+        if cleared:
+            print(f"Cleared cached credentials for profile '{args.profile}':", file=sys.stderr)
+            for item in cleared:
+                print(f"  • {item}", file=sys.stderr)
+        else:
+            print(f"No cached credentials found for profile '{args.profile}'", file=sys.stderr)
+        sys.exit(0)
+
     # Handle monitoring token request
     if args.get_monitoring_token:
         token = auth.get_monitoring_token()
         if token:
             print(token)
             sys.exit(0)
         else:
-            self._debug_print("No valid monitoring token found. Please authenticate first.")
+            # No cached token, trigger authentication to get one
+            auth._debug_print("No valid monitoring token found, triggering authentication...")
+            try:
+                # Run the normal authentication flow
+                exit_code = auth.run()
+                if exit_code == 0:
+                    # Authentication succeeded, try to get the token again
+                    token = auth.get_monitoring_token()
+                    if token:
+                        print(token)
+                        sys.exit(0)
+            except Exception as e:
+                auth._debug_print(f"Authentication failed: {e}")
+            
+            # If we get here, couldn't get a token even after auth attempt
+            # Return failure exit code so OTEL helper knows auth failed
+            # This prevents OTEL helper from using default/unknown values
             sys.exit(1)
 
     # Normal AWS credential flow