fix: gate NANP heuristics by numbering plan

Existing tests omitted non-NANP suffix collisions, allowing international callers to gain North American risk signals. The new regression tests cover these collisions and preserve NANP scores.

Author: SysAdminDoc

CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to CallShield will be documented in this file.
 
 ## Unreleased
 
+- North American toll-free, VoIP, neighbor-spoof, hot-campaign and repeat-call
+  checks now ignore international numbers whose last ten digits resemble a
+  North American number. Other international risk checks still run.
 - Region Rules now recognizes all 453 active geographic area codes in a pinned
   NANP registry snapshot, including new 465, 483 and 942. Unknown codes no
   longer trigger an out-of-region block. The 324 and 826 city labels are fixed.

README.md

@@ -12,7 +12,7 @@
 <p align="center">
   <a href="https://github.com/SysAdminDoc/CallShield/releases/latest"><img src="https://img.shields.io/github/v/release/SysAdminDoc/CallShield?style=flat-square&color=a6e3a1" alt="Release"></a>
   <img src="https://img.shields.io/badge/Spam%20Numbers-51%2C357-f38ba8?style=flat-square" alt="51,357 Numbers">
-  <img src="https://img.shields.io/badge/Tests-1547-94e2d5?style=flat-square" alt="1547 Tests">
+  <img src="https://img.shields.io/badge/Tests-1550-94e2d5?style=flat-square" alt="1550 Tests">
   <img src="https://img.shields.io/badge/Android-10%2B-89b4fa?style=flat-square" alt="Android 10+">
   <img src="https://img.shields.io/badge/License-MIT-cba6f7?style=flat-square" alt="MIT License">
   <img src="https://img.shields.io/badge/API%20Keys-None-fab387?style=flat-square" alt="No required API keys">
@@ -125,7 +125,7 @@ All detection layers implement a shared `IChecker` interface and run in priority
 |  4300 | **Region Rules** | Block | Opt-in offline blocking outside the US/Canadian regions and country calling codes you allow |
 |  4000 | **Quiet Hours** | Block | Block all non-contact calls during configurable hours (calls only) |
 |  3500 | **Frequency Auto-Block** | Block | Numbers that call 3+ times in 7 days get auto-blocked |
-|  3000 | **Heuristic Engine** | Block | VoIP ranges, neighbor spoofing, rapid-fire detection, 30+ rules |
+|  3000 | **Heuristic Engine** | Block | North American VoIP ranges, neighbor spoofing, toll-free and rapid-fire checks; international risk checks also run |
 |  2500 | **Campaign Burst** | Block | NPA-NXX prefix clustering detects coordinated spam waves |
 |  2250 | **Caller Name Rules** | Block | Carrier-presented names can match bounded, user-defined `*`/`?` patterns after every allow layer (requires the device to provide a name during screening) |
 |  2000 | **ML Spam Scorer** | Block | 20-feature on-device gradient-boosted tree model |
@@ -493,12 +493,12 @@ RELEASE_KEY_PASSWORD=...
 ## Testing
 
 ```bash
-./gradlew testDebugUnitTest   # 1547 tests
+./gradlew testDebugUnitTest   # 1550 tests
 ./gradlew connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=com.sysadmindoc.callshield.platform.TargetSdkBehaviorSmokeTest
 ./gradlew verifyPipelineTests # Cloudflare Worker (node) + data-pipeline and translation checks (python)
 ```
 
-The suite is **1547 total JVM unit tests**, run with Robolectric wherever a screen, a service or the database is involved.
+The suite is **1550 total JVM unit tests**, run with Robolectric wherever a screen, a service or the database is involved.
 
 Two GitHub workflows run without building the app. **Validation** runs the Worker and
 pipeline suites on every push except report-only ones (`run-pipeline-tests.ps1 -CorrectnessOnly`),
@@ -535,7 +535,7 @@ language in [issue #7](https://github.com/SysAdminDoc/CallShield/issues/7).
 | Community API | Cloudflare Workers |
 | URL Safety | Local spam-domain data; optional URLhaus (abuse.ch) |
 | Verification | Local Gradle, lint, and release-artifact checks |
-| Tests | 1547 JVM unit tests (JUnit) |
+| Tests | 1550 JVM unit tests (JUnit) |
 | Strings | 1583 string resources and 38 plural groups (translation-ready) |
 | Accessibility | 100+ content descriptions, 48dp touch targets |
 | Min SDK | 29 (Android 10) |

app/src/main/java/com/sysadmindoc/callshield/data/NumberingPlan.kt

@@ -0,0 +1,31 @@
+package com.sysadmindoc.callshield.data
+
+/** Numbering plan for the NANP-only detection rules. */
+enum class NumberingPlan {
+    NANP,
+    OTHER,
+    UNREADABLE,
+    ;
+
+    companion object {
+        fun from(number: String): NumberingPlan {
+            val compact = number.filterNot { it == ' ' || it == '-' || it == '(' || it == ')' || it == '.' }
+            val international = compact.startsWith('+')
+            val digits = if (international) compact.drop(1) else compact
+            if (digits.isEmpty() || digits.any { it !in '0'..'9' }) return UNREADABLE
+            if (international) {
+                if (digits.length !in 2..15 || digits.startsWith('0')) return UNREADABLE
+                return if (digits.startsWith('1')) {
+                    if (digits.length == 11) NANP else UNREADABLE
+                } else {
+                    OTHER
+                }
+            }
+            return if (digits.length == 10 || (digits.length == 11 && digits.startsWith('1'))) {
+                NANP
+            } else {
+                UNREADABLE
+            }
+        }
+    }
+}

app/src/main/java/com/sysadmindoc/callshield/data/SpamHeuristics.kt

@@ -85,8 +85,11 @@ class SpamHeuristics
         fun isNeighborSpoof(
             context: Context,
             incomingNumber: String,
+            numberingPlan: NumberingPlan = NumberingPlan.from(incomingNumber),
         ): Boolean {
+            if (numberingPlan != NumberingPlan.NANP) return false
             val userNumber = getUserPhoneNumber(context) ?: return false
+            if (NumberingPlan.from(userNumber) != NumberingPlan.NANP) return false
             val userDigits = filterAsciiDigitsLast(userNumber, 10)
             val inDigits = filterAsciiDigitsLast(incomingNumber, 10)
 
@@ -101,7 +104,11 @@ class SpamHeuristics
         // Toll-free numbers are heavily abused by robocallers
         private val tollFreePrefixes = setOf("800", "888", "877", "866", "855", "844", "833")
 
-        fun isTollFree(number: String): Boolean {
+        fun isTollFree(
+            number: String,
+            numberingPlan: NumberingPlan = NumberingPlan.from(number),
+        ): Boolean {
+            if (numberingPlan != NumberingPlan.NANP) return false
             val digits = filterAsciiDigitsLast(number, 10)
             if (digits.length < 10) return false
             return digits.substring(0, 3) in tollFreePrefixes
@@ -322,7 +329,11 @@ class SpamHeuristics
                 "437373",
             )
 
-        fun isHighSpamVoipRange(number: String): Boolean {
+        fun isHighSpamVoipRange(
+            number: String,
+            numberingPlan: NumberingPlan = NumberingPlan.from(number),
+        ): Boolean {
+            if (numberingPlan != NumberingPlan.NANP) return false
             val digits = filterAsciiDigitsLast(number, 10)
             if (digits.length < 10) return false
             return digits.substring(0, 6) in highSpamVoipNpanxx
@@ -341,7 +352,11 @@ class SpamHeuristics
 
         fun hasHotRanges(): Boolean = hotCampaignRanges.isNotEmpty()
 
-        fun isHotCampaignRange(number: String): Boolean {
+        fun isHotCampaignRange(
+            number: String,
+            numberingPlan: NumberingPlan = NumberingPlan.from(number),
+        ): Boolean {
+            if (numberingPlan != NumberingPlan.NANP) return false
             if (hotCampaignRanges.isEmpty()) return false
             val digits = filterAsciiDigitsLast(number, 10)
             if (digits.length < 6) return false
@@ -370,12 +385,15 @@ class SpamHeuristics
             number: String,
             windowMs: Long = 3600_000,
             threshold: Int = 3,
+            numberingPlan: NumberingPlan = NumberingPlan.from(number),
         ): Boolean {
+            if (numberingPlan != NumberingPlan.NANP) return false
             val now = System.currentTimeMillis()
             val normalized = filterAsciiDigitsLast(number, 10)
             val count =
                 recentNumbers.count { (num, time) ->
-                    filterAsciiDigitsLast(num, 10) == normalized && (now - time) < windowMs
+                    NumberingPlan.from(num) == NumberingPlan.NANP &&
+                        filterAsciiDigitsLast(num, 10) == normalized && (now - time) < windowMs
                 }
             return count >= threshold
         }
@@ -393,6 +411,7 @@ class SpamHeuristics
         fun analyze(
             context: Context,
             number: String,
+            numberingPlan: NumberingPlan = NumberingPlan.from(number),
             smsBody: String? = null,
             recentBlockedNumbers: List<Pair<String, Long>> = emptyList(),
             enableNeighborSpoof: Boolean = true,
@@ -418,31 +437,31 @@ class SpamHeuristics
             }
 
             // High-spam VoIP range
-            if (isHighSpamVoipRange(number)) {
+            if (isHighSpamVoipRange(number, numberingPlan)) {
                 score += 30
                 reasons.add("voip_spam_range")
             }
 
             // Active campaign range — 3+ distinct numbers from this NPA-NXX in last 24h
-            if (isHotCampaignRange(number)) {
+            if (isHotCampaignRange(number, numberingPlan)) {
                 score += 35
                 reasons.add("hot_campaign_range")
             }
 
             // Toll-free (mild signal — many legit businesses use these)
-            if (isTollFree(number)) {
+            if (isTollFree(number, numberingPlan)) {
                 score += 10
                 reasons.add("toll_free")
             }
 
             // Neighbor spoofing (gated by the Settings toggle)
-            if (enableNeighborSpoof && isNeighborSpoof(context, number)) {
+            if (enableNeighborSpoof && isNeighborSpoof(context, number, numberingPlan)) {
                 score += 50
                 reasons.add("neighbor_spoof")
             }
 
             // Rapid-fire calling
-            if (isRapidFire(recentBlockedNumbers, number)) {
+            if (isRapidFire(recentBlockedNumbers, number, numberingPlan = numberingPlan)) {
                 score += 40
                 reasons.add("rapid_fire")
             }
@@ -531,6 +550,13 @@ class SpamHeuristics
                 smsBody: String? = null,
                 recentBlockedNumbers: List<Pair<String, Long>> = emptyList(),
                 senderProvenance: SenderProvenance? = null,
-            ): HeuristicResult = shared.analyze(context, number, smsBody, recentBlockedNumbers, senderProvenance = senderProvenance)
+            ): HeuristicResult =
+                shared.analyze(
+                    context,
+                    number,
+                    smsBody = smsBody,
+                    recentBlockedNumbers = recentBlockedNumbers,
+                    senderProvenance = senderProvenance,
+                )
         }
     }

app/src/main/java/com/sysadmindoc/callshield/data/checker/Checkers.kt

@@ -934,6 +934,7 @@ internal class HeuristicChecker(
             spamHeuristics.analyze(
                 context = appContext,
                 number = ctx.number,
+                numberingPlan = ctx.numberingPlan,
                 smsBody = sms,
                 recentBlockedNumbers = recentBlocked.map { it.number to it.timestamp },
                 enableNeighborSpoof = ctx.prefs[SpamRepository.KEY_NEIGHBOR_SPOOF] ?: true,

app/src/main/java/com/sysadmindoc/callshield/data/checker/IChecker.kt

@@ -3,6 +3,7 @@ package com.sysadmindoc.callshield.data.checker
 import android.content.Context
 import android.util.Log
 import androidx.datastore.preferences.core.Preferences
+import com.sysadmindoc.callshield.data.NumberingPlan
 import com.sysadmindoc.callshield.data.SenderProvenance
 import com.sysadmindoc.callshield.data.SpamRepository
 import com.sysadmindoc.callshield.data.repository.SpamRepositoryImpl
@@ -140,6 +141,9 @@ data class CheckContext(
      */
     val alternateForms: List<String> = emptyList(),
 ) {
+    /** Shared plan classification for NANP-only checkers in this evaluation. */
+    val numberingPlan: NumberingPlan = NumberingPlan.from(number)
+
     /**
      * Forms to try when matching stored numbers exactly, canonical first.
      * Allow and block lookups both use it, so a number saved in any form

app/src/test/java/com/sysadmindoc/callshield/data/NanpHeuristicGateTest.kt

@@ -0,0 +1,93 @@
+package com.sysadmindoc.callshield.data
+
+import android.content.Context
+import android.telephony.TelephonyManager
+import androidx.datastore.preferences.core.emptyPreferences
+import androidx.test.core.app.ApplicationProvider
+import com.sysadmindoc.callshield.data.checker.CheckContext
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows
+
+@RunWith(RobolectricTestRunner::class)
+class NanpHeuristicGateTest {
+    private val context: Context = ApplicationProvider.getApplicationContext()
+    private val heuristics = SpamHeuristics()
+
+    @After
+    fun resetHotRanges() = heuristics.updateHotRanges(emptyList())
+
+    @Test
+    fun `context classifies international national and unreadable numbers once`() {
+        for (number in listOf("+493012340101", "+658005551234", "+642025551234")) {
+            assertEquals(NumberingPlan.OTHER, checkContext(number).numberingPlan)
+        }
+        assertEquals(NumberingPlan.NANP, checkContext("+13012340101").numberingPlan)
+        assertEquals(NumberingPlan.NANP, checkContext("(301) 234-0101").numberingPlan)
+        assertEquals(NumberingPlan.UNREADABLE, checkContext("++13012340101").numberingPlan)
+        assertEquals(NumberingPlan.UNREADABLE, checkContext("+1301234").numberingPlan)
+    }
+
+    @Test
+    fun `all five NANP rules ignore international suffix collisions`() {
+        setOwnNumber("3012349999")
+        heuristics.updateHotRanges(listOf("301234"))
+        val now = System.currentTimeMillis()
+        val berlin = "+493012340101"
+        val singapore = "+658005551234"
+        val newZealand = "+642025551234"
+        val history = List(3) { berlin to now - 1000L }
+
+        assertFalse(heuristics.isNeighborSpoof(context, berlin))
+        assertFalse(heuristics.isHotCampaignRange(berlin))
+        assertFalse(heuristics.isTollFree(singapore))
+        assertFalse(heuristics.isHighSpamVoipRange(newZealand))
+        assertFalse(heuristics.isRapidFire(history, berlin))
+        assertFalse(heuristics.isRapidFire(history, "+13012340101"))
+
+        for (number in listOf(berlin, singapore, newZealand)) {
+            val result =
+                heuristics.analyze(
+                    context,
+                    number,
+                    numberingPlan = checkContext(number).numberingPlan,
+                    recentBlockedNumbers = history,
+                )
+            assertEquals(number, 0, result.score)
+            assertTrue(number, result.reasons.isEmpty())
+        }
+    }
+
+    @Test
+    fun `NANP fixture retains neighbor hot range and rapid fire signals`() {
+        setOwnNumber("3012349999")
+        heuristics.updateHotRanges(listOf("301234"))
+        val number = "+13012340101"
+        val now = System.currentTimeMillis()
+        val history = List(3) { number to now - 1000L }
+        val result =
+            heuristics.analyze(
+                context,
+                number,
+                numberingPlan = checkContext(number).numberingPlan,
+                recentBlockedNumbers = history,
+            )
+
+        assertEquals(100, result.score)
+        assertEquals(listOf("hot_campaign_range", "neighbor_spoof", "rapid_fire"), result.reasons)
+        assertTrue(heuristics.isTollFree("+18005551234"))
+        assertTrue(heuristics.isHighSpamVoipRange("+12025551234"))
+    }
+
+    private fun checkContext(number: String) = CheckContext(appContext = context, number = number, realtimeCall = true, prefs = emptyPreferences())
+
+    private fun setOwnNumber(number: String) {
+        val telephony = context.getSystemService(Context.TELEPHONY_SERVICE) as TelephonyManager
+        Shadows.shadowOf(telephony).setLine1Number(number)
+    }
+}

app/src/test/java/com/sysadmindoc/callshield/data/PhoneNumberFuzzTest.kt

@@ -56,11 +56,13 @@ class PhoneNumberFuzzTest {
         }
 
         // SpamHeuristics — public methods that take a phone number
+        NumberingPlan.from(input)
         SpamHeuristics.isTollFree(input)
         SpamHeuristics.isInternationalPremium(input)
         SpamHeuristics.isHighSpamVoipRange(input)
         SpamHeuristics.isInvalidFormat(input)
         SpamHeuristics.isHotCampaignRange(input)
+        SpamHeuristics.isRapidFire(listOf(input to System.currentTimeMillis()), input)
 
         // SpamHeuristics.isWangiriCountryCode (public)
         SpamHeuristics.isWangiriCountryCode(input)