Remotely register twilio numbers as signal numbers

Value Statement

AS a provider of the signal-boost service

• I WANT to be able to remotely authorize any server to send messages as any twillio-generated phone number
• SO THAT i can spin up new signal-blaster channels quickly
• AND test my app with a CI pipeline that uses ephemeral twilio numbers to test the app by sending and receiving messages

Acceptance Criteria

GIVEN I control a twilio phone number (555-555-5555) and a twilio API Key

• WHEN I send a POST request to /numbers/registration/new with body { number: '15555555555' }
• THEN a background job should authorize sigal-cli to use the phone number
• AND return a success message when the job completes (either as a response to my request or as a response to a GET to numbers/registration/status?id=<some_id>

GIVEN the same conditions as above

• WHEN I send a POST request for a number I don't control (eg: { number: +14444444444` }
• THEN a background job should attempt to authorize signal-cli to use the phone number
• AND return an error message when it fails

GIVEN the same conditions as above

• AND I have already registered 555-555-5555
• WHEN I send a POST request to register the number
• THEN the server should inform me immediately that the number is already registered

Implementation Notes

Something like this...

components of phoneNumberService:

• (1) #purchase (from twilio)
  • search all phone numbers w/ sms enabled, select first one returned
  • create twilio number with this number (give it a name and register webhook endpoint)
  • save number w/ status "PURCHASED"
  • return status/number tuple
• (2) #register (with signal)
  • call signal-cli -u PHONE_NUMBER register -> set number status "VERIFICATION_REQUESTED"
  • poll for change in status of phone number to "VERIFIED" -> return success/number tuple
  • if no status change after 30 seconds, set status to "VERIFICATION_FAILED", return failure/number tuple
• (3) #verify (signal code)
  • listen for POST to /twilio_sms endpoint (dev flow will require ngrok for this)
  • parse verification code (easy) and and phone number (hard) from body, pass to #verify
  • pass VERIFICATION_CODE and PHONE_NUMBER to signal-cli -u PHONE_NUMBER verify VERIFICATION_CODE
  • set pNum status to "VERIFIED" on success (to "VERIFICATION_FAILED" if failure)
  • (this side effect will be read by polling job in (2))
• (_) #purchaseAndRegister (composes (1) and (2) for external interface)

usage/interface

• (1) bash script
  • to be run on production box (possibly as part of deploy)
  • ./bin/phone_numbers/purchase_many calls ./bin/purchase_number N times (w/ N as first argument to script)
  • ./bin/phone_numbers/purchase calls phoneNumberService#purchase, logs results
  • ./bin/phone_numbers/register calls phoneNumberService#register, logs results
  • ./bin/phone_numbers/purchase_and_register calls purchase_number, register_number, logs results
  • purchase may be called only once, register may be called multiple times (on deploy), and should be idempotent
• (2) api endpoints (require auth token)
  • POST /phone_numbers/new -> calls #purchase and #register, returns status/number tuple (may exit early from #purchase)
  • GET /phone_numbers/get -> returns list of phone numbers and their statuses