RemoteRF 2.0.15__tar.gz → 2.1.0__tar.gz

{remoterf-2.0.15 → remoterf-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remoterf
-Version: 2.0.15
+Version: 2.1.0
 Summary: A python API to remotely access signal centric hardware. Client-side only! Courtesy of Wireless Lab @ UCLA & Prof. Ian Roberts.
 Author-email: Ethan Ge <ethoGalaxy@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -9,11 +9,18 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: remoterf-federation-core==0.16.0
 Requires-Dist: grpcio<2.0.0,>=1.78.1
 Requires-Dist: protobuf<7.0.0,>=6.31.1
 Requires-Dist: numpy
 Requires-Dist: prompt_toolkit
 Requires-Dist: python-dotenv
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: certifi
+Requires-Dist: pydantic<3.0,>=2.6
+Requires-Dist: keyring<26,>=24
+Requires-Dist: aioice<0.11,>=0.10
+Requires-Dist: aioquic<2.0,>=1.2
 Dynamic: license-file
 
 # Remote RF
@@ -181,6 +188,68 @@ health. Remote firmware flashing is deliberately unsupported.
 
 If `pip install` doesn't work, you can clone the [source](https://github.com/WirelessLabAtUCLA/RemoteRF-Client) directly from github.
 
+## RemoteRF Global v0 / Remote Internet Access
+
+By default, RemoteRF assumes you're on the same network as the RemoteRF
+Server, and you configure the client with that server's address:
+
+```bash
+remoterf --config --addr 192.168.1.20:12321
+```
+
+For deployments exposed through the initial RemoteRF Global gateway, the
+same workflow works with a DNS hostname instead of a LAN IP:
+
+```bash
+remoterf --config --addr ucla.global.remoterf.net:12321
+```
+
+The client does not know or care whether `ucla.global.remoterf.net` is a
+directly reachable RemoteRF Server, a LAN server, or a RemoteRF Global v0
+transparent TCP gateway forwarding to a RemoteRF Server elsewhere. From the
+client's perspective, it's simply a RemoteRF Server endpoint identified by
+`host:port` — an IPv4 address, an IPv6 address (bracketed, e.g.
+`[2001:db8::1]:12321`), or a normal DNS hostname all work the same way.
+Certificate bootstrap (`host:cert_port`) and the gRPC connection
+(`host:port`) are both made against whatever hostname you configure — the
+client stores and uses that hostname as-is and never resolves it to an IP
+before saving your configuration, so DNS/IP changes on the server side don't
+require reconfiguration.
+
+**TLS note:** RemoteRF Global v0 does not weaken certificate verification.
+The RemoteRF Server's certificate must include the hostname you connect
+with (e.g. `ucla.global.remoterf.net`) in its Subject Alternative Name
+(SAN) for standard TLS hostname validation to succeed — this is a
+server-side certificate requirement, not a client setting. If you're
+instead connecting through something like Tailscale, where the address you
+dial differs from the identity in the certificate, use the existing
+`REMOTERF_TLS_SERVER_NAME` override described above; it still requires that
+name to be present in the certificate.
+
+v0 is intentionally minimal — it does **not** include RemoteRF Global
+accounts, deployment discovery/selection, federation, NAT traversal, direct
+P2P, automatic routing, or global resource IDs. Those are future versions.
+The client-side software behaves identically whether you point it at a LAN
+server or at a RemoteRF Global v0 endpoint.
+
+### RemoteRF Global v2 Phase-1 development boundary
+
+The disposable Global v1 account-selection and deployment-session client was
+removed at Gate C. The normal CLI supports direct/native gRPC accounts and
+clean HTTPS deployment-home accounts; neither path treats a broker identity,
+username, email, or home token as destination credentials.
+
+Gate G adds permission visibility to the ordinary `perms` command. It renders
+HOME-local groups plus current destination-signed federated groups with their
+contract/version/state and retrieval time. An unreachable destination is
+explicitly labeled as unsigned transport status, never as an authoritative
+empty group result. This works when the HOME has zero devices.
+
+Phase 1 still grants no federated device discovery, reservation, lease,
+session, streaming, RX, TX, or radio access. Production remains unchanged.
+See [deployment accounts](docs/deployment-accounts-v2.md) and
+[identity boundary](docs/gate-c-identity-boundary.md).
+
 <!-- 1. **Clone the repository:**
 ```bash
 git clone https://github.com/WirelessLabAtUCLA/RemoteRF-Client

remoterf-2.0.15/src/remoterf.egg-info/PKG-INFO → remoterf-2.1.0/README.md

@@ -1,21 +1,3 @@
-Metadata-Version: 2.4
-Name: remoterf
-Version: 2.0.15
-Summary: A python API to remotely access signal centric hardware. Client-side only! Courtesy of Wireless Lab @ UCLA & Prof. Ian Roberts.
-Author-email: Ethan Ge <ethoGalaxy@gmail.com>
-License-Expression: GPL-3.0-or-later
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: grpcio<2.0.0,>=1.78.1
-Requires-Dist: protobuf<7.0.0,>=6.31.1
-Requires-Dist: numpy
-Requires-Dist: prompt_toolkit
-Requires-Dist: python-dotenv
-Dynamic: license-file
-
 # Remote RF
 
 A python API to remotely access signal centric hardware. 
@@ -181,6 +163,68 @@ health. Remote firmware flashing is deliberately unsupported.
 
 If `pip install` doesn't work, you can clone the [source](https://github.com/WirelessLabAtUCLA/RemoteRF-Client) directly from github.
 
+## RemoteRF Global v0 / Remote Internet Access
+
+By default, RemoteRF assumes you're on the same network as the RemoteRF
+Server, and you configure the client with that server's address:
+
+```bash
+remoterf --config --addr 192.168.1.20:12321
+```
+
+For deployments exposed through the initial RemoteRF Global gateway, the
+same workflow works with a DNS hostname instead of a LAN IP:
+
+```bash
+remoterf --config --addr ucla.global.remoterf.net:12321
+```
+
+The client does not know or care whether `ucla.global.remoterf.net` is a
+directly reachable RemoteRF Server, a LAN server, or a RemoteRF Global v0
+transparent TCP gateway forwarding to a RemoteRF Server elsewhere. From the
+client's perspective, it's simply a RemoteRF Server endpoint identified by
+`host:port` — an IPv4 address, an IPv6 address (bracketed, e.g.
+`[2001:db8::1]:12321`), or a normal DNS hostname all work the same way.
+Certificate bootstrap (`host:cert_port`) and the gRPC connection
+(`host:port`) are both made against whatever hostname you configure — the
+client stores and uses that hostname as-is and never resolves it to an IP
+before saving your configuration, so DNS/IP changes on the server side don't
+require reconfiguration.
+
+**TLS note:** RemoteRF Global v0 does not weaken certificate verification.
+The RemoteRF Server's certificate must include the hostname you connect
+with (e.g. `ucla.global.remoterf.net`) in its Subject Alternative Name
+(SAN) for standard TLS hostname validation to succeed — this is a
+server-side certificate requirement, not a client setting. If you're
+instead connecting through something like Tailscale, where the address you
+dial differs from the identity in the certificate, use the existing
+`REMOTERF_TLS_SERVER_NAME` override described above; it still requires that
+name to be present in the certificate.
+
+v0 is intentionally minimal — it does **not** include RemoteRF Global
+accounts, deployment discovery/selection, federation, NAT traversal, direct
+P2P, automatic routing, or global resource IDs. Those are future versions.
+The client-side software behaves identically whether you point it at a LAN
+server or at a RemoteRF Global v0 endpoint.
+
+### RemoteRF Global v2 Phase-1 development boundary
+
+The disposable Global v1 account-selection and deployment-session client was
+removed at Gate C. The normal CLI supports direct/native gRPC accounts and
+clean HTTPS deployment-home accounts; neither path treats a broker identity,
+username, email, or home token as destination credentials.
+
+Gate G adds permission visibility to the ordinary `perms` command. It renders
+HOME-local groups plus current destination-signed federated groups with their
+contract/version/state and retrieval time. An unreachable destination is
+explicitly labeled as unsigned transport status, never as an authoritative
+empty group result. This works when the HOME has zero devices.
+
+Phase 1 still grants no federated device discovery, reservation, lease,
+session, streaming, RX, TX, or radio access. Production remains unchanged.
+See [deployment accounts](docs/deployment-accounts-v2.md) and
+[identity boundary](docs/gate-c-identity-boundary.md).
+
 <!-- 1. **Clone the repository:**
 ```bash
 git clone https://github.com/WirelessLabAtUCLA/RemoteRF-Client

{remoterf-2.0.15 → remoterf-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "remoterf"
-version = "2.0.15"
+version = "2.1.0"
 description = "A python API to remotely access signal centric hardware. Client-side only! Courtesy of Wireless Lab @ UCLA & Prof. Ian Roberts."
 readme = "README.md"
 license = "GPL-3.0-or-later"
@@ -12,11 +12,18 @@ license-files = ["LICENSE"]
 authors = [{ name = "Ethan Ge", email = "ethoGalaxy@gmail.com" }]
 requires-python = ">=3.10"
 dependencies = [
+  "remoterf-federation-core==0.16.0",
   "grpcio>=1.78.1,<2.0.0",
   "protobuf>=6.31.1,<7.0.0",
   "numpy",
   "prompt_toolkit",
   "python-dotenv",
+  "httpx>=0.27,<1.0",
+  "certifi",
+  "pydantic>=2.6,<3.0",
+  "keyring>=24,<26",
+  "aioice>=0.10,<0.11",
+  "aioquic>=1.2,<2.0",
 ]
 classifiers = [
   "Programming Language :: Python :: 3",
@@ -28,6 +35,8 @@ remoterf = "remoteRF.remoterf_cli:main"
 
 [tool.setuptools]
 package-dir = { "" = "src" }
+# src/remoteRF.py: see its docstring (upgrades from 2.0.7-2.0.13).
+py-modules = ["remoteRF"]
 
 [tool.setuptools.packages.find]
 where = ["src"]

{remoterf-2.0.15/src/remoteRF/drivers/adalm_pluto → remoterf-2.1.0/src/remoteRF/common/grpc}/__init__.py

@@ -13,4 +13,4 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-from . import pluto_remote as adi
+from . import grpc_pb2, grpc_pb2_grpc

remoterf-2.1.0/src/remoteRF/common/grpc/deployment_capabilities.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+package remote_rf;
+import "grpc.proto";
+
+// Optional discovery. Existing GenericRPC/IDL/device protocols are unchanged.
+service DeploymentCapabilitiesV1 {
+  rpc GetCapabilities (DeploymentCapabilitiesRequest) returns (DeploymentCapabilitiesResponse);
+}
+message DeploymentCapabilitiesRequest {
+  string protocol_version = 1;
+}
+message DeploymentCapabilitiesResponse {
+  string capabilities_json = 1;
+  ErrorEnvelope error = 2;
+}

remoterf-2.1.0/src/remoteRF/common/grpc/deployment_capabilities_pb2.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: deployment_capabilities.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'deployment_capabilities.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from . import grpc_pb2 as grpc__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1d\x64\x65ployment_capabilities.proto\x12\tremote_rf\x1a\ngrpc.proto\"9\n\x1d\x44\x65ploymentCapabilitiesRequest\x12\x18\n\x10protocol_version\x18\x01 \x01(\t\"d\n\x1e\x44\x65ploymentCapabilitiesResponse\x12\x19\n\x11\x63\x61pabilities_json\x18\x01 \x01(\t\x12\'\n\x05\x65rror\x18\x02 \x01(\x0b\x32\x18.remote_rf.ErrorEnvelope2\x82\x01\n\x18\x44\x65ploymentCapabilitiesV1\x12\x66\n\x0fGetCapabilities\x12(.remote_rf.DeploymentCapabilitiesRequest\x1a).remote_rf.DeploymentCapabilitiesResponseb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'deployment_capabilities_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_DEPLOYMENTCAPABILITIESREQUEST']._serialized_start=56
+  _globals['_DEPLOYMENTCAPABILITIESREQUEST']._serialized_end=113
+  _globals['_DEPLOYMENTCAPABILITIESRESPONSE']._serialized_start=115
+  _globals['_DEPLOYMENTCAPABILITIESRESPONSE']._serialized_end=215
+  _globals['_DEPLOYMENTCAPABILITIESV1']._serialized_start=218
+  _globals['_DEPLOYMENTCAPABILITIESV1']._serialized_end=348
+# @@protoc_insertion_point(module_scope)

remoterf-2.1.0/src/remoteRF/common/grpc/deployment_capabilities_pb2_grpc.py

@@ -0,0 +1,100 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+from . import deployment_capabilities_pb2 as deployment__capabilities__pb2
+
+GRPC_GENERATED_VERSION = '1.74.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + f' but the generated code in deployment_capabilities_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class DeploymentCapabilitiesV1Stub(object):
+    """Optional discovery. Existing GenericRPC/IDL/device protocols are unchanged.
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.GetCapabilities = channel.unary_unary(
+                '/remote_rf.DeploymentCapabilitiesV1/GetCapabilities',
+                request_serializer=deployment__capabilities__pb2.DeploymentCapabilitiesRequest.SerializeToString,
+                response_deserializer=deployment__capabilities__pb2.DeploymentCapabilitiesResponse.FromString,
+                _registered_method=True)
+
+
+class DeploymentCapabilitiesV1Servicer(object):
+    """Optional discovery. Existing GenericRPC/IDL/device protocols are unchanged.
+    """
+
+    def GetCapabilities(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_DeploymentCapabilitiesV1Servicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'GetCapabilities': grpc.unary_unary_rpc_method_handler(
+                    servicer.GetCapabilities,
+                    request_deserializer=deployment__capabilities__pb2.DeploymentCapabilitiesRequest.FromString,
+                    response_serializer=deployment__capabilities__pb2.DeploymentCapabilitiesResponse.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'remote_rf.DeploymentCapabilitiesV1', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('remote_rf.DeploymentCapabilitiesV1', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class DeploymentCapabilitiesV1(object):
+    """Optional discovery. Existing GenericRPC/IDL/device protocols are unchanged.
+    """
+
+    @staticmethod
+    def GetCapabilities(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/remote_rf.DeploymentCapabilitiesV1/GetCapabilities',
+            deployment__capabilities__pb2.DeploymentCapabilitiesRequest.SerializeToString,
+            deployment__capabilities__pb2.DeploymentCapabilitiesResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

{remoterf-2.0.15 → remoterf-2.1.0}/src/remoteRF/common/utils/banner.py

@@ -47,7 +47,7 @@ COMPACT_BANNER = "RemoteRF"
 ASCII_WORDMARK_WIDTH = max(len(line) for line in ASCII_BANNER.splitlines())
 ASCII_BANNER_WIDTH = max(len(line) for line in BRANDED_ASCII_BANNER.splitlines())
 ASCII_BANNER_MIN_COLUMNS = ASCII_BANNER_WIDTH + 1
-PANEL_CONTENT_WIDTH = 35
+PANEL_CONTENT_WIDTH = 39
 PANEL_INNER_WIDTH = PANEL_CONTENT_WIDTH + 2
 PANEL_WIDTH = PANEL_INNER_WIDTH + 2
 PANEL_GAP = 1
@@ -111,12 +111,15 @@ def _panel_lines(
     marker = "◆" if unicode_supported else "*"
     label = f"{horizontal} REMOTERF CLIENT "
     top = f"{top_left}{label}{horizontal * (PANEL_INNER_WIDTH - len(label))}{top_right}"
-    content = (
+    content = [
         f"{marker} www.remoterf.net",
-        "Created by the Wireless Lab at UCLA",
+        "Created by https://wireless.ee.ucla.edu",
         f"VERSION  {version}",
-        f"SERVER   {server or 'NA'}",
-    )
+    ]
+    # Before a target is chosen there is no server to name; an "NA" row would
+    # only say so twice.
+    if server:
+        content.append(f"SERVER   {server}")
     body = [
         f"{vertical} {_fit_panel_text(line):<{PANEL_CONTENT_WIDTH}} {vertical}"
         for line in content
@@ -169,12 +172,12 @@ def _compact_lines(
         heading = COMPACT_BANNER[:width]
 
     short_version = str(version).split(maxsplit=1)[0]
-    server = str(server or "NA")
+    server = str(server or "")
     detail_options = (
-        f"v{version} {separator} {server}",
-        f"v{short_version} {separator} {server}",
-        f"v{short_version}",
-    )
+        (f"v{version} {separator} {server}", f"v{short_version} {separator} {server}")
+        if server
+        else (f"v{version}",)
+    ) + (f"v{short_version}",)
     details = next((line for line in detail_options if len(line) <= width), "")
     if not details:
         details = detail_options[-1][:width]

{remoterf-2.0.15 → remoterf-2.1.0}/src/remoteRF/common/utils/process_arg.py

@@ -30,6 +30,31 @@ _MAX_NDARRAY_DIMENSIONS = 8
 _SUPPORTED_NDARRAY_KINDS = {"b", "i", "u", "f", "c"}
 
 
+# Gate I slice 3: complex samples as interleaved int16 IQ, a quarter of the
+# complex128 bytes, decoded to complex64. Only exact for integer-valued data
+# within int16 range (a 12-bit ADC's, say); map_iq16 refuses anything else.
+IQ16 = "ci16"
+
+
+def fits_iq16(array: np.ndarray) -> bool:
+    if not (isinstance(array, np.ndarray) and np.iscomplexobj(array)):
+        return False
+    parts = np.stack((array.real, array.imag))
+    return bool(np.all(np.abs(parts) <= 32767) and np.array_equal(parts, np.round(parts)))
+
+
+def map_iq16(array: np.ndarray) -> grpc_pb2.Argument:
+    if not fits_iq16(array):
+        raise ValueError("samples are not integer-valued int16 IQ")
+    iq = np.empty(array.shape + (2,), dtype=np.int16)
+    iq[..., 0], iq[..., 1] = array.real, array.imag
+    arg = grpc_pb2.Argument()
+    arg.ndarray_value.dtype = IQ16
+    arg.ndarray_value.shape.extend(array.shape)
+    arg.ndarray_value.data = np.ascontiguousarray(iq).tobytes(order="C")
+    return arg
+
+
 def _validate_ndarray(dtype: np.dtype, shape) -> int:
     """Return the expected payload length for a safe numeric ndarray."""
     if dtype.hasobject or dtype.kind not in _SUPPORTED_NDARRAY_KINDS:
@@ -49,18 +74,22 @@ def _validate_ndarray(dtype: np.dtype, shape) -> int:
 
 
 def _decode_ndarray(descriptor: grpc_pb2.NDArrayValue) -> np.ndarray:
+    iq16 = descriptor.dtype == IQ16
     try:
-        dtype = np.dtype(descriptor.dtype)
+        dtype = np.dtype(np.int16) if iq16 else np.dtype(descriptor.dtype)
     except (TypeError, ValueError) as exc:
         raise ValueError(f"invalid ndarray dtype: {descriptor.dtype!r}") from exc
 
     shape = tuple(int(item) for item in descriptor.shape)
-    expected = _validate_ndarray(dtype, shape)
+    expected = _validate_ndarray(dtype, shape + (2,) if iq16 else shape)
     actual = len(descriptor.data)
     if actual != expected:
         raise ValueError(
             f"ndarray byte length mismatch: expected {expected}, got {actual}"
         )
+    if iq16:
+        iq = np.frombuffer(descriptor.data, dtype=dtype).reshape(shape + (2,))
+        return (iq[..., 0].astype(np.float32) + 1j * iq[..., 1].astype(np.float32)).astype(np.complex64)
     return np.frombuffer(descriptor.data, dtype=dtype).reshape(shape).copy()
 
 

{remoterf-2.0.15 → remoterf-2.1.0}/src/remoteRF/config/cert_fetcher.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 import hashlib
 import os
 import socket
+import urllib.error
 import urllib.request
 from pathlib import Path
 from typing import Optional
@@ -38,6 +39,26 @@ def _ensure_parent_dir(p: Path) -> None:
 def _looks_like_pem_cert(data: bytes) -> bool:
     return b"BEGIN CERTIFICATE" in data and b"END CERTIFICATE" in data
 
+
+def looks_like_pem_cert(data: bytes) -> bool:
+    """Public alias of `_looks_like_pem_cert` for generic callers."""
+    return _looks_like_pem_cert(data)
+
+
+def fetch_ca_bytes(host: str, port: int, *, timeout_sec: float = 3.0) -> bytes:
+    """Fetch raw CA certificate bytes (HTTP first, then raw-TCP fallback),
+    without writing anything to disk. Shared by direct-mode's
+    `fetch_and_save_ca_cert` below.
+    """
+    try:
+        return _fetch_http(host, port, timeout_sec)
+    except urllib.error.URLError as exc:
+        if isinstance(exc.reason, (OSError, socket.timeout)):
+            raise  # nothing answered: a raw retry would only wait the timeout again
+        return _fetch_raw_tcp(host, port, timeout_sec)
+    except Exception:
+        return _fetch_raw_tcp(host, port, timeout_sec)
+
 def sha256_fingerprint_pem(pem_bytes: bytes) -> str:
     h = hashlib.sha256(pem_bytes).hexdigest()
     return ":".join(h[i:i+2] for i in range(0, len(h), 2))
@@ -48,9 +69,16 @@ def _fetch_http(host: str, port: int, timeout_sec: float) -> bytes:
     with urllib.request.urlopen(req, timeout=timeout_sec) as resp:
         return resp.read()
 
+def _bare_host(host: str) -> str:
+    """Strip IPv6 literal brackets (e.g. '[::1]' -> '::1') for raw-socket use."""
+    host = host.strip()
+    if host.startswith("[") and host.endswith("]"):
+        return host[1:-1]
+    return host
+
 def _fetch_raw_tcp(host: str, port: int, timeout_sec: float) -> bytes:
     chunks: list[bytes] = []
-    with socket.create_connection((host, port), timeout=timeout_sec) as s:
+    with socket.create_connection((_bare_host(host), port), timeout=timeout_sec) as s:
         s.settimeout(timeout_sec)
         while True:
             try:
@@ -164,10 +192,7 @@ def fetch_and_save_ca_cert(
             return True
 
         # Fetch (HTTP first, then raw TCP fallback)
-        try:
-            data = _fetch_http(host, port, timeout_sec)
-        except Exception:
-            data = _fetch_raw_tcp(host, port, timeout_sec)
+        data = fetch_ca_bytes(host, port, timeout_sec=timeout_sec)
 
         if not data or not _looks_like_pem_cert(data):
             return False