- **Permission** is binary: *yes* (allowed) or *no* (denied).

- **Subject** in this case is anything that implements interface `authz.Subject`.

- **Action** here is an enumerated list of actions, but we stick to `Create`, `Read`, `Update`, and `Delete` here.

A **permission** is always applied at a given **level**:

**Permissions** at a higher **level** always override permissions at a **lower** level.

The effect of a **permission** can be:

- **positive** (allows)

- **negative** (denies)

**Negative** permissions **always** override **positive** permissions at the same level.

Both **negative** and **positive** permissions override **abstain** at the same level.

- `sign` can be either `+` or `-`. If it is omitted, sign is assumed to be `+`.

- `level` is either `*`, `site`, `org`, or `user`.

- `id` is any valid UUID v4.

- `action` is `create`, `read`, `modify`, or `delete`.

- `-user.workspace.*.create`: user is not allowed to create workspaces.

A *role* is a set of permissions. When evaluating a role's permission to form an action, all the relevant permissions for the role are combined at each level. Permissions at a higher level override permissions at a lower level.

Y indicates that the role provides positive permissions, N indicates the role provides negative permissions, and _ indicates the role does not provide positive or negative permissions. YN_ indicates that the value in the cell does not matter for the access result.

| Role (example) | Site | Org | User | Result |

Package `authztest` implements _exhaustive_ unit testing for the `authz` package.

The `authz.Authorize` function has three* inputs:

- Subject (for example, a user or API key)

- Action (for example, read or write).

**Not including the ruleset, which we're keeping static for the moment.*

Normally to test a pure function like this, you'd write a table test with all of the permutations by hand, for example:

func Test_Authorize(t *testing.T) {

....

testCases := []struct {

name string

subject authz.Subject

action authz.Action

expectedError error

}{

subject: &User{ID: "admin"},

object: &authz.ZObject{

OrgOwner: "default",

},

expectedError: nil,

},

}

}

This approach is problematic because of the cardinality of the RBAC model.

Recall that the legacy `pkg/access/authorize`:

- Exposes 8 possible actions, 5 possible site-level roles, 4 possible org-level roles, and 24 possible resource types

- Enforces site-wide versus organization-wide permissions separately

The new authentication model must maintain backward compatibility with this model, whilst allowing additional features such as:

- User-level ownership (which means user-level permission enforcement)

- Custom roles

The resulting permissions model ([documented in Notion](https://www.notion.so/coderhq/Workspaces-V2-Authz-RBAC-24fd193386eb4cf79a282a2a69e8f917)) results in a large **finite** solution space in the order of **hundreds of millions**.

Instead, we generate (almost) all possible sets of inputs to the library, and ensure that `authz.Authorize` performs as expected.

The actual investigation of the solution space is [documented in Notion](https://www.notion.so/coderhq/Authz-Exhaustive-Testing-7683ea694c6e4c12ab0124439916b13a), but the crucial take-away of that document is:

- There is a **large** but **finite** number of possible inputs to `authz.Authorize`,

- The solution space can be broken down into 9 groups, and

- Most importantly, *each group has the same expected result.*

We group the search space into a number of groups. Each group corresponds to a set of test cases with the same expected result. Each group consists of a set of **impactful** permissions and a set of **noise** permissions.

**Impactful** permissions are the top-level permissions that are expected to override anything else, and should be the only inputs that determine the expected result.

**Noise** is simply a set of additional permissions at a lower level that *should not* be impactful.

For each group, we take the **impactful set** of permissions, and add **noise**, and combine this into a role.

We then take the *set cross-product* of the **impactful set** and the **noise**, and assert that the expected access level of that role to perform a given action.

As some of these sets are quite large, we sample some of the noise to reduce the search space.

**Example:**

Recall that we define a permission as a 4-tuple of `(level, resource_type, resource_id, action)` (for example, `(site, workspace, 123, read)`).

A `Set` is a slice of permissions. The search space of all possible permissions is too large, so instead this package allows generating more meaningful sets for testing. This is equivalent to pruning in AI problems: a technique to reduce the size of the search space by removing parts that do not have significance.

The resulting search space for a row is the cross product between all sets in said row. `+` indicates the union of two sets. For example, Y+_ indicates the union of all positive permissions and abstain permissions.

| Row | * | Site | Org | Org:mem | User | Access |

|-----|------|------|------|---------|------|--------|

| W+ | Y+_ | YN_ | YN_ | YN_ | YN_ | Y |

| U- | _ | _ | _ | _ | N+Y_ | N |

| A+ | _ | _ | _ | _ | Y+_ | Y |

| A- | _ | _ | _ | _ | _ | N |

Each row in the above table corresponds to a set of role permutations.

There are 12 possible groups of role permutations:

- Case 1 (W+):

- Impactful set: positive wildcard permissions.

- Noise: positive, negative, abstain across site, org, org-member, and user levels.

- Impactful set: nil permission.

- Noise: abstain on user level.

- Expected result: deny.