exolimbs 0.4.0__tar.gz

exolimbs-0.4.0/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 seanyang1983
+
+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.
+
+-------------------------------------------------------------------------------
+THIRD-PARTY NOTICES
+
+This project is a compatibility bridge. It does NOT bundle or redistribute
+OpenClaw. When the CLI backend is used, it invokes a user-installed `openclaw`
+binary. OpenClaw is distributed under the MIT License, Copyright (c) 2025
+Peter Steinberger / OpenClaw Foundation. "OpenClaw", "ClawHub" and related marks
+belong to their respective owners; this project is not affiliated with or
+endorsed by them. If you choose to redistribute any OpenClaw components, you must
+include their MIT license and attribution.

exolimbs-0.4.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: exolimbs
+Version: 0.4.0
+Summary: Run ClawHub skills, sandbox, Playwright browser & multi-language runtimes as Hermes hands/feet. Structured JSON, zero extra LLM tokens.
+Author-email: seanyang1983 <yase19636404@163.com>
+License: MIT
+Project-URL: Homepage, https://github.com/seanyang1983/exolimbs
+Project-URL: Issues, https://github.com/seanyang1983/exolimbs/issues
+Project-URL: Store, https://your-store.example.com
+Keywords: hermes,openclaw,clawhub,agent,sandbox,playwright,skills
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: browser
+Requires-Dist: playwright<2,>=1.44; extra == "browser"
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Dynamic: license-file
+
+# Exolimbs — Hermes plugin
+
+> Give your Hermes agent OpenClaw / ClawHub's hands and feet.
+> Run community skills, an isolated sandbox, a Playwright browser, and
+> multi-language runtimes — through a tiny structured-JSON tool surface, with
+> **zero extra LLM tokens** on the execution path.
+
+Hermes is the brain. Exolimbs is the deterministic execution substrate. It
+never calls a model itself, has no conversation/memory/UI, and exposes six tools.
+
+> ℹ️ "Exolimbs" is the working title. **Rename before any commercial
+> launch** — see `DESIGN.md` → *Naming & legal*. The package, plugin name, and
+> entry point are all in one place each, so renaming is a 5-minute job.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `claw_skill_search` | Search the ClawHub registry |
+| `claw_skill_install` | Install + verify a skill (slug / `git:owner/repo@ref` / local path) |
+| `claw_skill_run` | Deterministically run a skill's script entrypoint |
+| `claw_sandbox_exec` | Run a command in an isolated (Docker) sandbox with rollback |
+| `claw_browser` | Playwright browser automation via a structured action list |
+| `claw_runtime` | Quick snippet in python / node / bash / ruby / go |
+
+## Two interchangeable backends
+
+Set `exolimbs.backend` in `~/.hermes/config.yaml` (or `EXOLIMBS_BACKEND`):
+
+| Mode | Behaviour |
+|------|-----------|
+| `cli` | Bridges to the real `openclaw` / `clawhub` CLIs (`--non-interactive --json`). Best registry parity. Requires Node + OpenClaw installed. |
+| `native` | Fully decoupled Python substrate. No Node needed. Handles sandbox/browser/runtime + `git:`/local skill installs natively. |
+| `auto` (default) | `cli` if the `openclaw` binary is on PATH, else `native`. |
+
+## Install
+
+**As a directory plugin (simplest):**
+
+```bash
+# copy the package into your Hermes plugins dir
+cp -r exolimbs ~/.hermes/plugins/exolimbs
+hermes plugins enable exolimbs
+```
+
+**As a pip package (distribution):**
+
+```bash
+pip install exolimbs           # core
+pip install "exolimbs[browser]" # + Playwright
+playwright install chromium          # one-time browser download
+hermes plugins enable exolimbs
+```
+
+Verify inside a session:
+
+```
+/exo doctor
+```
+
+## Configure (`~/.hermes/config.yaml`)
+
+```yaml
+exolimbs:
+  backend: auto            # auto | cli | native
+  sandbox_enabled: true
+  sandbox_image: "python:3.12-slim"
+  sandbox_network: false
+  default_timeout_s: 120
+  max_retries: 2
+  rollback: true
+  registry_base_url: "https://clawhub.ai"
+  browser_headless: true
+  # Pro:
+  audit_log: false
+  # license_key: "EXL1...."   # or set EXOLIMBS_LICENSE in .env
+```
+
+## Free vs Pro (open-core)
+
+- **Free:** all six tools, both backends, retry/rollback, trust-envelope verify.
+- **Pro:** JSONL audit log, curated/verified skill packs, auto-update, priority
+  support. Unlock with `EXOLIMBS_LICENSE`. See `DESIGN.md` for pricing/channels.
+
+Licenses are signed **Ed25519** tokens (`EXL1.<payload>.<signature>`), verified
+fully **offline** against an embedded public key — no phone-home, air-gap safe.
+
+**Issuing licenses (vendor-side only):**
+
+```bash
+python scripts/gen_keys.py                 # once: make keypair (seed -> .secrets/, git-ignored)
+                                           # paste printed public key into exolimbs/_licensing.py
+python scripts/issue_license.py --sub alice@example.com --tier pro --days 365
+# -> prints EXL1.<...> ; customer sets EXOLIMBS_LICENSE to that token
+```
+
+Revoke an issued license by adding its `jti` to `_REVOKED` in `_licensing.py` and
+shipping a release.
+
+## Security
+
+Third-party skills are untrusted code. Prefer `claw_sandbox_exec` with
+`network: false` for anything you don't fully trust. Without Docker, sandbox
+calls run locally and are flagged `"sandboxed": false`.
+
+## Development
+
+```bash
+pip install -e ".[dev,browser]"
+pytest -q
+```
+
+## License
+
+MIT (this plugin). Not affiliated with OpenClaw/ClawHub. See `LICENSE`.

exolimbs-0.4.0/README.md

@@ -0,0 +1,115 @@
+# Exolimbs — Hermes plugin
+
+> Give your Hermes agent OpenClaw / ClawHub's hands and feet.
+> Run community skills, an isolated sandbox, a Playwright browser, and
+> multi-language runtimes — through a tiny structured-JSON tool surface, with
+> **zero extra LLM tokens** on the execution path.
+
+Hermes is the brain. Exolimbs is the deterministic execution substrate. It
+never calls a model itself, has no conversation/memory/UI, and exposes six tools.
+
+> ℹ️ "Exolimbs" is the working title. **Rename before any commercial
+> launch** — see `DESIGN.md` → *Naming & legal*. The package, plugin name, and
+> entry point are all in one place each, so renaming is a 5-minute job.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `claw_skill_search` | Search the ClawHub registry |
+| `claw_skill_install` | Install + verify a skill (slug / `git:owner/repo@ref` / local path) |
+| `claw_skill_run` | Deterministically run a skill's script entrypoint |
+| `claw_sandbox_exec` | Run a command in an isolated (Docker) sandbox with rollback |
+| `claw_browser` | Playwright browser automation via a structured action list |
+| `claw_runtime` | Quick snippet in python / node / bash / ruby / go |
+
+## Two interchangeable backends
+
+Set `exolimbs.backend` in `~/.hermes/config.yaml` (or `EXOLIMBS_BACKEND`):
+
+| Mode | Behaviour |
+|------|-----------|
+| `cli` | Bridges to the real `openclaw` / `clawhub` CLIs (`--non-interactive --json`). Best registry parity. Requires Node + OpenClaw installed. |
+| `native` | Fully decoupled Python substrate. No Node needed. Handles sandbox/browser/runtime + `git:`/local skill installs natively. |
+| `auto` (default) | `cli` if the `openclaw` binary is on PATH, else `native`. |
+
+## Install
+
+**As a directory plugin (simplest):**
+
+```bash
+# copy the package into your Hermes plugins dir
+cp -r exolimbs ~/.hermes/plugins/exolimbs
+hermes plugins enable exolimbs
+```
+
+**As a pip package (distribution):**
+
+```bash
+pip install exolimbs           # core
+pip install "exolimbs[browser]" # + Playwright
+playwright install chromium          # one-time browser download
+hermes plugins enable exolimbs
+```
+
+Verify inside a session:
+
+```
+/exo doctor
+```
+
+## Configure (`~/.hermes/config.yaml`)
+
+```yaml
+exolimbs:
+  backend: auto            # auto | cli | native
+  sandbox_enabled: true
+  sandbox_image: "python:3.12-slim"
+  sandbox_network: false
+  default_timeout_s: 120
+  max_retries: 2
+  rollback: true
+  registry_base_url: "https://clawhub.ai"
+  browser_headless: true
+  # Pro:
+  audit_log: false
+  # license_key: "EXL1...."   # or set EXOLIMBS_LICENSE in .env
+```
+
+## Free vs Pro (open-core)
+
+- **Free:** all six tools, both backends, retry/rollback, trust-envelope verify.
+- **Pro:** JSONL audit log, curated/verified skill packs, auto-update, priority
+  support. Unlock with `EXOLIMBS_LICENSE`. See `DESIGN.md` for pricing/channels.
+
+Licenses are signed **Ed25519** tokens (`EXL1.<payload>.<signature>`), verified
+fully **offline** against an embedded public key — no phone-home, air-gap safe.
+
+**Issuing licenses (vendor-side only):**
+
+```bash
+python scripts/gen_keys.py                 # once: make keypair (seed -> .secrets/, git-ignored)
+                                           # paste printed public key into exolimbs/_licensing.py
+python scripts/issue_license.py --sub alice@example.com --tier pro --days 365
+# -> prints EXL1.<...> ; customer sets EXOLIMBS_LICENSE to that token
+```
+
+Revoke an issued license by adding its `jti` to `_REVOKED` in `_licensing.py` and
+shipping a release.
+
+## Security
+
+Third-party skills are untrusted code. Prefer `claw_sandbox_exec` with
+`network: false` for anything you don't fully trust. Without Docker, sandbox
+calls run locally and are flagged `"sandboxed": false`.
+
+## Development
+
+```bash
+pip install -e ".[dev,browser]"
+pytest -q
+```
+
+## License
+
+MIT (this plugin). Not affiliated with OpenClaw/ClawHub. See `LICENSE`.

exolimbs-0.4.0/exolimbs/__init__.py

@@ -0,0 +1,113 @@
+"""Exolimbs — Hermes plugin.
+
+Turns OpenClaw / ClawHub's mature execution substrate (skill registry, local
+sandbox, Playwright browser automation, multi-language runtimes, retry/rollback)
+into a set of structured-JSON tools for Hermes.
+
+Design:
+- Hermes is the brain (LLM/conversation/memory/UI).
+- Exolimbs is the hands/feet (deterministic execution). It NEVER calls an
+  LLM itself -> zero extra model tokens on the execution path.
+- Two interchangeable backends, switchable via config:
+    * "cli"    -> shells out to the real `openclaw` / `clawhub` CLIs.
+    * "native" -> a decoupled Python re-implementation (no Node dependency).
+    * "auto"   -> cli if the `openclaw` binary is present, else native.
+
+Every tool handler:
+  - has signature `handler(args: dict, **kwargs) -> str`
+  - ALWAYS returns a JSON string (success and error alike)
+  - NEVER raises
+"""
+
+from __future__ import annotations
+
+import logging
+
+from . import schemas, tools
+from .config import get_settings
+
+logger = logging.getLogger(__name__)
+
+__version__ = "0.4.0"
+
+
+def _cli_available() -> bool:
+    """check_fn used to hide CLI-only behaviour gracefully (never raises)."""
+    try:
+        from .backends.cli_backend import openclaw_binary
+
+        return openclaw_binary() is not None
+    except Exception:  # pragma: no cover - defensive
+        return False
+
+
+def _tools_available() -> bool:
+    """Tools are available whenever a backend can be resolved.
+
+    The CLI backend needs the `openclaw` binary; the native backend always
+    resolves. So tools are available unless the user pinned `backend: cli`
+    without installing the CLI.
+    """
+    try:
+        settings = get_settings()
+        if settings.backend == "cli":
+            return _cli_available()
+        return True
+    except Exception:  # pragma: no cover - defensive
+        return True
+
+
+def register(ctx) -> None:
+    """Entry point called once at startup. Wires schemas -> handlers.
+
+    If this function raises, Hermes disables the plugin but keeps running, so we
+    keep it defensive and side-effect-light.
+    """
+    pairs = (
+        ("claw_skill_search", schemas.CLAW_SKILL_SEARCH, tools.claw_skill_search),
+        ("claw_skill_install", schemas.CLAW_SKILL_INSTALL, tools.claw_skill_install),
+        ("claw_skill_run", schemas.CLAW_SKILL_RUN, tools.claw_skill_run),
+        ("claw_sandbox_exec", schemas.CLAW_SANDBOX_EXEC, tools.claw_sandbox_exec),
+        ("claw_browser", schemas.CLAW_BROWSER, tools.claw_browser),
+        ("claw_runtime", schemas.CLAW_RUNTIME, tools.claw_runtime),
+    )
+
+    for name, schema, handler in pairs:
+        ctx.register_tool(
+            name=name,
+            toolset="exolimbs",
+            schema=schema,
+            handler=handler,
+            check_fn=_tools_available,
+        )
+
+    # Ship an opt-in "how to drive me" skill. Not in the system-prompt index,
+    # so it costs zero standing tokens until the agent explicitly loads it.
+    try:
+        from pathlib import Path
+
+        skill_md = Path(__file__).parent / "skills" / "exolimbs" / "SKILL.md"
+        if skill_md.exists():
+            ctx.register_skill("exolimbs", skill_md)
+    except Exception as exc:  # pragma: no cover - optional
+        logger.debug("exolimbs: skill registration skipped: %s", exc)
+
+    # Diagnostics slash command: /exo status
+    try:
+        ctx.register_command(
+            "exo",
+            handler=tools.slash_claw,
+            description="Exolimbs status / backend info",
+            args_hint="[status|backend|doctor]",
+        )
+    except Exception as exc:  # pragma: no cover - optional
+        logger.debug("exolimbs: slash command skipped: %s", exc)
+
+    s = get_settings()
+    logger.info(
+        "exolimbs v%s registered (backend=%s, resolved=%s, pro=%s)",
+        __version__,
+        s.backend,
+        s.resolved_backend(),
+        s.is_pro(),
+    )

exolimbs-0.4.0/exolimbs/_ed25519.py

@@ -0,0 +1,144 @@
+"""Minimal, dependency-free Ed25519 (RFC 8032) for offline license verification.
+
+Adapted from the public-domain reference implementation by the Ed25519 authors
+(https://ed25519.cr.yp.to/software.html). Modular exponentiation uses Python's
+built-in ``pow`` for speed. This is used for one-off, offline signature checks
+(license tokens) — it is NOT constant-time and must not be used to sign secrets
+on adversarial shared hardware. Signing happens vendor-side; verification ships
+to customers with zero third-party dependencies.
+
+Public API:
+    public_from_seed(seed32) -> bytes32
+    sign(message, seed32, public_key=None) -> bytes64
+    verify(signature64, message, public_key32) -> bool
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+_b = 256
+_q = 2**255 - 19
+_l = 2**252 + 27742317777372353535851937790883648493
+
+
+def _H(m: bytes) -> bytes:
+    return hashlib.sha512(m).digest()
+
+
+def _inv(x: int) -> int:
+    return pow(x, _q - 2, _q)
+
+
+_d = -121665 * _inv(121666) % _q
+_I = pow(2, (_q - 1) // 4, _q)
+
+
+def _xrecover(y: int) -> int:
+    xx = (y * y - 1) * _inv(_d * y * y + 1)
+    x = pow(xx, (_q + 3) // 8, _q)
+    if (x * x - xx) % _q != 0:
+        x = (x * _I) % _q
+    if x % 2 != 0:
+        x = _q - x
+    return x
+
+
+_By = 4 * _inv(5) % _q
+_Bx = _xrecover(_By)
+_B = [_Bx % _q, _By % _q]
+
+
+def _edwards(P: list[int], Q: list[int]) -> list[int]:
+    x1, y1 = P
+    x2, y2 = Q
+    x3 = (x1 * y2 + x2 * y1) * _inv(1 + _d * x1 * x2 * y1 * y2)
+    y3 = (y1 * y2 + x1 * x2) * _inv(1 - _d * x1 * x2 * y1 * y2)
+    return [x3 % _q, y3 % _q]
+
+
+def _scalarmult(P: list[int], e: int) -> list[int]:
+    # Iterative double-and-add (avoids deep recursion).
+    result = [0, 1]
+    addend = P
+    while e > 0:
+        if e & 1:
+            result = _edwards(result, addend)
+        addend = _edwards(addend, addend)
+        e >>= 1
+    return result
+
+
+def _bit(h: bytes, i: int) -> int:
+    return (h[i // 8] >> (i % 8)) & 1
+
+
+def _encodeint(y: int) -> bytes:
+    return y.to_bytes(_b // 8, "little")
+
+
+def _encodepoint(P: list[int]) -> bytes:
+    x, y = P
+    val = (y & ((1 << (_b - 1)) - 1)) | ((x & 1) << (_b - 1))
+    return val.to_bytes(_b // 8, "little")
+
+
+def _decodeint(s: bytes) -> int:
+    return int.from_bytes(s, "little")
+
+
+def _Hint(m: bytes) -> int:
+    return _decodeint(_H(m)) % (1 << (2 * _b))
+
+
+def _secret_scalar(seed: bytes) -> int:
+    h = _H(seed)
+    return 2 ** (_b - 2) + sum(2**i * _bit(h, i) for i in range(3, _b - 2))
+
+
+def public_from_seed(seed: bytes) -> bytes:
+    if len(seed) != 32:
+        raise ValueError("seed must be 32 bytes")
+    a = _secret_scalar(seed)
+    return _encodepoint(_scalarmult(_B, a))
+
+
+def sign(message: bytes, seed: bytes, public_key: bytes | None = None) -> bytes:
+    if len(seed) != 32:
+        raise ValueError("seed must be 32 bytes")
+    h = _H(seed)
+    a = _secret_scalar(seed)
+    pk = public_key if public_key is not None else _encodepoint(_scalarmult(_B, a))
+    r = _Hint(h[32:64] + message)
+    R = _scalarmult(_B, r)
+    S = (r + _Hint(_encodepoint(R) + pk + message) * a) % _l
+    return _encodepoint(R) + _encodeint(S)
+
+
+def _isoncurve(P: list[int]) -> bool:
+    x, y = P
+    return (-x * x + y * y - 1 - _d * x * x * y * y) % _q == 0
+
+
+def _decodepoint(s: bytes) -> list[int]:
+    y = _decodeint(s) & ((1 << (_b - 1)) - 1)
+    x = _xrecover(y)
+    if x & 1 != _bit(s, _b - 1):
+        x = _q - x
+    P = [x, y]
+    if not _isoncurve(P):
+        raise ValueError("point not on curve")
+    return P
+
+
+def verify(signature: bytes, message: bytes, public_key: bytes) -> bool:
+    try:
+        if len(signature) != 64 or len(public_key) != 32:
+            return False
+        R = _decodepoint(signature[:32])
+        A = _decodepoint(public_key)
+        S = _decodeint(signature[32:64])
+        h = _Hint(signature[:32] + public_key + message)
+        return _scalarmult(_B, S) == _edwards(R, _scalarmult(A, h))
+    except Exception:
+        return False

exolimbs-0.4.0/exolimbs/_licensing.py

@@ -0,0 +1,132 @@
+"""Open-core licensing gate — real offline Ed25519 verification.
+
+The free tier ships all six execution tools. Pro features (audit log, curated
+skill packs, auto-update, priority support) require a signed license token.
+
+Token format (compact, JWT-like, EdDSA / Ed25519):
+
+    EXL1.<base64url(payload_json)>.<base64url(signature)>
+
+`payload_json` is a UTF-8 JSON object, e.g.:
+
+    {"sub": "alice@example.com", "tier": "pro", "exp": 1771000000,
+     "iat": 1760000000, "jti": "lic_abc123", "features": ["audit", "packs"]}
+
+The signature covers the ASCII bytes of `"EXL1." + base64url(payload)` (the
+header+payload, exactly like JWS). Verification is fully offline against the
+embedded public key — no phone-home, works air-gapped. Revoke issued licenses by
+shipping their `jti` in `_REVOKED` with a release.
+
+Signing happens vendor-side only (see scripts/issue_license.py). The private seed
+never ships and is git-ignored.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from functools import lru_cache
+
+from . import _ed25519
+
+# Vendor Ed25519 public key (hex, 32 bytes). Replace via scripts/gen_keys.py.
+_PUBLIC_KEY_HEX = "0ac58e8a93d3b09dfb5425c31e4f855dbba6b347cc1e4d001a40ba4aed288490"
+
+_PRO_TIERS = frozenset({"pro", "team", "enterprise"})
+_PREFIX = "EXL1"
+
+# License IDs (jti) revoked after issuance. Ship updates with releases.
+_REVOKED: frozenset[str] = frozenset()
+
+
+def _b64url_decode(s: str) -> bytes:
+    pad = "=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode(s + pad)
+
+
+def b64url_encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _public_key() -> bytes:
+    return bytes.fromhex(_PUBLIC_KEY_HEX)
+
+
+def decode_license(token: str) -> dict | None:
+    """Verify signature + structure. Returns the payload dict or None.
+
+    Does NOT check expiry/tier/revocation — see `license_status`.
+    """
+    if not token or not _PUBLIC_KEY_HEX:
+        return None
+    parts = token.strip().split(".")
+    if len(parts) != 3 or parts[0] != _PREFIX:
+        return None
+    _, payload_b64, sig_b64 = parts
+    try:
+        signing_input = f"{_PREFIX}.{payload_b64}".encode("ascii")
+        signature = _b64url_decode(sig_b64)
+        if not _ed25519.verify(signature, signing_input, _public_key()):
+            return None
+        payload = json.loads(_b64url_decode(payload_b64).decode("utf-8"))
+        return payload if isinstance(payload, dict) else None
+    except Exception:
+        return None
+
+
+def license_status(token: str | None) -> dict:
+    """Full evaluation -> {valid, tier, reason, ...}. Never raises."""
+    import os
+
+    token = (token or os.environ.get("EXOLIMBS_LICENSE") or "").strip()
+    if not token:
+        return {"valid": False, "tier": "free", "reason": "no license"}
+    payload = decode_license(token)
+    if payload is None:
+        return {"valid": False, "tier": "free", "reason": "invalid signature"}
+    jti = payload.get("jti")
+    if jti and jti in _REVOKED:
+        return {"valid": False, "tier": "free", "reason": "revoked", "jti": jti}
+    exp = payload.get("exp")
+    if exp is not None and time.time() > float(exp):
+        return {"valid": False, "tier": "free", "reason": "expired", "exp": exp}
+    tier = str(payload.get("tier", "")).lower()
+    if tier not in _PRO_TIERS:
+        return {"valid": False, "tier": tier or "free", "reason": "non-pro tier"}
+    return {
+        "valid": True,
+        "tier": tier,
+        "reason": "ok",
+        "sub": payload.get("sub"),
+        "exp": exp,
+        "features": payload.get("features", []),
+        "jti": jti,
+    }
+
+
+@lru_cache(maxsize=16)
+def is_pro(key: str | None = None) -> bool:
+    return license_status(key)["valid"]
+
+
+def require_pro(feature: str, key: str | None = None) -> dict | None:
+    """Return an error dict if the feature needs Pro and the license is invalid."""
+    if is_pro(key):
+        return None
+    return {
+        "ok": False,
+        "error": f"'{feature}' requires an Exolimbs Pro license",
+        "upgrade": "https://your-store.example.com",
+    }
+
+
+def describe(key: str | None = None) -> str:
+    st = license_status(key)
+    if st["valid"]:
+        exp = st.get("exp")
+        when = time.strftime("%Y-%m-%d", time.gmtime(exp)) if exp else "perpetual"
+        return f"Pro ({st['tier']}, expires {when})"
+    if st["reason"] == "no license":
+        return "Free"
+    return f"Free (license {st['reason']})"