python-wheels 0.1.0__py3-none-any.whl

python_wheels-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: python-wheels
+Version: 0.1.0
+Summary: Verify Sigstore-attested wheels from python-wheels-builds before installing
+Project-URL: Homepage, https://github.com/patrickryankenneth/python-wheels
+Project-URL: Builds, https://github.com/patrickryankenneth/python-wheels-builds
+Project-URL: Index, https://python-wheels.github.io
+Project-URL: Issues, https://github.com/patrickryankenneth/python-wheels/issues
+Project-URL: Changelog, https://github.com/patrickryankenneth/python-wheels/blob/main/CHANGELOG.md
+Author-email: Patrick Ryan <patrickryankenneth@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: attestation,pip,provenance,sigstore,slsa,supply-chain,wheels
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.9
+Provides-Extra: sigstore
+Requires-Dist: sigstore<4.6,>=4.0; extra == 'sigstore'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# python-wheels
+
+**Status: working - v0.1.0.** The `python-wheels` CLI (command: `pywheels`,
+also installed as `python-wheels`) verifies and installs attested wheels
+today. First attested build shipped: `dbt-oss` for `win_arm64`.
+
+## The problem
+
+Some Python packages don't ship a wheel for your platform: an
+uncommon architecture, Alpine/musl instead of glibc, an OS upstream doesn't
+target, or just a combination nobody's gotten around to building for. Right
+now the options are "build it from source yourself, every time" or "hope
+someone in the community hosts one somewhere."
+
+It's also not always upstream being lazy. PyPI caps a project at 10GB of
+total storage, and wheels for every platform/arch/Python-version
+combination add up fast - that's part of why projects like PyTorch host
+some of their wheels off-PyPI and point people at an extra index instead.
+`python-wheels` is aimed at exactly that situation: popular packages that
+can't or don't publish a wheel for your platform, for any reason.
+
+## What it does
+
+```bash
+pip install python-wheels
+pywheels install dbt-oss==2.0.5 \
+  --repo patrickryankenneth/python-wheels-builds \
+  --tag dbt-oss-v2.0.5 \
+  --workflow build-dbt-oss-win-arm64.yml
+```
+
+1. **Checks upstream first.** If pip can already resolve real wheels for
+   the package - and its whole dependency closure, not just the top-level
+   package - on your platform, it says so and prints the plain
+   `pip install` command; this tool gets out of the way whenever upstream
+   already has you covered. A small per-package override list
+   (`overrides.json`) handles the rare case where a package's real wheel
+   availability is hidden from pip's normal resolution - e.g. `dbt-oss`,
+   whose PyPI sdist is a stub build backend that fetches a real prebuilt
+   wheel from GitHub, keyed by platform, with no source to fall back to.
+2. **Falls back, but verifies.** If there's no usable upstream wheel, it
+   fetches the matching release from
+   [python-wheels-builds](https://github.com/patrickryankenneth/python-wheels-builds)
+   and checks, before recommending anything:
+   - its **build provenance attestation** (SLSA - built by the expected CI
+     workflow, from the expected repo and ref, unmodified since),
+   - its **upstream-source attestation** (built from the real, tagged
+     upstream release - not a fork or a patched copy),
+   - the **source archive's digest** against what that attestation
+     recorded, when a source archive is available.
+
+   Verification runs offline via [sigstore](https://pypi.org/project/sigstore/)
+   (`pip install python-wheels[sigstore]`) if it's installed, or falls back
+   to the `gh` CLI (no pip dependency, needs network) if it isn't. Run
+   `pywheels doctor` to see which backend is usable on your machine.
+3. **Fails loudly, not silently.** `pywheels install` never runs
+   `pip install` for you - it only ever prints the exact command that's
+   safe to run. If verification fails, or neither backend is available at
+   all, it says so plainly and falls back to `pip install
+   --no-binary=:all:` (unverified, from source) as the last resort - never
+   a silent, unattested install.
+
+`pywheels verify` runs the same verification directly against a wheel
+that's already on disk, or a specific release tag - useful for checking a
+build without going through the whole `install` flow.
+
+## Where the wheels actually come from
+
+This repo is only the installer and verifier. The wheels themselves are
+built and attested in
+[python-wheels-builds](https://github.com/patrickryankenneth/python-wheels-builds),
+and also served as a plain [PEP 503](https://peps.python.org/pep-0503/)
+index at [python-wheels.github.io](https://python-wheels.github.io) for
+anyone who just wants `pip install --extra-index-url
+https://python-wheels.github.io/simple/ <package>` without the
+verification step. `pywheels` is the piece that ties the CLI, the
+release repo, and the attestation checks together so you don't have to run
+`gh attestation verify` by hand.
+
+## Longer-term direction
+
+The build side is currently one hand-tuned workflow for one package
+(`dbt-oss`/`dbt-core` on Windows ARM64). The goal is to turn that into a
+standardized, reproducible build recipe that can target other popular PyPI
+packages missing wheels for a given platform - starting with the platforms
+that come up most often (Alpine/musl, less-common architectures, newer
+Python versions upstream hasn't built for yet), rather than trying to
+cover everything at once.
+
+## Not yet decided
+
+- CLI surface beyond `install`/`verify`/`doctor` (list available
+  platforms? show why a package fell back? a way to request a new
+  package/platform combo?)
+- How package/platform requests get prioritized once this covers more than
+  one package
+- Whether to eventually provide a wrapper mode that invokes pip directly after verification, 
+  versus keeping the strict "print the safe command only" separation.
+
+Contributions and issues on any of the above are welcome - this project is
+still early, even with a first attested build shipped.

python_wheels-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pywheels/__init__.py,sha256=TpM3MTXInLX2wP0p91p0IXOxENixCmV8NyW4FHW14ts,206
+pywheels/cli.py,sha256=YxC7b5dSAWTQd19CelVH7dgyGWmeSyzy0B3gZT1BFhY,20214
+pywheels/github_release.py,sha256=X2e7UEfABcsS8tktq6VZQTmpX_TbB7b1qf-y1zUHXdo,4930
+pywheels/overrides.json,sha256=0SkJcZMLUvwC5wcINEn2jgBfqUcgmyWbuAqfYHcuXNs,566
+pywheels/verify.py,sha256=NMxiQBhxnkMcxJJyziIhBPs0P7tts1lY2NVm-kpA2ok,14210
+python_wheels-0.1.0.dist-info/METADATA,sha256=qY5xUSI5j7PLVcuU7ATutEOotPBUUZCZ3rmSJAYAtY0,6261
+python_wheels-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+python_wheels-0.1.0.dist-info/entry_points.txt,sha256=Y_IzU_QVw6XqzTqsf5L-2uUxOslWaZYA4PRWT9NvFBA,81
+python_wheels-0.1.0.dist-info/licenses/LICENSE,sha256=Qzm3fHs1tWQQVJDoxOjYz6Y3ukVfcC58oVHkkM-2SR0,1069
+python_wheels-0.1.0.dist-info/RECORD,,

python_wheels-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

python_wheels-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+python-wheels = pywheels.cli:main
+pywheels = pywheels.cli:main

python_wheels-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Ryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pywheels/__init__.py

@@ -0,0 +1,5 @@
+"""pywheels: verify Sigstore-attested wheels from python-wheels-builds
+before installing. See cli.py for the command-line interface and
+verify.py for the verification logic itself."""
+
+__version__ = "0.1.0"

pywheels/cli.py

@@ -0,0 +1,415 @@
+"""pywheels: fetch and verify a wheel from a python-wheels-builds release
+before anything gets near `pip install`.
+
+    pywheels verify dbt-core --repo you/python-wheels-builds \
+        --tag dbt-oss-v2.0.5 --workflow build-dbt-oss-win-arm64.yml
+
+    pywheels verify dbt-core --repo you/python-wheels-builds \
+        --workflow smoke-test-build-dbt-oss.yml --local-dir ./pywheels-sample
+
+    pywheels doctor
+
+Backend selection (--backend auto|sigstore|gh, default auto): try sigstore
+first (offline, needs the optional `sigstore` extra), fall back to the
+`gh` CLI if that's not installed (needs network, needs nothing from pip).
+If neither is available, verification of one of pywheels' own wheels fails
+loudly - see verify.py's VerificationError, not a silent pass-through.
+
+--repo defaults to $PYWHEELS_REPO so a single-project install of this CLI
+doesn't have to pass it on every call; set that once in your shell profile,
+or keep passing --repo explicitly if you point pywheels at more than one
+release repo.
+
+    pywheels install dbt-core==2.0.5 --tag dbt-oss-v2.0.5 \
+        --workflow build-dbt-oss-win-arm64.yml
+
+v1 `install` does NOT call `pip install` for you. It only tells you which
+`pip install ...` command is safe to run, because "safe" here specifically
+means "verified", and we can only ever verify wheels signed by our own
+--repo - never an arbitrary upstream wheel. Concretely, per package:
+  1. Can pip resolve real, non-source wheels for this package and its
+     whole dependency closure on your platform? If so, say so and print
+     the plain `pip install` command - unverified, since it's not ours to
+     attest, but not blocked either.
+     NOTE: for a pure-Python package like dbt-core itself this check is
+     almost meaningless on its own (dbt-core ships one universal
+     py3-none-any wheel for every platform) - the real gap for us is
+     always in a *dependency* that ships real per-platform wheels (e.g.
+     dbt-extractor, a Rust extension with no win-arm64 wheel on PyPI).
+     Because pip resolves the whole tree, not just the top-level package,
+     this check does still fail correctly on an unsupported platform -
+     it's just resolving the dependency graph, not "does dbt-core have a
+     wheel". Nothing here inspects any dependency's own download-a-binary
+     logic at import/run time (if one exists) - see the "not yet handled"
+     note below.
+  2. Otherwise, fetch the matching wheel from --repo/--tag and run it
+     through verify_wheel. If it verifies, print the `pip install` command
+     for the wheel now sitting in --workdir. If verification fails or the
+     backend can't run at all, say so plainly and do NOT print an install
+     command for it.
+  3. If neither worked, print the `pip install --no-binary=:all:` command
+     as the last resort, with no attestation behind it either.
+
+Not yet handled generally: some upstream packages hide their real wheel
+availability behind package-specific indirection that plain pip resolution
+can't see through - e.g. dbt-oss, whose PyPI "sdist" is actually a stub
+build backend that downloads a real wheel from GitHub, keyed by platform,
+with no source to fall back to (see overrides.json). Add an entry there for
+each such package as you confirm its actual mechanism (e.g. pytorch, which
+needs a non-default --index-url to see real wheels at all) - don't guess at
+a new package's mechanism speculatively; confirm it the way dbt-oss's was
+confirmed, by reading what its build backend or index actually does.
+
+`verify` always assumes you're pointing it at one of our own wheels; the
+"is this actually a python-wheels artifact, or a normal upstream package
+we don't sign" decision lives in `install`, above.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from .github_release import fetch_release_assets, find_local_assets, get_latest_release_tag
+from .verify import (
+    verify_wheel,
+    VerificationError,
+    sigstore_available,
+    gh_available,
+    DEFAULT_UPSTREAM_PREDICATE_TYPE,
+)
+
+# A single-project install of this CLI is the common case, so --repo can be
+# set once via env var instead of on every call. Still overridable per-call.
+DEFAULT_REPO = os.environ.get("PYWHEELS_REPO")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pywheels")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    v = sub.add_parser("verify", help="verify a wheel's attestations before you trust it")
+    v.add_argument("package", help="package name, e.g. dbt-core")
+    v.add_argument("--repo", required=DEFAULT_REPO is None, default=DEFAULT_REPO,
+                    help="owner/repo of the release, e.g. you/python-wheels-builds "
+                         "(default: $PYWHEELS_REPO if set)")
+    v.add_argument("--tag", help="release tag, e.g. dbt-oss-v2.0.5 (ignored with --local-dir)")
+    v.add_argument("--workflow", required=True, help="workflow filename that signed it, e.g. build-dbt-oss-win-arm64.yml")
+    v.add_argument("--ref", default="refs/heads/main", help="git ref the signing workflow ran from (default: %(default)s)")
+    v.add_argument("--upstream-predicate-type", default=DEFAULT_UPSTREAM_PREDICATE_TYPE,
+                    help="predicate type URL for the upstream-source attestation (default: %(default)s)")
+    v.add_argument("--workdir", default=".pywheels-cache", help="where downloaded assets are cached (default: %(default)s)")
+    v.add_argument("--local-dir", type=Path, default=None,
+                    help="skip the GitHub fetch and verify files already on disk under this directory "
+                         "instead (e.g. output of `gh run download`)")
+    v.add_argument("--backend", choices=["auto", "sigstore", "gh"], default="auto",
+                    help="verification backend (default: %(default)s - sigstore if installed, else gh)")
+    v.add_argument("-v", "--verbose", action="count", default=0,
+                    help="pass through extra logging to the backend. Repeatable (-vv). "
+                         "sigstore: raises its own -v/-vv debug logging. "
+                         "gh: has no verbosity flag, so this instead asks for --format=json "
+                         "(the closest thing gh offers to a detailed result dump).")
+
+    i = sub.add_parser("install", help="print the safe pip install command for a package: verified ours, or plain upstream, or source")
+    i.add_argument("package", help="package name, optionally pinned, e.g. dbt-core or dbt-core==2.0.5")
+    i.add_argument("--repo", required=DEFAULT_REPO is None, default=DEFAULT_REPO,
+                    help="owner/repo to check if upstream has no usable wheel "
+                         "(default: $PYWHEELS_REPO if set)")
+    i.add_argument("--workflow", required=True, help="workflow filename that signs our wheels, e.g. build-dbt-oss-win-arm64.yml")
+    i.add_argument("--tag", default=None,
+                    help="release tag to use from --repo (default: that repo's latest release). "
+                         "Required if your tag naming doesn't match '<package>-v<version>' - "
+                         "e.g. dbt-core==2.0.5 needs --tag dbt-oss-v2.0.5 explicitly, since the "
+                         "release-tag prefix ('dbt-oss') and the pip package name ('dbt-core') differ.")
+    i.add_argument("--ref", default="refs/heads/main", help="git ref the signing workflow ran from (default: %(default)s)")
+    i.add_argument("--upstream-predicate-type", default=DEFAULT_UPSTREAM_PREDICATE_TYPE,
+                    help="predicate type URL for the upstream-source attestation (default: %(default)s)")
+    i.add_argument("--index-url", default=None, help="pip index to check for upstream wheels (default: pip's own default, i.e. PyPI)")
+    i.add_argument("--workdir", default=".pywheels-cache", help="where our downloaded wheel is cached if we fetch one (default: %(default)s)")
+    i.add_argument("--backend", choices=["auto", "sigstore", "gh"], default="auto",
+                    help="verification backend for our own wheel (default: %(default)s - sigstore if installed, else gh)")
+    i.add_argument("-v", "--verbose", action="count", default=0, help="pass through extra logging to the verify backend")
+
+    sub.add_parser("doctor", help="check which verification backends are usable, and how to fix the ones that aren't")
+
+    return parser
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    if args.local_dir is None and not args.tag:
+        print("error: pass either --tag (to fetch a release) or --local-dir (to use files on disk)", file=sys.stderr)
+        return 2
+
+    try:
+        if args.local_dir is not None:
+            assets = find_local_assets(args.package, args.local_dir)
+        else:
+            dest = Path(args.workdir)
+            dest.mkdir(parents=True, exist_ok=True)
+            assets = fetch_release_assets(args.repo, args.tag, args.package, dest)
+
+        report = verify_wheel(
+            assets.wheel,
+            assets.bundle,
+            repo=args.repo,
+            workflow_file=args.workflow,
+            ref=args.ref,
+            upstream_predicate_type=args.upstream_predicate_type,
+            source_archive_path=assets.archive,
+            backend=args.backend,
+            verbose=args.verbose,
+        )
+    except (FileNotFoundError, VerificationError) as exc:
+        print(f"{args.package}: could not verify - {exc}", file=sys.stderr)
+        return 2
+
+    print(f"(using backend: {report.backend})")
+    for a in report.attestations:
+        status = "ignored" if a.ignored else ("OK" if a.verified else "FAILED")
+        print(f"[{status}] {a.predicate_type or '(unknown predicate)'}")
+        if not a.verified and not a.ignored:
+            print(f"    {a.detail}", file=sys.stderr)
+
+    if report.archive_checked:
+        print(f"[{'OK' if report.archive_ok else 'FAILED'}] source archive digest")
+        if not report.archive_ok and report.archive_check_error:
+            print(f"    {report.archive_check_error}", file=sys.stderr)
+
+    if report.ok:
+        print(f"\n{args.package}: verified OK")
+        return 0
+
+    print(f"\n{args.package}: VERIFICATION FAILED - refusing to trust this wheel", file=sys.stderr)
+    return 1
+
+
+def _split_package_spec(spec: str):
+    """'dbt-core==2.0.5' -> ('dbt-core', '2.0.5'); 'dbt-core' -> ('dbt-core', None)."""
+    if "==" in spec:
+        name, version = spec.split("==", 1)
+        return name, version
+    return spec, None
+
+
+_OVERRIDES_PATH = Path(__file__).resolve().parent / "overrides.json"
+
+
+def _load_overrides() -> dict:
+    try:
+        return json.loads(_OVERRIDES_PATH.read_text())
+    except FileNotFoundError:
+        return {}
+
+
+def _pip_can_resolve_wheels(spec: str, index_url: Optional[str]) -> bool:
+    """Default strategy. Dry-run only - downloads (never installs) `spec`
+    and its full dependency closure into a throwaway dir with
+    --only-binary=:all:, then deletes it. Success means pip found real
+    wheels for every package in that closure, not just the top-level one:
+    a pure-Python top-level package (like dbt-core's own py3-none-any
+    wheel) will "have a wheel" on every platform regardless, so this check
+    only means something because pip resolves dependencies too - that's
+    where a real per-platform gap (e.g. dbt-extractor having no win-arm64
+    wheel) actually shows up. --no-deps would defeat the point; don't add
+    it here.
+
+    Only correct when the package's own PyPI index metadata actually
+    reflects what it can serve. Some packages hide real wheel availability
+    behind a stub build backend or an alternate index - see overrides.json
+    and _pip_can_resolve_via_source_build for the confirmed exception."""
+    with tempfile.TemporaryDirectory(prefix="pywheels-check-") as tmp:
+        cmd = [sys.executable, "-m", "pip", "download", "--only-binary=:all:", "-d", tmp, spec]
+        if index_url:
+            cmd += ["--index-url", index_url]
+        return subprocess.run(cmd, capture_output=True).returncode == 0
+
+
+def _pip_can_resolve_via_source_build(spec: str, index_url: Optional[str]) -> bool:
+    """Override strategy "source-build-probe". For a package whose PyPI
+    "sdist" never actually compiles anything - it's a stub whose PEP 517
+    build backend downloads a real prebuilt wheel from elsewhere, keyed by
+    platform (see overrides.json's note for dbt-oss specifically) - the
+    only way to know if upstream covers this platform is to actually run
+    that backend. --no-deps: we're probing whether THIS package's own
+    backend serves this platform, not re-checking its dependencies (which
+    the default strategy already handles fine when they're ordinary
+    wheels, as dbt-oss's sole dependency `mashumaro` is)."""
+    with tempfile.TemporaryDirectory(prefix="pywheels-probe-") as tmp:
+        cmd = [sys.executable, "-m", "pip", "download", "--no-binary=:all:", "--no-deps", "-d", tmp, spec]
+        if index_url:
+            cmd += ["--index-url", index_url]
+        return subprocess.run(cmd, capture_output=True).returncode == 0
+
+
+_STRATEGIES = {
+    "source-build-probe": _pip_can_resolve_via_source_build,
+}
+
+
+def _upstream_available(spec: str, package: str, index_url: Optional[str]) -> bool:
+    override = _load_overrides().get(package)
+    strategy = _STRATEGIES.get(override["strategy"]) if override else None
+    check = strategy or _pip_can_resolve_wheels
+    return check(spec, index_url)
+
+
+def _print_pip_cmd(*parts: str) -> None:
+    print("  " + " ".join(parts))
+
+
+def _cmd_install(args: argparse.Namespace) -> int:
+    package, version = _split_package_spec(args.package)
+    spec = args.package
+
+    print(f"pywheels install {spec}: checking whether pip can resolve real wheels for your platform...")
+    if _upstream_available(spec, package, args.index_url):
+        print(f"\nupstream has wheels for {spec} and its dependencies on this platform.")
+        print("this is NOT attested by us - we only ever verify wheels from our own --repo. safe to run:\n")
+        cmd = ["pip", "install", spec]
+        if args.index_url:
+            cmd += ["--index-url", args.index_url]
+        _print_pip_cmd(*cmd)
+        return 0
+
+    print(f"\npip could not resolve real wheels for {spec} and its dependencies on this platform.")
+    print(f"checking {args.repo} for an attested build...")
+
+    if not args.tag and version:
+        print(
+            f"\ncan't guess a release tag from the version pin ({version}) - this repo's tag "
+            f"prefixes don't necessarily match the pip package name (e.g. tag 'dbt-oss-v2.0.5' "
+            f"for package 'dbt-core'). Pass --tag explicitly.",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        tag = args.tag or get_latest_release_tag(args.repo)
+        dest = Path(args.workdir)
+        dest.mkdir(parents=True, exist_ok=True)
+        assets = fetch_release_assets(args.repo, tag, package, dest)
+    except FileNotFoundError as exc:
+        print(f"{args.repo}: no wheel available either ({exc})")
+        print("nothing we can vouch for. building from source, unverified, is your only option:\n")
+        _print_pip_cmd("pip", "install", "--no-binary=:all:", spec)
+        return 1
+
+    try:
+        report = verify_wheel(
+            assets.wheel,
+            assets.bundle,
+            repo=args.repo,
+            workflow_file=args.workflow,
+            ref=args.ref,
+            upstream_predicate_type=args.upstream_predicate_type,
+            source_archive_path=assets.archive,
+            backend=args.backend,
+            verbose=args.verbose,
+        )
+    except VerificationError as exc:
+        print(f"{args.package}: could not verify ({exc})", file=sys.stderr)
+        print("refusing to recommend an unverifiable wheel. building from source, unverified:\n")
+        _print_pip_cmd("pip", "install", "--no-binary=:all:", spec)
+        return 2
+
+    print(f"(using backend: {report.backend})")
+    for a in report.attestations:
+        status = "ignored" if a.ignored else ("OK" if a.verified else "FAILED")
+        print(f"[{status}] {a.predicate_type or '(unknown predicate)'}")
+    if report.archive_checked:
+        print(f"[{'OK' if report.archive_ok else 'FAILED'}] source archive digest")
+        if not report.archive_ok and report.archive_check_error:
+            print(f"    {report.archive_check_error}", file=sys.stderr)
+
+    if not report.ok:
+        print(f"\n{args.package}: VERIFICATION FAILED for {tag} - refusing to recommend this wheel", file=sys.stderr)
+        print("building from source, unverified, is your remaining option:\n")
+        _print_pip_cmd("pip", "install", "--no-binary=:all:", spec)
+        return 1
+
+    print(f"\n{args.package}: verified OK ({tag}). safe to run:\n")
+    _print_pip_cmd("pip", "install", str(assets.wheel))
+    return 0
+
+
+_GH_INSTALL_HINTS = {
+    "Linux": "sudo apt install gh   (Debian/Ubuntu)  |  see https://github.com/cli/cli/blob/trunk/docs/install_linux.md for other distros",
+    "Darwin": "brew install gh",
+    "Windows": "winget install --id GitHub.cli   |   or: choco install gh",
+}
+
+
+def _cmd_doctor(_args: argparse.Namespace) -> int:
+    print("pywheels doctor")
+    print("-" * 44)
+    any_backend = False
+
+    if sigstore_available():
+        proc = subprocess.run([sys.executable, "-m", "sigstore", "--version"], capture_output=True, text=True)
+        if proc.returncode == 0:
+            any_backend = True
+            print(f"[OK]      sigstore backend: {(proc.stdout or proc.stderr).strip()}")
+        else:
+            print("[BROKEN]  sigstore is installed but `python -m sigstore` did not run cleanly")
+            print(f"          {(proc.stderr or proc.stdout).strip()}")
+            print("          fix: pip install --upgrade --force-reinstall sigstore")
+    else:
+        print("[missing] sigstore backend (optional)")
+        print("          fix: pip install sigstore   (or: pip install pywheels[sigstore])")
+
+    if gh_available():
+        proc = subprocess.run(["gh", "--version"], capture_output=True, text=True)
+        version = (proc.stdout or proc.stderr).strip().splitlines()[0] if proc.stdout or proc.stderr else "gh"
+        any_backend = True
+        print(f"[OK]      gh backend: {version}")
+        auth = subprocess.run(["gh", "auth", "status"], capture_output=True, text=True)
+        if auth.returncode != 0:
+            print("          note: gh is not authenticated (`gh auth login`) - public-repo verification "
+                  "should still work, but may hit lower rate limits")
+    else:
+        print("[missing] gh backend (optional)")
+        hint = _GH_INSTALL_HINTS.get(platform.system(), "see https://cli.github.com")
+        print(f"          fix: {hint}")
+
+    print("-" * 44)
+    if any_backend:
+        print("at least one verification backend is usable")
+        return 0
+    print("NO verification backend is usable - pywheels will refuse to verify any wheel")
+    print("install sigstore or gh (see above) before relying on this tool")
+    return 1
+
+
+def main(argv=None) -> None:
+    # stdout is block-buffered (not line-buffered) whenever it isn't a real
+    # terminal - which is exactly the case under CI - while stderr is
+    # always unbuffered. Left alone, that means every stderr line (our
+    # archive_check_error diagnostics, verification failure messages, etc)
+    # gets flushed immediately while stdout's lines sit queued until the
+    # process exits - so in a captured CI log, the "why it failed" lines
+    # appear to jump to the top, ahead of the OK/FAILED context they're
+    # explaining, instead of appearing where they were actually printed.
+    # Force line-buffering so stdout and stderr interleave in real order.
+    sys.stdout.reconfigure(line_buffering=True)
+    sys.stderr.reconfigure(line_buffering=True)
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "verify":
+        sys.exit(_cmd_verify(args))
+    elif args.command == "install":
+        sys.exit(_cmd_install(args))
+    elif args.command == "doctor":
+        sys.exit(_cmd_doctor(args))
+
+
+if __name__ == "__main__":
+    main()

pywheels/github_release.py

@@ -0,0 +1,125 @@
+"""Minimal GitHub Releases client: locate and download the assets pywheels
+needs for one package from a release - the wheel, its attestation bundle,
+and the source archive if one is attached.
+
+Also supports finding those same three files in a local directory tree
+(find_local_assets) - useful for testing against artifacts you already
+have on disk (e.g. pulled via `gh run download`) without a live release to
+fetch from.
+
+Uses only the standard library (urllib) - two simple GETs don't justify a
+`requests` dependency.
+
+v1 scope: single-package repo (dbt-oss). The archive-name match below is
+dbt-oss-specific; generalize it (e.g. read a manifest asset instead of
+guessing a filename pattern) once pywheels serves more than one package.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+API_ROOT = "https://api.github.com"
+
+
+@dataclass
+class ReleaseAssets:
+    wheel: Path
+    bundle: Path
+    archive: Optional[Path]
+
+
+def _get_release(repo: str, tag: str) -> dict:
+    url = f"{API_ROOT}/repos/{repo}/releases/tags/{tag}"
+    req = urllib.request.Request(url, headers={"Accept": "application/vnd.github+json"})
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as exc:
+        raise FileNotFoundError(f"release {tag!r} not found in {repo} (HTTP {exc.code})") from exc
+
+
+def get_latest_release_tag(repo: str) -> str:
+    """Used by `install` when the caller doesn't pin a --tag. `verify` never
+    calls this - it always wants a specific, caller-named release."""
+    url = f"{API_ROOT}/repos/{repo}/releases/latest"
+    req = urllib.request.Request(url, headers={"Accept": "application/vnd.github+json"})
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            release = json.loads(resp.read())
+    except urllib.error.HTTPError as exc:
+        raise FileNotFoundError(f"no releases found in {repo} (HTTP {exc.code})") from exc
+    tag = release.get("tag_name")
+    if not tag:
+        raise FileNotFoundError(f"latest release in {repo} has no tag_name")
+    return tag
+
+
+def _download(url: str, dest: Path) -> Path:
+    req = urllib.request.Request(url, headers={"Accept": "application/octet-stream"})
+    with urllib.request.urlopen(req, timeout=120) as resp:
+        dest.write_bytes(resp.read())
+    return dest
+
+
+def fetch_release_assets(repo: str, tag: str, package: str, dest_dir: Path) -> ReleaseAssets:
+    release = _get_release(repo, tag)
+    assets = {a["name"]: a for a in release.get("assets", [])}
+
+    wheel_pattern = f"{package.replace('-', '_')}-*.whl"
+    wheel_name = next((n for n in assets if fnmatch.fnmatch(n, wheel_pattern)), None)
+    if wheel_name is None:
+        raise FileNotFoundError(f"no wheel matching {wheel_pattern!r} in {repo}@{tag}")
+
+    bundle_name = f"{wheel_name}.attestations.jsonl"
+    if bundle_name not in assets:
+        raise FileNotFoundError(f"no attestation bundle {bundle_name!r} in {repo}@{tag}")
+
+    archive_name = next(
+        (n for n in assets if n.startswith("dbt-oss-source-") and n.endswith(".tar.gz")),
+        None,
+    )
+
+    wheel_path = _download(assets[wheel_name]["browser_download_url"], dest_dir / wheel_name)
+    bundle_path = _download(assets[bundle_name]["browser_download_url"], dest_dir / bundle_name)
+    archive_path = (
+        _download(assets[archive_name]["browser_download_url"], dest_dir / archive_name)
+        if archive_name else None
+    )
+
+    return ReleaseAssets(wheel=wheel_path, bundle=bundle_path, archive=archive_path)
+
+
+def find_local_assets(package: str, local_dir: Path) -> ReleaseAssets:
+    """Same three files as fetch_release_assets, located by searching a
+    local directory tree instead of a GitHub release - e.g. the layout
+    `gh run download` produces (wheel nested under an artifact-name folder,
+    bundle files flat, archive nested under its own artifact folder)."""
+    if not local_dir.is_dir():
+        raise FileNotFoundError(f"not a directory: {local_dir}")
+
+    wheel_pattern = f"{package.replace('-', '_')}-*.whl"
+    wheel_path = next(
+        (p for p in local_dir.rglob("*.whl") if fnmatch.fnmatch(p.name, wheel_pattern)),
+        None,
+    )
+    if wheel_path is None:
+        raise FileNotFoundError(f"no wheel matching {wheel_pattern!r} under {local_dir}")
+
+    bundle_name = f"{wheel_path.name}.attestations.jsonl"
+    bundle_path = next((p for p in local_dir.rglob(bundle_name)), None)
+    if bundle_path is None:
+        raise FileNotFoundError(f"no attestation bundle {bundle_name!r} under {local_dir}")
+
+    archive_path = next(
+        (p for p in local_dir.rglob("*.tar.gz") if p.name.startswith("dbt-oss-source-")),
+        None,
+    )
+
+    return ReleaseAssets(wheel=wheel_path, bundle=bundle_path, archive=archive_path)

pywheels/overrides.json

@@ -0,0 +1,6 @@
+{
+  "dbt-oss": {
+    "strategy": "source-build-probe",
+    "note": "PyPI's dbt-oss sdist is a stub: its custom PEP 517 backend (_dbt_sa_build) downloads a prebuilt wheel from a hardcoded GitHub release URL keyed by platform tag, checked against an embedded sha256 manifest, with no real source to build otherwise. --only-binary=:all: can never see this - pip's index metadata never advertises a real wheel at all, stub or not - so a full source build (which actually invokes the backend) is the only way to know whether upstream truly covers a given platform."
+  }
+}

pywheels/verify.py

@@ -0,0 +1,330 @@
+"""Verification logic for python-wheels-builds artifacts.
+
+Two backends, tried in this order unless one is forced:
+
+  1. sigstore  - offline, no network needed at verify time, but requires
+                 the `sigstore` package (optional dependency) and a local
+                 attestation bundle.
+  2. gh        - the GitHub CLI, if it's on PATH. Needs network (it asks
+                 GitHub for attestations on the wheel's digest directly),
+                 but needs nothing installed via pip.
+
+If neither is available, verification of one of OUR OWN wheels fails
+loudly (VerificationError) rather than silently letting an unverified
+wheel through - this tool exists specifically to not do that. Deciding
+whether a requested package is even one of ours (vs. a plain upstream
+package pywheels doesn't attest, which is fine to install unverified with
+a warning) is an `install`-command concern, not this module's - see the
+docstring in cli.py.
+
+For a given wheel, a successful verification means:
+  1. Every attestation we actually asked for verifies, scoped to the exact
+     signer identity (repo + workflow file) - not just "signed by someone
+     using GitHub Actions OIDC".
+  2. Among those, there's a SLSA build-provenance attestation AND our own
+     upstream-source attestation - both required.
+  3. If a source archive is supplied, it hashes to the digest recorded in
+     the upstream-source predicate (snapshot_archive_sha256).
+
+Attestation types we didn't ask for (IGNORED_PREDICATE_TYPES) are recorded
+but never attempted or counted - see release/v0.2 below.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import importlib.util
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+OIDC_ISSUER = "https://token.actions.githubusercontent.com"
+BUILD_PROVENANCE_PREDICATE = "https://slsa.dev/provenance/v1"
+
+# GitHub auto-attaches this the moment a wheel becomes part of a published
+# Release. We never asked for it, its bundle has no Rekor tlog entry (so
+# sigstore-python can't even parse it), and nothing we do depends on it.
+# Record it, don't verify it, don't count it against the wheel.
+IGNORED_PREDICATE_TYPES = {
+    "https://in-toto.io/attestation/release/v0.2",
+}
+
+DEFAULT_UPSTREAM_PREDICATE_TYPE = "https://patrickryankenneth.github.io/attestations/upstream-source/v1"
+
+
+class VerificationError(Exception):
+    """Hard failure: missing files, unreadable bundle, or no usable
+    backend at all. A verified-but-failed check is a normal outcome
+    reported via VerifyReport.ok, not an exception."""
+
+
+def sigstore_available() -> bool:
+    return importlib.util.find_spec("sigstore") is not None
+
+
+def gh_available() -> bool:
+    return shutil.which("gh") is not None
+
+
+@dataclass
+class AttestationResult:
+    predicate_type: str
+    predicate: dict
+    verified: bool
+    detail: str
+    ignored: bool = False
+
+
+@dataclass
+class VerifyReport:
+    wheel: Path
+    backend: str = ""
+    attestations: list = field(default_factory=list)  # list[AttestationResult]
+    archive_checked: bool = False
+    archive_ok: Optional[bool] = None
+    # Set when archive_ok is False *because we never got predicate content
+    # to check against* (e.g. `gh attestation download` failed) rather than
+    # because we checked it and it genuinely didn't match. Still fails
+    # closed either way - see verify_wheel - but this lets callers show an
+    # actionable message instead of a bare "FAILED" that looks identical to
+    # a real hash mismatch.
+    archive_check_error: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        checked = [a for a in self.attestations if not a.ignored]
+        has_build_provenance = any(
+            a.verified and a.predicate_type == BUILD_PROVENANCE_PREDICATE for a in checked
+        )
+        has_upstream_source = any(
+            a.verified and a.predicate_type and a.predicate_type != BUILD_PROVENANCE_PREDICATE
+            for a in checked
+        )
+        archive_ok = self.archive_ok is not False  # not checked -> doesn't block
+        return has_build_provenance and has_upstream_source and archive_ok
+
+
+def _signer_identity(repo: str, workflow_file: str, ref: str) -> str:
+    return f"https://github.com/{repo}/.github/workflows/{workflow_file}@{ref}"
+
+
+def _signer_workflow(repo: str, workflow_file: str) -> str:
+    return f"{repo}/.github/workflows/{workflow_file}"
+
+
+def _split_bundle_lines(bundle_jsonl: Path) -> list:
+    """Each line of a `gh attestation download` bundle is a complete
+    Sigstore Bundle on its own. Split into temp files for per-bundle
+    verification."""
+    if not bundle_jsonl.exists():
+        raise VerificationError(f"attestation bundle not found: {bundle_jsonl}")
+    lines = [line for line in bundle_jsonl.read_text().splitlines() if line.strip()]
+    if not lines:
+        raise VerificationError(f"attestation bundle is empty: {bundle_jsonl}")
+    tmpdir = Path(tempfile.mkdtemp(prefix="pywheels-bundle-"))
+    paths = []
+    for i, line in enumerate(lines):
+        p = tmpdir / f"bundle-{i}.json"
+        p.write_text(line)
+        paths.append(p)
+    return paths
+
+
+def _decode_predicate(bundle_line_path: Path):
+    bundle = json.loads(bundle_line_path.read_text())
+    payload_b64 = bundle["dsseEnvelope"]["payload"]
+    statement = json.loads(base64.b64decode(payload_b64))
+    return statement.get("predicateType", ""), statement.get("predicate", {})
+
+
+# ---------------------------------------------------------------- sigstore
+
+def _sigstore_verify_identity(target: Path, bundle: Path, cert_identity: str, *, verbose: int = 0):
+    # sigstore's -v/-vv is a top-level flag (it sits on the `sigstore`
+    # parser, before the subcommand), not an option on `verify identity`
+    # itself - see `sigstore --help`.
+    cmd = [sys.executable, "-m", "sigstore"] + ["-v"] * verbose + [
+        "verify", "identity",
+        "--bundle", str(bundle),
+        "--cert-identity", cert_identity,
+        "--cert-oidc-issuer", OIDC_ISSUER,
+        "--offline",
+        str(target),
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    return proc.returncode == 0, (proc.stdout + proc.stderr).strip()
+
+
+def _verify_with_sigstore(wheel_path: Path, bundle_jsonl_path: Path, *, repo: str, workflow_file: str, ref: str,
+                           verbose: int = 0):
+    cert_identity = _signer_identity(repo, workflow_file, ref)
+    results = []
+    for line_path in _split_bundle_lines(bundle_jsonl_path):
+        predicate_type, predicate = _decode_predicate(line_path)
+        if predicate_type in IGNORED_PREDICATE_TYPES:
+            results.append(AttestationResult(
+                predicate_type, predicate, verified=False,
+                detail="not checked - known GitHub-native attestation, not one we asked for",
+                ignored=True,
+            ))
+            continue
+        ok, detail = _sigstore_verify_identity(wheel_path, line_path, cert_identity, verbose=verbose)
+        results.append(AttestationResult(predicate_type, predicate, verified=ok, detail=detail))
+    return results
+
+
+# --------------------------------------------------------------------- gh
+
+def _gh_verify_identity(wheel_path: Path, repo: str, signer_workflow: str, predicate_type: str, *, verbose: int = 0):
+    # `gh attestation verify` has no -v/--verbose of its own. The closest
+    # equivalent gh documents is --format=json, which dumps the full
+    # verification result instead of the one-line human summary - so
+    # that's what verbose asks for here rather than a made-up flag.
+    cmd = [
+        "gh", "attestation", "verify", str(wheel_path),
+        "--repo", repo,
+        "--signer-workflow", signer_workflow,
+        "--predicate-type", predicate_type,
+    ]
+    if verbose:
+        cmd += ["--format", "json"]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    return proc.returncode == 0, (proc.stdout + proc.stderr).strip()
+
+
+def _gh_download_bundle(wheel_path: Path, repo: str) -> Path:
+    tmpdir = Path(tempfile.mkdtemp(prefix="pywheels-gh-"))
+    # `gh` runs with cwd=tmpdir (below) so its output bundle lands somewhere
+    # we can glob cleanly, isolated from anything else in the caller's cwd.
+    # wheel_path may be relative (e.g. the CLI's default --workdir is
+    # ".pywheels-cache") - resolved against the CALLER's cwd, not tmpdir.
+    # Passing it through unresolved means `gh` looks for it relative to
+    # tmpdir instead, where it never exists - it then fails trying to open
+    # the wheel to hash it, in a way that reads like an attestation/archive
+    # problem but is really just this path bug. Resolve before handing it
+    # to a subprocess running in a different directory.
+    proc = subprocess.run(
+        ["gh", "attestation", "download", str(wheel_path.resolve()), "--repo", repo],
+        capture_output=True, text=True, cwd=tmpdir,
+    )
+    if proc.returncode != 0:
+        raise VerificationError(f"gh attestation download failed: {(proc.stderr or proc.stdout).strip()}")
+    matches = list(tmpdir.glob("*.jsonl"))
+    if not matches:
+        raise VerificationError("gh attestation download did not produce a bundle file")
+    return matches[0]
+
+
+def _verify_with_gh(wheel_path: Path, *, repo: str, workflow_file: str, upstream_predicate_type: str,
+                     verbose: int = 0):
+    signer_workflow = _signer_workflow(repo, workflow_file)
+    results = []
+
+    ok, detail = _gh_verify_identity(wheel_path, repo, signer_workflow, BUILD_PROVENANCE_PREDICATE, verbose=verbose)
+    results.append(AttestationResult(BUILD_PROVENANCE_PREDICATE, {}, verified=ok, detail=detail))
+
+    ok, detail = _gh_verify_identity(wheel_path, repo, signer_workflow, upstream_predicate_type, verbose=verbose)
+    results.append(AttestationResult(upstream_predicate_type, {}, verified=ok, detail=detail))
+
+    # Bonus, not required: pull predicate content too, purely for the
+    # archive-digest check below. A plain download - no sigstore parsing.
+    # NOTE: this can fail for reasons that have nothing to do with the
+    # wheel itself or with the identity checks above - `gh attestation
+    # download` is a separate code path in `gh` from `verify identity` and
+    # can fail on its own (network blip, rate limit, a `gh` bug, etc). The
+    # identity checks above already ran and stand on their own, so we
+    # don't turn this into a VerificationError - but we DO surface *why*
+    # it failed instead of swallowing it, so a caller checking the archive
+    # digest afterward can tell "we never got to check" apart from "we
+    # checked and it didn't match", and can actually see the real reason
+    # instead of guessing. See VerifyReport.archive_check_error.
+    download_error = None
+    try:
+        bundle_path = _gh_download_bundle(wheel_path, repo)
+        for line_path in _split_bundle_lines(bundle_path):
+            predicate_type, predicate = _decode_predicate(line_path)
+            for r in results:
+                if r.predicate_type == predicate_type and not r.predicate:
+                    r.predicate = predicate
+    except VerificationError as exc:
+        download_error = str(exc)
+
+    return results, download_error
+
+
+# ------------------------------------------------------------------- main
+
+def verify_wheel(
+    wheel_path: Path,
+    bundle_jsonl_path: Optional[Path] = None,
+    *,
+    repo: str,
+    workflow_file: str,
+    ref: str = "refs/heads/main",
+    upstream_predicate_type: str = DEFAULT_UPSTREAM_PREDICATE_TYPE,
+    source_archive_path: Optional[Path] = None,
+    backend: str = "auto",
+    verbose: int = 0,
+) -> VerifyReport:
+    if not wheel_path.exists():
+        raise VerificationError(f"wheel not found: {wheel_path}")
+
+    chosen = backend
+    if chosen == "auto":
+        if sigstore_available():
+            chosen = "sigstore"
+        elif gh_available():
+            chosen = "gh"
+        else:
+            raise VerificationError(
+                "no verification backend available - install sigstore (`pip install sigstore`) "
+                "or the GitHub CLI (`gh`, see https://cli.github.com). Run `pywheels doctor` for "
+                "details. Refusing to treat an unverifiable wheel as trusted."
+            )
+
+    report = VerifyReport(wheel=wheel_path, backend=chosen)
+
+    if chosen == "sigstore":
+        if bundle_jsonl_path is None:
+            raise VerificationError("sigstore backend requires a local attestation bundle")
+        report.attestations = _verify_with_sigstore(
+            wheel_path, bundle_jsonl_path, repo=repo, workflow_file=workflow_file, ref=ref, verbose=verbose,
+        )
+    elif chosen == "gh":
+        report.attestations, report.archive_check_error = _verify_with_gh(
+            wheel_path, repo=repo, workflow_file=workflow_file, upstream_predicate_type=upstream_predicate_type,
+            verbose=verbose,
+        )
+    else:
+        raise VerificationError(f"unknown backend: {chosen!r}")
+
+    if source_archive_path is not None:
+        report.archive_checked = True
+        expected = next(
+            (a.predicate["snapshot_archive_sha256"] for a in report.attestations
+             if a.verified and a.predicate and "snapshot_archive_sha256" in a.predicate),
+            None,
+        )
+        if expected is None:
+            # Still fail closed - we have no digest to trust the archive
+            # against, whether that's because the predicate genuinely
+            # doesn't carry one or because we never fetched it. But make
+            # the two cases distinguishable to the caller: if a download
+            # error is on record, this ISN'T a real digest mismatch.
+            report.archive_ok = False
+            if report.archive_check_error is None:
+                report.archive_check_error = (
+                    "no snapshot_archive_sha256 found in any verified attestation's predicate "
+                    "(predicate content was retrieved, but the digest was genuinely absent)"
+                )
+        else:
+            actual = hashlib.sha256(source_archive_path.read_bytes()).hexdigest()
+            report.archive_ok = (actual == expected)
+
+    return report