Add a `--umask` option to determine what permissions new files/databases get.

The new `--umask` option takes one of three values:

* `--umask masked`, the default, takes the inherited umask and forces o+rwx on.
* `--umask inherit` takes the inherited umask as-is.
* `--umask OCTAL` sets the umask to exactly `OCTAL` and is broadly equivalent to `umask OCTAL && pilcrow --umask inherit`.

This fell out of a conversation with @wlonk, who is working on notifications. Since notifications may require [VAPID] keys, the server will need a way to store those keys. That would generally be "in the pilcrow database," which lead me to the observation that Pilcrow creates that database as world-readable by default. "World-readable" and "encryption/signing keys" are not things that belong in the same sentence.

[VAPID]: https://datatracker.ietf.org/doc/html/rfc8292

The most "obvious" solution would be to set the permissions used for the sqlite database when it's created. That's harder than it sounds: sqlite has no built-in facility for doing this. The closest thing that exists today is the [`modeof`] query parameter, which copies the permissions (and ownership) from some other file. We also can't reliably set the permissions ourselves, as sqlite may - depending on build options and configuration - [create multiple files][wal].

[`modeof`]: https://www.sqlite.org/uri.html
[wal]: https://www.sqlite.org/wal.html

Using `umask` is a whole-process solution to this. As Pilcrow doesn't attempt to create other files, there's little issue with doing it this way, but this is a design risk for future work if it creates files that are _intended_ to be readable by more than just the Pilcrow daemon user.

Merges options-umask into main.

1 files changed, 12 insertions, 0 deletions

diff --git a/docs/ops.md b/docs/ops.md
index 4dfec49..a622c04 100644
--- a/docs/ops.md
+++ b/docs/ops.md
@@ -9,3 +9,15 @@ To avoid destroying backups that may still be needed, `pilcrow` will not start i
 - Start the server with **a copy** of the backup database, and determine if any data has been lost. If not, shut it down, replace your main database by copying the backup, and carry on.
 
 The `pilcrow` database is an ordinary file. While the server is not running, it can be freely copied or renamed without invalidating the data in it.
+
+## Permissions
+
+The Pilcrow database (`pilcrow.db` by default) should have restricted permissions, as it contains data that is either confidential (such as users' conversations), sensitive (such as the service's configuration), or both. At minimum, it should not be world-readable on the server where Pilcrow is installed.
+
+By default, the `pilcrow` command will set the process' umask to a value that prevents the creation of world-readable or world-writeable files, so that the Pilcrow database will be created with appropriate filesystem permissions. This behaviour can be controlled using the `--umask` startup option, which takes the following values:
+
+- `masked`, the default, which takes the inherited umask and additionally sets the world-readable, world-writeable, and world-executable bits;
+- `inherit`, which takes the inherited umask as-is, requiring the operator to set a sensible value here; or
+- any octal value corresponding to a valid umask, such as `0027`.
+
+Pilcrow does not check or change the permissions of the database after creation. Changing the umask of the server after the database has been created has no effect on the database's filesystem permissions.