API: Remove unnecessary jargon (#402)

* refactor: `rekor` -> `transparency` in public APIs

Signed-off-by: William Woodruff <william@trailofbits.com>

* _cli: fix import

Signed-off-by: William Woodruff <william@trailofbits.com>

* treewide: switch from pdoc3 to pdoc

Signed-off-by: William Woodruff <william@trailofbits.com>

* docs: tweak Python version constraint

Signed-off-by: William Woodruff <william@trailofbits.com>

* _cli: lintage

Signed-off-by: William Woodruff <william@trailofbits.com>

* docs: rename workflow

...allows us to make a nicer automatic badge.

Signed-off-by: William Woodruff <william@trailofbits.com>

* README: link to API docs

Signed-off-by: William Woodruff <william@trailofbits.com>

Signed-off-by: William Woodruff <william@trailofbits.com>

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: docs-deploy
+name: Documentation
 
 on:
   push:
@@ -16,14 +16,21 @@ jobs:
 
       - uses: actions/setup-python@v4
         with:
-          python-version: ">= 3.7"
+          # NOTE: We use 3.10+ typing syntax via future, which pdoc only
+          # understands if it's actually run with Python 3.10 or newer.
+          python-version: ">= 3.10"
           cache: "pip"
           cache-dependency-path: pyproject.toml
 
+      - name: setup
+        run: |
+          make dev SIGSTORE_EXTRA=doc
+
       - name: docs
         run: |
           make doc
-          mv ./html/sigstore /tmp/sigstore
+          mv ./html/ /tmp/sigstore
+
       - name: deploy
         run: |
           # Configure git, checkout a new orphan branch for the docs.

CONTRIBUTING.md

@@ -88,8 +88,8 @@ If you're running Python 3.7 or newer, you can run the documentation build local
 make doc
 ```
 
-`sigstore` uses [`pdoc3`](https://github.com/pdoc3/pdoc) to generate HTML documentation for
-the public Python APIs.
+`sigstore` uses [`pdoc`](https://github.com/mitmproxy/pdoc) to generate HTML
+documentation for the public Python APIs.
 
 ### Releasing
 
@@ -141,5 +141,5 @@ in changes to `sigstore`'s CLI, please record them under the "Unreleased" sectio
 with an entry in an appropriate subsection ("Added", "Changed", "Removed", or "Fixed").
 
 * Ensure your commits are signed off, as sigstore uses the
-[DCO](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin). 
+[DCO](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin).
 You can do it using `git commit -s`, or `git commit -s --amend` if you want to amend already existing commits.

Makefile

@@ -40,7 +40,6 @@ all:
 
 env/pyvenv.cfg: pyproject.toml
 	# Create our Python 3 virtual environment
-	rm -rf env
 	python3 -m venv env
 	./env/bin/python -m pip install --upgrade pip
 	./env/bin/python -m pip install -e .[$(SIGSTORE_EXTRA)]
@@ -78,8 +77,7 @@ test: env/pyvenv.cfg
 .PHONY: doc
 doc: env/pyvenv.cfg
 	. env/bin/activate && \
-		command -v pdoc3 && \
-		PYTHONWARNINGS='error::UserWarning' pdoc --force --html $(PY_MODULE)
+		pdoc --output-directory html $(PY_MODULE)
 
 .PHONY: package
 package: env/pyvenv.cfg

README.md

@@ -60,6 +60,8 @@ for more details and usage examples.
 
 ## Usage
 
+For Python API usage, see our [documentation](https://sigstore.github.io/sigstore-python/).
+
 You can run `sigstore` as a standalone program, or via `python -m`:
 
 ```console

pyproject.toml

@@ -69,11 +69,13 @@ lint = [
   # See: https://github.com/python/typeshed/issues/8699
   # "types-pyOpenSSL",
 ]
+doc = [
+  "pdoc",
+]
 dev = [
   "build",
   "bump >= 1.3.2",
-  "pdoc3",
-  "sigstore[test,lint]",
+  "sigstore[doc,test,lint]",
 ]
 
 [tool.isort]

sigstore/_cli.py

@@ -41,8 +41,8 @@
     Issuer,
     detect_credential,
 )
-from sigstore.rekor import RekorEntry
 from sigstore.sign import Signer
+from sigstore.transparency import LogEntry
 from sigstore.verify import (
     CertificateVerificationFailure,
     RekorEntryMissing,
@@ -785,7 +785,7 @@ def _collect_verification_state(
         logger.debug(f"Using signature from: {inputs['sig']}")
         b64_signature = inputs["sig"].read_text()
 
-        entry: Optional[RekorEntry] = None
+        entry: Optional[LogEntry] = None
         if inputs["bundle"].is_file():
             logger.debug(f"Using offline Rekor bundle from: {inputs['bundle']}")
             bundle = RekorBundle.parse_file(inputs["bundle"])

sigstore/_internal/merkle.py

@@ -26,7 +26,7 @@
 import struct
 from typing import List, Tuple
 
-from sigstore.rekor import RekorEntry
+from sigstore.transparency import LogEntry
 
 
 class InvalidInclusionProofError(Exception):
@@ -95,7 +95,7 @@ def _hash_leaf(leaf: bytes) -> bytes:
     return hashlib.sha256(data).digest()
 
 
-def verify_merkle_inclusion(entry: RekorEntry) -> None:
+def verify_merkle_inclusion(entry: LogEntry) -> None:
     """Verify the Merkle Inclusion Proof for a given Rekor entry."""
     inclusion_proof = entry.inclusion_proof
     if inclusion_proof is None:

sigstore/_internal/rekor/client.py

@@ -34,7 +34,7 @@
 from sigstore._internal.ctfe import CTKeyring
 from sigstore._internal.tuf import TrustUpdater
 from sigstore._utils import base64_encode_pem_cert
-from sigstore.rekor import RekorEntry
+from sigstore.transparency import LogEntry
 
 logger = logging.getLogger(__name__)
 
@@ -67,12 +67,12 @@ class Config:
     signed_entry_timestamp: StrictStr = Field(alias="SignedEntryTimestamp")
     payload: RekorBundle._Payload = Field(alias="Payload")
 
-    def to_entry(self) -> RekorEntry:
+    def to_entry(self) -> LogEntry:
         """
         Creates a `RekorEntry` from this offline Rekor bundle.
         """
 
-        return RekorEntry(
+        return LogEntry(
             uuid=None,
             body=self.payload.body,
             integrated_time=self.payload.integrated_time,
@@ -83,7 +83,7 @@ def to_entry(self) -> RekorEntry:
         )
 
     @classmethod
-    def from_entry(cls, entry: RekorEntry) -> RekorBundle:
+    def from_entry(cls, entry: LogEntry) -> RekorBundle:
         """
         Returns a `RekorBundle` for this `RekorEntry`.
         """
@@ -171,7 +171,7 @@ class RekorEntries(_Endpoint):
 
     def get(
         self, *, uuid: Optional[str] = None, log_index: Optional[int] = None
-    ) -> RekorEntry:
+    ) -> LogEntry:
         """
         Retrieve a specific log entry, either by UUID or by log index.
 
@@ -191,14 +191,14 @@ def get(
             resp.raise_for_status()
         except requests.HTTPError as http_error:
             raise RekorClientError from http_error
-        return RekorEntry._from_response(resp.json())
+        return LogEntry._from_response(resp.json())
 
     def post(
         self,
         b64_artifact_signature: str,
         sha256_artifact_hash: str,
         b64_cert: str,
-    ) -> RekorEntry:
+    ) -> LogEntry:
         """
         Submit a new entry for inclusion in the Rekor log.
         """
@@ -223,7 +223,7 @@ def post(
         except requests.HTTPError as http_error:
             raise RekorClientError from http_error
 
-        return RekorEntry._from_response(resp.json())
+        return LogEntry._from_response(resp.json())
 
     @property
     def retrieve(self) -> RekorEntriesRetrieve:
@@ -245,7 +245,7 @@ def post(
         signature: bytes,
         artifact_hash: str,
         certificate: Certificate,
-    ) -> Optional[RekorEntry]:
+    ) -> Optional[LogEntry]:
         """
         Retrieves an extant Rekor entry, identified by its artifact signature,
         artifact hash, and signing certificate.
@@ -290,9 +290,9 @@ def post(
         # We select the oldest entry for our actual return value,
         # since a malicious actor could conceivably spam the log with
         # newer duplicate entries.
-        oldest_entry: Optional[RekorEntry] = None
+        oldest_entry: Optional[LogEntry] = None
         for result in results:
-            entry = RekorEntry._from_response(result)
+            entry = LogEntry._from_response(result)
             if (
                 oldest_entry is None
                 or entry.integrated_time < oldest_entry.integrated_time

sigstore/_internal/set.py

@@ -23,7 +23,7 @@
 from cryptography.hazmat.primitives import hashes
 
 from sigstore._internal.rekor import RekorClient
-from sigstore.rekor import RekorEntry
+from sigstore.transparency import LogEntry
 
 
 class InvalidSetError(Exception):
@@ -34,7 +34,7 @@ class InvalidSetError(Exception):
     pass
 
 
-def verify_set(client: RekorClient, entry: RekorEntry) -> None:
+def verify_set(client: RekorClient, entry: LogEntry) -> None:
     """
     Verify the Signed Entry Timestamp for a given Rekor `entry` using the given `client`.
     """

sigstore/sign.py

@@ -35,7 +35,7 @@
 from sigstore._internal.sct import verify_sct
 from sigstore._internal.tuf import TrustUpdater
 from sigstore._utils import sha256_streaming
-from sigstore.rekor import RekorEntry
+from sigstore.transparency import LogEntry
 
 logger = logging.getLogger(__name__)
 
@@ -165,7 +165,7 @@ class SigningResult(BaseModel):
     The base64-encoded signature.
     """
 
-    log_entry: RekorEntry
+    log_entry: LogEntry
     """
     A record of the Rekor log entry for the signing operation.
     """

sigstore/rekor.py → sigstore/transparency.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 """
-Data structures returned by Rekor.
+Transparency log data structures.
 """
 
 from __future__ import annotations
@@ -26,31 +26,31 @@
 
 
 @dataclass(frozen=True)
-class RekorEntry:
+class LogEntry:
     """
-    Represents a Rekor log entry.
+    Represents a transparency log entry.
 
-    Log entries are retrieved from Rekor after signing or verification events,
-    or generated from "offline" Rekor bundles supplied by the user.
+    Log entries are retrieved from the transparency log after signing or verification events,
+    or generated from "offline" log entry bundles supplied by the user.
     """
 
     uuid: Optional[str]
     """
-    This entry's unique ID in the Rekor instance it was retrieved from.
+    This entry's unique ID in the log instance it was retrieved from.
 
-    For sharded Rekor deployments, IDs are unique per-shard.
+    For sharded log deployments, IDs are unique per-shard.
 
-    Not present for `RekorEntry` instances loaded from offline bundles.
+    Not present for `LogEntry` instances loaded from offline bundles.
     """
 
     body: str
     """
-    The base64-encoded body of the Rekor entry.
+    The base64-encoded body of the transparency log entry.
     """
 
     integrated_time: int
     """
-    The UNIX time at which this entry was integrated into the Rekor log.
+    The UNIX time at which this entry was integrated into the transparency log.
     """
 
     log_id: str
@@ -64,7 +64,7 @@ class RekorEntry:
     The index of this entry within the log.
     """
 
-    inclusion_proof: Optional["RekorInclusionProof"]
+    inclusion_proof: Optional["LogInclusionProof"]
     """
     An optional inclusion proof for this log entry.
 
@@ -77,9 +77,9 @@ class RekorEntry:
     """
 
     @classmethod
-    def _from_response(cls, dict_: dict[str, Any]) -> RekorEntry:
+    def _from_response(cls, dict_: dict[str, Any]) -> LogEntry:
         """
-        Create a new `RekorEntry` from the given API response.
+        Create a new `LogEntry` from the given API response.
         """
 
         # Assumes we only get one entry back
@@ -89,21 +89,21 @@ def _from_response(cls, dict_: dict[str, Any]) -> RekorEntry:
 
         uuid, entry = entries[0]
 
-        return RekorEntry(
+        return LogEntry(
             uuid=uuid,
             body=entry["body"],
             integrated_time=entry["integratedTime"],
             log_id=entry["logID"],
             log_index=entry["logIndex"],
-            inclusion_proof=RekorInclusionProof.parse_obj(
+            inclusion_proof=LogInclusionProof.parse_obj(
                 entry["verification"]["inclusionProof"]
             ),
             signed_entry_timestamp=entry["verification"]["signedEntryTimestamp"],
         )
 
     def encode_canonical(self) -> bytes:
         """
-        Returns a canonicalized JSON (RFC 8785) representation of the Rekor log entry.
+        Returns a canonicalized JSON (RFC 8785) representation of the transparency log entry.
 
         This encoded representation is suitable for verification against
         the Signed Entry Timestamp.
@@ -118,9 +118,9 @@ def encode_canonical(self) -> bytes:
         return encode_canonical(payload).encode()  # type: ignore
 
 
-class RekorInclusionProof(BaseModel):
+class LogInclusionProof(BaseModel):
     """
-    Represents an inclusion proof for a Rekor log entry.
+    Represents an inclusion proof for a transparency log entry.
     """
 
     log_index: StrictInt = Field(..., alias="logIndex")