msgctl 0.1.0a1__py3-none-any.whl

msg/admin/root.py

@@ -0,0 +1,347 @@
+"""Local root administration; never imported by a network adapter or worker.
+
+The underscored provisioning functions are internal local use cases. The command
+entrypoint must pass OS-console checks before calling them. Tests call these use
+cases only against disposable directories and never enable a network root route.
+"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import replace
+from datetime import timedelta
+import getpass
+import os
+from pathlib import Path
+import re
+import sys
+
+from msg.constants import *
+from msg.core.codec import b64,unb64,canonical,decode,digest,loads,wire
+from msg.core.errors import Failure,require
+from msg.core.models import Certificate,CertificateRequest,Credential,IssuancePolicy,Signature,ResourceRef,Event,AuditEvent
+from msg.security.crypto import Ed25519Signer,seal_private_key,open_private_key
+from msg.security.certificates import sign_certificate,csr_body,verify_csr
+from msg.security.capabilities import grant_for
+from msg.storage.git import durable_write
+from msg.bootstrap import bootstrap,seed_resource
+from msg.plugins.common import new_id
+from msg.plugins.identity import certificate_resource
+
+
+def root_envelope(config_dir):
+    from msg.config import root_private_dir
+    current=root_private_dir(Path(config_dir))/'key.json'
+    legacy=Path(config_dir)/'root'/'key.json'
+    return legacy if legacy.is_file() and not current.exists() else current
+
+
+async def _provision(app,pin):
+    """Initialize only an empty installation; partial state requires explicit recovery."""
+    settings=app.settings
+    protected=settings.root_private_dir
+    marker=settings.config_dir/'initialization.pending'
+    require(not root_envelope(settings.config_dir).exists() and not settings.trust_file.exists() and
+            not marker.exists(),'initialization_requires_recovery')
+    await app.open_storage()
+    async with app.metadata.transaction(write=False) as tx:
+        require(tx.one('SELECT COUNT(*) FROM resources')[0] == 0,'initialization_requires_recovery')
+    root=Ed25519Signer.generate()
+    envelope=seal_private_key(root.private_bytes(),pin)
+    settings.config_dir.mkdir(parents=True,exist_ok=True)
+    durable_write(marker,b'1\n',mode=0o600)
+    protected.mkdir(mode=0o700,parents=True,exist_ok=True)
+    os.chmod(protected,0o700)
+    settings.service_keys.mkdir(mode=0o700,parents=True,exist_ok=True)
+    os.chmod(settings.service_keys,0o700)
+    settings.trust_file.parent.mkdir(mode=0o755,parents=True,exist_ok=True)
+    # Wrapped before touching the installation; a rejected PIN leaves no partial state.
+    durable_write(root_envelope(settings.config_dir),canonical(envelope),mode=0o600)
+    online=Ed25519Signer.generate()
+    receipt=Ed25519Signer.generate()
+    durable_write(settings.service_keys/'online.key',online.private_bytes(),mode=0o600)
+    durable_write(settings.service_keys/'receipt.key',receipt.private_bytes(),mode=0o600)
+    durable_write(settings.service_keys/'tokens.key',os.urandom(32),mode=0o600)
+    now=app.clock()
+    await bootstrap(app.metadata,app.contents,app.registry,now,
+                    selftest_run_id=app.selftest_run_id)
+    root_grants=app.primary_ceiling()
+    root_certificate=Certificate(resource_id='cert_root',serial=new_id('serial'),subject_id=ROOT_SUBJECT,
+        key_id=root.key_id,issuer_id=ROOT_SUBJECT,parent_certificate_id=None,authority_sources=(),kind='ca',
+        grants=root_grants,not_before=now,expires_at=now+timedelta(days=3650),target_service=settings.service_url,
+        delegation_depth=8,issuance=IssuancePolicy(issue_grants=root_grants,max_cert_ttl_seconds=31536000,
+            max_child_ca_depth=3,max_delegation_depth=8),signature=Signature(key_id=root.key_id,algorithm='ed25519',value=b''))
+    root_certificate=sign_certificate(root_certificate,root)
+    online_use=grant_for(app.registry.capability('cert.issue'),scope=app.default_scope())
+    csr=CertificateRequest(resource_id=new_id('csr'),applicant=ONLINE_CA,subject_id=ONLINE_CA,
+        requested_issuer=ROOT_SUBJECT,public_key=online.public_key,kind='ca',grants=(online_use,),
+        issuance=IssuancePolicy(issue_grants=app.base_grants(),max_cert_ttl_seconds=settings.base_certificate_ttl,
+            max_child_ca_depth=0,max_delegation_depth=8),requested_ttl_seconds=31536000,
+        target_service=settings.service_url,delegation_depth=0,authority_sources=(),request_digest='',
+        possession_proof=Signature(key_id=online.key_id,algorithm='ed25519',value=b''))
+    csr=replace(csr,request_digest=digest(csr_body(csr)),
+                possession_proof=online.sign(canonical(csr_body(csr)),purpose='csr'))
+    async with app.metadata.transaction(write=True) as tx:
+        for uid,signer,ceiling in ((ROOT_SUBJECT,root,()),(ONLINE_CA,online,(online_use,))):
+            await tx.save_credential(Credential(id=signer.key_id,subject_id=uid,kind='signing_key',verifier=signer.public_key,
+                ceiling=ceiling,not_before=now,expires_at=None,revoked_at=None),0)
+            for name in ('keys','certificates'):
+                await seed_resource(tx,app.contents,dict(id='r_'+digest((uid,name))[7:39],type='topic',name=name,parent=uid,
+                    owner=uid,group=PUBLIC_GROUP,mode='0555'),now)
+        await certificate_resource(tx,root_certificate,now)
+        await tx.register_certificate(root_certificate,None,0)
+        await seed_resource(tx,app.contents,dict(id=csr.resource_id,type='csr',name=csr.resource_id,parent=CSR_SPACE,
+            owner=ONLINE_CA,group=ADMINS_GROUP,mode='0600'),now)
+        await tx.save_csr(csr)
+        tx.set_setting('active_root_certificate',root_certificate.resource_id)
+        tx.set_setting('online_ca_request',csr.resource_id)
+        tx.set_setting('receipt_public_key',{'key_id':receipt.key_id,'public_key':b64(receipt.public_key)})
+    durable_write(settings.trust_file,canonical({'version':1,'public_key':b64(root.public_key),
+                                               'certificate':wire(root_certificate)}),mode=0o444)
+    marker.unlink()
+    await app.load()
+    return csr.resource_id,root
+
+
+async def _approve_csr(app,csr_id,signer, *, expected_digest,operator):
+    now=app.clock()
+    async with app.metadata.transaction(write=True) as tx:
+        csr=await tx.csr(csr_id)
+        state=await tx.csr_state(csr_id)
+        require(csr.requested_issuer==ROOT_SUBJECT,'not_root_request')
+        if expected_digest is not None:
+            require(csr.request_digest==expected_digest,'csr_changed_after_confirmation')
+        verify_csr(csr)
+        if state.status=='issued':
+            return await tx.certificate(state.certificate_id)
+        require(state.status=='pending','csr_not_pending')
+        require(signer.key_id==app.certificates.root_certificate.key_id,'root_key_mismatch')
+        parent=app.certificates.root_certificate
+        certificate=Certificate(resource_id=new_id('cert'),serial=new_id('serial'),subject_id=csr.subject_id,
+            key_id=csr.possession_proof.key_id,issuer_id=ROOT_SUBJECT,parent_certificate_id=parent.resource_id,
+            authority_sources=csr.authority_sources,kind=csr.kind,grants=csr.grants,not_before=now,
+            expires_at=min(now+timedelta(seconds=csr.requested_ttl_seconds),parent.expires_at),
+            target_service=csr.target_service,delegation_depth=csr.delegation_depth,issuance=csr.issuance,
+            signature=Signature(key_id=signer.key_id,algorithm='ed25519',value=b''))
+        certificate=sign_certificate(certificate,signer)
+        await certificate_resource(tx,certificate,now)
+        await app.certificates.validate_publication(certificate,csr,tx)
+        await tx.register_certificate(certificate,csr_id,state.generation)
+        credential=await tx.credential(certificate.key_id)
+        if not credential.ceiling:
+            subject=await tx.subject(credential.subject_id)
+            await tx.save_credential(replace(credential,ceiling=certificate.grants),subject.auth_version)
+        if csr_id==tx.setting('online_ca_request'):
+            tx.set_setting('online_ca_certificate',certificate.resource_id)
+        event=Event(id=new_id('audit'),type='root.cert.issue',time=now,request_id=csr_id,
+            actor=ROOT_SUBJECT,subject=ROOT_SUBJECT,resources=(ResourceRef(id=certificate.resource_id),),
+            data={'operator':operator,'csr_digest':csr.request_digest,'grants':wire(certificate.grants)})
+        await tx.append_audit(AuditEvent(event=event,authority=(ResourceRef(id=parent.resource_id),),
+            before_digest=csr.request_digest,after_digest=digest(certificate),previous_digest=None,entry_digest='',result='issued'))
+        return certificate
+
+
+def require_local_console(config_dir):
+    """OS root plus a local VT/serial console, not an arbitrary pseudo-terminal.
+
+    Remote SSH and terminal multiplexers normally use /dev/pts and cannot satisfy
+    this boundary merely by deleting SSH_* variables or supplying client=cli.
+    Deployments that need another administrative channel must use a separately
+    audited OS policy, not relax this check through the network configuration.
+    """
+    require(hasattr(os,'geteuid') and os.geteuid()==0,'local_os_administrator_required')
+    require(not any(name in os.environ for name in ('SSH_CONNECTION','SSH_CLIENT','SSH_TTY')),'remote_admin_forbidden')
+    require(sys.stdin.isatty() and sys.stdout.isatty(),'local_console_required')
+    tty=os.path.realpath(os.ttyname(sys.stdin.fileno()))
+    require(re.fullmatch(r'/dev/(console|tty[0-9]+|ttyS[0-9]+|hvc[0-9]+)',tty) is not None,
+            'local_console_required')
+    path=Path(config_dir).resolve()
+    require(path.exists() and path.stat().st_uid==0 and not path.stat().st_mode&0o022,'unsafe_config_owner')
+    return f'uid:{os.geteuid()}:{tty}'
+
+
+class RootAdmin:
+    def __init__(self,config_dir=Path('/etc/msgd')):
+        self.config_dir=Path(config_dir)
+
+    def _app(self):
+        from msg.application import Application
+        from msg.config import load_settings
+        return Application(load_settings(self.config_dir))
+
+    def initialize(self):
+        require_local_console(self.config_dir)
+        app=self._app()
+        if root_envelope(self.config_dir).exists() and app.settings.trust_file.exists():
+            status=self.doctor()
+            require(all(status['checks'].get(k,{}).get('ok') for k in ('storage','root_trust','bootstrap','root_private_boundary')),
+                    'initialization_requires_recovery')
+            private=open_private_key(loads(root_envelope(self.config_dir).read_bytes()),getpass.getpass('Current root PIN/passphrase: '))
+            trust=loads(app.settings.trust_file.read_bytes())
+            require(Ed25519Signer.from_bytes(private).public_key==unb64(trust['public_key']),'root_key_mismatch')
+            return status['root_id']
+        first=getpass.getpass('New root PIN/passphrase: ')
+        second=getpass.getpass('Confirm root PIN/passphrase: ')
+        require(first==second,'pin_confirmation_mismatch')
+        csr,_=asyncio.run(_provision(app,first))
+        print(canonical({'status':'initialized','root_id':ROOT_SUBJECT,'online_ca_request':csr}).decode())
+        return ROOT_SUBJECT
+
+    def issue(self,csr_id):
+        operator=require_local_console(self.config_dir)
+        app=self._app()
+        async def read():
+            await app.load()
+            async with app.metadata.transaction(write=False) as tx:
+                return await tx.csr(csr_id),await tx.csr_state(csr_id)
+        csr,state=asyncio.run(read())
+        # json.dumps escapes terminal controls; no raw user-controlled text is printed.
+        print(canonical({'request':wire(csr),'state':wire(state),'public_key_fingerprint':digest(csr.public_key)}).decode())
+        if state.status=='issued':
+            async def previous():
+                async with app.metadata.transaction(write=False) as tx:
+                    return await tx.certificate(state.certificate_id)
+            return asyncio.run(previous())
+        require(input('Type the exact CSR digest to approve: ').strip()==csr.request_digest,'approval_cancelled')
+        pin=getpass.getpass('Root PIN/passphrase: ')
+        private=open_private_key(loads(root_envelope(self.config_dir).read_bytes()),pin)
+        signer=Ed25519Signer.from_bytes(private)
+        return asyncio.run(_approve_csr(app,csr_id,signer,expected_digest=csr.request_digest,operator=operator))
+
+    def change_pin(self):
+        require_local_console(self.config_dir)
+        require(input('Type CHANGE PIN to continue: ')=='CHANGE PIN','approval_cancelled')
+        path=root_envelope(self.config_dir)
+        private=open_private_key(loads(path.read_bytes()),getpass.getpass('Current root PIN/passphrase: '))
+        first=getpass.getpass('New root PIN/passphrase: ')
+        require(first==getpass.getpass('Confirm new root PIN/passphrase: '),'pin_confirmation_mismatch')
+        durable_write(path,canonical(seal_private_key(private,first)),mode=0o600)
+
+    def rotate(self, *, lost_key=False, resume=False):
+        operator=require_local_console(self.config_dir)
+        app=self._app()
+        from msg.admin.rotation import prepare,complete,journal_path
+        if resume:
+            require(journal_path(app).is_file(),'rotation_journal_missing')
+            journal=loads(journal_path(app).read_bytes())
+            print(canonical(journal['statement']).decode())
+            require(input('Type the new root fingerprint to resume: ')==journal['statement']['new_fingerprint'],'approval_cancelled')
+            pin=getpass.getpass('New root PIN/passphrase: ')
+        else:
+            asyncio.run(app.load())
+            print(canonical({'old_fingerprint':digest(app.certificates.root_public_key),
+                'effect':'all existing certificate chains require reissuance','lost_key':lost_key}).decode())
+            require(input('Type ROTATE ROOT '+digest(app.certificates.root_public_key)+': ')==
+                    'ROTATE ROOT '+digest(app.certificates.root_public_key),'approval_cancelled')
+            old=None if lost_key else Ed25519Signer.from_bytes(open_private_key(
+                loads(root_envelope(self.config_dir).read_bytes()),getpass.getpass('Current root PIN/passphrase: ')))
+            pin=getpass.getpass('New root PIN/passphrase: ')
+            require(pin==getpass.getpass('Confirm new root PIN/passphrase: '),'pin_confirmation_mismatch')
+            journal=prepare(app,Ed25519Signer.generate(),pin,old_signer=old,operator=operator)
+        return asyncio.run(complete(app,journal,pin=pin))
+
+    def doctor(self):
+        # Imported lazily: this read-only diagnostic must not run schema migrations.
+        from msg.admin.diagnostics import doctor
+        return doctor(self.config_dir)
+
+    def selftest(self):
+        from msg.admin.diagnostics import selftest
+        return asyncio.run(selftest())
+
+
+    def revoke(self,certificate_id,reason):
+        operator=require_local_console(self.config_dir)
+        app=self._app()
+        asyncio.run(app.load())
+        async def read():
+            async with app.metadata.transaction(write=False) as tx:return await tx.certificate(certificate_id)
+        certificate=asyncio.run(read())
+        print(canonical({'certificate':wire(certificate),'reason':reason}).decode())
+        require(input('Type REVOKE '+certificate_id+' to continue: ')=='REVOKE '+certificate_id,'approval_cancelled')
+        private=open_private_key(loads(root_envelope(self.config_dir).read_bytes()),getpass.getpass('Root PIN/passphrase: '))
+        return asyncio.run(_revoke(app,certificate_id,Ed25519Signer.from_bytes(private),reason=reason,operator=operator))
+
+
+    def sign_backup_retirement(self,source,destination):
+        """Root-sign an operator's statement that listed backup sets lost one old key."""
+        require_local_console(self.config_dir)
+        from msg.admin.backup_retirement import unsigned_statement
+        from msg.security.backup_retirement import sign_record
+        target=Path(destination)
+        require(not target.exists() and not target.is_symlink(),'backup_retirement_destination_exists')
+        body=unsigned_statement(loads(Path(source).read_bytes()))
+        print(canonical({'statement':body,'digest':digest(body),
+                         'claim':'listed_backup_sets_only'}).decode())
+        require(input('Type ATTEST BACKUP RETIREMENT '+digest(body)+': ')==
+                'ATTEST BACKUP RETIREMENT '+digest(body),'approval_cancelled')
+        private=open_private_key(loads(root_envelope(self.config_dir).read_bytes()),getpass.getpass('Root PIN/passphrase: '))
+        record=sign_record(body,Ed25519Signer.from_bytes(private))
+        durable_write(target,canonical(record),mode=0o600)
+        return {'status':'backup_retirement_signed','path':str(target),'digest':digest(record)}
+
+    def import_backup_retirement(self,source):
+        """Only this console path persists a record; reads re-verify it every time."""
+        operator=require_local_console(self.config_dir)
+        from msg.admin.backup_retirement import import_record
+        app=self._app()
+        record=loads(Path(source).read_bytes())
+        print(canonical({'record':record,'digest':digest(record)}).decode())
+        require(input('Type IMPORT BACKUP RETIREMENT '+digest(record)+': ')==
+                'IMPORT BACKUP RETIREMENT '+digest(record),'approval_cancelled')
+        async def run():
+            await app.load()
+            try:
+                async with app.metadata.transaction(write=True) as tx:
+                    return await import_record(tx,record,now=app.clock(),operator=operator)
+            finally:
+                await app.close()
+        attestation=asyncio.run(run())
+        return {'status':'backup_retirement_imported','scope':'listed_backup_sets_only',
+                **attestation.view()}
+
+    def backup(self,destination):
+        require_local_console(self.config_dir)
+        target=Path(destination)
+        require(not target.exists() and not target.is_symlink(),'backup_destination_exists')
+        envelope=loads(root_envelope(self.config_dir).read_bytes())
+        trust=loads((self.config_dir/'trust'/'root.json').read_bytes())
+        require(input('Type BACKUP ROOT to continue: ')=='BACKUP ROOT','approval_cancelled')
+        private=open_private_key(envelope,getpass.getpass('Root PIN/passphrase: '))
+        require(b64(Ed25519Signer.from_bytes(private).public_key)==trust['public_key'],'root_key_mismatch')
+        durable_write(target,canonical({'format':'msg-root-backup-v1','envelope':envelope,'trust':trust}),mode=0o600)
+        return {'status':'encrypted_backup_created','path':str(target),'fingerprint':digest(unb64(trust['public_key']))}
+
+
+    def recover(self,source):
+        require_local_console(self.config_dir)
+        target=root_envelope(self.config_dir)
+        require(not target.exists(),'root_material_already_present')
+        backup=loads(Path(source).read_bytes())
+        require(set(backup)=={'format','envelope','trust'} and backup['format']=='msg-root-backup-v1','invalid_root_backup')
+        current=loads((self.config_dir/'trust'/'root.json').read_bytes())
+        require(canonical(current)==canonical(backup['trust']),'trust_anchor_mismatch')
+        print(canonical({'fingerprint':digest(unb64(current['public_key'])),'action':'recover_missing_encrypted_root_key'}).decode())
+        require(input('Type RECOVER ROOT to continue: ')=='RECOVER ROOT','approval_cancelled')
+        private=open_private_key(backup['envelope'],getpass.getpass('Backup root PIN/passphrase: '))
+        require(b64(Ed25519Signer.from_bytes(private).public_key)==current['public_key'],'root_key_mismatch')
+        target.parent.mkdir(mode=0o700,parents=True,exist_ok=True)
+        os.chmod(target.parent,0o700)
+        durable_write(target,canonical(backup['envelope']),mode=0o600)
+        return {'status':'root_key_recovered','fingerprint':digest(unb64(current['public_key']))}
+
+
+async def _revoke(app,certificate_id,signer, *, reason,operator):
+    require(certificate_id!=app.certificates.root_certificate.resource_id,'root_rotation_required')
+    require(signer.key_id==app.certificates.root_certificate.key_id,'root_key_mismatch')
+    async with app.metadata.transaction(write=True) as tx:
+        certificate=await tx.certificate(certificate_id)
+        statement={'certificate_id':certificate_id,'reason':reason,'time':wire(app.clock()),
+                   'issuer':ROOT_SUBJECT,'operator':operator}
+        signature=signer.sign(canonical(statement),purpose='revocation')
+        event=Event(id=new_id('audit'),type='root.cert.revoke',time=app.clock(),request_id=new_id('local'),
+            actor=ROOT_SUBJECT,subject=ROOT_SUBJECT,resources=(ResourceRef(id=certificate_id),),
+            data={**statement,'signature':wire(signature)})
+        await tx.revoke_certificate(certificate_id,AuditEvent(event=event,
+            authority=(ResourceRef(id=app.certificates.root_certificate.resource_id),),before_digest=digest(certificate),
+            after_digest=digest(statement),previous_digest=None,entry_digest='',result='revoked'))
+    return {'certificate_id':certificate_id,'revoked':True,'signature':wire(signature)}

msg/admin/rotation.py

@@ -0,0 +1,197 @@
+"""Explicit local trust rotation with a PIN-encrypted, crash-recoverable journal.
+
+The journal never contains a plaintext private key. Installing a new trust anchor
+invalidates all old certificate chains for new requests. Historical public keys
+and signed records remain available; they are not retroactively re-signed.
+"""
+from __future__ import annotations
+from dataclasses import replace
+from datetime import timedelta
+import os
+
+from msg.constants import ROOT_SUBJECT, ONLINE_CA, ADMINS_GROUP, CSR_SPACE
+from msg.core.codec import canonical, decode, digest, wire, b64, loads
+from msg.core.errors import require
+from msg.core.models import Certificate, CertificateRequest, Credential, Signature, IssuancePolicy, AuditEvent, Event, ResourceRef
+from msg.plugins.common import new_id
+from msg.plugins.identity import certificate_resource
+from msg.security.crypto import seal_private_key, Ed25519Signer
+from msg.security.certificates import sign_certificate, csr_body
+from msg.security.rotation_journal import authorization, validate as validate_journal
+from msg.security.root_files import read_private, rotation_lock
+from msg.security.capabilities import grant_for
+from msg.storage.git import durable_write
+from msg.bootstrap import seed_resource
+
+
+def journal_path(app):
+    from msg.admin.root import root_envelope
+    return root_envelope(app.settings.config_dir).parent/'rotation.pending.json'
+
+
+def prepare(app, new_signer, new_pin, *, old_signer, operator):
+    with rotation_lock(journal_path(app).parent):
+        return _prepare(app, new_signer, new_pin, old_signer=old_signer, operator=operator)
+
+
+def _prepare(app, new_signer, new_pin, *, old_signer, operator):
+    require(not journal_path(app).exists(), 'root_rotation_pending')
+    old = app.certificates.root_certificate
+    if old_signer is not None:
+        require(old_signer.key_id == old.key_id, 'root_key_mismatch')
+    now = app.clock()
+    grants = app.primary_ceiling()
+    new = Certificate(resource_id=new_id('cert_root'), serial=new_id('serial'), subject_id=ROOT_SUBJECT,
+        key_id=new_signer.key_id, issuer_id=ROOT_SUBJECT, parent_certificate_id=None, authority_sources=(), kind='ca',
+        grants=grants, not_before=now, expires_at=now+timedelta(days=3650), target_service=app.settings.service_url,
+        delegation_depth=8, issuance=IssuancePolicy(issue_grants=grants,max_cert_ttl_seconds=31536000,
+            max_child_ca_depth=3,max_delegation_depth=8),
+        signature=Signature(key_id=new_signer.key_id, algorithm='ed25519', value=b''))
+    new = sign_certificate(new, new_signer)
+    statement = {'old_certificate':old.resource_id, 'old_fingerprint':digest(app.certificates.root_public_key),
+        'new_certificate':new.resource_id, 'new_fingerprint':digest(new_signer.public_key), 'time':wire(now),
+        'operator':operator, 'previous_key_proved':old_signer is not None}
+    online = app.online_signer
+    csr = CertificateRequest(resource_id=new_id('csr'), applicant=ONLINE_CA, subject_id=ONLINE_CA,
+        requested_issuer=ROOT_SUBJECT, public_key=online.public_key, kind='ca',
+        grants=(grant_for(app.registry.capability('cert.issue'),scope=app.default_scope()),),
+        issuance=IssuancePolicy(issue_grants=app.base_grants(),max_cert_ttl_seconds=app.settings.base_certificate_ttl,
+            max_child_ca_depth=0,max_delegation_depth=8), requested_ttl_seconds=31536000,
+        target_service=app.settings.service_url,delegation_depth=0,authority_sources=(),request_digest='',
+        possession_proof=Signature(key_id=online.key_id,algorithm='ed25519',value=b''))
+    csr = replace(csr, request_digest=digest(csr_body(csr)),
+                  possession_proof=online.sign(canonical(csr_body(csr)),purpose='csr'))
+    from msg.admin.root import root_envelope
+    key_file=root_envelope(app.settings.config_dir)
+    require(not key_file.is_symlink(),'unsafe_root_private_path')
+    journal={'version':2,'old_certificate':wire(old),'new_trust':{'version':1,
+        'public_key':b64(new_signer.public_key),'certificate':wire(new)},
+        'new_envelope':seal_private_key(new_signer.private_bytes(),new_pin),
+        'previous_envelope_digest':digest(read_private(key_file)) if key_file.exists() else None,
+        'online_csr':wire(csr),'statement':statement}
+    proof=canonical(authorization(journal))
+    journal['new_signature']=wire(new_signer.sign(proof,purpose='root-rotation'))
+    journal['old_signature']=wire(old_signer.sign(proof,purpose='root-rotation')) if old_signer else None
+    protected=journal_path(app).parent
+    require(not protected.is_symlink(),'unsafe_root_private_path')
+    protected.mkdir(parents=True,exist_ok=True,mode=0o700)
+    os.chmod(protected,0o700)
+    durable_write(journal_path(app),canonical(journal),mode=0o600)
+    return journal
+
+
+async def complete(app, journal, *, pin):
+    with rotation_lock(journal_path(app).parent):
+        return await _complete(app, journal, pin=pin)
+
+
+async def _complete(app, journal, *, pin):
+    from msg.security.crypto import verify
+    pending=journal_path(app)
+    protected=pending.parent
+    require(not protected.is_symlink() and not pending.is_symlink(),
+            'unsafe_root_private_path')
+    online=Ed25519Signer.from_bytes((app.settings.service_keys/'online.key').read_bytes())
+    signer,old,new,csr,proof=validate_journal(journal,pin=pin,
+        service=app.settings.service_url,online_public=online.public_key)
+    key_file=protected/'key.json'
+    require(not key_file.is_symlink(),'unsafe_root_private_path')
+    if key_file.exists():
+        require(digest(read_private(key_file)) in {
+            journal['previous_envelope_digest'],digest(canonical(journal['new_envelope']))},
+            'root_envelope_changed')
+    else:
+        require(journal['previous_envelope_digest'] is None,'root_envelope_missing')
+    # Reject unsafe or substituted history BEFORE changing the database anchor.
+    history = protected/'history'/old.resource_id/'key.json'
+    for directory in (protected/'history', history.parent):
+        require(not directory.is_symlink(), 'unsafe_root_private_path')
+    require(not history.is_symlink(), 'unsafe_root_private_path')
+    if history.exists():
+        require(digest(read_private(history)) == journal['previous_envelope_digest'],
+                'rotation_history_mismatch')
+    elif journal['previous_envelope_digest'] is not None:
+        require(key_file.exists() and
+                digest(read_private(key_file)) == journal['previous_envelope_digest'],
+                'rotation_history_missing')
+    require(app.settings.trust_file.is_file() and not app.settings.trust_file.is_symlink(),
+            'rotation_trust_missing')
+    current_trust = loads(app.settings.trust_file.read_bytes())
+    # This method is called only after the local console has approved the exact
+    # journal. It also handles the state where PostgreSQL committed but protected files did not.
+    await app.open_storage()
+    async with app.metadata.transaction(write=True) as tx:
+        current=tx.setting('active_root_certificate','cert_root')
+        require(current in {old.resource_id,new.resource_id},'trust_anchor_mismatch')
+        existing=await tx.certificate(old.resource_id)
+        require(canonical(existing)==canonical(old),'trust_anchor_mismatch')
+        old_key=await tx.credential(old.key_id)
+        require(old_key.subject_id==ROOT_SUBJECT and
+                digest(old_key.verifier)==journal['statement']['old_fingerprint'],
+                'rotation_statement_mismatch')
+        old_trust = {'version': 1, 'public_key': b64(old_key.verifier), 'certificate': wire(old)}
+        require(canonical(current_trust) in (canonical(old_trust), canonical(journal['new_trust'])),
+                'rotation_trust_changed')
+        if journal['old_signature'] is not None:
+            verify(old_key.verifier,canonical(proof),decode(Signature,journal['old_signature']),
+                   purpose='root-rotation')
+        if current == new.resource_id:
+            require(canonical(await tx.certificate(new.resource_id))==canonical(new) and
+                    canonical(await tx.csr(csr.resource_id))==canonical(csr) and
+                    old_key.revoked_at is not None and await tx.certificate_revoked(old.resource_id),
+                    'rotation_resume_mismatch')
+            installed=await tx.credential(new.key_id)
+            require(installed.verifier==signer.public_key and installed.revoked_at is None,
+                    'rotation_resume_mismatch')
+        else:
+            subject=await tx.subject(ROOT_SUBJECT)
+            require(subject.local_only,'root_policy_corrupt')
+            # Credential saves are upserts; a retired root key must never be revived.
+            require(tx.one('SELECT 1 FROM credentials WHERE id=?',(signer.key_id,)) is None,
+                    'root_key_reused')
+            await tx.save_credential(Credential(id=signer.key_id,subject_id=ROOT_SUBJECT,kind='signing_key',
+                verifier=signer.public_key,ceiling=(),not_before=new.not_before,expires_at=None,revoked_at=None),subject.auth_version)
+            await tx.save_credential(replace(old_key,revoked_at=app.clock()),subject.auth_version)
+            await certificate_resource(tx,new,app.clock())
+            await tx.register_certificate(new,None,0)
+            event=Event(id=new_id('audit'),type='root.rotate',time=app.clock(),request_id=new.resource_id,
+                actor=ROOT_SUBJECT,subject=ROOT_SUBJECT,resources=(ResourceRef(id=new.resource_id),),
+                data={'statement':journal['statement'],'authorization':proof,'new_signature':journal['new_signature'],
+                      'old_signature':journal['old_signature']})
+            await tx.revoke_certificate(old.resource_id,AuditEvent(event=event,authority=(),
+                before_digest=digest(old),after_digest=digest(new),previous_digest=None,entry_digest='',result='root_rotated'))
+            await seed_resource(tx,app.contents,dict(id=csr.resource_id,type='csr',name=csr.resource_id,parent=CSR_SPACE,
+                owner=ONLINE_CA,group=ADMINS_GROUP,mode='0600'),app.clock())
+            await tx.save_csr(csr)
+            tx.set_setting('online_ca_request',csr.resource_id)
+            tx.set_setting('online_ca_certificate',None)
+            tx.set_setting('active_root_certificate',new.resource_id)
+            tx.set_setting('authorization_epoch',tx.setting('authorization_epoch',0)+1)
+            tx.set_setting('root_rotation:'+new.resource_id,journal['statement'])
+    # The journal and envelope must use the same independently protected root
+    # directory, including when resuming after the metadata commit.
+    for directory in (protected,protected/'history',protected/'history'/old.resource_id):
+        require(not directory.is_symlink(),'unsafe_root_private_path')
+        directory.mkdir(parents=True,exist_ok=True,mode=0o700)
+        os.chmod(directory,0o700)
+    history=protected/'history'/old.resource_id/'key.json'
+    require(not history.is_symlink(),'unsafe_root_private_path')
+    if history.exists():
+        require(digest(read_private(history))==journal['previous_envelope_digest'],
+                'rotation_history_mismatch')
+    elif journal['previous_envelope_digest'] is not None:
+        # Never archive an already installed new envelope as the old key.
+        require(key_file.exists() and
+                digest(read_private(key_file))==journal['previous_envelope_digest'],
+                'rotation_history_missing')
+        durable_write(history,read_private(key_file),mode=0o600)
+    durable_write(key_file,canonical(journal['new_envelope']),mode=0o600)
+    durable_write(app.settings.trust_file,canonical(journal['new_trust']),mode=0o444)
+    # Journal survives every earlier failure and is removed only after both
+    # metadata and protected files have durable copies.
+    pending.unlink(missing_ok=True)
+    directory=os.open(protected,os.O_RDONLY|os.O_DIRECTORY)
+    try:os.fsync(directory)
+    finally:os.close(directory)
+    return {'root_id':ROOT_SUBJECT,'certificate_id':new.resource_id,'fingerprint':digest(signer.public_key),
+        'online_ca_request':csr.resource_id,'restart_required':True,'old_certificate_chains_valid':False}

msg/admin/token_delivery_check.py

@@ -0,0 +1,54 @@
+"""Exercise one-use credential release only on the caller's isolated Test Root."""
+from datetime import timedelta
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import httpx
+
+from msg.client import ClientState, MsgClient
+from msg.core.errors import Failure
+from msg.transports.client import HTTPTransport
+from msg.transports.http import create_app
+
+
+async def check_token_delivery(app, now):
+    with TemporaryDirectory(prefix='msg-token-selftest-') as directory:
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=create_app(app))) as http:
+            state = ClientState(Path(directory), server=app.settings.service_url)
+            transport = HTTPTransport(state.server, http=http)
+            client = MsgClient(state, transport, clock=lambda: now, retries=0)
+            created = await client.temporary()
+            if created.status != 'ok':
+                return False
+            original = state.token
+            send = transport.call
+
+            async def discard(packet):
+                result = await send(packet)
+                if result.status != 'ok':
+                    raise Failure('selftest_issuance_failed')
+                raise httpx.ReadTimeout('selftest response loss')
+
+            transport.call = discard
+            for attempt in (client.rotate_token, client.recover_token):
+                try:
+                    await attempt()
+                    return False
+                except Failure as exc:
+                    if exc.code != 'transport_uncertain':
+                        return False
+            # Both processes can restart; refreshing only the request expiry
+            # does not refresh either the token lifetime or recovery deadline.
+            state = ClientState(Path(directory), server=app.settings.service_url)
+            client = MsgClient(state, HTTPTransport(state.server, http=http),
+                               clock=lambda: now+timedelta(seconds=1), retries=0)
+            replay = await client.recover_token()
+            if replay.status != 'error' or replay.error.code != 'token_delivery_unavailable':
+                return False
+            completed = await client.recover_token()
+            if completed.status != 'ok' or not state.token or state.token[0] == original[0]:
+                return False
+            async with app.metadata.transaction(write=False) as tx:
+                old = await tx.credential(original[0])
+                current = await tx.credential(state.token[0])
+            return old.revoked_at is not None and current.revoked_at is None and client._token_journal() == (None, None)