RFC 9404

JSON Meta Application Protocol (JMAP) Blob Management Extension

📅 published August 2023, from ietf

RFC 9404: JMAP Blob Management Extension 💖

Okay bestie, let's start with the header tea ☕ This is RFC 9404, the JSON Meta Application Protocol (JMAP) Blob Management Extension 🎀. B. Gondwana, Ed. from Fastmail wrote it, it's dated August 2023, it's a Standards Track doc, and its ISSN is 2070-1721 ✨. It updates RFC 8620 🔥. The header doesn't have an Obsoletes line, so nothing gets replaced here.

Abstract ✨

Okay so the JMAP base protocol (RFC 8620) already lets you upload and download arbitrary binary data with HTTP POST and GET on one endpoint 📦. That binary data is called a "blob" 🫧.

This extension adds more ways to create and access blobs by making inline method calls inside a normal JMAP request 💅. It also adds a reverse lookup so you can find out where blobs are referenced from other data types 🔍. Iconic 👑

Status of This Memo 🌸

This is an Internet Standards Track document 🦋.

It's a product of the Internet Engineering Task Force (IETF) 🌈. It represents the consensus of the IETF community, it got public review, and the Internet Engineering Steering Group (IESG) approved it for publication ✅. More info on Internet Standards is in Section 2 of RFC 7841 📚.

For the current status, any errata, and how to give feedback, go to https://www.rfc-editor.org/info/rfc9404 🔗.

Copyright (c) 2023 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) as they stand on the publication date. Please actually read these, because they describe your rights and restrictions for this document 📜. Code Components pulled out of this document must include Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Revised BSD License 🫶.

Table of Contents 🗺️

1.  Introduction
2.  Conventions Used in This Document
3.  Addition to the Capabilities Object
  3.1.  urn:ietf:params:jmap:blob
    3.1.1.  Capability Example
4.  Blob Methods
  4.1.  Blob/upload
    4.1.1.  Blob/upload Simple Example
    4.1.2.  Blob/upload Complex Example
  4.2.  Blob/get
    4.2.1.  Blob/get Simple Example
    4.2.2.  Blob/get Example with Range and Encoding Errors
  4.3.  Blob/lookup
    4.3.1.  Blob/lookup Example
5.  Security Considerations
6.  IANA Considerations
  6.1.  JMAP Capability Registration for "blob"
  6.2.  JMAP Error Codes Registration for "unknownDataType"
  6.3.  Creation of "JMAP Data Types" Registry
7.  References
  7.1.  Normative References
  7.2.  Informative References
Acknowledgements
Author's Address

1. Introduction 🧚

Sometimes JMAP [RFC8620] interactions need you to create a blob and then reference it 🫧. Just like IMAP literals got extended by [RFC7888], you can embed small blobs directly in the JMAP method calls array, which can cut down on round trips 🏃‍♀️💨.

When you're fetching an object, it's also handy to grab that object's raw content without another round trip 🍓.

Since raw blobs can hold arbitrary binary data, this document defines a use of the base64 coding from [RFC4648] for both creating and fetching blob data 🔐.

When JMAP gets proxied through a system that adds its own access restrictions, it can be useful to know which objects reference a particular blob 🕵️‍♀️. This document defines a way to discover those references 💖.

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" are to be read as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, just like shown here 💅. Otherwise they're just regular words, babe.

The definitions of JSON keys and datatypes in this document follow the conventions in [RFC8620] 🧾.

3. Addition to the Capabilities Object 🎀

The capabilities object comes back as part of the JMAP Session object. See [RFC8620], Section 2 🔍.

This document defines one extra capability URI ✨.

3.1. urn:ietf:params:jmap:blob 🫧

Okay, so if the capability urn:ietf:params:jmap:blob shows up in an account's accountCapabilities property, it means the server supports extra API methods on the Blob datatype 🙌. Servers that include the capability in one or more accountCapabilities properties MUST also include it 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 info about the server's capabilities and permissions for that account 📋:

  • maxSizeBlobSet: "UnsignedInt|null"

This is the maximum size of a blob (in octets) that the server will let you create. It includes blobs made by concatenating multiple data sources together 📏.

Clients MUST NOT attempt to create blobs larger than this size 🚫.

If this value is null, clients don't have to limit the size of the blobs they try to create. Servers can still reject a creation whatever the size, for example because of low disk space or per-user rate limits 💀.

  • maxDataSources: "UnsignedInt"

This is the maximum number of DataSourceObjects allowed per creation in a Blob/upload 🧩.

Servers MUST allow at least 64 DataSourceObjects per creation 💪.

  • supportedTypeNames: "String[]"

This is an array of data type names that are supported for Blob/lookup. If the server doesn't support lookups, this will be an empty list 🫥.

The supportedTypeNames list may include private types that aren't in the "JMAP Data Types" registry defined by this document 🕶️. Clients MUST ignore type names they don't recognise 🙈.

  • supportedDigestAlgorithms: "String[]"

This is an array of supported digest algorithms for Blob/get. If the server can't calculate blob digests, this will be an empty list 🧮. Algorithms in this list MUST be present in the "HTTP Digest Algorithm Values" registry defined by [RFC3230]. In JMAP, though, they must be lowercased, e.g., "md5" rather than "MD5" 🔡.

Clients SHOULD prefer algorithms that appear earlier in this list ⭐.

3.1.1. Capability Example 🌷

{
  "capabilities": {
    ...,
    "urn:ietf:params:jmap:blob": {}
  },
  "accounts": {
    "A13842": {
      ...
      "accountCapabilities": {
        "urn:ietf:params:jmap:blob": {
          "maxSizeBlobSet": 50000000,
          "maxDataSources": 100,
          "supportedTypeNames" : [
            "Mailbox",
            "Thread",
            "Email"
          ],
          "supportedDigestAlgorithms" : [
            "sha",
            "sha-256"
          ]
        }
      }
    }
  }
}

4. Blob Methods 🦋

A blob is a sequence of zero or more octets 🫧.

JMAP [RFC8620] defines the Blob/copy method. This spec doesn't change it, and it's selected by the urn:ietf:params:jmap:core capability 🧠.

The following JMAP methods are selected by the urn:ietf:params:jmap:blob capability 🎯.

4.1. Blob/upload 📤

This is kind of similar to a Foo/set in [RFC8620] 👯. But blobs can't be updated or deleted, so only create is allowed in the method call 🚫✏️. Blobs also don't have state, so there's no state field in the method response 🫥.

Parameters 🎀

  • accountId: "Id"

This is the id of the account where the blobs will be created 🏠.

  • create: "Id[UploadObject]"

This is a map of creation id to UploadObjects 🗂️.

Result ✨

The result is the same as for Foo/set in [RFC8620], with created and notCreated objects mapping from the creation id 💅.

The created objects contain:

  • id: "Id"

This is the blobId that was created 🆔.

  • type: "String|null"

This is the media type as given in the creation, if there was one. If none was provided, the server MAY do content analysis and return one of the following: the calculated value, application/octet-string, or null 🕵️‍♀️.

  • size: "UnsignedInt"

As per [RFC8620], this is the size of the created blob in octets 📏.

The created objects will also contain any other properties identical to the ones that would come back in the JSON response of the upload endpoint described in [RFC8620]. This might get extended in the future. In this document, implementations are expected to extend both the upload endpoint and the Blob/upload responses the same way 🔮.

If a creation has a problem, the server returns a notCreated response with a map from the failed creation id to a SetError object 🙅‍♀️.

For each successful upload, servers MUST add an entry to the createdIds map ([RFC8620], Section 3.3) for the request. Even if the caller didn't explicitly pass a createdIds, the value must be available to later methods defined in the same Request Object 🔗. This lets you use the blobId through a back-reference in later method calls 🪄.

The created blob has the same lifetime and expiry semantics as any other binary object created through the mechanism in [RFC8620], Section 6 ⏳.

Uploads through this mechanism are restricted by the maxUploadSize limit for JMAP requests that the server specifies, and clients SHOULD consider using the upload mechanism defined by [RFC8620] for blobs bigger than a megabyte 🏋️‍♀️.

UploadObject 📦

  • data: "DataSourceObject[]"

This is an array of zero or more octet sources, in order (zero creates an empty blob). The result of each source is concatenated in order to create the blob 🧵.

  • type: "String|null" (default: null)

This is a hint for the media type of the data 💭.

DataSourceObject 🧩

Exactly one of these:

  • data:asText: "String|null" (raw octets, must be UTF-8)
  • data:asBase64: "String|null" (base64 representation of octets)

...or a blobId source, which has:

  • blobId: "Id"
  • offset: "UnsignedInt|null" (MAY be zero)
  • length: "UnsignedInt|null" (MAY be zero)

If offset is null, then it's assumed to be zero 0️⃣.

If length is null, then it's the remaining octets in the blob 🧃.

If the range can't be fully satisfied (i.e., it begins or extends past the end of the data in the blob), then the DataSourceObject is invalid and results in a notCreated response for this creation id 💔.

If the data properties have any invalid references or invalid data inside them, the server MUST NOT guess the user's intent. It MUST reject the creation and return a notCreated response for that creation id. Don't play guessing games, server. 🚨

Likewise, invalid characters in the base64 of data:asBase64, or invalid UTF-8 in data:asText, MUST result in a notCreated response ⚠️.

The DataSourceObject definition might get extended in the future, for example to fetch external content 🌍.

A server MUST accept at least 64 DataSourceObjects per create, as described in Section 3.1 of this document 💯.

4.1.1. Blob/upload Simple Example ✨

Okay bestie, heads up 💖 the data:asBase64 field is split over a few lines here only so it fits on the page 🫶. On the actual wire it's one long continuous string with no line breaks, so don't panic if your copy looks different 😭.

Method Call:

[
 "Blob/upload",
 {
  "accountId": "account1",
  "create": {
   "1": {
    "data" : [
    {
     "data:asBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKA
                       AAAA1BMVEX/AAAZ4gk3AAAAAXRSTlN/gFy0ywAAAApJRE
                       FUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
    }
   ],
   "type": "image/png"
   }
  }
 },
 "R1"
]

Response:

[
  "Blob/upload",
  {
    "accountId" : "account1",
    "created" : {
      "1": {
        "id" : "G4c6751edf9dd6903ff54b792e432fba781271beb",
        "type" : "image/png",
        "size" : 95
      }
    }
  },
  "R1"
]

4.1.2. Blob/upload Complex Example 🎀

Now the fancy one 🦋 this time we chain a couple of uploads together. The CAT blob pulls pieces out of b4 by pointing at it with #b4, mixes in some raw text and base64, and then we ask for it back with Blob/get 🧚

Method Calls:

[
 [
  "Blob/upload",
  {
   "create": {
    "b4": {
     "data": [
      {
       "data:asText": "The quick brown fox jumped over the lazy dog."
      }
     ]
    }
   }
  },
  "S4"
 ],
 [
   "Blob/upload",
   {
    "create": {
      "cat": {
        "data": [
          {
            "data:asText": "How"
          },
          {
            "blobId": "#b4",
            "length": 7,
            "offset": 3
          },
          {
            "data:asText": "was t"
          },
          {
            "blobId": "#b4",
            "length": 1,
            "offset": 1
          },
          {
            "data:asBase64": "YXQ/"
          }
        ]
      }
    }
   },
   "CAT"
 ],
 [
   "Blob/get",
   {
    "properties": [
      "data:asText",
      "size"
    ],
    "ids": [
      "#cat"
    ]
   },
   "G4"
  ]
]

Responses:

[
  [
    "Blob/upload",
    {
      "oldState": null,
      "created": {
        "b4": {
          "id": "Gc0854fb9fb03c41cce3802cb0d220529e6eef94e",
          "size": 45,
          "type": "application/octet-stream"
        }
      },
      "notCreated": null,
      "accountId": "account1"
    },
    "S4"
  ],
  [
    "Blob/upload",
    {
      "oldState": null,
      "created": {
        "cat": {
          "id": "Gcc60576f036321ae6e8037ffc56bdee589bd3e23",
          "size": 19,
          "type": "application/octet-stream"
        }
      },
      "notCreated": null,
      "accountId": "account1"
    },
    "CAT"
  ],
  [
    "Blob/get",
    {
      "list": [
        {
          "id": "Gcc60576f036321ae6e8037ffc56bdee589bd3e23",
          "data:asText": "How quick was that?",
          "size": 19
        }
      ],
      "notFound": [],
      "accountId": "account1"
    },
    "G4"
  ]
]

4.2. Blob/get 🍓

Blob/get is a standard JMAP get 💅 with two extra optional parameters on top:

  • offset: "UnsignedInt|null"

Start this many octets into the blob data. If null or unspecified, this defaults to zero.

  • length: "UnsignedInt|null"

Return at most this many octets of the blob data. If null or unspecified, then all remaining octets in the blob are returned. This can be considered equivalent to an infinitely large length value, except that the isTruncated warning is not given unless the start offset is past the end of the blob.

Request Properties:

Any of:

  • data:asText
  • data:asBase64
  • data (returns data:asText if the selected octets are valid UTF-8 or data:asBase64)
  • digest:<algorithm> (where <algorithm> is one of the named algorithms in the supportedDigestAlgorithms capability)
  • size

If not given, the properties default to data and size. 🌸

Result Properties:

  • data:asText: "String|null"

The raw octets of the selected range if they are valid UTF-8; otherwise, null.

  • data:asBase64: "String"

The base64 encoding of the octets in the selected range.

  • digest:<algorithm>: "String"

The base64 encoding of the digest of the octets in the selected range, calculated using the named algorithm.

  • isEncodingProblem: "Boolean" (default: false)
  • isTruncated: "Boolean" (default: false)
  • size: "UnsignedInt"

The number of octets in the entire blob.

The size value MUST always be the number of octets in the underlying blob, regardless of offset and length. Lowkey the most important rule in this whole section 📏✨

The data fields hold a representation of the octets inside the selected range that are actually present in the blob. If the octets selected are not valid UTF-8 (including cutting off in the middle of a multi-octet sequence) and data or data:asText was requested, then the key isEncodingProblem MUST be set to true, and the data:asText response value MUST be null. In the case where data was requested and the data is not valid UTF-8, then data:asBase64 MUST be returned. 🙈

If the selected range asks for data outside the blob (so the offset+length is bigger than the blob), then the result is either just the octets from the offset to the end of the blob, or an empty string if the offset is past the end of the blob. Either way, the isTruncated property in the result MUST be set to true to tell the client that the requested range could not be fully satisfied. If digest was requested, any digest is calculated on the octets that would be returned for a data field. 💀

Servers SHOULD store the size for blobs in a format that is efficient to read, and clients SHOULD limit their request to just the size parameter if that is all they need, as fetching blob content could be significantly more expensive and slower for the server. 🫶

4.2.1. Blob/get Simple Example 🦋

In this example, a blob containing the string "The quick brown fox jumped over the lazy dog." has blobId Gc0854fb9fb03c41cce3802cb0d220529e6eef94e. 🧚

The first method call only asks for the size across multiple blobs, and the second asks for both the size and a short range of the data for one of the blobs. Iconic multitasking 👑

Method Calls:

[
  [
    "Blob/get",
    {
      "accountId" : "account1",
      "ids" : [
        "Gc0854fb9fb03c41cce3802cb0d220529e6eef94e",
        "not-a-blob"
      ],
      "properties" : [
        "data:asText",
        "digest:sha",
        "size"
      ]
    },
    "R1"
  ],
  [
    "Blob/get",
    {
      "accountId" : "account1",
      "ids" : [
        "Gc0854fb9fb03c41cce3802cb0d220529e6eef94e"
      ],
      "properties" : [
        "data:asText",
        "digest:sha",
        "digest:sha-256",
        "size"
      ],
      "offset" : 4,
      "length" : 9
    },
    "R2"
  ]
]

Responses:

[
 [
  "Blob/get",
  {
   "accountId": "account1",
   "list": [
    {
     "id": "Gc0854fb9fb03c41cce3802cb0d220529e6eef94e",
     "data:asText": "The quick brown fox jumped over the lazy dog.",
     "digest:sha": "wIVPufsDxBzOOALLDSIFKebu+U4=",
     "size": 45
    }
  ],
  "notFound": [
   "not-a-blob"
  ]
 },
 "R1"
],
[
  "Blob/get",
  {
   "accountId": "account1",
   "list": [
    {
     "id": "Gc0854fb9fb03c41cce3802cb0d220529e6eef94e",
     "data:asText": "quick bro",
     "digest:sha": "QiRAPtfyX8K6tm1iOAtZ87Xj3Ww=",
     "digest:sha-256": "gdg9INW7lwHK6OQ9u0dwDz2ZY/gubi0En0xlFpKt0OA=",
     "size": 45
     }
    ]
   },
   "R2"
  ]
]

4.2.2. Blob/get Example with Range and Encoding Errors ✨

okay so b1 is the text "The quick brown fox jumped over the \x81\x81 dog.", and those \x81\x81 bytes are an invalid UTF-8 sequence 💀 which is exactly why this example is so spicy. here's how each of the G calls goes:

  • G1: defaults to data and size, so b1 comes back with isEncodingProblem and a base64 value 🫶
  • G2: since data:asText was explicitly selected, it doesn't try to return a value for the data, so b1 just gets isEncodingProblem 🙈
  • G3: since only data:asBase64 was requested, there's no encoding problem and both values come back 🌸
  • G4: the requested range could be satisfied as text, so both blobs come back as data:asText with no encoding problem 🎀
  • G5: neither blob can satisfy the requested range, so isTruncated is true for both 😭
Note: Some values have been wrapped for line length. There would be no wrapping in the data:asBase64 values on the wire.

Method Calls:

[
  [
    "Blob/upload",
    {
      "create": {
        "b1": {
          "data": [
            {
              "data:asBase64": "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZW
                                Qgb3ZlciB0aGUggYEgZG9nLg=="
            }
          ]
        },
        "b2": {
          "data": [
            {
              "data:asText": "hello world"
            }
          ],
          "type" : "text/plain"
        }
      }
    },
    "S1"
  ],
  [
    "Blob/get",
    {
      "ids": [
        "#b1",
        "#b2"
      ]
    },
    "G1"
  ],
  [
    "Blob/get",
    {
      "ids": [
        "#b1",
        "#b2"
      ],
      "properties": [
        "data:asText",
        "size"
      ]
    },
    "G2"
  ],
  [
    "Blob/get",
    {
      "ids": [
        "#b1",
        "#b2"
      ],
      "properties": [
        "data:asBase64",
        "size"
      ]
    },
    "G3"
  ],
  [
    "Blob/get",
    {
      "offset": 0,
      "length": 5,
      "ids": [
        "#b1",
        "#b2"
      ]
    },
    "G4"
  ],
  [
    "Blob/get",
    {
      "offset": 20,
      "length": 100,
      "ids": [
        "#b1",
        "#b2"
      ]
    },
    "G5"
  ]
]

Responses:

[
  [
    "Blob/upload",
    {
      "oldState": null,
      "created": {
        "b2": {
          "id": "G2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
          "size": 11,
          "type": "application/octet-stream"
        },
        "b1": {
          "id": "G72cfa4804194563685d9a4b695f7ba20e7739576",
          "size": 43,
          "type": "text/plain"
        }
      },
      "updated": null,
      "destroyed": null,
      "notCreated": null,
      "notUpdated": null,
      "notDestroyed": null,
      "accountId": "account1"
    },
    "S1"
  ],
  [
    "Blob/get",
    {
      "list": [
        {
          "id": "G72cfa4804194563685d9a4b695f7ba20e7739576",
          "isEncodingProblem": true,
          "data:asBase64": "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZW
                            Qgb3ZlciB0aGUggYEgZG9nLg==",
          "size": 43
        },
        {
          "id": "G2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
          "data:asText": "hello world",
          "size": 11
        }
      ],
      "notFound": [],
      "accountId": "account1"
    },
    "G1"
  ],
  [
    "Blob/get",
    {
      "list": [
        {
          "id": "G72cfa4804194563685d9a4b695f7ba20e7739576",
          "isEncodingProblem": true,
          "size": 43
        },
        {
          "id": "G2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
          "data:asText": "hello world",
          "size": 11
        }
      ],
      "notFound": [],
      "accountId": "account1"
    },
    "G2"
  ],
  [
    "Blob/get",
    {
      "list": [
        {
          "id": "G72cfa4804194563685d9a4b695f7ba20e7739576",
          "data:asBase64": "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZW
                            Qgb3ZlciB0aGUggYEgZG9nLg==",
          "size": 43
        },
        {
          "id": "G2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
          "data:asBase64": "aGVsbG8gd29ybGQ=",
          "size": 11
        }
      ],
      "notFound": [],
      "accountId": "account1"
    },
    "G3"
  ],
  [
    "Blob/get",
    {
      "list": [
        {
          "id": "G72cfa4804194563685d9a4b695f7ba20e7739576",
          "data:asText": "The q",
          "size": 43
        },
        {
          "id": "G2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
          "data:asText": "hello",
          "size": 11
        }
      ],
      "notFound": [],
      "accountId": "account1"
    },
    "G4"
  ],
  [
    "Blob/get",
    {
      "list": [
        {
          "id": "G72cfa4804194563685d9a4b695f7ba20e7739576",
          "isTruncated": true,
          "isEncodingProblem": true,
          "data:asBase64": "anVtcGVkIG92ZXIgdGhlIIGBIGRvZy4=",
          "size": 43
        },
        {
          "id": "G2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
          "isTruncated": true,
          "data:asText": "",
          "size": 11
        }
      ],
      "notFound": [],
      "accountId": "account1"
    },
    "G5"
  ]
]

4.3. Blob/lookup 🔍

okay so this method is basically a reverse lookup 🕵️‍♀️ you give it a list of blobIds, and for each type name you ask, it tells you which Ids of that type reference the blob. bestie, the word "reference" is kinda loose here because every data type has its own idea of "contains", but the vibe is: you could discover this blobId by looking at this object, or at other objects recursively contained within this object.

For example, with a server that supports [RFC8621], if a Mailbox references a blob and any Emails within that Mailbox reference the blobId, then the Mailbox references that blobId. And for any Thread that references an Email that references a blobId, the Thread references the blobId too 🧵

but wait, this does NOT mean that if an Email references a Mailbox in its mailboxIds property, then any blobId referenced by other Emails in that Mailbox are also referenced by the initial Email. not the same thing, so don't mix them up 🙅‍♀️

Parameters

  • accountId: "Id"

The id of the account used for the call. 🪪

  • typeNames: "String[]"

A list of names from the "JMAP Data Types" registry or defined by private extensions that the client has requested. Only names for which "Can reference blobs" is true may be specified, and the capability that defines each type must also be used by the overall JMAP request in which this method is called.

If a type name is not known by the server, or the associated capability has not been requested, then the server returns an "unknownDataType" error. 🚫

  • ids: "Id[]"

A list of blobId values to be looked for.

Response

  • list: "BlobInfo[]"

A list of BlobInfo objects.

BlobInfo Object

  • id: "Id"

The blobId.

  • matchedIds: "String[Id[]]"

A map from type name to a list of Ids of that data type (e.g., the name "Email" maps to a list of emailIds).

If a blob is not visible to a user, or does not exist on the server at all, the server MUST still return an empty array for each type. This is so nobody can tell whether the blob is on the server but just hidden from them 👀🔒

4.3.1. Blob/lookup Example 🦋

Method Call:

[
  "Blob/lookup",
  {
    "typeNames": [
      "Mailbox",
      "Thread",
      "Email"
    ],
    "ids": [
      "Gd2f81008cf07d2425418f7f02a3ca63a8bc82003",
      "not-a-blob"
    ]
  },
  "R1"
]

Response:

[
  "Blob/lookup",
  {
    "list": [
      {
        "id": "Gd2f81008cf07d2425418f7f02a3ca63a8bc82003",
        "matchedIds": {
          "Mailbox": [
            "M54e97373",
            "Mcbe6b662"
          ],
          "Thread": [
            "T1530616e"
          ],
          "Email": [
            "E16e70a73eb4",
            "E84b0930cf16"
          ]
        }
      }
    ],
    "notFound": [
      "not-a-blob"
    ]
  },
  "R1"
]

5. Security Considerations 🚨

bestie, this part is serious, so read it carefully 🥺 all the security considerations for JMAP [RFC8620] apply to this specification too. On top of that, there are extra considerations for the data types and functionality this document introduces, and those are described right here.

JSON parsers are not all consistent when it comes to non-UTF-8 data. JMAP requires that all JSON data be UTF-8 encoded, so servers MUST only return a null value if data:asText is requested for a range of octets that is not valid UTF-8, and set isEncodingProblem: true. 💅

Servers MUST apply any access controls. If the authenticated user would be unable to discover the blobId by making queries, then that fact cannot be discovered via a Blob/lookup. For example, if an Email exists in a Mailbox that the authenticated user does not have access to see, then that emailId MUST NOT be returned in a lookup for a blob that is referenced by that email. 🙅‍♀️🔐

The server MUST NOT trust that the data given to a Blob/upload is a well-formed instance of the specified media type. Also, if the server attempts to parse the given blob, only hardened parsers designed to deal with arbitrary untrusted data should be used. The server SHOULD NOT reject data on the grounds that it is not a valid specimen of the stated type. 🧨

Warning, bestie: with carefully chosen data sources, Blob/upload can be used to recreate dangerous content on the far side of security scanners (anti-virus or exfiltration scanners, for example) that may be watching the upload endpoint. Server implementations SHOULD provide a hook to allow security scanners to check the resulting blob after concatenating the data sources, in the same way that they do for the upload endpoint. 🚩

Digest algorithms can be expensive for servers to calculate. Servers that share resources between multiple users should track resource usage by clients and rate-limit expensive operations to avoid resource starvation. 🐢💸

6. IANA Considerations 🗂️

6.1. JMAP Capability Registration for "blob" 🎀

IANA has registered the "blob" JMAP capability as follows:

  • Capability Name: urn:ietf:params:jmap:blob
  • Specification document: RFC 9404
  • Intended use: common
  • Change Controller: IETF
  • Security and privacy considerations: RFC 9404, Section 5

6.2. JMAP Error Codes Registration for "unknownDataType" 🌈

IANA has registered the "unknownDataType" JMAP error code as follows:

  • JMAP Error Code: unknownDataType
  • Intended use: common
  • Change Controller: IETF
  • Reference: RFC 9404
  • Description: The server does not recognise this data type, or the capability to enable it is not present in the current Request Object.

6.3. Creation of "JMAP Data Types" Registry 🦋

okay so IANA made a brand new registry called "JMAP Data Types" 💖 Table 1 shows what's already in it when it starts out, bestie.

   +================+=====+=======+=========================+=========+
   |Type Name       |Can  |Can Use|Capability               |Reference|
   |                |Ref  |for    |                         |         |
   |                |Blobs|State  |                         |         |
   |                |     |Change |                         |         |
   +================+=====+=======+=========================+=========+
   |Core            |No   |No     |urn:ietf:params:jmap:core|[RFC8620]|
   +----------------+-----+-------+-------------------------+---------+
   |PushSubscription|No   |No     |urn:ietf:params:jmap:core|[RFC8620]|
   +----------------+-----+-------+-------------------------+---------+
   |Mailbox         |Yes  |Yes    |urn:ietf:params:jmap:mail|[RFC8621]|
   +----------------+-----+-------+-------------------------+---------+
   |Thread          |Yes  |Yes    |urn:ietf:params:jmap:mail|[RFC8621]|
   +----------------+-----+-------+-------------------------+---------+
   |Email           |Yes  |Yes    |urn:ietf:params:jmap:mail|[RFC8621]|
   +----------------+-----+-------+-------------------------+---------+
   |EmailDelivery   |No   |Yes    |urn:ietf:params:jmap:mail|[RFC8621]|
   +----------------+-----+-------+-------------------------+---------+
   |SearchSnippet   |No   |No     |urn:ietf:params:jmap:mail|[RFC8621]|
   +----------------+-----+-------+-------------------------+---------+
   |Identity        |No   |Yes    |urn:ietf:params:jmap:    |[RFC8621]|
   |                |     |       |submission               |         |
   +----------------+-----+-------+-------------------------+---------+
   |EmailSubmission |No   |Yes    |urn:ietf:params:jmap:    |[RFC8621]|
   |                |     |       |submission               |         |
   +----------------+-----+-------+-------------------------+---------+
   |VacationResponse|No   |Yes    |urn:ietf:params:jmap:    |[RFC8621]|
   |                |     |       |vacationresponse         |         |
   +----------------+-----+-------+-------------------------+---------+
   |MDN             |No   |No     |urn:ietf:params:jmap:mdn |[RFC9007]|
   +----------------+-----+-------+-------------------------+---------+

                                 Table 1

The registration policy for this registry is "Specification Required" [RFC8126]. Either an RFC or a similarly stable reference document defines a JMAP Data Type and its associated capability. 🌸

IANA will appoint designated experts to review requests for additions to this registry. Their guidance is to allow any registration that comes with a stable document describing the capability, and control over the URI namespace that the capability URI points to. 🧚 So basically, no sketchy registrations, periodt. 💅

7. References 📚

7.1. Normative References

7.2. Informative References

Acknowledgements 🫶

Huge thanks to Joris Baum, Jim Fenton, Neil Jenkins, Alexey Melnikov, Ken Murchison, Robert Stepanek, and the JMAP Working Group in the IETF. You all ate this spec up. 👑

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
📦 where this page comes from