feat: add server name scoping support in DNS TXT records (#481)

Implements optional n=<pattern> parameter in DNS TXT records to allow
fine-grained permission scoping for server names. This enables DNS
controllers to delegate limited namespaces to different teams while
maintaining security isolation.

Key changes:
- Added DNSAuthRecord struct to support name patterns alongside public keys
- Collect all valid DNS records instead of stopping at first match
- Validate name patterns must start with reverse domain to prevent
  cross-domain privilege escalation
- Added comprehensive tests for all scoping scenarios

Example usage:
v=MCPv1; k=ed25519; p=<key>; n=com.example/team-foo-*

This change addresses Microsoft's requirement for granular permission
control within path portions while preserving existing behavior for
records without the n= parameter.

Fixes #481

Author: jalateras

DNS_SCOPING_TEST_GUIDE.md

@@ -0,0 +1,294 @@
+# DNS TXT Name Scoping - Testing Guide
+
+This guide provides step-by-step instructions for testing the new DNS TXT name scoping feature that allows fine-grained permission control through the optional `n=<pattern>` parameter.
+
+## Prerequisites
+
+- Go 1.24.x installed
+- Access to DNS management for a test domain (or use mock testing)
+- Ed25519 key pair for signing
+
+## 1. Unit Testing
+
+### Run the DNS auth handler tests
+```bash
+# Run only DNS authentication tests
+go test ./internal/api/handlers/v0/auth -v -run TestDNSAuthHandler
+
+# Run the new name pattern scoping tests specifically
+go test ./internal/api/handlers/v0/auth -v -run TestDNSAuthHandler_NamePatternScoping
+```
+
+### Expected output
+All tests should pass, including:
+- Backward compatibility tests (records without `n=` parameter)
+- Specific name pattern tests
+- Multiple keys with different patterns
+- Edge cases (spaces, complex paths, etc.)
+
+## 2. Integration Testing with Local Server
+
+### Step 1: Start the local development environment
+```bash
+# Start the full stack with Docker
+make dev-compose
+
+# Or run locally without Docker
+make build
+make dev-local
+```
+
+### Step 2: Generate test Ed25519 key pairs
+```bash
+# Generate a key pair using OpenSSL
+openssl genpkey -algorithm ed25519 -out private1.pem
+openssl pkey -in private1.pem -pubout -out public1.pem
+
+# Extract the base64-encoded public key
+openssl pkey -in private1.pem -pubout -outform DER | tail -c +13 | base64
+```
+
+### Step 3: Create test DNS TXT records
+
+For testing, you can either:
+
+#### Option A: Use actual DNS (if you have a domain)
+Add these TXT records to your domain:
+
+```bash
+# Traditional wildcard (backward compatible)
+"v=MCPv1; k=ed25519; p=YOUR_PUBLIC_KEY_BASE64"
+
+# Scoped to specific pattern
+"v=MCPv1; k=ed25519; p=YOUR_PUBLIC_KEY_BASE64; n=com.yourdomain/team-alpha-*"
+
+# Another scoped pattern
+"v=MCPv1; k=ed25519; p=ANOTHER_PUBLIC_KEY_BASE64; n=com.yourdomain/team-beta-*"
+```
+
+#### Option B: Use mock testing (recommended for development)
+The test suite includes a mock DNS resolver that simulates DNS responses.
+
+## 3. API Testing
+
+### Step 1: Create a test script for authentication
+Create a file `test_dns_auth.go`:
+
+```go
+package main
+
+import (
+    "crypto/ed25519"
+    "encoding/base64"
+    "encoding/hex"
+    "encoding/json"
+    "fmt"
+    "net/http"
+    "strings"
+    "time"
+)
+
+func main() {
+    // Your test configuration
+    domain := "example.com"
+    registryURL := "http://localhost:8080"
+
+    // Generate timestamp
+    timestamp := time.Now().UTC().Format(time.RFC3339)
+
+    // Sign the timestamp with your private key
+    privateKeyBytes, _ := base64.StdEncoding.DecodeString("YOUR_PRIVATE_KEY_BASE64")
+    privateKey := ed25519.PrivateKey(privateKeyBytes)
+    signature := ed25519.Sign(privateKey, []byte(timestamp))
+    signedTimestamp := hex.EncodeToString(signature)
+
+    // Create the request
+    payload := map[string]string{
+        "domain":           domain,
+        "timestamp":        timestamp,
+        "signed_timestamp": signedTimestamp,
+    }
+
+    jsonData, _ := json.Marshal(payload)
+
+    // Send request to registry
+    resp, err := http.Post(
+        registryURL+"/v0/auth/dns",
+        "application/json",
+        strings.NewReader(string(jsonData)),
+    )
+
+    if err != nil {
+        panic(err)
+    }
+    defer resp.Body.Close()
+
+    // Parse response
+    var result map[string]interface{}
+    json.NewDecoder(resp.Body).Decode(&result)
+
+    fmt.Printf("Response: %+v\n", result)
+
+    // The JWT token will contain the scoped permissions
+    if token, ok := result["registry_token"].(string); ok {
+        // Decode and inspect the JWT claims to verify permissions
+        fmt.Printf("Token received: %s...\n", token[:50])
+    }
+}
+```
+
+### Step 2: Test different scenarios
+
+#### Test 1: Backward compatibility (no n= parameter)
+```bash
+# DNS TXT record:
+"v=MCPv1; k=ed25519; p=YOUR_KEY"
+
+# Expected permissions in JWT:
+# - com.example/*
+# - com.example.*
+```
+
+#### Test 2: Specific team scope
+```bash
+# DNS TXT record:
+"v=MCPv1; k=ed25519; p=YOUR_KEY; n=com.example/team-foo-*"
+
+# Expected permissions in JWT:
+# - com.example/team-foo-*
+```
+
+#### Test 3: Multiple keys with different scopes
+```bash
+# DNS TXT records:
+"v=MCPv1; k=ed25519; p=KEY1; n=com.example/app1-*"
+"v=MCPv1; k=ed25519; p=KEY2; n=com.example/app2-*"
+
+# Sign with KEY1, expect permission: com.example/app1-*
+# Sign with KEY2, expect permission: com.example/app2-*
+```
+
+## 4. Testing with the Publisher CLI
+
+### Step 1: Build the publisher tool
+```bash
+make publisher
+```
+
+### Step 2: Create a test server.json
+```json
+{
+  "name": "com.example/team-foo-server",
+  "description": "Test server with scoped permissions",
+  "version": "1.0.0"
+}
+```
+
+### Step 3: Attempt to publish with different scopes
+
+#### With matching scope (should succeed):
+```bash
+# DNS TXT: n=com.example/team-foo-*
+./bin/mcp-publisher publish server.json
+# Should succeed as the pattern matches
+```
+
+#### With non-matching scope (should fail):
+```bash
+# DNS TXT: n=com.example/team-bar-*
+# Trying to publish: com.example/team-foo-server
+./bin/mcp-publisher publish server.json
+# Should fail with permission denied
+```
+
+## 5. Verification Checklist
+
+- [ ] **Backward Compatibility**: Records without `n=` grant wildcard permissions
+- [ ] **Exact Scoping**: Records with `n=com.example/foo-*` only allow matching patterns
+- [ ] **Multiple Keys**: Different keys can have different scopes
+- [ ] **Pattern Matching**: Wildcards in patterns work correctly
+- [ ] **Edge Cases**:
+  - [ ] Spaces in `n=` value are trimmed
+  - [ ] Empty `n=` defaults to wildcard
+  - [ ] Complex paths like `com.example/services/auth/*` work
+  - [ ] Explicit `n=*` behaves like no `n=` parameter
+
+## 6. JWT Token Inspection
+
+To verify the permissions in the JWT token:
+
+```bash
+# Use jwt.io or a JWT decoder library to inspect the token
+# Look for the "permissions" claim:
+{
+  "permissions": [
+    {
+      "action": "publish",
+      "resource": "com.example/team-foo-*"
+    }
+  ]
+}
+```
+
+## 7. Common Test Scenarios
+
+### Scenario A: Enterprise Team Isolation
+```bash
+# Team Alpha's TXT record
+"v=MCPv1; k=ed25519; p=ALPHA_KEY; n=com.microsoft/team-alpha-*"
+
+# Team Beta's TXT record
+"v=MCPv1; k=ed25519; p=BETA_KEY; n=com.microsoft/team-beta-*"
+
+# Result: Each team can only publish to their namespace
+```
+
+### Scenario B: Gradual Migration
+```bash
+# Start with wildcard
+"v=MCPv1; k=ed25519; p=OLD_KEY"
+
+# Add scoped key alongside
+"v=MCPv1; k=ed25519; p=OLD_KEY"
+"v=MCPv1; k=ed25519; p=NEW_KEY; n=com.example/prod-*"
+
+# Both keys work, with different permission levels
+```
+
+### Scenario C: Subdomain Scoping
+```bash
+# Scope to specific subdomain path
+"v=MCPv1; k=ed25519; p=KEY; n=com.example.api/*"
+
+# Only allows: com.example.api/service1, com.example.api/service2, etc.
+```
+
+## Troubleshooting
+
+### Issue: "no valid MCP public keys found"
+- Verify TXT record format exactly matches the pattern
+- Check base64 encoding of public key
+- Ensure no extra spaces in the record
+
+### Issue: "signature verification failed"
+- Confirm timestamp is within ±15 seconds
+- Verify private key matches public key in TXT record
+- Check signature is hex-encoded
+
+### Issue: Permission denied despite correct pattern
+- Inspect JWT token to see actual permissions
+- Verify the pattern in `n=` matches exactly
+- Check for typos in the resource pattern
+
+## Security Considerations
+
+1. **Key Rotation**: The system supports multiple TXT records for zero-downtime rotation
+2. **Timestamp Window**: 15-second window prevents replay attacks
+3. **Pattern Validation**: Patterns are used as-is, ensure they're correctly formatted
+4. **DNS Propagation**: Allow time for DNS changes to propagate (usually 5-60 minutes)
+
+## Additional Resources
+
+- [Original Issue #481](https://github.com/modelcontextprotocol/registry/issues/481)
+- [Pull Request #490](https://github.com/modelcontextprotocol/registry/pull/490)
+- [DNS Authentication Documentation](../docs/guides/publishing/auth-dns.md)