@passioncode-ai/fabric-agent-adapter 0.39.1 → 0.41.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_delegation.py

@@ -16,8 +16,8 @@ R compared by its encoding).
 
 from __future__ import annotations
 
-import base64
 import hashlib
+import http.client
 import ipaddress
 import json
 import math
@@ -31,6 +31,21 @@ from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple
 import urllib.error
 import urllib.parse
 import urllib.request
+import sys as _sys  # noqa: E402
+from pathlib import Path as _Path  # noqa: E402
+if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
+    _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+from fabric_crypto import (  # noqa: E402 - the core (FAA-65)
+    SMALL_ORDER_ENCODINGS,  # noqa: F401 - public here since v0.39.1 (test/fixtures/kit-api)
+    b64url as _b64encode,
+    b64url_decode as _b64decode,
+    ed25519_verify,
+    is_small_order_key,
+)
+from fabric_jsvalue import (  # noqa: E402 - the core (FAA-65)
+    MISSING as _MISSING,
+    jcs,
+)
 
 REFUSAL_CODES = (
     "unauthenticated", "token-expired", "wrong-audience", "scope-not-granted", "effect-above-ceiling", "no-grant",
@@ -50,6 +65,8 @@ JWKS_MAX_AGE_SECONDS = 600
 JWKS_REREAD_SECONDS = 60
 # After a failed read, wait this long before trying again, so a down issuer does not cost every call a fetch.
 JWKS_RETRY_SECONDS = 10
+# One read of the key set, headers and body together, ends within this many seconds (Node's AbortSignal.timeout(5000)).
+JWKS_FETCH_SECONDS = 5.0
 # JavaScript's String.prototype.trim set, so a header is trimmed as the contract's verifier trims it.
 _JS_WHITESPACE = "\t\n\v\f\r \u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
 
@@ -76,31 +93,15 @@ REFUSAL_MESSAGES = {
     "unknown-state": "The state cannot be established, so the call is refused.",
 }
 
-_B64URL = re.compile(r"^[A-Za-z0-9_-]+$")
+_B64URL = re.compile(r"^[A-Za-z0-9_-]+\Z")
 # DL-2's grammar, as the contract's verifier types the claims (DEC-0045): an agent id, an opaque session or task id,
 # a URI, a jti and a scope.
-AGENT_ID = re.compile(r"^[a-z][a-z0-9-]{1,62}(\.[a-z][a-z0-9-]{0,31})?$")
-OPAQUE_ID = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
-_URI = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:\S+$")
-_JTI = re.compile(r"^[A-Za-z0-9._~-]{16,128}$")
-_SCOPE = re.compile(r"^[a-z][a-z0-9._-]{1,127}( [a-z][a-z0-9._-]{1,127})*$")
+AGENT_ID = re.compile(r"^[a-z][a-z0-9-]{1,62}(\.[a-z][a-z0-9-]{0,31})?\Z")
+OPAQUE_ID = re.compile(r"^[A-Za-z0-9._:-]{1,128}\Z")
+_URI = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:\S+\Z")
+_JTI = re.compile(r"^[A-Za-z0-9._~-]{16,128}\Z")
+_SCOPE = re.compile(r"^[a-z][a-z0-9._-]{1,127}( [a-z][a-z0-9._-]{1,127})*\Z")
 _SPEND_WINDOWS = ("total", "task", "project", "day", "week", "month")
-# The small-order points of edwards25519 and their non-canonical encodings, sign bit cleared (the contract's
-# src/ed25519.ts; libsodium's has_small_order list).
-SMALL_ORDER_ENCODINGS = (
-    "0000000000000000000000000000000000000000000000000000000000000000", "0100000000000000000000000000000000000000000000000000000000000000",
-    "26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05", "c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a",
-    "ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f", "edffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f",
-    "eeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f",
-)
-_MISSING = object()
-
-
-def is_small_order_key(raw: bytes) -> bool:
-    """Whether a 32-byte Ed25519 public key is a point of small order, in any encoding (CT-29)."""
-    if len(raw) != 32:
-        return True
-    return (raw[:31] + bytes([raw[31] & 0x7F])).hex() in SMALL_ORDER_ENCODINGS
 
 
 def _full(pattern: "re.Pattern[str]", value: Any) -> bool:
@@ -128,90 +129,9 @@ def _is_time(value: Any) -> bool:
 
 # --- Ed25519 (RFC 8032 §5.1) ----------------------------------------------------------------------------
 
-_P = 2 ** 255 - 19
-_L = 2 ** 252 + 27742317777372353535851937790883648493
-_D = (-121665 * pow(121666, _P - 2, _P)) % _P
-_SQRT_M1 = pow(2, (_P - 1) // 4, _P)
-
-
-def _add(a: Tuple[int, int, int, int], b: Tuple[int, int, int, int]) -> Tuple[int, int, int, int]:
-    x1, y1, z1, t1 = a
-    x2, y2, z2, t2 = b
-    aa = (y1 - x1) * (y2 - x2) % _P
-    bb = (y1 + x1) * (y2 + x2) % _P
-    cc = 2 * t1 * t2 * _D % _P
-    dd = 2 * z1 * z2 % _P
-    e, f, g, h = bb - aa, dd - cc, dd + cc, bb + aa
-    return (e * f % _P, g * h % _P, f * g % _P, e * h % _P)
-
-
-def _mul(scalar: int, point: Tuple[int, int, int, int]) -> Tuple[int, int, int, int]:
-    result = (0, 1, 1, 0)
-    while scalar:
-        if scalar & 1:
-            result = _add(result, point)
-        point = _add(point, point)
-        scalar >>= 1
-    return result
-
-
-def _decode_point(data: bytes) -> Optional[Tuple[int, int, int, int]]:
-    if len(data) != 32:
-        return None
-    y = int.from_bytes(data, "little")
-    sign = y >> 255
-    y &= (1 << 255) - 1
-    if y >= _P:
-        return None
-    x2 = (y * y - 1) * pow(_D * y * y + 1, _P - 2, _P) % _P
-    if x2 == 0:
-        if sign:
-            return None
-        return (0, y, 1, 0)
-    x = pow(x2, (_P + 3) // 8, _P)
-    if (x * x - x2) % _P:
-        x = x * _SQRT_M1 % _P
-    if (x * x - x2) % _P:
-        return None
-    if x & 1 != sign:
-        x = _P - x
-    return (x, y, 1, x * y % _P)
-
-
-def _encode_point(point: Tuple[int, int, int, int]) -> bytes:
-    x, y, z, _ = point
-    zi = pow(z, _P - 2, _P)
-    x, y = x * zi % _P, y * zi % _P
-    return (y | ((x & 1) << 255)).to_bytes(32, "little")
-
-
-_G = _decode_point(bytes.fromhex("5866666666666666666666666666666666666666666666666666666666666666"))
-_IDENTITY = (1).to_bytes(32, "little")
-
-
-def ed25519_verify(public_key: bytes, message: bytes, signature: bytes) -> bool:
-    """RFC 8032 §5.1.7, cofactorless: [S]B == R + [k]A, compared by R's encoding. False, never an exception."""
-    if len(public_key) != 32 or len(signature) != 64:
-        return False
-    s = int.from_bytes(signature[32:], "little")
-    if s >= _L:
-        return False
-    a = _decode_point(public_key)
-    if a is None or _encode_point(_mul(8, a)) == _IDENTITY:
-        return False  # a small-order key would accept R = [S]B for a quarter or more of all messages; OpenSSL refuses it
-    k = int.from_bytes(hashlib.sha512(signature[:32] + public_key + message).digest(), "little") % _L
-    neg_a = ((-a[0]) % _P, a[1], a[2], (-a[3]) % _P)
-    return secrets.compare_digest(_encode_point(_add(_mul(s, _G), _mul(k, neg_a))), signature[:32])
-
 
 # --- the compact document ------------------------------------------------------------------------------
 
-def _b64decode(segment: str) -> bytes:
-    """Base64url without padding, as Node reads it: a dangling sixth bit group is ignored."""
-    if len(segment) % 4 == 1:
-        segment = segment[:-1]
-    return base64.urlsafe_b64decode(segment + "=" * (-len(segment) % 4))
-
 
 class _Duplicate(ValueError):
     pass
@@ -305,7 +225,8 @@ def _key_for(jwks: Dict[str, Any], kid: str) -> Dict[str, Any]:
         raw = _b64decode(jwk["x"])
     except ValueError:
         return {"problem": "unusable-key"}
-    if len(raw) != 32:
+    # D4: exactly the 43 characters that write 32 bytes, so the key compared with the estate record is one string.
+    if len(raw) != 32 or _b64encode(raw) != jwk["x"]:
         return {"problem": "unusable-key"}
     if is_small_order_key(raw):
         return {"problem": "small-order-key"}  # refused before any verification (DEC-0045, CT-29)
@@ -460,24 +381,27 @@ def _readable_clock(now: Any) -> bool:
         return False
 
 
-def _estate_problem(estate: Any, kid: str, x: str, now: float, applied: Any = None,
-                    revocations: Any = None) -> Optional[Tuple[str, str]]:
+def _estate_problem(estate: Any, kid: str, x: str, now: float, applied: Any = _MISSING,
+                    revocations: Any = _MISSING) -> Optional[Tuple[str, str]]:
     """DL-14 row 4a (DEC-0055, DEC-0060), right after the signature: when the callee reads the estate record, the
     token's kid and the published key must be certified by that revision. `estate` is a revision the caller verified
-    (fabric_estate.verify_estate_record) and its machine applied, or a callable returning it; None skips the rule (a
-    callable returning None is an unreadable source). `applied` is the highest revision the machine applied
-    (`{"revision", "digest"?}`); `revocations` the revocation delta's entries applied since (a list or a callable). A
-    source that raises is unreadable, never a pass. Returns ("token" | "issuer", detail) or None."""
-    if estate is None:
+    (fabric_estate.verify_estate_record) and its machine applied, or a callable returning it; only an omitted `estate`
+    skips the rule, and None (given, or returned by the callable) is an unreadable source, as Node's null is (D3).
+    `applied` is the highest revision the machine applied (`{"revision", "digest"?}`); `revocations` the revocation
+    delta's entries applied since (a list or a callable). An omitted one is absent; None is unreadable. A source that
+    raises is unreadable, never a pass. Returns ("token" | "issuer", detail) or None."""
+    if estate is _MISSING:
         return None
     try:
         record = estate() if callable(estate) else estate
         extra = revocations() if callable(revocations) else revocations
     except Exception:
         return ("issuer", "estate-unreadable")
+    if applied is None:  # the contract's hubKeyCertified refuses a null applied mark after its record checks: unreadable
+        return ("issuer", "estate-unreadable")
     import fabric_estate  # beside this file; imported here, since fabric_estate imports this module
-    verdict = fabric_estate.hub_key_certified(record, kid, x, now, applied,
-                                              fabric_estate._MISSING if extra is None else extra)
+    given = {} if applied is _MISSING else {"applied": applied}
+    verdict = fabric_estate.hub_key_certified(record, kid, x, now, extra_revocations=extra, **given)
     if verdict["certified"]:
         return None
     # The clock was refused before row 1, so a verdict here is the token's or the trust source's.
@@ -485,8 +409,8 @@ def _estate_problem(estate: Any, kid: str, x: str, now: float, applied: Any = No
 
 
 def verify_delegation(token: Any, *, audience: str, jwks: Any, now: float, capability: str, effect: str,
-                      issuer: Optional[str], read_only: bool = False, estate: Any = None,
-                      estate_applied: Any = None, estate_revocations: Any = None) -> Dict[str, Any]:
+                      issuer: Optional[str], read_only: bool = False, estate: Any = _MISSING,
+                      estate_applied: Any = _MISSING, estate_revocations: Any = _MISSING) -> Dict[str, Any]:
     """DL-13, in its fixed order: nothing about a token is believed before its signature is.
     `now` is seconds since the epoch. Returns {ok: True, claims, principal, caller, chain, kid} or a refusal
     {ok: False, code, detail[, data]} whose detail is a short machine word, never the token. `issuer` is required.
@@ -606,8 +530,8 @@ UNSAFE_NO_JTI_STORE = _NoReplayProtection()
 
 
 def verify_approval(approval: Optional[str], *, audience: str, jwks: Any, now: float, action_digest: str,
-                    jti_store: Any, issuer: Optional[str], estate: Any = None, estate_applied: Any = None,
-                    estate_revocations: Any = None) -> Dict[str, Any]:
+                    jti_store: Any, issuer: Optional[str], estate: Any = _MISSING, estate_applied: Any = _MISSING,
+                    estate_revocations: Any = _MISSING) -> Dict[str, Any]:
     """DL-18: a missing approval is approval-required carrying the action digest; any fault of the document is
     approval-invalid; a second use is approval-reused. The jti is consumed last."""
     if approval is None or approval == "":
@@ -681,90 +605,6 @@ def read_delegation_token(headers: Any) -> Optional[Dict[str, str]]:
 
 # --- RFC 8785 canonical JSON --------------------------------------------------------------------------------
 
-def _number(value: float) -> str:
-    """ECMAScript Number::toString, which RFC 8785 §3.2.2.3 prescribes."""
-    if value == 0:
-        return "0"
-    if value < 0:
-        return "-" + _number(-value)
-    digits, exponent = _shortest(value)
-    k, n = len(digits), len(digits) + exponent
-    if k <= n <= 21:
-        return digits + "0" * (n - k)
-    if 0 < n <= 21:
-        return digits[:n] + "." + digits[n:]
-    if -6 < n <= 0:
-        return "0." + "0" * (-n) + digits
-    e = n - 1
-    mantissa = digits if k == 1 else digits[0] + "." + digits[1:]
-    return "%se%s%d" % (mantissa, "+" if e >= 0 else "-", abs(e))
-
-
-def _shortest(value: float) -> Tuple[str, int]:
-    """The shortest round-trip digits of a positive finite double (Python's repr is shortest round-trip)."""
-    text = repr(value)
-    mantissa, _, exp = text.partition("e")
-    whole, _, frac = mantissa.partition(".")
-    digits = (whole + frac).lstrip("0")
-    exponent = (int(exp) if exp else 0) - len(frac)
-    if not digits:
-        return "0", 0
-    stripped = digits.rstrip("0")
-    exponent += len(digits) - len(stripped)
-    return stripped, exponent
-
-
-_ESCAPES = {'"': '\\"', "\\": "\\\\", "\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
-
-
-def _string(value: str) -> str:
-    out = ['"']
-    for ch in value:
-        code = ord(ch)
-        if 0xD800 <= code <= 0xDFFF:
-            raise TypeError("a lone surrogate has no canonical form")
-        if ch in _ESCAPES:
-            out.append(_ESCAPES[ch])
-        elif code < 0x20:
-            out.append("\\u%04x" % code)
-        else:
-            out.append(ch)
-    out.append('"')
-    return "".join(out)
-
-
-def jcs(value: Any) -> str:
-    """RFC 8785: members sorted by UTF-16 code units, numbers in ECMAScript form, strings as JSON.stringify
-    escapes them. Refuses what has no canonical form: a non-finite number, a lone surrogate, a non-JSON value.
-    A JSON number is a double: an integer beyond 2**53 is written as JavaScript would write it."""
-    if value is None:
-        return "null"
-    if value is True:
-        return "true"
-    if value is False:
-        return "false"
-    if isinstance(value, int):
-        if abs(value) < 2 ** 53:
-            return str(value)
-        try:
-            return _number(float(value))
-        except OverflowError:
-            raise TypeError("a number beyond a double has no canonical form") from None
-    if isinstance(value, float):
-        if not math.isfinite(value):
-            raise TypeError("a non-finite number has no canonical form")
-        return _number(value)
-    if isinstance(value, str):
-        return _string(value)
-    if isinstance(value, list):
-        return "[" + ",".join(jcs(item) for item in value) + "]"
-    if isinstance(value, dict):
-        if not all(isinstance(key, str) for key in value):
-            raise TypeError("only string member names have a canonical form")
-        keys = sorted(value, key=lambda key: key.encode("utf-16-be", "surrogatepass"))
-        return "{" + ",".join(_string(key) + ":" + jcs(value[key]) for key in keys) + "}"
-    raise TypeError("%s has no canonical form" % type(value).__name__)
-
 
 def action_digest(action: Any) -> str:
     """The digest an approval binds: sha256: and the hex SHA-256 of the action's RFC 8785 form."""
@@ -789,18 +629,60 @@ class _NoRedirect(urllib.request.HTTPRedirectHandler):
         return None
 
 
-_OPENER = urllib.request.build_opener(_NoRedirect)
+def _opener(deadline: Dict[str, Any]) -> urllib.request.OpenerDirector:
+    """No redirect, and a timer that shuts the socket down at the deadline: a socket timeout bounds one read, so an
+    issuer trickling a byte a second would otherwise hold the caller for as long as it likes (finding 13)."""
+    def watched(base: type) -> type:
+        class Watched(base):  # type: ignore[misc, valid-type]
+            def connect(self) -> None:
+                super().connect()
+                sock = self.sock
+
+                def fire() -> None:
+                    deadline["fired"] = True
+                    try:
+                        sock.shutdown(2)  # socket.SHUT_RDWR
+                    except OSError:
+                        pass
+                timer = threading.Timer(max(0.0, deadline["end"] - time.monotonic()), fire)
+                timer.daemon = True
+                deadline["timer"] = timer
+                timer.start()
+        return Watched
+
+    class Http(urllib.request.HTTPHandler):
+        def http_open(self, req: Any) -> Any:
+            return self.do_open(watched(http.client.HTTPConnection), req)
+
+    class Https(urllib.request.HTTPSHandler):
+        def https_open(self, req: Any) -> Any:
+            return self.do_open(watched(http.client.HTTPSConnection), req, context=self._context)
+    return urllib.request.build_opener(_NoRedirect, Http, Https)
 
 
 def _fetch(source: str) -> Any:
     if source.startswith(("https://", "http://")):
         request = urllib.request.Request(source, headers={"Accept": "application/json"})
+        deadline: Dict[str, Any] = {"end": time.monotonic() + JWKS_FETCH_SECONDS, "fired": False, "timer": None}
         try:
-            with _OPENER.open(request, timeout=5) as response:  # https or loopback http only, no redirect
-                return json.loads(response.read(65537)[:65536])
+            with _opener(deadline).open(request, timeout=JWKS_FETCH_SECONDS) as response:  # https or loopback http only
+                body = b""
+                while len(body) <= 65536 and not deadline["fired"]:
+                    chunk = response.read1(65537 - len(body))
+                    if not chunk:
+                        break
+                    body += chunk
+            if deadline["fired"] or time.monotonic() > deadline["end"]:
+                raise TimeoutError("the key set did not arrive within %s s" % JWKS_FETCH_SECONDS)
+            return json.loads(body[:65536])
         except urllib.error.HTTPError as exc:
             exc.close()
             raise
+        except http.client.HTTPException as exc:  # a garbage status line or headers: the issuer cannot be read
+            raise ConnectionError(type(exc).__name__) from None
+        finally:
+            if deadline["timer"] is not None:
+                deadline["timer"].cancel()
     return json.loads(Path(source).expanduser().read_text())
 
 
@@ -828,28 +710,37 @@ class JwksCache:
         self._tried_at = -math.inf
         self._reread_at = -math.inf  # the last re-read for a kid the set did not hold
         self._lock = threading.Lock()
-
-    def _read(self, now: float) -> None:
-        self._tried_at = now
-        try:
-            value = self._fetch(self.source)
-        except (OSError, ValueError):
-            return
-        if _has_keys(value):
-            self._keys, self._read_at = value, now
+        self._pending: Optional[threading.Event] = None
 
     def get(self, kid: Optional[str] = None) -> Optional[Dict[str, Any]]:
+        """The key set, or None. The read runs outside the lock (finding 13): a caller whose kid the set holds never
+        waits on another caller's fetch, and one read at a time goes out, as Node's `pending` does."""
+        leader, waiting = False, None
         with self._lock:
             now = self._clock()
             fresh = now - self._read_at < JWKS_MAX_AGE_SECONDS
             known = self._keys is not None and (kid is None or any(isinstance(k, dict) and k.get("kid") == kid for k in self._keys["keys"]))
-            if not fresh:
-                if now - self._tried_at >= JWKS_RETRY_SECONDS:
-                    self._read(now)
-            elif not known and now - self._reread_at >= JWKS_REREAD_SECONDS:
+            due = (not fresh and now - self._tried_at >= JWKS_RETRY_SECONDS) or (fresh and not known and now - self._reread_at >= JWKS_REREAD_SECONDS)
+            if due and fresh:
                 self._reread_at = now
-                self._read(now)
-            return self._keys if now - self._read_at < JWKS_MAX_AGE_SECONDS else None
+            if due and self._pending is None:
+                self._pending, self._tried_at, leader = threading.Event(), now, True
+            elif due:
+                waiting = self._pending
+        if leader:
+            try:
+                value = self._fetch(self.source)
+            except Exception:  # noqa: BLE001 - whatever a source raises leaves the set unread; the age check decides
+                value = None
+            with self._lock:
+                if _has_keys(value):
+                    self._keys, self._read_at = value, now
+                done, self._pending = self._pending, None
+            done.set()
+        elif waiting is not None:
+            waiting.wait(JWKS_FETCH_SECONDS + 1)
+        with self._lock:
+            return self._keys if self._clock() - self._read_at < JWKS_MAX_AGE_SECONDS else None
 
 
 def _kid_of(token: str) -> Optional[str]:
@@ -864,8 +755,8 @@ TIERS = ("T0", "T1", "T2")
 
 
 def delegation_gate(*, audience: str, jwks: Any, effects: Mapping[str, str], issuer: str,
-                    read_only: bool = False, clock: Callable[[], float] = time.time, estate: Any = None,
-                    estate_applied: Any = None, estate_revocations: Any = None) -> Callable[..., Dict[str, Any]]:
+                    read_only: bool = False, clock: Callable[[], float] = time.time, estate: Any = _MISSING,
+                    estate_applied: Any = _MISSING, estate_revocations: Any = _MISSING) -> Callable[..., Dict[str, Any]]:
     """A check for one tools/call: `gate(tool, headers, tier="T2")` answers the accepted delegation or a DL-19
     refusal. `effects` maps each tool to its declared effect class (its manifest entry); a tool with none is
     refused rather than guessed. `jwks` is a JwksCache or a key set; `issuer` (auth.delegation.issuer) is required.