lockin-blocker 1.0.0__tar.gz

lockin_blocker-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest -v

lockin_blocker-1.0.0/.gitignore

@@ -0,0 +1,32 @@
+# Byte-compiled
+__pycache__/
+*.py[cod]
+
+# Virtual environment
+.venv/
+venv/
+
+# Build artifacts
+dist/
+*.egg-info/
+build/
+
+# Test / coverage
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+
+# Project state (local, per-user)
+state.json
+
+# uv
+uv.lock

lockin_blocker-1.0.0/AGENTS.md

@@ -0,0 +1,45 @@
+# AGENTS.md — lockin
+
+> For AI coding agents working on this project.
+
+## Setup
+
+```bash
+uv sync --extra dev
+uv run lockin --help
+```
+
+## Rules
+
+1. **TDD always.** Write the test first, watch it fail, then implement.
+2. **Conventional commits:** `feat(scope):`, `fix(scope):`, `test(scope):`, `refactor(scope):`, `chore:`.
+3. **Don't break the host.** Never run `nft delete table` or `sudo tee /etc/hosts` without explicit approval.
+4. **Verify before claiming done.** Run `uv run ruff check . && uv run pytest` after every task.
+
+## Commands
+
+```bash
+uv run ruff check .          # lint
+uv run ruff check --fix .    # auto-fix
+uv run pytest                # all tests
+uv run pytest -v -k "name"   # specific test
+uv run lockin --help         # CLI help
+```
+
+## Architecture
+
+lockin uses `/etc/hosts` + nftables for system-level domain blocking. No proxy, no certs, no browser extensions.
+
+| Module | Responsibility |
+|--------|---------------|
+| `lockin/cli.py` | Click commands, arg parsing, output formatting |
+| `lockin/block.py` | Orchestration: start/stop/status via /etc/hosts + nftables |
+| `lockin/hosts.py` | /etc/hosts manager — adds/removes blocked domain entries |
+| `lockin/nat.py` | nftables/iptables QUIC sinkhole (UDP 443 drop) |
+| `lockin/scheduler.py` | systemd/at/cron/thread unblock scheduling |
+
+## Dependencies
+
+- `click` — CLI framework
+- `pyyaml` — rules file parsing
+- `ruff`, `pytest` — dev only

lockin_blocker-1.0.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0 — 2026-05-24
+
+Initial release.

lockin_blocker-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Madhusudan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lockin_blocker-1.0.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: lockin-blocker
+Version: 1.0.0
+Summary: Block distracting websites on Linux — system-level blocking via /etc/hosts and nftables
+Project-URL: Homepage, https://github.com/madhusudan-kulkarni/lockin
+Project-URL: Repository, https://github.com/madhusudan-kulkarni/lockin
+Project-URL: Issues, https://github.com/madhusudan-kulkarni/lockin/issues
+Author-email: Madhusudan Kulkarni <hello@madhusudan.dev>
+License: MIT
+License-File: LICENSE
+Keywords: cli,focus,linux,nftables,productivity,self-control,website-blocker
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lockin
+
+[![CI](https://github.com/madhusudan-kulkarni/lockin/actions/workflows/ci.yml/badge.svg)](https://github.com/madhusudan-kulkarni/lockin/actions)
+
+Block distracting websites at the system level. No proxy, no certs, no extensions.
+
+lockin writes blocked domains to `/etc/hosts` and blocks QUIC/HTTP3 via nftables. Every app on your system is affected — browsers, terminals, email clients — until the timer expires.
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/madhusudan-kulkarni/lockin/main/install.sh | bash
+```
+
+Or with uv:
+
+```bash
+uv tool install git+https://github.com/madhusudan-kulkarni/lockin.git
+```
+
+Requires Python ≥3.11, uv, and nftables (or iptables). lockin uses `sudo` for firewall rules and `/etc/hosts` writes.
+
+## Usage
+
+```bash
+# Block social media for 2 hours
+lockin start --rule social --for 2h
+
+# Only allow coding sites
+lockin start --rule coding --for 1h30m
+
+# Block until 5 PM
+lockin start --rule social --until 17:00
+
+# Check remaining time
+lockin status
+
+# End early
+lockin stop
+```
+
+| Command | Purpose |
+|---------|---------|
+| `lockin start --rule <name> --for 30m` | Start a block |
+| `lockin start --rule <name> --until 17:00` | Block until a specific time |
+| `lockin stop` | End the current block |
+| `lockin status` | Show active block and time remaining |
+| `lockin list` | List all rules |
+| `lockin cleanup` | Remove leftover entries from crashes |
+| `lockin doctor` | Check installation health |
+
+Durations: `30m`, `2h`, `1h30m`. Times: `17:00`, `9:30pm`.
+
+## How it works
+
+`lockin start --rule social --for 2h` does three things:
+
+1. **Adds domains to `/etc/hosts`** — blocked domains resolve to `127.0.0.2` and `::1`. All apps see the block.
+2. **Blocks QUIC/HTTP3** via nftables — rejects UDP 443 so browsers fall back to TCP, where the hosts file takes effect.
+3. **Schedules cleanup** via systemd timer (falls back to at → cron → in-process). When time's up, hosts entries are removed and nftables rules are flushed.
+
+Blocked sites show **connection refused**. This is intentional — no cert warnings, no browser errors, nothing to maintain.
+
+## Rules
+
+Rules live in `~/.config/lockin/rules.yaml`. A default file is copied there on first run.
+
+```bash
+$EDITOR ~/.config/lockin/rules.yaml
+```
+
+```yaml
+whitelists:
+  coding:
+    - github.com
+    - stackoverflow.com
+    - docs.python.org
+
+blacklists:
+  social:
+    - twitter.com
+    - facebook.com
+    - reddit.com
+    - youtube.com
+```
+
+Whitelist mode blocks everything except the listed domains. Blacklist mode allows everything except the listed domains.
+
+## Troubleshooting
+
+**Sites still blocked after `lockin stop`** — run `lockin cleanup`. The background timer may have failed without a TTY for sudo. `lockin status` auto-detects and cleans stale entries.
+
+**QUIC bypassing the block** — restart your browser after starting a block. The nftables REJECT rule forces TCP fallback, but browsers cache QUIC capability.
+
+**Permission denied** — your user needs sudo access for nftables and `/etc/hosts`.
+
+## Uninstall
+
+```bash
+lockin cleanup
+uv tool uninstall lockin
+```
+
+## License
+
+MIT

lockin_blocker-1.0.0/README.md

@@ -0,0 +1,106 @@
+# lockin
+
+[![CI](https://github.com/madhusudan-kulkarni/lockin/actions/workflows/ci.yml/badge.svg)](https://github.com/madhusudan-kulkarni/lockin/actions)
+
+Block distracting websites at the system level. No proxy, no certs, no extensions.
+
+lockin writes blocked domains to `/etc/hosts` and blocks QUIC/HTTP3 via nftables. Every app on your system is affected — browsers, terminals, email clients — until the timer expires.
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/madhusudan-kulkarni/lockin/main/install.sh | bash
+```
+
+Or with uv:
+
+```bash
+uv tool install git+https://github.com/madhusudan-kulkarni/lockin.git
+```
+
+Requires Python ≥3.11, uv, and nftables (or iptables). lockin uses `sudo` for firewall rules and `/etc/hosts` writes.
+
+## Usage
+
+```bash
+# Block social media for 2 hours
+lockin start --rule social --for 2h
+
+# Only allow coding sites
+lockin start --rule coding --for 1h30m
+
+# Block until 5 PM
+lockin start --rule social --until 17:00
+
+# Check remaining time
+lockin status
+
+# End early
+lockin stop
+```
+
+| Command | Purpose |
+|---------|---------|
+| `lockin start --rule <name> --for 30m` | Start a block |
+| `lockin start --rule <name> --until 17:00` | Block until a specific time |
+| `lockin stop` | End the current block |
+| `lockin status` | Show active block and time remaining |
+| `lockin list` | List all rules |
+| `lockin cleanup` | Remove leftover entries from crashes |
+| `lockin doctor` | Check installation health |
+
+Durations: `30m`, `2h`, `1h30m`. Times: `17:00`, `9:30pm`.
+
+## How it works
+
+`lockin start --rule social --for 2h` does three things:
+
+1. **Adds domains to `/etc/hosts`** — blocked domains resolve to `127.0.0.2` and `::1`. All apps see the block.
+2. **Blocks QUIC/HTTP3** via nftables — rejects UDP 443 so browsers fall back to TCP, where the hosts file takes effect.
+3. **Schedules cleanup** via systemd timer (falls back to at → cron → in-process). When time's up, hosts entries are removed and nftables rules are flushed.
+
+Blocked sites show **connection refused**. This is intentional — no cert warnings, no browser errors, nothing to maintain.
+
+## Rules
+
+Rules live in `~/.config/lockin/rules.yaml`. A default file is copied there on first run.
+
+```bash
+$EDITOR ~/.config/lockin/rules.yaml
+```
+
+```yaml
+whitelists:
+  coding:
+    - github.com
+    - stackoverflow.com
+    - docs.python.org
+
+blacklists:
+  social:
+    - twitter.com
+    - facebook.com
+    - reddit.com
+    - youtube.com
+```
+
+Whitelist mode blocks everything except the listed domains. Blacklist mode allows everything except the listed domains.
+
+## Troubleshooting
+
+**Sites still blocked after `lockin stop`** — run `lockin cleanup`. The background timer may have failed without a TTY for sudo. `lockin status` auto-detects and cleans stale entries.
+
+**QUIC bypassing the block** — restart your browser after starting a block. The nftables REJECT rule forces TCP fallback, but browsers cache QUIC capability.
+
+**Permission denied** — your user needs sudo access for nftables and `/etc/hosts`.
+
+## Uninstall
+
+```bash
+lockin cleanup
+uv tool uninstall lockin
+```
+
+## License
+
+MIT

lockin_blocker-1.0.0/install.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+bold()  { echo -e "\033[1m$1\033[0m"; }
+green() { echo -e "\033[32m$1\033[0m"; }
+red()   { echo -e "\033[31m$1\033[0m"; }
+
+need() {
+  if ! command -v "$1" &>/dev/null; then
+    red "Missing: $1 — $2"
+    exit 1
+  fi
+}
+
+need python3  "python >= 3.11"
+need uv       "curl -LsSf https://astral.sh/uv/install.sh | sh"
+need nft      "sudo dnf install nftables   # Fedora\n  sudo apt install nftables    # Debian/Ubuntu"
+echo ""
+
+bold "Installing lockin..."
+uv tool install --force git+https://github.com/madhusudan-kulkarni/lockin.git
+
+green "✓ lockin installed."
+echo ""
+bold "Quick start:"
+echo "  lockin list"
+echo "  lockin start --rule coding --for 2h"
+echo "  lockin start --rule social --until 17:00"
+echo "  \$EDITOR ~/.config/lockin/rules.yaml   # customize"

lockin_blocker-1.0.0/lockin/__init__.py

@@ -0,0 +1,3 @@
+"""lockin — Block distracting websites so you can focus."""
+
+__version__ = "1.0.0"

lockin_blocker-1.0.0/lockin/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m lockin."""
+
+from lockin.cli import main
+
+if __name__ == "__main__":
+    main()

lockin_blocker-1.0.0/lockin/block.py

@@ -0,0 +1,276 @@
+"""Core orchestration: start/stop/status of blocking sessions.
+
+lockin v2 uses /etc/hosts for domain blocking (replaces mitmproxy).
+No proxy, no certs, no MITM. System-level blocking that catches all
+applications, not just browsers.
+"""
+
+import contextlib
+import datetime
+import json
+import re
+import shutil
+from pathlib import Path
+
+import yaml
+
+from lockin import nat, scheduler
+from lockin.hosts import add_entries, get_entries, remove_entries
+
+STATE_DIR = Path.home() / ".config" / "lockin"
+STATE_FILE = STATE_DIR / "state.json"
+DEFAULT_RULES_PATH = Path(__file__).parent / "data" / "rules.yaml"
+USER_RULES_PATH = STATE_DIR / "rules.yaml"
+
+
+def parse_duration(duration_str: str) -> int:
+    """Parse a human duration string into total minutes.
+
+    Examples: "30m" → 30, "2h" → 120, "1h30m" → 90.
+    """
+    pattern = r"^(?:(\d+)h)?(?:(\d+)m)?$"
+    match = re.match(pattern, duration_str)
+    if not match or (not match.group(1) and not match.group(2)):
+        raise ValueError(
+            f"Invalid duration: '{duration_str}'. "
+            "Use format like '30m', '2h', or '1h30m'."
+        )
+    hours = int(match.group(1) or 0)
+    minutes = int(match.group(2) or 0)
+    total = hours * 60 + minutes
+    if total <= 0:
+        raise ValueError(f"Duration must be positive: '{duration_str}'.")
+    return total
+
+
+def load_rules(path: Path) -> dict:
+    """Load rules from a YAML file."""
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    if data is None:
+        return {"whitelists": {}, "blacklists": {}}
+    return data
+
+
+def get_rules_path() -> Path:
+    """Get the rules file path, preferring user config over default."""
+    if USER_RULES_PATH.exists():
+        return USER_RULES_PATH
+    if DEFAULT_RULES_PATH.exists():
+        return DEFAULT_RULES_PATH
+    raise FileNotFoundError("No rules file found.")
+
+
+def ensure_user_rules() -> Path:
+    """Copy default rules to user config if not present."""
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    if not USER_RULES_PATH.exists() and DEFAULT_RULES_PATH.exists():
+        USER_RULES_PATH.write_text(DEFAULT_RULES_PATH.read_text())
+    return get_rules_path()
+
+
+def find_rule(rule_name: str, rules: dict) -> tuple[str, str, list[str]]:
+    """Find a rule by name. Returns (name, block_type, addresses).
+
+    Raises ValueError if rule not found.
+    """
+    for section, block_type in [
+        ("whitelists", "whitelist"),
+        ("blacklists", "blacklist"),
+    ]:
+        section_rules = rules.get(section, {})
+        if rule_name in section_rules:
+            return rule_name, block_type, section_rules[rule_name]
+    available = []
+    for section in ("whitelists", "blacklists"):
+        available.extend(rules.get(section, {}).keys())
+    raise ValueError(
+        f"Rule '{rule_name}' not found. "
+        f"Available: {', '.join(sorted(available)) or 'none'}"
+    )
+
+
+def list_rules(rules_path: Path) -> list[tuple[str, str, int]]:
+    """Return all rules as (name, block_type, address_count) tuples."""
+    rules = load_rules(rules_path)
+    result = []
+    for section, block_type in [
+        ("whitelists", "whitelist"),
+        ("blacklists", "blacklist"),
+    ]:
+        for name, addresses in rules.get(section, {}).items():
+            result.append((name, block_type, len(addresses)))
+    return sorted(result)
+
+
+def get_state(path: Path | None = None) -> dict | None:
+    """Read the current block state, or None if no block is active."""
+    if path is None:
+        path = STATE_FILE
+    if not path.exists():
+        return None
+    with open(path) as f:
+        return json.load(f)
+
+
+def save_state(state: dict, path: Path | None = None) -> None:
+    """Write block state to disk."""
+    if path is None:
+        path = STATE_FILE
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(state, f, indent=2)
+
+
+def clear_state(path: Path | None = None) -> None:
+    """Remove the state file."""
+    if path is None:
+        path = STATE_FILE
+    path.unlink(missing_ok=True)
+
+
+def is_block_active(state: dict | None) -> bool:
+    """Check if a saved block is still in effect."""
+    if state is None:
+        return False
+    end = datetime.datetime.fromisoformat(state["end"])
+    return datetime.datetime.now() < end
+
+
+def start_block(
+    rule_name: str,
+    duration_minutes: int | None = None,
+    until_time: str | None = None,
+) -> dict:
+    """Start a new block. Returns the state dict.
+
+    Raises:
+        ValueError: rule not found or invalid duration
+        RuntimeError: block already active
+    """
+    # Check for existing block
+    existing = get_state()
+    if is_block_active(existing):
+        assert existing is not None
+        end = datetime.datetime.fromisoformat(existing["end"])
+        raise RuntimeError(
+            f"Block '{existing['rule_name']}' already active "
+            f"until {end.strftime('%H:%M')}."
+        )
+
+    # Clean up stale state from a crash
+    if existing:
+        _cleanup_stale(existing)
+
+    # Compute block time
+    now = datetime.datetime.now().replace(second=0, microsecond=0)
+    if until_time:
+        end = datetime.datetime.strptime(until_time, "%H:%M").replace(
+            year=now.year, month=now.month, day=now.day
+        )
+        if end <= now:
+            end += datetime.timedelta(days=1)
+    else:
+        assert duration_minutes is not None
+        end = now + datetime.timedelta(minutes=duration_minutes)
+
+    # Load and find rule
+    rules_path = get_rules_path()
+    rules = load_rules(rules_path)
+    name, block_type, addresses = find_rule(rule_name, rules)
+
+    # 1. Write /etc/hosts entries (blocks at DNS level, all apps)
+    add_entries(addresses, name)
+
+    # 2. Drop QUIC/UDP 443 (prevents HTTP3 bypass)
+    nat.setup()
+
+    # 3. Schedule automatic cleanup — use absolute path so the
+    #    systemd timer can find lockin when running as root.
+    lockin_bin = shutil.which("lockin")
+    if not lockin_bin:
+        lockin_bin = str(Path.home() / ".local" / "bin" / "lockin")
+    reset_cmd = f"{lockin_bin} reset"
+    method, job_id = scheduler.schedule(end, reset_cmd)
+
+    # 4. Save state
+    state = {
+        "rule_name": name,
+        "block_type": block_type,
+        "domains": addresses,
+        "start": now.isoformat(),
+        "end": end.isoformat(),
+        "schedule_method": method,
+        "schedule_id": job_id,
+    }
+    save_state(state)
+    return state
+
+
+def stop_block() -> dict | None:
+    """Stop the active block. Returns the cleared state or None."""
+    state = get_state()
+    if state is None:
+        return None
+
+    _cleanup_stale(state)
+    clear_state()
+    return state
+
+
+def _cleanup_stale(state: dict) -> None:
+    """Clean up all resources from a block — each step independent
+    so a failure in one doesn't prevent the others from running."""
+    with contextlib.suppress(Exception):
+        remove_entries()
+    with contextlib.suppress(Exception):
+        nat.reset()
+    with contextlib.suppress(Exception):
+        scheduler.cancel(
+            state.get("schedule_method", ""),
+            state.get("schedule_id", ""),
+        )
+
+
+def get_status() -> str:
+    """Get a human-readable status of the current block."""
+    state = get_state()
+    if state is None or not is_block_active(state):
+        if state is not None:
+            _cleanup_stale(state)
+            clear_state()
+        # Auto-cleanup: if scheduler failed to clean hosts, do it now
+        if get_entries():
+            remove_entries()
+            nat.reset()
+        return "No active block."
+
+    end = datetime.datetime.fromisoformat(state["end"])
+    remaining = end - datetime.datetime.now()
+    if remaining.total_seconds() < 0:
+        remaining = datetime.timedelta(0)
+
+    hours, remainder = divmod(int(remaining.total_seconds()), 3600)
+    minutes = remainder // 60
+    time_str = f"{hours}h {minutes}m" if hours else f"{minutes}m"
+
+    # Verify /etc/hosts entries and nftables
+    hosts_entries = get_entries()
+    hosts_status = (
+        "active" if hosts_entries else "MISSING"
+    )
+    nat_status = "active"  # We can't easily check nftables without sudo
+
+    lines = [
+        f"Rule:      {state['rule_name']} ({state['block_type']})",
+        f"Remaining: {time_str}",
+        f"Ends at:   {end.strftime('%H:%M:%S')}",
+        f"Hosts:     {hosts_status} ({len(hosts_entries)} domains)",
+        f"Firewall:  {nat_status} (QUIC blocked)",
+    ]
+    if hosts_status == "MISSING":
+        lines.append("")
+        lines.append(
+            "Hosts entries are missing. Run 'lockin stop' to clean up."
+        )
+    return "\n".join(lines)