Return Evaluated Caveat Context

[drew-richardson]

Problem Statement

1. Functional: we want to be able to export (synchronize) permissions to systems which cannot be modified to communicate with SpiceDB. Caveat details are a critical aspect of this.
2. Usability: we need to be able to display caveat details to users during review, approval, and auditing.
3. Availability: For resilience we want to back up and/or cache the result of CheckPermission calls so things will function even if SpiceDB is unavailable. The details of the relationship caveats are required for this.

Solution Brainstorm

Expand the SpiceDB permission lookup calls (ex: CheckPermission, LookupResources, and LookupSubjects) to optionally include information about the relationships with caveats encountered (Relationship including the CaveatName and Context) while evaluating the permission(s).

Example

Schema

caveat unexpired_grant(now timestamp, expires_at timestamp) {
   now < expires_at
}

definition person {}

definition team {
   relation member: person
   relation guest: person with unexpired_grant
   permission team_members = member + guest
}

definition application {
   relation owner: team
   relation user: team with unexpired_grant
   permission access = owner->team_members + user->team_members
}

Relationships

team:discovery#member@person:don
team:discovery#guest@person:drew[unexpired_grant:{"expires_at":"2024-09-01T00:00:00.000000Z"}]
team:discovery#guest@person:joe[unexpired_grant:{"expires_at":"2024-04-01T00:00:00.000000Z"}]
application:pulse#user@team:discovery[unexpired_grant:{"expires_at":"2024-07-01T00:00:00.000000Z"}]

Checks

To be concrete we will make a full proposal; however, we acknowledge that we are not the experts here and are being specific rather than prescriptive.

We propose adding a flag to the three primary permission calls (CheckPermission, LookupResources, and LookupSubjects) that will cause them to return all the caveat information for the edges traversed (userset rewritten) during the permission computation. Hence,

1. A successful CheckPermission call with

   application:pulse#access@person:drew with {"now":"2024-05-13T20:13:52.226861Z"}
   

   might return

   Permissionship: CheckPermissionResponse_PERMISSIONSHIP_HAS_PERMISSION
   [application:pulse#user@team:discovery[unexpired_grant:{"expires_at":"2024-07-01T00:00:00.000000Z"}],
   team:discovery#guest@person:drew[unexpired_grant:{"expires_at":"2024-09-01T00:00:00.000000Z"}]]
   

   In this example we might then take the minimum expires_at and use that in the cache or external system. In other cases, such as the country location, we might ensure they’re all the same (as you can’t be in two places at the same time) and use that.

2. A rejected CheckPermission call with

   application:pulse#access@person:joe with {"now":"2024-05-13T20:13:52.226861Z"}
   

   might return something like

   Permissionship: CheckPermissionResponse_PERMISSIONSHIP_NO_PERMISSION
   [application:pulse#user@team:discovery[unexpired_grant:{"expires_at":"2024-07-01T00:00:00.000000Z"}],
   team:discovery#guest@person:joe[unexpired_grant:{"expires_at":"2024-04-01T00:00:00.000000Z"}]]
   

3. A LookupSubjects with

   application:pulse#access@person:* with {"now":"2024-05-13T20:13:52.226861Z"}
   

   Would return something like

   [{SubjectObjectId: drew, Permissionship: LookupPermissionship_LOOKUP_PERMISSIONSHIP_HAS_PERMISSION,
   [application:pulse#user@team:discovery[unexpired_grant:{"expires_at":"2024-07-01T00:00:00.000000Z"}],
   team:discovery#guest@person:drew[unexpired_grant:{"expires_at":"2024-09-01T00:00:00.000000Z"}]]}]
   

   I think in this case, returning things without a permission is a bigger change to the API and so is reasonable to omit.