msgctl 0.1.0a1__py3-none-any.whl

msg/plugins/transfer.py

@@ -0,0 +1,249 @@
+"""All network adapters expose these same six transfer operations."""
+from __future__ import annotations
+from dataclasses import replace
+from datetime import timedelta
+from types import SimpleNamespace
+
+from msg.core.codec import b64,unb64,wire,decode,canonical,loads,parse_time,digest
+from msg.core.errors import Failure,require
+from msg.core.models import ResourceRef,HandlerOutput
+from msg.core.tags import normalize_tag
+from msg.core.read_query import read_query_version
+from msg.core.transfer import TransferService
+from msg.plugins.common import registration,resolve,create_resource,check_access
+from msg.plugins.schemas import obj,INTEGER,STRING,IDENTIFIER,BYTES,REF
+
+DIGEST={'type':'string','pattern':'^sha256:[0-9a-f]{64}$'}
+SIZE={'type':'integer','minimum':0,'maximum':2**63-1}
+QUERY_MEDIA='application/vnd.msg.read-query+json'
+
+
+async def sealed_read_query(app,ctx,request,tx,transfer):
+    require(transfer.subject_id==ctx.principal.subject,'query_ref_principal_mismatch')
+    require(transfer.state=='sealed' and transfer.direction=='upload' and
+            transfer.output is not None,'query_transfer_not_sealed')
+    require(transfer.expires_at>ctx.now,'query_ref_expired')
+    ref=transfer.output
+    resource=await tx.resource(ref.id)
+    require(resource.type=='file' and resource.owner==ctx.principal.subject and
+            resource.state=='active','invalid_query_ref')
+    await check_access(app,ctx,request,tx,ref.id,'read')
+    revision=await tx.revision(ref)
+    require(revision.content.media_type==QUERY_MEDIA and revision.content.size<=65536 and
+            revision.content.digest==transfer.expected_digest,'query_ref_digest_mismatch')
+    try:
+        descriptor=loads(await app.contents.read_bytes(revision.content,limit=65536))
+    except Failure as exc:
+        raise Failure('invalid_query_ref') from exc
+    require(type(descriptor) is dict and set(descriptor)=={'version','kind','arguments'} and
+            descriptor['version']==1 and descriptor['kind'] in {'read','search'} and
+            type(descriptor['arguments']) is dict,'invalid_query_ref')
+    args=descriptor['arguments']
+    kind=descriptor['kind']
+    require(args.get('parent' if kind=='read' else 'scope') is not None and
+            'cursor' not in args,'invalid_query_ref')
+    operation='discovery.read_query' if kind=='read' else 'discovery.lexical_search'
+    contract_version=(read_query_version(args) if kind=='read' else
+        4 if kind=='search' and 'suggest' in args else
+        3 if kind=='search' and any(name in args for name in
+        ('source_kind','relation_type')) else 2 if kind=='search' and 'facets' in args else 1)
+    try:
+        app.registry.validate(app.registry.operation(operation,contract_version).input_schema,args)
+    except Failure as exc:
+        raise Failure('invalid_query_ref') from exc
+    return ref,revision,kind,args
+
+
+def query_ref_principal(principal):
+    return {'actor':principal.actor,'subject':principal.subject,
+            'credential_id':principal.credential_id}
+
+
+def negotiate(app,request):
+    a=request.arguments
+    limits=app.settings.server.limits
+    request_bytes=min(limits.max_request_bytes,a.get('max_request_bytes',limits.max_request_bytes))
+    response_bytes=min(limits.max_response_bytes,a.get('max_response_bytes',limits.max_response_bytes))
+    path_bytes=min(limits.max_path_bytes,a.get('max_path_bytes',limits.max_path_bytes))
+    # Calculate an envelope with maximal fixed-length IDs/offsets and the caller's
+    # actual proof overhead. Two Base64 layers are needed for data inside a path.
+    packet=wire(request)
+    packet.update(operation='transfer.part_put',request_id='r'*64,payload_digest='sha256:'+'0'*64,
+        arguments={'transfer_id':'tr_'+'0'*32,'offset':2**63-1,'data':'','digest':'sha256:'+'0'*64})
+    overhead=len(canonical(packet))+48
+    path_prefix=len('/-/g/transfer.part_put/j/')
+    path_budget=(path_bytes-path_prefix)*3//4-overhead
+    request_budget=request_bytes-overhead
+    response_budget=response_bytes-1024
+    chosen=min(app.settings.max_part_bytes,a.get('requested_part_bytes',app.settings.max_part_bytes),
+               request_budget*3//4,path_budget*3//4,response_budget*3//4)
+    require(chosen>=1,'transport_limit_too_small')
+    return {'part_bytes':chosen,'max_request_bytes':request_bytes,'max_response_bytes':response_bytes,
+            'max_path_bytes':path_bytes}
+
+
+def install(app):
+    op,finish=registration(app,'transfer',('identity','content'))
+
+    def service():
+        async def publish(ctx,tx,parent,blob):
+            # An internal operation label is not a new or user-supplied principal.
+            operation=SimpleNamespace(operation='transfer.seal',contract_version=1)
+            resource=await create_resource(app,ctx,operation,tx,parent=parent,type='file',body=blob,
+                media_type=blob.media_type,mode=0o600)
+            return ResourceRef(id=resource.id,revision=resource.revision)
+        return TransferService(app.metadata,app.contents,app.authorizer,app.clock,publish=publish,
+                               ttl=app.settings.transfer_ttl,part_bytes=app.settings.max_part_bytes)
+
+    @op('transfer.open',obj({'direction':{'enum':['upload','download']},'target':REF,'size':SIZE,'digest':DIGEST,
+        'media_type':STRING,'requested_part_bytes':{'type':'integer','minimum':1},
+        'max_request_bytes':{'type':'integer','minimum':1},'max_response_bytes':{'type':'integer','minimum':1},
+        'max_path_bytes':{'type':'integer','minimum':1}},('direction',)))
+    async def open_transfer(ctx,request,tx):
+        a=request.arguments
+        target=decode(ResourceRef,a['target']) if 'target' in a else None
+        if target is not None and target.id.startswith('/'):
+            target=replace(target,id=await resolve(tx,target.id))
+        limits=negotiate(app,request)
+        transfer=await service().open(ctx,a['direction'],target,a.get('size'),a.get('digest'),
+            ctx.now+timedelta(seconds=app.settings.transfer_ttl),limits=limits,
+            media_type=a.get('media_type','application/octet-stream'))
+        return HandlerOutput(data={'transfer_id':transfer.id,'direction':transfer.direction,'state':transfer.state,
+            'target':wire(transfer.target),'size':transfer.expected_size,'digest':transfer.expected_digest,
+            'expires_at':wire(transfer.expires_at),**limits})
+
+    @op('transfer.part_put',obj({'transfer_id':IDENTIFIER,'offset':SIZE,'data':BYTES,'digest':DIGEST},
+                                ('transfer_id','offset','data','digest')))
+    async def put(ctx,request,tx):
+        a=request.arguments
+        chunk=await service().put(ctx,a['transfer_id'],a['offset'],unb64(a['data'],limit=app.settings.max_part_bytes),a['digest'])
+        return HandlerOutput(data={'chunk':wire(chunk)})
+
+    @op('transfer.part_get',obj({'transfer_id':IDENTIFIER,'offset':SIZE,'length':SIZE},
+                               ('transfer_id','offset','length')),effect='read')
+    async def get(ctx,request,tx):
+        a=request.arguments
+        chunk,data=await service().get(ctx,a['transfer_id'],(a['offset'],a['offset']+a['length']))
+        return HandlerOutput(data={'chunk':wire(chunk),'data':b64(data)})
+
+    @op('transfer.status',obj({'transfer_id':IDENTIFIER,'cursor':STRING,'limit':{'type':'integer','minimum':1,'maximum':500}},
+                              ('transfer_id',)),effect='read')
+    async def status(ctx,request,tx):
+        a=request.arguments
+        page=await service().status(ctx,a['transfer_id'],a.get('cursor'),a.get('limit',50))
+        transfer=await tx.transfer(a['transfer_id'])
+        output={'transfer_id':transfer.id,'state':transfer.state,'direction':transfer.direction,
+                'generation':transfer.generation,'size':transfer.expected_size,'digest':transfer.expected_digest,
+                'missing':wire(page.items),'next_cursor':page.next_cursor,'output':wire(transfer.output)}
+        if transfer.expected_size is None:
+            after=int(a.get('cursor','0'))
+            rows=tx.rows('SELECT offset,length FROM chunks WHERE transfer_id=? AND offset>=? ORDER BY offset LIMIT ?',
+                        (transfer.id,after,a.get('limit',50)+1))
+            selected=rows[:a.get('limit',50)]
+            output['received']=[[row[0],row[0]+row[1]] for row in selected]
+            output['next_cursor']=str(rows[-1][0]) if len(rows)>len(selected) else None
+        return HandlerOutput(data=output)
+
+    @op('transfer.seal',obj({'transfer_id':IDENTIFIER,'final_size':SIZE,'final_digest':DIGEST},
+                           ('transfer_id','final_size','final_digest')))
+    async def seal(ctx,request,tx):
+        a=request.arguments
+        ref=await service().seal(ctx,a['transfer_id'],a['final_size'],a['final_digest'])
+        return HandlerOutput(resources=(ref,),data={'transfer_id':a['transfer_id'],'state':'sealed',
+                                                  'size':a['final_size'],'digest':a['final_digest']},output=ref)
+
+    @op('transfer.cancel',obj({'transfer_id':IDENTIFIER},('transfer_id',)))
+    async def cancel(ctx,request,tx):
+        await service().cancel(ctx,request.arguments['transfer_id'])
+        return HandlerOutput(data={'transfer_id':request.arguments['transfer_id'],'state':'cancelled'})
+
+    @op('transfer.query_seal',obj({'transfer_id':IDENTIFIER},('transfer_id',)))
+    async def query_seal(ctx,request,tx):
+        transfer=await tx.transfer(request.arguments['transfer_id'])
+        ref,revision,kind,_=await sealed_read_query(app,ctx,request,tx,transfer)
+        expiry=min(transfer.expires_at,ctx.now+timedelta(minutes=15))
+        source=await tx.resource(ref.id)
+        marker_key='query_ref_source:'+ref.id
+        previous=tx.setting(marker_key)
+        retention=max(transfer.expires_at,expiry)+timedelta(hours=1)
+        if previous is not None:
+            retention=max(retention,parse_time(previous['retain_until']))
+        tx.set_setting(marker_key,{'transfer_id':transfer.id,'subject':ctx.principal.subject,
+            'revision':ref.revision,'digest':revision.content.digest,'parent':source.parent,
+            'retain_until':wire(retention)})
+        token=app.cursors.encode('query-ref',
+            {'service':app.settings.service_url,'transfer_id':transfer.id,
+             'output':wire(ref),'digest':revision.content.digest,'query_kind':kind},
+            {'principal':query_ref_principal(ctx.principal),'expires_at':wire(expiry)})
+        return HandlerOutput(data={'query_ref':token,'expires_at':wire(expiry),
+                                   'next':'/_r/q/'+token})
+
+    @op('transfer.query_get',obj({'query_ref':STRING,'cursor':STRING},('query_ref',)),effect='read')
+    async def query_get(ctx,request,tx):
+        token=request.arguments['query_ref']
+        signed=app.cursors.inspect(token)
+        require(signed.get('kind')=='query-ref','invalid_query_ref')
+        query,position=signed['query'],signed['position']
+        require(query.get('service')==app.settings.service_url,'wrong_service')
+        require(position.get('principal')==query_ref_principal(ctx.principal),
+                'query_ref_principal_mismatch')
+        require(ctx.now<parse_time(position['expires_at']),'query_ref_expired')
+        transfer=await tx.transfer(query['transfer_id'])
+        ref,revision,kind,args=await sealed_read_query(app,ctx,request,tx,transfer)
+        require(query.get('output')==wire(ref) and query.get('digest')==revision.content.digest,
+                'query_ref_digest_mismatch')
+        require(query.get('query_kind')==kind,'query_ref_digest_mismatch')
+        operation='discovery.read_query' if kind=='read' else 'discovery.lexical_search'
+        contract_version=(read_query_version(args) if kind=='read' else
+            4 if kind=='search' and 'suggest' in args else
+            3 if kind=='search' and any(name in args for name in
+            ('source_kind','relation_type')) else 2 if kind=='search' and 'facets' in args else 1)
+        principal=query_ref_principal(ctx.principal)
+        normalized=dict(args)
+        if kind=='read' and contract_version==3:
+            normalized['query_version']=3
+        scope_field='parent' if kind=='read' else 'scope'
+        if normalized.get(scope_field):
+            normalized[scope_field]=await resolve(tx,normalized[scope_field])
+        if normalized.get('tag'):
+            normalized['tag']=normalize_tag(normalized['tag'])
+        nested_args=args
+        internal_page=None
+        if request.arguments.get('cursor'):
+            compact=app.cursors.inspect(request.arguments['cursor'])
+            require(compact.get('kind')=='query-ref-page' and
+                    compact.get('query',{}).get('query_ref_digest')==digest(token),
+                    'invalid_cursor')
+            page=compact['position']
+            require(page.get('principal')==principal,'query_ref_principal_mismatch')
+            require(ctx.now<parse_time(page['expires_at']),'cursor_expired')
+            require(page.get('query_digest')==digest(normalized),'cursor_query_mismatch')
+            internal_page={'arguments':normalized,'last':page['last'],
+                           'snapshot':page['snapshot']}
+        # Reuse the installed read handler and its current per-object Authorizer.
+        # Query bytes can select only this registered read operation.
+        nested=SimpleNamespace(operation=operation,contract_version=contract_version,
+                               arguments=nested_args,internal_page_state=internal_page)
+        output=await app.registry.operation(operation,contract_version).handler(ctx,nested,tx)
+        data=dict(output.data)
+        if data.get('cursor'):
+            # This oversized cursor was generated in this call by the trusted
+            # read handler. Never expose it or raise the public 8 KiB limit.
+            encoded=data['cursor'].split('.',1)[0]
+            generated=loads(unb64(encoded,limit=131072))
+            require(generated.get('kind')=='read-page','invalid_cursor')
+            page_query,page=generated['query'],generated['position']
+            require(page_query=={'operation':operation,'arguments':normalized},
+                    'cursor_query_mismatch')
+            expiry=min(parse_time(position['expires_at']),parse_time(page['expires_at']))
+            short=app.cursors.encode('query-ref-page',{'query_ref_digest':digest(token)},
+                {'last':page['last'],'snapshot':page['snapshot'],'principal':principal,
+                 'query_digest':digest(normalized),'expires_at':wire(expiry)})
+            data['cursor']=short
+            if data.get('next'):
+                data.update(next=f'/_r/q/{token}/c/{short}',next_requires_auth=True)
+            if 'pageInfo' in data:
+                data['pageInfo']={**data['pageInfo'],'endCursor':short}
+        return replace(output,data=data)
+
+    finish()

msg/security/age_keys.py

@@ -0,0 +1,112 @@
+"""age X25519 key text encoding. This module does not encrypt age payloads."""
+from __future__ import annotations
+
+import hashlib
+
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey,X25519PublicKey
+
+from msg.core.errors import Failure, require
+
+ALPHABET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l'
+
+
+def _polymod(values):
+    generators=(0x3b6a57b2,0x26508e6d,0x1ea119fa,0x3d4233dd,0x2a1462b3)
+    check=1
+    for value in values:
+        top=check>>25
+        check=((check&0x1ffffff)<<5)^value
+        for index,generator in enumerate(generators):
+            if (top>>index)&1:
+                check^=generator
+    return check
+
+
+def _hrp_expand(hrp):
+    return [ord(char)>>5 for char in hrp]+[0]+[ord(char)&31 for char in hrp]
+
+
+def _convert(data,from_bits,to_bits, *, pad):
+    accumulator=bits=0
+    result=[]
+    maximum=(1<<to_bits)-1
+    for value in data:
+        require(0<=value<(1<<from_bits),'invalid_age_key')
+        accumulator=(accumulator<<from_bits)|value
+        bits+=from_bits
+        while bits>=to_bits:
+            bits-=to_bits
+            result.append((accumulator>>bits)&maximum)
+    if pad and bits:
+        result.append((accumulator<<(to_bits-bits))&maximum)
+    elif not pad:
+        require(bits<from_bits and (accumulator<<(to_bits-bits))&maximum==0,'invalid_age_key')
+    return bytes(result)
+
+
+def _encode(hrp,payload):
+    values=_convert(payload,8,5,pad=True)
+    checksum=_polymod([*_hrp_expand(hrp),*values,0,0,0,0,0,0])^1
+    check=[(checksum>>(5*(5-index)))&31 for index in range(6)]
+    return hrp+'1'+''.join(ALPHABET[value] for value in (*values,*check))
+
+
+def _decode(value,hrp):
+    require(type(value) is str and value.lower()==value and value.startswith(hrp+'1'),
+            'invalid_age_recipient')
+    characters=value[len(hrp)+1:]
+    require(len(characters)==58 and all(char in ALPHABET for char in characters),
+            'invalid_age_recipient')
+    numbers=[ALPHABET.index(char) for char in characters]
+    require(_polymod([*_hrp_expand(hrp),*numbers])==1,'invalid_age_recipient')
+    raw=_convert(numbers[:-6],5,8,pad=False)
+    require(len(raw)==32,'invalid_age_recipient')
+    return raw
+
+
+def recipient_from_public(public: bytes):
+    require(type(public) is bytes and len(public)==32,'invalid_encryption_public_key')
+    return _encode('age',public)
+
+
+def public_from_recipient(recipient: str):
+    public=_decode(recipient,'age')
+    try:
+        # Reject low-order points which cannot produce an X25519 shared secret.
+        X25519PrivateKey.generate().exchange(X25519PublicKey.from_public_bytes(public))
+    except ValueError as exc:
+        raise Failure('invalid_age_recipient') from exc
+    return public
+
+
+def encryption_key_id(public: bytes):
+    require(type(public) is bytes and len(public)==32,'invalid_encryption_public_key')
+    return 'ek_'+hashlib.sha256(b'msg-encryption-subkey-v1\0'+public).hexdigest()
+
+
+def generate_age_key():
+    private=X25519PrivateKey.generate()
+    secret=private.private_bytes_raw()
+    public=private.public_key().public_bytes_raw()
+    # age's X25519 identity is upper-case Bech32; the recipient is lower-case.
+    identity=_encode('age-secret-key-',secret).upper()
+    return identity,recipient_from_public(public)
+
+
+def recipient_from_identity(identity: str):
+    require(type(identity) is str and identity==identity.upper(),'invalid_age_identity')
+    try:
+        private=_decode(identity.lower(),'age-secret-key-')
+        public=X25519PrivateKey.from_private_bytes(private).public_key().public_bytes_raw()
+    except Failure as exc:
+        raise Failure('invalid_age_identity') from exc
+    return recipient_from_public(public)
+
+
+def private_from_identity(identity: str):
+    require(type(identity) is str and identity==identity.upper(),'invalid_age_identity')
+    try:
+        private=X25519PrivateKey.from_private_bytes(_decode(identity.lower(),'age-secret-key-'))
+    except (Failure,ValueError) as exc:
+        raise Failure('invalid_age_identity') from exc
+    return private

msg/security/authentication.py

@@ -0,0 +1,141 @@
+"""Principal construction is a trusted server operation, never request data."""
+from __future__ import annotations
+
+import hashlib
+import hmac
+from dataclasses import replace
+from msg.constants import ROOT_SUBJECT
+from msg.core.codec import digest,unb64,parse_time
+from msg.core.errors import Failure,require
+from msg.core.models import Principal,SignatureProof,TokenProof
+from msg.core.requests import payload_fields,signing_bytes
+from msg.security.crypto import key_id,subject_id,verify
+from msg.security.quarantine import active as quarantine_active
+from msg.security.token_delivery import recovery_verifier
+
+
+CUSTODIAL_SIGNED_WRITES=frozenset({
+    'content.post_create','content.post_edit','content.file_put','content.attach',
+    'discussion.reply','discussion.quote','discussion.repost','identity.token_rotate',
+    'identity.custodial_upgrade_start','identity.custodial_upgrade_finish',
+    'identity.custodial_rewrap_entry','identity.custodial_rewrap_revision',
+    'identity.custodial_rewrap_ack',
+})
+
+
+class AuthenticationService:
+    def __init__(self,registry,certificates,service,clock,primary_ceiling,temporary_ceiling):
+        self.registry,self.certificates,self.service,self.clock=registry,certificates,service,clock
+        self.primary_ceiling,self.temporary_ceiling=primary_ceiling,temporary_ceiling
+
+    async def authenticate(self,request,session, *, entry):
+        require(session.setting('active_root_certificate',self.certificates.root_certificate.resource_id)==
+                self.certificates.root_certificate.resource_id,'service_restart_required')
+        spec=self.registry.operation(request.operation,request.contract_version)
+        if quarantine_active(session):
+            require(spec.effect=='read','writes_paused')
+            raise Failure('recovery_quarantined')
+        require(request.protocol_version==1 and request.target_service==self.service,'wrong_service')
+        require(request.payload_digest==digest(payload_fields(request)),'payload_digest_mismatch')
+        now=self.clock()
+        if spec.effect!='read' or request.proof is not None:
+            require(request.expires_at is not None and now<request.expires_at,'request_expired')
+            require((request.expires_at-now).total_seconds()<=300,'request_expiry_too_long')
+        proof=request.proof
+        if request.operation=='identity.register':
+            require(isinstance(proof,SignatureProof),'proof_required')
+            public=unb64(request.arguments['public_key'],limit=32)
+            require(len(public)==32 and request.subject==subject_id(public),'subject_mismatch')
+            verify(public,signing_bytes(request),proof.signature,purpose='request')
+            return Principal(actor=request.subject,subject=request.subject,credential_id=key_id(public),
+                             method='signature',certificates=(),ceiling=self.primary_ceiling())
+        if request.operation in {'identity.temporary','identity.custodial_create'}:
+            require(proof is None and request.subject is None,'invalid_bootstrap')
+            nonce=unb64(request.arguments['nonce'],limit=64)
+            require(len(nonce)>=24,'invalid_bootstrap_nonce')
+            # The high-entropy claim defines the initial temporary subject; ordinary anonymous
+            # reads cannot create it. The token itself is derived only by the server.
+            prefix='u_cust_' if request.operation=='identity.custodial_create' else 'u_tmp_'
+            subject=prefix+hashlib.sha256(nonce).hexdigest()[:32]
+            return Principal(actor=subject,subject=subject,credential_id='t_'+subject[2:],method='token',
+                             certificates=(),ceiling=self.temporary_ceiling())
+        if request.operation=='identity.token_recover':
+            require(proof is None and request.subject is not None,'invalid_recovery_proof')
+            old=await session.credential(request.arguments['credential_id'])
+            require(old.kind=='token' and old.subject_id==request.subject,'recovery_unavailable')
+            actor=await session.subject(old.subject_id)
+            require(not actor.local_only and actor.resource_id!=ROOT_SUBJECT,'local_only')
+            verifier=recovery_verifier(request.arguments['recovery_secret'])
+            row=session.one('''SELECT recovery_verifier,recovery_expires_at,consumed_at,request_id
+                FROM token_deliveries WHERE credential_id=? AND subject=?''',
+                (old.id,actor.resource_id))
+            require(row is not None and hmac.compare_digest(row[0],verifier) and
+                    parse_time(row[1])>now and row[3]==request.arguments['original_request_id'],
+                    'recovery_unavailable')
+            if row[2] is not None:
+                previous=await session.request_result(actor.resource_id,request.request_id,request.payload_digest)
+                require(previous is not None and previous.data.get('previous_credential')==old.id,
+                        'recovery_unavailable')
+            else:
+                require(old.revoked_at is None and old.expires_at>now,'recovery_unavailable')
+            operation='identity.token_recover@1'
+            ceiling=tuple(replace(g,operations=frozenset({operation})) for g in self.primary_ceiling()
+                          if g.capability=='identity.basic' and operation in g.operations)
+            require(bool(ceiling),'recovery_unavailable')
+            return Principal(actor=actor.resource_id,subject=actor.resource_id,
+                             credential_id=old.id,method='recovery',certificates=(),ceiling=ceiling)
+        if proof is None:
+            require(request.subject is None and spec.effect=='read','authentication_required')
+            return Principal(actor=None,subject=None,credential_id=None,method='anonymous',certificates=(),ceiling=())
+        credential_id=proof.signature.key_id if isinstance(proof,SignatureProof) else proof.credential_id
+        credential=await session.credential(credential_id)
+        actor=await session.subject(credential.subject_id)
+        require(credential.not_before<=now and (credential.expires_at is None or now<credential.expires_at),
+                'credential_expired')
+        if isinstance(proof,SignatureProof):
+            require(credential.kind=='signing_key','wrong_credential_kind')
+            verify(credential.verifier,signing_bytes(request),proof.signature,purpose='request')
+            method='signature'
+            ids=proof.certificates
+        elif isinstance(proof,TokenProof):
+            require(credential.kind=='token','wrong_credential_kind')
+            require(hmac.compare_digest(credential.verifier,hashlib.sha256(proof.token).digest()),'invalid_token')
+            method='token'
+            ids=()
+        else:
+            raise Failure('invalid_proof')
+        if credential.revoked_at is not None:
+            # A token invalidated by its own successful rotation may only retrieve
+            # that exact committed rotation result. It cannot authorize new work.
+            previous=None
+            if method=='token' and request.operation in {
+                    'identity.token_rotate','identity.custodial_upgrade_finish'}:
+                previous=await session.request_result(actor.resource_id,request.request_id,request.payload_digest)
+            require(previous is not None and previous.data.get('previous_credential')==credential.id,
+                    'credential_revoked')
+            successor=await session.credential(previous.data['credential_id'])
+            require(successor.subject_id==actor.resource_id and successor.revoked_at is None and
+                    (successor.expires_at is None or successor.expires_at>now),'credential_revoked')
+        subject=await session.subject(request.subject or actor.resource_id)
+        require(not (actor.local_only or subject.local_only or actor.resource_id==ROOT_SUBJECT or
+                     subject.resource_id==ROOT_SUBJECT) or entry=='local_admin','local_only')
+        require(entry in spec.entries,'entry_not_allowed')
+        operation=f'{spec.name}@{spec.version}'
+        require(any(operation in g.operations for g in credential.ceiling),'credential_ceiling')
+        if actor.kind=='custodial' and method=='token' and spec.effect!='read':
+            download_only=(spec.name=='transfer.open' and
+                           request.arguments.get('direction')=='download')
+            require(spec.name in CUSTODIAL_SIGNED_WRITES or download_only,
+                    'custodial_operation_not_supported')
+        require(not spec.require_signature or method=='signature','signature_required')
+        valid=[]
+        for cid in ids:
+            cert=await self.certificates.validate(cid,session)
+            require(cert.subject_id==actor.resource_id and cert.key_id==credential.id,'certificate_subject_mismatch')
+            valid.append(cert)
+        if actor.resource_id!=subject.resource_id:
+            require(any(c.kind=='delegation' and any(
+                (session.setting('delegation:'+s.id) or {}).get('grantor')==subject.resource_id
+                for s in c.authority_sources) for c in valid),'delegation_required')
+        return Principal(actor=actor.resource_id,subject=subject.resource_id,credential_id=credential.id,
+                         method=method,certificates=tuple(c.resource_id for c in valid),ceiling=credential.ceiling)