Metadata-Version: 2.4
Name: git-buckets-keyring
Version: 0.1.1
Summary: Keyring backend and STS proof builder for git-buckets package registries.
Keywords: aws,keyring,pypi,sts,packaging,private-registry
Author: Full Duplex Media
Author-email: Full Duplex Media <contact@fullduplex.media>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Software Distribution
Requires-Dist: boto3
Requires-Dist: keyring
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# git-buckets-keyring

A stateless [keyring](https://pypi.org/project/keyring/) backend for git-buckets package registries. It turns
your ambient AWS profile into a short-lived package token so `uv sync` and `pip install` can reach a private
index with no login step.

It stores nothing. On each lookup it SigV4-signs an `sts:GetCallerIdentity` call with your profile, trades that
proof for a 1-hour token at `https://<host>/auth/token`, and hands the token to the client as the HTTP Basic
password. Tokens are cached in-process only, never on disk.

## Setup

Once per machine:

```sh
uv tool install git-buckets-keyring
export UV_KEYRING_PROVIDER=subprocess         # or tool.uv.keyring-provider = "subprocess"
export GB_KEYRING_HOSTS=git.example.cloud     # hosts this backend is allowed to answer for
export GB_KEYRING_PROFILE=my-profile          # optional: the AWS profile to mint with
```

Then in the consuming project's `pyproject.toml`:

```toml
[[tool.uv.index]]
name = "demos"
url = "https://gb@git.example.cloud/packages/demos/pypi/"
explicit = true

[tool.uv.sources]
demos-cli = { index = "demos" }
```

The `gb@` in the URL is load-bearing: uv only performs keyring discovery when the index URL carries a username.

## GB_KEYRING_HOSTS

A comma-separated allowlist of hostnames, empty by default. The backend returns `None` for every host that is not
listed, and for every username other than `gb`, so it is inert on other machines and other indexes. It is an
allowlist, not a target: the host used is the one the client asked about, admitted only if it is listed.

## GB_KEYRING_PROFILE

The AWS profile to mint with, overriding `AWS_PROFILE` and the rest of the default chain. Unset, the backend uses
the ambient session as before. Set it when a project works against one AWS account while pulling packages entitled
through another, so `AWS_PROFILE` is already pointed somewhere else. A profile that does not exist is treated like
any other failure: no token, no exception.

## GB_KEYRING_DEBUG

Set to anything non-empty to have the backend print one line on **stderr** explaining why it declined — wrong
username, host not on the allowlist, or the mint failed and why. Off by default, and stdout stays clean either way
so `keyring get` output is still just the token. The token is never printed to stderr.

## Printing a token by hand

```sh
keyring get https://git.example.cloud/packages/demos/pypi/ gb
```

## If the bundled `keyring` script collides

`uv tool install git-buckets-keyring` installs a `keyring` executable of its own. If that clashes with an existing
one, install the other way round:

```sh
uv tool install keyring --with git-buckets-keyring
```
