Designing Efficient Permission Inheritance in SpiceDB

Concrete Problem: Inherited Access in a File‑System‑Like Hierarchy

You need to grant a user read access to every file inside a folder, and you want that access to propagate when the user is added to a parent folder. With SpiceDB you model this as a recursive parent relationship in the tuple schema and rely on the Check API to resolve the inheritance. The challenge is to design the schema so that the Check call remains fast even when the folder tree is deep.

Thesis: Use a lightweight recursive tuple schema and test it early with the spdb CLI

SpiceDB’s ReBAC model lets you express recursive relationships declaratively. By keeping the schema simple and validating it with the CLI you can catch performance regressions before they hit production.

1. Define a Recursive Schema

The schema lives in a file called schema.spice and is uploaded with spdb schema upload. Below is a minimal example that models folders, files, and a parent relationship:

type folder
  relation child: folder | file

# Recursive parent relationship
relation parent: folder
  child

# Permission granted through parent chain
relation reader: folder
  parent
  owner

# Example principals
type user

# Example objects
object folder:root
object file:file1

Key points:

• parent is a *recursive* relation that points from a child to its parent.
• Permission inheritance is expressed by the reader relation, which includes parent and an owner relation (not shown).
• All tuples are stored in SpiceDB; the application does not need to maintain a separate access list.

2. Upload the Schema and Seed Tuples

Run the following on a machine with the spdb CLI installed and network access to the SpiceDB instance. You need the spdb:admin role to upload schemas and create tuples.

# Upload schema
spdb schema upload schema.spice

# Seed parent relationships
spdb tuple create folder:root parent folder:root
spdb tuple create folder:sub1 parent folder:root
spdb tuple create file:file1 parent folder:sub1

# Grant user Alice as reader of root
spdb tuple create folder:root reader user:alice

After these commands, the graph looks like:

Object	Relation	Principal
folder:root	parent	folder:root
folder:sub1	parent	folder:root
file:file1	parent	folder:sub1
folder:root	reader	user:alice

3. Test Permission Inheritance with the Check API

Use the spdb check command to verify that Alice can read file:file1. The command queries the graph and returns a boolean.

spdb check file:file1 reader user:alice
# Expected: true (Alice inherits reader from root through parent chain)

To confirm that the inheritance works, try a user that is not a reader of root:

spdb check file:file1 reader user:bob
# Expected: false

4. Monitor Latency and Understand Trade‑offs

Recursive queries can become expensive when the depth grows. SpiceDB uses a graph traversal algorithm that touches every node in the path. In a shallow hierarchy (depth < 5) the Check call is sub‑millisecond, but at depth 50 it can exceed 200 ms, especially under heavy write load.

Two mitigations:

• Indexing: SpiceDB automatically indexes tuples by relation and principal, but you can add index: true to critical relations in the schema to force more efficient lookups.
• Zookie Tokens: When you perform a spdb read with a Zookie token, SpiceDB guarantees that the read is consistent with the latest writes. However, generating and passing a Zookie adds a small overhead. In high‑write scenarios, consider batching writes and using a single Zookie for a batch of checks.

Actionable Checklist

1. Define a minimal recursive schema that captures your permission inheritance.
2. Upload the schema and seed tuples via spdb.
3. Use spdb check to validate inheritance logic early.
4. Measure Check latency on realistic tree depths; if latency > 100 ms, add indexing or flatten the hierarchy.
5. In production, monitor Check latency with Prometheus metrics exposed by SpiceDB.

By following these steps you can confidently use SpiceDB’s ReBAC model for complex permission graphs while keeping authorization checks performant.