JSON Meta Application Protocol (JMAP) Sharing
updates
- rfc-8620 — The JSON Meta Application Protocol (JMAP)
Extracted elements (28)
Managing the set of Principals within a system is explicitly out of scope for this specification because it is highly domain specific and likely maps directly from a directory service or other user management system.
The server MAY limit the maximum number of ShareNotifications stored per user and coalesce multiple changes to the same object into a single notification, because automatic deletion upon reaching a limit can itself be a security issue by hiding sharing changes from the user.
The specification separates _permission_ to access data from _subscription_ (desire to see it). A user may have permission to access many shared mailboxes but subscribe only to the ones they care about, allowing clients to present distinct interfaces for subscribed vs. browsable data.
Implementations backed by an external directory may be unable to calculate changes for Principal/changes and Principal/queryChanges, in which case they will always return a 'cannotCalculateChanges' error as defined in the core JMAP specification.
A server MUST reject any change to a Principal it doesn't allow with a 'forbidden' SetError. Where changes are supported, the server SHOULD allow updates to 'name', 'description', and 'timeZone' for the current user's own Principal.
All shareable data types MUST define three common properties: isSubscribed (Boolean indicating user subscription intent), myRights (String[Boolean] map of the user's current permissions), and shareWith (Id[String[Boolean]]|null map of Principals and their granted rights).
For servers implementing this specification, the Session object MUST only include Accounts where the user is subscribed to at least one record or the Account belongs to the user.
For ShareNotification/set, only destroy is supported; any attempt to create or update a ShareNotification MUST be rejected with a 'forbidden' SetError.
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, except where that Account belongs to the user.
The 'created' property MUST be supported as a sort criterion for ShareNotification/query results.
The Principal's email property, if not null, MUST conform to the 'addr-spec' syntax as defined in RFC 5322, Section 3.4.1.
The Principal's timeZone property, if not null, MUST be a time zone name from the IANA Time Zone Database.
The Principal that owns the Account containing shared data MUST NOT appear in the shareWith map, as the owner's rights are implicit.
The server SHOULD create a ShareNotification whenever the user's permissions change on an object. It MAY omit notifications for group Principal permission changes if this would be more overwhelming than helpful.
A Principal object represents an individual, group, location, resource, or other entity. Required properties include id, type (one of 'individual', 'group', 'resource', 'location', 'other'), name, description, email, timeZone, capabilities, and accounts.
A ShareNotification object records when the user's permissions on a shared object change. Properties include id, created (UTCDate), changedBy (Entity with name/email/principalId), objectType, objectAccountId, objectId, oldRights, newRights, and name. Only the server may create ShareNotifications.
Principal/query supports a FilterCondition with optional properties: accountIds (list of Account ids), email (substring match), name (substring match), text (name/email/description substring match), type (exact match), and timeZone (exact match). All conditions must match.
ShareNotification/query supports a FilterCondition with optional properties: after (UTCDate), before (UTCDate), objectType (exact match), and objectAccountId (exact match). All given conditions must match.
The urn:ietf:params:jmap:principals capability advertises support for Principal and ShareNotification data types. Its value in accountCapabilities MUST contain currentUserPrincipalId (Id|null), the id of the Principal corresponding to the fetching user.
The urn:ietf:params:jmap:principals:owner key in accountCapabilities indicates an Account is owned by a Principal. Its value contains accountIdForPrincipal (the Account holding Principal objects) and principalId (the owning Principal's id).
IANA registered 'Principal' in the JMAP Data Types registry: cannot reference blobs, can be used for state change, requires urn:ietf:params:jmap:principals capability.
IANA registered 'ShareNotification' in the JMAP Data Types registry: cannot reference blobs, can be used for state change, requires urn:ietf:params:jmap:principals capability.
IANA registered 'urn:ietf:params:jmap:principals' in the JMAP Capabilities registry, with intended use 'common', change controller IETF, and reference RFC 9670.
IANA registered 'urn:ietf:params:jmap:principals:owner' in the JMAP Capabilities registry, with intended use 'common', change controller IETF, and reference RFC 9670.
A user can cause resource exhaustion by generating many ShareNotifications through frequent changes to sharing status. Servers should coalesce notifications, limit stored notifications per user, and rate-limit sharing permission changes; deletion upon reaching limits is discouraged as it can silently hide changes from the user.
Allowing users to edit their own Principal's name or email could enable spoofing — a user might impersonate another to trick others into sharing private data. Servers SHOULD keep audit logs of such changes; simply forbidding duplicate names is insufficient because visually similar Unicode characters can still be exploited.
Sharing data can convert a transitory account compromise into a persistent one by setting up sharing with an attacker-controlled Principal. Mitigations include requiring additional authorization for configuring sharing or sending out-of-band notifications whenever a new permission is added.
The set of Principals within a shared environment MUST be strictly controlled. Open Principal registration risks accidental sharing with unintended parties, delivery of unwanted content, and spam via ShareNotification names.