Draft: draft-ietf-gnap-core-protocol

Commentary: for This is still in progress pending the discussion on the polymorphism issue described in the thread . 
 Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-164 - -gnap - core - protocol - editors- 
 Alright , I found a few more places that needed updating too , and updated this with the rest of the stuff on the branch . 
 Since we now have worked a solution for standard interactions ( which is nice when end - user = RO ) , we could now review if more advanced scenarii make sense . There 's another case which is not complex , you do n't even need an interaction ( then end - user ! = RO but RO is a rule engine from an organisation ) . But I see at least 2 more advanced cases : message interactions . Would be most useful when end - user ! = RO ( and we suppose the RO is also a natural person here ) . multi - step interactions . Messaging patterns could enable sequential or parallel flow of communications , therefore enabling multi - step if you can have a proper way to declare the interaction completed ( although how that would work is not clear ) . -Use case 1 : on first use , a message ( signed by the AS ) is sent from the client , on behalf of the end - user ( for instance a doctor ) to a recipient ( the RO , for instance a patient ) . The patient could choose to allow a one - time access or more durable access ( probably limited to a maximum time ) , in which case we fallback on the no interaction case seen above for similar follow - up requests . -potential start methods : DIDComm , DIDComm query , RCS messaging , email , etc . ( probably need to limit to secure channels though ... ) . Note that DIDComm was already discussed as a possibility in ( interaction section ) . The details of how that communication would work is not straightforward . Probably the end - user and the AS would have to know the RO ( e.g. DIDComm to address , telephone number in case of RCS messaging , etc . ) , how does this happen ? How do you handle trust on first use ? ( a problem unresolved for DIDComm , but PAKE or similar could be useful ) How do you avoid spoofing ROs with unwanted requests ? Supposing the recipient answers , how do you establish a duplex request - response for the consent request ? ( probably you 'd need a specific DIDComm type ) . The risk of unrecoverable error / panic ( example : RO unreachable ) is much more likely than in the usual redirect 
 This relates to a major privacy discussion in the closing days of the DID Core spec It 's desirable to avoid fingerprinting and traffic analysis by keeping the entropy of a DID and DID Document as high as possible . This means limiting the content of the DID Document to only those elements that involve control . Ideally , a DID would control only one service endpoint . Should that service endpoint be a messaging ( inbox ) or an authorization server ? In an AS first world , inbox access would look like any other request for authorization . Note also that there are many reasons for a resource server to want to message the RO . This happens when the RS gets a valid access authorization but an exception occurs such as a jurisdictional issue or a decision that the client is untrusted for some reason . In US healthcare law , for example , the RS MAY ask the client for a signed software statement and if the client certificate does not provide an adequate root of trust then the RS MUST notify the RO ( a " black box warning " ) and allow the RO to override the client trust issue . This , in effect , looks like a messaging channel between the RS and the RO that can be mediated by the AS . 
 -Target for an extension ( + need to check how to best define extension points ) 
 See also 
 The general principle is layed out in section 4 , but without any specific details . DIDComm itself could be an extension , but there 's been no request for it , so closing . 
 The current interaction modes listed are : , , , , and . There are three different types of flags here : how the client can tell the user how to interact with the AS ( , , ) how the client can handle a response from the AS ( ) hints to the AS ( ) We should consider whether it makes sense to group these so that future extensions do n’t run the risk of conflicts and so that the purpose of each is clearer to developers . For example ( names TBD ): ( See PR ) 
 +1 This brings clarity . 
 I like this approach , and it 's largely equivalent to what we have right now ( but with more clarity ) . I think it could even be combined with the bundling concept in if we wanted to . 
 Polymorphism question ... are we going for the style where if an array has only one value it 's also okay to send that one value itself ? e.g. can also be represented by It 's less important for string values , but forcing everything into an array starts to look awkward when values are objects : vs 
 I made an initial attempt at this in PR , however depending on the polymorphism question above I 'll need to clean it up still . 
 My personal view is that the polymorphism should always be clearly unambiguous for every field . In other words , if it 's an object it always means the same thing , an array always means the same thing , etc . If this means that a field is either an object or an array of those objects , then we could support that . However , I 'd argue that we should n't have this kind of optimization when there 's no semantic difference . That is to say , when there 's an array of one object it should still always been an array unless we have a compelling reason to define both formats . For access tokens , it 's semantically different to ask for a single vs. multiple access tokens , so they use this object vs. array - of - object structure mentioned here . But what 's proposed here looks like a simple optimization . While I personally think that 's sensible to do , I think we can and should address that optimization separately . This is the approach I took with . 
 I guess this question is actually slightly more complex than whether this is a simple optimization of a single - value array . Where it gets tricky is when we want to use multiple of these modes combined . Combining string values is easy : Combining objects can be done in two ways : It 's a difference of " object with keys " vs " array of objects " I guess . The downside of the " object with keys " approach is then simple string values are n't really possible without doing the awkward boolean true thing , whereas an " array of objects " could also just as easily be an " array of objects and strings " . This is mostly a stylistic question at this point , but I do think we should write up some guidance around this so that we have something to reference when we have these questions in the future . 
 Good questions on polymorphism . That 's pretty similar to what Justin suggested , I would start with the syntax that we think is most consistent and then see if compact alternatives make sense . But I liked lisp . So I may not be acting normally :-)  aside I think it 's hard to tell for sure right now . 
 I do n't think it makes sense to have multiple modes for " finish " . How would the AS know which one(s ) to fire ? 
 That 's an interesting point that I had n't seen mentioned before . I was thinking of the exchange as the client saying " here are all the things I can do " and the AS picking the ones of the list that it supports . So in some cases one AS may not support some completion modes that another AS does , where a client can support all . 
 The model I 'm in favor of is the client instance providing multiple ways to get started and one way to get back . Letting the AS pick the return leaves the client in charge of listening to different callbacks , which are going to have different security properties . This seems like it 's going to open the door to new and fun attack vectors -- like convincing a client to go poll by posting to a static URL when it should be getting a bound callback parameter on a dynamic URL . This is a very different situation than the AS listening for multiple interaction points , though -- the AS is in more control and the security stakes are known to be high , so it should be more aware of the process . If the client has multiple ways to get back , the AS would likely want to offer different experiences for each , based on those expectations . This is where the multiple - mode bundling idea of comes into play , in which case we 'd look at having the upper - level " interact " structure possibly be multiple , in that case . 
 I also think a single finish is best . The only case I 'd imagine several possibilities is if the client can specify the rules to help decide , but it 's probably over complex ( I do n't see a practical example of where that would be useful ) . So aligned with previous comment . One additional ( maybe unrelated ) question is whether the continuation could allow to chain successive interactions or whether everything is supposed to be handled in one go . Successive interaction could be useful if you 'd want to implement a process with several successive URIs . Maybe that 's dumb but I had the demand from a customer just yesterday ( did n't think much about it yet ) . 
 Okay , if a single finish is the plan we should make sure these motivations are clarified in the spec too ! With the current syntax ( before this PR ) it 's possible for the syntax to allow multiple finish options . With the new syntax we can at least enforce a single finish option . 
 Apologies for any newbie mistakes , but this makes me wonder how we handle the response to an authorization request . In many real - world cases , especially healthcare , the authorization is requested by a client as user agent of the RQ but the response is presented to the RS by another client such as the institutional system of the RQ 's employer that may be under the control of another RQ or an institution . This delegation of the authorization from one client to another may be out of scope for GNAP but I am worried about how the RS will handle this distinction in cases where they want to minimize their risk . 
 So I 'm wondering if we should make " finish " just be the internal structure of what 's in " callback " today : This would keep the " one way to finish " aspect , but would n't rule out someone defining some sort of hybrid finish if something like that would exist . 
 Actually that solves as well by dropping the name " callback " entirely . I think this is a good plan . I 'll update the PR . 
 Actually this has some pretty significant implications elsewhere in the spec . Right now there 's a lot of references to the " callback " mode , e.g. Dropping that from the object means we do n't really have a way to refer to the " callback " mode anymore . I think I 'm okay with this , since we can still refer to the " redirect " or " push " modes defined in the spec . e.g : changes to If we agree I 'll keep going with the changes here . 
 A more significant change is the response from the AS , in does n't make sense anymore , so probably that would have to change to : and I do like that it 's removing one layer of abstraction though and being more direct . 
 Those are still separate " interaction finish methods " that would need to be defined separately , and so I think it should be fine to swap the references in - place . I think the return for this could now actually be something like : Or we could keep it collapsed , swapping for like with the request : I 'm not convinced having different member names for different finish methods at the top level of the object is a good idea , from a namespace cleanliness perspective -- extensions are going to be able to define both start and finish methods , and they 'll need to somehow live in the response together . Maybe like with the discussion above we just keep the " verbose " form and figure out if an optimization makes sense later ? I could go either way , personally . 
 in your use case , the end - user and resource owner are separate , so the client is n't handling the " start " of the interaction process . The client can still be notified of when it 's finished in a secure fashion , which is what the " pushback " method is good for . Or the client can just poll , waiting for it to be approved by someone , so it would n't need to know externally when the authorization is completed . 
 Okay that makes sense . I do n't think the client benefits from having the method confirmed in the response so I 'll start with the simpler version that 's more inline with the current one anyway : 
 Alright , that was quite a bit of surgery but I do think this cleans things up nicely now ! Current draft can be viewed here : https://deploy - preview-164 - -gnap - core - protocol - editors- 
 I 'm playing catch - up here so please bear with me . Yes , the end - user and resource owner are separate . In this use - case the resource owner 's client is irrelevant because they have delegated authority to respond to requests to an authorization server . In this use - case the end user is using two different clients as part of the interaction process . One client is a true user agent , the other client is an agent of some other entity . The client that interacts with the authorization server is logically and maybe legally separate from the client that interacts with the resource server . Optionally , the end - user that began the interaction with the authorization server may delegate their authorization to another end - user that will actually access the resource with a different client . Finally , in this use - case , the resource server may seek signed software statements from the client presenting the authorization . Those software statements may or may not also be shared with the authorization server as part of the interaction . I do n't understand your response about client polling because I am not concerned about that . If this use - case is already handled in the spec , please point me to the relevant sections . 
 Justin might correct if I 'm wrong , but seems to me that this use case is currently not covered . As far as I understand it however , it would be possible I think through biscuit tokens ( + ) , but the delegation between clients is not covered through the protocol . 
 I do n't expect the delegation between clients to be covered through protocol , just possible . The issue of delegation among end - users has been a hot topic in credential and storage W3C workgroups . Here , for example is with over 100 messages . There are many others and the issue is far from resolved . My goal is harmony between W3C data models and GNAP . I 've created a very concise model for that may be helpful here as well . The use - case we 're discussing here is on . In due course , we may choose to consider harmony on the other use cases as well , such as authentication . I know precious little cryptography . If we used biscuits , would GNAP adopt them for everything or would the option be a request on the part of the requesting party ? 
 will look into your docs . GNAP is agnostic on the token format , of course the default being jwt . Biscuits are indeed based on fancy crypto 
 Is there a chance that the interaction could panic / fail with an unrecoverable error that requires to stop the flow ? For instance : reach a timeout ( the RO just went for a walk ) the client developer made a mistake in the start section , his device is unable to redirect to a proper display 
 Regarding the wording : we currently use " completed interaction " in the text . Maybe people could wonder if that 's the same as " finish " ? 
 I believe your concerns would be better managed in dedicated issues . I 've looked at your use case ( thanks for the slides , that 's clear ) . In my view , the delegation that you 're describing with different clients should be managed through tokens that are able to manage that complexity , such as biscuits . See I 've also created a new issue for the distinct case when end - user ! = RO , see Please feel free to comment on those issues directly . 
 See PR 
 PR has been merged 
 Looks good to me . Put in one wording suggestion , but not critical .
Paragraph (version B):
When the AS is done interacting with the user, the AS interaction-
callback to the client instance using the redirect URL provided in
(2).  The redirect URL is augmented with an interaction reference
that the AS associates with the ongoing request created in (2) and
referenced in (4).  The redirect URL is also augmented with a hash
of the security information provided in (2) and (3).  The client
instance loads the verification information from (2) and (3) from
the session created in (1).  The client instance interaction-hash
based on this information and continues only if the hash
validates.  Note that the client instance needs to ensure that the
parameters for the incoming request match those that it is
expecting from the session created in (1).  The client instance
also needs to be prepared for the end-user never being returned to
the client instance and handle time outs appropriately.