Internet DRAFT - draft-ietf-jmap-sharing
draft-ietf-jmap-sharing
JMAP N.M. Jenkins, Ed.
Internet-Draft Fastmail
Intended status: Standards Track 6 February 2024
Expires: 9 August 2024
JMAP Sharing
draft-ietf-jmap-sharing-05
Abstract
This document specifies a data model for sharing data between users
using JMAP. Specifications for other data types can reference this
document to support a consistent model of sharing.
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 August 2024.
Copyright Notice
Copyright (c) 2024 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 Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Jenkins Expires 9 August 2024 [Page 1]
Internet-Draft JMAP Sharing February 2024
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.3. Data Model Overview . . . . . . . . . . . . . . . . . . . 3
1.4. Subscriptions . . . . . . . . . . . . . . . . . . . . . . 4
1.5. Addition to the Capabilities Object . . . . . . . . . . . 4
1.5.1. urn:ietf:params:jmap:principals . . . . . . . . . . . 5
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 . . . . . . . . . . . . . . . . . . . . . . 7
2.4. Principal/query . . . . . . . . . . . . . . . . . . . . . 7
2.4.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 7
2.5. Principal/queryChanges . . . . . . . . . . . . . . . . . 8
3. Share Notifications . . . . . . . . . . . . . . . . . . . . . 8
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 . . . . . . . . . . . . . . . . . 10
3.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 10
3.6.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 10
3.7. ShareNotification/queryChanges . . . . . . . . . . . . . 10
4. Framework for shared data . . . . . . . . . . . . . . . . . . 10
4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 11
5. Security Considerations . . . . . . . . . . . . . . . . . . . 14
5.1. Spoofing . . . . . . . . . . . . . . . . . . . . . . . . 14
5.2. Unnoticed sharing . . . . . . . . . . . . . . . . . . . . 14
5.3. Unauthorised principals . . . . . . . . . . . . . . . . . 14
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
6.1. JMAP Capability Registration for "principals" . . . . . . 15
6.2. JMAP Capability Registration for "principals:owner" . . . 15
7. Normative References . . . . . . . . . . . . . . . . . . . . 15
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
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.
Jenkins Expires 9 August 2024 [Page 2]
Internet-Draft JMAP Sharing February 2024
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.
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.
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 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 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.
Jenkins Expires 9 August 2024 [Page 3]
Internet-Draft JMAP Sharing February 2024
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
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 2.4). 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.
Jenkins Expires 9 August 2024 [Page 4]
Internet-Draft JMAP Sharing February 2024
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.
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.
Jenkins Expires 9 August 2024 [Page 5]
Internet-Draft JMAP Sharing February 2024
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 (immutable; server-set)
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.
- 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.
* *accounts*: Id[Account]|null
A map of account id to Account object for each JMAP Account
containing data for this principal that the user has access to, or
null if none.
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 which they will always return
a "cannotCalculateChanges" error, as described in the core JMAP
specification.
Jenkins Expires 9 August 2024 [Page 6]
Internet-Draft JMAP Sharing February 2024
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 reject this change, and probably will reject
any other 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.
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 any of the ids in
this list are keys in the Principal's "accounts" property (i.e.,
if any of the account ids belong to the principal).
* *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.
Jenkins Expires 9 August 2024 [Page 7]
Internet-Draft JMAP Sharing February 2024
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 which they will always return
a "cannotCalculateChanges" error, as described in the core JMAP
specification.
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.
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 (immutable; server-set)
The id of the ShareNotification.
* *created*: UTCDate (immutable; server-set)
The time this notification was created.
* *changedBy*: Person (immutable; server-set)
Who made the change.
- *name*: String
The name of the person who made the change.
Jenkins Expires 9 August 2024 [Page 8]
Internet-Draft JMAP Sharing February 2024
- *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 (immutable; server-set)
The name of the data type for the object whose permissions have
changed, e.g., "Calendar" or "Mailbox".
* *objectAccountId*: String (immutable; server-set)
The id of the account where this object exists.
* *objectId*: String (immutable; server-set)
The id of the object that this notification is about.
* *oldRights*: String[Boolean]|null (immutable; server-set)
The "myRights" property of the object for the user before the
change.
* *newRights*: String[Boolean]|null (immutable; server-set)
The "myRights" property of the object for the user after the
change.
* *name*: String (immutable; server-set)
The name of the object at the time the notification was made.
Determining the name will depend on the data type in question, for
example it might be the "title" property of a CalendarEvent or the
"name" of a Mailbox, and is implementation specific. The name is
to show to users who have had their access rights to the object
removed, so that they know what it is they can no longer access.
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.
Jenkins Expires 9 August 2024 [Page 9]
Internet-Draft JMAP Sharing February 2024
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.
4. 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.
Each key is the name of a permission defined for that data type.
The value for the key is true if the user has the permission, or
false if they do not.
* *shareWith*: Id[String[Boolean]]|null
Jenkins Expires 9 August 2024 [Page 10]
Internet-Draft JMAP Sharing February 2024
A map of principal id to rights to give that principal (in the
same format as the myRights property), or null if not shared with
anyone. The account id for the principal id can be found in the
capabilities of the Account this object is in (see Section 1.5.2).
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.1. Example
Suppose we are designing a data model for a very simple todo 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
lists sharable 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, 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
Has the user indicated they wish to see this list? If false,
clients should not display this todo list with the user's other
lists, but should provide a means for users to see and subscribe
to all lists that have been shared with them.
* *myRights*: TodoListRights
The set of permissions the user currently has for this todo list.
* *shareWith*: Id[TodoListRights]|null
Jenkins Expires 9 August 2024 [Page 11]
Internet-Draft JMAP Sharing February 2024
A map of principal id to rights to give that principal, or null if
not shared with anyone or the user does not have the "mayAdmin"
right for this list. Users with the "mayAdmin" right 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.
We would 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
May the user add this principal as a sharee of a todo list?
A client wishing to let the user configure sharing would look at the
account capabilities for the Account containing the user's Todo data,
and find the "urn:ietf:params:jmap:principals:owner" property, as per
Section 1.5.2.
In the "accounts" property of the JMAP session object...
"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"
}
}
}
Figure 1
From this it now knows which account has the Principal data, and can
fetch the list of principals to offer the user to share the list
with, making an API request like this:
[[ "Principal/get", {
"accountId": "u33084183",
"ids": null
}, "0" ]]
Figure 2
Jenkins Expires 9 August 2024 [Page 12]
Internet-Draft JMAP Sharing February 2024
Here's an example response (where Joe Bloggs is another user that
this user could share their todo list with, but who has not shared
any data in their own account with this user):
[[ "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" ]]
Figure 3
A todo list can be shared with Joe Bloggs by updating its shareWith
property, as in this example request:
Jenkins Expires 9 August 2024 [Page 13]
Internet-Draft JMAP Sharing February 2024
[[ "TodoList/set", {
"accountId": "u12345678",
"update": {
"tl01n231": {
"shareWith": {
"P2342fnddd20": {
"mayRead": true,
"mayWrite": true,
"mayAdmin": false
}
}
}
}
}, "0" ]]
Figure 4
5. Security Considerations
All security considerations of JMAP [RFC8620] apply to this
specification. Additional considerations are detailed below.
5.1. 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.
5.2. 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.
5.3. 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:
* An increased risk of a user accidentally sharing data with an
unintended person.
Jenkins Expires 9 August 2024 [Page 14]
Internet-Draft JMAP Sharing February 2024
* An attacker may share unwanted or offensive information with the
user.
* An attacker may share items with spam content in the names in
order to generate ShareNotification objects, which are likely to
be prominently displayed to the sharee.
6. IANA Considerations
6.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 5
6.2. 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 5
7. 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,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
Jenkins Expires 9 August 2024 [Page 15]
Internet-Draft JMAP Sharing February 2024
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
2019, <https://www.rfc-editor.org/info/rfc8620>.
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 August 2024 [Page 16]
