JMAP B. Gondwana, Ed. Internet-Draft Fastmail Updates: 8620 (if approved) 2 November 2024 Intended status: Standards Track Expires: 6 May 2025 JMAP File Storage extension draft-gondwana-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 6 May 2025. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. Gondwana Expires 6 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 . . . . . . . . . . . . . . . . . 3 4. Filenode Data Type . . . . . . . . . . . . . . . . . . . . . 3 4.1. Filenode objects . . . . . . . . . . . . . . . . . . . . 4 4.2. Filenode Methods . . . . . . . . . . . . . . . . . . . . 5 4.2.1. Filenode/set . . . . . . . . . . . . . . . . . . . . 5 4.2.2. Filenode/get . . . . . . . . . . . . . . . . . . . . 6 4.2.3. Filenode/changes . . . . . . . . . . . . . . . . . . 6 4.2.4. Filenode/query . . . . . . . . . . . . . . . . . . . 6 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" . . . 9 6.3. JMAP Data Types registration for "Filenode" . . . . . . . 10 7. TODO . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 8. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 10. Normative References . . . . . . . . . . . . . . . . . . . . 11 11. Informative References . . . . . . . . . . . . . . . . . . . 11 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 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 6 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: * TODO: limits 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. Gondwana Expires 6 May 2025 [Page 3] Internet-Draft JMAP Filenode November 2024 4.1. Filenode objects The filenode object has the following keys: * id: Id (server-set) the Id of this node * 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 has no data (the empty file, or a collection) * size: Number (server-set) the size in bytes of the associated blob data. This must be 0 if the blobId is null. * name: String User-visible name for the FileNode, This can be any UTF-8 string of at least 1 character in length, except: - The name MUST be unique for all Filenodes with the same parentId. - The name MUST NOT be "." or ".." - The name MUST NOT contain a "/" A server MAY limit the name length and will return an invalidProperties error if this limit is exceeded. * 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. * created: UTCDate The date the node was created. * modifed: UTCDate Gondwana Expires 6 May 2025 [Page 4] Internet-Draft JMAP Filenode November 2024 The date the node was last updated. * accessed: UTCDate The date the node was last accessed. NOTE: this is not updated by the server, clients must store a new value if they want to use this. It is recommended to NOT use this field, or to only lazily update it when making other changes to the server. * executable: Boolean 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: - 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) Gondwana Expires 6 May 2025 [Page 5] Internet-Draft JMAP Filenode November 2024 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. 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: Number|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 Gondwana Expires 6 May 2025 [Page 6] Internet-Draft JMAP Filenode November 2024 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: Date The creation date of the node (as returned on the Filenode object) must be before this date to match the condition. * createdAfter: Date The creation date of the node (as returned on the Filenode object) must be on or after this date to match the condition. * modifiedBefore: Date The modified date of the node (as returned on the Filenode object) must be before this date to match the condition. * modifiedAfter: Date The modified date of the node (as returned on the Filenode object) must be on or after this date to match the condition. * accessedBefore: Date The accessed date of the node (as returned on the Filenode object) must be before this date to match the condition. * accessedAfter: Date The accessed date of the node (as returned on the Filenode object) must be on or after this date to match the condition. * minSize: Number Gondwana Expires 6 May 2025 [Page 7] Internet-Draft JMAP Filenode November 2024 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: Number 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 * typeMatch: String Does a glob match of the specified type against the _type_ property of the node. It also supports the following sort properties: * name: Sort by name only * 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: Gondwana Expires 6 May 2025 [Page 8] Internet-Draft JMAP Filenode November 2024 Sort directories first, AND sort by media type for files * executable: Sort non-executable files first * created: Sort by creation time * modified: Sort by modification time * accessed: Sort by access time 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 6.2. JMAP Error Codes registration for "nodeHasChildren" IANA is requested to register the "nodeHasChildren" JMAP Error Code as follows: Gondwana Expires 6 May 2025 [Page 9] Internet-Draft JMAP Filenode November 2024 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 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-gondwana-jmap-filenode-00* * initial proposal Gondwana Expires 6 May 2025 [Page 10] Internet-Draft JMAP Filenode November 2024 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, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, DOI 10.17487/RFC4918, June 2007, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 2019, . 11. Informative References [I-D.ietf-jmap-calendars] Jenkins, N. and M. Douglass, "JMAP for Calendars", Work in Progress, Internet-Draft, draft-ietf-jmap-calendars-20, 21 July 2024, . [I-D.ietf-jmap-contacts] Jenkins, N., "JMAP for Contacts", Work in Progress, Internet-Draft, draft-ietf-jmap-contacts-10, 6 June 2024, . [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, . Gondwana Expires 6 May 2025 [Page 11] Internet-Draft JMAP Filenode November 2024 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, DOI 10.17487/RFC5545, September 2009, . [RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV)", RFC 6352, DOI 10.17487/RFC6352, August 2011, . 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 6 May 2025 [Page 12]