docs(trusted-documents): Clarify trusted documents and persisted oper…

…ations
ldebruijn · Sep 14, 2024 · fe3cf59 · fe3cf59
1 parent f62e996
commit fe3cf59
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ _This is repository inspired by the great work of the Javascript [GraphQL Armor]
 
 ## Features
 
-* [Persisted Operations](docs/protections/persisted_operations.md)
+* [Trusted Documents (Persisted Operations)](docs/protections/trusted_documents)
 * [Block Field Suggestions](docs/protections/block_field_suggestions.md)
 * [Obfuscate upstream errors](docs/protections/obfuscate_upstream_errors.md)
 * [Max Aliases](docs/protections/max_aliases.md)

diff --git a/docs/README.md b/docs/README.md
@@ -18,7 +18,7 @@ Protect supports various running modes for different needs and purposes.
 
 This section contains all the documentation about each protection feature.
 
-* [Persisted Operations](protections/persisted_operations.md)
+* [Persisted Operations](protections/trusted_documents)
 * [Block Field Suggestions](protections/block_field_suggestions.md)
 * [Max Aliases](protections/max_aliases.md)
 * [Max Tokens](protections/max_tokens.md)

diff --git a/docs/protections/persisted_operations.md → docs/protections/trusted_documents.md b/docs/protections/persisted_operations.md → docs/protections/trusted_documents.md
@@ -1,11 +1,19 @@
-# Persisted Operations
+# Trusted Documents (Persisted Operations)
 
 Persisted Operations are essentially an operation allowlist. Persisted Operations provide an additional layer of security to your GraphQL API by disallowing arbitrary queries to be performed against your APIs.
 
 Check [Production Considerations](https://www.graphile.org/postgraphile/production/#simple-query-allowlist-persisted-queries--persisted-operations) for a more in-depth reasoning.
 
 We recommend that all GraphQL APIs that only intend a specific/known set of clients to use the API should use Persisted Operations.
 
+## What is the difference between Trusted Documents and Persisted Operations?
+
+They are the same thing. The intention is to compose a set of operations you expect to happen, typically during the build time of your clients, and load these onto your server. You allow only these operations to be executed through the exchange of the ID (or hash) of these operations.
+
+Trusted Documents conveys these operations are trusted.
+
+We use Trusted Documents and Persisted Operations interchangeably in this documentation.
+
 <!-- TOC -->
 
 ## Configuration
@@ -14,7 +22,7 @@ You can configure `graphql-protect` to enable Persisted Operations.
 
 ```yaml
 # ...
-
+# Trusted documents uses the same configuration as persisted operations, as they are the same thing.
 persisted_operations:
   # Enable or disable the feature, disabled by default
   enabled: false