~ivilata/gwit-spec

123b65281beffffeec417cdabe1408bd596b0ded — Ivan Vilata-i-Balaguer 2 months ago 723cc3f
State mapping of locations with Git remotes & URLs as basic concept.

Otherwise it is introduced too late (initial retrieval) and dispersed among
several places.  Besides making the concept more relevant, this also allows
refactoring some redundant sentences here and there (or at least get to them
with a little more context).
1 files changed, 4 insertions(+), 2 deletions(-)

M README.md
M README.md => README.md +4 -2
@@ 9,7 9,7 @@ gwit inherits many of Git's distributed properties:
- Someone who accesses a gwit site for the first time gets a full copy (a Git clone) of it, including previous versions.

  The whole site becomes thus available without further network access, enabling offline reading and search.
- Updates to the site may be fetched from other locations which host copies of the site (using whatever means supported by Git to access remote repositories, or "remotes").
- Updates to the site may be fetched from other locations which host copies of the site (Git remotes).

  A location may be some local external media (like a USB drive), allowing sneakernet scenarios. Also, a local copy of a gwit site may be made available to others, thus increasing site availability (also for archival and censorship circumvention purposes).
- To verify the authenticity of site content coming from diverse locations, gwit makes use of Git's support of PGP signatures over commits.


@@ 53,6 53,8 @@ A gwit site is just *a Git repository branch associated with a PGP public key* w

This means that the relation between site and site key is one-to-one: if an author wants to create another site, then a new site key MUST be created. Thus, using one's day-to-day PGP key as a site key is NOT RECOMMENDED. The mechanisms to relate a site (and its key) to a particular identity outside of gwit are out of the scope of this specification.

To get content from a site, one needs to know at least one accessible location that hosts a copy of it. That location MUST be a Git repository (a "remote"), and it MUST be represented by a local file system path or other URL allowed by Git for a remote.

As gwit site identifiers are not meaningful nor memorable to humans, some support is provided to allow using **petnames** for sites. This specification uses the concepts of petname, edge name, and (self-)proposed name from the paper [Petnames: A humane approach to secure, decentralized naming][petnames].

[petnames]: https://spritely.institute/static/papers/petnames.html


@@ 172,7 174,7 @@ remote = https://lab.example.org/s.one/gwit-site.git
If someone wants to use a client program to retrieve a gwit site for the first time, then the client MUST know:

- The site identifier, i.e. the site key fingerprint. This MUST be a string of hexadecimal digits.
- The location of an existing copy of the site, accessible to it (either locally or remotely). This MUST be a local file system path or other URL format supported by Git for a remote.
- The location of an accessible copy of the site. This MUST be the URL of a Git remote.

These ID/location pairs may be conveyed to the client via different methods (like person-to-person, search engines, or site directories), however this specification only covers the discovery mechanism described further above, where each site can provide a number of introductions for other sites with their respective ID and locations. At any rate, the choice among a variety of available locations for the initial retrieval of a particular site is up to the implementation.