Developer Documentation¶
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.
API Architecture¶
This chapter of the developer documentation was the deliverable for work package 2b of the sciencemesh-nextcloud project
Invitation flow API¶
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:
nextcloud-sender (Nextcloud server of the sender)
revad-sender (IOP server of the sender)
receiver (the receiver’s system; opaque for this part of the flow)
Obtaining the invite token (from Nextcloud GUI)¶
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:
Method: POST
Content Type: JSON
Request Body: empty
Authentication: http basic auth, with the sending user’s actual username, but with <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
The <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.
Obtaining the invite token (from Reva CLI)¶
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 <clientID> and <clientSecret>
This results in a REST call from sending-revad to sending-nextcloud:
Method: POST
Content Type: JSON
URL: https://nextcloud-sender/index.php/apps/sciencemesh/api/auth/Authenticate
Request Body: e.g. ‘{“clientID”:”einstein”,”clientSecret”:”relativity”}’
X-Reva-Secret header: <shared-secret>
The <clientID> and <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.
Accepting the invite token¶
Step-by-step, this is how it works for the receiver: There are again three systems involved:
sender (the sender’s system; opaque for this part of the flow)
revad-receiver (IOP server of the receiver)
nextcloud-receiver (Nextcloud server of the receiver)
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:
If coming through the Nextcloud GUI, the Nextcloud-based user manager verifies username + loopback secret
If coming through the Reva CLI, the Nextcloud-based user manager verifies username + user password
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”:
receiving-user
-(“Forward this invite acceptance notice!”)->
receiving-revad
-(“Here is an invite acceptance notice!”)->
sending-revad
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.
File sharing API¶
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.
Registration flow API¶
The registration for ScienceMesh is currently still quite a manual process. See admin guide.