From bd461f529aa5dd0615a628cc158615c22caac0a1 Mon Sep 17 00:00:00 2001 From: Andrew Cady Date: Mon, 25 Oct 2021 15:13:33 -0400 Subject: readme --- EndoForge/README.md | 130 ++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 95 insertions(+), 35 deletions(-) diff --git a/EndoForge/README.md b/EndoForge/README.md index 0a1f644..795441c 100644 --- a/EndoForge/README.md +++ b/EndoForge/README.md @@ -1,74 +1,132 @@ EndoForge ---------- -A Self-Forge. +=================== +### A `Self-Forge` -Convert any Git repository into a Self-Forge by merging this repository. +Convert any Git repository into a `Self-Forge` with a simple setting change. +Synopsis: +``` + git config core.self-forge true +``` +Install `EndoForge`: +``` + make install +``` +## WHAT IS A `Self-Forge` -WHAT IT DOES ------------- +A `Self-Forge` is a `Git` repository that allows anonymous contribution directly +through the `Git-Over-SSH` protocol. Each contributor is directly validated with +`OpenSSH` cryptography. -This repository contains the code to share itself (the repository) through -Git-over-SSH. It can be merged into other repositories, turning them -self-sharing. +A `Self-Forge` relieves the owner of the repository and the repository's other +contributors from all needing to share a common "hub" `Forge` before the owner +can accept a contribution. Instead, users need only `IP` connectivity to the +machine containing the repository. -It also contains the code to listen for changes sent to itself through -Git-over-SSH. +The contributions are stored in namespaces according to the public keys of the +contributors. This prevents collisions. +(It is also possible to do _without_ `IP` connectivity using DHT connectivity; +see `tuntox.git`.) +## WHAT IS A `Forge` +A `Forge` is a "place" where programmers share source code. (Anyone could share +any content, in principle. The point is to track past changes.) The largest +`Forge`, for example, is Microsoft's `GitHub`. +Note that a `Forge` is different from a web site. A `Git`-based `Forge` must +accept contributions in the `Git-Over-SSH` protocol. That is the convenient and +standard way to use `Git`. +Nevertheless, the typical `Forge` requires users to go sign up for some web +service before they can connect using `Git`'s native language of `SSH`. +`EndoForge` uses the key provided by the `SSH` client. -HOW IT WORKS ------------- +Using a `Self-Forge` relieves users of dependency on any troublesome +intermediary `Forge`. You get your own `Forge`. You are your own `Forge`. + +## What is `Git-Over-SSH` + +`Git-Over-SSH` is the standard `Git` protocol for _both reading and writing_ a +repository. It is the same `Git` protocol one uses when _pushing_ to +`github.com` or any other `Git`-based `Forge`. + +`Git` has other protocols for read-only access, including `Git-Over-HTTPS`. That +type of access to a `Git` repository, including domain name and CA certificate, +can be provided via `CGit` by running `selfpublish.sh`. + +HOW TO ACCESS A SELF-FORGE +-------------------------- -Git contains a program `git-receive-pack` which implements a git -protocol server. The `git-receive-pack` expects to be launched as an SSH -server "ForcedCommand" in a configuration that protects the server from -untrustworthy users. +Users can run `git clone` on your `SSH` address, like this: -Normally, the SSH server only permits users who have already uploaded -their public keys to the server. It assumes that access should be closed -to new users. +[TODO: edit document dynamically to get real values here] +``` + git clone $(id -u)@$(hostname):$(pwd) +``` -Installing this code reverses that assumption, granting open access to -unrecognized users. This is made safe by limiting write access to a -GIT_NAMESPACE over which the user proves global mathematical ownership with -their SSH client key. This means that the user cannot overwrite anyone else's -data. +They can then commit changes to the repository, and push them back to `origin`. -The user's uploaded data is still saved and is ready to be be merged into the -main repository manually, or even automatically. Automatic merging could be -authorized on the basis of the public key, or through a consensus algorithm -comparing branches signed by many different keys. +The changes will exist in a separate space from where any other user can +overwrite. The cryptography of `OpenSSH` makes this possible. +HOW IT WORKS +------------ +Normally, `OpenSSH` server only permits connections from users whose keys have +been pre-authorized on the server. `OpenSSH` assumes that access should be +closed to new users. Installing `EndoForge` modifies the `OpenSSH` server +configuration so that this assumption is reversed. Access is opened to unknown +users. +Anonymous users are forced to run the command `~/.ssh/AnonymousAccessCommand` +upon login, instead of whatever command they select for themselves. The user can +choose or configure their `AnonymousAccessCommand` to provide sandboxing, or to +implement a user authentication scheme in some flexible way. +`EndoForge` installs a `~/.ssh/AnonymousAccessCommand` that allows anonymous +users to run the `Git` protocol commands (`git-receive-pack`, etc.) to access +repositories available on the system. A repository must be configured +`core.self-forge true` to allow this access. -HOW TO INSTALL +INSTALLATION -------------- Run: ``` - make install + make install ``` This installs the `AnonymousAccessCommand` in the current user's home directory (under `$HOME/.ssh`). -Then, if sudo access is available, it enables anonymous access by -editing the system `OpenSSH` configuration. +Then, if sudo access is available, it enables anonymous access by editing the +system `OpenSSH` configuration. This allows any user to listen for `SSH` +connections via the file `$HOME/.ssh/AnonymousAccessCommand`. +Finally, the command to enable public access to the `Self-Forge` may be run: +Run: +``` + git config core.self-forge true +``` + +Note that, once installed, you can run this in ANY repository. + +You can also run `make shared` but that just runs the same `git config` for you. +## HOW TO DISABLE +To disable public access to the repository, run: +``` + git config core.self-forge false +``` NON-ROOT INSTALLATION --------------------- @@ -77,12 +135,14 @@ A systemd unit file to run `OpenSSH` as an unprivileged user is included. The configuration file sets the port to `22022`. -This type of installation is vastly inferior to running as root, because only -root can make `OpenSSH` listen on port `22`, as it is designed to do. +This type of installation is vastly inferior to one requiring root, because +`OpenSSH` is much easier to connect to servers that listen on port `22` than any +other port. The `install-user` target runs the unprivileged `OpenSSH` server. ``` - make install-user + make install-user ``` +The script `selftest.sh` tests connecting to the port 22022 server. -- cgit v1.2.3