PRC-1: UserInfo Request Topic

[danscan]

2024-02-06 Update

This proposal has been updated to rename the topic to xyz.genesis.oidc.userinfo to reflect the convention that has emerged where the only request topics related to features of the Passes protocol, such as org.passes.provide-pass, org.passes.provide-topics, org.passes.request-batch, and org.passes.request-with-default-provider use the org.passes.* namespace.

Application-related request topics will instead use the namespace of the application that proposes them. For example, because Genesis (https://genesis.xyz) is proposing this request, it belongs in the xyz.genesis.* namespace.

This change helps standards to evolve without central coordination around Passes.org or this discussions site, enabling things to progress more easily and quickly.

This discussion will now be closed.

---

Simple Summary

A Pass Request Topic for requesting user info.

Abstract

This is a standards proposal for a Pass Request Topic that allows apps to request user information. It proposes requesting a set of OpenID Connect (OIDC) Standard Claims via JSON ClaimKey[], and receiving a JSON Record<ClaimKey, Value> as a result.

The proposed topic xyz.genesis.oidc.userinfo gets its name from the OIDC Spec's UserInfo Request.

Motivation

A standard pass request topic for user info allows apps to request a known set of user information from pass providers.

Specification

• Topic ID: xyz.genesis.oidc.userinfo
• Request Body Codec: JSON
• Result Body Codec: JSON

type Topic = 'xyz.genesis.oidc.userinfo';

type RequestBody = ClaimKey[];

type ResultBody<TRequestBody extends RequestBody> = {
  [K in keyof TRequestBody]: StandardClaims[TRequestBody[K]] | undefined;
};

type ClaimKey = keyof StandardClaims;

// https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
type StandardClaims = {
  sub: string;
  name: string;
  given_name: string;
  family_name: string;
  middle_name: string;
  nickname: string;
  preferred_username: string;
  profile: string;
  picture: string;
  website: string;
  email: string;
  email_verified: boolean;
  gender: string;
  birthdate: string;
  zoneinfo: string;
  locale: string;
  phone_number: string;
  phone_number_verified: boolean;
  address: JSON;
  updated_at: number;
};

Examples

const userinfoTopic = new RequestTopic({
  id: 'xyz.genesis.oidc.userinfo',
  requestBodyCodec: Codecs.Json,
  resultBodyCodec: Codecs.Json,
});

const result = await userInfoTopic.sendRequest([
  'email',
  'name',
  'picture',
]);
// {
//    status: 'accepted',
//    body: {
//      email: '[email protected]',
//      name: 'John Appleseed',
//      picture: 'https://i.pravatar.cc/300'
//    }
// }

Open Questions

• SignedRequestTopic? Should the standard include whether this is a signed request topic, or should apps be free to request a signature-wrapped version of this request topic at will?
• Topic? Is the topic ID org.passes.userinfo appropriate? Should it instead be something like org.passes.prc-1 or net.openid.userinfo?

[xaelophone]

This looks great, and I appreciate that it draws from the work of existing standards like OpenID Connect as inspiration.

On the open questions:

1. SignedRequestType? – I think there are a few guiding questions that we can ask ourselves. First, are there common use cases where developers would prefer to request data that isn't signed? Second, I'd ask if an abstracted, generalied signature wrapper for any type actually has any use cases. If not, I'd argue it's likely added complexity for something that should simply be integrated to request types.
2. Topic I think org.passes.userinfo is appropriate. It's probably easier to discuss topics with natural language than trying to discuss arbitrary numbers sequences for multiple request types like PRC-X, PRC-Y, etc.

[danscan]

SignedRequestType? – I think there are a few guiding questions that we can ask ourselves. First, are there common use cases where developers would prefer to request data that isn't signed? Second, I'd ask if an abstracted, generalied signature wrapper for any type actually has any use cases. If not, I'd argue it's likely added complexity for something that should simply be integrated to request types.

For now, the advantages of unsigned request types are:

1. It's simpler to deal with unsigned request types in development because you don't need to implement result signature verification.
2. It's faster for the end user to complete because they don't need to sign.

There are also some request types where wrapping their results in a signature would be redundant, e.g. org.ethereum.json-rpc-request. If you send a tx or sign a message, the result already contains the result of a signature (tx hash; signed message, etc). Taking that tx hash or signed message and then signing it again may not be useful in most cases.

Topic I think org.passes.userinfo is appropriate. It's probably easier to discuss topics with natural language than trying to discuss arbitrary numbers sequences for multiple request types like PRC-X, PRC-Y, etc.

Yeah I agree with that! Perhaps the more precise choice is between org.passes.userinfo and net.openid.userinfo. That is, is the topic's namespace the RFC proposer's or the namespace of the nearest upstream specification?

[danscan]

Note: I edited this discussion to replace RequestType with RequestTopic and requestTag with topic to reflect terminology changes.

[jayscambler]

What are the advantages of using net.opened.userinfo? Is the primary benefit standardizing the nomenclature around an existing protocol?

Would using OpenID’s specs standardizes those fields and then Pass Providers would specify additional fields through Pass Request topics?

[danscan]

OpenID Connect is a pretty well-adopted spec around exchanging common profile fields between apps, and so you’re right that’s the primary benefit. This RFC provides a simple way to request profile fields by standing on the shoulders of OIDC claims. That said, OIDC claims limit user profile fields to a pretty primitive set, and Passes is capable of much more, so this RFC is really just a starting point.

…

On Wed, Jan 24, 2024 at 9:49 PM Jay Scambler ***@***.***> wrote: What are the advantages of using net.opened.userinfo? Is the primary benefit standardizing the nomenclature around an existing protocol? Would using OpenID’s specs standardizes those fields and then Pass Providers would specify additional fields through Pass Request topics? — Reply to this email directly, view it on GitHub <#5 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAMQES7GDUURDF26HZEBENTYQHBZXAVCNFSM6AAAAABALXHJTWVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DEMZZHEZDA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[jayscambler]

The use cases that I'm imagining where Passes would be particularly helpful are definitely outside the scope of fields within the OIDC claims, so I think it's appropriate to go with org.passes.userinfo for the topic id.

[danscan]

Update:

This proposal has been updated to rename the topic to xyz.genesis.oidc.userinfo to reflect the convention that has emerged where the only request topics related to features of the Passes protocol, such as org.passes.provide-pass, org.passes.provide-topics, org.passes.request-batch, and org.passes.request-with-default-provider use the org.passes.* namespace.

Application-related request topics will instead use the namespace of the application that proposes them. For example, because Genesis (https://genesis.xyz) is proposing this request, it belongs in the xyz.genesis.* namespace.

This change helps standards to evolve without central coordination around Passes.org or this discussions site, enabling things to progress more easily and quickly.

This discussion will now be closed.