diff --git a/README.md b/README.md index cea774e..39c0735 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,18 @@ It includes: * muxrpc handlers for tunneling connections * a fully embedded HTTP server & HTML frontend, for administering the room +![](./docs/screenshot.png) + ## Features * [x] Rooms v1 (`tunnel.connect`, `tunnel.endpoints`, etc.) -* [x] Simple allow-listing, administerd via the web dashboard -* [x] Sign-in with SSB -* [ ] Alias management +* [x] User management (allow- & denylisting + moderator & administrator roles), all administered via the web dashboard +* [x] Multiple [privacy modes](https://ssb-ngi-pointer.github.io/rooms2/#privacy-modes) +* [x] [Sign-in with SSB](https://ssb-ngi-pointer.github.io/ssb-http-auth-spec/) +* [x] Alias management + +## Getting started +For an architecture and instructions on setting up a webserver to use with `go-ssb-room`, [read the documentation](./docs). ## Development @@ -26,22 +32,29 @@ go build ./server -h Usage of ./server: + -aliases-as-subdomains + needs to be disabled if a wildcard certificate for the room is not available. (default true) -dbg string listen addr for metrics and pprof HTTP server (default "localhost:6078") + -https-domain string + which domain to use for TLS and AllowedHosts checks -lishttp string address to listen on for HTTP requests (default ":3000") -lismux string address to listen on for secret-handshake+muxrpc (default ":8008") - -nounixsock - disable the UNIX socket RPC interface -logs string where to write debug output to (default is just stderr) + -mode value + the privacy mode (values: open, community, restricted) determining room access controls + -nounixsock + disable the UNIX socket RPC interface -repo string - where to put the log and indexes (default "/home/cryptix/.ssb-go-room") + where to put the log and indexes (default "~/.ssb-go-room") -shscap string secret-handshake app-key (or capability) (default "1KHLiKZvAvjbY1ziZEHMXawbCEIM6qwjCDm3VYRan/s=") -version print version number and build date + ``` If you want to view the development server in your browser: @@ -108,7 +121,7 @@ cd cmd/insert-user go build # optional step: run a script to generate a valid ssb id @.ed25519, useful for trying things out quickly ./generate-fake-id.sh -./insert-user -name -key <@pubkey.ed25519> +./insert-user -login -key <@pubkey.ed25519> ``` Then repeat your password twice and you are all set for development. @@ -132,6 +145,8 @@ The folder `web/handlers` contains the HTTP handlers for the dashboard. Each sub ## Authors * [cryptix](https://github.com/cryptix) (`@p13zSAiOpguI9nsawkGijsnMfWmFd5rlUNpzekEE+vI=.ed25519`) +* [staltz](https://github.com/staltz) +* [cblgh](https://github.com/cblgh) ## License diff --git a/docs/README.md b/docs/README.md index 627bc02..859ea0d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,18 +1,40 @@ +# Getting Started +There are two paths to starting your own room: creating a build from source, or downloading one +of the premade [releases](https://github.com/ssb-ngi-pointer/go-ssb-room/releases). + +## Creating a build +* [Download Go](https://golang.org/doc/install) & [set up your Go environment](https://golang.org/doc/install#install). You will need at least Go v1.16. +* Download the repository `git clone git@github.com:ssb-ngi-pointer/go-ssb-room.git && cd go-ssb-room` +* [Read the development instructions](../README.md) +* You should now have a working go-ssb-room binary! Read the HTTP Hosting section below, for + more instructions on the last mile. + # Architecture ## Invite flow -This implementation of Rooms 2.0 is compliant with the [Rooms 2.0 specification](https://github.com/ssb-ngi-pointer/rooms2), but we add a few additional features and pages in order to improve user experience when their SSB app does not support [SSB URIs](https://github.com/ssb-ngi-pointer/ssb-uri-spec). +This implementation of Rooms 2.0 is compliant with the [Rooms 2.0 +specification](https://github.com/ssb-ngi-pointer/rooms2), but we add a few additional features +and pages in order to improve user experience when their SSB app does not support [SSB +URIs](https://github.com/ssb-ngi-pointer/ssb-uri-spec). A summary can be seen in the following chart: ![Chart](./invites-chart.png) -When the browser and operating system detects no support for opening SSB URIs, we redirect to a fallback page which presents the user with two broad options: (1) install an SSB app that supports SSB URIs, (2) link to another page where the user can manually input the user's SSB ID in a form. +When the browser and operating system detects no support for opening SSB URIs, we redirect to a +fallback page which presents the user with two broad options: (1) install an SSB app that +supports SSB URIs, (2) link to another page where the user can manually input the user's SSB ID +in a form. ## Sign-in flow -This implementation is compliant with [SSB HTTP Authentication](https://github.com/ssb-ngi-pointer/ssb-http-auth-spec), but we add a few additional features and pages in order to improve user experience. For instance, besides conventional SSB HTTP Auth, we also render a QR code to sign-in with a remote SSB app (an SSB identity not on the device that has the browser open). We also support sign-in with username/password, what we call "fallback authentication". +This implementation is compliant with [SSB HTTP +Authentication](https://github.com/ssb-ngi-pointer/ssb-http-auth-spec), but we add a few +additional features and pages in order to improve user experience. For instance, besides +conventional SSB HTTP Auth, we also render a QR code to sign-in with a remote SSB app (an SSB +identity not on the device that has the browser open). We also support sign-in with +username/password, what we call "fallback authentication". A summary can be seen in the following chart: @@ -20,17 +42,28 @@ A summary can be seen in the following chart: # HTTP Hosting -We currently assume a standard HTTPS server in front of go-ssb-room to facilitate TLS termination and certificate management. This should be possible with most modern HTTP servers since it's a pretty standard practice, known as [reverse proxying](https://en.wikipedia.org/wiki/Reverse_proxy). +We currently assume a standard HTTPS server in front of go-ssb-room to facilitate TLS +termination and certificate management. This should be possible with most modern HTTP servers +since it's a pretty standard practice, known as [reverse +proxying](https://en.wikipedia.org/wiki/Reverse_proxy). Two bits of rationale: -1) People usually want to have more than one site on their server. Put differently, we could have [LetsEncrypt](https://letsencrypt.org/) inside the go-ssb-room server but it would have to listen on port :443—blocking the use of other domains on the same IP. -2) Listening on :443 can be pretty annoying (you might need root privileges or similar capabilities). +1) People usually want to have more than one site on their server. Put differently, we could +have [LetsEncrypt](https://letsencrypt.org/) inside the go-ssb-room server but it would have to +listen on port :443—blocking the use of other domains on the same IP. 2) Listening on :443 can +be pretty annoying (you might need root privileges or similar capabilities). -go-ssb-room needs three headers to function properly, which need to be forwarded by the webserver. +go-ssb-room needs three headers to function properly, which need to be forwarded by the +webserver. * `X-Forwarded-Host` as which domain name the room is running (enforce strict TLS checking) * `X-Forwarded-Proto` to ensure that TLS is used (and redirect if necessary) -* `X-Forwarded-For` the remote TCP/IP address of the client accessing the room (used for rate limiting) +* `X-Forwarded-For` the remote TCP/IP address of the client accessing the room (used for rate + limiting) -[nginx-example.conf](./nginx-example.conf) contains an [nginx](https://nginx.org) config that we use for [hermies.club](https://hermies.club). To get a wildcard TLS certificate you can follow the steps in [this article](https://medium.com/@alitou/getting-a-wildcard-ssl-certificate-using-certbot-and-deploy-on-nginx-15b8ffa34157), which uses the [certbot](https://certbot.eff.org/) utility. +[nginx-example.conf](./nginx-example.conf) contains an [nginx](https://nginx.org) config that +we use for [hermies.club](https://hermies.club). To get a wildcard TLS certificate you can +follow the steps in [this +article](https://medium.com/@alitou/getting-a-wildcard-ssl-certificate-using-certbot-and-deploy-on-nginx-15b8ffa34157), +which uses the [certbot](https://certbot.eff.org/) utility. diff --git a/docs/screenshot.png b/docs/screenshot.png new file mode 100644 index 0000000..0d80389 Binary files /dev/null and b/docs/screenshot.png differ