Add some documentation about shares

website/site/content/docs/api/intro.md

@@ -18,12 +18,13 @@ The "raw" `openapi.yml` specification file can be found
 
 The routes can be divided into protected, unprotected routes and admin
 routes. The unprotected, or open routes are at `/open/*` while the
-protected routes are at `/sec/*` and admin routes are at `/admin/*`.
-Open routes don't require authenticated access and can be used by any
-user. The protected routes require an authenticated user. The admin
-routes require a special http header with a value from the config
-file. They are disabled by default, you need to specify a secret in
-order to enable admin routes.
+protected routes are at `/sec/*` and `/share/*`, while admin routes
+are at `/admin/*`. Open routes don't require authenticated access and
+can be used by any user. The protected routes require either an
+authenticated user (for `/sec/*`) or a valid share id and possibly the
+password (for `/share/*`). The admin routes require a special http
+header with a value from the config file. They are disabled by
+default, you need to specify a secret in order to enable admin routes.
 
 ## Authentication
 
@@ -44,6 +45,16 @@ must be `docspell_auth` and a custom header must be named
 The admin route (see below) `/admin/user/resetPassword` can be used to
 reset a password of a user.
 
+To authenticate for a share, the `/open/share/verify` endpoint must be
+used. It expects the share id and possibly a password. If the share
+requires a password, but it was not specified in the request, the
+response indicates this. The request must then be replayed with the
+correct password to retrieve a token. This token can then be used to
+all `/share/*` endpoints to identify the share - analog to the
+protected `/sec/*` routes. It can be either specfied as a cookie or
+via the header `Docspell-Share-Auth`.
+
+
 ### OpenID Connect
 
 Docspell can be configured to be a relying party for OpenID Connect.

website/site/content/docs/features/_index.md

@@ -44,6 +44,8 @@ description = "A list of features and limitations."
   upload files; these urls allow to be configured with metadata like
   tags, folder etc that are applied to all files uploaded through this
   url
+- [Share](@/docs/webapp/share.md) documents via cryptic public links
+  (optionally protected by a password)
 - [Send documents via e-mail](@/docs/webapp/mailitem.md)
 - [E-Mail notification](@/docs/webapp/notifydueitems.md) for documents
   with due dates

website/site/content/docs/webapp/share.md

@@ -0,0 +1,196 @@
++++
+title = "Shares"
+weight = 120
+[extra]
+mktoc = true
++++
+
+Docspell has a thought-out share feature that allows you to create
+read-only views to a subset of your documents and create a public but
+not-guessable link to it.
+
+# Concept
+
+A share is a cryptic *share id* that maps to a
+[query](@/docs/query/_index.md). A share can be accessed via a public
+link that contains the share id.
+
+{% infobubble(mode="warning", title="Please note") %}
+
+Everyone who has this link can access all documents resulting from the
+query and their metadata.
+
+{% end %}
+
+To further protect this link, a password can be specified which should
+be distributed via a different channel than the link. If a password is
+defined for a share, it is required to access the items. Otherwise,
+the share id is all that's needed.
+
+A share also requires to set a *publication end date* as a protection
+for leaving links available forever. Of course, you can explicitely
+set it to a very far away date should you really want it.
+
+The query is executed under the user who created the share. Thus it
+returns all the items the user can see. This is important when you
+have folders that are only visible to you. If you don't want to share
+certain items, you must alter the query accordingly.
+
+Given the nature of a query, there are two kinds of shares possible:
+dynamic and static ones. A dynamic share uses a query that may yield
+different results over time, for example `tag:invoice`. A static query
+is a query that explicitely selects items by their id. This means the
+latter will always result in the selected items (except if one of them
+is deleted); whereas the former query could return different results
+each time it is executed, because new documents could have been added
+in the meantime that now match the criteria (like tagged with
+`invoice` in the example).
+
+A share can be enabled and disabled to quickly make it available or
+hidden.
+
+
+## Use Cases
+
+A useful application for shares is to have a simple view to documents
+that are not sensible, like manuals. You could create a share for all
+your manuals, for example using tags `tags:manual` and bookmark it.
+
+Another use case is to share sensible documents with a partner who
+needs access to it, for example if you want to share all your tax
+documents with the company/person who helps you with doing you tax
+submission.
+
+# Creating shares
+
+There are the following ways to create a share:
+
+1. From the search page: enter a query or use the search menu and then
+   click the *share* button to share the resulting documents. This
+   usually creates a dynamic share.
+2. From selecting items: In the search view, click *Select Mode* and
+   select a few items. Then click the *share* button to share exactly
+   these items. This will create a static share.
+3. By creating it manually: You can also go to *Collective Profile*
+   and create a new share using the provided form.
+
+Once you created the share, you can copy the url or send it via e-mail
+(requires to have [e-mail
+settings](@/docs/webapp/emailsettings.md#smtp-settings) defined).
+
+## Creating from search results
+
+When at the search page, add some criteria until you have the results
+you want to publish. In the screenshot below all items with tag
+`Manual` are selected. Then click the *Share Button*.
+
+{{ figure(file="share-01.png") }}
+
+A form appears that lets you edit the query and set some properties.
+The query is taken from the search page and may look a bit strange. It
+will use ids rather than names, which makes the query a bit more
+robust. For example: the query `tag=manual` also works, but should you
+rename the tag, the share won't work anymore. By using ids as in
+`tag.id=4AUye…`, the query is immune to renamings.
+
+A name can be given to make it better distinguishable from other
+shares. Then a password and the *Publish Until* date can be set. The
+*Publish Until* date is mandatory. You can set it to something very
+far away to have shares exist "forever".
+
+{{ figure(file="share-02.png") }}
+
+Clicking *Cancel* brings you back to the search results. If you are
+satifsied, click *Publish*. The next screen allows you to inspect your
+new share and to copy the url and/or send an e-mail. The email form is
+prefilled with some template that contains the link, so you don't need
+to copy it.
+
+{{ figure(file="share-03.png") }}
+
+The new share can now be found in *Collective Profile -> Shares*.
+Clicking *Done* brings you back to the search results.
+
+## Creating from selecting items
+
+Creating a share for a hand picked set of items is almost the same as
+the above. In the search page, go to *Select Mode* and select some
+items.
+
+{{ figure(file="share-04.png") }}
+
+Then click the *Share* button and follow the same process as described
+above. The query selects now exactly the picked items like in
+`id~=AhVX…,FG65Xy…`.
+
+
+## Creating manually
+
+At *Collective Profile -> Shares* there is a *New share* button, which
+will present a form where you can create a share. The query must then
+be filled manually (there is some syntax help). It is the same query
+as in the "power search" bar, as described
+[here](@/docs/query/_index.md).
+
+{{ figure(file="share-12.png") }}
+
+## Managing Shares
+
+Go to *Collective Profile -> Shares* to see all the shares of your
+collective. You can also look into shares that were created by other
+users.
+
+{{ figure(file="share-06.png") }}
+
+To not make it too easy to look into private folders, you cannot
+change attributes of shares that were created by another user.
+However, you can delete all shares. This is for now a compromise,
+assuming small groups that still talk to each other: All users of a
+collective are equal and should be able to see shares and also delete
+them. But since a share of another user could be used to easily look
+into folders where you are not a member, editing other shares is not
+allowed.
+
+If you edit your own share, you can change its properties.
+
+{{ figure(file="share-07.png") }}
+
+If you are not the owner, the form is hidden:
+
+{{ figure(file="share-08.png") }}
+
+
+# Accessing a share
+
+Pasting the share link into a browser shows you the results of the
+query:
+
+{{ figure(file="share-09.png") }}
+
+The search input allows to do a fulltext search and the search menu to
+the left can be used to further constrain the results. The search will
+be combined with the stored query, such that the results always remain
+within the original results of the share.
+
+The options in the dropdown menus for correspondent, concerning etc
+are taken from the results. So only the data that is shared by the
+search results will be available to select. Other data is not leaked.
+
+Clicking the search icon next to the search input, switches the input
+to be the "power search" input:
+
+{{ figure(file="share-11.png") }}
+
+There is a link below the input field that opens a new tab with the
+[query documentation page](@/docs/query/_index.md).
+
+The user can click on the tags and other data in the item cards which
+will populate the corresponding section in the search menu, just like
+the default search view. You can click on an item card to go to the
+detail view:
+
+{{ figure(file="share-10.png") }}
+
+This link to a single item is also bookmarkable. You can copy it via
+the QR code or by clicking the *Copy* button. In the detail view you
+can select multiple attachments and download each.