opensysml 0.3.0__tar.gz → 0.3.2__tar.gz

{opensysml-0.3.0 → opensysml-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensysml
-Version: 0.3.0
+Version: 0.3.2
 Summary: Python client library for OpenSysML, a SysML v2 parser and execution runtime
 Author: Open-MBEE
 License-Expression: Apache-2.0
@@ -28,11 +28,11 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: grpcio>=1.83.0
 Requires-Dist: protobuf>=7.35.1
-Requires-Dist: filelock>=3.0.0
-Requires-Dist: psutil>=5.9.0
+Requires-Dist: sigstore<5,>=4.5.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: psutil>=5.9.0; extra == "dev"
 Requires-Dist: grpcio-tools>=1.83.0; extra == "dev"
 Requires-Dist: mypy>=1.8.0; extra == "dev"
 Requires-Dist: types-protobuf>=4.24.0; extra == "dev"
@@ -48,7 +48,7 @@ Python client for OpenSysML: parse, inspect and execute SysML v2 models over the
 `sysml-grpc` service.
 
 ```bash
-pip install opensysml             # from PyPI, once the first release is published
+pip install opensysml             # from PyPI
 pip install -e python/          # or from a checkout, at the repository root
 ```
 
@@ -60,8 +60,7 @@ print(model.eval("1 + 2 * 3"))                     # 7
 
 print(model.eval("mass", subject="Demo::sedan"))   # 1200.0 — that object, not the default
                                                    # requires the service's evaluate_subject
-                                                   # capability, rather than trusting a
-                                                   # service that would ignore the subject
+                                                   # capability; the client checks it first
 
 vehicle = model["Vehicle"]                         # by short name or FQN
 vehicle.attributes()                               # own and inherited, with resolved facts
@@ -87,22 +86,74 @@ Every call goes through the `sysml-grpc` service, which `opensysml` starts for y
 
 ## Service ownership
 
-`opensysml` never stops a service it did not start.
-
-- A connection that finds a healthy service already listening uses it and takes
-  no ownership of it: nothing is recorded, and closing the connection leaves the
-  service running. Whoever started it decides when it stops.
-- A service `opensysml` starts is recorded in
-  `~/.opensysml/sysml-grpc-<port>.pid` (`$OPENSYSML_STATE_DIR` overrides the
-  directory) as the service's pid and process start time, plus the pid and start
-  time of the process that started it. Only that process stops it, and only when
-  the last connection holding it is closed or the interpreter exits.
-- The start times are what authenticate the record: a pid is re-checked against
-  the start time written for it, so a pid the operating system has since reused
-  is treated as a stale record — cleaned up, never signalled. A command line
-  that merely looks like `sysml-grpc` is not identity and is never acted on.
-- A service that crashes leaves a record whose process is gone; the next
-  connection detects that, removes it and starts a service of its own.
+`opensysml` uses a service of its own, and never stops a service it did not
+start.
+
+- A connection made without naming a service starts a **private child** of this
+  interpreter. The child binds port 0, so the kernel assigns the port, and it
+  reports the address it was given on its stdout — no port is chosen, probed or
+  retried by the client, and two interpreters starting at once cannot collide.
+- One private child serves **every** connection of an interpreter that needs the
+  same service release. The first of them starts it; it stops when the last one
+  closes, or when the interpreter exits. Sharing it shares its parse cache,
+  which is what makes a second connection cheap (see below).
+- Its lifetime is this interpreter's. Nothing is recorded on disk about it, no
+  other process adopts it, and a service another process left listening is
+  neither reused nor cleaned up.
+- Connecting to a service `opensysml` did not start is explicit: pass a host and
+  port (`opensysml.connect("localhost", 50051)`, or `connect("localhost:50051")`),
+  set `$OPENSYSML_SERVICE=host:port`, or pass `auto_start=False` to require a
+  service the caller manages. Closing such a connection leaves it running.
+
+### No orphans
+
+The client holds the write end of the child's **stdin pipe** and never writes to
+it; the child reads its stdin and shuts down on end of file. Nothing else holds
+that write end, so the pipe closes when the owning process goes away — and it is
+the kernel that closes it, not any code of ours. That survives what an `atexit`
+hook or a supervisor thread does not: `SIGKILL`, `os._exit`, a fatal interpreter
+error, and a crash during shutdown. On an orderly close the client also closes
+stdin itself and then signals the child, so exit is prompt rather than eventual.
+
+The client signals only through the `Popen` object of the child it started, so no
+pid it did not start — including one the operating system has since reused —
+can be signalled. That guarantee no longer needs a start-time check to hold,
+because there is no pid on disk to re-authenticate.
+
+Per platform:
+
+- **Linux** and **macOS**: the child is started in a session of its own
+  (`start_new_session=True`), so a `SIGINT` or `SIGHUP` sent to the client's
+  process group does not reach it; stdin is what ends it. Other children the
+  client spawns do not inherit the write end, since CPython closes descriptors
+  across `subprocess` by default, so it has exactly one holder.
+- **Windows**: the operating system closes the same anonymous pipe when the
+  owning process exits, however it exits, so the guarantee is unchanged. Windows
+  has no `fork()`, so the case below cannot arise there.
+- **`fork()`**: the forked child inherits the write end, which would hold the
+  service open past its owner. An `os.register_at_fork` hook therefore disowns
+  the inherited services in the new process and closes its copy of the pipe: the
+  service stays tied to the process that started it, and a forked child that
+  connects starts one of its own.
+
+The single limitation is deliberate: a service reached explicitly is not tied to
+the client's lifetime, because the client does not own it.
+
+### Cost of a private child
+
+Measured on Linux with `python/scripts/measure_private_service.py` (n=20):
+
+|                                                       |     p50 |     p95 |
+| ----------------------------------------------------- | ------: | ------: |
+| first connection: spawn, bind, report, handshake      |  7.0 ms |  9.1 ms |
+| a later connection joining this interpreter's child   |  0.6 ms |  1.0 ms |
+| a child per connection, rather than one shared        | 29.6 ms | 54.6 ms |
+| parsing a model the shared child has already parsed   |  0.3 ms |  1.2 ms |
+| the same parse in a child of that connection's own    | 139.8 ms | 269.6 ms |
+
+The last two rows are why the child is per interpreter rather than per
+connection: a child per connection would not only spawn N times, it would parse
+each model N times, against a cache hit some 500x cheaper.
 
 ## Pinned release digests
 

{opensysml-0.3.0 → opensysml-0.3.2}/README.md

@@ -4,7 +4,7 @@ Python client for OpenSysML: parse, inspect and execute SysML v2 models over the
 `sysml-grpc` service.
 
 ```bash
-pip install opensysml             # from PyPI, once the first release is published
+pip install opensysml             # from PyPI
 pip install -e python/          # or from a checkout, at the repository root
 ```
 
@@ -16,8 +16,7 @@ print(model.eval("1 + 2 * 3"))                     # 7
 
 print(model.eval("mass", subject="Demo::sedan"))   # 1200.0 — that object, not the default
                                                    # requires the service's evaluate_subject
-                                                   # capability, rather than trusting a
-                                                   # service that would ignore the subject
+                                                   # capability; the client checks it first
 
 vehicle = model["Vehicle"]                         # by short name or FQN
 vehicle.attributes()                               # own and inherited, with resolved facts
@@ -43,22 +42,74 @@ Every call goes through the `sysml-grpc` service, which `opensysml` starts for y
 
 ## Service ownership
 
-`opensysml` never stops a service it did not start.
-
-- A connection that finds a healthy service already listening uses it and takes
-  no ownership of it: nothing is recorded, and closing the connection leaves the
-  service running. Whoever started it decides when it stops.
-- A service `opensysml` starts is recorded in
-  `~/.opensysml/sysml-grpc-<port>.pid` (`$OPENSYSML_STATE_DIR` overrides the
-  directory) as the service's pid and process start time, plus the pid and start
-  time of the process that started it. Only that process stops it, and only when
-  the last connection holding it is closed or the interpreter exits.
-- The start times are what authenticate the record: a pid is re-checked against
-  the start time written for it, so a pid the operating system has since reused
-  is treated as a stale record — cleaned up, never signalled. A command line
-  that merely looks like `sysml-grpc` is not identity and is never acted on.
-- A service that crashes leaves a record whose process is gone; the next
-  connection detects that, removes it and starts a service of its own.
+`opensysml` uses a service of its own, and never stops a service it did not
+start.
+
+- A connection made without naming a service starts a **private child** of this
+  interpreter. The child binds port 0, so the kernel assigns the port, and it
+  reports the address it was given on its stdout — no port is chosen, probed or
+  retried by the client, and two interpreters starting at once cannot collide.
+- One private child serves **every** connection of an interpreter that needs the
+  same service release. The first of them starts it; it stops when the last one
+  closes, or when the interpreter exits. Sharing it shares its parse cache,
+  which is what makes a second connection cheap (see below).
+- Its lifetime is this interpreter's. Nothing is recorded on disk about it, no
+  other process adopts it, and a service another process left listening is
+  neither reused nor cleaned up.
+- Connecting to a service `opensysml` did not start is explicit: pass a host and
+  port (`opensysml.connect("localhost", 50051)`, or `connect("localhost:50051")`),
+  set `$OPENSYSML_SERVICE=host:port`, or pass `auto_start=False` to require a
+  service the caller manages. Closing such a connection leaves it running.
+
+### No orphans
+
+The client holds the write end of the child's **stdin pipe** and never writes to
+it; the child reads its stdin and shuts down on end of file. Nothing else holds
+that write end, so the pipe closes when the owning process goes away — and it is
+the kernel that closes it, not any code of ours. That survives what an `atexit`
+hook or a supervisor thread does not: `SIGKILL`, `os._exit`, a fatal interpreter
+error, and a crash during shutdown. On an orderly close the client also closes
+stdin itself and then signals the child, so exit is prompt rather than eventual.
+
+The client signals only through the `Popen` object of the child it started, so no
+pid it did not start — including one the operating system has since reused —
+can be signalled. That guarantee no longer needs a start-time check to hold,
+because there is no pid on disk to re-authenticate.
+
+Per platform:
+
+- **Linux** and **macOS**: the child is started in a session of its own
+  (`start_new_session=True`), so a `SIGINT` or `SIGHUP` sent to the client's
+  process group does not reach it; stdin is what ends it. Other children the
+  client spawns do not inherit the write end, since CPython closes descriptors
+  across `subprocess` by default, so it has exactly one holder.
+- **Windows**: the operating system closes the same anonymous pipe when the
+  owning process exits, however it exits, so the guarantee is unchanged. Windows
+  has no `fork()`, so the case below cannot arise there.
+- **`fork()`**: the forked child inherits the write end, which would hold the
+  service open past its owner. An `os.register_at_fork` hook therefore disowns
+  the inherited services in the new process and closes its copy of the pipe: the
+  service stays tied to the process that started it, and a forked child that
+  connects starts one of its own.
+
+The single limitation is deliberate: a service reached explicitly is not tied to
+the client's lifetime, because the client does not own it.
+
+### Cost of a private child
+
+Measured on Linux with `python/scripts/measure_private_service.py` (n=20):
+
+|                                                       |     p50 |     p95 |
+| ----------------------------------------------------- | ------: | ------: |
+| first connection: spawn, bind, report, handshake      |  7.0 ms |  9.1 ms |
+| a later connection joining this interpreter's child   |  0.6 ms |  1.0 ms |
+| a child per connection, rather than one shared        | 29.6 ms | 54.6 ms |
+| parsing a model the shared child has already parsed   |  0.3 ms |  1.2 ms |
+| the same parse in a child of that connection's own    | 139.8 ms | 269.6 ms |
+
+The last two rows are why the child is per interpreter rather than per
+connection: a child per connection would not only spawn N times, it would parse
+each model N times, against a cache hit some 500x cheaper.
 
 ## Pinned release digests
 

{opensysml-0.3.0 → opensysml-0.3.2}/opensysml/__init__.py

@@ -3,7 +3,12 @@
 import warnings
 
 from opensysml._version import VERSION as _declared_version
-from opensysml.connection import Connection, DEFAULT_PORT, split_target
+from opensysml.connection import (
+    Connection,
+    DEFAULT_PORT,
+    named_target,
+    split_target,
+)
 from opensysml.model import Model
 from opensysml.symbol import Symbol
 from opensysml.diagnostic import Diagnostic
@@ -33,11 +38,11 @@ from opensysml.errors import (
     RenameReferencedError,
     OwnerNotFoundError, OwnerNotNamespaceError, IllegalMemberKindError,
     MemberNameTakenError, DeleteReferencedError,
-    InstanceTypeError, InvalidRequestError, ModelError,
+    InstanceTypeError, InvalidRequestError, ManifestSignatureError, ModelError,
     ModelFileNotFoundError, ModelNotFoundError, ServiceError,
     ServiceTimeoutError, StaleServiceError, SymbolNotFoundError,
-    TypeMismatchError, UnpinnedReleaseError, UnsupportedOperationError,
-    UnsupportedValueError, WrongKindError,
+    TypeMismatchError, UnpinnedReleaseError, UnsignedReleaseError,
+    UnsupportedOperationError, UnsupportedValueError, WrongKindError,
 )
 
 __all__ = [
@@ -57,11 +62,12 @@ __all__ = [
     "RenameReferencedError", "OverlappingEditsError", "EditResultError",
     "OwnerNotFoundError", "OwnerNotNamespaceError", "IllegalMemberKindError",
     "MemberNameTakenError", "DeleteReferencedError",
-    "InstanceTypeError", "InvalidRequestError", "MissingCapabilityError",
+    "InstanceTypeError", "InvalidRequestError", "ManifestSignatureError",
+    "MissingCapabilityError",
     "ModelError", "ModelFileNotFoundError", "ModelNotFoundError",
     "ServiceError", "ServiceTimeoutError", "StaleServiceError",
     "SymbolNotFoundError",
-    "TypeMismatchError", "UnpinnedReleaseError",
+    "TypeMismatchError", "UnpinnedReleaseError", "UnsignedReleaseError",
     "UnsupportedOperationError", "UnsupportedValueError",
     "WrongKindError",
     "load", "loads", "connect", "convert",
@@ -84,13 +90,15 @@ _default_connection_params = None
 def _get_default_connection(host='localhost', port=None):
     """Get or create the default module-level connection.
     
-    If called with different host/port than last time, creates new connection.
+    If called with a different service than last time, creates new connection.
     A ``host:port`` address written as the host names the same service as the
     two given separately, so it reuses the same connection.
     
     Args:
-        host (str): Service hostname, or a ``host:port`` address
-        port (int, optional): Service port (default: 50051)
+        host (str): Hostname of an externally managed service, or a
+            ``host:port`` address naming one; unnamed, the private service this
+            interpreter starts is used
+        port (int, optional): Port of an externally managed service
     
     Returns:
         Connection: Singleton default connection
@@ -99,12 +107,13 @@ def _get_default_connection(host='localhost', port=None):
         ValueError: If host names a port that is unreadable or disagrees with port
     """
     global _default_connection, _default_connection_params
-    host, port = split_target(host, port)
-    params = (host, port)
+    # Keyed by the service named, if any, so the unnamed default is one key
+    # rather than one per spelling of it.
+    params = named_target(host, port)
     
     # Create new connection if params changed or no connection exists
     if _default_connection is None or _default_connection_params != params:
-        # Close old connection to avoid refcount leak
+        # Close old connection to avoid holding a service nothing is using
         if _default_connection is not None:
             _default_connection.close()
         _default_connection = Connection(host, port, auto_start=True)
@@ -163,13 +172,17 @@ def connect(host='localhost', port=None, auto_start=True, version=None,
     Convenience function that creates a new Connection instance.
     
     Args:
-        host (str): Service hostname, or a ``host:port`` address, whose port is
-            used when no separate port is given (default: 'localhost')
-        port (int, optional): Service port (default: 50051)
-        auto_start (bool): If True, automatically start service if not running (default: True)
+        host (str): Hostname of an externally managed service, or a
+            ``host:port`` address naming one. Naming either connects to a
+            service this client does not manage; unnamed, and with
+            $OPENSYSML_SERVICE unset, a private service is used instead
+            (default: 'localhost')
+        port (int, optional): Port of an externally managed service
+        auto_start (bool): If True, start a private service when no address is
+            named. If False, start nothing (default: True)
         version (str, optional): Release tag the service must report, or
             'latest'; defaults to $OPENSYSML_GRPC_VERSION. Checked whether the
-            service is started here or managed by the caller
+            service is private or externally managed
         require_capabilities (iterable, optional): Capability names the service
             must report, checked at connect time
     
@@ -178,8 +191,8 @@ def connect(host='localhost', port=None, auto_start=True, version=None,
 
     Raises:
         ValueError: If host names a port that is unreadable or disagrees with port
-        StaleServiceError: If another release is already listening on the
-            address and this client may not stop it
+        ConnectionError: If a private service cannot be started
+        StaleServiceError: If the service reached is another release
         MissingCapabilityError: If the service lacks a required capability
 
     Example:
@@ -187,7 +200,6 @@ def connect(host='localhost', port=None, auto_start=True, version=None,
         >>> conn.port
         50123
     """
-    host, port = split_target(host, port)
     return Connection(
         host, port, auto_start=auto_start, version=version,
         require_capabilities=require_capabilities,

{opensysml-0.3.0 → opensysml-0.3.2}/opensysml/_version.py

@@ -6,4 +6,4 @@ neither is a second copy that can drift. `scripts/check_version.py` compares
 this value with the release tag before anything is uploaded.
 """
 
-VERSION = "0.3.0"
+VERSION = "0.3.2"

{opensysml-0.3.0 → opensysml-0.3.2}/opensysml/binary.py

@@ -12,6 +12,13 @@ from opensysml.errors import (
     ChecksumMismatchError,
     ConnectionError,
     UnpinnedReleaseError,
+    UnsignedReleaseError,
+)
+from opensysml.signing import (
+    BUNDLE_ASSET,
+    MANIFEST_ASSET,
+    signer_for,
+    verified_manifest_digest,
 )
 
 # Releases publish sysml-grpc-<goos>-<goarch> raw, with a .sha256 sidecar.
@@ -71,6 +78,20 @@ PINNED_SHA256 = {
             'sysml-grpc-linux-arm64': '6f370241e327dd1277e2b8f35bed4388bae1e4172ff4d2a213c24dee2452536d',
             'sysml-grpc-windows-amd64.exe': '1464a3aca63dd2c4d6cb8639f9958b6d887035cb7a7edd197aaa039fb5ab19f2',
         },
+        'v0.2.1': {
+            'sysml-grpc-darwin-amd64': '589c6e248f69bc373c536d05379b9339d0c77443e67682aa06fc045dadc0606a',
+            'sysml-grpc-darwin-arm64': 'f0397b0b1b9219470a1346d4e4a9135a3e2c3e480951e5aa54a55e593adb7214',
+            'sysml-grpc-linux-amd64': 'b1885a0c956a69201f7d00d6d1a4f19f9df12831cedcee8ad4682a9918ffd8a6',
+            'sysml-grpc-linux-arm64': '3451bb569c1c2993a5c648df27cadcec900d46e6e1d957f87aac979c8a16c9e5',
+            'sysml-grpc-windows-amd64.exe': '3a630d38c2691a27c8f6e3b781f48e05b727c559b219b9c2e7bd8651c222628d',
+        },
+        'v0.3.0': {
+            'sysml-grpc-darwin-amd64': '8c034172f604ec78c6c045b8eef0ddb2fdebac4f22852480ad3289a3e940cf14',
+            'sysml-grpc-darwin-arm64': 'c9f8fb0a424277cc83ab3f388e11e54fcc9328b9a2cb86a911e7b96fb6cb316a',
+            'sysml-grpc-linux-amd64': 'b39b720e020c325020af95c33640ad3583c938d74c40d29a0741fab6c03412de',
+            'sysml-grpc-linux-arm64': '2faeacdbc3dcd20053b2dc79b559bbbf2f53b7470d982b9908c7665a53b37462',
+            'sysml-grpc-windows-amd64.exe': 'f50f1b53008154c1a5fb39eb56f09464dedcf081037af765978304b2f33615c6',
+        },
     },
 }
 
@@ -123,35 +144,51 @@ def unpinned_downloads_allowed(github_repo=None):
     return repo in [named.strip() for named in allowed.split(',')]
 
 
-def expected_digest(version, asset, served_digest, github_repo=None):
-    """The digest a download must have, preferring the pin over what was served.
+def expected_digest(version, asset, served_digest, github_repo=None,
+                    verified_digest=None, unverified_reason=None):
+    """The digest a download must have, from the pin or the signed manifest.
+
+    The pin wins wherever there is one, and a verified manifest contradicting it
+    is a failure rather than a reason to prefer either. Where there is no pin, a
+    digest taken from a manifest signed by the release pipeline stands in for
+    one; nothing else does.
 
     Args:
         version (str): Release tag, resolved (never 'latest')
         asset (str): Asset name (e.g. 'sysml-grpc-linux-amd64')
         served_digest (str): Digest from the .sha256 served beside the binary
         github_repo (str, optional): GitHub repository (owner/repo)
+        verified_digest (str, optional): Digest from the release's signed
+            checksum manifest, once its signature verified
+        unverified_reason (str, optional): Why there is no verified digest, said
+            in the refusal when there is no pin either
 
     Returns:
         str: The digest to verify the download against
 
     Raises:
         ChecksumMismatchError: If the served digest contradicts the pinned one,
-            which is a release republished with another binary
-        UnpinnedReleaseError: If nothing is pinned for it and same-origin trust
-            was not allowed explicitly
+            which is a release republished with another binary, or if a verified
+            manifest contradicts the pin
+        UnpinnedReleaseError: If nothing is pinned for it, no signed manifest
+            vouched for it, and same-origin trust was not allowed explicitly
     """
     repo = github_repo or default_github_repo()
     pinned = pinned_digest(version, asset, repo)
     if pinned is None:
+        if verified_digest is not None:
+            # Signed by the pipeline that built the release, so it is not the
+            # origin vouching for itself: as good as a pin.
+            return verified_digest
         if not unpinned_downloads_allowed(repo):
+            unverified = f" and {unverified_reason}" if unverified_reason else ""
             raise UnpinnedReleaseError(
-                f"opensysml pins no SHA-256 digest for {asset} of {version} of {repo}, so "
-                f"the only checksum available is the one served beside the binary, which "
-                f"a compromised release would serve too. Upgrade opensysml to a release "
-                f"that pins {version}, ask for a pinned release with version=, or accept "
-                f"same-origin trust for this repository by setting "
-                f"${ALLOW_UNPINNED_ENV}={repo} (or =1 for any repository)."
+                f"opensysml pins no SHA-256 digest for {asset} of {version} of {repo}"
+                f"{unverified}, so the only checksum available is the one served beside "
+                f"the binary, which a compromised release would serve too. Upgrade "
+                f"opensysml to a release that pins {version}, ask for a pinned release "
+                f"with version=, or accept same-origin trust for this repository by "
+                f"setting ${ALLOW_UNPINNED_ENV}={repo} (or =1 for any repository)."
             )
         warnings.warn(
             f"opensysml pins no digest for {asset} of {version} of {repo}; verifying it "
@@ -161,6 +198,12 @@ def expected_digest(version, asset, served_digest, github_repo=None):
             stacklevel=3,
         )
         return served_digest
+    if verified_digest is not None and verified_digest != pinned:
+        raise ChecksumMismatchError(
+            f"Checksum mismatch for {asset} of {version}: the signed {MANIFEST_ASSET} "
+            f"of {repo} lists {verified_digest}, but opensysml pins {pinned}. The "
+            f"release was rebuilt after this opensysml pinned it; it was not installed."
+        )
     if served_digest != pinned:
         raise ChecksumMismatchError(
             f"Checksum mismatch for {asset} of {version}: {repo} serves {served_digest}, "
@@ -170,6 +213,62 @@ def expected_digest(version, asset, served_digest, github_repo=None):
     return pinned
 
 
+def release_download_url(version, asset, github_repo=None):
+    """URL a release publishes an asset at.
+
+    Args:
+        version (str): Release tag, resolved (never 'latest')
+        asset (str): Asset name (e.g. 'SHA256SUMS.txt')
+        github_repo (str, optional): GitHub repository (owner/repo)
+
+    Returns:
+        str: Download URL
+    """
+    repo = github_repo or default_github_repo()
+    return f'https://github.com/{repo}/releases/download/{version}/{asset}'
+
+
+def signed_manifest_digest(version, asset, github_repo=None):
+    """The digest for an asset from the release's signed checksum manifest.
+
+    Args:
+        version (str): Release tag, resolved (never 'latest')
+        asset (str): Asset name (e.g. 'sysml-grpc-linux-amd64')
+        github_repo (str, optional): GitHub repository (owner/repo)
+
+    Returns:
+        str: SHA-256 hex digest, from a manifest the release pipeline signed
+
+    Raises:
+        UnsignedReleaseError: If the release publishes no signature this client
+            can check, or nothing could be verified
+        ManifestSignatureError: If the signature does not verify
+    """
+    repo = github_repo or default_github_repo()
+    signer = signer_for(repo)
+    if signer is None:
+        raise UnsignedReleaseError(
+            f"opensysml knows no release pipeline identity for {repo}, so a signed "
+            f"{MANIFEST_ASSET} of it would not be verifiable"
+        )
+
+    downloaded = {}
+    for name in (MANIFEST_ASSET, BUNDLE_ASSET):
+        url = release_download_url(version, name, repo)
+        try:
+            with urllib.request.urlopen(url, timeout=NETWORK_TIMEOUT) as response:
+                downloaded[name] = response.read()
+        except (OSError, http.client.HTTPException) as e:
+            raise UnsignedReleaseError(
+                f"{version} of {repo} publishes no readable {name} ({url}: {e}), so "
+                f"its checksums carry no signature to verify"
+            )
+
+    return verified_manifest_digest(
+        downloaded[MANIFEST_ASSET], downloaded[BUNDLE_ASSET], asset, signer
+    )
+
+
 def resolve_latest_version(github_repo=None):
     """Resolve the tag of the repository's latest published release.
 
@@ -380,9 +479,11 @@ def download_binary(version='latest', github_repo=None):
         str: Path to downloaded binary
     
     Raises:
-        ChecksumMismatchError: If the download does not match the digest pinned
-            for it, or the release serves a digest contradicting the pin
-        UnpinnedReleaseError: If nothing is pinned for the release
+        ChecksumMismatchError: If the download does not match the digest expected
+            for it, the release serves a digest contradicting the pin, or the
+            signature on its checksum manifest does not verify
+        UnpinnedReleaseError: If nothing is pinned for the release and its
+            checksum manifest carries no signature that could be verified
         ConnectionError: If the download or its installation fails
     """
     github_repo = github_repo or default_github_repo()
@@ -392,9 +493,10 @@ def download_binary(version='latest', github_repo=None):
     binary_name = release_asset_name()
 
     # Construct URLs
-    base_url = f'https://github.com/{github_repo}/releases/download/{version}'
-    binary_url = f'{base_url}/{binary_name}'
-    checksum_url = f'{base_url}/{binary_name}.sha256'
+    binary_url = release_download_url(version, binary_name, github_repo)
+    checksum_url = release_download_url(
+        version, binary_name + '.sha256', github_repo
+    )
     
     binary_path = get_binary_path()
     os.makedirs(os.path.dirname(binary_path), exist_ok=True)
@@ -406,10 +508,22 @@ def download_binary(version='latest', github_repo=None):
         
         # Parse checksum (format: "hexdigest  filename\n")
         served_checksum = checksum_content.split()[0]
+        # A release nothing is pinned for is vouched for by the signature on its
+        # checksum manifest instead, which the origin cannot forge.
+        verified_checksum = unverified_reason = None
+        if pinned_digest(version, binary_name, github_repo) is None:
+            try:
+                verified_checksum = signed_manifest_digest(
+                    version, binary_name, github_repo
+                )
+            except UnsignedReleaseError as e:
+                unverified_reason = str(e)
         # The pinned digest wins, so a release republished with another binary
         # cannot vouch for itself through the sidecar it serves.
         expected_checksum = expected_digest(
-            version, binary_name, served_checksum, github_repo
+            version, binary_name, served_checksum, github_repo,
+            verified_digest=verified_checksum,
+            unverified_reason=unverified_reason,
         )
         
         # Download binary