From 6e23cd9ef8c2f68e93f992e06f8d0660f71a4d95 Mon Sep 17 00:00:00 2001
From: bndw <ben@bdw.to>
Date: Mon, 16 Feb 2026 12:07:06 -0800
Subject: feat: add NIP-42 test client for auth and rate limit testing

---
 testclient/README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 testclient/README.md

(limited to 'testclient/README.md')

diff --git a/testclient/README.md b/testclient/README.md
new file mode 100644
index 0000000..a96ebe8
--- /dev/null
+++ b/testclient/README.md
@@ -0,0 +1,75 @@
+# NIP-42 Test Client
+
+A test client for testing NIP-42 WebSocket authentication and rate limiting.
+
+## Features
+
+- ✅ **Persistent keypair**: Generates and saves a keypair to `testclient.key`
+- ✅ **NIP-42 auth**: Automatically handles AUTH challenges (via library)
+- ✅ **Publish events**: Posts a kind 1 note to test write access
+- ✅ **Query events**: Subscribes to recent kind 1 notes to test read access
+- ✅ **Rate limit testing**: Can be run repeatedly to test rate limits
+
+## Usage
+
+```bash
+# Build
+go build -o testclient
+
+# Run against local relay
+./testclient
+
+# Run against remote relay
+./testclient -relay wss://muxstr.x.bdw.to
+
+# Run multiple times to test rate limiting
+for i in {1..10}; do ./testclient; done
+```
+
+## Adding to Relay Allowlist
+
+After first run, the client generates a keypair in `testclient.key`.
+
+To get the pubkey for your allowlist:
+
+```bash
+# Get hex pubkey
+cat testclient.key | xxd -r -p | sha256sum | cut -d' ' -f1
+
+# Or run the client and copy from the log output
+./testclient
+# Look for: "Using pubkey: <hex>"
+```
+
+Add this pubkey to your `config.yaml`:
+
+```yaml
+auth:
+  write:
+    enabled: true
+    allowed_npubs:
+      - npub1yourpubkeyhere...  # Convert hex to npub or use hex
+```
+
+## Testing Scenarios
+
+### Test NIP-42 Auth
+
+1. Enable write auth in config
+2. Add testclient pubkey to allowlist
+3. Run client - should succeed
+4. Remove pubkey from allowlist
+5. Run client - should receive AUTH challenge and fail
+
+### Test Rate Limiting
+
+```bash
+# Spam events to trigger rate limit
+while true; do ./testclient; sleep 0.1; done
+```
+
+Expected: After N requests/sec, receives "rate limit exceeded"
+
+## Dependencies
+
+- `fiatjaf.com/nostr` - Official Go Nostr library with NIP-42 support
-- 
cgit v1.2.3