msgctl 0.1.0a1__py3-none-any.whl

msg/client_certificates.py

@@ -0,0 +1,98 @@
+"""User CA keys stay on the client; the service verifies published certificates."""
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import timedelta
+from pathlib import Path
+import sys
+from uuid import uuid4
+
+from msg.core.codec import b64,canonical,decode,digest,wire,loads
+from msg.core.errors import require
+from msg.core.models import CertificateRequest,Certificate,Signature,CapabilityGrant,IssuancePolicy
+from msg.security.certificates import csr_body,verify_csr,sign_certificate
+from msg.security.crypto import Ed25519Signer,key_id
+from msg.storage.git import durable_write
+
+
+def local_key(path, *, create=False):
+    path=Path(path)
+    if not path.exists() and create:
+        path.parent.mkdir(mode=0o700,parents=True,exist_ok=True)
+        key=Ed25519Signer.generate()
+        durable_write(path,key.private_bytes(),mode=0o600)
+        return key
+    require(path.is_file() and not path.is_symlink() and path.stat().st_mode&0o077==0,'unsafe_ca_key_permissions')
+    return Ed25519Signer.from_bytes(path.read_bytes())
+
+
+async def request_certificate(client,spec,key_path=None):
+    require(client.state.subject and client.state.signer is not None,'registered_identity_required')
+    require(set(spec)<={'requested_issuer','kind','grants','issuance','requested_ttl_seconds','delegation_depth'},'unknown_csr_field')
+    issuer=spec.get('requested_issuer','u_root')
+    if issuer.startswith('/'):
+        result=client.checked(await client.call('discovery.get',{'id':issuer,'fields':['id']},anonymous=True))
+        issuer=result.data['id']
+    signer=local_key(key_path or client.state.directory/'ca.key',create=True) if spec.get('kind')=='ca' or key_path else client.state.signer
+    csr=CertificateRequest(resource_id='client-pending',applicant=client.state.subject,subject_id=client.state.subject,
+        requested_issuer=issuer,public_key=signer.public_key,kind=spec.get('kind','capability'),
+        grants=tuple(decode(CapabilityGrant,g) for g in spec.get('grants',())),
+        issuance=decode(IssuancePolicy,spec['issuance']) if spec.get('issuance') else None,
+        requested_ttl_seconds=spec.get('requested_ttl_seconds',86400),target_service=client.state.server,
+        delegation_depth=spec.get('delegation_depth',0),authority_sources=(),request_digest='',
+        possession_proof=Signature(key_id=signer.key_id,algorithm='ed25519',value=b''))
+    proof=signer.sign(canonical(csr_body(csr)),purpose='csr')
+    args={k:v for k,v in wire(csr).items() if k in {'requested_issuer','public_key','kind','grants','issuance',
+        'requested_ttl_seconds','delegation_depth'}}
+    args['possession_proof']=wire(proof)
+    journal=client.state.directory/('csr-'+digest(csr_body(csr))[7:39]+'.json')
+    pending=loads(journal.read_bytes()) if journal.exists() else {'request_id':uuid4().hex}
+    durable_write(journal,canonical(pending),mode=0o600)
+    result=await client.call('cert.request',args,request_id=pending['request_id'])
+    if result.status=='ok':
+        durable_write(journal,canonical({**pending,'csr_id':result.data['csr_id'],'request_digest':result.data['request_digest']}),mode=0o600)
+    return result
+
+
+async def issue_certificate(client,csr_id,issuer_certificate_id,key_path, *, expected_digest=None):
+    signer=local_key(key_path)
+    issuer_result=client.checked(await client.call('cert.get',{'id':issuer_certificate_id},anonymous=True))
+    parent=decode(Certificate,issuer_result.data['certificate'])
+    require(parent.kind=='ca' and parent.issuance is not None and parent.key_id==signer.key_id,'not_matching_ca_key')
+    require(parent.subject_id==client.state.subject and parent.subject_id!='u_root','local_only')
+    certificates=(issuer_certificate_id,)
+    result=client.checked(await client.call('cert.get',{'id':csr_id},signer=signer,certificates=certificates))
+    csr=decode(CertificateRequest,result.data['request'])
+    verify_csr(csr)
+    require(csr.requested_issuer==parent.subject_id,'wrong_requested_issuer')
+    # The review binds the exact immutable request, not a mutable title or path.
+    print(canonical({'request':wire(csr),'issuer':issuer_certificate_id}).decode(),file=sys.stderr)
+    if expected_digest is None:
+        require(sys.stdin.isatty(),'approval_digest_required')
+        expected_digest=input('Type the exact CSR digest to approve: ').strip()
+    require(expected_digest==csr.request_digest,'approval_digest_mismatch')
+    if result.data['state']['status']=='issued':
+        return await client.call('cert.get',{'id':result.data['state']['certificate_id']},anonymous=True)
+    require(result.data['state']['status']=='pending','csr_not_pending')
+    journal=client.state.directory/('issued-'+digest((csr_id,issuer_certificate_id))[7:39]+'.json')
+    if journal.exists():
+        pending=loads(journal.read_bytes())
+        require(pending['csr_digest']==csr.request_digest,'approval_digest_mismatch')
+        cert=decode(Certificate,pending['certificate'])
+    else:
+        now=client.clock()
+        require(parent.not_before<=now<parent.expires_at,'issuer_expired')
+        require(csr.requested_ttl_seconds<=parent.issuance.max_cert_ttl_seconds,'certificate_ttl_escalation')
+        cert=Certificate(resource_id='cert_'+uuid4().hex,serial='serial_'+uuid4().hex,subject_id=csr.subject_id,
+            key_id=key_id(csr.public_key),issuer_id=parent.subject_id,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''))
+        cert=sign_certificate(cert,signer)
+        pending={'csr_digest':csr.request_digest,'certificate':wire(cert),'request_id':uuid4().hex}
+        durable_write(journal,canonical(pending),mode=0o600)
+    # Server revalidates issuance scope, operations, revocation, expiry, authority
+    # sources and remaining depth in the committing SQLite transaction.
+    return await client.call('cert.publish',{'csr_id':csr_id,'certificate':wire(cert)},signer=signer,
+        certificates=certificates,request_id=pending['request_id'])

msg/client_content.py

@@ -0,0 +1,43 @@
+"""Client-side immutable Revision signing for structured text patches.
+
+The returned arguments go through the ordinary signed OperationRequest client.
+A Revision signature is separate from both that request and the server receipt.
+The caller must fetch and verify the exact current/base bytes beforehand.
+"""
+from uuid import uuid4
+
+from msg.core.codec import canonical, digest, wire
+from msg.core.errors import require
+from msg.core.models import BlobRef, Revision
+from msg.core.text_patch import apply_patch
+
+
+def signed_patch_arguments(signer, resource, previous, source, patch, *, subject,
+                           created_at, actor=None, change_note=None, revision_id=None,
+                           base_revision=None, base_generation=None, base_source=None):
+    require(previous.resource_id==resource.id and previous.id==resource.revision,
+            'revision_conflict')
+    require(digest(source.encode('utf-8'))==previous.content.digest and
+            len(source.encode('utf-8'))==previous.content.size,'content_digest_mismatch')
+    require(previous.content.media_type in {'text/plain','text/markdown'},'text_patch_required')
+    require(base_revision is None or base_source is not None,'base_content_required')
+    body=apply_patch(source,patch,base_source=base_source)
+    blob=BlobRef(digest=digest(body.encode('utf-8')),size=len(body.encode('utf-8')),
+                 media_type=previous.content.media_type)
+    revision=Revision(format_version=1,id=revision_id or 'v_'+uuid4().hex,
+        resource_id=resource.id,parents=(previous.id,),content=blob,
+        relations=previous.relations,actor=actor or subject,subject=subject,
+        author=previous.author,created_at=created_at,manifest_digest='',
+        change_note=change_note,source_kind='user',source_version=1,source_digest=digest(patch))
+    manifest={key:value for key,value in wire(revision).items()
+              if key not in {'manifest_digest','signature'}}
+    signature=signer.sign(canonical(manifest),purpose='revision')
+    args={'id':resource.id,'base_revision':base_revision or previous.id,
+          'base_generation':resource.generation if base_generation is None else base_generation,
+          'patch':patch,'revision_id':revision.id,'content_created_at':wire(created_at),
+          'content_signature':wire(signature)}
+    if change_note is not None:
+        args['change_note']=change_note
+    if base_revision is not None:
+        args['rebase']=True
+    return args

msg/client_custodial.py

@@ -0,0 +1,206 @@
+"""Local, journaled custodial history recovery. Plaintext never leaves this client."""
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from uuid import uuid4
+
+from msg.client_recovery import _age, _protected_file
+from msg.client_secrets import write_private
+from msg.core.codec import canonical, digest, loads, wire
+from msg.core.errors import Failure, require
+from msg.security.age_keys import encryption_key_id, public_from_recipient, recipient_from_identity
+from msg.security.custodial_migration import ack_statement, stage_statement
+from msg.security.vault import client_upgrade_proof
+from msg.storage.git import durable_write
+
+
+def journal_for(state):
+    for name in ('custodial-upgrade.json', 'custodial-history.json'):
+        path = state.directory / name
+        if path.exists() or path.is_symlink():
+            path = _protected_file(path)
+            require(path.stat().st_size <= 4 * 1024 * 1024, 'custodial_journal_too_large')
+            body = loads(path.read_bytes())
+            challenge = body.get('challenge')
+            require(challenge and challenge['subject_id'] == state.subject and
+                    challenge['public_key'] == body['public_key'] and
+                    body['encryption_recipient'] == state.encryption_recipient and
+                    body.get('server', state.server) == state.server,
+                    'custodial_upgrade_journal_mismatch')
+            require(state.signer is not None and body['public_key'] == wire(state.signer.public_key),
+                    'custodial_upgrade_journal_mismatch')
+            return path, body
+    raise Failure('custodial_upgrade_journal_missing')
+
+
+async def inventory(client):
+    _, journal = journal_for(client.state)
+    return client.checked(await client.call('identity.custodial_upgrade_inventory',
+        {'challenge_id': journal['challenge']['challenge_id']}))
+
+
+async def transition(client, action, *, resolution='verified', loss_revisions=(), reason=None,
+                     external_ciphertexts_migrated=False):
+    from msg.client_upgrade import locked_state
+    from msg.client_tokens import remove_journal
+    client._require_token_secret_transport()
+    with locked_state(client.state):
+        path, journal = journal_for(client.state)
+        challenge = journal['challenge']
+        pending = journal.get('pending_transition')
+        intent = {'action': action, 'resolution': resolution, 'loss_revisions': sorted(loss_revisions),
+                  'reason': reason, 'external_ciphertexts_migrated': external_ciphertexts_migrated}
+        if pending is None:
+            state = (await inventory(client)).data
+            identity = _protected_file(client.state.age_key_path).read_text().strip()
+            require(recipient_from_identity(identity) == state['recipient'], 'encryption_identity_mismatch')
+            args = {'challenge_id': challenge['challenge_id'], 'action': action,
+                'age_proof': client_upgrade_proof(identity, challenge),
+                'external_ciphertexts_migrated': external_ciphertexts_migrated,
+                'inventory_digest': state['inventory_digest'], 'observed_digest': state['observed_digest'],
+                'results_digest': state['results_digest']}
+            if action == 'finalize':
+                args.update(resolution=resolution, loss_revisions=sorted(loss_revisions),
+                            reviewed_policy_version=state['recovery_policy_version'])
+                if reason is not None:
+                    args['reason'] = reason
+            request_id = uuid4().hex
+            args['migration_ack'] = wire(client.state.signer.sign(canonical(
+                stage_statement(client.state.subject, args, request_id)), purpose='custodial-decision-v1'))
+            pending = {'intent': intent, 'arguments': args, 'request_id': request_id}
+            journal['pending_transition'] = pending
+            journal['server'] = client.state.server
+            durable_write(path, canonical(journal), mode=0o600)
+        else:
+            require(pending['intent'] == intent, 'custodial_transition_pending')
+        async def recovered():
+            result = await client.call('identity.custodial_upgrade_result',
+                {'challenge_id': challenge['challenge_id']}, signer=client.state.signer,
+                subject=client.state.subject, certificates=())
+            require(result.status == 'ok' and result.data.get('finalization_request_id') ==
+                    pending['request_id'], 'custodial_transition_recovery_pending')
+            return result
+        try:
+            result = await client.call('identity.custodial_upgrade_finish', pending['arguments'],
+                                       request_id=pending['request_id'], contract_version=2)
+        except Failure as exc:
+            if exc.code != 'transport_uncertain' or action != 'finalize':
+                raise
+            result = await recovered()
+        if result.status == 'error' and action == 'finalize' and result.error.code in {
+                'credential_revoked', 'credential_expired', 'custodial_token_required'}:
+            result = await recovered()
+        if result.status == 'ok':
+            journal.pop('pending_transition', None)
+            if action == 'finalize':
+                client.state.accept_identity(result)
+                journal['status'] = 'completed'
+                journal['completed_result'] = wire(result.data)
+                destination = client.state.directory / 'custodial-history.json'
+                durable_write(destination, canonical(journal), mode=0o600)
+                if path != destination:
+                    remove_journal(path)
+            else:
+                durable_write(path, canonical(journal), mode=0o600)
+        elif result.error.code not in {'internal_error', 'transport_uncertain'}:
+            # A signed refusal proves this decision did not commit. A fresh
+            # observation may be taken; uncertain transport keeps the journal.
+            journal.pop('pending_transition', None)
+            durable_write(path, canonical(journal), mode=0o600)
+        return result
+
+
+async def _ciphertext(client, ref, directory, name):
+    entry = client.checked(await client.call('keystore.get', {'id': ref['id'], 'revision': ref['revision']}))
+    require(entry.data['format'] == 'age' and entry.data['size'] <= 1114112,
+            'age_keystore_entry_required')
+    path = directory / name
+    await client.download(entry.output, path)
+    value = path.read_bytes()
+    require(digest(value) == ref['ciphertext_digest'], 'custodial_rewrap_ciphertext_mismatch')
+    return value
+
+
+async def acknowledge(client, old_revision, *, method='rewrap'):
+    from msg.client_upgrade import locked_state
+    with locked_state(client.state):
+        state = (await inventory(client)).data
+        require(not state['inventory_changed'], 'custodial_inventory_changed')
+        source = next((item for item in state['sources'] if item['revision'] == old_revision), None)
+        require(source is not None, 'custodial_rewrap_not_in_frozen_inventory')
+        identity_path = _protected_file(client.state.age_key_path)
+        require(recipient_from_identity(identity_path.read_text().strip()) == state['recipient'],
+                'custodial_rewrap_recipient_mismatch')
+        with tempfile.TemporaryDirectory(prefix='custodial-history-', dir=client.state.directory) as temp:
+            directory = Path(temp)
+            if method == 'rewrap':
+                mapping = state['mappings'].get(old_revision)
+                require(mapping is not None and mapping['old'] == {k: v for k, v in source.items() if k != 'key_id'},
+                        'custodial_rewrap_mapping_missing')
+                target = dict(mapping['new'], key_id=state['new_key_id'], recipient=state['recipient'])
+                ciphertext = await _ciphertext(client, mapping['new'], directory, 'mapped.age')
+                plaintext = _age('--decrypt', '--identity', str(identity_path), input_data=ciphertext)
+                target_ref = mapping['new']
+            else:
+                require(method == 'compatibility_recovery', 'invalid_recovery_method')
+                target = state['recovery_envelope']
+                require(target is not None and target['subject_id'] == client.state.subject and
+                        target['old_key_id'] == source['key_id'] and target['new_key_id'] == state['new_key_id'] and
+                        target['recipient'] == state['recipient'], 'custodial_recovery_envelope_mismatch')
+                encrypted_key = await _ciphertext(client, target['ciphertext'], directory, 'key.age')
+                raw = _age('--decrypt', '--identity', str(identity_path), input_data=encrypted_key)
+                payload = loads(raw)
+                require(set(payload) == {'format','purpose','subject_id','challenge_id','encryption_key_id',
+                                         'encryption_recipient','age_identity'} and
+                        payload['format'] == 'msg-custodial-retired-key-v1' and
+                        payload['purpose'] == 'retired-encryption-subkey-recovery' and
+                        payload['subject_id'] == client.state.subject and
+                        payload['challenge_id'] == state['challenge_id'] and
+                        payload['encryption_key_id'] == source['key_id'], 'custodial_recovery_envelope_mismatch')
+                old_recipient = recipient_from_identity(payload['age_identity'])
+                require(old_recipient == payload['encryption_recipient'] and
+                        encryption_key_id(public_from_recipient(old_recipient)) == source['key_id'],
+                        'custodial_recovery_key_mismatch')
+                old_path = directory / 'retired.agekey'
+                write_private(old_path, (payload['age_identity'] + '\n').encode('ascii'))
+                ciphertext = await _ciphertext(client, source, directory, 'original.age')
+                plaintext = _age('--decrypt', '--identity', str(old_path), input_data=ciphertext)
+                target_ref = target['ciphertext']
+            request_id = uuid4().hex
+            plaintext_digest = digest(plaintext)
+            signed = ack_statement(client.state.subject, state['challenge_id'], state['inventory_digest'],
+                                   source, target, plaintext_digest, request_id, method=method)
+            signature = client.state.signer.sign(canonical(signed), purpose='custodial-history-ack-v1')
+        return client.checked(await client.call('identity.custodial_rewrap_ack', {
+            'challenge_id': state['challenge_id'], 'old_revision': old_revision,
+            'new_revision': target_ref['revision'], 'ciphertext_digest': target_ref['ciphertext_digest'],
+            'plaintext_digest': plaintext_digest, 'inventory_digest': state['inventory_digest'],
+            'method': method, 'decryption_ack': wire(signature)}, request_id=request_id, contract_version=2))
+
+
+async def migrate(client, *, method='rewrap', limit=100):
+    require(type(limit) is int and 1 <= limit <= 1000, 'invalid_migration_limit')
+    state = (await inventory(client)).data
+    require(not state['inventory_changed'], 'custodial_inventory_changed')
+    if method == 'compatibility_recovery' and state['recovery_envelope'] is None:
+        client.checked(await transition(client, 'recovery_envelope'))
+    outcomes = []
+    for source in state['sources']:
+        revision = source['revision']
+        if revision in state['verified_revisions']:
+            continue
+        if len(outcomes) == limit:
+            break
+        try:
+            chosen = 'rewrap' if source['key_id'] == state['new_key_id'] else method
+            if chosen == 'rewrap' and revision not in state['mappings']:
+                client.checked(await client.call('identity.custodial_rewrap_revision', {
+                    'challenge_id': state['challenge_id'],
+                    'ciphertext_ref': {'id': source['id'], 'revision': revision},
+                    'old_encryption_key_id': state['old_key_id'], 'new_recipient': state['recipient']}))
+            result = await acknowledge(client, revision, method=chosen)
+            outcomes.append({'revision': revision, 'status': result.status, 'method': chosen})
+        except Failure as exc:
+            outcomes.append({'revision': revision, 'status': 'pending', 'error': exc.code})
+    return {'items': outcomes, 'inventory': wire((await inventory(client)).data), 'finalized': False}

msg/client_market.py

@@ -0,0 +1,104 @@
+"""Small CLI adapters over the declared market contracts, never a second API."""
+from collections.abc import Mapping
+from uuid import uuid4
+
+from msg.core.codec import canonical, digest, parse_time, unb64, wire
+from msg.core.errors import require
+
+# Values are (operation, positional argument). JSON is parsed by the CLI's
+# existing bounded JSON/@file/stdin reader. Exact prices remain explicit input.
+COMMANDS = {
+    'money': {
+        'state':('money.state',None), 'banks':('money.banks',None),
+        'balance':('money.balance',None), 'ledger':('money.ledger','json'),
+        'offers':('money.offers',None), 'entitlements':('money.entitlements',None),
+        'transfer':('money.transfer','json'), 'redeem':('money.redeem','json'),
+        'purchase':('money.purchase_get','purchase_id'),
+        'settle':('money.purchase_settle','purchase_id'),
+        'cancel':('money.purchase_cancel','purchase_id'),
+    },
+    'store': {
+        'get':('store.listing_get','id'), 'create':('store.listing_create','json'),
+        'update':('store.listing_update','json'),
+        'deposit':('store.package_deposit','json'), 'package':('store.package_get','id'),
+    },
+    'bounty': {
+        'get':('bounty.get','listing_id'), 'create':('bounty.create','json'),
+        'top-up':('bounty.top_up','json'), 'pause':('bounty.pause','listing_id'),
+        'resume':('bounty.resume','listing_id'), 'close':('bounty.close','listing_id'),
+        'claims':('bounty.claims','listing_id'), 'challenge':('bounty.challenge','listing_id'),
+        'claim':('bounty.claim','json'), 'prove':(None,'listing_id'),
+    },
+    'orders': {
+        'create':('orders.create','json'), 'buy':('orders.buy','json'),
+        'pay':('orders.fund','json'), 'get':('orders.get','order_id'),
+        'list':('orders.list','json'), 'payment':('orders.payment','order_id'),
+        'cancel':('orders.cancel','order_id'), 'contract':('orders.contract','order_id'),
+        'resolve':('orders.dispute_execute','json'), 'dispute':('orders.dispute_open','json'),
+        'case':('orders.dispute_get','case_id'),
+    },
+    'delivery': {
+        'get':('delivery.get','order_id'), 'prepare':('delivery.prepare','order_id'),
+        'accept':('delivery.accept','json'), 'submit':('delivery.submit','json'),
+        'claim':('delivery.claim','json'),
+    },
+}
+
+
+def add_commands(commands):
+    for group, actions in COMMANDS.items():
+        sub = commands.add_parser(group, help='Signed market operations; amounts are exact minor units.').add_subparsers(
+            dest='action', required=True)
+        for action, (operation, field) in actions.items():
+            help_text = ('Sign a current-key PoP challenge and claim; not a human/Sybil check.'
+                         if group=='bounty' and action=='prove' else None)
+            cmd = sub.add_parser(action, help=help_text)
+            if field=='json':
+                cmd.add_argument('payload', nargs='?', default='{}', help='JSON, @file or - for stdin.')
+            elif field:
+                cmd.add_argument('value')
+            cmd.add_argument('--request-id', help='Reuse exactly this ID and input after an uncertain response.')
+            if operation is not None:
+                cmd.add_argument('--contract-version', type=int,
+                    help='Explicit published operation version; never changes the signed input silently.')
+            if group=='store' and action=='update':
+                cmd.add_argument('--generation', type=int, required=True)
+
+
+async def prove_bounty(client, listing_id, request_id=None):
+    require(client.state.signer is not None and client.state.subject is not None, 'signing_identity_required')
+    request_id = request_id or uuid4().hex
+    # Repeat the SAME challenge request after a lost claim response. Never
+    # silently replace the nonce or extend TTL while retaining the claim ID.
+    challenge_id = 'bounty-challenge-' + digest((client.state.subject,listing_id,request_id))[7:39]
+    challenged = await client.call('bounty.challenge',{'listing_id':listing_id},request_id=challenge_id)
+    if challenged.status != 'ok':
+        return challenged
+    payload = challenged.data.get('challenge')
+    fields = {'challenge_id','listing_id','claimant_subject_id','nonce','issued_at','expires_at','verifier_version'}
+    require(isinstance(payload,Mapping) and set(payload)==fields and
+            payload['listing_id']==listing_id and payload['claimant_subject_id']==client.state.subject and
+            payload['verifier_version']==1 and len(unb64(payload['nonce'],limit=32))==24 and
+            0 < (parse_time(payload['expires_at'])-parse_time(payload['issued_at'])).total_seconds() <= 300,
+            'bounty_challenge_mismatch')
+    proof = client.state.signer.sign(canonical(payload),purpose='bounty-pop-v1')
+    return await client.call('bounty.claim',{'challenge_id':payload['challenge_id'],'proof':wire(proof)},
+                             request_id=request_id)
+
+
+async def run_command(client, args, parse_arguments):
+    operation, field = COMMANDS[args.command][args.action]
+    if operation is None:
+        return await prove_bounty(client,args.value,args.request_id)
+    params = parse_arguments(args.payload) if field=='json' else {field:args.value} if field else {}
+    kwargs = {'request_id':args.request_id}
+    version = getattr(args, 'contract_version', None)
+    if version is not None:
+        require(type(version) is int and 1 <= version <= 2**31 - 1, 'invalid_contract_version')
+        kwargs['contract_version'] = version
+    elif operation=='money.redeem':
+        kwargs['contract_version']=2
+    if args.command=='store' and args.action=='update':
+        require(isinstance(params.get('id'),str),'listing_id_required')
+        kwargs['expected']=((params['id'],args.generation),)
+    return await client.call(operation,params,**kwargs)

msg/client_recovery.py

@@ -0,0 +1,186 @@
+"""Local age backup of a self-custody encryption subkey.
+
+The service receives only ciphertext. Decrypting an envelope does not log in to
+an account or grant the custodian any application permission.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from uuid import uuid4
+
+from msg.client_secrets import write_private
+from msg.core.codec import canonical, digest, loads, wire
+from msg.core.errors import Failure, require
+from msg.security.age_keys import (
+    encryption_key_id, public_from_recipient, recipient_from_identity,
+)
+
+
+def _protected_file(path):
+    path=Path(path)
+    require(path.is_file() and not path.is_symlink() and
+            path.stat().st_uid==os.geteuid() and path.stat().st_mode&0o077==0,
+            'unsafe_encryption_key_permissions')
+    return path
+
+
+def _age(*arguments,input_data):
+    executable=shutil.which('age')
+    require(executable is not None,'age_dependency_unavailable')
+    try:
+        result=subprocess.run([executable,*arguments],input=input_data,capture_output=True,
+                              timeout=60,check=False)
+    except (OSError,subprocess.TimeoutExpired) as exc:
+        raise Failure('age_operation_failed') from exc
+    require(result.returncode==0,'age_operation_failed')
+    return result.stdout
+
+
+def create_recovery_envelope(state,recipients):
+    """Return a standard age ciphertext for an independently recoverable key."""
+    require(state.subject is not None and state.encryption_recipient is not None,
+            'self_custody_identity_required')
+    recipients=tuple(recipients)
+    require(1<=len(recipients)<=8 and len(set(recipients))==len(recipients),
+            'invalid_recovery_recipients')
+    for recipient in recipients:
+        public_from_recipient(recipient)
+    require(any(recipient!=state.encryption_recipient for recipient in recipients),
+            'independent_recovery_recipient_required')
+    identity=_protected_file(state.age_key_path).read_text().strip()
+    require(recipient_from_identity(identity)==state.encryption_recipient,
+            'encryption_identity_mismatch')
+    key_id=encryption_key_id(public_from_recipient(state.encryption_recipient))
+    plaintext=canonical({'format':'msg-recovery-envelope-v1','purpose':'encryption-subkey-recovery',
+        'subject_id':state.subject,'encryption_key_id':key_id,
+        'encryption_recipient':state.encryption_recipient,'age_identity':identity})
+    arguments=['--encrypt']
+    for recipient in recipients:
+        arguments.extend(('--recipient',recipient))
+    ciphertext=_age(*arguments,input_data=plaintext)
+    require(ciphertext.startswith(b'age-encryption.org/v1\n'),'invalid_recovery_envelope')
+    return ciphertext,{'subject_id':state.subject,'encryption_key_id':key_id,
+                       'recipient_fingerprints':tuple(encryption_key_id(public_from_recipient(r))
+                                                      for r in recipients),'purpose':'encryption-subkey-recovery'}
+
+
+async def save_recovery_envelope(client,recipients, *, policy_version,name=None):
+    """Store ciphertext and register its owner-declared metadata under an opted-in policy."""
+    ciphertext,metadata=create_recovery_envelope(client.state,recipients)
+    policy=client.checked(await client.call('identity.recovery_policy_get',{})).data
+    require(policy['opted_in'] and policy['version']==policy_version and
+            policy['encryption_key_id']==metadata['encryption_key_id'],
+            'recovery_policy_not_opted_in')
+    by_fingerprint={item['fingerprint']:item for item in policy['recipients']}
+    offered=set(metadata['recipient_fingerprints'])
+    require(offered<=by_fingerprint.keys(),'recovery_recipient_not_in_policy')
+    custodian_refs=sorted({by_fingerprint[fingerprint]['custodian_ref']
+                           for fingerprint in offered
+                           if by_fingerprint[fingerprint].get('custodian_ref') is not None})
+    name=name or 'recovery-'+metadata['encryption_key_id'][:18]
+    with tempfile.TemporaryDirectory(prefix='recovery-',dir=client.state.directory) as folder:
+        path=Path(folder)/'envelope.age'
+        write_private(path,ciphertext)
+        uploaded=client.checked(await client.upload(path,media_type='application/octet-stream'))
+        stored=client.checked(await client.call('keystore.put',{'name':name,'format':'age',
+                                                   'source':wire(uploaded.output)}))
+    registered=client.checked(await client.call('identity.recovery_envelope_register',{
+        'ciphertext_ref':wire(stored.resources[0]),
+        'encryption_key_id':metadata['encryption_key_id'],'policy_version':policy_version,
+        'recipient_fingerprints':sorted(offered),'custodian_refs':custodian_refs,
+        'purpose':'encryption-subkey-recovery'}))
+    return stored,registered,metadata
+
+
+def restore_recovery_envelope(ciphertext,custodian_identity_path,output_path, *,
+                              expected_subject_id,expected_encryption_key_id):
+    """Offline decrypt and validate an envelope, writing the restored key 0600."""
+    require(type(ciphertext) is bytes and ciphertext.startswith(b'age-encryption.org/v1\n'),
+            'invalid_recovery_envelope')
+    custodian=_protected_file(custodian_identity_path)
+    plaintext=_age('--decrypt','--identity',str(custodian),input_data=ciphertext)
+    try:
+        payload=loads(plaintext)
+        require(payload['format']=='msg-recovery-envelope-v1' and
+                payload['purpose']=='encryption-subkey-recovery' and
+                payload['subject_id']==expected_subject_id and
+                payload['encryption_key_id']==expected_encryption_key_id,
+                'recovery_envelope_mismatch')
+        recipient=recipient_from_identity(payload['age_identity'])
+        require(recipient==payload['encryption_recipient'] and
+                encryption_key_id(public_from_recipient(recipient))==expected_encryption_key_id,
+                'recovery_envelope_mismatch')
+    except (KeyError,TypeError) as exc:
+        raise Failure('invalid_recovery_envelope') from exc
+    write_private(output_path,(payload['age_identity']+'\n').encode())
+    return {'subject_id':expected_subject_id,'encryption_key_id':expected_encryption_key_id,
+            'recipient':recipient,'restored_locally':True,'account_authority':'none'}
+
+
+async def rewrap_age_keystore_entry(client,resource_id,old_identity_path, *,
+                                    expected_revision):
+    """Re-encrypt one selected age entry for the current subkey, never scanning a vault."""
+    require(client.state.subject is not None and client.state.signer is not None and
+            client.state.encryption_recipient is not None,'signing_identity_required')
+    old_identity=_protected_file(old_identity_path)
+    old_recipient=recipient_from_identity(old_identity.read_text().strip())
+    recipient=client.state.encryption_recipient
+    require(old_recipient!=recipient,'encryption_key_unchanged')
+    public_from_recipient(recipient)
+    entry=client.checked(await client.call('keystore.get',{
+        'id':resource_id,'revision':expected_revision}))
+    require(entry.data['format']=='age' and entry.data['size']<=1048576,
+            'age_keystore_entry_required')
+    current=client.checked(await client.call('discovery.get',{'id':resource_id,'view':'meta'}))
+    require(current.data['owner']==client.state.subject,'keystore_owner_required')
+    require(current.data['revision']==expected_revision,'revision_conflict')
+    with tempfile.TemporaryDirectory(prefix='rewrap-',dir=client.state.directory) as folder:
+        directory=Path(folder)
+        prior=directory/'prior.age'
+        await client.download(entry.output,prior)
+        plaintext=_age('--decrypt','--identity',str(old_identity),input_data=prior.read_bytes())
+        ciphertext=_age('--encrypt','--recipient',recipient,input_data=plaintext)
+        require(ciphertext.startswith(b'age-encryption.org/v1\n'),'invalid_ciphertext_envelope')
+        renewed=directory/'renewed.age'
+        write_private(renewed,ciphertext)
+        uploaded=client.checked(await client.upload(renewed,media_type='application/octet-stream'))
+        result=client.checked(await client.call('keystore.put',{
+            'id':resource_id,'name':current.data['name'],'format':'age',
+            'source':wire(uploaded.output)},
+            expected=((resource_id,current.data['generation']),)))
+    return result
+
+
+async def verify_custodial_rewrap_entry(client,resource_id,revision,new_identity_path, *,
+                                        expected_recipient,expected_ciphertext_digest):
+    """Owner-side age round trip; the plaintext stays in this process."""
+    identity=_protected_file(new_identity_path)
+    require(recipient_from_identity(identity.read_text().strip())==expected_recipient,
+            'custodial_rewrap_recipient_mismatch')
+    entry=client.checked(await client.call('keystore.get',{
+        'id':resource_id,'revision':revision}))
+    require(entry.data['format']=='age' and entry.data['size']<=1114112,
+            'custodial_rewrap_age_required')
+    with tempfile.TemporaryDirectory(prefix='verify-rewrap-',dir=client.state.directory) as folder:
+        path=Path(folder)/'ciphertext.age'
+        await client.download(entry.output,path)
+        ciphertext=path.read_bytes()
+        require(digest(ciphertext)==expected_ciphertext_digest,
+                'custodial_rewrap_ciphertext_mismatch')
+        plaintext=_age('--decrypt','--identity',str(identity),input_data=ciphertext)
+    return {'id':resource_id,'revision':revision,'recipient':expected_recipient,
+            'ciphertext_digest':expected_ciphertext_digest,'decrypted_locally':True,
+            'plaintext_digest':digest(plaintext),'upgrade_finalized':False}
+
+
+async def ack_custodial_rewrap_entry(client,challenge_id,old_revision,new_identity_path):
+    """Compatibility wrapper for the scoped, locally decrypted ACK workflow."""
+    from msg.client_custodial import acknowledge, journal_for
+    _,journal=journal_for(client.state)
+    require(journal['challenge']['challenge_id']==challenge_id and
+            Path(new_identity_path)==client.state.age_key_path,'custodial_upgrade_journal_mismatch')
+    return await acknowledge(client,old_revision)