hnakra/README.md

# hnakra

The successor to HLHV. More stable and capable than ever!

Hnakra is similar to an HTTP reverse proxy, but it uses a custom protocol to
allow services to connect to the router instead of the other way around. This
approach provides a greater level of security and ease of setup, and allows
services to do cool things like hide behind a firewall on a completely different
network.

Hnakra is also designed to be multi-protocol, so services can make their content
and functionality available over HTTP, HTTPS, gemini, etc. In theory, any
request/response based protocol that uses URLs could be integrated into Hnakra.
Currently, only HTTPS is supported, but other protocols are coming soon.

## Security features

Hnakra has a highly configurable user/permission system for dictating what
services are allowed to do what. Services authenticate the identity of the
router using its TLS certificate, and the router authenticates the identity of
connecting services using a supplied username/key combination. This is so each
service can be given limited access to a particular portion of the site.

## Router server

This module comes with a basic router implementation, located at `cmd/router`.
It can be configured using `/etc/hnakra/hnakra.conf`. Each line in the
configuration file can be blank, a command, or a comment. A list of available
commands:

### `alias <alias> -> <target>`
When a request comes in with a host matching `alias`, it is replaced with
`target` before being routed to the appropriate service. If `(fallback)` is
specified as `alias`, any host that doesn't match a pre-existing alias will be
rewritten as `target`. By default, hosts equivalent to `localhost` are aliased
to the target `@`. It is reccomended to alias your domain name to `@` as well so
you don't need to hard-code it into your services.

### `unalias <alias>`
`unalias` undoes an alias that was created previously.

### `keyPath <path>`
`keyPath` specifies the location of the TLS key to load.

### `certPath <path>`
`certPath` specifies the location of the TLS certificate to load.

### `rcon`
This command enables the remote console, which lets you monitor the state of the
router from a webpage. It is available at `https://@/debug/rcon`. Before
accessing it, you must set up at least one user with rcon access.

### `router <port>`
This command specifies the port that services will connect to. If not specified,
the value of `$HNAKRA_ROUTER_PORT` will be used. If that is also blank, it will
default to a value of `2048`.

### `https [port]`
This command enables the HTTPS protocol. If the port is left blank, the value of
`$HNAKRA_HTTPS_PORT` will be used. If that is also blank, it will default to a
value of `443`.

### `http [port]`
This command enables the insecure HTTP protocol. If the port is left blank, the
value of `$HNAKRA_HTTP_PORT` will be used. If that is also blank, it will
default to a value of `80`.

### `gemini [port]`
This command enables the gemini protocol. If the port is left blank, the value
of `$HNAKRA_GEMINI_PORT` will be used. If that is also blank, it will defaul to
a value of `1965`.

### `noSecurity I AM NOT USING THIS IN PRODUCTION.`
This command disables username/key authentication entirely and lets any service
mount anywhere. For this to work, it must be typed exactly as shown above.

### `user <name>:<key hash> -> <capability>, ...`
The `user` command creates a new user under the specified name, with the
specified bcrypt key hash. Following the user is a `->` symbol, then a
comma-separated list of capabilities that user has. A capability can be a mount
point pattern, or the value `(rcon)`. Mount point patterns are interpreted as
follows:

- A singular glob, `*`, allows the user to mount services on any host or path.
- A URL pattern without any globs or trailing slashes (such as `https://@/path`)
  allows the user to mount services on that exact path only.
- If the host component of the pattern is prefixed with a `.`, it will match
  subdomains of that host as well as the host itself.
- If the host component of the pattern is prefixed with a `*`, it will match any
  host ending in the host component (not including the glob).
- If the path component of the pattern is affixed with a `/`, it will match any
  paths under it, as well as the path itself.
- If the path component of the pattern is affixed with a `*`, it will match any
  path that starts with the path component (not including the glob).

For example, the pattern `https://.@/static/` allows a user to mount services on
`@` (or any subdomain of `@`) at `/static` (or anything underneath `/static`) on
the HTTPS protocol.

Specifiying a value as `(rcon)` as opposed to a mount point pattern will allow
access to the rcon panel (if it is enabled) by logging in with this user's
credentials.

## Service package

This module also comes with a package that allows you to easily create a service
in just a few lines of code. Some examples can be found in the `examples`
directory.