# HG changeset patch
# User Matthew Wild <mwild1@gmail.com>
# Date 1599828647 -3600
# Node ID 2b6918714792e4cd76c5249add064b78410ef5d4
# Parent  354dc1e7977ad2330f90ae6cb1d47db8ccabfb4f
mod_invites_adhoc: New module to allow invite creation via ad-hoc commands (XEP-0401)

diff -r 354dc1e7977a -r 2b6918714792 mod_invites_adhoc/README.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_invites_adhoc/README.markdown	Fri Sep 11 13:50:47 2020 +0100
@@ -0,0 +1,48 @@
+---
+labels:
+- 'Stage-Beta'
+summary: 'Enable ad-hoc command for XMPP clients to create invitations'
+...
+
+Introduction
+============
+
+This module is part of the suite of modules that implement invite-based
+account registration for Prosody. The other modules are:
+
+- mod_invites
+- mod_invites_page
+- mod_invites_register
+- mod_invites_register_web
+- mod_register_apps
+
+For details and a full overview, start with the mod_invites documentation.
+
+Details
+=======
+
+mod_invites_adhoc allows XMPP clients to create new invites on the server.
+Clients must support either XEP-0401 (Easy Onboarding) or XEP-0050 (Ad-hoc
+commands).
+
+There are three types of invitation that can be created:
+
+| Account-only invites | These can be used to register a new account |
+| Contact-only invites | These can be shared with a contact so they can easily add you to their contact list |
+| Account-and-contact invites | Like a contact-only invite, but also allows the contact to register on the current server if they don't already have an XMPP account |
+
+Only configured admins of the server are able to create account-only invites. By default
+normal users may only create contact-only invites, but account-and-contact invites can
+be enabled with the `allow_user_invites` option.
+
+Configuration
+=============
+
+| Name                  | Description                                                           | Default                                   |
+|-----------------------|-----------------------------------------------------------------------|-------------------------------------------|
+| allow_user_invites    | Whether non-admin users can invite contacts to register on this server| `false`                                   |
+| allow_contact_invites | Whether non-admin users can invite contacts to their roster           | `true`                                    |
+
+The `allow_user_invites` option should be set as desired. However it is
+strongly recommended to leave the other option (`allow_contact_invites`)
+at its default to provide the best user experience.
\ No newline at end of file
diff -r 354dc1e7977a -r 2b6918714792 mod_invites_adhoc/mod_invites_adhoc.lua
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_invites_adhoc/mod_invites_adhoc.lua	Fri Sep 11 13:50:47 2020 +0100
@@ -0,0 +1,80 @@
+-- XEP-0401: Easy User Onboarding
+local dataforms = require "util.dataforms";
+local datetime = require "util.datetime";
+local split_jid = require "util.jid".split;
+
+local new_adhoc = module:require("adhoc").new;
+
+-- Whether local users can invite other users to create an account on this server
+local allow_user_invites = module:get_option_boolean("allow_user_invites", false);
+-- Who can see and use the contact invite command. It is strongly recommended to
+-- keep this available to all local users. To allow/disallow invite-registration
+-- on the server, use the option above instead.
+local allow_contact_invites = module:get_option_boolean("allow_contact_invites", true);
+
+local invites;
+if prosody.shutdown then -- COMPAT hack to detect prosodyctl
+	invites = module:depends("invites");
+end
+
+local invite_result_form = dataforms.new({
+		title = "Your invite has been created",
+		{
+			name = "url" ;
+			var = "landing-url";
+			label = "Invite web page";
+			desc = "Share this link";
+		},
+		{
+			name = "uri";
+			label = "Invite URI";
+			desc = "This alternative link can be opened with some XMPP clients";
+		},
+		{
+			name = "expire";
+			label = "Invite valid until";
+		},
+	});
+
+module:depends("adhoc");
+
+-- This command is available to all local users, even if allow_user_invites = false
+-- If allow_user_invites is false, creating an invite still works, but the invite will
+-- not be valid for registration on the current server, only for establishing a roster
+-- subscription.
+module:provides("adhoc", new_adhoc("Create new contact invite", "urn:xmpp:invite#invite",
+		function (_, data)
+			local username = split_jid(data.from);
+			local invite = invites.create_contact(username, allow_user_invites);
+			--TODO: check errors
+			return {
+				status = "completed";
+				form = {
+					layout = invite_result_form;
+					values = {
+						uri = invite.uri;
+						url = invite.landing_page;
+						expire = datetime.datetime(invite.expires);
+					};
+				};
+			};
+		end, allow_contact_invites and "local_user" or "admin"));
+
+-- This is an admin-only command that creates a new invitation suitable for registering
+-- a new account. It does not add the new user to the admin's roster.
+module:provides("adhoc", new_adhoc("Create new account invite", "urn:xmpp:invite#create-account",
+		function ()
+			local invite = invites.create_account();
+			--TODO: check errors
+			return {
+				status = "completed";
+				form = {
+					layout = invite_result_form;
+					values = {
+						uri = invite.uri;
+						url = invite.landing_page;
+						expire = datetime.datetime(invite.expires);
+					};
+				};
+			};
+		end, "admin"));