From f61964b98e8584ed0613bf8b96a06c0cf7544ebb Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <liw@liw.fi>
Date: Sat, 12 Oct 2013 11:31:20 +0100
Subject: Describe ACL requirements and design

---
 git.liw.fi.yarn | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 66 insertions(+), 2 deletions(-)

diff --git a/git.liw.fi.yarn b/git.liw.fi.yarn
index d91c311..0808b3f 100644
--- a/git.liw.fi.yarn
+++ b/git.liw.fi.yarn
@@ -8,8 +8,72 @@ against either the real or a test instance of the setup. It requires
 the person running it to have admin access on the Gitano instance,
 so the tests can create and remove users and repositories.
 
-Pre-requisites
-==============
+ACL design
+==========
+
+Requirements
+------------
+
+I want to run a git server primarily for my own use. I may later
+offer hosting of particular repositories for friends, or Soile,
+but we'll see. I want to have both public and private repositories,
+and I want to allow others' limited push access to some repos,
+to make collaboration easier. I don't want others to be able to
+create repos, I think, but not sure about that yet.
+
+I'll want to host all of my free software projects on my server,
+and also some private repositories, such as my personal journal.
+
+Possible design
+---------------
+
+All access control will be granted via memberships in groups.
+
+* `gitano-admin` is the built-in superuser group, whose members
+  can do anything. Most importantly, they can administer users
+  and create top-level repositories.
+  - I am the only admin, at least for now
+* `trusted` is for people whom I trust to not abuse their priviledges.
+  They can push anything to any public non-personal repository, and
+  can create their own repositories under `personal/${user}/` and
+  `private/${user}/`.
+* `guest` can push to branches prefixed with `${user}/` in any
+  public repo, and anything to any repo they own. They can't
+  create any repos, but a `gitano-admin` may create one for them.
+
+For my free software projects, which are public, anyone can clone them
+(over the git protocol), and browser their source code (with cgit). If
+they provide useful patches and want to have an account on my server
+to make collaboration easier, I can make them a guest account. That
+allows them to push their changes to a branch, from which I can review
+and merge them.
+
+The trusted group is not meant for making it easier for collaborators
+to start merging to my free software project master branches. The
+access control is too coarse for that. It is, instead, meant for
+allowing friends host their own stuff on my server.
+
+Simple design
+-------------
+
+However, setting up groups and stuff is currently unnecessary. I
+will instead have a simpler setup:
+
+* `gitano-admin` can do anything.
+* Everyone else can access public repos and push to branches
+  prefixed with their username.
+* Private repos are under the `private/` prefix, and I'll add
+  my username to allow others to have them in the future.
+  Private repos are not visible via cgit or over the git protocol,
+  and can only be accessed over ssh by a `gitano-admin` (which is
+  only me, for now).
+
+This is what the test suite is meant to test. It is a simple design
+that I can, later, improve upon to add more groups, and give people
+more detailed control and access.
+
+Test suite pre-requisites
+=========================
 
 Yarn must be run with `--env` used to set the environment variables
 `GITANO` and `GITHOST`. `GITANO` must be the Unix user for the
-- 
cgit v1.2.1