chtypes 2.0.0.dev8__py3-none-any.whl → 2.0.0.dev10__py3-none-any.whl

chtypes/__init__.py

@@ -69,6 +69,7 @@ from .errors import (
     CODE_ARTIFACT_INCOMPATIBLE,
     CODE_ARTIFACT_MISSING,
     CODE_ARTIFACT_PINNED,
+    CODE_ARTIFACT_REVOKED,
     CODE_ARTIFACT_UNPUBLISHED,
     CODE_ARTIFACT_UNTRUSTED,
     CODE_CACHE_UNUSABLE,
@@ -77,17 +78,20 @@ from .errors import (
     CODE_SOURCE_RETIRED,
     CODE_SOURCE_UNAUTHORIZED,
     CODE_SOURCE_UNREACHABLE,
+    Advisory,
     ArtifactCorruptError,
     ArtifactError,
     ArtifactIncompatibleError,
     ArtifactMissingError,
     ArtifactPinnedError,
+    ArtifactRevokedError,
     ArtifactUnpublishedError,
     ArtifactUntrustedError,
     CacheUnusableError,
     CallError,
     ChtypesError,
     InternalError,
+    Revocation,
     SchemaError,
     SourceForbiddenError,
     SourceIncompatibleError,
@@ -130,6 +134,7 @@ __all__ = [
     "CODE_ARTIFACT_INCOMPATIBLE",
     "CODE_ARTIFACT_MISSING",
     "CODE_ARTIFACT_PINNED",
+    "CODE_ARTIFACT_REVOKED",
     "CODE_ARTIFACT_UNPUBLISHED",
     "CODE_ARTIFACT_UNTRUSTED",
     "CODE_CACHE_UNUSABLE",
@@ -139,11 +144,13 @@ __all__ = [
     "CODE_SOURCE_UNAUTHORIZED",
     "CODE_SOURCE_UNREACHABLE",
     "EXPORT_NONE",
+    "Advisory",
     "ArtifactCorruptError",
     "ArtifactError",
     "ArtifactIncompatibleError",
     "ArtifactMissingError",
     "ArtifactPinnedError",
+    "ArtifactRevokedError",
     "ArtifactUnpublishedError",
     "ArtifactUntrustedError",
     "AtMergeEntry",
@@ -183,6 +190,7 @@ __all__ = [
     "Reason",
     "Registry",
     "Resolved",
+    "Revocation",
     "RowResult",
     "Schema",
     "SchemaDescription",

chtypes/__main__.py

@@ -3,6 +3,7 @@
 
     chtypes fetch <spelling>... | --all  [--platform <os-arch>] [--cache <dir>] [--lock <file>]
                                          [--frozen] [--offline] [--update] [--strict]
+                                         [--allow-revoked] [--require-revocation-check]
     chtypes verify [--cache <dir>] [--strict]   re-verify every installed build
     chtypes list   [--cache <dir>] [--offline] [--strict]
     chtypes where  [--cache <dir>] [--strict] [--all]   the cache root; --all: every search dir
@@ -37,7 +38,7 @@ from collections.abc import Sequence
 
 from . import __version__ as chtypes_version
 from . import _ocifetch as fetch_layer
-from ._codes import CODE_ARTIFACT_CORRUPT
+from ._codes import CODE_ARTIFACT_CORRUPT, CODE_ARTIFACT_REVOKED
 from ._ocifetch import _channel
 from ._ocifetch import _constants as C
 from ._ocifetch._ensure import _translate_transport_error, detect_host_platform, missing_notes
@@ -148,6 +149,19 @@ def build_parser() -> argparse.ArgumentParser:
             "(or set CHTYPES_OFFLINE=1)"
         ),
     )
+    fetch.add_argument(
+        "--allow-revoked",
+        action="store_true",
+        help=(
+            "use a build a verified revocation refuses, with one warning "
+            "(this call only; never --lock or --update)"
+        ),
+    )
+    fetch.add_argument(
+        "--require-revocation-check",
+        action="store_true",
+        help="a revocation status that cannot be read is the transport's error, not a warning",
+    )
 
     verify = sub.add_parser(
         "verify",
@@ -249,6 +263,8 @@ def _options(args: argparse.Namespace, *, platform: str | None = None):
         lock_path=lock_path,
         lock_write=lock_write,
         update=getattr(args, "update", False),
+        allow_revoked=getattr(args, "allow_revoked", False),
+        require_revocation_check=getattr(args, "require_revocation_check", False),
     )
     return fetch._to_options(platform)
 
@@ -348,10 +364,23 @@ def _cmd_verify(args: argparse.Namespace) -> int:
         return EXIT_OK
     _say_notes(options)
     failed = 0
+    revoked = 0
     for r in results:
-        if not r.ok:
+        if r.revocation is not None:
+            # A build a stored revocation refuses (docs/guides/fetch-v1.md,
+            # "Build-level revocation"); it is reported whatever its bytes say.
+            revoked += 1
+            _say(f"REVOKED {r.version} {r.platform} {r.dir}: {r.detail}")
+        elif not r.ok:
             failed += 1
             _say(f"chtypes: FAILED {r.version} {r.platform} {r.dir}: {r.detail}")
+    if revoked:
+        # Exit 11 wins over a mismatch's 1: a revocation is the more specific finding.
+        _say(
+            f"chtypes: {revoked} of {len(results)} installed build(s) are revoked "
+            f"[{CODE_ARTIFACT_REVOKED}]"
+        )
+        return C.ERROR_EXIT_CODES[CODE_ARTIFACT_REVOKED]
     if failed:
         _say(f"chtypes: {failed} of {len(results)} installed build(s) FAILED verification")
         return C.ERROR_EXIT_CODES[CODE_ARTIFACT_CORRUPT]

chtypes/_advisory.py

@@ -0,0 +1,38 @@
+"""What a `CHTYPES_ARTIFACT_REVOKED` error carries for programs
+(docs/guides/fetch-v1.md, "Build-level revocation"; public issue #625).
+
+A leaf module, so the fetch layer's errors and the public ones share the two
+types without importing each other."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["Advisory", "Revocation"]
+
+
+@dataclass(frozen=True)
+class Advisory:
+    """One advisory a revocation names, every string made safe to print. A
+    signed revocation's carries its `revoked_at`; a 410's carries the `build` it
+    names, newest first. A field the source did not send is "". `class_` is the
+    advisory's `class` (a keyword in Python)."""
+
+    id: str = ""
+    url: str = ""
+    class_: str = ""
+    summary: str = ""
+    build: str = ""
+    superseded_by: str = ""
+    revoked_at: str = ""
+
+
+@dataclass(frozen=True)
+class Revocation:
+    """`signed` is true for a verified, signed revocation of `manifest`, whose
+    one advisory it is, and false for a 410's body, which is unsigned, names no
+    manifest (`manifest` is "") and lists one advisory per revoked build."""
+
+    signed: bool = False
+    manifest: str = ""
+    advisories: tuple[Advisory, ...] = ()

chtypes/_codes.py

@@ -1,6 +1,6 @@
 # Code generated by scripts/fetch-v1/gen-constants.py from
 # spec/fetch-v1/constants.json. DO NOT EDIT.
-# Source sha256: 82afa8d6cba96c10b5945c6f7c1c8360a504cc8ac6231e74017cc6c20b908df6
+# Source sha256: 5aa3d14a5d8b60399040a8242f003135fa5f6c2c402de7d4e2db4c768a3366ae
 """The shared error codes (docs/guides/fetch-v1.md §8), one per entry of the
 fetch constants' `errors`, in their order. `chtypes.errors` re-exports them
 (docs/reference/bindings-v1.md §4, the codes)."""
@@ -21,3 +21,4 @@ CODE_SOURCE_INCOMPATIBLE: Final[str] = "CHTYPES_SOURCE_INCOMPATIBLE"
 CODE_ARTIFACT_INCOMPATIBLE: Final[str] = "CHTYPES_ARTIFACT_INCOMPATIBLE"
 CODE_CACHE_UNUSABLE: Final[str] = "CHTYPES_CACHE_UNUSABLE"
 CODE_SOURCE_RETIRED: Final[str] = "CHTYPES_SOURCE_RETIRED"
+CODE_ARTIFACT_REVOKED: Final[str] = "CHTYPES_ARTIFACT_REVOKED"

chtypes/_decode.py

@@ -431,8 +431,9 @@ def decode_batch(raw: bytes, export: bytes | None) -> BatchResult:
     export_declined = _bytes(obj, "export_declined", where)
     if export_declined:
         # A declined export has no payload and no spans, whatever buffer the call
-        # returned: the library may hand back a zero-length one, so the document's
-        # export_declined decides, never the buffer's length.
+        # returned: the library returns a NULL out_export for it (builds up to
+        # 20261011.105019 returned a zero-length buffer), and the document's
+        # export_declined decides, never the buffer.
         export, spans = None, None
     return BatchResult(
         outcome=Outcome.of(_text(obj, "outcome", where)),

chtypes/_input.py

@@ -45,6 +45,31 @@ def body_bytes(value: bytes, what: str = "body") -> bytes:
     raise TypeError(f"{what} must be bytes, not {type(value).__name__}")
 
 
+_NON_UTF8_HINT = (
+    "this ABI generation cannot carry a non-UTF-8 value in a JSON input; "
+    "write the bytes as unhex('<hex>') in the expression instead"
+)
+
+
+def _is_utf8(text: str) -> bool:
+    """False for a `str` that cannot be UTF-8 encoded (a lone surrogate, as
+    `surrogateescape` makes of undecodable bytes)."""
+    try:
+        text.encode("utf-8")
+    except UnicodeEncodeError:
+        return False
+    return True
+
+
+def _refuse_non_utf8(what: str, part: str, key: str) -> Exception:
+    # The key is shown escaped (ASCII only), never as the raw text.
+    return misuse(
+        f"{what}: the key {json.dumps(key)} is not valid UTF-8, and {_NON_UTF8_HINT}"
+        if part == "key"
+        else f"{what}: the value for key {json.dumps(key)} is not valid UTF-8, and {_NON_UTF8_HINT}"
+    )
+
+
 def _string_map(mapping: Mapping[str, str], what: str) -> dict[str, str]:
     out: dict[str, str] = {}
     for key, value in mapping.items():
@@ -53,6 +78,12 @@ def _string_map(mapping: Mapping[str, str], what: str) -> dict[str, str]:
                 f"{what} maps strings to strings only; got {type(key).__name__} -> "
                 f"{type(value).__name__} for {key!r} (a value is never rewritten)"
             )
+        # json.dumps would write a lone surrogate as a \udXXX escape, a value
+        # the library does not read as the bytes the caller meant: refuse.
+        if not _is_utf8(key):
+            raise _refuse_non_utf8(what, "key", key)
+        if not _is_utf8(value):
+            raise _refuse_non_utf8(what, "value", key)
         out[key] = value
     return out
 
@@ -75,6 +106,8 @@ def settings_json(
     if session_timezone is not None:
         if not isinstance(session_timezone, str):
             raise TypeError(f"session_timezone must be str, not {type(session_timezone).__name__}")
+        if not _is_utf8(session_timezone):
+            raise misuse(f"the zone: the value is not valid UTF-8, and {_NON_UTF8_HINT}")
         if _ZONE_KEY in merged:
             raise misuse(
                 f"the {_ZONE_KEY} option and a {_ZONE_KEY} settings key were both given; "
@@ -141,10 +174,12 @@ def server_profile_json(profile: ServerProfile) -> bytes:
     if profile.timezone is not None:
         if not isinstance(profile.timezone, str):
             raise TypeError(f"timezone must be str, not {type(profile.timezone).__name__}")
+        if not _is_utf8(profile.timezone):
+            raise misuse(f"server profile: the timezone is not valid UTF-8, and {_NON_UTF8_HINT}")
         if profile.timezone != "":
             doc["timezone"] = profile.timezone
     if profile.settings is not None:
-        doc["settings"] = _string_map(profile.settings, "settings")
+        doc["settings"] = _string_map(profile.settings, "server profile settings")
     if profile.macros is not None:
-        doc["macros"] = _string_map(profile.macros, "macros")
+        doc["macros"] = _string_map(profile.macros, "server profile macros")
     return _dump(doc)

chtypes/_ocifetch/__init__.py

@@ -4,7 +4,7 @@ Not part of this package's public API: every name here is subject to change
 without notice until the v1 switch. `_constants` is generated; the fetch
 logic lives in sibling modules. The seam (docs/guides/fetch-v1.md "The seam")
 is the only surface anything outside this package may use: `ensure`,
-`resolve_installed`, `list_installed`, `verify_installed` and
+`resolve_installed`, `check_installed`, `list_installed`, `verify_installed` and
 `fetch_signed`, plus the `Request`/`Options`/`Resolved`/
 `VerifyResult` shapes they take and return; and beside it the CLI's `resolve`
 and `prune` and the registry's in-use `hold` (§1, "In use"). Every other module here
@@ -25,9 +25,11 @@ from chtypes._ocifetch._ensure import (
     Request,
     Resolved,
     VerifyResult,
+    check_installed,
     ensure,
     fetch_signed,
     list_installed,
+    reset_revocation_memo_for_tests,
     resolve_installed,
     verify_installed,
 )
@@ -43,11 +45,13 @@ __all__ = [
     "Resolved",
     "Superseded",
     "VerifyResult",
+    "check_installed",
     "ensure",
     "fetch_signed",
     "hold",
     "list_installed",
     "prune",
+    "reset_revocation_memo_for_tests",
     "resolve",
     "resolve_each",
     "resolve_installed",

chtypes/_ocifetch/_channel.py

@@ -133,6 +133,10 @@ class Channel:
     # lookups see only records signed with it. "" does neither (the v1 contract
     # and every production channel).
     own_fingerprint: str = ""
+    # Build-level revocation (_revocation.py; docs/guides/fetch-v1.md, "Build-level
+    # revocation"): generation 2, the dev channel and the production one. The v1
+    # contract has none of it.
+    revocation: bool = False
 
 
 # What a 2.0.0-dev SDK speaks, and what every process speaks unless a test
@@ -149,6 +153,7 @@ DEV_CHANNEL: Final = Channel(
     overridable=False,
     pinnable=False,
     own_fingerprint=CHS_ABI_FINGERPRINT.removeprefix("sha256:"),
+    revocation=True,
 )
 
 # The v1 contract the fetch-v1 conformance cases specify, from the generated
@@ -183,6 +188,7 @@ PROD_V2_CHANNEL: Final = Channel(
     keys=C.RELEASE_KEYS,
     overridable=True,
     pinnable=True,
+    revocation=True,
 )
 
 _lock = threading.Lock()

chtypes/_ocifetch/_constants.py

@@ -1,6 +1,6 @@
 # Code generated by scripts/fetch-v1/gen-constants.py from
 # spec/fetch-v1/constants.json. DO NOT EDIT.
-# Source sha256: 82afa8d6cba96c10b5945c6f7c1c8360a504cc8ac6231e74017cc6c20b908df6
+# Source sha256: 5aa3d14a5d8b60399040a8242f003135fa5f6c2c402de7d4e2db4c768a3366ae
 """The v1 fetch constants, generated: see docs/guides/fetch-v1.md."""
 
 from __future__ import annotations
@@ -46,6 +46,7 @@ ARTIFACT_TYPE: Final[str] = "application/vnd.wavehouse.chtypes.artifact.v1"
 GOLDENS_ARTIFACT_TYPE: Final[str] = "application/vnd.wavehouse.chtypes.goldens.v1"
 FIXTURES_ARTIFACT_TYPE: Final[str] = "application/vnd.wavehouse.chtypes.sdk-fetch-fixtures.v1"
 CHANNEL_ARTIFACT_TYPE: Final[str] = "application/vnd.wavehouse.chtypes.channel.v1"
+REVOCATION_ARTIFACT_TYPE: Final[str] = "application/vnd.wavehouse.chtypes.revocation.v1"
 
 DSSE_PAYLOAD_TYPE: Final[str] = "application/vnd.in-toto+json"
 DSSE_MAX_SIGNATURES: Final[int] = 4
@@ -56,6 +57,7 @@ PREDICATE_TYPE_ARTIFACT: Final[str] = "https://artifacts.wavehouse.dev/spec/arti
 PREDICATE_TYPE_GOLDENS: Final[str] = "https://artifacts.wavehouse.dev/spec/goldens/v1"
 PREDICATE_TYPE_FIXTURES: Final[str] = "https://artifacts.wavehouse.dev/spec/sdk-fetch-fixtures/v1"
 PREDICATE_TYPE_CHANNEL: Final[str] = "https://artifacts.wavehouse.dev/spec/channel/v1"
+PREDICATE_TYPE_REVOCATION: Final[str] = "https://artifacts.wavehouse.dev/spec/revocation/v1"
 
 KEYID_ALGORITHM: Final[str] = "sha256-first16hex"
 RELEASE_KEYS: Final[tuple[dict[str, str], ...]] = (
@@ -87,6 +89,7 @@ RETIRED_STATUSES: Final[tuple[int, ...]] = (410,)
 
 CONNECT_TIMEOUT_S: Final[float] = 30.0
 IDLE_READ_TIMEOUT_S: Final[float] = 60.0
+REVOCATION_CHECK_S: Final[float] = 5.0
 
 MANIFEST_MAX_BYTES: Final[int] = 4194304
 BUNDLE_MAX_BYTES: Final[int] = 1048576
@@ -109,6 +112,7 @@ PROD_V2_BASES: Final[tuple[str, ...]] = ("https://registry.wavehouse.dev/chtypes
 PROD_V2_SYSTEM_DIRS: Final[tuple[str, ...]] = ("/usr/local/share/chtypes/v2", "/opt/chtypes/v2")
 CACHE_UNPACKED_DIR: Final[str] = "unpacked/sha256"
 CACHE_VERIFIED_RECORD: Final[str] = "verified.json"
+CACHE_REVOCATION_RECORD: Final[str] = "revocation.json"
 CACHE_ANNOTATION_PREFIX: Final[str] = "dev.wavehouse.chtypes."
 
 LOCK_SCHEMA: Final[int] = 3
@@ -132,4 +136,5 @@ ERROR_EXIT_CODES: Final[dict[str, int]] = {
     "CHTYPES_ARTIFACT_INCOMPATIBLE": 8,
     "CHTYPES_CACHE_UNUSABLE": 9,
     "CHTYPES_SOURCE_RETIRED": 10,
+    "CHTYPES_ARTIFACT_REVOKED": 11,
 }