git-buckets 0.2.0__tar.gz → 0.3.0__tar.gz

git_buckets-0.3.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.3
+Name: git-buckets
+Version: 0.3.0
+Summary: Git over S3: clone, fetch and push repositories backed by an S3 bucket.
+Author: Full Duplex Media
+Author-email: Full Duplex Media <contact@fullduplex.media>
+License: Apache 2.0
+Requires-Dist: boto3>=1.43.77
+Requires-Dist: click>=8.4.2
+Requires-Dist: keyring>=25.7.0
+Requires-Dist: keyring-pass>=0.9.3
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# git-buckets
+
+`gb` is the end-user CLI for a git-buckets deployment: git repos and Python package indexes over HTTPS, backed by S3.
+Someone else runs the deployment. You log in once and then use stock git and uv.
+
+## Install
+
+Prereqs:
+- git (≥ 2.13, ≥ 2.40 for bundle-accelerated clones)
+- [git-lfs](https://git-lfs.com/)
+- Python ≥ 3.14
+
+```sh
+uv tool install git-buckets
+# or: pipx install git-buckets
+```
+
+## First login
+
+```sh
+gb login git.example.com
+```
+
+Once per deployment, never per bucket. This signs you in through the browser, stores the session, writes the
+credential-helper stanza for `https://*.git.example.com` plus `transfer.bundleURI = true` into your global gitconfig,
+and records the deployment.
+
+On a box with no browser, `--no-browser` prints a URL to open elsewhere and reads the code back at a masked prompt.
+
+```sh
+gb auth status              # deployments known, the user on each, where each secret lives
+gb logout git.example.com   # revoke the session token, erase the stored credentials
+```
+
+## Daily use
+
+Remote URLs are `https://<bucket>.<deployment-domain>/<repo>`: the first hostname label is the bucket's public label,
+the path is the repo name, as deep as you like. `git clone https://my-bucket.git.example.com/tools/cli/my-project`, then
+fetch, pull and push are stock git as well.
+
+**New repos are made by pushing.** There is no create command, simply push to a new path on an existing bucket and
+you've created a new repo.
+
+```sh
+git init && git remote add origin https://my-bucket.git.example.com/tools/gui/my-new-project
+git push -u origin main
+```
+
+**Signed commits.** Buckets require them by default: every commit a push introduces is checked, so set up signing before
+the first push (`gpg.format ssh` + `user.signingkey` + `commit.gpgsign` is the short route).
+
+**LFS.** Downloads at any size and uploads up to 5 GB per file need nothing installed: objects come from the same host
+under the same credential. Above 5 GB an upload needs gb's transfer agent, which also makes both directions parallel and
+resumable. Once per repo:
+
+```sh
+gb lfs install [--remote <name>]
+```
+
+**Packages.** Each bucket is one Python index. In the consuming project's `pyproject.toml`:
+
+```toml
+[[tool.uv.index]]
+name = "my-bucket-index"
+url = "https://gb@my-bucket.git.example.com/packages/pypi/"
+explicit = true
+
+[tool.uv.sources]
+my-package = { index = "my-bucket-index" }
+
+[tool.uv]
+keyring-provider = "subprocess"
+```
+
+Then just `uv sync` as normal. The `gb@` is **required**: uv only does keyring discovery when the index URL carries a
+username.
+
+Publishing needs one more line on the index, in the publishing project rather than the consuming one, naming the repo
+the package belongs to:
+
+```toml
+[[tool.uv.index]]
+name = "my-bucket-index"
+url = "https://gb@my-bucket.git.example.com/packages/pypi/"
+publish-url = "https://gb@my-bucket.git.example.com/packages/pypi/upload/tools/cli/my-project/"
+explicit = true
+```
+
+Then `uv build && uv publish --index my-bucket-index`. Push rights are publish rights: the repo in the upload URL is the
+one your token must reach with `rw`.
+
+**CI.** A runner has no login session: it assumes the team's token role via OIDC and sets
+`UV_KEYRING_PROVIDER=subprocess` and `GB_KEYRING_HOSTS="*.git.example.com"`. `GB_KEYRING_HOSTS` is CI only, never needed
+on a user machine.
+
+## Repo lifecycle
+
+Every subcommand takes `<bucket>/<repo>`, plus `-H/--host <domain>` when more than one deployment is registered.
+
+```sh
+gb repo list
+gb repo info my-bucket/tools/cli/my-project          # head, refs, size, last push; -v lists every ref
+gb repo protect my-bucket/tools/cli/my-project main  # blocks delete while the ref exists
+gb repo unprotect my-bucket/tools/cli/my-project main
+gb repo delete my-bucket/tools/cli/my-project --yes  # without --yes it only prints what would go
+```
+
+Delete takes the repo's LFS objects, locks, bundles, packages and rendered web tree with it. The undo path is S3
+versioning on the operator's side, not a `gb` command. There is no rename.
+
+## Where the secrets live
+
+The refresh token (one year, fixed from sign-in) goes in your OS keyring, or in `~/.config/gb/hosts.yml` at 0600 when no
+keyring works: gb says which, once. On a headless Linux box, `pass` + gpg-agent is the supported keyring. The hourly ID
+and session tokens are just caches under `~/.local/state/gb/<domain>/`.
+
+## Troubleshooting
+
+- git prompts for a username and password: the host isn't registered. `gb auth status`, then `gb login`.
+- `the session for <domain> has expired`: the refresh token is past its year, or was revoked. Log in again.
+- A push is refused but a fetch works: your grant on that prefix is read-only.
+- A package index won't authenticate: `GB_KEYRING_DEBUG=1 uv sync` prints why the keyring backend declined.

git_buckets-0.3.0/README.md

@@ -0,0 +1,122 @@
+# git-buckets
+
+`gb` is the end-user CLI for a git-buckets deployment: git repos and Python package indexes over HTTPS, backed by S3.
+Someone else runs the deployment. You log in once and then use stock git and uv.
+
+## Install
+
+Prereqs:
+- git (≥ 2.13, ≥ 2.40 for bundle-accelerated clones)
+- [git-lfs](https://git-lfs.com/)
+- Python ≥ 3.14
+
+```sh
+uv tool install git-buckets
+# or: pipx install git-buckets
+```
+
+## First login
+
+```sh
+gb login git.example.com
+```
+
+Once per deployment, never per bucket. This signs you in through the browser, stores the session, writes the
+credential-helper stanza for `https://*.git.example.com` plus `transfer.bundleURI = true` into your global gitconfig,
+and records the deployment.
+
+On a box with no browser, `--no-browser` prints a URL to open elsewhere and reads the code back at a masked prompt.
+
+```sh
+gb auth status              # deployments known, the user on each, where each secret lives
+gb logout git.example.com   # revoke the session token, erase the stored credentials
+```
+
+## Daily use
+
+Remote URLs are `https://<bucket>.<deployment-domain>/<repo>`: the first hostname label is the bucket's public label,
+the path is the repo name, as deep as you like. `git clone https://my-bucket.git.example.com/tools/cli/my-project`, then
+fetch, pull and push are stock git as well.
+
+**New repos are made by pushing.** There is no create command, simply push to a new path on an existing bucket and
+you've created a new repo.
+
+```sh
+git init && git remote add origin https://my-bucket.git.example.com/tools/gui/my-new-project
+git push -u origin main
+```
+
+**Signed commits.** Buckets require them by default: every commit a push introduces is checked, so set up signing before
+the first push (`gpg.format ssh` + `user.signingkey` + `commit.gpgsign` is the short route).
+
+**LFS.** Downloads at any size and uploads up to 5 GB per file need nothing installed: objects come from the same host
+under the same credential. Above 5 GB an upload needs gb's transfer agent, which also makes both directions parallel and
+resumable. Once per repo:
+
+```sh
+gb lfs install [--remote <name>]
+```
+
+**Packages.** Each bucket is one Python index. In the consuming project's `pyproject.toml`:
+
+```toml
+[[tool.uv.index]]
+name = "my-bucket-index"
+url = "https://gb@my-bucket.git.example.com/packages/pypi/"
+explicit = true
+
+[tool.uv.sources]
+my-package = { index = "my-bucket-index" }
+
+[tool.uv]
+keyring-provider = "subprocess"
+```
+
+Then just `uv sync` as normal. The `gb@` is **required**: uv only does keyring discovery when the index URL carries a
+username.
+
+Publishing needs one more line on the index, in the publishing project rather than the consuming one, naming the repo
+the package belongs to:
+
+```toml
+[[tool.uv.index]]
+name = "my-bucket-index"
+url = "https://gb@my-bucket.git.example.com/packages/pypi/"
+publish-url = "https://gb@my-bucket.git.example.com/packages/pypi/upload/tools/cli/my-project/"
+explicit = true
+```
+
+Then `uv build && uv publish --index my-bucket-index`. Push rights are publish rights: the repo in the upload URL is the
+one your token must reach with `rw`.
+
+**CI.** A runner has no login session: it assumes the team's token role via OIDC and sets
+`UV_KEYRING_PROVIDER=subprocess` and `GB_KEYRING_HOSTS="*.git.example.com"`. `GB_KEYRING_HOSTS` is CI only, never needed
+on a user machine.
+
+## Repo lifecycle
+
+Every subcommand takes `<bucket>/<repo>`, plus `-H/--host <domain>` when more than one deployment is registered.
+
+```sh
+gb repo list
+gb repo info my-bucket/tools/cli/my-project          # head, refs, size, last push; -v lists every ref
+gb repo protect my-bucket/tools/cli/my-project main  # blocks delete while the ref exists
+gb repo unprotect my-bucket/tools/cli/my-project main
+gb repo delete my-bucket/tools/cli/my-project --yes  # without --yes it only prints what would go
+```
+
+Delete takes the repo's LFS objects, locks, bundles, packages and rendered web tree with it. The undo path is S3
+versioning on the operator's side, not a `gb` command. There is no rename.
+
+## Where the secrets live
+
+The refresh token (one year, fixed from sign-in) goes in your OS keyring, or in `~/.config/gb/hosts.yml` at 0600 when no
+keyring works: gb says which, once. On a headless Linux box, `pass` + gpg-agent is the supported keyring. The hourly ID
+and session tokens are just caches under `~/.local/state/gb/<domain>/`.
+
+## Troubleshooting
+
+- git prompts for a username and password: the host isn't registered. `gb auth status`, then `gb login`.
+- `the session for <domain> has expired`: the refresh token is past its year, or was revoked. Log in again.
+- A push is refused but a fetch works: your grant on that prefix is read-only.
+- A package index won't authenticate: `GB_KEYRING_DEBUG=1 uv sync` prints why the keyring backend declined.

{git_buckets-0.2.0 → git_buckets-0.3.0}/pyproject.toml

@@ -1,15 +1,15 @@
 [project]
 name = "git-buckets"
-version = "0.2.0"
+version = "0.3.0"
 description = "Git over S3: clone, fetch and push repositories backed by an S3 bucket."
 readme = "README.md"
 requires-python = ">=3.14"
 dependencies = [
-    "boto3",
-    "click",
-    "fduplex-git-remote-s3",
-    "keyring",
-    "packaging",
+    "boto3>=1.43.77",
+    "click>=8.4.2",
+    "keyring>=25.7.0",
+    "keyring-pass>=0.9.3",
+    "pyyaml>=6.0.3",
 ]
 
 [[project.authors]]
@@ -24,6 +24,8 @@ git-buckets = "git_buckets.keyring.backend"
 
 [project.scripts]
 gb = "git_buckets.cli:cli"
+git-credential-gb = "git_buckets.credential:main"
+git-lfs-gb = "git_buckets.lfs_agent:main"
 keyring = "keyring.cli:main"
 
 [build-system]

{git_buckets-0.2.0 → git_buckets-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "git-buckets"
-version = "0.2.0"
+version = "0.3.0"
 description = "Git over S3: clone, fetch and push repositories backed by an S3 bucket."
 authors = [
   { name = 'Full Duplex Media', email = 'contact@fullduplex.media' }
@@ -9,11 +9,11 @@ readme = 'README.md'
 license = { text = 'Apache 2.0' }
 requires-python = ">=3.14"
 dependencies = [
-    "boto3",
-    "click",
-    "fduplex-git-remote-s3",
-    "keyring",
-    "packaging",
+    "boto3>=1.43.77",
+    "click>=8.4.2",
+    "keyring>=25.7.0",
+    "keyring-pass>=0.9.3",
+    "pyyaml>=6.0.3",
 ]
 
 [project.entry-points."keyring.backends"]
@@ -21,6 +21,10 @@ git-buckets = "git_buckets.keyring.backend"
 
 [project.scripts]
 gb = "git_buckets.cli:cli"
+# `helper = gb` in a gitconfig makes git exec `git credential-gb`, i.e. this script.
+git-credential-gb = "git_buckets.credential:main"
+# lfs.customtransfer.gb.path in a repo's config points at this; `gb lfs install` writes it.
+git-lfs-gb = "git_buckets.lfs_agent:main"
 keyring = "keyring.cli:main"
 
 [build-system]

git_buckets-0.3.0/src/git_buckets/cli.py

@@ -0,0 +1,240 @@
+import click
+
+
+@click.group(context_settings=dict(help_option_names=['-h', '--help']))
+@click.version_option(package_name='git-buckets')
+def cli() -> None:
+    """git-buckets: git repos and Python package indexes over HTTPS."""
+
+
+@cli.command(name='login')
+@click.option('--no-browser', is_flag=True, help='Skip the loopback redirect; print a URL and read back a code.')
+@click.option('-v', '--verbose', is_flag=True, help='Print the full summary, not just the confirmation line.')
+@click.argument('domain')
+def login_command(domain: str, no_browser: bool, verbose: bool) -> None:
+    """Connect to a git-buckets deployment: gb login git.example.com.
+
+    Runs the browser sign-in once, stores the session, writes the credential-helper stanza into your global
+    gitconfig and records the deployment. One command per deployment, never per bucket.
+    """
+    from . import login as login_module
+    from .termio import masked_prompt
+
+    try:
+        result = login_module.login(domain, no_browser=no_browser, echo=click.echo, prompt=masked_prompt)
+    except Exception as x:
+        raise click.ClickException(str(x)) from None
+    login_module.report(result, click.echo, verbose=verbose)
+
+
+@cli.command(name='logout')
+@click.argument('domain')
+def logout_command(domain: str) -> None:
+    """Revoke the current session token and erase the stored credentials for a deployment."""
+    from . import login as login_module
+
+    try:
+        outcome = login_module.logout(domain)
+    except Exception as x:
+        raise click.ClickException(str(x)) from None
+    click.echo(f'Revoked the session token for {domain}.' if outcome['revoked'] else 'No session token to revoke.')
+    if outcome['error']:
+        click.echo(f'Warning: the revocation call failed ({outcome["error"]}); the local session is erased anyway.')
+    click.echo(f'Erased the stored refresh token and caches for {domain}.')
+    key = outcome['helper_key']
+    click.echo('The gitconfig stanza is left in place; remove it with:')
+    click.echo(f'    git config --global --unset-all {key}')
+
+
+@cli.group(name='auth')
+def auth_group() -> None:
+    """Inspect the deployments gb knows about."""
+
+
+@auth_group.command(name='status')
+def auth_status_command() -> None:
+    """The deployments known, the user on each, and where each secret is stored."""
+    from . import login as login_module
+
+    rows = login_module.status()
+    if not rows:
+        click.echo('No deployments. Run: gb login <deployment-domain>')
+        return
+    for row in rows:
+        click.echo(row['domain'])
+        click.echo(f'  user     {row["user"] or "(unknown)"}')
+        click.echo(f'  storage  {row["storage"]}')
+        click.echo(f'  session  {row["session"]}')
+
+
+@cli.group(name='lfs')
+def lfs_group() -> None:
+    """Git LFS: register gb's transfer agent for large files."""
+
+
+@lfs_group.command(name='install')
+@click.option('--remote', default='origin', show_default=True, help='Remote to check the deployment against.')
+def lfs_install_command(remote: str) -> None:
+    """Register gb's LFS transfer agent in this repo.
+
+    Nothing is required for downloads or for uploads up to 5 GB: stock git-lfs handles both. Above 5 GB
+    git-lfs has no multipart upload of its own, so the agent is the only way to push such a file at all --
+    and once it is installed both directions go through it, in parallel parts that resume rather than one
+    stream that restarts. Repo-local by design: the agent only knows how to talk to a git-buckets deployment.
+    """
+    from .lfs_agent import AgentError, install
+
+    try:
+        settings = install(remote, echo=click.echo)
+    except AgentError as x:
+        raise click.ClickException(str(x)) from None
+    click.echo(f'Registered the gb LFS transfer agent in this repo ({settings["lfs.customtransfer.gb.path"]}).')
+    click.echo('Uploads and downloads now go through gb: parallel parts, resumable, and no 5 GB upload limit.')
+
+
+@cli.command(name='lfs-agent', hidden=True)
+def lfs_agent_command() -> None:
+    """The git-lfs custom transfer process, for a config that spells it out as `gb lfs-agent`."""
+    from .lfs_agent import main
+
+    raise SystemExit(main([]))
+
+
+def _human_bytes(count: int) -> str:
+    size = float(count)
+    for unit in ('B', 'KB', 'MB', 'GB', 'TB'):
+        if size < 1024 or unit == 'TB':
+            return f'{size:.0f} {unit}' if unit == 'B' else f'{size:.1f} {unit}'
+        size /= 1024
+    return f'{size:.1f} TB'
+
+
+_HOST_OPTION = click.option('-H', '--host', default=None, help='Deployment domain; the sole gb login if omitted.')
+
+
+@cli.group(name='repo')
+def repo_group() -> None:
+    """Manage repos: list them, inspect one, protect refs, delete."""
+
+
+@repo_group.command(name='list')
+@_HOST_OPTION
+def repo_list_command(host: str | None) -> None:
+    """List the buckets and repos your token can see."""
+    from . import repo as repo_module
+
+    try:
+        domain, entry = repo_module.select_host(host)
+        result = repo_module.list_repos(domain, entry)
+    except Exception as x:
+        raise click.ClickException(str(x)) from None
+    for bucket in result.get('buckets', []):
+        click.echo(bucket['alias'])
+        if not bucket['repos']:
+            click.echo('  (no repos)')
+        for name in bucket['repos']:
+            click.echo(f'  {name}')
+
+
+@repo_group.command(name='info')
+@_HOST_OPTION
+@click.option('-v', '--verbose', is_flag=True, help='Also list every ref with its sha.')
+@click.argument('name')
+def repo_info_command(name: str, host: str | None, verbose: bool) -> None:
+    """Show one repo: gb repo info <bucket>/<repo>."""
+    from . import repo as repo_module
+
+    try:
+        bucket, path = repo_module.parse_name(name)
+        domain, entry = repo_module.select_host(host)
+        result = repo_module.info(domain, entry, bucket, path)
+    except Exception as x:
+        raise click.ClickException(str(x)) from None
+    click.echo(f'{result["bucket"]}/{result["repo"]}')
+    click.echo(f'  alias      {result["alias"]}')
+    click.echo(f'  web url    {result["web_url"]}')
+    click.echo(f'  seq        {result["seq"]}')
+    click.echo(f'  head       {result["head"]}')
+    click.echo(f'  refs       {len(result["refs"])}')
+    protected = result.get('protected') or []
+    click.echo(f'  protected  {", ".join(protected) if protected else "none"}')
+    click.echo(f'  entries    {result["entries"]}')
+    click.echo(f'  bytes      {_human_bytes(result["bytes"])}')
+    last_push = result.get('last_push')
+    if last_push:
+        click.echo(f'  last push  {last_push["by"]} at {last_push["at"]}')
+    else:
+        click.echo('  last push  (none)')
+    if verbose:
+        click.echo('  refs:')
+        for refname, sha in result['refs'].items():
+            click.echo(f'    {refname}  {sha}')
+
+
+@repo_group.command(name='delete')
+@_HOST_OPTION
+@click.option('--yes', is_flag=True, help='Actually delete; without it, nothing is touched.')
+@click.argument('name')
+def repo_delete_command(name: str, host: str | None, yes: bool) -> None:
+    """Delete a repo and everything it published: gb repo delete <bucket>/<repo>."""
+    from . import repo as repo_module
+
+    try:
+        bucket, path = repo_module.parse_name(name)
+        domain, entry = repo_module.select_host(host)
+    except Exception as x:
+        raise click.ClickException(str(x)) from None
+    if not yes:
+        click.echo(f'This deletes {name}: its LFS objects, locks, bundles, packages and rendered web tree.')
+        click.echo('S3 versioning is the undo path; a re-push re-creates the repo from nothing.')
+        raise click.ClickException('refusing to delete without confirmation; re-run with --yes')
+    try:
+        result = repo_module.delete(domain, entry, bucket, path)
+    except Exception as x:
+        raise click.ClickException(str(x)) from None
+    deleted = result['deleted']
+    click.echo(
+        f'Deleted {name}: {deleted["objects"]} object(s), {deleted["web_objects"]} web object(s), '
+        f'{deleted["pins"]} pin(s).'
+    )
+
+
+def _protect(operation: str, name: str, ref: str, host: str | None) -> None:
+    from . import repo as repo_module
+
+    call = repo_module.protect if operation == 'protect' else repo_module.unprotect
+    try:
+        bucket, path = repo_module.parse_name(name)
+        domain, entry = repo_module.select_host(host)
+        result = call(domain, entry, bucket, path, ref)
+    except Exception as x:
+        raise click.ClickException(str(x)) from None
+    protected = result.get('protected') or []
+    click.echo(f'protected: {", ".join(protected) if protected else "none"}')
+
+
+@repo_group.command(name='protect')
+@_HOST_OPTION
+@click.argument('name')
+@click.argument('ref')
+def repo_protect_command(name: str, ref: str, host: str | None) -> None:
+    """Protect a ref against deletion: gb repo protect <bucket>/<repo> <ref>."""
+    _protect('protect', name, ref, host)
+
+
+@repo_group.command(name='unprotect')
+@_HOST_OPTION
+@click.argument('name')
+@click.argument('ref')
+def repo_unprotect_command(name: str, ref: str, host: str | None) -> None:
+    """Remove a ref's protection: gb repo unprotect <bucket>/<repo> <ref>."""
+    _protect('unprotect', name, ref, host)
+
+
+@cli.command(name='credential', hidden=True)
+@click.argument('operation')
+def credential_command(operation: str) -> None:
+    """The git credential helper, for a gitconfig that spells it out as `helper = "gb credential"`."""
+    from .credential import main
+
+    raise SystemExit(main([operation]))

git_buckets-0.3.0/src/git_buckets/credential.py

@@ -0,0 +1,83 @@
+"""The git credential helper: ``git credential-gb``, which is what ``helper = gb`` in a gitconfig runs.
+
+Deliberately importless beyond the client's own small modules: this runs on every git operation against the
+deployment. A warm session token is one cached-file read; a live MicroVM behind it is not something the cache
+can promise, which is what ``wake.probe`` is for -- one cheap authenticated request, silent unless the bucket
+turns out to be cold. ``GB_NO_WAKE_PROBE=1`` drops back to the old zero-network warm path.
+"""
+
+import sys
+
+from . import hosts, session, wake
+
+_USERNAME = 'gb'
+
+
+def parse(stream) -> dict[str, str]:  # noqa: ANN001
+    """Read git's key=value block, terminated by a blank line or EOF."""
+    fields: dict[str, str] = {}
+    for raw in stream:
+        line = raw.rstrip('\n')
+        if not line:
+            break
+        key, _, value = line.partition('=')
+        if key:
+            fields[key] = value
+    return fields
+
+
+def get(fields: dict[str, str]) -> str | None:
+    """The credential block for a registered host, or None to decline.
+
+    Declining is the whole point of the host match: installing gb can never change what git sends to
+    somebody else's server.
+    """
+    if fields.get('protocol', 'https') != 'https':
+        return None
+    resolved = hosts.resolve(fields.get('host', ''))
+    if resolved is None:
+        return None
+    domain, entry = resolved
+    token = session.token(domain, entry)
+    # The bucket's own host, not the deployment domain the token was minted against: that is what git is
+    # about to talk to, and the only host the launcher's cold path answers for.
+    wake.probe(fields.get('host', domain).partition(':')[0], token)
+    return f'username={_USERNAME}\npassword={token}\n'
+
+
+def erase(fields: dict[str, str]) -> None:
+    """Drop the cached session token for a registered host, so the next ``get`` mints fresh instead of
+    handing back the same rejected value.
+
+    git-lfs runs ``reject`` (our ``erase``) then ``fill`` (our ``get``) on a 401 and retries with whatever
+    ``get`` returns, with no backoff. If ``get`` kept answering from a warm cache, that would loop forever on a
+    revoked or skewed token. This is why erase has to actually do something, unlike plain git's store/erase.
+    """
+    if fields.get('protocol', 'https') != 'https':
+        return
+    resolved = hosts.resolve(fields.get('host', ''))
+    if resolved is None:
+        return
+    domain, _entry = resolved
+    session.forget_token(domain)
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    operation = argv[0] if argv else ''
+    try:
+        fields = parse(sys.stdin)
+        if operation == 'get':
+            answer = get(fields)
+        elif operation == 'erase':
+            erase(fields)
+            answer = None
+        else:
+            # store is a no-op: gb owns its own storage and git has nothing to tell it about the session.
+            answer = None
+    except Exception as x:
+        print(f'gb: {x}', file=sys.stderr)
+        return 1
+    if answer:
+        sys.stdout.write(answer)
+    return 0