233 lines
9.7 KiB
ReStructuredText
233 lines
9.7 KiB
ReStructuredText
========
|
|
Profiles
|
|
========
|
|
|
|
A description of Synapse user profile metadata support.
|
|
|
|
|
|
Overview
|
|
========
|
|
|
|
Internally within Synapse users are referred to by an opaque ID, which consists
|
|
of some opaque localpart combined with the domain name of their home server.
|
|
Obviously this does not yield a very nice user experience; users would like to
|
|
see readable names for other users that are in some way meaningful to them.
|
|
Additionally, users like to be able to publish "profile" details to inform other
|
|
users of other information about them.
|
|
|
|
It is also conceivable that since we are attempting to provide a
|
|
worldwide-applicable messaging system, that users may wish to present different
|
|
subsets of information in their profile to different other people, from a
|
|
privacy and permissions perspective.
|
|
|
|
A Profile consists of a display name, an (optional?) avatar picture, and a set
|
|
of other metadata fields that the user may wish to publish (email address, phone
|
|
numbers, website URLs, etc...). We put no requirements on the display name other
|
|
than it being a valid Unicode string. Since it is likely that users will end up
|
|
having multiple accounts (perhaps by necessity of being hosted in multiple
|
|
places, perhaps by choice of wanting multiple distinct identifies), it would be
|
|
useful that a metadata field type exists that can refer to another Synapse User
|
|
ID, so that clients and HSes can make use of this information.
|
|
|
|
Metadata Fields
|
|
---------------
|
|
|
|
[[TODO(paul): Likely this list is incomplete; more fields can be defined as we
|
|
think of them. At the very least, any sort of supported ID for the 3rd Party ID
|
|
servers should be accounted for here.]]
|
|
|
|
* Synapse Directory Server username(s)
|
|
|
|
* Email address
|
|
|
|
* Phone number - classify "home"/"work"/"mobile"/custom?
|
|
|
|
* Twitter/Facebook/Google+/... social networks
|
|
|
|
* Location - keep this deliberately vague to allow people to choose how
|
|
granular it is
|
|
|
|
* "Bio" information - date of birth, etc...
|
|
|
|
* Synapse User ID of another account
|
|
|
|
* Web URL
|
|
|
|
* Freeform description text
|
|
|
|
|
|
Visibility Permissions
|
|
======================
|
|
|
|
A home server implementation could offer the ability to set permissions on
|
|
limited visibility of those fields. When another user requests access to the
|
|
target user's profile, their own identity should form part of that request. The
|
|
HS implementation can then decide which fields to make available to the
|
|
requestor.
|
|
|
|
A particular detail of implementation could allow the user to create one or more
|
|
ACLs; where each list is granted permission to see a given set of non-public
|
|
fields (compare to Google+ Circles) and contains a set of other people allowed
|
|
to use it. By giving these ACLs strong identities within the HS, they can be
|
|
referenced in communications with it, granting other users who encounter these
|
|
the "ACL Token" to use the details in that ACL.
|
|
|
|
If we further allow an ACL Token to be present on Room join requests or stored
|
|
by 3PID servers, then users of these ACLs gain the extra convenience of not
|
|
having to manually curate people in the access list; anyone in the room or with
|
|
knowledge of the 3rd Party ID is automatically granted access. Every HS and
|
|
client implementation would have to be aware of the existence of these ACL
|
|
Token, and include them in requests if present, but not every HS implementation
|
|
needs to actually provide the full permissions model. This can be used as a
|
|
distinguishing feature among competing implementations. However, servers MUST
|
|
NOT serve profile information from a cache if there is a chance that its limited
|
|
understanding could lead to information leakage.
|
|
|
|
|
|
Client Concerns of Multiple Accounts
|
|
====================================
|
|
|
|
Because a given person may want to have multiple Synapse User accounts, client
|
|
implementations should allow the use of multiple accounts simultaneously
|
|
(especially in the field of mobile phone clients, which generally don't support
|
|
running distinct instances of the same application). Where features like address
|
|
books, presence lists or rooms are presented, the client UI should remember to
|
|
make distinct with user account is in use for each.
|
|
|
|
|
|
Directory Servers
|
|
=================
|
|
|
|
Directory Servers can provide a forward mapping from human-readable names to
|
|
User IDs. These can provide a service similar to giving domain-namespaced names
|
|
for Rooms; in this case they can provide a way for a user to reference their
|
|
User ID in some external form (e.g. that can be printed on a business card).
|
|
|
|
The format for Synapse user name will consist of a localpart specific to the
|
|
directory server, and the domain name of that directory server:
|
|
|
|
@localname:some.domain.name
|
|
|
|
The localname is separated from the domain name using a colon, so as to ensure
|
|
the localname can still contain periods, as users may want this for similarity
|
|
to email addresses or the like, which typically can contain them. The format is
|
|
also visually quite distinct from email addresses, phone numbers, etc... so
|
|
hopefully reasonably "self-describing" when written on e.g. a business card
|
|
without surrounding context.
|
|
|
|
[[TODO(paul): we might have to think about this one - too close to email?
|
|
Twitter? Also it suggests a format scheme for room names of
|
|
#localname:domain.name, which I quite like]]
|
|
|
|
Directory server administrators should be able to make some kind of policy
|
|
decision on how these are allocated. Servers within some "closed" domain (such
|
|
as company-specific ones) may wish to verify the validity of a mapping using
|
|
their own internal mechanisms; "public" naming servers can operate on a FCFS
|
|
basis. There are overlapping concerns here with the idea of the 3rd party
|
|
identity servers as well, though in this specific case we are creating a new
|
|
namespace to allocate names into.
|
|
|
|
It would also be nice from a user experience perspective if the profile that a
|
|
given name links to can also declare that name as part of its metadata.
|
|
Furthermore as a security and consistency perspective it would be nice if each
|
|
end (the directory server and the user's home server) check the validity of the
|
|
mapping in some way. This needs investigation from a security perspective to
|
|
ensure against spoofing.
|
|
|
|
One such model may be that the user starts by declaring their intent to use a
|
|
given user name link to their home server, which then contacts the directory
|
|
service. At some point later (maybe immediately for "public open FCFS servers",
|
|
maybe after some kind of human intervention for verification) the DS decides to
|
|
honour this link, and includes it in its served output. It should also tell the
|
|
HS of this fact, so that the HS can present this as fact when requested for the
|
|
profile information. For efficiency, it may further wish to provide the HS with
|
|
a cryptographically-signed certificate as proof, so the HS serving the profile
|
|
can provide that too when asked, avoiding requesting HSes from constantly having
|
|
to contact the DS to verify this mapping. (Note: This is similar to the security
|
|
model often applied in DNS to verify PTR <-> A bidirectional mappings).
|
|
|
|
|
|
Identity Servers
|
|
================
|
|
|
|
The identity servers should support the concept of pointing a 3PID being able to
|
|
store an ACL Token as well as the main User ID. It is however, beyond scope to
|
|
do any kind of verification that any third-party IDs that the profile is
|
|
claiming match up to the 3PID mappings.
|
|
|
|
|
|
User Interface and Expectations Concerns
|
|
========================================
|
|
|
|
Given the weak "security" of some parts of this model as compared to what users
|
|
might expect, some care should be taken on how it is presented to users,
|
|
specifically in the naming or other wording of user interface components.
|
|
|
|
Most notably mere knowledge of an ACL Pointer is enough to read the information
|
|
stored in it. It is possible that Home or Identity Servers could leak this
|
|
information, allowing others to see it. This is a security-vs-convenience
|
|
balancing choice on behalf of the user who would choose, or not, to make use of
|
|
such a feature to publish their information.
|
|
|
|
Additionally, unless some form of strong end-to-end user-based encryption is
|
|
used, a user of ACLs for information privacy has to trust other home servers not
|
|
to lie about the identify of the user requesting access to the Profile.
|
|
|
|
|
|
API Requirements
|
|
================
|
|
|
|
The data model presented here puts the following requirements on the APIs:
|
|
|
|
Client-Server
|
|
-------------
|
|
|
|
Requests that a client can make to its Home Server
|
|
|
|
* get/set my Display Name
|
|
This should return/take a simple "text/plain" field
|
|
|
|
* get/set my Avatar URL
|
|
The avatar image data itself is not stored by this API; we'll just store a
|
|
URL to let the clients fetch it. Optionally HSes could integrate this with
|
|
their generic content attacmhent storage service, allowing a user to set
|
|
upload their profile Avatar and update the URL to point to it.
|
|
|
|
* get/add/remove my metadata fields
|
|
Also we need to actually define types of metadata
|
|
|
|
* get another user's Display Name / Avatar / metadata fields
|
|
|
|
[[TODO(paul): At some later stage we should consider the API for:
|
|
|
|
* get/set ACL permissions on my metadata fields
|
|
|
|
* manage my ACL tokens
|
|
]]
|
|
|
|
Server-Server
|
|
-------------
|
|
|
|
Requests that Home Servers make to others
|
|
|
|
* get a user's Display Name / Avatar
|
|
|
|
* get a user's full profile - name/avatar + MD fields
|
|
This request must allow for specifying the User ID of the requesting user,
|
|
for permissions purposes. It also needs to take into account any ACL Tokens
|
|
the requestor has.
|
|
|
|
* push a change of Display Name to observers (overlaps with the presence API)
|
|
|
|
Room Event PDU Types
|
|
--------------------
|
|
|
|
Events that are pushed from Home Servers to other Home Servers or clients.
|
|
|
|
* user Display Name change
|
|
|
|
* user Avatar change
|
|
[[TODO(paul): should the avatar image itself be stored in all the room
|
|
histories? maybe this event should just be a hint to clients that they should
|
|
re-fetch the avatar image]]
|