wgusr 1.0.0__py3-none-any.whl

wgusr/__init__.py

@@ -0,0 +1,3 @@
+"""wgusr — WireGuard user management tool."""
+
+__version__ = "0.1.0"

wgusr/__main__.py

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

wgusr/activate.py

@@ -0,0 +1,162 @@
+"""Activate a WireGuard interface using wg syncconf or wg set.
+
+Requires: root, wg, wg-quick, and ip in PATH.
+
+wg set / wg syncconf only update WireGuard's cryptokey routing table.
+Kernel routes for each peer's AllowedIPs are added by wg-quick at
+`up` time, not by wg.  This module adds those routes after syncing
+so that a newly-added peer becomes immediately reachable without
+disrupting existing tunnels.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+
+def _check_wg_binary() -> None:
+    """Check that wg binary is available."""
+    if not shutil.which("wg"):
+        raise RuntimeError("'wg' binary not found in PATH; install wireguard-tools")
+
+
+def _check_ip_binary() -> None:
+    """Check that ip (iproute2) binary is available."""
+    if not shutil.which("ip"):
+        raise RuntimeError("'ip' binary not found in PATH; install iproute2")
+
+
+def _interface_exists(interface: str) -> bool:
+    """Return True when the WireGuard interface is present in the kernel."""
+    r = subprocess.run(
+        ["ip", "-br", "link", "show", "dev", interface],
+        capture_output=True,
+        text=True,
+    )
+    return r.returncode == 0
+
+
+def _add_route_for_allowed_ip(interface: str, cidr: str) -> None:
+    """Add a kernel route for one AllowedIP, idempotently.
+
+    Runs ``ip route show <cidr> dev <interface>`` first; skips the add if
+    the route is already present.  Between the check and the add another
+    process may have installed the same route — that raises "File exists", which
+    is caught and silently ignored (race lost, route is present).  Any other
+    error is propagated.
+    """
+    check = subprocess.run(
+        ["ip", "route", "show", cidr, "dev", interface],
+        capture_output=True,
+        text=True,
+    )
+    if check.stdout.strip():
+        return  # already present
+
+    try:
+        subprocess.run(
+            ["ip", "route", "add", cidr, "dev", interface],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        if exc.returncode != 0 and "File exists" in (exc.stderr or ""):
+            return  # race lost; route is present
+        raise
+
+
+def sync_interface(interface: str) -> None:
+    """Apply the full wg0.conf to the live interface via wg syncconf.
+
+    After pushing the peer/cryptokey configuration to the kernel, enumerate all
+    live peers via ``wg show <iface> allowed-ips`` and add a kernel route for
+    each AllowedIP.  This replicates what ``wg-quick up`` does at bring-up
+    time so that newly-added peers become immediately reachable without
+    tearing down existing tunnels.
+    """
+    _check_wg_binary()
+    _check_ip_binary()
+
+    if not shutil.which("wg-quick"):
+        raise RuntimeError("'wg-quick' not found in PATH; install wireguard-tools")
+
+    # 1. Strip wg-quick options and push peer config to the kernel.
+    strip = subprocess.run(
+        ["wg-quick", "strip", interface],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    subprocess.run(
+        ["wg", "syncconf", interface, "/dev/stdin"],
+        input=strip.stdout,
+        text=True,
+        check=True,
+    )
+
+    # 2. Enumerate live peers and add kernel routes for their AllowedIPs.
+    #    ``wg show <iface> allowed-ips`` emits one line per peer:
+    #    "<pubkey>\t<cidr>[,<cidr>...]"
+    show = subprocess.run(
+        ["wg", "show", interface, "allowed-ips"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    for line in show.stdout.splitlines():
+        if not line.strip():
+            continue
+        parts = line.split("\t")
+        if len(parts) < 2:
+            continue
+        for cidr in parts[1].split(","):
+            cidr = cidr.strip()
+            if cidr:
+                _add_route_for_allowed_ip(interface, cidr)
+
+
+def sync_peer(
+    interface: str,
+    pubkey: str,
+    allowed_ips: str,
+    psk: str | None = None,
+    keepalive: int | None = None,
+) -> None:
+    """Apply a single peer to the live interface via wg set.
+
+    Uses ``wg set`` to update/add a single peer without touching others.
+    After updating the cryptokey routing, adds a kernel route for each
+    AllowedIP so the peer is immediately reachable.
+
+    The interface must already exist (e.g. brought up via ``wg-quick up``);
+    raises ``RuntimeError`` if it does not.
+    """
+    _check_wg_binary()
+    _check_ip_binary()
+
+    if not _interface_exists(interface):
+        raise RuntimeError(
+            f"interface {interface!r} does not exist; "
+            f"run `wg-quick up {interface}` first to bring it up"
+        )
+
+    cmd = ["wg", "set", interface, "peer", pubkey, "allowed-ips", allowed_ips]
+
+    if psk:
+        cmd.extend(["preshared-key", "/dev/stdin"])
+
+    if keepalive is not None and keepalive > 0:
+        cmd.extend(["persistent-keepalive", str(keepalive)])
+
+    if psk:
+        subprocess.run(cmd, input=psk, text=True, check=True)
+    else:
+        subprocess.run(cmd, check=True)
+
+    # Add kernel route(s) for each comma-separated AllowedIP.
+    for cidr in allowed_ips.split(","):
+        cidr = cidr.strip()
+        if cidr:
+            _add_route_for_allowed_ip(interface, cidr)

wgusr/cli.py

@@ -0,0 +1,395 @@
+"""CLI entry point for wgusr.
+
+wgusr [--wg-dir DIR] [--interface IF] [--clients-dir DIR]
+     {add,delete,list,view,clear,init,sync} ...
+
+Pre-flight checks:
+  - Root requirement for --wg-dir under /etc/wireguard
+  - Process umask set to 0o077 before any file write
+  - wg and wg-quick availability checked before sync
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import click
+
+from wgusr import __version__
+from wgusr.config import ServerInfo
+from wgusr.keys import KeyPair, derive_public_key, generate_keypair
+from wgusr.manager import (
+    add_user,
+    clear_all,
+    delete_user,
+    list_users,
+    sync_all_users,
+    sync_user,
+    view_user,
+)
+from wgusr.sync_io import atomic_write_wgconf
+from wgusr.validators import (
+    IPV4,
+    KEEPALIVE,
+    PUBKEY,
+    USERNAME,
+    make_conf_path,
+)
+
+DEFAULT_INTERFACE = "wg0"
+DEFAULT_WG_DIR = "/etc/wireguard"
+
+
+def _make_server(wg_dir: str, interface: str, clients_dir: str | None) -> ServerInfo:
+    """Load or initialise a ServerInfo."""
+    wg_dir = os.path.realpath(wg_dir)
+    os.makedirs(wg_dir, exist_ok=True)
+
+    conf_path = make_conf_path(wg_dir, interface)
+    if not os.path.exists(conf_path):
+        click.echo(
+            f"error: {conf_path} does not exist.\n"
+            f"  Run 'wgusr init' to create a new interface, or check --wg-dir.",
+            err=True,
+        )
+        raise SystemExit(1)
+
+    server = ServerInfo.from_path(wg_dir, interface, clients_dir=clients_dir)
+    server.ensure_clients_dir()
+
+    pub = derive_public_key(server.private_key)
+    server.set_public_key(pub)
+
+    return server
+
+
+@click.group()
+@click.version_option(version=__version__)
+@click.option(
+    "--wg-dir",
+    default=DEFAULT_WG_DIR,
+    help=f"wireguard config directory (default: {DEFAULT_WG_DIR})",
+)
+@click.option(
+    "--interface", "-i",
+    default=DEFAULT_INTERFACE,
+    help=f"wireguard interface name (default: {DEFAULT_INTERFACE})",
+)
+@click.option(
+    "--clients-dir",
+    help="directory for client artifacts (default: <wg-dir>/clients)",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    wg_dir: str,
+    interface: str,
+    clients_dir: str | None,
+) -> None:
+    ctx.ensure_object(dict)
+    ctx.obj["wg_dir"] = wg_dir
+    ctx.obj["interface"] = interface
+    ctx.obj["clients_dir"] = clients_dir
+
+
+@cli.command(
+    epilog=(
+        "Examples:  "
+        "wgusr add alice vpn.example.com  |  "
+        "wgusr add bob 192.168.1.100  |  "
+        "wgusr -i wg0 add carol vpn.example.com --ip 10.0.73.50\n"
+        "\n"
+        "endpoint_host is the server's public hostname or IP."
+        " The port is automatically added from your wg0.conf ListenPort."
+    ),
+)
+@click.argument("user", type=USERNAME)
+@click.argument("endpoint_host")
+@click.option("--ip", type=IPV4, help="assign a specific VPN IP")
+@click.option("--select-ip", is_flag=True, help="interactively select IP")
+@click.option("--dns", type=IPV4, help="DNS server for client (default: server tunnel IP)")
+@click.option("--keepalive", type=KEEPALIVE, default=None, help="persistent-keepalive seconds (0=off)")
+@click.option("--no-psk", is_flag=True, help="skip preshared key (not recommended)")
+@click.option("--existing-keys", is_flag=True, help="use existing private/public key pair")
+@click.option("--private-key", "existing_private", help="private key (requires --existing-keys)")
+@click.option("--public-key", "existing_public", help="public key (requires --existing-keys)")
+@click.pass_context
+def add(
+    ctx: click.Context,
+    user: str,
+    endpoint_host: str,
+    ip: str | None,
+    select_ip: bool,
+    dns: str | None,
+    keepalive: int | None,
+    no_psk: bool,
+    existing_keys: bool,
+    existing_private: str | None,
+    existing_public: str | None,
+) -> None:
+    wg_dir = ctx.obj["wg_dir"]
+    interface = ctx.obj["interface"]
+    clients_dir = ctx.obj["clients_dir"]
+
+    os.umask(0o077)
+
+    server = _make_server(wg_dir, interface, clients_dir)
+
+    existing_kp: KeyPair | None = None
+    if existing_keys:
+        if not existing_private or not existing_public:
+            click.echo("error: --existing-keys requires --private-key and --public-key", err=True)
+            raise SystemExit(1)
+        existing_kp = KeyPair(private=existing_private, public=existing_public)
+
+    try:
+        add_user(
+            server=server,
+            user=user,
+            endpoint_host=endpoint_host,
+            vpn_ip=ip,
+            select_ip_flag=select_ip,
+            dns=dns,
+            keepalive=keepalive,
+            psk=not no_psk,
+            existing_keys=existing_kp,
+        )
+    except Exception as exc:
+        click.echo(f"error: add failed: {exc}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command()
+@click.argument("user", required=False, type=USERNAME)
+@click.option("--key", "pubkey", type=PUBKEY, help="delete by public key")
+@click.option("--force", "-f", is_flag=True, help="confirm delete when only one source matches")
+@click.pass_context
+def delete(
+    ctx: click.Context,
+    user: str | None,
+    pubkey: str | None,
+    force: bool,
+) -> None:
+    wg_dir = ctx.obj["wg_dir"]
+    interface = ctx.obj["interface"]
+    clients_dir = ctx.obj["clients_dir"]
+
+    os.umask(0o077)
+
+    server = _make_server(wg_dir, interface, clients_dir)
+
+    try:
+        delete_user(
+            server=server,
+            user=user or "",
+            pubkey=pubkey,
+            force=force,
+        )
+    except Exception as exc:
+        click.echo(f"error: delete failed: {exc}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command()
+@click.pass_context
+def list(ctx: click.Context) -> None:
+    wg_dir = ctx.obj["wg_dir"]
+    interface = ctx.obj["interface"]
+    clients_dir = ctx.obj["clients_dir"]
+
+    os.umask(0o077)
+
+    server = _make_server(wg_dir, interface, clients_dir)
+
+    try:
+        list_users(server)
+    except Exception as exc:
+        click.echo(f"error: list failed: {exc}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command()
+@click.argument("user", type=USERNAME)
+@click.pass_context
+def view(ctx: click.Context, user: str) -> None:
+    wg_dir = ctx.obj["wg_dir"]
+    interface = ctx.obj["interface"]
+    clients_dir = ctx.obj["clients_dir"]
+
+    os.umask(0o077)
+
+    server = _make_server(wg_dir, interface, clients_dir)
+
+    try:
+        view_user(server, user)
+    except FileNotFoundError as exc:
+        click.echo(f"error: {exc}", err=True)
+        raise SystemExit(1)
+    except Exception as exc:
+        click.echo(f"error: view failed: {exc}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command()
+@click.option("--yes", "-y", is_flag=True, help="skip confirmation prompt")
+@click.pass_context
+def clear(ctx: click.Context, yes: bool) -> None:
+    wg_dir = ctx.obj["wg_dir"]
+    interface = ctx.obj["interface"]
+    clients_dir = ctx.obj["clients_dir"]
+
+    os.umask(0o077)
+
+    if not yes:
+        response = click.prompt("Deleting ALL users and configuration. Are you sure? [y/N] ").strip()
+        if response.lower() not in ("y", "yes"):
+            raise SystemExit(1)
+
+    server = _make_server(wg_dir, interface, clients_dir)
+
+    try:
+        clear_all(server)
+    except Exception as exc:
+        click.echo(f"error: clear failed: {exc}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command()
+@click.pass_context
+def init(ctx: click.Context) -> None:
+    import ipaddress
+
+    import wgconfig
+
+    wg_dir = ctx.obj["wg_dir"]
+    interface = ctx.obj["interface"]
+
+    os.umask(0o077)
+
+    interface = click.prompt("Listen port", default=str(51820)).strip() or "51820"
+    try:
+        port = int(interface)
+    except ValueError:
+        click.echo("error: port must be an integer", err=True)
+        raise SystemExit(1)
+
+    endpoint = click.prompt("Server public address (e.g. vpn.example.com)").strip()
+    if not endpoint:
+        click.echo("error: server address is required", err=True)
+        raise SystemExit(1)
+
+    ip_range = click.prompt("VPN network CIDR", default="10.0.73.0/24").strip() or "10.0.73.0/24"
+    try:
+        net = ipaddress.ip_network(ip_range, strict=False)
+    except ValueError:
+        click.echo(f"error: invalid CIDR: {ip_range!r}", err=True)
+        raise SystemExit(1)
+    server_ip = str(net.network_address + 1)
+
+    use_existing = click.prompt("Use existing private/public key? [y/N]", default="n").strip().lower()
+    if use_existing == "y":
+        priv = click.prompt("Private key (base64)").strip()
+        pub = click.prompt("Public key (base64)").strip()
+    else:
+        priv_path = click.prompt("Path to existing private key file (or press Enter to generate)", default="").strip()
+        if priv_path:
+            priv = Path(priv_path).read_text().strip()
+            pub = derive_public_key(priv)
+        else:
+            kp = generate_keypair()
+            priv, pub = kp.private, kp.public
+
+    wg_dir_real = os.path.realpath(wg_dir)
+    os.makedirs(wg_dir_real, exist_ok=True)
+    conf_path = os.path.join(wg_dir_real, f"{interface}.conf")
+
+    if os.path.exists(conf_path):
+        click.echo(
+            f"error: {conf_path} already exists; refusing to overwrite",
+            err=True,
+        )
+        raise SystemExit(1)
+
+    wc = wgconfig.WGConfig(conf_path)
+    wc.initialize_file(leading_comment=f"# {interface} interface")
+    wc.add_attr(None, "Address", f"{server_ip}/24")
+    wc.add_attr(None, "ListenPort", str(port))
+    wc.add_attr(None, "PrivateKey", priv)
+    wc.add_attr(None, "SaveConfig", "true")
+    wc.add_attr(None, "PostUp", f"nft add element ip filter WG_IFACES {{ {interface} }}; nft add element ip nat WG_IFACES {{ {interface} }}")
+    wc.add_attr(None, "PostDown", f"nft delete element ip filter WG_IFACES {{ {interface} }}; nft delete element ip nat WG_IFACES {{ {interface} }}")
+
+    atomic_write_wgconf(wc, conf_path)
+
+    click.echo(f"created {conf_path}")
+    click.echo(f"server public key: {pub}")
+    click.echo(f"endpoint: {endpoint}:{port}")
+
+
+@cli.command()
+@click.argument("user", required=False, type=USERNAME)
+@click.option("--all", "sync_all", is_flag=True, help="sync all peers via wg syncconf")
+@click.pass_context
+def sync(ctx: click.Context, user: str | None, sync_all: bool) -> None:
+    """Apply a user's peer to the live interface via wg set, or --all via wg syncconf."""
+    if not user and not sync_all:
+        click.echo("error: pass a user or use --all", err=True)
+        raise SystemExit(1)
+    if user and sync_all:
+        click.echo("error: pass a user or --all, not both", err=True)
+        raise SystemExit(1)
+
+    wg_dir = ctx.obj["wg_dir"]
+    interface = ctx.obj["interface"]
+    clients_dir = ctx.obj["clients_dir"]
+
+    os.umask(0o077)
+
+    server = _make_server(wg_dir, interface, clients_dir)
+
+    try:
+        if sync_all:
+            sync_all_users(server)
+        else:
+            assert user is not None
+            sync_user(server, user)
+    except Exception as exc:
+        click.echo(f"error: sync failed: {exc}", err=True)
+        raise SystemExit(1)
+
+
+def main(argv: list[str] | None = None) -> None:
+    if argv is None:
+        argv = sys.argv[1:]
+    new_argv: list[str] = []
+    skip_next = False
+    for i, arg in enumerate(argv):
+        if skip_next:
+            skip_next = False
+            continue
+        if arg == "-v" and i + 1 < len(argv):
+            new_argv.append("view")
+            new_argv.append(argv[i + 1])
+            skip_next = True
+        else:
+            new_argv.append(arg)
+    try:
+        cli.main(new_argv, standalone_mode=False)
+    except click.exceptions.UsageError as exc:
+        if exc.ctx is not None:
+            click.echo(f"error: {str(exc)}", err=True)
+            click.echo(exc.ctx.get_help(), err=True)
+        else:
+            click.echo(f"error: {str(exc)}", err=True)
+        raise SystemExit(2)
+    except click.exceptions.Abort:
+        click.echo("aborted", err=True)
+        raise SystemExit(1)
+    except click.exceptions.Exit as exc:
+        raise SystemExit(exc.exit_code)
+
+
+if __name__ == "__main__":
+    main()