TNS Deposit Service
===================

A passive SIP signaling capture service for the TNS Enterprise Branded Calling
platform. Observes outbound SIP INVITEs, identifies calls from TNS-enrolled
TNs, and fires pre-call token deposits via the TNS Call Event API — all
without touching the SIP signaling path.


Deployment Modes
----------------

The service supports two deployment modes, selected via the
`capture.deployment_mode` config field:

  native_host    Runs on the call-processing host itself (SBC, PBX, or
                 CCaaS platform). Captures SIP traffic on the local
                 interfaces. No external network changes required.
                 The recommended mode for partner platforms and Linux-based
                 SBCs that support third-party package installation.

  span_tap       Runs on a separate host receiving SIP traffic via a switch
                 SPAN/mirror port. Used when the call-processing platform
                 cannot host a third-party service (proprietary SBC, fully
                 managed cloud, security policy restrictions). Requires
                 promiscuous-mode capture on a dedicated tap interface.

The capture mechanism is identical in both modes — only the configuration
differs.


Quick Start (native_host)
-------------------------

  1. Install the package
       apt install tns-deposit-service        # Debian/Ubuntu
       yum install tns-deposit-service        # RHEL/CentOS (EPEL required for python3-scapy)

  2. Verify dependencies
       tns-deposit-service-preflight

  3. Edit the config
       /etc/tns-deposit-service/config.yaml

     Required values:
       - capture.deployment_mode  ("native_host" — already the default)
       - capture.target_ips       (carrier-facing SBC/trunk IPs — CRITICAL for correctness)
       - tns.api_url              (provided by TNS during onboarding)
       - registry                 (where to find the registered TN list)

  4. Validate the config
       tns-deposit-service --check-config

  5. Start the service
       systemctl enable --now tns-deposit-service

  6. Check it's running
       systemctl status tns-deposit-service
       curl http://127.0.0.1:8080/status


Quick Start (span_tap)
----------------------

  1. Provision a dedicated capture host
       - Any Linux distribution with libpcap support
       - At least two NICs: one for management, one for SPAN ingestion
       - Sized to handle peak SIP signaling rate plus headroom

  2. Configure the SPAN destination interface
       - Bring the interface up but assign no IP address
       - Add no default route via this interface
       - Example (Linux):
           ip link set eth1 up

  3. Configure the network switch to mirror SIP signaling traffic to
     the capture host's SPAN destination interface. Mirror traffic from
     the SBC's call-processing-facing interface (where outbound INVITEs
     leave for the carrier).

     Example Cisco config:
       monitor session 1 source interface GigabitEthernet1/0/1 tx
       monitor session 1 destination interface GigabitEthernet1/0/24

  4. Install the package on the capture host
       apt install tns-deposit-service

  5. Edit /etc/tns-deposit-service/config.yaml and set:
       capture:
         deployment_mode: "span_tap"
         interface: "eth1"          # the SPAN destination interface
         target_ips:                # SBCs whose traffic to observe
           - "10.20.30.40"
           - "10.20.30.41"
         promiscuous: true
       tns:
         api_url: "..."
       registry:
         source: "..."
         ...

  6. Validate the config
       tns-deposit-service --check-config

  7. Start the service and verify INVITEs are being captured
       systemctl enable --now tns-deposit-service
       journalctl -u tns-deposit-service -f


How It Works
------------

  - Captures SIP packets via libpcap with a tight BPF filter:
    by default, UDP port 5060 packets whose payload begins with "INVITE".

  - For each INVITE, extracts the originating number (preferring
    P-Asserted-Identity, falling back to From header) and the terminating
    number from the Request-URI.

  - The originating number is checked against a registered TN list (from
    config, SQLite, or a remote database).

  - For matches, fires an asynchronous HTTPS POST to the TNS Call Event
    API to deposit the token before the call reaches the terminating carrier.

  - The original call signaling is untouched and proceeds normally.


Authentication
--------------

  The current TNS Call Event API does not require authentication. This
  service version (0.1.x) makes unauthenticated POST requests to the
  configured API endpoint.

  If a future API version introduces authentication, a new service
  version will be released to handle it.


What This Does NOT Do
---------------------

  - Does not proxy, redirect, or modify any SIP traffic.
  - Does not affect call setup, call quality, or call routing.
  - Cannot decrypt SIP-TLS encrypted signaling (passive capture limitation).
  - Cannot fire deposits if the service is stopped or unreachable from the
    network path. Calls will proceed normally without branding in that case.


Endpoints
---------

  The service exposes a small HTTP server (bound to 127.0.0.1:8080 by default):

  GET /healthz        Liveness probe. Returns "ok" with HTTP 200.
  GET /metrics        Prometheus-format counters and gauges.
  GET /status         JSON snapshot of current state.


Logs
----

  Logs go to journald (use journalctl -u tns-deposit-service to view).
  By default, logs are emitted as structured JSON — set service.log_format
  to "text" in the config for human-readable output during debugging.


Common Operations
-----------------

  Re-run dependency preflight check at any time:
    tns-deposit-service-preflight

  Reload after config change:
    systemctl restart tns-deposit-service

  Tail logs in real time:
    journalctl -u tns-deposit-service -f

  Print the BPF filter that would be applied:
    tns-deposit-service --print-bpf

  Validate config without starting:
    tns-deposit-service --check-config


Troubleshooting
---------------

  Service won't start? Run preflight first:
    tns-deposit-service-preflight

  This will identify any missing Python modules, missing libpcap,
  missing config files, or other environmental issues.

  After fixing dependencies on Debian/Ubuntu, you can also run:
    apt-get install -f

  This resolves any unmet declared dependencies from the package.

  SPAN deployment not seeing any INVITEs?
    1. Verify the SPAN session is configured correctly on the switch.
    2. Verify the capture interface is up:
         ip link show eth1
    3. Verify packets are arriving at the interface:
         tcpdump -i eth1 -nn port 5060 -c 10
    4. Verify the service is in span_tap mode with promiscuous=true.
    5. Check that target_ips includes the actual SBC IPs you expect to see.


Support
-------

  Support and operational issues: TNS Solutions Engineering
  Documentation: https://tnsi.com/docs/deposit-service
