keyflint-verify 1.1.0__tar.gz

keyflint_verify-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KeyFlint Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keyflint_verify-1.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: keyflint-verify
+Version: 1.1.0
+Summary: Zero-dependency offline verifier and MCP tool gating for KeyFlint Ed25519 license tokens
+Author: ArceeDev
+License-Expression: MIT
+Project-URL: Homepage, https://keyflint.dev/
+Project-URL: Source, https://github.com/ArceeDev/keyflint/tree/main/sdks/python-verify
+Project-URL: Issues, https://github.com/ArceeDev/keyflint/issues
+Keywords: license,licensing,ed25519,offline,keyflint,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: fast
+Requires-Dist: cryptography>=43.0.0; extra == "fast"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: cryptography>=43.0.0; extra == "test"
+Requires-Dist: mcp>=1.2; extra == "test"
+Dynamic: license-file
+
+# keyflint-verify
+
+Offline verifier for KeyFlint license tokens (`LIC-<TIER>-<PAYLOAD>.<SIGNATURE>`). It is pure Python standard library: no C compiler and no dependencies. If `cryptography` is installed it is used automatically (`pip install keyflint-verify[fast]`).
+
+```python
+from keyflint_verify import verify_license
+r = verify_license("LIC-PRO-eyJ...", PUBLIC_KEY_HEX, machine_id="ws-node-01")
+if not r: raise SystemExit(r.error)  # e.g. ERR_LICENSE_EXPIRED
+print(r.payload["tier"], r.payload["features"])
+```
+
+## MCP servers
+
+```python
+from keyflint_verify.mcp import KeyFlint
+kf = KeyFlint()  # KEYFLINT_LICENSE, KEYFLINT_PUBLIC_KEYS, KEYFLINT_URL, KEYFLINT_CHECKOUT_URL
+
+@mcp.tool()
+@kf.require_license(features=["core"])  # offline only
+def search(query: str) -> str: ...
+
+@mcp.tool()
+@kf.metered(credits=5)                  # offline check + POST /api/v1/quota/deduct
+async def summarize(url: str) -> str: ...
+```
+
+- Works with sync and async tools and with MCPServer / FastMCP (`mcp` v1 and v2). Put the KeyFlint decorator **below** `@mcp.tool()`. The signature is preserved, so the tool schema does not change.
+- `@metered` charges **before** the tool runs. It sends an automatic `Idempotency-Key` and reuses it on its single network retry, so a retry never charges twice.
+- Failures raise `LicenseError`, a subclass of the SDK's standard MCP error. The client receives a JSON-RPC error: `-32060` invalid license, `-32061` feature not in plan, `-32062` credits exhausted (HTTP 402, with `checkout_url` in `data`), `-32063` gateway error (`-32042` is reserved by MCP for URL elicitation). Each message states the cause, whether credits were charged, and the next step.
+- For node-locked licenses the machine id is computed automatically with the same algorithm as the gateway (`keyflint_verify.fingerprint`).
+
+## Key rotation
+
+`public_keys` can be a single hex key, a list of historical keys, or a `{kid: hex}` mapping. Tokens without `kid` (every token issued by KeyFlint v1.0) are tried against all the keys. With a `{kid: hex}` mapping, a token with a signed `kid` is checked only against that key (`ERR_UNKNOWN_KID` if absent); strings and lists are tried key by key. `KEYFLINT_PUBLIC_KEYS` accepts the gateway's published keyring and mixed lists (`oldhex,k2=newhex`). To contain a leaked key, remove it from the ring. `r.key_id` tells you which key verified the token.
+
+## Guarantees
+
+- `validate_offline` is a byte-for-byte copy of the gateway's `offline_validator.py`. A test fails if the two drift apart.
+- Tokens whose signed `issued_at` is more than 300 s ahead of the local clock fail with `ERR_CLOCK_BEFORE_ISSUANCE` (rolled-back clock). Expiry has no extra tolerance. Offline checks cannot stop a determined clock rollback; use short expirations with online renewal when that matters.
+- The same 47 conformance vectors as the npm `keyflint-verify` package, run on both the OpenSSL path and the pure RFC 8032 path.
+
+```bash
+python -m unittest discover -s tests   # from sdks/python-verify, with src on PYTHONPATH or after pip install -e .
+```

keyflint_verify-1.1.0/README.md

@@ -0,0 +1,44 @@
+# keyflint-verify
+
+Offline verifier for KeyFlint license tokens (`LIC-<TIER>-<PAYLOAD>.<SIGNATURE>`). It is pure Python standard library: no C compiler and no dependencies. If `cryptography` is installed it is used automatically (`pip install keyflint-verify[fast]`).
+
+```python
+from keyflint_verify import verify_license
+r = verify_license("LIC-PRO-eyJ...", PUBLIC_KEY_HEX, machine_id="ws-node-01")
+if not r: raise SystemExit(r.error)  # e.g. ERR_LICENSE_EXPIRED
+print(r.payload["tier"], r.payload["features"])
+```
+
+## MCP servers
+
+```python
+from keyflint_verify.mcp import KeyFlint
+kf = KeyFlint()  # KEYFLINT_LICENSE, KEYFLINT_PUBLIC_KEYS, KEYFLINT_URL, KEYFLINT_CHECKOUT_URL
+
+@mcp.tool()
+@kf.require_license(features=["core"])  # offline only
+def search(query: str) -> str: ...
+
+@mcp.tool()
+@kf.metered(credits=5)                  # offline check + POST /api/v1/quota/deduct
+async def summarize(url: str) -> str: ...
+```
+
+- Works with sync and async tools and with MCPServer / FastMCP (`mcp` v1 and v2). Put the KeyFlint decorator **below** `@mcp.tool()`. The signature is preserved, so the tool schema does not change.
+- `@metered` charges **before** the tool runs. It sends an automatic `Idempotency-Key` and reuses it on its single network retry, so a retry never charges twice.
+- Failures raise `LicenseError`, a subclass of the SDK's standard MCP error. The client receives a JSON-RPC error: `-32060` invalid license, `-32061` feature not in plan, `-32062` credits exhausted (HTTP 402, with `checkout_url` in `data`), `-32063` gateway error (`-32042` is reserved by MCP for URL elicitation). Each message states the cause, whether credits were charged, and the next step.
+- For node-locked licenses the machine id is computed automatically with the same algorithm as the gateway (`keyflint_verify.fingerprint`).
+
+## Key rotation
+
+`public_keys` can be a single hex key, a list of historical keys, or a `{kid: hex}` mapping. Tokens without `kid` (every token issued by KeyFlint v1.0) are tried against all the keys. With a `{kid: hex}` mapping, a token with a signed `kid` is checked only against that key (`ERR_UNKNOWN_KID` if absent); strings and lists are tried key by key. `KEYFLINT_PUBLIC_KEYS` accepts the gateway's published keyring and mixed lists (`oldhex,k2=newhex`). To contain a leaked key, remove it from the ring. `r.key_id` tells you which key verified the token.
+
+## Guarantees
+
+- `validate_offline` is a byte-for-byte copy of the gateway's `offline_validator.py`. A test fails if the two drift apart.
+- Tokens whose signed `issued_at` is more than 300 s ahead of the local clock fail with `ERR_CLOCK_BEFORE_ISSUANCE` (rolled-back clock). Expiry has no extra tolerance. Offline checks cannot stop a determined clock rollback; use short expirations with online renewal when that matters.
+- The same 47 conformance vectors as the npm `keyflint-verify` package, run on both the OpenSSL path and the pure RFC 8032 path.
+
+```bash
+python -m unittest discover -s tests   # from sdks/python-verify, with src on PYTHONPATH or after pip install -e .
+```

keyflint_verify-1.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "keyflint-verify"
+version = "1.1.0"
+description = "Zero-dependency offline verifier and MCP tool gating for KeyFlint Ed25519 license tokens"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "ArceeDev" }]
+keywords = ["license", "licensing", "ed25519", "offline", "keyflint", "mcp"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Security :: Cryptography",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+fast = ["cryptography>=43.0.0"]
+mcp = ["mcp>=1.2"]
+test = ["pytest>=8", "cryptography>=43.0.0", "mcp>=1.2"]
+
+[project.urls]
+Homepage = "https://keyflint.dev/"
+Source = "https://github.com/ArceeDev/keyflint/tree/main/sdks/python-verify"
+Issues = "https://github.com/ArceeDev/keyflint/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+keyflint_verify = ["py.typed"]

keyflint_verify-1.1.0/setup.cfg

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

keyflint_verify-1.1.0/src/keyflint_verify/__init__.py

@@ -0,0 +1,119 @@
+"""keyflint-verify: offline verification of KeyFlint license tokens.
+
+``validate_offline`` is a verbatim copy of the KeyFlint gateway's
+``app/infrastructure/security/offline_validator.py``. ``verify_license`` adds
+key-ring support (single key, list of historical keys, or ``{kid: hex}``),
+matching the ``keyflint-verify`` npm package.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional, Sequence, Union
+
+from ._validator import validate_offline
+
+__all__ = ["validate_offline", "verify_license", "decode_payload", "VerifyResult", "PublicKeys"]
+__version__ = "1.1.0"
+
+PublicKeys = Union[str, Sequence[str], Mapping[str, str]]
+
+
+@dataclass(frozen=True)
+class VerifyResult:
+    valid: bool
+    payload: Optional[dict[str, Any]]
+    error: Optional[str]
+    key_id: Optional[str] = None
+
+    def __bool__(self) -> bool:
+        return self.valid
+
+
+def _normalize_keys(keys: PublicKeys) -> Optional[list[tuple[Optional[str], str]]]:
+    if isinstance(keys, str):
+        pairs: list[tuple[Optional[str], Any]] = [(None, keys)]
+    elif isinstance(keys, Mapping):
+        pairs = [(str(k), v) for k, v in keys.items()]
+    elif isinstance(keys, Sequence):
+        pairs = [(str(i), v) for i, v in enumerate(keys)]
+    else:
+        return None
+    if not pairs:
+        return None
+    out: list[tuple[Optional[str], str]] = []
+    for kid, hex_key in pairs:
+        try:
+            if not isinstance(hex_key, str) or len(bytes.fromhex(hex_key)) != 32:
+                return None
+        except ValueError:
+            return None
+        out.append((kid, hex_key))
+    return out
+
+
+def decode_payload(token: str) -> Optional[dict[str, Any]]:
+    """Returns the token payload WITHOUT verifying it (display / routing only)."""
+    try:
+        payload_b64 = token.split(".")[0].split("-", 2)[2]
+        raw = base64.urlsafe_b64decode(payload_b64 + "=" * (-len(payload_b64) % 4))
+        payload = json.loads(raw)
+        return payload if isinstance(payload, dict) else None
+    except Exception:
+        return None
+
+
+_PRE_SIGNATURE_ERRORS = frozenset({
+    "ERR_EMPTY_TOKEN", "ERR_INVALID_TOKEN_FORMAT", "ERR_INVALID_TOKEN_PREFIX", "ERR_INVALID_PUBLIC_KEY",
+    "ERR_MALFORMED_BASE64_PAYLOAD", "ERR_MALFORMED_BASE64_SIGNATURE", "ERR_INVALID_SIGNATURE_LENGTH",
+})
+
+
+def _peek_kid(token: str) -> Optional[str]:
+    kid = (decode_payload(token) or {}).get("kid")
+    return kid if isinstance(kid, str) else None
+
+
+def verify_license(
+    token: str,
+    public_keys: PublicKeys,
+    *,
+    now: Optional[int] = None,
+    machine_id: Optional[str] = None,
+    domain: Optional[str] = None,
+    force_pure_python: bool = False,
+) -> VerifyResult:
+    """Verifies a token against one or more trusted public keys.
+
+    Tokens without ``kid`` (all KeyFlint v1.0 tokens) are tried against every key.
+    With a ``{kid: hex}`` mapping, a token with a signed ``kid`` is checked only against
+    that key (``ERR_UNKNOWN_KID`` when the mapping has no such kid). A single key or a
+    list has no names, so every key is tried.
+    """
+    ring = _normalize_keys(public_keys)
+    if ring is None:
+        # Structural token errors take precedence, exactly like validate_offline.
+        _, _, err = validate_offline(token, "", now, machine_id, domain)
+        return VerifyResult(False, None, err)
+
+    kid = _peek_kid(token) if isinstance(token, str) else None
+    if kid is not None and isinstance(public_keys, Mapping):
+        matching = [e for e in ring if e[0] == kid]
+        if not matching:
+            # Report structural errors first (same order as the npm package), then the kid.
+            _, _, err = validate_offline(token, ring[0][1], now, machine_id, domain,
+                                         force_pure_python=force_pure_python)
+            return VerifyResult(False, None, err if err in _PRE_SIGNATURE_ERRORS else "ERR_UNKNOWN_KID")
+        ring = matching
+
+    last = VerifyResult(False, None, "ERR_SIGNATURE_TAMPERED")
+    for key_id, hex_key in ring:
+        ok, payload, err = validate_offline(
+            token, hex_key, now, machine_id, domain, force_pure_python=force_pure_python
+        )
+        if err == "ERR_SIGNATURE_TAMPERED":
+            continue
+        return VerifyResult(ok, payload, err, key_id if ok else None)
+    return last

keyflint_verify-1.1.0/src/keyflint_verify/_validator.py

@@ -0,0 +1,369 @@
+"""KeyFlint Standalone Offline Validator.
+
+Zero external dependencies. Can be packaged and distributed independently.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import re
+import time
+from typing import Any, Optional
+
+# RFC 8032 Curve Parameters for standalone zero-dependency verification
+_Q = 2**255 - 19
+_L = 2**252 + 27742317777372353535851937790883648493
+_D = (-121665 * pow(121666, _Q - 2, _Q)) % _Q
+_D2 = (2 * _D) % _Q
+_I = pow(2, (_Q - 1) // 4, _Q)
+_BY = (4 * pow(5, _Q - 2, _Q)) % _Q
+
+_ExtPt = tuple[int, int, int, int]
+_EXT_IDENTITY: _ExtPt = (0, 1, 1, 0)
+
+
+def _xrec(y: int) -> int:
+    u = (y * y - 1) % _Q
+    v = (_D * y * y + 1) % _Q
+    xx = (u * pow(v, _Q - 2, _Q)) % _Q
+    x = pow(xx, (_Q + 3) // 8, _Q)
+    if (x * x - xx) % _Q != 0:
+        x = (x * _I) % _Q
+    if (x * x - xx) % _Q != 0:
+        raise ValueError("Invalid Ed25519 point: no square root")
+    if x & 1:
+        x = _Q - x
+    return x
+
+
+_BX = _xrec(_BY)
+_BP_EXT: _ExtPt = (_BX, _BY, 1, (_BX * _BY) % _Q)
+
+
+def _ext_add(p1: _ExtPt, p2: _ExtPt) -> _ExtPt:
+    x1, y1, z1, t1 = p1
+    x2, y2, z2, t2 = p2
+    a = ((y1 - x1) * (y2 - x2)) % _Q
+    b = ((y1 + x1) * (y2 + x2)) % _Q
+    c = (t1 * _D2 * t2) % _Q
+    d = (2 * z1 * z2) % _Q
+    e = (b - a) % _Q
+    f = (d - c) % _Q
+    g = (d + c) % _Q
+    h = (b + a) % _Q
+    return ((e * f) % _Q, (g * h) % _Q, (f * g) % _Q, (e * h) % _Q)
+
+
+def _ext_dbl(p: _ExtPt) -> _ExtPt:
+    x1, y1, z1, _ = p
+    a = (x1 * x1) % _Q
+    b = (y1 * y1) % _Q
+    c = (2 * z1 * z1) % _Q
+    h = (a + b) % _Q
+    xy = x1 + y1
+    e = (h - xy * xy) % _Q
+    g = (a - b) % _Q
+    f = (c + g) % _Q
+    return ((e * f) % _Q, (g * h) % _Q, (f * g) % _Q, (e * h) % _Q)
+
+
+def _smult_ext(pt: _ExtPt, e: int) -> _ExtPt:
+    res = _EXT_IDENTITY
+    addend = pt
+    scalar = e
+    while scalar > 0:
+        if scalar & 1:
+            res = _ext_add(res, addend)
+        addend = _ext_dbl(addend)
+        scalar >>= 1
+    return res
+
+
+def _dpt_ext(s: bytes) -> _ExtPt:
+    if len(s) != 32:
+        raise ValueError("Invalid point length")
+    raw = int.from_bytes(s, "little")
+    y = raw & ((1 << 255) - 1)
+    sign_bit = (raw >> 255) & 1
+    if y >= _Q:
+        raise ValueError("Non-canonical y >= p")
+    x = _xrec(y)
+    if x == 0 and sign_bit == 1:
+        raise ValueError("Invalid point: x=0 with sign bit 1")
+    if (x & 1) != sign_bit:
+        x = _Q - x
+    if (-x * x + y * y - 1 - _D * x * x * y * y) % _Q != 0:
+        raise ValueError("Point off Ed25519 curve")
+    return (x, y, 1, (x * y) % _Q)
+
+
+def _pure_ed25519_verify(sig: bytes, m: bytes, pk: bytes) -> bool:
+    if len(sig) != 64 or len(pk) != 32:
+        return False
+    s_val = int.from_bytes(sig[32:], "little")
+    if s_val >= _L:
+        return False
+    try:
+        r_ext = _dpt_ext(sig[:32])
+        a_ext = _dpt_ext(pk)
+    except ValueError:
+        return False
+    h_val = int.from_bytes(hashlib.sha512(sig[:32] + pk + m).digest(), "little") % _L
+    x1, y1, z1, _ = _smult_ext(_BP_EXT, s_val)
+    x2, y2, z2, _ = _ext_add(r_ext, _smult_ext(a_ext, h_val))
+    return (x1 * z2 - x2 * z1) % _Q == 0 and (y1 * z2 - y2 * z1) % _Q == 0
+
+
+# Tolerated difference between the issuer's clock and the local clock for `issued_at`.
+CLOCK_SKEW_LEEWAY_SECONDS = 300
+
+_B64URL_PATTERN = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def _b64url_decode(s: str) -> bytes:
+    """Decode unpadded URL-safe base64 string to bytes with strict character set validation."""
+    if not isinstance(s, str) or not _B64URL_PATTERN.match(s):
+        raise ValueError("Invalid Base64URL string: contains illegal characters or whitespace.")
+    pad_len = (4 - len(s) % 4) % 4
+    return base64.b64decode((s + "=" * pad_len).encode("ascii"), altchars=b"-_", validate=True)
+
+
+def _normalize_domain_host(raw: Optional[str], *, allow_wildcard: bool = False) -> Optional[str]:
+    """Normalizes a hostname (optional :port, trailing FQDN dot, and IDNA punycode) using stdlib only."""
+    if not raw or not isinstance(raw, str):
+        return None
+    s = raw.strip()
+    if not s or any(ch in s for ch in ("/", "\\", "@", "?", "#", " ", "\t", "\r", "\n")):
+        return None
+
+    wildcard = False
+    if s.startswith("*."):
+        if not allow_wildcard:
+            return None
+        wildcard = True
+        s = s[2:]
+    elif "*" in s:
+        return None
+
+    if ":" in s:
+        host_part, port_part = s.rsplit(":", 1)
+        if not port_part.isdigit():
+            return None
+        port_num = int(port_part)
+        if port_num < 1 or port_num > 65535:
+            return None
+        s = host_part
+
+    s = s.rstrip(".")
+    if not s or s.startswith(".") or ".." in s:
+        return None
+
+    labels = s.split(".")
+    if wildcard and len(labels) < 2:
+        return None
+
+    ascii_labels: list[str] = []
+    for label in labels:
+        if not label:
+            return None
+        try:
+            enc = label.encode("idna").decode("ascii").lower()
+        except UnicodeError:
+            return None
+        if (
+            not enc
+            or any(not (ch.isalnum() or ch == "-") for ch in enc)
+            or enc.startswith("-")
+            or enc.endswith("-")
+        ):
+            return None
+        ascii_labels.append(enc)
+
+    normalized = ".".join(ascii_labels)
+    return f"*.{normalized}" if wildcard else normalized
+
+
+def _matches_allowed_domains(allowed: list[str], domain: Optional[str]) -> bool:
+    if not allowed:
+        return True
+    candidate = _normalize_domain_host(domain, allow_wildcard=False)
+    if not candidate:
+        return False
+    for pattern in allowed:
+        if not isinstance(pattern, str):
+            continue
+        pat = _normalize_domain_host(pattern, allow_wildcard=True)
+        if not pat:
+            continue
+        if pat == candidate:
+            return True
+        if pat.startswith("*."):
+            suffix = pat[2:]
+            if suffix and "." in suffix and (
+                candidate == suffix or candidate.endswith("." + suffix)
+            ):
+                return True
+    return False
+
+
+def validate_offline(
+    license_token: Optional[str] = None,
+    public_key_hex: str = "",
+    current_time: Optional[int] = None,
+    expected_machine_id: Optional[str] = None,
+    expected_domain: Optional[str] = None,
+    *,
+    license_key: Optional[str] = None,
+    force_pure_python: bool = False,
+) -> tuple[bool, Optional[dict[str, Any]], Optional[str]]:
+    """Validates a KeyFlint license token offline.
+
+    Parameters:
+        license_token: Complete token string (LIC-<TIER>-<PAYLOAD>.<SIG>)
+        public_key_hex: 64-character hex string of 32-byte Ed25519 public key
+        current_time: Optional Unix epoch seconds for expiration test (defaults to time.time())
+        expected_machine_id: Optional local machine ID to enforce node-locking
+        expected_domain: Optional caller hostname/domain to enforce allowed_domains lock
+        license_key: Alias for license_token
+        force_pure_python: Force pure-stdlib RFC 8032 curve math even if cryptography is installed
+
+    Returns:
+        (is_valid: bool, payload: Optional[dict], error_code: Optional[str])
+    """
+    token = license_token if license_token is not None else license_key
+
+    # 1. Structure validation
+    if not token or not isinstance(token, str):
+        return False, None, "ERR_EMPTY_TOKEN"
+
+    if "." not in token:
+        return False, None, "ERR_INVALID_TOKEN_FORMAT"
+
+    parts = token.split(".")
+    if len(parts) != 2:
+        return False, None, "ERR_INVALID_TOKEN_FORMAT"
+
+    header_part, sig_b64 = parts
+    if not header_part.startswith("LIC-"):
+        return False, None, "ERR_INVALID_TOKEN_PREFIX"
+
+    subparts = header_part.split("-", 2)
+    if len(subparts) != 3:
+        return False, None, "ERR_INVALID_TOKEN_FORMAT"
+
+    _, token_tier, payload_b64 = subparts
+    if not token_tier or not payload_b64:
+        return False, None, "ERR_INVALID_TOKEN_FORMAT"
+
+    # 2. Public key decode
+    try:
+        if not isinstance(public_key_hex, str):
+            return False, None, "ERR_INVALID_PUBLIC_KEY"
+        pub_bytes = bytes.fromhex(public_key_hex.strip())
+        if len(pub_bytes) != 32:
+            return False, None, "ERR_INVALID_PUBLIC_KEY"
+    except Exception:
+        return False, None, "ERR_INVALID_PUBLIC_KEY"
+
+    # 3. Base64url decodings
+    try:
+        payload_bytes = _b64url_decode(payload_b64)
+    except Exception:
+        return False, None, "ERR_MALFORMED_BASE64_PAYLOAD"
+
+    try:
+        sig_bytes = _b64url_decode(sig_b64)
+        if len(sig_bytes) != 64:
+            return False, None, "ERR_INVALID_SIGNATURE_LENGTH"
+    except Exception:
+        return False, None, "ERR_MALFORMED_BASE64_SIGNATURE"
+
+    # 4. Cryptographic signature verification (OpenSSL fast path with pure-python RFC 8032 fallback)
+    sig_valid = False
+    if force_pure_python:
+        sig_valid = _pure_ed25519_verify(sig_bytes, payload_bytes, pub_bytes)
+    else:
+        try:
+            from cryptography.hazmat.primitives.asymmetric import ed25519
+
+            c_pk = ed25519.Ed25519PublicKey.from_public_bytes(pub_bytes)
+            c_pk.verify(sig_bytes, payload_bytes)
+            sig_valid = True
+        except ImportError:
+            sig_valid = _pure_ed25519_verify(sig_bytes, payload_bytes, pub_bytes)
+        except Exception:
+            sig_valid = False
+
+    if not sig_valid:
+        return False, None, "ERR_SIGNATURE_TAMPERED"
+
+    # 5. JSON payload deserialization
+    try:
+        payload = json.loads(payload_bytes.decode("utf-8"))
+    except Exception:
+        return False, None, "ERR_MALFORMED_JSON_PAYLOAD"
+
+    if not isinstance(payload, dict):
+        return False, None, "ERR_INVALID_PAYLOAD_STRUCTURE"
+
+    # 6. Tier consistency
+    tier_val = payload.get("tier")
+    if not isinstance(tier_val, str) or tier_val.lower() != token_tier.lower():
+        return False, payload, "ERR_TIER_MISMATCH"
+
+    # 7. Expiration boundary check
+    now = current_time if current_time is not None else int(time.time())
+    expires_at = payload.get("expires_at")
+    if expires_at is not None:
+        if isinstance(expires_at, bool) or not isinstance(expires_at, (int, float)):
+            return False, payload, "ERR_MALFORMED_EXPIRATION"
+        if now > expires_at:
+            return False, payload, "ERR_LICENSE_EXPIRED"
+
+    # 7b. Clock sanity: a local clock earlier than the signed issuance time (beyond the
+    # tolerated skew) means the clock was rolled back or is badly wrong.
+    issued_at = payload.get("issued_at")
+    if isinstance(issued_at, (int, float)) and not isinstance(issued_at, bool):
+        if now + CLOCK_SKEW_LEEWAY_SECONDS < issued_at:
+            return False, payload, "ERR_CLOCK_BEFORE_ISSUANCE"
+
+    # 8. Node lock / Machine ID enforcement
+    locked_machine = payload.get("machine_id")
+    if locked_machine is not None and not isinstance(locked_machine, str):
+        return False, payload, "ERR_INVALID_PAYLOAD_STRUCTURE"
+    if expected_machine_id is not None and not isinstance(expected_machine_id, str):
+        return False, payload, "ERR_NODE_LOCK_VIOLATION"
+
+    norm_locked = (
+        locked_machine.strip().lower()
+        if isinstance(locked_machine, str) and locked_machine.strip()
+        else None
+    )
+    norm_expected_hw = (
+        expected_machine_id.strip().lower()
+        if isinstance(expected_machine_id, str) and expected_machine_id.strip()
+        else None
+    )
+
+    if norm_locked is not None:
+        if norm_expected_hw is None or norm_locked != norm_expected_hw:
+            return False, payload, "ERR_NODE_LOCK_VIOLATION"
+    elif norm_expected_hw is not None:
+        return False, payload, "ERR_NODE_LOCK_VIOLATION"
+
+    # 9. Domain lock enforcement
+    if expected_domain is not None and not isinstance(expected_domain, str):
+        return False, payload, "ERR_DOMAIN_LOCK_VIOLATION"
+
+    allowed_domains = payload.get("allowed_domains")
+    if allowed_domains is not None:
+        if not isinstance(allowed_domains, list) or any(
+            not isinstance(d, str) for d in allowed_domains
+        ):
+            return False, payload, "ERR_INVALID_PAYLOAD_STRUCTURE"
+        if allowed_domains and not _matches_allowed_domains(allowed_domains, expected_domain):
+            return False, payload, "ERR_DOMAIN_LOCK_VIOLATION"
+
+    return True, payload, None