Listen to Fastmail CEO Bron Gondwana talk about JMAP on the Digital Citizen Podcast

JMAP Sharing

This document specifies a data model for sharing data between users using JMAP.

Introduction

JMAP ([@!RFC8620] – JSON Meta Application Protocol) is a generic protocol for synchronizing data, such as mail, calendars or contacts, between a client and a server. It is optimized for mobile and web environments, and aims to provide a consistent interface to different data types.

This specification defines a data model to represent entities in a collaborative environment and a framework for sharing data between them that can be used to provide a consistent sharing model for different data types. It does not define what may be shared, or the granularity of permissions, as this will depend on the data in question.

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 in Section 1.1 of [@!RFC8620]. Data types defined in the core specification are also used in this document.

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 these specific capitalizations) are used to refer to the data types defined in this document and instances of those data types.

Data Model Overview

A Principal (see Section XXX) 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.

Subscriptions

Permissions determine whether a user may access data, but not whether they want 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 have permission to access many mailboxes, but can subscribe 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 their subscriptions.

The JMAP Session object (see [@!RFC8620], Section 2) typically includes 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. The Session object MUST 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 for changes to data SHOULD only be sent for data the user has subscribed to and MUST 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 server MAY 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 may query the set of Principals they have access to with “Principal/query” (see Section XXX). The Principal object may then provide Account objects if the user has permission to access data for that principal, even if they are not yet subscribed.

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.

urn:ietf:params:jmap:principals

Represents support for the Principal and ShareNotification data types and associated API methods.

The value of this property in the JMAP Session capabilities property is an empty object.

The value of this property in an account’s accountCapabilities property is an object that MUST contain the following information on server capabilities and permissions for that account:

urn:ietf:params:jmap:principals:owner

This URI is solely used as a key in an account’s accountCapabilities property; it does not appear in the JMAP Session capabilities. Support is implied by the urn:ietf:params:jmap:principals session capability.

If present, the account (and data therein) is owned by a principal. Some accounts may not be owned by a principal (e.g., the account that contains the data for the principals themselves), in which case this property is omitted.

The value of this property is an object with the following properties:

Principals

A Principal represents an individual, group, location (e.g. a room), resource (e.g. a projector) or other entity in a collaborative environment. Sharing in JMAP is generally configured by assigning rights to certain data within an account to other principals, for example a user may assign permission to read their calendar to a principal representing another user, or their team.

In a shared environment such as a workplace, a user may have access to a large number of principals.

In most systems the user will have access to a single Account containing Principal objects, but they may have access to multiple if, for example, aggregating data from different places.

A Principal object has the following properties:

Principal/get

This is a standard “/get” method as described in [@!RFC8620], Section 5.1.

Principal/changes

This is a standard “/changes” method as described in [@!RFC8620], Section 5.2.

Principal/set

This is a standard “/set” method as described in [@!RFC8620], Section 5.3.

Users SHOULD be allowed to update the “name”, “description” and “timeZone” properties of the Principal with the same id as the “currentUserPrincipalId” in the Account capabilities.

However, the server may, and probably will, reject any change with a forbidden SetError. Managing principals is likely tied to a directory service or some other vendor-specific solution, and may occur out-of-band, or via an additional capability defined elsewhere.

Principal/query

This is a standard “/query” method as described in [@!RFC8620], Section 5.5

Filtering

A FilterCondition object has the following properties:

All conditions in the FilterCondition object must match for the Principal to match.

Principal/queryChanges

This is a standard “/queryChanges” method as described in [@!RFC8620], Section 5.6.

Share Notifications

The ShareNotification data type records when the user’s permissions to access a shared object changes. ShareNotification are only created by the server; users cannot create them explicitly. Notifications are stored in the same Account as the Principals.

Clients SHOULD present the list of notifications to the user and allow them to dismiss them. To dismiss a notification you use a standard “/set” call to destroy it.

The server SHOULD create a ShareNotification whenever the user’s permissions change on an object. It SHOULD NOT create a notification for permission changes to a group principal, even if the user is in the group.

Auto-deletion of Notifications

The server MAY limit the maximum number of notifications it will store for a user. When the limit is reached, any new notification will cause the previously oldest notification to be automatically deleted.

The server MAY coalesce notifications if appropriate, or remove notifications that it deems are no longer relevant or after a certain period of time. The server SHOULD automatically destroy a notification about an object if the user subscribes to that object.

Object Properties

The ShareNotification object has the following properties:

ShareNotification/get

This is a standard “/get” method as described in [@!RFC8620], Section 5.1.

ShareNotification/changes

This is a standard “/changes” method as described in [@!RFC8620], Section 5.2.

ShareNotification/set

This is a standard “/set” method as described in [@!RFC8620], Section 5.3.

Only destroy is supported; any attempt to create/update MUST be rejected with a forbidden SetError.

ShareNotification/query

This is a standard “/query” method as described in [@!RFC8620], Section 5.5.

Filtering

A FilterCondition object has the following properties:

Sorting

The “created” property MUST be supported for sorting.

ShareNotification/queryChanges

This is a standard “/queryChanges” method as described in [@!RFC8620], Section 5.6.

Framework for shared data

Shareable data types SHOULD define the following three properties:

Security Considerations

All security considerations of JMAP [@!RFC8620] apply to this specification. Additional considerations are detailed below.

Spoofing

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

Unnoticed sharing

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

Unauthorised principals

The set of principals within a shared environment SHOULD be strictly controlled. If adding a new principal is open to the public, risks include:

IANA Considerations

JMAP Capability Registration for “principals”

IANA will register the “principals” JMAP Capability as follows:

Capability Name: urn:ietf:params:jmap:principals

Specification document: this document

Intended use: common

Change Controller: IETF

Security and privacy considerations: this document, Section XXX

JMAP Capability Registration for “principals:owner”

IANA will register the “principals:owner” JMAP Capability as follows:

Capability Name: urn:ietf:params:jmap:principals:owner

Specification document: this document

Intended use: common

Change Controller: IETF

Security and privacy considerations: this document, Section XXX