1 files changed, 181 insertions, 0 deletions

diff --git a/internal/auth/README.md b/internal/auth/README.md
new file mode 100644
index 0000000..adfe260
--- /dev/null
+++ b/internal/auth/README.md
@@ -0,0 +1,181 @@
+# Nostr HTTP Authentication (NIP-98)
+
+This package implements [NIP-98](https://github.com/nostr-protocol/nips/blob/master/98.md) authentication for gRPC using the standard `credentials.PerRPCCredentials` interface.
+
+## Overview
+
+NIP-98 provides HTTP authentication using Nostr event signatures instead of bearer tokens or OAuth2. It uses cryptographic signatures to prove the request came from a specific public key, without requiring passwords or centralized identity providers.
+
+## How It Works
+
+### Authentication Flow
+
+1. **Client** creates a special kind 27235 event with:
+   - `u` tag: Full request URI
+   - `method` tag: HTTP method (GET, POST, etc.) or gRPC method name
+   - `payload` tag (optional): SHA256 hash of the request body
+   - `created_at`: Current Unix timestamp
+
+2. **Client** signs the event with their private key
+
+3. **Client** base64-encodes the event JSON and sends it in the `Authorization` header:
+   ```
+   Authorization: Nostr <base64-encoded-event>
+   ```
+
+4. **Server** validates the event:
+   - Verifies the signature matches the pubkey
+   - Checks the timestamp is recent (prevents replay attacks)
+   - Verifies the `u` and `method` tags match the actual request
+   - Optionally validates the payload hash
+
+5. **Server** adds the validated pubkey to the request context for use by handlers
+
+### Example Event
+
+```json
+{
+  "id": "9e1b6471f...",
+  "pubkey": "79be667ef9dc...",
+  "created_at": 1682327852,
+  "kind": 27235,
+  "tags": [
+    ["u", "https://api.example.com/nostr.v1.NostrRelay/PublishEvent"],
+    ["method", "POST"],
+    ["payload", "5c9e3a4d..."]
+  ],
+  "content": "",
+  "sig": "d2d6e9f0..."
+}
+```
+
+## Usage
+
+### Client Side
+
+Use the `NostrCredentials` type with standard gRPC dial options:
+
+```go
+import (
+    "google.golang.org/grpc"
+    "northwest.io/muxstr/internal/auth"
+    "northwest.io/muxstr/internal/nostr"
+)
+
+// Generate or load your private key
+key, _ := nostr.GenerateKey()
+
+// Create credentials
+creds := auth.NewNostrCredentials(key)
+
+// Use with gRPC client
+conn, err := grpc.NewClient(
+    "localhost:50051",
+    grpc.WithPerRPCCredentials(creds),
+    grpc.WithTransportCredentials(insecure.NewCredentials()),
+)
+```
+
+The credentials automatically sign each request with a fresh NIP-98 event.
+
+### Server Side
+
+Use the interceptors to validate incoming requests:
+
+```go
+import (
+    "google.golang.org/grpc"
+    "northwest.io/muxstr/internal/auth"
+)
+
+// Create auth options
+authOpts := &auth.InterceptorOptions{
+    TimestampWindow: 60, // Accept events within 60 seconds
+    Required:        true, // Reject unauthenticated requests
+}
+
+// Create gRPC server with interceptors
+server := grpc.NewServer(
+    grpc.UnaryInterceptor(auth.NostrUnaryInterceptor(authOpts)),
+    grpc.StreamInterceptor(auth.NostrStreamInterceptor(authOpts)),
+)
+```
+
+### Accessing the Authenticated Pubkey
+
+In your handlers, retrieve the authenticated pubkey from the context:
+
+```go
+func (s *Server) PublishEvent(ctx context.Context, req *pb.PublishEventRequest) (*pb.PublishEventResponse, error) {
+    pubkey, ok := auth.PubkeyFromContext(ctx)
+    if !ok {
+        return nil, status.Error(codes.Unauthenticated, "no authentication")
+    }
+
+    // Verify the event was signed by the authenticated user
+    if req.Event.Pubkey != pubkey {
+        return nil, status.Error(codes.PermissionDenied, "event pubkey doesn't match auth")
+    }
+
+    // Process the event...
+}
+```
+
+## Security Considerations
+
+### Replay Protection
+
+Events include a `created_at` timestamp. The server validates that events are recent (within the configured `TimestampWindow`). This prevents replay attacks where an attacker intercepts and re-sends a valid auth event.
+
+### Transport Security
+
+While NIP-98 provides authentication (proving who you are), it doesn't provide encryption. Use TLS/SSL to encrypt the connection and prevent eavesdropping.
+
+```go
+// Client with TLS
+creds := credentials.NewClientTLSFromCert(nil, "")
+conn, err := grpc.NewClient(addr,
+    grpc.WithTransportCredentials(creds),
+    grpc.WithPerRPCCredentials(nostrCreds),
+)
+```
+
+### Payload Validation
+
+The `payload` tag is optional but recommended for POST/PUT requests. When present, the server can verify the request body hasn't been tampered with:
+
+```go
+authOpts := &auth.InterceptorOptions{
+    ValidatePayload: true, // Verify payload hash if present
+}
+```
+
+## Configuration Options
+
+### InterceptorOptions
+
+- **`TimestampWindow`**: Maximum age of events in seconds (default: 60)
+- **`Required`**: Whether to reject unauthenticated requests (default: false)
+- **`ValidatePayload`**: Whether to verify payload hash when present (default: false)
+- **`AllowedPubkeys`**: Optional whitelist of allowed pubkeys (nil = allow all)
+
+### NostrCredentials Options
+
+- **`IncludePayload`**: Whether to include payload hash in auth events (default: false)
+
+## Benefits Over Traditional Auth
+
+1. **No passwords**: Uses public key cryptography
+2. **Decentralized**: No central identity provider
+3. **Per-request auth**: Each request is independently authenticated
+4. **Nostr compatible**: Works with existing Nostr identities and tools
+5. **Standard pattern**: Uses industry-standard gRPC credentials interface
+6. **Key rotation**: Easy to rotate keys without server-side updates
+
+## Compatibility
+
+This implementation follows the gRPC `credentials.PerRPCCredentials` interface, making it a drop-in replacement for OAuth2, JWT, or other auth mechanisms. It works with:
+
+- Standard gRPC clients (Go, Python, JS, etc.)
+- gRPC-Web and Connect protocol
+- All gRPC features (unary, streaming, metadata, etc.)