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.

Implemented — see services/pstn-trunk.sh (run sudo ./setup.sh pstn-trunk after asterisk-digital-ocean or asterisk (home/LAN) is installed — both are supported, see the file for the static-IP caveat on the LAN variant). Generic SIP trunk add-on that defaults to VoIP.ms but isn't hardcoded to it — any provider supporting IP authentication works. Covers:

• IP-authenticated trunk, US/NANP-only outbound dialplan, no catch-all.
• Two independent concurrent-call caps, one per direction (default 10 outbound / 10 inbound — bumped up from an initial default of 3 once roles existed to gate who can even reach the trunk; "ability creep is real," so the two caps stay the hard backstop regardless). Global per direction, not per-extension.
• Three-tier per-extension permission model: internal (default — no PSTN at all, but can always call/receive other extensions and internal ring groups), restricted (also only pre-approved US numbers, both directions), full (also any US number). Internal extension-to-extension dialing is never gated by any tier — deliberately, even though VoIP.ms itself offers free SIP-to-SIP calling, to avoid routing purely-internal calls through an extra external hop for no benefit.
• Permissions AND concurrency caps are both live, not baked into the dialplan. Stored in pstn-permissions.conf / pstn-limits.conf, read by the dialplan via Asterisk's AST_CONFIG() on every call — editing either file takes effect on the next call, no restart, no reinstall. services/pstn-trunk.sh's "update in place" mode deliberately never touches either (same protection this repo's update-mode convention already gives .env/firewall/Caddy config elsewhere) — only a "fresh" reinstall (with confirmation) or the web UI below change it.
• A configurable inbound ring-group (one extension or several), each member's live tier/approved-numbers checked per inbound call via an unrolled per-member dialplan block (no AGI needed).
• services/security-dashboard.sh integration — a "PSTN Trunk" tab shows both concurrency caps and every extension (parsed from pjsip.conf) with its live tier and approved numbers, all editable with no restart. This is what makes the tier model and caps actually manageable day-to-day instead of needing a reinstall for every change.
• ntfy alerts on denied/rejected calls (immediate — permission denied, number not approved, or either concurrency cap hit) and spend/volume thresholds (hourly check: once/month on a spend threshold, every hour on a call-burst threshold).
• Structural settings (server, DID, ring-group membership, ntfy, rate/thresholds) persist to .pstn-trunk.env so "update in place" reapplies them without re-prompting — the concurrency cap numbers themselves are not structural, they live in pstn-limits.conf instead (see above).

services/pstn-trunk.sh's own header comment explains how the trunk/dialplan config survives Easy Asterisk's regeneration, and why permissions are a separate live file rather than baked in — both architectural wrinkles discovered while implementing this, worth reading before touching either file.

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.

  Update — read VoIP.ms's actual ToS (not just the wiki) on this. The wiki says plainly "only accounts with a balance over $0 are able to send and receive calls" — new call attempts should be blocked in real time at $0, and that's still the core assumption this design leans on. But the ToS separately says the account "may run on a negative balance," that any negative balance is "immediately due and payable," that VoIP.ms may suspend an account below a $5 minimum balance (30-day notice first), and may permanently close it after 30 consecutive days negative. Read together, not a contradiction — two different things:

  • Can new calls start — real-time balance check, blocked at $0. Core assumption holds.
  • Can the balance ever read negative — yes, most plausibly from recurring fees (DID monthly, E911) landing when the balance is already near zero, or edge-case settlement of an in-progress call ticking slightly negative before teardown. Neither is a runaway toll-fraud scenario; both mean liability isn't cleanly capped at the funded amount to the exact penny, and the account needs topping up within the 30-day windows or it gets suspended/closed (an account-status consequence, not "30 free days of unblocked calling while negative").
  • Still not verified against an actual live account — this is a read of their published wiki + ToS text, not a test. Watch the real balance for the first month or two after go-live, and don't panic at a small negative reading — check whether it's a recurring fee or an actual call spike before assuming the block failed.

• 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.

• Inbound: wanted. A DID is in scope, not outbound-only. Decide pay-per-minute vs. unlimited DID plan based on expected inbound volume (see cost estimate below), and decide E911 deliberately rather than skipping it by default — VoIP.ms doesn't require it, but without it 911 dialed from the line either fails or doesn't carry accurate address/location info.

Cost estimate (100 min/month each direction, US-only)

Verified against VoIP.ms's public wiki/rate pages, not a live account — confirm at sign-up since rates can change.

Item	Rate	Monthly	Annual
DID (phone number), pay-per-minute plan	$0.85/mo flat	—	$10.20
Inbound usage	$0.009/min	$0.90	$10.80
Outbound usage	$0.01/min	$1.00	$12.00
Total		~$2.75	~$33

• Skipping the DID (outbound-only) drops this to ~$12/year.
• Adding E911 adds a $1.50 one-time fee plus $1.50/month regulatory fee (~$18/year) — pushes the total above to ~$51/year.
• Funding minimum: VoIP.ms requires a $15 minimum deposit to activate calling — a one-time balance top-up, not a recurring charge. At ~$2.75/month usage that balance lasts ~5 months before a refill is needed (longer at lower volume). Leave auto-recharge off per the toll-fraud design above.

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.

Important nuance: these two layers bound different things, and neither alone bounds both. NANP-only restriction bounds cost-per-minute (a compromised box can only ever reach $0.01/min US numbers, never $2–5/min international/premium destinations) — that risk is fully closed. It does not bound how fast the prepaid balance gets burned: nothing stops a compromised box from opening many concurrent US-destination calls in parallel and draining the whole balance (e.g. $15 balance ÷ $0.01/min = 1,500 minutes total, which 20 concurrent legs could burn through in under an hour). The prepaid-balance-off-auto-recharge layer bounds the dollar ceiling; only a concurrent-call cap bounds the speed of a breach. Treat the concurrent-call cap and spend/volume alert below as required before funding a live trunk, not optional hardening.

Implemented: the concurrent-call caps in services/pstn-trunk.sh are global per direction (default 10 outbound / 10 inbound, each tracked via its own GROUP()/GROUP_COUNT() in the dialplan, shared across all extensions) — not per-extension. Inbound didn't have a cap at all until this was pointed out as a gap (outbound's cap doesn't protect against an inbound call-flood, which also costs money per-minute on VoIP.ms) — both directions are covered symmetrically now. The spend/volume alert is also implemented: an hourly cron script reads a call log the dialplan appends to directly (not Asterisk's CDR — see the service file's own comments for why) and alerts via ntfy once per month when estimated spend crosses a threshold, and every hour that call volume in the last hour looks like a burst. Denied/rejected calls alert immediately, separately from that hourly check.

What it takes technically (asterisk-digital-ocean)

• A PJSIP trunk: endpoint / aor / identify sections in the pjsip config. Implemented with IP authentication (no auth section, no SIP password stored anywhere) — see services/pstn-trunk.sh. Provider name, server hostname, and DID are all prompted at install time (VoIP.ms is only the suggested default), so any provider supporting IP auth works.
• An outbound dialplan route matching US numbers only — implemented: _1NXXNXXXXX (11-digit NANP with leading 1) and _NXXNXXXXX (10-digit, auto-prefixed with 1), both routed to the trunk. No catch-all _X. pattern.
• Three-tier permission model — implemented, superseding an earlier flat allow-list design. internal / restricted / full per extension, read live from pstn-permissions.conf via AST_CONFIG() rather than baked into the dialplan text — no changes needed to Easy Asterisk's own per-device pjsip.conf sections, since the gate lives entirely in files this repo already owns. Internal extension-to-extension dialing is never gated by any tier — only the two NANP patterns (outbound) and the ring-group (inbound) are. Numbers are stored pipe-separated specifically because they're used as a REGEX() alternation pattern in the dialplan — see the security note below on why the untrusted call-time value must never be interpolated into the pattern side of that check.
• Inbound ring-group — implemented. A space-separated list of extensions to ring for inbound calls (one, or several for a ring group via Dial(PJSIP/a&PJSIP/b,20)), prompted at install. Each member's tier is checked live per inbound call (an unrolled dialplan block per member — full always rings, restricted only rings if the caller's number is on that member's approved list, internal never rings).
• Security note on the REGEX() checks: an inbound Caller-ID (or an outbound dialed number) is attacker-influenced data and must never be interpolated into the pattern argument of REGEX() — only ever the string being tested. Doing it backwards would let a crafted Caller-ID (e.g. containing regex metacharacters) forge a match against an unrelated approved-numbers entry. Both checks in services/pstn-trunk.sh put the admin-controlled approved-list in the pattern position and the live call data in the tested-string position — worth keeping that direction if this is ever refactored.
• Web UI — implemented. services/security-dashboard.sh's "PSTN Trunk" tab lists every extension (parsed from pjsip.conf, the same marker format Easy Asterisk's own rebuild_dialplan() uses) with a tier dropdown and approved-numbers field, saving straight to pstn-permissions.conf. Tested end-to-end with a real running instance of the (stdlib-only) Python app: extension parsing, tier changes, number normalization/ validation, and persistence all verified with actual HTTP requests against a live server in a sandboxed test — not just read through.
• Provider-specific setup that isn't scriptable (user does this manually): create the account, order a DID, decide pay-per-minute vs. unlimited DID plan and whether to add E911, pick a server/POP, fund the prepaid balance ($15 minimum for VoIP.ms), turn off auto-recharge. services/pstn-trunk.sh prompts for the server hostname, DID, allowed extensions, ring extensions, both concurrency caps, ntfy topic, and spend-alert settings at install time (the cap numbers are then live/web-editable afterward — see above).
• Defense-in-depth alongside the trunk:
  • Implemented: independent outbound/inbound concurrent-call caps in the dialplan (GROUP()/GROUP_COUNT(), default 10/10) so an unauthorized or compromised extension can't open dozens of simultaneous legs in either direction. Global per direction, not per-extension — see the note above.
  • Implemented: an outbound call-count/spend alert via ntfy — a self-contained call log (not Asterisk's CDR) plus an hourly cron script. Denied/rejected calls also alert immediately. See services/pstn-trunk.sh's "Spend/volume alerts" README section for the exact mechanics and why CDR wasn't used.
  • 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)

Looked at as alternatives to VoIP.ms specifically because VoIP.ms's own ToS confirms it selectively requires a government ID scan at signup (VPN/proxy use, certain number types, internal risk scoring — not universal, but real). None of these were verified to never require ID either; KYC requirements are trending industry-wide (FCC STIR/SHAKEN, Robocall Mitigation Database), so treat "no ID requirement found" as exactly that, not confirmation.

• DIDLogic — ruled out: has a $20/month minimum, confirmed directly by checking their portal (not something search results surfaced). Would otherwise have needed zero code changes — same IP-auth model and single-IP-per-regional-POP hostname pattern this service already handles.
• Anveo Direct (anveodirect.com — a different product from plain Anveo/anveo.com, its hosted-PBX sibling with monthly subscription tiers; don't confuse the two, their pricing models aren't comparable) — leading candidate. ~$0.001/min outbound, no minimum commitment, $25 minimum to fund the account (close to VoIP.ms's $15). Confirmed via their current official FAQ (fetched directly, not via search — search results had gone stale on this exact point):
  • IP authentication, no SIP registration — matches this service's architecture with zero changes needed to the auth model.
  • No dial-prefix requirement — a stale/outdated forum claim (found via search) suggested one was needed; the current official FAQ's own sample config shows plain number dialing, nothing prepended. Don't trust that claim if it resurfaces.
  • Sends inbound signaling from multiple fixed IPs, not one: 169.48.232.158, 204.216.109.55, 176.9.39.206, 72.9.149.25 (per their FAQ as of this writing — confirmed different from what web search surfaced independently, which was a different, apparently stale set of 5 IPs). This is what prompted the multi-IP identify support below.
  • STIR/SHAKEN signing is handled by Anveo as intermediate provider for personal use (originating your own calls, not reselling to customers) — no FCC registration/certificate needed on our side.
  • Still open: does Anveo actually block new outbound calls in real time at $0 balance (matching VoIP.ms's documented behavior), or only enforce via the recurring-fee grace-period mechanism their FAQ describes? Not confirmed either way — ask their support before funding a real account, since it's the crux of the toll-fraud backstop assumption.
• SIP.US — prepaid, but a flat ~$24.95/mo per-channel (unlimited minutes on that channel) model, not pay-per-minute — not actually similarly-priced at this project's volume (100 min/month costs ~$1-3/mo pay-per-minute vs. $24.95/mo flat). Notable anyway for automated real-time fraud detection (kills in-progress unauthorized calls, auto-disables international calling on suspicious activity) — a provider-side version of what this repo hand-built in the dialplan, if that trade-off (higher price, less to maintain yourself) ever appeals.
• 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.

Multi-provider support beyond VoIP.ms — implemented

services/pstn-trunk.sh now generalizes two things that were originally built VoIP.ms-shaped, driven directly by researching Anveo Direct as an alternative:

• Multiple inbound identify match IPs, not just one. The install prompt still auto-resolves the server hostname to an IP (VoIP.ms's one-POP-one-hostname model), but now also asks for any additional known source IPs a provider might publish (Anveo Direct's case) — PJSIP allows repeating match= within a single identify object to build one match set against the trunk endpoint, so this needed no new config objects, just a loop emitting one match= line per IP.
• No dial-prefix support was added — turned out not to be needed for Anveo Direct once verified against their current official FAQ rather than a stale search result. If a future provider genuinely needs one, that's the next generalization point (a prefix prepended to ${EXTEN} before Dial()).

Bug caught while testing this: .pstn-trunk.env (the structural settings file "update in place" reapplies) was being written with unquoted values. Harmless as long as every value happened to be a single word, but a multi-IP list (always space-separated once there's more than one) or a multi-word provider name (e.g. "Anveo Direct") broke source-ing it entirely — bash treats the second word as a command to run ("Direct: command not found"). This was a latent bug that predates the multi-IP work (a multi-extension ring group has the same shape), only surfaced by actually exercising the update-mode round trip instead of just inspecting generator output. Fixed by quoting every value in that heredoc.

Open items for whoever picks this up next

1. Decide: new services/pstn-trunk.sh... Done — separate service file, generalized to any IP-auth SIP provider (VoIP.ms is just the default).
2. IP auth vs. registration Done — IP authentication, no password stored.
3. Exact NANP dial pattern(s) Done — _1NXXNXXXXX / _NXXNXXXXX.
4. Inbound Done — rings a configurable list of extensions (ring-group supported), each checked live per-call against its own tier. Permission model Done — superseded the original flat allow-list with a 3-tier model (internal/restricted/full) managed live via pstn-permissions.conf + the Security Dashboard web UI, no reinstall needed to change. Generic Asterisk target Done — services/pstn-trunk.sh now supports either asterisk-digital-ocean or the home/LAN asterisk install (the latter with a static-IP caveat for the provider's IP authentication). Still unresolved: pick pay-per-minute vs. unlimited DID plan on VoIP.ms's side based on real expected volume, and decide on E911 (see cost estimate).
5. Concurrent-call cap Done — both directions now (inbound was a real gap, since it also costs money per-minute and outbound's cap doesn't cover it), default 10/10, global not per-extension, live-editable via pstn-limits.conf/web UI. Spend/volume alert Done — ntfy, hourly threshold + burst check, plus immediate alerts on denied/rejected calls.
6. Verify against a live VoIP.ms account (still not done — only their wiki
   • ToS text has been read, see "Decision so far" above for what that turned up): confirm new outbound calls actually get blocked at $0 balance as documented; watch whether/when the balance goes slightly negative in normal operation (expected from recurring fees, not necessarily a sign of a problem) and top up within the 30-day windows the ToS describes so the account/DID doesn't get suspended or closed. Also confirm the chosen POP server's actual source IP for inbound calls matches what services/pstn-trunk.sh resolved via DNS at install time (VoIP.ms's docs mention some redundancy/failover between servers — if inbound calls ever stop matching the identify section, this is the first thing to check).