spiriconfig 0.1.0__py3-none-any.whl

spiriconfig/__init__.py

@@ -0,0 +1,15 @@
+"""SpiriConfig: plugin-based configuration and container management.
+
+The core is deliberately small. It discovers plugins, gives them a CLI to hang
+subcommands off and a web UI to render pages into, and runs commands on their
+behalf. Everything a user would actually call a feature lives in a plugin.
+
+The rule the whole project is built around: **anything the web UI can do, the
+user must be able to do without it.** Concretely, that means we drive the
+system by running the same commands a human would run -- see
+:mod:`spiriconfig.commands`.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

spiriconfig/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m spiriconfig`` as well as the ``spiriconfig`` script."""
+
+from __future__ import annotations
+
+from spiriconfig.cli import app
+
+if __name__ == "__main__":
+    app()

spiriconfig/advanced.py

@@ -0,0 +1,146 @@
+"""Advanced mode: a filter on what the web UI *shows*.
+
+Advanced mode hides clutter. It is not a permission system, and it must never be
+used as one -- a hidden button is still a reachable capability, and the CLI does
+everything regardless of what the UI is currently showing. That is deliberate:
+the CLI is the escape hatch that makes progressive enhancement true, so gating it
+would undercut the whole project. If you ever need "this person may not restart
+containers", that is authorisation, and it belongs in front of the *command*, not
+in front of the button.
+
+So: advanced mode decides what a page renders. Nothing else.
+
+Plugins use it like this::
+
+    from spiriconfig import advanced
+
+    ui.button("Up", on_click=...)          # everyone sees this
+
+    with advanced.only():
+        ui.button("Edit", on_click=...)    # only developers see this
+
+Elements inside :func:`only` are *bound* to the setting rather than conditionally
+created, so flipping the toggle shows and hides them instantly, with no page
+rebuild and no lost state in whatever the user was doing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from loguru import logger
+from nicegui import app, binding, context, ui
+from nicegui.element import Element
+
+from spiriconfig import theme
+from spiriconfig.config import settings
+from spiriconfig.preferences import preferences
+
+#: Key this setting is stored under, in whatever store `preferences()` resolves to.
+PREFERENCE_KEY = "advanced"
+
+#: Key for the per-connection state object in NiceGUI's client storage.
+_STATE_KEY = "advanced_state"
+
+
+@binding.bindable_dataclass
+class AdvancedState:
+    """The live setting for one connected client.
+
+    A bindable dataclass, so that assigning to :attr:`enabled` immediately
+    propagates to every element bound to it.
+    """
+
+    enabled: bool = False
+
+
+def state() -> AdvancedState:
+    """Return the advanced-mode state for the client being served right now.
+
+    Seeded on first access from the person's stored preference, falling back to
+    ``SPIRICONFIG_ADVANCED`` -- so a developer image can ship with advanced mode
+    on by default, and a customer image with it off, from the same code.
+
+    The live object is held per connection; the *durable* value lives in the
+    preference store, which is the thing that will become per-user.
+    """
+    client_storage = app.storage.client
+    if _STATE_KEY not in client_storage:
+        default = settings().advanced
+        try:
+            stored = preferences().get(PREFERENCE_KEY, default)
+        except Exception:  # noqa: BLE001 - a broken store must not break the page
+            logger.exception("could not read the advanced-mode preference")
+            stored = default
+        client_storage[_STATE_KEY] = AdvancedState(enabled=bool(stored))
+    return client_storage[_STATE_KEY]
+
+
+def enabled() -> bool:
+    """Whether advanced mode is on for the client being served right now."""
+    return state().enabled
+
+
+def set_enabled(value: bool) -> None:
+    """Turn advanced mode on or off, and remember the choice.
+
+    The live state updates first so the UI responds even if persistence fails --
+    a preference we could not save is a much smaller problem than a toggle that
+    appears not to work.
+    """
+    state().enabled = value
+    try:
+        preferences().set(PREFERENCE_KEY, value)
+    except Exception:  # noqa: BLE001
+        logger.exception("could not save the advanced-mode preference")
+
+
+def mark(element: Element) -> Element:
+    """Show ``element`` only in advanced mode. Returns it, so it chains.
+
+    Also makes it *look* advanced, which is the same act: an element cannot be
+    advanced-only and yet fail to say so, because this is the only way to make it
+    advanced-only in the first place.
+
+    How it says so depends on what it is. A button takes the purple as its Quasar
+    ``color`` prop -- purple lettering on a flat button, a purple face on a solid
+    one -- because Quasar's own stylesheet sets ``outline: 0`` on ``.q-btn``, and
+    a ring drawn on a button is a fight with the framework that we would be
+    re-fighting at every upgrade. Everything else gets the dashed ring.
+    """
+    element.classes(add=theme.ADVANCED_CLASS)
+    if isinstance(element, ui.button):
+        element.props(f"color={theme.ADVANCED}")
+    return element.bind_visibility_from(state(), "enabled")
+
+
+@contextmanager
+def only() -> Iterator[None]:
+    """Show everything created inside this block only in advanced mode.
+
+    Binds the elements that appear in the current slot, rather than wrapping them
+    in a container: a wrapper element would sit inside the parent's flex or grid
+    layout and quietly change how the visible siblings are arranged.
+    """
+    slot = context.slot
+    before = len(slot.children)
+    try:
+        yield
+    finally:
+        for element in slot.children[before:]:
+            mark(element)
+
+
+def toggle() -> ui.switch:
+    """A switch for advanced mode. Always visible -- it is the way back.
+
+    Purple when it is on, and grey when it is off, wearing the same colour as the
+    ring around everything it reveals: the switch is the legend for the marks.
+    """
+    switch = ui.switch(
+        "Advanced",
+        value=enabled(),
+        on_change=lambda event: set_enabled(event.value),
+    ).props(f"color={theme.ADVANCED}")
+    return switch.tooltip("Show developer features: raw commands, file editing")

spiriconfig/auth.py

@@ -0,0 +1,246 @@
+"""The optional PAM login in front of the web UI.
+
+Off unless ``SPIRICONFIG_AUTH=pam`` (see :class:`~spiriconfig.config.Settings`).
+When on, every page redirects to ``/login`` until the browser has authenticated
+against the host's PAM stack, exactly as ``login`` or ``sshd`` would.
+
+This is only a login gate -- authentication, not authorization (see
+:doc:`design </design>`). Once past it everyone shares the one process, which runs
+as whoever launched it, so every authenticated user has the same access. It answers
+"is this a person the machine trusts?", not "what may this particular person do?";
+the second question has no answer here, because per-user permissions are not part
+of the model.
+
+Why the login rule below is shaped the way it is: only root can read
+``/etc/shadow``, so only a root process can verify *another* user's password. A
+non-root process can verify *its own* user's password and no one else's (PAM's
+setuid ``unix_chkpwd`` helper is what lets it do even that). :func:`authenticate`
+enforces exactly that boundary rather than pretending to a power the kernel will
+not grant it.
+"""
+
+from __future__ import annotations
+
+import grp
+import os
+import pwd
+from dataclasses import dataclass
+
+from loguru import logger
+from nicegui import app, ui
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import RedirectResponse, Response
+
+from spiriconfig import theme
+from spiriconfig.config import Settings
+
+log = logger.bind(component="auth")
+
+
+def is_root() -> bool:
+    """Whether the process can verify any account's password, not just its own.
+
+    A function, not a module constant, so a test can mock it -- and so the answer
+    is read now rather than frozen at import.
+    """
+    return os.geteuid() == 0
+
+
+def running_user() -> str:
+    """The account this process runs as: the only login possible when not root."""
+    return pwd.getpwuid(os.geteuid()).pw_name
+
+
+@dataclass(frozen=True)
+class AuthResult:
+    """The outcome of one login attempt.
+
+    ``error`` is written for a person to read on the login page, so it names what
+    is wrong without leaking whether it was the username or the password that
+    failed the PAM check itself -- that distinction is a gift to someone guessing.
+    """
+
+    ok: bool
+    username: str | None = None
+    error: str | None = None
+
+
+def _in_group(username: str, group: str) -> bool:
+    """Whether ``username`` belongs to ``group``, by membership or primary gid.
+
+    A user's primary group does not list them in ``gr_mem``, so checking only the
+    member list would miss someone whose *primary* group is the admin one. A group
+    that does not exist is a misconfiguration, not a member: logged loudly, because
+    the visible symptom is otherwise "nobody can log in" with no reason given.
+    """
+    try:
+        entry = grp.getgrnam(group)
+    except KeyError:
+        log.error(
+            "auth group {!r} does not exist; no one can log in until it does or "
+            "SPIRICONFIG_AUTH_GROUP names a group that does",
+            group,
+        )
+        return False
+    if username in entry.gr_mem:
+        return True
+    try:
+        return pwd.getpwnam(username).pw_gid == entry.gr_gid
+    except KeyError:
+        return False
+
+
+def authenticate(username: str, password: str, config: Settings) -> AuthResult:
+    """Decide a login, applying the who-may-I-even-check rule before touching PAM.
+
+    The policy, and the only part of this module with logic worth testing on its
+    own. PAM is imported lazily and last: a box where ``auth`` is ``none`` never
+    loads libpam at all, and a box where libpam will not load fails one login with
+    a clear message instead of crashing the process at import.
+    """
+    username = username.strip()
+    if not username or not password:
+        return AuthResult(False, error="Enter a username and a password.")
+
+    if not is_root():
+        # We can only verify our own account's password, so no other name could
+        # succeed even if we tried it. Say so plainly rather than failing the PAM
+        # check for a reason the user cannot act on.
+        me = running_user()
+        if username != me:
+            return AuthResult(
+                False,
+                error=(
+                    f"SpiriConfig is running as {me!r}, and a non-root process can "
+                    f"only log in that one account. Log in as {me!r}."
+                ),
+            )
+    elif not _in_group(username, config.auth_group):
+        # Root can verify anyone, so without this gate every system account --
+        # nobody, service users -- would be an admin login.
+        return AuthResult(
+            False,
+            error=f"{username!r} is not a member of the {config.auth_group!r} group.",
+        )
+
+    try:
+        import pamela
+    except Exception as exc:  # noqa: BLE001 - libpam may be missing/unloadable
+        log.error("PAM is unavailable, cannot authenticate: {}", exc)
+        return AuthResult(False, error="PAM is unavailable on this host; cannot log in.")
+
+    try:
+        pamela.authenticate(username, password, service=config.auth_service)
+    except pamela.PAMError as exc:
+        # INFO, not WARNING: a failed login is a normal event, and the reason
+        # (bad password vs. expired account) belongs in the log, not on the page.
+        log.info("PAM rejected {!r} via service {!r}: {}", username, config.auth_service, exc)
+        return AuthResult(False, error="Incorrect username or password.")
+
+    log.info("{!r} logged in", username)
+    return AuthResult(True, username=username)
+
+
+# Routes reachable without a session. The login page has to be, or there is no
+# way to get one; NiceGUI's own traffic is handled by prefix in the middleware.
+unrestricted_page_routes = {"/login"}
+
+
+class AuthMiddleware(BaseHTTPMiddleware):
+    """Send an unauthenticated request to ``/login``, remembering where it meant to go.
+
+    Everything under ``/_nicegui`` is let through unconditionally: it is the
+    framework's own assets and websocket, and the login page itself cannot render
+    without them. Only whole-page navigations are gated -- which is all that needs
+    to be, since a page is where a person actually arrives.
+    """
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        if not app.storage.user.get("authenticated", False):
+            path = request.url.path
+            if path not in unrestricted_page_routes and not path.startswith("/_nicegui"):
+                app.storage.user["referrer_path"] = path
+                return RedirectResponse("/login")
+        return await call_next(request)
+
+
+def logout() -> None:
+    """Drop the session and return to the login page."""
+    username = app.storage.user.get("username")
+    app.storage.user.clear()
+    if username:
+        log.info("{!r} logged out", username)
+    ui.navigate.to("/login")
+
+
+def header_account() -> None:
+    """The 'you are X / log out' control for the shared header.
+
+    Renders nothing when no one is authenticated, so the header can call it
+    unconditionally: with ``auth`` off no session ever carries a username, so this
+    simply draws nothing and the header is unchanged.
+    """
+    username = app.storage.user.get("username")
+    if not username:
+        return
+    ui.space()
+    ui.label(username).classes("text-white text-sm").mark("account-user")
+    ui.button(icon="logout", on_click=logout).props(
+        "flat round dense color=white"
+    ).mark("logout").tooltip("Log out")
+
+
+def login_page(config: Settings) -> None:
+    """Register ``/login``. Called only when :attr:`~spiriconfig.config.Settings.auth` is on."""
+
+    @ui.page("/login")
+    def _login() -> None:
+        theme.apply()
+
+        # Already in? The middleware lets /login through, so a logged-in visitor
+        # would otherwise sit staring at a login form. Send them on.
+        if app.storage.user.get("authenticated", False):
+            ui.navigate.to("/")
+            return
+
+        # Not root -> only running_user() can ever succeed, so name it and lock the
+        # field. Making someone guess the one account that works would be a small
+        # cruelty the PAM rule lets us avoid.
+        fixed_user = None if is_root() else running_user()
+
+        with ui.card().classes("absolute-center w-80 gap-3"):
+            ui.label("SpiriConfig").classes("text-xl font-bold")
+            username = ui.input("Username", value=fixed_user or "").classes("w-full")
+            username.mark("username")
+            if fixed_user is not None:
+                username.props("readonly")
+            password = ui.input(
+                "Password", password=True, password_toggle_button=True
+            ).classes("w-full")
+            password.mark("password")
+
+            def _submit() -> None:
+                result = authenticate(username.value, password.value, config)
+                if result.ok:
+                    app.storage.user.update(authenticated=True, username=result.username)
+                    ui.navigate.to(app.storage.user.pop("referrer_path", "/"))
+                else:
+                    ui.notify(result.error, type="negative")
+
+            password.on("keydown.enter", _submit)
+            ui.button("Log in", on_click=_submit).classes("w-full").mark("login")
+
+
+__all__ = [
+    "AuthMiddleware",
+    "AuthResult",
+    "authenticate",
+    "header_account",
+    "is_root",
+    "login_page",
+    "logout",
+    "running_user",
+]

spiriconfig/cli.py

@@ -0,0 +1,197 @@
+"""The ``spiriconfig`` command.
+
+The root CLI owns almost nothing. It configures logging, discovers plugins, and
+mounts each plugin's Typer app as a subcommand, so ``spiriconfig docker up foo``
+is the docker plugin's own code. The only thing the core adds is ``serve``, which
+starts the web UI, and ``plugins``, which tells you what got loaded.
+"""
+
+from __future__ import annotations
+
+import getpass
+import secrets
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from spiriconfig import logging
+from spiriconfig.config import settings
+from spiriconfig.plugins import Plugin, discover
+
+app = typer.Typer(
+    name="spiriconfig",
+    help="Plugin-based configuration and container management.",
+    no_args_is_help=True,
+)
+
+
+def _mount(plugins: list[Plugin]) -> None:
+    """Mount each plugin's Typer app as ``spiriconfig <name>``."""
+    for plugin in plugins:
+        sub = plugin.cli()
+        if sub is None:
+            continue
+        app.add_typer(sub, name=plugin.name, help=plugin.description or None)
+
+
+@app.command()
+def serve() -> None:
+    """Start the web UI."""
+    from spiriconfig import web
+
+    config = settings()
+    web.serve(config)
+
+
+@app.command("plugins")
+def list_plugins() -> None:
+    """List the installed plugins."""
+    plugins = discover()
+    if not plugins:
+        typer.echo("No plugins installed.")
+        return
+    width = max(len(p.name) for p in plugins)
+    for plugin in plugins:
+        faces = []
+        if plugin.cli() is not None:
+            faces.append("cli")
+        if plugin.has_page:
+            faces.append("web")
+        typer.echo(f"{plugin.name:<{width}}  {','.join(faces):<8}  {plugin.description}")
+
+
+def _write_file(path: Path, content: str) -> None:
+    """Create parent directories and write a file, for the install's two files."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+
+
+@app.command()
+def install(
+    source: Annotated[
+        str,
+        typer.Argument(
+            help="What to install: a PyPI spec, a git+ URL, or '.' with --editable."
+        ),
+    ] = "spiriconfig",
+    compose_dir: Annotated[
+        Path | None,
+        typer.Option(help="Where the docker plugin looks for apps. [system: /srv/compose]"),
+    ] = None,
+    auth: Annotated[
+        str, typer.Option(help="Login gate: 'pam' (the default) or 'none'.")
+    ] = "pam",
+    host: Annotated[str, typer.Option(help="Address to bind.")] = "127.0.0.1",
+    port: Annotated[int, typer.Option(help="Port to bind.")] = 8080,
+    auth_group: Annotated[
+        str, typer.Option(help="Group whose members may log in, when run as root.")
+    ] = "wheel",
+    editable: Annotated[
+        bool, typer.Option("--editable", "-e", help="Install the source in editable mode.")
+    ] = False,
+    show: Annotated[
+        bool, typer.Option("--show", help="Print everything install would do, and stop."),
+    ] = False,
+) -> None:
+    """Install SpiriConfig as a systemd service on this machine.
+
+    As root it becomes a system service that runs as root -- the only install
+    where the PAM login is multi-user and the users plugin can manage accounts. As
+    a normal user it becomes a `systemctl --user` service running as you, so the
+    login only ever authenticates your own account.
+
+    `--show` prints the exact `uv tool install`, the unit file, the env file, and
+    the `systemctl` commands, so you can do the whole thing by hand instead.
+    """
+    from spiriconfig import service
+
+    scope = service.Scope.detect()
+    config = service.ServiceConfig(
+        compose_dir=compose_dir
+        or (Path("/srv/compose") if scope.system else Path.home() / "compose"),
+        storage_secret=secrets.token_urlsafe(32),
+        auth=auth,
+        auth_group=auth_group,
+        host=host,
+        port=port,
+    )
+    try:
+        service.check_exposure(config)
+    except service.ServiceError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from exc
+
+    exec_path = service.executable_path()
+    unit = service.render_unit_file(scope, exec_path)
+    env_file = service.render_env_file(config)
+
+    tool = service.install_tool_command(source, editable=editable)
+    steps = [tool, service.daemon_reload_command(scope), service.enable_command(scope)]
+    if not scope.system:
+        steps.append(service.linger_command(getpass.getuser()))
+
+    if show:
+        typer.echo(f"# {scope.name} install\n")
+        typer.echo(str(tool))
+        typer.echo(f"\n# write {scope.env_path}\n{env_file}")
+        typer.echo(f"# write {scope.unit_path}\n{unit}")
+        for step in steps[1:]:
+            typer.echo(str(step))
+        return
+
+    from spiriconfig.commands import run
+
+    run(tool, timeout=None).check()
+    _write_file(scope.env_path, env_file)
+    _write_file(scope.unit_path, unit)
+    for step in steps[1:]:
+        run(step).check()
+    typer.echo(f"Installed and started {service.SERVICE_NAME} ({scope.name} service).")
+
+
+@app.command()
+def update(
+    reinstall: Annotated[
+        bool,
+        typer.Option("--reinstall", help="Force a refetch -- needed for a git branch."),
+    ] = False,
+    show: Annotated[
+        bool, typer.Option("--show", help="Print the upgrade and restart, and stop."),
+    ] = False,
+) -> None:
+    """Update SpiriConfig in place, then restart the service.
+
+    The restart is handed to systemd to do a moment later rather than run inline,
+    because this very process is what gets restarted -- an inline restart would cut
+    the command off before it could report back.
+    """
+    from spiriconfig import service
+
+    scope = service.Scope.detect()
+    upgrade = service.upgrade_tool_command(reinstall=reinstall)
+    restart = service.restart_command(scope)
+
+    if show:
+        typer.echo(str(upgrade))
+        typer.echo(str(restart))
+        return
+
+    from spiriconfig.commands import run
+
+    run(upgrade, timeout=None).check()
+    run(restart).check()
+    typer.echo("Update applied; the service is restarting.")
+
+
+# Logging is configured, and plugins mounted, at import time: Typer needs every
+# subcommand registered before it can route `spiriconfig docker ...` or list them
+# in `--help`, and discovery logs as it goes, so the sinks have to exist first.
+# Discovery failures are logged and skipped inside discover(), so one broken
+# plugin cannot stop the CLI from starting.
+logging.configure(settings())
+_mount(discover())
+
+
+if __name__ == "__main__":
+    app()