From bb22cf520dee0019ec235b466b460cef2cab0d24 Mon Sep 17 00:00:00 2001 From: J1-PIPELINE Date: Sun, 5 Jul 2026 20:35:42 -0400 Subject: [PATCH 1/9] fix: correct dashboard port in README from 8080 to 5000 The README documented the dashboard on port 8080, but the actual code defaults to port 5000 (DASHBOARD_PORT=5000 in 01_install.sh and dashboard.py). This mismatch would confuse users trying to access the dashboard after installation. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 444f003..7c372b0 100644 --- a/README.md +++ b/README.md @@ -59,9 +59,9 @@ sudo ./02_configure.sh After installation, open the status dashboard: ```bash -# The dashboard is served on port 8080 +# The dashboard is served on port 5000 # Open in your browser: -# http://:8080 +# http://:5000 ``` ## πŸ“ Project Structure From 65ddcd30d04adb2e8cb2b7249ae82611894ea086 Mon Sep 17 00:00:00 2001 From: J1-PIPELINE Date: Sun, 5 Jul 2026 20:35:50 -0400 Subject: [PATCH 2/9] fix: prevent XSS via DHCP lease hostnames in dashboard The renderLeases() function used innerHTML with template literals to render DHCP lease data, including untrusted hostnames from dnsmasq leases. A malicious DHCP client could set a crafted hostname to inject JavaScript. Fixed by using DOM API (textContent) instead of innerHTML, which automatically escapes all HTML entities. --- templates/dashboard.html | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/templates/dashboard.html b/templates/dashboard.html index a2738e9..8ce2187 100644 --- a/templates/dashboard.html +++ b/templates/dashboard.html @@ -170,9 +170,20 @@

Connected Clients

tbody.innerHTML = 'No clients connected'; return; } - tbody.innerHTML = leases.map(l => - `${l.ip}${l.mac}${l.name || '*'}` - ).join(''); + tbody.innerHTML = ''; + for (const l of leases) { + const tr = document.createElement('tr'); + const tdIp = document.createElement('td'); + tdIp.textContent = l.ip || '*'; + const tdMac = document.createElement('td'); + tdMac.textContent = l.mac || '*'; + const tdName = document.createElement('td'); + tdName.textContent = l.name || '*'; + tr.appendChild(tdIp); + tr.appendChild(tdMac); + tr.appendChild(tdName); + tbody.appendChild(tr); + } } async function api(endpoint, method='POST') { From 626b59068acf52f9a25ebc860ab4de4c76c1e17f Mon Sep 17 00:00:00 2001 From: J1-PIPELINE Date: Sun, 5 Jul 2026 20:36:10 -0400 Subject: [PATCH 3/9] fix: use ipaddress module for robust subnet restriction The dashboard's AP subnet check used a fragile prefix match (client_ip.startswith()) that only worked for /24 subnets. A /16 or /28 configuration would silently bypass the restriction. Replaced with Python's ipaddress module for proper CIDR notation support. Now any valid subnet (e.g., 10.0.0.0/8, 172.16.0.0/16, 192.168.1.0/28) is correctly validated. --- 02_configure.sh | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/02_configure.sh b/02_configure.sh index 8b5de4b..f5fb8e3 100644 --- a/02_configure.sh +++ b/02_configure.sh @@ -140,7 +140,7 @@ ok "Stats helper ready" # ── Flask Dashboard ─────────────────────────────────────── info "Deploying dashboard..." cat > $APP_DIR/dashboard.py <<'DASHBOARD' -import os, json, subprocess, time +import os, json, subprocess, time, ipaddress from flask import Flask, render_template, jsonify, request from flask_socketio import SocketIO import threading @@ -151,7 +151,7 @@ socketio = SocketIO(app, cors_allowed_origins=[], async_mode="eventlet") PORT = int(os.environ.get("DASHBOARD_PORT", 5000)) # Restrict API endpoints to AP subnet by default -AP_SUBNET = os.environ.get("AP_SUBNET", "192.168.50.0/24") +AP_SUBNET = ipaddress.ip_network(os.environ.get("AP_SUBNET", "192.168.50.0/24"), strict=False) def get_stats(): try: @@ -177,9 +177,8 @@ def restrict_subnet(): """Optional: restrict write operations to AP subnet.""" # Allow all GET requests; restrict POST to AP subnet only if request.method == "POST": - client_ip = request.remote_addr - # Check if client is in AP subnet (simple prefix check for /24) - if not client_ip.startswith(AP_SUBNET.rsplit(".", 1)[0] + "."): + client_ip = ipaddress.ip_address(request.remote_addr) + if client_ip not in AP_SUBNET: return jsonify({"error": "Forbidden: not on AP subnet"}), 403 @app.route("/") From 650e8ceb2367e44dd38f03146209ff0740b1b05c Mon Sep 17 00:00:00 2001 From: J1-PIPELINE Date: Sun, 5 Jul 2026 20:36:30 -0400 Subject: [PATCH 4/9] fix: add requirements section and default password warning to README and installer - Added Requirements section to README documenting root access, Cloudflare WARP, WiFi AP chipset, and Telegram Bot Token needs - Added prominent default password warning in both README and 01_install.sh output - Resolves EGW-001 (missing requirements documentation) --- 01_install.sh | 7 +++++-- README.md | 11 +++++++++++ 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/01_install.sh b/01_install.sh index f90731d..a5d1e4f 100644 --- a/01_install.sh +++ b/01_install.sh @@ -20,7 +20,7 @@ AP_IFACE="wlan0" # WiFi interface used as AP (internal hotspot) WAN_IFACE="eth0" # LAN port = uplink from ISP router/switch AP_SSID="PiGateway" -AP_PASS="SuperSecret99" # ← Change this! +AP_PASS="SuperSecret99" # ← CHANGE THIS before production deployment! AP_CHANNEL=6 AP_IP="192.168.50.1" AP_SUBNET="192.168.50.0/24" @@ -203,13 +203,16 @@ systemctl unmask hostapd systemctl enable hostapd dnsmasq warp-svc ok "Services enabled" -# ── Install systemd units (created by next script) ─────── +# ── Done ─────────────────────────────────────────────────── info "Done! Run 02_configure.sh to deploy dashboard & bot." echo "" echo -e "${GREEN}======================================${NC}" echo -e "${GREEN} Pi Gateway base install complete! ${NC}" echo -e "${GREEN}======================================${NC}" echo "" +echo -e "${YELLOW}⚠ WARNING: Default AP password is set!${NC}" +echo -e "${YELLOW} Edit AP_PASS in 01_install.sh before production use.${NC}" +echo "" echo " AP SSID : $AP_SSID" echo " AP Pass : $AP_PASS" echo " AP IP : $AP_IP" diff --git a/README.md b/README.md index 7c372b0..93900a1 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,17 @@ ## πŸš€ Quick Start +### Requirements + +- **Raspberry Pi** (3B+, 4B, or 5) running **Raspberry Pi OS** (Debian-based) +- **Root access** β€” both scripts must run with `sudo` +- **Cloudflare WARP client** β€” the install script adds the Cloudflare apt repo automatically +- **Ethernet WAN uplink** on `eth0` (LAN cable from ISP router) +- **WiFi chipset** supporting AP mode (built-in on Pi 3B+/4/5, or USB adapter) +- **Telegram Bot Token** (optional, for bot functionality) β€” create via [@BotFather](https://t.me/BotFather) + +> ⚠️ **IMPORTANT**: Before running the installer, edit `01_install.sh` and change the default AP password (`AP_PASS="SuperSecret99"`). The default is a placeholder and MUST be changed for any production or public deployment. + ```bash git clone https://github.com/OneByJorah/EdgeGateway.git cd EdgeGateway From 3680b9e26162c46f16bc3fd6edd5f3f840db83bd Mon Sep 17 00:00:00 2001 From: J1-PIPELINE Date: Sun, 5 Jul 2026 20:36:37 -0400 Subject: [PATCH 5/9] fix: add default DROP policy to iptables firewall rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The iptables rules flushed existing rules but did not set a default DROP policy on INPUT and FORWARD chains, leaving the system with an implicit ACCEPT policy for any traffic not explicitly matched. Added explicit DROP defaults for INPUT and FORWARD chains, with ACCEPT for OUTPUT. This ensures only explicitly allowed traffic (loopback, established connections, APβ†’WARP forwarding) is permitted. --- 01_install.sh | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/01_install.sh b/01_install.sh index a5d1e4f..45a8731 100644 --- a/01_install.sh +++ b/01_install.sh @@ -166,6 +166,11 @@ iptables -F iptables -t nat -F iptables -X +# Default deny +iptables -P INPUT DROP +iptables -P FORWARD DROP +iptables -P OUTPUT ACCEPT + # Allow loopback iptables -A INPUT -i lo -j ACCEPT iptables -A OUTPUT -o lo -j ACCEPT From 3ad1b6f8199c9df462dde5b76fd7209c758eb042 Mon Sep 17 00:00:00 2001 From: J1-PIPELINE Date: Sun, 5 Jul 2026 20:36:52 -0400 Subject: [PATCH 6/9] feat: add requirements.txt with pinned Python dependencies - Created requirements.txt with version-pinned Python dependencies (flask, flask-socketio, python-telegram-bot==20.8, psutil, requests, gunicorn, eventlet) - Updated 01_install.sh to install from requirements.txt instead of inline pip install - Added reports/ to .gitignore --- .gitignore | 2 ++ 01_install.sh | 7 ++----- requirements.txt | 11 +++++++++++ 3 files changed, 15 insertions(+), 5 deletions(-) create mode 100644 requirements.txt diff --git a/.gitignore b/.gitignore index b91f767..178dcc1 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,5 @@ build/ *.so # Logs *.log +# Reports +reports/ diff --git a/01_install.sh b/01_install.sh index 45a8731..f9c3cb4 100644 --- a/01_install.sh +++ b/01_install.sh @@ -85,16 +85,13 @@ ok "Cloudflare WARP installed" info "Setting up Python environment..." python3 -m venv /opt/EdgeGateway/venv /opt/EdgeGateway/venv/bin/pip install -q --upgrade pip -/opt/EdgeGateway/venv/bin/pip install -q \ - flask flask-socketio \ - python-telegram-bot==20.8 \ - psutil requests \ - gunicorn eventlet +/opt/EdgeGateway/venv/bin/pip install -q -r /opt/EdgeGateway/requirements.txt ok "Python environment ready" # ── Copy app files ──────────────────────────────────────── info "Installing gateway app files..." mkdir -p /opt/EdgeGateway/{templates,static} +cp requirements.txt /opt/EdgeGateway/requirements.txt # (Files will be copied by 02_configure.sh) # ── Enable IP forwarding ────────────────────────────────── diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..46acaf0 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,11 @@ +# EdgeGateway Python dependencies +# Install in a virtual environment: python3 -m venv /opt/EdgeGateway/venv +# Then: pip install -r requirements.txt + +flask>=3.0,<4.0 +flask-socketio>=5.3,<6.0 +python-telegram-bot==20.8 +psutil>=5.9,<6.0 +requests>=2.31,<3.0 +gunicorn>=22.0,<23.0 +eventlet>=0.36,<0.37 From 81a4d5a59cf5b774f91743b960e2fdb171a7f1dd Mon Sep 17 00:00:00 2001 From: J1-PIPELINE Date: Sun, 5 Jul 2026 21:24:58 -0400 Subject: [PATCH 7/9] docs(EdgeGateway): add INTENT.md with ORACLE intent reconstruction --- INTENT.md | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 INTENT.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..d4d4fa6 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,217 @@ +# INTENT.md β€” J1-PIPELINE Phase -1 (ORACLE) + +**Repository:** `OneByJorah/EdgeGateway` +**Analysis Date:** 2026-07-05 +**Analyst:** J1-PIPELINE ORACLE (read-only) +**Status:** Intent Reconstructed + +--- + +## What This System Does + +**EdgeGateway** is a two-script provisioning system that transforms a Raspberry Pi (or any Debian/Ubuntu ARM host) into a self-contained secure edge gateway. It combines four subsystems into a single, repeatable deployment: + +| Subsystem | Role | Technology | +|-----------|------|------------| +| **WiFi Access Point** | Creates an internal hotspot (`wlan0`) for client devices to connect | `hostapd` + `dnsmasq` | +| **WARP Tunnel** | Routes *all* traffic (AP clients + WAN uplink) through Cloudflare's encrypted tunnel for DNS privacy and outbound proxying | `cloudflare-warp` client | +| **Monitoring Dashboard** | Real-time web UI showing WARP status, CPU/RAM/temperature, connected clients, throughput, and traffic totals | Flask + Flask-SocketIO + eventlet | +| **Telegram Bot** | Remote management via Telegram β€” status queries, WARP toggle/reconnect, service restart, Pi reboot | `python-telegram-bot` (v20.8) | + +### Technical Architecture + +``` +[ISP Router] --eth0--> [Raspberry Pi] --wlan0 (AP)--> [Client Devices] + | + Cloudflare WARP tunnel + | + [Cloudflare Edge] + | + [Internet] +``` + +- **eth0** = WAN uplink from ISP router (LAN cable) +- **wlan0** = WiFi Access Point (internal hotspot, SSID: `PiGateway`) +- **CloudflareWARP** = virtual tunnel interface β€” all forwarded traffic is MASQUERADEd through it +- **Fallback**: If WARP is down, traffic routes via raw WAN (eth0) as a degraded fallback +- **WARP Watchdog**: Cron job every 60s that reconnects WARP if the tunnel drops + +### Key Components + +| File | Purpose | +|------|---------| +| `01_install.sh` | System update, dependency install (hostapd, dnsmasq, iptables, Python), Cloudflare WARP client, Python venv with Flask/SocketIO/Telegram, hostapd config, dnsmasq config, iptables NAT rules, WARP registration, service enablement | +| `02_configure.sh` | WARP watchdog script, gateway stats helper (`gw-stats.sh`), Flask dashboard app (`dashboard.py`), Telegram bot (`bot.py`), systemd units for both services | +| `templates/dashboard.html` | Dark-themed real-time dashboard with stats cards, control buttons, and DHCP lease table | + +### API Surface (Dashboard) + +| Endpoint | Method | Action | +|----------|--------|--------| +| `/` | GET | Dashboard HTML | +| `/api/stats` | GET | JSON system stats | +| `/api/clients` | GET | JSON DHCP lease list | +| `/api/warp/toggle` | POST | Connect/disconnect WARP | +| `/api/warp/reconnect` | POST | Full WARP reconnect cycle | +| `/api/restart/` | POST | Restart hostapd, dnsmasq, or warp-svc | +| `/api/reboot` | POST | Reboot the Pi | + +### Telegram Bot Commands + +| Command | Action | +|---------|--------| +| `/start` | Show inline keyboard menu | +| `/status` | Display full system status | +| `/clients` | List connected DHCP clients | +| Inline buttons | WARP toggle, WARP reconnect, restart hostapd/dnsmasq, reboot Pi | + +### Operational Role + +EdgeGateway is a **turnkey edge appliance** β€” deploy it on a Raspberry Pi with two commands, and it becomes a privacy-respecting WiFi hotspot that tunnels all traffic through Cloudflare WARP. It is consumed by: + +- **End users** connecting to the `PiGateway` SSID β€” they get internet with DNS privacy (1.1.1.1) and encrypted outbound tunneling +- **The Pi's admin** β€” who monitors and controls the gateway via the web dashboard or Telegram bot +- **JorahOne's edge infrastructure** β€” as a repeatable, documented building block for privacy-first edge networking + +--- + +## Why This Was Built + +### Real Problem + +Setting up a privacy-respecting edge gateway on a Raspberry Pi traditionally requires: + +1. Manually configuring `hostapd` for WiFi AP mode +2. Manually configuring `dnsmasq` for DHCP/DNS +3. Manually setting up `iptables` NAT rules for traffic forwarding +4. Installing and registering a VPN/tunnel client (WireGuard, OpenVPN, or Cloudflare WARP) +5. Building a monitoring interface from scratch +6. Setting up remote management (SSH-only, no mobile-friendly option) + +This is error-prone, time-consuming, and produces a fragile, non-repeatable configuration. A single typo in `dnsmasq.conf` or a missed `iptables` rule breaks the entire gateway. There is no "one command to rule them all" for Pi-based WARP gateways. + +### Why Existing Tools Were Insufficient + +- **Commercial travel routers (GL.iNet, etc.)**: Proprietary, limited VPN protocol support, no Cloudflare WARP integration, no programmable API surface. +- **OpenWrt**: Powerful but steep learning curve, not Raspberry Pi-native, no WARP client in package repos. +- **Pi-hole**: DNS-level only β€” no traffic tunneling, no WiFi AP, no remote management. +- **DIY scripts on GitHub**: Fragmented β€” one repo for hostapd, another for VPN, another for monitoring. No unified, tested, two-step provisioning flow. +- **Cloudflare WARP standalone**: No WiFi AP integration, no dashboard, no remote management. + +EdgeGateway fills the gap: a **unified, two-command, repeatable provisioning system** that combines all of these into a single coherent deployment. + +### What Triggered Development + +The initial commit (`b176ed4` β€” "Initial commit: Pi Gateway installer scripts + docs") and the project's evolution show a clear trajectory: + +1. **Initial need** (June 15, 2026): A simple Pi-based gateway with WARP tunneling. The initial commit included both root-level files AND a `pi-router/` subdirectory with duplicate files β€” suggesting the project was originally named `pi-router` and later renamed to `EdgeGateway`. +2. **Security hardening** (June 15, 2026): Cleanup pass (`10839ba` β€” "Fix: full project cleanup and security hardening"). +3. **Dashboard** (June 15, 2026): Real-time monitoring UI (`41a7f55` β€” "Add dashboard screenshot"). +4. **Repo rename** (June 17, 2026): Migrated from `pi-router` to `EdgeGateway` branding across three commits (`3bed448` β†’ `f8601ee` β†’ `8cf0248`). +5. **Documentation maturity** (June 17–July 4, 2026): Multiple README iterations refining the narrative, aligning to J1 brand standard, and documenting host requirements. +6. **Code quality** (July 4, 2026): Ruff auto-fixes and portfolio standardization (`1619a2b`). +7. **Dependency bumps** (July 4, 2026): Dependabot PRs for `actions/checkout` and `github/codeql-action`. +8. **Security audit** (July 5, 2026): Email reference sanitization (`6401607` β€” "audit(EdgeGateway): sanitize email references"). + +The project was built iteratively, starting from a working installer and layering on observability (dashboard), remote management (Telegram bot), reliability (WARP watchdog), and security hardening over time. + +### Ecosystem Fit + +EdgeGateway is part of the **OneByJorah** portfolio of infrastructure tools. It complements: + +- **JorahOne's edge computing strategy**: Lightweight, ARM-optimized, privacy-first networking for edge deployments +- **The broader ecosystem**: Sits alongside other JorahOne repos as a self-contained, deployable component β€” not a library or framework, but a turnkey appliance +- **MIT licensing**: Open-source, community-friendly, aligned with JorahOne's permissive licensing model + +``` +OneByJorah Ecosystem +β”œβ”€β”€ EdgeGateway ← Turnkey Pi-based WARP gateway appliance +β”œβ”€β”€ EdgeRouter ← (sibling: router-focused infrastructure) +└── [other J1 repos] ← Self-contained deployable components +``` + +--- + +## Operational Classification + +**Classification: PRODUCTION** β€” this is a deployable, self-contained edge appliance with monitoring, self-healing, and a security disclosure process. + +Evidence: +- **Version**: CHANGELOG.md declares v1.0.0 (though no git tag exists β€” minor gap) +- **Health checks**: systemd-managed services with `Restart=always` and `RestartSec=5/10`; WARP watchdog cron job for self-healing +- **CI/CD**: CodeQL analysis on push/PR + weekly schedule; Dependabot for GitHub Actions dependency updates +- **Security posture**: SECURITY.md with 90-day disclosure timeline, dedicated security contact email, iptables firewall rules, AP subnet restriction on POST endpoints, Telegram admin whitelist +- **Security audits in git history**: Two security-focused commits β€” `10839ba` (full project cleanup and security hardening) and `6401607` (email reference sanitization) +- **Monitoring**: Real-time web dashboard (Flask + SocketIO), Telegram bot for remote status, `gw-stats.sh` for JSON metrics, vnstat traffic tracking, DHCP lease monitoring +- **Community readiness**: CONTRIBUTING.md, CODE_OF_CONDUCT.md (Contributor Covenant v2.1), bug report template, feature request template, PR template +- **No live deployment evidence**: `deploy_log.txt` confirms the system is NOT deployable in the current analysis environment (requires root + Cloudflare WARP) + +--- + +## Key Architectural Decisions + +1. **Two-phase provisioning** (`01_install.sh` β†’ `02_configure.sh`): Separates system-level installation (requires reboot) from application deployment. User can edit `config.env` between phases. This is a deliberate UX choice β€” the first script handles all the heavy system changes, the second deploys the application layer. + +2. **Python venv isolation**: Dashboard and bot run in `/opt/EdgeGateway/venv` β€” no system Python contamination. All dependencies (Flask, SocketIO, python-telegram-bot, psutil, gunicorn, eventlet) are isolated. + +3. **Config.env pattern**: All configuration centralized in `/etc/EdgeGateway/config.env` β€” single source of truth, sourced by both systemd units and scripts. No scattered config files. + +4. **WARP watchdog**: Cron-based self-healing β€” if the tunnel drops, it reconnects automatically within 60 seconds. This is critical for a gateway that must stay online. + +5. **Fallback routing**: If WARP is unreachable, traffic falls back to raw WAN (eth0) β€” degraded but not dead. The iptables rules include a fallback MASQUERADE on `$WAN_IFACE`. + +6. **AP subnet restriction**: Dashboard POST endpoints check client IP against the AP subnet β€” prevents WAN-side admin access. This is a security-by-design choice. + +7. **Telegram admin whitelist**: Only `ADMIN_CHAT_ID` users can control the gateway via bot. The bot validates `update.effective_user.id` against the whitelist on every interaction. + +8. **No Docker**: Deliberately bare-metal β€” the system needs direct access to network interfaces (hostapd, iptables, WARP tunnel) that Docker would complicate. The `stack_manifest.json` confirms `has_docker: false`. + +9. **ARM-first design**: The Cloudflare WARP apt repo is configured for `arm64` only. This is a deliberate Raspberry Pi focus β€” x86_64 hosts would need a different source. + +--- + +## Repository Structure + +``` +EdgeGateway/ +β”œβ”€β”€ 01_install.sh # Step 1: System + WARP + AP + firewall install +β”œβ”€β”€ 02_configure.sh # Step 2: Dashboard + Telegram bot + systemd units +β”œβ”€β”€ templates/ +β”‚ └── dashboard.html # Real-time monitoring UI (Flask template) +β”œβ”€β”€ .github/ +β”‚ β”œβ”€β”€ workflows/ +β”‚ β”‚ └── codeql.yml # CodeQL security analysis (weekly + push/PR) +β”‚ β”œβ”€β”€ dependabot.yml # Weekly GitHub Actions dependency updates +β”‚ β”œβ”€β”€ ISSUE_TEMPLATE/ +β”‚ β”‚ β”œβ”€β”€ bug_report.md +β”‚ β”‚ └── feature_request.md +β”‚ └── PULL_REQUEST_TEMPLATE.md +β”œβ”€β”€ README.md # Project documentation +β”œβ”€β”€ CHANGELOG.md # v1.0.0 release notes +β”œβ”€β”€ ROADMAP.md # Future plans (production stability, docs, tests) +β”œβ”€β”€ SECURITY.md # Vulnerability disclosure policy (90-day timeline) +β”œβ”€β”€ CONTRIBUTING.md # Contribution guidelines +β”œβ”€β”€ CODE_OF_CONDUCT.md # Contributor Covenant v2.1 +β”œβ”€β”€ LICENSE # MIT +β”œβ”€β”€ .gitignore +β”œβ”€β”€ stack_manifest.json # Deployment metadata +β”œβ”€β”€ deploy_log.txt # Deployment attempt log +β”œβ”€β”€ review_findings.json # Code review findings (1 finding: README missing requirements note) +β”œβ”€β”€ INTENT.md # This file +└── screenshot-dashboard.png # Dashboard preview image +``` + +--- + +## Notes + +- **Repo rename**: The project was originally named `pi-router` (evidenced by the initial commit `b176ed4` which included a `pi-router/` subdirectory with duplicate files). It was renamed to `EdgeGateway` on June 17, 2026 across three commits. The `pi-router/` directory was subsequently removed. +- **No git tags**: CHANGELOG.md declares v1.0.0 but no corresponding git tag exists. This is a minor release-process gap. +- **No `docs/` directory**: All documentation lives in the README. No separate docs folder exists. +- **No test files**: No test suite exists β€” deployment is the only validation path. The ROADMAP.md lists "Test coverage expansion" as a current goal. +- **Dependabot ecosystem**: Correctly configured for `github-actions` only β€” no ecosystem mismatch (the repo has no `package.json` or `Dockerfile`). +- **Security audit history**: Two security-focused commits in the git log β€” `10839ba` ("Fix: full project cleanup and security hardening") and `6401607` ("audit(EdgeGateway): sanitize email references"). This is a positive maturity signal. +- **Default credentials**: Default AP password (`SuperSecret99`) is a placeholder β€” must be changed before production use. The script explicitly comments "← Change this!". +- **Single-point-of-failure**: The Raspberry Pi itself is the gateway β€” if it goes down, all AP clients lose internet. No HA/failover mechanism. +- **WARP dependency**: The system's privacy guarantees depend entirely on Cloudflare WARP availability. The fallback (raw WAN) provides no privacy. +- **Review finding (EGW-001)**: README omits documented `sudo` and Cloudflare WARP client package availability requirements. Severity: medium. From aaff661acabf79510411d1e608f8f7c757294971 Mon Sep 17 00:00:00 2001 From: J1-PIPELINE Date: Sun, 5 Jul 2026 21:25:13 -0400 Subject: [PATCH 8/9] chore(EdgeGateway): add j1.yaml pipeline metadata --- j1.yaml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 j1.yaml diff --git a/j1.yaml b/j1.yaml new file mode 100644 index 0000000..824e128 --- /dev/null +++ b/j1.yaml @@ -0,0 +1,15 @@ +repo: EdgeGateway +class: Infrastructure +org: OneByJorah +owner: Jhonattan L. Jimenez +license: MIT +production_score: 0 +last_audit: 2026-07-05 +last_publish: 2026-07-04 +standards_version: "2.1" +dependencies: [] +deploy_target: scratch +tailscale_only: false +public_facing: false +community_sla_hours: 48 +adoption_tracked: false From 13f94905e130c94bf3018589217e8e268652f771 Mon Sep 17 00:00:00 2001 From: J1-PIPELINE Date: Tue, 7 Jul 2026 19:46:57 -0400 Subject: [PATCH 9/9] =?UTF-8?q?Rebrand:=20EdgeGateway=20=E2=86=92=20WarpGa?= =?UTF-8?q?te?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update git remote URL to OneByJorah/WarpGate - Update README: title, clone URL, project structure - Update INTENT.md: all references (repo name, paths, descriptions) - Update 01_install.sh: /etc/WarpGate, /opt/WarpGate paths - Update 02_configure.sh: /etc/WarpGate, /opt/WarpGate paths - Update j1.yaml: repo name - Update requirements.txt: header comment - Update deploy_log.txt: header --- 01_install.sh | 20 ++++++++++---------- 02_configure.sh | 16 ++++++++-------- INTENT.md | 28 ++++++++++++++-------------- README.md | 8 ++++---- deploy_log.txt | 2 +- j1.yaml | 2 +- requirements.txt | 4 ++-- 7 files changed, 40 insertions(+), 40 deletions(-) diff --git a/01_install.sh b/01_install.sh index f9c3cb4..1b88085 100644 --- a/01_install.sh +++ b/01_install.sh @@ -30,12 +30,12 @@ AP_COUNTRY="US" # ← Set your 2-letter country code (regulatory domai WARP_MTU=1280 DASHBOARD_PORT=5000 -BOT_TOKEN="" # Set after install or in /etc/EdgeGateway/config.env +BOT_TOKEN="" # Set after install or in /etc/WarpGate/config.env ADMIN_CHAT_ID="" # Your Telegram chat ID # ── Persist config ──────────────────────────────────────── -mkdir -p /etc/EdgeGateway -cat > /etc/EdgeGateway/config.env < /etc/WarpGate/config.env < /usr/local/bin/gw-stats.sh <<'STATS' set -o pipefail # Source config for interface names -source /etc/EdgeGateway/config.env 2>/dev/null +source /etc/WarpGate/config.env 2>/dev/null # Fallback defaults if config didn't load : "${WAN_IFACE:=eth0}" @@ -253,7 +253,7 @@ BOT_TOKEN = os.environ.get("BOT_TOKEN", "") ADMIN_IDS = [int(x) for x in os.environ.get("ADMIN_CHAT_ID", "").split(",") if x.strip()] if not BOT_TOKEN: - raise SystemExit("BOT_TOKEN not set! Edit /etc/EdgeGateway/config.env") + raise SystemExit("BOT_TOKEN not set! Edit /etc/WarpGate/config.env") if not ADMIN_IDS: logger.warning("ADMIN_CHAT_ID is empty β€” no users will have admin access!") @@ -391,7 +391,7 @@ After=network.target warp-svc.service [Service] User=root WorkingDirectory=$APP_DIR -EnvironmentFile=/etc/EdgeGateway/config.env +EnvironmentFile=/etc/WarpGate/config.env ExecStart=$VENV/bin/python $APP_DIR/dashboard.py Restart=always RestartSec=5 @@ -409,7 +409,7 @@ After=network.target [Service] User=root WorkingDirectory=$APP_DIR -EnvironmentFile=/etc/EdgeGateway/config.env +EnvironmentFile=/etc/WarpGate/config.env ExecStart=$VENV/bin/python $APP_DIR/bot.py Restart=always RestartSec=10 diff --git a/INTENT.md b/INTENT.md index d4d4fa6..5fc33b6 100644 --- a/INTENT.md +++ b/INTENT.md @@ -1,6 +1,6 @@ # INTENT.md β€” J1-PIPELINE Phase -1 (ORACLE) -**Repository:** `OneByJorah/EdgeGateway` +**Repository:** `OneByJorah/WarpGate` **Analysis Date:** 2026-07-05 **Analyst:** J1-PIPELINE ORACLE (read-only) **Status:** Intent Reconstructed @@ -9,7 +9,7 @@ ## What This System Does -**EdgeGateway** is a two-script provisioning system that transforms a Raspberry Pi (or any Debian/Ubuntu ARM host) into a self-contained secure edge gateway. It combines four subsystems into a single, repeatable deployment: +**WarpGate** is a two-script provisioning system that transforms a Raspberry Pi (or any Debian/Ubuntu ARM host) into a self-contained secure edge gateway. It combines four subsystems into a single, repeatable deployment: | Subsystem | Role | Technology | |-----------|------|------------| @@ -67,7 +67,7 @@ ### Operational Role -EdgeGateway is a **turnkey edge appliance** β€” deploy it on a Raspberry Pi with two commands, and it becomes a privacy-respecting WiFi hotspot that tunnels all traffic through Cloudflare WARP. It is consumed by: +WarpGate is a **turnkey edge appliance** β€” deploy it on a Raspberry Pi with two commands, and it becomes a privacy-respecting WiFi hotspot that tunnels all traffic through Cloudflare WARP. It is consumed by: - **End users** connecting to the `PiGateway` SSID β€” they get internet with DNS privacy (1.1.1.1) and encrypted outbound tunneling - **The Pi's admin** β€” who monitors and controls the gateway via the web dashboard or Telegram bot @@ -98,26 +98,26 @@ This is error-prone, time-consuming, and produces a fragile, non-repeatable conf - **DIY scripts on GitHub**: Fragmented β€” one repo for hostapd, another for VPN, another for monitoring. No unified, tested, two-step provisioning flow. - **Cloudflare WARP standalone**: No WiFi AP integration, no dashboard, no remote management. -EdgeGateway fills the gap: a **unified, two-command, repeatable provisioning system** that combines all of these into a single coherent deployment. +WarpGate fills the gap: a **unified, two-command, repeatable provisioning system** that combines all of these into a single coherent deployment. ### What Triggered Development The initial commit (`b176ed4` β€” "Initial commit: Pi Gateway installer scripts + docs") and the project's evolution show a clear trajectory: -1. **Initial need** (June 15, 2026): A simple Pi-based gateway with WARP tunneling. The initial commit included both root-level files AND a `pi-router/` subdirectory with duplicate files β€” suggesting the project was originally named `pi-router` and later renamed to `EdgeGateway`. +1. **Initial need** (June 15, 2026): A simple Pi-based gateway with WARP tunneling. The initial commit included both root-level files AND a `pi-router/` subdirectory with duplicate files β€” suggesting the project was originally named `pi-router` and later renamed to `WarpGate`. 2. **Security hardening** (June 15, 2026): Cleanup pass (`10839ba` β€” "Fix: full project cleanup and security hardening"). 3. **Dashboard** (June 15, 2026): Real-time monitoring UI (`41a7f55` β€” "Add dashboard screenshot"). -4. **Repo rename** (June 17, 2026): Migrated from `pi-router` to `EdgeGateway` branding across three commits (`3bed448` β†’ `f8601ee` β†’ `8cf0248`). +4. **Repo rename** (June 17, 2026): Migrated from `pi-router` to `WarpGate` branding across three commits (`3bed448` β†’ `f8601ee` β†’ `8cf0248`). 5. **Documentation maturity** (June 17–July 4, 2026): Multiple README iterations refining the narrative, aligning to J1 brand standard, and documenting host requirements. 6. **Code quality** (July 4, 2026): Ruff auto-fixes and portfolio standardization (`1619a2b`). 7. **Dependency bumps** (July 4, 2026): Dependabot PRs for `actions/checkout` and `github/codeql-action`. -8. **Security audit** (July 5, 2026): Email reference sanitization (`6401607` β€” "audit(EdgeGateway): sanitize email references"). +8. **Security audit** (July 5, 2026): Email reference sanitization (`6401607` β€” "audit(WarpGate): sanitize email references"). The project was built iteratively, starting from a working installer and layering on observability (dashboard), remote management (Telegram bot), reliability (WARP watchdog), and security hardening over time. ### Ecosystem Fit -EdgeGateway is part of the **OneByJorah** portfolio of infrastructure tools. It complements: +WarpGate is part of the **OneByJorah** portfolio of infrastructure tools. It complements: - **JorahOne's edge computing strategy**: Lightweight, ARM-optimized, privacy-first networking for edge deployments - **The broader ecosystem**: Sits alongside other JorahOne repos as a self-contained, deployable component β€” not a library or framework, but a turnkey appliance @@ -125,7 +125,7 @@ EdgeGateway is part of the **OneByJorah** portfolio of infrastructure tools. It ``` OneByJorah Ecosystem -β”œβ”€β”€ EdgeGateway ← Turnkey Pi-based WARP gateway appliance +β”œβ”€β”€ WarpGate ← Turnkey Pi-based WARP gateway appliance β”œβ”€β”€ EdgeRouter ← (sibling: router-focused infrastructure) └── [other J1 repos] ← Self-contained deployable components ``` @@ -152,9 +152,9 @@ Evidence: 1. **Two-phase provisioning** (`01_install.sh` β†’ `02_configure.sh`): Separates system-level installation (requires reboot) from application deployment. User can edit `config.env` between phases. This is a deliberate UX choice β€” the first script handles all the heavy system changes, the second deploys the application layer. -2. **Python venv isolation**: Dashboard and bot run in `/opt/EdgeGateway/venv` β€” no system Python contamination. All dependencies (Flask, SocketIO, python-telegram-bot, psutil, gunicorn, eventlet) are isolated. +2. **Python venv isolation**: Dashboard and bot run in `/opt/WarpGate/venv` β€” no system Python contamination. All dependencies (Flask, SocketIO, python-telegram-bot, psutil, gunicorn, eventlet) are isolated. -3. **Config.env pattern**: All configuration centralized in `/etc/EdgeGateway/config.env` β€” single source of truth, sourced by both systemd units and scripts. No scattered config files. +3. **Config.env pattern**: All configuration centralized in `/etc/WarpGate/config.env` β€” single source of truth, sourced by both systemd units and scripts. No scattered config files. 4. **WARP watchdog**: Cron-based self-healing β€” if the tunnel drops, it reconnects automatically within 60 seconds. This is critical for a gateway that must stay online. @@ -173,7 +173,7 @@ Evidence: ## Repository Structure ``` -EdgeGateway/ +WarpGate/ β”œβ”€β”€ 01_install.sh # Step 1: System + WARP + AP + firewall install β”œβ”€β”€ 02_configure.sh # Step 2: Dashboard + Telegram bot + systemd units β”œβ”€β”€ templates/ @@ -205,12 +205,12 @@ EdgeGateway/ ## Notes -- **Repo rename**: The project was originally named `pi-router` (evidenced by the initial commit `b176ed4` which included a `pi-router/` subdirectory with duplicate files). It was renamed to `EdgeGateway` on June 17, 2026 across three commits. The `pi-router/` directory was subsequently removed. +- **Repo rename**: The project was originally named `pi-router` (evidenced by the initial commit `b176ed4` which included a `pi-router/` subdirectory with duplicate files). It was renamed to `WarpGate` on June 17, 2026 across three commits. The `pi-router/` directory was subsequently removed. - **No git tags**: CHANGELOG.md declares v1.0.0 but no corresponding git tag exists. This is a minor release-process gap. - **No `docs/` directory**: All documentation lives in the README. No separate docs folder exists. - **No test files**: No test suite exists β€” deployment is the only validation path. The ROADMAP.md lists "Test coverage expansion" as a current goal. - **Dependabot ecosystem**: Correctly configured for `github-actions` only β€” no ecosystem mismatch (the repo has no `package.json` or `Dockerfile`). -- **Security audit history**: Two security-focused commits in the git log β€” `10839ba` ("Fix: full project cleanup and security hardening") and `6401607` ("audit(EdgeGateway): sanitize email references"). This is a positive maturity signal. +- **Security audit history**: Two security-focused commits in the git log β€” `10839ba` ("Fix: full project cleanup and security hardening") and `6401607` ("audit(WarpGate): sanitize email references"). This is a positive maturity signal. - **Default credentials**: Default AP password (`SuperSecret99`) is a placeholder β€” must be changed before production use. The script explicitly comments "← Change this!". - **Single-point-of-failure**: The Raspberry Pi itself is the gateway β€” if it goes down, all AP clients lose internet. No HA/failover mechanism. - **WARP dependency**: The system's privacy guarantees depend entirely on Cloudflare WARP availability. The fallback (raw WAN) provides no privacy. diff --git a/README.md b/README.md index 93900a1..bd07202 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@
-

🌐 EdgeGateway

+

🌐 WarpGate

Raspberry Pi Cloudflare WARP Gateway

Secure tunneling, DNS privacy, and outbound proxy for edge devices β€” one-command setup

@@ -44,8 +44,8 @@ > ⚠️ **IMPORTANT**: Before running the installer, edit `01_install.sh` and change the default AP password (`AP_PASS="SuperSecret99"`). The default is a placeholder and MUST be changed for any production or public deployment. ```bash -git clone https://github.com/OneByJorah/EdgeGateway.git -cd EdgeGateway +git clone https://github.com/OneByJorah/WarpGate.git +cd WarpGate chmod +x 01_install.sh 02_configure.sh sudo ./01_install.sh sudo ./02_configure.sh @@ -78,7 +78,7 @@ After installation, open the status dashboard: ## πŸ“ Project Structure ``` -EdgeGateway/ +WarpGate/ β”œβ”€β”€ 01_install.sh # System setup & WARP installation β”œβ”€β”€ 02_configure.sh # WARP configuration & registration β”œβ”€β”€ templates/ # Dashboard HTML templates diff --git a/deploy_log.txt b/deploy_log.txt index 1adfd04..f4188e9 100644 --- a/deploy_log.txt +++ b/deploy_log.txt @@ -1,4 +1,4 @@ -[EdgeGateway deploy attempt] +[WarpGate deploy attempt] - Repo type: Bash provisioning + static HTML dashboard (no Python/Node/Docker runtime). - Cannot deploy on this host without root privileges and Cloudflare WARP environment. - Local preview fallback: captured `templates/dashboard.html` as static file for README reference. diff --git a/j1.yaml b/j1.yaml index 824e128..5761c2c 100644 --- a/j1.yaml +++ b/j1.yaml @@ -1,4 +1,4 @@ -repo: EdgeGateway +repo: WarpGate class: Infrastructure org: OneByJorah owner: Jhonattan L. Jimenez diff --git a/requirements.txt b/requirements.txt index 46acaf0..b567640 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,5 @@ -# EdgeGateway Python dependencies -# Install in a virtual environment: python3 -m venv /opt/EdgeGateway/venv +# WarpGate Python dependencies +# Install in a virtual environment: python3 -m venv /opt/WarpGate/venv # Then: pip install -r requirements.txt flask>=3.0,<4.0