Re: [Txauth] Polymorphism (Was: JSON Schema?)

[Dick Hardt <[e-mail]>]

On Thu, Jul 9, 2020 at 5:46 PM Justin Richer <[e-mail]> wrote:

>
>
> On Jul 9, 2020, at 6:50 PM, Dick Hardt <[e-mail]> wrote:
>
>
>
> On Thu, Jul 9, 2020 at 12:17 PM Justin Richer <[e-mail]> wrote:
>
>> On Jul 9, 2020, at 2:32 PM, Dick Hardt <[e-mail]> wrote:
>>
>>
>> Looks like you missed the point of my code example, as your response is
>> focussed on the aspects I had in comments, so let me clarify.
>>
>>
>> The point seemed to be about the overall complexity and readability, and
>> that’s what I responded to.
>>
>
> It was about the complexity and readability -- of those specific lines of
> code.
>
>
> But it’s not just about those lines, it’s about the context that those
> lines are in and the follow-on code paths that they cause. A lot of what
> you had “in comments” for the XAuth example would have repeated what was
> already included in the XYZ example, as I pointed out.
>

The context between those lines is pretty much the same. Yes, the XAuth
example would have had to loop over each scope and RAR object, which is not
that different than XYZ looping over each item, and the deciding how to
process each item. My point is that checking the object type to decide what
to do is an opaque decision vs checking an explicit type.


>
>
> I've used JS type polymorphism to provide a cleaner API. For example,
> making an HTTP request. If I'm good with all the defaults, I can just
> provide the URI as a string, if I want to change a default, I provide an
> object and the URI is now a property of the object. Polymorphism allows the
> caller to have a simpler interface when it is a simple operation.
>
> Do you have any examples of JSON polymorphism used in other protocols
> besides in a JWT?
>
>
> Sounds to me like you’re describing exactly the kind of polymorphism that
> I’m talking about here. Use a string where it makes sense and an object
> where it makes sense, and there’s no ambiguity in calling the function. As
> you say, it's all about providing a cleaner API for the caller, and making
> things consistent in the model that the caller and provider are using. It
> takes a little bit of extra effort on the part of the API provider, but
> that’s where the complexity cost should be paid.
>

My examples are not the same at all. The caller has a simpler version of
passing the same object. XYZ is passing two different types, where a string
means one thing, and an object means something else. The string is not a
shorthand for the object.

In polymorphic APIs, it makes the code cleaner to pass a singular item when
the API takes an array, or the API takes a string for the common property
of the object which is the parameter. Here are some code examples for both:


// passing a singular item, a simpler version of foo(['string'])
foo('string')
// passing a plurality of the same item
foo(['string1','string2','string3'])

// implementation

foo = ( param ) => {
    var a = []
    if (typeof param === 'string') {
        a[0] = param;
    } else if (typeof param === 'array') {
        a = param;
    }
    // process array a
}


// pass a uri as string and accept all defaults, a simpler version of
bar({uri:'uri'})
bar('uri')
// pass an object with uri and method
bar({uri: 'uri', method: 'POST'})

// implementation
bar = ( param ) => {
    var p = DEFAULT_OBJ;
    if (typeof param === 'string') {
        p.uri = param;
    } else if (typeof param === 'object') {
        Object.keys(param).forEach( item => {
            p[item] = param[item];
        });
    }
    // process p object
}


In GNAP, we could take a string rather than an array for a scope parameter,
for example:

"scope": "read"


instead of

"scope": ["read"]


OIDC uses the latter polymorphism for

{
  "name": {"essential": true},
  "photo": null
}

as being shorthand for

{
  "name": {"essential": true},
  "photo": {"essential": false}
}



>
>
>
>>
>>
>> This line (which is determining the type of the item in the array):
>>
>> if (typeof item === string')
>>
>>
>> is implicitly stating that the item is an oauth scope.
>>
>>
>> No, it is not. It is saying that it is a resource request represented as
>> a string. One way to represent a resource request as a string is an OAuth 2
>> style scope. And if you’re building up from an existing OAuth 2 system,
>> then you could use a scope there. But that’s not the same as stating “the
>> item is a scope”. In my examples, I had been trying to use the terminology
>> that you were using, but I’m afraid that made things more unclear.
>>
>
> We are comparing how to do it in XYZ vs XAuth -- so to make it apples and
> apples, the string is a scope, since that is the use case we are looking at.
>
>
> You can use a scope as the string, and if you want to think of all string
> values in this request as all being “scopes", that’s fine, but only if you
> can concede that the scope can mean whatever the AS wants. I think that
> perhaps you’re putting a certain amount of semantic weight to “scope” that
> I’m missing, though.
>

The string could be a scope, or it could be a claim such as in my "oidc"
type example. The AS could support both scope and claims, and they could
have overlapping string values.



>
>
>
>>
>> Whereas it is explicit in this statement
>>
>> if (authorizations.type === 'oauth_scope')
>>
>>
>> which I think it easier to understand what is happening (in my opinion of
>> course).
>>
>> XYZ has types, they are just implicit. RAR has explicit types, and that
>> does not look to be holding back RAR. I don't understand why you think
>> having explicit types will hold us back.
>>
>>
>> The “type” in RAR is a name spacing device to allow extensibility in
>> different aspects of the request. This is at a lower layer than how they’re
>> being applied here, and it therefore makes more sense at that layer. It’s a
>> way for a particular API to define the dimensions that it cares about in
>> its request. It’s not really an even comparison.
>>
>
> And the type in XAuth authorizations is different schemas for making a
> request. "oauth_scope", "oauth_rar", and now "oidc". I would expect that
> there may be more in the future, and we have a clear way of adding schemas,
> and for the client and AS to know they are talking the same "language".
>
>
> And I’m saying that additional “schemas” for requesting information should
> be defined separately from the GNAP schema. We disagree on this topic and
> we’re repeating ourselves.
>

The charter is pretty clear that GNAP should not define schemas, so I don't
know what you mean by the "the GNAP schema"


>
>
>
>>
>> Do you want to let the string and object be anything the AS and RS decide
>> they could mean?
>>
>>
>> Yes. Just like the AS can decide that an OAuth scope could mean any
>> number of things.
>>
>
> That was what I was afraid of. While an OAuth scope could mean whatever
> the AS decides it wants to be, the Client and AS know it is an OAuth scope.
>
>
> How is that any different? I’m confused as to why you think it’s important
> to call this item a “scope” so that you “know what it is”, but then you’re
> OK with “scope” meaning literally anything.
>

A scope string is one of a set of strings defined by the AS.

The AS may use strings to define a different schema, such as which claims
to return from a userinfo endpoint.

 I'm going to separate the my other responses into separate threads as they
are different topics.

/Dick

>
> ᐧ