proposals/authorization-ucr/index.bs

<pre class='metadata'>
Title: Use Cases and Requirements for Authorization in Solid
Shortname: authorization-ucr
Level: 1
Max ToC Depth: 2
Status: w3c/ED
Group: solid-cg
URL: https://solid.github.io/authorization-panel/authorization-ucr/
Editor: Solid Editorial Team
Markup Shorthands: markdown yes
Abstract:
  Use Cases and Requirements for Authorization in Solid.
</pre>

<!-- For bikeshed style overrides -->
<style>

  table.collections thead tr {
    font-size: 16px;
  }

  table.collections tbody tr:nth-child(even) {
    background-color: lightgray;
    font-size: 12px;
  }

  @media (prefers-color-scheme: dark) {
    table.collections tbody tr:nth-child(even) {
      background-color: DarkSlateGray;
    }
  }

  table.collections tbody td {
    font-size: 12px;
  }

  figcaption {
    text-align: left;
  }

  a[data-link-type=dfn] {
    color: #000000;
  }

  .assertion {
    font-size: small;
  }

  @media (prefers-color-scheme: dark) {
    a[data-link-type=dfn] {
      color: #FFFFFF;
    }
  }

}

</style>

<div boilerplate="copyright">
MIT License Copyright 2019 - 2020 W3C Solid Community Group
</div>

Introduction {#intro}
================================================================================

The [[#usecases]] in this document represent real-world scenarios that
a Solid authorization system should support. The [[#requirements]] in this
document are derived from those use cases, and will inform and guide
the contents of a subsequent specification proposal.

Use Cases {#usecases}
================================================================================

Unless stated otherwise, the use cases herein assume that named
individuals (e.g., Alice, Bob, Carol, etc.) are already
[=authenticated agents=], and their corresponding [=identities=] are known
by the [=resource controller=] when they are granted access.

## Resource access ## {#uc-basic}

Alice has a private draft of her resume stored on her [=resource server=] at
`https://alice.example/resume`. Alice is the [=resource controller=]
for that resource.

<figure>
<figcaption>Alice's resume and recommendations resources at https://alice.example</figcaption>
  <table class="data collections" align="left">
    <col>
    <col>
    <col>
    <thead>
      <tr>
        <th scope="col">Resource</th>
        <th scope="col">Type</th>
        <th scope="col">Description</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>`resume`</td>
        <td>[=Resource=]</td>
        <td>Alice's curriculum vitae</td>
      </tr>
      <tr>
        <td>`recommendations`</td>
        <td>[=Resource=]</td>
        <td>Recommendations for Alice</td>
      </tr>
    </tbody>
  </table>
</figure>

### Change permissions ### {#basic-change-permissions}

Alice asks Bob to help make her resume more presentable. Alice must give Bob
permission to do this, because `resume` is not a public resource, and as the
[=resource controller=] Alice is the only one who can manage permissions for
it.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-change-permissions]]

</div>

### Read permissions ### {#basic-read-permissions}

Jasmine is a recruiter that has been helping Alice with job placement. Alice
gives Jasmine the ability to read the permissions on `resume`, so that
she can see who else Alice has shared her resume with.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-read-permissions]]

</div>

### Read-write access ### {#basic-write}

Alice gives Bob [=read access=] so that he can read the `resume` resource, and
[=write access=] so that he can make changes to it, which he does.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-read]]
* [[#req-write]]

</div>

### Read-append access ### {#basic-readappend}

#### Alice stores Danielle's recommendation #### {#basic-readappend-single-storage}

Danielle agrees to give Alice a personal reference, which Alice will include
in the references section of `resume`. Alice gives Danielle [=read access=] to
`resume` for context, and [=append access=] so that she can only add new data
to `resume`, and cannot change any existing data within it. Danielle adds a
glowing reference for Alice to `resume`.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-read]]
* [[#req-append]]

</div>

#### Danielle stores their own recommendation #### {#basic-readappend-multi-storage}

Danielle agrees to give Alice a personal reference, which Alice will link to
in the reference section of `resume`. Alice gives Danielle [=read access=] to
`resume` for context, and [=append access=] so that she can add a link to the
recommendation that she creates and hosts on her own [=resource server=] at
`https://danielle.example/recommendation`. Danielle is the [=resource
controller=] for that resource and gives it public [=read access=].

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-read]]
* [[#req-append]]

</div>

### Append-only access ### {#basic-appendonly}

Alice is interested in seeing whether any of her other contacts might
provide good recommendations that she can include as additional references
or a resume cover letter.

She creates a `recommendations` resource, and grants [=append access=] to the
`contacts` [=authorization group=], which represents every professional
contact in her virtual rolodex. She sends a mass-mail to `contacts`, with a
link to an app they can use to submit a recommendation, which will be appended
to `recommendations`. Since they only have [=append access=] and not [=read access=],
they can add to `recommendations` but they cannot see
recommendations that have already been added.

<div class="assertion">

* [[#req-agent-group]]
* [[#req-append]]

</div>

### Removing access ### {#basic-removing}

Alice removes Bob and Danielle's access to `resume`, since they've both
finished contributing to it. They can no longer read or make changes to it.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-change-permissions]]

</div>

### Read-only access ### {#basic-readonly}

Alice has a job interview with Carol. Alice gives Carol [=read access=] to
`resume` ahead of the interview.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-read]]

</div>

### Group access ### {#basic-group}

Alice has additional interest, and is now interviewing with people from
multiple organizations, including Carol, Oscar, and Frank.

To make it easier to keep track of everyone, Alice creates an `interviewing`
[=authorization group=] and adds Carol, Oscar, and Frank to it. She grants
[=read access=] on `resume` to the `interviewing` [=authorization group=].

Alice removes any individual permissions on `resume` that were granted to
members of the `interviewing` [=authorization group=] since they are no longer
necessary.

Now Alice can add new people she's interviewing with to the `interviewing`
[=authorization group=], and remove them when the opportunity is no longer
active. This is much more intuitive and easy for Alice.

<div class="assertion">

* [[#req-agent-group]]
* [[#req-read]]

</div>

### Public access ### {#basic-public}

Alice decides `resume` is ready to share with everyone, so she gives
[=read access=] to the public (everyone), and shares a link to it on
several job boards.

<div class="assertion">

* [[#req-public]]
* [[#req-read]]

</div>

### Logged in access ### {#basic-authenticated}

Alice runs an open online workshop for a few people she works with but also
she sends an invitation to a public mailing list suggesting experts in her
field should also come.

She sets the access to the materials so that anyone who has a solid ID can log
in and access it. (They have read access to the agenda, and write access to
the minutes, say).

She uses an app which accumulates the set of Ids of the people who have used
this access as a group.

People who follow her link to the materials are prompted by the system to log
in, or if necessary to make a new solid account and then log in.

After the workshop is over, she changes the access on the materials to
explicitly be that group.

<div class="assertion">

* [[#req-authenticated]]
* [[#req-read]]
* [[#req-write]]
* [[#req-agent-group]]

</div>

## Collection access ## {#uc-collections}

Note: These use cases are focused on access to a [=collection=] itself. Use
cases that focus on permissions related to [=resources=] included in that
[=collection=] are covered in [[#uc-inheritance]].

Alice has a portfolio [=collection=] stored on her [=resource server=] at
`https://alice.example/portfolio/`, which she is the [=resource controller=]
for. She provides access to the `portfolio` to potential employers as she
moves through a job interview process.

The `portfolio` [=collection=] includes [=resources=] representing individual
deliverables she's produced throughout her career, along with [=collections=] of
deliverables from larger scale projects that she's worked on.

The `portfolio` [=resource=] itself includes summary information about the
portfolio as a whole. For example, Alice details why she chose to include
the items together as a representation of her work.

<figure>
<figcaption>Alice's portfolio and opportunities [=collections=] at
https://alice.example/</figcaption>
  <table class="data collections" align="left">
    <col>
    <col>
    <col>
    <thead>
      <tr>
        <th scope="col">Resource</th>
        <th scope="col">Type</th>
        <th scope="col">Description</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>`portfolio/`</td>
        <td>[=Collection=]</td>
        <td>Resource includes summary information about the portfolio as a
        whole. Member [=resources=] include individual documents she's produced,
        and collections of deliverables from projects she's worked on.</td>
      </tr>
      <tr>
        <td>`-- document1`</td>
        <td>[=Resource=]</td>
        <td>Individual document</td>
      </tr>
      <tr>
        <td>`-- document2`</td>
        <td>[=Resource=]</td>
        <td>Individual document</td>
      </tr>
      <tr>
        <td>`-- project1/`</td>
        <td>[=Collection=]</td>
        <td>Individual document</td>
      </tr>
      <tr>
        <td>`---- documentA`</td>
        <td>[=Resource=]</td>
        <td>Project document</td>
      </tr>
      <tr>
        <td>`---- MovieA`</td>
        <td>[=Resource=]</td>
        <td>Project movie file</td>
      </tr>
      <tr>
        <td>`opportunities/`</td>
        <td>[=Collection=]</td>
        <td>Storage for descriptions of various different job opportunities
        Alice is interested in</td>
      </tr>
      <tr>
        <td>`comments/`</td>
        <td>[=Collection=]</td>
        <td>Storage of comments on Alice's portfolio</td>
      </tr>
    </tbody>
  </table>
</figure>

### Read-only access to a Collection ### {#collection-readonly}

Alice has identified several companies that she'd like to work for, as well as
the specific people (Carol, Oscar, and Frank) to contact at each one.

Alice sends individual e-mails to Carol, Oscar, and Frank with links to her
`resume` and `portfolio`.

Alice has granted Carol, Oscar, and Frank [=read access=] to her `resume`
which allows them to read its contents fully.

Alice has also granted them [=read access=] to the `portfolio` [=collection=].
She only wants them to see summary detail about the `portfolio` [=collection=]
itself, along with a listing of its contents, but not the contents of the
[=resources=] included in that [=collection=].

Alice wants to know which of them are really interested based on who asks her for
more access to the contents of the resources in `portfolio`.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-read]]
* [[#req-collection-read]]

</div>

### Read-write access to a Collection ### {#collection-readwrite}

Alice is revising the summary description of her `portfolio`, which is
stored in the [=resource=] for the `portfolio` [=collection=].

Milo is Alice's friend, and she enlists his help in reviewing and revising
her summary.

Alice gives Milo [=read access=] and [=write access=] to the `portfolio`
[=collection=] itself, which allows him read and modify the existing summary
in the `portfolio` [=resource=].

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-read]]
* [[#req-collection-write]]

</div>

### Read-create access to a Collection ### {#collection-readcreate}

Alice worked with Bob on a past project, and she has added a partial set
of the final project deliverables to the `project1` [=collection=]. She
knows that Bob has the rest, and he agrees to provide them.

Alice grants Bob the following access on the `project1` [=collection=]:

* [=Read access=] which allows him to see the summary detail of `project1`
    stored in the `project` [=resource=] itself, as well as
    a list of the [=resources=] in the [=collection=], which lets him confirm
    whether his uploads are stored successfully.
* [=Create access=] on `project1`, which allows him to add new [=resources=]
    to it.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-read]]
* [[#req-collection-create]]

</div>

### Read-create-delete access to a Collection ### {#collection-readcreatedelete}

Note: Despite this section's focus on permissions specific to the collection
resource itself, this use case also incorporates inherited read access to
better illustrate the scenario.

Over time Alice has asked her colleagues to leave comments on her `portfolio`,
which are stored in the `comments` [=collection=].

When she asks a colleague to leave a comment, she gives them the following
permissions:

* [=Read access=] to the `comments` [=collection=]
    so they can list existing comments (including their own).
* Inherited [=read access=] to the [=resources=] in the `comments` [=collection=],
    so they can read the contents of existing comments (including their own).
* [=Create access=] to the `comments` [=collection=], which allows them to
    add new comments, but not change any that exist already.
* Default permissions on new [=resources=] in `comments` that stipulate:
    * [=Delete access=] for the creator of a [=resource=] - so they can delete
        their own comments if they like, but no one else's.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-read]]
* [[#req-inheritance-readonly]]
* [[#req-collection-creator]]
* [[#req-collection-create]]
* [[#req-collection-delete]]

</div>

### Create-only access to a Collection ### {#collection-createonly}

Alice realizes it would be helpful if Carol, Oscar, and Frank could provide
her with job opportunities that they think she would be a fit for at their
respective organizations.

She provides them with [=create access=] to the `opportunities`
[=collection=]. This allows each of them to add new [=resources=] to
`opportunities`, without the ability to see the listing of other [=resources=]
in the [=collection=], or modify them. This means that they can each add
opportunities, but none of the others will see them.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-create]]

</div>

### Manage permissions for a Collection ### {#collection-control}

Bob reminds Alice that some of the other people who worked on `project1` may
also have materials they can add to the `portfolio`, but he needs to lookup
their information.

Alice trusts Bob with the contents of the `project1` collection, since it's
the output of their shared work. She gives him [=read permission access=]
and [=write permission access=] to `project1` so that he can help her
invite other colleagues from the past to add [=resources=] to it.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-read-permissions]]
* [[#req-collection-change-permissions]]

</div>

## Collection resource inherited access ## {#uc-inheritance}

Bob is leading a group of colleagues doing field research. This group
includes Charles, Felicia, Juan, and Irene.

The group uses a [=resource server=] for storing their information at
`https://research.example/`, which Bob administers as the [=resource
controller=].

Bob creates an [=authorization group=] called `research`, and adds Charles,
Felicia, Juan, and Irene to it.

<figure>
<figcaption>Contents of the research group's data store at
https://research.example/</figcaption>
  <table class="data collections" align="left">
    <col>
    <col>
    <col>
    <thead>
      <tr>
        <th scope="col">Resource</th>
        <th scope="col">Type</th>
        <th scope="col">Description</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>`weekly-status/`</td>
        <td>[=Collection=]</td>
        <td>Bob's notes from weekly status meetings with colleagues</td>
      </tr>
      <tr>
        <td>`-- 12-23-2019.note`</td>
        <td>[=Collection=]</td>
        <td>Text stored in collection resource, subordinate data
        and media included in collection</td>
      </tr>
      <tr>
        <td>`---- recording.mp4`</td>
        <td>Video</td>
        <td>Recorded audio/video of web conference meeting</td>
      </tr>
      <tr>
        <td>`-- 12-30-2019.note`</td>
        <td>[=Collection=]</td>
        <td>Text stored in collection resource, subordinate data
        and media included in collection</td>
      </tr>
      <tr>
        <td>`---- img1.png`</td>
        <td>Image</td>
        <td>Inline picture included in text of note</td>
      </tr>
      <tr>
        <td>`---- img2.png`</td>
        <td>Image</td>
        <td>Inline picture included in text of note</td>
      </tr>
      <tr>
        <td>`---- recording.mp4`</td>
        <td>Video</td>
        <td>Recorded audio/video of web conference meeting</td>
      </tr>
      <tr>
        <td>`-- 01-06-2020.note`</td>
        <td>[=Collection=]</td>
        <td>Text stored in collection resource, subordinate data
        and media included in collection</td>
      </tr>
      <tr>
        <td>`---- recording.mp4`</td>
        <td>Video</td>
        <td>Recorded audio/video of web conference meeting</td>
      </tr>
      <tr>
        <td>`daily-metrics/`</td>
        <td>[=Collection=]</td>
        <td>Daily device reading for group research</td>
      </tr>
      <tr>
        <td>`-- Jan-01-2020`</td>
        <td>[=Resource=]</td>
        <td>Daily reading</td>
      </tr>
      <tr>
        <td>`-- Jan-02-2020`</td>
        <td>[=Resource=]</td>
        <td>Daily reading</td>
      </tr>
      <tr>
        <td>`-- Jan-03-2020`</td>
        <td>[=Resource=]</td>
        <td>Daily reading</td>
      </tr>
      <tr>
        <td>`-- Jan-04-2020`</td>
        <td>[=Resource=]</td>
        <td>Daily reading</td>
      </tr>
      <tr>
        <td>`-- Jan-05-2020`</td>
        <td>[=Resource=]</td>
        <td>Daily reading</td>
      </tr>
      <tr>
        <td>`-- Jan-06-2020`</td>
        <td>[=Resource=]</td>
        <td>Daily reading</td>
      </tr>
      <tr>
        <td>`-- Jan-07-2020`</td>
        <td>[=Resource=]</td>
        <td>Daily reading</td>
      </tr>
      <tr>
        <td>`daily-summaries/`</td>
        <td>Collection</td>
        <td>Daily analysis for group research</td>
      </tr>
      <tr>
        <td>`-- Jan-01-2020`</td>
        <td>[=Resource=]</td>
        <td>Peer reviewed analysis for Jan 1</td>
      </tr>
      <tr>
        <td>`-- Jan-02-2020`</td>
        <td>[=Resource=]</td>
        <td>Peer reviewed analysis for Jan 2</td>
      </tr>
      <tr>
        <td>`-- Jan-03-2020`</td>
        <td>[=Resource=]</td>
        <td>Peer reviewed analysis for Jan 3</td>
      </tr>
  </table>
</figure>

### Read-only access to collection resources ### {#inheritance-readonly}

Bob has a weekly status meeting with the members of the `research`
[=authorization group=].

Bob is a diligent notetaker, which his colleagues appreciate. He's happy
to act as the scribe and post notes after the meeting for sharing
with his colleagues. However, he doesn't want the overhead of granting
them permissions every week to each newly created note.

Bob stores his notes from the weekly status meeting in the `weekly-status`
[=collection=].

He grants the `research` [=authorization group=] [=read access=] to
the `weekly-status` [=collection=], which means they can read specific details
about the [=collection=] and see a listing of the resources included in it (e.g.,
Bob's notes). He also grants them inherited [=read access=] to the members
of the [=collection=], which allows them to read the contents of each note.

This is especially important
because in this case each of Bob's notes are actually a [=collection=]
themselves, capable of storing inline data or attachments, like pictures or
videos.

Because Bob sets inherited [=read access=] at the `weekly-status`
[=collection=], it applies to all of the members already in the [=collection=], as
well as any that are added in the future.

<div class="assertion">

* [[#req-agent-group]]
* [[#req-collection-read]]
* [[#req-inheritance-readonly]]

</div>

### Read-create access to collection resources ### {#inheritance-readcreate}

Every day, someone in the group is responsible for recording data from devices
in the field, and storing those metrics in `daily-metrics`.

Bob sets the following permissions on the `daily-metrics` [=collection=] for
the `research` [=authorization group=]:

* [=Read access=] so they can see the current list of [=resources=] in
    the [=collection=].
* Inherited [=read access=] so that they can read the contents of those
    [=resources=].
* [=Create access=] so that they can add new readings. They cannot modify
    readings after they are recorded, because they do not have [=write access=],
    and they cannot remove them, because they do not have [=delete access=].
    This provides confidence that readings
    are not manipulated after the fact.

<div class="assertion">

* [[#req-agent-group]]
* [[#req-collection-read]]
* [[#req-inheritance-readonly]]
* [[#req-collection-create]]

</div>

### Manage a hierarchy of collection resources ### {#inheritance-manage}

The members of the `research` [=authorization group=] collaborate on a daily
summary, where they analyze the day's field readings stored in
`daily-summaries`, detailing any new, validated, or invalidated hypotheses.

Bob sets the following permissions on the `daily-summaries` [=collection=]
for the `research` [=authorization group=]:

* [=Read access=] so they can see the current list of [=resources=] in
    the `daily-summaries`.
* [=Create access=] so they can add new summary [=resources=] to `daily-summaries`
* [=Delete access=] so they can remove summary [=resources=] from `daily-summaries`
* Inherited [=read access=] so they can read the
    contents of the summaries in the [=collection=]
* Inherited [=write access=] so they can modify their contents
* Inherited [=create access=] so they can add [=resources=] to any [=collections=]
    that might be added to `daily-summaries`
* Inherited [=delete access=] so they can remove [=resources=] from any
    [=collections=] that might be added to `daily-summaries`

<div class="assertion">

* [[#req-agent-group]]
* [[#req-collection-read]]
* [[#req-collection-create]]
* [[#req-collection-delete]]
* [[#req-inheritance-readonly]]
* [[#req-inheritance-change]]
* [[#req-inheritance-create]]
* [[#req-inheritance-delete]]

</div>

### Create-append access to collection resources ### {#inheritance-createappend}

Bob purchases a new field device that is able to automatically push daily
metric readings in `daily-metrics`.

Bob gives the new field device the following permissions on the
`daily-metrics` [=collection=]:

* [=Read access=] so it can access the list of resources in the collection
* Inherited [=read access=] so it can read the contents of existing metric readings
* [=Create access=] so it can create a new daily metric resource if a member of
    the `research` [=authorization group=] hasn't made one for that day yet.
* Inherited [=append access=] so it can add metric readings to daily-metric
    resources that already exist.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-read]]
* [[#req-collection-create]]
* [[#req-inheritance-readonly]]
* [[#req-inheritance-appendonly]]

</div>

### Manage permissions for collection resources ### {#inheritance-control}

Bob realizes that he needs some help administering `https://research.example`.
He provides Carol with the following permissions on the
`https://research.example` collection:

* [=Read access=] so she can see the current list of [=resources=] in
    the [=collection=].
* Inherited [=read access=] so she can read the
    contents of the resources in the [=collection=]
* [=Read permission access=] and [=write permission access=] allowing her
    to read and manage permissions for all of the [=resources=] and
    included within it.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-read]]
* [[#req-inheritance-readonly]]
* [[#req-collection-read-permissions]]
* [[#req-collection-change-permissions]]

</div>

### Default permissions on created resources ### {#inheritance-defaultcreated}

Bob is granting inherited permissions to the `research` [=authorization
group=] at the [=collection=] level for `daily-summaries` and `daily-metrics`
that include the ability to add resources ([=write access=] / [=append
access=]).

It's important that the resources they create have the correct permissions
assigned automatically, and he needs to be able to ensure this when he sets up
their access. Otherwise, how can he be sure that the files aren't created with
access that is too liberal (e.g., public access), or too narrow to be usable
within their context?

Bob prefers to specify in granular fashion the default permissions of created
resources that should be assigned to any [=authorizations=] with [=write
access=] or [=append access=] on a given [=collection=].

<div class="assertion">

* [[#req-inheritance-default-permissions]]

</div>

### Default permissions for extended network ### {#inheritance-extended}

Alice has a blog and allows comments on her posts. Ideally, everyone's
comments would be immediately visible, but she has previously been overwhelmed
by spammers. So now she would like to try a compromise: allow the posts from
her extended social network (friend of her friends, colleagues and family)  to
be immediately visible. Other posts should only be visible and editable to
those who wrote them. They can then be viewable to the world when they get
reviewed.

<div class="assertion">

* [[#req-inheritance-default-permissions]]
* [[#req-agent-group]]
* [[#req-vc]]
* [[#req-vc-determine]]
* [[#req-conditional-relationship]]

</div>


### Adding new subjects to inherited permissions ### {#inheritance-adding}

Note: Adding a new subject means we are adding a new [=agent=],
[=authorization group=], and/or [=application=] to the collection that isn't
already part of an inherited [=authorization=]. Modifying permissions for
those that exist in inherited [=authorizations=] is covered in
[[#inheritance-modifying]].

Bob has given the `research` [=authorization group=] inherited [=read access=]
to the `weekly-status` [=collection=] (detailed in [[#inheritance-readonly]]).

Celeste isn't a regular member of the `research` [=authorization group=], but
happened to attend the weekly status meeting on December 30th, 2019.

Bob would like to give Celeste [=read access=] to **only** the note
for the meeting she attended (`12-30-2019.note`), without affecting the access
that he's given to the `research` [=authorization group=]. `research` has
inherited [=read access=] on everything in the `weekly-status` [=collection=],
and anything that is added to it.

Effective access to `12-30-2019.note` should be that Celeste and the members
of the `research` [=authorization group=] have inherited [=read access=].
Celeste has no other access to other resources in the `weekly-status`
[=collection=], nor any that will be created later. The access for the
`research` [=authorization group=] doesn't change.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-inheritance-readonly]]
* [[#req-inheritance-modify]]

</div>

### Modifying inherited permissions for existing subjects ### {#inheritance-modifying}

On the January 6th weekly status meeting, Bob and the `research`
[=authorization group=] covered a research topic related to a commercial
endeavor that Felicia is involved in. When Felicia saw this on the agenda, she
informed Bob that it would be a conflict of interest for her to participate in
the discussion.

To ensure that there would be no semblance of conflict or impropriety, Bob and
Felicia agreed that he would remove her access to the meeting note for that
session - `01-06-2020.note`, which is included in the `weekly-status`
[=collection=].

Effective access to `01-06-2020.note` then becomes the inherited [=read
access=] to the `research` [=authorization group=] (which Felicia is part of),
minus Felicia.

Felicia continues to have inherited [=read access=] to all other existing
resources included in the `weekly-status` collection, and any new resources
added to it. Inherited [=read access=] for others in the `research`
[=authorization group=] is unchanged.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-inheritance-readonly]]
* [[#req-inheritance-modify]]

</div>

### Forcing inherited permissions ### {#inheritance-forcing}

As the primary administrator and [=resource controller=] of
`https://resource.example`, Bob wants to ensure that he maintains ultimate
control over the data inside.

Even though he's given Carol permission to help him administer the [=resource
server=], he wants to ensure that she's not able to cut out his access. He
wants to always maintain a minimum of [=read access=], [=read permission access=],
and [=write permission access=] to all of the resources in
`https://resource.example`. This allows him to have
visibility into everything, and change their permissions as needed.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-change-permissions]]
* [[#req-inheritance-change-permissions]]
* [[#req-inheritance-read-permissions]]
* [[#req-inheritance-readonly]]
* [[#req-inheritance-force]]

</div>

## Conditional access ## {#uc-conditional}

Felicia works for an organization that conducts clinical trials, and leads a
team that processes and synthesizes incoming data from trial participants,
including participants in the `Acme` trial.

The organization uses a [=resource server=] at `https://trials.example` as a
data repository for all of their clinical trial data. Felicia is the
[=resource controller=] of `https://trials.example`, managing authorized
access to it for her colleagues, and a group of research interns.

<figure>
<figcaption>Contents of `/measurements` collection</figcaption>
  <table class="data collections" align="left">
    <col>
    <col>
    <col>
    <thead>
      <tr>
        <th scope="col">Resource</th>
        <th scope="col">Type</th>
        <th scope="col">Description</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>`/measurements/`</td>
        <td>[=Collection=]</td>
        <td>Measurements for all trial participants across all trials</td>
      </tr>
      <tr>
        <td>`-- meas-123-03052020`</td>
        <td>[=Resource=]</td>
        <td>Individual measurement</td>
      </tr>
      <tr>
        <td>`-- meas-431-03052020`</td>
        <td>[=Resource=]</td>
        <td>Individual measurement</td>
      </tr>
      <tr>
        <td>`-- meas-974-03052020`</td>
        <td>[=Resource=]</td>
        <td>Individual measurement</td>
      </tr>
      <tr>
        <td>`-- meas-153-03052020`</td>
        <td>[=Resource=]</td>
        <td>Individual measurement</td>
      </tr>
      <tr>
        <td>`-- meas-755-03052020`</td>
        <td>[=Resource=]</td>
        <td>Individual measurement</td>
      </tr>
      <tr>
        <td>`-- meas-644-03052020`</td>
        <td>[=Resource=]</td>
        <td>Individual measurement</td>
      </tr>
      <tr>
        <td>`-- meas-031-03052020`</td>
        <td>[=Resource=]</td>
        <td>Individual measurement</td>
      </tr>
      <tr>
        <td>`-- meas-858-03052020`</td>
        <td>[=Resource=]</td>
        <td>Individual measurement</td>
      </tr>
      <tr>
        <td>`-- ...`</td>
        <td>-</td>
        <td>Collection includes thousands of measurements</td>
      </tr>
      <tr>
        <td>`/reports/`</td>
        <td>[=Collection=]</td>
        <td>Reports prepared for senior team members</td>
      </tr>
      <tr>
        <td>`-- report-1`</td>
        <td>[=Resource=]</td>
        <td>Individual report prepared for senior team members</td>
      </tr>
    </tbody>
  </table>
</figure>

### Conditional access by time ### {#conditional-time}

Erin is a research intern that will be assisting Felicia's team in processing
and synthesizing data for the `Acme` trial. She will remain on the team until
the end of her current academic term on June 30th, 2020.

The `measurements` [=collection=] contains measurements for all trial
participants, across all trials.

Felicia has granted Erin [=read access=] to the `measurements` [=collection=],
and inherited [=read access=] and [=write access=] to the
[=resources=] in the `measurements` [=collection=]. Felicia adds a
time-based condition for Erin which states that this access
is only valid through June 30th, 2020.

Erin will have no access to `measurements` after June 30th, 2020.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-read]]
* [[#req-inheritance-readonly]]
* [[#req-inheritance-change]]
* [[#req-conditional-time]]

</div>

### Conditional access by tag ### {#conditional-tag}

As a research intern, Erin is responsible for processing all unprocessed
measurements for the `Acme` trial in `measurements`. However, there are
measurements for other trials in the `measurements` [=collection=], as well as
measurements that have already been processed.

* Each measurement in `measurements` is tagged with the trial it belongs to
* All measurements for the `Acme` trial are tagged with `Acme`
* When a new measurement is processed, it is tagged as `processed`

Felicia authorizes Erin to have [=read access=] to the `measurements`
[=collection=], and inherited [=read access=] and [=write access=]
to `measurements`, with a condition that the [=resources=] must:

* **include** the `Acme` [=tag=]
* **exclude** the `processed` [=tag=]

This allows Erin to work with new measurements for the `Acme` trial without
being exposed to measurements from other trials, or already processed
measurements from the `Acme` trial.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-read]]
* [[#req-inheritance-readonly]]
* [[#req-inheritance-change]]
* [[#req-conditional-tag]]

</div>

### Conditional access by relationship ### {#conditional-relationship}

Felicia is responsible for preparing and sharing internal reports for senior
research team members. These reports include direct links to source data,
including individual measurement [=resources=] in the `measurements`
[=collection=].

Senior research team members do not have regular access to `measurements`.
They only access individual [=resources=] in `measurements` that are linked
through these reports. Each report only links to a small subset of individual
measurements. Reports are often amended to reference additional measurements
over time.

When Felicia prepares a new report `/reports/report-1`, she authorizes only
the senior research team members receiving the report to have inherited [=read
access=] to [=resources=] in `measurements`, with a condition that a given
measurement must be
related to `/reports/report-1` by an `ex:hasMeasurement` predicate for that
access to be permitted.

This ensures that the senior research team members will be able to read
measurements referenced by `/reports/report-1`, or any references added to it
later, but no others.

There may be different ways to describe the relationships which propagate access rules, for example:

* Relationships may be `direct` or `indirect`, e.g., `report-1` references `measurement-2`, which in turn references `instrument-3`.
* Relationships may be `forward` or `inverse`, e.g., `slide-4` references `report-1`, so the permissions associated with `report-1` also apply to `slide-4`.
* Relationships may be asserted in the `referring` document, the `referenced` document, or some third document, e.g., a document other than `report-1` which contains the relationship linking `report-1` to `measurement-2`.

<div class="assertion">

* [[#req-agent-group]]
* [[#req-inheritance-readonly]]
* [[#req-conditional-relationship]]

</div>

### Conditional access by filter ### {#conditional-filter}

Felicia has been able to limit the scope of the [=resources=] that Erin can
access to unprocessed entries for the `Acme` trial, which is all that she
needs to perform her duties. However, each measurement [=resource=] also
contains personally identifiable information (PII) for the trial participant
associated with the measurement. Felicia needs to ensure that Erin cannot
access that PII.

Felicia authorizes Erin to access a reduced set of fields within the
measurement [=resources=]. When Erin retrieves a measurement, the response
will exclude the fields containing PII.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-read]]
* [[#req-inheritance-readonly]]
* [[#req-inheritance-change]]
* [[#req-conditional-tag]]
* [[#req-conditional-filter]]

</div>

### Conditional control boundaries ### {#conditional-control}

Megan works on Felicia's team. Felicia would like Megan to be responsible for
managing access to trial data for the research interns assigned to the `Acme`
project. Felicia doesn't want to give Megan more permission than she needs to
do that work.

Felicia grants Megan inherited [=read permission access=]
and [=write permission access=] to `measurements`, with
conditions that stipulate:

* she only has effective [=read permission access=] and
    [=write permission access=] of [=resources=] that include
    the `Acme` [=tag=] within the `measurements` [=collection=].
* she can only create or change [=authorizations=]
    targeting the `measurements` [=collection=] where
    [=agents=] are included in the `interns` [=authorization group=].
* she can't grant [=read permission access=] and/or [=write permission access=]
    to anyone else.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-collection-read]]
* [[#req-inheritance-read-permissions]]
* [[#req-inheritance-change-permissions]]
* [[#req-conditional-control]]
* [[#req-conditional-control-tag]]

</div>

### Conditional access by action ### {#conditional-action}

The University has a widely used blog for discussion with research teams
across the world. Researchers who post comments often want to correct errors
after publication. But this feature can lead to misunderstandings if edited
after someone else has commented on the comment. They institute the following
policy: their authors can edit comments for a minimum of 5 minutes and only
until these are themselves commented. After that point, the post will be in
read-only access mode.

<div class="assertion">

* [[#req-agent-group]]
* [[#req-collection-creator]]
* [[#req-inheritance-change]]
* [[#req-inheritance-readonly]]
* [[#req-conditional-action]]

</div>

### Conditional access by payment ### {#conditional-payment}

A musician would like to self publish her music to take advantage of a Solid
music App. She does this by making the song metadata available openly so that
fans can follow her new releases, specialised music search engines can index
it, and music apps can display the song's metadata in their users' preferred
language. To earn a living, she sets an access control rule on the resource,
allowing access on proof of payment. Payment methods need to be flexible and
allow for smooth integration with any music app, even enabling automatic
payment for small enough sums. Users of the Solid Music App would thus have
one more song to choose from amongst the large number made available by
musicians worldwide.

<div class="assertion">

* [[#req-read]]
* [[#req-conditional-action]]
* [[#req-conditional-relationship]]
* [[#req-vc]]
* [[#req-vc-determine]]

</div>

## Permissioning Applications ## {#uc-applications}

### Limiting access to trusted applications ### {#uc-trusted-applications}

Oscar stores all of his data in a private [=resource server=] at
`https://oscar.example`, where he is the [=resource controller=].

He stores a wide spectrum of things, from personal financial data to
collaborative projects that he works on with his friends and colleagues.

As the [=resource controller=] for `https://oscar.example`, any application
that operates with or on behalf of Oscar's [=identity=] would operate with the
same unfettered access that Oscar enjoys.

It is important to Oscar that he can include [=applications=] in his
[=authorizations=] to limit this unfettered access.

For example, to constrain Oscar's access to `https://oscar.example` to only
cases where an application he trusts is involved:

* Oscar **with the** `trusted-applications` [=authorization group=] has
    the following permissions on `https://oscar.example`:
    * [=Read access=] so that he can read summary data for the
        `https://oscar.example` [=resource=], and list its contents. Inherited
        [=read access=] to all member resources so he can read and/or list their
        contents.
    * [=Write access=] so that he can change summary data for the
        `https://oscar.example` [=resource=]. Inherited [=write access=] to
        all member [=resources=] so he can change their contents.
    * [=read permission access=] and [=write permission access=] so that
        he can read and manage permissions. Inherited [=read permission access=]
        and [=write permission access=] so that he can manage permissions
        for all member resources.
    * [=Create access=] and [=Delete access=] so that
        he can add and remove resources. Inherited [=create access=] and
        [=delete access=] so that he can add resources to member [=collections=]
        and delete resources from them.

Following that, per [[#inheritance-modifying]], he could extend this default
for the `health` [=collection=] to include `healthapp`:

* Oscar **with the** `trusted-applications` [=authorization group=] AND
    `healthapp` has [=read access=], [=write access=], [=create access=],
    [=delete access=], [=read permission access=],
    and [=write permission access=] to the `health` [=collection=], along
    with corresponding inherited permissions for [=collection=] member
    [=resources=].

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-application]]
* [[#req-collection-read]]
* [[#req-collection-write]]
* [[#req-collection-create]]
* [[#req-collection-delete]]
* [[#req-collection-read-permissions]]
* [[#req-collection-change-permissions]]
* [[#req-inheritance-change]]
* [[#req-inheritance-readonly]]
* [[#req-inheritance-create]]
* [[#req-inheritance-delete]]
* [[#req-inheritance-read-permissions]]
* [[#req-inheritance-change-permissions]]
* [[#req-inheritance-modify]]

</div>

### Limiting application access while not acting as resource controller ### {#uc-client-constraints}

Alice uses application *PerformChart* to visualize her work performance across
various projects. She works on projects across various organizations,
including *ACME* and *Omni*. While she has controller access to some of the
projects, she also has read-write access to many other projects. Since
*PerformChart* only provides analysis and visualization it doesn't need any
write access. Alice grants *PerformChart* read only access to all the projects
that she can access.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-application]]
* [[#req-client-constrained]]
* [[#req-collection-read]]
* [[#req-collection-write]]
* [[#req-inheritance-change]]
* [[#req-inheritance-readonly]]

</div>

### Application determining access privileges ### {#uc-client-determine-access-privileges}

Guinan uses an application to author and publish documents. The application
adapts its user interface to distinguish between allowed
(actionable) and disallowed features based on access information that the
[=resource server=] reveals, for example, permissions that are granted to the
application, to the public (everyone), or to a group.

For example, for user level permission, if the application is not granted
[=write access=] on the resource that Guinan is currently editing, the user
interface can disable the "Save" button in the menu. Guinan also wants to know
if the public is granted [=read access=] on the content they are updating, and
thus if it can be, for example, liked, bookmarked, archived by everyone.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-public]]
* [[#req-effective-modes]]
* [[#req-read]]
* [[#req-write]]

</div>

### Distinguishing mediated from direct access ### {#uc-distinguish-mediated-access}

A [=resource controller=] wishes to grant an [=agent=] [=access=] to a
[=resource=]. The controller wishes to grant a different [=access mode=]
depending on whether the agent accesses the resource via an [=application=] or
directly. For example, in the case of mediated access via an application, the
controller wishes to restrict the set of eligible applications. But the
controller also wishes to allow direct access.

<div class="assertion">

* [[#req-distinguish-mediated-access]]

</div>

## Delegation ## {#uc-delegation}

### Delegating subset of received access to another agent ### {#uc-delegation-subset}

An organization, *ACME*, grants Alice read-write access to one of their projects.
Alice wants to get an opinion from Bob, who doesn't have any access granted directly by *ACME*.
Alice needs to enable Bob to have read access to that project of *ACME*. She could:
* Save the information as files and share them with Bob
* Automate taking snapshots and sharing the latest version with Bob each time the project gets updated
* Set up a proxy which would allow Bob to have specific limited access impersonating Alice

However, *ACME* supports access delegation, which allows Alice to simply delegate read-only
access to that *ACME* project to Bob.

NOTE: This scenario can be combined with [Limiting application access while not acting as resource controller](#uc-client-constraints),
where Bob needs to authorize application(s) of his choice to exercise the read-only access delegated to him by Alice.

NOTE: See also [OAuth 2.0 Token Exchange - 1.1.  Delegation vs. Impersonation Semantics](https://datatracker.ietf.org/doc/html/rfc8693#section-1.1)


## Privacy ## {#uc-privacy}

### Limiting access to who else is permitted ### {#uc-whopermitted}

Alice is interviewing for a job with Carol. Alice is also interviewing for a
job with Oscar, Carol's direct competitor.

Alice has given Carol and Oscar [=read access=] to her `resume`.

Neither Carol or Oscar would appreciate knowing that Alice is interviewing
with both of them, so it's important neither Carol or Oscar know who else
Alice has shared her `resume` with, despite having [=read access=] to it.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-read-permissions]]
* [[#req-read]]

</div>

### Limiting access to other authorization conditions ### {#uc-historyofchanges}

As an extension of [[#uc-whopermitted]], it is also important to Alice that
that neither Carol nor Oscar be able to discern other characteristics of the
[=authorizations=] or conditions associated with Alice's `resume`.

For example, if the data Carol and Oscar saw in the resume was
[[#conditional-filter|filtered]] to only show a certain subset of her
background, she wouldn't want them to know that they were only seeing a
filtered view.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-read-permissions]]

</div>

### Minimal Credential Disclosure ### {#uc-minimalcredentials}

Following a link on a blog post, Alice comes to a resource that requires
authentication. She could present one of many verifiable credentials (as per
[[#capabilities-vc]]): three self-signed WebID credentials, four bank
accounts, a drivers licence, two passports, a proof that she is over 18, a
credential for her college and her university diploma, three club memberships
as well as her FBI credential. The resource only requires proof of being
over 18. Her client's credential manager should see this and select the
credential revealing the least amount of information needed to access the
resource.

<div class="assertion">

* [[#req-vc]]
* [[#req-vc-determine]]

</div>

### Limit information disclosure through URI ### {#uc-limituri}

A service with very high security and confidentiality requirements must
publish resources without the URL for any resource leaking information about
it's content. This service publishes all these resources using the Tor
protocol, so that the location of the servers can remain secret. All resources
on this Solid server are named by the root container using a UUID naming
scheme.

<figure>
<figcaption>Contents under
`https://ciadotgov4sjwlzihbbgxnqg3xiyrg7so2r2o3lt5wz5ypk4sxyjstad.onion/`</figcaption>
  <table class="data collections" align="left">
    <col>
    <col>
    <col>
    <thead>
      <tr>
        <th scope="col">Resource</th>
        <th scope="col">Type</th>
        <th scope="col">Description</th>
      </tr>
    </thead>
    <tbody>
     <tr>
        <td>`4fcffa1b-3cc2-4ace-be65-2b0cf8045550`</td>
        <td>[=Collection=]</td>
        <td>Collection for online meeting on 24 July 2025</td>
      </tr>
       <tr>
        <td>`aa91d049-9997-48c8-b115-2217c3c9c0d5`</td>
        <td>[=Resource=]</td>
        <td>Agent Alice's notes for the meeting stored in above collection</td>
      </tr>
      <tr>
        <td>`6b063d07-9f25-4692-ba3d-dff02f200028`</td>
        <td>Video</td>
        <td>Recorded audio/video of web conference meeting stored in above collection</td>
      </tr>
     <tr>
        <td>`4376ed72-37d8-4432-8dce-7a796f4bdd66`</td>
        <td>[=Collection=]</td>
        <td>Collection for 14 September 2025 online meeting</td>
      </tr>
      <tr>
        <td>`796d8d67-3e88-483f-b1c1-d4eba63827e3`</td>
        <td>Video</td>
        <td>Recorded audio/video of web conference meeting</td>
      </tr>
      <tr>
        <td>`b7123ed7-3861-4b37-9b53-cf9bd730fafe`</td>
        <td>[=Collection=]</td>
        <td>Subcollection of 14 Sept Collection for data dumps</td>
      </tr>
      <tr>
        <td>`2d97f889-8f7d-43fb-83f8-1437b05896ba`</td>
        <td>[=Resource=]</td>
        <td>Agent Smith's data stored in in `b7123ed7-3861-4b37-9b53-cf9bd730fafe` collection</td>
      </tr>
      <tr>
        <td>`17a63d0f-b99f-4268-929d-5a5fe5f5dd56`</td>
        <td>[=Resource=]</td>
        <td>Agent Alice's data stored in the same Collection as Agent Smith's</td>
      </tr>
  </table>
</figure>

Some of the UUID resources represent collections and others various types of
content. Collections can contain other collections as usual, but this cannot
be deduced from the name. Only clients that are authorized can tell from the
returned descriptions what the type of the resource is or what a container
contains.

The service would like to be able to use the same applications on those
resources as it does on its public facing Solid Web site, where it uses
humanly readable and memorable names for its resources.

<div class="assertion">

* [[#req-uripath]]

</div>


## Trust ## {#uc-trust}

### Only trust certain issuers of identity ### {#uc-trustedissuers}

Carol has a blog, and allows any [=authenticated agent=] (e.g., [[WEBID]],
[[DID]]) to comment on her blog posts.

Unfortunately, anyone can setup an identity provider, so Carol would like to
be able to recognize credentials issued from trustworthy identity providers.

<div class="assertion">

* [[#req-agent-identity]]
* [[#req-trusted-identity]]

</div>

### Block access to agents ### {#uc-blockagents}

A nonpartisan group provides a public annotation service, and allows any
[=authenticated agent=] to share fact-checked information.

Unfortunately, there are bad actors that seek to expose misinformation and
disinformation through the annotation service. The trusted moderators of the
service would like to be able to block bad actors from sharing content in the
future.

<div class="assertion">

* [[#req-agent-identity]]

</div>

## Validation ## {#uc-validation}

Juan likes to manage his [=authorizations=] manually. Every once in a while,
Juan makes a typo, or accidentally saves the [=authorization=] in an
incomplete state.

Juan runs into trouble on systems where the authorization system implementation
doesn't properly validate, most often resulting in Juan getting locked out of
the [=resource=] and needing administrator assistance to recover.

## Capabilities ## {#uc-capabilities}

### Possession of a group membership verifiable credential ### {#group-membership-vc}

Omni Corp granted Acme Corp read-write access to three of their projects: A, B,
and C. This grant allows all Acme Corp employees to have that access as long as
they can present a membership credential issued by Acme Corp. At the time of
the grant, Omni Corp notifies Acme Corp, detailing pertinent access details,
including the membership credential requirement for Acme Corp employees. Acme
Corp doesn't maintain a public list of their employees, so Omni Corp cannot
know who is employed by Acme Corp unless that person presents a verifiable
credential. Alice works for Acme Corp, and can now access the Omni Corp
projects A, B, and C, using her membership credential issued by Acme Corp.

### Possession of a verifiable credential ### {#capabilities-vc}

Oscar has a medical condition that causes random and very serious seizures
several times per year. Wherever Oscar is, he needs to be rushed immediately
to the closest hospital in an ambulance.

Oscar's government has recently rolled out a digital credential system for
health care professionals, which is like a digital id card for doctors and
care facilities that can be cryptographically verified.

Oscar has an emergency care record at `https://oscar.example/emergency`, and
Oscar's authorization system at `https://oscar.example` supports a verifiable
credential [=capability=].

Oscar has set permissions on `https://oscar.example/emergency` that grants
someone in possession of a verifiable medical credential to have inherited
[=read access=] to the contents. This gives them just enough background on his
condition to treat him properly.

<div class="assertion">

* [[#req-vc]]
* [[#req-inheritance-readonly]]
* [[#req-vc-determine]]

</div>

### Possession of a link ### {#capabilities-link}

Bob is about to give a confidential presentation to a group of his colleagues.
His presentation is stored on his personal [=resource server=] at
`https://bob.example/presentation`.

Bob is having trouble hooking his laptop up to the projector, and needs to
present in just a few minutes. Anne presented before Bob, and offers to bring
the presentation up for him on her system.

Unfortunately, Anne doesn't have an [=identity=] ready to go that he can
authorize. Luckily, his authorization system supports a link-based
[=capability=].

Bob quickly creates an [=authorization=] for
`https://bob.example/presentation` that allows anyone in possession of a
specially generated link to access the document with [=read access=]. He sets
it to [[#conditional-time|expire]] in three hours. Bob gives the link to Anne
and the presentation goes off perfectly.

* [[#req-vc]]
* [[#req-read]]
* [[#req-conditional-time]]

Functional Requirements {#requirements}
================================================================================

Note: Unless otherwise specified, *allowing or limiting access* in the
subsequent requirements should be interpreted in the context of allowing
or limiting access to a [=resource=] or [=collection=] by an [=agent=].

## Access by subject ## {#req-as}

### The system shall allow access to be limited based on the [=identity=] of the [=agent=]. ### {#req-agent-identity}

<div class="assertion">
  Related use cases: [[#uc-basic]], [[#uc-collections]]
</div>

### The system shall allow access to be limited based on the [=identity=] of the [=agent=], only when that identity is issued by a trusted identity provider. ### {#req-trusted-identity}

<div class="assertion">
  Related use cases: [[#uc-trustedissuers]]
</div>

### The system shall allow access to be limited to an [=agent=] based on the [=agent's=] membership in a certain group of [=agents=]. ### {#req-agent-group}

<div class="assertion">
  Related use cases: [[#basic-group]]
</div>

### The system shall allow access to be limited to an [=agent=] based on the client [=application=] in use by the [=agent=]. ### {#req-application}

<div class="assertion">
  Related use cases: [[#uc-trusted-applications]]
</div>

### The system shall allow an [=agent=] to limit modes and/or conditions of access for a given client [=application=] in their use for a [=resource=] or [=collection=] that they have been granted access to. ### {#req-client-constrained}

<div class="assertion">
  Related use cases: [[#uc-client-constraints]]
</div>

### The system shall allow access to be permitted for any unauthenticated or authenticated [=agent=]. ### {#req-public}

<div class="assertion">
  Related use cases: [[#basic-public]]
</div>

### The system shall allow access to be limited to any authenticated [=agent=]. ### {#req-authenticated}

<div class="assertion">
  Related use cases: [[#basic-authenticated]]
</div>

### The system shall allow distinguishing between mediated (via a third-party client application) and non-mediated access. ### {#req-distinguish-mediated-access}

<div class="assertion">
  Related use cases: [[#uc-distinguish-mediated-access]]
</div>

## Access by capability ## {#req-capabilities}

### The system shall allow access to be limited to an [=agent=] based on the [=agent's=] possession of a certain verifiable credential or capability. ### {#req-vc}

<div class="assertion">
  Related use cases: [[#capabilities-vc]], [[#capabilities-link]], [[#uc-minimalcredentials]]
</div>

### The system shall ensure that there are practical and efficient mechanisms available for the client to determine an appropriate credential to present for access to a given [=resource=]. ### {#req-vc-determine}

<div class="assertion">
  Related use cases: [[#capabilities-vc]], [[#uc-minimalcredentials]], [[#conditional-payment]]
</div>

## Access to resources ## {#req-resources}

### The system shall allow the ability to read the access permissions associated with a certain [=resource=] to be limited. ### {#req-read-permissions}

<div class="assertion">
  Related use cases: [[#basic-read-permissions]], [[#uc-whopermitted]], [[#uc-historyofchanges]]
</div>

### The system shall allow the ability to change the access permissions associated with a certain [=resource=] to be limited. ### {#req-change-permissions}

<div class="assertion">
  Related use cases: [[#basic-change-permissions]]
</div>

### The system shall provide the effective access permissions on a certain [=resource=] or [=collection=] as they relate to the [=agent=] making the request, in the request response. ### {#req-effective-modes}

<div class="assertion">
  Related use cases: [[#uc-client-determine-access-privileges]]
</div>

### The system shall allow the ability to read a certain [=resource=] to be limited.### {#req-read}

<div class="assertion">
  Related use cases: [[#basic-readonly]], [[#basic-write]], [[#basic-readappend]]
</div>

### The system shall allow the ability to change any of the existing contents of a certain [=resource=] to be limited.### {#req-write}

<div class="assertion">
  Related use cases: [[#basic-write]]
</div>

### The system shall allow the ability to change existing data in a certain [=resource=] to be limited, such that only new data can be added to it.### {#req-append}

<div class="assertion">
  Related use cases: [[#basic-appendonly]], [[#basic-readappend]]
</div>

### The system shall limit the ability to delete a certain [=resource=]. ### {#req-delete}

<div class="assertion">
  Related use cases: [[#collection-readcreatedelete]]
</div>

### The system shall allow for access to a [=resource=] or [=collection=] to be limited to the [=agent=] that created it. ### {#req-creator}

<div class="assertion">
  Related use cases: [[#collection-readcreatedelete]]
</div>

### The system shall not rely on the URI structure to infer semantics about the type of [=resources=]. ### {#req-uripath}

<div class="assertion">
  Related use cases: [[#uc-limituri]]
</div>

## Access to collections ## {#req-collections}

### The system shall allow the ability to read a certain [=collection=] to be limited, exposing only the data from the [=collection=] resource itself, and a listing of its members, and excluding the contents of its members, or any metadata about them. ### {#req-collection-read}

<div class="assertion">
  Related use cases: [[#collection-readonly]], [[#collection-readwrite]],
  [[#collection-readcreate]], [[#collection-readcreatedelete]]
</div>

### The system shall allow the ability to change data specific to a certain [=collection=] to be limited, including only the data from the [=collection=] resource itself, and excluding any additions or subtractions from its list of members. ### {#req-collection-write}

<div class="assertion">
  Related use cases: [[#collection-readwrite]]
</div>

### The system shall allow the ability to create a [=resource=] in a certain [=collection=] to be limited.### {#req-collection-create}

<div class="assertion">
  Related use cases: [[#collection-readwrite]], [[#collection-readcreate]],
  [[#collection-readcreatedelete]], [[#collection-createonly]]
</div>

### The system shall limit the ability to delete a [=resource=] in a certain [=collection=].### {#req-collection-delete}

<div class="assertion">
  Related use cases: [[#collection-readcreatedelete]]
</div>

### The system shall allow for the creator of a [=resource=] in a certain [=collection=] to be automatically granted access to the created [=resource=].### {#req-collection-creator}

<div class="assertion">
  Related use cases: [[#collection-readcreatedelete]]
</div>

### The system shall allow the ability to read the access permissions associated with a certain [=collection=] to be limited.### {#req-collection-read-permissions}

<div class="assertion">
  Related use cases: [[#collection-control]], [[#uc-whopermitted]],
  [[#uc-historyofchanges]]
</div>

### The system shall allow the ability to change the access permissions directly associated with a certain [=collection=] to be limited.### {#req-collection-change-permissions}

<div class="assertion">
  Related use cases: [[#collection-control]]
</div>

## Inherited access to collection resources ## {#req-inherited}

### The system shall allow for a certain [=collection=] to specify access permissions that are inherited by its members.### {#req-collection-inheritance}

<div class="assertion">
  Related use cases: [[#uc-inheritance]]
</div>

### The system shall allow for a certain resource to be read if the [=agent=] has inherited [=read access=] from the parent [=collection=] the [=resource=] is a member of. ### {#req-inheritance-readonly}

<div class="assertion">
  Related use cases: [[#inheritance-readonly]]
</div>

### The system shall allow for a resource to be changed if the [=agent=] has inherited [=write access=] from the parent [=collection=] the [=resource=] is a member of. ### {#req-inheritance-change}

<div class="assertion">
  Related use cases: [[#inheritance-manage]]
</div>

### The system shall allow for new data to be added to a [=resource=], without being able to change existing data in that [=resource=], if the [=agent=] has inherited [=append access=] from the parent [=collection=] the [=resource=] is a member of. ### {#req-inheritance-appendonly}

<div class="assertion">
  Related use cases: [[#inheritance-createappend]]
</div>

### The system shall allow for new resources to be added to a given [=collection=] if the [=agent=] has inherited [=create access=] from the parent [=collection=] that the given [=collection=] is a member of. ### {#req-inheritance-create}

<div class="assertion">
  Related use cases: [[#inheritance-readcreate]]
</div>

### The system shall allow for resources to be deleted from a given [=collection=] if the [=agent=] has inherited [=delete access=] from the parent [=collection=] that the given [=collection=] is a member of. ### {#req-inheritance-delete}

<div class="assertion">
  Related use cases: [[#collection-readcreatedelete]]
</div>

### The system shall allow for the members of a certain [=collection=] to extend or augment the permissions inherited from the parent [=collection=].### {#req-inheritance-modify}

<div class="assertion">
  Related use cases: [[#inheritance-adding]], [[#inheritance-modifying]]
</div>

### The system shall allow for a certain [=collection=] to specify access permissions that are inherited by its members and cannot be augmented. ### {#req-inheritance-force}

<div class="assertion">
  Related use cases: [[#inheritance-forcing]]
</div>

### The system shall allow for the default permissions of a newly created [=resource=] to be inherited from the parent [=collection=] the [=resource=] is a member of. ### {#req-inheritance-default-permissions}

<div class="assertion">
  Related use cases: [[#inheritance-defaultcreated]], [[#inheritance-extended]]
</div>

### The system shall allow for the access permissions directly associated with a certain resource to be read if the [=agent=] has inherited [=read permission access=] from the parent [=collection=] the [=resource=] is a member of. ### {#req-inheritance-read-permissions}

<div class="assertion">
  Related use cases: [[#inheritance-control]]
</div>

### The system shall allow for the access permissions directly associated with a certain resource to be changed if the [=agent=] has inherited [=write permission access=] from the parent [=collection=] the [=resource=] is a member of. ### {#req-inheritance-change-permissions}

<div class="assertion">
  Related use cases: [[#inheritance-control]]
</div>

## Conditional access ## {#req-conditional}

### The system shall allow the ability to limit access to a certain [=resource=] by a given start and/or end date and time.### {#req-conditional-time}

<div class="assertion">
  Related use cases: [[#conditional-time]]
</div>

### The system shall allow the ability to limit access to a certain [=resource=] by a tag associated with that resource.### {#req-conditional-tag}

<div class="assertion">
  Related use cases: [[#conditional-tag]]
</div>

### The system shall allow the ability to limit access to a certain [=resource=] based on the existence of a specific relationship with another [=resource=].### {#req-conditional-relationship}

<div class="assertion">
  Related use cases: [[#conditional-relationship]], [[#inheritance-extended]]
</div>

### The system shall allow access to be limited to only a subset of data in a certain [=resource=] based on supplied filter criteria.### {#req-conditional-filter}

<div class="assertion">
  Related use cases: [[#conditional-filter]]
</div>

### The system shall allow the [=access modes=] and/or conditions of a given access permission for a certain [=resource=] or [=collection=] to change after other specified conditions have been satisfied.### {#req-conditional-action}

<div class="assertion">
  Related use cases: [[#conditional-action]]
</div>

### The system shall allow the ability to read, create, or change only those access permissions for a given [=resource=] or [=collection=] that apply to a specified group of [=agents=] to be limited.### {#req-conditional-control}

<div class="assertion">
  Related use cases: [[#conditional-control]]
</div>

### The system shall allow the ability to read, create, or change access permissions for [=resources=] associated with a particular tag to be limited.### {#req-conditional-control-tag}

<div class="assertion">
  Related use cases: [[#conditional-control]]
</div>

Definitions {#definitions}
================================================================================

All definitions as stated below should be considered in the context of
an authorization system in Solid, whether explicitly stated or not.

An <dfn>agent</dfn> is a distinct individual, group, organization, or piece of
software with an [=identity=] that can be strongly authenticated.

An <dfn>identity</dfn> is used to uniquely identify a given [=agent=],
represented by a unique [[URI]]. Examples of compatible identity systems
include [[WEBID]] and [[DID]].

An <dfn>authenticated agent</dfn> is an [=agent=] that has proven control of a
given [=identity=].

An <dfn>application</dfn> is a piece of software that interfaces with a
[=resource server=], which may operate autonomously as an [=authenticated
agent=], or in piloted-fashion by another [=authenticated agent=].

A <dfn>resource controller</dfn> is an [=agent=] with fully permissioned
access and control over one or more [=resources=] residing on a [=resource
server=] on the Web.

A <dfn>resource server</dfn> is a web server that provides an interface to
make [=resources=] available to [=agents=] and [=applications=], with the
ability to secure access to those [=resources=] through associated
[=authorizations=].

A <dfn>resource</dfn> is the target of an HTTP request identified by a
[[URI]], as defined in [[!rfc9110]].

A <dfn>collection</dfn> is a [=resource=] that is representative of a set of
other [=resources=], which may include other [=collections=].

A <dfn>tag</dfn> is a type of metadata associated with a [=resource=] for
classification or identification.

An <dfn>authorization</dfn> is a [=resource=] that controls access to one or
more [=resources=].

An <dfn>authorization group</dfn> is a [=resource=] that represents some
combination of [=agents=], [=applications=], and [=authorization groups=].

A <dfn>capability</dfn> is an object an [=agent=] must possess to be permitted
to access a [=resource=].

An <dfn>access mode</dfn> denotes a class of operations that an [=agent=]
and/or [=application=] can perform on one or more [=resources=].

<dfn>Read access</dfn> is an [=access mode=] that allows [=agents=] and/or
[=applications=] the ability to read, but not modify a [=resource=]. When
the [=resource=] is a [=collection=], this includes access to the list
of [=resources=] in that [=collection=], but does not include access to
their contents, or any metadata about them.

<dfn>Write access</dfn> is an [=access mode=] that allows [=agents=] and/or
[=applications=] the ability to modify the contents of a [=resource=]. When
the resource is a [=collection=], the contents of the [=collection=] resource
itself can be modified, but [=create access=] and [=delete access=] are
required to create or delete [=resources=] from the [=collection=].

<dfn>Append access</dfn> is an [=access mode=] that allows [=agents=] and/or
[=applications=] to add data to the contents of a resource, but not modify
any of the existing contents. When the resource is a [=collection=], the
contents of the [=collection=] resource
itself can be added to, but [=create access=] is required to add new
[=resources=] to the [=collection=].

<dfn>Create access</dfn> is an [=access mode=] that allows [=agents=] and/or
[=applications=] to add new [=resources=] to a given [=collection=].

<dfn>Delete access</dfn> is an [=access mode=] that allows [=agents=] and/or
[=applications=] to delete a [=resource=]. If the [=resource=] is a
[=collection=], it includes the ability to delete [=resources=] in that
collection.

<dfn>Read permission access</dfn> is an [=access mode=] that allows [=agents=] and/or
[=applications=] to view [=authorizations=] associated with a [=resource=].

<dfn>Write permission access</dfn> is an [=access mode=] that allows [=agents=] and/or
[=applications=] to modify [=authorizations=] associated with a [=resource=].

<pre class="biblio">
{
  "webid": {
    "href": "https://www.w3.org/2005/Incubator/webid/spec/identity/",
    "title": "WebID 1.0",
    "authors": [
      "Tim Berners-Lee",
      "Henry Story",
      "Andrei Sambra"
    ]
  },
  "did": {
    "href": "https://www.w3.org/TR/did-core/",
    "title": "Decentralized Identifiers (DIDs) v1.0",
    "authors": [
      "Drummond Reed",
      "Manu Sporney",
      "Dave Longley",
      "Christopher Allen",
      "Ryan Grant",
      "Markus Sabadello"
    ]
  }
}
</pre>