idnits 2.17.1 draft-ietf-jmap-sharing-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (7 June 2021) is 1052 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JMAP N.M. Jenkins, Ed. 3 Internet-Draft Fastmail 4 Intended status: Standards Track 7 June 2021 5 Expires: 9 December 2021 7 JMAP Sharing 8 draft-ietf-jmap-sharing-00 10 Abstract 12 This document specifies a data model for sharing data between users 13 using JMAP. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on 9 December 2021. 32 Copyright Notice 34 Copyright (c) 2021 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 39 license-info) in effect on the date of publication of this document. 40 Please review these documents carefully, as they describe your rights 41 and restrictions with respect to this document. Code Components 42 extracted from this document must include Simplified BSD License text 43 as described in Section 4.e of the Trust Legal Provisions and are 44 provided without warranty as described in the Simplified BSD License. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 49 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 50 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.3. Data Model Overview . . . . . . . . . . . . . . . . . . . 3 52 1.4. Subscriptions . . . . . . . . . . . . . . . . . . . . . . 3 53 1.5. Addition to the Capabilities Object . . . . . . . . . . . 4 54 1.5.1. urn:ietf:params:jmap:principals . . . . . . . . . . . 4 55 1.5.2. urn:ietf:params:jmap:principals:owner . . . . . . . . 5 56 2. Principals . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 2.1. Principal/get . . . . . . . . . . . . . . . . . . . . . . 6 58 2.2. Principal/changes . . . . . . . . . . . . . . . . . . . . 6 59 2.3. Principal/set . . . . . . . . . . . . . . . . . . . . . . 6 60 2.4. Principal/query . . . . . . . . . . . . . . . . . . . . . 7 61 2.4.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 7 62 2.5. Principal/queryChanges . . . . . . . . . . . . . . . . . 7 63 3. Share Notifications . . . . . . . . . . . . . . . . . . . . . 7 64 3.1. Auto-deletion of Notifications . . . . . . . . . . . . . 8 65 3.2. Object Properties . . . . . . . . . . . . . . . . . . . . 8 66 3.3. ShareNotification/get . . . . . . . . . . . . . . . . . . 9 67 3.4. ShareNotification/changes . . . . . . . . . . . . . . . . 9 68 3.5. ShareNotification/set . . . . . . . . . . . . . . . . . . 9 69 3.6. ShareNotification/query . . . . . . . . . . . . . . . . . 9 70 3.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 9 71 3.6.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 9 72 3.7. ShareNotification/queryChanges . . . . . . . . . . . . . 9 73 3.8. Framework for shared data . . . . . . . . . . . . . . . . 10 74 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 75 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 76 5.1. JMAP Capability Registration for "principals" . . . . . . 10 77 5.2. JMAP Capability Registration for "principals:owner" . . . 10 78 6. Normative References . . . . . . . . . . . . . . . . . . . . 11 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 81 1. Introduction 83 JMAP ([RFC8620] - JSON Meta Application Protocol) is a generic 84 protocol for synchronizing data, such as mail, calendars or contacts, 85 between a client and a server. It is optimized for mobile and web 86 environments, and aims to provide a consistent interface to different 87 data types. 89 This specification defines a data model to represent entities in a 90 collaborative environment and a framework for sharing data between 91 them that can be used to provide a consistent sharing model for 92 different data types. It does not define _what_ may be shared, or 93 the granularity of permissions, as this will depend on the data in 94 question. 96 1.1. Notational Conventions 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 100 "OPTIONAL" in this document are to be interpreted as described in BCP 101 14 [RFC2119] [RFC8174] when, and only when, they appear in all 102 capitals, as shown here. 104 Type signatures, examples, and property descriptions in this document 105 follow the conventions established in Section 1.1 of [RFC8620]. Data 106 types defined in the core specification are also used in this 107 document. 109 1.2. Terminology 111 The same terminology is used in this document as in the core JMAP 112 specification, see [RFC8620], Section 1.6. 114 The terms Principal, and ShareNotification (with these specific 115 capitalizations) are used to refer to the data types defined in this 116 document and instances of those data types. 118 1.3. Data Model Overview 120 A Principal (see Section XXX) represents an individual, team or 121 resource (e.g., a room or projector). The object contains 122 information about the entity being represented, such as a name, 123 description and time zone. It may also hold domain-specific 124 information. A Principal may be associated with zero or more 125 Accounts (see [RFC8620], Section 1.6.2) containing data belonging to 126 the principal. Managing the set of principals within a system is out 127 of scope for this specification, as it is highly domain specific. 129 Data types may allow users to share data with others by assigning 130 permissions to principals. When a user's permissions are changed, a 131 ShareNotification object is created for them so a client can inform 132 the user of the changes. 134 1.4. Subscriptions 136 Permissions determine whether a user _may_ access data, but not 137 whether they _want_ to. Some shared data is of equal importance as 138 the user's own, while other data is just there should the user wish 139 to explicitly go find it. Clients will often want to differentiate 140 the two; for example, a company may share mailing list archives for 141 all departments with all employees, but a user may only generally be 142 interested in the few they belong to. They would have _permission_ 143 to access many mailboxes, but can _subscribe_ to just the ones they 144 care about. The client would provide separate interfaces for reading 145 mail in subscribed mailboxes and browsing all mailboxes they have 146 permission to access in order to manage their subscriptions. 148 The JMAP Session object (see [RFC8620], Section 2) typically includes 149 an object in the "accounts" property for every account that the user 150 has access to. Collaborative systems may share data between a very 151 large number of Principals, most of which the user does not care 152 about day-to-day. The Session object MUST only include Accounts 153 where either the user is subscribed to at least one record (see 154 [RFC8620], Section 1.6.3) in the account, or the account belongs to 155 the user. StateChange events for changes to data SHOULD only be sent 156 for data the user has subscribed to and MUST NOT be sent for any 157 Account where the user is not subscribed to any records in the 158 account, except where that account belongs to the user. 160 The server MAY reject the user's attempt to subscribe to some 161 resources even if they have permission to access them, e.g., a 162 calendar representing a location. 164 A user may query the set of Principals they have access to with 165 "Principal/query" (see Section XXX). The Principal object may then 166 provide Account objects if the user has permission to access data for 167 that principal, even if they are not yet subscribed. 169 1.5. Addition to the Capabilities Object 171 The capabilities object is returned as part of the JMAP Session 172 object; see [RFC8620], Section 2. This document defines two 173 additional capability URIs. 175 1.5.1. urn:ietf:params:jmap:principals 177 Represents support for the Principal and ShareNotification data types 178 and associated API methods. 180 The value of this property in the JMAP Session capabilities property 181 is an empty object. 183 The value of this property in an account's accountCapabilities 184 property is an object that MUST contain the following information on 185 server capabilities and permissions for that account: 187 * *currentUserPrincipalId*: "Id|null" The id of the principal in 188 this account that corresponds to the user fetching this object, if 189 any. 191 1.5.2. urn:ietf:params:jmap:principals:owner 193 This URI is solely used as a key in an account's accountCapabilities 194 property; it does not appear in the JMAP Session capabilities. 195 Support is implied by the "urn:ietf:params:jmap:principals" session 196 capability. 198 If present, the account (and data therein) is owned by a principal. 199 Some accounts may not be owned by a principal (e.g., the account that 200 contains the data for the principals themselves), in which case this 201 property is omitted. 203 The value of this property is an object with the following 204 properties: 206 * *accountIdForPrincipal*: "Id" The id of an account with the 207 "urn:ietf:params:jmap:principals" capability that contains the 208 corresponding Principal object. 210 * *principalId*: "Id" The id of the principal that owns this 211 account. 213 2. Principals 215 A Principal represents an individual, group, location (e.g. a room), 216 resource (e.g. a projector) or other entity in a collaborative 217 environment. Sharing in JMAP is generally configured by assigning 218 rights to certain data within an account to other principals, for 219 example a user may assign permission to read their calendar to a 220 principal representing another user, or their team. 222 In a shared environment such as a workplace, a user may have access 223 to a large number of principals. 225 In most systems the user will have access to a single Account 226 containing Principal objects, but they may have access to multiple 227 if, for example, aggregating data from different places. 229 A *Principal* object has the following properties: 231 * *id*: "Id" The id of the principal. 233 * *type*: "String" This MUST be one of the following values: 235 - "individual": This represents a single person. 237 - "group": This represents a group of people. 239 - "resource": This represents some resource, e.g. a projector. 241 - "location": This represents a location. 243 - "other": This represents some other undefined principal. 245 * *name*: "String" The name of the principal, e.g. "Jane Doe", or 246 "Room 4B". 248 * *description*: "String|null" A longer description of the 249 principal, for example details about the facilities of a resource, 250 or null if no description available. 252 * *email*: "String|null" An email address for the principal, or null 253 if no email is available. 255 * *timeZone*: "String|null" The time zone for this principal, if 256 known. If not null, the value MUST be a time zone id from the 257 IANA Time Zone Database TZDB (https://www.iana.org/time-zones). 259 * *capabilities*: "String[Object]" A map of JMAP capability URIs to 260 domain specific information about the principal in relation to 261 that capability, as defined in the document that registered the 262 capability. 264 2.1. Principal/get 266 This is a standard "/get" method as described in [RFC8620], 267 Section 5.1. 269 2.2. Principal/changes 271 This is a standard "/changes" method as described in [RFC8620], 272 Section 5.2. 274 2.3. Principal/set 276 This is a standard "/set" method as described in [RFC8620], 277 Section 5.3. 279 Users SHOULD be allowed to update the "name", "description" and 280 "timeZone" properties of the Principal with the same id as the 281 "currentUserPrincipalId" in the Account capabilities. 283 However, the server may, and probably will, reject any change with a 284 "forbidden" SetError. Managing principals is likely tied to a 285 directory service or some other vendor-specific solution, and may 286 occur out-of-band, or via an additional capability defined elsewhere. 288 2.4. Principal/query 290 This is a standard "/query" method as described in [RFC8620], 291 Section 5.5 293 2.4.1. Filtering 295 A *FilterCondition* object has the following properties: 297 * *accountIds*: "String[]" A list of account ids. The Principal 298 matches if the value for its accountId property is in this list. 300 * *email*: "String" Looks for the text in the email property. 302 * *name*: "String" Looks for the text in the name property. 304 * *text* "String" Looks for the text in the name, email, and 305 description properties. 307 * *type*: "String" The type must be exactly as given to match the 308 condition. 310 * *timeZone*: "String" The timeZone must be exactly as given to 311 match the condition. 313 All conditions in the FilterCondition object must match for the 314 Principal to match. 316 2.5. Principal/queryChanges 318 This is a standard "/queryChanges" method as described in [RFC8620], 319 Section 5.6. 321 3. Share Notifications 323 The ShareNotification data type records when the user's permissions 324 to access a shared object changes. ShareNotification are only 325 created by the server; users cannot create them explicitly. 326 Notifications are stored in the same Account as the Principals. 328 Clients SHOULD present the list of notifications to the user and 329 allow them to dismiss them. To dismiss a notification you use a 330 standard "/set" call to destroy it. 332 The server SHOULD create a ShareNotification whenever the user's 333 permissions change on an object. It SHOULD NOT create a notification 334 for permission changes to a group principal, even if the user is in 335 the group. 337 3.1. Auto-deletion of Notifications 339 The server MAY limit the maximum number of notifications it will 340 store for a user. When the limit is reached, any new notification 341 will cause the previously oldest notification to be automatically 342 deleted. 344 The server MAY coalesce notifications if appropriate, or remove 345 notifications that it deems are no longer relevant or after a certain 346 period of time. The server SHOULD automatically destroy a 347 notification about an object if the user subscribes to that object. 349 3.2. Object Properties 351 The *ShareNotification* object has the following properties: 353 * *id*: "String" The id of the ShareNotification. 355 * *created*: "UTCDate" The time this notification was created. 357 * *changedBy*: "Person" Who made the change. 359 - *name*: "String" The name of the person who made the change. 361 - *email*: "String|null" The email of the person who made the 362 change, or null if no email is available. 364 - *principalId*: "String|null" The id of the Principal 365 corresponding to the person who made the change, or null if no 366 associated principal. 368 * *objectType*: "String" The name of the data type for the object 369 whose permissions have changed, e.g. "Calendar" or "Mailbox". 371 * *objectAccountId*: "String" The id of the account where this 372 object exists. 374 * *objectId*: "String" The id of the object that this notification 375 is about. 377 * *name*: "String" The name of the object at the time the 378 notification was made. 380 * *oldRights*: "String[Boolean]|null" The "myRights" property of the 381 object for the user before the change. 383 * *newRights*: "String[Boolean]|null" The "myRights" property of the 384 object for the user after the change. 386 3.3. ShareNotification/get 388 This is a standard "/get" method as described in [RFC8620], 389 Section 5.1. 391 3.4. ShareNotification/changes 393 This is a standard "/changes" method as described in [RFC8620], 394 Section 5.2. 396 3.5. ShareNotification/set 398 This is a standard "/set" method as described in [RFC8620], 399 Section 5.3. 401 Only destroy is supported; any attempt to create/update MUST be 402 rejected with a "forbidden" SetError. 404 3.6. ShareNotification/query 406 This is a standard "/query" method as described in [RFC8620], 407 Section 5.5. 409 3.6.1. Filtering 411 A *FilterCondition* object has the following properties: 413 * *after*: "UTCDate|null" The creation date must be on or after this 414 date to match the condition. 416 * *before*: "UTCDate|null" The creation date must be before this 417 date to match the condition. 419 * *objectType*: "String" The objectType value must be identical to 420 the given value to match the condition. 422 * *objectAccountId*: "String" The objectAccountId value must be 423 identical to the given value to match the condition. 425 3.6.2. Sorting 427 The "created" property MUST be supported for sorting. 429 3.7. ShareNotification/queryChanges 431 This is a standard "/queryChanges" method as described in [RFC8620], 432 Section 5.6. 434 3.8. Framework for shared data 436 Shareable data types SHOULD define the following three properties: 438 * *isSubscribed*: "Boolean" Has the user indicated they wish to see 439 this data? The initial value for this when data is shared by 440 another user is implementation dependent, although data types may 441 give advice on appropriate defaults. 443 * *myRights*: "String[Boolean]" The set of permissions the user 444 currently has. Appropriate permissions are domain specific and 445 must be defined per data type. 447 * *shareWith*: "Id[String[Boolean]]" A map of principal id to rights 448 to give that principal. The account id for the principal id can 449 be found in the capabilities of the Account this object is in (see 450 Section XXX). Users with appropriate permission may set this 451 property to modify who the data is shared with. The principal 452 that owns the account this data is in MUST NOT be in the set of 453 sharees; their rights are implicit. 455 4. Security Considerations 457 All security considerations of JMAP [RFC8620] apply to this 458 specification. 460 TODO. 462 5. IANA Considerations 464 5.1. JMAP Capability Registration for "principals" 466 IANA will register the "principals" JMAP Capability as follows: 468 Capability Name: "urn:ietf:params:jmap:principals" 470 Specification document: this document 472 Intended use: common 474 Change Controller: IETF 476 Security and privacy considerations: this document, Section XXX 478 5.2. JMAP Capability Registration for "principals:owner" 480 IANA will register the "principals:owner" JMAP Capability as follows: 482 Capability Name: "urn:ietf:params:jmap:principals:owner" 484 Specification document: this document 486 Intended use: common 488 Change Controller: IETF 490 Security and privacy considerations: this document, Section XXX 492 6. Normative References 494 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 495 Requirement Levels", BCP 14, RFC 2119, 496 DOI 10.17487/RFC2119, March 1997, 497 . 499 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 500 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 501 May 2017, . 503 [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application 504 Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 505 2019, . 507 Author's Address 509 Neil Jenkins (editor) 510 Fastmail 511 PO Box 234, Collins St West 512 Melbourne VIC 8007 513 Australia 515 Email: neilj@fastmailteam.com 516 URI: https://www.fastmail.com