msgctl 0.1.0a1__py3-none-any.whl

msg/transports/mcp.py

@@ -0,0 +1,127 @@
+"""MCP 2025-11-25 JSON-RPC over stateless Streamable HTTP or local stdio.
+
+Remote calls carry the same signed operation envelope as other transports.
+Local stdio exposes argument schemas directly and delegates signing to msg.
+No root-administration operation is generated as an MCP tool.
+"""
+from __future__ import annotations
+from dataclasses import replace
+from msg import __version__
+from msg.core.codec import canonical,digest,loads
+from msg.core.errors import Failure,require
+from msg.core.executor import result_wire
+from msg.transports.packet import decode_packet,REQUEST_SCHEMA,RESULT_SCHEMA
+
+PROTOCOL_VERSION='2025-11-25'
+SUPPORTED_VERSIONS=frozenset({PROTOCOL_VERSION,'2025-06-18','2025-03-26'})
+
+
+class MCPServer:
+    def __init__(self,service, *, local_client=None):
+        self.service=service
+        self.local_client=local_client
+        self._requests={}
+
+    async def tools(self,cursor=None):
+        registry=self.service.registry
+        specs=registry.operations('network')
+        offset=0
+        if cursor:
+            offset=self.service.cursors.decode(cursor,'mcp-tools',registry.catalog()['digest'])
+            require(type(offset) is int and 0<=offset<=len(specs),'invalid_cursor')
+        if self.local_client is not None:
+            await registry.load_schemas(specs[offset:offset+8])
+        tools=[]
+        # Bounded discovery; an agent can request only the next useful page.
+        for spec in specs[offset:offset+8]:
+            tool_name=spec.name if spec.version==1 else f'{spec.name}@{spec.version}'
+            if self.local_client is not None:
+                input_schema=registry.schema(spec.input_schema)
+            else:
+                packet_schema={**REQUEST_SCHEMA,'properties':{**REQUEST_SCHEMA['properties'],
+                    'operation':{'const':spec.name},'contract_version':{'const':spec.version},
+                    'arguments':registry.schema(spec.input_schema)}}
+                input_schema={'type':'object','properties':{'packet':packet_schema},'required':['packet'],'additionalProperties':False}
+            tools.append({'name':tool_name,'description':f'{spec.name}@{spec.version}; {spec.effect}; contract /-/d/{spec.name.split(".",1)[0]}/{tool_name}',
+                'inputSchema':input_schema,'outputSchema':RESULT_SCHEMA,
+                'annotations':{'readOnlyHint':spec.effect=='read','idempotentHint':True,
+                    'destructiveHint':spec.effect!='read','openWorldHint':spec.effect=='external'}})
+        result={'tools':tools}
+        if offset+len(tools)<len(specs):
+            result['nextCursor']=self.service.cursors.encode('mcp-tools',registry.catalog()['digest'],offset+len(tools))
+        return result
+
+    async def handle(self,message):
+        id=message.get('id') if isinstance(message,dict) else None
+        try:
+            require(isinstance(message,dict) and message.get('jsonrpc')=='2.0' and
+                    isinstance(message.get('method'),str),'invalid_jsonrpc')
+            require(id is None or type(id) in (str,int),'invalid_jsonrpc_id')
+            require(not isinstance(id,str) or len(id)<=128,'invalid_jsonrpc_id')
+            method=message['method']
+            params=message.get('params',{})
+            require(isinstance(params,dict),'invalid_jsonrpc_params')
+            if id is None:
+                # Notifications never execute operations, even if their method is
+                # tools/call. This prevents unacknowledged mutation messages.
+                return None
+            if method=='initialize':
+                requested=params.get('protocolVersion')
+                selected=requested if requested in SUPPORTED_VERSIONS else PROTOCOL_VERSION
+                result={'protocolVersion':selected,'capabilities':{'tools':{'listChanged':False}},
+                        'serverInfo':{'name':'msg.lmm.best','version':__version__},
+                        'instructions':'Read /AGENTS.md. Network operations use one signed envelope. Root administration is not available.'}
+            elif method=='ping':
+                result={}
+            elif method=='tools/list':
+                require(set(params)<={'cursor','_meta'},'invalid_jsonrpc_params')
+                result=await self.tools(params.get('cursor'))
+            elif method=='tools/call':
+                require(set(params)<={'name','arguments','_meta'} and isinstance(params.get('name'),str),'invalid_jsonrpc_params')
+                name=params['name']
+                operation,separator,version=name.rpartition('@')
+                if separator:
+                    require(version.isdecimal() and int(version)>0,'invalid_operation_version')
+                    spec=self.service.registry.operation(operation,int(version))
+                else:
+                    spec=self.service.registry.operation(name)
+                require('network' in spec.entries,'entry_not_allowed')
+                arguments=params.get('arguments',{})
+                if self.local_client is None:
+                    require(isinstance(arguments,dict) and set(arguments)=={'packet'},'signed_packet_required')
+                    packet=decode_packet(arguments['packet'],self.service.settings.server.limits.max_request_bytes)
+                    require(packet.operation==spec.name and packet.contract_version==spec.version,'operation_mismatch')
+                    output=await self.service.executor.execute(packet,entry='network')
+                else:
+                    require(isinstance(arguments,dict),'invalid_jsonrpc_params')
+                    metadata=params.get('_meta',{})
+                    expected=metadata.get('msg/expected_generations',())
+                    request_id=metadata.get('msg/request_id')
+                    cache_key=(type(id).__name__,id)
+                    request_digest=digest((params['name'],arguments,expected))
+                    existing=self._requests.get(cache_key)
+                    if existing:
+                        require(existing[0]==request_digest,'jsonrpc_id_conflict')
+                        request_id=existing[1]
+                    packet=self.local_client.prepare(spec.name,arguments,expected=expected,
+                        request_id=request_id,contract_version=spec.version)
+                    self._requests[cache_key]=(request_digest,packet.request_id)
+                    # This is a process-local replay cache, not per-account server state.
+                    if len(self._requests)>256:
+                        self._requests.pop(next(iter(self._requests)))
+                    output=await self.local_client.send(packet)
+                value=result_wire(output)
+                encoded=canonical(value).decode()
+                # Structured content is authoritative. Avoid doubling large
+                # transfer chunks in the text compatibility projection.
+                text=encoded if len(encoded)<=8192 else canonical({'request_id':output.request_id,
+                    'status':output.status,'structured_content':True}).decode()
+                result={'content':[{'type':'text','text':text}],
+                        'structuredContent':value,'isError':output.status=='error'}
+            else:
+                return {'jsonrpc':'2.0','id':id,'error':{'code':-32601,'message':'method_not_found'}}
+            return {'jsonrpc':'2.0','id':id,'result':result}
+        except Failure as exc:
+            if id is None:
+                return None
+            return {'jsonrpc':'2.0','id':id,'error':{'code':-32602,'message':exc.code}}

msg/transports/packet.py

@@ -0,0 +1,42 @@
+"""URL and compression boundaries; common wire contracts live in core.packet."""
+from __future__ import annotations
+import zlib
+from msg.core.codec import unb64
+from msg.core.errors import require, Failure
+from msg.core.requests import SECRET_DELIVERY_MIN_VERSION
+from msg.core.models import OperationRequest, TokenProof
+from msg.core.packet import (
+    REQUEST_SCHEMA, RESULT_SCHEMA, decode_packet, decode_result, safe_error_code,
+)
+from msg.transports.url_safety import contains_secret_fields
+
+
+def require_url_safe_packet(packet: OperationRequest) -> None:
+    """Reject credentials and recovery claims before a GET URL is dispatched.
+
+    A signature is a bounded request proof; TokenProof and issuance claims are
+    reusable secrets. This guards both clients constructing URL packets and the
+    server receiving hand-built packets, including gzip envelopes.
+    """
+    require(not isinstance(packet.proof, TokenProof), 'secure_channel_required')
+    require(packet.operation not in SECRET_DELIVERY_MIN_VERSION, 'secure_channel_required')
+
+    require(not contains_secret_fields(packet.arguments), 'secure_channel_required')
+
+
+def gunzip(raw,limit):
+    inflater=zlib.decompressobj(wbits=31)
+    try:
+        result=inflater.decompress(raw,limit+1)
+        require(len(result)<=limit and not inflater.unconsumed_tail,'request_too_large')
+        result+=inflater.flush(limit+1-len(result))
+        require(len(result)<=limit and inflater.eof and not inflater.unused_data,'invalid_gzip')
+        return result
+    except zlib.error as exc:
+        raise Failure('invalid_gzip') from exc
+
+
+def path_packet(encoded,encoding,limit):
+    raw=unb64(encoded,limit=limit)
+    require(encoding in {'j','gz'},'unknown_encoding')
+    return decode_packet(gunzip(raw,limit) if encoding=='gz' else raw,limit)

msg/transports/read_tree_path.py

@@ -0,0 +1,65 @@
+"""Readable v3 paths: x/{collection} enters a node; up/1 closes it."""
+import re
+from urllib.parse import quote,unquote_to_bytes
+from msg.core.errors import Failure,require
+from msg.core.read_query import MAX_READ_DEPTH,NESTED_FIELDS,ROOT_FIELDS
+from msg.transports.dictionary import READ_QUERY_V1_SORT,READ_QUERY_V1_FIELDS
+
+
+def decode_read_tree_path(raw_path):
+    parts=raw_path.split(b'/')
+    require(len(parts)>=6 and parts[:4] in
+            ([b'',b'_r',b'q',b'3'],[b'',b'_read',b'q',b'3']),'invalid_path')
+    pieces=parts[4:]
+    proof=None
+    if len(pieces)>=2 and pieces[-2]==b'p':
+        proof=pieces[-1];pieces=pieces[:-2]
+    require(pieces and len(pieces)%2==0,'invalid_path')
+    root={'query_version':3}
+    stack=[root]
+    fields={value:key for key,value in READ_QUERY_V1_FIELDS.items()}
+    sorts={value:key for key,value in READ_QUERY_V1_SORT.items()}
+    for code,encoded in zip(pieces[::2],pieces[1::2],strict=True):
+        require(encoded and re.search(rb'%(?![0-9A-Fa-f]{2})',encoded) is None,'invalid_path')
+        try:value=unquote_to_bytes(encoded).decode('utf-8')
+        except UnicodeDecodeError as exc:raise Failure('invalid_path') from exc
+        require(quote(value,safe=',').encode()==encoded,'invalid_path')
+        node=stack[-1]
+        if code==b'x':
+            require(value in {'children','replies'},'invalid_nested_query')
+            require(len(stack)<=MAX_READ_DEPTH,'query_cost_exceeded')
+            tree=node.setdefault('expand',{})
+            require(value not in tree,'duplicate_query_parameter')
+            tree[value]={};stack.append(tree[value])
+            continue
+        if code==b'up':
+            require(value=='1' and len(stack)>1,'invalid_path')
+            stack.pop();continue
+        names={b'r':'parent',b't':'type',b's':'sort',b'f':'fields',b'n':'limit',b'a':'cursor',
+               b'co':'collection',b'pa':'parent'}
+        require(code in names,'unknown_query_parameter')
+        field=names[code]
+        require(len(stack)==1 or field in {'limit','fields'},'invalid_nested_query')
+        require(field not in node,'duplicate_query_parameter')
+        if field=='limit':
+            require(value.isdecimal() and 1<=int(value)<=(100 if len(stack)==1 else 10),
+                    'query_cost_exceeded')
+            value=int(value)
+        elif field=='fields':
+            selected=value.split(',')
+            allowed=ROOT_FIELDS if len(stack)==1 else NESTED_FIELDS
+            require(selected and len(selected)==len(set(selected)) and
+                    all(code in fields and fields[code] in allowed for code in selected),
+                    'unknown_projection_field')
+            value=[fields[code] for code in selected]
+        elif field=='sort':
+            require(value in sorts,'invalid_sort');value=sorts[value]
+        elif field=='collection':
+            require(value in {'children','replies'},'invalid_nested_query')
+        node[field]=value
+    require(len(stack)==1,'invalid_path')
+    if 'cursor' in root:
+        require(set(root)=={'query_version','cursor'},'cursor_query_mismatch')
+        return {'cursor':root['cursor']},proof
+    require(root.get('parent'),'read_query_root_required')
+    return root,proof

msg/transports/stdio.py

@@ -0,0 +1,36 @@
+"""Local MCP is a signed network client, never a msgd administrative proxy."""
+from __future__ import annotations
+import asyncio
+import os
+import sys
+from types import SimpleNamespace
+
+from msg.core.codec import canonical,loads
+from msg.core.cursors import CursorCodec
+from msg.core.errors import Failure
+from msg.transports.mcp import MCPServer
+
+
+async def serve_stdio(client,input_stream=None,output_stream=None):
+    input_stream=input_stream or sys.stdin.buffer
+    output_stream=output_stream or sys.stdout.buffer
+    registry=await client.contract_registry()
+    service=SimpleNamespace(registry=registry,cursors=CursorCodec(os.urandom(32)))
+    server=MCPServer(service,local_client=client)
+    limit=(await client.transport.discover()).max_request_bytes
+    while True:
+        line=await asyncio.to_thread(input_stream.readline,limit+2)
+        if not line:
+            break
+        try:
+            if len(line)>limit or not line.endswith(b'\n'):
+                # Framing cannot be recovered safely from an unterminated oversized line.
+                error={'jsonrpc':'2.0','id':None,'error':{'code':-32700,'message':'message_too_large'}}
+                output_stream.write(canonical(error)+b'\n');output_stream.flush()
+                break
+            result=await server.handle(loads(line))
+        except Failure as exc:
+            result={'jsonrpc':'2.0','id':None,'error':{'code':-32700,'message':exc.code}}
+        if result is not None:
+            output_stream.write(canonical(result)+b'\n')
+            output_stream.flush()

msg/transports/url_safety.py

@@ -0,0 +1,123 @@
+"""Bounded URL inspection shared by HTTP, PathGET and clients.
+
+Decoding here is for rejection only. It never produces a rewritten route or
+business arguments. Ordinary data (including percent literals and quoted /)
+still reaches its original parser. Only explicit credential field names and
+legacy credential slots are classified; arbitrary text is not a secret scanner.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from urllib.parse import SplitResult, unquote_to_bytes, urlsplit
+
+from msg.core.errors import Failure, require
+
+MAX_DECODE_LAYERS = 8
+_SECRET_NAMES = frozenset({
+    'token', 'accesstoken', 'refreshtoken', 'recoverysecret', 'newrecoverysecret',
+    'privatekey', 'secret', 'clientsecret', 'bootstrapclaim', 'password', 'apikey',
+    'authorization',
+})
+_BAD_ESCAPE = re.compile(rb'%(?![0-9a-fA-F]{2})')
+_CONTROL = re.compile(rb'[\x00-\x20\x7f]')
+
+
+def _layers(raw: bytes):
+    """At most eight decoding passes; never expose the rejected input."""
+    current = raw
+    for _ in range(MAX_DECODE_LAYERS + 1):
+        yield current
+        decoded = unquote_to_bytes(current)
+        if decoded == current:
+            return
+        current = decoded
+    require(False, 'invalid_path')
+
+
+def is_secret_field(name: str | bytes) -> bool:
+    raw = name.encode('utf-8') if isinstance(name, str) else name
+    for layer in _layers(raw):
+        # Understand conventional nested field labels, not arbitrary substrings.
+        for part in re.split(rb'[.\[\]]', layer.lower()):
+            normalized = part.strip().replace(b'_', b'').replace(b'-', b'')
+            if normalized.decode('ascii', errors='replace') in _SECRET_NAMES:
+                return True
+    return False
+
+
+def contains_secret_fields(value) -> bool:
+    pending = [value]
+    visited = 0
+    while pending:
+        item = pending.pop()
+        visited += 1
+        require(visited <= 16384, 'request_too_large')
+        if isinstance(item, Mapping):
+            if any(is_secret_field(key) for key in item):
+                return True
+            pending.extend(item.values())
+        elif isinstance(item, (list, tuple)):
+            pending.extend(item)
+    return False
+
+
+def require_safe_request_target(raw_path: bytes, query: bytes = b'', *, maximum: int) -> None:
+    """Inspect raw ASGI/request-target bytes before routing or sending a request."""
+    require(len(raw_path) + len(query) + bool(query) <= maximum, 'path_too_large')
+    require(b'#' not in raw_path and b'#' not in query, 'secure_channel_required')
+    require(raw_path.startswith(b'/') and not raw_path.startswith(b'//'), 'invalid_path')
+    require(not _CONTROL.search(raw_path) and not _CONTROL.search(query), 'invalid_path')
+    require(not _BAD_ESCAPE.search(raw_path) and not _BAD_ESCAPE.search(query), 'invalid_path')
+
+    # Inspect delimiters at every level, not just the name after one decoding.
+    # This catches both %2574oken and ordinary=x%26token=... without interpreting
+    # either spelling as an additional business parameter.
+    for layer in _layers(query):
+        for pair in re.split(rb'[&;]', layer):
+            require(not is_secret_field(pair.partition(b'=')[0]), 'secure_channel_required')
+
+    ambiguous = False
+    for layer in _layers(raw_path):
+        require(b'\\' not in layer and b'\x00' not in layer, 'invalid_path')
+        segments = layer.split(b'/')
+        if len(segments) >= 5 and segments[:3] == [b'', b'-', b'g']:
+            require(segments[4].lower() not in {b'token', b'bootstrap'},
+                    'secure_channel_required')
+        # A labelled assignment in a path is not a permitted secret channel.
+        for segment in segments:
+            if b'=' in segment:
+                require(not is_secret_field(segment.partition(b'=')[0]),
+                        'secure_channel_required')
+        if layer == b'/-' or layer.startswith(b'/-/'):
+            original = raw_path.split(b'/')
+            ambiguous |= (not (raw_path == b'/-' or raw_path.startswith(b'/-/')) or
+                          any(part in {b'.', b'..'} for part in segments) or
+                          any(b'%' in part for part in original[2:4]) or
+                          (len(original) > 4 and original[2] in {b'g', b'p'} and
+                           b'.' in original[3] and b'%' in original[4]))
+    require(not ambiguous, 'not_found')
+
+
+def require_safe_relative_url(path: str, *, maximum: int) -> None:
+    require(path.startswith('/') and not path.startswith('//'), 'invalid_relative_endpoint')
+    # Fragments are not transmitted; reject them before httpx/urlsplit can drop
+    # them. The server can only validate fragment-like bytes actually received.
+    raw_path, _, query = path.encode('utf-8').partition(b'?')
+    require_safe_request_target(raw_path, query, maximum=maximum)
+
+
+def require_matching_host(values: list[str], expected: SplitResult) -> None:
+    """Check Host syntax before a URL parser can discard delimiters or controls."""
+    require(len(values) == 1 and re.fullmatch(
+        r'(?:[A-Za-z0-9._-]+|\[[0-9A-Fa-f:.]+\])(?::[0-9]{1,5})?', values[0])
+        is not None, 'forbidden_host')
+    try:
+        supplied = urlsplit('//' + values[0])
+        port = supplied.port
+        default = 443 if expected.scheme == 'https' else 80
+        require((port is None or port > 0) and supplied.hostname == expected.hostname and
+                (port if port is not None else default) == (expected.port or default),
+                'forbidden_host')
+    except ValueError:
+        raise Failure('forbidden_host') from None