permitcore 1.0.0__py3-none-any.whl

permitcore/__init__.py

@@ -0,0 +1,670 @@
+"""
+PermitCore Python SDK — Official client for PermitCore license management.
+
+Quick start:
+    from permitcore import PermitCoreClient
+
+    client = PermitCoreClient("https://your-instance.com")
+    result = client.validate("PERMIT-XXXX-XXXX-XXXX-XXXX")
+
+    if result.is_valid:
+        print(f"Valid! Product: {result.product_name}")
+        if result.has_feature("export"):
+            enable_export()
+"""
+
+import base64
+import hashlib
+import json
+import os
+import platform
+import socket
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+from urllib import request as urllib_request
+from urllib.error import URLError, HTTPError
+from urllib.parse import quote
+
+
+class OfflineVerificationUnavailable(ImportError):
+    """
+    Raised when offline token verification is attempted but the optional
+    'cryptography' package is not installed. Only the offline-token features
+    (verify_offline_token / activate_offline / validate_offline) need it —
+    the rest of this SDK has zero external dependencies.
+    """
+    pass
+
+
+# ── Data classes ────────────────────────────────────────────────────────────
+
+@dataclass
+class LicenseResult:
+    is_valid: bool
+    product_name: Optional[str] = None
+    remaining_activations: Optional[int] = None
+    expires_at: Optional[str] = None
+    message: Optional[str] = None
+    custom_fields: Optional[Dict[str, str]] = None
+    vendor_warning: Optional[str] = None
+    features: Optional[List[str]] = None
+    is_trial: bool = False
+    trial_days_remaining: Optional[int] = None
+    node_locked: bool = False
+    offline_grace_days: Optional[int] = None
+    min_version: Optional[str] = None
+    max_version: Optional[str] = None
+    is_offline: bool = False
+    offline_cache_token: Optional[str] = None
+    """
+    ECDSA-signed pc_grace_v1 token (non-null only when the license has an offline grace
+    period configured and this call succeeded). The SDK caches this — not the rest of this
+    response — and verifies it locally before trusting a cached result on a later offline
+    call. See verify_grace_cache_token().
+    """
+
+    def has_feature(self, feature: str) -> bool:
+        """Returns True if the license includes the given feature flag (case-insensitive)."""
+        if not self.features:
+            return False
+        return any(f.lower() == feature.lower() for f in self.features)
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "LicenseResult":
+        return cls(
+            is_valid=data.get("isValid", False),
+            product_name=data.get("productName"),
+            remaining_activations=data.get("remainingActivations"),
+            expires_at=data.get("expiresAt"),
+            message=data.get("message"),
+            custom_fields=data.get("customFields"),
+            vendor_warning=data.get("vendorWarning"),
+            features=data.get("features"),
+            is_trial=data.get("isTrial", False),
+            trial_days_remaining=data.get("trialDaysRemaining"),
+            node_locked=data.get("nodeLocked", False),
+            offline_grace_days=data.get("offlineGraceDays"),
+            min_version=data.get("minVersion"),
+            max_version=data.get("maxVersion"),
+            offline_cache_token=data.get("offlineCacheToken"),
+        )
+
+
+@dataclass
+class FloatingSession:
+    success: bool
+    session_token: Optional[str] = None
+    expires_at: Optional[str] = None
+    message: Optional[str] = None
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "FloatingSession":
+        return cls(
+            success=data.get("success", False),
+            session_token=data.get("sessionToken"),
+            expires_at=data.get("expiresAt"),
+            message=data.get("message"),
+        )
+
+
+@dataclass
+class OfflineTokenPayload:
+    """Decoded payload of a `pc_offline_v1` offline activation token."""
+    version: int = 1
+    token_id: Optional[str] = None
+    tenant_slug: Optional[str] = None
+    kid: Optional[str] = None
+    tenant_id: Optional[str] = None
+    license_id: Optional[str] = None
+    license_key_hash: Optional[str] = None
+    device_id: Optional[str] = None
+    device_name: Optional[str] = None
+    product_name: Optional[str] = None
+    max_activations: Optional[int] = None
+    issued_at: Optional[str] = None
+    expires_at: Optional[str] = None
+    """
+    kid: TenantSigningKey.Kid used to sign this token — null on tokens issued before key
+    versioning existed (see the "legacy_null_kid" shared test vector). Mirrors
+    GraceCachePayload.kid; only used for informational/key-selection purposes by callers
+    that manage multiple signing keys — verify_offline_token() itself is handed the public
+    key to verify against directly and does not look it up via this field.
+    """
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "OfflineTokenPayload":
+        return cls(
+            version=data.get("version", 1),
+            token_id=data.get("tokenId"),
+            tenant_slug=data.get("tenantSlug"),
+            kid=data.get("kid"),
+            tenant_id=data.get("tenantId"),
+            license_id=data.get("licenseId"),
+            license_key_hash=data.get("licenseKeyHash"),
+            device_id=data.get("deviceId"),
+            device_name=data.get("deviceName"),
+            product_name=data.get("productName"),
+            max_activations=data.get("maxActivations"),
+            issued_at=data.get("issuedAt"),
+            expires_at=data.get("expiresAt"),
+        )
+
+
+@dataclass
+class OfflineTokenResult:
+    is_valid: bool
+    message: str = ""
+    payload: Optional[OfflineTokenPayload] = None
+
+
+@dataclass
+class GraceCachePayload:
+    """Decoded, verified payload of a `pc_grace_v1` offline grace-cache token."""
+    version: int = 1
+    tenant_slug: Optional[str] = None
+    kid: Optional[str] = None
+    license_key_hash: Optional[str] = None
+    device_id: Optional[str] = None
+    is_valid: bool = False
+    product_name: Optional[str] = None
+    features: Optional[List[str]] = None
+    remaining_activations: Optional[int] = None
+    expires_at: Optional[str] = None
+    issued_at: Optional[str] = None
+    valid_until: Optional[str] = None
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "GraceCachePayload":
+        return cls(
+            version=data.get("version", 1),
+            tenant_slug=data.get("tenantSlug"),
+            kid=data.get("kid"),
+            license_key_hash=data.get("licenseKeyHash"),
+            device_id=data.get("deviceId"),
+            is_valid=data.get("isValid", False),
+            product_name=data.get("productName"),
+            features=data.get("features"),
+            remaining_activations=data.get("remainingActivations"),
+            expires_at=data.get("expiresAt"),
+            issued_at=data.get("issuedAt"),
+            valid_until=data.get("validUntil"),
+        )
+
+
+@dataclass
+class GraceCacheResult:
+    is_valid: bool
+    message: str = ""
+    payload: Optional[GraceCachePayload] = None
+
+
+# ── Client ──────────────────────────────────────────────────────────────────
+
+class PermitCoreClient:
+    """
+    Official PermitCore Python SDK client.
+
+    Args:
+        base_url: Your PermitCore API base URL, e.g. "https://api.yourapp.com"
+        enable_offline_cache: Cache responses for offline grace period (default True)
+        timeout: HTTP request timeout in seconds (default 5)
+    """
+
+    def __init__(self, base_url: str, enable_offline_cache: bool = True, timeout: int = 5):
+        self._base = base_url.rstrip("/")
+        self._cache = enable_offline_cache
+        self._timeout = timeout
+
+    # ── Validate ─────────────────────────────────────────────────────────
+
+    def validate(self, license_key: str, version: Optional[str] = None) -> LicenseResult:
+        """
+        Validates a license key. Does NOT consume an activation slot.
+        version: Optional current software version — lets the server enforce
+        minVersion/maxVersion restrictions on the license.
+        Falls back to local cache when server is unreachable.
+        """
+        payload = {"licenseKey": license_key}
+        if version:
+            payload["version"] = version
+        try:
+            data = self._post("api/v1/validate", payload)
+            result = LicenseResult._from_dict(data)
+            if result.is_valid:
+                self._save_cache(license_key, result)
+            return result
+        except (URLError, OSError, TimeoutError):
+            cached = self._load_cache(license_key)
+            if cached:
+                return cached
+            return LicenseResult(is_valid=False, message="Cannot reach license server.", is_offline=True)
+
+    # ── Activate ─────────────────────────────────────────────────────────
+
+    def activate(self, license_key: str, device_id: Optional[str] = None,
+                 device_name: Optional[str] = None, version: Optional[str] = None) -> LicenseResult:
+        """
+        Validates AND activates the key on this device. Call only once per installation.
+        device_id: Optional — auto-generated HWID is used when omitted.
+        version: Optional current software version — lets the server enforce
+        minVersion/maxVersion restrictions on the license.
+        """
+        hwid = device_id or self.get_hardware_id()
+        try:
+            # [S-Nonce] Fetch a single-use nonce first (replay-attack protection)
+            nonce_data = self._get("api/v1/nonce")
+            nonce = nonce_data["nonce"]
+            payload = {"licenseKey": license_key, "deviceId": hwid, "nonce": nonce}
+            if device_name:
+                payload["deviceName"] = device_name
+            if version:
+                payload["version"] = version
+            data = self._post("api/v1/activate", payload)
+            result = LicenseResult._from_dict(data)
+            if result.is_valid:
+                self._save_cache(license_key, result)
+            return result
+        except (URLError, OSError, TimeoutError):
+            # [S-Continuity] If this device already activated successfully before (e.g. an app
+            # that re-runs activate() on every launch, or a reinstall that kept the cache file),
+            # fall back to that cached result instead of failing outright.
+            cached = self._load_cache(license_key)
+            if cached:
+                return cached
+            return LicenseResult(is_valid=False, message="Cannot reach license server.", is_offline=True)
+
+    # ── Meter ────────────────────────────────────────────────────────────
+
+    def meter(self, license_key: str, event_name: str, quantity: int = 1,
+              meta: Optional[dict] = None) -> bool:
+        """
+        Records a usage event for metered billing.
+        Returns True if the event was recorded on the server, False on any failure
+        (network error, or the server rejecting the event).
+        """
+        payload = {"licenseKey": license_key, "eventName": event_name, "quantity": quantity}
+        if meta:
+            payload["meta"] = meta
+        try:
+            data = self._post("api/v1/meter", payload)
+            return bool(data.get("recorded", False))
+        except (URLError, OSError, TimeoutError):
+            return False
+
+    # ── Floating ─────────────────────────────────────────────────────────
+
+    def checkout(self, license_key: str, device_id: Optional[str] = None,
+                 device_name: Optional[str] = None) -> FloatingSession:
+        """Checks out a concurrent seat for a floating license."""
+        hwid = device_id or self.get_hardware_id()
+        payload = {"licenseKey": license_key, "deviceId": hwid}
+        if device_name:
+            payload["deviceName"] = device_name
+        data = self._post("api/v1/float/checkout", payload)
+        return FloatingSession._from_dict(data)
+
+    def heartbeat(self, session_token: str) -> FloatingSession:
+        """Keeps a floating session alive. Call every 4–5 minutes."""
+        # [S-Float] Session token in the POST body — never the URL path — matches
+        # FloatingController.Heartbeat's FloatingTokenRequest exactly.
+        data = self._post("api/v1/float/heartbeat", {"sessionToken": session_token})
+        return FloatingSession._from_dict(data)
+
+    def checkin(self, session_token: str) -> None:
+        """Releases a floating seat."""
+        # [S-Float] Session token in the POST body — never the URL path — matches
+        # FloatingController.Checkin's FloatingTokenRequest exactly (also: it's a POST, not DELETE).
+        req = urllib_request.Request(
+            f"{self._base}/api/v1/float/checkin",
+            data=json.dumps({"sessionToken": session_token}).encode(),
+            method="POST",
+        )
+        req.add_header("Content-Type", "application/json")
+        req.add_header("User-Agent", "PermitCore-Python/1.0")
+        try:
+            with urllib_request.urlopen(req, timeout=self._timeout):
+                pass
+        except (URLError, OSError):
+            pass
+
+    # ── Offline token verification (pc_offline_v1, ECDSA P-256 / IEEE P1363) ───────────
+    #
+    # Requires the optional 'cryptography' package: pip install cryptography
+    # (or `pip install permitcore[offline]` if installed via extras). Lazy-imported so the
+    # rest of this SDK stays zero-dependency. Mirrors
+    # PermitCore.Infrastructure.Services.OfflineActivationService.Verify byte-for-byte.
+
+    @staticmethod
+    def verify_offline_token(token: str, public_key_base64: str) -> "OfflineTokenResult":
+        """
+        Verifies an offline activation token entirely locally — no network call.
+        This is the primitive every other offline_* method builds on.
+        """
+        parts = token.split(".") if token else []
+        if len(parts) != 3 or parts[0] != "pc_offline_v1":
+            return OfflineTokenResult(is_valid=False, message="Malformed token.")
+
+        ec, ec_utils, load_der_public_key, hashes, InvalidSignature = _require_cryptography()
+
+        try:
+            payload_bytes = parts[1].encode("utf-8")
+            sig = _b64url_decode(parts[2])
+            if len(sig) != 64:
+                return OfflineTokenResult(is_valid=False, message="Invalid signature.")
+
+            r = int.from_bytes(sig[:32], "big")
+            s = int.from_bytes(sig[32:], "big")
+            der_sig = ec_utils.encode_dss_signature(r, s)
+
+            public_key = load_der_public_key(base64.b64decode(public_key_base64))
+
+            try:
+                public_key.verify(der_sig, payload_bytes, ec.ECDSA(hashes.SHA256()))
+            except InvalidSignature:
+                return OfflineTokenResult(is_valid=False, message="Invalid signature.")
+
+            json_bytes = _b64url_decode(parts[1])
+            payload = OfflineTokenPayload._from_dict(json.loads(json_bytes))
+
+            if payload.expires_at and _parse_iso8601(payload.expires_at) < datetime.now(timezone.utc):
+                return OfflineTokenResult(is_valid=False, message="Token expired.", payload=payload)
+
+            return OfflineTokenResult(is_valid=True, message="Valid.", payload=payload)
+        except OfflineVerificationUnavailable:
+            raise
+        except Exception:
+            return OfflineTokenResult(is_valid=False, message="Invalid or corrupt token.")
+
+    # ── Grace-cache token verification (pc_grace_v1, ECDSA P-256 / IEEE P1363) ─────────
+    # Reference implementation — matches
+    # PermitCore.Infrastructure.Services.OfflineActivationService.VerifyGraceCache
+    # byte-for-byte, same relationship verify_offline_token above has to its server-side
+    # counterpart. Used by _save_cache/_load_cache below to replace the old unsigned
+    # offline-grace cache with one an attacker can't hand-edit.
+
+    @staticmethod
+    def verify_grace_cache_token(token: str, public_key_base64: str) -> "GraceCacheResult":
+        """
+        Verifies a pc_grace_v1 offline grace-cache token entirely locally — no network call.
+        Exposed publicly so a custom integration (not using the built-in cache) can implement
+        its own caching around the same verified primitive.
+        """
+        parts = token.split(".") if token else []
+        if len(parts) != 3 or parts[0] != "pc_grace_v1":
+            return GraceCacheResult(is_valid=False, message="Malformed token.")
+
+        ec, ec_utils, load_der_public_key, hashes, InvalidSignature = _require_cryptography()
+
+        try:
+            payload_bytes = parts[1].encode("utf-8")
+            sig = _b64url_decode(parts[2])
+            if len(sig) != 64:
+                return GraceCacheResult(is_valid=False, message="Invalid signature.")
+
+            r = int.from_bytes(sig[:32], "big")
+            s = int.from_bytes(sig[32:], "big")
+            der_sig = ec_utils.encode_dss_signature(r, s)
+
+            public_key = load_der_public_key(base64.b64decode(public_key_base64))
+
+            try:
+                public_key.verify(der_sig, payload_bytes, ec.ECDSA(hashes.SHA256()))
+            except InvalidSignature:
+                return GraceCacheResult(is_valid=False, message="Invalid signature.")
+
+            json_bytes = _b64url_decode(parts[1])
+            payload = GraceCachePayload._from_dict(json.loads(json_bytes))
+
+            if payload.valid_until and _parse_iso8601(payload.valid_until) < datetime.now(timezone.utc):
+                return GraceCacheResult(is_valid=False, message="Grace period expired.", payload=payload)
+
+            return GraceCacheResult(is_valid=True, message="Valid.", payload=payload)
+        except OfflineVerificationUnavailable:
+            raise
+        except Exception:
+            return GraceCacheResult(is_valid=False, message="Invalid or corrupt token.")
+
+    @staticmethod
+    def activate_offline(token: str, public_key_base64: str, device_id: str) -> "OfflineTokenResult":
+        """
+        Verifies an offline token, additionally checks it was issued for this device, and —
+        on success — persists the verified payload to local disk so validate_offline() can be
+        called later without needing the original token again.
+        """
+        result = PermitCoreClient.verify_offline_token(token, public_key_base64)
+        if not result.is_valid or result.payload is None:
+            return result
+
+        if (result.payload.device_id or "").lower() != (device_id or "").lower():
+            return OfflineTokenResult(
+                is_valid=False,
+                message="Token was issued for a different device.",
+                payload=result.payload,
+            )
+
+        try:
+            with open(_offline_cache_path(device_id), "w") as f:
+                json.dump(result.payload.__dict__, f)
+        except OSError:
+            pass  # cache failure must never block a successful verification
+
+        return result
+
+    @staticmethod
+    def validate_offline(device_id: str) -> "OfflineTokenResult":
+        """
+        Reads the locally persisted offline-activation result (from a prior activate_offline()
+        call) and checks it's still within its validity window. No network call, no token
+        needed — call this on every app launch once already offline-activated.
+        """
+        try:
+            path = _offline_cache_path(device_id)
+            if not os.path.exists(path):
+                return OfflineTokenResult(is_valid=False, message="No local offline activation found.")
+
+            with open(path) as f:
+                data = json.load(f)
+            payload = OfflineTokenPayload(**data)
+
+            if (payload.device_id or "").lower() != (device_id or "").lower():
+                return OfflineTokenResult(is_valid=False, message="Device mismatch.", payload=payload)
+
+            if payload.expires_at and _parse_iso8601(payload.expires_at) < datetime.now(timezone.utc):
+                return OfflineTokenResult(is_valid=False, message="Offline activation expired.", payload=payload)
+
+            return OfflineTokenResult(is_valid=True, message="Valid (offline).", payload=payload)
+        except (OSError, KeyError, TypeError, json.JSONDecodeError):
+            return OfflineTokenResult(is_valid=False, message="Corrupt local offline activation.")
+
+    def verify_offline_online(self, token: str) -> "OfflineTokenResult":
+        """
+        Optional online check: asks the server to verify the token AND check its revocation
+        status. Requires network. Use verify_offline_token() for pure offline verification —
+        this method does not need the 'cryptography' package, the server does the crypto.
+        """
+        try:
+            data = self._post("api/v1/offline/verify", {"token": token})
+            return OfflineTokenResult(
+                is_valid=bool(data.get("isValid", False)),
+                message=data.get("message") or "",
+            )
+        except (URLError, OSError, TimeoutError):
+            return OfflineTokenResult(is_valid=False, message="Cannot reach license server.")
+
+    # ── HWID ─────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def get_hardware_id() -> str:
+        """Generates a stable hardware fingerprint (SHA-256 of machine identifiers)."""
+        components = [
+            socket.gethostname(),
+            platform.system(),
+            platform.machine(),
+            str(os.cpu_count() or 1),
+            _get_or_create_seed(),
+        ]
+        combined = "|".join(c for c in components if c)
+        return hashlib.sha256(combined.encode()).hexdigest()
+
+    # ── Cache ─────────────────────────────────────────────────────────────
+
+    def _save_cache(self, license_key: str, result: LicenseResult) -> None:
+        # [S-Grace1] Cache the SIGNED token, not the raw response — the server only issues
+        # offline_cache_token when a grace period is configured, so a missing token here
+        # already means "nothing to cache," same as the old offline_grace_days check used to.
+        if not self._cache or not result.offline_cache_token:
+            return
+        try:
+            tenant_slug = _extract_unverified_tenant_slug(result.offline_cache_token)
+            if not tenant_slug:
+                return
+
+            pub_key_data = self._get(f"api/v1/{quote(tenant_slug, safe='')}/public-key")
+            public_key = pub_key_data.get("publicKey")
+            if not public_key:
+                return
+
+            # Verify before persisting anything — never cache a token this SDK can't itself
+            # verify later; that would just recreate the old "trust an opaque file" problem.
+            check = self.verify_grace_cache_token(result.offline_cache_token, public_key)
+            if not check.is_valid:
+                return
+
+            entry = {"token": result.offline_cache_token, "public_key": public_key}
+            with open(_cache_path(license_key), "w") as f:
+                json.dump(entry, f)
+        except Exception:
+            pass  # cache failure must never block the normal online flow
+
+    def _load_cache(self, license_key: str) -> Optional[LicenseResult]:
+        if not self._cache:
+            return None
+        try:
+            with open(_cache_path(license_key)) as f:
+                entry = json.load(f)
+            token = entry.get("token")
+            public_key = entry.get("public_key")
+            if not token or not public_key:
+                return None
+
+            # No network call here — verification uses only the public key persisted
+            # alongside the token at save time. This is the entire point: a hand-edited
+            # cache file (or one copied to another machine) fails ECDSA verification
+            # instead of silently working.
+            check = self.verify_grace_cache_token(token, public_key)
+            if not check.is_valid or check.payload is None:
+                return None
+
+            p = check.payload
+            valid_until_display = p.valid_until
+            try:
+                if p.valid_until:
+                    valid_until_display = _parse_iso8601(p.valid_until).strftime("%d %b %Y")
+            except Exception:
+                pass
+
+            return LicenseResult(
+                is_valid=p.is_valid,
+                product_name=p.product_name,
+                remaining_activations=p.remaining_activations,
+                expires_at=p.expires_at,
+                features=p.features,
+                is_offline=True,
+                message=f"Offline mode — valid until {valid_until_display} (cryptographically verified)",
+            )
+        except Exception:
+            return None
+
+    # ── HTTP helpers ──────────────────────────────────────────────────────
+
+    def _get(self, path: str) -> dict:
+        req = urllib_request.Request(f"{self._base}/{path}")
+        req.add_header("User-Agent", "PermitCore-Python/1.0")
+        with urllib_request.urlopen(req, timeout=self._timeout) as resp:
+            return json.loads(resp.read())
+
+    def _post(self, path: str, payload: dict) -> dict:
+        data = json.dumps(payload).encode()
+        req = urllib_request.Request(f"{self._base}/{path}", data=data, method="POST")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("User-Agent", "PermitCore-Python/1.0")
+        with urllib_request.urlopen(req, timeout=self._timeout) as resp:
+            return json.loads(resp.read())
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────
+
+def _cache_path(license_key: str) -> str:
+    h = hashlib.sha256(license_key.encode()).hexdigest()[:16]
+    return os.path.join(os.path.expanduser("~"), f".permitcore_cache_{h}")
+
+
+def _offline_cache_path(device_id: str) -> str:
+    h = hashlib.sha256((device_id or "").encode()).hexdigest()[:16]
+    return os.path.join(os.path.expanduser("~"), f".permitcore_offline_{h}")
+
+
+def _b64url_decode(s: str) -> bytes:
+    padding = "=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode(s + padding)
+
+
+def _extract_unverified_tenant_slug(token: str) -> Optional[str]:
+    """
+    Reads only the `tenantSlug` field out of a pc_grace_v1 token's payload, WITHOUT
+    verifying the signature — safe to do because it's only used to pick which tenant's
+    public-key endpoint to fetch. PermitCoreClient.verify_grace_cache_token() is what
+    actually establishes trust before anything gets persisted to disk.
+    """
+    if not token:
+        return None
+    parts = token.split(".")
+    if len(parts) != 3 or parts[0] != "pc_grace_v1":
+        return None
+    try:
+        data = json.loads(_b64url_decode(parts[1]))
+        return data.get("tenantSlug")
+    except Exception:
+        return None
+
+
+def _parse_iso8601(s: str) -> datetime:
+    if s.endswith("Z"):
+        s = s[:-1] + "+00:00"
+    dt = datetime.fromisoformat(s)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def _require_cryptography():
+    """
+    Lazy-imports the optional 'cryptography' package. Only called from inside the
+    offline-token verification functions — the rest of this SDK must import cleanly
+    without 'cryptography' installed.
+    """
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives import hashes
+        from cryptography.hazmat.primitives.asymmetric import ec, utils as ec_utils
+        from cryptography.hazmat.primitives.serialization import load_der_public_key
+    except ImportError as e:
+        raise OfflineVerificationUnavailable(
+            "Offline token verification requires the 'cryptography' package. "
+            "Install it with: pip install cryptography"
+        ) from e
+    return ec, ec_utils, load_der_public_key, hashes, InvalidSignature
+
+
+def _get_or_create_seed() -> str:
+    seed_path = os.path.join(os.path.expanduser("~"), ".permitcore_seed")
+    try:
+        if not os.path.exists(seed_path):
+            with open(seed_path, "w") as f:
+                f.write(str(uuid.uuid4()))
+        with open(seed_path) as f:
+            return f.read().strip()
+    except OSError:
+        return ""

permitcore-1.0.0.dist-info/METADATA

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: permitcore
+Version: 1.0.0
+Summary: Official Python SDK for PermitCore license management
+Author-email: PermitCore <sdk@permitcore.dev>
+License: MIT
+Project-URL: Homepage, https://permitcore.dev
+Project-URL: Repository, https://github.com/permitCore-spec/PermitCore/tree/main/SDKs/python
+Keywords: license,licensing,sdk,permitcore,activation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: offline
+Requires-Dist: cryptography>=41; extra == "offline"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: cryptography>=41; extra == "test"
+
+# PermitCore Python SDK
+
+Official Python client for [PermitCore](https://permitcore.dev) license management.
+
+**Requirements:** Python 3.8+, zero required dependencies. The optional `cryptography` package
+(`pip install permitcore[offline]`) is only needed for offline license token verification.
+
+---
+
+## Installation
+
+```bash
+pip install permitcore
+```
+
+Or, for offline license token verification support:
+
+```bash
+pip install permitcore[offline]
+```
+
+---
+
+## Quick start
+
+```python
+from permitcore import PermitCoreClient
+
+client = PermitCoreClient("https://your-instance.com")
+result = client.validate("PERMIT-XXXX-XXXX-XXXX-XXXX")
+
+if result.is_valid:
+    print(f"Valid! Product: {result.product_name}")
+    if result.has_feature("export"):
+        enable_export()
+```
+
+---
+
+## Validate
+
+```python
+result = client.validate(license_key, version="2.3.1")  # version is optional
+
+# result.is_valid                  bool
+# result.product_name              Optional[str]
+# result.remaining_activations     Optional[int]
+# result.expires_at                Optional[str]  (ISO 8601)
+# result.features                  Optional[List[str]]
+# result.custom_fields             Optional[Dict[str, str]]
+# result.is_trial                  bool
+# result.trial_days_remaining      Optional[int]
+# result.node_locked                bool
+# result.offline_grace_days        Optional[int]
+# result.min_version               Optional[str]
+# result.max_version               Optional[str]
+# result.vendor_warning            Optional[str]
+# result.message                   Optional[str]
+# result.is_offline                bool  (true when served from local cache)
+```
+
+`validate()` never consumes an activation slot. It falls back to the local disk cache when the
+server is unreachable, as long as the license has `offline_grace_days` configured. Passing
+`version` lets the server enforce `min_version`/`max_version` restrictions on the license.
+
+---
+
+## Activate
+
+```python
+result = client.activate(
+    license_key,
+    device_id=None,       # auto-generated HWID when omitted
+    device_name="Production Server #1",
+    version="2.3.1",      # optional
+)
+
+if not result.is_valid:
+    raise RuntimeError(f"Activation failed: {result.message}")
+```
+
+Call `activate()` **once** per installation. Use `validate()` on every subsequent launch.
+
+---
+
+## Meter (usage events)
+
+```python
+# Record a single API call
+recorded = client.meter(license_key, "api_call")
+
+# Record bulk usage with metadata
+recorded = client.meter(license_key, "export", quantity=5, meta={"format": "pdf", "pages": 12})
+```
+
+Returns `True` if the event was recorded on the server, `False` on any failure (network error, or
+the server rejecting the event).
+
+---
+
+## Floating licenses
+
+```python
+# Check out a seat at session start
+session = client.checkout(license_key)
+if not session.success:
+    raise RuntimeError(f"No seats available: {session.message}")
+
+token = session.session_token
+
+# Heartbeat every 4-5 minutes to keep the seat alive
+client.heartbeat(token)
+
+# Release the seat when done
+client.checkin(token)
+```
+
+---
+
+## Offline license tokens
+
+An offline activation token (`pc_offline_v1.<payload>.<signature>`) lets your app verify a
+license with **zero network calls**, using ECDSA P-256 signature verification against your
+tenant's public key (`GET /api/v1/{tenantSlug}/public-key`). Useful for air-gapped or
+intermittently-connected deployments. Requires the optional `cryptography` package
+(`pip install permitcore[offline]`) — a plain `pip install permitcore` install raises
+`OfflineVerificationUnavailable` if you call these without it.
+
+```python
+# Pure local verification — no network call. Never throws (except OfflineVerificationUnavailable
+# if 'cryptography' isn't installed).
+result = PermitCoreClient.verify_offline_token(token, public_key_base64)
+
+if result.is_valid:
+    print(f"Valid! Product: {result.payload.product_name}")
+else:
+    print(f"Invalid: {result.message}")
+```
+
+```python
+# Verify + bind to this device + persist locally (call once, e.g. at install time)
+result = PermitCoreClient.activate_offline(token, public_key_base64, device_id)
+
+# On every later launch — no token needed, reads the local cache, still no network call
+result = PermitCoreClient.validate_offline(device_id)
+```
+
+```python
+# Optional: ask the server to verify the token AND check its revocation status (requires network)
+result = client.verify_offline_online(token)
+```
+
+All four methods return an `OfflineTokenResult(is_valid, message, payload)`. `payload` (an
+`OfflineTokenPayload`) carries `token_id`, `tenant_slug`, `kid`, `tenant_id`, `license_id`,
+`license_key_hash`, `device_id`, `device_name`, `product_name`, `max_activations`, `issued_at`,
+`expires_at`. `kid` identifies which of the tenant's signing keys produced the token (`None` on
+tokens issued before key versioning existed) — informational only, `verify_offline_token()` still
+verifies against whatever `public_key_base64` you pass it. `verify_offline_token()` and
+`validate_offline()` never throw for malformed,
+tampered, expired, or missing input — they just return `is_valid=False` with a descriptive
+`message`.
+
+`activate_offline()`'s local cache is stored under the user's home directory as
+`.permitcore_offline_<hash>` (same convention as the `validate()`/`activate()` cache, keyed by
+device ID instead of license key).
+
+---
+
+## Version enforcement
+
+```python
+result = client.validate(license_key)
+
+my_version = "2.3.0"
+if result.min_version and my_version < result.min_version:
+    raise RuntimeError(f"Please update to version {result.min_version} or newer.")
+if result.max_version and my_version > result.max_version:
+    raise RuntimeError(f"This build ({my_version}) is not licensed for versions above {result.max_version}.")
+```
+
+Pass `version=my_version` to `validate()`/`activate()` to also have the *server* enforce this —
+otherwise only client-side comparison happens.
+
+---
+
+## Offline grace pattern
+
+```python
+result = client.validate(license_key)  # falls back to cache automatically
+
+if not result.is_valid:
+    raise RuntimeError(f"License invalid: {result.message}")
+
+if result.is_offline:
+    # Server unreachable — running on cached result
+    show_notice("Running in offline mode. Connect to the internet to refresh your license.")
+```
+
+The cache is stored under the user's home directory as `.permitcore_cache_<hash>`. It expires
+after `offline_grace_days` days.
+
+---
+
+## Constructor options
+
+```python
+client = PermitCoreClient(
+    base_url="https://your-instance.com",
+    enable_offline_cache=True,  # default — set False to always require network
+    timeout=5,                  # HTTP timeout in seconds
+)
+```
+
+---
+
+## LicenseResult reference
+
+| Field | Type | Description |
+|---|---|---|
+| `is_valid` | `bool` | True if the license is active and valid |
+| `product_name` | `Optional[str]` | Product the license belongs to |
+| `remaining_activations` | `Optional[int]` | Slots left before MaxActivations is reached |
+| `expires_at` | `Optional[str]` | Expiry date (ISO 8601 UTC), None if perpetual |
+| `features` | `Optional[List[str]]` | Feature flag list, e.g. `["export", "api"]` |
+| `custom_fields` | `Optional[Dict[str, str]]` | Arbitrary key/value metadata set on the license |
+| `is_trial` | `bool` | True for trial licenses |
+| `trial_days_remaining` | `Optional[int]` | Days until trial expires |
+| `node_locked` | `bool` | True if bound to a specific device |
+| `offline_grace_days` | `Optional[int]` | How many days the cache is valid |
+| `min_version` / `max_version` | `Optional[str]` | Version enforcement bounds |
+| `vendor_warning` | `Optional[str]` | Non-fatal message from the vendor |
+| `message` | `Optional[str]` | Reason when `is_valid = False` |
+| `is_offline` | `bool` | True when result came from local cache |
+
+---
+
+## Development
+
+```bash
+pip install -e ".[test]"   # installs pytest + cryptography for the test run
+pytest
+```
+
+`tests/test_vectors.py` runs this SDK's `verify_offline_token`/`verify_grace_cache_token` against
+the shared, language-agnostic cross-SDK protocol vectors in `../../test-vectors/vectors.json`
+(fixed ECDSA P-256/SHA-256 tokens every PermitCore SDK verifies identically — see that file's own
+`schemaNote`) and checks the `validate`/`activate` request bodies this SDK builds match the shared
+`requestShapes` key sets exactly.
+
+`has_feature(feature: str) -> bool` — case-insensitive feature check.

permitcore-1.0.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+permitcore/__init__.py,sha256=RoEWvPPGZLSPSwMKkcILuoUELVVqjKGb_Y6useV_gh4,29312
+permitcore-1.0.0.dist-info/METADATA,sha256=wVUYDckPJqPBBFq6lKVqmZwiJHcDHlWwXGS5YTDi-JQ,9562
+permitcore-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+permitcore-1.0.0.dist-info/top_level.txt,sha256=q3ZnWbUDCzeFHdOD_b9MvYs-se4LT7Aj6muWWnR2Gro,11
+permitcore-1.0.0.dist-info/RECORD,,

permitcore-1.0.0.dist-info/WHEEL

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

permitcore-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+permitcore