hs-verify 0.1.0__tar.gz

hs_verify-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: hs-verify
+Version: 0.1.0
+Summary: Keyless verification of Hunter-Seeker Verdicts (Ed25519 detached JWS over RFC 8785 JCS).
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/dmilstein-match/hunter-seeker-verify
+Project-URL: Source, https://github.com/dmilstein-match/hunter-seeker-verify
+Project-URL: JWKS, https://hunter-seeker.net/.well-known/jwks.json
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42
+
+# hs-verify
+
+Keyless verification of a **Hunter-Seeker Verdict** — the signed decision an AI agent receives
+when it asks Hunter-Seeker who to act on and why. No account, no API key, no call to
+Hunter-Seeker beyond fetching the public keys.
+
+```python
+from hs_verify import verify
+verify(verdict, signature)              # fetches the published JWKS
+verify(verdict, signature, jwks=jwks)   # fully offline
+```
+```bash
+hs-verify verdict.json signature.json [jwks.json]
+```
+
+Returns exactly one of `valid`, `invalid_signature`, `expired`, `unknown_key`. The verifier is
+not an oracle: those four words are the whole output.
+
+A Verdict with no signature is unverifiable and reports `invalid_signature`, never `valid`.
+
+Ed25519 detached JWS (RFC 7797, `b64:false`) over RFC 8785 canonical JSON. The TypeScript
+twin — `@hunter-seeker/verify` — tests against the same vectors, which is how the two are
+proven interoperable.
+
+**Pre-release:** the hosted JWKS is not serving yet and the committed test vectors are signed
+with a pre-release key. Full status, trust model and vectors:
+https://github.com/dmilstein-match/hunter-seeker-verify
+
+Apache-2.0.

hs_verify-0.1.0/README.md

@@ -0,0 +1,29 @@
+# hs-verify
+
+Keyless verification of a **Hunter-Seeker Verdict** — the signed decision an AI agent receives
+when it asks Hunter-Seeker who to act on and why. No account, no API key, no call to
+Hunter-Seeker beyond fetching the public keys.
+
+```python
+from hs_verify import verify
+verify(verdict, signature)              # fetches the published JWKS
+verify(verdict, signature, jwks=jwks)   # fully offline
+```
+```bash
+hs-verify verdict.json signature.json [jwks.json]
+```
+
+Returns exactly one of `valid`, `invalid_signature`, `expired`, `unknown_key`. The verifier is
+not an oracle: those four words are the whole output.
+
+A Verdict with no signature is unverifiable and reports `invalid_signature`, never `valid`.
+
+Ed25519 detached JWS (RFC 7797, `b64:false`) over RFC 8785 canonical JSON. The TypeScript
+twin — `@hunter-seeker/verify` — tests against the same vectors, which is how the two are
+proven interoperable.
+
+**Pre-release:** the hosted JWKS is not serving yet and the committed test vectors are signed
+with a pre-release key. Full status, trust model and vectors:
+https://github.com/dmilstein-match/hunter-seeker-verify
+
+Apache-2.0.

hs_verify-0.1.0/hs_verify/__init__.py

@@ -0,0 +1,114 @@
+"""hs-verify — keyless verification of a Hunter-Seeker Verdict.
+
+    from hs_verify import verify
+    status = verify(verdict, signature)            # fetches the published JWKS
+    status = verify(verdict, signature, jwks=jwks) # offline
+
+Returns exactly one of: "valid" | "invalid_signature" | "expired" | "unknown_key".
+No account, no API key, no call to Hunter-Seeker beyond fetching the public keys.
+Dependencies: `cryptography` only.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import os
+import math
+import urllib.request
+from datetime import datetime, timezone
+from typing import Any, Mapping, Optional
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+JWKS_URL = "https://hunter-seeker.net/.well-known/jwks.json"
+__all__ = ["verify", "canonicalize", "fetch_jwks", "JWKS_URL"]
+
+_ESC = {'"': '\\"', "\\": "\\\\", "\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+
+
+def _s(s: str) -> str:
+    return '"' + "".join(_ESC.get(c, f"\\u{ord(c):04x}" if ord(c) < 0x20 else c) for c in s) + '"'
+
+
+def _n(x: float | int) -> str:
+    if isinstance(x, int):
+        return str(x)
+    if math.isnan(x) or math.isinf(x):
+        raise ValueError("NaN/Infinity")
+    if x == 0:
+        return "0"
+    if x.is_integer() and abs(x) < 1e21:
+        return str(int(x))
+    r = repr(x)
+    if "e" in r:
+        m, e = r.split("e"); ei = int(e)
+        r = f"{m}e{'+' if ei >= 0 else '-'}{abs(ei)}"
+    return r
+
+
+def canonicalize(v: Any) -> str:
+    """RFC 8785 JCS (the subset a Verdict uses)."""
+    if v is None: return "null"
+    if v is True: return "true"
+    if v is False: return "false"
+    if isinstance(v, (int, float)): return _n(v)
+    if isinstance(v, str): return _s(v)
+    if isinstance(v, (list, tuple)): return "[" + ",".join(canonicalize(x) for x in v) + "]"
+    if isinstance(v, dict):
+        items = sorted(v.items(), key=lambda kv: list(str(kv[0]).encode("utf-16-be")))
+        return "{" + ",".join(f"{_s(str(k))}:{canonicalize(x)}" for k, x in items) + "}"
+    raise TypeError(type(v).__name__)
+
+
+def _b64u(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def fetch_jwks(url: Optional[str] = None, timeout: float = 5.0) -> dict:
+    """Fetch the published keys. `url` defaults to HS_JWKS_URL, else JWKS_URL.
+
+    Resolved at CALL time, not bound as a default argument: a default binds the value at import,
+    so `hs_verify.JWKS_URL = ...` silently did nothing and the library kept fetching the public
+    host. Anyone self-hosting an engine, or testing against a staging one, hits that — and it
+    fails as a 404 that looks like the service being down rather than like a setting being
+    ignored.
+    """
+    url = url or os.environ.get("HS_JWKS_URL") or JWKS_URL
+    with urllib.request.urlopen(url, timeout=timeout) as r:  # noqa: S310 - https, fixed host
+        return json.load(r)
+
+
+def verify(verdict: Mapping[str, Any], signature: Mapping[str, str], *,
+           jwks: Optional[Mapping[str, Any]] = None, now: Optional[datetime] = None) -> str:
+    # OUTSIDE the try, deliberately. A JWKS that cannot be fetched is a transport failure, not
+    # a verification result: swallowing it into the uniform "invalid_signature" below told the
+    # caller a genuine Verdict was FORGED because their DNS was down — the one error that
+    # makes an auditor reject a real decision. The four-word contract describes what the
+    # verifier concluded about the Verdict; it has no word for "I could not reach the keys",
+    # so that stays an exception the caller can see.
+    if jwks is None:
+        jwks = fetch_jwks()
+    try:
+        header = json.loads(_b64u(signature["protected"]))
+        if header.get("alg") != "EdDSA" or header.get("b64") is not False:
+            return "invalid_signature"
+        key = next((k for k in jwks.get("keys", []) if k.get("kid") == header.get("kid")), None)
+        if key is None:
+            return "unknown_key"
+        pub = Ed25519PublicKey.from_public_bytes(_b64u(key["x"]))
+        pub.verify(_b64u(signature["signature"]),
+                   signature["protected"].encode("ascii") + b"." + canonicalize(verdict).encode())
+    except Exception:  # noqa: BLE001 - uniform failure
+        return "invalid_signature"
+    exp = verdict.get("expires_at")
+    now = now or datetime.now(timezone.utc)
+    if isinstance(exp, str) and now.strftime("%Y-%m-%dT%H:%M:%SZ") > exp:
+        return "expired"
+    return "valid"
+
+
+def main() -> None:  # `hs-verify verdict.json signature.json [jwks.json]`
+    import sys
+    v = json.load(open(sys.argv[1])); s = json.load(open(sys.argv[2]))
+    j = json.load(open(sys.argv[3])) if len(sys.argv) > 3 else None
+    print(verify(v, s, jwks=j))

hs_verify-0.1.0/hs_verify.egg-info/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: hs-verify
+Version: 0.1.0
+Summary: Keyless verification of Hunter-Seeker Verdicts (Ed25519 detached JWS over RFC 8785 JCS).
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/dmilstein-match/hunter-seeker-verify
+Project-URL: Source, https://github.com/dmilstein-match/hunter-seeker-verify
+Project-URL: JWKS, https://hunter-seeker.net/.well-known/jwks.json
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42
+
+# hs-verify
+
+Keyless verification of a **Hunter-Seeker Verdict** — the signed decision an AI agent receives
+when it asks Hunter-Seeker who to act on and why. No account, no API key, no call to
+Hunter-Seeker beyond fetching the public keys.
+
+```python
+from hs_verify import verify
+verify(verdict, signature)              # fetches the published JWKS
+verify(verdict, signature, jwks=jwks)   # fully offline
+```
+```bash
+hs-verify verdict.json signature.json [jwks.json]
+```
+
+Returns exactly one of `valid`, `invalid_signature`, `expired`, `unknown_key`. The verifier is
+not an oracle: those four words are the whole output.
+
+A Verdict with no signature is unverifiable and reports `invalid_signature`, never `valid`.
+
+Ed25519 detached JWS (RFC 7797, `b64:false`) over RFC 8785 canonical JSON. The TypeScript
+twin — `@hunter-seeker/verify` — tests against the same vectors, which is how the two are
+proven interoperable.
+
+**Pre-release:** the hosted JWKS is not serving yet and the committed test vectors are signed
+with a pre-release key. Full status, trust model and vectors:
+https://github.com/dmilstein-match/hunter-seeker-verify
+
+Apache-2.0.

hs_verify-0.1.0/hs_verify.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+hs_verify/__init__.py
+hs_verify.egg-info/PKG-INFO
+hs_verify.egg-info/SOURCES.txt
+hs_verify.egg-info/dependency_links.txt
+hs_verify.egg-info/entry_points.txt
+hs_verify.egg-info/requires.txt
+hs_verify.egg-info/top_level.txt
+tests/test_verify.py

hs_verify-0.1.0/hs_verify.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hs_verify-0.1.0/hs_verify.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hs-verify = hs_verify:main

hs_verify-0.1.0/hs_verify.egg-info/requires.txt

@@ -0,0 +1 @@
+cryptography>=42

hs_verify-0.1.0/hs_verify.egg-info/top_level.txt

@@ -0,0 +1 @@
+hs_verify

hs_verify-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "hs-verify"
+version = "0.1.0"
+description = "Keyless verification of Hunter-Seeker Verdicts (Ed25519 detached JWS over RFC 8785 JCS)."
+requires-python = ">=3.10"
+dependencies = ["cryptography>=42"]
+license = {text = "Apache-2.0"}
+readme = "README.md"
+
+[project.urls]
+Homepage = "https://github.com/dmilstein-match/hunter-seeker-verify"
+Source = "https://github.com/dmilstein-match/hunter-seeker-verify"
+JWKS = "https://hunter-seeker.net/.well-known/jwks.json"
+
+[project.scripts]
+hs-verify = "hs_verify:main"
+
+[tool.pytest.ini_options]
+pythonpath = ["."]

hs_verify-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hs_verify-0.1.0/tests/test_verify.py

@@ -0,0 +1,14 @@
+import json, pathlib
+from datetime import datetime, timezone
+from hs_verify import verify, canonicalize
+
+VEC = json.loads((pathlib.Path(__file__).parents[2] / "vectors.json").read_text())
+
+def test_canonical_matches_engine():
+    assert canonicalize(VEC["payload"]) == VEC["canonical"]
+
+def test_valid_tampered_expired_unknown():
+    assert verify(VEC["payload"], VEC["signature"], jwks=VEC["jwks"]) == "valid"
+    assert verify(VEC["tampered"], VEC["signature"], jwks=VEC["jwks"]) == "invalid_signature"
+    assert verify(VEC["payload"], VEC["signature"], jwks={"keys": []}) == "unknown_key"
+    assert verify(VEC["payload"], VEC["signature"], jwks=VEC["jwks"], now=datetime(2100, 1, 1, tzinfo=timezone.utc)) == "expired"