annotate mod_register_json/README.md @ 6261:1c62edeb9147

mod_pastebin: Update Readme diff --git a/mod_pastebin/README.md b/mod_pastebin/README.md --- a/mod_pastebin/README.md +++ b/mod_pastebin/README.md @@ -37,12 +37,14 @@ For example: Pastes will be available by default at `http://<your-prosody>:5280/pastebin/` by default. -In Prosody 0.9 and later this can be changed with [HTTP -settings](https://prosody.im/doc/http). +Ports and path can be changed with [HTTP +settings](https://prosody.im/doc/http), for example like: -In 0.8 and older this can be changed with `pastebin_ports` (see below), -or you can forward another external URL from your web server to Prosody, -use `pastebin_url` to set that URL. +``` {.lua} + http_paths = { + pastebin = "/$host-paste"; + } +``` # Discovery @@ -82,27 +84,16 @@ The line and character tresholds are adv pastebin_line_threshold The maximum number of lines a message may have before it is sent to the pastebin. (default 4 lines) pastebin_trigger A string of characters (e.g. "!paste ") which if detected at the start of a message, always sends the message to the pastebin, regardless of length. (default: not set) pastebin_expire_after Number of hours after which to expire (remove) a paste, defaults to 24. Set to 0 to store pastes permanently on disk. - pastebin_ports List of ports to run the HTTP server on, same format as mod_httpserver's http_ports[^1] - pastebin_url Base URL to display for pastebin links, must end with / and redirect to Prosody's built-in HTTP server[^2] # Compatibility - ------ ------- - trunk Works + ------ --------------------- + trunk Works as of 25-06-13 + 13 Works 0.12 Works - 0.11 Works - 0.10 Works - 0.9 Works - 0.8 Works - ------ ------- + ------ --------------------- # Todo - Maximum paste length - Web interface to submit pastes? - -[^1]: As of Prosody 0.9, `pastebin_ports` is replaced by `http_ports`, - see [Prosody HTTP server documentation](https://prosody.im/doc/http) - -[^2]: See also - [http_external_url](https://prosody.im/doc/http#external_url)
author Menel <menel@snikket.de>
date Fri, 13 Jun 2025 11:39:58 +0200
parents fe081789f7b5
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2 labels:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 - 'Stage-Stable'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 summary: 'Token based JSON registration & verification servlet.'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 ...
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 ------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 This module let's you activate a httpserver interface to handle data
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11 from webforms with POST and Base64 encoded JSON.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13 Implementation Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 ----------------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16 Example Request format:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18 POST /your_register_base_url HTTP/1.1
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19 Host: yourserveraddress.com:yourchoosenport
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20 Content-Type: application/encoded
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21 Content-Transfer-Encoding: base64
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23 eyJ1c2VybmFtZSI6InVzZXJuYW1lb2ZjaG9pY2UiLCJwYXNzd29yZCI6InRoZXVzZXJwYXNzd29yZCIsImlwIjoidGhlcmVtb3RlYWRkcm9mdGhldXNlciIsIm1haWwiOiJ1c2VybWFpbEB1c2VybWFpbGRvbWFpbi50bGQiLCJhdXRoX3Rva2VuIjoieW91cmF1dGh0b2tlbm9mY2hvaWNlIn0=
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25 Where the encoded content is this (example) JSON Array:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26
3292
42dac034b2e0 mod_register_json/README: Add syntax hint
Kim Alvefur <zash@zash.se>
parents: 3291
diff changeset
27 ``` {.json}
3291
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
28 {
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
29 "username":"john.smith",
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
30 "password":"secret-password",
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
31 "ip":"192.168.0.0",
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
32 "mail":"john.smith@mail.example.net",
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
33 "auth_token":"yourauthtokenofchoice"
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
34 }
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
35 ```
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37 Your form implementation needs to pass **all** parameters, the
2876
ea6b5321db50 README files: Fix typos
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
38 auth\_token is needed to prevent misuses, if the request is successful
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39 the server will answer with status code 200 and with the body of the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40 response containing the token which your web app can send via e-mail to
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
41 the user to complete the registration.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43 Else, it will reply with the following http error codes:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45 - 400 - if there's an error syntax;
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46 - 401 - whenever an username is already pending registration or the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
47 auth token supplied is invalid;
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
48 - 403 - whenever registration is forbidden (blacklist, filtered mail
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49 etc.);
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50 - 406 - if the username supplied fails nodeprepping;
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51 - 409 - if the user already exists, or an user is associated already
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52 with the supplied e-mail;
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53 - 503 - whenever a request is throttled.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55 The verification URL path to direct the users to will be:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
56 **/your-base-path-of-choice/verify/** - on your Prosody's http server.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
57
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58 The module for now stores a hash of the user's mail address to help slow
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
59 down duplicated registrations.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61 It's strongly encouraged to have the web server communicate with the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62 servlet via https.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
63
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64 Usage
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65 -----
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67 Copy the module folder and all its contents (register\_json) into your
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68 prosody modules' directory.Add the module your vhost of choice
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
69 modules\_enabled.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71 Hint: pairing with mod\_register\_redirect is helpful, to allow server
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72 registrations only via your webform.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73
3291
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
74
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
75 Required configuration:
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
76
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
77 ```
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
78 reg_servlet_auth_token = "your-secret-token"
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
79 ```
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
80
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
81 Optional configuration directives:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
82
3291
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
83 ```
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
84 reg_servlet_base = "/base-path/" -- Base path of the plugin (default is register_account)
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
85 reg_servlet_secure = true -- Have the plugin only process requests on https (default is true)
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
86 reg_servlet_ttime = seconds -- Specifies the time (in seconds) between each request coming from the same remote address.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
87 reg_servlet_bl = { "1.2.3.4", "4.3.2.1" } -- The ip addresses in this list will be blacklisted and will not be able to submit registrations.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
88 reg_servlet_wl = { "1.2.3.4", "4.3.2.1" } -- The ip addresses in this list will be ignored by the throttling.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
89 reg_servlet_filtered_mails = { ".*banneddomain.tld", ".*deamailprovider.tld" } -- allows filtering of mail addresses via Lua patterns.
3291
4c3230c22c18 mod_register_json: Update README
Matthew Wild <mwild1@gmail.com>
parents: 2876
diff changeset
90 ```
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
91
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
92 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
93 -------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
94
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
95 0.9