feat: add NIP-42 test client for auth and rate limit testing

1 files changed, 75 insertions, 0 deletions

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