atbash-hermes-plugin 0.4.5.dev0__tar.gz → 0.4.5.dev2__tar.gz

atbash_hermes_plugin-0.4.5.dev2/MANIFEST.in

@@ -0,0 +1 @@
+include plugin.yaml

{atbash_hermes_plugin-0.4.5.dev0 → atbash_hermes_plugin-0.4.5.dev2}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: atbash-hermes-plugin
-Version: 0.4.5.dev0
+Version: 0.4.5.dev2
 Summary: Atbash safety plugin for Hermes Agent
 Author: atbash
 License-Expression: LicenseRef-Atbash-Proprietary
 Project-URL: Homepage, https://github.com/Atbash-Ai/atbash-hermes-plugin
 Project-URL: Repository, https://github.com/Atbash-Ai/atbash-hermes-plugin
 Keywords: atbash,hermes,hermes-agent,agent-safety,ai-safety,tool-guard,judge,policy
-Requires-Python: <3.13,>=3.10
+Requires-Python: <3.13,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: atbash-sdk==0.4.5.dev0
+Requires-Dist: atbash-sdk==0.5.1.dev0
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.29
 Requires-Dist: opentelemetry-sdk<2,>=1.29
@@ -48,6 +48,9 @@ If Hermes is installed in a virtual environment, use that environment's Python:
 /path/to/hermes/venv/bin/python -m pip install --pre atbash-hermes-plugin==0.4.3.dev0
 ```
 
+Maintainers: releases use clean staged source, live PyPI monotonic checks, and
+Trusted Publishing. See [the release process](docs/release.md).
+
 ## Configure Atbash
 
 The plugin needs an Atbash agent key. Configure either `ATBASH_KEY_PATH` or
@@ -233,13 +236,21 @@ Hermes sessions.
 
 ## Verdict Behavior
 
-- `ALLOW`: the tool proceeds.
+- `ALLOW` with `allow is True`: the tool proceeds. A missing `allow` flag is denied.
 - `HOLD`: the tool is blocked with a review message.
 - `BLOCK`, `DENY`, `REJECT`, `DISALLOW`: the tool is blocked.
 - Atbash API error:
   - `ATBASH_ENFORCE_DECISION=true`: fail closed and block.
   - `ATBASH_ENFORCE_DECISION=false`: fail open and allow.
 
+Atbash ships fail-closed on every tier. Setting `ATBASH_ENFORCE_DECISION=false`
+inverts that for this agent: a judge outage becomes a silent allow, and the
+governance layer stops governing for as long as it lasts. That is supported, but
+record a written risk acceptance in the deployment's security summary before
+turning it off, so the trade-off is auditable after an incident rather than
+discovered during one. See decision 0003 (fail-closed default) in the dashboard
+repo.
+
 For `HOLD`, the user-facing block message is:
 
 ```text

{atbash_hermes_plugin-0.4.5.dev0 → atbash_hermes_plugin-0.4.5.dev2}/README.md

@@ -30,6 +30,9 @@ If Hermes is installed in a virtual environment, use that environment's Python:
 /path/to/hermes/venv/bin/python -m pip install --pre atbash-hermes-plugin==0.4.3.dev0
 ```
 
+Maintainers: releases use clean staged source, live PyPI monotonic checks, and
+Trusted Publishing. See [the release process](docs/release.md).
+
 ## Configure Atbash
 
 The plugin needs an Atbash agent key. Configure either `ATBASH_KEY_PATH` or
@@ -215,13 +218,21 @@ Hermes sessions.
 
 ## Verdict Behavior
 
-- `ALLOW`: the tool proceeds.
+- `ALLOW` with `allow is True`: the tool proceeds. A missing `allow` flag is denied.
 - `HOLD`: the tool is blocked with a review message.
 - `BLOCK`, `DENY`, `REJECT`, `DISALLOW`: the tool is blocked.
 - Atbash API error:
   - `ATBASH_ENFORCE_DECISION=true`: fail closed and block.
   - `ATBASH_ENFORCE_DECISION=false`: fail open and allow.
 
+Atbash ships fail-closed on every tier. Setting `ATBASH_ENFORCE_DECISION=false`
+inverts that for this agent: a judge outage becomes a silent allow, and the
+governance layer stops governing for as long as it lasts. That is supported, but
+record a written risk acceptance in the deployment's security summary before
+turning it off, so the trade-off is auditable after an incident rather than
+discovered during one. See decision 0003 (fail-closed default) in the dashboard
+repo.
+
 For `HOLD`, the user-facing block message is:
 
 ```text

{atbash_hermes_plugin-0.4.5.dev0 → atbash_hermes_plugin-0.4.5.dev2}/atbash_hermes_plugin/__init__.py

@@ -4,6 +4,7 @@ import atexit
 import hashlib
 import json
 import logging
+import inspect
 import os
 import re
 import time
@@ -336,6 +337,134 @@ def _resolve_asset(token: str) -> str:
     return "other"
 
 
+_STATEMENT_SEP_RE = re.compile(r"[;&|<>$`\r\n]")
+
+def _flag_values(command: str, name: str) -> list:
+    return [
+        value.strip("'\"")
+        for value in re.findall(rf"--{re.escape(name)}[= ]+(\S+)", command)
+    ]
+
+def _numeric_amount(value: Optional[str]) -> Optional[str]:
+    """Return ``value`` only if it is a plain ASCII decimal, else ``None``.
+
+    ``[0-9]`` rather than ``\\d``: in Python ``\\d`` matches every Unicode
+    decimal digit, so ``--amount ١٢٣`` passed the check and was forwarded
+    verbatim into the un-redacted ``resolved`` block. Callers must treat a
+    ``None`` here as "unparsable", not as "no amount given" — see
+    ``_canonicalize_financial``.
+    """
+    if value is None or len(value) > 64:
+        return None
+    return value if re.fullmatch(r"(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)", value) else None
+
+
+_TRUE_VALUES = {"1", "true", "yes", "on"}
+
+_FALSE_VALUES = {"0", "false", "no", "off"}
+
+def _enforcement_enabled(value: Optional[str]) -> bool:
+    """Parse ATBASH_ENFORCE_DECISION as opt-OUT, not opt-in.
+
+    This flag guards every fail-open branch in the guard, so it must take an
+    explicit, recognised falsey value to switch off. Read with the truthy
+    matching used for the other flags, an empty string — which is what
+    docker-compose passes for `ATBASH_ENFORCE_DECISION=${VAR}` when the host
+    variable is unset — or a typo like "y" or "strict" silently put the guard
+    in fail-open mode with nothing in the log to show for it.
+    """
+    if value is None:
+        return True
+    normalized = value.strip().lower()
+    if normalized in _FALSE_VALUES:
+        return False
+    if normalized and normalized not in _TRUE_VALUES:
+        logger.error(
+            "ATBASH_ENFORCE_DECISION=%r is not a recognized value; "
+            "keeping enforcement on (fail-closed)",
+            value,
+        )
+    return True
+
+
+def _strict_reading(
+    command: str,
+    recipient_allowlist: set,
+    may_hide_other_actions: bool,
+) -> Dict[str, Any]:
+    """The most conservative concrete facts that survive an ambiguous command.
+
+    Replacing every fact with "ambiguous" makes asset-specific policy ("never
+    lifts ETH or ATBASH rules") unreachable for any command carrying a
+    separator. So report every asset named, the largest amount named (or
+    "unparsable"), and whether *every* recipient named is allowlisted.
+
+    Every field describes only the text that was parsed. When the command can
+    expand or chain into statements this never saw, `may_hide_other_actions` is
+    True and none of these facts bound what actually runs — which is why they
+    are named "…_named" and why nothing here may be read as permission.
+    """
+    recipients = _flag_values(command, "to") + _flag_values(command, "recipient")
+    lowered_recipients = {r.lower() for r in recipients}
+    tokens = _flag_values(command, "token")
+    addresses = [
+        address
+        for address in _ERC20_RE.findall(command)
+        if address.lower() not in lowered_recipients
+    ]
+    assets = sorted({_resolve_asset(t) for t in tokens + addresses}) or ["ETH"]
+
+    raw_amounts = _flag_values(command, "amount") + _flag_values(command, "max-usd")
+    parsed = [_numeric_amount(v) for v in raw_amounts]
+    if any(p is None for p in parsed):
+        max_amount: Optional[str] = "unparsable"
+    elif parsed:
+        max_amount = max(parsed, key=lambda v: float(v))
+    else:
+        max_amount = None
+
+    return {
+        "assets_named": assets,
+        "max_amount_named": max_amount,
+        "recipients_named": len(recipients),
+        "all_named_recipients_allowlisted": bool(recipients)
+        and all(r.lower() in recipient_allowlist for r in recipients),
+        "may_hide_other_actions": may_hide_other_actions,
+    }
+
+
+def _assert_sdk_capabilities(
+    sdk: Any,
+    atbash_class: Any,
+    tool_call_input_class: Any,
+) -> None:
+    guard_api_version = getattr(sdk, "GUARD_API_VERSION", 0)
+    if not isinstance(guard_api_version, int) or guard_api_version < 1:
+        raise RuntimeError(
+            "atbash-sdk does not expose hardened guard API version 1; "
+            "install atbash-sdk==0.2.0"
+        )
+    if not callable(getattr(atbash_class, "from_config", None)):
+        raise RuntimeError("atbash-sdk is missing Atbash.from_config")
+    if not callable(getattr(atbash_class, "audit_tool_call", None)):
+        raise RuntimeError("atbash-sdk is missing Atbash.audit_tool_call")
+    try:
+        from_config_parameters = inspect.signature(
+            atbash_class.from_config
+        ).parameters
+        parameters = inspect.signature(tool_call_input_class).parameters
+    except (TypeError, ValueError) as error:
+        raise RuntimeError("cannot inspect atbash-sdk guard APIs") from error
+    for required_parameter in ("judge", "org_name", "fail_closed"):
+        if required_parameter not in from_config_parameters:
+            raise RuntimeError(
+                "atbash-sdk Atbash.from_config is missing "
+                f"{required_parameter} support"
+            )
+    if "resolved" not in parameters:
+        raise RuntimeError("atbash-sdk ToolCallInput is missing resolved support")
+
+
 def _canonicalize_financial(command: str, recipient_allowlist: set) -> Optional[Dict[str, Any]]:
     if not command:
         return None
@@ -345,18 +474,90 @@ def _canonicalize_financial(command: str, recipient_allowlist: set) -> Optional[
         return None
 
     def _flag(name: str) -> Optional[str]:
-        m = re.search(rf"--{name}[= ]+(\S+)", command)
-        return m.group(1).strip("'\"") if m else None
+        values = _flag_values(command, name)
+        return values[0] if values else None
+
+    op = (
+        "swap" if re.search(r"\bswap\b", command, re.IGNORECASE)
+        else "approve" if re.search(r"\b(approve|erc20)\b", command, re.IGNORECASE)
+        else "transfer"
+    )
+
+    # The judge rules on this block rather than on the raw command — the SDK
+    # redacts every 0x address out of args before it is sent — so reading only
+    # the first occurrence of a flag lets a prompt-injected command assert an
+    # allowlisted 1-unit transfer while what actually executes is a second one.
+    # CLI parsers are last-flag-wins and a shell runs every `;`-separated
+    # statement. When the text can mean more than one thing, say so instead of
+    # picking a reading and asserting it.
+    repeated_recipient = len(_flag_values(command, "to")) + len(
+        _flag_values(command, "recipient")
+    ) > 1
+    repeated_flag = any(
+        len(_flag_values(command, name)) > 1
+        for name in ("token", "amount", "max-usd")
+    )
+    multi_statement = bool(_STATEMENT_SEP_RE.search(command))
+
+    # "absent" and "present but unparsable" must not collapse to the same
+    # signal. `--amount 1e9` parses as no plain decimal, and reporting it as
+    # amount=None next to recipient_status="allowlisted" hands the judge
+    # "allowlisted recipient, no amount stated" for a command that names a very
+    # large one — which is exactly what an "allow allowlisted USDT under N"
+    # policy would let through.
+    raw_amount = _flag("amount")
+    raw_max_usd = _flag("max-usd")
+    amount = _numeric_amount(raw_amount)
+    max_usd = _numeric_amount(raw_max_usd)
+    amount_unparsed = (raw_amount is not None and amount is None) or (
+        raw_max_usd is not None and max_usd is None
+    )
+
+    if repeated_recipient or repeated_flag or multi_statement or amount_unparsed:
+        return {
+            "operation": op,
+            "asset": "ambiguous",
+            "amount": None,
+            "max_usd": None,
+            "recipient_status": "ambiguous",
+            "ambiguous": True,
+            "amount_unparsed": amount_unparsed,
+            "ambiguous_reason": (
+                "multiple statements, redirection or substitution"
+                if multi_statement
+                else "repeated flag"
+                if (repeated_recipient or repeated_flag)
+                else "amount is not a plain decimal number"
+            ),
+            # Conservative facts, so an asset-specific rule is still reachable.
+            # Never grant on these: recipient_status above stays "ambiguous".
+            "strict_reading": _strict_reading(
+                command, recipient_allowlist, multi_statement
+            ),
+            "allowlist_scope": "USDT transfers/approvals only; never lifts ETH or ATBASH rules",
+            "note": (
+                "canonicalization withheld: the command carries more than one "
+                "transfer or flag value, an unreadable amount, or text that a "
+                "shell would expand, so no asset/amount/recipient claim here "
+                "can be trusted"
+            ),
+        }
 
+    to = _flag("to") or _flag("recipient")
     token = _flag("token")
     if not token:
-        m = _ERC20_RE.search(command)
-        if m:
-            token = m.group(1)
+        # Only an address that is not the recipient can be the token contract.
+        # Taking the first 0x in the command picked up the RECIPIENT of a
+        # native send, resolved it to "other", and made the stricter ETH rule
+        # unreachable for every command that names an address.
+        candidates = [
+            address
+            for address in _ERC20_RE.findall(command)
+            if not to or address.lower() != to.lower()
+        ]
+        if candidates:
+            token = candidates[0]
 
-    to = _flag("to") or _flag("recipient")
-    amount = _flag("amount")
-    max_usd = _flag("max-usd")
     asset = _resolve_asset(token or "")
 
     on_allow = bool(to) and to.lower() in recipient_allowlist
@@ -365,18 +566,16 @@ def _canonicalize_financial(command: str, recipient_allowlist: set) -> Optional[
     else:
         recipient_status = "external" if to else "unspecified"
 
-    op = (
-        "swap" if re.search(r"\bswap\b", command, re.IGNORECASE)
-        else "approve" if re.search(r"\b(approve|erc20)\b", command, re.IGNORECASE)
-        else "transfer"
-    )
-
     return {
         "operation": op,
         "asset": asset,
         "amount": amount,
         "max_usd": max_usd,
         "recipient_status": recipient_status,
+        "ambiguous": False,
+        # Always present so that its absence is never the thing that has to be
+        # noticed: here it is False, so amount=None really does mean "not given".
+        "amount_unparsed": False,
         "allowlist_scope": "USDT transfers/approvals only; never lifts ETH or ATBASH rules",
         "note": "canonicalized pre-judge; raw 0x addresses omitted (redacted upstream)",
     }
@@ -416,9 +615,29 @@ def _infer_action_class(tool_name: str) -> str:
 
 
 def _as_bool(value: Optional[str], default: bool) -> bool:
+    """Parse a boolean env var, refusing to guess.
+
+    This used to be ``value.strip().lower() in {"1","true","yes","on"}``, so
+    every value outside that set read as False. ``ATBASH_ENFORCE_DECISION=``
+    (empty, the normal shape when a .env entry is left blank) or a typo like
+    ``enabled`` therefore turned enforcement OFF silently, on the one setting
+    that decides whether this plugin blocks anything at all. An unrecognised
+    value now keeps the default and says so.
+    """
     if value is None:
         return default
-    return value.strip().lower() in {"1", "true", "yes", "on"}
+    v = value.strip().lower()
+    if v in {"1", "true", "yes", "on"}:
+        return True
+    if v in {"0", "false", "no", "off"}:
+        return False
+    logger.warning(
+        "Atbash: unrecognized boolean value %r; keeping the default (%s). "
+        "Use one of 1/true/yes/on or 0/false/no/off.",
+        value,
+        default,
+    )
+    return default
 
 
 def _normalize_verdict(raw: Any) -> str:
@@ -550,7 +769,7 @@ def _setup_telemetry() -> None:
 class AtbashHermesGuard:
     def __init__(self) -> None:
         self.debug = _as_bool(os.getenv("ATBASH_DEBUG"), False)
-        self.fail_closed = _as_bool(os.getenv("ATBASH_ENFORCE_DECISION"), True)
+        self.fail_closed = _enforcement_enabled(os.getenv("ATBASH_ENFORCE_DECISION"))
         self.endpoint = os.getenv("ATBASH_ENDPOINT")
         self.judge_endpoint_policy = os.getenv("ATBASH_JUDGE_ENDPOINT_POLICY")
         self.judge_verify_pubkey = os.getenv("ATBASH_JUDGE_VERIFY_PUBKEY")
@@ -1033,6 +1252,31 @@ class AtbashHermesGuard:
                     }
                 return None
 
+            # Strict allowlist. _normalize_verdict passes any unrecognised
+            # string straight through (it only maps None to ERROR), and this
+            # used to end in a bare `return None`, i.e. run the tool. So a
+            # renamed verdict, a typo, an SDK newer than this plugin, or a
+            # response the SDK itself marked allow=False all executed the
+            # call. Only an exact ALLOW that the SDK also vouches for runs;
+            # a missing allow flag is not permission.
+            allow_flag = _extract_allow(verdict_raw)
+            if verdict == "ALLOW" and allow_flag is True:
+                return None
+
+            logger.warning(
+                "Atbash unusable verdict tool=%s verdict=%s allow=%s reason=%s",
+                tool_name,
+                verdict,
+                allow_flag,
+                reason,
+            )
+            if self.fail_closed:
+                return {
+                    "action": "block",
+                    "message": (
+                        f"Blocked (unusable Atbash verdict {verdict!r}): {reason}"
+                    ),
+                }
             return None
         except Exception as e:
             logger.warning("Atbash guard error tool=%s err=%s", tool_name, e)
@@ -1046,7 +1290,34 @@ class AtbashHermesGuard:
 
 def register(ctx):
     _setup_telemetry()
-    guard = AtbashHermesGuard()
-    guard._run_boot_probe()
-    ctx.register_hook("pre_tool_call", guard.pre_tool_call)
-    logger.info("[atbash-hermes-plugin] registered pre_tool_call hook")
+    state: Dict[str, Any] = {"guard": None, "error": "guard initialization incomplete"}
+
+    def fail_closed_pre_tool_call(**kwargs: Any):
+        guard = state["guard"]
+        if guard is None:
+            return {
+                "action": "block",
+                "message": f"Blocked (Atbash guard unavailable): {state['error']}",
+            }
+        return guard.pre_tool_call(**kwargs)
+
+    # Hermes isolates plugin-load exceptions and continues startup, so install
+    # the blocking hook before any SDK/config initialization can fail.
+    ctx.register_hook("pre_tool_call", fail_closed_pre_tool_call)
+    try:
+        state["guard"] = AtbashHermesGuard()
+    except Exception as error:
+        state["error"] = str(error)
+        logger.error(
+            "[atbash-hermes-plugin] guard initialization failed; "
+            "pre_tool_call remains fail-closed err=%s",
+            error,
+        )
+        return
+    # Say which mode actually registered — operators read this line as
+    # confirmation that enforcement is on, so it must not claim fail-closed
+    # when ATBASH_ENFORCE_DECISION turned enforcement off.
+    logger.info(
+        "[atbash-hermes-plugin] registered pre_tool_call hook mode=%s",
+        "fail-closed" if state["guard"].fail_closed else "fail-open",
+    )

{atbash_hermes_plugin-0.4.5.dev0 → atbash_hermes_plugin-0.4.5.dev2}/atbash_hermes_plugin.egg-info/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: atbash-hermes-plugin
-Version: 0.4.5.dev0
+Version: 0.4.5.dev2
 Summary: Atbash safety plugin for Hermes Agent
 Author: atbash
 License-Expression: LicenseRef-Atbash-Proprietary
 Project-URL: Homepage, https://github.com/Atbash-Ai/atbash-hermes-plugin
 Project-URL: Repository, https://github.com/Atbash-Ai/atbash-hermes-plugin
 Keywords: atbash,hermes,hermes-agent,agent-safety,ai-safety,tool-guard,judge,policy
-Requires-Python: <3.13,>=3.10
+Requires-Python: <3.13,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: atbash-sdk==0.4.5.dev0
+Requires-Dist: atbash-sdk==0.5.1.dev0
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.29
 Requires-Dist: opentelemetry-sdk<2,>=1.29
@@ -48,6 +48,9 @@ If Hermes is installed in a virtual environment, use that environment's Python:
 /path/to/hermes/venv/bin/python -m pip install --pre atbash-hermes-plugin==0.4.3.dev0
 ```
 
+Maintainers: releases use clean staged source, live PyPI monotonic checks, and
+Trusted Publishing. See [the release process](docs/release.md).
+
 ## Configure Atbash
 
 The plugin needs an Atbash agent key. Configure either `ATBASH_KEY_PATH` or
@@ -233,13 +236,21 @@ Hermes sessions.
 
 ## Verdict Behavior
 
-- `ALLOW`: the tool proceeds.
+- `ALLOW` with `allow is True`: the tool proceeds. A missing `allow` flag is denied.
 - `HOLD`: the tool is blocked with a review message.
 - `BLOCK`, `DENY`, `REJECT`, `DISALLOW`: the tool is blocked.
 - Atbash API error:
   - `ATBASH_ENFORCE_DECISION=true`: fail closed and block.
   - `ATBASH_ENFORCE_DECISION=false`: fail open and allow.
 
+Atbash ships fail-closed on every tier. Setting `ATBASH_ENFORCE_DECISION=false`
+inverts that for this agent: a judge outage becomes a silent allow, and the
+governance layer stops governing for as long as it lasts. That is supported, but
+record a written risk acceptance in the deployment's security summary before
+turning it off, so the trade-off is auditable after an incident rather than
+discovered during one. See decision 0003 (fail-closed default) in the dashboard
+repo.
+
 For `HOLD`, the user-facing block message is:
 
 ```text

{atbash_hermes_plugin-0.4.5.dev0 → atbash_hermes_plugin-0.4.5.dev2}/atbash_hermes_plugin.egg-info/SOURCES.txt

@@ -1,5 +1,7 @@
 LICENSE
+MANIFEST.in
 README.md
+plugin.yaml
 pyproject.toml
 atbash_hermes_plugin/__init__.py
 atbash_hermes_plugin.egg-info/PKG-INFO
@@ -8,4 +10,6 @@ atbash_hermes_plugin.egg-info/dependency_links.txt
 atbash_hermes_plugin.egg-info/entry_points.txt
 atbash_hermes_plugin.egg-info/requires.txt
 atbash_hermes_plugin.egg-info/top_level.txt
-tests/test_memory_poisoning.py
+tests/test_memory_poisoning.py
+tests/test_pre_tool_call_verdicts.py
+tests/test_release_contract.py

{atbash_hermes_plugin-0.4.5.dev0 → atbash_hermes_plugin-0.4.5.dev2}/atbash_hermes_plugin.egg-info/requires.txt

@@ -1,4 +1,4 @@
-atbash-sdk==0.4.5.dev0
+atbash-sdk==0.5.1.dev0
 httpx<1,>=0.27
 opentelemetry-exporter-otlp-proto-http<2,>=1.29
 opentelemetry-sdk<2,>=1.29

atbash_hermes_plugin-0.4.5.dev2/plugin.yaml

@@ -0,0 +1,9 @@
+name: atbash-hermes-plugin
+version: 0.4.5.dev2
+description: Atbash guardrail plugin for Hermes Agent (pre-tool-call policy enforcement)
+author: Chromia
+entry: atbash_hermes_plugin
+tags: ["security", "guardrails", "atbash", "policy"]
+
+hooks:
+  pre_tool_call: true

{atbash_hermes_plugin-0.4.5.dev0 → atbash_hermes_plugin-0.4.5.dev2}/pyproject.toml

@@ -1,13 +1,13 @@
 [build-system]
-requires = ["setuptools>=69", "wheel"]
+requires = ["setuptools==84.0.0", "wheel==0.48.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "atbash-hermes-plugin"
-version = "0.4.5.dev0"
+version = "0.4.5.dev2"
 description = "Atbash safety plugin for Hermes Agent"
 readme = "README.md"
-requires-python = ">=3.10,<3.13"
+requires-python = ">=3.9,<3.13"
 authors = [
   { name = "atbash" }
 ]
@@ -24,7 +24,7 @@ keywords = [
   "policy"
 ]
 dependencies = [
-  "atbash-sdk==0.4.5.dev0",
+  "atbash-sdk==0.5.1.dev0",
   "httpx>=0.27,<1",
   "opentelemetry-exporter-otlp-proto-http>=1.29,<2",
   "opentelemetry-sdk>=1.29,<2",

atbash_hermes_plugin-0.4.5.dev2/tests/test_pre_tool_call_verdicts.py

@@ -0,0 +1,474 @@
+"""Regression tests for verdict handling in ``AtbashHermesGuard.pre_tool_call``.
+
+The guard used to be a denylist: it blocked HOLD, a fixed set of block words,
+and ERROR, then fell through to ``return None`` — which runs the tool. Any
+verdict outside that list (a typo, a renamed verdict, a judge returning
+something unexpected, a response the SDK marked ``allow=False``) silently
+permitted the action.
+
+These drive the real ``pre_tool_call`` with ``_judge`` replaced by a stub
+returning a given judge response, so the logic under test is the real one. The
+guard is built without ``__init__`` so no agent key, network, or atbash-sdk
+install is required.
+
+Uses unittest rather than pytest: the repo root carries an ``__init__.py`` (so
+Hermes can load the plugin as a package), which pytest collects as a package
+and fails to import on its own.
+
+Run:  python -m unittest discover -s tests -v
+  or: python tests/test_pre_tool_call_verdicts.py
+"""
+from __future__ import annotations
+
+import types
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+# Execute the plugin module into a private namespace. Loading it by path avoids
+# the ambiguity between the repo-root __init__.py and the package of the same
+# name underneath it.
+_MODULE_PATH = Path(__file__).resolve().parents[1] / "atbash_hermes_plugin" / "__init__.py"
+_plugin = types.ModuleType("atbash_hermes_plugin_under_test")
+_plugin.__file__ = str(_MODULE_PATH)
+exec(  # noqa: S102 — loading the module under test, by design
+    compile(_MODULE_PATH.read_text(encoding="utf-8"), str(_MODULE_PATH), "exec"),
+    _plugin.__dict__,
+)
+
+AtbashHermesGuard = _plugin.AtbashHermesGuard
+
+
+class FakeDecision:
+    """Mirrors the atbash-sdk Decision shape (verdict + allow + reason)."""
+
+    def __init__(self, verdict, allow=None, reason="because"):
+        self.verdict = verdict
+        self.reason = reason
+        if allow is not None:
+            self.allow = allow
+
+
+def make_guard(*, fail_closed=True, decision=None):
+    guard = AtbashHermesGuard.__new__(AtbashHermesGuard)
+    guard.debug = False
+    guard.fail_closed = fail_closed
+    guard._judge = lambda **kwargs: decision
+    return guard
+
+
+def call(guard):
+    return guard.pre_tool_call(tool_name="send_email", args={"to": "a@b.c"})
+
+
+def is_blocked(result):
+    return isinstance(result, dict) and result.get("action") == "block"
+
+
+class FakeContext:
+    def __init__(self):
+        self.hooks = []
+
+    def register_hook(self, name, callback):
+        self.hooks.append((name, callback))
+
+
+class SdkCapabilityChecks(unittest.TestCase):
+    def test_missing_guard_api_version_is_rejected(self):
+        sdk = types.SimpleNamespace()
+
+        with self.assertRaisesRegex(RuntimeError, "guard API"):
+            _plugin._assert_sdk_capabilities(sdk, object, object)
+
+    def test_tool_input_without_resolved_is_rejected(self):
+        class Atbash:
+            @classmethod
+            def from_config(
+                cls,
+                *,
+                judge=None,
+                org_name=None,
+                fail_closed=True,
+            ):
+                return cls()
+
+            def audit_tool_call(self):
+                return None
+
+        class ToolCallInput:
+            def __init__(self, *, tool_name, args=None, context=None):
+                pass
+
+        sdk = types.SimpleNamespace(GUARD_API_VERSION=1)
+
+        with self.assertRaisesRegex(RuntimeError, "resolved"):
+            _plugin._assert_sdk_capabilities(sdk, Atbash, ToolCallInput)
+
+    def test_from_config_without_fail_closed_is_rejected(self):
+        class Atbash:
+            @classmethod
+            def from_config(cls, *, judge=None, org_name=None):
+                return cls()
+
+            def audit_tool_call(self):
+                return None
+
+        class ToolCallInput:
+            def __init__(self, *, tool_name, resolved=None):
+                pass
+
+        sdk = types.SimpleNamespace(GUARD_API_VERSION=1)
+
+        with self.assertRaisesRegex(RuntimeError, "fail_closed"):
+            _plugin._assert_sdk_capabilities(sdk, Atbash, ToolCallInput)
+
+
+class RegistrationMustFailClosed(unittest.TestCase):
+    def test_guard_initialization_failure_leaves_blocking_hook_installed(self):
+        ctx = FakeContext()
+
+        with patch.object(
+            _plugin.AtbashHermesGuard,
+            "__init__",
+            side_effect=RuntimeError("incompatible sdk"),
+        ):
+            _plugin.register(ctx)
+
+        self.assertEqual(len(ctx.hooks), 1)
+        name, callback = ctx.hooks[0]
+        self.assertEqual(name, "pre_tool_call")
+        result = callback(tool_name="terminal", args={"command": "whoami"})
+        self.assertTrue(is_blocked(result))
+        self.assertIn("guard unavailable", result["message"].lower())
+
+
+class ResolvedFinancialDataMustStayBounded(unittest.TestCase):
+    def test_non_numeric_amount_flags_are_not_forwarded_as_resolved_data(self):
+        resolved = _plugin._canonicalize_financial(
+            "transfer --token USDT "
+            "--amount ghp_abcdefghijklmnopqrstuvwxyzABCDEFGH "
+            "--max-usd=Authorization:Bearer-secret",
+            set(),
+        )
+
+        self.assertIsNotNone(resolved)
+        self.assertIsNone(resolved["amount"])
+        self.assertIsNone(resolved["max_usd"])
+
+
+ALLOWLISTED = "0xa1ce00000000000000000000000000000000beef"
+ATTACKER = "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
+USDT_CONTRACT = "0xdac17f958d2ee523a2206206994597c13d831ec7"
+
+
+class ResolvedFinancialMustNotOverstateWhatItKnows(unittest.TestCase):
+    """`resolved` is the pre-digested block the judge rules on, and raw 0x
+    addresses are redacted out of args before the judge sees them — so a
+    canonicalization that reads only the FIRST occurrence of a flag lets a
+    prompt-injected command assert an allowlisted 1-unit transfer while the
+    command that actually runs moves everything to an attacker address."""
+
+    def test_duplicated_recipient_flag_is_not_asserted_as_allowlisted(self):
+        resolved = _plugin._canonicalize_financial(
+            f"transfer --token USDT --to {ALLOWLISTED} --amount 1 "
+            f"--to {ATTACKER} --amount 999999",
+            {ALLOWLISTED},
+        )
+
+        self.assertIsNotNone(resolved)
+        self.assertNotEqual(resolved["recipient_status"], "allowlisted")
+        self.assertIsNone(resolved["amount"])
+
+    def test_chained_statements_are_not_asserted_as_allowlisted(self):
+        for separator in [";", "&&", "||", "|", "\n"]:
+            with self.subTest(separator=separator):
+                resolved = _plugin._canonicalize_financial(
+                    f"transfer --token USDT --to {ALLOWLISTED} --amount 1 "
+                    f"{separator} transfer --token USDT --to {ATTACKER} "
+                    "--amount 999999",
+                    {ALLOWLISTED},
+                )
+
+                self.assertIsNotNone(resolved)
+                self.assertNotEqual(resolved["recipient_status"], "allowlisted")
+                self.assertIsNone(resolved["amount"])
+
+    def test_command_substitution_is_not_asserted_as_allowlisted(self):
+        resolved = _plugin._canonicalize_financial(
+            f"transfer --token USDT --to {ALLOWLISTED} --amount $(cat /tmp/amt)",
+            {ALLOWLISTED},
+        )
+
+        self.assertIsNotNone(resolved)
+        self.assertNotEqual(resolved["recipient_status"], "allowlisted")
+
+    def test_one_character_separators_are_not_asserted_as_allowlisted(self):
+        """`&&` was caught but a bare `&` was not, `$(` was but `${` was not,
+        and no redirection operator was. `cmd1 & cmd2` backgrounds the first and
+        runs the second exactly like `;`; `${VAR}` and `$VAR` expand to text the
+        canonicalizer never sees, and CLI parsers are last-flag-wins."""
+        for tail in [
+            "& drain.sh",
+            "> /etc/cron.d/atbash",
+            ">> /root/.bashrc",
+            "< /tmp/payload",
+            "${EXTRA}",
+            "$EXTRA",
+        ]:
+            with self.subTest(tail=tail):
+                resolved = _plugin._canonicalize_financial(
+                    f"transfer --token USDT --to {ALLOWLISTED} --amount 1 {tail}",
+                    {ALLOWLISTED},
+                )
+
+                self.assertIsNotNone(resolved)
+                self.assertNotEqual(resolved["recipient_status"], "allowlisted")
+                self.assertIsNone(resolved["amount"])
+                self.assertTrue(resolved["ambiguous"])
+
+    def test_ambiguous_block_keeps_the_strict_concrete_reading(self):
+        """Replacing every fact with "ambiguous" makes an asset-specific rule
+        ("never lifts ETH or ATBASH rules") unreachable for any command that
+        carries a separator. The conservative reading has to survive."""
+        resolved = _plugin._canonicalize_financial(
+            f"transfer --token ETH --to {ATTACKER} --amount 999 ; echo hi",
+            {ALLOWLISTED},
+        )
+
+        self.assertEqual(resolved["asset"], "ambiguous")
+        strict = resolved["strict_reading"]
+        self.assertEqual(strict["assets_named"], ["ETH"])
+        self.assertEqual(strict["max_amount_named"], "999")
+        self.assertEqual(strict["recipients_named"], 1)
+        self.assertFalse(strict["all_named_recipients_allowlisted"])
+        self.assertTrue(strict["may_hide_other_actions"])
+
+    def test_strict_reading_never_reads_as_a_clean_bill_of_health(self):
+        """A chained command whose *named* parts are all benign must still say
+        that a statement it never parsed can run."""
+        resolved = _plugin._canonicalize_financial(
+            f"transfer --token USDT --to {ALLOWLISTED} --amount 1 & drain.sh",
+            {ALLOWLISTED},
+        )
+        strict = resolved["strict_reading"]
+
+        self.assertTrue(strict["all_named_recipients_allowlisted"])
+        self.assertTrue(strict["may_hide_other_actions"])
+        self.assertNotEqual(resolved["recipient_status"], "allowlisted")
+
+    def test_single_unambiguous_transfer_still_resolves_normally(self):
+        resolved = _plugin._canonicalize_financial(
+            f"transfer --token USDT --to {ALLOWLISTED} --amount 1",
+            {ALLOWLISTED},
+        )
+
+        self.assertEqual(resolved["asset"], "USDT")
+        self.assertEqual(resolved["amount"], "1")
+        self.assertEqual(resolved["recipient_status"], "allowlisted")
+
+    def test_native_send_resolves_as_eth_not_other(self):
+        """No --token means a native ETH transfer. Inferring the token from the
+        first 0x in the command picks up the RECIPIENT, so the stricter ETH
+        rule could never fire for any command carrying an address."""
+        resolved = _plugin._canonicalize_financial(
+            f"send --to {ATTACKER} --amount 50",
+            set(),
+        )
+
+        self.assertEqual(resolved["asset"], "ETH")
+
+    def test_positional_contract_address_still_names_the_asset(self):
+        resolved = _plugin._canonicalize_financial(
+            f"erc20 approve {USDT_CONTRACT} --amount 100",
+            set(),
+        )
+
+        self.assertEqual(resolved["asset"], "USDT")
+
+
+class UnparsableAmountsMustNotReadAsNoAmount(unittest.TestCase):
+    """Dropping an unreadable amount to None is right — secret-shaped values
+    must never reach the un-redacted `resolved` block — but "absent" and
+    "present and unreadable" must not be the same signal. `--amount 1e9` next to
+    recipient_status="allowlisted" tells an "allow allowlisted USDT under N"
+    policy that no amount was named at all."""
+
+    def test_non_decimal_amount_is_not_a_clean_allowlisted_no_amount_block(self):
+        for value in ["1e9", "1_000", "1,000", "0x1e", "all", "9" * 65]:
+            with self.subTest(amount=value):
+                resolved = _plugin._canonicalize_financial(
+                    f"transfer --token USDT --to {ALLOWLISTED} --amount {value}",
+                    {ALLOWLISTED},
+                )
+
+                self.assertNotEqual(resolved["recipient_status"], "allowlisted")
+                self.assertIsNone(resolved["amount"])
+                self.assertTrue(resolved["amount_unparsed"])
+                self.assertTrue(resolved["ambiguous"])
+
+    def test_unreadable_max_usd_is_flagged_too(self):
+        resolved = _plugin._canonicalize_financial(
+            f"transfer --token USDT --to {ALLOWLISTED} --amount 1 --max-usd 1e9",
+            {ALLOWLISTED},
+        )
+
+        self.assertNotEqual(resolved["recipient_status"], "allowlisted")
+        self.assertTrue(resolved["amount_unparsed"])
+
+    def test_absent_amount_is_reported_as_absent_not_unparsable(self):
+        resolved = _plugin._canonicalize_financial(
+            f"transfer --token USDT --to {ALLOWLISTED}",
+            {ALLOWLISTED},
+        )
+
+        self.assertIsNone(resolved["amount"])
+        self.assertFalse(resolved["amount_unparsed"])
+        self.assertFalse(resolved["ambiguous"])
+
+    def test_unicode_digits_are_not_a_numeric_amount(self):
+        """In Python `\\d` matches every Unicode decimal digit, so Arabic-Indic
+        digits passed the numeric check and were forwarded verbatim."""
+        arabic_digits = "١٢٣"
+        self.assertIsNone(_plugin._numeric_amount(arabic_digits))
+
+        resolved = _plugin._canonicalize_financial(
+            f"transfer --token USDT --to {ALLOWLISTED} --amount {arabic_digits}",
+            {ALLOWLISTED},
+        )
+
+        self.assertIsNone(resolved["amount"])
+        self.assertTrue(resolved["amount_unparsed"])
+        self.assertNotIn(arabic_digits, str(resolved))
+
+    def test_plain_decimals_still_parse(self):
+        for value in ["1", "0", "12.5", ".5", "1000"]:
+            with self.subTest(amount=value):
+                self.assertEqual(_plugin._numeric_amount(value), value)
+
+
+class EnforcementMustBeOptOutNotOptIn(unittest.TestCase):
+    """ATBASH_ENFORCE_DECISION guards every fail-open branch. An empty value —
+    what docker-compose passes for an unset host variable — or a typo used to
+    read as false and silently disabled enforcement."""
+
+    def test_unrecognized_values_keep_enforcement_on(self):
+        for value in [None, "", "   ", "y", "t", "enabled", "strict", "TRUE", "on"]:
+            with self.subTest(value=value):
+                self.assertTrue(_plugin._enforcement_enabled(value))
+
+    def test_explicit_falsey_values_disable_enforcement(self):
+        for value in ["0", "false", "FALSE", "no", "off", " off "]:
+            with self.subTest(value=value):
+                self.assertFalse(_plugin._enforcement_enabled(value))
+
+    def test_debug_flag_stays_opt_in(self):
+        """Only enforcement inverts; a verbose-logging toggle must not turn
+        itself on because someone wrote ATBASH_DEBUG=maybe."""
+        self.assertFalse(_plugin._as_bool("maybe", False))
+        self.assertTrue(_plugin._as_bool("true", False))
+
+
+class RegistrationLogMustStateTheRealMode(unittest.TestCase):
+    """An operator tailing the log per the README treats the registration line
+    as confirmation that enforcement is on; it must not say fail-closed when
+    the guard is running fail-open."""
+
+    def _register_with_mode(self, fail_closed):
+        ctx = FakeContext()
+
+        def fake_init(guard_self):
+            guard_self.fail_closed = fail_closed
+
+        with patch.object(_plugin.AtbashHermesGuard, "__init__", fake_init):
+            with self.assertLogs(_plugin.logger, level="INFO") as captured:
+                _plugin.register(ctx)
+        return "\n".join(captured.output).lower()
+
+    def test_fail_open_registration_is_announced_as_fail_open(self):
+        output = self._register_with_mode(False)
+        self.assertIn("fail-open", output)
+
+    def test_fail_closed_registration_still_says_fail_closed(self):
+        output = self._register_with_mode(True)
+        self.assertIn("fail-closed", output)
+        self.assertNotIn("fail-open", output)
+
+
+
+class UnrecognizedVerdictsMustNotRun(unittest.TestCase):
+    def test_unrecognized_verdict_blocks_when_fail_closed(self):
+        for verdict in [
+            "MAYBE",
+            "",
+            "UNKNOWN",
+            "PENDING",
+            "NO VERDICT",
+            "GREEN",
+            "OK",
+            "PASS",
+            "ALLOWED",
+        ]:
+            with self.subTest(verdict=verdict):
+                result = call(make_guard(decision=FakeDecision(verdict)))
+                self.assertTrue(
+                    is_blocked(result),
+                    f"verdict {verdict!r} must not be allowed through, got {result!r}",
+                )
+
+    def test_allow_contradicted_by_allow_false_blocks(self):
+        """ALLOW while the SDK says allow=False is incoherent — must not run."""
+        result = call(make_guard(decision=FakeDecision("ALLOW", allow=False)))
+        self.assertTrue(is_blocked(result))
+
+    def test_none_response_blocks(self):
+        """_normalize_verdict maps None to ERROR; fail_closed must block it."""
+        self.assertTrue(is_blocked(call(make_guard(decision=None))))
+
+    def test_unrecognized_verdict_respects_fail_open_opt_out(self):
+        """The fix tightens the default; it does not override a deliberate
+        ATBASH_ENFORCE_DECISION=false."""
+        result = call(make_guard(fail_closed=False, decision=FakeDecision("MAYBE")))
+        self.assertIsNone(result)
+
+
+class LegitimateOutcomesUnchanged(unittest.TestCase):
+    def test_allow_runs_the_tool(self):
+        self.assertIsNone(call(make_guard(decision=FakeDecision("ALLOW", allow=True))))
+
+    def test_allow_without_an_allow_field_blocks(self):
+        """Missing allow is not permission. Only allow is True may run."""
+        result = call(make_guard(decision=FakeDecision("ALLOW")))
+        self.assertTrue(is_blocked(result))
+
+    def test_hold_blocks_with_review_message(self):
+        result = call(make_guard(decision=FakeDecision("HOLD")))
+        self.assertTrue(is_blocked(result))
+        self.assertIn("held for operator review", result["message"].lower())
+
+    def test_block_words_block(self):
+        for verdict in ["BLOCK", "DENY", "REJECT", "DISALLOW"]:
+            with self.subTest(verdict=verdict):
+                result = call(make_guard(decision=FakeDecision(verdict)))
+                self.assertTrue(is_blocked(result))
+                self.assertIn("Blocked by Atbash policy", result["message"])
+
+    def test_error_blocks_only_when_fail_closed(self):
+        self.assertTrue(is_blocked(call(make_guard(decision=FakeDecision("ERROR")))))
+        self.assertIsNone(
+            call(make_guard(fail_closed=False, decision=FakeDecision("ERROR")))
+        )
+
+    def test_judge_exception_still_blocks_when_fail_closed(self):
+        guard = make_guard()
+
+        def boom(**kwargs):
+            raise RuntimeError("judge unreachable")
+
+        guard._judge = boom
+        result = call(guard)
+        self.assertTrue(is_blocked(result))
+        self.assertIn("Atbash unavailable", result["message"])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

atbash_hermes_plugin-0.4.5.dev2/tests/test_release_contract.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import io
+import json
+import tarfile
+import zipfile
+from pathlib import Path
+
+import pytest
+from packaging.version import Version
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SPEC = importlib.util.spec_from_file_location("release", ROOT / "scripts/release.py")
+assert SPEC and SPEC.loader
+release = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(release)
+
+
+def _source_files(root: Path, version: str = "0.4.5") -> None:
+    (root / "pyproject.toml").write_text(
+        f'[project]\nname = "atbash-hermes-plugin"\nversion = "{version}"\n',
+        encoding="utf-8",
+    )
+    (root / "plugin.yaml").write_text(
+        f"name: atbash-hermes-plugin\nversion: {version}\n",
+        encoding="utf-8",
+    )
+
+
+def test_candidate_versions_use_full_history_and_never_reuse_a_gap() -> None:
+    releases = [Version("0.4.5"), Version("0.4.6.dev0"), Version("0.4.6.dev2")]
+    assert release.next_version("dev", Version("0.4.5"), releases) == Version("0.4.6.dev3")
+    assert release.next_version("latest", Version("0.4.5"), releases) == Version("0.4.6")
+
+    prereleases = [Version("0.4.5"), Version("0.4.6rc1")]
+    assert release.next_version("latest", Version("0.4.5"), prereleases) == Version("0.4.6")
+    assert release.next_version("dev", Version("0.4.5"), prereleases) == Version("0.4.7.dev0")
+
+    untagged_dev = [Version("0.4.5"), Version("0.4.8.dev4")]
+    assert release.next_version("dev", Version("0.4.5"), untagged_dev) == Version("0.4.8.dev5")
+
+
+def test_source_version_is_exact_and_atomic(tmp_path: Path) -> None:
+    _source_files(tmp_path)
+    assert release.read_source_version(tmp_path) == Version("0.4.5")
+    (tmp_path / "plugin.yaml").write_text(
+        "name: atbash-hermes-plugin\nversion: 0.4.4\n",
+        encoding="utf-8",
+    )
+    with pytest.raises(release.ReleaseError, match="versions disagree"):
+        release.read_source_version(tmp_path)
+    _source_files(tmp_path, "0.4.6rc1")
+    with pytest.raises(release.ReleaseError, match="exact X.Y.Z"):
+        release.read_source_version(tmp_path)
+
+
+def test_registry_failure_and_unsupported_history_fail_closed(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def fail(*_args: object, **_kwargs: object) -> None:
+        raise OSError("offline")
+
+    monkeypatch.setattr(release.urllib.request, "urlopen", fail)
+    with pytest.raises(release.ReleaseError, match="could not verify"):
+        release.load_releases()
+    with pytest.raises(release.ReleaseError, match="unsupported release base"):
+        release.next_version("dev", Version("0.4"), [Version("0.4.5")])
+    with pytest.raises(release.ReleaseError, match="unsupported release base"):
+        release.next_version("latest", Version("0.4.5"), [Version("1!0.4.5")])
+
+    monkeypatch.setattr(
+        release.urllib.request,
+        "urlopen",
+        lambda *_args, **_kwargs: _Response(
+            json.dumps({"releases": {"0.4.5": [], "1!0.4.5": []}}).encode()
+        ),
+    )
+    with pytest.raises(release.ReleaseError, match="unsupported version"):
+        release.load_releases()
+
+
+def test_staging_changes_both_manifests_only_in_the_copy(tmp_path: Path) -> None:
+    source = tmp_path / "source"
+    staged = tmp_path / "staged"
+    source.mkdir()
+    staged.mkdir()
+    _source_files(source)
+    _source_files(staged)
+    release.set_staged_version(staged, Version("0.4.6.dev0"))
+    assert release.read_source_version(source) == Version("0.4.5")
+    assert release.read_source_version(staged) == Version("0.4.6.dev0")
+
+
+def test_publish_workflow_fails_closed_outside_main() -> None:
+    workflow = (ROOT / ".github/workflows/publish.yml").read_text(encoding="utf-8")
+    guard = 'run: test "$GITHUB_REF" = refs/heads/main'
+    assert guard in workflow
+    assert workflow.index(guard) < workflow.index("actions/checkout@")
+
+
+def _metadata(name: str, version: str) -> bytes:
+    return f"Metadata-Version: 2.4\nName: {name}\nVersion: {version}\n".encode()
+
+
+def _valid_dist(root: Path, version: str = "0.4.6") -> None:
+    wheel = root / f"atbash_hermes_plugin-{version}-py3-none-any.whl"
+    dist_info = f"atbash_hermes_plugin-{version}.dist-info"
+    with zipfile.ZipFile(wheel, "w") as archive:
+        archive.writestr(f"{dist_info}/METADATA", _metadata(release.PROJECT, version))
+        archive.writestr(
+            f"{dist_info}/entry_points.txt",
+            "[hermes_agent.plugins]\natbash-hermes-plugin = atbash_hermes_plugin\n",
+        )
+        archive.writestr("atbash_hermes_plugin/__init__.py", "PLUGIN = True\n")
+
+    sdist = root / f"atbash_hermes_plugin-{version}.tar.gz"
+    prefix = f"atbash_hermes_plugin-{version}"
+    files = {
+        "PKG-INFO": _metadata(release.PROJECT, version),
+        "MANIFEST.in": b"include plugin.yaml\n",
+        "pyproject.toml": b"[project]\n",
+        "plugin.yaml": f"version: {version}\n".encode(),
+        "atbash_hermes_plugin/__init__.py": b"PLUGIN = True\n",
+    }
+    with tarfile.open(sdist, "w:gz") as archive:
+        for name, payload in files.items():
+            info = tarfile.TarInfo(f"{prefix}/{name}")
+            info.size = len(payload)
+            archive.addfile(info, io.BytesIO(payload))
+
+
+def test_distribution_verifier_requires_exact_names_module_and_entry_point(
+    tmp_path: Path,
+) -> None:
+    _valid_dist(tmp_path)
+    release.verify_dist(tmp_path, Version("0.4.6"))
+    wheel = tmp_path / "atbash_hermes_plugin-0.4.6-py3-none-any.whl"
+    with zipfile.ZipFile(wheel, "w") as archive:
+        archive.writestr(
+            "atbash_hermes_plugin-0.4.6.dist-info/METADATA",
+            _metadata(release.PROJECT, "0.4.6"),
+        )
+    with pytest.raises(release.ReleaseError, match="importable plugin module"):
+        release.verify_dist(tmp_path, Version("0.4.6"))
+
+
+def test_distribution_verifier_rejects_extra_or_misnamed_artifacts(tmp_path: Path) -> None:
+    _valid_dist(tmp_path)
+    (tmp_path / "unexpected.txt").write_text("no", encoding="utf-8")
+    with pytest.raises(release.ReleaseError, match="artifact names must be exact"):
+        release.verify_dist(tmp_path, Version("0.4.6"))
+
+
+class _Response(io.BytesIO):
+    status = 200
+
+    def __enter__(self) -> "_Response":
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+
+def _registry_response(dist: Path, *, corrupt: bool = False) -> _Response:
+    urls = []
+    for path in sorted(dist.iterdir()):
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        if corrupt and path.suffix == ".whl":
+            digest = "0" * 64
+        urls.append({"filename": path.name, "digests": {"sha256": digest}})
+    return _Response(json.dumps({"urls": urls}).encode())
+
+
+def test_uploaded_artifacts_are_retried_then_digest_matched(tmp_path: Path) -> None:
+    _valid_dist(tmp_path)
+    calls: list[str] = []
+    sleeps: list[float] = []
+
+    def opener(url: str, **_kwargs: object) -> _Response:
+        calls.append(url)
+        return _registry_response(tmp_path, corrupt=len(calls) == 1)
+
+    release.verify_uploaded(
+        tmp_path,
+        Version("0.4.6"),
+        attempts=2,
+        delay_seconds=0.25,
+        opener=opener,
+        sleeper=sleeps.append,
+    )
+    assert calls == [release.PYPI_VERSION_URL.format(version="0.4.6")] * 2
+    assert sleeps == [0.25]
+
+
+def test_uploaded_artifact_mismatch_fails_closed(tmp_path: Path) -> None:
+    _valid_dist(tmp_path)
+    with pytest.raises(release.ReleaseError, match="did not converge"):
+        release.verify_uploaded(
+            tmp_path,
+            Version("0.4.6"),
+            attempts=1,
+            opener=lambda *_args, **_kwargs: _registry_response(tmp_path, corrupt=True),
+            sleeper=lambda _delay: None,
+        )