SpiceDB Zookies: Solving Causal Consistency in ReBAC

Learn how to eliminate the 'New Enemy' problem in SpiceDB by implementing zookies to ensure causal consistency between authorization writes and reads.

The Problem: The 'New Enemy' Consistency Gap

In a distributed Relationship-Based Access Control (ReBAC) system, a common failure mode is the lack of causal consistency. This occurs when a user is granted a permission (a write), but a subsequent authorization check (a read) hits a database replica that hasn't yet received that update. In security contexts, this is known as the 'New Enemy' problem: a user is removed from a sensitive group, but because of replication lag, they can still access the resource for several seconds.

The takeaway is that eventual consistency is insufficient for authorization. To prevent unauthorized access during replication lag, you must use consistency tokens—referred to in SpiceDB as zookies—to ensure the check is performed against a snapshot of data at least as fresh as the last known change.

The Smallest Suitable Design for Causal Consistency

To implement causal consistency, the application must move from a stateless \"check\" pattern to a stateful \"token-passing\" pattern. The architecture requires three components: a relationship store (SpiceDB), a persistent storage backend (such as CockroachDB), and a client application that manages the zookie lifecycle.

The Zookie Workflow

Write Path: When the application updates a relationship (e.g., adding a user to a folder), the SpiceDB Write API returns a zookie. This token represents a specific point in the database's timeline.
Persistence: The application stores this zookie alongside the user's session or the object's metadata in its own primary database.
Read Path: When the user attempts to access a resource, the application retrieves the stored zookie and passes it into the Check API request.
Verification: SpiceDB ensures the request is routed to a node or snapshot that has seen the transaction associated with that zookie before returning a boolean result.

Trust and Data Boundaries

A critical engineering decision in SpiceDB is the separation of Identity from Authorization. SpiceDB does not store user passwords, email addresses, or object metadata; it only stores the relationships between IDs.

Application Boundary: The calling service is responsible for authenticating the user and mapping a session to a subject ID (e.g., user:123).
SpiceDB Boundary: SpiceDB is the single source of truth for the graph. It trusts the application to provide the correct IDs but does not verify if those IDs exist in the application's primary database.
Consistency Boundary: The zookie acts as the bridge between the write-path and the read-path, ensuring the application's view of the world is consistent with the authorization engine's view.

Implementation Example: Causal Check

Consider a scenario where a user is promoted to an admin role. Without a zookie, a rapid succession of requests might result in a 403 Forbidden because the read hit a stale replica.

# 1. Update relationship (Run via SpiceDB API/CLI)\n# Permission: user:alice is now an admin of organization:engineering\n# Expected result: Returns a zookie (e.g., \"zookie_v1_12345\")\nspicedb write relationship organization:engineering#admin user:alice

To verify the permission immediately, the application must include that specific token in the check request:

# 2. Perform Check with Zookie\n# Command: spicedb check --zookie \"zookie_v1_12345\" --subject user:alice --relation admin --object organization:engineering\n# Expected result: True

Risk: If the --zookie flag is omitted, SpiceDB may return a result based on the local node's current state, which could be stale, leading to intermittent authorization failures during high-write volumes.

Operational Checks and Failure Modes

Diagnostic Decision Table

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Symptom	Likely Cause	Verification Step
Intermittent 403s after a grant	Missing or stale zookies	Compare `Check` results with and without the latest zookie.
Increased latency on `Check`	Deep graph traversal	Analyze the schema for recursive `relation` definitions that create long chains.
Zookie \"Too Old\" Errors	Storage cleanup/TTL	Check the retention policy of the underlying database snapshots.

Failure Modes

Deep Nesting: If your schema defines permissions as user > group > sub-group > folder > file, SpiceDB must perform multiple recursive lookups. This can lead to latency spikes.
Zookie Loss: If the application fails to persist the zookie, it must fall back to a \"global\" consistency level, which may increase latency as the system ensures it is reading the most recent data across the cluster.

Conditions for Design Change

The zookie-based architecture is optimal for most ReBAC needs, but you should reconsider this design if:

Ultra-Low Latency Requirements: If the millisecond overhead of zookie validation is unacceptable, you may need to move to a cached permission model, accepting the risk of temporary staleness.
Massive Fan-out: If a single subject is a member of thousands of groups, the graph traversal may become a bottleneck, requiring a flattening of the relationship schema.

To verify the result of your implementation, deploy a test instance and execute a Write followed immediately by a Check without a zookie. Repeat this in a loop; if you see any False responses for a granted permission, your system is experiencing the consistency gap and requires zookie integration.

Solving Causal Consistency in ReBAC with SpiceDB Zookies