ubuntu-post-install/docs/pstn-calling-voipms-plan.md

PSTN Calling via VoIP.ms — Planning Notes

Research and decisions from a design discussion, saved here so the work can be picked up in a fresh chat without re-deriving the background. Nothing has been implemented yet — this is prep for a future services/*.sh addition on top of asterisk-digital-ocean.

Decision so far

• Provider: VoIP.ms. Chosen for its prepaid-balance model: turn off auto-recharge in the account's Finances settings and outbound calls simply fail once the balance hits $0 — that's the toll-fraud backstop if the droplet's Asterisk (asterisk-digital-ocean) is ever compromised. This behavior wasn't verified against a live account — confirm the auto-recharge toggle still works this way at sign-up time, since billing UX can change.
• Scope: US calling only, for now. No international, no premium-rate destinations. Enforce this twice — once via whatever dial-plan/prefix VoIP.ms requires for US routing, and again independently in Asterisk's own dialplan (see below), so a compromised extension can't reach anything outside the US even if the trunk itself would technically allow more later.

Why this matters (toll fraud)

A compromised Asterisk box can dial premium-rate or international numbers that cost real money fast (some destinations run several $/min) before anyone notices. Two independent layers matter more than either alone:

1. Trunk-side cap — prepaid balance, auto-recharge off. Limits total possible loss to whatever the balance is topped up to, but a live compromise could still burn through that balance in minutes if nothing else restricts what can be dialed.
2. Dialplan-side restriction — Asterisk should refuse to route calls outside the US/NANP pattern at all, regardless of what the trunk allows. This is the first line of defense and should exist independent of the trunk's own capabilities.

What it takes technically (asterisk-digital-ocean)

• A PJSIP trunk to VoIP.ms: endpoint / aor / auth / identify sections in the pjsip config, using either IP authentication or SIP registration — VoIP.ms supports both. IP auth is simpler for a droplet (it has a static IP already) and avoids storing a SIP password in the config at all — worth confirming with VoIP.ms which they actually recommend before choosing.
• An outbound dialplan route matching US numbers only, e.g. _1NXXNXXXXX (11-digit NANP with leading 1) or _NXXNXXXXX, depending on how numbers get dialed from the existing extensions, routed to the VoIP.ms trunk. No catch-all _X. pattern — an explicit NANP pattern is itself a hard block on non-US destinations at the dialplan level.
• VoIP.ms-specific setup that isn't scriptable (user does this manually): create the account, decide whether a DID is needed (this research was outbound-only — inbound PSTN wasn't discussed/decided), pick a VoIP.ms POP/server (affects the trunk hostname), fund the prepaid balance, turn off auto-recharge.
• Defense-in-depth to design alongside the trunk (not yet designed):
  • Per-extension concurrent-call cap in the dialplan (GROUP() / GROUP_COUNT()) so one compromised extension can't open dozens of simultaneous outbound legs at once.
  • A simple outbound call-count/spend alert — could live in the existing security-dashboard service (see services/security-dashboard.sh) or as a separate CDR-based check. Not designed yet.
  • Worth being explicit that CrowdSec's existing asterisk_bf / asterisk_user_enum scenarios (see services/crowdsec.sh) cover registration brute-force, which is a different threat model from a legitimately-registered extension being used for toll fraud — nobody should assume CrowdSec alone already covers this.

Provider landscape (for reference — not chosen)

• SIP.US — also prepaid, flat per-channel rate, built-in fraud detection. Considered, not chosen.
• Several providers (Nextiva, IDT Express) advertise AI/ML-based fraud monitoring as a second layer on top of normal billing — an extra net, not a substitute for a hard prepaid ceiling.
• Most providers don't market an explicit "spending cap" feature — the prepaid-balance + auto-recharge-off pattern is the de facto mechanism across the space, VoIP.ms included.

Open items for whoever picks this up next

1. Decide: new services/voipms-trunk.sh, or an optional trunk section added directly to services/asterisk-digital-ocean.sh? Leaning toward a separate service file so trunk config isn't forced on installs that don't want PSTN calling, matching this repo's one-feature-per-file convention (see CLAUDE.md).
2. IP auth vs. registration — confirm which VoIP.ms recommends for a single fixed-IP droplet.
3. Exact NANP dial pattern(s) and any prefix-stripping VoIP.ms requires.
4. Whether inbound (a DID) is wanted at all, or outbound-only for now — not discussed yet.
5. Design the concurrent-call cap and any spend/volume alerting mentioned above.