JMAP File Storage extension
draft-ietf-jmap-filenode-00
| Document | Type | Active Internet-Draft (jmap WG) | |
|---|---|---|---|
| Author | Bron Gondwana | ||
| Last updated | 2024-12-01 (Latest revision 2024-11-21) | ||
| Replaces | draft-gondwana-jmap-filenode | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Intended RFC status | Proposed Standard | ||
| Formats | |||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | WG Document | |
| Document shepherd | (None) | ||
| IESG | IESG state | I-D Exists | |
| Consensus boilerplate | Yes | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-ietf-jmap-filenode-00
JMAP B. Gondwana, Ed.
Internet-Draft Fastmail
Updates: 8620 (if approved) 22 November 2024
Intended status: Standards Track
Expires: 26 May 2025
JMAP File Storage extension
draft-ietf-jmap-filenode-00
Abstract
The JMAP base protocol (RFC8620) provides the ability to upload and
download arbitrary binary data. This binary data is called a "blob",
and can be used in all other JMAP extensions.
This extension adds a method to expose blobs as a filesystem along
with the types of metadata that are provided by other remote
filesystem protocols.
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 26 May 2025.
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
Gondwana Expires 26 May 2025 [Page 1]
Internet-Draft JMAP FileNode November 2024
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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions Used In This Document . . . . . . . . . . . . . . 3
3. Addition to the Capabilities Object . . . . . . . . . . . . . 3
3.1. urn:ietf:params:jmap:filenode . . . . . . . . . . . . . . 3
3.1.1. Capability Example . . . . . . . . . . . . . . . . . 4
4. FileNode Data Type . . . . . . . . . . . . . . . . . . . . . 4
4.1. FileNode objects . . . . . . . . . . . . . . . . . . . . 4
4.2. FileNode Methods . . . . . . . . . . . . . . . . . . . . 6
4.2.1. FileNode/set . . . . . . . . . . . . . . . . . . . . 6
4.2.2. FileNode/get . . . . . . . . . . . . . . . . . . . . 6
4.2.3. FileNode/changes . . . . . . . . . . . . . . . . . . 6
4.2.4. FileNode/query . . . . . . . . . . . . . . . . . . . 7
4.2.5. FileNode/queryChanges . . . . . . . . . . . . . . . . 9
5. Security considerations . . . . . . . . . . . . . . . . . . . 9
6. IANA considerations . . . . . . . . . . . . . . . . . . . . . 9
6.1. JMAP Capability registration for "filenode" . . . . . . . 9
6.2. JMAP Error Codes registration for "nodeHasChildren" . . . 10
6.3. JMAP Data Types registration for "FileNode" . . . . . . . 10
7. TODO . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
8. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11
10. Normative References . . . . . . . . . . . . . . . . . . . . 11
11. Informative References . . . . . . . . . . . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction
JMAP ([RFC8620] — (U+2014) JSON Meta Application Protocol) is a
generic protocol for synchronizing data 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.
In the same way that JMAP Calendars ([I-D.ietf-jmap-calendars])
replaces CalDAV ([RFC5545]) and JMAP Contacts
([I-D.ietf-jmap-contacts]) replaces CardDAV ([RFC6352]), this
document replaces the use of WebDAV ([RFC4918]) for remote filesystem
access.
Gondwana Expires 26 May 2025 [Page 2]
Internet-Draft JMAP FileNode November 2024
2. Conventions Used In This Document
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.
The definitions of JSON keys and datatypes in the document follow the
conventions described in the core JMAP specification [RFC8620].
3. Addition to the Capabilities Object
The capabilities object is returned as part of the JMAP Session
object; see [RFC8620], Section 2.
This document defines an additional capability URI.
3.1. urn:ietf:params:jmap:filenode
The capability urn:ietf:params:jmap:filenode being present in the
"accountCapabilities" property of an account represents support for
the FileNode datatype. Servers that include the capability in one or
more "accountCapabilities" properties MUST also include the property
in the "capabilities" property.
The value of this property in the JMAP session "capabilities"
property MUST be 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:
* maxFileNodeDepth: "UnsignedInt|null"
The maximum depth of the FileNode hierarchy (i.e., one more than
the maximum number of ancestors a FileNode may have), or null for
no limit.
* maxSizeFileNodeName: "UnsignedInt":
The maximum length, in (UTF-8) octets, allowed for the name of a
FileNode. This MUST be at least 100, although it is recommended
servers allow more.
* fileNodeQuerySortOptions: "String[]"
Gondwana Expires 26 May 2025 [Page 3]
Internet-Draft JMAP FileNode November 2024
A list of all the values the server supports for the "property"
field of the Comparator object in an "FileNode/query" sort (see
Section XXX). This MAY include properties the client does not
recognise (for example, custom properties specified in a vendor
extension). Clients MUST ignore any unknown properties in the
list.
* mayCreateTopLevelFileNode: "Boolean"
If true, the user may create a FileNode (see Section XXX) in this
account with a null parentId. (Permission for creating a child of an
existing FileNode is given by the "myRights" property on that
FileNode.)
3.1.1. Capability Example
TODO
4. FileNode Data Type
A FileNode is a set of metadata which behaves similar to an inode in
a filesystem. In [RFC4918] terminology a FileNode can refer to
either a collection or a resource.
The following JMAP Methods are selected by the
urn:ietf:params:jmap:filenode capability.
4.1. FileNode objects
The filenode object has the following keys:
* id: "Id" (immutable; server-set)
The Id of the FileNode.
* parentId: "Id|null"
The Id of the parent node, or null if this is the root node.
* blobId: "Id|null"
The blobId for the content of this node, or null if this node is a
collection. NOTE the zero byte file MUST have a non-null blobId.
* size: "UnsignedInt|null" (server-set)
The size in bytes of the associated blob data. This must be null
if, and only if, the blobId is null.
Gondwana Expires 26 May 2025 [Page 4]
Internet-Draft JMAP FileNode November 2024
* name: "String"
User-visible name for the FileNode. This MUST be a Net-Unicode
string [RFC5198] of at least 1 character in length, subject to the
maximum size given in the capability object. There MUST NOT be
two sibling Mailboxes with both the same parent and the same name.
Servers MAY reject names that violate server policy (e.g., names
containing control characters). Further:
- The name MUST NOT be "." or ".."
- The name MUST NOT contain a "/"
* type: "String|null"
The media type of the FileNode. This MUST be null if, and only
if, the node does not have a blobId.
Valid values are found in the IANA media-types registry.
Servers MUST NOT reject media types that are not recognised.
Servers MUST reject media types if the value does not conform to
the ABNF of [RFC6938] Section 4.2.
* created: "UTCDate" (default: current server time)
The date the node was created.
* modified: "UTCDate" (default: current server time)
The date the node was last updated. NOTE: this is not updated by
the server, clients must store a new value when making changes.
* accessed: "UTCDate" (default: current server time)
The date the node was last accessed. NOTE: this is not updated by
the server, clients must store a new value. See Implementation
Considerations for comments on the use of this field.
* executable: "Boolean" (default: false)
If true, the file is should be treated as an executable by
operating systems that support this flag.
* myRights: "FilesRights" (server-set)
The set of rights (ACLs) the user has in relation to this folder.
A *FilesRights* object has the following properties:
Gondwana Expires 26 May 2025 [Page 5]
Internet-Draft JMAP FileNode November 2024
- mayRead: Boolean The user may read the contents of this node.
- mayWrite: Boolean The user may modify the properties of this
node, including renaming children.
- mayAdmin: Boolean The user may change the sharing of this node
(see [I-D.ietf-jmap-sharing])
* shareWith: "String[FilesRights]|null"
A map of userId to rights for users this node is shared with. The
owner of the node MUST NOT be in this set. This is null if the
user requesting the object does not have myRights.mayAdmin, or if
the node is not shared with anyone.
4.2. FileNode Methods
4.2.1. FileNode/set
This is a standard Foo/set method, except for some things:
An additional top level argument:
* onDestroyRemoveChildren: "Boolean" (default: false)
If false, an attempt to destroy a FileNode which is the parentId of
another FileNode will be rejected with a nodeHasChildren error.
NOTE: if the other nodes are also been destroyed in the same
operation, then the server MUST NOT return this error. Servers must
either sort the destroys children before parents, or only check this
constraint on the final state, remembering that JMAP set operations
must be atomic.
If true, then all child nodes will also be destroyed when a node is
destroyed.
Further, since parentId creates a tree structure, an attempt to move
a node to a parent for which this node is also an ancestor is an
error, and an invalidProperties error will be returned.
4.2.2. FileNode/get
This is a standard Foo/get method.
4.2.3. FileNode/changes
This is a standard Foo/changes method.
Gondwana Expires 26 May 2025 [Page 6]
Internet-Draft JMAP FileNode November 2024
4.2.4. FileNode/query
This is a standard Foo/query method except for the following:
There's one more property to the query:
* depth: "UnsignedInt|null"
The number of levels of subdiretories to recurse into. If absent,
null, or zero, do not recurse.
The following filter criteria are defined:
* hasParentId: "Boolean"
If true, the node must have a non-null parentId (i.e. is not a
root node).
* parentId: "Id"
A FileNode id. A node must have a parentId equal to this to match
the condition.
* ancestorId: "Id"
A FileNode id. A node must have an ancestor (parent, parent of
parent, etc.) with an id equal to this to to match the condition.
* hasType: "Boolean"
If true, the FileNode must be a file/resource, not a directory/
collection.
* blobId: "Id"
A FileNode must have a blobId equal to this to match the
condition.
* isExecutable: "Boolean"
If true, the FileNode must have a true executable value.
* createdBefore: "UTCDate"
The creation date of the node (as returned on the FileNode object)
must be before this date to match the condition.
* createdAfter: "UTCDate"
Gondwana Expires 26 May 2025 [Page 7]
Internet-Draft JMAP FileNode November 2024
The creation date of the node (as returned on the FileNode object)
must be on or after this date to match the condition.
* modifiedBefore: "UTCDate"
The modified date of the node (as returned on the FileNode object)
must be before this date to match the condition.
* modifiedAfter: "UTCDate"
The modified date of the node (as returned on the FileNode object)
must be on or after this date to match the condition.
* accessedBefore: "UTCDate"
The accessed date of the node (as returned on the FileNode object)
must be before this date to match the condition.
* accessedAfter: "UTCDate"
The accessed date of the node (as returned on the FileNode object)
must be on or after this date to match the condition.
* minSize: "UnsignedInt"
The size of the node in bytes (as returned on the FileNode object)
must be equal to or greater than this number to match the
condition.
* maxSize: "UnsignedInt"
The size of the node in bytes (as returned on the FileNode object)
must be less than this number to match the condition.
* name: "String"
A FileNode must have exactly the same octets in its name property
to match the condition.
* nameMatch: "String"
Does a glob match of the specified name against the _name_
property of the node.
* type: "String"
A FileNode must have exactly the same octets in its type property
to match the condition
Gondwana Expires 26 May 2025 [Page 8]
Internet-Draft JMAP FileNode November 2024
* typeMatch: "String"
Does a glob match of the specified type against the _type_
property of the node.
It also supports the following additional sort properties:
* tree:
Sort by tree; which means by name, but any directory/collection
node is immediately followed by the recursive application of the
same sort to its child nodes. This is similar to the output of
the find command on a filesystem with the depth parameter provided
above.
* hasType:
Sort directories before files (false sorts before true)
* type:
Sorts directories first, and sorts by media type for files
4.2.5. FileNode/queryChanges
This is a standard Foo/queryChanges method.
5. Security considerations
TODO: lots of "filesystems are risky" - I guess look at the
referenced RFCs and what they said.
6. IANA considerations
6.1. JMAP Capability registration for "filenode"
IANA is requested to register the "filenode" JMAP Capability as
follows:
Capability Name: urn:ietf:params:jmap:filenode
Specification document: this document
Intended use: common
Change Controller: IETF
Security and privacy considerations: this document, Section XXX
Gondwana Expires 26 May 2025 [Page 9]
Internet-Draft JMAP FileNode November 2024
6.2. JMAP Error Codes registration for "nodeHasChildren"
IANA is requested to register the "nodeHasChildren" JMAP Error Code
as follows:
JMAP Error Code: nodeHasChildren
Intended use: common
Change Controller: IETF
Description: The node being destroyed is still referenced by other
nodes which have not been destroyed.
Reference: this document
6.3. JMAP Data Types registration for "FileNode"
IANA is requested to register the "FileNode" JMAP Data Type as
follows:
Type Name: FileNode
Can Reference Blobs: Yes
Can Use For State Change: Yes
Capability: urn:ietf:params:jmap:filenode
Reference: this document
7. TODO
* support SYMLINK types [RFC4437]
* design and document the capabilities object
* create real-world clients to test this
* security considerations
* a way to get or query all ancestor nodes
* QUESTION: should all the file-related fields be embedded in a sub-
object? There's lots of "must be NULL if and only-if this other
field is also NULL" - we could enforce that more easily with a
sub-object.
Gondwana Expires 26 May 2025 [Page 10]
Internet-Draft JMAP FileNode November 2024
* We need to address how shareWith and myRights expiration are done;
because both a potential fullPath and the real myRights depend on
changes to parent nodes.
8. Changes
EDITOR: please remove this section before publication.
The source of this document exists on github at:
https://github.com/brong/draft-gondwana-jmap-filenode/
(https://github.com/brong/draft-gondwana-jmap-filenode/)
*draft-ietf-jmap-filenode-00*
* upload as a working group document
*draft-gondwana-jmap-filenode-01*
* require a blobId for the zero-byte file
* make size also null for collections
* add more to the TODO section
* bikeshed; FileNode
* correct UTCDate, UnsignedInt, and normalised UTF-8.
* add some fields to the capabilities object
*draft-gondwana-jmap-filenode-00*
* initial proposal
9. Acknowledgements
Neil Jenkins and the JMAP working group at the IETF.
10. Normative References
[I-D.ietf-jmap-sharing]
Jenkins, N., "JMAP Sharing", Work in Progress, Internet-
Draft, draft-ietf-jmap-sharing-09, 17 April 2024,
<https://datatracker.ietf.org/doc/html/draft-ietf-jmap-
sharing-09>.
[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>.
Gondwana Expires 26 May 2025 [Page 11]
Internet-Draft JMAP FileNode November 2024
[RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed
Authoring and Versioning (WebDAV)", RFC 4918,
DOI 10.17487/RFC4918, June 2007,
<https://www.rfc-editor.org/info/rfc4918>.
[RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network
Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008,
<https://www.rfc-editor.org/info/rfc5198>.
[RFC6938] Scudder, J., "Deprecation of BGP Path Attributes: DPA,
ADVERTISER, and RCID_PATH / CLUSTER_ID", RFC 6938,
DOI 10.17487/RFC6938, May 2013,
<https://www.rfc-editor.org/info/rfc6938>.
[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>.
[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>.
11. Informative References
[I-D.ietf-jmap-calendars]
Jenkins, N. and M. Douglass, "JSON Meta Application
Protocol (JMAP) for Calendars", Work in Progress,
Internet-Draft, draft-ietf-jmap-calendars-22, 13 November
2024, <https://datatracker.ietf.org/doc/html/draft-ietf-
jmap-calendars-22>.
[I-D.ietf-jmap-contacts]
Jenkins, N., "JMAP for Contacts", Work in Progress,
Internet-Draft, draft-ietf-jmap-contacts-10, 6 June 2024,
<https://datatracker.ietf.org/doc/html/draft-ietf-jmap-
contacts-10>.
[RFC4437] Whitehead, J., Clemm, G., and J. Reschke, Ed., "Web
Distributed Authoring and Versioning (WebDAV) Redirect
Reference Resources", RFC 4437, DOI 10.17487/RFC4437,
March 2006, <https://www.rfc-editor.org/info/rfc4437>.
[RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)",
RFC 5545, DOI 10.17487/RFC5545, September 2009,
<https://www.rfc-editor.org/info/rfc5545>.
Gondwana Expires 26 May 2025 [Page 12]
Internet-Draft JMAP FileNode November 2024
[RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web Distributed
Authoring and Versioning (WebDAV)", RFC 6352,
DOI 10.17487/RFC6352, August 2011,
<https://www.rfc-editor.org/info/rfc6352>.
Author's Address
Bron Gondwana (editor)
Fastmail
Level 2, 114 William St
Melbourne VIC 3000
Australia
Email: brong@fastmailteam.com
URI: https://www.fastmail.com
Gondwana Expires 26 May 2025 [Page 13]