lovstudio-skill-helper 0.1.0__tar.gz

lovstudio_skill_helper-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.env

lovstudio_skill_helper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lovstudio
+
+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.

lovstudio_skill_helper-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: lovstudio-skill-helper
+Version: 0.1.0
+Summary: Lovstudio skill helper — activate and run paid Lovstudio skills locally. Decryption keys never touch disk.
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=42
+Requires-Dist: pyyaml>=6

lovstudio_skill_helper-0.1.0/README.md

@@ -0,0 +1,46 @@
+# lovstudio-skill-helper
+
+CLI helper for Lovstudio paid skills — activate your license and transparently decrypt/run protected skills locally. Decryption keys are fetched per-invocation from the license server and live only in process memory; they never touch disk.
+
+## Install
+
+The canonical way is via [`uv`](https://docs.astral.sh/uv/) — no install step needed, runs on first use:
+
+```bash
+uvx lovstudio-skill-helper activate <license-key>
+```
+
+Or install it persistently:
+
+```bash
+pipx install lovstudio-skill-helper
+```
+
+## Usage
+
+```bash
+# one-time per device
+lovstudio-skill-helper activate <license-key>
+
+# then any paid skill placeholder SKILL.md will call:
+lovstudio-skill-helper decrypt <skill-name>       # print plaintext SKILL.md to stdout
+lovstudio-skill-helper exec <skill-name> <script> # run an encrypted script once
+
+lovstudio-skill-helper status           # show current activation
+lovstudio-skill-helper heartbeat        # refresh last-seen
+lovstudio-skill-helper deactivate       # wipe local license
+```
+
+## How it works
+
+Paid skills ship as AES-256-GCM ciphertext under `~/.claude/skills/<name>/` (or `~/.claude/skills/lovstudio-<name>/`), placed there by `npx skills add ...`. Each call to `decrypt` / `exec`:
+
+1. Signs an HMAC proof with your license key (key itself never leaves the device).
+2. Hits the Lovstudio license server, which verifies the proof, checks entitlement, and returns a per-skill-version AES key.
+3. Decrypts in memory, streams to stdout or a `tempfile.TemporaryDirectory` that is wiped on exit.
+
+License keys are sold via the 手工川 (ShougongChuan) WeChat official account.
+
+## License
+
+MIT.

lovstudio_skill_helper-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lovstudio-skill-helper"
+version = "0.1.0"
+description = "Lovstudio skill helper — activate and run paid Lovstudio skills locally. Decryption keys never touch disk."
+requires-python = ">=3.9"
+dependencies = [
+  "cryptography>=42",
+  "pyyaml>=6",
+]
+
+[project.scripts]
+lovstudio-skill-helper = "lovstudio_skill_helper.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lovstudio_skill_helper"]

lovstudio_skill_helper-0.1.0/src/lovstudio_skill_helper/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

lovstudio_skill_helper-0.1.0/src/lovstudio_skill_helper/api.py

@@ -0,0 +1,123 @@
+"""Signed requests to the Lovstudio licensing Edge Functions.
+
+Protocol mirrors OpenClacky:
+    proof = HMAC_SHA256(license_key, f"{action}:{key_hash}:{user_id}:{device_id}:{timestamp}:{nonce}{extra}")
+
+The license_key itself is NEVER sent over the wire — only key_hash + proof.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import secrets
+import time
+import urllib.error
+import urllib.request
+
+from . import config
+
+
+def hmac_hex(key_hex: str, message: str) -> str:
+    return hmac.new(bytes.fromhex(key_hex), message.encode(), hashlib.sha256).hexdigest()
+
+
+def key_hash(license_key_hex: str) -> str:
+    return hashlib.sha256(bytes.fromhex(license_key_hex)).hexdigest()
+
+
+def parse_user_id_from_key(license_key_hex: str) -> int:
+    """First 8 hex chars of the license key = user_id. Server validates independently."""
+    return int(license_key_hex[:8], 16)
+
+
+def signed_payload(
+    license_key: str,
+    action: str,
+    device_id: str,
+    extra_suffix: str = "",
+    extra_fields: dict | None = None,
+) -> dict:
+    kh = key_hash(license_key)
+    uid = str(parse_user_id_from_key(license_key))
+    ts = str(int(time.time()))
+    nonce = secrets.token_hex(16)
+    msg = f"{action}:{kh}:{uid}:{device_id}:{ts}:{nonce}{extra_suffix}"
+    proof = hmac_hex(license_key, msg)
+    payload = {
+        "key_hash": kh,
+        "user_id": uid,
+        "device_id": device_id,
+        "timestamp": ts,
+        "nonce": nonce,
+        "proof": proof,
+    }
+    if extra_fields:
+        payload.update(extra_fields)
+    return payload
+
+
+class ApiError(RuntimeError):
+    def __init__(self, status: int, message: str):
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.message = message
+
+
+def call(path: str, body: dict, timeout: int = 15) -> dict:
+    req = urllib.request.Request(
+        f"{config.api_base()}/{path}",
+        data=json.dumps(body).encode(),
+        headers={
+            "content-type": "application/json",
+            "authorization": f"Bearer {config.anon_key()}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read())
+    except urllib.error.HTTPError as e:
+        try:
+            err_body = json.loads(e.read()).get("error", "unknown error")
+        except Exception:
+            err_body = "unknown error"
+        raise ApiError(e.code, err_body) from None
+
+
+def activate(license_key: str, device_id: str) -> dict:
+    payload = signed_payload(
+        license_key, "activate", device_id,
+        extra_fields={"device_info": config.device_info()},
+    )
+    return call("activate", payload)
+
+
+def heartbeat(license_key: str, device_id: str) -> dict:
+    return call("heartbeat", signed_payload(license_key, "heartbeat", device_id))
+
+
+def skill_keys(license_key: str, device_id: str, skill_name: str, skill_version: str) -> dict:
+    suffix = f":{skill_name}:{skill_version}"
+    payload = signed_payload(
+        license_key, "skill_keys", device_id,
+        extra_suffix=suffix,
+        extra_fields={"skill_name": skill_name, "skill_version": skill_version},
+    )
+    return call("skill_keys", payload)
+
+
+def list_catalog(timeout: int = 15) -> list[dict]:
+    """Public catalog of all skills (no auth). Returns [{name, category, paid}, ...]."""
+    url = f"{config.rest_base()}/skills?select=name,category,paid"
+    req = urllib.request.Request(
+        url,
+        headers={
+            "apikey": config.anon_key(),
+            "authorization": f"Bearer {config.anon_key()}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read())
+    except urllib.error.HTTPError as e:
+        raise ApiError(e.code, "catalog fetch failed") from None

lovstudio_skill_helper-0.1.0/src/lovstudio_skill_helper/cli.py

@@ -0,0 +1,264 @@
+"""lovstudio-skill-helper CLI — activate, heartbeat, decrypt, exec.
+
+Trust model:
+  - ~/.lovstudio/license.yml holds license_key (chmod 600). Anyone with this
+    file can impersonate the user. Don't share.
+  - Decryption keys are fetched from the server per invocation, used in
+    memory, then die with the process. They are NEVER written to disk.
+  - `exec` decrypts a script to a tmpdir, runs it, then deletes the tmpdir.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from . import api, config
+from .crypto import SkillManifest, decrypt_file
+
+
+_BUY_HINT = "  Buy a license key at https://lovstudio.ai (or follow the 手工川 / ShougongChuan WeChat OA)."
+
+
+def _require_license() -> dict:
+    lic = config.load_license()
+    if not lic:
+        print("error: not activated. run `lovstudio-skill-helper activate <key>` first.", file=sys.stderr)
+        print(_BUY_HINT, file=sys.stderr)
+        sys.exit(2)
+    return lic
+
+
+def cmd_activate(args) -> int:
+    raw = args.key.strip().lower()
+    # Accept the human-friendly "lk-" prefix; the wire protocol uses raw hex.
+    license_key = raw[3:] if raw.startswith("lk-") else raw
+    if len(license_key) != 64 or not all(c in "0123456789abcdef" for c in license_key):
+        print("error: license key must be 64 hex chars (with optional 'lk-' prefix).", file=sys.stderr)
+        return 2
+
+    existing = config.load_license() or {}
+    device_id = existing.get("device_id") or config.generate_device_id()
+
+    try:
+        resp = api.activate(license_key, device_id)
+    except api.ApiError as e:
+        print(f"error: activation failed — {e.message}", file=sys.stderr)
+        print(_BUY_HINT, file=sys.stderr)
+        return 1
+
+    data = {
+        "license_key": license_key,
+        "device_id": device_id,
+        "user_id": resp.get("user_id"),
+        "expires_at": resp.get("expires_at"),
+        "entitled_skills": resp.get("entitled_skills", []),
+        "last_heartbeat_at": None,
+    }
+    config.save_license(data)
+    skills = ", ".join(data["entitled_skills"]) or "(none)"
+    print(f"✓ activated. user_id={data['user_id']} entitled={skills}")
+    return 0
+
+
+def cmd_heartbeat(args) -> int:
+    lic = _require_license()
+    try:
+        resp = api.heartbeat(lic["license_key"], lic["device_id"])
+    except api.ApiError as e:
+        print(f"error: heartbeat failed — {e.message}", file=sys.stderr)
+        return 1
+    lic["expires_at"] = resp.get("expires_at")
+    config.save_license(lic)
+    print(f"✓ heartbeat ok. expires_at={resp.get('expires_at')}")
+    return 0
+
+
+def cmd_status(args) -> int:
+    lic = config.load_license()
+    if not lic:
+        print("not activated.")
+        return 0
+
+    if args.json:
+        redacted = {**lic, "license_key": lic["license_key"][:8] + "…"}
+        print(json.dumps(redacted, indent=2, ensure_ascii=False))
+        return 0
+
+    # License header.
+    key_short = lic["license_key"][:8] + "…"
+    entitled: set[str] = set(lic.get("entitled_skills") or [])
+    print(f"license_key       {key_short}")
+    print(f"device_id         {lic.get('device_id', '—')}")
+    print(f"user_id           {lic.get('user_id', '—')}")
+    print(f"expires_at        {lic.get('expires_at') or '— (no expiry)'}")
+    print(f"last_heartbeat_at {lic.get('last_heartbeat_at') or '—'}")
+    print(f"entitled          {len(entitled)} skill(s)")
+    print()
+
+    # Fetch catalog; fall back to flat list if offline.
+    try:
+        catalog = api.list_catalog()
+    except api.ApiError as e:
+        print(f"(catalog fetch failed — {e.message}; showing flat entitled list)", file=sys.stderr)
+        for name in sorted(entitled):
+            print(f"  [x] {name}")
+        return 0
+
+    # Group by category. `paid` flag tells user whether a skill requires a license at all.
+    by_cat: dict[str, list[dict]] = {}
+    for row in catalog:
+        cat = row.get("category") or "(uncategorized)"
+        by_cat.setdefault(cat, []).append(row)
+
+    known_names = {row["name"] for row in catalog}
+    # Entitled-but-not-in-catalog: show under a synthetic bucket so they aren't lost.
+    orphans = sorted(entitled - known_names)
+    if orphans:
+        by_cat.setdefault("(other)", []).extend({"name": n, "paid": True} for n in orphans)
+
+    for cat in sorted(by_cat):
+        rows = sorted(by_cat[cat], key=lambda r: r["name"])
+        granted = sum(1 for r in rows if r["name"] in entitled)
+        paid_count = sum(1 for r in rows if r.get("paid"))
+        print(f"{cat}  ({granted}/{paid_count} paid entitled, {len(rows)} total)")
+        for r in rows:
+            name = r["name"]
+            has = name in entitled
+            paid = r.get("paid", False)
+            if has:
+                mark = "[x]"
+            elif paid:
+                mark = "[ ]"
+            else:
+                mark = "  ·"  # free skill, no entitlement needed
+            suffix = "" if paid else "  (free)"
+            print(f"  {mark} {name}{suffix}")
+        print()
+
+    return 0
+
+
+def cmd_deactivate(args) -> int:
+    config.wipe_license()
+    print("✓ license wiped from local disk.")
+    return 0
+
+
+def _manifest_for(skill_name: str) -> SkillManifest:
+    d = config.skill_dir(skill_name)
+    if not (d / "MANIFEST.enc.json").exists():
+        candidates = config.skill_dir_candidates(skill_name)
+        print(f"error: skill '{skill_name}' not installed (no MANIFEST.enc.json found).", file=sys.stderr)
+        print(f"  searched, in order:", file=sys.stderr)
+        for c in candidates:
+            mark = "✓" if (c / "MANIFEST.enc.json").exists() else "✗"
+            print(f"    {mark} {c}", file=sys.stderr)
+        print(f"  install via either:", file=sys.stderr)
+        print(f"    npx skills add lovstudio/skills              # full marketplace", file=sys.stderr)
+        print(f"    npx skills add lovstudio/{skill_name}-skill   # just this one", file=sys.stderr)
+        sys.exit(2)
+    return SkillManifest(d)
+
+
+def _read_skill_version(manifest: SkillManifest) -> str:
+    """Version is baked into MANIFEST.enc.json (format v2+)."""
+    if manifest.skill_version:
+        return manifest.skill_version
+    raise RuntimeError(
+        f"manifest at {manifest.skill_dir} has no skill_version field. "
+        "Re-pack with pack-skill.py --skill-version <semver>."
+    )
+
+
+def _fetch_key(lic: dict, skill_name: str, version: str) -> bytes:
+    try:
+        resp = api.skill_keys(lic["license_key"], lic["device_id"], skill_name, version)
+    except api.ApiError as e:
+        print(f"error: skill_keys failed — {e.message}", file=sys.stderr)
+        # 403 = entitlement missing for this skill — point at the storefront.
+        if e.status in (401, 403):
+            print(_BUY_HINT, file=sys.stderr)
+        sys.exit(1)
+    return bytes.fromhex(resp["decryption_key"])
+
+
+def cmd_decrypt(args) -> int:
+    """Print the decrypted SKILL.md to stdout. This is what Claude reads."""
+    lic = _require_license()
+    manifest = _manifest_for(args.skill_name)
+    version = _read_skill_version(manifest)
+    key = _fetch_key(lic, args.skill_name, version)
+    plaintext = decrypt_file(manifest, "SKILL.md", key)
+    sys.stdout.buffer.write(plaintext)
+    return 0
+
+
+def cmd_exec(args) -> int:
+    """Decrypt a script file to a tmpdir, execute it, then clean up."""
+    lic = _require_license()
+    manifest = _manifest_for(args.skill_name)
+    version = _read_skill_version(manifest)
+    key = _fetch_key(lic, args.skill_name, version)
+
+    if args.script_path not in manifest.files:
+        print(f"error: '{args.script_path}' not in manifest.", file=sys.stderr)
+        return 2
+    plaintext = decrypt_file(manifest, args.script_path, key)
+
+    with tempfile.TemporaryDirectory(prefix="lovstudio-") as tmp:
+        tmp_path = Path(tmp) / Path(args.script_path).name
+        tmp_path.write_bytes(plaintext)
+        tmp_path.chmod(0o700)
+
+        # Pick interpreter from extension. KISS — extend when needed.
+        suffix = tmp_path.suffix
+        if suffix == ".py":
+            cmd = [sys.executable, str(tmp_path), *args.script_args]
+        elif suffix == ".sh":
+            cmd = ["bash", str(tmp_path), *args.script_args]
+        else:
+            cmd = [str(tmp_path), *args.script_args]
+
+        result = subprocess.run(cmd)
+        return result.returncode
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="lovstudio-skill-helper")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    p_activate = sub.add_parser("activate", help="activate a license key")
+    p_activate.add_argument("key", help="license key (e.g. lk-<64 hex chars>)")
+    p_activate.set_defaults(func=cmd_activate)
+
+    p_hb = sub.add_parser("heartbeat", help="send heartbeat to refresh license")
+    p_hb.set_defaults(func=cmd_heartbeat)
+
+    p_status = sub.add_parser("status", help="show local license state (by category, with entitlement marks)")
+    p_status.add_argument("--json", action="store_true", help="raw JSON output (old behavior)")
+    p_status.set_defaults(func=cmd_status)
+
+    p_deact = sub.add_parser("deactivate", help="wipe local license file")
+    p_deact.set_defaults(func=cmd_deactivate)
+
+    p_dec = sub.add_parser("decrypt", help="print decrypted SKILL.md to stdout")
+    p_dec.add_argument("skill_name")
+    p_dec.set_defaults(func=cmd_decrypt)
+
+    p_exec = sub.add_parser("exec", help="run a decrypted script from a skill")
+    p_exec.add_argument("skill_name")
+    p_exec.add_argument("script_path", help="relative path inside the skill, e.g. scripts/foo.py")
+    p_exec.add_argument("script_args", nargs=argparse.REMAINDER)
+    p_exec.set_defaults(func=cmd_exec)
+
+    args = p.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lovstudio_skill_helper-0.1.0/src/lovstudio_skill_helper/config.py

@@ -0,0 +1,112 @@
+"""On-disk layout for activated state.
+
+~/.lovstudio/
+└── license.yml                    # license_key, device_id, activated_at, expires_at,
+                                   # last_heartbeat_at, entitled_skills
+
+Encrypted skill bundles live under ~/.claude/skills/<name>/ (or the
+`lovstudio-<name>/` variant), placed there by `npx skills add ...`.
+
+Decryption keys are NEVER persisted here. They live in the running CLI's
+memory for the duration of one `decrypt` or `exec` invocation, then die.
+"""
+from __future__ import annotations
+
+import os
+import platform
+import uuid
+from pathlib import Path
+
+import yaml
+
+CONFIG_DIR = Path(os.environ.get("LOVSTUDIO_HOME", Path.home() / ".lovstudio"))
+LICENSE_FILE = CONFIG_DIR / "license.yml"
+
+# Default Edge Function endpoint. Overridable via env for dev/test.
+# Points at the lovstudio.ai web project (merged license system).
+DEFAULT_API_BASE = "https://nouchjcfeoobplxkwasg.supabase.co/functions/v1"
+# Default anon key — Edge Functions require it for JWT gate, even though
+# we enforce real auth via HMAC inside the function body.
+DEFAULT_ANON_KEY = (
+    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9."
+    "eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im5vdWNoamNmZW9vYnBseGt3YXNnIiwicm9sZSI6"
+    "ImFub24iLCJpYXQiOjE3NjYxNjI1OTMsImV4cCI6MjA4MTczODU5M30."
+    "P3A_AoAjp0EXIafeBBeqp972h_lO7oXjbKgu0OdMsjA"
+)
+
+
+def api_base() -> str:
+    return os.environ.get("LOVSTUDIO_API_BASE", DEFAULT_API_BASE)
+
+
+def rest_base() -> str:
+    """PostgREST base URL — derived from api_base() by stripping the Edge
+    Functions suffix. Overridable via env for dev/test.
+    """
+    override = os.environ.get("LOVSTUDIO_REST_BASE")
+    if override:
+        return override
+    base = api_base()
+    suffix = "/functions/v1"
+    root = base[: -len(suffix)] if base.endswith(suffix) else base
+    return f"{root}/rest/v1"
+
+
+def anon_key() -> str:
+    return os.environ.get("LOVSTUDIO_ANON_KEY", DEFAULT_ANON_KEY)
+
+
+def load_license() -> dict | None:
+    if not LICENSE_FILE.exists():
+        return None
+    return yaml.safe_load(LICENSE_FILE.read_text()) or {}
+
+
+def save_license(data: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    LICENSE_FILE.write_text(yaml.safe_dump(data, sort_keys=False))
+    # Restrict to owner-read/write — the key_secret equivalent is stored here.
+    LICENSE_FILE.chmod(0o600)
+
+
+def wipe_license() -> None:
+    if LICENSE_FILE.exists():
+        LICENSE_FILE.unlink()
+
+
+def generate_device_id() -> str:
+    """Stable-ish device id. Not privacy-sensitive; mirrors OpenClacky approach."""
+    return uuid.uuid4().hex
+
+
+def device_info() -> dict:
+    return {
+        "os": platform.system().lower(),
+        "os_version": platform.release(),
+        "hostname": platform.node(),
+        "python": platform.python_version(),
+    }
+
+
+def skill_dir_candidates(skill_name: str) -> list[Path]:
+    """Search candidates for an encrypted skill bundle, in priority order.
+
+    1. ~/.claude/skills/<name>/                ← `npx skills add` with bare name
+    2. ~/.claude/skills/lovstudio-<name>/      ← `npx skills add` with namespaced name
+                                                  (free skills + paid skills both land here)
+    """
+    return [
+        Path.home() / ".claude" / "skills" / skill_name,
+        Path.home() / ".claude" / "skills" / f"lovstudio-{skill_name}",
+    ]
+
+
+def skill_dir(skill_name: str) -> Path:
+    """Locate an encrypted skill bundle, returning the first candidate that
+    contains a MANIFEST.enc.json. Falls back to the primary path so callers
+    can render a sane error message.
+    """
+    for c in skill_dir_candidates(skill_name):
+        if (c / "MANIFEST.enc.json").exists():
+            return c
+    return skill_dir_candidates(skill_name)[0]

lovstudio_skill_helper-0.1.0/src/lovstudio_skill_helper/crypto.py

@@ -0,0 +1,52 @@
+"""AES-256-GCM decryption for brand skills.
+
+Reads MANIFEST.enc.json + per-file .enc blobs, returns plaintext.
+The decryption key is passed in by the caller (already fetched from the server);
+this module never persists it and never reads it from disk.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from pathlib import Path
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+
+class SkillManifest:
+    def __init__(self, skill_dir: Path):
+        manifest_path = skill_dir / "MANIFEST.enc.json"
+        if not manifest_path.exists():
+            raise FileNotFoundError(f"MANIFEST.enc.json not found in {skill_dir}")
+        data = json.loads(manifest_path.read_text())
+        self.skill_dir = skill_dir
+        self.skill_id: int = data["skill_id"]
+        self.skill_version_id: int = data["skill_version_id"]
+        self.skill_name: str | None = data.get("skill_name")
+        self.skill_version: str | None = data.get("skill_version")
+        self.cipher: str = data.get("cipher", "aes-256-gcm")
+        self.files: dict = data["files"]
+
+    def file_meta(self, rel_path: str) -> dict:
+        meta = self.files.get(rel_path)
+        if not meta:
+            raise KeyError(f"'{rel_path}' not in manifest")
+        return meta
+
+
+def decrypt_file(manifest: SkillManifest, rel_path: str, key: bytes) -> bytes:
+    """Decrypt one file to plaintext bytes. Verifies SHA256 checksum."""
+    meta = manifest.file_meta(rel_path)
+    enc_path = manifest.skill_dir / (rel_path + ".enc")
+    ciphertext = enc_path.read_bytes()
+    iv = base64.b64decode(meta["iv"])
+    tag = base64.b64decode(meta["tag"])
+    plaintext = AESGCM(key).decrypt(iv, ciphertext + tag, associated_data=None)
+
+    expected = meta.get("original_checksum")
+    if expected:
+        actual = hashlib.sha256(plaintext).hexdigest()
+        if actual != expected:
+            raise ValueError(f"checksum mismatch for {rel_path}")
+    return plaintext