Mercurial > prosody-modules
annotate mod_unified_push/README.md @ 5401:c8d04ac200fc
mod_http_oauth2: Reject loopback URIs as client_uri
This really should be a proper website with info, https://localhost is
not good enough. Ideally we'd validate that it's got proper DNS and is
actually reachable, but triggering HTTP or even DNS lookups seems like
it would carry abuse potential that would best to avoid.
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Tue, 02 May 2023 16:20:55 +0200 |
parents | 9032143bad08 |
children |
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 | |