push-to-outpost 0.1.0__tar.gz

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

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set version from release tag
+        run: |
+          VERSION="${{ github.ref_name }}"
+          VERSION="${VERSION#v}"
+          sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+          echo "Set version to $VERSION"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

push_to_outpost-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+local-agent/.env
+__pycache__/
+node_modules/
+.wrangler/
+.dev.vars
+.cf.env
+.venv/
+worker-configuration.d.ts
+web/*.js
+dist/

push_to_outpost-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: push-to-outpost
+Version: 0.1.0
+Summary: Push local tmux session snapshots to the outpost web viewer
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42

push_to_outpost-0.1.0/README.md

@@ -0,0 +1,119 @@
+# outpost
+
+Read-only web viewer for your local tmux sessions and pushed docs. No inbound
+connections to your machine — a local Python CLI pushes snapshots and docs
+out over HTTPS, and a Cloudflare Worker (with static assets, backed by D1)
+reads them back. The site itself is gated by Cloudflare Access (your login),
+so there's no app-level login code. Push API keys are minted and revoked
+from the website itself.
+
+## How it fits together
+
+```
+tmux sessions --(capture-pane)--> outpost CLI --(HTTPS POST, outbound)--> /api/push (key-gated, checked against D1)
+                                                                                     |
+                                                                               Cloudflare D1
+                                                                                     |
+                                    /api/sessions, /api/keys (worker/index.ts) <-- gated by Cloudflare Access
+                                                                                     |
+                                                web/ (static assets, served by the Worker)
+```
+
+## Setup
+
+1. **Log in to Cloudflare**: `npx wrangler login`, or set `CLOUDFLARE_API_TOKEN`
+   in `.cf.env` (gitignored) if the browser OAuth flow doesn't work for your
+   setup (e.g. WSL2 localhost-forwarding issues).
+2. **Create the D1 database**: `npm run db:create`. Copy the `database_id`
+   it prints into `wrangler.toml` (replacing the placeholder).
+2b. **Enable R2** (Dashboard → R2 — one-time acceptance, needed before the
+    bucket create call will work) and create the docs bucket:
+    `npx wrangler r2 bucket create outpost-docs`. Used for zip doc content
+    (`push-doc bundle.zip`) — markdown/html docs stay in D1.
+3. **Apply the schema locally and remotely**:
+   ```
+   npm run db:migrate
+   npm run db:migrate:remote
+   ```
+4. **Deploy**: `npm run deploy`. First run creates the Worker and gives you a
+   `*.workers.dev` URL.
+5. **Gate the site with Cloudflare Access** (Zero Trust → Access →
+   Applications — if Zero Trust won't enable itself from the dashboard, that
+   was a real bug for us and needed a support ticket):
+   - Application for `outpost.<subdomain>.workers.dev`, path `/*`,
+     policy: allow your own email only.
+   - A **second** application scoped to path `/api/push` with a **Bypass**
+     policy — Access matches the most specific path, so this keeps the push
+     endpoint open (it's key-gated instead, since the local agent can't do
+     an interactive login). `outpost push-doc` reuses this same endpoint
+     (as `op: "push-doc"`), so no separate Access application is needed for it.
+   - Make sure at least one identity provider (e.g. "One-time PIN") exists
+     under Settings → Authentication, or login will fail with "no login
+     methods available".
+6. **Install the CLI and log in**:
+   ```
+   uv sync
+   uv run outpost login
+   ```
+   This opens the site in your browser — sign in, click **API keys**, generate
+   one, and paste the secret back into the terminal prompt (input hidden). No
+   OAuth/localhost-callback flow involved, just copy-paste, so it works even
+   where browser-to-WSL localhost forwarding doesn't. The key is verified
+   against the server before being saved.
+7. **Run it**:
+   ```
+   uv run outpost push   # one-off push
+   uv run outpost run    # loop forever, pushing every 15s
+   ```
+   Keep `outpost run` running (its own tmux session, or a systemd/launchd
+   service).
+
+   Alongside tmux panes, each cycle also scans `~/.claude/projects/*/*.jsonl`
+   for Claude Code session transcripts modified in the last hour (`SESSION_MAX_AGE_MINUTES`,
+   default 60) and pushes any that changed as markdown docs — full
+   conversation history straight from Claude Code's own transcript, not a
+   scrape of whatever the terminal happened to redraw. This catches every
+   active session on the machine, not just ones visible in a tracked tmux
+   pane. Docs are keyed by session id, so re-pushes update in place, and (like
+   all docs) they expire 24h after the last push if the session goes idle
+   past `SESSION_MAX_AGE_MINUTES`.
+8. **Push a doc** (optional): separately from tmux panes, you can push a
+   markdown, HTML, or zip file to render on its own in the site:
+   ```
+   uv run outpost push-doc notes.md
+   uv run outpost push-doc report.html --title "Weekly report"
+   uv run outpost push-doc bundle.zip
+   ```
+   It shows up under **Docs** in the sidebar, and expires automatically 24h
+   after its last push (same expiry applies to tmux pane snapshots — re-push
+   to keep something alive). Markdown/HTML render inside a
+   sandboxed `<iframe>` (no `allow-same-origin`, so injected content can't
+   reach the page's localStorage or the cached decryption key even if a
+   pushed doc turns out to be hostile); zip files are decrypted locally and
+   browsable file-by-file (parsed client-side, not extracted server-side —
+   the server only ever sees the encrypted blob, stored in R2), with a
+   whole-archive download always available too. Re-running `push-doc` on the
+   same file (same slugified filename, or `--id`) updates the existing doc
+   rather than creating a new one.
+   Note: the window actually running `outpost run` is automatically
+   excluded from what it pushes — it recognizes its own startup banner in
+   its own scrollback, so its noisy per-cycle log output never counts as a
+   "changed" window. No configuration needed.
+
+## Notes
+
+- **Requires [wincred](https://github.com/vivainio/wincred)** (`wincred.exe`
+  on `PATH`) — this CLI only supports WSL2 + Windows Credential Manager for
+  storing config. There's no env-file fallback: `outpost login` writes
+  `TOWER_URL` and `PUSH_SECRET` as one JSON credential under
+  `outpost:config`, and `push`/`run` read it back from there. `PUSH_INTERVAL`
+  / `CAPTURE_LINES` can still be set as plain env vars if you want to override
+  the defaults (15s / 2000 lines).
+- API keys are stored in D1 as SHA-256 hashes only; the plaintext secret is
+  shown once at creation and never persisted. Revoke a key anytime from the
+  **API keys** panel on the site.
+- The frontend has no login code — Cloudflare Access rejects unauthenticated
+  requests before they reach any Pages Function.
+- If a Cloudflare-fronted request gets a mysterious `403` with body
+  `error code: 1010`, that's bot protection blocking the client's User-Agent
+  — the CLI already sets a custom one (`outpost-agent/1.0`).

push_to_outpost-0.1.0/outpost/__main__.py

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

push_to_outpost-0.1.0/outpost/agent.py

@@ -0,0 +1,191 @@
+import base64
+import hashlib
+import json
+import subprocess
+import urllib.error
+import urllib.request
+from typing import TypedDict
+
+from outpost import crypto
+from outpost.config import Config
+
+
+class WindowInfo(TypedDict):
+    session_name: str
+    window_index: int
+    window_name: str
+    window_active: bool
+    session_attached: bool
+
+
+def list_windows() -> list[WindowInfo]:
+    result = subprocess.run(
+        ["tmux", "list-windows", "-a", "-F",
+         "#{session_name}\t#{window_index}\t#{window_name}\t#{window_active}\t#{session_attached}"],
+        capture_output=True, text=True, timeout=5,
+    )
+    if result.returncode != 0:
+        return []
+    windows: list[WindowInfo] = []
+    for line in result.stdout.strip().splitlines():
+        session_name, window_index, window_name, window_active, session_attached = line.split("\t")
+        windows.append({
+            "session_name": session_name,
+            "window_index": int(window_index),
+            "window_name": window_name,
+            "window_active": window_active == "1",
+            "session_attached": session_attached == "1",
+        })
+    return windows
+
+
+def capture(session_name: str, window_index: int, lines: int) -> str:
+    target = f"{session_name}:{window_index}"
+    result = subprocess.run(
+        ["tmux", "capture-pane", "-e", "-p", "-t", target, "-S", f"-{lines}"],
+        capture_output=True, text=True, timeout=5,
+    )
+    return result.stdout if result.returncode == 0 else ""
+
+
+def _row_hash(window_name: str, window_active: bool, session_attached: bool, content: str) -> str:
+    return hashlib.sha256(f"{window_name}\t{window_active}\t{session_attached}\t{content}".encode()).hexdigest()
+
+
+# Tracks the last-pushed hash per pane so `run`'s loop can skip panes whose
+# content hasn't changed since the previous cycle. Only meaningful within a
+# single long-running process — each `push` invocation starts fresh.
+_last_hashes: dict[str, str] = {}
+
+
+def push_once(config: Config) -> int:
+    if not config.encryption_key:
+        raise SystemExit(
+            "No encryption password set. Run `outpost set-password` before pushing "
+            "(pane content must be encrypted before it leaves this machine)."
+        )
+
+    windows = list_windows()
+
+    # `outpost run` prints this exact banner once at startup, so any pane
+    # currently running it (i.e. still showing the banner in its scrollback
+    # window) can be recognized from its own captured content — no manual
+    # tagging needed to keep a push agent's own noisy log out of the tower.
+    self_signature = f"pushing to {config.tower_url} every "
+
+    key = base64.b64decode(config.encryption_key)
+
+    live = []
+    current_hashes: dict[str, str] = {}
+    changes = []
+    for w in windows:
+        pane_id = f"{w['session_name']}:{w['window_index']}"
+        content = capture(w["session_name"], w["window_index"], config.capture_lines)
+        if self_signature in content:
+            continue
+        live.append(pane_id)
+        # Hash the plaintext so change detection isn't defeated by encryption's
+        # random per-push IV producing a different ciphertext each time.
+        row_hash = _row_hash(w["window_name"], w["window_active"], w["session_attached"], content)
+        current_hashes[pane_id] = row_hash
+        if _last_hashes.get(pane_id) != row_hash:
+            changes.append({
+                "pane_id": pane_id,
+                "session_name": w["session_name"],
+                "window_index": w["window_index"],
+                "window_name": w["window_name"],
+                "window_active": w["window_active"],
+                "session_attached": w["session_attached"],
+                "content": crypto.encrypt(content, key),
+                "encrypted": True,
+            })
+
+    if not changes and set(current_hashes) == set(_last_hashes):
+        return 0  # nothing changed, nothing closed — skip the network call
+
+    req = urllib.request.Request(
+        f"{config.tower_url}/api/push",
+        data=json.dumps({"op": "push-tmux", "live": live, "changes": changes}).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {config.push_secret}",
+            "Content-Type": "application/json",
+            "User-Agent": "outpost-agent/1.0",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=10) as resp:
+        resp.read()
+
+    _last_hashes.clear()
+    _last_hashes.update(current_hashes)
+    return len(changes)
+
+
+def verify_key(tower_url: str, push_secret: str) -> bool:
+    req = urllib.request.Request(
+        f"{tower_url.rstrip('/')}/api/push",
+        data=json.dumps({"op": "push-tmux", "live": [], "changes": []}).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {push_secret}",
+            "Content-Type": "application/json",
+            "User-Agent": "outpost-agent/1.0",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return resp.status == 200
+    except urllib.error.HTTPError:
+        return False
+
+
+def push_doc(config: Config, doc_id: str, title: str, doc_format: str, content: str) -> None:
+    # Rides /api/push with op="push-doc" (rather than a separate endpoint)
+    # so doc pushes reuse the same Cloudflare Access Bypass policy as pane
+    # pushes (op="push-tmux").
+    if not config.encryption_key:
+        raise SystemExit(
+            "No encryption password set. Run `outpost set-password` before pushing "
+            "(doc content must be encrypted before it leaves this machine)."
+        )
+
+    key = base64.b64decode(config.encryption_key)
+    body = {
+        "op": "push-doc",
+        "doc_id": doc_id,
+        "title": title,
+        "format": doc_format,
+        "content": crypto.encrypt(content, key),
+        "encrypted": True,
+    }
+    req = urllib.request.Request(
+        f"{config.tower_url}/api/push",
+        data=json.dumps(body).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {config.push_secret}",
+            "Content-Type": "application/json",
+            "User-Agent": "outpost-agent/1.0",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=10) as resp:
+        resp.read()
+
+
+def fetch_encryption_salt(tower_url: str, push_secret: str) -> tuple[str, int]:
+    # Rides /api/push with op="get-salt" (rather than GET /api/encryption-salt)
+    # so this reaches the server through the same key-gated Access Bypass as
+    # every other agent call, instead of needing its own Access exemption.
+    req = urllib.request.Request(
+        f"{tower_url.rstrip('/')}/api/push",
+        data=json.dumps({"op": "get-salt"}).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {push_secret}",
+            "Content-Type": "application/json",
+            "User-Agent": "outpost-agent/1.0",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=10) as resp:
+        data = json.loads(resp.read())
+    return data["salt"], data["kdf_iterations"]

push_to_outpost-0.1.0/outpost/cli.py

@@ -0,0 +1,165 @@
+import argparse
+import base64
+import re
+import sys
+import time
+import urllib.error
+import webbrowser
+from pathlib import Path
+
+from outpost.agent import fetch_encryption_salt, push_doc, push_once, verify_key
+from outpost.config import Config, save_credentials
+from outpost.crypto import derive_key
+from outpost.sessions import push_sessions
+
+DEFAULT_TOWER_URL = "https://outpost.vivainio.workers.dev"
+
+FORMAT_BY_SUFFIX = {
+    ".md": "markdown",
+    ".markdown": "markdown",
+    ".html": "html",
+    ".htm": "html",
+    ".zip": "zip",
+}
+
+
+def _slugify(text: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9]+", "-", text).strip("-").lower()
+    return slug or "doc"
+
+
+def cmd_login(args: argparse.Namespace) -> None:
+    tower_url = args.tower_url.rstrip("/")
+    print(f"Opening {tower_url} — sign in, click \"API keys\", then generate one.")
+    webbrowser.open(tower_url)
+    while True:
+        secret = input("Paste the API key here: ").strip()
+        if not secret:
+            print("No key entered, try again (ctrl-c to abort).")
+            continue
+        if not re.fullmatch(r"[0-9a-fA-F]+", secret):
+            print("That doesn't look like a valid key (unexpected characters) — check your paste and try again.")
+            continue
+        print("Verifying key...")
+        try:
+            valid = verify_key(tower_url, secret)
+        except (urllib.error.URLError, OSError) as exc:
+            print(f"Couldn't reach the server ({exc}) — try again.")
+            continue
+        if not valid:
+            print("That key was rejected by the server. Check it and try again.")
+            continue
+        break
+    location = save_credentials(tower_url, secret)
+    print(f"Saved to {location}. You can now run: outpost run")
+
+
+def cmd_set_password(args: argparse.Namespace) -> None:
+    config = Config.from_env()
+    print("Fetching encryption salt...")
+    try:
+        salt, iterations = fetch_encryption_salt(config.tower_url, config.push_secret)
+    except (urllib.error.URLError, OSError) as exc:
+        raise SystemExit(f"Couldn't reach the server ({exc}). Try again.")
+
+    while True:
+        password = input("Password (same one you'll enter on the website): ").strip()
+        if password:
+            break
+        print("No password entered, try again (ctrl-c to abort).")
+
+    key = derive_key(password, salt, iterations)
+    encryption_key = base64.b64encode(key).decode()
+    location = save_credentials(config.tower_url, config.push_secret, encryption_key=encryption_key)
+    print(f"Saved to {location}. Pane content will now be encrypted before it's pushed.")
+
+
+def cmd_push(args: argparse.Namespace) -> None:
+    config = Config.from_env()
+    count = push_once(config)
+    session_count = push_sessions(config)
+    print(f"pushed {count} window(s) and {session_count} session(s) to {config.tower_url}")
+
+
+def cmd_push_doc(args: argparse.Namespace) -> None:
+    path = Path(args.path)
+    if not path.is_file():
+        raise SystemExit(f"No such file: {path}")
+
+    doc_format = args.format or FORMAT_BY_SUFFIX.get(path.suffix.lower())
+    if not doc_format:
+        raise SystemExit(
+            f"Can't infer format from {path.suffix!r} — pass --format {{markdown,html,zip}} explicitly."
+        )
+
+    title = args.title or path.name
+    doc_id = args.id or _slugify(path.stem)
+
+    if doc_format == "zip":
+        content = base64.b64encode(path.read_bytes()).decode()
+    else:
+        content = path.read_text(encoding="utf-8")
+
+    config = Config.from_env()
+    push_doc(config, doc_id, title, doc_format, content)
+    print(f"pushed doc {doc_id!r} ({doc_format}) to {config.tower_url}")
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+    config = Config.from_env()
+    print(f"pushing to {config.tower_url} every {config.push_interval}s (ctrl-c to stop)")
+    while True:
+        start = time.monotonic()
+        try:
+            count = push_once(config)
+            session_count = push_sessions(config)
+            if count or session_count:
+                print(f"pushed {count} changed window(s), {session_count} changed session(s)")
+            else:
+                print("no changes, skipped")
+        except urllib.error.URLError as exc:
+            print(f"push failed: {exc}", file=sys.stderr)
+        elapsed = time.monotonic() - start
+        time.sleep(max(0.0, config.push_interval - elapsed))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="outpost", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    login_parser = sub.add_parser(
+        "login", help="Open the site, generate an API key, and save it via wincred"
+    )
+    login_parser.add_argument("--tower-url", default=DEFAULT_TOWER_URL, help="Site URL")
+    login_parser.set_defaults(func=cmd_login)
+
+    set_password_parser = sub.add_parser(
+        "set-password", help="Set the shared encryption password (enter the same one on the website)"
+    )
+    set_password_parser.set_defaults(func=cmd_set_password)
+
+    push_parser = sub.add_parser("push", help="Push a single snapshot and exit")
+    push_parser.set_defaults(func=cmd_push)
+
+    run_parser = sub.add_parser("run", help="Push snapshots on a loop until stopped")
+    run_parser.set_defaults(func=cmd_run)
+
+    push_doc_parser = sub.add_parser(
+        "push-doc", help="Push a markdown/html/zip file, rendered separately from tmux sessions"
+    )
+    push_doc_parser.add_argument("path", help="Path to a .md, .html, or .zip file")
+    push_doc_parser.add_argument("--title", help="Display title (default: filename)")
+    push_doc_parser.add_argument(
+        "--format", choices=["markdown", "html", "zip"], help="Override format inferred from the file extension"
+    )
+    push_doc_parser.add_argument(
+        "--id", help="Stable doc id to upsert on re-push (default: slugified filename)"
+    )
+    push_doc_parser.set_defaults(func=cmd_push_doc)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

push_to_outpost-0.1.0/outpost/config.py

@@ -0,0 +1,84 @@
+import json
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+WINCRED_TARGET = "outpost:config"
+
+
+def _wincred_available() -> bool:
+    return shutil.which("wincred.exe") is not None
+
+
+def _wincred_get(target: str) -> str | None:
+    result = subprocess.run(
+        ["wincred.exe", "get", target], capture_output=True, text=True, stdin=subprocess.DEVNULL
+    )
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip()
+
+
+def _wincred_set(target: str, secret: str) -> None:
+    subprocess.run(["wincred.exe", "set", target], input=secret, text=True, check=True)
+
+
+def _require_wincred() -> None:
+    if not _wincred_available():
+        raise SystemExit(
+            "outpost requires wincred.exe on PATH (WSL2 + Windows Credential "
+            "Manager — see https://github.com/vivainio/wincred)."
+        )
+
+
+def save_credentials(tower_url: str, push_secret: str, encryption_key: str | None = None) -> str:
+    _require_wincred()
+    payload = {"tower_url": tower_url, "push_secret": push_secret}
+    if encryption_key is None:
+        # Preserve an existing encryption key across e.g. a re-login,
+        # unless the caller explicitly wants to set/clear one.
+        existing = _load_credentials()
+        if existing and existing.get("encryption_key"):
+            encryption_key = existing["encryption_key"]
+    if encryption_key:
+        payload["encryption_key"] = encryption_key
+    _wincred_set(WINCRED_TARGET, json.dumps(payload))
+    return f"Windows Credential Manager ({WINCRED_TARGET})"
+
+
+def _load_credentials() -> dict[str, str] | None:
+    if not _wincred_available():
+        return None
+    raw = _wincred_get(WINCRED_TARGET)
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+
+
+@dataclass
+class Config:
+    tower_url: str
+    push_secret: str
+    push_interval: float
+    capture_lines: int
+    session_max_age: float
+    encryption_key: str | None = None
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        _require_wincred()
+        creds = _load_credentials()
+        if not creds:
+            raise SystemExit("No credentials found. Run `outpost login` first.")
+        return cls(
+            tower_url=creds["tower_url"].rstrip("/"),
+            push_secret=creds["push_secret"],
+            push_interval=float(os.environ.get("PUSH_INTERVAL", "15")),
+            capture_lines=int(os.environ.get("CAPTURE_LINES", "2000")),
+            session_max_age=float(os.environ.get("SESSION_MAX_AGE_MINUTES", "60")) * 60,
+            encryption_key=creds.get("encryption_key"),
+        )

push_to_outpost-0.1.0/outpost/crypto.py

@@ -0,0 +1,19 @@
+import base64
+import hashlib
+import os
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+KEY_LENGTH = 32  # AES-256
+IV_LENGTH = 12  # standard GCM nonce size
+
+
+def derive_key(password: str, salt_hex: str, iterations: int) -> bytes:
+    salt = bytes.fromhex(salt_hex)
+    return hashlib.pbkdf2_hmac("sha256", password.encode(), salt, iterations, dklen=KEY_LENGTH)
+
+
+def encrypt(content: str, key: bytes) -> str:
+    iv = os.urandom(IV_LENGTH)
+    ciphertext = AESGCM(key).encrypt(iv, content.encode(), None)
+    return f"{base64.b64encode(iv).decode()}:{base64.b64encode(ciphertext).decode()}"