From 606e0a3329a3534a00889eee19c25e7d432f7d2d Mon Sep 17 00:00:00 2001
From: bndw <ben@bdw.to>
Date: Sat, 14 Feb 2026 10:11:16 -0800
Subject: refactor: restructure auth config for better UX

Changed from flat structure to hierarchical read/write config:

Before:
  auth:
    enabled: bool
    required: bool
    allowed_npubs_read: []
    allowed_npubs_write: []

After:
  auth:
    read:
      enabled: bool
      allowed_npubs: []
    write:
      enabled: bool
      allowed_npubs: []

Three states per operation:
- enabled=false: no auth, allow all
- enabled=true, allowed_npubs=[]: auth required, any valid signature
- enabled=true, allowed_npubs=[...]: auth required, whitelist only

Much clearer semantics and easier to reason about.
---
 internal/config/README.md | 70 +++++++++++++++++++++++++++--------------------
 1 file changed, 41 insertions(+), 29 deletions(-)

(limited to 'internal/config/README.md')

diff --git a/internal/config/README.md b/internal/config/README.md
index 7deb38f..3dcf215 100644
--- a/internal/config/README.md
+++ b/internal/config/README.md
@@ -80,41 +80,51 @@ database:
 
 # Authentication configuration
 auth:
-  # Enable authentication
-  enabled: false
-
-  # Require authentication for all requests
-  # If false, authentication is optional (pubkey available if provided)
-  required: false
+  # Read authentication (Subscribe, QueryEvents, CountEvents)
+  read:
+    enabled: false          # false = no auth, allow all
+    allowed_npubs: []       # npub format only (e.g., npub1...)
+    # If enabled=false: no auth, allow all reads
+    # If enabled=true && allowed_npubs=[]: auth required, any valid signature accepted
+    # If enabled=true && allowed_npubs=[...]: auth required, only whitelisted npubs
+
+  # Write authentication (PublishEvent, PublishBatch)
+  write:
+    enabled: false
+    allowed_npubs: []
 
   # Timestamp window in seconds for replay protection
   timestamp_window: 60
 
-  # Allowed npubs for read operations (optional, whitelist)
-  # If empty, all valid signatures are accepted for reads
-  # Use npub format only (e.g., npub1...)
-  allowed_npubs_read: []
-
-  # Allowed npubs for write operations (optional, whitelist)
-  # If empty, all valid signatures are accepted for writes
-  # Use npub format only (e.g., npub1...)
-  allowed_npubs_write: []
-
-  # Example use cases:
-  # - Public relay: allowed_npubs_write (only some can publish), empty read (everyone can read)
-  # - Private relay: both lists populated (restricted read and write)
-  # - Open relay: both lists empty (everyone can read and write)
-  #
-  # Example:
-  # allowed_npubs_read:
-  #   - npub1a2b3c4d5e6f...
-  # allowed_npubs_write:
-  #   - npub1a2b3c4d5e6f...
-
   # Skip authentication for these methods
   skip_methods:
     - "/grpc.health.v1.Health/Check"
 
+# Common patterns:
+# Public relay (anyone can read, only whitelisted can write):
+#   read:
+#     enabled: false
+#   write:
+#     enabled: true
+#     allowed_npubs:
+#       - npub1...
+#
+# Private relay (whitelisted read and write):
+#   read:
+#     enabled: true
+#     allowed_npubs:
+#       - npub1...
+#   write:
+#     enabled: true
+#     allowed_npubs:
+#       - npub1...
+#
+# Open relay (everyone can read and write):
+#   read:
+#     enabled: false
+#   write:
+#     enabled: false
+
 # Rate limiting configuration
 rate_limit:
   # Enable rate limiting
@@ -235,8 +245,10 @@ Complex types:
 
 ```bash
 # Lists (comma-separated, npub format)
-export MUXSTR_AUTH_ALLOWED_NPUBS_READ="npub1...,npub1..."
-export MUXSTR_AUTH_ALLOWED_NPUBS_WRITE="npub1..."
+export MUXSTR_AUTH_READ_ENABLED=true
+export MUXSTR_AUTH_READ_ALLOWED_NPUBS="npub1...,npub1..."
+export MUXSTR_AUTH_WRITE_ENABLED=true
+export MUXSTR_AUTH_WRITE_ALLOWED_NPUBS="npub1..."
 
 # Durations
 export MUXSTR_SERVER_READ_TIMEOUT="30s"
-- 
cgit v1.2.3