alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/services/launchd/com.alter.runtime.plist.in

@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  alter-runtime — ~Alter Identity Runtime (launchd user agent template)
+
+  Install path: ~/Library/LaunchAgents/com.alter.runtime.plist
+
+  Placeholders substituted by alter_runtime.service_install.render_launchd_plist():
+    @ALTER_RUNTIME_BIN@       — absolute path to the `alter-runtime` entry point
+    @ALTER_RUNTIME_LOG_DIR@   — directory for stdout/stderr log files
+    @ALTER_RUNTIME_HOME@      — value of $HOME at install time
+
+  After install, load with:
+    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.alter.runtime.plist
+    launchctl kickstart -k gui/$(id -u)/com.alter.runtime
+
+  Unload with:
+    launchctl bootout gui/$(id -u)/com.alter.runtime
+-->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.alter.runtime</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>@ALTER_RUNTIME_BIN@</string>
+        <string>daemon</string>
+    </array>
+
+    <!-- Start at login and keep running; restart on crash with a 5-second throttle. -->
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+        <key>Crashed</key>
+        <true/>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>5</integer>
+
+    <!-- Tight process-creation mask so sockets / state files land at 0o600. -->
+    <key>Umask</key>
+    <integer>63</integer>
+
+    <!-- Logs land under ~/Library/Logs/alter-runtime/ so macOS Console.app picks them up. -->
+    <key>StandardOutPath</key>
+    <string>@ALTER_RUNTIME_LOG_DIR@/alter-runtime.log</string>
+    <key>StandardErrorPath</key>
+    <string>@ALTER_RUNTIME_LOG_DIR@/alter-runtime.err.log</string>
+
+    <!-- Environment -->
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>@ALTER_RUNTIME_HOME@</string>
+    </dict>
+
+    <!-- Soft process limits — mirror the systemd unit. ProcessType=Background
+         tells launchd to apply the OS X timer / IO / scheduling defaults for
+         a background daemon (less CPU + IO priority, eligible for App Nap),
+         and LowPriorityIO further drops disk-IO priority so the daemon never
+         starves a foreground IDE / build that the operator is actively using.
+
+         Pentest 2026-04-26 (MEDIUM) follow-up: ship a sandbox-exec profile
+         next to this template that constrains filesystem writes to
+         ~/Library/Application Support/alter, ~/Library/Caches/alter and
+         ~/Library/Logs/alter-runtime, denies all network listening sockets
+         except the Unix socket under Application Support, and uses
+         ``allow-with-prompt`` for outbound HTTPS to alter-api.fly.dev only.
+         Tracked at alter-runtime#sandbox-profile (TODO; out of scope for
+         this PR — the plist itself is the security floor pre-sandbox). -->
+    <key>ProcessType</key>
+    <string>Background</string>
+    <key>LowPriorityIO</key>
+    <true/>
+
+    <!-- Nice-to-have for GUI sessions: the LaunchAgent inherits the user's
+         Aqua session so the Unix socket at ~/Library/Application Support/alter
+         is writable without extra entitlements. -->
+    <key>LimitLoadToSessionType</key>
+    <array>
+        <string>Aqua</string>
+        <string>Background</string>
+    </array>
+</dict>
+</plist>

alter_runtime/services/systemd/alter-runtime.service.in

@@ -0,0 +1,74 @@
+#
+# alter-runtime — ~Alter Identity Runtime (systemd user unit template)
+#
+# Install path: ~/.config/systemd/user/alter-runtime.service
+#
+# Placeholders substituted by alter_runtime.service_install.render_systemd_unit():
+#   @ALTER_RUNTIME_BIN@   — absolute path to the `alter-runtime` entry point
+#   @ALTER_RUNTIME_HOME@  — value of $HOME at install time (for Environment=)
+#
+# After install, enable with:
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now alter-runtime.service
+#
+# Logs: journalctl --user -u alter-runtime -f
+#
+
+[Unit]
+Description=~Alter Identity Runtime — local sovereign daemon
+Documentation=https://github.com/true-alter/Alter/blob/main/packages/alter-runtime/README.md
+# We do not require network-online.target because the daemon tolerates
+# offline starts — it degrades to its local cache and retries the DO
+# connection with exponential backoff (D-RT9).
+After=default.target
+# Cap restart storms during a bad deploy. StartLimit* keys live on [Unit]
+# (not [Service]) per systemd.unit(5).
+StartLimitIntervalSec=60
+StartLimitBurst=5
+
+[Service]
+Type=exec
+ExecStart=@ALTER_RUNTIME_BIN@ daemon
+Restart=on-failure
+RestartSec=5s
+
+# Environment
+Environment=HOME=@ALTER_RUNTIME_HOME@
+# XDG_RUNTIME_DIR is set by pam_systemd on interactive logins; for headless
+# sessions we let the daemon fall back to the per-uid /tmp path via
+# alter_runtime.config.unix_socket_path().
+
+# Keep stdout/stderr on the journal so `journalctl --user -u alter-runtime`
+# gives the operator immediate visibility.
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=alter-runtime
+
+# Process hygiene — run as the invoking user (implicit for user units),
+# with a tight umask so newly created socket / state files stay 0o600.
+UMask=0077
+
+# Resource limits — the daemon holds one httpx connection + small state
+# caches. Everything else is defensive.
+LimitNOFILE=1024
+MemoryMax=256M
+TasksMax=64
+
+# Hardening (works across systemd ≥ 240, which every supported distro ships)
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=%h/.config/alter %h/.cache/alter %h/.local/state/alter %h/.local/state/alter-runtime %h/.local/share/alter-runtime %h/.local/share/org-alter %t
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectKernelLogs=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictNamespaces=true
+LockPersonality=true
+SystemCallFilter=@system-service
+SystemCallErrorNumber=EPERM
+
+[Install]
+WantedBy=default.target

alter_runtime/services/systemd/cf-access-env.conf.in

@@ -0,0 +1,29 @@
+# alter-runtime — Cloudflare Access service-token environment drop-in.
+#
+# Install path: ~/.config/systemd/user/alter-runtime.service.d/cf-access-env.conf
+#
+# Loads the host's Cloudflare Access service-token credentials from
+# ~/.config/alter/cf-access.env so the daemon's httpx clients can inject
+# CF-Access-Client-Id + CF-Access-Client-Secret headers on every request
+# to mcp.truealter.com. Without these headers CF Access intercepts at the
+# edge with a 302 redirect to the truealteraccess.com login flow and the
+# daemon's session-JWT bearer token is never seen by the origin.
+#
+# The leading "-" on the EnvironmentFile= line makes the load non-fatal
+# when the file is absent — dev hosts, CI runners, and freshly installed
+# systems without a CF Access service token configured all still start
+# the daemon cleanly. The daemon's HTTP client treats absent env-vars as
+# "no CF Access auth" and returns an empty header dict from
+# alter_runtime.http_auth.cf_access_default_headers().
+#
+# Sister doctrine: D-SUBSTRATE-UNIFIED-1 §2.3 (the CF Access fork),
+# feedback-cf-access-secrets-out-of-mcp-json (envfile is the single
+# source of truth for CF Access service-token credentials).
+#
+# Option B (substrate-mTLS, canonical) in D-SUBSTRATE-UNIFIED-1 Stream 6
+# supersedes this drop-in once the Worker route at
+# mcp.truealter.com/substrate/events/{handle}/stream lands; until then
+# this is the transitional shape.
+
+[Service]
+EnvironmentFile=-%h/.config/alter/cf-access.env

alter_runtime/sockets/__init__.py

@@ -0,0 +1,20 @@
+"""Local-transport surfaces exposed by the alter-runtime daemon.
+
+Per D-RT2, the daemon exposes identity state on three local transports in
+parallel:
+
+* **Unix socket** at ``$XDG_RUNTIME_DIR/alter.sock`` (Linux) / Application
+  Support (macOS) - used by the CC hook, shell scripts, and arbitrary
+  language-agnostic callers. Line-delimited JSON-RPC.
+* **D-Bus** on the session bus (Linux only, optional dependency on
+  ``dbus-next``) - used by GNOME / KDE / Waybar modules and any desktop
+  tooling that speaks D-Bus natively.
+* **HTTP/SSE loopback** (Wave 3) - not yet implemented.
+
+Each transport is a :class:`alter_runtime.daemon.Component` that registers
+with the supervisor and shares the single-instance :class:`EventBus`.
+"""
+
+from alter_runtime.sockets.unix import UnixSocketServer
+
+__all__ = ["UnixSocketServer"]

alter_runtime/sockets/dbus.py

@@ -0,0 +1,272 @@
+"""DBusService - ``org.alter.Identity1`` on the session bus (Linux only).
+
+Exposes the daemon's identity event stream on the Linux session D-Bus under
+the bus name ``org.alter.Identity1`` and object path ``/org/alter/Identity``.
+This is the surface that Waybar / GNOME Shell / KDE Plasmoids consume.
+
+Interface
+---------
+
+::
+
+    <interface name="org.alter.Identity1">
+        <method name="Whoami">
+            <arg name="handle" type="s" direction="out"/>
+            <arg name="consent_tier" type="i" direction="out"/>
+        </method>
+        <method name="Ingest">
+            <arg name="kind" type="s" direction="in"/>
+            <arg name="payload_json" type="s" direction="in"/>
+            <arg name="accepted" type="b" direction="out"/>
+        </method>
+        <signal name="IdentityEvent">
+            <arg name="event_json" type="s"/>
+        </signal>
+    </interface>
+
+``IdentityEvent`` is emitted for every ``identity.event`` bus publish. The
+``event_json`` argument is the JSON-encoded event payload - consumers on the
+desktop side typically JSON-decode it and render a minimal subset
+(attunement, handle, kind) into a status-bar widget.
+
+Optional dependency
+-------------------
+
+The service is gated on ``dbus-next`` (installed via
+``alter-runtime[dbus]``). If the import fails (module missing, or running on
+a non-Linux platform) the component logs a warning and sleeps on the
+shutdown event - the daemon continues to run with its other surfaces.
+
+Tests skip this component unless ``dbus-next`` is importable *and* a session
+bus is available. CI on non-Linux platforms or on headless Linux runners
+without ``dbus-daemon`` will hit the fallback no-op path.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sys
+from typing import TYPE_CHECKING, Any
+
+from alter_runtime.config import DaemonConfig
+from alter_runtime.daemon import Component
+from alter_runtime.sockets.unix import INGEST_KIND_WHITELIST
+from alter_runtime.subscribers.bus import EventBus
+
+if TYPE_CHECKING:
+    from alter_runtime.config import Session
+
+__all__ = ["DBusService", "INGEST_KIND_WHITELIST", "is_dbus_available"]
+
+logger = logging.getLogger("alter_runtime.sockets.dbus")
+
+BUS_NAME: str = "org.alter.Identity1"
+OBJECT_PATH: str = "/org/alter/Identity"
+INTERFACE_NAME: str = "org.alter.Identity1"
+
+#: Egress topic - mirrors :mod:`alter_runtime.sockets.unix`.
+EGRESS_TOPIC: str = "local.signal"
+
+
+def is_dbus_available() -> bool:
+    """Return True if ``dbus-next`` can be imported on this platform.
+
+    We do the import here rather than at module top so that ``sockets/dbus.py``
+    is importable on every platform - the component class has to exist even
+    if the optional dependency isn't installed, so the daemon can log a
+    helpful warning and continue.
+    """
+    if not sys.platform.startswith("linux"):
+        return False
+    try:
+        import dbus_next  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+class DBusService(Component):
+    """Exports identity events on the Linux session D-Bus.
+
+    When the optional ``dbus-next`` dependency is unavailable the component's
+    :meth:`run` logs a single warning and blocks on shutdown, so callers can
+    register it unconditionally without breaking non-Linux installs.
+
+    Parameters
+    ----------
+    config:
+        Loaded :class:`DaemonConfig`.
+    bus:
+        Shared :class:`EventBus` - subscribes to ``identity.event`` to emit
+        ``IdentityEvent`` signals, and publishes to ``local.signal`` for
+        Ingest() callers.
+    session:
+        Authenticated alter-cli :class:`Session` - used for the ``Whoami``
+        method. Optional; Whoami returns empty strings when absent.
+    bus_name, object_path, interface_name:
+        Test hooks for overriding the D-Bus identifiers. Production code
+        should leave these at their defaults.
+    """
+
+    name = "dbus"
+
+    def __init__(
+        self,
+        config: DaemonConfig,
+        bus: EventBus,
+        session: Session | None = None,
+        *,
+        bus_name: str = BUS_NAME,
+        object_path: str = OBJECT_PATH,
+        interface_name: str = INTERFACE_NAME,
+    ) -> None:
+        self._config = config
+        self._bus = bus
+        self._session = session
+        self._bus_name = bus_name
+        self._object_path = object_path
+        self._interface_name = interface_name
+        self._stop_event = asyncio.Event()
+        self._message_bus: Any = None
+        self._interface: Any = None
+        self._bus_handler: Any = None
+
+    async def run(self) -> None:
+        """Start the D-Bus service, or fall back to a quiet no-op."""
+        if not is_dbus_available():
+            logger.warning(
+                "dbus unavailable (install `alter-runtime[dbus]` for the Linux desktop "
+                "surface) - continuing without D-Bus export"
+            )
+            await self._stop_event.wait()
+            return
+
+        try:
+            await self._start_dbus()
+        except Exception as exc:
+            logger.warning(
+                "dbus failed to start (%s: %s) - continuing without D-Bus export",
+                type(exc).__name__,
+                exc,
+            )
+            await self._stop_event.wait()
+            return
+
+        logger.info(
+            "dbus exported bus=%s path=%s interface=%s",
+            self._bus_name,
+            self._object_path,
+            self._interface_name,
+        )
+
+        try:
+            await self._stop_event.wait()
+        finally:
+            await self._teardown_dbus()
+
+    async def stop(self) -> None:
+        """Cooperative shutdown."""
+        self._stop_event.set()
+
+    # ------------------------------------------------------------------
+    # D-Bus lifecycle (only reached when dbus_next is importable)
+    # ------------------------------------------------------------------
+
+    async def _start_dbus(self) -> None:
+        """Connect to the session bus, publish the interface, subscribe to events."""
+        # Local imports guarded by is_dbus_available(). Kept inside the
+        # function so that test collection on non-Linux machines doesn't
+        # choke when the optional dep is missing.
+        from dbus_next.aio import MessageBus  # type: ignore[import-not-found]
+        from dbus_next.service import (  # type: ignore[import-not-found]
+            ServiceInterface,
+            method,
+            signal,
+        )
+
+        session = self._session
+        egress_bus = self._bus
+        loop = asyncio.get_running_loop()
+
+        class _AlterIdentityInterface(ServiceInterface):
+            """Concrete implementation of the ``org.alter.Identity1`` interface."""
+
+            def __init__(self, interface_name: str) -> None:
+                super().__init__(interface_name)
+
+            @method()
+            def Whoami(self) -> tuple[str, int]:  # type: ignore[override]
+                if session is None:
+                    return ("", 0)
+                return (session.handle, int(session.consent_tier))
+
+            @method()
+            def Ingest(self, kind: s, payload_json: s) -> b:  # type: ignore[override,valid-type]  # noqa: F821
+                try:
+                    payload = json.loads(payload_json) if payload_json else {}
+                except ValueError:
+                    return False
+                if not isinstance(payload, dict):
+                    return False
+                # Pentest 2026-04-26 (HIGH): mirror the unix-socket
+                # ``INGEST_KIND_WHITELIST`` gate - without it any session-
+                # bus peer could publish arbitrary ``kind`` values onto the
+                # in-process bus, including kinds reserved for trusted
+                # internal subscribers (``git_commit``, ``ebpf_exec`` etc.)
+                # which downstream consumers would treat as authentic.
+                if kind not in INGEST_KIND_WHITELIST:
+                    logger.warning(
+                        "dbus rejecting ingest kind=%r (not in whitelist)",
+                        kind,
+                    )
+                    return False
+                # Publish from the loop thread - D-Bus calls happen on the
+                # same asyncio loop in dbus-next's aio backend. We deliberately
+                # fire-and-forget the publish task; the bus guarantees its own
+                # in-memory ordering and nothing here awaits the result.
+                loop.create_task(  # noqa: RUF006
+                    egress_bus.publish(
+                        EGRESS_TOPIC,
+                        {"kind": kind, "payload": payload, "source": "dbus"},
+                    )
+                )
+                return True
+
+            @signal()
+            def IdentityEvent(self, event_json: s) -> s:  # type: ignore[override,valid-type]  # noqa: F821
+                return event_json
+
+        self._message_bus = await MessageBus().connect()
+        self._interface = _AlterIdentityInterface(self._interface_name)
+        self._message_bus.export(self._object_path, self._interface)
+        await self._message_bus.request_name(self._bus_name)
+
+        async def _on_identity_event(payload: dict[str, Any]) -> None:
+            if self._interface is None:
+                return
+            try:
+                body = json.dumps(payload, separators=(",", ":"))
+            except (TypeError, ValueError):
+                logger.debug("dbus skipping non-JSON-serialisable event")
+                return
+            try:
+                self._interface.IdentityEvent(body)
+            except Exception as exc:  # pragma: no cover
+                logger.warning("dbus signal emit failed: %s", exc)
+
+        self._bus_handler = _on_identity_event
+        self._bus.subscribe("identity.event", _on_identity_event)
+
+    async def _teardown_dbus(self) -> None:
+        if self._bus_handler is not None:
+            self._bus.unsubscribe("identity.event", self._bus_handler)
+            self._bus_handler = None
+        if self._message_bus is not None:
+            try:
+                self._message_bus.disconnect()
+            except Exception:  # pragma: no cover
+                pass
+            self._message_bus = None
+        self._interface = None