diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/events.md | 30 | ||||
| -rw-r--r-- | docs/ops.md | 14 |
2 files changed, 44 insertions, 0 deletions
diff --git a/docs/api/events.md b/docs/api/events.md index e692f82..9db4613 100644 --- a/docs/api/events.md +++ b/docs/api/events.md @@ -237,3 +237,33 @@ These events have the `event` field set to `"deleted"`. They include the followi | :---- | :-------- | :---------------------------------- | | `at` | timestamp | The moment the message was deleted. | | `id` | string | The deleted message's ID. | + +## VAPID key events + +The following events describe changes to Pilcrow's [VAPID key](https://developer.mozilla.org/en-US/docs/Web/API/PushManager/subscribe#applicationserverkey). + +These events have the `type` field set to `"vapid"`. + +### VAPID key changed + +```json +{ + "type": "vapid", + "event": "changed", + "at": "2025-08-30T05:44:58.100206Z", + "key": "BKILjh0SzTiHOZ5P_sfduv-iqtOg_S18nR7ePcjnDivJaOY6nOG1L3OmvjXjNnthlRDdVnawl1_owfdPCvmDt5U=" +} +``` + +Sent whenever the server's VAPID key changes. + +These events have the `event` field set to `"changed"`. They include the following additional fields: + +| Field | Type | Description | +| :---- | :-------- | :----------------------------------------------------------------------------------------------- | +| `at` | timestamp | The moment the key was changed. | +| `key` | string | A URL-safe Base64 encoding of the VAPID public key, usable to create new Web Push subscriptions. | + +The server may change its VAPID key at any time, and will do so periodically to manage the risk of the private key being leaked. When the key is changed, old keys are immediately destroyed, and the corresponding change events are removed from the event stream. + +Clients must use the most recent VAPID key when creating Web Push subscriptions. If the key changes, clients must invalidate or recreate existing subscriptions - the previous key is no longer valid and will no longer be used, and push subscriptions using that key will not be fulfilled. diff --git a/docs/ops.md b/docs/ops.md index a622c04..678d2a4 100644 --- a/docs/ops.md +++ b/docs/ops.md @@ -21,3 +21,17 @@ By default, the `pilcrow` command will set the process' umask to a value that pr - 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. + +## VAPID keys + +Pilcrow uses [VAPID] to identify itself to public Web Push brokers, which then deliver notifications to Pilcrow's users of interesting events, such as messages. VAPID uses cryptographic signatures to authenticate the server. + +[VAPID]: https://datatracker.ietf.org/doc/html/rfc8292 + +The key is stored in the `pilcrow` database. Pilcrow will create its key automatically, and will rotate the key every 30 days. + +If the `pilcrow` database is accessed inappropriately or leaked, then the key can be used to send push notifications to Pilcrow users as if from the Pilcrow server. If this happens, the key _must_ be rotated to prevent misuse. + +The key can be rotated at any time running `pilcrow […options…] rotate-vapid-key`, as the same user Pilcrow normally runs as. This does not require that the server be shut down or restarted. The `[…options…]` must be set to the same values as used by the running server. + +When the key is rotated, no further push messages will be sent from the Pilcrow server using that key. Unfortunately, the Web Push protocol doesn't allow Pilcrow to proactively invalidate clients' push subscriptions, but Pilcrow will inform clients when the key is rotated so that they can invalidate the affected subscriptions themselves. |