hostctl 0.3.1__tar.gz → 0.3.2__tar.gz

{hostctl-0.3.1 → hostctl-0.3.2}/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-09-23
+
+### Fixed
+
+- **`redact_uri` no longer over-redacts a well-formed URI.** The textual
+  fallback -- which reads the last `@` in the whole string as the userinfo
+  delimiter -- ran whenever `urlsplit` reported no password, including for
+  URIs that simply do not have one. `ssh://nas:22/mail/user@example.com`
+  carries no credential at all and came back as `ssh://nas@example.com`: a
+  diagnostic quietly naming a different host. Guessing is now confined to
+  input that does not parse -- when the URI is well formed, `urlsplit`'s
+  authority is the authority, so an `@` in a path is left alone. A password
+  hidden by an unencoded `/`, `?` or `#` is still redacted: that input is
+  malformed (the separator ends the authority, leaving `user:secret` read as
+  host:port), and detecting exactly that is what now gates the fallback.
+
+### Changed
+
+- `ConnectionString` now documents the parsing contract it already enforced:
+  the input must be a valid URI, and reserved characters in a password must
+  be percent-encoded. There is no lenient mode and none is planned -- a
+  password may itself contain `@` and `:`, so nothing can recover where an
+  unescaped one ended, and a guess in the parser would be a guess about what
+  to connect to. Documentation and tests only; behaviour is unchanged.
+
 ## [0.3.1] - 2026-09-22
 
 ### Fixed
@@ -762,7 +787,8 @@ test suite on Python 3.9 through 3.14.
   assigned to it; a config-less host now builds its own family configuration
   instead.
 
-[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/jose-pr/hostctl/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/jose-pr/hostctl/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/jose-pr/hostctl/compare/v0.2.7...v0.3.0
 [0.2.7]: https://github.com/jose-pr/hostctl/compare/v0.2.6...v0.2.7

{hostctl-0.3.1 → hostctl-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hostctl
-Version: 0.3.1
+Version: 0.3.2
 Summary: Run commands and access files on a host, local or remote, protocol-agnostic
 Project-URL: Homepage, https://github.com/jose-pr/hostctl/
 Project-URL: Documentation, https://jose-pr.github.io/hostctl/

{hostctl-0.3.1 → hostctl-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostctl"
-version = "0.3.1"
+version = "0.3.2"
 authors = [{ name = "Jose A." }]
 description = "Run commands and access files on a host, local or remote, protocol-agnostic"
 readme = "README.md"

{hostctl-0.3.1 → hostctl-0.3.2}/src/hostctl/AGENTS.md

@@ -156,7 +156,11 @@ and dispatches it with no args, and that script is shell text, not a program.
   renders. Supplying a password both in the URI and as an argument raises.
   `redact_uri(uri)` STRIPS a password and returns a valid, reusable URI (not a
   masked one, so a rendered form can never round-trip a wrong credential), for
-  logs, reprs, and error messages.
+  logs, reprs, and error messages. A WELL-FORMED URI IS NEVER OVER-REDACTED:
+  when it parses, `urlsplit`'s authority is the authority, so an `@` elsewhere
+  (`ssh://nas:22/mail/user@example.com`) is left alone. Only input that does
+  not parse gets the textual last-`@` guess, which may over-redact -- by then
+  the text has already failed to say where its authority ended.
 - A connection URI may carry a raw tab, CR, or LF in its **userinfo**: those
   are percent-encoded before `urlsplit` sees them, which would otherwise
   delete them silently (`ssh://u:pw<LF>otp:1@host` would authenticate with
@@ -189,9 +193,19 @@ path grammar, so `path()` raises.
 `ConnectionString(value, *, scheme=None, port=None, ...)` is the parsed form
 of a target -- host, scheme, port, user, password -- with `is_local` answered
 by `netimps` rather than guessed. It exists so a caller never reimplements
-connection-string parsing. `uri_hostname(value)` returns the bare hostname of
-a URI authority, unbracketing an IPv6 literal; it is the sibling of
-`uri_host`, `redact_uri` and `parse_credentials`.
+connection-string parsing. A bare host parses (a missing scheme is not an
+error), but otherwise the value MUST be a valid URI: an unclosed IPv6 literal,
+a non-numeric port, or an unescaped `/`, `?` or `#` in a password RAISES.
+**Percent-encode reserved characters in a password** -- there is no lenient
+mode and none will be added, because a password may itself contain `@` and
+`:`, so nothing can recover where an unescaped one ended, and guessing would
+be guessing what to connect to. (`@` and `:` do parse: last `@`, first `:`,
+per the URI grammar.) Use `redact_uri` when the text may not parse at all and
+the job is only keeping a secret out of a log.
+
+`uri_hostname(value)` returns the bare hostname of a URI authority,
+unbracketing an IPv6 literal; it is the sibling of `uri_host`, `redact_uri`
+and `parse_credentials`.
 
 `__version__` is the installed version string.
 

{hostctl-0.3.1 → hostctl-0.3.2}/src/hostctl/host/_common.py

@@ -230,6 +230,12 @@ def redact_uri(uri: str) -> str:
 
     A URI with no password is returned unchanged.
 
+    **A well-formed URI is never over-redacted.** When the URI parses, what
+    `urlsplit` says is the authority *is* the authority, so an `@` anywhere
+    else -- a mailbox in a path, `ssh://nas:22/mail/user@example.com` -- is
+    left alone. Guessing is confined to input that does not parse, where
+    there is nothing better to go on: see below.
+
     This never raises. It is meant for error messages and log records, where
     failing to render a diagnostic would be worse than rendering an odd one.
     Characters `urlsplit` would delete (tab, CR, LF) are percent-encoded first,
@@ -238,31 +244,37 @@ def redact_uri(uri: str) -> str:
     """
     try:
         parsed = _urlsplit(_encode_stripped_characters(uri))
-        password = parsed.password
+        # Not dead code: `.port` is a property that RAISES, and touching it
+        # is what decides "well formed" here. It catches both shapes that
+        # matter in one place -- a non-numeric or out-of-range port, and an
+        # unencoded `/`, `?` or `#` in a password, since the latter ends the
+        # authority and leaves `user:secret` being read as host:port. So the
+        # bad port IS the symptom of the hidden password.
+        parsed.port  # noqa: B018
     except ValueError:
-        # A malformed IPv6 authority. The textual fallback below still strips
-        # the userinfo, which is the whole job.
-        password = None
+        pass  # Malformed. The textual fallback below is all that is left.
     else:
-        if password is not None:
-            try:
-                return _without_password(parsed).geturl()
-            except ValueError:
-                # `_rebuild_authority` reads `parsed.port`, which raises for a
-                # non-numeric or out-of-range one. This function is called
-                # from inside exception handlers to format a diagnostic, so
-                # raising here would replace the real error with this one.
-                pass
-
-    # `urlsplit` finds no password when one contains an unencoded `/`, `?` or
-    # `#`: those end the authority, so the secret lands in the path or query
-    # and the "redacted" form used to be the input in full. Randomly generated
-    # passwords routinely contain `/`.
-    #
-    # Fall back to reading the userinfo textually. The last `@` wins, as it
-    # does in a real authority. This can over-redact a path that contains `@`
-    # -- deliberately: an odd diagnostic beats a password in a log, which is
-    # the trade-off this function already documents.
+        if parsed.password is None:
+            # Well formed and carrying no password: there is nothing to
+            # strip, and the fallback must not run. It reads the LAST `@` in
+            # the whole string as the userinfo delimiter, which would rewrite
+            # `ssh://nas:22/mail/user@example.com` -- a URI with no
+            # credentials at all -- into `ssh://nas@example.com`, naming a
+            # different host.
+            return uri
+        try:
+            return _without_password(parsed).geturl()
+        except ValueError:
+            # Not reachable through `.port`, which is already validated above;
+            # kept because "never raises" is a contract this function is
+            # called from inside exception handlers to honour.
+            pass
+
+    # Only a malformed URI reaches here. Read the userinfo textually: the last
+    # `@` wins, as it does in a real authority. This can over-redact -- but
+    # the text has already failed to say where its authority ended, so there
+    # is no reading of it that is known to be right, and an odd diagnostic
+    # beats a password in a log.
     head, separator, _rest = uri.partition("://")
     start = len(head) + len(separator)
     authority_end = uri.rfind("@")

{hostctl-0.3.1 → hostctl-0.3.2}/src/hostctl/host/_connection.py

@@ -110,6 +110,23 @@ class ConnectionString:
     not an invalid URI -- it is a URI with the scheme left off, which is what
     people type on a command line.
 
+    Beyond that, **the input must be a valid URI, and a malformed one
+    raises** -- an unclosed IPv6 literal, a non-numeric port, or a password
+    written with an unescaped `/`, `?` or `#` (each ends the authority, so
+    what precedes it is read as a port and fails to cast).
+
+    **Reserved characters in a password must be percent-encoded, and one
+    that is not gets no rescue attempt.** There is no rescue to make: a
+    password may itself contain `@` and `:`, so no rule recovers where an
+    unescaped one ended. Those two do parse -- the last `@` and the
+    first `:` win, as in any authority, giving `pa@ss` and `pa:ss` -- but
+    that is the URI grammar being applied, not a guess about the secret.
+    Guessing here would be guessing about what to *connect to*, so a raise is
+    the answer. :func:`redact_uri` is the other job and keeps its own rules:
+    stripping a secret out of text that may not parse at all, for a log line
+    nothing connects to. It does not over-redact a well-formed URI either --
+    it guesses only once the text has failed to parse.
+
     Every field can also be supplied directly, and three layers decide each
     one: **an explicit argument wins, then whatever the string carried, then
     `defaults`.**

{hostctl-0.3.1 → hostctl-0.3.2}/tests/test_connection_string.py

@@ -357,3 +357,39 @@ def test_replace_normalises_what_init_normalises():
 
     assert parsed.replace(scheme="WSS") == parsed
     assert ConnectionString("ssh://nas").replace(port="2222").port == 2222
+
+
+@pytest.mark.parametrize(
+    "target",
+    [
+        "ssh://root:pa/ss@nas",
+        "ssh://root:pa?ss@nas",
+        "ssh://root:pa#ss@nas",
+        "ssh://root:pw@[::1",
+        "ssh://root:pw@nas:notaport",
+    ],
+)
+def test_a_malformed_uri_raises_rather_than_being_guessed_at(target):
+    """The input must be a valid URI, and there is deliberately no lenient
+    mode: what this parses is what gets connected to, so a guess here is a
+    guess about the target. An unescaped `/`, `?` or `#` ends the authority,
+    which is why `root:pa` is then read as a port and fails to cast."""
+    with pytest.raises(ValueError):
+        ConnectionString(target)
+
+
+def test_reserved_characters_in_a_password_must_be_percent_encoded():
+    value = ConnectionString("ssh://root:pa%2Fss@nas")
+
+    assert value.username == "root"
+    assert value.password == "pa/ss"
+
+
+def test_at_and_colon_in_a_password_parse_by_the_uri_grammar():
+    """These two do not raise -- the last `@` and the first `:` delimit, as in
+    any authority. They are also why no textual fallback is possible: a
+    password may contain both, so nothing recovers where an unescaped one
+    ended. `redact_uri` may over-redact, but only once the text has failed
+    to parse at all; this may not guess even then."""
+    assert ConnectionString("ssh://root:pa@ss@nas").password == "pa@ss"
+    assert ConnectionString("ssh://root:pa:ss@nas").password == "pa:ss"

{hostctl-0.3.1 → hostctl-0.3.2}/tests/test_host_api.py

@@ -638,6 +638,32 @@ def test_redact_uri_leaves_a_credential_free_uri_alone():
     assert redact_uri("wss://nas:8443/api?x=1") == "wss://nas:8443/api?x=1"
 
 
+@pytest.mark.parametrize(
+    "uri",
+    (
+        "ssh://nas:22/mail/user@example.com",
+        "ssh://user@nas:22/path/foo@bar",
+        "https://host:443/a@b",
+        "ssh://nas:22/mail/a@b/more@here",
+    ),
+)
+def test_redact_uri_never_over_redacts_a_well_formed_uri(uri):
+    """The textual fallback reads the LAST `@` as the userinfo delimiter, and
+    it used to run whenever `urlsplit` reported no password -- including for
+    URIs that simply do not have one.
+
+    `ssh://nas:22/mail/user@example.com` carries no credential at all and came
+    back as `ssh://nas@example.com`: not merely over-redacted but pointing at
+    a different host. Guessing is now confined to input that does not parse.
+    """
+    assert redact_uri(uri) == uri
+
+
+def test_redact_uri_still_strips_a_password_beside_an_at_sign_in_the_path():
+    """The guard above must not cost the actual redaction."""
+    assert redact_uri("ssh://root:pw@nas:22/mail/a@b") == "ssh://root@nas:22/mail/a@b"
+
+
 def test_an_unsupported_session_raises_not_implemented_not_a_runtime_error():
     """AGENTS.md: unsupported run()/path()/spawn() raise NotImplementedError.