x403 0.1.0__tar.gz

x403-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv
+dist
+__pycache__
+*.egg-info

x403-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: x403
+Version: 0.1.0
+Summary: x403: a signed risk decision before money moves. Objects, canonical JSON, ES256 signing and verifying, the HTTP binding, a client and FastAPI middleware.
+Project-URL: Homepage, https://kredit.sh/x403
+Project-URL: Repository, https://github.com/kreditsh/x403
+Project-URL: Spec, https://github.com/kreditsh/x403/blob/main/spec/x403.md
+Author-email: kredit <hello@kredit.sh>
+License-Expression: Apache-2.0
+Keywords: agentic payments,ap2,kredit,mpp,risk,x401,x402,x403
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Provides-Extra: client
+Requires-Dist: httpx>=0.27; extra == 'client'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Requires-Dist: httpx>=0.27; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# x403
+
+The x403 protocol for Python: the objects, RFC 8785 canonical JSON, ES256 signing and verifying, the HTTP binding, a sync and an async client for any authority, and a FastAPI gate. One dependency, `cryptography`. Python 3.10+.
+
+```
+pip install x403            # objects, canonical JSON, signing, verifying
+pip install "x403[client]"  # plus the HTTP client (httpx)
+pip install "x403[fastapi]" # plus the FastAPI gate
+```
+
+## Ask before you execute
+
+```python
+from x403 import X403
+
+x403 = X403(authority="https://api.kredit.sh", api_key=os.environ["KREDIT_API_KEY"])
+
+decision = x403.decide(
+    direction="inbound",
+    policy_id="shop-checkout-v1",
+    payment={"type": "payment", "amount": "189.00", "currency": "USD", "rail": "card", "executor": {"id": "shop.example"}},
+    actor={"agent": {"status": "asserted", "id": "did:key:z6Mk..."}},
+    evidence=[{"type": "kredit.passport", "ref": passport_hash, "inline": passport}],
+    budget_ms=150,
+)
+
+if decision["decision"] == "allow":
+    ...  # within decision["constraints"]
+else:
+    ...  # decision["http_status"], decision["reasons"], decision.get("escalation")
+```
+
+## Verify offline
+
+```python
+result = x403.verify(decision)   # keys fetched once from authority.json
+assert result, result.reason
+```
+
+Or without a client, against keys you already hold:
+
+```python
+from x403 import verify_decision
+ok = verify_decision(decision, jwks)
+```
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+from x403 import AsyncX403
+from x403.middleware.fastapi import X403Gate, install, post_receipt
+
+app = FastAPI()
+install(app)
+authority = AsyncX403("https://api.kredit.sh", api_key=os.environ["KREDIT_API_KEY"])
+
+gate = X403Gate(
+    authority,
+    payment=lambda request: {"type": "payment", "amount": "189.00", "currency": "USD", "rail": "card", "executor": {"id": "shop.example"}},
+    policy_id="shop-checkout-v1",
+    budget_ms=150,
+)
+
+@app.post("/checkout")
+async def checkout(decision: dict = Depends(gate)):
+    auth = await charge(decision["constraints"])
+    await post_receipt(authority, decision, executed=True, execution={"rail": "card", "ref": auth.id},
+                       executor={"id": "did:web:shop.example", "kid": kid}, private_jwk=private_jwk)
+    return {"ok": True}
+```
+
+On allow the route receives the decision. On anything else the gate answers with the decision's `http_status`, the decision as the body and `X403-Decision` on the response. If the authority cannot be reached it fails closed with an executor-signed `authority_timeout` decision.
+
+## Sign your side
+
+```python
+from x403 import generate_key, sign_receipt, decision_hash
+
+pair = generate_key()   # publish pair.public_jwk at /.well-known/x403/jwks.json
+receipt = sign_receipt({"decision_ref": d["id"], "decision_hash": decision_hash(d), "executed": True,
+                        "executor": {"id": "did:web:shop.example", "kid": pair.kid}}, pair.private_jwk)
+```
+
+## Status codes
+
+`status_for(decision)` implements section 6.3 of the spec. The decision already carries `http_status`; use the function to pin the table in your own tests.
+
+Apache-2.0. Spec and registry: https://github.com/kreditsh/x403

x403-0.1.0/README.md

@@ -0,0 +1,89 @@
+# x403
+
+The x403 protocol for Python: the objects, RFC 8785 canonical JSON, ES256 signing and verifying, the HTTP binding, a sync and an async client for any authority, and a FastAPI gate. One dependency, `cryptography`. Python 3.10+.
+
+```
+pip install x403            # objects, canonical JSON, signing, verifying
+pip install "x403[client]"  # plus the HTTP client (httpx)
+pip install "x403[fastapi]" # plus the FastAPI gate
+```
+
+## Ask before you execute
+
+```python
+from x403 import X403
+
+x403 = X403(authority="https://api.kredit.sh", api_key=os.environ["KREDIT_API_KEY"])
+
+decision = x403.decide(
+    direction="inbound",
+    policy_id="shop-checkout-v1",
+    payment={"type": "payment", "amount": "189.00", "currency": "USD", "rail": "card", "executor": {"id": "shop.example"}},
+    actor={"agent": {"status": "asserted", "id": "did:key:z6Mk..."}},
+    evidence=[{"type": "kredit.passport", "ref": passport_hash, "inline": passport}],
+    budget_ms=150,
+)
+
+if decision["decision"] == "allow":
+    ...  # within decision["constraints"]
+else:
+    ...  # decision["http_status"], decision["reasons"], decision.get("escalation")
+```
+
+## Verify offline
+
+```python
+result = x403.verify(decision)   # keys fetched once from authority.json
+assert result, result.reason
+```
+
+Or without a client, against keys you already hold:
+
+```python
+from x403 import verify_decision
+ok = verify_decision(decision, jwks)
+```
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+from x403 import AsyncX403
+from x403.middleware.fastapi import X403Gate, install, post_receipt
+
+app = FastAPI()
+install(app)
+authority = AsyncX403("https://api.kredit.sh", api_key=os.environ["KREDIT_API_KEY"])
+
+gate = X403Gate(
+    authority,
+    payment=lambda request: {"type": "payment", "amount": "189.00", "currency": "USD", "rail": "card", "executor": {"id": "shop.example"}},
+    policy_id="shop-checkout-v1",
+    budget_ms=150,
+)
+
+@app.post("/checkout")
+async def checkout(decision: dict = Depends(gate)):
+    auth = await charge(decision["constraints"])
+    await post_receipt(authority, decision, executed=True, execution={"rail": "card", "ref": auth.id},
+                       executor={"id": "did:web:shop.example", "kid": kid}, private_jwk=private_jwk)
+    return {"ok": True}
+```
+
+On allow the route receives the decision. On anything else the gate answers with the decision's `http_status`, the decision as the body and `X403-Decision` on the response. If the authority cannot be reached it fails closed with an executor-signed `authority_timeout` decision.
+
+## Sign your side
+
+```python
+from x403 import generate_key, sign_receipt, decision_hash
+
+pair = generate_key()   # publish pair.public_jwk at /.well-known/x403/jwks.json
+receipt = sign_receipt({"decision_ref": d["id"], "decision_hash": decision_hash(d), "executed": True,
+                        "executor": {"id": "did:web:shop.example", "kid": pair.kid}}, pair.private_jwk)
+```
+
+## Status codes
+
+`status_for(decision)` implements section 6.3 of the spec. The decision already carries `http_status`; use the function to pin the table in your own tests.
+
+Apache-2.0. Spec and registry: https://github.com/kreditsh/x403

x403-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "x403"
+version = "0.1.0"
+description = "x403: a signed risk decision before money moves. Objects, canonical JSON, ES256 signing and verifying, the HTTP binding, a client and FastAPI middleware."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "kredit", email = "hello@kredit.sh" }]
+keywords = ["x403", "x402", "x401", "agentic payments", "risk", "ap2", "mpp", "kredit"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security :: Cryptography",
+]
+dependencies = ["cryptography>=42"]
+
+[project.optional-dependencies]
+client = ["httpx>=0.27"]
+fastapi = ["fastapi>=0.110", "httpx>=0.27"]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "build>=1.2", "twine>=5"]
+
+[project.urls]
+Homepage = "https://kredit.sh/x403"
+Repository = "https://github.com/kreditsh/x403"
+Spec = "https://github.com/kreditsh/x403/blob/main/spec/x403.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/x403"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/x403", "README.md", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

x403-0.1.0/src/x403/__init__.py

@@ -0,0 +1,46 @@
+"""x403: a signed risk decision before money moves."""
+
+from .client import AsyncX403, X403, X403Error, build_query
+from .headers import (
+    AUTH_SCHEME,
+    HEADER_DECISION,
+    HEADER_PRESENTATION,
+    HEADER_REQUIRED,
+    HEADER_RISK_DECISION,
+    authorization_risk,
+    decode,
+    encode,
+    parse_authorization_risk,
+    parse_www_authenticate,
+    www_authenticate,
+)
+from .jcs import canonicalize, hash_object, hash_string
+from .jws import (
+    KeyPair,
+    VerifyResult,
+    decision_hash,
+    generate_key,
+    sign,
+    sign_outcome,
+    sign_query,
+    sign_receipt,
+    thumbprint,
+    verify,
+    verify_decision,
+    verify_receipt,
+)
+from .registry import CODES, GROUPS, NORMATIVE_STATUSES, REGISTRY, check_of, effect_of, entry_of, escalation_of, group_of, status_for
+from .types import VERSION
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncX403", "X403", "X403Error", "build_query",
+    "AUTH_SCHEME", "HEADER_DECISION", "HEADER_PRESENTATION", "HEADER_REQUIRED", "HEADER_RISK_DECISION",
+    "authorization_risk", "decode", "encode", "parse_authorization_risk", "parse_www_authenticate", "www_authenticate",
+    "canonicalize", "hash_object", "hash_string",
+    "KeyPair", "VerifyResult", "decision_hash", "generate_key", "sign", "sign_outcome", "sign_query", "sign_receipt",
+    "thumbprint", "verify", "verify_decision", "verify_receipt",
+    "CODES", "GROUPS", "NORMATIVE_STATUSES", "REGISTRY", "check_of", "effect_of", "entry_of", "escalation_of", "group_of", "status_for",
+    "VERSION", "__version__",
+]

x403-0.1.0/src/x403/client.py

@@ -0,0 +1,166 @@
+"""The authority API client: the six calls of spec section 7, sync and async, and
+offline verification against the authority's published keys."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .headers import decode, encode
+from .jws import VerifyResult, verify_decision
+from .types import VERSION, Authority, Decision, JWKS, Outcome, Receipt, RiskQuery
+
+try:
+    import httpx
+except ImportError:  # pragma: no cover - the client extra is optional
+    httpx = None  # type: ignore[assignment]
+
+
+class X403Error(Exception):
+    def __init__(self, status: int, detail: Any):
+        self.status = status
+        self.detail = detail
+        super().__init__(f"{status}: {detail if isinstance(detail, str) else detail!r}")
+
+
+def build_query(**fields: Any) -> RiskQuery:
+    """Fill scheme and version so a caller passes only what varies."""
+    query: dict[str, Any] = {"scheme": "x403", "version": VERSION}
+    query.update({k: v for k, v in fields.items() if v is not None})
+    return query  # type: ignore[return-value]
+
+
+def _need_httpx() -> None:
+    if httpx is None:
+        raise RuntimeError("install x403[client] for the HTTP client")
+
+
+def _unpack(res: Any) -> Any:
+    try:
+        payload = res.json() if res.content else {}
+    except ValueError:
+        payload = res.text
+    if res.status_code >= 400:
+        detail = payload.get("detail") if isinstance(payload, dict) and "detail" in payload else payload
+        raise X403Error(res.status_code, detail)
+    return payload
+
+
+class _Base:
+    encode = staticmethod(encode)
+    decode = staticmethod(decode)
+
+    def __init__(self, authority: str, api_key: str | None = None, headers: dict[str, str] | None = None, timeout: float = 10.0):
+        self.authority = authority.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.extra = dict(headers or {})
+        self._jwks: JWKS | None = None
+        self._authority: Authority | None = None
+
+    def _headers(self, body: bool) -> dict[str, str]:
+        out = {"accept": "application/json", **self.extra}
+        if body:
+            out["content-type"] = "application/json"
+        if self.api_key:
+            out["authorization"] = f"Bearer {self.api_key}"
+        return out
+
+    def _jwks_path(self) -> str:
+        url = (self._authority or {}).get("jwks_url") or f"{self.authority}/.well-known/x403/jwks.json"
+        return url[len(self.authority) :] if url.startswith(self.authority) else url
+
+    def reset(self) -> None:
+        """Forget cached keys, e.g. after a verify fails on an unknown kid."""
+        self._jwks = None
+        self._authority = None
+
+
+class X403(_Base):
+    def __init__(self, authority: str, api_key: str | None = None, headers: dict[str, str] | None = None, timeout: float = 10.0, client: Any = None):
+        super().__init__(authority, api_key, headers, timeout)
+        _need_httpx()
+        self._client = client or httpx.Client(timeout=timeout)
+
+    def _call(self, method: str, path: str, body: Any = None) -> Any:
+        url = path if path.startswith("http") else f"{self.authority}{path}"
+        res = self._client.request(method, url, json=body, headers=self._headers(body is not None))
+        return _unpack(res)
+
+    def decide(self, **fields: Any) -> Decision:
+        return self._call("POST", "/x403/decide", build_query(**fields))
+
+    def preflight(self, **fields: Any) -> Decision:
+        """The same question with mode preflight: decide now, pay later citing the id."""
+        return self._call("POST", "/x403/decide", build_query(**{**fields, "mode": "preflight"}))
+
+    def receipt(self, receipt: Receipt) -> Receipt:
+        return self._call("POST", "/x403/receipts", receipt)
+
+    def outcome(self, outcome: Outcome) -> Outcome:
+        return self._call("POST", "/x403/outcomes", outcome)
+
+    def get(self, decision_id: str) -> Decision:
+        return self._call("GET", f"/x403/decisions/{decision_id}")
+
+    def authority_document(self) -> Authority:
+        if self._authority is None:
+            self._authority = self._call("GET", "/.well-known/x403/authority.json")
+        return self._authority  # type: ignore[return-value]
+
+    def jwks(self) -> JWKS:
+        """The authority's keys, fetched once from the address its document names."""
+        if self._jwks is None:
+            try:
+                self.authority_document()
+            except X403Error:
+                pass  # without a document the conventional path still answers
+            self._jwks = self._call("GET", self._jwks_path())
+        return self._jwks  # type: ignore[return-value]
+
+    def verify(self, decision: Decision) -> VerifyResult:
+        """Offline verification of a decision against the cached keys."""
+        return verify_decision(decision, self.jwks())
+
+
+class AsyncX403(_Base):
+    def __init__(self, authority: str, api_key: str | None = None, headers: dict[str, str] | None = None, timeout: float = 10.0, client: Any = None):
+        super().__init__(authority, api_key, headers, timeout)
+        _need_httpx()
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+
+    async def _call(self, method: str, path: str, body: Any = None) -> Any:
+        url = path if path.startswith("http") else f"{self.authority}{path}"
+        res = await self._client.request(method, url, json=body, headers=self._headers(body is not None))
+        return _unpack(res)
+
+    async def decide(self, **fields: Any) -> Decision:
+        return await self._call("POST", "/x403/decide", build_query(**fields))
+
+    async def preflight(self, **fields: Any) -> Decision:
+        return await self._call("POST", "/x403/decide", build_query(**{**fields, "mode": "preflight"}))
+
+    async def receipt(self, receipt: Receipt) -> Receipt:
+        return await self._call("POST", "/x403/receipts", receipt)
+
+    async def outcome(self, outcome: Outcome) -> Outcome:
+        return await self._call("POST", "/x403/outcomes", outcome)
+
+    async def get(self, decision_id: str) -> Decision:
+        return await self._call("GET", f"/x403/decisions/{decision_id}")
+
+    async def authority_document(self) -> Authority:
+        if self._authority is None:
+            self._authority = await self._call("GET", "/.well-known/x403/authority.json")
+        return self._authority  # type: ignore[return-value]
+
+    async def jwks(self) -> JWKS:
+        if self._jwks is None:
+            try:
+                await self.authority_document()
+            except X403Error:
+                pass
+            self._jwks = await self._call("GET", self._jwks_path())
+        return self._jwks  # type: ignore[return-value]
+
+    async def verify(self, decision: Decision) -> VerifyResult:
+        return verify_decision(decision, await self.jwks())

x403-0.1.0/src/x403/headers.py

@@ -0,0 +1,70 @@
+"""The HTTP binding: X403-* headers carry base64url JSON without padding, and the
+auth-scheme binding carries the same objects under WWW-Authenticate: Risk."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from .jws import base64url, from_base64url
+
+HEADER_REQUIRED = "X403-Required"
+HEADER_PRESENTATION = "X403-Presentation"
+HEADER_DECISION = "X403-Decision"
+HEADER_RISK_DECISION = "Risk-Decision"
+AUTH_SCHEME = "Risk"
+
+
+def encode(value: Any) -> str:
+    return base64url(json.dumps(value, separators=(",", ":"), ensure_ascii=False))
+
+
+def decode(text: str) -> Any:
+    return json.loads(from_base64url(text).decode("utf-8"))
+
+
+def _quote(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def www_authenticate(policy: str, realm: str | None = None, request: str | None = None, expires: str | None = None) -> str:
+    """`WWW-Authenticate: Risk policy="...", realm="...", request="...", expires="..."`"""
+    parts = [f"policy={_quote(policy)}"]
+    if realm:
+        parts.append(f"realm={_quote(realm)}")
+    if request:
+        parts.append(f"request={_quote(request)}")
+    if expires:
+        parts.append(f"expires={_quote(expires)}")
+    return f"{AUTH_SCHEME} " + ", ".join(parts)
+
+
+_PARAM = re.compile(r'(\w+)=(?:"((?:[^"\\]|\\.)*)"|([^,\s]+))')
+
+
+def parse_www_authenticate(header: str) -> dict[str, str] | None:
+    m = re.match(r"^\s*Risk\s+(.*)$", header, re.S)
+    if not m:
+        return None
+    out: dict[str, str] = {}
+    for name, quoted, bare in _PARAM.findall(m.group(1)):
+        out[name] = re.sub(r"\\(.)", r"\1", quoted if quoted else bare)
+    return out if "policy" in out else None
+
+
+def authorization_risk(presentation: dict[str, Any]) -> str:
+    """`Authorization: Risk <base64url presentation>`"""
+    return f"{AUTH_SCHEME} {encode(presentation)}"
+
+
+def parse_authorization_risk(header: str | None) -> dict[str, Any] | None:
+    if not header:
+        return None
+    m = re.match(r"^\s*Risk\s+([A-Za-z0-9_-]+)\s*$", header)
+    if not m:
+        return None
+    try:
+        return decode(m.group(1))
+    except (ValueError, UnicodeDecodeError):
+        return None

x403-0.1.0/src/x403/jcs.py

@@ -0,0 +1,103 @@
+"""RFC 8785 (JSON Canonicalization Scheme). Every hash and every signature in x403 is
+over this form, so two implementations that agree here agree everywhere. Numbers print
+the way ES6 Number.prototype.toString prints them, which is the form the RFC fixes."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from typing import Any
+
+
+def _es6_number(x: float) -> str:
+    if math.isnan(x) or math.isinf(x):
+        raise ValueError("JCS: non-finite number")
+    if x == 0:
+        return "0"
+    sign = "-" if x < 0 else ""
+    x = abs(x)
+    # repr gives the shortest digits that round-trip, which is the digit string ES6 uses;
+    # only the placement of the point and the exponent form differ, handled below.
+    text = repr(x)
+    if "e" in text:
+        mantissa, exponent = text.split("e")
+        e = int(exponent)
+    else:
+        mantissa, e = text, 0
+    if "." in mantissa:
+        whole, frac = mantissa.split(".")
+    else:
+        whole, frac = mantissa, ""
+    digits = whole + frac
+    point = e - len(frac)  # value = int(digits) * 10 ** point
+    digits = digits.lstrip("0")
+    while digits.endswith("0"):
+        digits = digits[:-1]
+        point += 1
+    k = len(digits)
+    n = point + k  # value = 0.digits * 10 ** n
+    if k <= n <= 21:
+        return sign + digits + "0" * (n - k)
+    if 0 < n <= 21:
+        return sign + digits[:n] + "." + digits[n:]
+    if -6 < n <= 0:
+        return sign + "0." + "0" * (-n) + digits
+    exp = n - 1
+    exp_text = ("+" if exp >= 0 else "-") + str(abs(exp))
+    if k == 1:
+        return sign + digits + "e" + exp_text
+    return sign + digits[0] + "." + digits[1:] + "e" + exp_text
+
+
+def _key(name: str) -> bytes:
+    # The RFC sorts by UTF-16 code units; comparing UTF-16BE bytes is the same order.
+    return name.encode("utf-16-be")
+
+
+def _serialize(value: Any) -> str:
+    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)
+        return _es6_number(float(value))
+    if isinstance(value, float):
+        return _es6_number(value)
+    if isinstance(value, str):
+        # json.dumps escapes only what the RFC escapes, with lowercase hex.
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(_serialize(v) for v in value) + "]"
+    if isinstance(value, dict):
+        items = sorted(((str(k), v) for k, v in value.items()), key=lambda kv: _key(kv[0]))
+        return "{" + ",".join(json.dumps(k, ensure_ascii=False) + ":" + _serialize(v) for k, v in items) + "}"
+    raise TypeError(f"JCS: cannot serialize {type(value).__name__}")
+
+
+def canonicalize(value: Any) -> str:
+    """The canonical JSON text of a value."""
+    return _serialize(value)
+
+
+def canonical_bytes(value: Any) -> bytes:
+    return canonicalize(value).encode("utf-8")
+
+
+def sha256_hex(data: bytes | str) -> str:
+    raw = data.encode("utf-8") if isinstance(data, str) else data
+    return hashlib.sha256(raw).hexdigest()
+
+
+def hash_object(value: Any) -> str:
+    """`sha256:<hex>` of the canonical form of an object."""
+    return "sha256:" + sha256_hex(canonical_bytes(value))
+
+
+def hash_string(text: str) -> str:
+    """`sha256:<hex>` of a string as given: a JWT, an SD-JWT, any opaque artifact."""
+    return "sha256:" + sha256_hex(text)