msgctl 0.1.0a1__py3-none-any.whl

msg/security/certificates.py

@@ -0,0 +1,183 @@
+"""Current-state certificate chain validation and distinct issuance ceilings."""
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import timedelta
+
+from msg.constants import ROOT_SPACE,ROOT_SUBJECT,ONLINE_CA
+from msg.core.codec import canonical,wire,digest
+from msg.core.errors import Failure,require
+from msg.core.models import Certificate,Signature
+from msg.security.crypto import key_id,verify
+from msg.security.policy import constraints_subset,scope_subset,grant_covers
+
+
+# Keep this list explicit. Adding a new ordinary capability must not silently
+# enlarge the permanent online issuer's signing authority.
+ONLINE_ISSUABLE_CAPABILITIES=frozenset({
+    'identity.basic','resource.basic','discussion.basic','communication.basic',
+    'discovery.basic','transfer.basic','group.basic','cert.request','git.basic',
+    'hosting.basic','keystore.basic','batch.basic','sharing.basic',
+    'money.basic','store.basic','bounty.basic','orders.basic','delivery.basic',
+})
+
+
+def certificate_body(certificate):
+    body=wire(certificate)
+    body.pop('signature')
+    return body
+
+
+def csr_body(request):
+    body=wire(request)
+    for key in ('resource_id','request_digest','possession_proof'):
+        body.pop(key,None)
+    return body
+
+
+def sign_certificate(certificate,signer):
+    return replace(certificate,signature=signer.sign(canonical(certificate_body(certificate)),purpose='certificate'))
+
+
+def verify_csr(request):
+    require(request.request_digest==digest(csr_body(request)),'csr_digest_mismatch')
+    verify(request.public_key,canonical(csr_body(request)),request.possession_proof,purpose='csr')
+
+
+class CertificateValidator:
+    def __init__(self,registry,root_certificate,root_public_key,service,clock):
+        self.registry=registry
+        self.root_certificate=root_certificate
+        self.root_public_key=root_public_key
+        self.service=service
+        self.clock=clock
+
+    async def validate_grant(self,grant,session):
+        spec=self.registry.capability(grant.capability,grant.version)
+        resource=await session.resource(grant.scope.resource_id)
+        require(resource.type in spec.scope_types,'invalid_scope_type')
+        require(bool(grant.operations) and grant.operations<=spec.operations,'invalid_grant_operations')
+        if spec.constraints_schema is not None:
+            self.registry.validate(spec.constraints_schema,grant.constraints)
+        else:
+            require(not grant.constraints,'unknown_grant_constraint')
+        return spec
+
+    async def allowed_issuance(self,grant,policy,session):
+        await self.validate_grant(grant,session)
+        for allowed in policy.issue_grants:
+            if (grant.capability==allowed.capability and grant.version==allowed.version and
+                grant.operations<=allowed.operations and await scope_subset(grant.scope,allowed.scope,session)
+                and constraints_subset(grant.constraints,allowed.constraints)):
+                return True
+        return False
+
+    async def validate(self,id,session, *, seen=None,certificate=None,issuance_resource=None):
+        seen=set() if seen is None else set(seen)
+        require(id not in seen and len(seen)<32,'certificate_cycle')
+        seen.add(id)
+        cert=certificate or await session.certificate(id)
+        now=self.clock()
+        require(cert.target_service==self.service,'wrong_service')
+        require(cert.not_before<=now<cert.expires_at,'certificate_expired')
+        if certificate is None:
+            require(not await session.certificate_revoked(id),'certificate_revoked')
+        if id==self.root_certificate.resource_id:
+            require(canonical(cert)==canonical(self.root_certificate),'trust_anchor_mismatch')
+            require(cert.subject_id==ROOT_SUBJECT and cert.issuer_id==ROOT_SUBJECT and
+                    cert.parent_certificate_id is None and cert.kind=='ca','invalid_root_certificate')
+            verify(self.root_public_key,canonical(certificate_body(cert)),cert.signature,purpose='certificate')
+            return cert
+        require(cert.subject_id!=ROOT_SUBJECT and cert.parent_certificate_id is not None,'local_only')
+        parent=await self.validate(cert.parent_certificate_id,session,seen=seen)
+        require(parent.kind=='ca' and parent.issuance is not None,'issuer_not_ca')
+        require(cert.issuer_id==parent.subject_id,'issuer_mismatch')
+        parent_key=await session.credential(parent.key_id)
+        require(parent_key.subject_id==parent.subject_id and parent_key.revoked_at is None,'issuer_key_revoked')
+        verify(parent_key.verifier,canonical(certificate_body(cert)),cert.signature,purpose='certificate')
+        subject_key=await session.credential(cert.key_id)
+        require(subject_key.subject_id==cert.subject_id,'certificate_key_mismatch')
+        require(subject_key.revoked_at is None and subject_key.not_before<=now and
+                (subject_key.expires_at is None or now<subject_key.expires_at),'certificate_key_revoked')
+        require(parent.not_before<=cert.not_before and cert.expires_at<=parent.expires_at,'certificate_validity_escalation')
+        require((cert.expires_at-cert.not_before).total_seconds()<=parent.issuance.max_cert_ttl_seconds,
+                'certificate_ttl_escalation')
+        require(cert.delegation_depth<=parent.issuance.max_delegation_depth,'delegation_depth_exceeded')
+        # Signing rights are explicit use grants, not inferred from issue_grants.
+        issue_resource=issuance_resource or session.setting('certificate_request:'+cert.resource_id,cert.resource_id)
+        require(any([await grant_covers(g,'cert.issue','cert.publish@1',issue_resource,session)
+                     for g in parent.grants]),'issuer_cannot_issue')
+        for grant in cert.grants:
+            require(await self.allowed_issuance(grant,parent.issuance,session),'issuance_scope_exceeded')
+        if cert.subject_id==ONLINE_CA:
+            require(parent.resource_id==self.root_certificate.resource_id and cert.kind=='ca' and
+                    cert.issuance is not None and cert.issuance.max_child_ca_depth==0 and
+                    len(cert.grants)==1 and cert.grants[0].capability=='cert.issue' and
+                    'cert.publish@1' in cert.grants[0].operations,
+                    'online_ca_policy_exceeded')
+            require(all(grant.capability in ONLINE_ISSUABLE_CAPABILITIES and
+                        not self.registry.capability(grant.capability,grant.version).ca_only
+                        for grant in cert.issuance.issue_grants),'online_ca_policy_exceeded')
+        if parent.subject_id==ONLINE_CA:
+            require(cert.kind in {'identity','delegation'} and
+                    (cert.kind!='delegation' or bool(cert.authority_sources)) and
+                    all(grant.capability in ONLINE_ISSUABLE_CAPABILITIES for grant in cert.grants),
+                    'online_ca_policy_exceeded')
+        if cert.kind=='ca':
+            require(cert.issuance is not None and parent.issuance.max_child_ca_depth>0,'ca_depth_exceeded')
+            require(any([await grant_covers(g,'cert.ca.issue','cert.publish@1',issue_resource,session)
+                         for g in parent.grants]),'issuer_cannot_issue_ca')
+            require(cert.issuance.max_child_ca_depth<parent.issuance.max_child_ca_depth,'ca_depth_exceeded')
+            # The signed policy on an old trust anchor may allow more levels.
+            # Count the validated parent chain so an L4 CA remains impossible.
+            level=1
+            ancestor=parent
+            while ancestor.resource_id!=self.root_certificate.resource_id:
+                level+=1
+                ancestor=await session.certificate(ancestor.parent_certificate_id)
+            require(level<=3 and 0<=cert.issuance.max_child_ca_depth<=3-level,'ca_depth_exceeded')
+            require(cert.issuance.max_cert_ttl_seconds<=parent.issuance.max_cert_ttl_seconds and
+                    cert.issuance.max_delegation_depth<=parent.issuance.max_delegation_depth,'issuance_policy_escalation')
+            for grant in cert.issuance.issue_grants:
+                require(await self.allowed_issuance(grant,parent.issuance,session),'issuance_scope_exceeded')
+        else:
+            require(cert.issuance is None,'unexpected_issuance_policy')
+        for source in cert.authority_sources:
+            await self.validate_authority(source,cert,session,seen=seen)
+        return cert
+
+    async def validate_authority(self,source,cert,session, *, seen=None):
+        resource=await session.resource(source.id)
+        require(resource.type=='delegation' and resource.state=='active','authority_source_inactive')
+        require(source.revision==resource.revision,'authority_source_changed')
+        # The controlled delegation facts are distinct from mutable ordinary content.
+        fact=session.setting('delegation:'+source.id)
+        require(fact is not None and fact['grantee']==cert.subject_id,'authority_source_invalid')
+        from msg.core.codec import parse_time,decode
+        from msg.core.models import CapabilityGrant
+        require(parse_time(fact['expires_at'])>self.clock(),'authority_source_expired')
+        for raw in fact['grants']:
+            grant=decode(CapabilityGrant,raw)
+            target=await session.resource(grant.scope.resource_id)
+            require(target.owner==fact['grantor'],'authority_source_lost')
+        allowed=tuple(decode(CapabilityGrant,g) for g in fact['grants'])
+        for grant in (*cert.grants, *(cert.issuance.issue_grants if cert.issuance else ())):
+            require(any([g.capability==grant.capability and g.version==grant.version and
+                         grant.operations<=g.operations and await scope_subset(grant.scope,g.scope,session)
+                         and constraints_subset(grant.constraints,g.constraints) for g in allowed]),
+                    'delegation_scope_exceeded')
+        if fact.get('parent_certificate'):
+            await self.validate(fact['parent_certificate'],session,seen=set(seen or ())|{cert.resource_id})
+        return fact
+
+    async def validate_publication(self,cert,csr,session):
+        verify_csr(csr)
+        require(cert.subject_id==csr.subject_id and cert.issuer_id==csr.requested_issuer and
+                cert.key_id==key_id(csr.public_key) and cert.kind==csr.kind and
+                cert.grants==csr.grants and cert.issuance==csr.issuance and
+                cert.authority_sources==csr.authority_sources and
+                cert.delegation_depth==csr.delegation_depth and cert.target_service==csr.target_service,
+                'csr_certificate_mismatch')
+        require((cert.expires_at-cert.not_before).total_seconds()<=csr.requested_ttl_seconds,
+                'csr_ttl_exceeded')
+        return await self.validate(cert.resource_id,session,certificate=cert,issuance_resource=csr.resource_id)

msg/security/crypto.py

@@ -0,0 +1,102 @@
+"""Ed25519 and password wrapping from cryptography; no custom cryptographic primitive."""
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass, field
+
+from cryptography.exceptions import InvalidSignature, InvalidTag
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
+from cryptography.hazmat.primitives.serialization import Encoding, PrivateFormat, NoEncryption, PublicFormat
+
+from msg.core.codec import b64, canonical, unb64
+from msg.core.errors import Failure, require
+from msg.core.models import Signature
+
+
+def key_id(public: bytes) -> str:
+    return 'k_'+hashlib.sha256(public).hexdigest()
+
+
+def subject_id(public: bytes) -> str:
+    return 'u_'+hashlib.sha256(b'msg-subject-v1\0'+public).hexdigest()[:32]
+
+
+def framed(payload: bytes, purpose: str) -> bytes:
+    require(purpose and '\0' not in purpose,'invalid_signature_purpose')
+    return b'msg.lmm.best/v1/'+purpose.encode('ascii')+b'\0'+payload
+
+
+@dataclass(frozen=True,slots=True)
+class Ed25519Signer:
+    _private: Ed25519PrivateKey=field(repr=False)
+
+    @classmethod
+    def generate(cls):
+        return cls(Ed25519PrivateKey.generate())
+
+    @classmethod
+    def from_bytes(cls,private: bytes):
+        require(len(private)==32,'invalid_private_key')
+        return cls(Ed25519PrivateKey.from_private_bytes(private))
+
+    @property
+    def public_key(self):
+        return self._private.public_key().public_bytes(Encoding.Raw,PublicFormat.Raw)
+
+    @property
+    def key_id(self):
+        return key_id(self.public_key)
+
+    def private_bytes(self):
+        return self._private.private_bytes(Encoding.Raw,PrivateFormat.Raw,NoEncryption())
+
+    def sign(self,payload: bytes, *, purpose: str):
+        return Signature(key_id=self.key_id,algorithm='ed25519',value=self._private.sign(framed(payload,purpose)))
+
+
+def verify(public: bytes,payload: bytes,signature: Signature, *, purpose: str):
+    require(signature.algorithm=='ed25519' and signature.key_id==key_id(public),'invalid_signature')
+    try:
+        Ed25519PublicKey.from_public_bytes(public).verify(signature.value,framed(payload,purpose))
+    except (InvalidSignature,ValueError,TypeError) as exc:
+        raise Failure('invalid_signature') from exc
+
+
+def _pin(pin):
+    require(type(pin) is str and len(pin)>=12 and
+            pin.casefold() not in {'password','passwordpassword','changemechangeme','defaultdefault'} and
+            not (pin.isdecimal() and len(pin)<20),'weak_pin')
+    return pin.encode('utf-8')
+
+
+def seal_private_key(private: bytes,pin: str):
+    password=_pin(pin)
+    signer=Ed25519Signer.from_bytes(private)
+    header={'version':1,'kdf':'scrypt','n':2**17,'r':8,'p':1,
+            'salt':b64(os.urandom(16)),'nonce':b64(os.urandom(12)),
+            'cipher':'aes-256-gcm','public_key':b64(signer.public_key)}
+    derived=Scrypt(salt=unb64(header['salt']),length=32,n=header['n'],r=8,p=1).derive(password)
+    encrypted=AESGCM(derived).encrypt(unb64(header['nonce']),private,canonical(header))
+    return dict(header,ciphertext=b64(encrypted))
+
+
+def open_private_key(envelope: dict,pin: str):
+    required={'version','kdf','n','r','p','salt','nonce','cipher','public_key','ciphertext'}
+    require(set(envelope)==required and envelope['version']==1 and envelope['kdf']=='scrypt' and
+            envelope['cipher']=='aes-256-gcm','invalid_key_envelope')
+    n=envelope['n']
+    require(type(n) is int and 2**17<=n<=2**20 and n&(n-1)==0 and
+            envelope['r']==8 and envelope['p']==1,'invalid_kdf_parameters')
+    header={k:v for k,v in envelope.items() if k!='ciphertext'}
+    salt,nonce=unb64(header['salt']),unb64(header['nonce'])
+    require(len(salt)==16 and len(nonce)==12,'invalid_key_envelope')
+    try:
+        derived=Scrypt(salt=salt,length=32,n=n,r=8,p=1).derive(pin.encode('utf-8'))
+        private=AESGCM(derived).decrypt(nonce,unb64(envelope['ciphertext']),canonical(header))
+        require(b64(Ed25519Signer.from_bytes(private).public_key)==header['public_key'],'invalid_key_envelope')
+        return private
+    except InvalidTag as exc:
+        raise Failure('invalid_pin') from exc

msg/security/custodial_migration.py

@@ -0,0 +1,292 @@
+"""Custodial exit invariants; evidence is scoped, and deletion is not retirement.
+
+The stored challenge binds both new public keys. Every later decision signs a
+fresh inventory and result digest. A recovery envelope is compatibility recovery,
+not a replacement ciphertext. No network claim can attest backup destruction.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from msg.core.codec import canonical, decode, digest, loads, unb64, wire
+from msg.core.errors import Failure, require
+from msg.core.models import ResourceRef, Signature
+from msg.security.crypto import key_id, verify
+from msg.security.age_keys import encryption_key_id, public_from_recipient
+from msg.security.backup_retirement import BackupRetirement, verified as verified_backup
+
+
+class MigrationPhase(StrEnum):
+    CHALLENGE = 'challenge'
+    MIGRATING = 'migrating'
+    IDENTITY_SWITCHED = 'identity_switched'
+    HISTORY_RECOVERABLE = 'history_recoverable'
+    ONLINE_KEY_RETIRED = 'online_key_retired'
+    SERVER_KEY_RETIRED = 'server_key_retired'
+
+
+def ordered(items):
+    return sorted(items, key=lambda item: (item['id'], item['revision']))
+
+
+def inventory_commitment(subject, details, challenge):
+    return digest({'domain': 'msg-custodial-inventory-v1', 'subject_id': subject,
+        'challenge_id': challenge['challenge_id'],
+        'version': details.get('inventory_version', 1),
+        'old_identity_key_id': details['old_identity_key_id'],
+        'new_identity_key_id': details['new_identity_key_id'],
+        'old_encryption_key_id': details['old_encryption_key_id'],
+        'new_encryption_key_id': details['new_encryption_key_id'],
+        'recipient': challenge['encryption_recipient'],
+        'items': details['age_inventory'],
+        'source_keys': details.get('source_keys', {})})
+
+
+def stage_statement(subject, arguments, request_id):
+    """Sign every decision field, not a caller-selected subset of the manifest."""
+    return {'domain': 'msg-custodial-decision-v1', 'subject_id': subject,
+            'request_id': request_id,
+            'decision': {key: value for key, value in arguments.items()
+                         if key != 'migration_ack'}}
+
+
+def ack_statement(subject, challenge_id, inventory_digest, source, target,
+                  plaintext_digest, request_id, *, method='rewrap'):
+    return {'domain': 'msg-custodial-history-ack-v1', 'subject_id': subject,
+            'challenge_id': challenge_id, 'inventory_digest': inventory_digest,
+            'source': source, 'target': target, 'method': method,
+            'plaintext_digest': plaintext_digest, 'request_id': request_id}
+
+
+def keyed_source(item, details):
+    return dict(item, key_id=details.get('source_keys', {}).get(
+        item['revision'], details['old_encryption_key_id']))
+
+
+def keyed_target(mapping, details):
+    return dict(mapping['new'], key_id=details['new_encryption_key_id'],
+                recipient=mapping['recipient'])
+
+
+async def owned_age_inventory(tx, subject):
+    """All retained owned keystore age revisions, not just current revisions."""
+    folder = tx.one("SELECT id FROM resources WHERE parent=? AND name='keystore'", (subject,))
+    if folder is None:
+        return []
+    result = []
+    for rid, revision_id in tx.rows('''SELECT r.id,v.id FROM revisions v
+        JOIN resources r ON r.id=v.resource_id WHERE r.parent=? AND r.owner=?
+        AND r.type='keystore' ORDER BY r.id,v.id''', (folder[0], subject)):
+        if tx.setting('keystore_format:' + revision_id) == 'age':
+            revision = await tx.revision(ResourceRef(id=rid, revision=revision_id))
+            result.append({'id': rid, 'revision': revision_id,
+                           'ciphertext_digest': revision.content.digest})
+    return result
+
+
+def output_refs(details):
+    """Outputs are not new source work; direct new-key writes remain sources."""
+    result = [m['new'] for m in details.get('rewrap_mappings', {}).values()
+              if m.get('copy_kind') != 'new_key_write']
+    envelope = details.get('recovery_envelope')
+    if envelope is not None:
+        result.append(envelope['ciphertext'])
+    return result
+
+
+def retirement_view(details, vault, *, identity_switched, subject_id=None, backup=None,
+                    backup_status='requires_offline_verification'):
+    """An absent online key cannot prove that historical backups lost that key."""
+    signing_deleted = bool(vault and vault[1] is None and vault[2] is None)
+    encryption_deleted = bool(vault and vault[3] is None and vault[4] is None)
+    # Only a locally imported, root-signed record verified by
+    # msg.security.backup_retirement may set this field. The network migration
+    # API never writes or accepts one; details['backup_retirement'] is ignored.
+    retired = isinstance(backup, BackupRetirement) and backup.binds(subject_id, details)
+    online = bool(identity_switched and vault and vault[0] == 'destroyed' and
+                  signing_deleted and encryption_deleted)
+    return {'identity_switched': identity_switched,
+            'token_revoked': identity_switched,
+            'online_signing_key_deleted': signing_deleted,
+            'online_encryption_key_deleted': encryption_deleted,
+            'backup_retired': retired,
+            'backup_status': 'local_attestation_verified' if retired else backup_status,
+            'backup_retirement_record': backup.view() if retired else None,
+            'server_key_retired': retired and online}
+
+
+@dataclass(frozen=True)
+class MigrationSnapshot:
+    data: dict
+
+    @property
+    def inventory_digest(self):
+        return self.data['inventory_digest']
+
+    def unchanged(self):
+        require(not self.data['inventory_changed'], 'custodial_inventory_changed')
+
+    def require_observation(self, arguments):
+        require(arguments.get('inventory_digest') == self.inventory_digest and
+                arguments.get('results_digest') == self.data['results_digest'] and
+                arguments.get('observed_digest') == self.data['observed_digest'],
+                'custodial_migration_preview_stale')
+
+
+async def verify_challenge_binding(tx, subject, status, challenge, details):
+    """Verify the original challenge even when there are no history ACKs.
+
+    The retired signing credential remains a historical verifier, not current
+    authority. A mutable copy of a key ID in the migration body is not a proof.
+    """
+    try:
+        public = unb64(challenge['public_key'], limit=32)
+        old = await tx.credential(details['old_identity_key_id'])
+        require(challenge['subject_id'] == subject and old.subject_id == subject and
+                old.kind == 'signing_key' and key_id(old.verifier) == old.id and
+                key_id(public) == details['new_identity_key_id'] and
+                old.id != details['new_identity_key_id'] and
+                encryption_key_id(public_from_recipient(challenge['encryption_recipient'])) ==
+                    details['new_encryption_key_id'] and
+                details['old_encryption_key_id'] != details['new_encryption_key_id'],
+                'custodial_challenge_invalid')
+        verify(old.verifier, canonical(challenge), decode(Signature, details['server_signature']),
+               purpose='custodial-upgrade-challenge')
+        old_age = tx.one('SELECT subject,recipient,public_key FROM encryption_subkeys WHERE key_id=?',
+                         (details['old_encryption_key_id'],))
+        require(old_age is not None and old_age[0] == subject and
+                encryption_key_id(public_from_recipient(old_age[1])) == details['old_encryption_key_id'] and
+                unb64(old_age[2], limit=32) == public_from_recipient(old_age[1]),
+                'custodial_challenge_invalid')
+    except (Failure, KeyError, TypeError, ValueError) as exc:
+        raise Failure('custodial_challenge_invalid') from exc
+    if status != 'completed':
+        require(old.revoked_at is None, 'custodial_signing_key_retired')
+    retained = tx.one('SELECT status FROM custodial_vault WHERE subject=?', (subject,))
+    if status == 'pending_rewrap' or (status == 'completed' and retained == ('decrypt_only',)):
+        target = tx.one('SELECT subject,recipient,is_primary,retired_at FROM encryption_subkeys '
+                        'WHERE key_id=?', (details['new_encryption_key_id'],))
+        require(target == (subject, challenge['encryption_recipient'], 1, None),
+                'custodial_encryption_target_changed')
+
+
+async def snapshot(tx, subject, status, challenge, details, *, now=None):
+    """Without a trusted clock a backup attestation cannot be current, so it is not used."""
+    await verify_challenge_binding(tx, subject, status, challenge, details)
+    frozen = details.get('age_inventory')
+    require(isinstance(frozen, list), 'custodial_inventory_required')
+    require(frozen == ordered(frozen) and len({i['revision'] for i in frozen}) == len(frozen),
+            'custodial_inventory_corrupt')
+    current = await owned_age_inventory(tx, subject)
+    outputs = output_refs(details)
+    current_sources = [item for item in current if item not in outputs]
+    expected = ordered(frozen + [item for item in outputs if item not in frozen])
+    added = [item for item in current_sources if item not in frozen]
+    missing = [item for item in frozen if item not in current]
+    drift = current != expected
+    commitment = inventory_commitment(subject, details, challenge)
+    mappings = details.get('rewrap_mappings', {})
+    acks = details.get('rewrap_acks', {})
+    recovery_acks = details.get('recovery_acks', {})
+    envelope = details.get('recovery_envelope')
+    sources = {item['revision']: item for item in frozen}
+    require(set(mappings) <= sources.keys() and set(acks) <= sources.keys() and
+            set(recovery_acks) <= sources.keys(), 'custodial_mapping_corrupt')
+    targets = set()
+    verified, legacy_acked, methods = set(), set(), {}
+    for revision, mapping in mappings.items():
+        source = sources[revision]
+        require(mapping['old'] == source and
+                mapping['recipient'] == challenge['encryption_recipient'] and
+                mapping.get('old_key_id', keyed_source(source, details)['key_id']) ==
+                    keyed_source(source, details)['key_id'] and
+                mapping.get('new_key_id', details['new_encryption_key_id']) ==
+                    details['new_encryption_key_id'], 'custodial_mapping_key_mismatch')
+        ref = mapping['new']
+        marker = (ref['id'], ref['revision'])
+        require(marker not in targets, 'custodial_mapping_target_reused')
+        targets.add(marker)
+        if ref not in current or source in missing:
+            continue
+        ack = acks.get(revision)
+        if ack is None:
+            continue
+        require(ack['new_revision'] == ref['revision'] and
+                ack['ciphertext_digest'] == ref['ciphertext_digest'],
+                'custodial_rewrap_mapping_mismatch')
+        legacy_acked.add(revision)
+        if ack.get('inventory_digest') != commitment:
+            continue
+        body = ack_statement(subject, challenge['challenge_id'], commitment,
+            keyed_source(source, details), keyed_target(mapping, details),
+            ack['plaintext_digest'], ack['request_id'])
+        verify(unb64(challenge['public_key']), canonical(body), decode(Signature, ack['signature']),
+               purpose='custodial-history-ack-v1')
+        verified.add(revision)
+        methods[revision] = 'rewrap'
+    if envelope is not None:
+        require(envelope['subject_id'] == subject and
+                envelope['old_key_id'] == details['old_encryption_key_id'] and
+                envelope['new_key_id'] == details['new_encryption_key_id'] and
+                envelope['recipient'] == challenge['encryption_recipient'] and
+                envelope['purpose'] == 'retired-encryption-subkey-recovery',
+                'custodial_recovery_envelope_mismatch')
+        if envelope['ciphertext'] in current:
+            for revision, ack in recovery_acks.items():
+                if sources[revision] in missing or ack.get('inventory_digest') != commitment:
+                    continue
+                require(keyed_source(sources[revision], details)['key_id'] == envelope['old_key_id'],
+                        'custodial_recovery_key_mismatch')
+                body = ack_statement(subject, challenge['challenge_id'], commitment,
+                    keyed_source(sources[revision], details), envelope,
+                    ack['plaintext_digest'], ack['request_id'], method='compatibility_recovery')
+                verify(unb64(challenge['public_key']), canonical(body),
+                       decode(Signature, ack['signature']), purpose='custodial-history-ack-v1')
+                verified.add(revision)
+                methods[revision] = 'compatibility_recovery'
+    policy_row = tx.one('SELECT body FROM recovery_policies WHERE subject=? ORDER BY version DESC LIMIT 1',
+                        (subject,))
+    policy = loads(policy_row[0]) if policy_row else {'version': 0, 'opted_in': False}
+    vault = tx.one('''SELECT status,signing_nonce,signing_ciphertext,age_nonce,age_ciphertext
+        FROM custodial_vault WHERE subject=?''', (subject,))
+    switched = status == 'completed'
+    backup_status, backup = await verified_backup(tx, subject, details, now=now) if switched \
+        else ('unavailable', None)
+    retirement = retirement_view(details, vault, identity_switched=switched, subject_id=subject,
+        backup=backup, backup_status='requires_offline_verification' if backup_status == 'unavailable'
+                                     else 'local_attestation_' + backup_status)
+    complete = not drift and verified == set(sources)
+    phase = MigrationPhase.CHALLENGE if status == 'pending' else MigrationPhase.MIGRATING
+    if switched:
+        phase = MigrationPhase.HISTORY_RECOVERABLE if complete else MigrationPhase.IDENTITY_SWITCHED
+        if retirement['online_signing_key_deleted'] and retirement['online_encryption_key_deleted']:
+            phase = MigrationPhase.ONLINE_KEY_RETIRED
+        if retirement['server_key_retired']:
+            phase = MigrationPhase.SERVER_KEY_RETIRED
+    results = {'mappings': mappings, 'acks': acks, 'recovery_envelope': envelope,
+               'recovery_acks': recovery_acks, 'resolution': details.get('resolution')}
+    return MigrationSnapshot({'challenge_id': challenge['challenge_id'], 'status': status,
+        'phase': str(phase), 'recipient': challenge['encryption_recipient'],
+        'old_key_id': details['old_encryption_key_id'], 'new_key_id': details['new_encryption_key_id'],
+        'frozen': frozen, 'sources': [keyed_source(item, details) for item in frozen],
+        'frozen_digest': digest(frozen), 'inventory_digest': commitment,
+        'inventory_version': details.get('inventory_version', 1),
+        'observed_digest': digest(current), 'results_digest': digest(results),
+        'mappings': mappings, 'acks': acks, 'recovery_envelope': envelope,
+        'recovery_acks': recovery_acks, 'methods': methods,
+        'inventory_changed': drift, 'delta': {'added': added, 'missing': missing},
+        'mapped_count': len(mappings), 'acked_count': len(legacy_acked),
+        'verified_revisions': sorted(verified),
+        'unresolved_revisions': sorted(set(sources) - verified),
+        'known_ciphertexts_migrated': not drift and legacy_acked == set(sources),
+        'history_recoverable': complete,
+        'verification_scope': 'enumerated_and_client_verified_revisions_only',
+        'recovery_policy_version': policy['version'],
+        'recovery_policy_requires_review': bool(policy.get('opted_in')),
+        'external_ciphertexts_migrated_owner_claim': details.get('external_ciphertexts_migrated', False),
+        'external_ciphertexts_verified': False,
+        'historical_revisions_require_migration': not complete,
+        'finalize_ready': complete and not policy.get('opted_in'),
+        'vault_remains_active': bool(vault and vault[0] == 'active'),
+        'retirement': retirement})