Feature: collection sharing (3.7.0+)

[pbiering]

This relates to

• Calendar sharing support (3.7.0+) #1499
• Feature: Secret, auth-less, read-only URLs #1977
• Collection sharing (legacy, EoL) #885 - stale and potentially too complex

Implementation is now in progress

Status as of 2026-02-20

• ShareType:

  • by-map
  • by-token
  • all (only supported for "list" and "info")

• Database:

  • CSV (initial, potentially discarded)
  • files ("pickle")

• Configuration by

  • POST-API
    • Content-Types
      • Input
        • JSON
        • FORM
      • Output
        • JSON
        • text/plain
        • text/csv for "list"
    • Actions
      • create
        • conflict check for already existing collections
      • delete
      • list
      • enable|disable|hide|unhide by user and owner
      • update
  • controlled by WebUI using POST-API -> see below (still in progress)

• Rights Extensions

  • add permissions to create share-by-token per collection
  • add permissions to create share-by-map per collection

• Supported C*DAV APIs

  • GET + HEAD(implicit)
  • PUT
  • DELETE
  • REPORT
  • PROPFIND
    • discover
      • support hiddden/unhidden
    • support whitelisted properties overlay
  • PROPPATCH
    • support whitelisted properties overlay adjustment
  • MOVE
  • MKCALENDAR conflict check for existing shares
  • MKCOL conflict check against existing shares

• sharing database verification

  • lightweight
  • comprehensive

WebUI extension to control sharing control using API by @maxberger (in progress)

• owner can insert/update/delete association per collection
• by-map: target-user will see the collection with its permission
  • toggle enable/disable an incoming share created by owner
  • toggle hide/unhide share (hidden: do not announce via PROPFIND)

Testing

• Mgmt-WebUI
• InfCloud
• Thunderbird

[pbiering]

Sneak preview: https://github.com/pbiering/Radicale/tree/feature-sharing

Do not use on any production system as internals are still subject to change

Documentation in (slow) progress, see for now inline in

• https://github.com/pbiering/Radicale/tree/feature-sharing/radicale/sharing
• https://github.com/pbiering/Radicale/blob/feature-sharing/radicale/tests/test_sharing.py

[maxberger]

Sneak preview with WebUI:
https://github.com/maxberger/Radicale/tree/feature-sharing

Not many features are supported right now, but the plan is to evolve this along with the backend development.

[pbiering]

The sneak preview of the backend above has now reached beta status and is beside granular feature control and comprehensive verification run I hope it's more or less complete. Many test cases were defined and passing.

I strongy hope that this fulfills the needs in referenced tickets.

Before I start now documenting POST-API and storage layout (for "files" based share config store) it would be good to receive some feedback.

Example for creating a token based sharing:

# create token-based share for a collection
curl -u user:userpw -d "PathMapped=/user/testcalendar1/" http://localhost:5232/.sharing/v1/token/create
ApiVersion=1
Status=success
PathOrToken=v1/OfD4z4BbQw2iaqef1R0ThviyxewbD056ka5ZD-Q-GEw=

# enable token-based share for collection
curl -u user:userpw -d "PathOrToken=v1/OfD4z4BbQw2iaqef1R0ThviyxewbD056ka5ZD-Q-GEw=" http://localhost:5232/.sharing/v1/token/enable

# request content of collection by using token
curl http://localhost:5232/.token/v1/OfD4z4BbQw2iaqef1R0ThviyxewbD056ka5ZD-Q-GEw=

Mapping works similar, see test_sharing.py for all the use cases until documentation exists.

[Neustradamus]

@pbiering: Thanks for your work!

[pbiering]

It would be glad if somebody can test this on Windows as I do not have a prepared system avaiable.

• create new branch for a PR with generic preparation adjustments, will be included in release 3.6.1
• create new branch for a PR on-top for 3.7.0.dev -> add API backend to control and hooks for collection sharing #1995

[pbiering]

PR now started, let see result of tests on Windows OS now...

[pbiering]

• backend code merged to upstream/master
• API doc started: https://github.com/Kozea/Radicale/blob/master/SHARING.md

[pbiering]

@maxberger - I've added additional Properties field to API to be able to overlay. API-wise I hope all required is implemented now. The last open one is controlling overlay properties by PROPPATCH...next on the list if easy to implement.

Beside birthday view all listed requirements from original PR are implemented: #885 (comment)

[pbiering]

configuring properties overlay via PROPPATCH was now also added by #2005

So featurewise it's complete now, all currently defined tests are passing.

Code review + optimization will take some time now, major focus is moving the permission control related database entry changes from csv/files into main code to remove duplicates (while trying to avoid any new race conditions).

[pbiering]

2 review PRs now applied, backend side is imho finished for now

Doc created: https://github.com/Kozea/Radicale/blob/master/SHARING.md

Please start now testing with upstream using APIs.

@maxberger requires still some time to extend the WebUI.

If there is a demand for an explicit "get" action, I can implement, otherwise using "list" API with filter and content item 0 from one-member-only list.

[maxberger]

Thanks for the backend work! I am slowly making my wait through making sure everything will get a button or representation on the frontend, but please be patient, it will happen one step at a time.

[maxberger]

Update: Main functionality (manage outgoing shares, manage incoming shares) is available. There are still some cleanups to do (call out external shares in collections view, hide some functionality, etc.).

PLEASE GIVE FEEDBACK: Let me know what works well in the UI and more specifically, what does not. Feel free to reply and tag me here or send me a PM.

[pbiering]

Some additional PRs were merged, during implementation of "bday" and real client test some issues were fixed. WebUI extensions are also applied.

Please test latest upstream - in case of issues found on *DAV level please provide the request and unexpected response content.

Sneak preview of "bday" can be found here (still unfinished): https://github.com/pbiering/Radicale/tree/sharing-bday

[pbiering]

This virtual feature sounds cool. Would it be possible to use the same collection_by_map to share an "availability-only" calendar, i.e. share just the reserved timeslots of a calendar as "busy" without sharing the details of the event?

You mean a virtual collection containing original VCALENDAR items having TRANSP:OPAQUE set and mask or clear description?

[maxberger]

Sharing as calendar with reduced details is one option, another one is transforming into VFREEBUSY, or even into VAVAILABILITY

[pbiering]

Before I have to start deep investigations of RFCs, can one provide example with source and target item or can even support it by programming? In case of converting VCALENDAR to virtual VFREEBUSY or VAVAILBILITY a new conversion has to be defined and implemented.

[maxberger]

Makes sense. I would be able to do the work, but right now I need to focus on getting the UI solid for the next release. So for the time being I guess this means help-needed?

[pbiering]

Makes sense. I would be able to do the work, but right now I need to focus on getting the UI solid for the next release. So for the time being I guess this means help-needed?

I assume there is no hurry to implement, so let's finish 3.7.0 first and then work on requested extensions, potentially it makes sense to create new feature issue(s) for that.

[pbiering]

Please test latest upstream from now, container-latest will be updated on next daily run.

[pbiering]

3.7.0 is now available as pre-release.