keyflint-verify 1.1.0__py3-none-any.whl

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/_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

keyflint_verify/fingerprint.py

@@ -0,0 +1,34 @@
+"""Hardware Machine ID Fingerprinting for Node-Locked Licenses.
+
+Zero external dependencies. Operates deterministically across Windows, Linux, and macOS.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import platform
+import socket
+import uuid
+
+
+def compute_machine_id() -> str:
+    """Computes a deterministic, cross-platform hardware fingerprint for node locking.
+
+    Formula: sha256(hostname:cpu_info:mac_address)
+    """
+    # 1. Hostname normalization
+    hostname = socket.gethostname().strip().lower()
+
+    # 2. Resilient CPU identification
+    proc = platform.processor().strip().lower()
+    mach = platform.machine().strip().lower()
+    sys_name = platform.system().strip().lower()
+    cpu_info = f"{proc}|{mach}|{sys_name}" if proc else f"{mach}|{sys_name}"
+
+    # 3. MAC Address extraction
+    mac_node = uuid.getnode()
+    mac_address = f"{mac_node:012x}".lower()
+
+    # 4. Canonical combination and SHA-256 digest
+    raw_identifier = f"{hostname}:{cpu_info}:{mac_address}"
+    return hashlib.sha256(raw_identifier.encode("utf-8")).hexdigest()

keyflint_verify/mcp.py

@@ -0,0 +1,394 @@
+"""KeyFlint licensing for MCP servers (FastMCP, MCPServer and the low-level ``mcp`` SDK).
+
+    from keyflint_verify.mcp import KeyFlint
+
+    kf = KeyFlint()                        # reads KEYFLINT_* environment variables
+
+    @mcp.tool()
+    @kf.require_license                    # offline Ed25519 check, no network
+    def search(query: str) -> str: ...
+
+    @mcp.tool()
+    @kf.metered(credits=5)                 # offline check + POST /api/v1/quota/deduct
+    async def summarize(url: str) -> str: ...
+
+Put the KeyFlint decorator *below* ``@mcp.tool()`` so the tool sees the wrapped function.
+Both decorators work on sync and async functions and keep the original signature, so
+the generated tool schema is unchanged.
+
+Failures raise :class:`LicenseError`. When the ``mcp`` package is installed it subclasses
+the SDK's standard MCP error (``MCPError`` in v2, ``McpError`` in v1), so the client
+receives a JSON-RPC error with ``code``, ``message`` and ``data``. Without ``mcp`` it is a
+plain ``Exception``.
+
+Environment variables:
+    KEYFLINT_LICENSE        license token (LIC-...)
+    KEYFLINT_PUBLIC_KEYS    hex key, comma-separated keys, or kid=hex pairs
+    KEYFLINT_URL            gateway base URL (required for @metered)
+    KEYFLINT_MACHINE_ID     machine id for node-locked licenses (default: auto)
+    KEYFLINT_DOMAIN         caller domain for domain-locked licenses
+    KEYFLINT_CHECKOUT_URL   upgrade link shown when credits run out
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any, Callable, Mapping, Optional, Sequence, TypeVar, Union, cast
+
+from . import PublicKeys, VerifyResult, decode_payload, verify_license
+from .fingerprint import compute_machine_id
+
+__all__ = [
+    "KeyFlint",
+    "LicenseError",
+    "LICENSE_INVALID",
+    "FEATURE_NOT_ENTITLED",
+    "QUOTA_EXHAUSTED",
+    "GATEWAY_ERROR",
+]
+
+# JSON-RPC server error range (-32000..-32099), stable across SDKs. -32042 is avoided because
+# MCP itself uses it for URLElicitationRequired.
+LICENSE_INVALID = -32060
+FEATURE_NOT_ENTITLED = -32061
+QUOTA_EXHAUSTED = -32062
+GATEWAY_ERROR = -32063
+
+_LICENSE_MESSAGES = {
+    "ERR_EMPTY_TOKEN": "No KeyFlint license is configured. Set KEYFLINT_LICENSE.",
+    "ERR_SIGNATURE_TAMPERED": "This license was not issued for this server (signature check failed). "
+    "Check KEYFLINT_LICENSE and KEYFLINT_PUBLIC_KEYS.",
+    "ERR_UNKNOWN_KID": "This license was signed with a key this server does not trust. "
+    "Check KEYFLINT_PUBLIC_KEYS.",
+    "ERR_NODE_LOCK_VIOLATION": "This license is locked to another machine.",
+    "ERR_DOMAIN_LOCK_VIOLATION": "This license is not valid for this domain.",
+    "ERR_CLOCK_BEFORE_ISSUANCE": "The system clock is earlier than the license issue date. "
+    "Correct the clock and retry.",
+}
+
+
+def _license_message(error: Optional[str], payload: Optional[Mapping[str, Any]], checkout_url: Optional[str]) -> str:
+    """Plain-language reason plus the next step; this text is what MCP clients show."""
+    code = error or "ERR_LICENSE_INVALID"
+    if code == "ERR_LICENSE_EXPIRED":
+        exp = (payload or {}).get("expires_at")
+        when = time.strftime("%Y-%m-%d", time.gmtime(exp)) if isinstance(exp, (int, float)) else None
+        text = f"Your license expired on {when}." if when else "Your license has expired."
+    else:
+        text = _LICENSE_MESSAGES.get(code, f"The KeyFlint license is invalid ({code}).")
+    if checkout_url and code not in ("ERR_CLOCK_BEFORE_ISSUANCE", "ERR_UNKNOWN_KID", "ERR_SIGNATURE_TAMPERED"):
+        text += f" Get or renew a license: {checkout_url}"
+    return text
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+try:  # mcp >= 2
+    from mcp.shared.exceptions import MCPError as _MCPBase  # type: ignore[import-not-found]
+
+    _MCP_FLAVOR = 2
+except ImportError:  # pragma: no cover - depends on installed SDK
+    try:  # mcp 1.x
+        from mcp.shared.exceptions import McpError as _MCPBase  # type: ignore[import-not-found,no-redef]
+        from mcp.types import ErrorData as _ErrorData  # type: ignore[import-not-found]
+
+        _MCP_FLAVOR = 1
+    except ImportError:
+        _MCPBase = Exception  # type: ignore[misc,assignment]
+        _MCP_FLAVOR = 0
+
+
+class LicenseError(_MCPBase):  # type: ignore[misc,valid-type]
+    """Standard MCP error carrying KeyFlint details in ``data``.
+
+    ``data["reason"]`` is the KeyFlint error code (``ERR_LICENSE_EXPIRED``,
+    ``QUOTA_EXHAUSTED``, ...). ``data["checkout_url"]`` is set when an upgrade link is configured.
+    """
+
+    def __init__(self, code: int, message: str, data: Mapping[str, Any]) -> None:
+        payload = dict(data)
+        self._text = message
+        if _MCP_FLAVOR == 2:
+            super().__init__(code, message, payload)
+        elif _MCP_FLAVOR == 1:  # pragma: no cover
+            super().__init__(_ErrorData(code=code, message=message, data=payload))
+        else:
+            super().__init__(message)
+            self.code = code  # type: ignore[misc]
+            self.message = message  # type: ignore[misc]
+            self.data = payload  # type: ignore[misc]
+        self.reason: str = str(payload.get("reason", ""))
+        self.details: dict[str, Any] = payload
+
+    def __str__(self) -> str:
+        return self._text
+
+
+def _error(code: int, reason: str, message: str, **extra: Any) -> LicenseError:
+    data = {"reason": reason, **{k: v for k, v in extra.items() if v is not None}}
+    return LicenseError(code, message, data)
+
+
+def _parse_keys_env(raw: str) -> PublicKeys:
+    """Parses ``hex``, ``hex,hex`` or ``kid=hex`` entries; bare keys in a named list become ``legacy-<i>``."""
+    items = [p.strip() for p in raw.split(",") if p.strip()]
+    if any("=" in p for p in items):
+        ring: dict[str, str] = {}
+        for i, p in enumerate(items):
+            kid, _, hex_key = p.rpartition("=")
+            ring[kid.strip() or f"legacy-{i}"] = hex_key.strip()
+        return ring
+    return items[0] if len(items) == 1 else items
+
+
+class KeyFlint:
+    """Holds the license configuration and exposes the MCP decorators."""
+
+    def __init__(
+        self,
+        *,
+        license_key: Optional[str] = None,
+        public_keys: Optional[PublicKeys] = None,
+        gateway_url: Optional[str] = None,
+        machine_id: Optional[str] = "auto",
+        domain: Optional[str] = None,
+        checkout_url: Optional[str] = None,
+        timeout: float = 5.0,
+        event_type: str = "mcp_tool_call",
+    ) -> None:
+        # KEYFORGE_* (pre-rename) is accepted as a fallback for every KEYFLINT_* variable.
+        env = {**{"KEYFLINT_" + k[9:]: v for k, v in os.environ.items() if k.startswith("KEYFORGE_")}, **os.environ}
+        self.license_key = license_key or env.get("KEYFLINT_LICENSE", "")
+        keys_env = env.get("KEYFLINT_PUBLIC_KEYS") or env.get("KEYFLINT_PUBLIC_KEY", "")
+        self.public_keys: PublicKeys = public_keys if public_keys is not None else _parse_keys_env(keys_env)
+        self.gateway_url = (gateway_url or env.get("KEYFLINT_URL", "")).rstrip("/")
+        self.machine_id = env.get("KEYFLINT_MACHINE_ID", machine_id) if machine_id == "auto" else machine_id
+        self.domain = domain or env.get("KEYFLINT_DOMAIN") or None
+        self.checkout_url = checkout_url or env.get("KEYFLINT_CHECKOUT_URL") or None
+        self.timeout = timeout
+        self.event_type = event_type
+        self._cached: Optional[VerifyResult] = None
+        self._cached_until: float = 0.0
+
+    # ------------------------------------------------------------------ offline
+
+    def _resolved_machine_id(self) -> Optional[str]:
+        if self.machine_id != "auto":
+            return self.machine_id
+        payload = decode_payload(self.license_key)
+        locked = payload.get("machine_id") if isinstance(payload, dict) else None
+        return compute_machine_id() if locked else None
+
+    def check(self, features: Optional[Sequence[str]] = None) -> VerifyResult:
+        """Verifies the configured license offline (cached until expiry, re-checked every 60 s)."""
+        now = time.time()
+        if self._cached is None or now >= self._cached_until:
+            result = verify_license(
+                self.license_key,
+                self.public_keys,
+                machine_id=self._resolved_machine_id(),
+                domain=self.domain,
+            )
+            if not result.valid:
+                raise _error(
+                    LICENSE_INVALID,
+                    result.error or "ERR_LICENSE_INVALID",
+                    _license_message(result.error, result.payload, self.checkout_url),
+                    checkout_url=self.checkout_url,
+                )
+            exp = (result.payload or {}).get("expires_at")
+            ttl = 60.0 if exp is None else max(0.0, min(60.0, float(exp) - now))
+            self._cached, self._cached_until = result, now + ttl
+        result = self._cached
+        if features:
+            have = set((result.payload or {}).get("features") or [])
+            missing = [f for f in features if f not in have]
+            if missing:
+                tier = (result.payload or {}).get("tier") or "current"
+                text = f"This tool requires the feature(s) {', '.join(missing)}, which the {tier} plan does not include."
+                if self.checkout_url:
+                    text += f" Upgrade: {self.checkout_url}"
+                raise _error(
+                    FEATURE_NOT_ENTITLED,
+                    "FEATURE_NOT_ENTITLED",
+                    text,
+                    missing_features=missing,
+                    tier=(result.payload or {}).get("tier"),
+                    checkout_url=self.checkout_url,
+                )
+        return result
+
+    # ------------------------------------------------------------------- online
+
+    def deduct(
+        self,
+        credits: int = 1,
+        *,
+        idempotency_key: Optional[str] = None,
+        event_type: Optional[str] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """POST /api/v1/quota/deduct. Retries once on network errors with the same idempotency key."""
+        if not self.gateway_url:
+            raise _error(GATEWAY_ERROR, "GATEWAY_NOT_CONFIGURED", "KEYFLINT_URL is not set; metered tools need the gateway.")
+        key = idempotency_key or f"mcp-{uuid.uuid4().hex}"
+        body = {
+            "license_key": self.license_key,
+            "credits": int(credits),
+            "idempotency_key": key,
+            "event_type": event_type or self.event_type,
+        }
+        if metadata:
+            body["metadata"] = dict(metadata)
+        req = urllib.request.Request(
+            f"{self.gateway_url}/api/v1/quota/deduct",
+            data=json.dumps(body).encode("utf-8"),
+            headers={"Content-Type": "application/json", "Idempotency-Key": key, "Accept": "application/json"},
+            method="POST",
+        )
+        last_exc: Optional[Exception] = None
+        for _attempt in range(2):
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:  # noqa: S310 - configured URL
+                    data = json.loads(resp.read().decode("utf-8") or "{}")
+                    return cast("dict[str, Any]", data.get("data", data))
+            except urllib.error.HTTPError as exc:
+                raise self._http_error(exc.code, exc.read()) from None
+            except (urllib.error.URLError, TimeoutError, OSError) as exc:
+                last_exc = exc
+        raise _error(GATEWAY_ERROR, "GATEWAY_UNREACHABLE",
+                     f"Could not reach the KeyFlint license server at {self.gateway_url} ({last_exc}). "
+                     "The tool did not run.")
+
+    def refund(self, idempotency_key: str, reason: Optional[str] = None) -> bool:
+        """Best-effort POST /api/v1/quota/refund for a previous deduct. Never raises; True on success."""
+        if not self.gateway_url:
+            return False
+        body: dict[str, Any] = {"license_key": self.license_key, "idempotency_key": idempotency_key}
+        if reason:
+            body["reason"] = reason
+        req = urllib.request.Request(
+            f"{self.gateway_url}/api/v1/quota/refund",
+            data=json.dumps(body).encode("utf-8"),
+            headers={"Content-Type": "application/json", "Accept": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout):  # noqa: S310 - configured URL
+                return True
+        except Exception:
+            return False
+
+    def _http_error(self, status: int, raw: bytes) -> LicenseError:
+        try:
+            err = json.loads(raw.decode("utf-8")).get("error", {})
+        except Exception:
+            err = {}
+        code = str(err.get("code") or f"HTTP_{status}")
+        message = str(err.get("message") or f"Gateway returned HTTP {status}.")
+        if status == 402 or code == "QUOTA_EXHAUSTED":
+            det = err.get("details") or {}
+            need, left = det.get("requested_credits"), det.get("remaining_credits")
+            if isinstance(need, int) and isinstance(left, int):
+                text = f"Credits exhausted: this tool needs {need} credits and the license has {left} left."
+            else:
+                text = "Credits exhausted for this license."
+            if self.checkout_url:
+                text += f" Top up: {self.checkout_url}"
+            text += " The tool did not run and no credits were charged."
+            return _error(QUOTA_EXHAUSTED, "QUOTA_EXHAUSTED", text, status=402, checkout_url=self.checkout_url,
+                          gateway_details=err.get("details") or None)
+        if status in (401, 403, 404):
+            return _error(LICENSE_INVALID, code, f"KeyFlint license rejected: {message}", status=status,
+                          checkout_url=self.checkout_url)
+        return _error(GATEWAY_ERROR, code, f"KeyFlint gateway error: {message} The tool did not run.", status=status)
+
+    # --------------------------------------------------------------- decorators
+
+    def require_license(
+        self, fn: Optional[F] = None, *, features: Optional[Sequence[str]] = None
+    ) -> Union[F, Callable[[F], F]]:
+        """Decorator: the tool runs only with a valid license (offline check)."""
+
+        def decorate(func: F) -> F:
+            return _wrap(func, lambda: self.check(features), None)
+
+        return decorate(fn) if fn is not None else decorate
+
+    def metered(
+        self,
+        credits: int = 1,
+        *,
+        features: Optional[Sequence[str]] = None,
+        event_type: Optional[str] = None,
+        refund_on_error: bool = True,
+    ) -> Callable[[F], F]:
+        """Decorator: offline license check, then debit ``credits`` before the tool runs.
+
+        With ``refund_on_error`` (default) the credits are given back via /quota/refund if the
+        tool raises or returns an MCP error result (``isError: True``).
+        """
+        if credits <= 0:
+            raise ValueError("credits must be a positive integer")
+
+        def decorate(func: F) -> F:
+            name = event_type or f"mcp:{func.__name__}"
+
+            def charge() -> Optional[Callable[[str], Any]]:
+                key = f"mcp-{uuid.uuid4().hex}"
+                self.deduct(credits, idempotency_key=key, event_type=name)
+                return (lambda reason: self.refund(key, reason)) if refund_on_error else None
+
+            return _wrap(func, lambda: self.check(features), charge)
+
+        return decorate
+
+
+def _is_error_result(out: Any) -> bool:
+    if isinstance(out, Mapping):
+        return out.get("isError") is True
+    return getattr(out, "isError", None) is True
+
+
+def _wrap(func: F, check: Callable[[], Any], charge: Optional[Callable[[], Any]]) -> F:
+    """``charge`` debits and may return a ``refund(reason)`` callback used if the tool fails."""
+    if inspect.iscoroutinefunction(func):
+
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            check()
+            undo = await asyncio.to_thread(charge) if charge is not None else None
+            try:
+                out = await func(*args, **kwargs)
+            except BaseException:
+                if undo is not None:
+                    await asyncio.to_thread(undo, "tool_error")
+                raise
+            if undo is not None and _is_error_result(out):
+                await asyncio.to_thread(undo, "tool_error_result")
+            return out
+
+        return cast(F, async_wrapper)
+
+    @functools.wraps(func)
+    def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+        check()
+        undo = charge() if charge is not None else None
+        try:
+            out = func(*args, **kwargs)
+        except BaseException:
+            if undo is not None:
+                undo("tool_error")
+            raise
+        if undo is not None and _is_error_result(out):
+            undo("tool_error_result")
+        return out
+
+    return cast(F, sync_wrapper)

keyflint_verify-1.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+keyflint_verify/__init__.py,sha256=K6XkiZlW8PYWfxsLlfwfUwLk6VXdd1EoZiZeFGf3fZo,4349
+keyflint_verify/_validator.py,sha256=FyG1vX-becWOhwriCY1OJmbimeW_Gl7Qscp7ogjJWl8,12331
+keyflint_verify/fingerprint.py,sha256=W26cZvfdx1kvVNn2tpGeYDBupAQapjYYwx6P8LblegE,1066
+keyflint_verify/mcp.py,sha256=vpOkow6LpjWEe34Reg--NS5Rr8IIHD22StzhB0G2_Dk,17069
+keyflint_verify/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keyflint_verify-1.1.0.dist-info/licenses/LICENSE,sha256=qET3uc7Ij0PfRpNxL8KxYA8_saqGlAv7RlcpnU2P92w,1078
+keyflint_verify-1.1.0.dist-info/METADATA,sha256=SRRPTYjiZIjDxa91CIGavsnLyxO9vDvtguJivqJmRmo,4187
+keyflint_verify-1.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+keyflint_verify-1.1.0.dist-info/top_level.txt,sha256=_p5jRNdpaVaWUfSwGNz7U17-91wMc44WtabItE__0jg,16
+keyflint_verify-1.1.0.dist-info/RECORD,,

keyflint_verify-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

keyflint_verify-1.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+keyflint_verify