Package: git-foolscap
https://github.com/warner/git-foolscapgit-foolscap is an extension for Git that allows you to publish or access Git repositories over the [Foolscap](http://foolscap.lothar.com/trac) protocol. This provides all the security benefits of ssh or authenticated HTTPS, but with a few important benefits:downstream users do not need an account on the server: merely sharing the secret FURL string with them is enough to provide accessaccess is limited to the one repository: users do not get full shell accessservers are quick and easy to set upusers can easily be limited to read-only access## InstallationJust usepip install git-foolscap. This will install two scripts into your $PATH:git-foolscapandgit-remote-pb. The former is the main entry point, and Git will run it whenever you rungit foolscap COMMAND... The latter implements the remote protocol, and Git will use it whenever you access a repository whose remote URL starts with “pb:” (i.e. it is a FURL).git-foolscap depends upon having Foolscap installed, which depends upon Twisted and pyOpenSSL.git-foolscap -handgit-foolscap –helpwill provide usage instructions. (Note thatgit foolscap –help, without the hyphen, doesn’t work, becausegit-foolscapdoes not provide a man page).## Theory Of OperationRepositories are published by running a small server (a Foolscap “flappserver”) which listens on a TCP port for encrypted connections. A “FURL” is allocated which will connect to the git remote protocol (in either read+write or read-only mode) for a specific repository. This FURL can be handed to clients, which merely use it as the URL for a standard git remote (e.g.git clone FURLorgit remote add NAME FURL). Foolscap FURLs are URIs which use “pb:” as their scheme instead of “http:” or “https:”.When a git client encounters thepb:FURL, it delegates control to a program namedgit-remote-pb(this is a standard feature of git, and holds true for arbitrary scheme names). Thegit-remote-pbprogram knows how to use Foolscap to connect to the target FURL and speak the git remote protocol through it.Technically, this means that servers only need thegit-foolscapexecutable, and clients only need thegit-remote-pbexecutable, but both are distributed in the same package for simplicity.## Usage: ServerSeegit foolscap –helpfor full details. Basically the server does this part once:` % git foolscap init--port=tcp:3116--location=tcp:HOSTNAME:3116% git foolscap start `and this part for each new client:` % git foolscap inviteread-write"comment about recipient" `The “invite” will produce a “wormhole code”, which the receiving user must type into their “accept” command. The secure FURL will then be sent through the wormhole.The FURLs can also be added (without invitation) usinggit foolscap add. It must then be cut-and-pasted to the recipient.To provide read-only access to a single repository, replaceread-writewithread-only. You can create as many FURLs as you like, by runninggit foolscap addorinvitemultiple times. Each can be revoked separately. To revoke access, rungit foolscap list, find the index number, and pass it intogit foolscap revoke.You may want to arrange forgit foolscap startto be run from a cron@rebootjob, or other boot-time startup script, to make sure that access is retained across a system reboot.@reboot cd PATH/TO/REPO && git foolscap start## Usage: ClientIf the repository owner usedgit foolscap invite, then you simply type this code into:` % git foolscap accept clone `The client can use tab-completion on the codewords, and the wordlist is specifically designed to be reliably transcribeable over a noisy voice channel.Instead of cloning a new copy of the repository, you can add the new FURL to an existing repo, by running this command from inside the repository:` % git foolscap acceptadd-remote`If the publisher usedgit foolscap addand sent you a full FURL (instead of a wormhole code), then you can just clone from it as you would a normal HTTPS (https://github.com/warner/git-foolscap.git) or SSH (git@github.com:warner/git-foolscap.git) URL. As long as you have git-foolscap installed, git will figure out how to do the right thing.## Cleaning up the FURLThe flappserver uses the–location=you provide to construct the “connection hints” portion of the FURL. This tells the client how to connect to the server. The server must have a publically-reachable address (or at least reachable by your clients), or you must configure a port-forwarding and put the externally-reachable address+port into the FURL.If you got the hostname wrong, or if you used an IP address and it has changed, you can edit the FURL later. You can also use multiple hints, and the client will try to connect to each of them until at least one works:pb://tvzddtbzbldthde5kdsvjvzpweifx7ae@tcp:example.com:57306,tcp:example.org:57306/jmxpcs6lsmgtuzdomxbgtfcmhgfmfbpc/my-repoThe first big random-looking string in the FURL identifies exactly which server public key is expected: it provides cryptographic assurance that the connection will go to the right server. No certificate authorities or trusted third parties are used. The second random string is a secret “swissnum” which securely identifies the resource being accessed (in this case, a table entry which points at a git repository and a read+write/read-only mode). Knowledge of this secret enables access: to share access, share the secret (and the rest of the FURL necessary to use it); to withhold access, don’t reveal the secret.## Configuring the flappserverEach flappserver has a “base directory” where it keeps all its state.git foolscap createdefaults to using.git/foolscap/for this purpose, creating it if necessary, then adding an entry for the new FURL.If you publish multiple repositories, you might want to share flappservers between them, especially if you must configure a port forwarding for each server. To do this, first create the one shared server with Foolscap’sflappserver create BASEDIRcommand, then use the–flappserver=BASEDIRargument when runninggit foolscap init. This establishes a symlink from.git/foolscapto the real BASEDIR, so subsequent git-foolscap commands will add an entry to that flappserver directly. If BASEDIR doesn’t already exist, it will be created.Note that at present,git foolscap init –flappserver=BASEDIRrequires the–port=and–location=arguments, even if BASEDIR already exists. However, in that case, their values are ignored in favor of the BASEDIR’s existing configuration. Hopefully this will be fixed in a future release.If you use a@rebootcronjob, you may want to useflappserver startdirectly, instead ofgit foolscap start.## Bugs, PatchesPlease file bugs and patches for git-foolscap on the Github issue tracker, athttps://github.com/warner/git-foolscap.For bugs and patches against foolscap itself, please use the Foolscap Trac, athttp://foolscap.lothar.com/trac. Foolscap source code is published on Github, athttps://github.com/warner/foolscap.thanks!