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

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

@@ -62,8 +62,8 @@ def _finite(value: float) -> bool:
 def _register_ok(kind: str, fields: Dict[str, Any]) -> bool:
     if kind == ENROLL_TOKEN_TYPE:
         return (_matches(_ESTATE_SCOPE, fields["scope"]) and _matches(_SHA256, fields["genesis"]) and fields["purpose"] == ENROLL_PURPOSE
-                and (fields["ceiling"] is None or _matches(_SHA256, fields["ceiling"])) and _finite(_estate.estate_time(fields["notBefore"]))
-                and _finite(_estate.estate_time(fields["expiresAt"])) and _matches(_NONCE32, fields["nonce"]) and _is_one(fields["uses"]))
+                and (fields["ceiling"] is None or _matches(_SHA256, fields["ceiling"])) and _finite(_ftime.parse_rfc3339_ms(fields["notBefore"]))
+                and _finite(_ftime.parse_rfc3339_ms(fields["expiresAt"])) and _matches(_NONCE32, fields["nonce"]) and _is_one(fields["uses"]))
     return _matches(_SHA256, fields["digest"]) and _matches(_NONCE32, fields["nonce"])
 
 
@@ -77,7 +77,7 @@ def signing_statement(kind: str, fields: Any) -> Optional[bytes]:
     if not _register_ok(kind, fields):
         return None
     try:
-        return _delegation.jcs(dict(fields, type=kind)).encode("utf-8")
+        return _jsv.jcs(dict(fields, type=kind)).encode("utf-8")
     except (TypeError, ValueError):
         return None
 
@@ -100,7 +100,7 @@ def verify_enroll_token(token: Any, *, record: Any, genesis: Any, at: Any) -> Di
     clock (an aware datetime or epoch seconds). The first failure answers: no-clock, malformed, wrong-estate, the passkey
     (no-trusted-authority, revoked-authority, duplicate-authority, unknown-authority), the assertion, then the window
     (too-long-lived, not-yet-valid, expired). Success: ``{"ok": True, "nonce", "expiresAt", "signedBy"}``."""
-    now = _estate._clock(at)
+    now = _ftime.clock_ms(at)
     if not _finite(now):
         return {"ok": False, "problem": "no-clock"}
     fields = _statement_fields(token)
@@ -112,31 +112,31 @@ def verify_enroll_token(token: Any, *, record: Any, genesis: Any, at: Any) -> Di
         return {"ok": False, "problem": "malformed"}
     if fields["scope"] != "estate:%s" % record["estate"] or not isinstance(genesis, str) or fields["genesis"] != genesis:
         return {"ok": False, "problem": "wrong-estate"}
-    authorities = _estate._list(record.get("authorities"))
+    authorities = _jsv.objects(record.get("authorities"))
     if not authorities:
         return {"ok": False, "problem": "no-trusted-authority"}
     credential_id = signature["credentialId"]
-    if any(entry.get("kind") == "authority" and _estate._same(entry.get("ref", _estate._MISSING), credential_id) for entry in _estate._list(record.get("revocations"))):
+    if any(entry.get("kind") == "authority" and _jsv.same(entry.get("ref", _jsv.MISSING), credential_id) for entry in _jsv.objects(record.get("revocations"))):
         return {"ok": False, "problem": "revoked-authority"}
-    matches = [entry for entry in authorities if _estate._same(entry.get("credentialId", _estate._MISSING), credential_id)]
+    matches = [entry for entry in authorities if _jsv.same(entry.get("credentialId", _jsv.MISSING), credential_id)]
     if len(matches) > 1:
         return {"ok": False, "problem": "duplicate-authority"}
     if not matches:
         return {"ok": False, "problem": "unknown-authority"}
     authority = matches[0]
     origins = authority.get("origins")
-    rp_id = _estate._show(authority.get("rpId", _estate._MISSING))
+    rp_id = _jsv.show(authority.get("rpId", _jsv.MISSING))
     if not _estate.is_signing_rp_id(rp_id):
         return {"ok": False, "problem": "wrong-rp"}
-    credential = {"credentialId": credential_id, "alg": _estate._show(authority.get("alg", _estate._MISSING)),
+    credential = {"credentialId": credential_id, "alg": _jsv.show(authority.get("alg", _jsv.MISSING)),
                   "publicKey": authority["publicKey"] if isinstance(authority.get("publicKey"), dict) else {}, "rpId": rp_id,
                   "origins": [o for o in origins if isinstance(o, str) and _estate.origin_within(o, rp_id)] if isinstance(origins, list) else []}
     challenge = hashlib.sha256(signing_statement(ENROLL_TOKEN_TYPE, fields)).digest()
     assertion = _estate.verify_assertion(signature, credential, challenge)
     if not assertion["ok"]:
         return {"ok": False, "problem": assertion["problem"]}
-    not_before = _estate.estate_time(fields["notBefore"])
-    expires_at = _estate.estate_time(fields["expiresAt"])
+    not_before = _ftime.parse_rfc3339_ms(fields["notBefore"])
+    expires_at = _ftime.parse_rfc3339_ms(fields["expiresAt"])
     if expires_at <= not_before or expires_at - not_before > MAX_ENROLL_TOKEN_SECONDS * 1000:
         return {"ok": False, "problem": "too-long-lived"}
     if now < not_before - _estate.CLOCK_SKEW_SECONDS * 1000:
@@ -177,8 +177,8 @@ def _token_findings(value: Dict[str, Any]) -> List[Dict[str, str]]:
         flag("/statement/purpose", "an enroll token's purpose is agent-host")
     if not _is_one(statement.get("uses")):
         flag("/statement/uses", "an enroll token is used once: uses is 1, and the hub binds its nonce on the first use")
-    not_before = _estate.estate_time(statement.get("notBefore"))
-    expires_at = _estate.estate_time(statement.get("expiresAt"))
+    not_before = _ftime.parse_rfc3339_ms(statement.get("notBefore"))
+    expires_at = _ftime.parse_rfc3339_ms(statement.get("expiresAt"))
     rest = {name: v for name, v in statement.items() if name != "type"}
     named = not extra and not missing and statement.get("purpose") == ENROLL_PURPOSE and _is_one(statement.get("uses")) and _finite(not_before) and _finite(expires_at)
     if named and signing_statement(ENROLL_TOKEN_TYPE, rest) is None:
@@ -201,20 +201,21 @@ _PROOF = re.compile(r"[A-Za-z0-9_-]{85}[AQgw]\Z")
 
 
 def _b64url(text: str) -> bytes:
+    """Strict base64url decode: a length the alphabet cannot produce raises, as the ceremony's readers expect."""
     return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
 
 
 def _es256_raw(octets: bytes, message: bytes, raw: bytes) -> bool:
     """ECDSA P-256 over SHA-256 with a 64-byte r || s signature, low-S only (relay-auth/1's form)."""
-    if len(octets) != 65 or octets[0] != 4 or not _estate.is_valid_p256_key(octets) or len(raw) != 64:
+    if len(octets) != 65 or octets[0] != 4 or not _crypto.is_valid_p256_key(octets) or len(raw) != 64:
         return False
     r, s = int.from_bytes(raw[:32], "big"), int.from_bytes(raw[32:], "big")
-    n = _estate._N
+    n = _crypto._P256_N
     if not (1 <= r < n and 1 <= s <= n // 2):
         return False
     e = int.from_bytes(hashlib.sha256(message).digest(), "big")
     w = pow(s, -1, n)
-    point = _estate._shamir(e * w % n, r * w % n, (int.from_bytes(octets[1:33], "big"), int.from_bytes(octets[33:], "big")))
+    point = _crypto._shamir(e * w % n, r * w % n, (int.from_bytes(octets[1:33], "big"), int.from_bytes(octets[33:], "big")))
     return point is not None and point[0] % n == r
 
 
@@ -227,7 +228,7 @@ def _proves(key: Dict[str, Any], message: str, proof: Any) -> bool:
     signature = _b64url(proof)
     if key.get("alg") == "es256":
         return _es256_raw(octets, message.encode("utf-8"), signature)
-    return _delegation.ed25519_verify(octets, message.encode("utf-8"), signature)
+    return _crypto.ed25519_verify(octets, message.encode("utf-8"), signature)
 
 
 def redeem_enroll_token(token: Any, machine_key: Any, proof: Any, ledger: Any) -> Dict[str, Any]:
@@ -244,11 +245,11 @@ def redeem_enroll_token(token: Any, machine_key: Any, proof: Any, ledger: Any) -
     if not _proves(machine_key, join, proof):
         return {"ok": False, "problem": "bad-proof"}
     fingerprint = _estate.device_key_fingerprint(machine_key)
-    entry = ledger.get(nonce, _estate._MISSING)
+    entry = ledger.get(nonce, _jsv.MISSING)
     if isinstance(entry, dict) and entry.get("state") == "revoked":
         return {"ok": False, "problem": "revoked"}
-    if entry is not _estate._MISSING:
-        bound = _estate._show(entry.get("fingerprint", _estate._MISSING)) if isinstance(entry, dict) else _estate._show(entry)
+    if entry is not _jsv.MISSING:
+        bound = _jsv.show(entry.get("fingerprint", _jsv.MISSING)) if isinstance(entry, dict) else _jsv.show(entry)
         return {"ok": False, "problem": "reused", "log": {"nonce": nonce, "presented": fingerprint, "boundTo": bound}}
     return {"ok": True, "record": {"nonce": nonce, "state": "redeemed", "fingerprint": fingerprint}}
 
@@ -268,13 +269,10 @@ _KEY_MEMBERS = ["alg", "kid", "publicKey", "use"]
 _ALGORITHMS = {"sig": ("es256", "ed25519"), "kem": ("ecdh-p256",)}
 
 
-def _json_equal(a: Any, b: Any) -> bool:
-    """The contract's jsonEqual: arrays in order, objects by their members, primitives as JavaScript's ===."""
-    if isinstance(a, list) or isinstance(b, list):
-        return isinstance(a, list) and isinstance(b, list) and len(a) == len(b) and all(_json_equal(x, y) for x, y in zip(a, b))
-    if isinstance(a, dict) or isinstance(b, dict):
-        return isinstance(a, dict) and isinstance(b, dict) and len(a) == len(b) and all(k in b and _json_equal(a[k], b[k]) for k in a)
-    return _estate._same(a, b)
+from fabric_jsvalue import json_equal as _json_equal  # noqa: E402,F401 - moved (FAA-65)
+import fabric_time as _ftime  # noqa: E402 - the core (FAA-65)
+import fabric_jsvalue as _jsv  # noqa: E402 - the core (FAA-65)
+import fabric_crypto as _crypto  # noqa: E402 - the core (FAA-65)
 
 
 def _is_role(value: Any) -> bool:
@@ -337,7 +335,7 @@ def pairing_commit(side: Any) -> Dict[str, Any]:
     problem = _side_problem(side)
     if problem:
         return {"ok": False, "problem": problem}
-    return {"ok": True, "commit": "sha256:" + _sha_hex(_delegation.jcs(dict({"type": COMMIT_TYPE, "role": side["role"]}, **_covered(side))))}
+    return {"ok": True, "commit": "sha256:" + _sha_hex(_jsv.jcs(dict({"type": COMMIT_TYPE, "role": side["role"]}, **_covered(side))))}
 
 
 def _message(value: Any, step: str) -> Optional[Dict[str, Any]]:
@@ -354,7 +352,7 @@ def check_reveal(commit: Any, reveal: Any, expected: Optional[str] = None) -> Di
     c, r = _message(commit, "commit"), _message(reveal, "reveal")
     if c is None or r is None:
         return {"ok": False, "problem": "malformed"}
-    if not _estate._same(r["role"], c["role"]) or (expected is not None and not _estate._same(r["role"], expected)):
+    if not _jsv.same(r["role"], c["role"]) or (expected is not None and not _jsv.same(r["role"], expected)):
         return {"ok": False, "problem": "role-mismatch"}
     made = pairing_commit({k: v for k, v in r.items() if k not in ("schema", "step")})
     if not made["ok"]:
@@ -369,14 +367,14 @@ def comparison_code(new_reveal: Any, trusted_reveal: Any) -> Dict[str, Any]:
     a, b = _message(new_reveal, "reveal"), _message(trusted_reveal, "reveal")
     if a is None or b is None:
         return {"ok": False, "problem": "malformed"}
-    if not _estate._same(a["role"], "new") or not _estate._same(b["role"], "trusted"):
+    if not _jsv.same(a["role"], "new") or not _jsv.same(b["role"], "trusted"):
         return {"ok": False, "problem": "role-mismatch" if _is_role(a["role"]) and _is_role(b["role"]) else "bad-role"}
     problem = _side_problem(a) or _side_problem(b)
     if problem:
         return {"ok": False, "problem": problem}
     if machine_of_keys(a["keys"]) == machine_of_keys(b["keys"]):
         return {"ok": False, "problem": "same-machine"}
-    digest = hashlib.sha256(_delegation.jcs({"type": CODE_TYPE, "new": _covered(a), "trusted": _covered(b)}).encode("utf-8")).digest()
+    digest = hashlib.sha256(_jsv.jcs({"type": CODE_TYPE, "new": _covered(a), "trusted": _covered(b)}).encode("utf-8")).digest()
     return {"ok": True, "code": str(int.from_bytes(digest[:5], "big") % 10 ** CODE_DIGITS).zfill(CODE_DIGITS)}
 
 
@@ -384,7 +382,7 @@ def estate_fingerprint(digest: Any) -> Dict[str, Any]:
     """The estate's fingerprint from revision 1's digest: five groups of five digits a person compares."""
     if not _matches(_SHA256, digest):
         return {"ok": False, "problem": "malformed"}
-    f = hashlib.sha256(_delegation.jcs({"type": FINGERPRINT_TYPE, "digest": digest}).encode("utf-8")).digest()
+    f = hashlib.sha256(_jsv.jcs({"type": FINGERPRINT_TYPE, "digest": digest}).encode("utf-8")).digest()
     groups = [str(int.from_bytes(f[5 * i:5 * i + 5], "big") % 10 ** FINGERPRINT_GROUP_DIGITS).zfill(FINGERPRINT_GROUP_DIGITS) for i in range(FINGERPRINT_GROUPS)]
     return {"ok": True, "fingerprint": " ".join(groups)}
 
@@ -403,8 +401,8 @@ def checked_comparison_code(new_commit: Any, new_reveal: Any, trusted_commit: An
 def rendezvous_verdict(opened_at: Any, messages: Any, at: Any) -> Dict[str, Any]:
     """A one-time rendezvous after the messages it carried, at ``at`` (an aware datetime or epoch seconds): open,
     complete, or burned with the reason and the index of the message that burned it."""
-    opened = _estate.estate_time(opened_at)
-    now = _estate._clock(at)
+    opened = _ftime.parse_rfc3339_ms(opened_at)
+    now = _ftime.clock_ms(at)
     if not _finite(opened) or not _finite(now) or not isinstance(messages, list):
         return {"state": "burned", "reason": "malformed", "index": -1}
     if now > opened + RENDEZVOUS_SECONDS * 1000 or now < opened - _estate.CLOCK_SKEW_SECONDS * 1000:
@@ -443,21 +441,21 @@ def _machine_of(record: Dict[str, Any], machine_id: Any) -> Optional[Dict[str, A
     machines = record.get("machines")
     if not isinstance(machines, list):
         return None
-    return next((m for m in machines if isinstance(m, dict) and _estate._same(m.get("id", _estate._MISSING), machine_id)), None)
+    return next((m for m in machines if isinstance(m, dict) and _jsv.same(m.get("id", _jsv.MISSING), machine_id)), None)
 
 
 def _machine_revoked(record: Dict[str, Any], machine_id: Any) -> bool:
     revocations = record.get("revocations")
     return isinstance(revocations, list) and any(isinstance(e, dict) and e.get("kind") == "machine"
-                                                 and _estate._same(e.get("ref", _estate._MISSING), machine_id) for e in revocations)
+                                                 and _jsv.same(e.get("ref", _jsv.MISSING), machine_id) for e in revocations)
 
 
 def join_listed(record: Any, new_reveal: Any, trusted_reveal: Any, genesis: Any) -> Dict[str, Any]:
     """What the new machine checks before it pins and applies: the estate is the one the code bound, and the record
     lists it with exactly the keys it revealed and the trusted machine with its revealed #sig key, revoking neither."""
     a, b = _message(new_reveal, "reveal"), _message(trusted_reveal, "reveal")
-    if (not isinstance(record, dict) or a is None or b is None or not _estate._same(a["role"], "new")
-            or not _estate._same(b["role"], "trusted") or _side_problem(a) or _side_problem(b)):
+    if (not isinstance(record, dict) or a is None or b is None or not _jsv.same(a["role"], "new")
+            or not _jsv.same(b["role"], "trusted") or _side_problem(a) or _side_problem(b)):
         return {"ok": False, "problem": "malformed"}
     if not isinstance(genesis, str) or b["genesis"] != genesis:
         return {"ok": False, "problem": "other-estate"}

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

@@ -0,0 +1,289 @@
+"""The kit's cryptography, once (FAA-65, layer L1): what the contract's verifiers need and nothing more.
+
+- ``ed25519_verify(public_key, message, signature)`` (RFC 8032) and ``is_small_order_key`` with
+  ``SMALL_ORDER_ENCODINGS``: a key of small order verifies forged signatures and is refused (DEC-0045).
+- ``is_valid_p256_key`` and ``es256_verify`` (ECDSA P-256 over SHA-256, DER or raw signatures) for passkeys.
+- base64url without padding (``b64url``, ``b64url_bytes``, ``node_base64``) and ``sha256``.
+
+Pure Python over integers: slow next to OpenSSL, constant inputs only, verification only. Nothing here signs.
+Standard library only; imports only ``fabric_jsvalue``.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import re
+from typing import Any, Optional, Tuple
+import secrets
+
+
+# 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",
+)
+
+
+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
+
+
+_ED_P = 2 ** 255 - 19
+
+
+_ED_L = 2 ** 252 + 27742317777372353535851937790883648493
+
+
+_ED_D = (-121665 * pow(121666, _ED_P - 2, _ED_P)) % _ED_P
+
+
+_ED_SQRT_M1 = pow(2, (_ED_P - 1) // 4, _ED_P)
+
+
+def _ed_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) % _ED_P
+    bb = (y1 + x1) * (y2 + x2) % _ED_P
+    cc = 2 * t1 * t2 * _ED_D % _ED_P
+    dd = 2 * z1 * z2 % _ED_P
+    e, f, g, h = bb - aa, dd - cc, dd + cc, bb + aa
+    return (e * f % _ED_P, g * h % _ED_P, f * g % _ED_P, e * h % _ED_P)
+
+
+def _ed_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 = _ed_add(result, point)
+        point = _ed_add(point, point)
+        scalar >>= 1
+    return result
+
+
+def _ed_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 >= _ED_P:
+        return None
+    x2 = (y * y - 1) * pow(_ED_D * y * y + 1, _ED_P - 2, _ED_P) % _ED_P
+    if x2 == 0:
+        if sign:
+            return None
+        return (0, y, 1, 0)
+    x = pow(x2, (_ED_P + 3) // 8, _ED_P)
+    if (x * x - x2) % _ED_P:
+        x = x * _ED_SQRT_M1 % _ED_P
+    if (x * x - x2) % _ED_P:
+        return None
+    if x & 1 != sign:
+        x = _ED_P - x
+    return (x, y, 1, x * y % _ED_P)
+
+
+def _ed_encode_point(point: Tuple[int, int, int, int]) -> bytes:
+    x, y, z, _ = point
+    zi = pow(z, _ED_P - 2, _ED_P)
+    x, y = x * zi % _ED_P, y * zi % _ED_P
+    return (y | ((x & 1) << 255)).to_bytes(32, "little")
+
+
+_ED_G = _ed_decode_point(bytes.fromhex("5866666666666666666666666666666666666666666666666666666666666666"))
+
+
+_ED_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 >= _ED_L:
+        return False
+    a = _ed_decode_point(public_key)
+    if a is None or _ed_encode_point(_ed_mul(8, a)) == _ED_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") % _ED_L
+    neg_a = ((-a[0]) % _ED_P, a[1], a[2], (-a[3]) % _ED_P)
+    return secrets.compare_digest(_ed_encode_point(_ed_add(_ed_mul(s, _ED_G), _ed_mul(k, neg_a))), signature[:32])
+
+
+def b64url_bytes(text: str) -> bytes:
+    """Buffer.from(text, "base64url") for text of the base64url alphabet: a dangling sixth bit group is ignored."""
+    return b64url_decode(text)
+
+
+def b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def node_base64(text: str) -> bytes:
+    """Buffer.from(text, "base64"): either alphabet, other characters skipped, stops at the first "=", a dangling
+    sixth bit group ignored."""
+    kept = []
+    for ch in text:
+        if ch == "=":
+            break
+        if ch.isascii() and (ch.isalnum() or ch in "+/-_"):
+            kept.append({"-": "+", "_": "/"}.get(ch, ch))
+    body = "".join(kept)
+    if len(body) % 4 == 1:
+        body = body[:-1]
+    return base64.b64decode(body + "=" * (-len(body) % 4))
+
+
+def sha256(data: bytes) -> bytes:
+    return hashlib.sha256(data).digest()
+
+
+_P256_P = 0xFFFFFFFF00000001000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFF
+
+
+_P256_A = _P256_P - 3
+
+
+_P256_B = 0x5AC635D8AA3A93E7B3EBBD55769886BC651D06B0CC53B0F63BCE3C3E27D2604B
+
+
+_P256_N = 0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551
+
+
+_P256_GX = 0x6B17D1F2E12C4247F8BCE6E563A440F277037D812DEB33A0F4A13945D898C296
+
+
+_P256_GY = 0x4FE342E2FE1A7F9B8EE7EB4A7C0F9E162BCE33576B315ECECBB6406837BF51F5
+
+
+def is_valid_p256_key(raw: bytes) -> bool:
+    """SEC 1 §3.2.2 for an uncompressed point: 0x04 ‖ X ‖ Y, X and Y below p, on y² = x³ − 3x + b. The cofactor is 1."""
+    if len(raw) != 65 or raw[0] != 0x04:
+        return False
+    x = int.from_bytes(raw[1:33], "big")
+    y = int.from_bytes(raw[33:], "big")
+    if x >= _P256_P or y >= _P256_P:
+        return False
+    return (y * y - (x * x * x + _P256_A * x + _P256_B)) % _P256_P == 0
+
+
+def _jacobian_double(p: Tuple[int, int, int]) -> Tuple[int, int, int]:
+    x, y, z = p
+    if y == 0 or z == 0:
+        return (0, 1, 0)
+    ysq = y * y % _P256_P
+    s = 4 * x * ysq % _P256_P
+    zsq = z * z % _P256_P
+    m = 3 * (x - zsq) * (x + zsq) % _P256_P  # a = −3
+    nx = (m * m - 2 * s) % _P256_P
+    ny = (m * (s - nx) - 8 * ysq * ysq) % _P256_P
+    nz = 2 * y * z % _P256_P
+    return (nx, ny, nz)
+
+
+def _jacobian_add(p: Tuple[int, int, int], q: Tuple[int, int, int]) -> Tuple[int, int, int]:
+    if p[2] == 0:
+        return q
+    if q[2] == 0:
+        return p
+    z1z1 = p[2] * p[2] % _P256_P
+    z2z2 = q[2] * q[2] % _P256_P
+    u1 = p[0] * z2z2 % _P256_P
+    u2 = q[0] * z1z1 % _P256_P
+    s1 = p[1] * q[2] * z2z2 % _P256_P
+    s2 = q[1] * p[2] * z1z1 % _P256_P
+    if u1 == u2:
+        return _jacobian_double(p) if s1 == s2 else (0, 1, 0)
+    h = (u2 - u1) % _P256_P
+    r = (s2 - s1) % _P256_P
+    hh = h * h % _P256_P
+    hhh = h * hh % _P256_P
+    v = u1 * hh % _P256_P
+    nx = (r * r - hhh - 2 * v) % _P256_P
+    ny = (r * (v - nx) - s1 * hhh) % _P256_P
+    nz = h * p[2] * q[2] % _P256_P
+    return (nx, ny, nz)
+
+
+def _shamir(u1: int, u2: int, q: Tuple[int, int]) -> Optional[Tuple[int, int]]:
+    """u1·G + u2·Q in affine form, or None at infinity."""
+    g = (_P256_GX, _P256_GY, 1)
+    qj = (q[0], q[1], 1)
+    both = _jacobian_add(g, qj)
+    out = (0, 1, 0)
+    for bit in range(max(u1.bit_length(), u2.bit_length()) - 1, -1, -1):
+        out = _jacobian_double(out)
+        a, b = (u1 >> bit) & 1, (u2 >> bit) & 1
+        if a and b:
+            out = _jacobian_add(out, both)
+        elif a:
+            out = _jacobian_add(out, g)
+        elif b:
+            out = _jacobian_add(out, qj)
+    if out[2] == 0:
+        return None
+    zinv = pow(out[2], -1, _P256_P)
+    return (out[0] * zinv * zinv % _P256_P, out[1] * zinv * zinv * zinv % _P256_P)
+
+
+def _der_integer(data: bytes, at: int) -> Tuple[Optional[int], int]:
+    if at + 2 > len(data) or data[at] != 0x02:
+        return None, at
+    length = data[at + 1]
+    start = at + 2
+    if length == 0 or length > 33 or start + length > len(data):
+        return None, at
+    body = data[start:start + length]
+    if body[0] & 0x80:
+        return None, at  # negative
+    if length > 1 and body[0] == 0 and not body[1] & 0x80:
+        return None, at  # not minimal
+    return int.from_bytes(body, "big"), start + length
+
+
+def _der_signature(signature: bytes) -> Optional[Tuple[int, int]]:
+    """An ASN.1 DER Ecdsa-Sig-Value (RFC 3279 §2.2.3), strictly: one SEQUENCE of two minimal positive INTEGERs."""
+    if len(signature) < 8 or signature[0] != 0x30:
+        return None
+    if signature[1] & 0x80:
+        return None  # a P-256 signature fits a short-form length
+    if signature[1] != len(signature) - 2:
+        return None
+    r, at = _der_integer(signature, 2)
+    if r is None:
+        return None
+    s, at = _der_integer(signature, at)
+    if s is None or at != len(signature):
+        return None
+    return r, s
+
+
+def es256_verify(x: bytes, y: bytes, message: bytes, signature: bytes) -> bool:
+    """ECDSA P-256 with SHA-256 over `message`, the signature in DER (FIPS 186-5 §6.4.2). False, never an exception."""
+    if not is_valid_p256_key(b"\x04" + x + y):
+        return False
+    parsed = _der_signature(signature)
+    if parsed is None:
+        return False
+    r, s = parsed
+    if not (1 <= r < _P256_N and 1 <= s < _P256_N):
+        return False
+    e = int.from_bytes(sha256(message), "big")
+    w = pow(s, -1, _P256_N)
+    point = _shamir(e * w % _P256_N, r * w % _P256_N, (int.from_bytes(x, "big"), int.from_bytes(y, "big")))
+    return point is not None and point[0] % _P256_N == r
+
+
+def b64url_decode(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))