ops-bridge/SCOPE.md

SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

---

One-liner

SSH reverse tunnel lifecycle manager — keeps remote execution environments continuously connected to the local Custodian State Hub via auto-reconnecting port-forwards. Supports both static SSH keys (no TTL) and CA-signed short-lived certificates via a pluggable cert_command interface.

---

Core Idea

Claude Code sessions run locally; the Custodian State Hub API runs locally. Remote machines (Railiance nodes, Temporal workers, Markitect services) need to reach the hub. Ops-bridge manages named SSH reverse tunnels with auto-reconnect, health checks, audit logging, and an MCP server so Claude Code can start/stop/inspect tunnels as tools.

---

In Scope

• Named SSH reverse tunnel lifecycle (bridge up/down/restart/status/logs/cert-status)
• Auto-reconnect with exponential backoff and configurable retry policy
• Optional HTTP health checks (confirm forwarded service is actually reachable from remote)
• Structured audit logging: JSON events (connected, disconnected, health_check_failed, etc.)
• Actor attribution: per-tunnel actor type (adm / agt / atm) for audit traceability, with naming convention enforcement (adm-*, agt-*, atm-*)
• Static key mode (default): ssh_key passed directly to SSH — no TTL, no cert logic, works without any CA or external tooling
• cert_command mode (optional): pluggable shell command that issues a short-lived CA-signed certificate before each SSH launch; TTL-aware pre-emptive cert refresh; cert_identity recorded in audit log — satisfies AccessManagementDirective §5
• PID + state file management in ~/.local/state/bridge/
• MCP server exposing tunnel lifecycle + OpsCatalog queries as Claude Code tools
• OpsCatalog: optional Git-backed YAML catalog of infrastructure topology (domains/targets/bridges)

---

Out of Scope

• Credential issuance and CA management (owned by ops-warden; ops-bridge consumes certs via the cert_command interface but never signs anything itself)
• SSH key generation for human admins (self-service: ssh-keygen)
• Host-side principal deployment (/etc/ssh/auth_principals/) — that is railiance-infra
• Long-running application hosting on remote machines (port-forward only, not deployment)
• VPN or layer-3 connectivity
• Monitoring/alerting beyond JSON audit logs
• Replacing SSH for general interactive access

---

Relevant When

• Remote Temporal workers or Railiance nodes need to reach the local Custodian MCP
• Need audit trail of which actor (adm / agt / atm) started/stopped tunnels
• Setting up a new machine in the Railiance ecosystem that must phone home to the hub
• Diagnosing connectivity issues between local hub and remote services
• Checking certificate validity for active tunnels (bridge cert-status)
• Integrating with a CA (ops-warden or Vault) for short-lived tunnel credentials

---

Not Relevant When

• All work is local (no remote services involved)
• Manually running ssh -R is acceptable
• No need for audit tracing of tunnel state changes

---

Current State

• Status: active (v0.1 core complete; AccessManagementDirective alignment done — BRIDGE-WP-0004)
• Implementation: ~80% — CLI tunneling fully functional, MCP integration working, health checks and audit logging complete; ActorType enum (adm/agt/atm) enforced; cert_command mode implemented with TTL-aware refresh and cert_identity audit logging; OpsCatalog framework present but not yet populated
• Stability: stable tunnel lifecycle; tested under network drops and SSH failures
• Usage: running in lab for daily Railiance/Temporal connectivity

---

How It Fits

• Upstream dependencies: SSH (system), OpenSSH server on remote hosts
• Downstream consumers: all remote Claude Code agents depend on ops-bridge to reach local hub MCP; activity-core Temporal server reachable via bridge tunnel
• Often used with: the-custodian (health checks point to hub API), activity-core (Temporal port-forwarding)

---

Terminology

• Preferred terms: tunnel, bridge, actor, actor_type, reconnect policy, health check, cert_command, cert_identity
• Actor types: adm (human operator), agt (LLM agent), atm (deterministic automation)
• Also known as: "the bridge"
• Potentially confusing: "bridge state" is a tunnel-specific state machine (stopped → starting → connected ↔ degraded → reconnecting), not a network bridge
• Legacy terms (deprecated): actor_class: human (→ adm), actor_class: automation (→ atm)

---

Related / Overlapping

• the-custodian — primary consumer; ops-bridge keeps remote agents connected to it
• ops-warden — optional upstream; owns CA and cert issuance; ops-bridge calls it via cert_command when short-lived certificates are required
• activity-core — Temporal server on remote reached via ops-bridge tunnel
• railiance-cluster / railiance-infra — remote hosts that need to phone home; owns host-side principal deployment (/etc/ssh/auth_principals/)

---

Provided Capabilities

type: infrastructure
title: SSH reverse tunnel connectivity
description: Named, auto-reconnecting SSH reverse tunnels with health checks and audit logging — keeps remote execution environments continuously connected to the local Custodian State Hub.
keywords: [ssh, tunnel, reverse-tunnel, connectivity, remote, bridge, ops-bridge]

---

Getting Oriented

• Start with: README.txt (architecture, config format, CLI commands, MCP integration)
• Key files / directories: ~/.config/bridge/tunnels.yaml (tunnel config), ~/.local/state/bridge/ (PID/state/cert files)
• Entry points: bridge --help; bridge up <tunnel-name>; bridge cert-status; MCP: bridge_status()
• AccessManagementDirective context: wiki/AccessManagementDirective.md
• Workplans: BRIDGE-WP-0004 (directive alignment), WARDEN-WP-0001 (ops-warden bootstrap)