deapi-mcp 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,443 @@
1
+ """OAuth clients other than the pre-registered ``deapi-mcp``: who they are, where they return.
2
+
3
+ Two ways a client introduces itself, neither of which needs a client database:
4
+
5
+ - **Client ID Metadata Document (CIMD).** The ``client_id`` is an HTTPS URL; the server
6
+ fetches the JSON document there and takes the client's name and redirect URIs from
7
+ it. The document's own ``client_id`` must equal the URL. The fetch is SSRF-safe (public
8
+ addresses only, pinned IP, no redirects, 5 kB cap) and cached for 5 minutes; failures
9
+ are never cached. Control of the URL's host is what identifies the client, so the sign-in
10
+ screen names that host.
11
+ - **Dynamic Client Registration (RFC 7591).** ``POST /register`` validates the metadata
12
+ and returns a ``client_id`` that *is* the registration: the metadata plus an HMAC
13
+ under a key derived from ``DEAPI_JWT_SECRET_KEY``. Any replica can verify it, nothing
14
+ is stored, and a flood of registrations costs nothing. Its name is whatever the
15
+ client said, so the sign-in screen marks it unverified.
16
+
17
+ Both kinds are public clients: no secret, PKCE required. Redirect URIs must match a
18
+ registered one exactly; a loopback ``http`` URI matches on any port (RFC 8252 §7.3).
19
+ """
20
+
21
+ import asyncio
22
+ import base64
23
+ import hashlib
24
+ import hmac
25
+ import ipaddress
26
+ import json
27
+ import logging
28
+ import re
29
+ import time
30
+ import unicodedata
31
+ from collections import OrderedDict
32
+ from dataclasses import dataclass
33
+ from typing import Any, Optional
34
+ from urllib.parse import urlsplit
35
+
36
+ from starlette.requests import Request
37
+ from starlette.responses import JSONResponse
38
+
39
+ from .utils import InputError, safe_fetch
40
+
41
+ logger = logging.getLogger(__name__)
42
+
43
+ PREREGISTERED_CLIENT_ID = "deapi-mcp"
44
+
45
+ MAX_REDIRECT_URIS = 5
46
+ MAX_REDIRECT_URI_LENGTH = 512
47
+ MAX_CLIENT_NAME_LENGTH = 80
48
+ MAX_METADATA_BYTES = 5 * 1024
49
+ CIMD_TIMEOUT_SECONDS = 5.0
50
+ # A fetched document is reused this long (failures are never cached).
51
+ CIMD_CACHE_TTL = 300
52
+ CIMD_CACHE_ENTRIES = 1000
53
+ DCR_PREFIX = "dcr."
54
+
55
+ MAX_REGISTRATION_BYTES = 8 * 1024
56
+ # Concurrent metadata fetches per process, and how long a failed one is remembered.
57
+ CIMD_MAX_CONCURRENT_FETCHES = 16
58
+ CIMD_FAILURE_TTL = 60
59
+
60
+ LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1"}
61
+ # Native apps' private-use schemes (RFC 8252 §7.1) take reverse-domain form, so they contain
62
+ # a dot. Schemes without one are accepted only from this list of known MCP clients.
63
+ KNOWN_NATIVE_SCHEMES = {"cursor"}
64
+ # Never a redirect target: browser-internal, OS protocol handlers, network and messaging.
65
+ FORBIDDEN_SCHEMES = {
66
+ "javascript",
67
+ "data",
68
+ "vbscript",
69
+ "file",
70
+ "about",
71
+ "blob",
72
+ "filesystem",
73
+ "view-source",
74
+ "jar",
75
+ "smb",
76
+ "ftp",
77
+ "sftp",
78
+ "ws",
79
+ "wss",
80
+ "intent",
81
+ "mailto",
82
+ "tel",
83
+ "sms",
84
+ "search-ms",
85
+ "search",
86
+ }
87
+ FORBIDDEN_SCHEME_PREFIXES = ("ms-", "chrome", "edge", "firefox", "opera", "safari", "res")
88
+ _SCHEME = re.compile(r"[a-z][a-z0-9+.-]*")
89
+ _CONTROL = re.compile(r"[\x00-\x1f\x7f]")
90
+ # Bidi overrides, zero-width and other invisible characters a name could hide behind.
91
+ _INVISIBLE = re.compile(
92
+ "[\u00ad\u061c\u115f\u1160\u180e\u200b-\u200f\u202a-\u202e"
93
+ "\u2060-\u206f\u3164\ufe00-\ufe0f\ufeff]"
94
+ )
95
+ _LETTERS = re.compile(r"[^a-z0-9]")
96
+
97
+
98
+ @dataclass(frozen=True)
99
+ class OAuthClient:
100
+ """A public client, as the sign-in screen and the token endpoint see it."""
101
+
102
+ client_id: str
103
+ kind: str # "cimd" or "dcr"
104
+ name: str
105
+ redirect_uris: tuple[str, ...]
106
+
107
+ @property
108
+ def verified_host(self) -> Optional[str]:
109
+ """The host that serves this client's metadata (CIMD only); deAPI does not vouch for it."""
110
+ return urlsplit(self.client_id).hostname if self.kind == "cimd" else None
111
+
112
+ def allows_redirect(self, redirect_uri: str) -> bool:
113
+ return any(redirect_matches(registered, redirect_uri) for registered in self.redirect_uris)
114
+
115
+
116
+ # --- redirect URIs ------------------------------------------------------------------------
117
+
118
+
119
+ def is_loopback_redirect(uri: str) -> bool:
120
+ parts = urlsplit(uri)
121
+ return parts.scheme == "http" and (parts.hostname or "") in LOOPBACK_HOSTS
122
+
123
+
124
+ def valid_redirect_uri(uri: Any) -> bool:
125
+ """https anywhere, http only on loopback, or a native app's private-use scheme."""
126
+ if not isinstance(uri, str) or not uri or len(uri) > MAX_REDIRECT_URI_LENGTH:
127
+ return False
128
+ if _CONTROL.search(uri) or " " in uri:
129
+ return False
130
+ try:
131
+ parts = urlsplit(uri)
132
+ parts.port # raises ValueError on a malformed port
133
+ except ValueError:
134
+ return False
135
+ scheme = parts.scheme.lower()
136
+ if parts.fragment or not _SCHEME.fullmatch(scheme) or scheme in FORBIDDEN_SCHEMES:
137
+ return False
138
+ if scheme == "https":
139
+ return bool(parts.hostname)
140
+ if scheme == "http":
141
+ return (parts.hostname or "") in LOOPBACK_HOSTS
142
+ # Private-use scheme (RFC 8252 §7.1): com.example.app:/cb, or a known client's own
143
+ # (cursor://anysphere.cursor-mcp/oauth/callback). OS protocol handlers stay out.
144
+ if scheme.startswith(FORBIDDEN_SCHEME_PREFIXES):
145
+ return False
146
+ if "." not in scheme and scheme not in KNOWN_NATIVE_SCHEMES:
147
+ return False
148
+ return bool(parts.netloc or parts.path)
149
+
150
+
151
+ def redirect_matches(registered: str, requested: str) -> bool:
152
+ """Exact match; a loopback http redirect may use any port (RFC 8252 §7.3)."""
153
+ if not valid_redirect_uri(requested):
154
+ return False
155
+ if registered == requested:
156
+ return True
157
+ if not (is_loopback_redirect(registered) and is_loopback_redirect(requested)):
158
+ return False
159
+ a, b = urlsplit(registered), urlsplit(requested)
160
+ return (a.hostname, a.path, a.query) == (b.hostname, b.path, b.query)
161
+
162
+
163
+ # Cyrillic and Greek letters that look like the Latin ones in "deapi".
164
+ _LOOKALIKES = str.maketrans(
165
+ {
166
+ "а": "a",
167
+ "е": "e",
168
+ "р": "p",
169
+ "і": "i",
170
+ "ԁ": "d",
171
+ "ӏ": "i",
172
+ "α": "a",
173
+ "ε": "e",
174
+ "ρ": "p",
175
+ "ι": "i",
176
+ "ı": "i",
177
+ "ɑ": "a",
178
+ "ⅾ": "d",
179
+ "ⅰ": "i",
180
+ }
181
+ )
182
+
183
+
184
+ def _clean_name(value: Any, fallback: str) -> str:
185
+ """A name safe to show: no control or invisible characters, short, not posing as deAPI."""
186
+ if not isinstance(value, str):
187
+ return fallback
188
+ name = unicodedata.normalize("NFKC", value)
189
+ name = " ".join(_INVISIBLE.sub("", _CONTROL.sub("", name)).split())
190
+ skeleton = _LETTERS.sub("", name.lower().translate(_LOOKALIKES))
191
+ if "deapi" in skeleton:
192
+ return fallback # only deAPI may call itself deAPI on its own sign-in screen
193
+ return name[:MAX_CLIENT_NAME_LENGTH] or fallback
194
+
195
+
196
+ def _validated_metadata(data: Any) -> tuple[str, tuple[str, ...]]:
197
+ """(client name, redirect URIs) from registration or CIMD metadata, or ValueError."""
198
+ if not isinstance(data, dict):
199
+ raise ValueError("client metadata must be a JSON object")
200
+ uris = data.get("redirect_uris")
201
+ if (
202
+ not isinstance(uris, list)
203
+ or not uris
204
+ or len(uris) > MAX_REDIRECT_URIS
205
+ or not all(valid_redirect_uri(u) for u in uris)
206
+ ):
207
+ raise ValueError(
208
+ f"redirect_uris must list 1-{MAX_REDIRECT_URIS} https, loopback http or "
209
+ "native-app URIs without fragments"
210
+ )
211
+ method = data.get("token_endpoint_auth_method", "none")
212
+ if method != "none":
213
+ raise ValueError("token_endpoint_auth_method must be none (public client with PKCE)")
214
+ grants = data.get("grant_types", ["authorization_code"])
215
+ if (
216
+ not isinstance(grants, list)
217
+ or not all(isinstance(g, str) for g in grants)
218
+ or not set(grants) <= {"authorization_code", "refresh_token"}
219
+ ):
220
+ raise ValueError("grant_types may only contain authorization_code and refresh_token")
221
+ responses = data.get("response_types", ["code"])
222
+ if (
223
+ not isinstance(responses, list)
224
+ or not all(isinstance(r, str) for r in responses)
225
+ or not set(responses) <= {"code"}
226
+ ):
227
+ raise ValueError("response_types may only contain code")
228
+ return _clean_name(data.get("client_name"), "Unnamed application"), tuple(uris)
229
+
230
+
231
+ # --- Dynamic Client Registration (stateless) ----------------------------------------------
232
+
233
+
234
+ def _dcr_key() -> bytes:
235
+ from .oauth_endpoints import get_jwt_secret_key
236
+
237
+ return hashlib.sha256(b"deapi-mcp/dcr-client-id\x00" + get_jwt_secret_key().encode()).digest()
238
+
239
+
240
+ def _b64(data: bytes) -> str:
241
+ return base64.urlsafe_b64encode(data).decode().rstrip("=")
242
+
243
+
244
+ def _unb64(text: str) -> bytes:
245
+ return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
246
+
247
+
248
+ def encode_dcr_client_id(name: str, redirect_uris: tuple[str, ...], issued_at: int) -> str:
249
+ payload = _b64(
250
+ json.dumps(
251
+ {"n": name, "r": list(redirect_uris), "t": issued_at}, separators=(",", ":")
252
+ ).encode()
253
+ )
254
+ signature = _b64(hmac.new(_dcr_key(), payload.encode(), hashlib.sha256).digest())
255
+ return f"{DCR_PREFIX}{payload}.{signature}"
256
+
257
+
258
+ def decode_dcr_client_id(client_id: str) -> Optional[OAuthClient]:
259
+ if not client_id.startswith(DCR_PREFIX):
260
+ return None
261
+ payload, sep, signature = client_id[len(DCR_PREFIX) :].partition(".")
262
+ if not sep:
263
+ return None
264
+ expected = _b64(hmac.new(_dcr_key(), payload.encode(), hashlib.sha256).digest())
265
+ if not hmac.compare_digest(expected.encode(), signature.encode()):
266
+ return None
267
+ try:
268
+ data = json.loads(_unb64(payload))
269
+ name = _clean_name(data["n"], "Unnamed application")
270
+ uris = tuple(str(u) for u in data["r"])
271
+ except (ValueError, KeyError, TypeError, RecursionError):
272
+ return None
273
+ return OAuthClient(client_id, "dcr", name, uris)
274
+
275
+
276
+ async def register_endpoint(request: Request) -> JSONResponse:
277
+ """RFC 7591 dynamic client registration for public clients."""
278
+ body = b""
279
+ async for chunk in request.stream():
280
+ body += chunk
281
+ if len(body) > MAX_REGISTRATION_BYTES:
282
+ return _registration_error(
283
+ "invalid_client_metadata", f"The body is limited to {MAX_REGISTRATION_BYTES} bytes"
284
+ )
285
+ try:
286
+ data = json.loads(body)
287
+ except (ValueError, RecursionError):
288
+ return _registration_error("invalid_client_metadata", "The body must be a JSON object")
289
+ try:
290
+ name, uris = _validated_metadata(data)
291
+ except ValueError as exc:
292
+ error = "invalid_redirect_uri" if "redirect_uris" in str(exc) else "invalid_client_metadata"
293
+ return _registration_error(error, str(exc))
294
+ issued_at = int(time.time())
295
+ client_id = encode_dcr_client_id(name, uris, issued_at)
296
+ logger.info("Registered a public OAuth client (%d redirect URIs)", len(uris))
297
+ return JSONResponse(
298
+ {
299
+ "client_id": client_id,
300
+ "client_id_issued_at": issued_at,
301
+ "client_name": name,
302
+ "redirect_uris": list(uris),
303
+ "token_endpoint_auth_method": "none",
304
+ "grant_types": ["authorization_code", "refresh_token"],
305
+ "response_types": ["code"],
306
+ },
307
+ status_code=201,
308
+ headers={"Cache-Control": "no-store"},
309
+ )
310
+
311
+
312
+ def _registration_error(error: str, description: str) -> JSONResponse:
313
+ return JSONResponse(
314
+ {"error": error, "error_description": description},
315
+ status_code=400,
316
+ headers={"Cache-Control": "no-store"},
317
+ )
318
+
319
+
320
+ # --- Client ID Metadata Documents ---------------------------------------------------------
321
+
322
+
323
+ def is_cimd_client_id(client_id: str) -> bool:
324
+ """An https URL with a path, no fragment and no credentials (CIMD client_id rules)."""
325
+ if len(client_id) > MAX_REDIRECT_URI_LENGTH:
326
+ return False
327
+ try:
328
+ parts = urlsplit(client_id)
329
+ except ValueError:
330
+ return False
331
+ if parts.scheme != "https" or not parts.hostname or parts.fragment:
332
+ return False
333
+ if parts.username or parts.password or parts.path in ("", "/"):
334
+ return False
335
+ try:
336
+ ipaddress.ip_address(parts.hostname)
337
+ return False # a client is identified by a domain, not an address
338
+ except ValueError:
339
+ return True
340
+
341
+
342
+ _cimd_cache: "OrderedDict[str, tuple[OAuthClient, float]]" = OrderedDict()
343
+
344
+
345
+ _cimd_failures: "OrderedDict[str, float]" = OrderedDict()
346
+ # How long a fetch may wait for a free slot before the client is refused for now.
347
+ CIMD_SLOT_WAIT_SECONDS = 2.0
348
+ _cimd_fetches: Optional[tuple[asyncio.AbstractEventLoop, asyncio.Semaphore]] = None
349
+
350
+
351
+ def _fetch_slots() -> asyncio.Semaphore:
352
+ """The fetch semaphore of the running event loop (created on first use there)."""
353
+ global _cimd_fetches
354
+ loop = asyncio.get_running_loop()
355
+ if _cimd_fetches is None or _cimd_fetches[0] is not loop:
356
+ _cimd_fetches = (loop, asyncio.Semaphore(CIMD_MAX_CONCURRENT_FETCHES))
357
+ return _cimd_fetches[1]
358
+
359
+
360
+ def _note_failure(client_id: str) -> None:
361
+ _cimd_failures[client_id] = time.monotonic() + CIMD_FAILURE_TTL
362
+ _cimd_failures.move_to_end(client_id)
363
+ while len(_cimd_failures) > CIMD_CACHE_ENTRIES:
364
+ _cimd_failures.popitem(last=False)
365
+
366
+
367
+ async def fetch_cimd_client(client_id: str) -> Optional[OAuthClient]:
368
+ """The client described at ``client_id``, or None when it cannot be used.
369
+
370
+ Bounded so it cannot be turned into a request reflector: one fetch per URL per
371
+ ``CIMD_FAILURE_TTL`` after a failure, ``CIMD_MAX_CONCURRENT_FETCHES`` at once, and the
372
+ whole fetch (not each read) within ``CIMD_TIMEOUT_SECONDS``.
373
+ """
374
+ cached = _cimd_cache.get(client_id)
375
+ if cached is not None and cached[1] > time.monotonic():
376
+ _cimd_cache.move_to_end(client_id)
377
+ return cached[0]
378
+ failed_until = _cimd_failures.get(client_id)
379
+ if failed_until is not None and failed_until > time.monotonic():
380
+ return None
381
+ slots = _fetch_slots()
382
+ try:
383
+ await asyncio.wait_for(slots.acquire(), CIMD_SLOT_WAIT_SECONDS)
384
+ except asyncio.TimeoutError:
385
+ logger.warning("Client metadata fetches at capacity; refusing %r for now", client_id[:80])
386
+ return None
387
+ try:
388
+ try:
389
+ body, _ = await asyncio.wait_for(_fetch_metadata(client_id), CIMD_TIMEOUT_SECONDS)
390
+ finally:
391
+ slots.release()
392
+ data = json.loads(body)
393
+ if not isinstance(data, dict) or data.get("client_id") != client_id:
394
+ raise ValueError("client_id in the document does not match its URL")
395
+ name, uris = _validated_metadata(data)
396
+ except (InputError, ValueError, TypeError, RecursionError, asyncio.TimeoutError) as exc:
397
+ logger.info("Client metadata document rejected (%s)", type(exc).__name__)
398
+ _note_failure(client_id)
399
+ return None
400
+ client = OAuthClient(client_id, "cimd", name, uris)
401
+ _cimd_cache[client_id] = (client, time.monotonic() + CIMD_CACHE_TTL)
402
+ _cimd_cache.move_to_end(client_id)
403
+ while len(_cimd_cache) > CIMD_CACHE_ENTRIES:
404
+ _cimd_cache.popitem(last=False)
405
+ return client
406
+
407
+
408
+ async def _fetch_metadata(url: str) -> tuple[bytes, str]:
409
+ body, content_type = await safe_fetch(
410
+ url,
411
+ max_bytes=MAX_METADATA_BYTES,
412
+ timeout=CIMD_TIMEOUT_SECONDS,
413
+ max_redirects=0,
414
+ schemes=("https",),
415
+ refused_content_types=(),
416
+ accept="application/json",
417
+ # Uncompressed only, so the byte cap counts what is actually received
418
+ extra_headers={"Accept-Encoding": "identity"},
419
+ )
420
+ return body, content_type
421
+
422
+
423
+ def looks_like_public_client_id(client_id: Optional[str]) -> bool:
424
+ """A client ID in one of the two public forms (it may still fail to resolve)."""
425
+ return bool(client_id) and (
426
+ str(client_id).startswith(DCR_PREFIX) or is_cimd_client_id(str(client_id))
427
+ )
428
+
429
+
430
+ async def resolve_client(client_id: Optional[str]) -> Optional[OAuthClient]:
431
+ """The public client behind ``client_id`` (CIMD or DCR), or None."""
432
+ if not client_id or client_id == PREREGISTERED_CLIENT_ID:
433
+ return None
434
+ if client_id.startswith(DCR_PREFIX):
435
+ return decode_dcr_client_id(client_id)
436
+ if is_cimd_client_id(client_id):
437
+ return await fetch_cimd_client(client_id)
438
+ return None
439
+
440
+
441
+ def clear_cimd_cache() -> None:
442
+ _cimd_cache.clear()
443
+ _cimd_failures.clear()