wish

README

Wish

Make SSH apps, just like that! 💫

SSH is an excellent platform to build remotely accessible applications on. It offers secure communication without the hassle of HTTPS certificates, it has user identification with SSH keys and it's accessible from anywhere with a terminal. Powerful protocols like Git work over SSH and you can even render TUIs directly over an SSH connection.

Wish is an SSH server with sensible defaults and a collection of middleware that makes building SSH apps easy. Wish is built on gliderlabs/ssh and should be easy to integrate into any existing projects.

What are SSH Apps?

Usually, when we think about SSH, we think about remote shell access into servers, most commonly through openssh-server.

That's a perfectly valid and probably the most common use of SSH, but it can do so much more than that. Just like HTTP, SMTP, FTP and others, SSH is a protocol! It is a cryptographic network protocol for operating network services securely over an unsecured network. ^1

That means, among other things, that we can write custom SSH servers, without touching openssh-server, so we can securely do more things than just providing a shell.

Wish is a library that helps writing these kind of apps using Go.

Middleware

Wish middlewares are analogous to those in several HTTP frameworks. They are essentially SSH handlers that you can use to do specific tasks, and then call the next middleware.

Notice that middlewares are composed from first to last, which means the last one is executed first.

Bubble Tea

The bubbletea middleware makes it easy to serve any Bubble Tea application over SSH. Each SSH session will get their own tea.Program with the SSH pty input and output connected. Client window dimension and resize messages are also natively handled by the tea.Program.

You can see a demo of the Wish middleware in action at: ssh git.charm.sh

Git

The git middleware adds git server functionality to any ssh server. It supports repo creation on initial push and custom public key based auth.

This middleware requires that git is installed on the server.

Logging

The logging middleware provides basic connection logging. Connects are logged with the remote address, invoked command, TERM setting, window dimensions and if the auth was public key based. Disconnect will log the remote address and connection duration.

Access Control

Not all applications will support general SSH connections. To restrict access to supported methods, you can use the activeterm middleware to only allow connections with active terminals connected and the accesscontrol middleware that lets you specify allowed commands.

Default Server

Wish includes the ability to easily create an always authenticating default SSH server with automatic server key generation.

Examples

There are examples for a standalone Bubble Tea application and Git server in the examples folder.

Apps Built With Wish

• Soft Serve
• Wishlist
• SSHWordle
• clidle
• ssh-warm-welcome

Pro Tip

When building various Wish applications locally you can add the following to your ~/.ssh/config to avoid having to clear out localhost entries in your ~/.ssh/known_hosts file:

Host localhost
    UserKnownHostsFile /dev/null

How it works?

Wish uses gliderlabs/ssh to implement its SSH server, and the OpenSSH is never used nor needed — you can even uninstall it if you want to.

Incidentally, there's no risk of accidentally sharing a shell because there's no default behavior that does that on Wish.

Running with SystemD

If you want to run a Wish app with systemd, you can create an unit like so:

/etc/systemd/system/myapp.service:

[Unit]
Description=My App
After=network.target

[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/home/myapp/
ExecStart=/usr/bin/myapp
Restart=on-failure

[Install]
WantedBy=multi-user.target

You can tune the values bellow, and once you're happy with them, you can run:

# need to run this every time you change the unit file
sudo systemctl daemon-reload

# start/restart/stop/etc:
sudo systemctl start myapp

If you use a new user for each app (which is good), you'll need to create them first:

useradd --system --user-group --create-home myapp

That should do it.

Feedback

We’d love to hear your thoughts on this project. Feel free to drop us a note!

• Twitter
• The Fediverse
• Discord

License

MIT

---

Part of Charm.

Charm热爱开源 • Charm loves open source

Documentation

Index

• func Error(s ssh.Session, v ...interface{})
• func Errorf(s ssh.Session, f string, v ...interface{})
• func Errorln(s ssh.Session, v ...interface{})
• func Fatal(s ssh.Session, v ...interface{})
• func Fatalf(s ssh.Session, f string, v ...interface{})
• func Fatalln(s ssh.Session, v ...interface{})
• func NewServer(ops ...ssh.Option) (*ssh.Server, error)
• func Print(s ssh.Session, v ...interface{})
• func Printf(s ssh.Session, f string, v ...interface{})
• func Println(s ssh.Session, v ...interface{})
• func WithAddress(addr string) ssh.Option
• func WithAuthorizedKeys(path string) ssh.Option
• func WithHostKeyPEM(pem []byte) ssh.Option
• func WithHostKeyPath(path string) ssh.Option
• func WithIdleTimeout(d time.Duration) ssh.Option
• func WithKeyboardInteractiveAuth(h ssh.KeyboardInteractiveHandler) ssh.Option
• func WithMaxTimeout(d time.Duration) ssh.Option
• func WithMiddleware(mw ...Middleware) ssh.Option
• func WithPasswordAuth(p ssh.PasswordHandler) ssh.Option
• func WithPublicKeyAuth(h ssh.PublicKeyHandler) ssh.Option
• func WithTrustedUserCAKeys(path string) ssh.Option
• func WithVersion(version string) ssh.Option
• func WriteString(s ssh.Session, v string) (int, error)
• type Middleware

Functions

func Error

func Error(s ssh.Session, v ...interface{})

Error prints the given error the the session's STDERR.

func Errorf

func Errorf(s ssh.Session, f string, v ...interface{})

Errorf formats according to the given format and prints to the session's STDERR.

func Errorln

func Errorln(s ssh.Session, v ...interface{})

Errorf formats according to the default format and prints to the session's STDERR.

func Fatal

func Fatal(s ssh.Session, v ...interface{})

Fatal prints to the given session's STDERR and exits 1.

func Fatalf

func Fatalf(s ssh.Session, f string, v ...interface{})

Fatalf formats according to the given format, prints to the session's STDERR followed by an exit 1.

Notice that this might cause formatting issues if you don't add a \r\n in the end of your string.

func Fatalln

func Fatalln(s ssh.Session, v ...interface{})

Fatalln formats according to the default format, prints to the session's STDERR, followed by a new line and an exit 1.

func NewServer

func NewServer(ops ...ssh.Option) (*ssh.Server, error)

NewServer is returns a default SSH server with the provided Middleware. A new SSH key pair of type ed25519 will be created if one does not exist. By default this server will accept all incoming connections, password and public key.

func Print

func Print(s ssh.Session, v ...interface{})

Print writes to the session's STDOUT followed.

func Printf

func Printf(s ssh.Session, f string, v ...interface{})

Printf formats according to the given format and writes to the session's STDOUT.

func Println

func Println(s ssh.Session, v ...interface{})

Println formats according to the default format and writes to the session's STDOUT.

func WithAddress

func WithAddress(addr string) ssh.Option

WithAddress returns an ssh.Option that sets the address to listen on.

func WithAuthorizedKeys

func WithAuthorizedKeys(path string) ssh.Option

WithAuthorizedKeys allows to use a SSH authorized_keys file to allowlist users.

func WithHostKeyPEM

func WithHostKeyPEM(pem []byte) ssh.Option

WithHostKeyPEM returns an ssh.Option that sets the host key from a PEM block.

func WithHostKeyPath

func WithHostKeyPath(path string) ssh.Option

WithHostKeyFile returns an ssh.Option that sets the path to the private.

func WithIdleTimeout

func WithIdleTimeout(d time.Duration) ssh.Option

WithIdleTimeout returns an ssh.Option that sets the connection's idle timeout.

func WithKeyboardInteractiveAuth

func WithKeyboardInteractiveAuth(h ssh.KeyboardInteractiveHandler) ssh.Option

WithKeyboardInteractiveAuth returns an ssh.Option that sets the keyboard interactive auth handler.

func WithMaxTimeout

func WithMaxTimeout(d time.Duration) ssh.Option

WithMaxTimeout returns an ssh.Option that sets the connection's absolute timeout.

func WithMiddleware

func WithMiddleware(mw ...Middleware) ssh.Option

WithMiddleware composes the provided Middleware and return a ssh.Option. This useful if you manually create an ssh.Server and want to set the Server.Handler.

Notice that middlewares are composed from first to last, which means the last one is executed first.

func WithPasswordAuth

func WithPasswordAuth(p ssh.PasswordHandler) ssh.Option

WithPasswordAuth returns an ssh.Option that sets the password auth handler.

func WithPublicKeyAuth

func WithPublicKeyAuth(h ssh.PublicKeyHandler) ssh.Option

WithPublicKeyAuth returns an ssh.Option that sets the public key auth handler.

func WithTrustedUserCAKeys

func WithTrustedUserCAKeys(path string) ssh.Option

WithTrustedUserCAKeys authorize certificates that are signed with the given Certificate Authority public key, and are valid. Analogous to the TrustedUserCAKeys OpenSSH option.

func WithVersion

func WithVersion(version string) ssh.Option

WithVersion returns an ssh.Option that sets the server version.

func WriteString

func WriteString(s ssh.Session, v string) (int, error)

WriteString writes the given string to the session's STDOUT.

Types

type Middleware

type Middleware func(ssh.Handler) ssh.Handler

Middleware is a function that takes an ssh.Handler and returns an ssh.Handler. Implementations should call the provided handler argument.