ohbin 0.2.2__py3-none-any.whl

ohbin/__init__.py

@@ -0,0 +1,95 @@
+"""ohbin — declarative GitHub-release binaries for uv projects.
+
+Declare tools in your project's pyproject:
+
+    [tool.ohbin.tools.rg]
+    repo = "BurntSushi/ripgrep"
+    version = "14.1.1"
+    binary = "rg"
+
+    [tool.ohbin.tools.rg.assets.darwin-arm64]
+    url = "https://github.com/BurntSushi/ripgrep/releases/download/14.1.1/ripgrep-14.1.1-aarch64-apple-darwin.tar.gz"
+    sha256 = "..."
+
+then `uv run ohbin run rg -- <args>`, or in-process `ohbin.ensure("rg")`.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from ohbin._engine import (
+    BinaryNotFoundError,
+    ChecksumMismatchError,
+    MissingPasswordError,
+    cache_root,
+    ensure_from,
+)
+from ohbin._errors import OhbinError
+from ohbin._manifest import ManifestError, find_pyproject, load_tool, load_tools
+from ohbin._platform import Platform, UnsupportedPlatformError, current_platform
+from ohbin._types import AssetEntry, ToolConfig
+
+__all__ = [
+    "AssetEntry",
+    "BinaryNotFoundError",
+    "ChecksumMismatchError",
+    "ManifestError",
+    "MissingPasswordError",
+    "OhbinError",
+    "Platform",
+    "ToolConfig",
+    "UnsupportedPlatformError",
+    "cache_root",
+    "current_platform",
+    "ensure",
+    "ensure_from",
+    "find_pyproject",
+    "load_tool",
+    "load_tools",
+]
+
+
+def _resolve_password(tool: str, cfg: ToolConfig, explicit: str | None) -> str | None:
+    """`--password` wins; otherwise fall back to the manifest, warning unless ack'd."""
+    if explicit is not None:
+        return explicit
+    pw = cfg.get("password")
+    if pw is not None and not cfg.get("password_committed_ok"):
+        print(
+            f"ohbin: warning: reading the password for {tool!r} from pyproject — keep it out "
+            "of public repos; set 'password_committed_ok = true' to silence this.",
+            file=sys.stderr,
+        )
+    return pw
+
+
+def ensure(tool: str, *, pyproject: Path | None = None, password: str | None = None) -> Path:
+    """Return the cached binary path for a declared tool, downloading on first use.
+
+    Reads `[tool.ohbin.tools.<tool>]` from the project's pyproject (discovered
+    from CWD, or `OHBIN_PYPROJECT`). This is the in-process entry point — call it
+    from build tooling that needs the binary's path rather than exec-ing it.
+
+    For encrypted tools, `password` (from `--password`) takes precedence over the
+    manifest's `password` field.
+    """
+    cfg = load_tool(tool, pyproject=pyproject)
+    plat = current_platform()
+    entry = cfg["assets"].get(plat.key)
+    if entry is None:
+        declared = ", ".join(sorted(cfg["assets"])) or "none"
+        msg = f"tool {tool!r} has no asset for {plat.key} (declared: {declared})"
+        raise UnsupportedPlatformError(msg)
+    encrypted = bool(cfg.get("encrypted"))
+    return ensure_from(
+        tool=tool,
+        version=cfg["version"],
+        binary=cfg["binary"],
+        url=entry["url"],
+        sha256=entry["sha256"],
+        encrypted=encrypted,
+        password=_resolve_password(tool, cfg, password) if encrypted else None,
+        binary_sha256=entry.get("binary_sha256"),
+    )

ohbin/__main__.py

@@ -0,0 +1,10 @@
+"""Allow `python -m ohbin`."""
+
+from __future__ import annotations
+
+import sys
+
+from ohbin.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ohbin/_add.py

@@ -0,0 +1,254 @@
+"""`ohbin add`: resolve a GitHub release's per-platform assets and write them into pyproject."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ohbin._engine import sha256_of_url
+from ohbin._errors import OhbinError
+from ohbin._github import Asset, fetch_release
+from ohbin._platform import (
+    ALL_ARCH_TOKENS,
+    TARGET_PLATFORMS,
+    Platform,
+    arch_tokens,
+    os_tokens,
+)
+from ohbin._types import AssetEntry, ToolConfig
+
+if TYPE_CHECKING:
+    from tomlkit.items import Item, Key, Table
+
+    # One element of a tomlkit container body: a real key + item, or (None, item)
+    # for standalone whitespace/comment lines.
+    BodyEntry = tuple[Key | None, Item]
+
+# Asset filenames that are never the binary we want.
+_DENY_SUFFIXES = (
+    ".txt",
+    ".sha256",
+    ".sha256sum",
+    ".sums",
+    ".asc",
+    ".sig",
+    ".minisig",
+    ".pem",
+    ".pubkey",
+    ".json",
+    ".deb",
+    ".rpm",
+    ".msi",
+    ".pdb",
+    ".md",
+)
+
+
+class AddError(OhbinError):
+    """Raised when a release yields no usable assets, or pyproject can't be located."""
+
+
+def _is_candidate(name: str) -> bool:
+    low = name.lower()
+    if low.endswith(_DENY_SUFFIXES):
+        return False
+    return not ("checksum" in low or "sbom" in low)
+
+
+def _archive_rank(name: str) -> int:
+    low = name.lower()
+    if low.endswith((".tar.gz", ".tgz")):
+        return 0
+    if low.endswith((".tar.xz", ".tar.bz2", ".tar")):
+        return 1
+    if low.endswith(".zip"):
+        return 2
+    return 3  # bare binary
+
+
+def _has_token(name: str, tokens: tuple[str, ...]) -> bool:
+    low = name.lower()
+    return any(token in low for token in tokens)
+
+
+def match_asset(assets: list[Asset], plat: Platform) -> Asset | None:
+    candidates = [a for a in assets if _is_candidate(a.name)]
+    primary = [a for a in candidates if _has_token(a.name, os_tokens(plat)) and _has_token(a.name, arch_tokens(plat))]
+    if not primary:
+        # Universal asset: matches the OS but carries no arch token at all
+        # (e.g. a `*_darwin_universal.tar.gz` serves both darwin arches).
+        primary = [
+            a for a in candidates if _has_token(a.name, os_tokens(plat)) and not _has_token(a.name, ALL_ARCH_TOKENS)
+        ]
+    if not primary:
+        return None
+    primary.sort(key=lambda a: (_archive_rank(a.name), len(a.name)))
+    return primary[0]
+
+
+def _digest_sha256(asset: Asset) -> str | None:
+    if asset.digest and asset.digest.startswith("sha256:"):
+        return asset.digest.removeprefix("sha256:")
+    return None
+
+
+def local_pyproject(explicit: Path | None) -> Path:
+    """Resolve the pyproject to *write* to: an explicit `--pyproject-file`, else ./pyproject.toml.
+
+    Mutating commands never walk up the tree — that would let `ohbin add` from a
+    subdirectory silently edit a parent project's pyproject. Reading still discovers
+    upward (see `find_pyproject`); writing stays local and explicit.
+    """
+    if explicit is not None:
+        return explicit
+    local = Path("pyproject.toml")
+    if not local.is_file():
+        msg = "no pyproject.toml in the current directory (pass --pyproject-file to target one)"
+        raise AddError(msg)
+    return local
+
+
+def resolve_tool(*, repo: str, version: str | None, binary: str | None) -> ToolConfig:
+    """Fetch the release and build a ToolConfig with per-platform assets + checksums."""
+    release = fetch_release(repo, version)
+    cmd_name = repo.split("/")[-1]
+    bin_name = binary or cmd_name
+
+    assets: dict[str, AssetEntry] = {}
+    for plat in TARGET_PLATFORMS:
+        asset = match_asset(release.assets, plat)
+        if asset is None:
+            print(f"  ! {plat.key:15} no matching asset — skipped", file=sys.stderr)
+            continue
+        sha256 = _digest_sha256(asset)
+        source = "digest" if sha256 else "downloaded+hashed"
+        if sha256 is None:
+            sha256 = sha256_of_url(asset.url)
+        assets[plat.key] = AssetEntry(url=asset.url, sha256=sha256)
+        print(f"  + {plat.key:15} {asset.name}  ({source})")
+
+    if not assets:
+        msg = f"no matching assets found in {repo}@{release.tag}"
+        raise AddError(msg)
+
+    return ToolConfig(
+        repo=repo,
+        version=release.tag.removeprefix("v"),
+        binary=bin_name,
+        assets=assets,
+    )
+
+
+def _deepest_last_table(table: Table) -> Table:
+    """Descend through the last sub-table at each level to the innermost one.
+
+    Standalone comments/blank lines between the end of a tool's last sub-table and
+    the next section header are parsed by tomlkit into *that* innermost sub-table's
+    body — so this is where trailing trivia lives and must be re-attached.
+    """
+    from tomlkit.items import Table
+
+    last_sub: Table | None = None
+    for _key, item in table.value.body:
+        if isinstance(item, Table):
+            last_sub = item
+    if last_sub is None:
+        return table
+    return _deepest_last_table(last_sub)
+
+
+def _detach_trailing_trivia(table: Table) -> list[BodyEntry]:
+    """Pop the trailing run of standalone whitespace/comments from a tool's last table.
+
+    Returns them in document order; an empty list when the table ends on a real key.
+    These belong to the *following* section (a comment block before the next header),
+    not the tool — overwriting the tool entry must not eat them.
+    """
+    from tomlkit.items import Comment, Whitespace
+
+    body = _deepest_last_table(table).value.body
+    trailing: list[BodyEntry] = []
+    while body and body[-1][0] is None and isinstance(body[-1][1], (Whitespace, Comment)):
+        trailing.insert(0, body.pop())
+    return trailing
+
+
+def write_tool(pyproject: Path, name: str, cfg: ToolConfig) -> None:
+    """Write/overwrite `[tool.ohbin.tools.<name>]`, preserving the rest of the file."""
+    import tomlkit
+    from tomlkit import TOMLDocument
+    from tomlkit.items import Table
+
+    doc = tomlkit.parse(pyproject.read_text())
+
+    def ensure(parent: TOMLDocument | Table, key: str, *, super_table: bool) -> Table:
+        existing = parent.get(key)
+        if isinstance(existing, Table):
+            return existing
+        created = tomlkit.table(is_super_table=super_table)
+        parent[key] = created
+        return created
+
+    tools = ensure(
+        ensure(ensure(doc, "tool", super_table=True), "ohbin", super_table=True),
+        "tools",
+        super_table=True,
+    )
+
+    # A comment block before the next top-level section is parsed into the
+    # innermost body of whichever tool is physically last in `[tool.ohbin.tools]`.
+    # Two cases must both preserve it:
+    #   - overwriting a tool: its own trailing trivia goes with the rebuilt entry;
+    #   - appending a new tool: tomlkit puts the new table *after* that trivia,
+    #     stranding the comment above the new entry and dropping the separator —
+    #     so detach it from the current last tool and move it past the new one.
+    old_entry = tools.get(name)
+    own_trailing = _detach_trailing_trivia(old_entry) if isinstance(old_entry, Table) else []
+    appending = not isinstance(old_entry, Table)
+    next_section_trivia: list[BodyEntry] = []
+    if appending and _deepest_last_table(tools) is not tools:
+        next_section_trivia = _detach_trailing_trivia(tools)
+
+    entry = tomlkit.table()
+    entry["repo"] = cfg["repo"]
+    entry["version"] = cfg["version"]
+    entry["binary"] = cfg["binary"]
+    if cfg.get("encrypted"):
+        entry["encrypted"] = True
+    if "password" in cfg:
+        entry["password"] = cfg["password"]
+    if cfg.get("password_committed_ok"):
+        entry["password_committed_ok"] = True
+
+    assets = tomlkit.table(is_super_table=True)
+    for plat_key, asset in cfg["assets"].items():
+        asset_table = tomlkit.table()
+        asset_table["url"] = asset["url"]
+        asset_table["sha256"] = asset["sha256"]
+        if "binary_sha256" in asset:
+            asset_table["binary_sha256"] = asset["binary_sha256"]
+        assets[plat_key] = asset_table
+    entry["assets"] = assets
+
+    tools[name] = entry
+    if own_trailing:
+        _deepest_last_table(entry).value.body.extend(own_trailing)
+    if next_section_trivia:
+        _deepest_last_table(entry).value.body.extend(next_section_trivia)
+    pyproject.write_text(tomlkit.dumps(doc))
+
+
+def add_tool(
+    *,
+    repo: str,
+    version: str | None,
+    name: str | None,
+    binary: str | None,
+    pyproject: Path | None,
+) -> tuple[str, Path]:
+    cfg = resolve_tool(repo=repo, version=version, binary=binary)
+    cmd_name = name or repo.split("/")[-1]
+    target = local_pyproject(pyproject)
+    write_tool(target, cmd_name, cfg)
+    return cmd_name, target

ohbin/_crypto.py

@@ -0,0 +1,95 @@
+"""Password-based encryption of release binaries via the system `openssl` CLI.
+
+A published blob is `gzip(raw binary)` → AES-256-CBC (PBKDF2 key derivation) →
+base64 text, so it fits inside a (text-only) GitHub gist. ohbin is the only thing
+that decrypts it, so a leaked gist link is useless without the password — which
+stays out of the gist (a private repo, or `--password`).
+
+We shell out to `openssl` instead of taking a Python crypto dependency, keeping the
+`run` hot path free of pip deps. The password is handed to openssl over an inherited
+pipe FD (`-pass fd:N`), never on argv, so it can't leak via the process table.
+
+CBC is unauthenticated; integrity is enforced one layer up by pinning the decrypted
+binary's SHA256 in the manifest (`binary_sha256`), which also catches a wrong
+password — a bad key almost always yields invalid PKCS#7 padding (openssl errors) or
+garbage that fails the gzip/SHA check.
+"""
+
+from __future__ import annotations
+
+import base64
+import gzip
+import os
+import shutil
+import subprocess
+
+from ohbin._errors import OhbinError
+
+# LibreSSL (macOS) and OpenSSL agree on this fully-pinned recipe; -pbkdf2 + an
+# explicit digest/iter count keeps producer and consumer interoperable.
+_ITER = "200000"
+_ENC_ARGS = ("enc", "-aes-256-cbc", "-pbkdf2", "-md", "sha256", "-iter", _ITER, "-salt")
+
+
+class OpensslMissingError(OhbinError):
+    """Raised when the `openssl` CLI isn't on PATH (required for encrypted tools)."""
+
+
+class DecryptError(OhbinError):
+    """Raised when decryption fails — almost always a wrong password or a corrupt blob."""
+
+
+def _openssl() -> str:
+    path = shutil.which("openssl")
+    if path is None:
+        msg = "openssl not found on PATH — required to (de)crypt an encrypted ohbin tool"
+        raise OpensslMissingError(msg)
+    return path
+
+
+def _run(extra: tuple[str, ...], stdin: bytes, password: str) -> bytes:
+    """Run `openssl enc [...] -pass fd:N` feeding the password over an inherited pipe."""
+    read_fd, write_fd = os.pipe()
+    try:
+        os.write(write_fd, password.encode())  # passwords are tiny — never blocks the buffer
+        os.close(write_fd)
+        # pass_fds keeps read_fd open + inheritable in the child; argv carries no secret.
+        proc = subprocess.run(
+            [_openssl(), *_ENC_ARGS, *extra, "-pass", f"fd:{read_fd}"],
+            input=stdin,
+            capture_output=True,
+            pass_fds=(read_fd,),
+            check=False,
+        )
+    finally:
+        os.close(read_fd)
+    if proc.returncode != 0:
+        detail = proc.stderr.decode(errors="replace").strip()
+        raise DecryptError(detail or "openssl failed")
+    return proc.stdout
+
+
+def encrypt_binary(binary: bytes, password: str) -> str:
+    """`gzip(binary)` → AES-256-CBC → base64. Returns gist-ready text."""
+    ciphertext = _run((), gzip.compress(binary), password)
+    return base64.b64encode(ciphertext).decode()
+
+
+def decrypt_binary(blob_b64: str, password: str) -> bytes:
+    """Reverse `encrypt_binary`: base64-decode → openssl -d → gunzip → raw binary."""
+    try:
+        ciphertext = base64.b64decode(blob_b64, validate=True)  # binascii.Error <: ValueError
+    except ValueError as exc:
+        msg = "encrypted blob is not valid base64"
+        raise DecryptError(msg) from exc
+    try:
+        plaintext = _run(("-d",), ciphertext, password)
+    except DecryptError as exc:
+        # openssl's raw "bad decrypt" + libressl file path is noise — say what it means.
+        msg = "decryption failed — wrong password or corrupt blob"
+        raise DecryptError(msg) from exc
+    try:
+        return gzip.decompress(plaintext)  # BadGzipFile <: OSError
+    except (OSError, EOFError) as exc:
+        msg = "decryption produced invalid data — wrong password or corrupt blob"
+        raise DecryptError(msg) from exc