From 9237814fedcd72ea76302ed0ce2726de1a8f2956 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Torjus=20H=C3=A5kestad?= <torjus@usit.uio.no>
Date: Sat, 7 Feb 2026 04:48:11 +0100
Subject: [PATCH] docs: add NATS subject structure and example server
 configuration

Document the complete subject hierarchy including deploy subjects,
response subjects, and discovery subject. Add example NATS server
configuration demonstrating tiered authentication with listener,
test deployer, and admin deployer permission patterns.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 133 insertions(+)

diff --git a/README.md b/README.md
index 24d2c1e..f06423d 100644
--- a/README.md
+++ b/README.md
@@ -256,6 +256,139 @@ nk -gen user -pubout
 
 Configure appropriate publish/subscribe permissions in your NATS server for each credential type.
 
+## NATS Subject Structure
+
+The deployment system uses the following NATS subject hierarchy:
+
+### Deploy Subjects
+
+| Subject Pattern | Purpose |
+|-----------------|---------|
+| `deploy.<tier>.<hostname>` | Deploy to a specific host |
+| `deploy.<tier>.all` | Deploy to all hosts in a tier |
+| `deploy.<tier>.role.<role>` | Deploy to hosts with a specific role in a tier |
+
+**Tier values:** `test`, `prod`
+
+**Examples:**
+- `deploy.test.myhost` - Deploy to myhost in test tier
+- `deploy.prod.all` - Deploy to all production hosts
+- `deploy.prod.role.dns` - Deploy to all DNS servers in production
+
+### Response Subjects
+
+| Subject Pattern | Purpose |
+|-----------------|---------|
+| `deploy.responses.<uuid>` | Unique reply subject for each deployment request |
+
+Deployers create a unique response subject for each request and include it in the `reply_to` field. Listeners publish status updates to this subject.
+
+### Discovery Subject
+
+| Subject Pattern | Purpose |
+|-----------------|---------|
+| `deploy.discover` | Host discovery requests and responses |
+
+Used by the `list_hosts` MCP tool and for discovering available deployment targets.
+
+## Example NATS Configuration
+
+Below is an example NATS server configuration implementing tiered authentication. This setup provides:
+
+- **Listeners** - Each host has credentials to subscribe to its own subjects and publish responses
+- **Test deployer** - Can deploy to test tier only (suitable for MCP without admin access)
+- **Admin deployer** - Can deploy to all tiers (for CLI or MCP with admin access)
+
+```conf
+authorization {
+  users = [
+    # Listener for a test-tier host
+    {
+      nkey: "UTEST_HOST1_PUBLIC_KEY_HERE"
+      permissions: {
+        subscribe: [
+          "deploy.test.testhost1"
+          "deploy.test.all"
+          "deploy.test.role.>"
+          "deploy.discover"
+        ]
+        publish: [
+          "deploy.responses.>"
+          "deploy.discover"
+        ]
+      }
+    }
+
+    # Listener for a prod-tier host with 'dns' role
+    {
+      nkey: "UPROD_DNS1_PUBLIC_KEY_HERE"
+      permissions: {
+        subscribe: [
+          "deploy.prod.dns1"
+          "deploy.prod.all"
+          "deploy.prod.role.dns"
+          "deploy.discover"
+        ]
+        publish: [
+          "deploy.responses.>"
+          "deploy.discover"
+        ]
+      }
+    }
+
+    # Test-tier deployer (MCP without admin)
+    {
+      nkey: "UTEST_DEPLOYER_PUBLIC_KEY_HERE"
+      permissions: {
+        publish: [
+          "deploy.test.>"
+          "deploy.discover"
+        ]
+        subscribe: [
+          "deploy.responses.>"
+          "deploy.discover"
+        ]
+      }
+    }
+
+    # Admin deployer (full access to all tiers)
+    {
+      nkey: "UADMIN_DEPLOYER_PUBLIC_KEY_HERE"
+      permissions: {
+        publish: [
+          "deploy.>"
+        ]
+        subscribe: [
+          "deploy.>"
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Key Permission Patterns
+
+| Credential Type | Publish | Subscribe |
+|-----------------|---------|-----------|
+| Listener | `deploy.responses.>`, `deploy.discover` | Own subjects, `deploy.discover` |
+| Test deployer | `deploy.test.>`, `deploy.discover` | `deploy.responses.>`, `deploy.discover` |
+| Admin deployer | `deploy.>` | `deploy.>` |
+
+### Generating NKeys
+
+```bash
+# Generate a keypair (outputs public key, saves seed to file)
+nk -gen user -pubout > mykey.pub
+# The seed (private key) is printed to stderr - save it securely
+
+# Or generate and save seed directly
+nk -gen user > mykey.seed
+nk -inkey mykey.seed -pubout  # Get public key from seed
+```
+
+The public key (starting with `U`) goes in the NATS server config. The seed file (starting with `SU`) is used by homelab-deploy via `--nkey-file`.
+
 ## License
 
 MIT