Sharing

Collaboration depends on sharing: a team schedules meetings in a common calendar, a sales department keeps one address book, a project group works on the same documents. Stalwart lets calendars, address books and file storage be shared between accounts, in two ways. Group calendars, address books and file folders are available to every member of the group. In addition, individual accounts can share their own resources with other accounts on the server.

The clients set up the sharing themselves. JMAP clients use the JMAP Sharing extension, and CalDAV, CardDAV and WebDAV clients use the WebDAV ACL (Access Control List) extension. Both let a user assign permissions, from read-only to full access, to other accounts or groups directly from the client, without any change to the server configuration.

Group resources

Calendars, address books and file folders for teams or departments are created as group resources, and a resource that belongs to a group is visible to every member. Group membership alone grants access. Enabling group resources therefore requires only that the groups exist on the server and that accounts are added to them. The next time members log in through a supported CalDAV, CardDAV or WebDAV client, they see the group’s calendars, address books or file folders alongside their personal resources.

In other respects, group resources behave like individual resources. Their permissions are managed centrally, and an update made by one member is immediately visible to the rest of the group.

Sharing individual resources

Accounts can also share their own calendars, address books and file folders with other accounts. This allows ad-hoc collaboration without an administrator: a user can share a personal calendar with a colleague, or give a teammate access to one directory. The user needs a client with the right support, either a JMAP client with JMAP Sharing or a CalDAV, CardDAV or WebDAV client that supports the WebDAV ACL extension. Both let the account holder assign permissions to other accounts or groups from the client.

To share a resource, a user has to name the account to share it with, which raises the question of how users discover the other accounts on the server. In groupware terminology, a principal is any entity that can be granted access to a resource, typically an account, a group or a system-defined role. Listing all principals would reveal every account on the server, so for privacy and security reasons directory queries are disabled by default. Users can therefore share with the contacts they already know, but they cannot browse or search the full list of accounts and groups unless directory queries are permitted.

Directory visibility is set on the Sharing singleton, found in the WebUI under Settings › Files & Sharing › Sharing. Enabling allowDirectoryQueries lets authenticated users look up principals through JMAP Sharing and WebDAV ACL, and so discover the accounts to share with. These lookups can expose sensitive information in mixed environments. The setting should therefore be enabled only where all accounts belong to the same organisation, or are isolated into clearly defined tenants.

With allowDirectoryQueries disabled, the lookups are restricted as follows:

• JMAP Principal/query fails with forbidden and the description The administrator has disabled directory queries.
• Principal/get returns only the accounts the user already has access to.
• WebDAV principal searches and listings return only those accounts.

Two WebDAV reports are not affected by the setting: acl-principal-prop-set and principal-match. They are controlled by the davPrincipalAcl and davPrincipalMatch permissions instead, and they return only accounts the user has access to. For finer control, permissions decide who may browse the directory, view group membership or discover principals across the server.

Sharing limits

maxShares on the Sharing singleton is the largest number of sharees that can be added to a single shared calendar, address book or file, 10 by default. Raising it allows broader sharing of each item, while lowering it keeps the access lists small.

Revoking access

When a user uses a shared resource, the user also keeps personal data on it, and that data has to be cleaned up when the share ends. Removing a share therefore starts a background task, ShareRevokeCleanup, which runs within about ten minutes. It deletes the data the user kept on the resource: subscriptions, colours and default alerts of shared calendars and address books, personal data and alarms on shared events, and dismissed notifications.

Not every user loses this data. Users who keep access in another way, for example through a group that still has the share, keep their data, and so do the members of the owning account.

Leaving a group works differently, because it does not start this task. A user who leaves a group keeps their data on the group’s shared resources until the next time a share is removed from that resource. When a user account is deleted, its data and the shares granted to it are removed.

Deleted accounts can also be retained. When an account is deleted with retention of deleted accounts enabled, the resources it shared become invisible to other users, and restoring the account restores their access. Retention of deleted accounts is an Enterprise feature, described in Recovering deleted items.

Copying and moving onto existing items

A WebDAV COPY or MOVE can overwrite an existing item, and overwriting needs more rights than adding. Overwriting an existing calendar event or contact needs both the right to add items and the right to remove items on the destination calendar or address book (WebDAV bind and unbind). Overwriting files needs the right to remove items on every file and folder being replaced. Without these rights, the request fails with 403.

Share notification retention

JMAP Sharing records each sharing operation as a ShareNotification. The record captures who shared what with whom, the previous and the new ACLs, and other contextual details. These records do not accumulate for ever. They are removed during the routine auto-expunge run once they are older than the period in expungeShareNotifyAfter, 30 days by default, on the DataRetention singleton. The DataRetention singleton is found in the WebUI under Settings › Storage › Data Retention › Archiving, Settings › Storage › Data Retention › Data Cleanup, Settings › Storage › Data Retention › Auto-Expunge, Settings › Storage › Data Retention › Telemetry.

Discovering shared calendars and address books

CalDAV and CardDAV clients that read only one calendar or address book home do not find the collections shared with the user on their own. Stalwart’s assisted discovery, enabled by default, lists those collections under the user’s own home, as described in WebDAV assisted discovery.