add docs for access control audit

pages/spicedb/modeling/_meta.json

@@ -5,5 +5,6 @@
   "recursion-and-max-depth": "Recursion & Max Depth",
   "protecting-a-list-endpoint": "Protecting a List Endpoint",
   "migrating-schema": "Updating and Migrating Schema",
-  "access-control-management": "Access Control Management"
+  "access-control-management": "Access Control Management",
+  "access-control-audit": "Access Control Audit"
 }

pages/spicedb/modeling/access-control-audit.mdx

@@ -0,0 +1,104 @@
+import { Callout } from 'nextra/components';
+
+# Access Control Audit
+
+Aside from providing means to [manage access control], another common feature is tools to audit access control.  
+This is put in place to let application administrators or users themselves understand:
+
+- what permissions do users have
+- how permissions have changed over time
+
+This is intimately related to [access-control management] but focuses on other types of queries over your application permissions.
+
+## Auditing User Permissions: What Permissions Does A User Have Over A Resource?
+
+If you want to determine the computed permission a user has over a resource you can leverage two different APIs in SpiceDB.
+
+- [ExperimentalReflectSchema] lets you query the permissions available for a specific resource.
+  You can even filter by permission name, or a permission name prefix.
+- [BulkCheckPermission] lets you perform various permission checks in a single round-trip.
+  This is more efficient than issuing individual checks because SpiceDB will batch many of the subproblems involved.
+
+## Auditing Access Grants: How Have Access Grants Changed?
+
+As we described in [access-control management], we distinguish **access grants** from **permissions**:
+
+- user `joe` being assigned as `reader` on repository `kubernetes` is an access grant
+- user `joe` having `read` permission over repository `kubernetes` is a permission
+
+Access grants describe how a subject can be granted permission to perform an operation over a resource, like for example *"a user views repository"*.
+A permission is a computation of all the different ways in which a user can be granted (or denied) access, like a direct role grant, indirectly via a team, indirectly as the owner of a top-level organization, temporarily as an auditor...
+
+To understand how access grants in the system have changed over time, you can use SpiceDB [Watch] API, which lets you stream all relationship changes.
+Please note that the [Watch] API is a near real-time streaming API, and thus the application developer is responsible for persisting the audit history according to their needs.
+By default, SpiceDB holds up to 24 hours of change history, after which it is garbage collected automatically.
+
+Let's assume the traditional GitHub repository authorization model:
+
+```zed
+definition user {}
+
+definition team {
+  relation member: user
+}
+
+definition repository {
+  relation role_reader: user | team#member
+  relation role_writer: user | team#member
+  relation role_adminer: user | team#member
+
+  permission read = role_reader + write
+  permission write = role_writer + admin
+  permission admin = role_adminer
+  
+}
+```
+
+If you wanted to understand how the access grants to the `kubernetes` repository have changed over time, you could call the [Watch] API and filter by `resource_type=repository` and `optional_resource_id=kubernetes`.
+
+## Auditing Permissions: How Have Permissions Changed?
+
+<Callout type="info">
+  Auditing permission changes is a very complex problem to solve at scale: that's why we built [Authzed Materialize].
+</Callout>
+
+SpiceDB does not offer an API to stream permission changes, but you could use a combination of APIs to compute a limited audit trail of permission changes.
+This strategy could also be used to build a materialized index of permissions to [Protect a List Endpoint] in your application's database.
+
+<Callout type="warning">
+  Please note this strategy is **very computationally intensive**, and it would very likely require scaling out a SpiceDB cluster.
+  It's only likely to work under very narrow use cases that can exploit domain awareness to reduce how many computations need to be run.
+</Callout>
+
+1. Use the [Watch] API to stream all relationship changes in the system
+1. Use the [ExperimentalComputablePermissions] API to determine all permissions affected by a relationship change
+
+These two APIs will be used as the foundation to start recomputing permissions, and the more siloed and controlled the use case, the higher the chances this can work at scale.
+
+- If you can silo the relationship changes to a specific resource, you could recompute all users that have permission over that resource by running [LookupSubjects] for each one of the affected permissions determined by [ExperimentalComputablePermissions].
+  Please note this does not give you the delta of permission changes, that will be the responsibility of the application developer.
+- However, if you can't exploit the application domain to silo how a permission changes, you'd be forced to recompute *all subjects over all available resources*, which is a **very** expensive operation to run to yield a potentially small delta of permission changes.
+
+## Auditing SpiceDB API Request and Responses
+
+SpiceDB does not offer an API to determine what API calls it has received.
+Some alternative options include:
+
+- Building a custom middleware for SpiceDB and using the [Middleware Framework].
+- Wrapping SpiceDB into another service that acts as the single access point to SpiceDB and thus can audit all access
+- Retrieving access logs using SpiceDB `--grpc-log-requests-enabled` and `--grpc-log-response-enabled`
+- Using [Authzed Audit Logging]
+
+[manage access control]: ./access-control-management
+[access-control management]: ./access-control-management
+[ExperimentalComputablePermissions]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.ExperimentalService.ExperimentalComputablePermissions
+[BulkCheckPermission]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.ExperimentalService.BulkCheckPermission
+[Watch]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.WatchService.Watch
+[Authzed Materialize]: https://authzed.com/products/authzed-materialize
+[ExperimentalComputablePermissions]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.ExperimentalService.ExperimentalComputablePermissions
+[BulkCheckPermission]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.ExperimentalService.BulkCheckPermission
+[Protect a List Endpoint]: ./protecting-a-list-endpoint
+[ExperimentalReflectSchema]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.ExperimentalService.ExperimentalReflectSchema
+[LookupSubjects]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupSubjects
+[Authzed Audit Logging]: https://authzed.com/docs/authzed/concepts/audit-logging
+[Middleware Framework]: https://github.com/authzed/spicedb/blob/b6f08c0fd2880540cbf564188b89141493ea3273/pkg/cmd/server/middleware.go