xenterprise 0.1.0__tar.gz

xenterprise-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+Odoo Proprietary License v1.0
+
+This software and associated files (the "Software") may only be used (executed,
+modified, executed after modifications) if you have purchased a valid license
+from the authors, typically via Odoo Apps, or if you have received a written
+agreement from the authors of the Software (see the COPYRIGHT file).
+
+You may develop Odoo modules that use the Software as a library (typically
+by depending on it, importing it and using its resources), but without copying
+any source code or material from the Software. You may distribute those
+modules under the license of your choice, provided that this license is
+compatible with the terms of the Odoo Proprietary License (For example:
+LGPL, MIT, or proprietary licenses similar to this one).
+
+It is forbidden to publish, distribute, sublicense, or sell copies of the Software
+or modified copies of the Software.
+
+The above copyright notice and this permission notice must 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.

xenterprise-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: xenterprise
+Version: 0.1.0
+Summary: Offline validation of Vauxoo RS256-JWT license tokens (base_license client, no Odoo).
+Author-email: Vauxoo <info@vauxoo.com>
+License-Expression: LicenseRef-OPL-1
+Project-URL: Homepage, https://www.vauxoo.com
+Project-URL: Source, https://git.vauxoo.com/vauxoo/xenterprise
+Keywords: license,jwt,rs256,vauxoo,odoo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyjwt<3,>=2.8
+Requires-Dist: cryptography
+Requires-Dist: requests
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: ruff; extra == "test"
+Dynamic: license-file
+
+# xenterprise
+
+Offline validation of Vauxoo RS256-JWT license tokens — the pure-Python client
+extracted from the Vauxoo `base_license` Odoo module.
+
+A proprietary module gates itself by listing `xenterprise` in its
+`external_dependencies.python` (so `pip` installs it on deploy) and calling
+`xenterprise.validate(...)` with the vendor public key. The signing server
+(`license_manager`, running at `https://enterprise.vauxoo.ai`) is unchanged:
+this package only **validates** tokens offline with the vendor **public** key —
+it never signs. Grace / expiry / revocation and anti-rollback semantics are
+identical to `base_license`, so a `license_manager` token validates the same way
+whether it is checked by the Odoo module or by this package.
+
+## Install
+
+```bash
+pip install xenterprise
+```
+
+## Public API
+
+```python
+import xenterprise
+from xenterprise import (
+    validate, Verdict,
+    LicenseError, LicenseInvalid, LicenseRevoked,
+    obfuscate_token, deobfuscate_token, compute_hwid,
+    DEFAULT_ISSUER, DEFAULT_SERVER_URL,
+)
+from xenterprise import client  # optional HTTP to the vendor
+
+v = xenterprise.validate(
+    token,                 # the RS256 JWT issued by license_manager
+    pubkey_pem=vendor_pem, # vendor PUBLIC key (PEM)
+    product_code="CR_EDI", # vendor catalog code
+    now=None,              # datetime | None (naive is read as UTC); None = now
+    last_seen=None,        # datetime | None, anti-rollback high-water mark
+    issuer=DEFAULT_ISSUER, # "vauxoo-license"
+    leeway=300,            # seconds of clock tolerance
+    blocked=False,         # True if a vendor revoke/expired verdict is persisted
+)
+
+if v.ok:            # True iff v.state in {"valid", "grace"}
+    ...             # deliver the gated value
+else:
+    raise SomeError(v.reason)
+```
+
+`validate` never raises for a license outcome and never does network I/O. It
+returns a `Verdict`:
+
+| field       | type                                               | notes                                   |
+|-------------|----------------------------------------------------|-----------------------------------------|
+| `.state`    | `valid` / `grace` / `expired` / `revoked` / `invalid` |                                      |
+| `.ok`       | `bool`                                             | `True` iff `state in {valid, grace}`    |
+| `.term_end` | `date \| None`                                     | product subscription end (`None` = perpetual) |
+| `.mode`     | `production` / `sandbox` / `None`                  | `None` when the token did not decode    |
+| `.claims`   | `dict`                                             | the decoded JWT claims (empty if undecodable) |
+| `.reason`   | `str`                                              | human-readable explanation              |
+
+### State semantics (identical to `base_license`)
+
+- **valid** — signature, issuer, required claims and mode check out; the token
+  is not past its `exp`; the product is granted and its `term_end` is in the
+  future (or perpetual).
+- **grace** — the token is past `exp` but still inside the `grace` window
+  (`grace` days from the token). Keep working; refresh when the vendor is
+  reachable.
+- **expired** — the product subscription `term_end` is in the past.
+- **revoked** — definitive. Produced from `blocked=True` (a persisted vendor
+  `revoked`/`expired` verdict) or `Verdict.revoked(...)`. Checked first, before
+  any decode.
+- **invalid** — missing/malformed token, bad signature, wrong issuer, missing
+  required claim, unknown mode, product not granted, clock rolled back, or the
+  token is expired **past** its grace window.
+
+### Binding (`aud` / `hwid`)
+
+`validate` deliberately does **not** check the production `aud`/`hwid` binding,
+because those identifiers are install-specific. The decoded `claims` are
+returned so an integrator can enforce binding with the identifiers it owns
+(e.g. compare `claims["aud"]` to the database uuid and `claims["hwid"]` to
+`compute_hwid(secret)`).
+
+### Optional HTTP client
+
+```python
+from xenterprise import client
+
+body = client.activate(server_url, key, database_uuid=..., hwid=...)
+body = client.refresh(server_url, key=..., database_uuid=...)
+token = client.interpret_response(body)   # raises LicenseRevoked / LicenseInvalid
+```
+
+The client returns the raw vendor body (`{"ok": ..., "token"/"error": ...}`)
+with a short timeout; `interpret_response` maps `revoked`/`expired` to
+`LicenseRevoked` (definitive) and any other error code to `LicenseInvalid`
+(soft — the vendor being unreachable must leave you in grace, never read as a
+revocation). Plain `http://` is refused unless `require_https=False`.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[test]"
+ruff check .
+pytest
+python -m build        # wheel + sdist in dist/
+```
+
+## License
+
+Odoo Proprietary License v1.0 (OPL-1). See `LICENSE`.

xenterprise-0.1.0/README.md

@@ -0,0 +1,114 @@
+# xenterprise
+
+Offline validation of Vauxoo RS256-JWT license tokens — the pure-Python client
+extracted from the Vauxoo `base_license` Odoo module.
+
+A proprietary module gates itself by listing `xenterprise` in its
+`external_dependencies.python` (so `pip` installs it on deploy) and calling
+`xenterprise.validate(...)` with the vendor public key. The signing server
+(`license_manager`, running at `https://enterprise.vauxoo.ai`) is unchanged:
+this package only **validates** tokens offline with the vendor **public** key —
+it never signs. Grace / expiry / revocation and anti-rollback semantics are
+identical to `base_license`, so a `license_manager` token validates the same way
+whether it is checked by the Odoo module or by this package.
+
+## Install
+
+```bash
+pip install xenterprise
+```
+
+## Public API
+
+```python
+import xenterprise
+from xenterprise import (
+    validate, Verdict,
+    LicenseError, LicenseInvalid, LicenseRevoked,
+    obfuscate_token, deobfuscate_token, compute_hwid,
+    DEFAULT_ISSUER, DEFAULT_SERVER_URL,
+)
+from xenterprise import client  # optional HTTP to the vendor
+
+v = xenterprise.validate(
+    token,                 # the RS256 JWT issued by license_manager
+    pubkey_pem=vendor_pem, # vendor PUBLIC key (PEM)
+    product_code="CR_EDI", # vendor catalog code
+    now=None,              # datetime | None (naive is read as UTC); None = now
+    last_seen=None,        # datetime | None, anti-rollback high-water mark
+    issuer=DEFAULT_ISSUER, # "vauxoo-license"
+    leeway=300,            # seconds of clock tolerance
+    blocked=False,         # True if a vendor revoke/expired verdict is persisted
+)
+
+if v.ok:            # True iff v.state in {"valid", "grace"}
+    ...             # deliver the gated value
+else:
+    raise SomeError(v.reason)
+```
+
+`validate` never raises for a license outcome and never does network I/O. It
+returns a `Verdict`:
+
+| field       | type                                               | notes                                   |
+|-------------|----------------------------------------------------|-----------------------------------------|
+| `.state`    | `valid` / `grace` / `expired` / `revoked` / `invalid` |                                      |
+| `.ok`       | `bool`                                             | `True` iff `state in {valid, grace}`    |
+| `.term_end` | `date \| None`                                     | product subscription end (`None` = perpetual) |
+| `.mode`     | `production` / `sandbox` / `None`                  | `None` when the token did not decode    |
+| `.claims`   | `dict`                                             | the decoded JWT claims (empty if undecodable) |
+| `.reason`   | `str`                                              | human-readable explanation              |
+
+### State semantics (identical to `base_license`)
+
+- **valid** — signature, issuer, required claims and mode check out; the token
+  is not past its `exp`; the product is granted and its `term_end` is in the
+  future (or perpetual).
+- **grace** — the token is past `exp` but still inside the `grace` window
+  (`grace` days from the token). Keep working; refresh when the vendor is
+  reachable.
+- **expired** — the product subscription `term_end` is in the past.
+- **revoked** — definitive. Produced from `blocked=True` (a persisted vendor
+  `revoked`/`expired` verdict) or `Verdict.revoked(...)`. Checked first, before
+  any decode.
+- **invalid** — missing/malformed token, bad signature, wrong issuer, missing
+  required claim, unknown mode, product not granted, clock rolled back, or the
+  token is expired **past** its grace window.
+
+### Binding (`aud` / `hwid`)
+
+`validate` deliberately does **not** check the production `aud`/`hwid` binding,
+because those identifiers are install-specific. The decoded `claims` are
+returned so an integrator can enforce binding with the identifiers it owns
+(e.g. compare `claims["aud"]` to the database uuid and `claims["hwid"]` to
+`compute_hwid(secret)`).
+
+### Optional HTTP client
+
+```python
+from xenterprise import client
+
+body = client.activate(server_url, key, database_uuid=..., hwid=...)
+body = client.refresh(server_url, key=..., database_uuid=...)
+token = client.interpret_response(body)   # raises LicenseRevoked / LicenseInvalid
+```
+
+The client returns the raw vendor body (`{"ok": ..., "token"/"error": ...}`)
+with a short timeout; `interpret_response` maps `revoked`/`expired` to
+`LicenseRevoked` (definitive) and any other error code to `LicenseInvalid`
+(soft — the vendor being unreachable must leave you in grace, never read as a
+revocation). Plain `http://` is refused unless `require_https=False`.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[test]"
+ruff check .
+pytest
+python -m build        # wheel + sdist in dist/
+```
+
+## License
+
+Odoo Proprietary License v1.0 (OPL-1). See `LICENSE`.

xenterprise-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xenterprise"
+version = "0.1.0"
+description = "Offline validation of Vauxoo RS256-JWT license tokens (base_license client, no Odoo)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-OPL-1"
+license-files = ["LICENSE"]
+authors = [{ name = "Vauxoo", email = "info@vauxoo.com" }]
+keywords = ["license", "jwt", "rs256", "vauxoo", "odoo"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "pyjwt>=2.8,<3",
+    "cryptography",
+    "requests",
+]
+
+[project.urls]
+Homepage = "https://www.vauxoo.com"
+Source = "https://git.vauxoo.com/vauxoo/xenterprise"
+
+[project.optional-dependencies]
+test = ["pytest>=7", "ruff"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

xenterprise-0.1.0/setup.cfg

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

xenterprise-0.1.0/src/xenterprise/__init__.py

@@ -0,0 +1,55 @@
+"""xenterprise: offline validation of Vauxoo RS256-JWT license tokens.
+
+Pure-Python client library extracted from the Vauxoo ``base_license`` Odoo
+module. A proprietary module gates itself by listing ``xenterprise`` in
+``external_dependencies.python`` and calling :func:`validate` with the vendor
+public key; the signing server (``license_manager``) is unchanged.
+
+Public API::
+
+    import xenterprise
+    from xenterprise import (
+        validate, Verdict,
+        LicenseError, LicenseInvalid, LicenseRevoked,
+        obfuscate_token, deobfuscate_token, compute_hwid,
+        DEFAULT_ISSUER, DEFAULT_SERVER_URL,
+    )
+    from xenterprise import client  # optional HTTP to the vendor
+"""
+
+from . import client
+from .crypto import (
+    CONTACT_INFO,
+    DEFAULT_ISSUER,
+    DEFAULT_SERVER_URL,
+    JWT_LEEWAY,
+    PUBLIC_KEY_PEM_PLACEHOLDER,
+    LicenseError,
+    LicenseInvalid,
+    LicenseRevoked,
+    compute_hwid,
+    deobfuscate_token,
+    obfuscate_token,
+)
+from .validate import Verdict, decode_token, validate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "validate",
+    "Verdict",
+    "decode_token",
+    "client",
+    "LicenseError",
+    "LicenseInvalid",
+    "LicenseRevoked",
+    "obfuscate_token",
+    "deobfuscate_token",
+    "compute_hwid",
+    "DEFAULT_ISSUER",
+    "DEFAULT_SERVER_URL",
+    "JWT_LEEWAY",
+    "CONTACT_INFO",
+    "PUBLIC_KEY_PEM_PLACEHOLDER",
+]

xenterprise-0.1.0/src/xenterprise/client.py

@@ -0,0 +1,128 @@
+"""Optional HTTP client to the vendor license server (pure ``requests``).
+
+This mirrors the HTTP side of ``base_license`` (``_call_server`` /
+``_activate`` / ``_refresh``) with no Odoo. The functions return the RAW vendor
+response body so the caller stays in control; :func:`interpret_response` maps
+that body to the package exceptions exactly as ``base_license`` does.
+
+The vendor API speaks one shape: HTTP 200 with a body of
+``{"ok": true, "token": ...}`` or ``{"ok": false, "error": "<code>"}``. Codes
+are ``invalid_request | forbidden | revoked | expired | rate_limited |
+server_error``. ``revoked`` and ``expired`` are definitive; everything else is
+soft (vendor unreachable -> stay in grace, never read as a revocation).
+"""
+
+import requests
+
+from .crypto import (
+    DEFAULT_SERVER_URL,
+    LicenseInvalid,
+    LicenseRevoked,
+)
+
+# Network timeout (seconds) for every vendor call. Kept short: a slow or down
+# vendor must never hang a user action; grace handling takes over instead.
+HTTP_TIMEOUT = 10
+
+
+def _post(server_url, endpoint, payload, timeout, require_https):
+    """POST ``{"params": payload}`` to ``server_url + endpoint`` and return the
+    parsed body, unwrapping Odoo's jsonrpc ``{"result": ...}`` envelope.
+
+    A non-200 status, a non-JSON or non-dict body is a transport failure and
+    raises ``requests.RequestException`` (vendor unreachable), never a business
+    verdict.
+    """
+    url = server_url.rstrip("/") + endpoint
+    if require_https and not url.lower().startswith("https://"):
+        raise LicenseInvalid("Refusing to contact a non-https license server.")
+    resp = requests.post(url, json={"params": payload}, timeout=timeout)
+    if resp.status_code != 200:
+        raise requests.HTTPError(f"Vendor returned HTTP {resp.status_code}.")
+    try:
+        data = resp.json()
+    except ValueError as err:
+        raise requests.RequestException(
+            f"Vendor returned a non-JSON body: {err}"
+        ) from err
+    if isinstance(data, dict) and "result" in data:
+        data = data["result"]
+    if not isinstance(data, dict):
+        raise requests.RequestException("Vendor returned an unexpected payload.")
+    return data
+
+
+def activate(
+    server_url=DEFAULT_SERVER_URL,
+    key=None,
+    *,
+    database_uuid=None,
+    hwid=None,
+    timeout=HTTP_TIMEOUT,
+    require_https=True,
+    **ctx,
+):
+    """First contact: exchange the license ``key`` for a signed token.
+
+    Returns the raw vendor body, e.g. ``{"ok": True, "token": "<jwt>"}`` or
+    ``{"ok": False, "error": "<code>"}``. Does not raise on a business error;
+    pass the body to :func:`interpret_response` to act on it.
+    """
+    payload = {"key": key, "database_uuid": database_uuid, "hwid": hwid}
+    payload.update(ctx)
+    return _post(server_url, "/v1/activate", payload, timeout, require_https)
+
+
+def refresh(
+    server_url=DEFAULT_SERVER_URL,
+    token=None,
+    *,
+    key=None,
+    database_uuid=None,
+    timeout=HTTP_TIMEOUT,
+    require_https=True,
+    **ctx,
+):
+    """Ask for a fresh token.
+
+    The vendor's ``/v1/refresh`` resolves the install from ``key`` +
+    ``database_uuid`` (the current ``token`` is accepted for call-shape parity
+    and forwarded as ``token`` in the payload, harmless to the server). Returns
+    the raw vendor body, like :func:`activate`.
+    """
+    payload = {"key": key, "database_uuid": database_uuid}
+    if token is not None:
+        payload["token"] = token
+    payload.update(ctx)
+    return _post(server_url, "/v1/refresh", payload, timeout, require_https)
+
+
+def sandbox(
+    server_url=DEFAULT_SERVER_URL,
+    credential=None,
+    *,
+    timeout=HTTP_TIMEOUT,
+    require_https=True,
+    **ctx,
+):
+    """Self-service sandbox: exchange a sandbox ``credential`` for a sandbox
+    token. Returns the raw vendor body, like :func:`activate`."""
+    payload = {"credential": credential}
+    payload.update(ctx)
+    return _post(server_url, "/v1/sandbox", payload, timeout, require_https)
+
+
+def interpret_response(body):
+    """Map a raw vendor body to a token string, or raise.
+
+    - ``error in (revoked, expired)`` -> :class:`~xenterprise.LicenseRevoked`
+      (definitive, blocks even inside grace).
+    - any other ``error`` code -> :class:`~xenterprise.LicenseInvalid` (soft).
+    - otherwise return ``body.get("token")`` (possibly ``None``).
+    """
+    error = body.get("error")
+    if error:
+        if error in ("revoked", "expired"):
+            raise LicenseRevoked(str(error))
+        raise LicenseInvalid(str(error))
+    return body.get("token")

xenterprise-0.1.0/src/xenterprise/crypto.py

@@ -0,0 +1,104 @@
+"""Crypto helpers, constants and exceptions for the xenterprise client.
+
+This module is pure Python (no Odoo imports). It is the extraction of the
+``license_crypto`` module that ships inside the Vauxoo ``base_license`` Odoo
+module, so a proprietary module can validate a vendor-signed license token by
+depending on this PyPI package instead of on the Odoo module.
+
+Security note: on-premise the customer controls the runtime, so the token cache
+obfuscation here is *obfuscation*, not real secrecy. The real protections are
+(a) the RS256 signature verified offline with the vendor public key and (b) the
+OPL-1 contract.
+"""
+
+import base64
+import hashlib
+
+# -----------------------------------------------------------------------------
+# Vendor public key (RS256)
+# -----------------------------------------------------------------------------
+# The vendor (license_manager, running at enterprise.vauxoo.ai) signs tokens
+# with its PRIVATE key. The client validates OFFLINE with the matching PUBLIC
+# key. There is NO production key embedded in this package: the caller passes
+# the vendor public key to :func:`xenterprise.validate` at runtime
+# (``pubkey_pem=...``). The placeholder below is only a clearly-marked default
+# so misconfiguration fails closed instead of trusting an attacker key.
+#
+# !!! PLACEHOLDER -- NOT A REAL KEY !!!
+# Fetch the real public key from ``GET https://enterprise.vauxoo.ai/v1/pubkey``
+# (or from the license_manager settings screen) and pass it at runtime. Never
+# commit a private key here.
+PUBLIC_KEY_PEM_PLACEHOLDER = """-----BEGIN PUBLIC KEY-----
+REPLACE_WITH_VENDOR_PUBLIC_KEY_FROM_license_manager
+-----END PUBLIC KEY-----"""
+
+# Expected ``iss`` claim; tokens with any other issuer are rejected.
+DEFAULT_ISSUER = "vauxoo-license"
+
+# Default vendor endpoint.
+DEFAULT_SERVER_URL = "https://enterprise.vauxoo.ai"
+
+# Leeway (seconds) applied to every time comparison (iat floor, clock rollback,
+# JWT decode) so a small, legitimate clock skew is not treated as an attack.
+JWT_LEEWAY = 300
+
+# Contact shown to the user when a license is invalid.
+CONTACT_INFO = (
+    "Please contact Vauxoo to renew or activate your license: "
+    "ventas@vauxoo.com / https://www.vauxoo.com"
+)
+
+
+class LicenseError(Exception):
+    """Base error for license validation failures."""
+
+
+class LicenseInvalid(LicenseError):
+    """Token is missing, malformed, badly signed, bound to another install,
+    expired past its grace window, or the product is not granted."""
+
+
+class LicenseRevoked(LicenseError):
+    """The vendor explicitly reported the license as ``revoked`` or ``expired``
+    in the application-level response body (``{"ok": false, "error": ...}``),
+    independent of the HTTP status.
+
+    This verdict is definitive: it blocks immediately, even inside the grace
+    window, and should be persisted by the caller so it survives a restart.
+    A bare HTTP 403 (WAF/proxy) is NOT this: it is a transport failure.
+    """
+
+
+def _fernet_key_from_secret(secret):
+    """Derive a urlsafe-base64 32-byte Fernet key from an arbitrary secret."""
+    digest = hashlib.sha256((secret or "base_license").encode("utf-8")).digest()
+    return base64.urlsafe_b64encode(digest)
+
+
+def obfuscate_token(token, secret):
+    """Encrypt the cached JWT so it is not stored as clear text."""
+    from cryptography.fernet import Fernet
+
+    fernet = Fernet(_fernet_key_from_secret(secret))
+    return fernet.encrypt(token.encode("utf-8")).decode("ascii")
+
+
+def deobfuscate_token(blob, secret):
+    """Reverse of :func:`obfuscate_token`. Returns None on any failure."""
+    if not blob:
+        return None
+    from cryptography.fernet import Fernet, InvalidToken
+
+    fernet = Fernet(_fernet_key_from_secret(secret))
+    try:
+        return fernet.decrypt(blob.encode("ascii")).decode("utf-8")
+    except (InvalidToken, ValueError):
+        return None
+
+
+def compute_hwid(hwid_secret):
+    """Install fingerprint: hash of a random secret persisted on first
+    activation by the caller. The real hardware id is unreliable in containers,
+    so the primary anchor stays the database uuid; this only ties the install
+    secret."""
+    return hashlib.sha256((hwid_secret or "").encode("utf-8")).hexdigest()