az2aws 1.0.0 → 1.0.2

package/CONTRIBUTING.md

@@ -1,54 +1,241 @@
-# Contributing
+# Contributing to az2aws
 
-## Get started
+Thank you for your interest in contributing to az2aws! This document provides guidelines and instructions for contributing.
 
-This project is written in TypeScript and is using prettier and eslint for code formatting. You need node v22.
+## Table of Contents
 
-1. Install node v22. I recommend installing that with nvm: https://github.com/nvm-sh/nvm
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Pull Request Process](#pull-request-process)
+- [Coding Standards](#coding-standards)
+- [Commit Message Guidelines](#commit-message-guidelines)
+- [Reporting Issues](#reporting-issues)
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions. We are committed to providing a welcoming and inclusive environment for everyone.
+
+## Getting Started
+
+This project is written in TypeScript and uses Prettier and ESLint for code formatting. You need Node.js v24 or higher.
+
+### Prerequisites
+
+1. Install [mise](https://mise.jdx.dev/) (runtime version manager):
 
 ```sh
-nvm install 22
+curl https://mise.run | sh
 ```
 
-2. Make node v22 default
+2. Activate mise in your shell. Add the following to your shell configuration file:
 
 ```sh
-nvm alias default 22
+echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
 ```
 
-3. Open a new terminal and verify node version (should return v22.X.X)
+Then restart your shell or run `source ~/.zshrc` (or the appropriate config file for your shell, such as `~/.bashrc`).
+
+3. Install Node.js v24:
+
+```sh
+mise use --global node@24
+```
+
+4. Verify Node.js version (should return v24.x.x):
 
 ```sh
 node -v
 ```
 
-4. Install yarn
+5. Install yarn:
 
 ```sh
 npm install -g yarn
 ```
 
-5. Fork and clone project
+### Setup
+
+1. Fork and clone the repository:
 
 ```sh
-git clone git@github.com:<GITHUB_USERNAME>/az2aws.git
+git clone git@github.com:<YOUR_GITHUB_USERNAME>/az2aws.git
 cd az2aws
 ```
 
-6. Install dependencies
+2. Install dependencies:
 
 ```sh
 yarn install
 ```
 
-7a. Start dev mode
+3. Start development mode:
 
 ```sh
 yarn start
 ```
 
-7b. Start prod mode
+Or build and run production mode:
 
 ```sh
 yarn build && node ./lib/index.js
 ```
+
+### Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `yarn start` | Start development mode with hot reload |
+| `yarn build` | Build for production |
+| `yarn test` | Run linting and formatting checks |
+| `yarn test:unit` | Run unit tests |
+| `yarn eslint` | Run ESLint |
+| `yarn prettier:check` | Check code formatting |
+| `yarn prettier:write` | Auto-fix code formatting |
+
+## Development Workflow
+
+1. Create a new branch from `main`:
+
+```sh
+git switch -c feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+2. Make your changes and ensure tests pass:
+
+```sh
+yarn test
+```
+
+3. Commit your changes following our [commit message guidelines](#commit-message-guidelines).
+
+4. Push your branch and create a Pull Request.
+
+## Pull Request Process
+
+### Before Submitting
+
+- [ ] Run `yarn test` and ensure all checks pass
+- [ ] Run `yarn build` to verify the build succeeds
+- [ ] Update documentation if you changed any user-facing behavior
+- [ ] Add tests for new functionality
+
+### PR Title Format
+
+Use a descriptive title that summarizes the change:
+
+```
+feat: add support for credential_process
+fix: resolve proxy configuration conflict
+docs: update installation instructions
+chore: update dependencies
+```
+
+### PR Description
+
+Please include:
+
+1. **Summary**: What does this PR do?
+2. **Motivation**: Why is this change needed?
+3. **Testing**: How did you test this change?
+4. **Related Issues**: Link any related issues (e.g., `Closes #123`)
+
+### Review Process
+
+1. A maintainer will review your PR
+2. Address any feedback or requested changes
+3. Once approved, a maintainer will merge your PR
+
+## Coding Standards
+
+### TypeScript
+
+- Use TypeScript for all new code
+- Avoid `any` type when possible; use proper typing
+- Use `interface` for object types
+- Export types that are used across modules
+
+### Code Style
+
+This project uses ESLint and Prettier. Your code will be automatically checked.
+
+```sh
+# Check formatting
+yarn prettier:check
+
+# Auto-fix formatting
+yarn prettier:write
+
+# Run linter
+yarn eslint
+```
+
+### File Organization
+
+```
+src/
+├── index.ts           # CLI entry point
+├── login.ts           # Core login logic
+├── awsConfig.ts       # AWS configuration handling
+├── configureProfileAsync.ts  # Profile configuration
+├── paths.ts           # Path utilities
+└── CLIError.ts        # Custom error class
+```
+
+### Best Practices
+
+- Keep functions small and focused
+- Add debug logging for troubleshooting: `debug("message")`
+- Handle errors gracefully with meaningful error messages
+- Avoid breaking changes to CLI options
+
+## Commit Message Guidelines
+
+Commit messages should be generated using some LLM model.
+
+## Reporting Issues
+
+### Bug Reports
+
+When reporting a bug, please include:
+
+1. **Environment**:
+   - OS and version
+   - Node.js version (`node -v`)
+   - az2aws version (`az2aws --version`)
+
+2. **Steps to Reproduce**: Clear steps to reproduce the issue
+
+3. **Expected Behavior**: What you expected to happen
+
+4. **Actual Behavior**: What actually happened
+
+5. **Debug Output**: Run with debug enabled and include the output:
+   ```sh
+   DEBUG=az2aws az2aws [your options]
+   ```
+
+   **Security note**: Debug logs may contain sensitive information (for example, SAML assertions such as SAMLResponse, SAML XML, role details, or other credentials/tokens). Do not share unredacted debug output in public issues or forums. If you attach logs to a bug report, carefully review and redact any secrets or identifiers before posting.
+
+### Feature Requests
+
+When requesting a feature, please include:
+
+1. **Use Case**: Why do you need this feature?
+2. **Proposed Solution**: How do you think it should work?
+3. **Alternatives Considered**: Other approaches you've thought about
+
+### Good First Issues
+
+Look for issues labeled `good first issue` if you're new to the project. These are typically smaller, well-defined tasks that are good for getting started.
+
+## Questions?
+
+If you have questions, feel free to:
+
+- Open a [GitHub Discussion](https://github.com/kuma0128/az2aws/discussions)
+- Open an issue with the `question` label
+
+Thank you for contributing!

package/README.md

@@ -1,5 +1,7 @@
 [![view on npm](http://img.shields.io/npm/v/az2aws.svg)](https://www.npmjs.org/package/az2aws)
 [![npm module downloads per month](http://img.shields.io/npm/dm/az2aws.svg)](https://www.npmjs.org/package/az2aws)
+[![CI](https://github.com/kuma0128/az2aws/actions/workflows/main.yml/badge.svg)](https://github.com/kuma0128/az2aws/actions/workflows/main.yml)
+[![codecov](https://codecov.io/gh/kuma0128/az2aws/graph/badge.svg)](https://codecov.io/gh/kuma0128/az2aws)
 
 # az2aws
 
@@ -11,7 +13,7 @@ Installation can be done in any of the following platform - Windows, Linux, Dock
 
 ### Windows
 
-Install [Node.js](https://nodejs.org/) v22 or higher. Then install az2aws with npm:
+Install [Node.js](https://nodejs.org/) v24 or higher. Then install az2aws with npm:
 
     npm install -g az2aws
 
@@ -21,7 +23,7 @@ You may need to install puppeteer dependency, if you're getting missing chrome o
 
 ### Linux
 
-In Linux you can either install for all users or just the current user. In either case, you must first install [Node.js](https://nodejs.org/) v22 or higher and any [puppeteer dependencies](https://github.com/GoogleChrome/puppeteer/blob/master/docs/troubleshooting.md#chrome-headless-doesnt-launch). Then follow the appropriate instructions.
+In Linux you can either install for all users or just the current user. In either case, you must first install [Node.js](https://nodejs.org/) v24 or higher and any [puppeteer dependencies](https://github.com/GoogleChrome/puppeteer/blob/master/docs/troubleshooting.md#chrome-headless-doesnt-launch). Then follow the appropriate instructions.
 
 #### Option A: Install for All Users
 
@@ -76,6 +78,23 @@ Now just run `az2aws`.
 
 https://snapcraft.io/az2aws
 
+## Command Options
+
+| Option | Description |
+|--------|-------------|
+| `--profile (-p)` | Profile name to use. Default: `default` or `AWS_PROFILE` |
+| `--all-profiles (-a)` | Run for all configured profiles |
+| `--force-refresh (-f)` | Force refresh even if credentials are valid |
+| `--configure (-c)` | Configure the profile |
+| `--mode (-m) <mode>` | `cli` (default), `gui`, or `debug` |
+| `--no-sandbox` | Disable Puppeteer sandbox (needed on Linux) |
+| `--no-prompt` | Skip prompts, use defaults |
+| `--enable-chrome-network-service` | Enable Network Service (for 3XX redirects) |
+| `--no-verify-ssl` | Disable AWS SSL verification |
+| `--enable-chrome-seamless-sso` | Enable Azure AD Seamless SSO |
+| `--no-disable-extensions` | Keep browser extensions enabled |
+| `--disable-gpu` | Disable GPU acceleration |
+
 ## Usage
 
 ### Configuration
@@ -103,43 +122,25 @@ To use az2aws with AWS China Cloud, set the `region` profile property in your ~/
 
 - cn-north-1
 
-#### Staying logged in, skip username/password for future logins
-
-During the configuration you can decide to stay logged in:
+#### Stay Logged In
 
-    ? Stay logged in: skip authentication while refreshing aws credentials (true|false) (false)
-
-If you set this configuration to true, the usual authentication with username/password/MFA is skipped as it's using session cookies to remember your identity. This enables you to use `--no-prompt` without the need to store your password anywhere, it's an alternative for using environment variables as described below.
-As soon as you went through the full login procedure once, you can just use:
+During configuration, you can enable "Stay logged in" to skip username/password/MFA on subsequent logins. Session cookies will remember your identity, allowing you to use `--no-prompt` without storing passwords:
 
     az2aws --no-prompt
-
-or
-
     az2aws --profile foo --no-prompt
 
-to refresh your aws credentials.
-
 #### Environment Variables
 
-You can optionally store your responses as environment variables:
+You can set defaults via environment variables (use with `--no-prompt`):
 
-- `AZURE_TENANT_ID`
-- `AZURE_APP_ID_URI`
-- `AZURE_DEFAULT_USERNAME`
-- `AZURE_DEFAULT_PASSWORD`
-- `AZURE_DEFAULT_ROLE_ARN`
-- `AZURE_DEFAULT_DURATION_HOURS`
+- `AZURE_TENANT_ID` / `AZURE_APP_ID_URI` - Azure AD settings
+- `AZURE_DEFAULT_USERNAME` / `AZURE_DEFAULT_PASSWORD` - Credentials
+- `AZURE_DEFAULT_ROLE_ARN` / `AZURE_DEFAULT_DURATION_HOURS` - AWS role settings
 
-To avoid having to `<Enter>` through the prompts after setting these environment variables, use the `--no-prompt` option when running the command.
+To avoid storing passwords in bash history, use a leading space:
 
-    az2aws --no-prompt
-
-Use the `HISTCONTROL` environment variable to avoid storing the password in your bash history (notice the space at the beginning):
-
-    $ HISTCONTROL=ignoreboth
-    $  export AZURE_DEFAULT_PASSWORD=mypassword
-    $ az2aws
+    HISTCONTROL=ignoreboth
+     export AZURE_DEFAULT_PASSWORD=mypassword
 
 #### Use an Existing Chrome Install and Profile
 
@@ -154,63 +155,39 @@ Example (macOS):
     export BROWSER_CHROME_BIN="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
     export BROWSER_USER_DATA_DIR="/Users/<user>/Library/Application Support/Google/Chrome"
     export BROWSER_PROFILE_DIR="Default"
-    aws-azure-login --mode gui --no-disable-extensions --no-sandbox
+    az2aws --mode gui --no-disable-extensions --no-sandbox
 
 Example (Linux):
 
     export BROWSER_CHROME_BIN="/usr/bin/google-chrome"
     export BROWSER_USER_DATA_DIR="/home/<user>/.config/google-chrome"
     export BROWSER_PROFILE_DIR="Default"
-    aws-azure-login --mode gui --no-disable-extensions --no-sandbox
+    az2aws --mode gui --no-disable-extensions --no-sandbox
 
 Using Chrome instead of Chromium allows you to use browser extensions such as password managers.
 
 ### Logging In
 
-Once az2aws is configured, you can log in. For the default profile, just run:
-
-    az2aws
-
-You will be prompted for your username and password. If MFA is required you'll also be prompted for a verification code or mobile device approval. To log in with a named profile:
-
-    az2aws --profile foo
-
-Alternatively, you can set the `AWS_PROFILE` environmental variable to the name of the profile just like the AWS CLI.
+    az2aws                    # Default profile
+    az2aws --profile foo      # Named profile
+    az2aws --mode gui         # Use browser UI (more reliable)
 
-Once you log in you can use the AWS CLI or SDKs as usual!
+You'll be prompted for username, password, and MFA if required. After login, use AWS CLI/SDKs as usual.
 
-If you are logging in on an operating system with a GUI, you can log in using the actual Azure web form instead of the CLI:
-
-    az2aws --mode gui
-
-Logging in with GUI mode is likely to be much more reliable.
-
-_Note:_ on virtual machines, or when rendering of the puppeteer UI fails, you might need to disable the GPU Hardware Acceleration:
-
-    az2aws --mode gui --disable-gpu
-
-_Note:_ on Linux you will likely need to disable the Puppeteer sandbox or Chrome will fail to launch:
-
-    az2aws --no-sandbox
-
-### Behind corporate proxy
-
-If behind corporate proxy, then just set https_proxy env variable.
+**Tips:**
+- Set `AWS_PROFILE` env var instead of using `--profile`
+- Use `--mode gui --disable-gpu` on VMs or if rendering fails
+- Use `--no-sandbox` on Linux
+- Set `https_proxy` env var for corporate proxy
 
 ## Automation
 
-### Renew credentials for all configured profiles
-
-You can renew credentials for all configured profiles in one run. This is especially useful, if the maximum session length on AWS side is configured to a low value due to security constraints. Just run:
+Renew all profiles at once (useful for short session limits):
 
     az2aws --all-profiles
+    az2aws --all-profiles --no-prompt    # With "Stay logged in" enabled
 
-If you configure all profiles to stay logged in, you can easily skip the prompts:
-
-    az2aws --all-profiles --no-prompt
-
-This will allow you to automate the credentials refresh procedure, eg. by running a cronjob every 5 minutes.
-To skip unnecessary calls, the credentials are only getting refreshed if the time to expire is lower than 11 minutes.
+Credentials are only refreshed if expiring within 11 minutes - safe to run as a cron job.
 
 ## Getting Your Tenant ID and App ID URI
 
@@ -232,14 +209,11 @@ The Azure login page uses JavaScript, which requires a real web browser. To auto
 
 ## Troubleshooting
 
-The nature of browser automation with Puppeteer means the solution is bit brittle. A minor change on the Microsoft side could break the tool. If something isn't working, you can fall back to GUI mode (above). To debug an issue, you can run in debug mode (--mode debug) to see the GUI while az2aws tries to populate it. You can also have the tool print out more detail on what it is doing to try to do in order to diagnose. az2aws uses the [Node debug module](https://www.npmjs.com/package/debug) to print out debug info. Just set the DEBUG environmental variable to 'az2aws'. On Linux/OS X:
-
-    DEBUG=az2aws az2aws
-
-On Windows:
+If login fails, try these in order:
 
-    set DEBUG=az2aws
-    az2aws
+1. **GUI mode**: `az2aws --mode gui` - most reliable
+2. **Debug mode**: `az2aws --mode debug` - see browser while CLI runs
+3. **Verbose logging**: `DEBUG=az2aws az2aws` (Windows: `set DEBUG=az2aws && az2aws`)
 
 ## Support for Other Authentication Providers
 

package/lib/login.js

@@ -236,6 +236,11 @@ const states = [
             (description) => { var _a; return (_a = description === null || description === void 0 ? void 0 : description.textContent) !== null && _a !== void 0 ? _a : ""; }, selected);
             console.log(descriptionMessage);
             try {
+                debug("Waiting for authentication code to be displayed");
+                await page.waitForSelector("#idRichContext_DisplaySign", {
+                    visible: true,
+                    timeout: 5000,
+                });
                 debug("Checking if authentication code is displayed");
                 const authenticationCodeElement = await page.$("#idRichContext_DisplaySign");
                 debug("Reading the authentication code");
@@ -788,6 +793,9 @@ exports.login = {
             };
         }
         if (awsNoVerifySsl) {
+            console.warn("WARNING: SSL certificate verification is disabled. " +
+                "This makes the connection vulnerable to MITM attacks. " +
+                "Consider using NODE_EXTRA_CA_CERTS environment variable instead.");
             stsOptions = {
                 ...stsOptions,
                 requestHandler: new node_http_handler_1.NodeHttpHandler({

package/package.json

@@ -1,20 +1,41 @@
 {
   "name": "az2aws",
-  "version": "1.0.0",
-  "description": "Use Azure AD SSO to log into the AWS CLI.",
+  "version": "1.0.2",
+  "description": "Use Azure AD SSO to log into the AWS CLI. A modern, actively maintained alternative to aws-azure-login.",
   "main": "index.js",
   "author": {
     "name": "az2aws devs",
     "url": "https://github.com/az2aws"
   },
   "license": "MIT",
+  "keywords": [
+    "aws",
+    "azure",
+    "azure-ad",
+    "entra-id",
+    "microsoft-entra",
+    "saml",
+    "sso",
+    "single-sign-on",
+    "cli",
+    "authentication",
+    "mfa",
+    "multi-factor-authentication",
+    "federated-login",
+    "aws-cli",
+    "credential-helper",
+    "sts",
+    "assume-role",
+    "puppeteer"
+  ],
+  "homepage": "https://github.com/kuma0128/az2aws#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/az2aws/az2aws.git"
+    "url": "git+https://github.com/kuma0128/az2aws.git"
   },
-  "bugs": "https://github.com/az2aws/az2aws/issues",
+  "bugs": "https://github.com/kuma0128/az2aws/issues",
   "engines": {
-    "node": ">=22.0"
+    "node": ">=24.0"
   },
   "bin": {
     "az2aws": "lib/index.js"
@@ -26,7 +47,10 @@
     "eslint": "eslint . --ext .ts",
     "prettier:write": "prettier --write \"src/**/*.{ts,json}\"",
     "prettier:check": "prettier --check \"src/**/*.ts\"",
-    "test": "yarn eslint && yarn prettier:check"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "yarn eslint && yarn prettier:check"
   },
   "dependencies": {
     "@aws-sdk/client-sts": "^3.473.0",
@@ -51,14 +75,16 @@
     "@types/inquirer": "^8.2.10",
     "@types/lodash": "^4.17.0",
     "@types/mkdirp": "^1.0.2",
-    "@types/node": "^20.11.30",
+    "@types/node": "^24.0.0",
     "@types/uuid": "^8.3.4",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "@typescript-eslint/parser": "^6.21.0",
+    "@vitest/coverage-v8": "^4.0.16",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^8.10.0",
     "prettier": "^2.8.8",
     "ts-node-dev": "^1.1.8",
-    "typescript": "^5.4.3"
+    "typescript": "^5.4.3",
+    "vitest": "^4.0.16"
   }
 }

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html", "lcov"],
+      include: ["src/**/*.ts"],
+      exclude: ["src/**/*.test.ts", "src/index.ts"],
+    },
+  },
+});

package/.claude/settings.local.json

@@ -1,16 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(yarn test)",
-      "Bash(npm run test)",
-      "Bash(npm run build:*)",
-      "Bash(npm install)",
-      "Bash(npm cache clean:*)",
-      "Bash(npm install:*)",
-      "Bash(yarn install)",
-      "WebFetch(domain:github.com)",
-      "WebFetch(domain:patch-diff.githubusercontent.com)",
-      "Bash(ls:*)"
-    ]
-  }
-}