msgctl 0.1.0a1__py3-none-any.whl

msg/core/read_query.py

@@ -0,0 +1,60 @@
+"""Version selection and shared budgets for explicit nested read projections."""
+from collections.abc import Mapping
+from dataclasses import dataclass
+import time
+
+from msg.core.codec import canonical
+from msg.core.errors import require
+
+MAX_READ_DEPTH=4
+MAX_READ_NODES=100
+MAX_READ_COST=1000
+MAX_READ_SCANNED=4096
+NESTED_FIELDS=('id','name','type','path','revision')
+ROOT_FIELDS=(*NESTED_FIELDS,'generation','created_at','modified_at','owner','group','mode')
+
+
+def read_query_version(arguments):
+    if arguments.get('query_version')==3 or isinstance(arguments.get('expand'),Mapping):
+        return 3
+    return 2 if any(name in arguments for name in ('expand','collection','nested_first')) else 1
+
+
+def expansion_schema(depth=MAX_READ_DEPTH):
+    if depth==0:
+        return {'type':'object','maxProperties':0}
+    node={'type':'object','properties':{
+        'limit':{'type':'integer','minimum':1,'maximum':10},
+        'fields':{'type':'array','items':{'enum':list(NESTED_FIELDS)},
+                  'minItems':1,'maxItems':len(NESTED_FIELDS),'uniqueItems':True},
+        'expand':expansion_schema(depth-1)},'additionalProperties':False}
+    return {'type':'object','properties':{'children':node,'replies':node},
+            'additionalProperties':False}
+
+
+@dataclass
+class ReadBudget:
+    deadline: float
+    max_bytes: int
+    nodes: int=0
+    cost: int=0
+    scanned: int=0
+
+    def check(self):
+        require(time.monotonic()<self.deadline,'query_cost_exceeded')
+
+    def scan(self):
+        self.check()
+        self.scanned+=1
+        require(self.scanned<=MAX_READ_SCANNED,'query_cost_exceeded')
+
+    def node(self,fields):
+        self.check()
+        self.nodes+=1
+        self.cost+=1+fields
+        require(self.nodes<=MAX_READ_NODES and self.cost<=MAX_READ_COST,
+                'query_cost_exceeded')
+
+    def output(self,data):
+        self.check()
+        require(len(canonical(data))<=self.max_bytes,'response_too_large')

msg/core/registry.py

@@ -0,0 +1,173 @@
+"""Finite, explicit plugin contracts. No code loading from resources."""
+from __future__ import annotations
+
+from copy import deepcopy
+
+from referencing.exceptions import Unresolvable
+from msg.core.schema_policy import local_validator
+from msg.core.codec import digest,wire
+from msg.core.errors import Failure,require
+
+
+# Older credential contracts remain in the registry so their published short
+# codes and schemas can explain the migration path, but the executor rejects
+# them. Keep this metadata separate from OperationSpec so contract identity and
+# published operation rows remain unchanged.
+_DEPRECATED_OPERATIONS={
+    ('identity.temporary',1):('identity.temporary',3),
+    ('identity.temporary',2):('identity.temporary',3),
+    ('identity.custodial_create',1):('identity.custodial_create',2),
+    ('identity.token_rotate',1):('identity.token_rotate',2),
+    ('identity.token_create',1):('identity.token_create',2),
+}
+
+
+class Registry:
+    def __init__(self):
+        self._types={}
+        self._capabilities={}
+        self._operations={}
+        self._schemas={}
+        self._validators={}
+        self._plugins={}
+        self._frozen=False
+
+    def _insert(self,collection,spec,kind):
+        require(not self._frozen,'registry_frozen')
+        require(spec.version>=1 and spec.name and '*' not in spec.name,'invalid_registry_name')
+        key=(spec.name,spec.version)
+        require(key not in collection,'duplicate_'+kind)
+        collection[key]=spec
+
+    def add_resource_type(self,spec):
+        self._insert(self._types,spec,'resource_type')
+
+    def add_capability(self,spec):
+        self._insert(self._capabilities,spec,'capability')
+
+    def add_operation(self,spec):
+        require(not spec.name.startswith('root.') or spec.entries==frozenset({'local_admin'}),'local_only_contract')
+        require(spec.entries and spec.entries<=frozenset({'local_admin','network','worker'}),'invalid_entries')
+        self._insert(self._operations,spec,'operation')
+
+    def add_schema(self,ref,schema):
+        require(not self._frozen and ref.id not in self._schemas,'schema_conflict')
+        # Keep one owned snapshot for both validation and publication. Caller
+        # dictionaries and lookup results must not mutate a frozen contract.
+        schema=deepcopy(schema)
+        validator=local_validator(schema)
+        self._schemas[ref.id]=schema
+        self._validators[ref.id]=validator
+
+    def add(self,manifest):
+        require(not self._frozen,'registry_frozen')
+        require(manifest.name not in self._plugins,'duplicate_plugin')
+        require(all(d in self._plugins for d in manifest.dependencies),'missing_plugin_dependency')
+        # Validate the entire manifest before modifying any registration map.
+        for collection,values in ((self._types,manifest.resource_types),
+                                  (self._capabilities,manifest.capabilities),
+                                  (self._operations,manifest.operations)):
+            keys=[(v.name,v.version) for v in values]
+            require(len(keys)==len(set(keys)) and not set(keys)&collection.keys(),'plugin_conflict')
+        for item in (*manifest.resource_types,*manifest.capabilities,*manifest.operations):
+            require(item.version>=1 and item.name and '*' not in item.name,'invalid_registry_name')
+        for item in manifest.operations:
+            require(not item.name.startswith('root.') or item.entries==frozenset({'local_admin'}),'local_only_contract')
+            require(item.entries and item.entries<=frozenset({'local_admin','network','worker'}),'invalid_entries')
+        for item in manifest.resource_types:
+            self.add_resource_type(item)
+        for item in manifest.capabilities:
+            self.add_capability(item)
+        for item in manifest.operations:
+            self.add_operation(item)
+        self._plugins[manifest.name]=manifest
+
+    def freeze(self):
+        require('identity' in self._plugins,'identity_plugin_required')
+        for spec in self._operations.values():
+            require(spec.input_schema.id in self._schemas and spec.output_schema.id in self._schemas,'missing_schema')
+        for cap in self._capabilities.values():
+            require(cap.scope_types<=set(n for n,v in self._types),'unknown_scope_type')
+            require(all(op in {f'{s.name}@{s.version}' for s in self._operations.values()}
+                        for op in cap.operations),'unknown_capability_operation')
+        self._frozen=True
+
+    @property
+    def frozen(self):
+        return self._frozen
+
+    def _get(self,collection,name,version,kind):
+        try:
+            return collection[(name,version)]
+        except KeyError as exc:
+            raise Failure('unknown_'+kind) from exc
+
+    def operation(self,name,version=1):
+        return self._get(self._operations,name,version,'operation')
+
+    def capability(self,name,version=1):
+        return self._get(self._capabilities,name,version,'capability')
+
+    def resource_type(self,name,version=1):
+        return self._get(self._types,name,version,'resource_type')
+
+    def capabilities(self):
+        return tuple(self._capabilities[k] for k in sorted(self._capabilities))
+
+    def operations(self,entry=None):
+        return tuple(self._operations[k] for k in sorted(self._operations)
+                     if entry is None or entry in self._operations[k].entries)
+
+    def resource_types(self):
+        return tuple(self._types[k] for k in sorted(self._types))
+
+    def schema(self,ref):
+        key=ref.id if hasattr(ref,'id') else ref
+        require(key in self._schemas,'schema_not_found')
+        return deepcopy(self._schemas[key])
+
+    def validate(self,ref,value):
+        try:
+            errors=sorted(self._validators[ref.id if hasattr(ref,"id") else ref].iter_errors(wire(value)),key=lambda e:str(e.path))
+        except Unresolvable as exc:
+            # Reference exception messages can include filesystem paths/URIs.
+            raise Failure('schema_reference_unresolvable') from exc
+        if errors:
+            raise Failure('schema_validation','.'.join(str(i) for i in errors[0].path) or 'arguments')
+
+    def describe(self,spec):
+        from msg.bootstrap import RULE_PATHS
+        name=spec.name
+        if name.startswith('identity.'):
+            rules=('identity','auth')
+        elif name.startswith('content.topic_') or name.startswith('discussion.'):
+            rules=('topics','read-write')
+        elif name.startswith('content.'):
+            rules=('read-write',)
+        elif name.startswith(('transfer.','keystore.','git.')):
+            rules=('files','protocol')
+        elif name.startswith(('cert.','group.')):
+            rules=('auth',)
+        elif name.startswith(('system.','tool.')):
+            rules=('security','protocol')
+        elif name.startswith('discovery.'):
+            rules=('read-write','protocol')
+        else:
+            rules=('protocol',)
+        rule_ids=tuple('msg.'+rule for rule in rules)
+        require(len(set(rule_ids))==len(rule_ids) and all(rid in RULE_PATHS for rid in rule_ids),
+                'dangling_requires_rules',name)
+        result={'name':spec.name,'version':spec.version,'effect':spec.effect,
+                'entries':sorted(spec.entries),'require_signature':spec.require_signature,
+                'input_schema':wire(spec.input_schema),'output_schema':wire(spec.output_schema),
+                'requires_rules':[{'rule_id':rule_id,'path':RULE_PATHS[rule_id]}
+                                  for rule_id in rule_ids]}
+        replacement=_DEPRECATED_OPERATIONS.get((spec.name,spec.version))
+        if replacement is not None:
+            result.update(deprecated=True,
+                          replaced_by=f'{replacement[0]}@{replacement[1]}')
+        return result
+
+    def catalog(self,entry='network'):
+        values=[self.describe(s) for s in self.operations(entry)]
+        return {'version':1,'digest':digest(values),'operations':values}

msg/core/requests.py

@@ -0,0 +1,58 @@
+"""The same signed envelope is used by HTTP, path GET, GraphQL, MCP and msg."""
+from __future__ import annotations
+from dataclasses import replace
+from datetime import UTC,datetime,timedelta
+from uuid import uuid4
+from msg.core.codec import canonical,digest,wire
+from msg.core.models import OperationRequest,SignatureProof,TokenProof
+
+
+# Old issuance contracts did not bind independent recovery material before
+# commit. Never execute or replay them: a historical result cannot prove
+# whether its secret was already delivered to the caller.
+SECRET_DELIVERY_MIN_VERSION = {
+    'identity.temporary': 3,
+    'identity.custodial_create': 2,
+    'identity.token_rotate': 2,
+    'identity.token_create': 2,
+    'identity.token_recover': 1,
+}
+
+
+def payload_fields(request):
+    data=wire(request)
+    for field in ('proof','payload_digest','source','expires_at'):
+        data.pop(field)
+    return data
+
+
+def signing_bytes(request):
+    data=wire(request)
+    data.pop('proof')
+    return canonical(data)
+
+
+def request_for(operation,arguments,service, *, subject=None,signer=None,token=None,
+                certificates=(),request_id=None,expires_at=None,source='msg',expected=(),return_fields=(),
+                contract_version=1):
+    request=OperationRequest(request_id=request_id or uuid4().hex,protocol_version=1,
+        operation=operation,contract_version=contract_version,target_service=service,subject=subject,
+        arguments=arguments,expected_generations=tuple(expected),
+        expires_at=expires_at or datetime.now(UTC)+timedelta(minutes=3),payload_digest='',proof=None,
+        return_fields=tuple(return_fields),source=source)
+    request=replace(request,payload_digest=digest(payload_fields(request)))
+    if signer is not None:
+        request=replace(request,proof=SignatureProof(signature=signer.sign(signing_bytes(request),purpose='request'),
+                                                   certificates=tuple(certificates)))
+    elif token is not None:
+        request=replace(request,proof=TokenProof(credential_id=token[0],token=token[1]))
+    return request
+
+
+def receipt_bytes(result):
+    value=wire(result)
+    for field in ('receipt','replayed','prefer_cli','cli_url'):
+        value.pop(field,None)
+    if result.operation in SECRET_DELIVERY_MIN_VERSION and value.get('data'):
+        value['data'].pop('token',None)
+    return canonical(value)

msg/core/schema_policy.py

@@ -0,0 +1,28 @@
+"""Self-contained JSON Schema contracts with no implicit filesystem/network I/O."""
+from jsonschema import Draft202012Validator
+from referencing import Registry as ReferenceRegistry
+from referencing.jsonschema import DRAFT202012
+
+from msg.core.errors import require
+
+
+def local_validator(schema):
+    Draft202012Validator.check_schema(schema)
+    pending = [DRAFT202012.create_resource(schema)]
+    while pending:
+        resource = pending.pop()
+        contents = resource.contents
+        if isinstance(contents, dict):
+            for keyword in ('$ref', '$dynamicRef', '$recursiveRef'):
+                if keyword in contents:
+                    reference = contents[keyword]
+                    require(isinstance(reference, str) and
+                            (reference == '' or reference.startswith('#')),
+                            'remote_schema_reference_forbidden')
+        # Follow schema-bearing keywords, not properties named "$ref" or ordinary
+        # instance data in default/examples/const. Nested dialects are respected.
+        pending.extend(resource.subresources())
+    # Fragment pointers may target an annotation containing another schema. An
+    # explicit registry also blocks that path: its default retriever performs no
+    # I/O, unlike jsonschema's legacy automatic reference retrieval behavior.
+    return Draft202012Validator(schema, registry=ReferenceRegistry())

msg/core/schemas.py

@@ -0,0 +1,30 @@
+"""Small explicit JSON schemas; no open-ended executable configuration."""
+STRING={'type':'string'}
+IDENTIFIER={'type':'string','minLength':1,'maxLength':160}
+INTEGER={'type':'integer','minimum':0}
+BOOLEAN={'type':'boolean'}
+BYTES={'type':'string','pattern':'^[A-Za-z0-9_-]*$'}
+REF={'type':'object','properties':{'id':IDENTIFIER,'revision':{'type':['string','null']}},'required':['id'],'additionalProperties':False}
+SCOPE={'type':'object','properties':{'resource_id':IDENTIFIER,'descendants':BOOLEAN},'required':['resource_id'],'additionalProperties':False}
+NETWORK_CONSTRAINTS={'type':'object','properties':{
+    'hosts':{'type':'array','items':STRING},'schemes':{'type':'array','items':{'enum':['http','https']}},
+    'methods':{'type':'array','items':{'enum':['GET','HEAD','POST','PUT','PATCH','DELETE','OPTIONS']}},
+    'ports':{'type':'array','items':{'type':'integer','minimum':1,'maximum':65535}},
+    'timeout_ms':{'type':'integer','minimum':1},'max_response_bytes':{'type':'integer','minimum':1},
+    'max_redirects':{'type':'integer','minimum':0}},'additionalProperties':False}
+GRANT={'type':'object','properties':{'capability':IDENTIFIER,'version':{'const':1},'scope':SCOPE,
+    'operations':{'type':'array','items':IDENTIFIER,'minItems':1,'uniqueItems':True},
+    'constraints':{'type':'object'}},'required':['capability','version','scope','operations','constraints'],
+    'additionalProperties':False}
+GRANTS={'type':'array','items':GRANT}
+ISSUANCE={'type':['object','null'],'properties':{'issue_grants':GRANTS,'max_cert_ttl_seconds':INTEGER,
+    'max_child_ca_depth':INTEGER,'max_delegation_depth':INTEGER},
+    'required':['issue_grants','max_cert_ttl_seconds','max_child_ca_depth','max_delegation_depth'],'additionalProperties':False}
+SIGNATURE={'type':'object','properties':{'key_id':IDENTIFIER,'algorithm':{'const':'ed25519'},'value':BYTES},
+           'required':['key_id','algorithm','value'],'additionalProperties':False}
+OUTPUT={'type':'object','properties':{'resources':{'type':'array','items':REF},'data':{'type':['object','null']},
+    'output':{'anyOf':[REF,{'type':'null'}]}},'required':['resources','data','output'],'additionalProperties':False}
+
+
+def obj(properties=None,required=()):
+    return {'type':'object','properties':properties or {},'required':list(required),'additionalProperties':False}

msg/core/tags.py

@@ -0,0 +1,21 @@
+"""Canonical user tags; labels never participate in authorization."""
+from __future__ import annotations
+
+import unicodedata
+
+from msg.core.errors import require
+
+
+def normalize_tag(value: str) -> str:
+    require(type(value) is str, 'invalid_tag')
+    tag = unicodedata.normalize('NFKC', value).strip().casefold()
+    tag = unicodedata.normalize('NFC', tag)
+    require(1 <= len(tag) <= 48 and len(tag.encode('utf-8')) <= 96, 'invalid_tag')
+    require(tag[0].isalnum() and all(char.isalnum() or char in {'-', '_'} for char in tag),
+            'invalid_tag')
+    return tag
+
+
+def normalize_tags(values) -> tuple[str, ...]:
+    require(type(values) in {list, tuple} and len(values) <= 16, 'invalid_tags')
+    return tuple(sorted({normalize_tag(value) for value in values}))

msg/core/template_dsl.py

@@ -0,0 +1,94 @@
+"""A non-executable, immutable template DSL."""
+from __future__ import annotations
+import re
+from dataclasses import dataclass
+from msg.core.codec import canonical,freeze_json,loads,decode
+from msg.core.errors import Failure,require
+from msg.core.models import FieldSpec,ResourceRef
+
+
+@dataclass(frozen=True,slots=True)
+class TemplateDefinition:
+    name: str
+    version: int
+    fields: tuple[FieldSpec,...]
+
+
+TemplateSyntaxError=Failure
+
+
+def _check(spec,value):
+    if value is None and not spec.required:
+        return None
+    if spec.type in {'str','text','enum'}:
+        require(type(value) is str,'template_type_error',spec.name)
+    elif spec.type=='int':
+        require(type(value) is int,'template_type_error',spec.name)
+    elif spec.type=='bool':
+        require(type(value) is bool,'template_type_error',spec.name)
+    elif spec.type in {'ref','file'}:
+        if not isinstance(value,str):
+            decode(ResourceRef,value)
+        else:
+            require(bool(re.fullmatch(r'[A-Za-z0-9_.:-]{1,128}',value)),'template_reference_error',spec.name)
+    if spec.type=='enum':
+        require(value in spec.choices,'template_enum_error',spec.name)
+    return freeze_json(value)
+
+
+def parse_template(source):
+    require(type(source) is str,'invalid_template')
+    lines=[s.strip() for s in source.splitlines() if s.strip() and not s.lstrip().startswith('#')]
+    require(bool(lines),'empty_template')
+    header=re.fullmatch(r'([A-Za-z][\w.-]*)@([1-9][0-9]*)',lines[0])
+    require(header is not None,'invalid_template_header')
+    result=[]
+    names=set()
+    for line in lines[1:]:
+        match=re.fullmatch(r'([A-Za-z][\w.-]*):([a-z]+(?:\([^)]*\))?)([!?]?)(?:=(.*))?',line)
+        require(match is not None,'invalid_template_field')
+        name,type_name,marker,default=match.groups()
+        require(name not in names,'duplicate_field',name)
+        names.add(name)
+        choices=()
+        if type_name.startswith('enum('):
+            choices=tuple(x.strip() for x in type_name[5:-1].split(','))
+            require(all(choices) and len(choices)==len(set(choices)),'invalid_enum',name)
+            type_name='enum'
+        require(type_name in {'str','text','int','bool','enum','ref','file'},'unknown_field_type',name)
+        require(marker!='!' or default is None,'required_field_has_default',name)
+        spec=FieldSpec(name=name,type=type_name,required=marker=='!',choices=choices)
+        if default is not None:
+            try:
+                value=loads(default)
+            except Failure:
+                require(type_name in {'str','text','enum','ref','file'},'invalid_default',name)
+                value=default
+            value=_check(spec,value)
+            spec=FieldSpec(name=name,type=type_name,required=False,choices=choices,default_json=canonical(value))
+        result.append(spec)
+    return TemplateDefinition(name=header[1],version=int(header[2]),fields=tuple(result))
+
+
+def normalize_values(template,values):
+    require(isinstance(values,dict) or hasattr(values,'items'),'invalid_template_values')
+    names={s.name for s in template.fields}
+    require(set(values)<=names,'unknown_template_field')
+    result={}
+    for spec in template.fields:
+        if spec.name in values:
+            result[spec.name]=_check(spec,values[spec.name])
+        elif spec.default_json is not None:
+            result[spec.name]=loads(spec.default_json)
+        else:
+            require(not spec.required,'missing_required',spec.name)
+    return result
+
+
+def canonical_values_json(values):
+    return canonical(values)
+
+
+def render_values(values):
+    return '\n\n'.join(f'**{name}**\n\n{value if isinstance(value,str) else canonical(value).decode()}'
+                         for name,value in values.items())+'\n'