bifrost-agent 0.1.0__tar.gz

bifrost_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

bifrost_agent-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store

bifrost_agent-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: bifrost-agent
+Version: 0.1.0
+Summary: Bifrost path-tunnel agent — connect a local Mac app to Bifrost
+Project-URL: Homepage, https://github.com/eskeon/bifrost-agent
+Project-URL: Repository, https://github.com/eskeon/bifrost-agent
+Author: Bifrost
+License-Expression: MIT
+Keywords: bifrost,tunnel,websocket
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12
+Description-Content-Type: text/markdown
+
+# bifrost-agent
+
+Mac path-tunnel agent for [Bifrost](https://github.com/eskeon/go-bifrost). Connects outbound over WebSocket and exposes a local HTTP app under `/services/{slug}`.
+
+## Install
+
+```bash
+pip install bifrost-agent
+```
+
+Requires Python 3.11+.
+
+## Connect
+
+1. In Bifrost Console → **Tunnels**, create a tunnel and attach a path route (set **Local URL** there, e.g. `http://127.0.0.1:3000`).
+2. Copy the one-time install command and run:
+
+```bash
+sudo bifrost tunnel install <token>
+```
+
+The token embeds the Bifrost WebSocket URL and auth secret. Local upstream URLs are **not** passed on the CLI — they come from the console on each request.
+
+## Commands
+
+```bash
+sudo bifrost tunnel install <token>   # LaunchDaemon + system config
+bifrost tunnel run                    # foreground (uses saved config)
+bifrost tunnel run <token>            # one-shot / save user config + run
+sudo bifrost tunnel uninstall
+bifrost version
+```
+
+System config: `/Library/Application Support/bifrost/config.json`  
+Logs: `/Library/Logs/bifrost-tunnel.log`
+
+## Develop
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+bifrost version
+```
+
+## Publish
+
+Repo: https://github.com/eskeon/bifrost-agent  
+
+Tag a release (`v*`); GitHub Actions builds and publishes to PyPI as `bifrost-agent`.

bifrost_agent-0.1.0/README.md

@@ -0,0 +1,50 @@
+# bifrost-agent
+
+Mac path-tunnel agent for [Bifrost](https://github.com/eskeon/go-bifrost). Connects outbound over WebSocket and exposes a local HTTP app under `/services/{slug}`.
+
+## Install
+
+```bash
+pip install bifrost-agent
+```
+
+Requires Python 3.11+.
+
+## Connect
+
+1. In Bifrost Console → **Tunnels**, create a tunnel and attach a path route (set **Local URL** there, e.g. `http://127.0.0.1:3000`).
+2. Copy the one-time install command and run:
+
+```bash
+sudo bifrost tunnel install <token>
+```
+
+The token embeds the Bifrost WebSocket URL and auth secret. Local upstream URLs are **not** passed on the CLI — they come from the console on each request.
+
+## Commands
+
+```bash
+sudo bifrost tunnel install <token>   # LaunchDaemon + system config
+bifrost tunnel run                    # foreground (uses saved config)
+bifrost tunnel run <token>            # one-shot / save user config + run
+sudo bifrost tunnel uninstall
+bifrost version
+```
+
+System config: `/Library/Application Support/bifrost/config.json`  
+Logs: `/Library/Logs/bifrost-tunnel.log`
+
+## Develop
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+bifrost version
+```
+
+## Publish
+
+Repo: https://github.com/eskeon/bifrost-agent  
+
+Tag a release (`v*`); GitHub Actions builds and publishes to PyPI as `bifrost-agent`.

bifrost_agent-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bifrost-agent"
+version = "0.1.0"
+description = "Bifrost path-tunnel agent — connect a local Mac app to Bifrost"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Bifrost" }]
+keywords = ["bifrost", "tunnel", "websocket"]
+dependencies = [
+  "click>=8.1",
+  "httpx>=0.27",
+  "websockets>=12",
+]
+
+[project.urls]
+Homepage = "https://github.com/eskeon/bifrost-agent"
+Repository = "https://github.com/eskeon/bifrost-agent"
+
+[project.scripts]
+bifrost = "bifrost_agent.cli:main"

bifrost_agent-0.1.0/src/bifrost_agent/__init__.py

@@ -0,0 +1,3 @@
+"""Bifrost path-tunnel agent."""
+
+__version__ = "0.1.0"

bifrost_agent-0.1.0/src/bifrost_agent/__main__.py

@@ -0,0 +1,4 @@
+from bifrost_agent.cli import main
+
+if __name__ == "__main__":
+    main()

bifrost_agent-0.1.0/src/bifrost_agent/agent.py

@@ -0,0 +1,207 @@
+"""WebSocket tunnel agent — forwards Bifrost http_req frames to local_url."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+from typing import Any
+from urllib.parse import urljoin, urlparse
+
+import httpx
+import websockets
+
+from bifrost_agent import __version__
+from bifrost_agent.config import Config
+
+log = logging.getLogger("bifrost.agent")
+
+MAX_BODY = 8 << 20
+SUBPROTOCOL = "bifrost-tunnel"
+
+
+def _ws_url(url: str) -> str:
+    if url.startswith("https://"):
+        return "wss://" + url[len("https://") :]
+    if url.startswith("http://"):
+        return "ws://" + url[len("http://") :]
+    return url
+
+
+def _join_local(local_url: str, path: str, query: str) -> str:
+    base = local_url.rstrip("/") + "/"
+    rel = (path or "/").lstrip("/")
+    target = urljoin(base, rel)
+    if query:
+        sep = "&" if "?" in target else "?"
+        target = f"{target}{sep}{query}"
+    return target
+
+
+async def _forward(client: httpx.AsyncClient, msg: dict[str, Any]) -> dict[str, Any]:
+    req_id = str(msg.get("id") or "")
+    local_url = str(msg.get("local_url") or "").strip()
+    if not local_url:
+        return {
+            "type": "http_res",
+            "id": req_id,
+            "status": 502,
+            "error": "missing local_url",
+        }
+    parsed = urlparse(local_url)
+    if parsed.scheme not in ("http", "https") or not parsed.netloc:
+        return {
+            "type": "http_res",
+            "id": req_id,
+            "status": 502,
+            "error": "invalid local_url",
+        }
+
+    method = str(msg.get("method") or "GET").upper()
+    path = str(msg.get("path") or "/")
+    query = str(msg.get("query") or "")
+    headers_in = msg.get("headers") or {}
+    headers: dict[str, str] = {}
+    if isinstance(headers_in, dict):
+        for k, vals in headers_in.items():
+            if str(k).lower() in {
+                "host",
+                "content-length",
+                "connection",
+                "transfer-encoding",
+                "keep-alive",
+                "upgrade",
+            }:
+                continue
+            if isinstance(vals, list) and vals:
+                headers[str(k)] = str(vals[0])
+            elif isinstance(vals, str):
+                headers[str(k)] = vals
+
+    body = b""
+    if msg.get("body"):
+        try:
+            body = base64.b64decode(msg["body"])
+        except Exception:  # noqa: BLE001
+            return {
+                "type": "http_res",
+                "id": req_id,
+                "status": 502,
+                "error": "invalid body encoding",
+            }
+        if len(body) > MAX_BODY:
+            return {
+                "type": "http_res",
+                "id": req_id,
+                "status": 413,
+                "error": "body too large",
+            }
+
+    url = _join_local(local_url, path, query)
+    try:
+        resp = await client.request(method, url, headers=headers, content=body)
+    except Exception as exc:  # noqa: BLE001
+        return {
+            "type": "http_res",
+            "id": req_id,
+            "status": 502,
+            "error": str(exc),
+        }
+
+    out_headers: dict[str, list[str]] = {}
+    for k, v in resp.headers.multi_items():
+        if k.lower() in {"transfer-encoding", "connection", "content-encoding"}:
+            continue
+        out_headers.setdefault(k, []).append(v)
+
+    resp_body = resp.content
+    if len(resp_body) > MAX_BODY:
+        return {
+            "type": "http_res",
+            "id": req_id,
+            "status": 502,
+            "error": "response too large",
+        }
+
+    return {
+        "type": "http_res",
+        "id": req_id,
+        "status": resp.status_code,
+        "headers": out_headers,
+        "body": base64.b64encode(resp_body).decode("ascii") if resp_body else "",
+    }
+
+
+async def _session(cfg: Config) -> None:
+    url = _ws_url(cfg.url)
+    async with websockets.connect(
+        url,
+        subprotocols=[SUBPROTOCOL],
+        max_size=MAX_BODY + (1 << 20),
+        ping_interval=None,
+    ) as ws:
+        await ws.send(
+            json.dumps(
+                {
+                    "type": "hello",
+                    "token": cfg.token,
+                    "version": __version__,
+                }
+            )
+        )
+        welcome_raw = await ws.recv()
+        welcome = json.loads(welcome_raw)
+        if welcome.get("type") != "welcome":
+            raise RuntimeError(f"expected welcome, got {welcome.get('type')!r}")
+        log.info(
+            "connected tunnel_id=%s name=%r",
+            welcome.get("tunnel_id"),
+            welcome.get("name"),
+        )
+
+        async with httpx.AsyncClient(timeout=60.0, follow_redirects=False) as client:
+            async for raw in ws:
+                if isinstance(raw, bytes):
+                    raw = raw.decode("utf-8", errors="replace")
+                try:
+                    msg = json.loads(raw)
+                except json.JSONDecodeError:
+                    log.warning("bad frame")
+                    continue
+                typ = msg.get("type")
+                if typ == "ping":
+                    await ws.send(json.dumps({"type": "pong"}))
+                elif typ == "http_req":
+                    res = await _forward(client, msg)
+                    await ws.send(json.dumps(res))
+                elif typ == "error":
+                    log.error("server error: %s", msg.get("message"))
+                else:
+                    log.debug("ignore type=%s", typ)
+
+
+async def run(cfg: Config) -> None:
+    cfg.validate()
+    backoff = 1.0
+    while True:
+        try:
+            await _session(cfg)
+            backoff = 1.0
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            log.warning("disconnected: %s; reconnecting in %.0fs", exc, backoff)
+            await asyncio.sleep(backoff)
+            backoff = min(backoff * 2, 30.0)
+
+
+def run_forever(cfg: Config) -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(message)s",
+    )
+    try:
+        asyncio.run(run(cfg))
+    except KeyboardInterrupt:
+        pass

bifrost_agent-0.1.0/src/bifrost_agent/cli.py

@@ -0,0 +1,99 @@
+"""CLI: bifrost tunnel install|run|uninstall, bifrost version."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from bifrost_agent import __version__
+from bifrost_agent.agent import run_forever
+from bifrost_agent.config import Config, default_config_path, load, save, user_config_path
+from bifrost_agent.install_token import parse_install_token
+from bifrost_agent.launchd import install as launchd_install
+from bifrost_agent.launchd import uninstall as launchd_uninstall
+
+
+@click.group()
+@click.version_option(__version__, prog_name="bifrost")
+def main() -> None:
+    """Bifrost tunnel agent."""
+
+
+@main.group()
+def tunnel() -> None:
+    """Manage the path tunnel agent."""
+
+
+@tunnel.command("install")
+@click.argument("token")
+def tunnel_install(token: str) -> None:
+    """Install LaunchDaemon from a console install token (requires sudo)."""
+    try:
+        parsed = parse_install_token(token)
+        cfg = Config(url=parsed.url, token=parsed.token)
+        launchd_install(cfg)
+    except PermissionError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+    click.echo("installed LaunchDaemon com.bifrost.tunnel")
+    click.echo("config: /Library/Application Support/bifrost/config.json")
+    click.echo("logs:   /Library/Logs/bifrost-tunnel.log")
+
+
+@tunnel.command("uninstall")
+def tunnel_uninstall() -> None:
+    """Remove LaunchDaemon and system config (requires sudo)."""
+    try:
+        launchd_uninstall()
+    except PermissionError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+    click.echo("uninstalled com.bifrost.tunnel")
+
+
+@tunnel.command("run")
+@click.argument("token", required=False)
+@click.option("--config", "config_path", type=click.Path(), default=None, help="Config file path")
+def tunnel_run(token: str | None, config_path: str | None) -> None:
+    """Run the agent in the foreground."""
+    try:
+        if token:
+            parsed = parse_install_token(token)
+            cfg = Config(url=parsed.url, token=parsed.token)
+            # Convenience: persist to user config when not root.
+            if config_path:
+                from pathlib import Path
+
+                save(cfg, Path(config_path))
+            else:
+                try:
+                    save(cfg, user_config_path())
+                except OSError:
+                    pass
+        elif config_path:
+            from pathlib import Path
+
+            cfg = load(Path(config_path))
+        else:
+            cfg = load(default_config_path())
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+    run_forever(cfg)
+
+
+@main.command("version")
+def version_cmd() -> None:
+    """Print version."""
+    click.echo(__version__)
+
+
+if __name__ == "__main__":
+    main()

bifrost_agent-0.1.0/src/bifrost_agent/config.py

@@ -0,0 +1,52 @@
+"""Agent config (url + auth token only — local upstreams come from Bifrost)."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+SYSTEM_CONFIG = Path("/Library/Application Support/bifrost/config.json")
+
+
+@dataclass
+class Config:
+    url: str
+    token: str
+
+    def validate(self) -> None:
+        if not (self.url or "").strip():
+            raise ValueError("url is required")
+        if not (self.token or "").strip():
+            raise ValueError("token is required")
+
+
+def user_config_path() -> Path:
+    home = Path.home()
+    return home / "Library" / "Application Support" / "bifrost" / "config.json"
+
+
+def default_config_path() -> Path:
+    """Prefer system config when readable (LaunchDaemon), else user config."""
+    if SYSTEM_CONFIG.is_file() and os.access(SYSTEM_CONFIG, os.R_OK):
+        return SYSTEM_CONFIG
+    return user_config_path()
+
+
+def load(path: Path | None = None) -> Config:
+    p = path or default_config_path()
+    if not p.is_file():
+        raise FileNotFoundError(f"config not found: {p}")
+    data = json.loads(p.read_text(encoding="utf-8"))
+    cfg = Config(url=str(data.get("url") or ""), token=str(data.get("token") or ""))
+    cfg.validate()
+    return cfg
+
+
+def save(cfg: Config, path: Path) -> None:
+    cfg.validate()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(asdict(cfg), indent=2) + "\n", encoding="utf-8")
+    os.chmod(path, 0o600)

bifrost_agent-0.1.0/src/bifrost_agent/install_token.py

@@ -0,0 +1,43 @@
+"""Parse Cloudflare-style opaque install tokens from the Bifrost console."""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class InstallToken:
+    url: str
+    token: str
+
+
+def parse_install_token(raw: str) -> InstallToken:
+    raw = (raw or "").strip()
+    if not raw:
+        raise ValueError("install token is required")
+
+    # Allow pasting the full command by accident.
+    if raw.startswith("sudo "):
+        parts = raw.split()
+        raw = parts[-1] if parts else raw
+
+    pad = "=" * (-len(raw) % 4)
+    try:
+        data = base64.urlsafe_b64decode(raw + pad)
+    except Exception as exc:  # noqa: BLE001
+        raise ValueError("invalid install token encoding") from exc
+
+    try:
+        obj = json.loads(data.decode("utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        raise ValueError("invalid install token json") from exc
+
+    if not isinstance(obj, dict):
+        raise ValueError("invalid install token")
+    url = str(obj.get("url") or "").strip()
+    token = str(obj.get("token") or "").strip()
+    if not url or not token:
+        raise ValueError("install token missing url or token")
+    return InstallToken(url=url, token=token)

bifrost_agent-0.1.0/src/bifrost_agent/launchd.py

@@ -0,0 +1,84 @@
+"""macOS LaunchDaemon install/uninstall for the tunnel agent."""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from bifrost_agent.config import SYSTEM_CONFIG, Config, save
+
+LABEL = "com.bifrost.tunnel"
+PLIST_PATH = Path("/Library/LaunchDaemons") / f"{LABEL}.plist"
+LOG_PATH = Path("/Library/Logs/bifrost-tunnel.log")
+
+
+def _require_root() -> None:
+    if os.geteuid() != 0:
+        raise PermissionError("this command requires root (use sudo)")
+
+
+def _bifrost_bin() -> str:
+    # Prefer the invoking executable (works under `sudo bifrost …`).
+    argv0 = Path(sys.argv[0]).resolve()
+    if argv0.is_file() and os.access(argv0, os.X_OK):
+        return str(argv0)
+    found = shutil.which("bifrost")
+    if found:
+        return found
+    return sys.executable
+
+
+def install(cfg: Config) -> None:
+    _require_root()
+    save(cfg, SYSTEM_CONFIG)
+
+    bin_path = _bifrost_bin()
+    # If invoked as `python -m bifrost_agent`, run via module.
+    if Path(bin_path).name.startswith("python"):
+        program = [bin_path, "-m", "bifrost_agent", "tunnel", "run"]
+    else:
+        program = [bin_path, "tunnel", "run"]
+
+    LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    plist = {
+        "Label": LABEL,
+        "ProgramArguments": program,
+        "RunAtLoad": True,
+        "KeepAlive": True,
+        "StandardOutPath": str(LOG_PATH),
+        "StandardErrorPath": str(LOG_PATH),
+    }
+    PLIST_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with PLIST_PATH.open("wb") as f:
+        plistlib.dump(plist, f)
+    os.chmod(PLIST_PATH, 0o644)
+
+    # bootout if already loaded, then bootstrap
+    subprocess.run(
+        ["launchctl", "bootout", f"system/{LABEL}"],
+        check=False,
+        capture_output=True,
+    )
+    subprocess.run(
+        ["launchctl", "bootstrap", "system", str(PLIST_PATH)],
+        check=True,
+    )
+    subprocess.run(["launchctl", "enable", f"system/{LABEL}"], check=False)
+    subprocess.run(["launchctl", "kickstart", "-k", f"system/{LABEL}"], check=False)
+
+
+def uninstall() -> None:
+    _require_root()
+    subprocess.run(
+        ["launchctl", "bootout", f"system/{LABEL}"],
+        check=False,
+        capture_output=True,
+    )
+    if PLIST_PATH.exists():
+        PLIST_PATH.unlink()
+    if SYSTEM_CONFIG.exists():
+        SYSTEM_CONFIG.unlink()