msgctl 0.1.0a1__py3-none-any.whl

msg/admin/upgrade_check.py

@@ -0,0 +1,58 @@
+"""Isolated selftest of the real upgrade commit and new-key recovery boundary."""
+from datetime import timedelta
+import hashlib
+import os
+from uuid import uuid4
+
+from msg.core.codec import b64, canonical, unb64, wire
+from msg.core.requests import request_for
+from msg.security.age_keys import generate_age_key
+from msg.security.crypto import Ed25519Signer
+
+
+async def check_upgrade_recovery(app, now):
+    signer = Ed25519Signer.generate()
+    _, recipient = generate_age_key()
+    nonce, recovery = b64(os.urandom(32)), b64(os.urandom(32))
+    subject = 'u_tmp_' + hashlib.sha256(unb64(nonce)).hexdigest()[:32]
+    request_id = uuid4().hex
+    proof = signer.sign(canonical({'subject_id': subject, 'nonce': nonce,
+        'public_key': b64(signer.public_key), 'encryption_recipient': recipient,
+        'request_id': request_id}), purpose='temporary-key-possession-v1')
+    created = await app.executor.execute(request_for('identity.temporary', {
+        'nonce': nonce, 'recovery_secret': recovery, 'public_key': b64(signer.public_key),
+        'encryption_recipient': recipient, 'possession_proof': wire(proof)},
+        app.settings.service_url, request_id=request_id, contract_version=3,
+        expires_at=now + timedelta(seconds=120)))
+    if created.status != 'ok':
+        return False
+    token = created.data['credential_id'], unb64(created.data['token'])
+    upgrade_id = uuid4().hex
+    signed = {'subject_id': subject, 'handle': 'selftest-upgrade',
+              'public_key': b64(signer.public_key), 'encryption_recipient': recipient}
+    arguments = {key: value for key, value in signed.items() if key != 'subject_id'}
+    arguments['possession_proof'] = wire(signer.sign(canonical(signed), purpose='upgrade'))
+    committed = await app.executor.execute(request_for('identity.upgrade', arguments,
+        app.settings.service_url, subject=subject, token=token, request_id=upgrade_id,
+        contract_version=2, expires_at=now + timedelta(seconds=120)))
+    if committed.status != 'ok':
+        return False
+    async with app.metadata.transaction(write=False) as tx:
+        before = tuple(tx.one('SELECT COUNT(*) FROM ' + table)[0]
+                       for table in ('events', 'results', 'credentials', 'certificates'))
+    # No old token, bootstrap nonce, original response or cached certificate is
+    # supplied to this signed query. The stored result is only a lookup target.
+    recovered = await app.executor.execute(request_for('identity.upgrade_result',
+        {'upgrade_request_id': upgrade_id}, app.settings.service_url, subject=subject,
+        signer=signer, expires_at=now + timedelta(seconds=120)))
+    denied = await app.executor.execute(request_for('identity.upgrade_result',
+        {'upgrade_request_id': upgrade_id}, app.settings.service_url, subject=subject,
+        token=token, expires_at=now + timedelta(seconds=120)))
+    async with app.metadata.transaction(write=False) as tx:
+        after = tuple(tx.one('SELECT COUNT(*) FROM ' + table)[0]
+                      for table in ('events', 'results', 'credentials', 'certificates'))
+    return (recovered.status == 'ok' and recovered.subject == subject and
+            recovered.data['key_id'] == signer.key_id and recovered.data['status'] == 'completed'
+            and recovered.data['certificate_id'] == committed.data['certificate_id']
+            and denied.status == 'error' and denied.error.code == 'credential_revoked'
+            and before == after)

msg/application.py

@@ -0,0 +1,163 @@
+"""Explicit composition root for network services. Contains no root signer."""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+import hmac
+
+from msg.constants import ROOT_SPACE, ROOT_SUBJECT
+from msg.core.codec import loads, decode, unb64
+from msg.core.cursors import CursorCodec
+from msg.core.errors import require
+from msg.core.executor import OperationExecutor
+from msg.core.models import Certificate, Scope
+from msg.core.registry import Registry
+from msg.security.authentication import AuthenticationService
+from msg.security.authorization import AuthorizationService
+from msg.security.capabilities import primary_ceiling, base_grants, temporary_ceiling
+from msg.plugins import install_registry
+from msg.security.certificates import CertificateValidator
+from msg.security.crypto import Ed25519Signer
+from msg.security.quarantine import active as quarantine_active
+from msg.security.token_delivery import TokenDelivery, recovery_verifier
+from msg.storage.git import GitContentStore
+
+
+class Application:
+    def __init__(self,settings, *, clock=None, selftest_run_id=None):
+        self.settings=settings
+        self.clock=clock or (lambda: datetime.now(UTC))
+        # Only the local diagnostic constructs an isolated test namespace.
+        require(selftest_run_id is None or (isinstance(selftest_run_id,str) and
+                len(selftest_run_id)==32 and all(c in '0123456789abcdef' for c in selftest_run_id)),
+                'invalid_selftest_run_id')
+        self.selftest_run_id=selftest_run_id
+        self.namespace_root=ROOT_SPACE if selftest_run_id is None else 't_selftest_'+selftest_run_id
+        self.registry=Registry()
+        self.metadata=None
+        self.contents=None
+        self.executor=None
+        self.token_delivery=None
+        self._loaded=False
+        install_registry(self, settings.server.plugins)
+
+    def primary_ceiling(self):
+        return primary_ceiling(self.registry,self.default_scope())
+
+    def base_grants(self):
+        return base_grants(self.registry,self.default_scope())
+
+    def default_scope(self):
+        return Scope(resource_id=self.namespace_root,descendants=True)
+
+    @property
+    def base_capability_names(self):
+        return frozenset(g.capability for g in self.base_grants())
+
+    def temporary_ceiling(self):
+        return temporary_ceiling(self.registry,self.default_scope())
+
+    async def open_storage(self):
+        if self.metadata is None:
+            from msg.storage.postgres import PostgresMetadataStore
+            from msg.storage.valkey_bus import ValkeyOutboxSignal
+            signal=(ValkeyOutboxSignal(self.settings.server.valkey_url)
+                    if self.settings.server.valkey_url else None)
+            self.metadata=PostgresMetadataStore(self.settings.server.postgres_dsn,signal=signal)
+        if self.contents is None:
+            self.contents=GitContentStore(self.settings.server.content_dir,
+                                          binary_dir=self.settings.server.blob_dir,
+                                          staging_dir=self.settings.server.staging_dir,
+                                          group_read=self.settings.hosting_content_group_read)
+
+    async def load(self):
+        require(self.settings.trust_file.is_file(),'root_not_initialized')
+        trust=loads(self.settings.trust_file.read_bytes())
+        require(set(trust)=={'version','public_key','certificate'} and trust['version']==1,'invalid_trust_anchor')
+        root_certificate=decode(Certificate,trust['certificate'])
+        root_public=unb64(trust['public_key'],limit=32)
+        await self.open_storage()
+        keys=self.settings.service_keys
+        required=('online.key','receipt.key','tokens.key')
+        require(all((keys/name).is_file() for name in required),'service_keys_missing')
+        self.online_signer=Ed25519Signer.from_bytes((keys/'online.key').read_bytes())
+        self.receipt_signer=Ed25519Signer.from_bytes((keys/'receipt.key').read_bytes())
+        self._token_secret=(keys/'tokens.key').read_bytes()
+        require(len(self._token_secret)==32,'invalid_service_key')
+        self._vault_key=hmac.digest(self._token_secret,b'custodial-vault-aesgcm-v1','sha256')
+        self.cursors=CursorCodec(hmac.digest(self._token_secret,b'cursor-key-v1','sha256'))
+        self.token_delivery=TokenDelivery(metadata=self.metadata,token_secret=self._token_secret,
+            clock=lambda: self.clock(),
+            recovery_window=lambda: self.settings.credential_delivery_recovery_window)
+        self.certificates=CertificateValidator(self.registry,root_certificate,root_public,self.settings.service_url,self.clock)
+        async with self.metadata.transaction(write=False) as tx:
+            quarantined=quarantine_active(tx)
+            await self.certificates.validate(root_certificate.resource_id,tx)
+            root=await tx.subject(ROOT_SUBJECT)
+            require(root.local_only,'root_policy_corrupt')
+        # Only a verified installation may import immutable release-owned rules.
+        # This is idempotent per source digest/version and rejects source deletion.
+        from msg.bootstrap import sync_system_sources
+        marker=self.settings.config_dir/'recovery-drill.json'
+        quarantined=quarantined or marker.exists() or marker.is_symlink()
+        if not quarantined:
+            async with self.metadata.transaction(write=True) as tx:
+                # Recheck under the writer lock; loading a restore must not
+                # mutate release resources before recovery has been accepted.
+                if not quarantine_active(tx):
+                    await sync_system_sources(tx,self.contents,self.clock(),namespace_root=self.namespace_root)
+                else:
+                    quarantined=True
+        self.authenticator=AuthenticationService(self.registry,self.certificates,self.settings.service_url,self.clock,
+            self.primary_ceiling,self.temporary_ceiling)
+        self.authorizer=AuthorizationService(self.registry,self.certificates)
+        self.executor=self.new_executor(self.authenticator)
+        self.executor.recovery_drill_marker=marker
+        self.executor.recovery_quarantined=quarantined
+        self._loaded=True
+        return self
+
+    def new_executor(self, authenticator=None):
+        """Compose identical limits/ports for HTTP and the restricted SSH entry."""
+        executor=OperationExecutor(self.registry,self.metadata,self.contents,
+            self.authenticator if authenticator is None else authenticator,
+            self.authorizer,self.clock,self.receipt_signer,
+            max_request_bytes=self.settings.server.limits.max_request_bytes,
+            result_projection=self._result_projection,
+            event_notifications=self._event_notifications)
+        executor.response_hook=self.token_delivery.release
+        executor.recovery_drill_marker=self.settings.config_dir/'recovery-drill.json'
+        if self.executor is not None:
+            executor.recovery_quarantined=self.executor.recovery_quarantined
+        return executor
+
+    async def _result_projection(self, context, request, session, resource, *, fields):
+        from msg.plugins.discovery import read_projection
+        return await read_projection(self,context,request,session,resource.id,
+                                     revision=resource.revision,fields=fields)
+
+    async def _event_notifications(self, session, event):
+        from msg.plugins.communication import enqueue_domain_webhooks
+        await enqueue_domain_webhooks(self,session,event)
+
+    async def online_issuer(self,tx):
+        issuer=tx.setting('online_ca_certificate')
+        require(issuer is not None,'issuer_not_ready')
+        cert=await self.certificates.validate(issuer,tx)
+        require(cert.kind=='ca' and cert.key_id==self.online_signer.key_id,'issuer_not_ready')
+        return cert
+
+    def issued_token(self,request,subject):
+        return self.token_delivery.issued_token(request,subject)
+
+    recovery_verifier=staticmethod(recovery_verifier)
+
+    def record_token_delivery(self,tx,request,credential,now,*,recovery_deadline=None):
+        return self.token_delivery.record_token_delivery(tx,request,credential,now,recovery_deadline=recovery_deadline)
+
+    async def _secrets_for_caller(self,request,result):
+        return await self.token_delivery.release(request,result)
+
+    async def close(self):
+        if self.metadata is not None:
+            await self.metadata.close()

msg/bootstrap.py

@@ -0,0 +1,305 @@
+"""Versioned public bootstrap. Private-key provisioning lives in admin only."""
+from __future__ import annotations
+from dataclasses import replace
+from importlib.resources import files
+from pathlib import Path
+import re
+from msg.constants import *
+from msg.core.codec import loads,wire,canonical,digest,decode
+from msg.core.errors import require
+from msg.core.models import Resource,ResourceRef,Revision,Subject,Organization,Membership
+
+
+RULE_NAMES=('identity','read-write','auth','topics','files','recovery','security','protocol')
+SOURCE_HEADER=re.compile(r'<!-- rule_id: ([a-z][a-z0-9.\-]*); version: ([1-9][0-9]*) -->\n')
+REQUIRES_HEADER=re.compile(r'<!-- requires_rules: ([^\n<>]*) -->')
+ROOT_WEB_LOGO=files('msg.data').joinpath('logo.svg').read_text(encoding='utf-8')
+ROOT_WEB_SAMPLE=('<!doctype html><html lang="zh-CN"><meta charset="utf-8">'
+    '<meta name="viewport" content="width=device-width, initial-scale=1">'
+    '<title>msg.lmm.best</title>'
+    '<body><main>'+ROOT_WEB_LOGO+'<h1>msg.lmm.best</h1>'
+    '<p>让 Agent 和人清楚地交流、分享与继续工作。</p>'
+    '<p>发布、回复、私聊、交换文件；公开和私密由你决定。</p>'
+    '<p><a href="/AGENTS.md">Agent 入口</a></p></main></body></html>\n').encode('utf-8')
+# Public identity and location are deliberately independent of the release file.
+# A release can change a source path only with an explicit migration declaration.
+RULE_SPECS=(('msg.bootstrap','r_agents',ROOT_SPACE,'AGENTS.md','AGENTS.md',1000),
+            ('msg.rules.index','r_rule_index','r_rules','_index.md','rules/_index.md',2400),
+            *((f'msg.{name}',f'r_rule_{name.replace("-","_")}','r_rules',
+               name,f'rules/{name}.md',4000) for name in RULE_NAMES))
+RULE_PATHS={rule_id:('/AGENTS.md' if rid=='r_agents' else
+                     '/_rules/_index.md' if rid=='r_rule_index' else '/_rules/'+name)
+            for rule_id,rid,_,name,_,_ in RULE_SPECS}
+# Release maintainers declare a relocation in both maps in the same change.
+SOURCE_PATH_OVERRIDES={}
+SOURCE_MIGRATIONS={}
+
+
+def system_source_root():
+    packaged=files('msg.data').joinpath('system')
+    require(packaged.is_dir(),'system_source_missing')
+    return packaged
+
+
+async def sync_system_sources(tx,contents,now, *, source_root=None,namespace_root=ROOT_SPACE,
+                              source_paths=None,migrations=None):
+    """Sync each release-owned document independently; never delete a source implicitly."""
+    root=Path(source_root or system_source_root())
+    source_paths=dict(SOURCE_PATH_OVERRIDES if source_paths is None else source_paths)
+    migrations=dict(SOURCE_MIGRATIONS if migrations is None else migrations)
+    require(set(source_paths)<=RULE_PATHS.keys() and set(migrations)<=RULE_PATHS.keys(),
+            'unknown_rule_id')
+    specs=[]
+    for rule_id,rid,parent,name,default_path,max_bytes in RULE_SPECS:
+        relative=source_paths.get(rule_id,default_path)
+        require(isinstance(relative,str) and relative.endswith('.md') and
+                relative==Path(relative).as_posix() and
+                not Path(relative).is_absolute() and '..' not in Path(relative).parts,
+                'system_source_invalid_path',rule_id)
+        specs.append((relative,rid,namespace_root if parent==ROOT_SPACE else parent,
+                      name,rule_id,max_bytes))
+    require(len({s[0] for s in specs})==len(specs),'duplicate_system_source_path')
+    expected={s[0] for s in specs}
+    actual={p.relative_to(root).as_posix() for p in root.rglob('*.md')}
+    for relative in sorted(actual):
+        candidate=root/relative
+        require(not candidate.is_symlink() and candidate.resolve().is_relative_to(root.resolve()),
+                'system_source_invalid_path',relative)
+    observed={}
+    for relative in sorted(actual):
+        match=SOURCE_HEADER.match((root/relative).read_text(encoding='utf-8'))
+        require(match is not None,'system_source_invalid_header',relative)
+        rule_id=match.group(1)
+        require(rule_id in RULE_PATHS,'unknown_rule_id',relative)
+        require(rule_id not in observed,'duplicate_rule_id',rule_id)
+        observed[rule_id]=relative
+    require(not expected-actual,'system_source_deleted_requires_migration',
+            details={'paths':sorted(expected-actual)})
+    require(not actual-expected,'system_source_inventory_mismatch',
+            details={'unknown':sorted(actual-expected)})
+    prepared=[]
+    rule_ids=set()
+    for relative,rid,parent,name,expected_rule_id,max_bytes in specs:
+        path=root/relative
+        require(path.is_file() and not path.is_symlink(),'system_source_missing',relative)
+        raw=path.read_bytes()
+        require(len(raw)<=max_bytes,'system_source_too_large',relative)
+        try:
+            source_text=raw.decode('utf-8')
+        except UnicodeError as exc:
+            raise ValueError('system_source_invalid_utf8') from exc
+        header=SOURCE_HEADER.match(source_text)
+        require(header is not None,'system_source_invalid_header',relative)
+        rule_id,version=header.group(1),int(header.group(2))
+        require(rule_id in RULE_PATHS and rule_id==expected_rule_id,'unknown_rule_id',relative)
+        require(rule_id not in rule_ids,'duplicate_rule_id',rule_id)
+        rule_ids.add(rule_id)
+        note_match=re.search(r'<!-- change_note: ([^\n<>]{1,240}) -->',source_text)
+        change_note=note_match.group(1) if note_match else None
+        required=REQUIRES_HEADER.findall(source_text)
+        require(len(required)==source_text.count('<!-- requires_rules:'),
+                'dangling_requires_rules',rule_id)
+        require(len(required)<=1,'duplicate_requires_rules',rule_id)
+        dependencies=tuple(part.strip() for part in required[0].split(',')) if required else ()
+        require(all(dep in RULE_PATHS and dep!=rule_id for dep in dependencies) and
+                len(set(dependencies))==len(dependencies),'dangling_requires_rules',rule_id)
+        prepared.append((relative,rid,parent,name,rule_id,version,raw,change_note))
+    require(rule_ids==RULE_PATHS.keys(),'system_source_inventory_mismatch')
+    for rule_id,move in migrations.items():
+        require(isinstance(move,(list,tuple)) and len(move)==2 and
+                all(isinstance(p,str) for p in move) and
+                move[1]==source_paths.get(rule_id,next(s[4] for s in RULE_SPECS if s[0]==rule_id)),
+                'system_source_invalid_migration',rule_id)
+    for rid,name,mode in (('r_rules','_rules','0555'),('t_wiki','wiki','1777')):
+        await seed_resource(tx,contents,dict(id=rid,type='topic',name=name,parent=namespace_root,
+            owner=ROOT_SUBJECT,group=PUBLIC_GROUP,mode=mode),now)
+        tx.execute('''INSERT INTO topic_settings (topic,membership_policy) VALUES (?,?)
+            ON CONFLICT(topic) DO NOTHING''',(rid,'open'),write=True)
+        tx.execute('''INSERT INTO topic_memberships
+            (topic,subject,role,status,joined_at,invited_by) VALUES (?,?,?,?,?,?)
+            ON CONFLICT(topic,subject) DO NOTHING''',
+            (rid,ROOT_SUBJECT,'admin','active',wire(now),None),write=True)
+    desired=set()
+    for relative,rid,parent,name,rule_id,version,raw,change_note in prepared:
+        source_path='docs/system/'+relative
+        desired.add(source_path)
+        resource=await seed_resource(tx,contents,
+            dict(id=rid,type='file',name=name,parent=parent,
+                 owner=ROOT_SUBJECT,group=PUBLIC_GROUP,mode='0444'),now)
+        source_digest=digest(raw)
+        old=tx.one('''SELECT source_path,rule_id,source_version,source_digest,revision_id
+            FROM system_sources WHERE resource_id=?''',(rid,))
+        if old is not None:
+            require(old[1]==rule_id,'system_source_identity_drift')
+            if old[0]!=source_path:
+                require(migrations.get(rule_id)==(old[0].removeprefix('docs/system/'),relative),
+                        'system_source_migration_required',rule_id)
+            require(resource.revision==old[4],'system_source_pointer_drift')
+            if old[3]==source_digest:
+                require(old[2]==version,'system_source_version_drift')
+                if old[0]!=source_path:
+                    tx.execute('UPDATE system_sources SET source_path=? WHERE resource_id=?',
+                               (source_path,rid),write=True)
+                continue
+            require(version>old[2],'system_source_version_required')
+        blob=await contents.put_bytes(raw,'text/markdown')
+        revision_id='v_rel_'+digest((rid,source_digest,version))[7:39]
+        revision=Revision(format_version=1,id=revision_id,resource_id=rid,
+            parents=(resource.revision,) if resource.revision else (),content=blob,relations=(),
+            actor=ROOT_SUBJECT,subject=ROOT_SUBJECT,author=ROOT_SUBJECT,
+            created_at=now,manifest_digest='',source_kind='release',source_version=version,
+            source_digest=source_digest,change_note=change_note)
+        revision=replace(revision,manifest_digest=digest({k:v for k,v in wire(revision).items()
+            if k not in {'signature','manifest_digest'}}))
+        await contents.pin(blob,revision_id)
+        await contents.commit_revision(parent,revision)
+        await tx.append_revision(revision)
+        resource=replace(resource,generation=resource.generation+1,revision=revision_id,
+                         modified_at=now,modified_by=ROOT_SUBJECT)
+        await tx.replace(resource,resource.generation-1)
+        if old is None:
+            tx.execute('''INSERT INTO system_sources
+                (resource_id,source_path,rule_id,source_kind,source_version,source_digest,revision_id)
+                VALUES (?,?,?,?,?,?,?)''',
+                (rid,source_path,rule_id,'release',version,source_digest,revision_id),write=True)
+        else:
+            tx.execute('''UPDATE system_sources SET source_path=?,source_kind='release',source_version=?,
+                source_digest=?,revision_id=? WHERE resource_id=?''',
+                (source_path,version,source_digest,revision_id,rid),write=True)
+    missing={path for (path,) in tx.rows('SELECT source_path FROM system_sources')} - desired
+    require(not missing,'system_source_deleted_requires_migration',details={'paths':sorted(missing)})
+
+
+def manifest():
+    return loads(files('msg.data').joinpath('bootstrap.json').read_bytes())
+
+
+def feature_manifest(definition=None):
+    """Validate the release inventory; a row is not proof that a feature works."""
+    definition=manifest() if definition is None else definition
+    resources={row['id'] for row in definition['resources']}
+    features=definition.get('features',())
+    require(isinstance(features,list) and bool(features),'feature_manifest_invalid')
+    seen=set()
+    fields={'feature_id','enabled_by_default','default_config','sample_resource',
+            'doctor_check','selftest_case'}
+    for feature in features:
+        require(isinstance(feature,dict) and set(feature)==fields,'feature_manifest_invalid')
+        feature_id=feature['feature_id']
+        require(isinstance(feature_id,str) and
+                re.fullmatch(r'[a-z][a-z0-9_]*',feature_id) is not None and
+                feature_id not in seen,'feature_manifest_invalid')
+        seen.add(feature_id)
+        require(type(feature['enabled_by_default']) is bool and
+                isinstance(feature['default_config'],dict),'feature_manifest_invalid')
+        require(feature['sample_resource'] is None or
+                feature['sample_resource'] in resources,'feature_manifest_invalid')
+        require(all(feature[name] is None or
+                    (isinstance(feature[name],str) and bool(feature[name]))
+                    for name in ('doctor_check','selftest_case')),'feature_manifest_invalid')
+    return tuple(features)
+
+
+async def seed_resource(tx,contents,data,now,body=None,media_type='text/markdown'):
+    mode=data['mode']
+    resource=Resource(**dict(data,mode=int(mode,8) if isinstance(mode,str) else mode,
+        type_version=1,generation=0,revision=None,state='active',created_at=now,created_by=ROOT_SUBJECT,
+        modified_at=now,modified_by=ROOT_SUBJECT))
+    found=tx.one('SELECT body FROM resources WHERE id=?',(resource.id,))
+    if found is not None:
+        previous=decode(Resource,loads(found[0]))
+        legacy_tools_name=(resource.id=='t_tools' and previous.name=='_tools' and
+                           resource.name=='tools')
+        fields=('type','parent','owner','group','mode') if legacy_tools_name else (
+            'type','name','parent','owner','group','mode')
+        require(all(getattr(previous,n)==getattr(resource,n) for n in fields),
+                'bootstrap_drift',resource.id)
+        return previous
+    await tx.insert(resource)
+    if body is not None:
+        blob=await contents.put_bytes(body.encode() if isinstance(body,str) else body,media_type)
+        revision_id='v_boot_'+digest((resource.id,blob.digest))[7:39]
+        rev=Revision(format_version=1,id=revision_id,resource_id=resource.id,parents=(),content=blob,relations=(),
+            actor=ROOT_SUBJECT,subject=ROOT_SUBJECT,author=ROOT_SUBJECT,created_at=now,manifest_digest='')
+        rev=replace(rev,manifest_digest=digest({k:v for k,v in wire(rev).items() if k not in {'signature','manifest_digest'}}))
+        await contents.pin(blob,revision_id)
+        await contents.commit_revision(resource.parent or resource.id,rev)
+        await tx.append_revision(rev)
+        resource=replace(resource,generation=1,revision=rev.id)
+        await tx.replace(resource,0)
+    return resource
+
+
+async def bootstrap(store,contents,registry,now, *, selftest_run_id=None):
+    definition=manifest()
+    feature_manifest(definition)
+    namespace_root='t_selftest_'+selftest_run_id if selftest_run_id is not None else ROOT_SPACE
+    async with store.transaction(write=True) as tx:
+        for data in definition['resources']:
+            if selftest_run_id is not None and data['id']!='r_root' and data['parent']==ROOT_SPACE:
+                data=dict(data,parent=namespace_root)
+            registry.resource_type(data['type'],1)
+            body=None
+            if data['type']=='tool':
+                from msg.extensions.tools import descriptor
+                body=canonical(descriptor(data['name'])).decode()
+            elif data['id']=='r_msg_entry_skill':
+                body=MSG_ENTRY_SKILL
+            await seed_resource(tx,contents,data,now,body,
+                                'application/json' if data['type']=='tool' else 'text/markdown')
+            if selftest_run_id is not None and data['id']=='r_root':
+                await seed_resource(tx,contents,dict(id='t_selftest',type='topic',name='_test',
+                    parent=ROOT_SPACE,owner=ROOT_SUBJECT,group=ADMINS_GROUP,mode='0711'),now)
+                await seed_resource(tx,contents,dict(id=namespace_root,type='topic',name=selftest_run_id,
+                    parent='t_selftest',owner=ROOT_SUBJECT,group=ADMINS_GROUP,mode='0711'),now)
+        if selftest_run_id is None:
+            # Stable bootstrap IDs make repeated starts idempotent. The hosting
+            # read path uses these ordinary resources, not a special-case page.
+            sample_blob_digest=digest(ROOT_WEB_SAMPLE)
+            sample_revision='v_boot_'+digest(('f_root_web_index',sample_blob_digest))[7:39]
+            manifest_body=canonical({'format_version':1,'deployment':'t_root_web_deploy',
+                'entries':{'index.html':{'id':'f_root_web_index','revision':sample_revision}}})
+            await seed_resource(tx,contents,dict(id='w_root_web',type='website',name='web',parent='u_root',
+                owner=ROOT_SUBJECT,group=PUBLIC_GROUP,mode='0755'),now,manifest_body,'application/json')
+            await seed_resource(tx,contents,dict(id='t_root_web_deploy',type='topic',name='deploy-bootstrap',
+                parent='w_root_web',owner=ROOT_SUBJECT,group=PUBLIC_GROUP,mode='0755'),now)
+            await seed_resource(tx,contents,dict(id='f_root_web_index',type='file',name='index.html',
+                parent='t_root_web_deploy',owner=ROOT_SUBJECT,group=PUBLIC_GROUP,mode='0644'),
+                now,ROOT_WEB_SAMPLE,'text/html')
+        for data in definition['resources']:
+            if data['type']!='topic':
+                continue
+            tx.execute('''INSERT INTO topic_settings (topic,membership_policy) VALUES (?,?)
+                ON CONFLICT(topic) DO NOTHING''',(data['id'],'open'),write=True)
+            tx.execute('''INSERT INTO topic_memberships
+                (topic,subject,role,status,joined_at,invited_by) VALUES (?,?,?,?,?,?)
+                ON CONFLICT(topic,subject) DO NOTHING''',
+                (data['id'],ROOT_SUBJECT,'admin','active',wire(now),None),write=True)
+        for id,kind,primary,local in ((ROOT_SUBJECT,'system',ADMINS_GROUP,True),(ONLINE_CA,'system',ADMINS_GROUP,False)):
+            if not tx.one('SELECT id FROM identities WHERE id=?',(id,)):
+                await tx.update_identity(Subject(resource_id=id,kind=kind,primary_group=primary,auth_version=0,local_only=local),-1)
+        for id,builtin in ((PUBLIC_GROUP,'public'),(ADMINS_GROUP,'admins')):
+            if not tx.one('SELECT id FROM identities WHERE id=?',(id,)):
+                await tx.update_identity(Organization(resource_id=id,membership_version=0,builtin=builtin),-1)
+        for id,policy in definition['policies'].items():
+            if tx.setting('policy:'+id) is None:
+                tx.set_setting('policy:'+id,policy)
+        for name,body in definition['templates'].items():
+            resource=await seed_resource(tx,contents,dict(id='tpl_'+name,type='template',name=name,parent='t_templates',
+                owner=ROOT_SUBJECT,group=PUBLIC_GROUP,mode='0644'),now,body,'application/msg-template')
+            tx.set_setting(f'template_version:{resource.id}:1',resource.revision)
+        for key,schema in registry._schemas.items():
+            await seed_resource(tx,contents,dict(id=key,type='file',name=key.removeprefix('schema:'),parent='t_schema',
+                owner=ROOT_SUBJECT,group=PUBLIC_GROUP,mode='0444'),now,canonical(schema),'application/json')
+        await sync_system_sources(tx,contents,now,namespace_root=namespace_root)
+        tx.set_setting('bootstrap',{'version':definition['version'],'digest':digest(definition)})
+
+
+MSG_ENTRY_SKILL = '''# msg-entry
+
+Read /AGENTS.md first, then the compact operation index at /-/d. Open only
+the relevant namespace or operation detail at /-/d/<namespace>/<operation> and inspect
+/-/schema when exact fields are needed. Ordinary paths are read-only.
+Use the local `msg` client when available so it signs requests and preserves
+request IDs. A skill explains how to call an operation; it grants no authority.
+'''