iricity-frontier-shared 0.5.0__py3-none-any.whl

frontier_shared/__init__.py

@@ -0,0 +1,128 @@
+"""Frontier State Protocol primitives, Python implementation.
+
+Byte-for-byte compatible with the JavaScript reference (`@iricity/frontier-shared`),
+proven by the shared conformance vectors in ``frontier_shared/vectors``.
+"""
+
+from .base58 import base58_decode, base58_encode, multibase_decode_base58btc, multibase_encode_base58btc
+from .canonical import MAX_DEPTH, canonical_json, format_number
+from .credential import (
+    AUTHORIZATION_CREDENTIAL_TYPE,
+    AUTHORIZATION_VOCAB,
+    CREDENTIAL_CONTEXT_V2,
+    CREDENTIAL_SUBJECT_FIELDS,
+    CRYPTOSUITE,
+    DATA_INTEGRITY_PROOF,
+    PROOF_PURPOSE,
+    credential_hash_data,
+    credential_subject_from_authorization,
+    issue_authorization_credential,
+    verify_authorization_credential,
+    verify_credential,
+)
+from .envelope import (
+    ENVELOPE_DOMAIN_TAG,
+    ENVELOPE_VERSION,
+    TIMESTAMP_PATTERN,
+    create_envelope,
+    envelope_hash,
+    envelope_header,
+    envelope_id_from_hash,
+    envelope_signing_input,
+    is_timestamp,
+    verify_envelope,
+)
+from .hashing import HASH_PREFIX, hash_bytes, hash_payload, hash_record, hash_text, is_hash_ref, sha256_hex, sha256_hex_bytes
+from .keys import (
+    ED25519_MULTICODEC_PREFIX,
+    KeyPair,
+    decode_signature,
+    did_from_public_key_bytes,
+    encode_signature,
+    fingerprint_did,
+    is_did_key,
+    is_valid_signature_text,
+    public_key_bytes_from_did,
+    public_key_multibase_from_did,
+    resolve_signer,
+    sign_bytes,
+    verify_bytes,
+)
+from .receipt import (
+    RECEIPT_DOMAIN_TAG,
+    RECEIPT_SIGNATURE_ALGORITHMS,
+    RECEIPT_VERSION,
+    compute_receipt_hash,
+    create_receipt_record,
+    derive_receipt_id,
+    receipt_core,
+    receipt_signing_input,
+    verify_receipt_chain,
+    verify_receipt_record,
+)
+
+__version__ = "0.5.0"
+
+__all__ = [
+    "__version__",
+    "issue_authorization_credential",
+    "verify_credential",
+    "verify_authorization_credential",
+    "credential_hash_data",
+    "credential_subject_from_authorization",
+    "CREDENTIAL_CONTEXT_V2",
+    "AUTHORIZATION_VOCAB",
+    "AUTHORIZATION_CREDENTIAL_TYPE",
+    "CREDENTIAL_SUBJECT_FIELDS",
+    "CRYPTOSUITE",
+    "DATA_INTEGRITY_PROOF",
+    "PROOF_PURPOSE",
+    "canonical_json",
+    "format_number",
+    "MAX_DEPTH",
+    "hash_text",
+    "is_valid_signature_text",
+    "is_timestamp",
+    "TIMESTAMP_PATTERN",
+    "envelope_id_from_hash",
+    "derive_receipt_id",
+    "HASH_PREFIX",
+    "sha256_hex",
+    "sha256_hex_bytes",
+    "hash_payload",
+    "hash_bytes",
+    "hash_record",
+    "is_hash_ref",
+    "base58_encode",
+    "base58_decode",
+    "multibase_encode_base58btc",
+    "multibase_decode_base58btc",
+    "ED25519_MULTICODEC_PREFIX",
+    "KeyPair",
+    "resolve_signer",
+    "did_from_public_key_bytes",
+    "public_key_bytes_from_did",
+    "public_key_multibase_from_did",
+    "is_did_key",
+    "fingerprint_did",
+    "sign_bytes",
+    "verify_bytes",
+    "encode_signature",
+    "decode_signature",
+    "ENVELOPE_VERSION",
+    "ENVELOPE_DOMAIN_TAG",
+    "create_envelope",
+    "verify_envelope",
+    "envelope_header",
+    "envelope_hash",
+    "envelope_signing_input",
+    "RECEIPT_VERSION",
+    "RECEIPT_DOMAIN_TAG",
+    "RECEIPT_SIGNATURE_ALGORITHMS",
+    "create_receipt_record",
+    "verify_receipt_record",
+    "verify_receipt_chain",
+    "receipt_core",
+    "receipt_signing_input",
+    "compute_receipt_hash",
+]

frontier_shared/base58.py

@@ -0,0 +1,47 @@
+"""Base58btc (Bitcoin alphabet), as used by multibase prefix 'z'."""
+
+from __future__ import annotations
+
+__all__ = ["base58_encode", "base58_decode", "multibase_encode_base58btc", "multibase_decode_base58btc"]
+
+ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+_INDEX = {char: index for index, char in enumerate(ALPHABET)}
+
+
+def base58_encode(data: bytes) -> str:
+    data = bytes(data)
+    if not data:
+        return ""
+    value = int.from_bytes(data, "big")
+    encoded = ""
+    while value > 0:
+        value, remainder = divmod(value, 58)
+        encoded = ALPHABET[remainder] + encoded
+    leading = len(data) - len(data.lstrip(b"\x00"))
+    return "1" * leading + encoded
+
+
+def base58_decode(text: str) -> bytes:
+    if not isinstance(text, str):
+        raise TypeError("base58_decode expects a string")
+    if text == "":
+        return b""
+    value = 0
+    for char in text:
+        digit = _INDEX.get(char)
+        if digit is None:
+            raise ValueError(f"base58_decode: invalid character {char!r}")
+        value = value * 58 + digit
+    body = b"" if value == 0 else value.to_bytes((value.bit_length() + 7) // 8, "big")
+    leading = len(text) - len(text.lstrip("1"))
+    return b"\x00" * leading + body
+
+
+def multibase_encode_base58btc(data: bytes) -> str:
+    return "z" + base58_encode(data)
+
+
+def multibase_decode_base58btc(text: str) -> bytes:
+    if not isinstance(text, str) or not text.startswith("z"):
+        raise ValueError('expected a multibase base58btc string starting with "z"')
+    return base58_decode(text[1:])

frontier_shared/canonical.py

@@ -0,0 +1,131 @@
+"""Canonical JSON per RFC 8785 (JSON Canonicalization Scheme).
+
+Rules implemented:
+- object members sorted by the UTF-16 code units of their names
+- numbers serialized with the ECMAScript Number-to-string algorithm; every number
+  is a double, so integers beyond 2**53 are rounded exactly as JavaScript rounds them
+- strings escaped exactly as ECMAScript JSON.stringify escapes them
+- no insignificant whitespace
+
+Rejected, because a canonical form must be unambiguous and a verifier must not be
+crashable: non-finite floats, non-string keys, non-JSON values, nesting deeper than
+MAX_DEPTH.
+"""
+
+from __future__ import annotations
+
+import math
+from decimal import Decimal
+from typing import Any
+
+__all__ = ["canonical_json", "format_number", "MAX_DEPTH"]
+
+MAX_DEPTH = 256
+_MAX_SAFE_INTEGER = 2**53
+
+
+def format_number(value: float | int) -> str:
+    """ECMAScript Number::toString for a finite number (ECMA-262 section 6.1.6.1.20)."""
+    if isinstance(value, bool):
+        raise TypeError("booleans are not numbers")
+    if isinstance(value, int):
+        if abs(value) < _MAX_SAFE_INTEGER:
+            return str(value)
+        # JSON has only doubles: a larger integer literal is the nearest double.
+        value = float(value)
+    if not isinstance(value, float):
+        raise TypeError(f"not a number: {type(value).__name__}")
+    if math.isnan(value) or math.isinf(value):
+        raise ValueError("canonical_json: non-finite number")
+    if value == 0.0:
+        return "0"
+
+    sign = "-" if value < 0 else ""
+    # repr() gives the shortest digit string that round-trips, the same digits
+    # ECMAScript chooses. Decimal exposes them as (digits, exponent).
+    tup = Decimal(repr(abs(value))).as_tuple()
+    digits = list(tup.digits)
+    exponent = int(tup.exponent)
+    while len(digits) > 1 and digits[-1] == 0:
+        digits.pop()
+        exponent += 1
+    k = len(digits)
+    n = k + exponent  # value = 0.d1d2...dk x 10^n
+    s = "".join(str(d) for d in digits)
+
+    if k <= n <= 21:
+        body = s + "0" * (n - k)
+    elif 0 < n <= 21:
+        body = s[:n] + "." + s[n:]
+    elif -6 < n <= 0:
+        body = "0." + "0" * (-n) + s
+    else:
+        e = n - 1
+        exp = ("+" if e >= 0 else "-") + str(abs(e))
+        body = (s if k == 1 else s[0] + "." + s[1:]) + "e" + exp
+    return sign + body
+
+
+_SHORT_ESCAPES = {
+    '"': '\\"',
+    "\\": "\\\\",
+    "\b": "\\b",
+    "\f": "\\f",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+}
+
+
+def _escape_string(text: str) -> str:
+    out = ['"']
+    for ch in text:
+        esc = _SHORT_ESCAPES.get(ch)
+        if esc is not None:
+            out.append(esc)
+            continue
+        code = ord(ch)
+        if code < 0x20 or 0xD800 <= code <= 0xDFFF:
+            out.append("\\u%04x" % code)
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def _key_order(name: Any) -> bytes:
+    # Lexicographic order of UTF-16BE bytes equals UTF-16 code unit order.
+    if not isinstance(name, str):
+        raise TypeError("canonical_json: object keys must be strings")
+    return name.encode("utf-16-be", "surrogatepass")
+
+
+def _serialize(value: Any, path: str, depth: int) -> str:
+    if depth > MAX_DEPTH:
+        raise TypeError(f"canonical_json: nesting deeper than {MAX_DEPTH} at {path}")
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, str):
+        return _escape_string(value)
+    if isinstance(value, (int, float)):
+        try:
+            return format_number(value)
+        except ValueError as error:
+            raise ValueError(f"{error} at {path}") from None
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(_serialize(item, f"{path}[{index}]", depth + 1) for index, item in enumerate(value)) + "]"
+    if isinstance(value, dict):
+        members = []
+        for key in sorted(value.keys(), key=_key_order):
+            members.append(_escape_string(key) + ":" + _serialize(value[key], f"{path}.{key}", depth + 1))
+        return "{" + ",".join(members) + "}"
+    raise TypeError(f"canonical_json: unsupported value {type(value).__name__} at {path}")
+
+
+def canonical_json(value: Any) -> str:
+    """Return the RFC 8785 canonical JSON text of a JSON-compatible Python value."""
+    return _serialize(value, "$", 0)

frontier_shared/conformance.py

@@ -0,0 +1,267 @@
+"""Conformance runner: prove this implementation reproduces the published vectors byte for byte.
+
+Usage::
+
+    frontier-shared-conformance                 # bundled vectors
+    frontier-shared-conformance path/to/vectors.json
+    python -m frontier_shared.conformance
+
+An implementation conforms only when every suite passes and none is skipped.
+Exit status 0 when conformant, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from .base58 import base58_decode, base58_encode
+from .canonical import canonical_json
+from .envelope import create_envelope, verify_envelope
+from .hashing import hash_payload
+from .keys import KeyPair, did_from_public_key_bytes, public_key_bytes_from_did
+from .receipt import create_receipt_record, verify_receipt_record
+from .credential import credential_hash_data, issue_authorization_credential, verify_authorization_credential, verify_credential
+
+__all__ = ["VECTORS_VERSION", "SUITES", "load_vectors", "bundled_vectors_path", "bundled_lock_path", "run_conformance", "format_report", "main"]
+
+VECTORS_VERSION = "3"
+SUITES = ["canonical_json", "hash_payload", "base58btc", "did_key", "ed25519", "envelope", "receipt", "credential", "rejections"]
+
+
+def bundled_vectors_path() -> Path:
+    return Path(str(resources.files("frontier_shared") / "vectors" / f"v{VECTORS_VERSION}" / "vectors.json"))
+
+
+def bundled_lock_path() -> Path:
+    return Path(str(resources.files("frontier_shared") / "vectors" / f"v{VECTORS_VERSION}" / "vectors.lock.json"))
+
+
+def load_vectors(path: str | Path | None = None) -> dict:
+    target = Path(path) if path else bundled_vectors_path()
+    with open(target, "r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def _signer(v: dict) -> dict:
+    return {"private_key_seed_hex": v["signer_seed_hex"]}
+
+
+def run_conformance(vectors: dict | None = None) -> dict:
+    if vectors is None:
+        vectors = load_vectors()
+    results: list[dict] = []
+
+    def record(suite: str, case_id: str, status: str, detail: str | None = None) -> None:
+        entry = {"suite": suite, "id": case_id, "status": status}
+        if detail:
+            entry["detail"] = detail
+        results.append(entry)
+
+    def check(suite: str, case_id: str, fn) -> None:
+        try:
+            outcome = fn()
+            if outcome is True:
+                record(suite, case_id, "passed")
+            else:
+                record(suite, case_id, "failed", outcome if isinstance(outcome, str) else "mismatch")
+        except Exception as error:  # noqa: BLE001 - every failure is a finding
+            record(suite, case_id, "failed", f"{type(error).__name__}: {error}")
+
+    def suite(name: str) -> list:
+        cases = vectors.get(name)
+        if not isinstance(cases, list) or not cases:
+            record(name, "*", "failed", f'vectors file has no "{name}" suite')
+            return []
+        return cases
+
+    for v in suite("canonical_json"):
+        def canonical_case(v=v):
+            actual = canonical_json(v["input"])
+            if actual != v["expected_canonical"]:
+                return f"expected {v['expected_canonical']} got {actual}"
+            digest = hash_payload(v["input"])
+            return True if digest == v["expected_hash"] else f"hash mismatch: {digest}"
+        check("canonical_json", v["id"], canonical_case)
+
+    for v in suite("hash_payload"):
+        def hash_case(v=v):
+            actual = hash_payload(v["input"])
+            return True if actual == v["expected_hash"] else f"expected {v['expected_hash']} got {actual}"
+        check("hash_payload", v["id"], hash_case)
+
+    for v in suite("base58btc"):
+        def base58_case(v=v):
+            encoded = base58_encode(bytes.fromhex(v["input_hex"]))
+            if encoded != v["expected"]:
+                return f"encode: expected {v['expected']} got {encoded}"
+            decoded = base58_decode(v["expected"]).hex()
+            return True if decoded == v["input_hex"] else f"decode: expected {v['input_hex']} got {decoded}"
+        check("base58btc", v.get("id") or v["input_hex"] or "empty", base58_case)
+
+    for v in suite("did_key"):
+        def did_case(v=v):
+            did = did_from_public_key_bytes(bytes.fromhex(v["public_key_hex"]))
+            if did != v["expected_did"]:
+                return f"encode: expected {v['expected_did']} got {did}"
+            raw = public_key_bytes_from_did(v["expected_did"]).hex()
+            return True if raw == v["public_key_hex"] else f"decode: expected {v['public_key_hex']} got {raw}"
+        check("did_key", v["expected_did"], did_case)
+
+    for v in suite("ed25519"):
+        def ed25519_case(v=v):
+            pair = KeyPair.from_seed(v["seed_hex"])
+            if pair.public_key_bytes.hex() != v["public_key_hex"]:
+                return "public key mismatch"
+            actual = pair.sign(bytes.fromhex(v["message_hex"])).hex()
+            return True if actual == v["expected_signature_hex"] else f"signature mismatch: {actual}"
+        check("ed25519", v["id"], ed25519_case)
+
+    for v in suite("envelope"):
+        def envelope_case(v=v):
+            detached = bool(v.get("detached"))
+            env = create_envelope(
+                payload=v["payload"],
+                payload_type=v["payload_type"],
+                signer=_signer(v),
+                created_at=v["created_at"],
+                previous_envelope_hash=v["previous_envelope_hash"],
+                detached=detached,
+            )
+            e = v["expected"]
+            for field in ("signer", "payload_hash", "envelope_hash", "envelope_id"):
+                if env[field] != e[field]:
+                    return f"{field}: expected {e[field]} got {env[field]}"
+            if env["signature"]["value"] != e["signature_value"]:
+                return f"signature: {env['signature']['value']}"
+            if detached and "payload" in env:
+                return "detached envelope must not carry a payload"
+            verification = verify_envelope(env, payload=v["payload"]) if detached else verify_envelope(env)
+            if not verification["verified"]:
+                return "self-verification failed: " + "; ".join(verification["errors"])
+            if detached and not verify_envelope(env)["verified"]:
+                return "detached envelope must verify without its payload"
+            return True
+        check("envelope", v["id"], envelope_case)
+
+    for v in suite("receipt"):
+        def receipt_case(v=v):
+            if v.get("legacy"):
+                verification = verify_receipt_record(v["receipt"], record=v["record"])
+                if verification["verified"] != v["expected"]["verified"]:
+                    return f"legacy: expected verified={v['expected']['verified']} got {verification['verified']}: " + "; ".join(verification["errors"])
+                return True
+            issuer: Any = _signer(v) if v.get("signer_seed_hex") else v["issuer"]
+            receipt = create_receipt_record(record=v["record"], previous_hash=v["previous_hash"], issuer=issuer, timestamp=v["timestamp"])
+            e = v["expected"]
+            for field in ("receipt_id", "record_hash", "previous_hash", "receipt_hash", "issuer", "signature", "signature_algorithm", "verification_status"):
+                if receipt.get(field) != e.get(field):
+                    return f"{field}: expected {e.get(field)} got {receipt.get(field)}"
+            verification = verify_receipt_record(receipt, record=v["record"])
+            return True if verification["verified"] else "self-verification failed: " + "; ".join(verification["errors"])
+        check("receipt", v["id"], receipt_case)
+
+    for v in suite("credential"):
+        def credential_case(v=v):
+            if v.get("authorization_record"):
+                bound = verify_authorization_credential(v["authorization_record"], at=v["at"])
+                if bound["verified"] != v["expected"]["verified"]:
+                    return f"expected verified={v['expected']['verified']}: " + "; ".join(bound["errors"])
+                if bound["issuer"] != v["expected"]["issuer"]:
+                    return f"issuer: expected {v['expected']['issuer']} got {bound['issuer']}"
+                return True
+            credential = issue_authorization_credential(v["authorization"], _signer(v), created=v["created"], id=v.get("credential_id"))
+            e = v["expected"]
+            if credential["id"] != e["id"]:
+                return f"id: expected {e['id']} got {credential['id']}"
+            if credential["issuer"] != e["issuer"]:
+                return f"issuer: expected {e['issuer']} got {credential['issuer']}"
+            if credential["proof"]["verificationMethod"] != e["verification_method"]:
+                return f"verificationMethod: {credential['proof']['verificationMethod']}"
+            if credential["proof"]["proofValue"] != e["proof_value"]:
+                return f"proofValue: expected {e['proof_value']} got {credential['proof']['proofValue']}"
+            hash_data = credential_hash_data(credential, credential["proof"]).hex()
+            if hash_data != e["hash_data_hex"]:
+                return f"hash_data: expected {e['hash_data_hex']} got {hash_data}"
+            if canonical_json(credential["credentialSubject"]) != canonical_json(e["credential_subject"]):
+                return "credentialSubject differs"
+            verification = verify_credential(credential, at=v["at"])
+            return True if verification["verified"] else "self-verification failed: " + "; ".join(verification["errors"])
+        check("credential", v["id"], credential_case)
+
+    for v in suite("rejections"):
+        def rejection_case(v=v):
+            options = v.get("options") or {}
+            if v["kind"] == "credential":
+                kwargs = {}
+                if "at" in options:
+                    kwargs["at"] = options["at"]
+                if "expected_issuer" in options:
+                    kwargs["expected_issuer"] = options["expected_issuer"]
+                verification = verify_credential(v["object"], **kwargs)
+                return True if verification["verified"] is False else "tampered credential was accepted"
+            if v["kind"] == "authorization":
+                verification = verify_authorization_credential(v["object"], at=options.get("at"))
+                return True if verification["verified"] is False else "unbound authorization was accepted"
+            if v["kind"] == "envelope":
+                kwargs = {}
+                if "payload" in options:
+                    kwargs["payload"] = options["payload"]
+                if "expected_signer" in options:
+                    kwargs["expected_signer"] = options["expected_signer"]
+                if "allowed_payload_types" in options:
+                    kwargs["allowed_payload_types"] = options["allowed_payload_types"]
+                verification = verify_envelope(v["object"], **kwargs)
+                return True if verification["verified"] is False else "tampered envelope was accepted"
+            if v["kind"] == "receipt":
+                kwargs = {}
+                if "record" in options:
+                    kwargs["record"] = options["record"]
+                if "previous_receipt" in options:
+                    kwargs["previous_receipt"] = options["previous_receipt"]
+                if "expected_issuer" in options:
+                    kwargs["expected_issuer"] = options["expected_issuer"]
+                verification = verify_receipt_record(v["object"], **kwargs)
+                return True if verification["verified"] is False else "tampered receipt was accepted"
+            return f"unknown rejection kind {v['kind']}"
+        check("rejections", v["id"], rejection_case)
+
+    passed = sum(1 for r in results if r["status"] == "passed")
+    failed = sum(1 for r in results if r["status"] == "failed")
+    skipped = sum(1 for r in results if r["status"] == "skipped")
+    return {
+        "vectors_version": vectors.get("vectors_version"),
+        "conformant": failed == 0 and skipped == 0 and passed > 0,
+        "passed": passed,
+        "failed": failed,
+        "skipped": skipped,
+        "results": results,
+    }
+
+
+def format_report(report: dict) -> str:
+    lines = [
+        f"conformance vectors {report['vectors_version']}: {report['passed']} passed, "
+        f"{report['failed']} failed, {report['skipped']} skipped"
+    ]
+    for r in report["results"]:
+        if r["status"] != "passed":
+            detail = f": {r['detail']}" if r.get("detail") else ""
+            lines.append(f"  [{r['status']}] {r['suite']}/{r['id']}{detail}")
+    lines.append("RESULT: conformant" if report["conformant"] else "RESULT: not conformant")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    vectors = load_vectors(args[0]) if args else load_vectors()
+    report = run_conformance(vectors)
+    print(format_report(report))
+    return 0 if report["conformant"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())