msgctl 0.1.0a1__py3-none-any.whl

msg/client_secrets.py

@@ -0,0 +1,58 @@
+"""Local encryption helpers. Neither plaintext nor private keys reach a transport."""
+from __future__ import annotations
+import os
+from pathlib import Path
+import tempfile
+from msg.core.codec import b64,unb64,wire
+from msg.core.errors import require
+from msg.core.models import ResourceRef
+from msg.security.sealed_box import generate_key,encrypt,decrypt,FORMAT
+
+
+def write_private(path,content):
+    path=Path(path)
+    path.parent.mkdir(parents=True,exist_ok=True)
+    fd=os.open(path,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600)
+    try:
+        with os.fdopen(fd,'wb') as output:
+            output.write(content);output.flush();os.fsync(output.fileno())
+    except BaseException:
+        path.unlink(missing_ok=True)
+        raise
+
+
+def encryption_keygen(path):
+    private,public=generate_key()
+    write_private(path,private)
+    return {'format':FORMAT,'recipient':b64(public),'private_key_file':str(path)}
+
+
+async def put_secret(client,name,path,recipient):
+    # The msg envelope is bounded. Already encrypted large age/OpenPGP files can
+    # instead use transfer + keystore.put(source=...), without loading them here.
+    with Path(path).open('rb') as source:
+        plaintext=source.read(524289)
+    require(len(plaintext)<=524288,'use_streaming_age_or_openpgp')
+    sealed=encrypt(plaintext,unb64(recipient,limit=32))
+    with tempfile.TemporaryDirectory(prefix='encrypted-',dir=client.state.directory) as temp:
+        ciphertext=Path(temp)/'ciphertext';write_private(ciphertext,sealed)
+        uploaded=client.checked(await client.upload(ciphertext,media_type='application/octet-stream'))
+        return await client.call('keystore.put',{'name':name,'format':FORMAT,'source':wire(uploaded.output)})
+
+
+async def get_secret(client,resource,output,private_key):
+    path=Path(private_key)
+    require(path.is_file() and not path.is_symlink() and path.stat().st_uid==os.geteuid() and
+            path.stat().st_mode&0o077==0,'unsafe_encryption_key_permissions')
+    private=path.read_bytes()
+    require(len(private)==32,'invalid_encryption_key')
+    entry=client.checked(await client.call('keystore.get',{'id':resource}))
+    require(entry.data['format']==FORMAT,'external_decryptor_required')
+    require(entry.data['size']<=1048576,'ciphertext_envelope_too_large')
+    require(not Path(output).exists(),'download_target_exists')
+    with tempfile.TemporaryDirectory(prefix='encrypted-',dir=client.state.directory) as temp:
+        ciphertext=Path(temp)/'ciphertext'
+        await client.download(entry.output,ciphertext)
+        plaintext=decrypt(ciphertext.read_bytes(),private)
+        write_private(output,plaintext)
+    return {'id':entry.data['id'],'revision':entry.data['revision'],'path':str(output),'decrypted_locally':True}

msg/client_tokens.py

@@ -0,0 +1,99 @@
+"""Protected one-use credential journals; no network authority comes from an ID."""
+from functools import wraps
+import os
+import stat
+
+from msg.client_upgrade import locked_state
+from msg.core.codec import b64, loads, unb64
+from msg.core.errors import Failure, require
+
+JOURNAL_OPERATIONS = {
+    'temporary.json': ('identity.temporary', 3),
+    'custodial-bootstrap.json': ('identity.custodial_create', 2),
+    'token-rotation.json': ('identity.token_rotate', 2),
+}
+
+
+def remove_journal(path):
+    """The local credential must already be durable before removing its intent."""
+    path.unlink()
+    fd = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def token_operation(method):
+    """Serialize with identity upgrades too, without blocking the event loop."""
+    @wraps(method)
+    async def locked(self, *args, **kwargs):
+        self._require_token_secret_transport()
+        with locked_state(self.state):
+            require(not any((self.state.directory/name).exists() or
+                            (self.state.directory/name).is_symlink() for name in
+                            ('identity-upgrade.json', 'custodial-upgrade.json')),
+                    'identity_recovery_pending')
+            self._token_journal()
+            return await method(self, *args, **kwargs)
+    return locked
+
+
+def read_journal(state):
+    paths = [state.directory/name for name in JOURNAL_OPERATIONS]
+    present = [p for p in paths if p.exists() or p.is_symlink()]
+    require(len(present) <= 1, 'multiple_token_journals')
+    if not present:
+        return None, None
+    path = present[0]
+    try:
+        fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    except OSError:
+        raise Failure('unsafe_token_journal') from None
+    try:
+        info = os.fstat(fd)
+        require(stat.S_ISREG(info.st_mode) and info.st_uid == os.geteuid() and
+                info.st_nlink == 1 and info.st_mode & 0o077 == 0, 'unsafe_token_journal')
+        with os.fdopen(fd, 'rb', closefd=False) as stream:
+            raw = stream.read(8193)
+    finally:
+        os.close(fd)
+    require(len(raw) <= 8192, 'invalid_token_journal')
+    try:
+        saved = loads(raw)
+        require(isinstance(saved, dict), 'invalid_token_journal')
+        operation, version = JOURNAL_OPERATIONS[path.name]
+        require(saved.get('operation') == operation and saved.get('contract_version') == version,
+                'legacy_token_journal_requires_manual_resolution')
+        # Older journals stay recoverable using their pre-bound secret, but cannot
+        # silently generate replacement keys. Newly written intentions also bind
+        # the origin and local key pair, including before any network call.
+        if 'server' in saved:
+            require(saved['server'] == state.server, 'token_journal_server_mismatch')
+        for field in ('nonce', 'recovery_secret'):
+            require(len(unb64(saved[field], limit=64)) >= 32, 'invalid_token_journal')
+        for field in ('credential_id', 'subject_id', 'request_id'):
+            require(isinstance(saved[field], str) and 0 < len(saved[field]) <= 160,
+                    'invalid_token_journal')
+        recovery = saved.get('recovery')
+        if recovery is not None:
+            require(isinstance(recovery, dict), 'invalid_token_journal')
+            for field in ('nonce', 'new_recovery_secret'):
+                require(len(unb64(recovery[field], limit=64)) >= 32, 'invalid_token_journal')
+            for field in ('request_id', 'credential_id'):
+                require(isinstance(recovery[field], str) and 0 < len(recovery[field]) <= 160,
+                        'invalid_token_journal')
+        require(state.subject is None or saved['subject_id'] == state.subject,
+                'token_journal_subject_mismatch')
+        if operation == 'identity.temporary':
+            require(state.signer is not None and state.encryption_recipient is not None,
+                    'token_journal_key_missing')
+            if 'public_key' in saved:
+                require(saved['public_key'] == b64(state.signer.public_key) and
+                        saved.get('encryption_recipient') == state.encryption_recipient,
+                        'token_journal_key_mismatch')
+    except Failure:
+        raise
+    except (KeyError, ValueError, TypeError):
+        raise Failure('invalid_token_journal') from None
+    return path, saved

msg/client_upgrade.py

@@ -0,0 +1,188 @@
+"""Durable same-subject upgrade intent; status recovery never reuses old authority."""
+from contextlib import contextmanager
+import os
+import re
+import stat
+from uuid import uuid4
+
+from msg.core.codec import b64, canonical, loads, wire
+from msg.core.errors import Failure, require
+from msg.security.crypto import Ed25519Signer
+from msg.storage.git import durable_write
+
+
+@contextmanager
+def upgrade_lock(directory):
+    """A crash releases the OS lock; a second caller fails instead of blocking an event loop."""
+    try:
+        import fcntl
+    except ImportError:
+        raise Failure('upgrade_lock_unavailable') from None
+    try:
+        fd = os.open(directory/'identity-upgrade.lock', os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+    except OSError:
+        raise Failure('unsafe_upgrade_lock') from None
+    try:
+        info = os.fstat(fd)
+        require(stat.S_ISREG(info.st_mode) and info.st_uid == os.geteuid() and
+                info.st_nlink == 1 and info.st_mode & 0o077 == 0, 'unsafe_upgrade_lock')
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            raise Failure('identity_upgrade_busy', retryable=True) from None
+        yield
+    finally:
+        os.close(fd)
+
+
+
+@contextmanager
+def locked_state(state):
+    """Refresh accepted credentials under the same lock used by every transition."""
+    with upgrade_lock(state.directory):
+        fresh = type(state)(state.directory, server=state.server)
+        state.__dict__.update(fresh.__dict__)
+        yield
+
+def read_intent(path):
+    try:
+        fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    except OSError:
+        raise Failure('unsafe_upgrade_journal') from None
+    try:
+        info = os.fstat(fd)
+        require(stat.S_ISREG(info.st_mode) and info.st_uid == os.geteuid() and
+                info.st_nlink == 1 and info.st_mode & 0o077 == 0, 'unsafe_upgrade_journal')
+        with os.fdopen(fd, 'rb', closefd=False) as stream:
+            raw = stream.read(8193)
+    finally:
+        os.close(fd)
+    require(len(raw) <= 8192, 'invalid_upgrade_journal')
+    try:
+        value = loads(raw)
+        require(isinstance(value, dict) and set(value) == {
+            'version', 'server', 'subject_id', 'handle', 'public_key',
+            'encryption_recipient', 'credential_id', 'request_id'}, 'invalid_upgrade_journal')
+        require(value['version'] == 1 and all(isinstance(value[name], str) and value[name]
+            for name in value if name != 'version'), 'invalid_upgrade_journal')
+        require(re.fullmatch('[0-9a-f]{32}', value['request_id']) is not None,
+                'invalid_upgrade_journal')
+    except (ValueError, TypeError, KeyError):
+        raise Failure('invalid_upgrade_journal') from None
+    return value
+
+
+def confirm_local_identity(state, pending, result, journal):
+    require(result.status == 'ok' and result.subject == pending['subject_id'] and
+            result.data.get('subject_id') == pending['subject_id'] and
+            result.data.get('key_id') == state.signer.key_id and
+            result.data.get('handle') == pending['handle'] and
+            result.data.get('encryption_recipient') == pending['encryption_recipient'] and
+            isinstance(result.data.get('certificate_id'), str) and bool(result.data['certificate_id']),
+            'upgrade_result_mismatch')
+    if result.operation == 'identity.upgrade_result':
+        require(result.data.get('status') == 'completed' and
+                result.data.get('upgrade_request_id') == pending['request_id'],
+                'upgrade_result_mismatch')
+    else:
+        require(result.operation == 'identity.upgrade' and result.request_id == pending['request_id'],
+                'upgrade_result_mismatch')
+    # Do not remove the recovery journal until the local identity is durable.
+    # A crash after this write but before unlink is recovered with the new key.
+    state.accept_identity(result)
+    journal.unlink()
+    fd = os.open(state.directory, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+    return result
+
+
+def pending_upgrade(state):
+    path = state.directory/'identity-upgrade.json'
+    if not (path.exists() or path.is_symlink()):
+        return None
+    pending = read_intent(path)
+    require(pending['server'] == state.server and pending['subject_id'] == state.subject and
+            re.fullmatch(r'[a-z][a-z0-9-]{1,40}', pending['handle']), 'upgrade_journal_mismatch')
+    return {'status': 'pending', 'handle': pending['handle'], 'request_id': pending['request_id'],
+            'resume': 'msg identity upgrade'}
+
+
+async def upgrade_identity(client, handle=None):
+    state = client.state
+    client._require_token_secret_transport()
+    with locked_state(state):
+        journal = state.directory/'identity-upgrade.json'
+        resuming = journal.exists() or journal.is_symlink()
+        pending = read_intent(journal) if resuming else None
+        if handle is None:
+            require(pending is not None, 'upgrade_handle_required')
+            handle = pending['handle']
+        require(isinstance(handle, str) and re.fullmatch(r'[a-z][a-z0-9-]{1,40}', handle)
+                and handle not in {'root', 'online-ca'}, 'invalid_handle')
+        if resuming:
+            require(state.signer is not None and state.encryption_recipient is not None,
+                    'upgrade_journal_key_missing')
+            require((pending['server'], pending['subject_id'], pending['handle'],
+                     pending['public_key'], pending['encryption_recipient']) ==
+                    (state.server, state.subject, handle, b64(state.signer.public_key),
+                     state.encryption_recipient), 'upgrade_journal_mismatch')
+            require(state.token is None or state.token[0] == pending['credential_id'],
+                    'upgrade_journal_mismatch')
+        else:
+            require(state.subject is not None and state.token is not None, 'temporary_identity_required')
+            require(not any((state.directory/name).exists() or (state.directory/name).is_symlink() for name in (
+                'temporary.json', 'custodial-bootstrap.json', 'token-rotation.json',
+                'custodial-upgrade.json')), 'identity_recovery_pending')
+            if state.signer is None:
+                state.save_signer(Ed25519Signer.generate())
+            recipient = state.ensure_encryption_key()
+            pending = {'version': 1, 'server': state.server, 'subject_id': state.subject,
+                'handle': handle, 'public_key': b64(state.signer.public_key),
+                'encryption_recipient': recipient, 'credential_id': state.token[0],
+                'request_id': uuid4().hex}
+            # Only a credential ID is stored here, never the old token or a private key.
+            durable_write(journal, canonical(pending), mode=0o600)
+
+        async def recover():
+            return await client.call('identity.upgrade_result',
+                {'upgrade_request_id': pending['request_id']}, signer=state.signer,
+                subject=pending['subject_id'], certificates=())
+
+        if resuming:
+            recovered = await recover()
+            if recovered.status == 'ok':
+                return confirm_local_identity(state, pending, recovered, journal)
+            # A not-yet-bound new key can occur after a pre-send crash. Only the
+            # still-valid original credential may submit the fixed intention.
+            if state.token is None or recovered.error.code not in {
+                    'credential_not_found', 'not_found', 'invalid_signature',
+                    'credential_ceiling', 'self_custody_signature_required',
+                    'upgrade_not_completed'}:
+                return recovered
+
+        require(state.token is not None, 'temporary_identity_required')
+        signed = {name: pending[name] for name in ('subject_id', 'handle', 'public_key',
+                                                   'encryption_recipient')}
+        arguments = {name: pending[name] for name in ('handle', 'public_key', 'encryption_recipient')}
+        arguments['possession_proof'] = wire(state.signer.sign(canonical(signed), purpose='upgrade'))
+        try:
+            result = await client.call('identity.upgrade', arguments,
+                                       request_id=pending['request_id'], contract_version=2)
+        except Failure as exc:
+            if exc.code != 'transport_uncertain':
+                raise
+            recovered = await recover()
+            if recovered.status != 'ok':
+                raise exc
+            result = recovered
+        if result.status == 'error' and result.error.code in {
+                'credential_revoked', 'credential_expired', 'not_temporary'}:
+            recovered = await recover()
+            if recovered.status == 'ok':
+                result = recovered
+        if result.status == 'ok':
+            return confirm_local_identity(state, pending, result, journal)
+        return result

msg/config.py

@@ -0,0 +1,318 @@
+"""Server configuration and client configuration have separate roots."""
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from msg.core.errors import require
+from msg.core.models import MailConfig, ServerConfig, TransportLimits
+from msg.security.age_keys import public_from_recipient,encryption_key_id
+
+
+@dataclass(frozen=True,slots=True)
+class RecoveryCustodian:
+    id: str
+    name: str
+    recipient: str
+    fingerprint: str
+    description: str | None = None
+    policy_ref: str | None = None
+
+
+@dataclass(frozen=True,slots=True)
+class MoneyConfig:
+    enabled: bool = True
+    currency_id: str = 'primary'
+    display_name: str = 'MSG'
+    code: str = 'MSG'
+    scale: int = 6
+    transfer_fee: int = 0
+    allow_overdraft: bool = False
+
+
+def root_private_dir(config_dir: Path) -> Path:
+    """Root material is outside the network service configuration tree."""
+    directory = Path(config_dir)
+    if directory == Path('/etc/msgd'):
+        return Path('/var/lib/msgd-root')
+    return directory.parent / (directory.name + '-root')
+
+
+def server_config_file(config_dir: Path) -> Path:
+    """Prefer the current name, but keep an existing legacy install readable."""
+    directory = Path(config_dir)
+    current, legacy = directory/'msgd.toml', directory/'server.toml'
+    require(not (current.exists() and legacy.exists()), 'ambiguous_server_configuration')
+    return legacy if legacy.exists() else current
+
+
+@dataclass(frozen=True,slots=True)
+class Settings:
+    server: ServerConfig
+    service_url: str
+    listen: str='127.0.0.1'
+    port: int=8042
+    public_web_origin: str | None=None
+    temporary_ttl: int=3600
+    credential_delivery_recovery_window: int=900
+    transfer_ttl: int=86400
+    base_certificate_ttl: int=2592000
+    max_part_bytes: int=65536
+    worker_isolation: str='bubblewrap'
+    tool_timeout_ms: int=10000
+    tool_max_response_bytes: int=4194304
+    tool_methods: tuple[str,...]=('GET','HEAD')
+    tool_ports: tuple[int,...]=(80,443)
+    recovery_custodians: tuple[RecoveryCustodian,...]=()
+    money: MoneyConfig=MoneyConfig()
+    hosting_base_capacity_bytes: int=10*1024*1024
+    hosting_recovery_marker: Path | None=None
+    hosting_content_group_read: bool=False
+
+    @property
+    def config_dir(self):
+        return self.server.config_dir
+
+    @property
+    def trust_file(self):
+        return self.config_dir/'trust'/'root.json'
+
+    @property
+    def service_keys(self):
+        return self.server.service_keys_dir
+
+    @property
+    def root_private_dir(self):
+        return root_private_dir(self.config_dir)
+
+    @property
+    def repositories_dir(self):
+        return self.server.repositories_dir
+
+
+def load_settings(config_dir=Path('/etc/msgd')):
+    config_dir=Path(config_dir)
+    path=server_config_file(config_dir)
+    require(path.is_file(),'configuration_missing')
+    data=tomllib.loads(path.read_text())
+    require(set(data)<={'server','storage','limits','plugins','tools','recovery','identity','money','hosting'},'unknown_configuration_section')
+    identity=data.get('identity',{})
+    require(isinstance(identity,dict) and set(identity)<={'credential_delivery_recovery_window'},
+            'unknown_identity_configuration')
+    window=identity.get('credential_delivery_recovery_window','15m')
+    require(isinstance(window,str) and len(window)<=3 and
+            re.fullmatch(r'[1-9][0-9]*m',window) is not None,
+            'invalid_credential_delivery_recovery_window')
+    window_minutes=int(window[:-1])
+    require(1<=window_minutes<=60,'invalid_credential_delivery_recovery_window')
+    hosting=data.get('hosting',{})
+    require(isinstance(hosting,dict) and set(hosting)<={'base_capacity_bytes','recovery_marker','content_group_read'},
+            'unknown_hosting_configuration')
+    hosting_base=hosting.get('base_capacity_bytes',10*1024*1024)
+    require(type(hosting_base) is int and 0 < hosting_base <= 1024**4,
+            'invalid_hosting_capacity')
+    content_group_read=hosting.get('content_group_read',False)
+    require(type(content_group_read) is bool,'invalid_content_group_read')
+    recovery_marker=hosting.get('recovery_marker')
+    require(recovery_marker is None or (isinstance(recovery_marker,str) and
+            Path(recovery_marker).is_absolute() and '..' not in Path(recovery_marker).parts and
+            not any(ord(c)<32 for c in recovery_marker)), 'invalid_hosting_recovery_marker')
+    money=data.get('money',{})
+    require(isinstance(money,dict) and set(money)<=set(MoneyConfig.__dataclass_fields__),
+            'unknown_money_configuration')
+    fixed={'enabled':True,'currency_id':'primary','scale':6,
+           'transfer_fee':0,'allow_overdraft':False}
+    for name,expected in fixed.items():
+        value=money.get(name,expected)
+        require(type(value) is type(expected) and value==expected,
+                'invalid_money_configuration')
+    display_name=money.get('display_name','MSG')
+    code=money.get('code','MSG')
+    require(type(display_name) is str and 1<=len(display_name)<=80 and
+            display_name==display_name.strip() and all(ord(char)>=32 for char in display_name),
+            'invalid_money_display_name')
+    require(type(code) is str and re.fullmatch(r'[A-Z][A-Z0-9]{1,15}',code) is not None,
+            'invalid_money_code')
+    server=data.get('server',{})
+    require(set(server)<={'service_url','listen','port','public_web_origin','temporary_ttl','transfer_ttl'},
+            'unknown_server_configuration')
+    service=server.get('service_url','https://msg.lmm.best')
+    require(isinstance(service,str),'invalid_service_url')
+    service=service.rstrip('/')
+    url=urlsplit(service)
+    require(url.scheme in {'https','http'} and url.hostname and not url.username and not url.password and not url.query and not url.fragment and not url.path,
+            'invalid_service_url')
+    require(type(server.get('port',8042)) is int and 1<=server.get('port',8042)<=65535,'invalid_listen_port')
+    require(isinstance(server.get('listen','127.0.0.1'),str) and server.get('listen','127.0.0.1'),'invalid_listen_address')
+    for key,default in (('temporary_ttl',3600),('transfer_ttl',86400)):
+        require(type(server.get(key,default)) is int and server.get(key,default)>0,'invalid_ttl')
+    store=data.get('storage',{})
+    require(set(store)<={'postgres_dsn','valkey_url','content','repositories','blobs','staging','service_keys'},
+            'unknown_storage_configuration')
+    postgres_dsn=store.get('postgres_dsn')
+    require(isinstance(postgres_dsn,str) and bool(postgres_dsn.strip()) and not any(ord(c)<32 for c in postgres_dsn),
+            'invalid_postgres_dsn')
+    # libpq service files keep credentials outside the service configuration.
+    if postgres_dsn.startswith(('postgresql://','postgres://')):
+        try:
+            pg_url=urlsplit(postgres_dsn)
+            require(bool(pg_url.hostname) and not pg_url.fragment,'invalid_postgres_dsn')
+        except ValueError:
+            require(False,'invalid_postgres_dsn')
+    else:
+        require(postgres_dsn.startswith('service=') and len(postgres_dsn.split())==1 and
+                len(postgres_dsn)>len('service='),'invalid_postgres_dsn')
+    valkey_url=store.get('valkey_url')
+    if valkey_url is not None:
+        require(isinstance(valkey_url,str),'invalid_valkey_url')
+        try:
+            cache_url=urlsplit(valkey_url)
+            require(cache_url.scheme in {'redis','rediss','unix'} and
+                    (bool(cache_url.hostname) if cache_url.scheme!='unix' else bool(cache_url.path)) and
+                    not cache_url.fragment,'invalid_valkey_url')
+        except ValueError:
+            require(False,'invalid_valkey_url')
+    content_dir=Path(store.get('content','/var/lib/msgd/git/content'))
+    # Existing installations with an explicit old content path keep their old
+    # sibling repository and embedded blob locations until an operator migrates.
+    modern_layout=content_dir.name=='content' and content_dir.parent.name=='git'
+    repository_default=(content_dir.parent/'repos' if modern_layout else
+                        content_dir.parent/'repositories')
+    blob_default=(content_dir.parent.parent/'blobs'/'sha256' if modern_layout else
+                  content_dir/'binary')
+    service_keys_default=(config_dir/'service' if (config_dir/'service').exists() and
+                          not modern_layout else
+                          (content_dir.parent.parent if modern_layout else content_dir.parent)/'service')
+    require(all(isinstance(store.get(key,str(default)),str) and
+                Path(store.get(key,str(default))).is_absolute()
+                for key,default in (('content',content_dir),('repositories',repository_default),
+                                    ('blobs',blob_default),('staging',Path('/var/lib/msgd/transfers/staging')),
+                                    ('service_keys',service_keys_default))),
+            'storage_paths_must_be_absolute')
+    limits=data.get('limits',{})
+    require(set(limits)<={'request_bytes','response_bytes','path_bytes','part_bytes'},'unknown_limit')
+    for value in limits.values():
+        require(type(value) is int and value>=256,'invalid_limit')
+    mail_file=config_dir/'mail.toml'
+    mail=None
+    if mail_file.exists():
+        raw=tomllib.loads(mail_file.read_text())
+        require(set(raw)<={'enabled','host','port','tls','sender','credential_file'},'unknown_mail_configuration')
+        if raw.get('enabled',False):
+            require(raw.get('tls') in {'starttls','tls'},'mail_tls_required')
+            mail=MailConfig(enabled=True,host=raw['host'],port=raw.get('port',587),tls=raw['tls'],sender=raw['sender'],
+                credential_file=Path(raw['credential_file']) if raw.get('credential_file') else None)
+    recovery=data.get('recovery',{})
+    require(isinstance(recovery,dict) and set(recovery)<={'custodians'},'unknown_recovery_configuration')
+    raw_custodians=recovery.get('custodians',[])
+    require(isinstance(raw_custodians,list) and len(raw_custodians)<=16,'invalid_recovery_custodians')
+    custodians=[]
+    for item in raw_custodians:
+        require(isinstance(item,dict) and set(item)<={'id','name','recipient','description','policy_ref'},
+                'unknown_recovery_custodian_field')
+        require(all(name in item for name in ('id','name','recipient')),
+                'invalid_recovery_custodian')
+        require(type(item['id']) is str and re.fullmatch(r'[a-z][a-z0-9-]{1,63}',item['id']) is not None and
+                type(item['name']) is str and 1<=len(item['name'])<=100,
+                'invalid_recovery_custodian')
+        require(all(value is None or (type(value) is str and len(value)<=500)
+                    for value in (item.get('description'),item.get('policy_ref'))),
+                'invalid_recovery_custodian')
+        public=public_from_recipient(item['recipient'])
+        custodians.append(RecoveryCustodian(id=item['id'],name=item['name'],
+            recipient=item['recipient'],fingerprint=encryption_key_id(public),
+            description=item.get('description'),policy_ref=item.get('policy_ref')))
+    require(len({item.id for item in custodians})==len(custodians),'duplicate_recovery_custodian')
+    require(set(data.get('plugins',{}))<={'enabled'},'unknown_plugin_configuration')
+    plugins=tuple(data.get('plugins',{}).get('enabled',('identity','content','discussion','communication','discovery','achievements','recovery','sharing','money','offers','store','bounty','orders','delivery','transfer','extensions','system','batch')))
+    require(all(isinstance(name,str) for name in plugins) and len(set(plugins))==len(plugins),'invalid_plugin_list')
+    require('identity' in plugins,'identity_plugin_required')
+    tools=data.get('tools',{})
+    require(set(tools)<={'isolation','timeout_ms','max_response_bytes','methods','ports'},'unknown_tool_configuration')
+    require(tools.get('isolation','bubblewrap')=='bubblewrap','unsafe_tool_worker')
+    for name,default in (('timeout_ms',10000),('max_response_bytes',4194304)):
+        require(type(tools.get(name,default)) is int and tools.get(name,default)>0,'invalid_tool_limit')
+    require(isinstance(tools.get('methods',[]),(list,tuple)) and all(m in {'GET','HEAD','POST','PUT','PATCH','DELETE','OPTIONS'} for m in tools.get('methods',[])),'invalid_tool_methods')
+    require(isinstance(tools.get('ports',[]),(list,tuple)) and all(type(p) is int and 1<=p<=65535 for p in tools.get('ports',[])),'invalid_tool_ports')
+    public_web=server.get('public_web_origin')
+    if public_web is not None:
+        require(isinstance(public_web,str),'invalid_hosting_origin')
+        hosted=urlsplit(public_web)
+        require(hosted.scheme in {'https','http'} and hosted.hostname and not hosted.username and not hosted.password and not hosted.path and not hosted.query and not hosted.fragment,'invalid_hosting_origin')
+    require(public_web is None or public_web.rstrip('/')==service.rstrip('/'),
+            'hosting_origin_must_match_service')
+    return Settings(server=ServerConfig(config_dir=config_dir,
+        postgres_dsn=postgres_dsn,valkey_url=valkey_url,
+        content_dir=content_dir,
+        repositories_dir=Path(store.get('repositories',repository_default)),
+        blob_dir=Path(store.get('blobs',blob_default)),
+        staging_dir=Path(store.get('staging','/var/lib/msgd/transfers/staging')),plugins=plugins,
+        service_keys_dir=Path(store.get('service_keys',service_keys_default)),
+        limits=TransportLimits(max_request_bytes=limits.get('request_bytes',1048576),
+            max_response_bytes=limits.get('response_bytes',1048576),max_path_bytes=limits.get('path_bytes',8192),
+            encodings=frozenset({'j','gz'})),mail=mail),service_url=service,listen=server.get('listen','127.0.0.1'),
+        port=server.get('port',8042),public_web_origin=public_web,
+        temporary_ttl=server.get('temporary_ttl',3600),transfer_ttl=server.get('transfer_ttl',86400),
+        credential_delivery_recovery_window=window_minutes*60,
+        max_part_bytes=limits.get('part_bytes',65536),tool_timeout_ms=tools.get('timeout_ms',10000),
+        tool_max_response_bytes=tools.get('max_response_bytes',4194304),
+        tool_methods=tuple(tools.get('methods',('GET','HEAD'))),tool_ports=tuple(tools.get('ports',(80,443))),
+        recovery_custodians=tuple(custodians),
+        money=MoneyConfig(display_name=display_name,code=code),
+        hosting_base_capacity_bytes=hosting_base,
+        hosting_recovery_marker=Path(recovery_marker) if recovery_marker is not None else None,
+        hosting_content_group_read=content_group_read)
+
+
+def write_example(config_dir,data_dir,service_url='https://msg.lmm.best',*,postgres_dsn='service=msgd',valkey_url=None):
+    """Local install helper: writes no private key or default PIN."""
+    config_dir,data_dir=Path(config_dir),Path(data_dir)
+    config_dir.mkdir(parents=True,exist_ok=True)
+    path=server_config_file(config_dir)
+    if not path.exists():
+        path.write_text(f'''[server]
+service_url = {json.dumps(service_url)}
+listen = "127.0.0.1"
+port = 8042
+
+[identity]
+credential_delivery_recovery_window = "15m"
+
+[money]
+enabled = true
+currency_id = "primary"
+display_name = "MSG"
+code = "MSG"
+scale = 6
+transfer_fee = 0
+allow_overdraft = false
+
+[hosting]
+base_capacity_bytes = 10485760
+content_group_read = false
+
+[storage]
+postgres_dsn = {json.dumps(postgres_dsn)}
+{f'valkey_url = {json.dumps(valkey_url)}' if valkey_url is not None else '# valkey_url = "redis://127.0.0.1:6379/0"'}
+content = {json.dumps(str(data_dir/"git"/"content"))}
+repositories = {json.dumps(str(data_dir/"git"/"repos"))}
+blobs = {json.dumps(str(data_dir/"blobs"/"sha256"))}
+staging = {json.dumps(str(data_dir/"transfers"/"staging"))}
+service_keys = {json.dumps(str(data_dir/"service"))}
+
+[limits]
+request_bytes = 1048576
+response_bytes = 1048576
+path_bytes = 8192
+part_bytes = 65536
+
+[tools]
+isolation = "bubblewrap"
+methods = ["GET", "HEAD"]
+ports = [80, 443]
+''')
+    return load_settings(config_dir)