Metadata-Version: 2.4
Name: git-buckets-keyring
Version: 0.1.0
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
```

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.

## 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
```
