Effective recipients endpoints for nested shared folders

[shepilov]

Context

Nested shared folders use additive access: a child folder can add recipients or stronger rights, while parent access still applies to descendants.
io.cozy.sharings.members represents only direct members of one sharing document. The Drive UI needs another view: the combined list of everyone who can access a selected file or folder, including inherited recipients from parent shared folders.

Endpoints

• GET /sharings/recipients/:file-id
• GET /sharings/drives/:drive-id/recipients/:file-id

User journey

1. User opens Drive.
2. User selects one file or folder.
3. User clicks Share.
4. UI opens the share modal.
5. UI calls the effective recipients endpoint for this single file/folder.
6. UI displays:
   • direct recipients on this share,
   • inherited recipients from parent shared folders,
   • whether each recipient can be edited from this modal.

Backend behavior

• Resolve all additive sharing scopes that apply to the target.
• Collect direct members from each applicable io.cozy.sharings document.
• Deduplicate recipients by stable identity, preferably instance, then email fallback.
• Merge permissions so read-write wins over read-only.
• Return source metadata so UI can explain where access comes from.
• Mark inherited-only recipients as can_edit_here=false.
• Do not mutate sharing docs.
• Do not copy inherited members into child sharing docs.

Response

   {
  "file_id": "target-file-id",
  "recipients": [
    {
      "name": "Alice",
      "email": "alice@example.com",
      "instance": "https://alice.example.com",
      "status": "ready",
      "read_only": false,
      "sources": [
        {
          "sharing_id": "parent-sharing-id",
          "root_id": "parent-folder-id",
          "root_name": "Project",
          "kind": "ancestor",
          "member_index": 1,
          "read_only": false,
          "manageable": false
        }
      ]
    }
  ]
}

Permission checks

• Regular endpoint: caller must have at least read access to the requested file/folder.
• Shared-drive endpoint: caller must be a member of :drive-id, and :file-id must belong to this shared drive.
• The endpoint is read-only, so it must not require write permission just to display access.

Client integration

Add cozy-stack-client helpers:

client.collection('io.cozy.sharings').fetchEffectiveRecipients({ id })

client.collection('io.cozy.sharings').fetchSharedDriveEffectiveRecipients({
driveId,
id
})