Archway

Archway is an identity-aware command-line and terminal client for academic SSH access. It keeps institutional identity, short-lived OPKSSH credentials, gateway selection, and safe OpenSSH options behind one interface while continuing to use standard opkssh and ssh binaries.

This initial implementation includes:

• archway c[onnect] HOST with automatic credential refresh and ProxyJump routing
• list, info, status, auth, and disconnect commands with short aliases
• an interactive terminal host picker when run without arguments
• strict public-key and host-key defaults
• a built-in UGA Living Labs profile based on opkssh-setup
• YAML inventory/configuration without a runtime dependency on a YAML library
• SSH-native host discovery filtered by signed OIDC email, group, and role claims
• a server installer that manages OPKSSH providers, authorization, and discovery policy
• managed server claims and bastion-driven /etc/opk/auth_id reconciliation
• legacy destination password authentication after an OPKSSH bastion jump

Build

Go 1.22 or newer is required.

go install git.factory.uga.edu/MLL/archway@latest

To build from a clone, run:

make build
./bin/archway status

Copy archway.example.yml to the path shown by archway config, then customize the user and host inventory. Archway also honors ARCHWAY_CONFIG for an alternate config path.

archway list
archway connect --dry-run atlas.servers.lan
archway c atlas.servers.lan
archway discover

Arguments following the host are passed to OpenSSH, so remote commands and SSH options remain available:

archway c atlas.servers.lan -- uname -a

Archway does not write ~/.ssh/config, fetch host keys, or replace SSH. The supplied UGA setup repository remains the administrator/bootstrap source for ~/.opk/config.yml and initial host trust; Archway consumes the resulting OPKSSH credential and orchestrates connections.

Server installation

The server installer works with the OPKSSH server setup. It does not download OPKSSH.

Use archway-server.example.json as the inventory template. See docs/server-installation.md for the full procedure.

sudo archway server install --config archway-server.json
sudo opkssh audit
sudo sshd -t
sudo systemctl reload sshd

The installer updates one marked block in /etc/opk/auth_id. It keeps all authorization entries outside that block.

Security behavior

Before a connection, Archway inspects the signed PKToken expiration embedded in the OpenSSH certificate next to the configured identity. OPKSSH marks the outer SSH certificate as valid forever, so that outer validity is not treated as the credential lifetime. If the PKToken is missing, expired, or near expiry, Archway runs opkssh login uga interactively. Connections disable password and keyboard-interactive fallback, select only the configured OPKSSH identity, enforce strict host-key checking, and enable bounded keepalives. Use host_key_policy: accept-new only when institution policy permits trust-on-first-use.

Scope

This is the CLI/TUI foundation. Signed central inventory distribution, richer session tracking, policy signatures, and a graphical client can be added on top of the same config and execution packages without changing the SSH transport.