credux 0.2.0__tar.gz

credux-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+# Builds and uploads a release when a version tag is pushed.
+#
+# Every job is guarded on the repository name. This file is copied into more
+# than one checkout, and a tag pushed in any of them would otherwise start a
+# run that builds a distribution from that tree. The guard makes such a run a
+# no-op before anything is checked out.
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    if: github.repository == 'AlbertoSpinella/credux'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: pytest
+
+  version-guard:
+    if: github.repository == 'AlbertoSpinella/credux'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: The tag and the declared version must agree
+        run: |
+          declared="$(sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml | head -1)"
+          if [ "v$declared" != "${{ github.ref_name }}" ]; then
+            echo "tag ${{ github.ref_name }} does not match pyproject.toml version $declared" >&2
+            exit 1
+          fi
+
+  publish:
+    if: github.repository == 'AlbertoSpinella/credux'
+    needs: [test, version-guard]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

credux-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

credux-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alberto Spinella
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

credux-0.2.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.5
+Name: credux
+Version: 0.2.0
+Summary: Manage cloud credentials and the profiles that use them
+Project-URL: Homepage, https://github.com/AlbertoSpinella/credux
+Project-URL: Repository, https://github.com/AlbertoSpinella/credux
+Project-URL: Issues, https://github.com/AlbertoSpinella/credux/issues
+Author: Alberto Spinella
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aws,cli,credentials,iam,identity-center,profiles,sso
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: boto3>=1.34
+Requires-Dist: click>=8.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: keyring>=24.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# credux
+
+Credux manages your AWS credentials and materializes the ones you are actively
+using into `~/.aws/credentials` and `~/.aws/config`, under profile names it
+derives from a template you control.
+
+It understands three kinds of credential:
+
+- long-term **IAM user** access keys, kept in your OS keychain;
+- **IAM roles** assumed on demand, optionally chained through other credux
+  credentials;
+- **IAM Identity Center** (AWS SSO) permission sets, discovered automatically
+  from your Identity Center account.
+
+Any tool that takes `--profile` or reads `AWS_PROFILE` works with the result: no
+wrapper, no credential process, no AWS CLI installation required.
+
+## Requirements
+
+- Python 3.10 or later
+- An OS keychain: macOS Keychain, Windows Credential Manager, or a Linux Secret
+  Service provider such as gnome-keyring or kwallet (see
+  [troubleshooting](docs/troubleshooting.md#headless-linux-and-wsl-no-keychain)
+  for headless Linux and WSL)
+- For `credux console`'s default browser command: Firefox plus *two* extensions,
+  [Multi-Account Containers](https://addons.mozilla.org/en-US/firefox/addon/multi-account-containers/)
+  for the containers themselves and
+  [Open external links in a container](https://addons.mozilla.org/en-US/firefox/addon/open-url-in-container/)
+  for the `ext+container:` URL scheme credux hands to the browser. Any other
+  browser works by pointing `settings.browser_command` at it.
+
+Runtime dependencies are `boto3`, `click`, `rich`, `keyring`, and `jinja2`.
+
+## Install
+
+Install it with [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install credux
+credux --version
+```
+
+pipx keeps credux in its own virtual environment and puts the `credux` command on
+your `PATH` (usually `~/.local/bin`). Remove it with `pipx uninstall credux`.
+
+If you do not have pipx: `brew install pipx`, `apt install pipx`, or
+`python3 -m pip install --user pipx`.
+
+A plain virtual environment does the same job:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install credux
+ln -s "$PWD/.venv/bin/credux" ~/.local/bin/credux
+```
+
+### Upgrading
+
+`credux upgrade` replaces this installation with another release from the
+index:
+
+```bash
+credux upgrade                   # newest release
+credux upgrade --version 0.1.0   # a specific release, also a way to repair
+credux upgrade --from ./credux   # whatever is checked out in a local clone
+```
+
+It drives whichever installer owns the environment credux is running in, and
+refuses an editable install or an installation outside any virtual environment
+rather than writing over either. Details in
+[docs/releasing.md](docs/releasing.md#how-credux-upgrade-works).
+
+## Quickstart
+
+```bash
+credux add iam-user            # prompts for org, account, user, and keys
+credux start acme-billing-User-ada
+eval "$(credux shell-init)"    # add this line to your shell rc instead, once
+pu acme-billing-User-ada       # sets AWS_PROFILE in *this* shell
+aws sts get-caller-identity
+credux console acme-billing-User-ada   # open the account in a browser container
+```
+
+`credux start` writes the profile into `~/.aws/credentials`, so any tool that
+reads a profile can use it right away. `credux shell-init` installs the `pu`
+shell function (which sets `AWS_PROFILE` in your current shell) and registers tab
+completion for bash, zsh, and fish.
+
+Profile names are searched, not spelled out: `credux console billing` finds
+`acme-billing-User-ada`, and an ambiguous term asks which one you meant.
+
+Using IAM Identity Center? Register the session once and let credux discover
+every account and permission set you can reach:
+
+```bash
+credux add sso-session acme --start-url https://acme.awsapps.com/start --sso-region eu-west-1
+credux login acme     # device-authorization flow in your browser
+credux sync acme      # discovers accounts/roles, creates/renames profiles
+```
+
+Then `credux list` shows everything configured, which sessions are active, and
+how long each has left.
+
+## Profile names are a template you own
+
+`acme-billing-User-ada` above is credux's default naming template, not a rule.
+It is one house style, and `credux add`/`credux sync` say so until you have
+picked your own:
+
+```bash
+credux config set naming.iam_sso '{account_name}-{role}'
+```
+
+Variables: `org`, `account_name`, `account_id`, `user`, `role`, `subdomain`,
+`region`. Identity Center profiles are renamed by the next `credux sync`;
+IAM user and role profiles keep the name they were added under. See
+[docs/configuration.md](docs/configuration.md#naming).
+
+## Your existing `~/.aws` files
+
+Credux owns one marker-delimited block in `~/.aws/credentials` and
+`~/.aws/config`, and preserves everything outside it byte for byte. Before its
+first write to a file that already existed, it copies that file to
+`<path>.credux.bak` (mode `0600`) and tells you where. See
+[docs/security.md](docs/security.md#the-one-time-backup).
+
+## The fake `default` profile
+
+Every write to `~/.aws/credentials` also (re-)writes a profile literally named
+`default`, holding deliberately invalid keys (`test`/`test` unless you configure
+otherwise).
+
+AWS SDKs and the `aws` CLI silently fall back to `default` whenever no
+`--profile`/`AWS_PROFILE` is given. Without that slot pinned to keys AWS will
+reject, a script or terminal tab that forgot to select a profile could quietly
+run against whatever real credentials happened to be sitting there. With the fake
+profile in place, the same mistake fails loudly with an authentication error.
+
+Disable it with `credux config set default_profile.enabled false`. If you had a
+`default` profile of your own, credux warns that the two now compete and
+`credux doctor` keeps reporting it.
+
+## Documentation
+
+| Document | Covers |
+|---|---|
+| [docs/usage.md](docs/usage.md) | Every command, profile searching, `pu` and completion, Identity Center, several sessions at once, scheduled refresh, browser containers. |
+| [docs/configuration.md](docs/configuration.md) | Every `config.json` key: settings, naming templates, the management-account prefix, integrations, `post_sync` hooks. |
+| [docs/security.md](docs/security.md) | Where secrets live and where they never go, file permissions, the one-time backup. |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | `credux doctor`, keychain on headless Linux and WSL, exit codes. |
+| [docs/architecture.md](docs/architecture.md) | For contributors: the layering rule, the invariants, the module map. |
+
+`examples/config.json` is a complete configuration file to read alongside
+[docs/configuration.md](docs/configuration.md).
+
+## Contributing
+
+Issues and pull requests are welcome. The project follows strict test-driven
+development.
+
+Development happens in a separate tree, and what arrives here is the released
+state: one commit per release, which is why the history is short and every
+commit is a version. A pull request is read as a proposal rather than something
+merged into this branch - an accepted one is applied upstream and appears in the
+next release commit, credited in the discussion it came from.
+
+```bash
+git clone https://github.com/AlbertoSpinella/credux.git
+cd credux
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+Before changing anything, read [docs/architecture.md](docs/architecture.md) for
+the layering rule and the invariants any change must preserve, and
+[docs/testing.md](docs/testing.md) for the test conventions and the traps this
+project has already hit.
+
+## Licence
+
+MIT; see [LICENSE](LICENSE).

credux-0.2.0/README.md

@@ -0,0 +1,182 @@
+# credux
+
+Credux manages your AWS credentials and materializes the ones you are actively
+using into `~/.aws/credentials` and `~/.aws/config`, under profile names it
+derives from a template you control.
+
+It understands three kinds of credential:
+
+- long-term **IAM user** access keys, kept in your OS keychain;
+- **IAM roles** assumed on demand, optionally chained through other credux
+  credentials;
+- **IAM Identity Center** (AWS SSO) permission sets, discovered automatically
+  from your Identity Center account.
+
+Any tool that takes `--profile` or reads `AWS_PROFILE` works with the result: no
+wrapper, no credential process, no AWS CLI installation required.
+
+## Requirements
+
+- Python 3.10 or later
+- An OS keychain: macOS Keychain, Windows Credential Manager, or a Linux Secret
+  Service provider such as gnome-keyring or kwallet (see
+  [troubleshooting](docs/troubleshooting.md#headless-linux-and-wsl-no-keychain)
+  for headless Linux and WSL)
+- For `credux console`'s default browser command: Firefox plus *two* extensions,
+  [Multi-Account Containers](https://addons.mozilla.org/en-US/firefox/addon/multi-account-containers/)
+  for the containers themselves and
+  [Open external links in a container](https://addons.mozilla.org/en-US/firefox/addon/open-url-in-container/)
+  for the `ext+container:` URL scheme credux hands to the browser. Any other
+  browser works by pointing `settings.browser_command` at it.
+
+Runtime dependencies are `boto3`, `click`, `rich`, `keyring`, and `jinja2`.
+
+## Install
+
+Install it with [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install credux
+credux --version
+```
+
+pipx keeps credux in its own virtual environment and puts the `credux` command on
+your `PATH` (usually `~/.local/bin`). Remove it with `pipx uninstall credux`.
+
+If you do not have pipx: `brew install pipx`, `apt install pipx`, or
+`python3 -m pip install --user pipx`.
+
+A plain virtual environment does the same job:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install credux
+ln -s "$PWD/.venv/bin/credux" ~/.local/bin/credux
+```
+
+### Upgrading
+
+`credux upgrade` replaces this installation with another release from the
+index:
+
+```bash
+credux upgrade                   # newest release
+credux upgrade --version 0.1.0   # a specific release, also a way to repair
+credux upgrade --from ./credux   # whatever is checked out in a local clone
+```
+
+It drives whichever installer owns the environment credux is running in, and
+refuses an editable install or an installation outside any virtual environment
+rather than writing over either. Details in
+[docs/releasing.md](docs/releasing.md#how-credux-upgrade-works).
+
+## Quickstart
+
+```bash
+credux add iam-user            # prompts for org, account, user, and keys
+credux start acme-billing-User-ada
+eval "$(credux shell-init)"    # add this line to your shell rc instead, once
+pu acme-billing-User-ada       # sets AWS_PROFILE in *this* shell
+aws sts get-caller-identity
+credux console acme-billing-User-ada   # open the account in a browser container
+```
+
+`credux start` writes the profile into `~/.aws/credentials`, so any tool that
+reads a profile can use it right away. `credux shell-init` installs the `pu`
+shell function (which sets `AWS_PROFILE` in your current shell) and registers tab
+completion for bash, zsh, and fish.
+
+Profile names are searched, not spelled out: `credux console billing` finds
+`acme-billing-User-ada`, and an ambiguous term asks which one you meant.
+
+Using IAM Identity Center? Register the session once and let credux discover
+every account and permission set you can reach:
+
+```bash
+credux add sso-session acme --start-url https://acme.awsapps.com/start --sso-region eu-west-1
+credux login acme     # device-authorization flow in your browser
+credux sync acme      # discovers accounts/roles, creates/renames profiles
+```
+
+Then `credux list` shows everything configured, which sessions are active, and
+how long each has left.
+
+## Profile names are a template you own
+
+`acme-billing-User-ada` above is credux's default naming template, not a rule.
+It is one house style, and `credux add`/`credux sync` say so until you have
+picked your own:
+
+```bash
+credux config set naming.iam_sso '{account_name}-{role}'
+```
+
+Variables: `org`, `account_name`, `account_id`, `user`, `role`, `subdomain`,
+`region`. Identity Center profiles are renamed by the next `credux sync`;
+IAM user and role profiles keep the name they were added under. See
+[docs/configuration.md](docs/configuration.md#naming).
+
+## Your existing `~/.aws` files
+
+Credux owns one marker-delimited block in `~/.aws/credentials` and
+`~/.aws/config`, and preserves everything outside it byte for byte. Before its
+first write to a file that already existed, it copies that file to
+`<path>.credux.bak` (mode `0600`) and tells you where. See
+[docs/security.md](docs/security.md#the-one-time-backup).
+
+## The fake `default` profile
+
+Every write to `~/.aws/credentials` also (re-)writes a profile literally named
+`default`, holding deliberately invalid keys (`test`/`test` unless you configure
+otherwise).
+
+AWS SDKs and the `aws` CLI silently fall back to `default` whenever no
+`--profile`/`AWS_PROFILE` is given. Without that slot pinned to keys AWS will
+reject, a script or terminal tab that forgot to select a profile could quietly
+run against whatever real credentials happened to be sitting there. With the fake
+profile in place, the same mistake fails loudly with an authentication error.
+
+Disable it with `credux config set default_profile.enabled false`. If you had a
+`default` profile of your own, credux warns that the two now compete and
+`credux doctor` keeps reporting it.
+
+## Documentation
+
+| Document | Covers |
+|---|---|
+| [docs/usage.md](docs/usage.md) | Every command, profile searching, `pu` and completion, Identity Center, several sessions at once, scheduled refresh, browser containers. |
+| [docs/configuration.md](docs/configuration.md) | Every `config.json` key: settings, naming templates, the management-account prefix, integrations, `post_sync` hooks. |
+| [docs/security.md](docs/security.md) | Where secrets live and where they never go, file permissions, the one-time backup. |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | `credux doctor`, keychain on headless Linux and WSL, exit codes. |
+| [docs/architecture.md](docs/architecture.md) | For contributors: the layering rule, the invariants, the module map. |
+
+`examples/config.json` is a complete configuration file to read alongside
+[docs/configuration.md](docs/configuration.md).
+
+## Contributing
+
+Issues and pull requests are welcome. The project follows strict test-driven
+development.
+
+Development happens in a separate tree, and what arrives here is the released
+state: one commit per release, which is why the history is short and every
+commit is a version. A pull request is read as a proposal rather than something
+merged into this branch - an accepted one is applied upstream and appears in the
+next release commit, credited in the discussion it came from.
+
+```bash
+git clone https://github.com/AlbertoSpinella/credux.git
+cd credux
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+Before changing anything, read [docs/architecture.md](docs/architecture.md) for
+the layering rule and the invariants any change must preserve, and
+[docs/testing.md](docs/testing.md) for the test conventions and the traps this
+project has already hit.
+
+## Licence
+
+MIT; see [LICENSE](LICENSE).

credux-0.2.0/docs/README.md

@@ -0,0 +1,25 @@
+# credux documentation
+
+Start at the [project README](../README.md) for what credux is, how to install
+it, and a quickstart.
+
+## Using credux
+
+| Document | Covers |
+|---|---|
+| [usage.md](usage.md) | Command reference, profile searching, `pu` and tab completion, Identity Center, running several sessions at once, scheduled refresh, the AWS console and browser containers. |
+| [configuration.md](configuration.md) | Every key in `config.json`: `settings`, naming templates and the management-account prefix, `sso_sessions`, `integrations`, `post_sync`. |
+| [security.md](security.md) | Where secrets live and where they never go, file permissions, the one-time backup, the console-URL caveat. |
+| [troubleshooting.md](troubleshooting.md) | `credux doctor`, keychain on headless Linux and WSL, common failures, the exit-code table. |
+
+## Working on credux
+
+| Document | Covers |
+|---|---|
+| [architecture.md](architecture.md) | The layering rule, the five invariants any change must preserve, the module map, resolution and chaining, repo-wide rules. |
+| [providers.md](providers.md) | How to add a provider for another cloud. |
+| [testing.md](testing.md) | How to run the suite, the test conventions, and the traps this project has actually hit. |
+| [releasing.md](releasing.md) | Cutting a release and how `credux upgrade` decides what to do. |
+
+Read [architecture.md](architecture.md) before changing structure and
+[testing.md](testing.md) before writing tests.