Mercurial > prosody-modules

annotate mod_unified_push/README.md @ 5256:44f7edd4f845

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_oauth2: Reject non-local hosts in more code paths We're not issuing tokens for users on remote hosts, we can't even authenticate them since they're remote. Thus the host is always the local module.host so no need to pass around the host in most cases or use it for anything but enforcing the same host.
author Kim Alvefur <zash@zash.se>
date Thu, 16 Mar 2023 17:52:10 +0100
parents 9032143bad08
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - Stage-Alpha
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: "Unified Push provider"
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ---
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 This module implements a [Unified Push](https://unifiedpush.org/) Provider
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 that uses XMPP to talk to a Push Distributor (e.g. [Conversations](http://codeberg.org/iNPUTmice/Conversations)).
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
10 It allows push notifications to be delivered to apps on your device over XMPP.
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
11 This means notifications can be delivered quickly and efficiently (apps don't
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
12 need to repeatedly poll for new notifications).
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
13
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
14 For a list of compatible apps, see the [UnifiedPush apps list](https://unifiedpush.org/users/apps/).
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
15
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
16 A server-independent external component is also available - see [the 'up'
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
17 project](https://codeberg.org/inputmice/up). That project also contains a
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
18 description of the protocol between the XMPP server and the client.
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 This module and the protocol it implements is at an experimental prototype
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 stage.
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 Note that this module is **not related** to XEP-0357 push notifications for
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 XMPP. It does not send push notifications to disconnected XMPP clients. For
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 that, see [mod_cloud_notify](https://modules.prosody.im/mod_cloud_notify).
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 ## Configuration
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28
5156
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
29 | Name | Description | Default |
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
30 |-------------------------------|---------------------------------------------------------|---------------------------------------------|
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
31 | unified_push_acl | A list of domains or users permitted to use the service | current host, or parent host if a component |
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
32 | unified_push_backend | Backend to use: "paseto", "storage" or "jwt" | "paseto" (trunk), "storage" (0.12) |
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
33 | unified_push_registration_ttl | Maximum lifetime of a push registration (seconds) | `86400` (1 day) |
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
34
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
35 ### Backends
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
36
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
37 The module needs to track registrations, and be able to associate tokens with
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
38 users. There are multiple ways to do this, but not every method is supported
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
39 on every Prosody version.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
40
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
41 By default the module will automatically select the best backend that is
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
42 supported on the current Prosody version you are using.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
43
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
44 #### storage backend
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
45
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
46 This is the default backend on Prosody 0.12 and earlier. It stores tokens and
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
47 their associated data in Prosody's configured data store.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
48
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
49 Supported by all Prosody versions.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
50
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
51 #### paseto backend
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
52
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
53 This is a stateless (i.e. no storage required) backend that uses encrypted
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
54 [PASETO tokens](https://paseto.io/) to store registration info. It is the
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
55 default backend on Prosody trunk, as PASETO support is not available in
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
56 Prosody 0.12 and earlier.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
57
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
58 #### jwt backend
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
59
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
60 This is a stateless backend that uses [JWT tokens](https://jwt.io/) to store
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
61 registration info. It is supported in Prosody 0.12 and higher.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
62
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
63 **Note:** The JWT tokens are **not encrypted**, which means the JID
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
64 associated with a registration is visible to apps and services that send you
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
65 push notifications. This can have privacy implications. If in doubt, do not
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
66 use this backend.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
67
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
68 This backend requires you to set a secure random string in the config file,
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
69 using the `unified_push_secret` option.
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 A random push secret can be generated with the command
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72 `openssl rand -base64 32`. Changing the secret will invalidate all existing
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73 push registrations.
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74
5156
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
75 ### HTTP configuration
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
76
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
77 This module exposes a HTTP endpoint (to receive push notifications from app
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
78 servers). For more information on configuring HTTP services in Prosody, see
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
79 [Prosody HTTP documentation](https://prosody.im/doc/http).
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
80
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
81 #### Example configuration
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
82
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
83 ##### Normal method
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
84
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
85 Just add just add `"unified_push"` to your `modules_enabled` option.
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
86 This is the easiest and **recommended** configuration.
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
87
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
88 ``` {.lua}
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
89 modules_enabled = {
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
90 ---
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
91 "unified_push";
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
92 ---
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
93 }
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
94 ```
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
95
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
96 ##### Component method
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
97
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
98 This is an example of how to configure the module as an internal component,
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
99 e.g. on a subdomain or other non-user domain.
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
100
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
101 This example creates a push notification component called
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
102 'notify.example.com'.
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
103
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
104 The 'http_host' line instructs Prosody to expose this module's HTTP services
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
105 on the 'example.com' host, which avoids needing to create/update DNS records
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
106 and HTTPS certificates if example.com is already set up.
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
107
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
108 ``` {.lua}
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
109 Component "notify.example.com" "unified_push"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
110 unified_push_secret = "<secret string here>"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
111 http_host = "example.com"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
112 ```
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
113
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
114 ## Compatibility
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
115
5139
449e4ca4de32 mod_unified_push: Remove dependency on trunk util.jwt (0.12 compat)
Matthew Wild <mwild1@gmail.com>
parents: 5138
diff changeset
116 | trunk | Works |
5156
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
117 | 0.12 | Works |