annotate mod_pubsub_subscription/README.markdown @ 5193:2bb29ece216b

mod_http_oauth2: Implement stateless dynamic client registration Replaces previous explicit registration that required either the additional module mod_adhoc_oauth2_client or manually editing the database. That method was enough to have something to test with, but would not probably not scale easily. Dynamic client registration allows creating clients on the fly, which may be even easier in theory. In order to not allow basically unauthenticated writes to the database, we implement a stateless model here. per_host_key := HMAC(config -> oauth2_registration_key, hostname) client_id := JWT { client metadata } signed with per_host_key client_secret := HMAC(per_host_key, client_id) This should ensure everything we need to know is part of the client_id, allowing redirects etc to be validated, and the client_secret can be validated with only the client_id and the per_host_key. A nonce injected into the client_id JWT should ensure nobody can submit the same client metadata and retrieve the same client_secret
author Kim Alvefur <zash@zash.se>
date Fri, 03 Mar 2023 21:14:19 +0100
parents 97fac0ba0469
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4511
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 # Introduction
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 This module lets you programmatically subscribe to updates from a
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 [pubsub][xep0060] node, even if the pubsub service is remote.
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6 ## Example
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 ``` {.lua}
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9 module:depends("pubsub_subscription");
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 module:add_item("pubsub-subscription", {
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11 service = "pubsub.example.com";
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12 node = "otter_facts";
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 -- Callbacks:
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15 on_subscribed = function()
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16 module:log("info", "Otter facts incoming!");
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 end;
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19 on_item = function(event)
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20 module:log("info", "Random Otter Fact: %s", event.payload:get_text());
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21 end;
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22 });
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23 ```
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25 ## Usage
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27 Ensure the module is loaded and add your subscription via the
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28 `:add_item` API. The item table MUST have `service` and `node` fields
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
29 and SHOULD have one or more `on_<event>` callbacks.
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31 The JID of the pubsub service is given in `service` (could also be the
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32 JID of an user for advanced PEP usage) and the node is given in,
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33 unsurprisingly, the `node` field.
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35 The various `on_event` callback functions, if present, gets called when
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36 new events are received. The most interesting would be `on_item`, which
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37 receives incoming items. Available events are:
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39 `on_subscribed`
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40 : The subscription was successful, events may follow.
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
41
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42 `on_unsubscribed`
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43 : Subscription was removed successfully, this happens if the
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44 subscription is removed, which you would normally never do.
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46 `on_error`
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
47 : If there was an error subscribing to the pubsub service. Receives a
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
48 table with `type`, `condition`, `text`, and `extra` fields as
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49 argument.
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51 `on_item`
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52 : An item publication, the payload itself available in the `payload`
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53 field in the table provided as argument. The ID of the item can be
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54 found in `item.attr.id`.
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
56 `on_retract`
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
57 : When an item gets retracted (removed by the publisher). The ID of
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58 the item can be found in `item.attr.id` of the table argument..
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
59
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60 `on_purge`
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61 : All the items were removed by the publisher.
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
63 `on_delete`
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64 : The entire pubsub node was removed from the pubsub service. No
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65 subscription exists after this.
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67 ``` {.lua}
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68 event_payload = {
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
69 -- Common prosody event entries:
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70 stanza = util.stanza;
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71 origin = util.session;
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73 -- PubSub service details
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
74 service = "pubsub.example.com";
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
75 node = "otter_facts";
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
76
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
77 -- The pubsub event itself
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
78 item = util.stanza; -- <item/>
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
79 payload = util.stanza; -- actual payload, child of <item/>
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
80 }
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
81 ```
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
82
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
83 # Compatibility
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
84
97fac0ba0469 mod_pubsub_subscription: New module providing an API for pubsub subscriptions
Kim Alvefur <zash@zash.se>
parents:
diff changeset
85 Should work with Prosody \>= 0.11.x