Skip to content
/ atxt Public

atxt: a Twilio-based pseudonymous SMS forwarding service

License

Notifications You must be signed in to change notification settings

veliander/atxt

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

atxt (Anonymized TeXT)– a pseudonymous, non-blocking SMS forwarding service concept written in Scala

atxt uses Twilio's SMS functionality to forward text messages without revealing phone numbers, or any other personally identifiable information. The service is very lightweight, with no registration or account creation necessary. Interaction with the system is simple and consists of 3 phases:

  • First contact: whenever atxt receives an SMS (any text) from a new number, it assigns a unique alias to that number and adds it to its subscriber list.

    first contact

  • [De]Authorization: whenever atxt receives from an existing subscriber an SMS consisting of a single word, it considers that word to be a subscriber alias and attempts to toggle the authorization of that alias to send messages to the sender (by default, one's own alias can send messages to itself, but no other alias is authorized to do so).

    authorization

  • Forwarding: whenever atxt receives from an existing subscriber an SMS consisting of two or more words, it considers the first word to be the recipient's alias, and all subsequent words to comprise a message. If sender's alias is authorized to send messages to the recipient's alias, the message is thus forwarded to the phone number associated with the recipient's alias, with indication that it originates from sender's alias. forward sent forward received

How to get running

After taking care of the prerequisites, you should get the service running locally and passing all tests. After that, deploy to your platform of choice, point your Twilio number's Messaging Webhook to your service URL and select POST as the method.

Prerequisites

Installing

Install sbt (although if you don't have it already, perhaps this is not the right project for you)

Set the following environment variables:

TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN
TWILIO_PHONE_NUMBER
REDIS_URL
PLAY_HTTP_SECRET_KEY

For proper values, see the Twilio, Redis, and Play documentation.

Running the tests

Make sure the environment variables are set correctly:

  • REDIS_URL contains proper credentials and points to a service that is running and accessible
  • Twilio variables are configured with test credentials

When ready, type

sbt test

Make sure all tests pass before proceeding further.

Deployment

You can deploy atxt on any platform, from your laptop (provided you allow Twilio to send POST requests to it), to one or more Heroku dynos, to a dedicated cluster on AWS. Just keep in mind that the goal here is to provide a simple example of non-blocking code, not a secure communications platform. 😀

Don't forget to set the real credentials of your Twilio account in the ENV variables.

My reference deployment platform is Heroku (a free dyno using a free Heroku Redis instance). It works well, but if the dyno falls asleep, the message that awakes it may result in an error as Twilio times out in 15 seconds, while a sleeping Heroku dyno takes 30 seconds to wake up.

Built With

  • Scala 2.12 (works a lot better than previous versions for flattening Futures).
  • Play 2.6 - The reactive web framework from Lightbend.
  • Rediscala - A Redis client for Scala (2.10+) and AKKA (2.2+) with non-blocking and asynchronous I/O operations. Writen by @etaty.
  • Twilio Java SDK - Although Java-only, still the best way to call Twilio API functions from Scala.
  • nomen-est-omen - A random, composite name generation library by @igr.

Authors

  • @veliander

License

This project is licensed under the MIT License - see the LICENSE.md file for details