Improve local development credential documentation (#402)

Co-authored-by: Maria Ines Parnisari <[email protected]>

Author: ivanauth

app/spicedb/concepts/commands/page.mdx

@@ -27,13 +27,12 @@ A database that stores and computes permissions
 
 ### Children commands
 
-- [spicedb datastore](#reference-spicedb-datastore)	 - datastore operations
-- [spicedb lsp](#reference-spicedb-lsp)	 - serve language server protocol
-- [spicedb man](#reference-spicedb-man)	 - Generate man page
-- [spicedb serve](#reference-spicedb-serve)	 - serve the permissions database
-- [spicedb serve-testing](#reference-spicedb-serve-testing)	 - test server with an in-memory datastore
-- [spicedb version](#reference-spicedb-version)	 - displays the version of SpiceDB
-
+- [spicedb datastore](#reference-spicedb-datastore) - datastore operations
+- [spicedb lsp](#reference-spicedb-lsp) - serve language server protocol
+- [spicedb man](#reference-spicedb-man) - Generate man page
+- [spicedb serve](#reference-spicedb-serve) - serve the permissions database
+- [spicedb serve-testing](#reference-spicedb-serve-testing) - test server with an in-memory datastore
+- [spicedb version](#reference-spicedb-version) - displays the version of SpiceDB
 
 ## Reference: `spicedb datastore`
 
@@ -49,11 +48,10 @@ Operations against the configured datastore
 
 ### Children commands
 
-- [spicedb datastore gc](#reference-spicedb-datastore-gc)	 - executes garbage collection
-- [spicedb datastore head](#reference-spicedb-datastore-head)	 - compute the head (latest) database migration revision available
-- [spicedb datastore migrate](#reference-spicedb-datastore-migrate)	 - execute datastore schema migrations
-- [spicedb datastore repair](#reference-spicedb-datastore-repair)	 - executes datastore repair
-
+- [spicedb datastore gc](#reference-spicedb-datastore-gc) - executes garbage collection
+- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head (latest) database migration revision available
+- [spicedb datastore migrate](#reference-spicedb-datastore-migrate) - execute datastore schema migrations
+- [spicedb datastore repair](#reference-spicedb-datastore-repair) - executes datastore repair
 
 ## Reference: `spicedb datastore gc`
 
@@ -148,8 +146,6 @@ spicedb datastore gc [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb datastore head`
 
 compute the head (latest) database migration revision available
@@ -181,8 +177,6 @@ spicedb datastore head [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb datastore migrate`
 
 Executes datastore schema migrations for the datastore.
@@ -222,8 +216,6 @@ spicedb datastore migrate [revision] [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb datastore repair`
 
 Executes a repair operation for the datastore
@@ -317,8 +309,6 @@ spicedb datastore repair [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb lsp`
 
 serve language server protocol
@@ -342,20 +332,17 @@ spicedb lsp [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb man`
 
 Generate a man page for SpiceDB.
- The output can be redirected to a file and installed to the system:
+The output can be redirected to a file and installed to the system:
 
 ```
   spicedb man > spicedb.1
   sudo mv spicedb.1 /usr/share/man/man1/
   sudo mandb  # Update man page database
 ```
 
-
 ```
 spicedb man
 ```
@@ -368,8 +355,6 @@ spicedb man
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb serve`
 
 start a SpiceDB server
@@ -558,8 +543,6 @@ spicedb serve [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb serve-testing`
 
 An in-memory spicedb server which serves completely isolated datastores per client-supplied auth token used.
@@ -621,8 +604,6 @@ spicedb serve-testing [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb version`
 
 displays the version of SpiceDB
@@ -644,6 +625,3 @@ spicedb version [flags]
       --log-level string     verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info")
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
-
-
-

app/spicedb/getting-started/client-libraries/page.mdx

@@ -1,3 +1,5 @@
+import { Tabs } from "nextra/components";
+
 # Official Client Libraries
 
 SpiceDB is primarily accessed by a [gRPC] API and thus client libraries can be generated for any programming language.
@@ -9,13 +11,55 @@ AuthZed builds and maintains gRPC client libraries for the following languages:
 - [Python](https://github.com/authzed/authzed-py)
 - [Ruby](https://github.com/authzed/authzed-rb)
 - [Java](https://github.com/authzed/authzed-java)
-- [Dotnet](https://github.com/authzed/authzed-dotnet)
+- [.NET](https://github.com/authzed/authzed-dotnet)
 
 Because the above libraries are generated from protobuf definitions in our [API repo],
 the primary documentation for the gRPC API is in the [buf documentation] for SpiceDB's services.
 The gRPC client documentation associated with each host language will also be helpful for putting together invocations.
 Additionally, there are `example` directories in the client libraries that provide example usages.
 
+## Local Development
+
+When developing locally, you'll need to configure your client based on how SpiceDB is running.
+
+### SpiceDB running without TLS (most common)
+
+If SpiceDB is started without TLS (using `--grpc-no-tls`), use insecure plaintext credentials:
+
+<Tabs items={["Node", "Go", "Python", "Ruby", "Java", ".NET"]}>
+  <Tabs.Tab>`v1.ClientSecurity.INSECURE_PLAINTEXT_CREDENTIALS`</Tabs.Tab>
+  <Tabs.Tab>
+    `grpcutil.WithInsecureBearerToken()` and
+    `grpc.WithTransportCredentials(insecure.NewCredentials())`
+  </Tabs.Tab>
+  <Tabs.Tab>`insecure_bearer_token_credentials()`</Tabs.Tab>
+  <Tabs.Tab>`credentials: :this_channel_is_insecure`</Tabs.Tab>
+  <Tabs.Tab>`.usePlaintext()`</Tabs.Tab>
+  <Tabs.Tab>
+    `ChannelCredentials.Insecure` with `UnsafeUseInsecureChannelCallCredentials
+    = true` (also requires
+    `AppContext.SetSwitch("System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport",
+    true)`)
+  </Tabs.Tab>
+</Tabs>
+
+This applies to localhost, Docker, OrbStack, and other local environments running without TLS.
+
+### SpiceDB running with TLS using self-signed certificates
+
+If SpiceDB is running with TLS but using a self-signed or untrusted certificate:
+
+<Tabs items={['Node', 'Go']}>
+    <Tabs.Tab>
+        `v1.ClientSecurity.INSECURE_LOCALHOST_ALLOWED` (allows localhost connections without CA verification)
+    </Tabs.Tab>
+    <Tabs.Tab>
+        Load the self-signed CA explicitly with `grpcutil.WithCustomCerts()` or use `grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{InsecureSkipVerify: true}))` for localhost only (not recommended for production)
+    </Tabs.Tab>
+</Tabs>
+
+See the [Protecting a Blog Application](./protecting-a-blog#checking-permissions) tutorial for examples.
+
 ## HTTP Clients
 
 SpiceDB exposes an HTTP API when run with the `--http-enabled` flag.