recycled numbers send OTPs to whoever owns them now

"""Reconcile Twilio's daily deactivation feed against your contact list.

Read only. GET requests and nothing else: give this an API Key with read access
rather than the account auth token. The repair is printed, never performed,
because this script holds a credential to an account that can send messages and
spend money.
"""
import argparse
import datetime as dt
import json
import logging
import os
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("twilio_deactivations_audit")

MESSAGING = "https://messaging.twilio.com/v1"


def normalize(raw, default_cc="1"):
    """Reduce any phone number to one comparable E.164 string, or None.

    The feed is E.164. Contact tables are not: they hold (415) 555-0100,
    415-555-0100, +1 415 555 0100 and one with a trailing space. Comparing the
    raw strings matches nothing, the report says zero findings, and everybody
    concludes the problem does not apply to them. Pure, and tested, because this
    function silently decides whether the audit works at all.
    """
    text = str(raw or "").strip()
    if not text:
        return None
    plus = text.startswith("+")
    digits = "".join(c for c in text if c.isdigit())
    if not digits:
        return None
    if not plus and len(digits) == 10:
        digits = str(default_cc) + digits
    elif not plus and len(digits) == 11 and digits.startswith(str(default_cc)):
        pass
    elif not plus and len(digits) < 10:
        return None
    return "+" + digits


def load_contacts(rows, default_cc="1"):
    """Normalise a contact list into number -> record. Pure.

    Accepts plain strings or dicts carrying number, suppressed and last_sent_at.
    """
    out = {}
    for row in rows:
        record = {"number": row} if isinstance(row, str) else dict(row)
        key = normalize(record.get("number"), default_cc)
        if key:
            record["number"] = key
            out[key] = record
    return out


def reconcile(deactivations, contacts):
    """Intersect the feed with the contact list. Pure.

    deactivations: number -> deactivation date (YYYY-MM-DD).
    contacts: number -> record, both already normalised.
    """
    matches = []
    for number, on in deactivations.items():
        record = contacts.get(number)
        if record is None:
            continue
        matches.append({
            "number": number,
            "deactivated_on": on,
            "last_sent_at": record.get("last_sent_at"),
            "suppressed": bool(record.get("suppressed")),
            "label": record.get("label") or record.get("name") or "",
        })
    return sorted(matches, key=lambda m: m["number"])


def verdict(match):
    """Classify one match. Pure. Returns (state, detail).

    Dates are compared as ISO strings on the first ten characters, so a full
    timestamp and a bare date compare correctly against each other.
    """
    on = str(match.get("deactivated_on") or "")[:10]
    sent = str(match.get("last_sent_at") or "")[:10]

    if match.get("suppressed"):
        return ("suppressed",
                "already suppressed. Keep the record: it is the evidence that "
                "consent for this number ended on %s." % on)

    if sent and on and sent >= on:
        return ("misdelivered",
                "deactivated %s and you sent to it on %s. Those messages "
                "reached whoever owns the number now. If any of them carried a "
                "verification code, treat it as an access-control incident."
                % (on, sent))

    return ("at-risk",
            "deactivated %s and still active in your list. The next send goes "
            "to a stranger and the consent record you hold is the previous "
            "owner's." % on)


def get(session, url, **params):
    r = session.get(url, params=params, timeout=30, allow_redirects=False)
    if r.status_code in (401, 403):
        raise SystemExit("%d from Twilio: check TWILIO_ACCOUNT_SID and that the "
                         "API key belongs to that account with read access"
                         % r.status_code)
    return r


def feed_for(session, day):
    """Numbers deactivated on one day, or an empty list.

    The API answers with a short-lived signed URL, either as redirect_to in a
    JSON body or as a Location header on a redirect. The signature is the
    authorisation on that URL, so it is fetched with a bare request: an HTTP
    client that attaches basic auth to the redirect too is why this works on one
    machine and not another.
    """
    r = get(session, "%s/Deactivations" % MESSAGING, Date=day)
    if r.status_code == 404:
        log.info("no deactivation feed published for %s", day)
        return []
    target = r.headers.get("Location")
    if not target:
        try:
            target = (r.json() or {}).get("redirect_to")
        except ValueError:
            target = None
    if not target:
        log.warning("no redirect_to for %s (status %d)", day, r.status_code)
        return []

    body = requests.get(target, timeout=60)
    body.raise_for_status()
    return [line.strip() for line in body.text.splitlines() if line.strip()]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--days", type=int, default=7,
                    help="how many days of the feed to pull, ending yesterday")
    ap.add_argument("--contacts", required=True,
                    help="JSON file: a list of numbers, or of objects with "
                         "number, suppressed and last_sent_at")
    ap.add_argument("--country-code", default="1",
                    help="country code to assume for bare national numbers")
    args = ap.parse_args()

    account = os.environ.get("TWILIO_ACCOUNT_SID")
    key = os.environ.get("TWILIO_API_KEY")
    secret = os.environ.get("TWILIO_API_SECRET")
    if not (account and key and secret):
        log.error("set TWILIO_ACCOUNT_SID, TWILIO_API_KEY and TWILIO_API_SECRET "
                  "(an API Key with read access, not the auth token)")
        return 2

    with open(args.contacts, encoding="utf-8") as fh:
        contacts = load_contacts(json.load(fh), args.country_code)
    log.info("%d contact(s) after normalisation", len(contacts))

    session = requests.Session()
    session.auth = (key, secret)

    deactivations = {}
    for offset in range(1, args.days + 1):
        day = (dt.date.today() - dt.timedelta(days=offset)).isoformat()
        for raw in feed_for(session, day):
            number = normalize(raw, args.country_code)
            if number and number not in deactivations:
                deactivations[number] = day

    matches = reconcile(deactivations, contacts)
    incidents = 0
    for match in matches:
        state, detail = verdict(match)
        line = "%-13s %s  %s" % (state, match["number"], detail)
        if state == "suppressed":
            log.info(line)
            continue
        if state == "misdelivered":
            incidents += 1
        log.warning(line)
        log.warning("  repair: suppress %s in your contact table now, and "
                    "re-verify ownership before you send to it again. Do not "
                    "carry the old consent record onto a recycled number.",
                    match["number"])

    log.info("%d deactivation(s) over %d day(s), %d match(es), %d already "
             "messaged", len(deactivations), args.days, len(matches), incidents)
    return 1 if matches else 0


if __name__ == "__main__":
    sys.exit(main())

/**
 * Reconcile Twilio's daily deactivation feed against your contact list.
 *
 * Read only. GET requests and nothing else: give this an API Key with read
 * access rather than the account auth token. The repair is printed, never
 * performed.
 */
import { readFile } from 'node:fs/promises';

const MESSAGING = 'https://messaging.twilio.com/v1';

/**
 * Reduce any phone number to one comparable E.164 string, or null.
 *
 * The feed is E.164. Contact tables are not: they hold (415) 555-0100,
 * 415-555-0100, +1 415 555 0100 and one with a trailing space. Comparing the
 * raw strings matches nothing, the report says zero findings, and everybody
 * concludes the problem does not apply to them. Pure, and tested, because this
 * function silently decides whether the audit works at all.
 */
export function normalize(raw, defaultCc = '1') {
  const text = String(raw ?? '').trim();
  if (!text) return null;
  const plus = text.startsWith('+');
  let digits = text.replace(/[^0-9]/g, '');
  if (!digits) return null;
  if (!plus && digits.length === 10) digits = String(defaultCc) + digits;
  else if (!plus && digits.length === 11 && digits.startsWith(String(defaultCc))) {
    // already national plus country code
  } else if (!plus && digits.length < 10) return null;
  return `+${digits}`;
}

/**
 * Normalise a contact list into a Map of number to record. Pure. Accepts plain
 * strings or objects carrying number, suppressed and last_sent_at.
 */
export function loadContacts(rows, defaultCc = '1') {
  const out = new Map();
  for (const row of rows) {
    const record = typeof row === 'string' ? { number: row } : { ...row };
    const key = normalize(record.number, defaultCc);
    if (key) {
      record.number = key;
      out.set(key, record);
    }
  }
  return out;
}

/** Intersect the feed with the contact list. Pure. Both already normalised. */
export function reconcile(deactivations, contacts) {
  const matches = [];
  for (const [number, on] of deactivations) {
    const record = contacts.get(number);
    if (!record) continue;
    matches.push({
      number,
      deactivated_on: on,
      last_sent_at: record.last_sent_at ?? null,
      suppressed: Boolean(record.suppressed),
      label: record.label ?? record.name ?? '',
    });
  }
  return matches.sort((a, b) => (a.number < b.number ? -1 : 1));
}

/**
 * Classify one match. Pure. Returns [state, detail]. Dates are compared as ISO
 * strings on the first ten characters, so a full timestamp and a bare date
 * compare correctly against each other.
 */
export function verdict(match) {
  const on = String(match.deactivated_on ?? '').slice(0, 10);
  const sent = String(match.last_sent_at ?? '').slice(0, 10);

  if (match.suppressed) {
    return ['suppressed',
      'already suppressed. Keep the record: it is the evidence that consent ' +
      `for this number ended on ${on}.`];
  }

  if (sent && on && sent >= on) {
    return ['misdelivered',
      `deactivated ${on} and you sent to it on ${sent}. Those messages reached ` +
      'whoever owns the number now. If any of them carried a verification code, ' +
      'treat it as an access-control incident.'];
  }

  return ['at-risk',
    `deactivated ${on} and still active in your list. The next send goes to a ` +
    "stranger and the consent record you hold is the previous owner's."];
}

function authHeader(key, secret) {
  return `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}`;
}

/**
 * Numbers deactivated on one day, or an empty array. The API answers with a
 * short-lived signed URL, either as redirect_to in a JSON body or as a Location
 * header on a redirect. The signature is the authorisation on that URL, so it
 * is fetched without the Twilio credentials.
 */
async function feedFor(auth, day) {
  const u = new URL(`${MESSAGING}/Deactivations`);
  u.searchParams.set('Date', day);
  const res = await fetch(u, { headers: { Authorization: auth }, redirect: 'manual' });
  if (res.status === 401 || res.status === 403) {
    throw new Error(`${res.status} from Twilio: check TWILIO_ACCOUNT_SID and ` +
                    'that the API key belongs to that account with read access');
  }
  if (res.status === 404) {
    console.log(`no deactivation feed published for ${day}`);
    return [];
  }
  let target = res.headers.get('location');
  if (!target) {
    try { target = (await res.json())?.redirect_to ?? null; } catch { target = null; }
  }
  if (!target) {
    console.warn(`no redirect_to for ${day} (status ${res.status})`);
    return [];
  }
  const body = await fetch(target);
  if (!body.ok) throw new Error(`${body.status} fetching the signed feed for ${day}`);
  return (await body.text()).split('\n').map((l) => l.trim()).filter(Boolean);
}

function argOf(name, fallback) {
  const i = process.argv.indexOf(name);
  return i === -1 ? fallback : process.argv[i + 1];
}

async function main() {
  const account = process.env.TWILIO_ACCOUNT_SID;
  const key = process.env.TWILIO_API_KEY;
  const secret = process.env.TWILIO_API_SECRET;
  if (!account || !key || !secret) {
    console.error('set TWILIO_ACCOUNT_SID, TWILIO_API_KEY and TWILIO_API_SECRET ' +
                  '(an API Key with read access, not the auth token)');
    process.exitCode = 2;
    return;
  }
  const path = argOf('--contacts', null);
  if (!path) {
    console.error('--contacts is required: a JSON file of numbers or records');
    process.exitCode = 2;
    return;
  }
  const days = Number(argOf('--days', 7));
  const cc = String(argOf('--country-code', '1'));
  const auth = authHeader(key, secret);

  const contacts = loadContacts(JSON.parse(await readFile(path, 'utf-8')), cc);
  console.log(`${contacts.size} contact(s) after normalisation`);

  const deactivations = new Map();
  for (let offset = 1; offset <= days; offset += 1) {
    const day = new Date(Date.now() - offset * 86400000).toISOString().slice(0, 10);
    for (const raw of await feedFor(auth, day)) {
      const number = normalize(raw, cc);
      if (number && !deactivations.has(number)) deactivations.set(number, day);
    }
  }

  const matches = reconcile(deactivations, contacts);
  let incidents = 0;
  for (const match of matches) {
    const [state, detail] = verdict(match);
    const line = `${state.padEnd(13)} ${match.number}  ${detail}`;
    if (state === 'suppressed') { console.log(line); continue; }
    if (state === 'misdelivered') incidents += 1;
    console.warn(line);
    console.warn(`  repair: suppress ${match.number} in your contact table now, ` +
                 'and re-verify ownership before you send to it again. Do not ' +
                 'carry the old consent record onto a recycled number.');
  }

  console.log(`${deactivations.size} deactivation(s) over ${days} day(s), ` +
              `${matches.length} match(es), ${incidents} already messaged`);
  process.exitCode = matches.length ? 1 : 0;
}

// Only run when invoked directly. The test file imports this module, and without
// the guard main() would run there too, fail on the missing credentials and set a
// non-zero exit code that fails the whole test file even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from twilio_deactivations_audit import load_contacts, normalize, reconcile, verdict


def test_every_common_contact_format_normalises_to_one_key():
    for raw in ["+14155550100", "(415) 555-0100", "415-555-0100",
                " +1 415 555 0100 ", "1 (415) 555 0100"]:
        assert normalize(raw) == "+14155550100"


def test_a_non_us_number_keeps_its_own_country_code():
    assert normalize("+44 20 7946 0100") == "+442079460100"


def test_junk_and_short_numbers_are_dropped_rather_than_guessed():
    assert normalize("") is None
    assert normalize(None) is None
    assert normalize("not a number") is None
    assert normalize("5550100") is None


def test_reconcile_matches_across_different_formats():
    # The whole point: the feed is E.164 and the contact table is not.
    contacts = load_contacts([
        {"number": "(415) 555-0100", "last_sent_at": None},
        {"number": "415-555-0199"},
    ])
    deactivations = {"+14155550100": "2026-08-01"}
    matches = reconcile(deactivations, contacts)
    assert [m["number"] for m in matches] == ["+14155550100"]
    assert matches[0]["deactivated_on"] == "2026-08-01"


def test_sending_after_the_deactivation_date_is_an_incident():
    state, detail = verdict({"number": "+14155550100",
                             "deactivated_on": "2026-08-01",
                             "last_sent_at": "2026-08-14T09:12:00Z"})
    assert state == "misdelivered"
    assert "access-control incident" in detail


def test_a_send_before_the_deactivation_is_only_at_risk():
    state, _ = verdict({"number": "+14155550100",
                        "deactivated_on": "2026-08-01",
                        "last_sent_at": "2026-07-30"})
    assert state == "at-risk"


def test_a_match_with_no_sends_is_still_at_risk():
    state, detail = verdict({"number": "+14155550100",
                             "deactivated_on": "2026-08-01",
                             "last_sent_at": None})
    assert state == "at-risk"
    assert "consent record" in detail


def test_an_already_suppressed_match_is_not_reported_as_a_problem():
    state, _ = verdict({"number": "+14155550100", "deactivated_on": "2026-08-01",
                        "last_sent_at": "2026-08-14", "suppressed": True})
    assert state == "suppressed"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
  loadContacts, normalize, reconcile, verdict,
} from './twilio-deactivations-audit.mjs';

test('every common contact format normalises to one key', () => {
  for (const raw of ['+14155550100', '(415) 555-0100', '415-555-0100',
    ' +1 415 555 0100 ', '1 (415) 555 0100']) {
    assert.equal(normalize(raw), '+14155550100');
  }
});

test('a non us number keeps its own country code', () => {
  assert.equal(normalize('+44 20 7946 0100'), '+442079460100');
});

test('junk and short numbers are dropped rather than guessed', () => {
  assert.equal(normalize(''), null);
  assert.equal(normalize(null), null);
  assert.equal(normalize('not a number'), null);
  assert.equal(normalize('5550100'), null);
});

test('reconcile matches across different formats', () => {
  const contacts = loadContacts([
    { number: '(415) 555-0100', last_sent_at: null },
    { number: '415-555-0199' },
  ]);
  const deactivations = new Map([['+14155550100', '2026-08-01']]);
  const matches = reconcile(deactivations, contacts);
  assert.deepEqual(matches.map((m) => m.number), ['+14155550100']);
  assert.equal(matches[0].deactivated_on, '2026-08-01');
});

test('sending after the deactivation date is an incident', () => {
  const [state, detail] = verdict({
    number: '+14155550100',
    deactivated_on: '2026-08-01',
    last_sent_at: '2026-08-14T09:12:00Z',
  });
  assert.equal(state, 'misdelivered');
  assert.match(detail, /access-control incident/);
});

test('a send before the deactivation is only at risk', () => {
  const [state] = verdict({
    number: '+14155550100', deactivated_on: '2026-08-01', last_sent_at: '2026-07-30',
  });
  assert.equal(state, 'at-risk');
});

test('a match with no sends is still at risk', () => {
  const [state, detail] = verdict({
    number: '+14155550100', deactivated_on: '2026-08-01', last_sent_at: null,
  });
  assert.equal(state, 'at-risk');
  assert.match(detail, /consent record/);
});

test('an already suppressed match is not reported as a problem', () => {
  const [state] = verdict({
    number: '+14155550100',
    deactivated_on: '2026-08-01',
    last_sent_at: '2026-08-14',
    suppressed: true,
  });
  assert.equal(state, 'suppressed');
});