JMAP N.M. Jenkins, Ed. Internet-Draft Fastmail Intended status: Standards Track 7 June 2021 Expires: 9 December 2021 JMAP Sharing draft-ietf-jmap-sharing-00 Abstract This document specifies a data model for sharing data between users using JMAP. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 9 December 2021. Copyright Notice Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 Jenkins Expires 9 December 2021 [Page 1] Internet-Draft JMAP Sharing June 2021 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.3. Data Model Overview . . . . . . . . . . . . . . . . . . . 3 1.4. Subscriptions . . . . . . . . . . . . . . . . . . . . . . 3 1.5. Addition to the Capabilities Object . . . . . . . . . . . 4 1.5.1. urn:ietf:params:jmap:principals . . . . . . . . . . . 4 1.5.2. urn:ietf:params:jmap:principals:owner . . . . . . . . 5 2. Principals . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Principal/get . . . . . . . . . . . . . . . . . . . . . . 6 2.2. Principal/changes . . . . . . . . . . . . . . . . . . . . 6 2.3. Principal/set . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Principal/query . . . . . . . . . . . . . . . . . . . . . 7 2.4.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 7 2.5. Principal/queryChanges . . . . . . . . . . . . . . . . . 7 3. Share Notifications . . . . . . . . . . . . . . . . . . . . . 7 3.1. Auto-deletion of Notifications . . . . . . . . . . . . . 8 3.2. Object Properties . . . . . . . . . . . . . . . . . . . . 8 3.3. ShareNotification/get . . . . . . . . . . . . . . . . . . 9 3.4. ShareNotification/changes . . . . . . . . . . . . . . . . 9 3.5. ShareNotification/set . . . . . . . . . . . . . . . . . . 9 3.6. ShareNotification/query . . . . . . . . . . . . . . . . . 9 3.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 9 3.6.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 9 3.7. ShareNotification/queryChanges . . . . . . . . . . . . . 9 3.8. Framework for shared data . . . . . . . . . . . . . . . . 10 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 5.1. JMAP Capability Registration for "principals" . . . . . . 10 5.2. JMAP Capability Registration for "principals:owner" . . . 10 6. Normative References . . . . . . . . . . . . . . . . . . . . 11 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 1. 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. Jenkins Expires 9 December 2021 [Page 2] Internet-Draft JMAP Sharing June 2021 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 in Section 1.1 of [RFC8620]. Data types defined in the core specification are also used in this document. 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 these specific capitalizations) 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 (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. 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. 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 Jenkins Expires 9 December 2021 [Page 3] Internet-Draft JMAP Sharing June 2021 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. 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. 1.5.1. 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: * *currentUserPrincipalId*: "Id|null" The id of the principal in this account that corresponds to the user fetching this object, if any. Jenkins Expires 9 December 2021 [Page 4] Internet-Draft JMAP Sharing June 2021 1.5.2. 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: * *accountIdForPrincipal*: "Id" The id of an account with the "urn:ietf:params:jmap:principals" capability that contains the corresponding Principal object. * *principalId*: "Id" The id of the principal that owns this account. 2. 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: * *id*: "Id" The id of the principal. * *type*: "String" This MUST be one of the following values: - "individual": This represents a single person. - "group": This represents a group of people. Jenkins Expires 9 December 2021 [Page 5] Internet-Draft JMAP Sharing June 2021 - "resource": This represents some resource, e.g. a projector. - "location": This represents a location. - "other": This represents some other undefined principal. * *name*: "String" The name of the principal, e.g. "Jane Doe", or "Room 4B". * *description*: "String|null" A longer description of the principal, for example details about the facilities of a resource, or null if no description available. * *email*: "String|null" An email address for the principal, or null if no email is available. * *timeZone*: "String|null" The time zone for this principal, if known. If not null, the value MUST be a time zone id from the IANA Time Zone Database TZDB (https://www.iana.org/time-zones). * *capabilities*: "String[Object]" A map of JMAP capability URIs to domain specific information about the principal in relation to that capability, as defined in the document that registered the capability. 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. 2.3. 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. Jenkins Expires 9 December 2021 [Page 6] Internet-Draft JMAP Sharing June 2021 2.4. Principal/query This is a standard "/query" method as described in [RFC8620], Section 5.5 2.4.1. Filtering A *FilterCondition* object has the following properties: * *accountIds*: "String[]" A list of account ids. The Principal matches if the value for its accountId property is in this list. * *email*: "String" Looks for the text in the email property. * *name*: "String" Looks for the text in the name property. * *text* "String" Looks for the text in the name, email, and description properties. * *type*: "String" The type must be exactly as given to match the condition. * *timeZone*: "String" The timeZone must be exactly as given to match the condition. All conditions in the FilterCondition object must match for the Principal to match. 2.5. Principal/queryChanges This is a standard "/queryChanges" method as described in [RFC8620], Section 5.6. 3. 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. Jenkins Expires 9 December 2021 [Page 7] Internet-Draft JMAP Sharing June 2021 3.1. 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. 3.2. Object Properties The *ShareNotification* object has the following properties: * *id*: "String" The id of the ShareNotification. * *created*: "UTCDate" The time this notification was created. * *changedBy*: "Person" Who made the change. - *name*: "String" The name of the person who made the change. - *email*: "String|null" The email of the person who made the change, or null if no email is available. - *principalId*: "String|null" The id of the Principal corresponding to the person who made the change, or null if no associated principal. * *objectType*: "String" The name of the data type for the object whose permissions have changed, e.g. "Calendar" or "Mailbox". * *objectAccountId*: "String" The id of the account where this object exists. * *objectId*: "String" The id of the object that this notification is about. * *name*: "String" The name of the object at the time the notification was made. * *oldRights*: "String[Boolean]|null" The "myRights" property of the object for the user before the change. * *newRights*: "String[Boolean]|null" The "myRights" property of the object for the user after the change. Jenkins Expires 9 December 2021 [Page 8] Internet-Draft JMAP Sharing June 2021 3.3. ShareNotification/get This is a standard "/get" method as described in [RFC8620], Section 5.1. 3.4. ShareNotification/changes This is a standard "/changes" method as described in [RFC8620], Section 5.2. 3.5. 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. 3.6. ShareNotification/query This is a standard "/query" method as described in [RFC8620], Section 5.5. 3.6.1. Filtering A *FilterCondition* object has the following properties: * *after*: "UTCDate|null" The creation date must be on or after this date to match the condition. * *before*: "UTCDate|null" The creation date must be before this date to match the condition. * *objectType*: "String" The objectType value must be identical to the given value to match the condition. * *objectAccountId*: "String" The objectAccountId value must be identical to the given value to match the condition. 3.6.2. Sorting The "created" property MUST be supported for sorting. 3.7. ShareNotification/queryChanges This is a standard "/queryChanges" method as described in [RFC8620], Section 5.6. Jenkins Expires 9 December 2021 [Page 9] Internet-Draft JMAP Sharing June 2021 3.8. Framework for shared data Shareable data types SHOULD define the following three properties: * *isSubscribed*: "Boolean" Has the user indicated they wish to see this data? The initial value for this when data is shared by another user is implementation dependent, although data types may give advice on appropriate defaults. * *myRights*: "String[Boolean]" The set of permissions the user currently has. Appropriate permissions are domain specific and must be defined per data type. * *shareWith*: "Id[String[Boolean]]" A map of principal id to rights to give that principal. The account id for the principal id can be found in the capabilities of the Account this object is in (see Section XXX). Users with appropriate permission may set this property to modify who the data is shared with. The principal that owns the account this data is in MUST NOT be in the set of sharees; their rights are implicit. 4. Security Considerations All security considerations of JMAP [RFC8620] apply to this specification. TODO. 5. IANA Considerations 5.1. 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 5.2. JMAP Capability Registration for "principals:owner" IANA will register the "principals:owner" JMAP Capability as follows: Jenkins Expires 9 December 2021 [Page 10] Internet-Draft JMAP Sharing June 2021 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 6. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 2019, . Author's Address Neil Jenkins (editor) Fastmail PO Box 234, Collins St West Melbourne VIC 8007 Australia Email: neilj@fastmailteam.com URI: https://www.fastmail.com Jenkins Expires 9 December 2021 [Page 11]