<commit_before># Upspin Access Control

## Introduction

This document describes the access control model for Upspin.

All such information is maintained by files in the Upspin name space itself.
In particular, all the information necessary to decide the accessibility of an
item in the tree under user U's root is available to the Directory server
holding U's root.

Despite the length of this document, the general model is very simple.
Plain text files describe what rights are granted, saying for instance that a
given user may read files.
These rules apply at the directory level and are inherited by subdirectories.
By default, with no such access control files in a user's tree, that user and
only that user has the right to read or modify the files.

## Users

By user, we mean an account known to the Upspin Key service, identified by an
e-mail-like name: `<EMAIL>`.
Each valid user has a *user* *root* directory held on at least one Directory
server.
Each user proves identity to Upspin servers,
their own and others',
using the user's key pair registered in the central Key server.

## Groups

A group identifies a list of users, the *members* of that group.
Each group is associated with a single user, its *owner*, and the owner is
implicitly a member of every group that the user owns.

The membership of a group is defined by the contents of a file in the Group
subdirectory of the owner's user root, and the path name of that file is the
global name of the group.
Within that file is a list of the members, separated by white space and/or
commas.

For example, `<EMAIL>` might define a group for her family.
She would define that group by creating a file, say
`<EMAIL>/Group/family`, and writing to it something like,

```
<EMAIL>
<EMAIL>
<EMAIL>
```

Once that file is created, the group called `<EMAIL>/Group/family` is
defined to contain those users, plus `<EMAIL>` herself, as members.

The full name `<EMAIL>/Group/family` is cumbersome, but as we will see
in the next section, when `<EMAIL>` wants to identify this group, it
will usually be in the context of her own directory tree, and just the final
component, `family`, is sufficient to identify it.

`Group` files are always readable and writable by the owner, but otherwise act
as regular items within the Upspin name space as far as client I/O is concerned.

`Group` files can be placed directly in the `Group` directory of the user's
root, or in subdirectories of that `Group` directory.
The name of the group will always be the full Upspin path, including user name,
of the group definition file.
The advantage of using subdirectories is that the access control mechanisms of
Upspin, which operate at the directory level (see the next section), make it
possible to have a particular group's membership be public or private as
appropriate.
`Group` files are plain files in all respects.

## Access control model

Absent any other information, every item in the user's Upspin tree is readable
and writable only by the owner, that is, the user whose root begins the path
name of the item.
By default, then, `<EMAIL>/foo/bar` is a file owned and accessible only
by `<EMAIL>`.
However, the access rights may be modified by the presence of an access control
file in the directory `foo` that holds `bar`, or by an access control file in
`foo`'s parent, and so on.

Access control files may be placed in any directory, including a user root.
They define the access rights that apply to the directory itself, its contents,
its subdirectories, and so on, recursively.
However, if an access control file exists in a directory, the access rights it
grants completely override those granted through the recursive inheritance
mechanism, with some special exceptions for the owner.<commit_msg>doc: clarify permission to Group files<commit_after># Upspin Access Control

## Introduction

This document describes the access control model for Upspin.

All such information is maintained by files in the Upspin name space itself.
In particular, all the information necessary to decide the accessibility of an
item in the tree under user U's root is available to the Directory server
holding U's root.

Despite the length of this document, the general model is very simple.
Plain text files describe what rights are granted, saying for instance that a
given user may read files.
These rules apply at the directory level and are inherited by subdirectories.
By default, with no such access control files in a user's tree, that user and
only that user has the right to read or modify the files.

## Users

By user, we mean an account known to the Upspin Key service, identified by an
e-mail-like name: `<EMAIL>`.
Each valid user has a *user* *root* directory held on at least one Directory
server.
Each user proves identity to Upspin servers,
their own and others',
using the user's key pair registered in the central Key server.

## Groups

A group identifies a list of users, the *members* of that group.
Each group is associated with a single user, its *owner*, and the owner is
implicitly a member of every group that the user owns.

The membership of a group is defined by the contents of a file in the Group
subdirectory of the owner's user root, and the path name of that file is the
global name of the group.
Within that file is a list of the members, separated by white space and/or
commas.

For example, `<EMAIL>` might define a group for her family.
She would define that group by creating a file, say
`<EMAIL>/Group/family`, and writing to it something like,

```
<EMAIL>
<EMAIL>
<EMAIL>
```

Once that file is created, the group called `<EMAIL>/Group/family` is
defined to contain those users, plus `<EMAIL>` herself, as members.

The full name `<EMAIL>/Group/family` is cumbersome, but as we will see
in the next section, when `<EMAIL>` wants to identify this group, it
will usually be in the context of her own directory tree, and just the final
component, `family`, is sufficient to identify it.

`Group` files are always readable and writable by the owner, and only the owner
can create and edit them, but otherwise they act as regular items within the
Upspin name space as far as client I/O is concerned.

`Group` files can be placed directly in the `Group` directory of the user's
root, or in subdirectories of that `Group` directory.
The name of the group will always be the full Upspin path, including user name,
of the group definition file.
The advantage of using subdirectories is that the access control mechanisms of
Upspin, which operate at the directory level (see the next section), make it
possible to have a particular group's membership be public or private as
appropriate.
`Group` files are plain files in all respects.

## Access control model

Absent any other information, every item in the user's Upspin tree is readable
and writable only by the owner, that is, the user whose root begins the path
name of the item.
By default, then, `<EMAIL>/foo/bar` is a file owned and accessible only
by `<EMAIL>`.
However, the access rights may be modified by the presence of an access control
file in the directory `foo` that holds `bar`, or by an access control file in
`foo`'s parent, and so on.

Access control files may be placed in any directory, including a user root.
They define the access rights that apply to the directory itself, its contents,
its subdirectories, and so on, recursively.
However, if an access control file exists in a directory, the access rights it
grants completely override those granted through the recursive inheritance
mechanism, with some special exceptions for the owner.
{'fraction_non_alphanumeric': 0.049795810828612834, 'fraction_numerical': 0.0, 'mean_word_length': 4.4618705035971225, 'pattern_counts': {'":': 0, '<': 27, '<?xml version=': 0, '>': 27, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6573141', 'n_tokens_mistral': 1967, 'n_tokens_neox': 1903, 'n_words': 1262}