relay-shell 0.1.0__py3-none-any.whl

relay_shell/__init__.py

@@ -0,0 +1,7 @@
+"""relay_shell - a reliable, capable MCP server for shell and SSH operations."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

relay_shell/__main__.py

@@ -0,0 +1,230 @@
+"""Entrypoint: ``relay_shell`` / ``python -m relay_shell``.
+
+Transport and all behaviour come from ``RELAY_SHELL_*`` environment variables (see
+``.env.example``). Logging goes to **stderr** only: the stdio transport owns
+stdout/stdin for JSON-RPC, so a stray stdout write would corrupt the stream.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from pathlib import Path
+
+from .config import get_settings
+from .server import Relay, build_server
+from .verifier import Status, verify_deploy
+
+
+def _configure_logging() -> None:
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+    stderr = logging.StreamHandler(sys.stderr)
+    stderr.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
+    root.addHandler(stderr)
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="relay-shell",
+        description=(
+            "MCP server for governed shell and SSH operations. Behaviour is "
+            "configured via RELAY_SHELL_* environment variables; see "
+            ".env.example for the full surface."
+        ),
+    )
+    parser.add_argument(
+        "--check-config",
+        action="store_true",
+        help=(
+            "Load settings, construct the server (audit sink, policy, "
+            "inventory, OAuth if enabled) WITHOUT starting a transport, "
+            "and exit 0 if everything initialized cleanly. Exits 2 on "
+            "invalid configuration or a degraded audit sink. Intended "
+            "for CI pipelines that bake an image."
+        ),
+    )
+    parser.add_argument(
+        "--verify-deploy",
+        action="store_true",
+        help=(
+            "Compare each shipped deploy template (systemd unit + "
+            "drop-in, logrotate, Caddyfile) against the file the "
+            "installer is expected to have laid down on this host. "
+            "Exits 0 if every entry matches, 2 if any DRIFT / MISSING / "
+            "ABSENT_TEMPLATE is found. Intended for production drift "
+            "detection and image-bake validation."
+        ),
+    )
+    parser.add_argument(
+        "--templates-dir",
+        type=Path,
+        default=None,
+        help=(
+            "Override the shipped-templates lookup. Default: the wheel's "
+            "packaged copy, falling back to deploy/ next to this file."
+        ),
+    )
+    parser.add_argument(
+        "--install-prefix",
+        type=Path,
+        default=None,
+        help=(
+            "Treat this directory as a chroot-style root: each absolute "
+            "install path is rebased under it. Used by tests and "
+            "image-bake validation."
+        ),
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_out",
+        help=("Emit machine-readable output for --verify-deploy (ignored for other subcommands)."),
+    )
+    return parser
+
+
+def _check_config() -> int:
+    """Validate config + build the server without starting a transport.
+
+    Returns 0 on success, 2 on any initialization failure or a degraded
+    audit sink. All output goes to stderr so the stdio transport's
+    contract is preserved even when this is called from a parent process
+    that pipes our streams.
+    """
+    try:
+        settings = get_settings()
+    except Exception as exc:  # noqa: BLE001
+        print(f"relay_shell: invalid configuration: {exc}", file=sys.stderr)
+        return 2
+    try:
+        # build_server registers every tool and (for http+auth) constructs
+        # the OAuth provider. Both validate the side-effecting parts of the
+        # config (audit path open, ssh_config parse, OAuth state dir).
+        build_server(settings)
+        # build_server holds the Relay internally; instantiate one alongside
+        # so we can inspect the audit sink's degraded flag. The instantiation
+        # is cheap and benign (audit file is opened append-only).
+        relay = Relay(settings)
+    except Exception as exc:  # noqa: BLE001
+        print(f"relay_shell: build_server failed: {exc}", file=sys.stderr)
+        return 2
+
+    if relay.audit.degraded:
+        print(
+            f"relay_shell: audit sink degraded ({relay.audit.degraded_reason}); "
+            f"refuse this configuration for production deployment.",
+            file=sys.stderr,
+        )
+        return 2
+
+    print(
+        f"relay_shell: config OK "
+        f"(transport={settings.transport}, "
+        f"policy={settings.policy_mode}, "
+        f"audit={settings.audit_path})",
+        file=sys.stderr,
+    )
+    return 0
+
+
+def _verify_deploy(
+    templates_dir: Path | None,
+    install_prefix: Path | None,
+    json_out: bool,
+) -> int:
+    """Run drift detection and print a report.
+
+    Returns 0 if every finding is OK, 2 otherwise. Errors never escape as
+    tracebacks: ``verify_deploy()`` itself folds template-resolution failures
+    into structured ``ABSENT_TEMPLATE`` findings.
+    """
+    report = verify_deploy(templates_dir=templates_dir, install_prefix=install_prefix)
+
+    if json_out:
+        payload = {
+            "ok": report.ok,
+            "findings": [
+                {
+                    "name": f.name,
+                    "template": f.template,
+                    "install_path": f.install_path,
+                    "status": f.status.value,
+                    "detail": f.detail,
+                }
+                for f in report.findings
+            ],
+        }
+        print(json.dumps(payload, indent=2))
+    else:
+        # Column widths chosen so the longest name + status + path stays
+        # under 100 cols for typical install paths.
+        name_w = max((len(f.name) for f in report.findings), default=0)
+        status_w = max((len(f.status.value) for f in report.findings), default=0)
+        for f in report.findings:
+            line = f"{f.name:<{name_w}}  {f.status.value:<{status_w}}  {f.install_path}"
+            if f.detail and f.status is not Status.OK:
+                line += f"  ({f.detail})"
+            print(line)
+        if report.ok:
+            print("relay-shell: verify-deploy OK", file=sys.stderr)
+        else:
+            drift = len(report.by_status(Status.DRIFT))
+            missing = len(report.by_status(Status.MISSING))
+            absent = len(report.by_status(Status.ABSENT_TEMPLATE))
+            print(
+                f"relay-shell: verify-deploy FAILED "
+                f"(drift={drift}, missing={missing}, absent_template={absent})",
+                file=sys.stderr,
+            )
+
+    return 0 if report.ok else 2
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Build and run the server. Returns a process exit code."""
+    parser = _build_arg_parser()
+    args = parser.parse_args(argv)
+
+    _configure_logging()
+
+    if args.verify_deploy:
+        return _verify_deploy(args.templates_dir, args.install_prefix, args.json_out)
+
+    if args.check_config:
+        return _check_config()
+
+    log = logging.getLogger("relay_shell")
+    try:
+        settings = get_settings()
+    except Exception as exc:  # noqa: BLE001
+        print(f"relay_shell: invalid configuration: {exc}", file=sys.stderr)
+        return 2
+
+    server = build_server(settings)
+    log.info(
+        "relay_shell starting (transport=%s, policy=%s, audit=%s)",
+        settings.transport,
+        settings.policy_mode,
+        settings.audit_path,
+    )
+    try:
+        if settings.transport == "http":
+            server.run(transport="streamable-http")
+        else:
+            server.run(transport="stdio")
+    except KeyboardInterrupt:
+        log.info("relay_shell stopped (interrupt)")
+        return 0
+    except Exception as exc:  # noqa: BLE001
+        log.error("relay_shell exited with error: %s", exc)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

relay_shell/_deploy/Caddyfile

@@ -0,0 +1,78 @@
+# Caddyfile for the relay-shell HTTP transport.
+#
+# relay-shell binds 127.0.0.1:8080 by design. Caddy terminates TLS via ACME
+# (Let's Encrypt by default, ZeroSSL fallback), restricts the source to an
+# explicit CIDR allowlist, sets security headers, and reverse proxies to the
+# loopback MCP port.
+#
+# Automated provisioning and renewal are handled by Caddy's built-in ACME
+# client; no cron, no certbot. Certificates persist under Caddy's data
+# directory (default `/var/lib/caddy/.local/share/caddy/certificates`) and
+# renew in the background well before expiry.
+#
+# This file is parameterized through environment variables so it can be
+# installed unmodified by `deploy/install-edge.sh`:
+#
+#   RELAY_SHELL_EDGE_DOMAIN        Public hostname presented in the TLS cert
+#                                  (must have a DNS A/AAAA record pointing here)
+#   RELAY_SHELL_EDGE_ACME_EMAIL    Contact email for ACME registration
+#   RELAY_SHELL_EDGE_CLIENT_CIDRS  Space-separated allowlist for tool traffic
+#                                  and /token (defaults to loopback only)
+#   RELAY_SHELL_EDGE_UPSTREAM      Loopback upstream (default 127.0.0.1:8080)
+#   RELAY_SHELL_EDGE_ACME_CA       Optional ACME directory override
+#                                  (e.g. Let's Encrypt staging for dry runs)
+#
+# To stage against the Let's Encrypt staging CA before going live, set
+# RELAY_SHELL_EDGE_ACME_CA=https://acme-staging-v02.api.letsencrypt.org/directory.
+
+{
+	email {$RELAY_SHELL_EDGE_ACME_EMAIL}
+	acme_ca {$RELAY_SHELL_EDGE_ACME_CA:https://acme-v02.api.letsencrypt.org/directory}
+}
+
+{$RELAY_SHELL_EDGE_DOMAIN} {
+	# OAuth browser/redirect + discovery must be reachable for the auth
+	# flow; they still require a registered client and PKCE.
+	handle /authorize {
+		reverse_proxy {$RELAY_SHELL_EDGE_UPSTREAM:127.0.0.1:8080} {
+			header_up Host {upstream_hostport}
+		}
+	}
+	handle /.well-known/oauth-authorization-server {
+		reverse_proxy {$RELAY_SHELL_EDGE_UPSTREAM:127.0.0.1:8080} {
+			header_up Host {upstream_hostport}
+		}
+	}
+	handle /.well-known/oauth-protected-resource* {
+		reverse_proxy {$RELAY_SHELL_EDGE_UPSTREAM:127.0.0.1:8080} {
+			header_up Host {upstream_hostport}
+		}
+	}
+
+	# Everything else (tool traffic, /token) is CIDR-restricted. Override
+	# RELAY_SHELL_EDGE_CLIENT_CIDRS to the source ranges of your MCP client.
+	@blocked not remote_ip {$RELAY_SHELL_EDGE_CLIENT_CIDRS:127.0.0.1/8 ::1}
+	handle @blocked {
+		respond "Forbidden" 403
+	}
+
+	reverse_proxy {$RELAY_SHELL_EDGE_UPSTREAM:127.0.0.1:8080} {
+		header_up Host {upstream_hostport}
+	}
+
+	header {
+		Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
+		X-Content-Type-Options "nosniff"
+		X-Frame-Options "DENY"
+		Referrer-Policy "no-referrer"
+		-Server
+	}
+
+	log {
+		output file /var/log/caddy/relay-shell-access.log {
+			roll_size 50MiB
+			roll_keep 5
+		}
+		format json
+	}
+}

relay_shell/_deploy/install-edge.sh

@@ -0,0 +1,272 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# relay-shell edge installer - idempotent.
+#
+# Installs Caddy and lays down the relay-shell Caddyfile with automated TLS
+# via ACME (Let's Encrypt by default, ZeroSSL fallback). Provisioning and
+# renewal are handled by Caddy's built-in ACME client; there is no cron and
+# no certbot. Certificates persist across restarts under Caddy's data dir.
+#
+# Required:
+#   RELAY_SHELL_EDGE_DOMAIN        public hostname (DNS A/AAAA must point here)
+#   RELAY_SHELL_EDGE_ACME_EMAIL    contact email for ACME registration
+#
+# Recommended:
+#   RELAY_SHELL_EDGE_CLIENT_CIDRS  space-separated source allowlist for
+#                                  tool traffic and /token (defaults to
+#                                  loopback only, which blocks remote clients)
+#
+# Optional:
+#   RELAY_SHELL_EDGE_UPSTREAM      loopback upstream (default 127.0.0.1:8080)
+#   RELAY_SHELL_EDGE_ACME_CA       ACME directory override (e.g. LE staging)
+#   RELAY_SHELL_EDGE_OPEN_FIREWALL set to 1 to open 80/443 via ufw if present
+#   RELAY_SHELL_EDGE_DRY_RUN       set to 1 to print the parameterized
+#                                  Caddyfile template and exit
+#   RELAY_SHELL_EDGE_FORCE         set to 1 to overwrite an existing
+#                                  /etc/caddy/Caddyfile that this installer
+#                                  did not place (back it up first!)
+#
+# Location: deploy/install-edge.sh  Run as: root (sudo)
+
+SCRIPT_NAME="$(basename "$0")"
+SRC_DIR="$(cd "$(dirname "$0")" && pwd)"
+CADDYFILE_SRC="$SRC_DIR/Caddyfile"
+CADDYFILE_DST="/etc/caddy/Caddyfile"
+ENV_DROPIN_DIR="/etc/systemd/system/caddy.service.d"
+ENV_DROPIN="$ENV_DROPIN_DIR/relay-shell-edge.conf"
+EDGE_ENV_FILE="/etc/relay-shell/relay-shell-edge.env"
+OPERATOR_ENV_FILE="/etc/relay-shell/relay-shell.env"
+
+log()  { echo "[$(date -Iseconds)] [$SCRIPT_NAME] $*"; }
+warn() { log "WARN: $*" >&2; }
+die()  { log "FATAL: $*" >&2; exit 1; }
+
+require_var() {
+    local name="$1"
+    local val="${!name:-}"
+    [ -n "$val" ] || die "$name is required (export it before running, or set it in $OPERATOR_ENV_FILE)"
+}
+
+# Parse a systemd-style EnvironmentFile safely. Unlike `source`, this does
+# not execute the file, so values containing spaces, shell metacharacters,
+# or unbalanced quotes cannot crash or hijack the installer. Only keys
+# matching RELAY_SHELL_EDGE_* are exported.
+load_edge_env() {
+    local file="$1" line key val
+    [ -r "$file" ] || return 0
+    while IFS= read -r line || [ -n "$line" ]; do
+        case "$line" in
+            ''|\#*) continue ;;
+        esac
+        line="${line#export }"
+        case "$line" in
+            *=*) ;;
+            *) continue ;;
+        esac
+        key="${line%%=*}"
+        val="${line#*=}"
+        case "$key" in
+            RELAY_SHELL_EDGE_*) ;;
+            *) continue ;;
+        esac
+        # Strip a single pair of surrounding double or single quotes if
+        # present (systemd permits, but does not require, them).
+        case "$val" in
+            \"*\") val="${val#\"}"; val="${val%\"}" ;;
+            \'*\') val="${val#\'}"; val="${val%\'}" ;;
+        esac
+        # Reject control characters and embedded newlines (the latter cannot
+        # appear in a single read line, but be explicit).
+        case "$val" in
+            *[$'\n\r']*) die "value for $key in $file contains a newline" ;;
+        esac
+        export "$key=$val"
+    done < "$file"
+}
+
+load_edge_env "$OPERATOR_ENV_FILE"
+
+[ "$(id -u)" -eq 0 ] || die "must run as root"
+[ -r "$CADDYFILE_SRC" ] || die "Caddyfile template not found at $CADDYFILE_SRC"
+
+require_var RELAY_SHELL_EDGE_DOMAIN
+require_var RELAY_SHELL_EDGE_ACME_EMAIL
+
+: "${RELAY_SHELL_EDGE_UPSTREAM:=127.0.0.1:8080}"
+: "${RELAY_SHELL_EDGE_CLIENT_CIDRS:=127.0.0.1/8 ::1}"
+: "${RELAY_SHELL_EDGE_ACME_CA:=https://acme-v02.api.letsencrypt.org/directory}"
+
+# Reject any value containing characters that would corrupt the systemd
+# EnvironmentFile we write below (newlines were caught above; reject NULs
+# and stray quotes that would unbalance the file).
+for var in RELAY_SHELL_EDGE_DOMAIN RELAY_SHELL_EDGE_ACME_EMAIL \
+           RELAY_SHELL_EDGE_ACME_CA RELAY_SHELL_EDGE_UPSTREAM \
+           RELAY_SHELL_EDGE_CLIENT_CIDRS; do
+    case "${!var}" in
+        *[$'\n\r\0']*) die "$var contains a control character" ;;
+    esac
+done
+
+log "Edge domain : $RELAY_SHELL_EDGE_DOMAIN"
+log "ACME email  : $RELAY_SHELL_EDGE_ACME_EMAIL"
+log "ACME CA     : $RELAY_SHELL_EDGE_ACME_CA"
+log "Upstream    : $RELAY_SHELL_EDGE_UPSTREAM"
+log "Client CIDRs: $RELAY_SHELL_EDGE_CLIENT_CIDRS"
+
+if [ "${RELAY_SHELL_EDGE_CLIENT_CIDRS}" = "127.0.0.1/8 ::1" ]; then
+    warn "client CIDR allowlist is loopback only - remote clients will be 403'd until you set RELAY_SHELL_EDGE_CLIENT_CIDRS"
+fi
+
+if [ "${RELAY_SHELL_EDGE_DRY_RUN:-0}" = "1" ]; then
+    log "Dry run - printing the parameterized Caddyfile template below."
+    log "Caddy substitutes {\$RELAY_SHELL_EDGE_*} at service start using the values logged above."
+    cat "$CADDYFILE_SRC"
+    exit 0
+fi
+
+if ! command -v caddy >/dev/null 2>&1; then
+    log "Installing Caddy from the official apt repository"
+    if ! command -v apt-get >/dev/null 2>&1; then
+        die "no caddy binary and apt-get unavailable - install Caddy manually (see https://caddyserver.com/docs/install) and re-run"
+    fi
+    apt-get update -qq
+    apt-get install -y -qq debian-keyring debian-archive-keyring apt-transport-https curl gnupg
+    install -d -m 0755 /etc/apt/keyrings
+    if [ ! -f /etc/apt/keyrings/caddy-stable-archive-keyring.gpg ]; then
+        curl -fsSL https://dl.cloudsmith.io/public/caddy/stable/gpg.key \
+            | gpg --dearmor -o /etc/apt/keyrings/caddy-stable-archive-keyring.gpg
+        chmod 0644 /etc/apt/keyrings/caddy-stable-archive-keyring.gpg
+    fi
+    if [ ! -f /etc/apt/sources.list.d/caddy-stable.list ]; then
+        cat >/etc/apt/sources.list.d/caddy-stable.list <<'REPO'
+deb [signed-by=/etc/apt/keyrings/caddy-stable-archive-keyring.gpg] https://dl.cloudsmith.io/public/caddy/stable/deb/debian any-version main
+deb-src [signed-by=/etc/apt/keyrings/caddy-stable-archive-keyring.gpg] https://dl.cloudsmith.io/public/caddy/stable/deb/debian any-version main
+REPO
+    fi
+    apt-get update -qq
+    apt-get install -y -qq caddy
+else
+    log "Caddy already installed: $(caddy version 2>/dev/null | head -1)"
+fi
+
+# The rest of the installer assumes a systemd-managed caddy.service (the
+# official apt package ships one). A binary installed by hand may not. Bail
+# out early with an actionable message instead of failing inside `systemctl`.
+if ! systemctl list-unit-files caddy.service >/dev/null 2>&1 \
+        || ! systemctl list-unit-files caddy.service 2>/dev/null | grep -q '^caddy\.service'; then
+    die "caddy binary is present but no caddy.service systemd unit was found.
+       Install the official apt package (this script does that automatically
+       when caddy is missing) or provide your own caddy.service unit before
+       re-running. See https://caddyserver.com/docs/install."
+fi
+
+install -d -m 0755 /etc/caddy
+install -d -m 0750 -o caddy -g caddy /var/log/caddy 2>/dev/null || install -d -m 0755 /var/log/caddy
+
+# A magic marker on the first non-comment line lets us recognize a Caddyfile
+# this installer owns vs. one a human (or another tool) has placed there for
+# unrelated sites. Refusing to clobber the latter prevents an outage when
+# this is run on a host that already serves other vhosts via Caddy.
+MANAGED_MARKER="# relay-shell:install-edge:managed"
+RELAY_SHELL_EDGE_FORCE="${RELAY_SHELL_EDGE_FORCE:-0}"
+
+if [ -e "$CADDYFILE_DST" ] && [ "$RELAY_SHELL_EDGE_FORCE" != "1" ]; then
+    if ! head -n 5 "$CADDYFILE_DST" | grep -qF "$MANAGED_MARKER"; then
+        die "$CADDYFILE_DST exists and was not written by this installer.
+       Refusing to overwrite a Caddyfile that may serve other sites.
+       Options:
+         - merge the contents of $CADDYFILE_SRC into $CADDYFILE_DST by hand
+           (it is a single site block scoped to \$RELAY_SHELL_EDGE_DOMAIN), or
+         - back up the existing file and re-run with RELAY_SHELL_EDGE_FORCE=1
+           to replace it."
+    fi
+fi
+
+log "Installing $CADDYFILE_DST"
+# Prepend the ownership marker so a future run recognizes its own file.
+{
+    echo "$MANAGED_MARKER"
+    cat "$CADDYFILE_SRC"
+} > "$CADDYFILE_DST.tmp"
+chmod 0644 "$CADDYFILE_DST.tmp"
+mv "$CADDYFILE_DST.tmp" "$CADDYFILE_DST"
+
+# Write a dedicated systemd EnvironmentFile rather than inlining values into
+# the drop-in. Keeps the drop-in static and avoids `%`-specifier expansion
+# that systemd applies inside Environment= assignments.
+#
+# Note on quoting: systemd's EnvironmentFile parser treats whitespace inside
+# an unquoted value as a separator for additional KEY=VALUE pairs on the
+# same line, which would silently truncate RELAY_SHELL_EDGE_CLIENT_CIDRS to
+# the first CIDR. Emit every value double-quoted, with embedded double
+# quotes escaped, so multi-token values survive intact.
+emit_env() {
+    local key="$1" val="$2"
+    # Escape backslashes first, then double quotes.
+    val="${val//\\/\\\\}"
+    val="${val//\"/\\\"}"
+    printf '%s="%s"\n' "$key" "$val"
+}
+
+log "Installing edge env file at $EDGE_ENV_FILE"
+install -d -m 0755 /etc/relay-shell
+umask 077
+{
+    echo "# Managed by relay-shell deploy/install-edge.sh - do not hand-edit."
+    echo "# Update $OPERATOR_ENV_FILE and re-run the installer instead."
+    emit_env RELAY_SHELL_EDGE_DOMAIN       "$RELAY_SHELL_EDGE_DOMAIN"
+    emit_env RELAY_SHELL_EDGE_ACME_EMAIL   "$RELAY_SHELL_EDGE_ACME_EMAIL"
+    emit_env RELAY_SHELL_EDGE_ACME_CA      "$RELAY_SHELL_EDGE_ACME_CA"
+    emit_env RELAY_SHELL_EDGE_UPSTREAM     "$RELAY_SHELL_EDGE_UPSTREAM"
+    emit_env RELAY_SHELL_EDGE_CLIENT_CIDRS "$RELAY_SHELL_EDGE_CLIENT_CIDRS"
+} > "$EDGE_ENV_FILE"
+# Not secret, but still security-relevant edge configuration: keep it
+# root-owned and group-readable by caddy (which needs to read it for the
+# drop-in's EnvironmentFile=), not world-readable.
+if getent group caddy >/dev/null 2>&1; then
+    chown root:caddy "$EDGE_ENV_FILE"
+    chmod 0640 "$EDGE_ENV_FILE"
+else
+    chmod 0600 "$EDGE_ENV_FILE"
+    warn "no 'caddy' group found; $EDGE_ENV_FILE is root-only - caddy may fail to read it"
+fi
+umask 022
+
+log "Installing systemd environment drop-in at $ENV_DROPIN"
+install -d -m 0755 "$ENV_DROPIN_DIR"
+cat >"$ENV_DROPIN" <<EOF
+# Managed by relay-shell deploy/install-edge.sh.
+# Values live in $EDGE_ENV_FILE so unit syntax is not affected by user input.
+[Service]
+EnvironmentFile=$EDGE_ENV_FILE
+EOF
+chmod 0644 "$ENV_DROPIN"
+
+log "Validating Caddyfile syntax"
+# `caddy validate` reads the same env Caddy will see at start, so export here.
+export RELAY_SHELL_EDGE_DOMAIN RELAY_SHELL_EDGE_ACME_EMAIL RELAY_SHELL_EDGE_ACME_CA \
+       RELAY_SHELL_EDGE_UPSTREAM RELAY_SHELL_EDGE_CLIENT_CIDRS
+caddy validate --config "$CADDYFILE_DST" --adapter caddyfile
+
+if [ "${RELAY_SHELL_EDGE_OPEN_FIREWALL:-0}" = "1" ] && command -v ufw >/dev/null 2>&1; then
+    log "Opening 80/tcp and 443/tcp via ufw"
+    ufw allow 80/tcp  >/dev/null || warn "ufw allow 80/tcp failed"
+    ufw allow 443/tcp >/dev/null || warn "ufw allow 443/tcp failed"
+fi
+
+systemctl daemon-reload
+log "Enabling and (re)starting caddy"
+systemctl enable caddy >/dev/null
+systemctl restart caddy
+
+# Give Caddy a brief moment to settle, then report.
+sleep 1
+if systemctl is-active --quiet caddy; then
+    log "Caddy is active. Initial certificate issuance happens on the first HTTPS request to ${RELAY_SHELL_EDGE_DOMAIN}."
+    log "Watch progress with:  journalctl -u caddy -f"
+else
+    die "caddy failed to start - check 'journalctl -u caddy -n 100'"
+fi
+
+log "Done. Verify the cert with:  curl -I https://${RELAY_SHELL_EDGE_DOMAIN}/.well-known/oauth-protected-resource"

relay_shell/_deploy/install.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# relay-shell installer - idempotent. Creates a dedicated service account and venv,
+# installs the package, and lays down the systemd/logrotate assets. It does
+# NOT enable or start the service: review the unit and configuration first.
+#
+# Location: deploy/install.sh   Run as: root (sudo)
+
+SCRIPT_NAME="$(basename "$0")"
+PREFIX="/var/lib/relay-shell"
+SRC_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+log() { echo "[$(date -Iseconds)] [$SCRIPT_NAME] $*"; }
+die() { log "FATAL: $*" >&2; exit 1; }
+
+[ "$(id -u)" -eq 0 ] || die "must run as root"
+
+log "Ensuring service account 'relay-shell'"
+if ! id relay-shell >/dev/null 2>&1; then
+    useradd --system --create-home --home-dir "$PREFIX" \
+            --shell /usr/sbin/nologin relay-shell
+fi
+
+log "Creating venv at $PREFIX/venv"
+if [ ! -x "$PREFIX/venv/bin/python" ]; then
+    sudo -u relay-shell python3 -m venv "$PREFIX/venv"
+fi
+sudo -u relay-shell "$PREFIX/venv/bin/pip" install --quiet --upgrade pip
+sudo -u relay-shell "$PREFIX/venv/bin/pip" install --quiet "$SRC_DIR"
+
+log "Audit log directory"
+mkdir -p /var/log/relay-shell
+chown relay-shell:relay-shell /var/log/relay-shell
+if [ ! -e /var/log/relay-shell/audit.jsonl ]; then
+    install -o relay-shell -g relay-shell -m 0600 /dev/null /var/log/relay-shell/audit.jsonl
+fi
+chattr +a /var/log/relay-shell/audit.jsonl 2>/dev/null || \
+    log "WARN: could not set append-only (non-ext filesystem?)"
+
+log "Installing systemd unit + hardening drop-in"
+install -m 0644 "$SRC_DIR/deploy/systemd/relay-shell.service" /etc/systemd/system/relay-shell.service
+mkdir -p /etc/systemd/system/relay-shell.service.d
+install -m 0644 "$SRC_DIR/deploy/systemd/relay-shell.service.d/hardening.conf" \
+        /etc/systemd/system/relay-shell.service.d/hardening.conf
+systemctl daemon-reload
+
+log "Installing logrotate config"
+install -m 0644 "$SRC_DIR/deploy/logrotate/relay-shell" /etc/logrotate.d/relay-shell
+
+mkdir -p /etc/relay-shell
+[ -e /etc/relay-shell/relay-shell.env ] || {
+    install -m 0640 -o root -g relay-shell "$SRC_DIR/.env.example" /etc/relay-shell/relay-shell.env
+    log "Wrote /etc/relay-shell/relay-shell.env from .env.example - EDIT IT before starting"
+}
+
+log "Done. Review /etc/relay-shell/relay-shell.env and the unit, then:"
+log "  systemctl enable --now relay-shell"
+log "  (HTTP transport: put deploy/Caddyfile in front; restrict the CIDRs)"

relay_shell/_deploy/logrotate/relay-shell

@@ -0,0 +1,22 @@
+# /etc/logrotate.d/relay-shell
+#
+# The audit log is append-only on disk (chattr +a). The append-only attribute
+# must be dropped only for the rotate itself and restored immediately, so a
+# compromised process cannot rewrite history through the rotation window.
+
+/var/log/relay-shell/audit.jsonl {
+    daily
+    rotate 90
+    missingok
+    notifempty
+    compress
+    delaycompress
+    create 0600 relay-shell relay-shell
+    dateext
+    prerotate
+        /usr/bin/chattr -a /var/log/relay-shell/audit.jsonl 2>/dev/null || true
+    endscript
+    postrotate
+        /usr/bin/chattr +a /var/log/relay-shell/audit.jsonl 2>/dev/null || true
+    endscript
+}