JMAP Sharing
draft-ietf-jmap-sharing-09

Received changes through RFC Editor sync (changed state to RFC, created became rfc relationship between draft-ietf-jmap-sharing and RFC 9670, changed IESG state to RFC Published)

[Ballot discuss]
Thanks for this document, as a non-expert I found it easy to read. I have one potential issue, related to subscriptions, I'd like to have a discussion about.

Caveat, as mentioned, I'm not an expert in this technology area, I'm simply going on what the words in the respective specifications say. If the correct outcome of the DISCUSSion is for you to apply a clue bat to me, and no changes to the document, that's fine.

It seems as though there's a conflict between what you write:

  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. 

And the definition of the session object in RFC 8620:

  A successful authenticated GET request to the JMAP Session resource
  MUST return a JSON-encoded *Session* object, giving details about the
  data and capabilities the server can provide to the client given
  those credentials.  It has the following properties:
...
  o  accounts: "Id[Account]"

      A map of an account id to an Account object for each account (see
      Section 1.6.2) the user has access to. 
...

RFC 8620 doesn't say "typically has" it says "has", which to my eyes is a requirement, not a suggestion, notwithstanding the lack of RFC 2119 keyword.

If (as it appears) you're making a normative change to what RFC 8620 specifies, that doesn't bother me,  but I think you should call it out more clearly, and I think you should use the Updates: 8620 header.

Continuing,

            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.

A close reading of RFC 8620 section 7.1 makes it seem like the above is also a change, although PushSubscription in 8620 seems like the exception that proves the rule that 7.1 didn't mean what the plain language of it says.

After reading Section 4 of your document, though, I wonder if you are even talking about the same thing as what RFC 8620 describes as a subscription. Your Section 4 defines "isSubscribed" to mean "the user wishes to subscribe to see this data" and AFAICT doesn't relate to push notifications, except through the much earlier sentence about StateChange that I quote above.

Can you say a few words about how PushSubscription and isSubscribed relate to one another, and whether this relationship will be sufficiently clear to the intended audience of this document? Because it's not at all clear to me.

Depending on what the intended relationship between these two things is, maybe a few words about it in the document would help, maybe it needs to update RFC 8620, etc.

[Ballot comment]
Numerous sections use the bullet points and empty lines in way that  "mis-group" the items for me, making it difficult to parse. I almost raised this as a DISCUSS. An example:

*  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

  The email property of the principal contains the given string.
*  name: String

To me this keeps reading as "A list of accounts..." belongs to "email: String".

IMHO, the proper way would be:

*  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
  The email property of the principal contains the given string.

*  name: String
  stuff ...



Setion 3.6.1: What is the logic for "after" including the date and "before" not including the date?

[Ballot comment]
Thanks for the work done, it seems like a useful document.

Nevertheless, some non-blocking comments:

- the abstract and contents present this I-D as a "data model" but, in my own view, a data model does not include "methods" or actions. Suggest to augment the abstract to also mention "methods"
- even with a i18n section, section 2 allows for only one unknown-language version of "description"
- section 1.5.1 I wonder why the plural form is used in urn:ietf:params:jmap:principals as there can be only one principal

Hope this helps improving the document.

-éric

[Ballot comment]
Thanks for working on this specification, and thanks for adding the internationalization consideration section, this was helpful. No objection from transport layer considerations :-).

[Ballot comment]
Thanks to Susan Hares for the General Area Review Team (Gen-ART) review
(https://mailarchive.ietf.org/arch/msg/gen-art/nZz2fnG_Y5EFsQnoPvi1-q-_y7Y).
and to Yaron Sheffer for the SECDIR review (https://mailarchive.ietf.org/arch/msg/secdir/RJWI2E_uRwrUcp18hFZV-LZ7WEw).

-------------------------------------------------------------------------------
COMMENT
-------------------------------------------------------------------------------

The IANA review of this document seems to not have concluded yet.

-------------------------------------------------------------------------------
NIT
-------------------------------------------------------------------------------

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

Reference [RFC7564] to RFC7564, which was obsoleted by RFC8264 (this may be on
purpose).

Section 2, paragraph 5
> ilable. If given, the value MUST be conform with the "addr-spec" syntax, as d
>                                  ^^^^^^^^^^
There may an error in the verb form "be conform".

Section 3.2, paragraph 2
>  on the data type in question. For example it might be the "title" property o
>                                    ^^^^^^^
A comma is probably missing here.

Section 4, paragraph 2
> The specification makes the lists sharable by referencing this document and d
>                                  ^^^^^^^^
Do not mix variants of the same word ("sharable" and "shareable") within a
single text.

[Ballot comment]
General, nit:  I'm personally not a fan of the tagging in the text version to signal bold and italic text in the html version.  Especially when it occurs adjacent to formal naming/format language.

General, very small nit:  A mix of Principal and principal occur throughout the document.  Pick one.  (I'm assuming the RFC editor will flag this)

[Ballot discuss]
# Orie Steele, ART AD, comments for draft-ietf-jmap-sharing-07
CC @OR13

https://author-tools.ietf.org/api/idnits?url=https://www.ietf.org/archive/id/draft-ietf-jmap-sharing-07.txt&submitcheck=True

Thanks to the authors for this document, and to Arnt Gulbrandsen for the shepherd write up.

## Discuss

```
243   *  *id*: Id (immutable; server-set)
244       The id of the principal.
245   *  *type*: String
246       This MUST be one of the following values:
247       -  individual: This represents a single person.
248       -  group: This represents a group of people.
249       -  resource: This represents some resource, e.g., a projector.
250       -  location: This represents a location.
251       -  other: This represents some other undefined principal.
252   *  *name*: String
```

The repeated '*' make this section difficult to read, I initially assumed this syntax indicated the field is not optional.

After reviewing RFC8620, it seems to simply be a "bolding" / "emphasis" effect.

This section (and similar ones) contain many instances of "String" which is defined in https://datatracker.ietf.org/doc/html/rfc8620#section-1.1

As has been discussed on the list regarding a related document: https://mailarchive.ietf.org/arch/msg/jmap/nEumbk7DKcV6AOg6q-7yD_qetU0/

Unicode / i18n processing of these fields is possibly non trivial...

The document would be greatly improved by a section commenting on what kinds of JSON Strings / UTF-8 strings must remain supported.
Examples in an appendix demonstrating interesting edge cases / unicode characters might help.


```
310   *  *accountIds*: String[]
311       A list of account ids.  The Principal matches if any of the ids in
312       this list are keys in the Principal's "accounts" property (i.e.,
313       if any of the account ids belong to the principal).
```

Should this not be Id[] ? Is full UTF-8 equality check expected here?

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

Why not SHOULD or MUST? What happens if there is no limit?

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

Why not MUST? Should 362 say "unsubscribes" ?


```
439   *  *objectAccountId*: String
440       The objectAccountId value must be identical to the given value to
441       match the condition.
```

Should this be `*objectAccountId*: Id` ?

[Ballot comment]

## Comments

```
173   The server MAY reject the user's attempt to subscribe to some
174   resources even if they have permission to access them, e.g., a
175   calendar representing a location.
```

Can this be strengthened to a SHOULD with clear conditions for when the server MUST allow subscription?

```
177   A user may query the set of Principals they have access to with
178   "Principal/query" (see Section 2.4).  The Principal object may then
179   provide Account objects if the user has permission to access data for
180   that principal, even if they are not yet subscribed.
```

Can this be strengthened with normative language?
For example:
The Principle object MUST contain / provide when...
The Principle object MUST NOT contain / provide when...


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

Can this language be strengthened?

For example: When the server rejects updates it MUST use a SetError of type forbidden as described in Section 5.3 of RFC8620.


```
314   *  *email*: String
315       Looks for the text in the email property.
```

I suggest a stronger reference for IDNA compatible email identifiers.
There are many combinations of unicode characters that will not result in a valid email address.
Consider: https://datatracker.ietf.org/doc/html/rfc6531
If this field is not required to be a well formed email (possibly one build of an IDNA), perhaps note that directly.

```
318   *  *text* String
319       Looks for the text in the name, email, and description properties.
```

The use of the word text is slightly misleading here without inclusion of the charset, since strictly speaking this is filtering on octets (encoding some UTF-8 string), correct?

Thanks to Yaron Sheffer for his comments to this effect in the SEC DIR review.

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

Why not MUST? The way this is written, an implementation could easily decide to reverse these recommendations.

```
614 5.  Security Considerations
```

Please consider adding security considerations regarding deceptive use of unicode characters, perhaps drawing from previous work, for example from: https://datatracker.ietf.org/doc/html/rfc5894#section-1.4

"""
  The introduction of the larger repertoire of characters
  potentially makes the set of misspellings larger, especially given
  that in some cases the same appearance, for example on a business
  card, might visually match several Unicode code points or several
  sequences of code points.
"""

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

Why not MUST?

Is consent from existing principles required or recommended when adding new principles?


## Nits

```
536   "u12345678": {
537       "name": "jane.doe@example.com"
538       "isPersonal": true
539       "isReadOnly": false
540       "accountCapabilities": {
541           "urn:com.example:jmap:todo": {},
542           "urn:ietf:params:jmap:principals:owner": {
543               accountIdForPrincipal: "u33084183",
544               principalId: "P105aga511jaa"
545           }
546       }
547   }
```

This example is malformed JSON. accountIdForPrincipal and principalId are missing quotes, and the there is no indication of elision, consider starting with { ... "u12345678": ... }

Its also strange that "name" is an email in this example, consider an interesting unicode example like:

"Voß" or some user chosen string that includes emojis (just make sure they are black or white).

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

IANA has completed its review of draft-ietf-jmap-sharing-07. If any part of this review is inaccurate, please let us know.

IANA understands that, upon approval of this document, there are two actions which we must complete.

First, in the JMAP Capabilities registry in the JSON Meta Application Protocol (JMAP) registry group located at:

https://www.iana.org/assignments/jmap/

two new registrations will be made with intended use common as follows:

Capability Name: urn:ietf:params:jmap:principals
Intended Use: common
Change Controller: IETF
Security and Privacy Considerations: [ RFC-to-be; Section 5 ]
Reference: [ RFC-to-be ]

Capability Name: urn:ietf:params:jmap:principals:owner
Intended Use: common
Change Controller: IETF
Security and Privacy Considerations: [ RFC-to-be; Section 5 ]
Reference: [ RFC-to-be ]

As this document requests registrations in an Expert Review or Specification Required (see RFC 8126) registry, we have initiated the required Expert Review via a separate request. This review must be completed before the document's IANA state can be changed to "IANA OK."

Second, in the JMAP Data Type registry also in the JSON Meta Application Protocol (JMAP) registry group located at:

https://www.iana.org/assignments/jmap/

two new registrations will be made as follows:

Type Name: Principal
Can Reference Blobs: No
Can Use for State Change: Yes
Capability: urn:ietf:params:jmap:principals
Reference: [ RFC-to-be ]

Type Name: ShareNotification
Can Reference Blobs: No
Can Use for State Change: Yes
Capability: urn:ietf:params:jmap:principals
Reference: [ RFC-to-be ]

As this also requests registrations in an Expert Review or Specification Required (see RFC 8126) registry, we have initiated and completed the required Expert Review via a separate request.

We understand that these are the only actions required to be completed upon approval of this document.

NOTE: The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

For definitions of IANA review states, please see:

https://datatracker.ietf.org/help/state/draft/iana-review

Thank you,

David Dong
IANA Services Sr. Specialist

The following Last Call announcement was sent out (ends 2024-04-01):

From: The IESG
To: IETF-Announce
CC: arnt.gulbrandsen@icann.org, brong@fastmailteam.com, draft-ietf-jmap-sharing@ietf.org, jmap-chairs@ietf.org, jmap@ietf.org, superuser@gmail.com
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (JMAP Sharing) to Proposed Standard


The IESG has received a request from the JSON Mail Access Protocol WG (jmap)
to consider the following document: - 'JMAP Sharing'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2024-04-01. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This document specifies a data model for sharing data between users
  using JMAP.  Future documents can reference this one when defining
  data types to support a consistent model of sharing.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-jmap-sharing/



No IPR declarations have been submitted directly on this I-D.

# Document Shepherd Write-Up for jmap-sharing

## Document History

1. The WG consensus is broad; this document has the support of
  everyone who's written a draft or code.

2. The draft's progress was remarkably frictionless.

3. No appeal has been threatened, no discontent.

4. This document is not implementable in itself; it discusses how to
  share resources among different users in JMAP and defines a couple
  of things that will be common to all resources shared, but defines
  no resources that could be shared.

## Additional Reviews

5. The document does not relate to any other WGs or standards
  organizations.

6. This document requires security review, which I'm sure will be
  forthcoming.

7. There is no YANG module.

8. The document has been reviewed by several JMAP experts; automated
  checks are not applicable.

## Document Shepherd Checks

9. In my opinion, this document is needed, clearly written, complete,
  correctly designed, and ready to be handed off to the responsible
  Area Director.

10. I've read through the lists of common issues, and this document
    escapes.

11. Publication as Proposed Standard is requested. This is the proper
    type, since all of the JMAP standards are on the standards track
    and this document has not progressed further. Datatracker reflects
    this accurately.

12. Reasonable efforts have been made to remind all authors of the
    intellectual property rights (IPR) disclosure obligations
    described in [BCP 79][7]. As far as I know, all disclosures have
    been filed. I asked in person at the IETF meeting in Prague.

13. The author has shown his willingness to be listed as such.

14. I've run the idnits tool and applied skeptical eyeballs; the
    document looks flawless. In fact, I complimented the author.

15. All normative references should be normative; there are no
    informative references.

16. All normative references are freely available to anyone, network
    permitting.

17. There are no downward references.

18. There are no normative references to unready documents, etc.

19. The publication of this document will not change the status of
    anything.

20. The IANA considerations section requests the inclusion of two
    strings, which is well discussed in the body of the document. The
    body of the document discusses nothing more.

21. No designated expert is required.

# Document Shepherd Write-Up for jmap-sharing

## Document History

1. The WG consensus is broad; this document has the support of
  everyone who's written a draft or code.

2. The draft's progress was remarkably frictionless.

3. No appeal has been threatened, no discontent.

4. This document is not implementable in itself; it discusses how to
  share resources among different users in JMAP and defines a couple
  of things that will be common to all resources shared, but defines
  no resources that could be shared.

## Additional Reviews

5. The document does not relate to any other WGs or standards
  organizations.

6. This document requires security review, which I'm sure will be
  forthcoming.

7. There is no YANG module.

8. The document has been reviewed by several JMAP experts; automated
  checks are not applicable.

## Document Shepherd Checks

9. In my opinion, this document is needed, clearly written, complete,
  correctly designed, and ready to be handed off to the responsible
  Area Director.

10. I've read through the lists of common issues, and this document
    escapes.

11. Publication as Proposed Standard is requested. This is the proper
    type, since all of the JMAP standards are on the standards track
    and this document has not progressed further. Datatracker reflects
    this accurately.

12. Reasonable efforts have been made to remind all authors of the
    intellectual property rights (IPR) disclosure obligations
    described in [BCP 79][7]. As far as I know, all disclosures have
    been filed. I asked in person at the IETF meeting in Prague.

13. The author has shown his willingness to be listed as such.

14. I've run the idnits tool and applied skeptical eyeballs; the
    document looks flawless. In fact, I complimented the author.

15. All normative references should be normative; there are no
    informative references.

16. All normative references are freely available to anyone, network
    permitting.

17. There are no downward references.

18. There are no normative references to unready documents, etc.

19. The publication of this document will not change the status of
    anything.

20. The IANA considerations section requests the inclusion of two
    strings, which is well discussed in the body of the document. The
    body of the document discusses nothing more.

21. No designated expert is required.