msgctl 0.1.0a1__py3-none-any.whl

msg/constants.py

@@ -0,0 +1,11 @@
+"""Protocol identities and protected bootstrap IDs, not application workflows."""
+ROOT_SPACE='r_root'
+ROOT_SUBJECT='u_root'
+ONLINE_CA='u_online_ca'
+PUBLIC_GROUP='g_public'
+ADMINS_GROUP='g_admins'
+CA_SPACE='t_ca'
+CSR_SPACE='t_csr'
+CERT_SPACE='t_certificates'
+TOOLS_SPACE='t_tools'
+PROTOCOL_VERSION=1

msg/core/batching.py

@@ -0,0 +1,23 @@
+"""The one child-envelope validator for atomic and independent batches."""
+from msg.core.codec import canonical
+from msg.core.errors import require
+from msg.core.packet import decode_packet
+from msg.core.requests import SECRET_DELIVERY_MIN_VERSION
+
+# Credential delivery has response-only secrets; it requires its own call.
+NO_BATCH=frozenset(SECRET_DELIVERY_MIN_VERSION) | {'identity.register','identity.upgrade'}
+
+
+def packets(registry,request,subject,max_bytes=None):
+    max_bytes=max_bytes or len(canonical(request))
+    values=[]
+    for value in request.arguments['requests']:
+        packet=decode_packet(value,max_bytes)
+        spec=registry.operation(packet.operation,packet.contract_version)
+        require(spec.effect in {'read','transaction'} and not packet.operation.startswith('batch.')
+                and packet.operation not in NO_BATCH and 'network' in spec.entries,'operation_not_batchable')
+        require(packet.subject==subject,'batch_subject_mismatch')
+        values.append(packet)
+    require(len({p.request_id for p in values})==len(values),'duplicate_batch_request_id')
+    require(request.request_id not in {p.request_id for p in values},'recursive_request_id')
+    return values

msg/core/codec.py

@@ -0,0 +1,253 @@
+"""Versioned deterministic JSON, strict parsing and immutable contract records.
+
+Canonical v1 uses UTF-8, sorted Unicode keys, compact separators and JSON finite
+numbers as emitted by Python. It is not advertised as RFC 8785/JCS. Signed
+request test vectors define the wire representation for non-Python clients.
+"""
+from __future__ import annotations
+
+import base64
+import dataclasses
+import hashlib
+import json
+import math
+import re
+import types
+import typing
+from functools import lru_cache
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from types import MappingProxyType
+from .errors import Failure, require
+
+
+def freeze_json(value):
+    if value is None or type(value) in (bool, int, str):
+        return value
+    if type(value) is float:
+        require(math.isfinite(value), "non_finite_float")
+        return value
+    if isinstance(value, (tuple, list)):
+        return tuple(freeze_json(x) for x in value)
+    if isinstance(value, Mapping):
+        require(all(type(k) is str for k in value), "non_string_json_key")
+        return MappingProxyType({k: freeze_json(v) for k, v in value.items()})
+    raise Failure("unsupported_json_type")
+
+
+def b64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def unb64(value: str, *, limit: int = 16 * 1024 * 1024) -> bytes:
+    require(type(value) is str and len(value) <= (limit * 4 // 3 + 4), "invalid_base64")
+    require(bool(re.fullmatch(r"[A-Za-z0-9_-]*", value)), "invalid_base64")
+    try:
+        result = base64.b64decode(value + "=" * (-len(value) % 4), altchars=b"-_", validate=True)
+    except (ValueError, TypeError) as exc:
+        raise Failure("invalid_base64") from exc
+    require(b64(result) == value and len(result) <= limit, "invalid_base64")
+    return result
+
+
+def timestamp(value: datetime) -> str:
+    require(isinstance(value, datetime) and value.tzinfo is not None and
+            value.utcoffset() is not None, "naive_datetime")
+    return value.astimezone(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+def parse_time(value: str) -> datetime:
+    require(type(value) is str and value.endswith("Z"), "invalid_datetime")
+    try:
+        result = datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise Failure("invalid_datetime") from exc
+    require(result.tzinfo is not None, "naive_datetime")
+    return result.astimezone(UTC)
+
+
+def wire(value, *, compact: bool = False):
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        result = {}
+        for field in dataclasses.fields(value):
+            v = getattr(value, field.name)
+            if v is None and field.metadata.get('omit_if_none'):
+                continue
+            if compact and (v is None or v == () or v == frozenset()):
+                continue
+            result[field.name] = f"{v:04o}" if field.name == "mode" else wire(v, compact=compact)
+        return result
+    if isinstance(value, Mapping):
+        return {k: wire(v, compact=compact) for k, v in value.items()
+                if not compact or v is not None}
+    if isinstance(value, (tuple, list)):
+        return [wire(v, compact=compact) for v in value]
+    if isinstance(value, (set, frozenset)):
+        return sorted((wire(v, compact=compact) for v in value), key=canonical)
+    if isinstance(value, datetime):
+        return timestamp(value)
+    if isinstance(value, bytes):
+        return b64(value)
+    if isinstance(value, Path):
+        return str(value)
+    if value is None or type(value) in (bool, int, str):
+        return value
+    if type(value) is float and math.isfinite(value):
+        return value
+    raise Failure("invalid_json_value")
+
+
+def canonical(value) -> bytes:
+    try:
+        return json.dumps(wire(value), ensure_ascii=False, sort_keys=True,
+                          separators=(",", ":"), allow_nan=False).encode("utf-8")
+    except (UnicodeError, ValueError, TypeError, RecursionError) as exc:
+        if isinstance(exc, Failure):
+            raise
+        raise Failure("invalid_json_value") from exc
+
+
+def digest(value: bytes | object) -> str:
+    return "sha256:" + hashlib.sha256(value if isinstance(value, bytes) else canonical(value)).hexdigest()
+
+
+def loads(raw: str | bytes):
+    def pairs(items):
+        result = {}
+        for key, value in items:
+            require(key not in result, "duplicate_json_key", key)
+            result[key] = value
+        return result
+    def constant(_):
+        raise Failure("non_finite_float")
+    try:
+        value = json.loads(raw, object_pairs_hook=pairs, parse_constant=constant)
+        freeze_json(value)
+        return value
+    except (UnicodeError, ValueError, TypeError, RecursionError) as exc:
+        if isinstance(exc, Failure):
+            raise
+        raise Failure("invalid_json") from exc
+
+
+@lru_cache(maxsize=256)
+def _record_shape(cls):
+    # Registered Python classes are immutable schema definitions. This cache
+    # never contains user identities, authorization decisions, or mutable rows.
+    return ({f.name: f for f in dataclasses.fields(cls)}, typing.get_type_hints(cls))
+
+
+def decode(cls, value, field: str = ""):
+    """Decode only declared fields; booleans never masquerade as integers."""
+    if isinstance(cls, typing.TypeAliasType):
+        if cls.__name__ in {"Json", "JsonMap"}:
+            if cls.__name__ == "JsonMap":
+                require(isinstance(value, Mapping), "invalid_type", field)
+            return freeze_json(value)
+        return decode(cls.__value__, value, field)
+    if hasattr(cls, "__supertype__"):
+        return decode(cls.__supertype__, value, field)
+    origin, args = typing.get_origin(cls), typing.get_args(cls)
+    if origin in (typing.Union, types.UnionType):
+        for option in args:
+            try:
+                return decode(option, value, field)
+            except (Failure, TypeError, ValueError):
+                continue
+        raise Failure("invalid_union", field)
+    if origin is typing.Literal:
+        require(any(type(value) is type(v) and value == v for v in args), "invalid_enum", field)
+        return value
+    if origin in (tuple, list, frozenset, set):
+        require(isinstance(value, (tuple, list, set, frozenset)), "invalid_type", field)
+        if origin is tuple and args and args[-1] is not Ellipsis:
+            require(len(args) == len(value), "invalid_length", field)
+            return tuple(decode(t, x, field) for t, x in zip(args, value, strict=True))
+        child = args[0] if args else typing.Any
+        return origin(decode(child, x, field) for x in value)
+    if origin in (dict, Mapping):
+        require(isinstance(value, Mapping), "invalid_type", field)
+        return MappingProxyType({decode(args[0], k, field): decode(args[1], v, field)
+                                 for k, v in value.items()})
+    if cls is datetime:
+        return parse_time(value)
+    if cls is bytes:
+        return unb64(value)
+    if cls is Path:
+        require(type(value) is str, "invalid_type", field)
+        return Path(value)
+    if cls is typing.Any:
+        return freeze_json(value)
+    if dataclasses.is_dataclass(cls):
+        require(isinstance(value, Mapping), "invalid_type", field)
+        fields, hints = _record_shape(cls)
+        unknown = set(value) - fields.keys()
+        require(not unknown, "unknown_field", (field + "." if field else "") +
+                (sorted(unknown)[0] if unknown else ""))
+        result = {}
+        for name, f in fields.items():
+            where = f"{field}.{name}" if field else name
+            if name not in value:
+                require(f.default is not dataclasses.MISSING or
+                        f.default_factory is not dataclasses.MISSING, "missing_field", where)
+                continue
+            if name == "mode":
+                mode = value[name]
+                require(type(mode) is str and re.fullmatch(r"[0-7]{4}", mode) is not None,
+                        "invalid_mode", where)
+                result[name] = int(mode, 8)
+            else:
+                result[name] = decode(hints[name], value[name], where)
+        return cls(**result)
+    if cls in (str, bool, int, float, type(None)):
+        require(type(value) is cls, "invalid_type", field)
+        if cls is float:
+            require(math.isfinite(value), "non_finite_float", field)
+        return value
+    raise Failure("unsupported_contract_type", field)
+
+
+def validate_record(obj):
+    for f in dataclasses.fields(obj):
+        value = getattr(obj, f.name)
+        if isinstance(value, datetime):
+            require(value.tzinfo is not None and value.utcoffset() is not None, "naive_datetime", f.name)
+            object.__setattr__(obj, f.name, value.astimezone(UTC))
+        elif isinstance(value, Mapping):
+            object.__setattr__(obj, f.name, freeze_json(value))
+        elif isinstance(value, list):
+            object.__setattr__(obj, f.name, tuple(value))
+        elif isinstance(value, set):
+            object.__setattr__(obj, f.name, frozenset(value))
+        if f.name in {"generation", "size", "expected_size", "offset", "attempts", "delegation_depth",
+                      "max_child_ca_depth", "max_delegation_depth", "max_redirects"} and value is not None:
+            require(type(value) is int and value >= 0, "invalid_nonnegative_integer", f.name)
+        if f.name in {"version", "type_version", "format_version", "protocol_version", "contract_version",
+                      "max_cert_ttl_seconds", "requested_ttl_seconds"}:
+            if f.name == "version" and type(obj).__name__ == "PluginManifest":
+                require(type(value) is str and bool(value), "invalid_version", f.name)
+            elif f.name == "version" and type(obj).__name__ == "Membership":
+                require(type(value) is int and value >= 0, "invalid_version", f.name)
+            else:
+                require(type(value) is int and value >= 1, "invalid_version", f.name)
+    if type(obj).__name__ == "Resource":
+        from msg.core.tags import normalize_tags
+
+        require(type(obj.mode) is int and 0 <= obj.mode <= 0o7777, "invalid_mode")
+        require(obj.state in {"active", "archived", "purged"}, "invalid_state")
+        require(obj.parent != obj.id, "parent_cycle")
+        require(obj.tags == normalize_tags(obj.tags), "invalid_tags")
+    if type(obj).__name__ == "Relation" and obj.excerpt is not None:
+        require(len(obj.excerpt) == 2 and all(type(n) is int for n in obj.excerpt)
+                and 0 <= obj.excerpt[0] <= obj.excerpt[1], "invalid_byte_range")
+    if hasattr(obj, "not_before") and getattr(obj, "expires_at", None) is not None:
+        require(obj.not_before < obj.expires_at, "invalid_validity")
+
+
+def record(**kwargs):
+    """Dataclass decoration plus local validation, not a domain base class."""
+    def decorate(cls):
+        cls.__post_init__ = validate_record
+        return dataclasses.dataclass(**kwargs)(cls)
+    return decorate

msg/core/contracts.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from .models import *
+from .query import QuerySession
+from .tool_execution import ToolRunner
+
+class MetadataSession(QuerySession, Protocol):
+    def on_rollback(self, effect: Callable[[], Awaitable[None]]) -> None: ...
+    async def resource(self, id: ResourceId) -> Resource: ...
+    async def resolve(self, path: str) -> ResourceId: ...
+    async def path(self, id: ResourceId) -> str: ...
+    async def ancestors(self, id: ResourceId) -> tuple[Resource, ...]: ...
+    async def children(
+        self, parent: ResourceId, cursor: str | None, limit: int
+    ) -> Page[Resource]: ...
+    async def revision(self, ref: ResourceRef) -> Revision: ...
+    async def history(
+        self, id: ResourceId, cursor: str | None, limit: int
+    ) -> Page[Revision]: ...
+    async def insert(self, resource: Resource) -> None: ...
+    async def replace(
+        self, resource: Resource, expected_generation: int
+    ) -> None: ...
+    async def append_revision(self, revision: Revision) -> None: ...
+    async def subject(self, id: ResourceId) -> Subject: ...
+    async def organization(self, id: ResourceId) -> Organization: ...
+    async def credential(self, id: ID) -> Credential: ...
+    async def certificate(self, id: ResourceId) -> Certificate: ...
+    async def certificate_revoked(self, id: ResourceId) -> bool: ...
+    async def memberships(
+        self, subject: ResourceId
+    ) -> tuple[Membership, ...]: ...
+    async def request_result(
+        self, subject: ResourceId, id: RequestId, digest: Digest
+    ) -> OperationResult | None: ...
+    async def save_result(
+        self, subject: ResourceId, digest: Digest, result: OperationResult
+    ) -> None: ...
+    async def update_identity(
+        self, record: Subject | Organization | Membership | EmailSettings,
+        expected_generation: int
+    ) -> None: ...
+    async def save_credential(
+        self, credential: Credential, expected_auth_version: int
+    ) -> None: ...
+    async def csr(self, id: ResourceId) -> CertificateRequest: ...
+    async def csr_state(
+        self, id: ResourceId
+    ) -> CertificateRequestState: ...
+    async def save_csr(
+        self, request: CertificateRequest
+    ) -> None: ...
+    async def transition_csr(
+        self, state: CertificateRequestState, expected_generation: int
+    ) -> None: ...
+    async def revoke_certificate(
+        self, id: ResourceId, event: AuditEvent
+    ) -> None: ...
+    async def register_certificate(
+        self, certificate: Certificate, csr_id: ResourceId,
+        expected_generation: int
+    ) -> None: ...
+    async def transfer(self, id: ID) -> TransferSession: ...
+    async def save_transfer(
+        self, session: TransferSession, expected_generation: int | None
+    ) -> None: ...
+    async def put_chunk(self, chunk: TransferChunk) -> None: ...
+    async def missing_ranges(
+        self, id: ID, cursor: str | None, limit: int
+    ) -> Page[ByteRange]: ...
+    async def append_event(self, event: Event) -> None: ...
+    async def append_audit(self, event: AuditEvent) -> None: ...
+    async def enqueue(self, job: EffectJob) -> None: ...
+    async def job(self, id: ID) -> EffectJob: ...
+    async def save_job(self, job: EffectJob) -> None: ...
+
+
+class MetadataStore(Protocol):
+    def transaction(
+        self, *, write: bool
+    ) -> AbstractAsyncContextManager[MetadataSession]: ...
+
+
+class ContentStore(Protocol):
+    async def put(
+        self, chunks: AsyncIterator[bytes], media_type: str,
+        expected_digest: Digest | None = None
+    ) -> BlobRef: ...
+    def read(
+        self, blob: BlobRef, byte_range: ByteRange | None = None
+    ) -> AsyncIterator[bytes]: ...
+    async def pin(self, blob: BlobRef, lease_id: ID) -> None: ...
+    async def unpin(self, blob: BlobRef, lease_id: ID) -> None: ...
+
+
+class Authenticator(Protocol):
+    async def authenticate(
+        self, request: OperationRequest, session: MetadataSession,
+        *, entry: Entry
+    ) -> Principal: ...
+
+
+class Authorizer(Protocol):
+    async def require(
+        self, context: ExecutionContext, request: OperationRequest,
+        checks: tuple[AccessRequirement, ...], session: MetadataSession
+    ) -> tuple[ResourceRef, ...]: ...
+
+
+class Signer(Protocol):
+    @property
+    def key_id(self) -> ID: ...
+    def sign(self, payload: bytes, *, purpose: str) -> Signature: ...
+
+
+class ClientTransport(Protocol):
+    async def discover(self) -> TransportLimits: ...
+    async def call(self, request: OperationRequest) -> OperationResult: ...
+
+
+# Compatibility import only. The unused invoke -> ResourceRef declaration never
+# described the injected runner. ToolRunner is now the one actual execution port;
+# publication and current-authority/attempt checks remain owned by EffectWorker.
+ToolExecutor = ToolRunner
+
+
+class NotificationSender(Protocol):
+    async def send(self, job: EffectJob) -> Literal['sent', 'uncertain']: ...

msg/core/cursors.py

@@ -0,0 +1,68 @@
+"""Opaque position cursors are not authentication credentials."""
+import hmac
+from msg.core.codec import b64,unb64,canonical,loads,digest,parse_time,wire
+from msg.core.errors import require
+
+
+class CursorCodec:
+    def __init__(self,key):
+        self.key=key
+
+    def encode(self,kind,query,position):
+        data=canonical({'v':1,'kind':kind,'query':query,'position':position})
+        tag=hmac.digest(self.key,b'cursor-v1\0'+data,'sha256')
+        return b64(data)+'.'+b64(tag)
+
+    def inspect(self,value):
+        require(isinstance(value,str) and len(value)<=8192 and value.count('.')==1,'invalid_cursor')
+        encoded,signature=value.split('.')
+        raw=unb64(encoded)
+        require(hmac.compare_digest(hmac.digest(self.key,b'cursor-v1\0'+raw,'sha256'),unb64(signature)),'invalid_cursor')
+        data=loads(raw)
+        require(data.get('v')==1,'invalid_cursor')
+        return data
+
+    def decode(self,value,kind,query):
+        data=self.inspect(value)
+        require(data.get('v')==1 and data.get('kind')==kind and data.get('query')==query,'cursor_query_mismatch')
+        return data['position']
+
+    def encode_page(self,operation,arguments,position,snapshot,principal,expires_at):
+        query={'operation':operation,'arguments':arguments}
+        return self.encode('read-page',query,{'last':position,'snapshot':wire(snapshot),
+            'principal':principal,'expires_at':wire(expires_at),'query_digest':digest(query)})
+
+    def inspect_page(self,value,now):
+        data=self.inspect(value)
+        require(data.get('kind')=='read-page','cursor_kind_mismatch')
+        position=data.get('position')
+        require(isinstance(position,dict) and position.get('query_digest')==digest(data.get('query')),
+                'invalid_cursor')
+        require(now<parse_time(position['expires_at']),'cursor_expired')
+        return data['query'],position
+
+    def decode_page(self,value,operation,arguments,principal,now):
+        query,position=self.inspect_page(value,now)
+        require(query=={'operation':operation,'arguments':arguments},'cursor_query_mismatch')
+        require(position['principal']==principal,'cursor_principal_mismatch')
+        return position['last'],parse_time(position['snapshot'])
+
+    def encode_read(self,ref,max_bytes,offset,fence,line_start,continued,principal,expires_at,
+                    previous=None):
+        query={'ref':wire(ref),'max_bytes':max_bytes}
+        return self.encode('read-segment',query,{'offset':offset,'fence':fence,'line_start':line_start,
+            'continued':continued,'principal':principal,'expires_at':wire(expires_at),
+            'previous':previous})
+
+    def inspect_read(self,value,now):
+        data=self.inspect(value)
+        require(data.get('kind')=='read-segment','cursor_kind_mismatch')
+        position=data.get('position')
+        require(isinstance(position,dict) and now<parse_time(position['expires_at']),
+                'cursor_expired')
+        return data['query'],position
+
+    def decode_read(self,value,principal,now):
+        query,position=self.inspect_read(value,now)
+        require(position['principal']==principal,'cursor_principal_mismatch')
+        return query,position

msg/core/email_address.py

@@ -0,0 +1,33 @@
+"""Validate one exact mailbox before binding or passing it to SMTP.
+
+An email endpoint is an addr-spec, not a display name, group or address list.
+Do not normalize it: the verified endpoint snapshot must identify the same bytes.
+"""
+from __future__ import annotations
+
+from email import policy
+from email.errors import HeaderParseError, NonASCIILocalPartDefect
+from email.headerregistry import Address
+import re
+
+from msg.core.errors import Failure, require
+
+
+def validate_address(address: str) -> Address:
+    require(isinstance(address, str) and len(address) <= 254 and
+            re.fullmatch(r'[^\s@]+@[^\s@]+\.[^\s@]+', address) is not None and
+            not any(ord(c) < 32 or ord(c) == 127 for c in address), 'invalid_email')
+    try:
+        header = policy.default.header_factory('To', address)
+        mailboxes, groups = header.addresses, header.groups
+    except (HeaderParseError, ValueError, IndexError):
+        raise Failure('invalid_email') from None
+    # SMTPUTF8 mailboxes remain supported. All other parser defects, including
+    # obsolete or partially recovered syntax, fail closed rather than redirect.
+    require(len(mailboxes) == len(groups) == 1 and groups[0].display_name is None and
+            all(isinstance(d, NonASCIILocalPartDefect) for d in header.defects),
+            'invalid_email')
+    mailbox = mailboxes[0]
+    require(bool(mailbox.username and mailbox.domain) and mailbox.addr_spec == address,
+            'invalid_email')
+    return mailbox

msg/core/errors.py

@@ -0,0 +1,22 @@
+"""Stable errors shared by business operations and every transport."""
+from __future__ import annotations
+
+
+class Failure(ValueError):
+    def __init__(self, code: str, field: str | None = None, *, retryable: bool = False,
+                 details: dict | None = None):
+        super().__init__(code)
+        self.code, self.field, self.retryable, self.details = code, field, retryable, details
+
+    def as_dict(self) -> dict:
+        value = {"code": self.code, "retryable": self.retryable}
+        if self.field:
+            value["field_path"] = self.field
+        if self.details:
+            value["details"] = self.details
+        return value
+
+
+def require(condition: bool, code: str, field: str | None = None, **kwargs) -> None:
+    if not condition:
+        raise Failure(code, field, **kwargs)

msg/core/events.py

@@ -0,0 +1,6 @@
+"""Deterministic committed-operation event identity shared by all producers."""
+from msg.core.codec import digest
+
+
+def event_id(request, subject):
+    return 'e_' + digest((subject, request.request_id))[7:39]

msg/core/execution_ports.py

@@ -0,0 +1,20 @@
+"""Fixed executor dependencies, not plugin hooks or a workflow interface.
+
+ResultProjection is a permission-checked read in the existing transaction.
+TransactionalEventNotifications may enqueue durable jobs in that transaction;
+it must never perform external I/O or commit it. Execution, auth and receipt
+ownership remain in OperationExecutor.
+"""
+from typing import Protocol
+from msg.core.contracts import MetadataSession
+from msg.core.models import Event, ExecutionContext, JsonMap, OperationRequest, ResourceRef
+
+
+class ResultProjection(Protocol):
+    async def __call__(self, context: ExecutionContext, request: OperationRequest,
+                       session: MetadataSession, resource: ResourceRef,
+                       *, fields: tuple[str, ...]) -> JsonMap: ...
+
+
+class TransactionalEventNotifications(Protocol):
+    async def __call__(self, session: MetadataSession, event: Event) -> None: ...