JMAP for Quotas

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 3 June 2023.¶

Copyright Notice

Copyright (c) 2022 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) 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

JMAP ([RFC8620] – (U+2013) JSON Meta Application Protocol) is a generic protocol for synchronising data, such as mails, calendars or contacts, between a client and a server. It is optimised for mobile and web environments, and aims to provide a consistent interface to different data types.¶

This specification defines a data model for handling quotas over JMAP, allowing a user to obtain details about a certain quota.¶

This specification does not address quota administration, which should be handled by other means.¶

2. Addition to the capabilities object

The capabilities object is returned as part of the JMAP Session object; see [RFC8620], section 2.¶

This document defines one additional capability URI.¶

3. Data types

In addition to the standard JMAP data types, a couple of additional data types are common to the definition of Quota objects and properties.¶

Servers that support the new data types defined in this document MUST support all the properties specified for these data types.¶

4. Quota

The quota is an object that displays the limit set to an account usage. It then shows as well the current usage in regard to that limit.¶

The quota object MUST contain the following fields:¶

• id: "Id"¶

• The unique identifier for this object.¶

• resourceType: "ResourceType"¶

• The resource type of the quota as defined in Section 3.2.¶

• used: "UnsignedInt"¶

• The current usage of the defined quota, using the "resourceType" defined as unit of measure. Computation of this value is handled by the server.¶

• limit: "UnsignedInt"¶

• The hard limit set by this quota, using the "resourceType" defined as unit of measure. Objects in scope may not be created or updated if this limit is reached.¶

• scope: "Scope"¶

• The "Scope" of this quota as defined in Section 3.1.¶

• name: "String"¶

• The name of the quota object. Useful for managing quotas and using queries for searching.¶

• dataTypes: "String[]"¶

• A list of all the type names (e.g., Email, Calendar, etc.) to which this quota applies. This allows to assign quotas to distinct or shared data types. This MAY include data types the client does not recognise. Clients MUST ignore any unknown data type in the list.¶

The quota object MAY contain the following fields:¶

• warnLimit: "UnsignedInt|null"¶

• The warn limit set by this quota object, using the "resourceType" defined as unit of measure. It can be used to send a warning to an entity about to reach the hard limit soon, but with no action taken yet. If set, it SHOULD be lower than the "softLimit" (if present and different than null) and the "limit".¶

• softLimit: "UnsignedInt|null"¶

• The soft limit set by this quota object, using the "resourceType" defined as unit of measure. It can be used to still allow some operations, but refuse some others. What is allowed or not is up to the server. For example, it could be used for blocking outgoing events of an entity (sending emails, creating calendar events, ...) while still receiving incoming events (receiving emails, receiving calendars events, ...). If set, it SHOULD be higher than the "warnLimit" (if present and different than null) but lower than the "limit".¶

• description: "String|null"¶

• Arbitrary free, human readable, description of this quota. It might be used to explain where the limit comes from and explain the entities and data types this quota applies to. The description MUST be encoded in UTF-8 [RFC3629] as described in [RFC8620] section 1.5, selected based on an Accept-Language header in the request (as defined in [RFC9110], Section 12.5.4) or out-of-band information about the user's language/locale.¶

The following JMAP methods are supported.¶

5. Examples

[[ "Quota/get", {
  "accountId": "u33084183",
  "ids": null
}, "0" ]]

[[ "Quota/get", {
  "accountId": "u33084183",
  "state": "78540",
  "list": [{
    "id": "2a06df0d-9865-4e74-a92f-74dcc814270e",
    "resourceType": "count",
    "used": 1056,
    "warnLimit": 1600,
    "softLimit": 1800,
    "limit": 2000,
    "scope": "account",
    "name": "bob@example.com",
    "description": "Personal account usage",
    "dataTypes" : [ "Mail", "Calendar", "Contact" ]
  }, {
    "id": "3b06df0e-3761-4s74-a92f-74dcc963501x",
    "resourceType": "octets",
    ...
  }, ...],
  "notFound": []
}, "0" ]]

[[ "Quota/changes", {
  "accountId": "u33084183",
  "sinceState": "10824",
  "maxChanges": 20
}, "0" ],
[ "Quota/get", {
  "accountId": "u33084183",
  "#ids": {
    "resultOf": "0",
    "name": "Quota/changes",
    "path": "/updated"
  },
  "#properties": {
    "resultOf": "0",
    "name": "Quota/changes",
    "path": "/updatedProperties"
  }
}, "1" ]]

[[ "Quota/changes", {
  "accountId": "u33084183",
  "oldState": "10824",
  "newState": "10826",
  "hasMoreChanges": false,
  "updatedProperties": ["used"],
  "created": [],
  "updated": ["2a06df0d-9865-4e74-a92f-74dcc814270e"],
  "destroyed": []
}, "0" ],
[ "Quota/get", {
  "accountId": "u33084183",
  "state": "10826",
  "list": [{
    "id": "2a06df0d-9865-4e74-a92f-74dcc814270e",
    "used": 1246
  }],
  "notFound": []
}, "1" ]]

6. Push

Servers MUST support the JMAP push mechanisms, as specified in [RFC8620] Section 7, to receive notifications when the state changes for the Quota type defined in this specification.¶

7. Security considerations

All security considerations of JMAP ([RFC8620]) apply to this specification.¶

Implementors should be careful to make sure the implementation of the extension specified in this document does not violate the site's security policy. The resource usage of other users is likely to be considered confidential information and should not be divulged to unauthorized persons.¶

As for any resource shared across users (for example, a quota with the "domain" or "global" scope), a user that can consume the resource can affect the resources available to the other users. For example, a user could spam themselves with events and make the shared resource hit the limit and unusable for others (implementors could mitigate that with some rate limiting implementation on the server).¶

Also, revealing domain and global quota counts to all users may cause privacy leakage of other sensitive data, or at least the existence of other sensitive data. For example, "user1" is part of a private list belonging to the server, so he shouldn't know how many users are in there. But by comparing the quota count before and after sending a message to the list, it could reveal the number of people of the list, as the domain or global quota count would go up by the number of people subscribed. Likely to limit those attacks, quotas with "domain" or "global" scope should only be visible to the administrators of the server and not all users.¶

8. IANA Considerations

Author's Address