feat: add premium entitlement and extension contract

Author: RMANOV

docs/premium/entitlement.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/RMANOV/sqlite-memory-mcp/docs/premium/entitlement.schema.json",
+  "title": "sqlite-memory premium entitlement",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "entitlement_id",
+    "customer_id",
+    "plan",
+    "features",
+    "signature"
+  ],
+  "properties": {
+    "entitlement_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "customer_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "plan": {
+      "type": "string",
+      "minLength": 1
+    },
+    "features": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "machine_ids": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "default": []
+    },
+    "org_id": {
+      "type": "string"
+    },
+    "seat_count": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "issued_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "not_before": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "expires_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "owner_approval_sha256": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "alg",
+        "value"
+      ],
+      "properties": {
+        "alg": {
+          "type": "string",
+          "const": "ed25519"
+        },
+        "value": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Base64-encoded Ed25519 signature over the canonical JSON payload excluding this signature object."
+        },
+        "key_id": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

docs/premium/private_extension_contract.md

@@ -0,0 +1,69 @@
+# Private Premium Extension Contract
+
+This file defines the minimal integration contract for a separate private repo.
+
+## Goal
+
+The public repo stays OSS and safe to share.
+The private repo contains premium logic and is loaded only through the gated runtime boundary.
+
+## Required public-side contract
+
+- Public loader: `premium_runtime.py`
+- Public contract module: `premium_contract.py`
+- Runtime env var for the private entrypoint:
+  - `SQLITE_MEMORY_PREMIUM_ENTRYPOINT`
+
+## Supported private entrypoint shapes
+
+- `package.module`
+- `package.module:register`
+- `C:\path\to\premium_plugin.py`
+- `C:\path\to\premium_plugin.py::register`
+
+## Recommended private function signature
+
+```python
+from premium_contract import PremiumMountContext, PremiumRegistrationResult
+
+def register_premium_extensions(
+    mcp,
+    *,
+    server_name: str | None = None,
+    mount_context: PremiumMountContext | None = None,
+) -> PremiumRegistrationResult:
+    ...
+```
+
+## Guaranteed inputs from the public runtime
+
+- `server_name`
+- `mount_context.contract_version`
+- `mount_context.feature_id`
+- `mount_context.machine_id`
+- `mount_context.config`
+
+## Minimal private repo skeleton
+
+```python
+from premium_contract import PREMIUM_RUNTIME_CONTRACT_VERSION
+
+def register_premium_extensions(mcp, *, server_name=None, mount_context=None):
+    if mount_context is None:
+        raise RuntimeError("mount_context required")
+    if mount_context.contract_version != PREMIUM_RUNTIME_CONTRACT_VERSION:
+        raise RuntimeError("contract mismatch")
+
+    # mount premium tools or sub-MCP here
+    return {
+        "mounted": True,
+        "contract_version": mount_context.contract_version,
+        "extension_name": "sqlite-memory-premium",
+        "features": ["acl_rbac", "partner_digest"],
+    }
+```
+
+## Boundary rule
+
+The private repo must not assume direct access to secrets from the public repo.
+Entitlements, approval tokens, and public-key material stay outside git and are injected at runtime.

premium_contract.py

@@ -0,0 +1,62 @@
+"""Public contract for separate premium extension repositories.
+
+This module is safe to publish. It defines the stable registration surface
+that a private premium repo can target without living inside the OSS core.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, TypedDict
+
+PREMIUM_RUNTIME_CONTRACT_VERSION = "1.0"
+
+
+@dataclass(slots=True)
+class PremiumMountContext:
+    """Context passed from OSS core into a private premium extension."""
+
+    contract_version: str
+    server_name: str
+    feature_id: str
+    machine_id: str
+    config: dict[str, Any] = field(default_factory=dict)
+
+
+class PremiumRegistrationResult(TypedDict, total=False):
+    """Structured result returned by premium registration hooks."""
+
+    mounted: bool
+    contract_version: str
+    extension_name: str
+    features: list[str]
+    notes: str
+
+
+class PremiumExtensionRegistrar(Protocol):
+    """Callable signature for a private premium registration hook."""
+
+    def __call__(
+        self,
+        mcp: Any,
+        *,
+        server_name: str | None = None,
+        mount_context: PremiumMountContext | None = None,
+    ) -> PremiumRegistrationResult | dict[str, Any] | None: ...
+
+
+def build_mount_context(
+    *,
+    server_name: str,
+    feature_id: str,
+    machine_id: str,
+    config: dict[str, Any] | None = None,
+) -> PremiumMountContext:
+    """Build a standard context object for private premium extensions."""
+    return PremiumMountContext(
+        contract_version=PREMIUM_RUNTIME_CONTRACT_VERSION,
+        server_name=server_name,
+        feature_id=feature_id,
+        machine_id=machine_id,
+        config=dict(config or {}),
+    )

premium_runtime.py

@@ -30,6 +30,7 @@
     record_memory_event,
     setup_logger,
 )
+from premium_contract import build_mount_context
 
 logger = setup_logger("sqlite-premium", "premium_runtime.log")
 
@@ -738,6 +739,12 @@ def _resolve_module_from_entrypoint(entrypoint: str):
 def _register_loaded_module(
     module: Any, mcp: Any, server_name: str, attr_name: str | None
 ):
+    mount_context = build_mount_context(
+        server_name=server_name,
+        feature_id="private_extension_runtime",
+        machine_id=MACHINE_ID,
+        config=load_premium_config(),
+    )
     if attr_name:
         target = getattr(module, attr_name, None)
         if target is None:
@@ -758,9 +765,16 @@ def _register_loaded_module(
 
     if callable(target):
         try:
-            return target(mcp, server_name=server_name)
+            return target(
+                mcp,
+                server_name=server_name,
+                mount_context=mount_context,
+            )
         except TypeError:
-            return target(mcp)
+            try:
+                return target(mcp, server_name=server_name)
+            except TypeError:
+                return target(mcp)
     if hasattr(mcp, "mount"):
         mcp.mount(target)
         return {"mounted": True}

tests/test_premium_runtime.py

@@ -6,6 +6,7 @@
 sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
 
 import premium_runtime
+from premium_contract import PREMIUM_RUNTIME_CONTRACT_VERSION
 from schema import init_db
 
 
@@ -217,3 +218,41 @@ def test_maybe_mount_premium_extensions_loads_private_module_when_allowed(
 
     assert audit["decision"] == "load_success"
     assert audit["reason"] == "premium_extensions_loaded"
+
+
+def test_maybe_mount_premium_extensions_passes_mount_context(tmp_path, monkeypatch):
+    db_path = str(tmp_path / "memory.db")
+    init_db(db_path)
+    premium_file = tmp_path / "premium_plugin_ctx.py"
+    premium_file.write_text(
+        "def register_premium_extensions(mcp, *, server_name=None, mount_context=None):\n"
+        "    mcp.loaded_server_name = server_name\n"
+        "    mcp.contract_version = mount_context.contract_version\n"
+        "    mcp.feature_id = mount_context.feature_id\n"
+        "    return {'mounted': True, 'contract_version': mount_context.contract_version}\n",
+        encoding="utf-8",
+    )
+    mcp = DummyMCP()
+    monkeypatch.setenv("SQLITE_MEMORY_PREMIUM_ENTRYPOINT", str(premium_file))
+    monkeypatch.setattr(premium_runtime, "_get_conn", lambda: _conn_ctx(db_path))
+    monkeypatch.setattr(
+        premium_runtime,
+        "evaluate_feature_gate",
+        lambda conn, **kwargs: {
+            "allowed": True,
+            "decision": "allowed",
+            "reason": "entitlement_valid",
+            "feature_id": "private_extension_runtime",
+            "entitlement_id": "ent-ctx",
+            "customer_id": "cust-ctx",
+        },
+    )
+
+    result = premium_runtime.maybe_mount_premium_extensions(
+        mcp, server_name="sqlite-unified"
+    )
+
+    assert result["status"] == "loaded"
+    assert mcp.loaded_server_name == "sqlite-unified"
+    assert mcp.contract_version == PREMIUM_RUNTIME_CONTRACT_VERSION
+    assert mcp.feature_id == "private_extension_runtime"