<div align="center">

# ⚡ AWS-Auth

### Fast, Intelligent AWS SSO Authentication & Model Context Protocol (MCP) Server

[![CI](https://github.com/N0mansky/aws-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/N0mansky/aws-auth/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/N0mansky/aws-auth?color=blue&logo=github)](https://github.com/N0mansky/aws-auth/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![MCP Ready](https://img.shields.io/badge/MCP-Server%20Ready-purple.svg)](https://modelcontextprotocol.io/)

**Eliminate AWS SSO login fatigue.** Zero configuration boilerplate, smart role prioritization, atomic credential caching, and native AI pair-programming integration.

[Quick Start](#-quick-start) •
[Why aws-auth?](#-why-aws-auth-vs-alternatives) •
[AI / MCP Integration](#-ai-agent-integration-model-context-protocol) •
[Features](#-key-features) •
[Documentation](#-documentation)

---

</div>

```text
  ┌───────────────────────┐       ┌────────────────────────┐       ┌───────────────────────┐
  │  IAM Identity Center  │ ────> │       aws-auth         │ ────> │  ~/.aws/credentials   │
  │     (AWS SSO OIDC)    │       │  (Smart Role Selector) │       │ (Strict 0600 POSIX)   │
  └───────────────────────┘       └───────────┬────────────┘       └───────────┬───────────┘
                                              │                                │
                                  ┌───────────▼────────────┐       ┌───────────▼───────────┐
                                  │   MCP Server (stdio)   │       │ Terraform / K8s / CLI │
                                  │ (Claude / Cursor / AI) │       │ (Instant Compatibility)│
                                  └────────────────────────┘       └───────────────────────┘
```

---

## 💡 Why `aws-auth` vs Alternatives?

| Feature | `aws-auth` | Official `aws sso login` | `granted` / `assume` | `aws-vault` |
| :--- | :---: | :---: | :---: | :---: |
| **Zero-Config Account Discovery** | ✅ **Automatic** | ❌ Requires manual `~/.aws/config` | ⚠️ Partial | ❌ Manual |
| **Model Context Protocol (MCP)** | ✅ **Native built-in** | ❌ None | ❌ None | ❌ None |
| **1-Second MRU / Pinned Logins** | ✅ **Smart Prioritization** | ❌ None | ⚠️ History prompt | ❌ None |
| **Real-time Substring & Alias Filter** | ✅ **Instant typing** | ❌ None | ✅ Yes | ❌ None |
| **Direct `~/.aws/credentials` Sync** | ✅ **Atomic & `0600`** | ❌ Token cache only | ⚠️ Shell wrapper | ⚠️ Keychain wrapper |
| **Legacy & GUI Tool Compatibility** | ✅ **100% Out of Box** | ⚠️ Many tools fail | ⚠️ Requires wrapper | ⚠️ Requires wrapper |
| **WSL2 -> Windows Browser Bridge** | ✅ **Automatic** | ❌ Fails / manual copy | ⚠️ Partial | ❌ No |
| **EC2 SSM & EKS Context Switching** | ✅ **Built-in** | ❌ Separate tools | ❌ Separate tools | ❌ No |

👉 **Read the full [Feature Comparison Guide](docs/COMPARISON.md)**.

---

## ✨ Key Features

- 🎯 **AWS Best-Practice Named Profiles**: Credentials are kept in named profile sections (e.g., `[staging-admin]`) and scoped to your terminal session via `export AWS_PROFILE`, preventing unsafe overwrites to `[default]`.
- ⚡ **Zero-Boilerplate Discovery**: No need to maintain hundreds of lines in `~/.aws/config`. Enter your SSO Start URL once, and all authorized accounts and roles are loaded dynamically.
- ⭐ **Smart Role Prioritization (MRU)**: Automatically pins your most recently used roles (e.g. `QA Admin`, `Prod Admin`) to `#1` and `#2`. Pressing `Enter` logs you in within **1 second**.
- 🔍 **Interactive Substring Search**: Type any keyword (`prod`, `qa`, `admin`, `gpu`, `eks`) at the selection prompt to instantly filter dozens of accounts.
- 🤖 **Native Model Context Protocol (MCP) Server**: Expose AWS profile switching, caller identity, and EC2/EKS exploration to LLM pair programmers (Claude Desktop, Cursor, Antigravity, Gemini).
- 🔒 **Enterprise-Grade Security**: Strict POSIX `0600` file permissions, atomic file replacement (`os.replace`), and 300-second expiration safety margins.
- 🌐 **WSL2 Seamless Browser Bridge**: Automatically detects WSL2 and opens authorization URLs directly in your Windows host browser.
- ☸️ **DevOps Acceleration**: Instant EC2 SSM shell sessions and 1-click Amazon EKS kubeconfig context switching.

---

## 📦 Installation

### Option 1: Standalone Binary (Recommended)

Download the latest pre-compiled binary from [GitHub Releases](https://github.com/N0mansky/aws-auth/releases/latest):

#### Windows (PowerShell 1-Liner)
Run in PowerShell to automatically download the binary, configure PATH, and set up shell integration:
```powershell
irm https://raw.githubusercontent.com/N0mansky/aws-auth/main/install.ps1 | iex
```

*Or manual download via PowerShell:*
```powershell
curl.exe -L https://github.com/N0mansky/aws-auth/releases/latest/download/aws-auth-windows-amd64.exe -o aws-auth.exe
```

#### Linux (x86_64)
```bash
curl -L https://github.com/N0mansky/aws-auth/releases/latest/download/aws-auth-linux-amd64 -o aws-auth
chmod +x aws-auth && sudo mv aws-auth /usr/local/bin/
```

#### macOS (Universal)
```bash
curl -L https://github.com/N0mansky/aws-auth/releases/latest/download/aws-auth-macos-universal -o aws-auth
chmod +x aws-auth && sudo mv aws-auth /usr/local/bin/
```

### Option 2: Clone & Install from Source (Automated Shell Setup)

`install.sh` and `install.ps1` automatically configure the shell integration wrapper in your shell profile:

```bash
git clone https://github.com/N0mansky/aws-auth.git
cd aws-auth

./install.sh                      # Linux / macOS / WSL2 (configures ~/.zshrc, ~/.bashrc)
powershell .\install.ps1          # Windows (PowerShell - configures $PROFILE)
.\install.bat                     # Windows (Command Prompt)
```

### Option 3: Install via pip

```bash
pip install git+https://github.com/N0mansky/aws-auth.git
```

---

## 🐚 Shell Integration (`AWS_PROFILE`)

To enable seamless session scoping without child-process limitations, `install.sh` and `install.ps1` automatically install a shell wrapper. 

If you installed manually or via `pip`, add this block to your `~/.zshrc`, `~/.bashrc`, or `~/.profile`:

```bash
# >>> aws-auth shell wrapper >>>
# Auto-export active profile on shell startup if present
if [ -f ~/.aws-auth/current_profile ]; then
    export AWS_PROFILE=$(< ~/.aws-auth/current_profile)
fi

# Scopes active profile to current terminal session via AWS_PROFILE
aws-auth() {
    command /usr/local/bin/aws-auth "$@"
    local ret=$?
    if [ $ret -eq 0 ] && [ -f ~/.aws-auth/current_profile ]; then
        export AWS_PROFILE=$(< ~/.aws-auth/current_profile)
    fi
    return $ret
}
# <<< aws-auth shell wrapper <<<
```

Reload your shell or run `source ~/.zshrc` (or `source ~/.bashrc`). Terminal prompts like **Starship** (`☁️  <profile>`) and tools like `kubectl` or `aws` will instantly reflect your active profile!

---

## 🚀 Quick Start

### 1. Interactive Login

```bash
aws-auth
```

```text
Available account-role combinations (Showing 1-10 of 18):
+-----+------------------------------+-----------------+------------------------------+-------------+
| #   | Account                      | Account ID      | Role                         | Region      |
+-----+------------------------------+-----------------+------------------------------+-------------+
| 1   | ⭐ Production-App (PROD)        | (111222333444)  | AdministratorAccess     | us-east-1   |
| 2   | ⭐ Staging-Web (QA)          | (555666777888)  | AdministratorAccess     | us-east-1   |
| 3   | Analytics-Data                  | (999888777666)  | AdministratorAccess     | us-east-1   |
...
Select number 1-10 (default: 1) (type keyword to filter): [ENTER]

✅ Profile 'production-app-admin' saved to ~/.aws/credentials.
✅ Active profile set to: production-app-admin (scoped via AWS_PROFILE)
```

### 2. Configure Portal & Custom Aliases

```bash
aws-auth --configure
```

Customize environment labels and preferred accounts in `~/.aws-auth/config.json`:
```json
{
  "sso_start_url": "https://my-company.awsapps.com/start",
  "sso_region": "us-east-1",
  "preferred_accounts": ["Staging-Web", "Production-App"],
  "aliases": {
    "555666777888": "QA",
    "111222333444": "PROD"
  }
}
```

---

## 🤖 AI Agent Integration (Model Context Protocol)

`aws-auth` runs as a high-performance **MCP Server** over stdio.

### Add to Claude Desktop (`claude_desktop_config.json`) or Cursor:

```json
{
  "mcpServers": {
    "aws-auth": {
      "command": "aws-auth",
      "args": ["--mcp"]
    }
  }
}
```

### What AI Assistants Can Do with `aws-auth`:
- Check active AWS Account, Region, and IAM Role ARN (`aws_get_caller_identity`).
- Switch active AWS profile (`aws_switch_profile`) without human intervention.
- Inspect running EC2 instances and Amazon EKS clusters (`aws_list_ec2_instances`, `aws_list_eks_clusters`).
- Update local Kubernetes context (`aws_update_kubeconfig`).

👉 **Read the full [MCP Setup & Tool Reference Guide](docs/MCP_GUIDE.md)**.

---

## 🛠️ CLI Command Reference

```bash
# Core Authentication
aws-auth                     # Interactive SSO login & smart role switch
aws-auth --configure         # Interactive SSO portal setup
aws-auth --identity          # Show current STS caller identity
aws-auth --refresh-cache     # Force refresh remote account/role metadata
aws-auth --write-default     # Opt-in to write/sync credentials to [default] section

# Profile Management & Session Scoping
aws-auth --list-profiles          # List all stored AWS profiles (* marks active)
aws-auth --current-profile        # Print active profile name (fast query)
aws-auth -p, --use-profile NAME   # Activate named profile in current session
aws-auth -s, --switch-profile     # Interactive profile switcher
aws-auth --set-default NAME       # Copy profile credentials to [default] section
aws-auth --delete NAME            # Delete profile credentials

# Resource Discovery & DevOps
aws-auth --list-ec2          # List EC2 instances and connect via SSM
aws-auth --list-eks          # List EKS clusters and update kubeconfig

# Scripting & Headless Automation
aws-auth --current-profile --json # JSON output {"current_profile": "..."}
aws-auth --list-profiles --json
aws-auth --identity --json
eval $(aws-auth --export-env prod-profile)  # Export AWS keys to current shell

# AWS credential_process standard
aws-auth --credential-process my-profile
```

---

## 📚 Documentation

- 📊 [Comparison with AWS CLI, Granted & AWS-Vault](docs/COMPARISON.md)
- 🤖 [Model Context Protocol (MCP) Guide](docs/MCP_GUIDE.md)
- 🐧 [WSL2 Setup & Windows Integration Guide](docs/WSL2_SETUP.md)
- 💻 [Linux Detailed Installation](docs/aws-kubectl-linux-install.md)
- 🪟 [Windows Detailed Installation](docs/aws-kubectl-windows-install.md)

---

## 🛠️ Development & Testing

Unified commands are provided via the [Makefile](Makefile):

```bash
make help          # View all available targets
make venv          # Initialize virtual environment and install dev dependencies
make test          # Run automated unit tests with pytest
make check         # Run full quality gate (secret scanning, Bandit SAST, audit, tests)
make build         # Compile standalone PyInstaller binary
```

---

## 🤝 Contributing

Contributions are welcome! Please check out [CONTRIBUTING.md](CONTRIBUTING.md) for details on setting up a development environment, testing standards, and security policies.

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).