memstack-skill-loader 3.5.0__py3-none-any.whl

memstack_skill_loader/license.py

@@ -0,0 +1,409 @@
+"""License validation for MemStack Pro skill gating."""
+
+import asyncio
+import functools
+import getpass
+import hashlib
+import hmac as hmac_mod
+import json
+import os
+import socket
+import sys
+import threading
+import time
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+import httpx
+
+# ---------------------------------------------------------------------------
+# Data types
+# ---------------------------------------------------------------------------
+
+VALIDATE_URL = "https://admin.cwaffiliateinvestments.com/api/licenses/validate"
+LICENSE_FILE = Path.home() / ".memstack" / "license.json"
+GRACE_PERIOD_FILE = Path.home() / ".memstack" / "grace-period.json"
+DISK_CACHE_FILE = Path.home() / ".memstack" / "license-cache.json"
+DISK_CACHE_MAX_AGE = 24 * 60 * 60  # 24 hours in seconds
+HTTP_TIMEOUT = 5.0  # seconds
+MAX_KEY_LEN = 256
+GRACE_PERIOD_DAYS = 3
+
+# Skills that require a Pro license. Free-tier users see a locked message.
+PRO_EXCLUSIVE_SKILLS = frozenset({"consolidate", "context-db", "api-docs", "branching", "multi-agent", "codebase-index", "doc-index", "diagram-generator", "browser-use", "session-restore", "drift-detection", "mcp-builder", "claude-api-helper", "test-generator", "log-analyzer", "performance-profiler", "dependency-auditor", "git-worktrees", "error-handler", "web-scraper", "advanced-security", "env-manager-pro", "hooks-integration", "developer-growth-analysis", "gtm-validator", "meeting-insights-analyzer", "model-router", "rag-builder", "video-pipeline"})
+
+
+@dataclass
+class LicenseStatus:
+    valid: bool
+    tier: str
+    cached_at: float  # time.time() when this entry was cached
+    grace_period: bool = False  # True if access granted via grace period
+    grace_days_remaining: int = 0
+    grace_expired: bool = False  # True only when grace period has ended
+    grace_tampered: bool = False  # True if HMAC integrity check failed
+
+
+def is_pro_exclusive(skill_name: str) -> bool:
+    """Return True if *skill_name* requires a Pro license."""
+    return skill_name.lower() in PRO_EXCLUSIVE_SKILLS
+
+
+# ---------------------------------------------------------------------------
+# In-memory cache: {license_key: (LicenseStatus, expires_at)}
+# Per-key locks prevent duplicate API calls from concurrent requests.
+# ---------------------------------------------------------------------------
+
+_cache: dict[str, tuple[LicenseStatus, float]] = {}
+_locks: dict[str, asyncio.Lock] = {}
+_session_validated: set[str] = set()  # keys validated this session
+
+
+def _get_lock(key: str) -> asyncio.Lock:
+    """Return a per-key asyncio.Lock, creating one if needed."""
+    if key not in _locks:
+        _locks[key] = asyncio.Lock()
+    return _locks[key]
+
+
+def clear_cache(key: str | None = None) -> None:
+    """Remove cached license status.
+
+    Pass *key* to clear a single entry, or ``None`` to clear all.
+    """
+    if key is None:
+        _cache.clear()
+        _session_validated.clear()
+    else:
+        _cache.pop(key, None)
+        _session_validated.discard(key)
+
+
+def _save_disk_cache(key: str, status: LicenseStatus) -> None:
+    """Persist license validation result to disk with a timestamp."""
+    try:
+        DISK_CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        DISK_CACHE_FILE.write_text(
+            json.dumps({
+                "license_key": key,
+                "valid": status.valid,
+                "tier": status.tier,
+                "timestamp": time.time(),
+            }, indent=2),
+            encoding="utf-8",
+        )
+    except OSError as exc:
+        print(f"[license] failed to write disk cache: {exc}", file=sys.stderr)
+
+
+def _load_disk_cache(key: str) -> LicenseStatus | None:
+    """Load cached license result from disk if it exists and is < 24hrs old."""
+    try:
+        if not DISK_CACHE_FILE.exists():
+            return None
+        data = json.loads(DISK_CACHE_FILE.read_text(encoding="utf-8"))
+        if data.get("license_key") != key:
+            return None
+        cached_time = data.get("timestamp", 0)
+        age = time.time() - cached_time
+        if age > DISK_CACHE_MAX_AGE:
+            print("[license] disk cache expired (>24hrs)", file=sys.stderr)
+            return None
+        return LicenseStatus(
+            valid=bool(data.get("valid", False)),
+            tier=data.get("tier", "free"),
+            cached_at=cached_time,
+        )
+    except (OSError, json.JSONDecodeError, ValueError) as exc:
+        print(f"[license] failed to read disk cache: {exc}", file=sys.stderr)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# HMAC helpers — machine-tied tamper detection for grace period file.
+# ---------------------------------------------------------------------------
+
+
+@functools.lru_cache(maxsize=None)
+def _machine_secret() -> bytes:
+    """Derive a machine-specific secret from hostname + username."""
+    try:
+        username = os.getlogin()
+    except OSError:
+        username = getpass.getuser()
+    identity = f"{socket.gethostname()}{username}"
+    return hmac_mod.new(
+        b"memstack-grace-v1", identity.encode("utf-8"), hashlib.sha256
+    ).digest()
+
+
+@functools.lru_cache(maxsize=None)
+def _machine_id() -> str:
+    """Generate a stable machine fingerprint for license binding."""
+    try:
+        username = os.getlogin()
+    except OSError:
+        username = getpass.getuser()
+    raw = f"{socket.gethostname()}-{username}-{sys.platform}"
+    return hashlib.sha256(raw.encode()).hexdigest()[:32]
+
+
+def _compute_hmac(first_run_str: str) -> str:
+    """Compute HMAC-SHA256 hex digest for a first_run date string."""
+    return hmac_mod.new(
+        _machine_secret(), first_run_str.encode("utf-8"), hashlib.sha256
+    ).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# Grace period helpers — cached in-memory, refreshed daily.
+# Uses a threading lock (not asyncio) since file I/O is synchronous.
+# ---------------------------------------------------------------------------
+
+_grace_lock = threading.Lock()
+_grace_cache: tuple[bool, int, str, bool] | None = None
+# (allowed, days_remaining, date_str, tampered)
+
+
+def _get_grace_period_status() -> tuple[bool, int, bool]:
+    """Check the 3-day grace period for users without a license key.
+
+    Returns (is_active, days_remaining, tampered).
+    - is_active=True, days_remaining>0: grace period still active
+    - is_active=False, days_remaining<=0: grace period expired
+    - tampered=True: HMAC integrity check failed
+    """
+    global _grace_cache
+
+    today_str = date.today().isoformat()
+
+    # Check in-memory cache — valid if same calendar day
+    if _grace_cache is not None:
+        cached_allowed, cached_remaining, cached_date, cached_tampered = _grace_cache
+        if cached_date == today_str:
+            return (cached_allowed, cached_remaining, cached_tampered)
+
+    with _grace_lock:
+        # Double-check after acquiring lock
+        if _grace_cache is not None:
+            cached_allowed, cached_remaining, cached_date, cached_tampered = _grace_cache
+            if cached_date == today_str:
+                return (cached_allowed, cached_remaining, cached_tampered)
+
+        try:
+            if GRACE_PERIOD_FILE.exists():
+                data = json.loads(GRACE_PERIOD_FILE.read_text(encoding="utf-8"))
+                first_run_str = data["first_run"]
+
+                if "hmac" in data:
+                    # Verify HMAC
+                    expected = _compute_hmac(first_run_str)
+                    if not hmac_mod.compare_digest(data["hmac"], expected):
+                        print(
+                            "[license] grace period HMAC mismatch — tampered",
+                            file=sys.stderr,
+                        )
+                        _grace_cache = (False, 0, today_str, True)
+                        return (False, 0, True)
+                else:
+                    # Legacy file without HMAC — migrate by rewriting with HMAC
+                    print(
+                        "[license] migrating legacy grace-period.json (adding HMAC)",
+                        file=sys.stderr,
+                    )
+                    data["hmac"] = _compute_hmac(first_run_str)
+                    GRACE_PERIOD_FILE.write_text(
+                        json.dumps(data, indent=2), encoding="utf-8"
+                    )
+                    try:
+                        os.chmod(GRACE_PERIOD_FILE, 0o600)
+                    except OSError:
+                        pass
+
+                first_run = date.fromisoformat(first_run_str)
+            else:
+                # First run — create the grace period file with HMAC
+                first_run = date.today()
+                first_run_str = first_run.isoformat()
+                file_data = {
+                    "first_run": first_run_str,
+                    "hmac": _compute_hmac(first_run_str),
+                }
+                GRACE_PERIOD_FILE.parent.mkdir(parents=True, exist_ok=True)
+                GRACE_PERIOD_FILE.write_text(
+                    json.dumps(file_data, indent=2), encoding="utf-8"
+                )
+                try:
+                    os.chmod(GRACE_PERIOD_FILE, 0o600)
+                except OSError:
+                    pass
+                print(
+                    f"[license] grace period started: {first_run_str}",
+                    file=sys.stderr,
+                )
+
+            elapsed = (date.today() - first_run).days
+            remaining = max(GRACE_PERIOD_DAYS - elapsed, 0)
+            allowed = remaining > 0
+
+            _grace_cache = (allowed, remaining, today_str, False)
+            return (allowed, remaining, False)
+        except (json.JSONDecodeError, KeyError, ValueError, OSError) as exc:
+            print(f"[license] grace period check failed: {exc}", file=sys.stderr)
+            _grace_cache = (False, 0, today_str, False)
+            return (False, 0, False)
+
+
+# ---------------------------------------------------------------------------
+# License key helpers
+# ---------------------------------------------------------------------------
+
+
+def get_license_key() -> str | None:
+    """Read the license key from env var or ~/.memstack/license.json."""
+    key = os.environ.get("MEMSTACK_PRO_LICENSE_KEY")
+    if key:
+        return key.strip()
+
+    if LICENSE_FILE.exists():
+        try:
+            data = json.loads(LICENSE_FILE.read_text(encoding="utf-8"))
+            k = data.get("license_key", "")
+            if k:
+                return k.strip()
+        except (json.JSONDecodeError, OSError) as exc:
+            print(f"[license] failed to read {LICENSE_FILE}: {exc}", file=sys.stderr)
+
+    return None
+
+
+def save_license_key(key: str) -> None:
+    """Persist *key* to ~/.memstack/license.json with restricted permissions."""
+    LICENSE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    LICENSE_FILE.write_text(
+        json.dumps({"license_key": key}, indent=2),
+        encoding="utf-8",
+    )
+    try:
+        os.chmod(LICENSE_FILE, 0o600)
+    except OSError:
+        pass
+    print(f"[license] saved key to {LICENSE_FILE}", file=sys.stderr)
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+
+async def validate_license(
+    license_key: str | None = None,
+    email: str | None = None,
+) -> LicenseStatus:
+    """Validate a MemStack Pro license key.
+
+    Resolution order for the key:
+      1. Explicit *license_key* argument
+      2. MEMSTACK_PRO_LICENSE_KEY env var
+      3. ~/.memstack/license.json
+      4. If none found, check 14-day grace period
+
+    *email* is forwarded to the API for contact tracking but does not
+    affect caching — the cache key is the license key alone.
+
+    Returns a cached result when the cache is still fresh.
+    """
+    key = license_key or get_license_key()
+    if not key:
+        # No key — check grace period
+        grace_active, days_remaining, tampered = _get_grace_period_status()
+
+        if tampered:
+            return LicenseStatus(
+                valid=False, tier="free", cached_at=0, grace_tampered=True
+            )
+
+        if grace_active:
+            print(
+                f"[license] grace period active: {days_remaining} days remaining",
+                file=sys.stderr,
+            )
+            return LicenseStatus(
+                valid=True,
+                tier="pro",
+                cached_at=time.time(),
+                grace_period=True,
+                grace_days_remaining=days_remaining,
+            )
+        # Grace expired
+        return LicenseStatus(
+            valid=False, tier="free", cached_at=0, grace_expired=True
+        )
+
+    # Basic format check
+    if len(key) > MAX_KEY_LEN or not key.strip():
+        return LicenseStatus(valid=False, tier="free", cached_at=0)
+
+    async with _get_lock(key):
+        return await _validate_locked(key, email)
+
+
+async def _validate_locked(key: str, email: str | None) -> LicenseStatus:
+    """Inner validation, called while holding the per-key lock.
+
+    - First call per session: always hits the API.
+    - Subsequent calls in the same session: return in-memory result.
+    - If API is unreachable: fall back to disk cache (< 24hrs old).
+    - If disk cache is stale/missing and API is unreachable: deny access.
+    """
+    now = time.time()
+
+    # Within a session, reuse the in-memory result (don't re-validate)
+    if key in _session_validated and key in _cache:
+        cached_status, _ = _cache[key]
+        return cached_status
+
+    # --- build request body ---
+    body_payload: dict[str, str] = {"license_key": key, "machine_id": _machine_id()}
+    if email:
+        body_payload["email"] = email
+
+    # --- always call API on session start ---
+    try:
+        async with httpx.AsyncClient(timeout=HTTP_TIMEOUT) as client:
+            resp = await client.post(VALIDATE_URL, json=body_payload)
+            resp.raise_for_status()
+            body = resp.json()
+    except httpx.HTTPStatusError as exc:
+        print(f"[license] HTTP {exc.response.status_code}: {exc}", file=sys.stderr)
+        status = LicenseStatus(valid=False, tier="free", cached_at=now)
+        _cache[key] = (status, now + 60)
+        _session_validated.add(key)
+        return status
+    except (httpx.HTTPError, json.JSONDecodeError, ValueError) as exc:
+        print(f"[license] network error: {exc}", file=sys.stderr)
+        # API unreachable — fall back to disk cache if < 24hrs old
+        disk_status = _load_disk_cache(key)
+        if disk_status is not None:
+            print("[license] using disk cache fallback", file=sys.stderr)
+            _cache[key] = (disk_status, now + 3600)
+            _session_validated.add(key)
+            return disk_status
+        # No valid disk cache — deny access
+        status = LicenseStatus(valid=False, tier="free", cached_at=now)
+        _cache[key] = (status, now + 60)
+        _session_validated.add(key)
+        return status
+
+    valid = bool(body.get("valid", False))
+    tier = body.get("tier", "free") if valid else "free"
+
+    status = LicenseStatus(valid=valid, tier=tier, cached_at=now)
+    _cache[key] = (status, now + 86400)  # session-long in-memory cache
+    _session_validated.add(key)
+
+    # Persist to disk for offline fallback
+    _save_disk_cache(key, status)
+
+    return status

memstack_skill_loader/search.py

@@ -0,0 +1,164 @@
+"""Semantic search against the LanceDB skill index."""
+
+import os
+import sys
+from pathlib import Path
+
+import lancedb
+
+from .config import Config, load_config
+
+_model = None
+_db = None
+_table = None
+
+
+def _get_model(config: Config):
+    """Lazy-load the sentence-transformers model."""
+    global _model
+    if _model is None:
+        from sentence_transformers import SentenceTransformer
+        _model = SentenceTransformer(config.embedding_model)
+    return _model
+
+
+def warmup_model(config: Config):
+    """Pre-load the embedding model into memory. Call from a background thread at startup."""
+    cache_dir = os.environ.get("HF_HOME") or os.environ.get(
+        "TRANSFORMERS_CACHE", os.path.join(Path.home(), ".cache", "huggingface")
+    )
+    print(f"HuggingFace cache directory: {cache_dir}", file=sys.stderr)
+    print(f"Loading embedding model '{config.embedding_model}' in background...", file=sys.stderr)
+    try:
+        _get_model(config)
+        print("Embedding model loaded and ready.", file=sys.stderr)
+    except Exception as e:
+        print(f"Background model warmup failed: {e}", file=sys.stderr)
+
+
+def _get_table(config: Config):
+    """Get the LanceDB skills table, return None if not indexed yet."""
+    global _db, _table
+    if _table is None:
+        db_path = str(config.resolved_vector_db_path)
+        if not Path(db_path).exists():
+            return None
+        _db = lancedb.connect(db_path)
+        try:
+            _table = _db.open_table("skills")
+        except Exception:
+            return None
+    return _table
+
+
+def reset_cache():
+    """Reset cached db/table/model. Call after reindexing."""
+    global _db, _table, _model
+    _db = None
+    _table = None
+    _model = None
+
+
+def search_skills(query: str, config: Config | None = None, top_k: int | None = None) -> list[dict]:
+    """Semantic search for skills matching the query.
+
+    Returns list of dicts with: name, description, source_label, content, score
+    """
+    if config is None:
+        config = load_config()
+    if top_k is None:
+        top_k = config.default_top_k
+
+    table = _get_table(config)
+    if table is None:
+        return []
+
+    model = _get_model(config)
+    query_vector = model.encode(query).tolist()
+
+    results = (
+        table.search(query_vector)
+        .metric("cosine")
+        .limit(top_k)
+        .to_pandas()
+    )
+
+    skills = []
+    for _, row in results.iterrows():
+        # Cosine distance is 0-2; convert to similarity 0-1
+        distance = row.get("_distance", 0)
+        similarity = round(max(0, 1 - distance), 4)
+        skills.append({
+            "name": row["name"],
+            "description": row["description"],
+            "source_label": row["source_label"],
+            "content": row["content"],
+            "filepath": row["filepath"],
+            "score": similarity,
+        })
+
+    return skills
+
+
+def list_all_skills(config: Config | None = None) -> list[dict]:
+    """Return all indexed skills (name + description only, no content)."""
+    if config is None:
+        config = load_config()
+
+    table = _get_table(config)
+    if table is None:
+        return []
+
+    df = table.to_pandas()
+    skills = []
+    for _, row in df.iterrows():
+        skills.append({
+            "name": row["name"],
+            "description": row["description"],
+            "source_label": row["source_label"],
+        })
+
+    return sorted(skills, key=lambda s: s["name"])
+
+
+def get_skill_by_name(name: str, config: Config | None = None) -> dict | None:
+    """Get a skill by exact or fuzzy name match."""
+    if config is None:
+        config = load_config()
+
+    table = _get_table(config)
+    if table is None:
+        return None
+
+    df = table.to_pandas()
+    name_lower = name.lower().replace("-", " ").replace("_", " ")
+
+    # Exact match first
+    for _, row in df.iterrows():
+        if row["name"].lower() == name_lower:
+            return {
+                "name": row["name"],
+                "description": row["description"],
+                "source_label": row["source_label"],
+                "content": row["content"],
+                "filepath": row["filepath"],
+            }
+
+    # Fuzzy: check if query is substring of name or name is substring of query
+    for _, row in df.iterrows():
+        row_name_lower = row["name"].lower()
+        if name_lower in row_name_lower or row_name_lower in name_lower:
+            return {
+                "name": row["name"],
+                "description": row["description"],
+                "source_label": row["source_label"],
+                "content": row["content"],
+                "filepath": row["filepath"],
+            }
+
+    # Last resort: semantic search with top_k=1
+    results = search_skills(name, config, top_k=1)
+    if results and results[0]["score"] > 0.5:
+        return results[0]
+
+    return None