git-buckets 0.2.0__tar.gz

git_buckets-0.2.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.3
+Name: git-buckets
+Version: 0.2.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
+Requires-Dist: click
+Requires-Dist: fduplex-git-remote-s3
+Requires-Dist: keyring
+Requires-Dist: packaging
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# git-buckets
+
+Git over S3: clone, fetch and push repositories backed by an S3 bucket.
+
+The end-user surface lands in Increment 3 of the refactor. See the repo root `README.md`.

git_buckets-0.2.0/README.md

@@ -0,0 +1,5 @@
+# git-buckets
+
+Git over S3: clone, fetch and push repositories backed by an S3 bucket.
+
+The end-user surface lands in Increment 3 of the refactor. See the repo root `README.md`.

git_buckets-0.2.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "git-buckets"
+version = "0.2.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",
+]
+
+[[project.authors]]
+name = "Full Duplex Media"
+email = "contact@fullduplex.media"
+
+[project.license]
+text = "Apache 2.0"
+
+[project.entry-points."keyring.backends"]
+git-buckets = "git_buckets.keyring.backend"
+
+[project.scripts]
+gb = "git_buckets.cli:cli"
+keyring = "keyring.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12.0"]
+build-backend = "uv_build"

git_buckets-0.2.0/pyproject.toml.orig

@@ -0,0 +1,28 @@
+[project]
+name = "git-buckets"
+version = "0.2.0"
+description = "Git over S3: clone, fetch and push repositories backed by an S3 bucket."
+authors = [
+  { name = 'Full Duplex Media', email = 'contact@fullduplex.media' }
+]
+readme = 'README.md'
+license = { text = 'Apache 2.0' }
+requires-python = ">=3.14"
+dependencies = [
+    "boto3",
+    "click",
+    "fduplex-git-remote-s3",
+    "keyring",
+    "packaging",
+]
+
+[project.entry-points."keyring.backends"]
+git-buckets = "git_buckets.keyring.backend"
+
+[project.scripts]
+gb = "git_buckets.cli:cli"
+keyring = "keyring.cli:main"
+
+[build-system]
+requires = ['uv_build>=0.11.0,<0.12.0']
+build-backend = 'uv_build'

git_buckets-0.2.0/src/git_buckets/cli.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+
+import boto3
+import click
+
+from .publish import Distribution, PublishError, default_distributions, parse_distributions, publish, resolve_target
+
+
+def _session(profile: str | None) -> boto3.Session:
+    return boto3.Session(profile_name=profile) if profile else boto3.Session()
+
+
+_profile_option = click.option('--profile', default=None, help='AWS profile to use (overrides AWS_PROFILE).')
+
+
+@click.group()
+@click.version_option(package_name='git-buckets')
+def cli() -> None:
+    """Git over S3."""
+
+
+@cli.command(name='publish')
+@click.option('--bucket', 'bucket', default=None, help='Registry bucket alias (<bucket-name>.<web-domain>).')
+@click.option('--repo', 'repo', default=None, help='Repo within the bucket that owns the package.')
+@click.option('--remote', 'remote', default='origin', show_default=True, help='Git remote to read the target from.')
+@_profile_option
+@click.option('--dry-run', is_flag=True, help='Resolve, mint and pre-check for real, but upload nothing.')
+@click.argument('dists', nargs=-1, type=click.Path(path_type=Path))
+def publish_command(
+    bucket: str | None,
+    repo: str | None,
+    remote: str,
+    profile: str | None,
+    dry_run: bool,
+    dists: tuple[Path, ...],
+) -> None:
+    """Publish already-built distributions to a git-bucket's package registry.
+
+    Not manifest-bound: run it from any Python project. With no flags the target comes from the project's
+    s3://[profile@]bucket-alias/repo git remote, and with no paths the batch is dist/*.
+
+    The AWS profile is resolved in order: --profile if given, else the profile embedded in the remote's
+    s3:// URL, else AWS_PROFILE from the environment, else the default credential chain.
+    """
+    if bucket is None:
+        click.echo(f'Resolving git remote {remote}...')
+    try:
+        target = resolve_target(bucket=bucket, repo=repo, remote=remote, profile=profile)
+        click.echo(f'Bucket:  {target.alias}')
+        click.echo(f'Repo:    {target.repo}')
+        click.echo(f'Profile: {target.profile or "(ambient)"}')
+        distributions: list[Distribution] = parse_distributions(list(dists) or default_distributions())
+        result = publish(_session(target.profile), target, distributions, dry_run=dry_run, report=click.echo)
+    except PublishError as x:
+        raise click.ClickException(str(x)) from None
+
+    if result.dry_run:
+        click.echo('Dry run: nothing was uploaded.')

git_buckets-0.2.0/src/git_buckets/keyring/__init__.py

@@ -0,0 +1 @@
+"""Keyring backend and STS proof builder for git-buckets package registries."""

git_buckets-0.2.0/src/git_buckets/keyring/backend.py

@@ -0,0 +1,120 @@
+"""A stateless keyring backend that turns an ambient AWS profile into a git-buckets package token.
+
+The backend is inert unless the caller's host is on the ``GB_KEYRING_HOSTS`` allowlist and the username is the
+``gb`` sentinel, so installing it can never change what any other index or tool resolves.
+"""
+
+import os
+import sys
+from urllib.parse import urlsplit
+
+import boto3
+from keyring.backend import KeyringBackend
+from keyring.compat import properties
+from keyring.credentials import Credential, SimpleCredential
+from keyring.errors import PasswordDeleteError, PasswordSetError
+
+from .proof import mint_token
+
+_HOSTS_ENV = 'GB_KEYRING_HOSTS'
+_PROFILE_ENV = 'GB_KEYRING_PROFILE'
+_DEBUG_ENV = 'GB_KEYRING_DEBUG'
+_USERNAME = 'gb'
+
+# Above the OS keyrings (5) so it wins inside uv's isolated tool environment; the host allowlist, not the
+# priority, is what keeps it from answering for anything else.
+_PRIORITY = 9.9
+
+_tokens: dict[tuple[str, str], str] = {}
+
+
+def _allowed_hosts() -> set[str]:
+    raw = os.environ.get(_HOSTS_ENV, '')
+    return {host.strip().lower() for host in raw.split(',') if host.strip()}
+
+
+def _profile() -> str:
+    return os.environ.get(_PROFILE_ENV, '').strip()
+
+
+def _debug(message: str) -> None:
+    """Explain a refusal on stderr; stdout carries the password and must stay clean."""
+    if os.environ.get(_DEBUG_ENV):
+        print(f'git-buckets-keyring: {message}', file=sys.stderr)
+
+
+def _host_of(service: str) -> str | None:
+    """Return the hostname from a full index URL or a bare host, or None when there isn't one."""
+    if not service:
+        return None
+    candidate = service if '://' in service else f'//{service}'
+    try:
+        return urlsplit(candidate).hostname
+    except ValueError:
+        return None
+
+
+def _scheme_of(service: str) -> str:
+    """Return the lowercased scheme when the service string names one explicitly, else ''.
+
+    A bare host (no ``://``) carries no scheme at all, which is not the same as an insecure one.
+    """
+    if not service or '://' not in service:
+        return ''
+    try:
+        return urlsplit(service).scheme.lower()
+    except ValueError:
+        return ''
+
+
+class GitBucketsBackend(KeyringBackend):
+    """Mint a short-lived package token for an allowlisted git-buckets deployment."""
+
+    @properties.classproperty
+    def priority(cls) -> float:  # noqa: N805
+        return _PRIORITY
+
+    def get_password(self, service: str, username: str) -> str | None:
+        if username != _USERNAME:
+            _debug(f'declined: username {username!r} is not {_USERNAME!r}')
+            return None
+        host = _host_of(service)
+        allowed = _allowed_hosts()
+        if host is None:
+            _debug(f'declined: no host in service {service!r}')
+            return None
+        if host.lower() not in allowed:
+            listed = ', '.join(sorted(allowed)) if allowed else f'empty (set {_HOSTS_ENV})'
+            _debug(f'declined: host {host!r} is not on the {_HOSTS_ENV} allowlist: {listed}')
+            return None
+        scheme = _scheme_of(service)
+        if scheme and scheme != 'https':
+            _debug(f'declined: scheme {scheme!r} for host {host!r} is not https')
+            return None
+
+        profile = _profile()
+        cached = _tokens.get((host, profile))
+        if cached is not None:
+            return cached
+        try:
+            # Inside the try: a missing or typo'd profile must fail closed like any other mint failure.
+            session = boto3.Session(profile_name=profile) if profile else None
+            token = mint_token(host, session)
+        except Exception as x:
+            # A raising backend breaks the client's whole credential lookup; no profile means no answer.
+            _debug(f'declined: mint for {host!r} failed ({type(x).__name__}: {x})')
+            return None
+        _tokens[(host, profile)] = token
+        return token
+
+    def get_credential(self, service: str, username: str | None) -> Credential | None:
+        password = self.get_password(service, username or _USERNAME)
+        if password is None:
+            return None
+        return SimpleCredential(_USERNAME, password)
+
+    def set_password(self, service: str, username: str, password: str) -> None:
+        raise PasswordSetError('git-buckets keyring is stateless; tokens are minted, not stored')
+
+    def delete_password(self, service: str, username: str) -> None:
+        raise PasswordDeleteError('git-buckets keyring is stateless; there is nothing to delete')

git_buckets-0.2.0/src/git_buckets/keyring/proof.py

@@ -0,0 +1,90 @@
+"""Build a SigV4-signed ``sts:GetCallerIdentity`` proof and trade it for a git-buckets package token.
+
+The proof is the whole authentication: the server validates the components, rebuilds the call and replays it
+against real STS, so AWS performs the signature check. ``X-Gb-Server-Id`` is added before signing, which is what
+binds the proof to one deployment.
+"""
+
+import json
+from hashlib import sha256
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+import boto3
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+
+_STS_BODY = 'Action=GetCallerIdentity&Version=2011-06-15'
+_SERVER_ID_HEADER = 'X-Gb-Server-Id'
+_DEFAULT_REGION = 'us-east-1'
+_TIMEOUT_S = 15
+
+
+class ProofError(Exception):
+    """The proof could not be built, sent, or exchanged for a token."""
+
+
+def build_proof(session: Any, host: str) -> dict[str, Any]:
+    """Return the signed request bundle ``{'method', 'url', 'headers', 'body'}`` for ``host``.
+
+    Hand-rolled rather than presigned: boto3 has never supported presigning GetCallerIdentity (boto3#756).
+    """
+    credentials = session.get_credentials()
+    if credentials is None:
+        raise ProofError('no AWS credentials')
+    region = session.region_name or _DEFAULT_REGION
+
+    request = AWSRequest(
+        method='POST',
+        url=f'https://sts.{region}.amazonaws.com/',
+        data=_STS_BODY,
+        headers={
+            'Content-Type': 'application/x-www-form-urlencoded',
+            # Signed, not merely sent: presence inside SignedHeaders is what makes the audience unforgeable.
+            _SERVER_ID_HEADER: host,
+        },
+    )
+    SigV4Auth(credentials, 'sts', region).add_auth(request)
+
+    return {
+        'method': 'POST',
+        'url': request.url,
+        'headers': dict(request.headers),
+        'body': _STS_BODY,
+    }
+
+
+def mint_token(host: str, session: Any = None) -> str:
+    """Exchange a freshly-signed proof for a short-lived package token at ``https://<host>/auth/token``."""
+    proof = build_proof(session if session is not None else boto3.Session(), host)
+    body = json.dumps(proof).encode()
+    request = Request(
+        f'https://{host}/auth/token',
+        data=body,
+        method='POST',
+        headers={
+            'Content-Type': 'application/json',
+            # CloudFront OAC rejects a body-carrying POST without this with a bare edge 403.
+            'x-amz-content-sha256': sha256(body).hexdigest(),
+        },
+    )
+
+    try:
+        with urlopen(request, timeout=_TIMEOUT_S) as response:
+            status = response.status
+            payload = response.read()
+    except HTTPError as x:
+        raise ProofError(f'token request failed with status {x.code}') from None
+    except (URLError, OSError) as x:
+        raise ProofError(f'token request failed: {x}') from None
+
+    if not 200 <= status < 300:
+        raise ProofError(f'token request failed with status {status}')
+    try:
+        token = json.loads(payload)['token']
+    except (ValueError, KeyError, TypeError):
+        raise ProofError('token response is malformed') from None
+    if not isinstance(token, str) or not token:
+        raise ProofError('token response is malformed')
+    return token

git_buckets-0.2.0/src/git_buckets/publish.py

@@ -0,0 +1,352 @@
+"""Transport distributions built elsewhere into a repo's ``<repo>/packages/`` prefix.
+
+``gb publish`` is not manifest-bound: its habitat is an arbitrary Python project folder, so everything it needs
+comes from flags or from the project's ``s3://`` git remote. It never builds, never invokes a backend and never
+reimplements packaging semantics — filename grammar is ``packaging``'s problem, and the upload is a direct
+conditional PutObject against Access-Grants-vended credentials rather than a legacy upload API.
+
+The registry pre-check runs before any upload and a non-answer is fatal: publish does not proceed on an
+unanswered ownership question.
+"""
+
+import subprocess
+from base64 import b64encode
+from collections.abc import Callable
+from dataclasses import dataclass
+from json import loads
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+from zipfile import BadZipFile, ZipFile
+
+from git_remote_s3 import BucketAliasError, parse_git_url, resolve_bucket_alias
+from git_remote_s3.common import register_s3_access_grants
+from packaging.utils import (
+    InvalidSdistFilename,
+    InvalidVersion,
+    InvalidWheelFilename,
+    canonicalize_name,
+    parse_sdist_filename,
+    parse_wheel_filename,
+)
+
+from .keyring.proof import ProofError, mint_token
+
+_METADATA_SUFFIX = '.metadata'
+_SDIST_SUFFIXES = ('.tar.gz', '.zip')
+_TIMEOUT_S = 30
+# 409 ConditionalRequestConflict is the one conditional-write failure AWS documents as retryable.
+_CONFLICT_ATTEMPTS = 3
+
+
+class PublishError(Exception):
+    """Publishing could not proceed. Every instance is a loud, actionable CLI failure."""
+
+
+def _silent(_message: str) -> None:
+    """Default progress reporter: publish() is a library call, so it says nothing unless asked to."""
+
+
+@dataclass(frozen=True)
+class Target:
+    """Where a batch is going: the manifest bucket name, the physical S3 bucket, the host and the repo."""
+
+    manifest_bucket: str
+    bucket: str
+    host: str
+    repo: str
+    profile: str | None
+
+    @property
+    def alias(self) -> str:
+        """The registry alias the publisher actually knows, rebuilt from the halves ``_split_alias`` produced."""
+        return f'{self.manifest_bucket}.{self.host}'
+
+
+@dataclass(frozen=True)
+class Distribution:
+    path: Path
+    name: str
+    version: str
+    is_wheel: bool
+
+    @property
+    def filename(self) -> str:
+        return self.path.name
+
+
+@dataclass(frozen=True)
+class Upload:
+    key: str
+    body: bytes
+
+
+@dataclass(frozen=True)
+class PublishResult:
+    target: Target
+    ownership: dict[str, bool]
+    keys: list[str]
+    dry_run: bool
+
+
+def _remote_url(remote: str) -> str | None:
+    try:
+        completed = subprocess.run(
+            ['git', 'config', '--get', f'remote.{remote}.url'],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if completed.returncode != 0:
+        return None
+    return completed.stdout.strip() or None
+
+
+def _no_target_error(remote: str) -> PublishError:
+    return PublishError(
+        f'cannot resolve where to publish: no --bucket/--repo given and git remote {remote!r} is not an '
+        f's3:// git-buckets URL (looked in {Path.cwd()}). Pass --bucket <bucket-name>.<web-domain> and '
+        '--repo <repo>, or run from a checkout cloned from a git-bucket.'
+    )
+
+
+def _split_alias(alias: str, remote: str) -> tuple[str, str, str]:
+    """``<manifest-bucket>.<web-domain>`` → (manifest bucket, host, physical bucket).
+
+    The alias is the record git-buckets itself renders as ``{{ bucket.name }}.{{ web.domain }}``, so the first
+    dot splits it exactly. The registry pre-check needs the host and the manifest name; only the upload uses the
+    physical bucket the TXT record resolves to.
+    """
+    if '.' not in alias:
+        raise PublishError(
+            f'bucket {alias!r} is a physical bucket name, not a registry alias: publish needs the '
+            '<bucket-name>.<web-domain> form (e.g. demos.git.example.com) because the ownership pre-check and '
+            'the package token are served by the deployment at that host.'
+        )
+    manifest_bucket, host = alias.split('.', 1)
+
+    try:
+        bucket = resolve_bucket_alias(alias, remote)
+    except BucketAliasError as x:
+        raise PublishError(f'cannot resolve bucket alias {alias!r}: {x}') from None
+    if '.' in bucket:
+        # Manifest bucket names can never contain a dot, so a dotted answer means alias resolution was opted
+        # out of (s3.dns-alias / remote.<name>.s3-dns-alias) and the host came back verbatim.
+        raise PublishError(
+            f'cannot resolve bucket alias {alias!r}: DNS alias resolution is disabled for this remote, so the '
+            'alias host would be used as a bucket name. Re-enable it (git config --unset s3.dns-alias, or the '
+            f'remote.{remote}.s3-dns-alias key) to publish.'
+        )
+    return manifest_bucket, host, bucket
+
+
+def resolve_target(
+    *, bucket: str | None, repo: str | None, remote: str = 'origin', profile: str | None = None
+) -> Target:
+    """Explicit flags, else the project's ``s3://`` git remote, else a loud error naming both options."""
+    if (bucket is None) != (repo is None):
+        raise PublishError('--bucket and --repo must be given together (or neither, to use the git remote)')
+
+    url_profile: str | None = None
+    if bucket is None:
+        _scheme, url_profile, bucket, repo = parse_git_url(_remote_url(remote))
+    if bucket is None or not repo:
+        raise _no_target_error(remote)
+
+    manifest_bucket, host, physical = _split_alias(bucket, remote)
+    return Target(
+        manifest_bucket=manifest_bucket,
+        bucket=physical,
+        host=host,
+        repo=repo.strip('/'),
+        profile=profile if profile is not None else url_profile,
+    )
+
+
+def default_distributions(root: Path | None = None) -> list[Path]:
+    """``dist/*`` — the conventional output directory, whatever built it."""
+    dist = (root or Path.cwd()) / 'dist'
+    if not dist.is_dir():
+        raise PublishError(f'no distributions given and no {dist} directory: build first, or pass paths')
+    paths = sorted(path for path in dist.iterdir() if path.is_file())
+    if not paths:
+        raise PublishError(f'no distributions given and {dist} is empty: build first, or pass paths')
+    return paths
+
+
+def parse_distribution(path: Path) -> Distribution:
+    """One file → (canonical name, version) via ``packaging``; never a hand-rolled filename regex."""
+    filename = path.name
+    try:
+        if filename.endswith('.whl'):
+            name, version, _build, _tags = parse_wheel_filename(filename)
+            return Distribution(path=path, name=str(name), version=str(version), is_wheel=True)
+        if filename.endswith(_SDIST_SUFFIXES):
+            name, version = parse_sdist_filename(filename)
+            return Distribution(path=path, name=str(name), version=str(version), is_wheel=False)
+    except (InvalidWheelFilename, InvalidSdistFilename, InvalidVersion) as x:
+        raise PublishError(f'{filename}: not a valid distribution filename ({x})') from None
+    raise PublishError(f'{filename}: unknown distribution type (expected a .whl, .tar.gz or .zip)')
+
+
+def parse_distributions(paths: list[Path]) -> list[Distribution]:
+    """Parse a batch and reject one that does not belong to a single project."""
+    if not paths:
+        raise PublishError('no distributions to publish')
+    missing = [str(path) for path in paths if not path.is_file()]
+    if missing:
+        raise PublishError(f'no such distribution file(s): {", ".join(missing)}')
+
+    distributions = [parse_distribution(path) for path in paths]
+    names = sorted({dist.name for dist in distributions})
+    if len(names) > 1:
+        raise PublishError(
+            f'this batch spans {len(names)} projects ({", ".join(names)}): one publish targets one repo, so it '
+            'must carry one project. Pass explicit paths, or run gb publish from the member directory (a uv '
+            'workspace build drops every member into one shared dist/).'
+        )
+    return distributions
+
+
+def wheel_metadata(path: Path) -> bytes:
+    """The wheel's ``*.dist-info/METADATA`` member, for the PEP 658 sidecar."""
+    try:
+        with ZipFile(path) as archive:
+            members = [
+                name for name in archive.namelist() if name.endswith('.dist-info/METADATA') and name.count('/') == 1
+            ]
+            if len(members) != 1:
+                raise PublishError(f'{path.name}: expected exactly one .dist-info/METADATA, found {len(members)}')
+            return archive.read(members[0])
+    except (BadZipFile, OSError) as x:
+        raise PublishError(f'{path.name}: cannot read wheel ({x})') from None
+
+
+def plan_uploads(target: Target, distributions: list[Distribution]) -> list[Upload]:
+    """The exact objects a batch writes: the distribution, plus a metadata sidecar for wheels only."""
+    uploads: list[Upload] = []
+    for dist in distributions:
+        prefix = f'{target.repo}/packages/{canonicalize_name(dist.name)}/'
+        uploads.append(Upload(key=f'{prefix}{dist.filename}', body=dist.path.read_bytes()))
+        if dist.is_wheel:
+            uploads.append(Upload(key=f'{prefix}{dist.filename}{_METADATA_SUFFIX}', body=wheel_metadata(dist.path)))
+    return uploads
+
+
+def check_ownership(target: Target, name: str, token: str) -> bool:
+    """The registry's one-bit answer for ``name`` in this bucket. Any non-answer is fatal, never a default."""
+    url = (
+        f'https://{target.host}/packages/{quote(target.manifest_bucket)}/pypi/{quote(canonicalize_name(name))}/'
+        f'?ownership={quote(target.repo, safe="")}'
+    )
+    # The edge renames Authorization into X-Gb-Authorization; the client only ever sends the standard header.
+    credential = b64encode(f'gb:{token}'.encode()).decode()
+    request = Request(url, method='GET', headers={'Authorization': f'Basic {credential}'})
+
+    try:
+        with urlopen(request, timeout=_TIMEOUT_S) as response:
+            status = response.status
+            payload = response.read()
+    except HTTPError as x:
+        raise PublishError(f'ownership pre-check for {name!r} failed with status {x.code}') from None
+    except (URLError, OSError) as x:
+        raise PublishError(f'ownership pre-check for {name!r} failed: registry unreachable ({x})') from None
+
+    if not 200 <= status < 300:
+        raise PublishError(f'ownership pre-check for {name!r} failed with status {status}')
+    try:
+        available = loads(payload)['available']
+    except (ValueError, KeyError, TypeError):
+        raise PublishError(f'ownership pre-check for {name!r} returned a malformed answer') from None
+    return bool(available)
+
+
+def _mint(target: Target, session: Any) -> str:
+    try:
+        return mint_token(target.host, session)
+    except ProofError as x:
+        raise PublishError(f'cannot mint a package token for {target.host}: {x}') from None
+
+
+def _human_size(size: int) -> str:
+    value = float(size)
+    for unit in ('B', 'KiB', 'MiB', 'GiB'):
+        if value < 1024 or unit == 'GiB':
+            return f'{int(value)} {unit}' if unit == 'B' else f'{value:.1f} {unit}'
+        value /= 1024
+    return f'{value:.1f} GiB'
+
+
+def _put(s3: Any, target: Target, upload: Upload) -> None:
+    for attempt in range(1, _CONFLICT_ATTEMPTS + 1):
+        try:
+            s3.put_object(
+                Bucket=target.bucket,
+                Key=upload.key,
+                Body=upload.body,
+                IfNoneMatch='*',
+                ChecksumAlgorithm='SHA256',
+            )
+            return
+        except s3.exceptions.ClientError as x:
+            code = x.response.get('Error', {}).get('Code')
+            if code == 'PreconditionFailed':
+                raise PublishError(
+                    f'{upload.key.rsplit("/", 1)[-1]} is already published at s3://{target.alias}/{upload.key}: '
+                    'published artifacts are immutable, so bump the version and re-publish.'
+                ) from None
+            if code == 'ConditionalRequestConflict' and attempt < _CONFLICT_ATTEMPTS:
+                continue
+            raise PublishError(f'upload of {upload.key} failed: {x}') from None
+
+
+def publish(
+    session: Any,
+    target: Target,
+    distributions: list[Distribution],
+    *,
+    dry_run: bool = False,
+    report: Callable[[str], None] = _silent,
+) -> PublishResult:
+    """Mint, pre-check every distinct name, then conditionally PUT each object. Nothing uploads on a dry run.
+
+    ``report`` receives one short line per phase as it happens, so a caller can stream progress through the long
+    silent stretches (token mint, pre-check, credential vending, the uploads themselves).
+    """
+    uploads = plan_uploads(target, distributions)
+
+    report('Minting a package token...')
+    token = _mint(target, session)
+
+    ownership: dict[str, bool] = {}
+    for name in sorted({d.name for d in distributions}):
+        report(f'Checking who owns {name}...')
+        ownership[name] = check_ownership(target, name, token)
+        report(f'Owner:   {name}: {"available" if ownership[name] else "claimed"}')
+    claimed = [name for name, available in ownership.items() if not available]
+    if claimed:
+        raise PublishError(
+            f'{", ".join(claimed)}: already claimed by another repo in bucket {target.manifest_bucket!r}. '
+            'Publish it from the repo that owns the name, or rename the project.'
+        )
+
+    keys = [upload.key for upload in uploads]
+    if dry_run:
+        report('Would write:')
+        for key in keys:
+            report(f'  s3://{target.alias}/{key}')
+        return PublishResult(target=target, ownership=ownership, keys=keys, dry_run=True)
+
+    report('Vending upload credentials...')
+    s3 = session.client('s3')
+    register_s3_access_grants(s3, session)
+    report('Writing:')
+    for upload in uploads:
+        report(f'  uploading {upload.key.rsplit("/", 1)[-1]} ({_human_size(len(upload.body))})...')
+        _put(s3, target, upload)
+        report(f'  s3://{target.alias}/{upload.key}')
+    return PublishResult(target=target, ownership=ownership, keys=keys, dry_run=False)