1.1.Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14[RFC2119][RFC8174] when, and only when, they appear in all capitals, as shown here.¶

Type signatures, examples, and property descriptions in this document follow the conventions established inSection 1.1 of [RFC8620]. Data types defined in the core specification are also used in this document.¶

Examples of API exchanges only show the methodCalls array of the Request object or the methodResponses array of the Response object. For compactness, the rest of the Request/Response object is omitted.¶

1.2.Terminology

The same terminology is used in this document as in the core JMAP specification. See[RFC8620],Section 1.6.¶

The terms "Principal" and "ShareNotification" (with this specific capitalization) are used to refer to the data types defined in this document and instances of those data types.¶

1.3.Data Model Overview

A Principal (seeSection 2) represents an individual, team, or resource (e.g., a room or projector). The object contains information about the entity being represented, such as a name, description, and time zone. It may also hold domain-specific information. A Principal may be associated with zero or more Accounts (see[RFC8620],Section 1.6.2) containing data belonging to the Principal. Managing the set of Principals within a system is out of scope for this specification, as it is highly domain specific. It is likely to map directly from a directory service or other user management system.¶

Data types may allow users to share data with others by assigning permissions to Principals. When a user's permissions are changed, a ShareNotification object is created for them so a client can inform the user of the changes.¶

1.4.Subscribing to Shared Data

Permissions determine whether a usermay access data but not whether theywant to. Some shared data is of equal importance as the user's own, while other data is just there should the user wish to explicitly go find it. Clients will often want to differentiate the two. For example, a company may share mailing list archives for all departments with all employees, but a user may only generally be interested in the few they belong to. They would havepermission to access many mailboxes but cansubscribe to just the ones they care about. The client would provide separate interfaces for reading mail in subscribed mailboxes and browsing all mailboxes they have permission to access in order to manage those that they are subscribed to.¶

The JMAP Session object (see[RFC8620],Section 2) is defined to include an object in the "accounts" property for every Account that the user has access to. Collaborative systems may share data between a very large number of Principals, most of which the user does not care about day to day. For servers implementing this specification, the Session objectMUST only include Accounts where either the user is subscribed to at least one record (see[RFC8620],Section 1.6.3) in the Account or the Account belongs to the user. StateChange events ([RFC8620],Section 7.1) for changes to dataSHOULD only be sent for data the user has subscribed to andMUST NOT be sent for any Account where the user is not subscribed to any records in the Account, except where that Account belongs to the user.¶

The serverMAY reject the user's attempt to subscribe to some resources even if they have permission to access them (e.g., a calendar representing a location).¶

A user can query the set of Principals they have access to with "Principal/query" (seeSection 2.4). The Principal object will contain an Account object for all Accounts where the user has permission to access data for that Principal, even if they are not yet subscribed.¶

1.5.Addition to the Capabilities Object

The capabilities object is returned as part of the JMAP Session object; see[RFC8620],Section 2. This document defines two additional capability URIs.¶

2.1.Principal/get

This is a standard "/get" method as described in[RFC8620],Section 5.1.¶

2.2.Principal/changes

This is a standard "/changes" method as described in[RFC8620],Section 5.2.¶

Note: Implementations backed by an external directory may be unable to calculate changes. In this case, they will always return a "cannotCalculateChanges" error as described in the core JMAP specification.¶

2.3.Principal/set

This is a standard "/set" method as described in[RFC8620],Section 5.3.¶

Managing Principals is likely tied to a directory service or some other vendor-specific solution. This management may occur out of band or via an additional capability defined elsewhere. Allowing direct user modification of properties has security considerations, as noted inSection 6. A serverMUST reject any change it doesn't allow with a "forbidden" SetError.¶

Where a server does support changes via this API, itSHOULD allow an update to the "name", "description", and "timeZone" properties of the Principal with the same id as the "currentUserPrincipalId" in the Account capabilities. This allows the user to update their own details.¶

2.4.Principal/query

This is a standard "/query" method as described in[RFC8620],Section 5.5.¶

2.5.Principal/queryChanges

This is a standard "/queryChanges" method as described in[RFC8620],Section 5.6.¶

Note: Implementations backed by an external directory may be unable to calculate changes. In this case, they will always return a "cannotCalculateChanges" error as described in the core JMAP specification.¶

3.1.ShareNotification/get

This is a standard "/get" method as described in[RFC8620],Section 5.1.¶

3.2.ShareNotification/changes

This is a standard "/changes" method as described in[RFC8620],Section 5.2.¶

3.3.ShareNotification/set

This is a standard "/set" method as described in[RFC8620],Section 5.3.¶

Only destroy is supported; any attempt to create/updateMUST be rejected with a "forbidden" SetError.¶

3.4.ShareNotification/query

This is a standard "/query" method as described in[RFC8620],Section 5.5.¶

3.5.ShareNotification/queryChanges

This is a standard "/queryChanges" method as described in[RFC8620],Section 5.6.¶

4.1.Example

Suppose we are designing a data model for a very simple to-do list. There is a Todo data type representing a single item to do, each of which belongs to a single TodoList. The specification makes the TodoLists shareable by referencing this document and defining the common properties.¶

First, it would define a set of domain-specific rights. For example, a TodoListRights object may have the following properties:¶

mayRead:Boolean

The user may fetch this TodoList and any Todos that belong to this TodoList.¶

mayWrite:Boolean

The user may create, update, or destroy Todos that belong to this TodoList and may change the "name" property of this TodoList.¶

mayAdmin:Boolean

The user may see and modify the "myRights" property of this TodoList and may destroy this TodoList.¶

Then in the TodoList data type, we would include the three common properties described inSection 4, in addition to any type-specific properties (like "name" in this case):¶

id:Id (immutable; server-set)

The id of the object.¶

name:String

A name for this list of Todos.¶

isSubscribed:Boolean

True if the user has indicated they wish to see this list. Iffalse, clients should not display this TodoList with the user's other TodoLists but should provide a means for users to see and subscribe to all TodoLists that have been shared with them.¶

myRights:TodoListRights

The set of permissions the user currently has for this TodoList.¶

shareWith:Id[TodoListRights]|null

If not shared with anyone, the value isnull. Otherwise, it's a map where the keys are Principal ids and the values are the rights given to those Principals. Users with the "mayAdmin" right may set this property to modify who the data is shared with. The Principal that owns the Account that this data is inMUST NOT be in the map; their rights are implicit.¶

We would also define a new Principal capability with two properties:¶

accountId:Id|null

The accountId containing the Todo data for this Principal, if it has been shared with the requesting user.¶

mayShareWith:Boolean

The user may give this Principal permission to access a TodoList.¶

A client wishing to let the user configure sharing would look at the "capabilities" for the Account containing the user's Todo data and find the "urn:ietf:params:jmap:principals:owner" property, as perSection 1.5.2. For example, the JMAP Session object might contain:¶

{  "accounts": {    "u12345678": {      "name": "jane.doe@example.com",      "isPersonal": true,      "isReadOnly": false,      "accountCapabilities": {        "urn:com.example:jmap:todo": {},        "urn:ietf:params:jmap:principals:owner": {          "accountIdForPrincipal": "u33084183",          "principalId": "P105aga511jaa"        }      }    },    ...  },  ...}

From this, the client now knows which Account has the Principal data, and it can fetch the list of Principals and offer to share it with the user by making an API request like this:¶

[[ "Principal/get", {  "accountId": "u33084183",  "ids": null}, "0" ]]

Here's an example response (where "Joe Bloggs" is another user that this user could share their TodoList with; Joe has not shared any of their own data with this user, so the "accounts" property isnull):¶

[[ "Principal/get", {  "accountId": "u33084183",  "state": "7b8eff5zz",  "list": [{    "id": "P2342fnddd20",    "type": "individual",    "name": "Joe Bloggs",    "description": null,    "email": "joe.bloggs@example.com",    "timeZone": "Australia/Melbourne",    "capabilities": {        "urn:com.example:jmap:todo": {            "accountId": null,            "mayShareWith": true        }    },    "accounts": null  }, {    "id": "P674pp24095qo49pr",    "name": "Board room",    "type": "location",    ...  }, ... ],  "notFound": []}, "0" ]]

A TodoList can be shared with "Joe Bloggs" by updating its shareWith property, as in this example request:¶

[[ "TodoList/set", {  "accountId": "u12345678",  "update": {    "tl01n231": {        "shareWith": {            "P2342fnddd20": {                "mayRead": true,                "mayWrite": true,                "mayAdmin": false            }        }    }  }}, "0" ]]

6.1.Spoofing

Allowing users to edit their own Principal's name (and, to a lesser extent, email, description, or type) could allow a user to change their Principal to look like another user in the system, potentially tricking others into sharing private data with them. Servers may choose to forbid this andSHOULD keep logs of such changes to provide an audit trail.¶

Note that simply forbidding the use of a name already in the system is insufficient protection, as a malicious user could still change their name to something easily confused with the existing name by using trivial misspellings or visually similar Unicode characters.¶

6.2.Unnoticed Sharing

Sharing data with another user allows someone to turn a transitory account compromise (e.g., brief access to an unlocked or logged-in client) into a persistent compromise (by setting up sharing with a user that is controlled by the attacker). This can be mitigated by requiring further authorization for configuring sharing or sending notifications to the sharer via another channel whenever a new permission is added.¶

6.3.Denial of Service

By creating many changes to the sharing status of objects, a user can cause many ShareNotifications to be generated, which could lead to resource exhaustion. Servers can mitigate this by coalescing multiple changes to the same object into a single notification, limiting the maximum number of notifications it stores per user and/or rate-limiting the changes to sharing permissions in the first place. Automatically deleting older notifications after reaching a limit can mean the user is not made aware of a sharing change, which can itself be a security issue. For this reason, it is better to coalesce changes and use other mitigation strategies.¶

6.4.Unauthorized Principals

The set of Principals within a shared environmentMUST be strictly controlled. If adding a new Principal is open to the public, risks include:¶

• An increased risk of a user accidentally sharing data with an unintended person.¶
• An attacker sharing unwanted or offensive information with the user.¶
• An attacker sharing items with spam content in the names in order to generate ShareNotification objects, which are likely to be prominently displayed to the user receiving them.¶

7.1.JMAP Capability Registration for "principals"

IANA has registered "principals" in the "JMAP Capabilities" registry as follows:¶

Capability Name:

urn:ietf:params:jmap:principals¶

Intended Use:

common¶

Change Controller:

IETF¶

Security and Privacy Considerations:

RFC 9670,Section 6¶

Reference:

RFC 9670¶

7.2.JMAP Capability Registration for "principals:owner"

IANA has registered "principals:owner" in the "JMAP Capabilities" registry as follows:¶

Capability Name:

urn:ietf:params:jmap:principals:owner¶

Intended Use:

common¶

Change Controller:

IETF¶

Security and Privacy Considerations:

RFC 9670,Section 6¶

Reference:

RFC 9670¶

7.3.JMAP Data Type Registration for "Principal"

IANA has registered "Principal" in the "JMAP Data Types" registry as follows:¶

Type Name:

Principal¶

Can Reference Blobs:

No¶

Can Use for State Change:

Yes¶

Capability:

urn:ietf:params:jmap:principals¶

Reference:

RFC 9670¶

7.4.JMAP Data Type Registration for "ShareNotification"

IANA has registered "ShareNotification" in the "JMAP Data Types" registry as follows:¶

Type Name:

ShareNotification¶

Can Reference Blobs:

No¶

Can Use for State Change:

Yes¶

Capability:

urn:ietf:params:jmap:principals¶

Reference:

RFC 9670¶