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)

---
labels:
- 'Stage-Alpha'
summary: 'Implementation of PROXY protocol versions 1 and 2'
...

Introduction
============

This module implements the PROXY protocol in versions 1 and 2, which fulfills
the following usecase as described within the official protocol specifications:

> Relaying TCP connections through proxies generally involves a loss of the
> original TCP connection parameters such as source and destination addresses,
> ports, and so on.
> 
> The PROXY protocol's goal is to fill the server's internal structures with the
> information collected by the proxy that the server would have been able to get
> by itself if the client was connecting directly to the server instead of via a
> proxy.

You can find more information about the PROXY protocol on
[the official website](https://www.haproxy.com/blog/haproxy/proxy-protocol/)
or within
[the official protocol specifications.](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)


Usage
=====

Copy the plugin into your prosody's modules directory. And add it
between your enabled modules into the global section (modules\_enabled).

As the PROXY protocol specifications do not allow guessing if the PROXY protocol
shall be used or not, you need to configure separate ports for all the services
that should be exposed with PROXY protocol support:

```lua
--[[
  Maps TCP ports to a specific Prosody network service. Further information about
  available service names can be found further down below in the module documentation.
]]-- 
proxy_port_mappings = {
	[15222] = "c2s",
	[15269] = "s2s"
}

--[[
  Specifies a list of trusted hosts or networks which may use the PROXY protocol
  If not specified, it will default to: 127.0.0.1, ::1 (local connections only)
  An empty table ({}) can be configured to allow connections from any source.
  Please read the module documentation about potential security impact.
]]-- 
proxy_trusted_proxies = {
	"192.168.10.1",
	"172.16.0.0/16"
}

--[[
  While you can manually override the ports this module is listening on with
  the "proxy_ports" directive, it is highly recommended to not set it and instead
  only configure the appropriate mappings with "proxy_port_mappings", which will
  automatically start listening on all mapped ports.

  Example: proxy_ports = { 15222, 15269 }
]]--
```

The above example configuration, which needs to be placed in the global section,
would listen on both tcp/15222 and tcp/15269. All incoming connections have to 
originate from trusted hosts/networks (configured by _proxy_trusted_proxies_) and
must be initiated by a PROXYv1 or PROXYv2 sender. After processing the PROXY
protocol, those connections will get mapped to the configured service name.

Please note that each port handled by _mod_net_proxy_ must be mapped to another
service name by adding an item to _proxy_port_mappings_, otherwise a warning will
be printed during module initialization and all incoming connections to unmapped ports
will be dropped after processing the PROXY protocol requests.

The service name can be found by analyzing the source of the module, as it is the
same name as specified within the _name_ attribute when calling
`module:provides("net", ...)` to initialize a network listener. The following table
shows the names for the most commonly used Prosody modules:

  ------------- --------------------------
  **Module**    **Service Name**
  c2s           c2s (Plain/StartTLS)
  s2s           s2s (Plain/StartTLS)
  proxy65       proxy65 (Plain)
  http          http (Plain)
  net_multiplex multiplex (Plain/StartTLS)
  ------------- --------------------------

This module should work with all services that are providing ports which either
offer plaintext or StartTLS-based encryption. Please note that instead of using
this module for HTTP-based services (BOSH/WebSocket) it might be worth resorting
to use proxy which is able to process HTTP and insert a _X-Forwarded-For_ header
instead.


Example
=======

This example provides you with a Prosody server that accepts regular connections on
tcp/5222 (C2S) and tcp/5269 (S2S) while also offering dedicated PROXY protocol ports
for both modules, configured as tcp/15222 (C2S) and tcp/15269 (S2S):

```lua
c2s_ports = {5222}
s2s_ports = {5269}
proxy_port_mappings = {
	[15222] = "c2s",
	[15269] = "s2s"
}
```

After adjusting the global configuration of your Prosody server accordingly, you can
configure your desired sender accordingly. Below is an example for a working HAProxy
configuration which will listen on the default XMPP ports (5222+5269) and connect to
your XMPP backend running on 192.168.10.10 using the PROXYv2 protocol:

```
defaults d-xmpp
	log global
	mode tcp
	option redispatch
	option tcplog
	option tcpka
	option clitcpka
	option srvtcpka
	
	timeout connect 5s
	timeout client 24h
	timeout server 60m

frontend f-xmpp
	bind :::5222,:::5269 v4v6
	use_backend b-xmpp-c2s if { dst_port eq 5222 }
	use_backend b-xmpp-s2s if { dst_port eq 5269 }
	
backend b-xmpp-c2s
	balance roundrobin
	option independent-streams
	server mycoolprosodybox 192.168.10.10:15222 send-proxy-v2
	
backend b-xmpp-s2s
	balance roundrobin
	option independent-streams
	server mycoolprosodybox 192.168.10.10:15269 send-proxy-v2
```


Limitations
===========

It is currently not possible to use this module for offering PROXY protocol support
on SSL/TLS ports, which will automatically initiate a SSL handshake. This might be
possible in the future, but it currently does not look like this could easily be
implemented due to the current handling of such connections.


Important Notes
===============

Please do not expose any ports offering PROXY protocol to the internet - while regular
clients will be unable to use them anyways, it is outright dangerous and allows anyone
to spoof the actual IP address. It is highly recommended to only allow PROXY
connections from trusted sources, e.g. your loadbalancer.


Compatibility
=============

  ----- -----
  trunk Works
  0.12  Works
  0.11  Works
  0.10  Works
  ----- -----