readme

1 files 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.