A ashkan@beigi.net 8672b0de6b Add Phase-1 eSIM provisioning implementation

Full working closed-loop eSIM provisioning stack (spec in claude.md / plan/):
Flask API, SQLite subscriber store, credential/profile generator, Open5GS
and free5gc core adapters, captive portal, operational scripts, systemd
units, network configs, and a 44-test suite.

Profile generation currently returns a mock JSON profile; real SGP.22
generation via pySim is the planned Phase-2 upgrade.

Fixes two bugs found while getting the suite green:
- generate_imsi hardcoded a 10-digit MSIN, producing 16-digit IMSIs for a
  3-digit MNC; MSIN length is now 15 - len(mcc) - len(mnc).
- check_rate_limit compared timestamps as strings across mismatched formats
  (SQLite CURRENT_TIMESTAMP vs Python isoformat); both sides now normalized
  via SQLite datetime() so the window check is chronologically correct.

Add .gitignore for venv, caches, runtime config.yaml, and databases.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-01 05:56:31 +00:00

2.1 KiB

Raw Blame History

Android / Termux Deployment

Run the eSIM provisioning server on an Android device using Termux (no root required for basic operation).

Prerequisites

Android 9 or later
Termux installed from F-Droid (not the Play Store version — it is outdated)
Optional: Termux:Boot (F-Droid) for automatic start on reboot
5G-capable device with a pre-provisioned SIM for gNB backhaul

Install

# In Termux, from the repo root:
bash android/termux_setup.sh

The script will:

Update Termux packages
Install Python, nginx, and required libraries
Deploy the server files to ~/esim-provisioning/
Write a localised config.yaml
Configure nginx on port 8080
Initialise the SQLite database

Start the Server

~/esim-provisioning/start.sh

WiFi Hotspot

Go to Settings → Network → Hotspot & Tethering → WiFi Hotspot
Set a name (e.g. Emergency-5G) and remove the password (open network)
Enable the hotspot

Clients connect to the hotspot, then navigate to:

http://192.168.43.1:8080/activate

Most Android devices use 192.168.43.1 as the hotspot gateway. Samsung and Pixel devices may differ — check with ip route in Termux and update config.yaml accordingly.

Captive Portal Limitation

Without root, full DNS hijacking is not possible. Clients will not be automatically redirected — they must open the URL manually or scan a QR code posted at the deployment site.

With root + Termux, install dnsmasq via pkg install dnsmasq and add:

address=/#/192.168.43.1

to /data/data/com.termux/files/usr/etc/dnsmasq.conf, then run dnsmasq.

Configuration

Edit ~/esim-provisioning/config.yaml to set your MCC, MNC, and OP key, then restart:

pkill -f server.app
CONFIG_PATH=~/esim-provisioning/config.yaml python -m server.app &

Auto-Start on Reboot (Termux:Boot)

Install Termux:Boot from F-Droid. The setup script copies start.sh to ~/.termux/boot/ automatically. Open Termux:Boot once to enable it.

2.1 KiB Raw Blame History