mcp-event-subscriptions 0.1.0a1__py3-none-any.whl

mcp_event_subscriptions/__init__.py

@@ -0,0 +1,241 @@
+"""Experimental webhook subscription records and a restricted JWE profile."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import re
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from importlib.resources import files
+from typing import Any
+from urllib.parse import urlsplit
+
+from jsonschema import Draft202012Validator, FormatChecker
+from jwcrypto import jwe, jwk
+
+MAX_BYTES = 64 * 1024
+PROFILE = "mcp-subscription-envelope-v1"
+HEADER = {
+    "alg": "dir",
+    "enc": "A256GCM",
+    "typ": "mcp-subscription+jwe",
+    "cty": "application/json",
+}
+SCHEMA = json.loads(
+    files(__package__).joinpath("subscription-v1.schema.json").read_text()
+)
+VALIDATOR = Draft202012Validator(SCHEMA, format_checker=FormatChecker())
+
+
+class RecordError(ValueError):
+    """Invalid subscription data. Messages do not include the record."""
+
+
+class EnvelopeError(ValueError):
+    """Invalid, unauthenticated, or incorrectly bound envelope."""
+
+
+class ExpiredSubscription(EnvelopeError):
+    """The recovered subscription lease has expired."""
+
+
+def _pairs(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON key")
+        result[key] = value
+    return result
+
+
+def _constant(value: str) -> Any:
+    raise ValueError("non-finite JSON value")
+
+
+def _loads(value: str | bytes) -> Any:
+    return json.loads(value, object_pairs_hook=_pairs, parse_constant=_constant)
+
+
+def _encode(value: Any) -> bytes:
+    return json.dumps(
+        value, sort_keys=True, separators=(",", ":"), allow_nan=False
+    ).encode()
+
+
+def _json_value(value: Any) -> None:
+    if value is None or type(value) in (str, bool, int, float):
+        return
+    if type(value) is list:
+        for item in value:
+            _json_value(item)
+        return
+    if type(value) is dict and all(type(k) is str for k in value):
+        for item in value.values():
+            _json_value(item)
+        return
+    raise ValueError("non-JSON value")
+
+
+def _stamp(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def validate_subscription(record: Any) -> dict[str, Any]:
+    """Validate structure and semantics; return an independent JSON copy."""
+    try:
+        _json_value(record)
+        encoded = _encode(record)
+        if len(encoded) > MAX_BYTES or not VALIDATOR.is_valid(record):
+            raise ValueError("invalid structure or size")
+        url = urlsplit(record["delivery"]["url"])
+        # DNS, SSRF policy, and endpoint verification remain adapter responsibilities.
+        if (
+            url.scheme != "https"
+            or not url.hostname
+            or "@" in url.netloc
+            or "#" in record["delivery"]["url"]
+            or any(c.isspace() or ord(c) < 32 for c in record["delivery"]["url"])
+        ):
+            raise ValueError("invalid callback URL")
+        if url.port is not None and not 1 <= url.port <= 65535:
+            raise ValueError("invalid callback port")
+        secret = record["delivery"]["secret"][6:]
+        raw = base64.b64decode(secret, validate=True)
+        if not 24 <= len(raw) <= 64 or base64.b64encode(raw).decode() != secret:
+            raise ValueError("invalid secret")
+        expiry, refresh = (
+            record["lease"]["expiresAt"],
+            record["lease"]["refreshBefore"],
+        )
+        if (expiry is None) != (refresh is None):
+            raise ValueError("inconsistent lease")
+        if expiry is not None and _stamp(refresh) > _stamp(expiry):
+            raise ValueError("invalid lease order")
+        return _loads(encoded)
+    except (ValueError, TypeError, KeyError, OverflowError, RecursionError) as error:
+        raise RecordError("invalid subscription record") from error
+
+
+def _context(context: Any, resource: str) -> dict[str, str]:
+    if (
+        type(context) is not dict
+        or set(context) != {"server", "tenant", "resource"}
+        or any(type(v) is not str or not v for v in context.values())
+        or context["resource"] != resource
+    ):
+        raise EnvelopeError("invalid envelope context")
+    return dict(context)
+
+
+def _b64(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).rstrip(b"=").decode()
+
+
+def _unb64(value: str) -> bytes:
+    if re.fullmatch(r"[A-Za-z0-9_-]*", value) is None:
+        raise EnvelopeError("invalid base64url")
+    try:
+        raw = base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
+    except (ValueError, binascii.Error) as error:
+        raise EnvelopeError("invalid base64url") from error
+    if _b64(raw) != value:
+        raise EnvelopeError("noncanonical base64url")
+    return raw
+
+
+def _key(keys: Mapping[str, bytes], kid: str) -> jwk.JWK:
+    if type(kid) is not str or re.fullmatch(r"[A-Za-z0-9_-]{1,128}", kid) is None:
+        raise EnvelopeError("invalid key identifier")
+    material = keys.get(kid)
+    if type(material) is not bytes or len(material) != 32:
+        raise EnvelopeError("unknown or invalid encryption key")
+    return jwk.JWK(kty="oct", k=_b64(material))
+
+
+def seal(
+    record: Any,
+    keys: Mapping[str, bytes],
+    *,
+    active_key: str,
+    context: dict[str, str],
+) -> str:
+    """Encrypt a validated record with a random IV and trusted storage context."""
+    record = validate_subscription(record)
+    context = _context(context, record["id"])
+    key = _key(keys, active_key)
+    payload = _encode({"profile": PROFILE, "context": context, "subscription": record})
+    token = jwe.JWE(
+        payload,
+        protected=_encode({**HEADER, "kid": active_key}).decode(),
+        algs=["dir", "A256GCM"],
+    )
+    token.add_recipient(key)
+    compact = token.serialize(compact=True)
+    if len(compact.encode()) > MAX_BYTES:
+        raise EnvelopeError("envelope exceeds size limit")
+    return compact
+
+
+def open_envelope(
+    token: str,
+    keys: Mapping[str, bytes],
+    *,
+    expected_context: dict[str, str],
+    now: datetime | None = None,
+) -> dict[str, Any]:
+    """Authenticate, validate, bind and check expiry before returning a record."""
+    try:
+        if type(token) is not str or len(token) > MAX_BYTES or not token.isascii():
+            raise EnvelopeError("invalid envelope size or encoding")
+        parts = token.split(".")
+        if len(parts) != 5 or parts[1]:
+            raise EnvelopeError("invalid compact JWE")
+        header_bytes, _, iv, ciphertext, tag = map(_unb64, parts)
+        header = _loads(header_bytes)
+        if (
+            type(header) is not dict
+            or set(header) != set(HEADER) | {"kid"}
+            or any(header[k] != v for k, v in HEADER.items())
+            or len(iv) != 12
+            or len(tag) != 16
+            or not ciphertext
+        ):
+            raise EnvelopeError("unsupported envelope header or framing")
+        key = _key(keys, header["kid"])
+        decoded = jwe.JWE(algs=["dir", "A256GCM"])
+        decoded.deserialize(token, key=key)
+        payload = _loads(decoded.payload)
+        if (
+            type(payload) is not dict
+            or set(payload) != {"profile", "context", "subscription"}
+            or payload["profile"] != PROFILE
+        ):
+            raise EnvelopeError("unsupported envelope payload")
+        record = validate_subscription(payload["subscription"])
+        expected = _context(expected_context, record["id"])
+        if _context(payload["context"], record["id"]) != expected:
+            raise EnvelopeError("envelope context mismatch")
+        current = now if now is not None else datetime.now(UTC)
+        if current.tzinfo is None or current.utcoffset() is None:
+            raise EnvelopeError("clock must be timezone-aware")
+        expiry = record["lease"]["expiresAt"]
+        if expiry is not None and current >= _stamp(expiry):
+            raise ExpiredSubscription("subscription expired")
+        return record
+    except EnvelopeError:
+        raise
+    except Exception as error:
+        # No raw token, secret, or decrypted record in the public error message.
+        raise EnvelopeError("invalid encrypted subscription") from error
+
+
+__all__ = [
+    "EnvelopeError",
+    "ExpiredSubscription",
+    "RecordError",
+    "open_envelope",
+    "seal",
+    "validate_subscription",
+]

mcp_event_subscriptions/subscription-v1.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://chiragagg5k.github.io/mcp-event-subscriptions/schemas/subscription-v1.schema.json",
+  "title": "Experimental MCP webhook subscription record v1",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "principal": {
+      "type": "string",
+      "minLength": 1
+    },
+    "event": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "arguments": {
+          "type": "object"
+        }
+      },
+      "required": [
+        "name",
+        "arguments"
+      ],
+      "additionalProperties": false
+    },
+    "delivery": {
+      "type": "object",
+      "properties": {
+        "mode": {
+          "const": "webhook"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://"
+        },
+        "secret": {
+          "type": "string",
+          "pattern": "^whsec_[A-Za-z0-9+/]+={0,2}$"
+        }
+      },
+      "required": [
+        "mode",
+        "url",
+        "secret"
+      ],
+      "additionalProperties": false
+    },
+    "lease": {
+      "type": "object",
+      "properties": {
+        "expiresAt": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$"
+        },
+        "refreshBefore": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,6})?Z$"
+        }
+      },
+      "required": [
+        "expiresAt",
+        "refreshBefore"
+      ],
+      "additionalProperties": false
+    },
+    "extensions": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(?:\\.[a-z][a-z0-9-]*){2,}$"
+      }
+    }
+  },
+  "required": [
+    "version",
+    "id",
+    "principal",
+    "event",
+    "delivery",
+    "lease"
+  ],
+  "additionalProperties": false
+}

mcp_event_subscriptions-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: mcp-event-subscriptions
+Version: 0.1.0a1
+Summary: Experimental portable MCP webhook subscription records and JWE envelopes
+Project-URL: Repository, https://github.com/ChiragAgg5k/mcp-event-subscriptions
+Project-URL: Documentation, https://github.com/ChiragAgg5k/mcp-event-subscriptions#readme
+Project-URL: Issues, https://github.com/ChiragAgg5k/mcp-event-subscriptions/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: jwcrypto<2,>=1.5.6
+Description-Content-Type: text/markdown
+
+# MCP Event Subscriptions
+
+An experimental, portable subscription record for MCP Events, with an optional
+[JWE](https://www.rfc-editor.org/rfc/rfc7516) encrypted envelope.
+
+Store the same record in a database, a key-value store, or an upstream webhook
+configuration. This repository defines its fields, encrypted encoding, and
+validation rules, with a Python reference implementation and conformance vectors.
+
+**Independent proposal. This is not an adopted MCP specification or an IETF RFC.**
+The format may change before a stable release. It does not change MCP event
+requests or notification payloads.
+
+## What is here
+
+- [Record specification](SPEC.md) and [JSON Schema](schemas/subscription-v1.schema.json).
+- [Encrypted envelope profile](profiles/encrypted-envelope.md): JWE Compact,
+  `dir` + `A256GCM`, with explicit server/tenant/resource binding.
+- [Appwrite webhook profile](profiles/appwrite-webhook.md): proposed storage
+  mapping and the limits of write-only upstream state.
+- [Examples](examples/) and [conformance vectors](test-vectors/README.md).
+- [Python reference implementation](packages/python/README.md).
+- [Upstream discussion draft](proposals/upstream-mcp.md).
+
+## Install the alpha release
+
+Once the first release is published to PyPI:
+
+```sh
+pip install mcp-event-subscriptions==0.1.0a1
+```
+
+See [RELEASING.md](RELEASING.md) for the Trusted Publishing setup and release process.
+
+## Quick start
+
+Python 3.12 or newer and [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync --group dev
+uv run python examples/roundtrip.py
+uv run python -m unittest discover -s tests -v
+```
+
+```python
+import json
+import secrets
+from mcp_event_subscriptions import seal, open_envelope
+
+record = json.load(open("examples/subscription.json"))
+context = {
+    "server": "https://mcp.example.com",
+    "tenant": "project_demo",
+    "resource": record["id"],
+}
+keys = {"k1": secrets.token_bytes(32)}
+token = seal(record, keys, active_key="k1", context=context)
+restored = open_envelope(token, keys, expected_context=context)
+assert restored == record
+```
+
+The sample subscription expires in 2030. Examples and vectors use synthetic
+principals and secrets. Fixed test-vector keys are public fixtures, never
+production keys.
+
+## Scope
+
+Version 1 describes webhook subscription state and optional encrypted storage.
+It does not specify a SQL layout, implement a delivery queue, establish current
+caller authorization, or make refresh/delete operations atomic. Adapters must
+provide their own coordination and revocation checks. Encryption cannot detect
+replay of an older, still-valid envelope without current state.
+
+The Appwrite profile is documentation, not a working Appwrite adapter. It is not
+wire-compatible with the existing `v1.<kid>.<ciphertext>` envelope in
+[appwrite/mcp PR #132](https://github.com/appwrite/mcp/pull/132).
+
+## Discussing the proposal
+
+Start with the [open questions](proposals/upstream-mcp.md#open-questions): which
+fields should be common, whether an encrypted profile belongs alongside the
+schema, and what lifecycle guarantees adapters must expose. No proposal has
+been submitted upstream by this repository.
+
+## Development
+
+```sh
+uv run --group dev ruff check .
+uv run --group dev black --check .
+uv run python -m unittest discover -s tests -v
+uv build
+```
+
+Licensed under the MIT License. See [SECURITY.md](SECURITY.md) before using the
+reference implementation with real secrets.

mcp_event_subscriptions-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,6 @@
+mcp_event_subscriptions/__init__.py,sha256=CN7ecNATFiIu64p1aJ386h89aDTPVPdeKuakk-jsN1o,8301
+mcp_event_subscriptions/subscription-v1.schema.json,sha256=8fkYQerIm6TBmj357PxqSC0cYUvEtNBtL7y9WXiX9VU,2194
+mcp_event_subscriptions-0.1.0a1.dist-info/METADATA,sha256=oBcz0pGnouODsu9wKxdyS8eKyIJw0TdCeyVJi_9NiI8,4268
+mcp_event_subscriptions-0.1.0a1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mcp_event_subscriptions-0.1.0a1.dist-info/licenses/LICENSE,sha256=FDRCGLH-p80m3w5GPU7K3VIJ00j37PKHvbAfViPs5aY,1065
+mcp_event_subscriptions-0.1.0a1.dist-info/RECORD,,

mcp_event_subscriptions-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_event_subscriptions-0.1.0a1.dist-info/licenses/LICENSE

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