The ‘sciencemesh’ app for Nextcloud adds API endpoints so that Nextcloud can serve as a user backend, a shares backend, and a storage backend for revad.
This chapter of the developer documentation was the deliverable for work package 2b of the sciencemesh-nextcloud project
Nextcloud already supports OCM out of the box, but not the invitation-first flow that is used on the ScienceMesh. There are three systems involved:
Step-by-step, this is how it works for the sender if the sending user uses the Nextcloud GUI to generate the invite token:
The sending user uses the GUI of nextcloud-sender to request the generation of an invite token.
This results in a REST call from nextcloud-sender to revad-sender:
<loopback-secret>as the password (this is because the server-side PHP code does not know the user’s real password)
Inside revad, this http request triggers a grpc request, including the username and loopback secret
<loopback-secret> is checked by reva’s Nextcloud-based auth backend (note that both the loopback secret and the user’s actual password will grant access)
The invite token is generated by reva
The token is returned from the grpc call within revad-sender
The token is returned from the rest call back to nextcloud-sender
The token is displayed in the GUI, for the sending user to copy and relay out-of-band to the receiving user.
Step-by-step, this is how it works for the sender if the sending user uses the Reva CLI to generate the invite token:
The sending user uses the CLI client of revad-sender to request the generation of an invite token.
The reva CLI tool sends a grpc request, including the
This results in a REST call from sending-revad to sending-nextcloud:
<clientSecret> are checked by reva’s Nextcloud-based auth backend (note that both the loopback secret and the user’s actual password will grant access)
A JSON-serialized CS3 User object is returned.
The token is generated by revad-sender.
The token is returned from the grpc call
The token is displayed in the CLI tool, for the sending user to copy and relay out-of-band to the receiving user.
Step-by-step, this is how it works for the receiver: There are again three systems involved:
The receiving user either pastes the token into the Nextcloud GUI, or into reva-cli. Authentication works the same way as on the sending side:
A REST call for ‘forward OCM invite’ is made from revad-receiver to nextcloud-receiver. Note that the ‘forward’ here may feel like a bit of a misnomer, but it probably refers to the fact that all the receiving revad effectively does is take the token from the message body and launch an almost identical request to it. So it really is a case of “forwarding the message”:
-(“Forward this invite acceptance notice!")->
-(“Here is an invite acceptance notice!")->
A REST call for ‘accept OCM invite’ made from nextcloud-receiver to sender. Note that this again feels like a misnomer because sending-revad is not ordered to accept the invite, it is just receiving the information that the receiver has done so.
When the sending user looks for a recipient to share a resource with, and starts typing the recipient identifier, the autocomplete function gathers search results from a number of share providers,
one of which will be ScienceMesh.
The ScienceMesh share provider compares the characters typed so far to names of users who accepted the sender’s invite, and provides an autocomplete result.
If the user clicks this, a rest call to https://revad-sender/ocm/send will be made
For authentication, the username and
loopback-secret will be sent by Nextcloud, and they will loop back to Nextcloud in a user authentication request.
The sender can also call
ocm-share-create in the Reva CLI using their username and password.
This would then similarly result in a call to the OCM Core share provider service, and the OCM share manager driver, which results in:
After that, in both cases, it will trigger a call to the CreateOCMShare method of the OCM share provider service, and the OCM share manager driver, which results in:
addSentSharerest call to nextcloud-sender (authenticated this time with
X-Reva-Secret), to store the sent share on the sender side
When the OCM /shares POST comes in, it triggers a call to the CreateOCMCoreShare method (not “CreateOCMShare method”) of the OCM Core service (not “OCM share provider service”), which also triggers Share function of the OCM share manager driver. So the code paths sound very similar but are subtly different:
The Share method of the OCM share manager driver figures out whether the share was generated locally, and if not, concludes that it must be on the receiving side.
addReceivedShare rest call is made to nextcloud-sender (authenticated with
X-Reva-Secret), to store the sent share on the sender side.
In a future version we will also implement data transfer shares that trigger an rclone job, but for now, all received shares just result in a webdav mount on the receiver side.
So when the receiver accesses the resource that was shared with them, the data is actually fetched from the source in real-time.
When the receiver access the resource through their Nextcloud GUI, the receiving-nextcloud will see in its database that the given path is a webdav mount.
It will do a webdav request to sending-revad.
This will lead to
InitiateDownload calls to sending-nextcloud.
The file contents are delivered along the following path:
sending-nextcloud -> sending-revad -> receiving-nextcloud -> webbrowser
Similarly, the receiver can access the resource through their Nextcloud WebDAV interface, from their Nextcloud Mobile app, through their Reva CLI or their revad’s WebDAV interface.
The registration for ScienceMesh is currently still quite a manual process. See the admin guide.