Merge branch 'for_developers' into 'master'

Update docs

See merge request !12

docs/.pages

@@ -6,3 +6,4 @@ nav:
  - mobile
  - advanced
  - training
+ - for_developers

docs/advanced/.pages

-nav:
-- web-pages
-- restore_from_trash
-- privacy_considerations
-- api_access
-- migration_from_dfs
-- corner_cases

docs/advanced/privacy_considerations/index.md → docs/advanced/privacy_considerations.md

+---
+title: Privacy considerations
+---
+
 # Privacy considerations when managing confidential data in CERNBox
 
 CERNBox is [suitable for storing personal data](https://cern.service-now.com/service-portal?id=kb_article&n=KB0003808), including sensitive personal data. CERNBox data and backups are always stored on the CERN premises.

docs/advanced/api_access/index.md → docs/for_developers/api_access.md

 # API access to data in CERNBox
 
 !!! Warning
-    This access method is reserved to developers and integrators, who need to interact with CERNBox and/or the underlying EOS storage from another service. End users should use the available regular [access methods](../../desktop/other-access-methods/desktop-mobile-access.md).
+    This access method is reserved to developers and integrators, who need to interact with CERNBox and/or the underlying EOS storage from another service. End users should use the available regular [access methods](../desktop/other-access-methods/desktop-mobile-access.md).
 
 If you are a developer and your workflow requires programmatic access to CERNBox and/or EOS, you can follow these guidelines to automate specific actions.
 
@@ -13,26 +13,34 @@ In the following, `wget` and `curl` are used to illustrate how to use the API.
 
 Files or folders that have been shared via public links can be anonymously downloaded as follows:
 
-`curl https://cernbox.cern.ch/remote.php/dav/public-files/<public-link-hash>/<relative-path-to-file>`
+```bash
+curl https://cernbox.cern.ch/remote.php/dav/public-files/<public-link-hash>/<relative-path-to-file>
+```
 
 If you have created a public link on a folder with _edit_ or _uploader_ rights, then the following allows you to anonymously upload content to that folder:
 
-`curl -T <some-file> -X PUT https://cernbox.cern.ch/remote.php/dav/public-files/<public-link-hash>/<target-filename>`
+```bash
+curl -T <some-file> -X PUT https://cernbox.cern.ch/remote.php/dav/public-files/<public-link-hash>/<target-filename>
+```
 
-Note that for _uploader_ links, the target file gets an extra hash appended to the name, to prevent collisions as the user does not have rights to list or overwrite existing content (see also [sharing](../../web/sharing/public-share.md)).
+Note that for _uploader_ links, the target file gets an extra hash appended to the name, to prevent collisions as the user does not have rights to list or overwrite existing content (see also [sharing](../web/sharing/public-share.md)).
 
 
 ## Protected shares
 
 Files or folders under protected shares can be accessed using HTTP Basic authentication at the `api.cernbox.cern.ch` endpoint. This endpoint is accessible withint the CERN network only. For example:
 
-`wget --user <account> --password <password> https://api.cernbox.cern.ch/remote.php/dav/files/<account>/eos/<full-path-to-target>`
+```bash
+wget --user <account> --password <password> https://api.cernbox.cern.ch/remote.php/dav/files/<account>/eos/<full-path-to-target>
+```
 
 Note that such a full path MUST contain `<account>` above the EOS path.
 
 Similarly, it is possible to upload content to protected shares:
 
-`curl -T <some-file> -u <account>:<password> -X PUT https://api.cernbox.cern.ch/remote.php/dav/files/<account>/eos/<full-path-to-target>`
+```bash
+curl -T <some-file> -u <account>:<password> -X PUT https://api.cernbox.cern.ch/remote.php/dav/files/<account>/eos/<full-path-to-target>
+```
 
 
 ## Share API

docs/for_developers/file-picker/.pages

+nav:
+- index.md
+- embedding.md
+- data.md
+- styling.md
+- setup.md
\ No newline at end of file

docs/for_developers/file-picker/data.md

+# Data
+
+The message posted to the parent will always include two fields: a `ready`
+boolean and a `files` array of strings. This is valid for all working modes.
+
+The File-picker works asynchronously. It has to make some requests to validate
+the token used to access the ownCloud instance and, when sharing public links,
+it also has to wait for the link generation.
+
+Whenever the user makes a selection on the File-picker, the iframe will post an
+instant message to the parent with the `ready` boolean set to `false` and an
+empty `files` array. This can be used by the application to disable the
+confirmation button or show a loading spinner. Once the work is done, another
+message will be posted, with `ready` set to `true` and the list of URLs for
+selected files.
+
+!!! note
+    Any click in a file checkbox (select or deselect a file) will trigger a new message with the updated list of files. This is to so the users do not have to confirm their selection inside the File-picker.
+
+This list of links can then be handled by the backend of the application using
+the File-picker. They can be downloaded straight away and the token included as
+parameter will be enough to authenticate the user.
+
+## File selector
+
+### When using URL sharing
+
+Please refer to the [URL sharing](../embedding#url-sharing) section for more
+information.
+
+```json
+{
+  "data": {
+    "ready": true,
+    "files": [
+      "https://new.cernbox.cern.ch/remote.php/webdav/eos/user/j/johndoe/document_1.docx?access_token=123456789xyz",
+      "https://new.cernbox.cern.ch/remote.php/webdav/eos/user/j/johndoe/document_2.docx?access_token=123456789xyz",
+      "https://new.cernbox.cern.ch/remote.php/webdav/eos/user/j/johndoe/document_3.docx?access_token=123456789xyz",
+      "https://new.cernbox.cern.ch/remote.php/webdav/eos/user/j/johndoe/document_4.docx?access_token=123456789xyz"
+    ]
+  }
+}
+```
+
+### When using public link sharing
+
+Please refer to the [public link sharing](../embedding#public-link-sharing)
+section for more information.
+
+```json
+{
+  "data": {
+    "ready": true,
+    "files": [
+      "https://newqa.cernbox.cern.ch/remote.php/dav/public-files/WLyTQEmXHJVlQdO/document_1.docx",
+      "https://newqa.cernbox.cern.ch/remote.php/dav/public-files/JgheoMVYenmfLGq/document_2.docx",
+      "https://newqa.cernbox.cern.ch/remote.php/dav/public-files/MvbhjhEJgjHassK/document_3.docx",
+      "https://newqa.cernbox.cern.ch/remote.php/dav/public-files/JBjteoIJgMJEQtz/document_4.docx"
+    ]
+  }
+}
+```
+
+## Location selector
+
+Please refer to the [location selector](../embedding#location-selector)
+section for more information.
+
+```json
+{
+  "data": {
+    "ready": true,
+    "files": ["/example/folder/under_user_home"],
+    "username": "johndoe",
+    "accessToken": "123456789xyz"
+  }
+}
+```

docs/for_developers/file-picker/embedding.md

+---
+title: Embed it in your site
+---
+# Embed the file-picker in your site
+
+To embed the File-picker, you have to use an `<iframe>` tag:
+
+```html
+<iframe
+  src="https://filepicker.cernbox.cern.ch/?origin=https://mysite.cern.ch"
+></iframe>
+```
+
+The source URL is https://filepicker.cernbox.cern.ch, and it must be passed an
+`origin` query parameter containing the URL of the iframe parent.
+
+!!! warning 
+    Remember, you have to specify the protocol (usually `https://`) in the origin.
+
+This enables the iframe to check it against a list of approved sites before
+setting it as `targetOrigin` argument of the `postMessage` the File-picker does.
+Otherwise if the parent is vulnerable the iframe could be hijacked and the
+message captured, including the user token.
+
+By default anything under `cern.ch` is allowed. Outside sources can
+[open an issue](https://github.com/cernbox/file-picker-wrapper/issues/new)
+requesting addition to the whitelist.
+
+## Operation modes
+
+There are two ways to use the File-picker, depending on the value of the
+`locationPicker` search parameter.
+
+### File selector
+
+This mode allows users to select files from their storage and then sends the
+selection to the parent application. This selection can be sent as a URL or a
+public link.
+
+This is the default mode and there is no configuration setting for it.
+
+#### URL sharing
+
+By default, the File-picker will send the files' URL to the parent application,
+along with an authentication token to enable the download. This token is usually
+short lived, therefore this mode is more suited for downloading the selected
+files straight away after the user has made the selection (for example to copy
+them to the parent application's backend).
+
+#### Public link sharing
+
+Alternatively, the File-picker can generate public links for the selected files
+and send them to the parent application. This can be enabled by passing the
+`publicLink=1` parameter. These links will be valid in the longer term, and so
+they can be used to link files somewhere without copying them. The duration of
+the links can be adjusted with the `publicLinkDuration`, in days. These public
+links will have the [`internal`](https://cs3org.github.io/cs3apis/#cs3.sharing.link.v1beta1.CreatePublicShareRequest)
+flag set (so they are not visible in ownCloud web), and can be given a
+description via the `description` parameter.
+
+!!! info "Keep in mind"
+    If the owner of the file deletes or moves it, the public link will stop being valid. This is especially important if you plan to have long-term access to the files.
+
+### Location selector
+
+This mode allows users to select a path inside their storage for the parent
+application to upload files into it.
+
+The File-picker will provide the parent application with authentication details
+along with the selected path.
+
+## Query parameters
+
+The File-picker accepts the following parameters through the query string:
+
+| Name           | Description                                                                                                  | Values                    | Default | Required | Example                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------- | ------- | -------- | ------------------------ |
+| origin         | URL of the iframe parent                                                                                     | `string`                  |         | Yes      | `https://indico.cern.ch` |
+| locationPicker | Show the location picker instead of the regular File-picker                                                  | `bool`                    | `false` | No       | `1`                      |
+| style          | Style to apply to the File-picker                                                                            | `light \| dark \| indico` | `light` | No       | `light`                  |
+| startPath      | Start path for the File-picker browser, always starting with `/` (overriden by `userHome`)                   | `string`                  | `/`     | No       | `/aFolder/subFolder`     |
+| userHome       | Whether the File-picker should start the browser in the user home folder (takes precedence over `startPath`) | `bool`                    | `true`  | No       | `0`                      |
+
+The following parameters are only relevant when using the regular File-picker, not `locationPicker`.
+
+| Name                  | Description                                                                                                                                                                              | Values   | Default | Required | Example                            |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------- | ---------------------------------- |
+| publicLink            | If `true`, the File-picker will generate [public links](https://doc.owncloud.com/webui/next/classic_ui/files/public_link_shares.html) for the shared files                               | `bool`   | `false` | No       | `1`                                |
+| publicLinkDuration    | If `publicLink` is `true`, number of days links will be valid before expiry                                                                                                              | `number` | `0`     | No       | `30`                               |
+| publicLinkDescription | [Description](https://cs3org.github.io/cs3apis/#cs3.sharing.link.v1beta1.CreatePublicShareRequest) for the public link                                                                   | `string` |         | No       | `CodiMD`                           |
+| mimeTypes             | A url-encoded, comma-separated list of [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) to filter the contents of the user storage | `string` |         | No       | `image%2Fjpeg%2Cimage%2Fsvg%2Bxml` |

docs/for_developers/file-picker/index.md

+---
+title: What does it do?
+---
+# What does the file-picker do?
+
+The CERNBox File-picker provides a way to integrate a cloud storage into other
+applications.
+
+It can be embedded in a web, and will show a file browser which allows the users
+to navigate their CERNBox storage.
+
+The File-picker features two use cases:
+
+- **Select files** from the user storage and make them available to the parent
+  application via their URL a public link.
+- **Select a location** from the user storage and pass it to the parent
+  application for it to upload files into.
+
+Once the user has made a selection, it will send the parent application URLs or
+public links for the selected files.
+
+The File-picker handles authentication into CERNBox itself, and in the case of
+using file URLs, those include a token to grant access for the parent
+application. When using public links this is not needed.
+
+## How to use it
+
+Here is a small guide to integrate CERNBox in a site using the File-picker.
+
+- How to [embed the file-picker in your site](embedding.md), different modes of
+  operation and configuration parameters.
+- How to [get files from CERNBox](data.md) once the user has selected some.
+- How to [style the file-picker](styling.md).
+
+## How to set up your own
+
+- [Setting up](setup.md) a File-picker for your ownCloud instance.

docs/for_developers/file-picker/setup.md

+# Setup a File Picker instance
+
+To set up your own File-picker instance, you need to do the following:
+
+- Install the File-picker
+- Edit the configuration files
+- Set up a web server
+
+This guide has been tested in CentOS 7 and Ubuntu 22.04, but it should work in
+most distros, as it is a basic procedure.
+
+!!! note 
+    The `rsync` package should be installed in the system.
+
+## Install the File-picker
+
+1. Clone the File-picker repo
+
+```bash
+mkdir -p /var/www/fp
+cd /var/www/fp
+git clone https://github.com/cernbox/file-picker-wrapper.git .
+```
+
+2. Run `make` to create the directory and files which will be served.
+
+```bash
+make dist
+```
+
+## Edit the configuration files
+
+You can find templates of the configuration files in the repo.
+
+- [`file-picker-config.json`](https://github.com/cernbox/file-picker-wrapper/blob/master/file-picker-config.json.template)
+- [`allowed-origins.json`](https://github.com/cernbox/file-picker-wrapper/blob/master/allowed-origins.json.template)
+
+The files should be placed in the `/dist` subdirectory created by `make` in the
+previous step.
+
+### file-picker-config.json
+
+This file contains the server and authentication details:
+
+```json
+{
+  "server": "https://example.com",
+  "openIdConnect": {
+    "metadata_url": "https://example.com/.well-known/openid-configuration",
+    "authority": "https://example.com",
+    "client_id": "example-client-id",
+    "response_type": "code",
+    "scope": "openid profile email",
+    "redirect_uri": "https://example.com/oidc-callback.html",
+    "silent_redirect_uri": "https://example.com/oidc-silent-callback.html",
+    "logLevel": 1,
+    "popupWindowFeatures": "location=no,toolbar=no,width=895,height=990,left=100,top=100"
+  }
+}
+```
+
+You want to configure the following fields:
+
+- The hostname in `redirect_uri` and `silent_redirect_uri` should be the one where the file-picker
+will be served from.
+- `server` should be pointing to the owncloud instance.
+  
+Then, fill in the details for your OIDC provider in the `metadata_url`,
+`authority` and `client_id` fields. These should point to the OCIS IDP or your
+institution's SSO. You will have to register a `client_id` for the File-picker
+in there. You can find more info in [OCIS documentation](https://doc.owncloud.com/ocis/next/deployment/services/s-list/idp.html)
+or your institution's docs.
+
+You can later adjust the `height` and `width` in `popupWindowFeatures` to
+fine-tune the size of the login web dimensions.
+
+### allowed-origins.json
+
+This file contains a list of the origins that the file-picker will accept in the
+[`origin` query parameter](docs/embedding/#query-parameters).
+You can use the `*` wildcard to whitelist entire domains. Imagine you host two
+applications in the `mycloud.net` domain which you want to allow use of the
+File-picker:
+
+- app1.mycloud.net
+- app2.mycloud.net
+
+To do so, you can set the contents of `allowed-origins.json` to:
+
+```json
+["*.mycloud.net"]
+```
+
+## Set up a web server
+
+The File-picker requires a simple web server for the html and js bundle. This
+example uses [nginx](https://www.nginx.com/). You will also need a proper SSL
+certificate and key. Once you have those, first you enable access to the files
+you created accessible for the `nginx` user:
+
+```bash
+cd /var/www/
+chown -R nginx:nginx fp
+```
+
+Then, add the following to the `http` section of the `/etc/nginx/nginx.conf`.
+
+!!! note 
+    Replace `YOURHOSTNAME` with the the hostname on which the File-picker will be available; and `YOURSSLCERTFILE` and `YOURSSLKEYFILE` with the path to the SSL certificate and key files.
+
+```conf
+[...]
+
+server {
+  listen 8080 default_server;
+  listen [::]:8080 default_server;
+  # hostname we will be serving on, e.g. localhost
+  server_name YOURHOSTNAME;
+  return 301 https://$server_name$request_uri;
+}
+
+server {
+  listen 443 ssl http2;
+  listen [::]:443 ssl http2;
+  server_name YOURHOSTNAME;
+
+  ssl_certificate YOURSSLCERTFILE;
+  ssl_certificate_key YOURSSLKEYFILE;
+  ssl_session_timeout 1d;
+  ssl_session_cache shared:SSL:10m;
+
+  ssl_protocols TLSv1.2;
+  ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
+  ssl_prefer_server_ciphers off;
+  add_header Strict-Transport-Security "max-age=63072000" always;
+  ssl_stapling on;
+  ssl_stapling_verify on;
+
+  # location of the build of file-picker
+  root   /var/www/fp/dist;
+  index  index.html;
+
+  location / {
+    try_files   $uri $uri/ =404;
+    access_log  /var/log/nginx/fp.access.log;
+    error_log   /var/log/nginx/fp.error.log;
+  }
+}
+```
+
+You can test the configuration with:
+
+```bash
+nginx -t
+```
+
+If the configuration is correct, restart nginx for the changes to take effect:
+
+```bash
+systemctl restart nginx
+```
+
+And that's all! You should be able to access the File-picker by navigating your
+browser to the address you configured in nginx. Once you confirm it works, you
+can embed it into an application by following the rest of these docs.
+
+**Good luck! 🎉**

docs/for_developers/file-picker/styling.md

+# Styling
+
+Styling is done via the [style Search Param](embedding.md). Right now there are
+two general styles, using the following values for the param:
+
+- [Dark style](https://filepicker.cernbox.cern.ch/?userHome=true&style=dark): `style=dark`
+- [Light style](https://filepicker.cernbox.cern.ch/?userHome=true&style=light): `style=light`
+
+As well as some custom themes:
+
+| Application                                  | Example                                                                | Search parameter |
+| -------------------------------------------- | ---------------------------------------------------------------------- | ---------------- |
+| [Indico](https://getindico.io/)              | [Link](https://filepicker.cernbox.cern.ch/?userHome=true&style=indico) | `style=indico`   |
+| [CodiMD](https://github.com/hackmdio/codimd) | [Link](https://filepicker.cernbox.cern.ch/?userHome=true&style=codimd) | `style=codimd`   |
+
+You can check out the
+[repo](https://github.com/cernbox/file-picker-wrapper/blob/master/dark-styles.css)
+for some examples on styling.

mkdocs.yml

@@ -46,11 +46,18 @@ markdown_extensions:
   - pymdownx.keys
   - pymdownx.mark
   - pymdownx.tilde
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
   - toc:
       permalink: true
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
 
 
 plugins: