Introduction

This module is part of the suite of modules that implement invite-based account registration for Prosody. The other modules are:

Additional functionality is also available as community modules:

This module manages the creation and consumption of invite codes for the host(s) it is loaded onto. It currently does not expose any admin/user-facing functionality (though in the future it will probably gain a way to view/manage pending invites).

Instead, other modules can use the API from this module to create invite tokens which can be used to e.g. register accounts or create automatic subscription approvals.

This module should not be confused with the similarly named mod_invite (note the missing ‘s’!). That module was a precursor to this one that helped test and prove the concept of invite-based registration, and is now deprecated.

Configuration

This module exposes just one option - the length of time that a generated invite should be valid for by default.

-- Configure the number of seconds a token is valid for (default 7 days)
invite_expiry = 86400 * 7

Invites setup

For a fully-featured invite-based setup, the following provides an example configuration:

-- Specify the external URL format of the invite links

VirtualHost "example.com"
modules_enabled = {
    "invites";
    "invites_adhoc";
    "invites_register";
}

Restart Prosody and create a new invite using an ad-hoc command in an XMPP client connected to your admin account, or use the command line:

prosodyctl mod_invites generate example.com

External dependencies

The default HTML templates for the web-based modules1 depend on the Bootstrap 4 CSS and JavaScript libraries, and the jQuery library. They expect these to be available at https://example.com/share.

An easy way to provide theam instead if you are on Debian 10 (buster) is to enable mod_http_libjs and install the following packages:

apt install libjs-bootstrap4 libjs-jquery

On other systems you will need to manually fetch and put these libraries somewhere on the filesystem that Prosody can read, and serve them using mod_http_libjs with a custom libjs_path setting.

Command

When invoked via prosodyctl, mod_invites currently exposes a single sub-command, generate, for generating new invites.

generate

Two kinds of invites can be generated on the command line using prosodyctl, regular invites that facilitate creation of a new account, and password reset invites that enable an existing user to reset their password.

Regular account invite

For the most basic case of generating a new invite, only a VirtualHost name is supplied as an argument:

sudo prosodyctl mod_invites generate example.com

Assigning roles

To generate an admin invite, e.g. for yourself the first time you start Prosody, pass the --admin flag:

sudo prosodyctl mod_invites generate example.com --admin

This automatically assigns the prosody:admin role account(s) created from this invite.

Other roles can be set using the --role flag.

sudo prosodyctl mod_invites generate example.com --role prosody:member

Password reset invite

To create a password reset invite for jdoe@example.com, you would pass the username using the --reset flag like:

sudo prosodyctl mod_invites generate example.com --reset jdoe

The invite should then be securely communicated to the user.

  1. mod_invites_register_web and mod_invites_page↩︎