mod_voipms: New Module to send and receive SMS/MMS via VoIP.ms APIs. diff --git a/mod_voipms/README.md b/mod_voipms/README.md new file mode 100644 --- /dev/null +++ b/mod_voipms/README.md @@ -0,0 +1,51 @@ +--- +labels: +- 'Stage-Alpha' +- 'Type-Web' +summary: Send and receive SMS/MMS via VoIP.ms APIs. +rockspec: + build: + modules: + mod_voipms: mod_voipms.lua +... + +Introduction +============ + +This is a Prosody module to map JIDs to DIDs on VoIP.ms and support sending/receiving SMS/MMS. + +Configuration +============= + +| option | type | default | +|-----------------------|--------|---------| +| voipms\_api\_username | string | nil | +| voipms\_api\_password | string | nil | +| voipms\_query\_key | string | nil | +| voipms\_jid\_map | table | nil | +``` +VirtualHost "sms.example.com" +modules_enabled = { + "voipms"; +} +voipms_api_username = john@example.com -- E-mail registered with VoIP.ms +voipms_api_password = abcd1234 -- API password configured in VoIP.ms +voipms_query_key = some_query_key -- query param 'key' part of your URL callback +voipms_jid_map = { + ["your_jid@your_domain.com"] = "+1234567890" +} +``` + +HTTP +==== + +The module is served on Prosody's default HTTP ports at the path /voipms. More details on configuring HTTP modules in Prosody can be found in the HTTP documentation. + +VoIP.ms Webhook URL +=================== + +This module receives the VoIP.ms Webhook URL (POST) at the /voipms endpoint. It uses the sendSMS/sendMMS GET methods against the VoIP.ms APIs. This is an example webhook to use in VoIP.ms: + +``` +https://sms.example.com/voipms?key=some_query_key +``` diff --git a/mod_voipms/mod_voipms.lua b/mod_voipms/mod_voipms.lua new file mode 100644 --- /dev/null +++ b/mod_voipms/mod_voipms.lua @@ -0,0 +1,166 @@ +local http = require "net.http" +local json = require "util.json" +local st = require "util.stanza" + +local api_username = module:get_option_string("voipms_api_username") +local api_password = module:get_option_string("voipms_api_password") +local query_key = module:get_option("voipms_query_key") +local jid_map = module:get_option("voipms_jid_map") or {} +local rest_endpoint = "https://voip.ms/api/v1/rest.php" + +if not api_username or not api_password or not query_key then + module:log("error", "Missing required config values (voipms_api_username, voipms_api_password, voipms_query_key)") + return +end + +module:depends("http") + +local function normalize_number(num) + if not num then return nil end + if num:sub(1, 1) ~= "+" then + return "+1" .. num + end + return num +end + +local function extract_query_key(event) + return (event.request.url.query or ""):match("key=([^&]+)") +end + +module:provides("http", { + route = { + ["POST"] = function(event) + local req = event.request + local body = req.body or "" + + if extract_query_key(event) ~= query_key then + module:log("warn", "Unauthorized webhook: missing or invalid key") + return { status_code = 403 } + end + + local json_payload, err = json.decode(body) + if not json_payload then + module:log("warn", "Invalid JSON: %s", err or "unknown error") + return { status_code = 400 } + end + + local payload = json_payload.data and json_payload.data.payload + if not payload then + module:log("warn", "Missing payload in JSON") + return { status_code = 400 } + end + + local from = payload.from and payload.from.phone_number + local to_list = payload.to or {} + local to = #to_list > 0 and to_list[1].phone_number or nil + + if not from or not to then + module:log("warn", "Missing phone numbers (from: %s, to: %s)", tostring(from), tostring(to)) + return { status_code = 400 } + end + + local normalized_to = normalize_number(to) + local target_jid = nil + + for jid, did in pairs(jid_map) do + if normalize_number(did) == normalized_to then + target_jid = jid + break + end + end + + if not target_jid then + module:log("warn", "No JID mapping for DID %s", normalized_to) + return { status_code = 404 } + end + + local normalized_from = normalize_number(from) + local message_text = payload.text or "" + + local message = st.message({ + from = normalized_from .. "@" .. module.host, + to = target_jid, + type = "chat" + }):tag("body"):text(message_text):up() + + if payload.media and #payload.media > 0 then + for _, media_item in ipairs(payload.media) do + if media_item.url then + message_text = message_text .. "\n" .. media_item.url + message:tag("x", { xmlns = "jabber:x:oob" }) + :tag("url"):text(media_item.url):up():up() + end + end + end + + module:send(message) + module:log("info", "Delivered SMS from %s to %s", normalized_from, target_jid) + + return { status_code = 204 } + end + } +}) + +module:hook("message/bare", function(event) + local stanza = event.stanza + if stanza.attr.type ~= "chat" then return end + + local from_jid = stanza.attr.from + local to_jid = stanza.attr.to + local body = stanza:get_child_text("body") + if not body or body == "" then return end + + local from_number = jid_map[from_jid] + if not from_number then + module:log("warn", "No DID mapping for JID %s", from_jid) + return + end + + local to_number = to_jid:match("^([^@]+)") + if not to_number then + module:log("warn", "Malformed JID in message.to: %s", to_jid) + return + end + + to_number = normalize_number(to_number) + + local media_urls = {} + for line in body:gmatch("[^\r\n]+") do + if line:match("^https?://") then + table.insert(media_urls, line) + end + end + + local method = (#media_urls > 0) and "sendMMS" or "sendSMS" + local query = { + api_username = api_username, + api_password = api_password, + method = method, + did = from_number, + dst = to_number, + message = body + } + + if method == "sendMMS" then + for i, url in ipairs(media_urls) do + query["media_url[" .. (i - 1) .. "]"] = url + end + end + + local query_str = http.formencode(query) + + http.request(rest_endpoint .. "?" .. query_str, { + method = "GET"; + }, function(response_body, code) + if code == 200 then + local resp, err = json.decode(response_body) + if not resp or resp.status ~= "success" then + module:log("error", "Failed to send %s: %s", method, err or (resp and resp.status) or "unknown") + else + module:log("info", "Sent %s from %s to %s", method, from_number, to_number) + end + else + module:log("error", "HTTP error sending %s: code %s", method, tostring(code)) + end + end) +end)

# mod_auth_token

This module enables Prosody to authenticate time-based one-time-pin (TOTP) HMAC tokens.

This is an alternative to "external authentication" which avoids the need to
make a blocking HTTP call to the external authentication service (usually a web application backend).

Instead, the application generates the HMAC token, which is then sent to
Prosody via the XMPP client and Prosody verifies the authenticity of this
token.

If the token is verified, then the user is authenticated.

## Luarocks dependencies

You'll need to install the following luarocks

  otp 0.1-5
  luatz 0.3-1

## How to generate the TOTP seed and shared signing secret

You'll need a shared OTP_SEED value for generating time-based one-time-pin
(TOTP) values and a shared private key for signing the HMAC token.

You can generate the OTP_SEED value with Python, like so:

    >>> import pyotp
    >>> pyotp.random_base32()
    u'XVGR73KMZH2M4XMY'

and the shared secret key as follows:

    >>> import pyotp
    >>> pyotp.random_base32(length=32)
    u'JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7'

## Configuration

Firest you need to enable the relevant modules to your Prosody.cfg file.

Look for the line `modules_enabled` (either globally or for your
particular `VirtualHost`), and then add the following to tokens:

    modules_enabled = {
        -- Token authentication
            "auth_token";
            "sasl_token";
    }

The previously generated token values also need to go into your Prosody.cfg file:

    authentication = "token";
    token_secret = "JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7";
    otp_seed = "XVGR73KMZH2M4XMY";

The application that generates the tokens also needs access to these values.

For an example on how to generate a token, take a look at the `generate_token`
function in the `test_token_auth.lua` file inside this directory.

## Custom SASL auth

This module depends on a custom SASL auth mechanism called X-TOKEN and which
is provided by the file `mod_sasl_token.lua`.

Prosody doesn't automatically pick up this file, so you'll need to update your
configuration file's `plugin_paths` to link to this subdirectory (for example
to `/usr/lib/prosody-modules/mod_auth_token/`).

## Generating the token

Here's a Python snippet showing how you can generate the token that Prosody
will then verify:

    import base64
    import pyotp
    import random

    # Constants
    OTP_INTERVAL = 30
    OTP_DIGITS = 8

    jid = '{}@{}'.format(username, domain)

    otp_service = pyotp.TOTP(
        OTP_SEED,  # OTP_SEED must be set to the value generated previously (see above)
        digits=OTP_DIGITS,
        interval=OTP_INTERVAL
    )
    otp = otp_service.generate_otp(otp_service.timecode(datetime.utcnow()))

    nonce = ''.join([str(random.randint(0, 9)) for i in range(32)])
    string_to_sign = otp + nonce + jid
    signature = hmac.new(token_secret, string_to_sign, hashlib.sha256).digest()
    token = u"{} {}".format(otp+nonce, base64.b64encode(signature))