Metadata-Version: 2.4
Name: netcurfew
Version: 0.1.9
Summary: Parental internet timer & screen-time control daemon
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.111
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.7
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: anyio[trio]>=4; extra == "dev"
Requires-Dist: bandit[toml]>=1.7; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Dynamic: license-file

# NetCurfew

A production-grade local screen-time and internet control system for parents.

NetCurfew runs a privileged background daemon that manipulates OS firewall rules.
Access is granted by the parent via an interactive menu, CLI, or local web dashboard —
from any device on the same network, including a smartphone.

---

## Architecture

```
 Menu (netcurfew-menu.bat)   CLI (netcurfew)   Web UI (browser)
           |                       |                  |
           +----------+------------+------------------+
                      | HTTP REST  (localhost:5000)
                      v
           NetCurfew Daemon  (FastAPI / runs as admin)
                      |
                      v  OS firewall commands
           Windows netsh / Linux iptables / macOS pfctl
```

**Default state: internet BLOCKED.** Access must be explicitly granted.

---

## Installation

```bash
# Requires Python 3.11+
pip install netcurfew

# Or install from source
pip install -e .
```

### Check version and updates

```bash
netcurfew --version
```

Prints the installed version and checks PyPI for a newer release automatically.

### Optional: set a parent PIN

```bash
netcurfew set-pin 123456
```

Once set, all internet access changes (start, stop, extend, allow) require the PIN.

---

## Quick Start — Interactive Menu (Recommended)

The easiest way to operate NetCurfew is the included menu script.
Double-click `netcurfew-menu.bat` or run it from a terminal:

```cmd
netcurfew-menu.bat
```

```
+------------------------------------------+
|        NetCurfew - Internet Control       |
+------------------------------------------+
|                                          |
|   SERVICE                                |
|   [1] Start Daemon                       |
|   [2] Stop  Daemon                       |
|                                          |
|   INTERNET ACCESS                        |
|   [3] Show Status                        |
|   [4] Allow 15 Minutes                   |
|   [5] Allow 30 Minutes                   |
|   [6] Allow  1 Hour                      |
|   [7] Allow  2 Hours                     |
|   [8] Unlimited  (Work Mode)             |
|   [9] Block Internet Now                 |
|                                          |
|   SETTINGS                               |
|   [P] Set Parent PIN                     |
|   [0] Exit                               |
+------------------------------------------+
```

Option `[1]` starts the daemon in the background with `--no-block-on-exit` so
closing the menu window does not cut internet. Option `[2]` finds and stops it.

---

## Running the Daemon Manually

The daemon **must run with elevated privileges**.

### Windows (Run as Administrator)

```cmd
netcurfew serve
```

For work machines where you don't want Ctrl+C to block internet:

```cmd
netcurfew serve --no-block-on-exit
```

To install as a Windows Service (using NSSM or sc.exe):

```cmd
sc create NetCurfew binPath= "C:\Python311\Scripts\netcurfew.exe serve" start= auto
sc start NetCurfew
```

### Linux (systemd)

Create `/etc/systemd/system/netcurfew.service`:

```ini
[Unit]
Description=NetCurfew Internet Control Daemon
After=network.target

[Service]
ExecStart=/usr/local/bin/netcurfew serve
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now netcurfew
```

### macOS (launchd)

```bash
sudo netcurfew serve
```

---

## CLI Usage

```bash
# View current state
netcurfew status

# Check installed version and whether an update is available
netcurfew --version

# Grant internet access — defaults to the first allowed_durations entry (15m)
netcurfew start

# Grant a specific duration
netcurfew start 30m
netcurfew start 1h
netcurfew start 2h

# Allow internet indefinitely — no timer (Work Mode)
netcurfew allow

# Block internet immediately
netcurfew stop

# Add time to the current active session
netcurfew extend 15m

# Supply PIN via flag (skips interactive prompt)
netcurfew start 30m --pin 123456
netcurfew allow --pin 123456
netcurfew stop --pin 123456

# Skip PIN prompt entirely (useful in scripts or when no PIN is configured)
netcurfew start -i
netcurfew allow -i
netcurfew stop -i
netcurfew extend 30m -i
```

If no parent PIN is configured, the PIN prompt is skipped automatically.
Use `--immediately` / `-i` to bypass the prompt when a PIN is set.

---

## Web Dashboard

Open `http://<machine-ip>:5000` in any browser on the local network.

Features:
- Live status badge: `🟢 INTERNET ACTIVE` (timed), `🟡 INTERNET UNLIMITED` (work mode), `🔴 INTERNET BLOCKED`
- MM:SS / HH:MM:SS countdown for timed sessions; `∞` for unlimited
- Quick-start buttons: +15m, +30m, +1h, +2h
- `∞ Unlimited (Work Mode)` button for uninterrupted access
- Extend (+15m, +30m) and Stop Now buttons when a session is active
- PIN modal appears automatically if a parent PIN is configured
- Mobile-responsive, no internet required (fully self-contained — no CDN dependencies)

---

## Configuration (`config.json`)

| Key | Default | Description |
|-----|---------|-------------|
| `parent_pin_hash` | `null` | Scrypt-hashed PIN (set via `netcurfew set-pin`) |
| `default_port` | `5000` | Daemon listen port |
| `allowed_durations` | `[15,30,60,120]` | Allowed session lengths (minutes) |
| `lan_only` | `true` | Bind only to localhost/LAN |

---

## Security Notes

- All firewall changes require the daemon to run as **Administrator / root**.
- The daemon binds to `127.0.0.1` by default; LAN access requires binding to a local
  network interface (handled when `lan_only: true`).
- Session timing uses `time.monotonic()` — immune to OS clock manipulation.
- Fail-safe: the daemon blocks internet on startup and shutdown by default.
- Use `--no-block-on-exit` only on trusted parent/admin machines.
