From 9087254af2a53c4d4a2878a54d7bdd62bef95af4 Mon Sep 17 00:00:00 2001
From: Jess <140121672+jess-desu@users.noreply.github.com>
Date: Mon, 23 Sep 2024 16:54:37 -0400
Subject: [PATCH] Adding relationship integrity docs.mdx

Adding @josephschorr's relationship integrity docs
---
 pages/spicedb/concepts/datastores.mdx | 30 +++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/pages/spicedb/concepts/datastores.mdx b/pages/spicedb/concepts/datastores.mdx
index ca93f9f..8c339f3 100644
--- a/pages/spicedb/concepts/datastores.mdx
+++ b/pages/spicedb/concepts/datastores.mdx
@@ -125,6 +125,36 @@ ALTER ZONE default CONFIGURE ZONE USING gc.ttlseconds = 90000;
 
 [crdb-gc]: https://www.cockroachlabs.com/docs/stable/configure-replication-zones.html#replication-zone-variables
 
+#### Relationship Integrity
+
+Relationship Integrity is a new experimental feature in SpiceDB that ensures that data written into the supported backing datastores (currently: only CockroachDB) is validated as having been written by SpiceDB itself.
+
+- **What does relationship integrity ensure?**
+Relationship integrity primarily ensures that all relationships written into the backing datastore were written via a trusted instance of SpiceDB or that the caller has access to the key(s) necessary to write those relationships.
+It ensures that if someone gains access to the underlying datastore, they cannot simply write new relationships of their own invention.
+
+- **What does relationship integrity *not* ensure?** 
+Since the relationship integrity feature signs each individual relationship, it does not ensure that removal of relationships is by a trusted party.
+Schema is also currently unverified, so an untrusted party could change it as well.
+Support for schema changes will likely come in a future version.
+
+**Setting up relationship integrity**
+To run with relationship integrity, new flags must be given to SpiceDB:
+
+```zed
+spicedb serve ...existing flags...
+--datastore-relationship-integrity-enabled
+--datastore-relationship-integrity-current-key-id="somekeyid"
+--datastore-relationship-integrity-current-key-filename="some.key"
+```
+
+Place the generated key contents (which must support an HMAC key) in `some.key`
+
+**Deployment Process**
+1. Start with a **clean** datastore for SpiceDB. **At this time, migrating an existing SpiceDB installation is not supported.**
+2. Run the standard `migrate` command but with relationship integrity flags included.
+3. Run SpiceDB with the relationship integrity flags included.
+
 ## Cloud Spanner
 
 ### Usage Notes