Merge branch 'master' of ssh://git.laantungir.net:222/laantungir/nostr_core_lib

Working on Ginxsom auth and NIP 42 on a different computer at the same
time. My bad.

build.sh

@@ -135,6 +135,7 @@ if [ "$HELP" = true ]; then
     echo "  011 - Relay information document"
     echo "  013 - Proof of Work"
     echo "  019 - Bech32 encoding (nsec/npub)"
+    echo "  042 - Authentication of clients to relays"
     echo "  044 - Encryption (modern)"
     echo ""
     echo "Examples:"
@@ -184,7 +185,7 @@ print_info "Auto-detecting needed NIPs from your source code..."
 NEEDED_NIPS=""
 if [ -n "$FORCE_NIPS" ]; then
     if [ "$FORCE_NIPS" = "all" ]; then
-        NEEDED_NIPS="001 004 005 006 011 013 019 044"
+        NEEDED_NIPS="001 004 005 006 011 013 019 042 044"
         print_info "Forced: Building all available NIPs"
     else
         # Convert comma-separated list to space-separated with 3-digit format
@@ -203,7 +204,7 @@ else
         # Check for nostr_core.h (includes everything)
         if grep -q '#include[[:space:]]*["\<]nostr_core\.h["\>]' *.c 2>/dev/null; then
             print_info "Found #include \"nostr_core.h\" - building all NIPs"
-            NEEDED_NIPS="001 004 005 006 011 013 019 044"
+            NEEDED_NIPS="001 004 005 006 011 013 019 042 044"
         elif [ -n "$DETECTED" ]; then
             NEEDED_NIPS="$DETECTED"
             print_success "Auto-detected NIPs: $(echo $NEEDED_NIPS | tr ' ' ',')"
@@ -221,7 +222,7 @@ fi
 
 # If building tests, include all NIPs to ensure test compatibility
 if [ "$BUILD_TESTS" = true ] && [ -z "$FORCE_NIPS" ]; then
-    NEEDED_NIPS="001 004 005 006 011 013 019 044"
+    NEEDED_NIPS="001 004 005 006 011 013 019 042 044"
     print_info "Building tests - including all available NIPs for test compatibility"
 fi
 
@@ -484,13 +485,14 @@ detect_system_curl
 ###########################################################################################
 
 SOURCES="nostr_core/crypto/nostr_secp256k1.c"
-SOURCES="$SOURCES nostr_core/crypto/nostr_aes.c"  
+SOURCES="$SOURCES nostr_core/crypto/nostr_aes.c"
 SOURCES="$SOURCES nostr_core/crypto/nostr_chacha20.c"
 SOURCES="$SOURCES cjson/cJSON.c"
 SOURCES="$SOURCES nostr_core/utils.c"
 SOURCES="$SOURCES nostr_core/nostr_common.c"
 SOURCES="$SOURCES nostr_core/core_relays.c"
 SOURCES="$SOURCES nostr_websocket/nostr_websocket_openssl.c"
+SOURCES="$SOURCES nostr_core/request_validator.c"
 
 NIP_DESCRIPTIONS=""
 
@@ -506,6 +508,7 @@ for nip in $NEEDED_NIPS; do
             011) NIP_DESCRIPTIONS="$NIP_DESCRIPTIONS NIP-011(Relay-Info)" ;;
             013) NIP_DESCRIPTIONS="$NIP_DESCRIPTIONS NIP-013(PoW)" ;;
             019) NIP_DESCRIPTIONS="$NIP_DESCRIPTIONS NIP-019(Bech32)" ;;
+            042) NIP_DESCRIPTIONS="$NIP_DESCRIPTIONS NIP-042(Auth)" ;;
             044) NIP_DESCRIPTIONS="$NIP_DESCRIPTIONS NIP-044(Encrypt)" ;;
         esac
     else

nostr_core/nip013.c

@@ -277,3 +277,332 @@ int nostr_add_proof_of_work(cJSON* event, const unsigned char* private_key,
     // If we reach here, we've exceeded max attempts
     return NOSTR_ERROR_CRYPTO_FAILED;
 }
+
+/**
+ * Calculate PoW difficulty (leading zero bits) for an event ID
+ *
+ * @param event_id_hex Hexadecimal event ID string (64 characters)
+ * @return Number of leading zero bits, or negative error code on failure
+ */
+int nostr_calculate_pow_difficulty(const char* event_id_hex) {
+    if (!event_id_hex) {
+        return NOSTR_ERROR_INVALID_INPUT;
+    }
+    
+    // Validate hex string length (should be 64 characters for SHA-256)
+    size_t hex_len = strlen(event_id_hex);
+    if (hex_len != 64) {
+        return NOSTR_ERROR_NIP13_CALCULATION;
+    }
+    
+    // Convert hex to bytes
+    unsigned char hash[32];
+    if (nostr_hex_to_bytes(event_id_hex, hash, 32) != NOSTR_SUCCESS) {
+        return NOSTR_ERROR_NIP13_CALCULATION;
+    }
+    
+    // Use existing NIP-13 reference implementation
+    return count_leading_zero_bits(hash);
+}
+
+/**
+ * Extract nonce information from event tags
+ *
+ * @param event Complete event JSON object
+ * @param nonce_out Output pointer for nonce value (can be NULL)
+ * @param target_difficulty_out Output pointer for target difficulty (can be NULL)
+ * @return NOSTR_SUCCESS if nonce tag found, NOSTR_ERROR_NIP13_NO_NONCE_TAG if not found, other error codes on failure
+ */
+int nostr_extract_nonce_info(cJSON* event, uint64_t* nonce_out, int* target_difficulty_out) {
+    if (!event) {
+        return NOSTR_ERROR_INVALID_INPUT;
+    }
+    
+    // Initialize output values
+    if (nonce_out) *nonce_out = 0;
+    if (target_difficulty_out) *target_difficulty_out = -1;
+    
+    // Get tags array
+    cJSON* tags = cJSON_GetObjectItem(event, "tags");
+    if (!tags || !cJSON_IsArray(tags)) {
+        return NOSTR_ERROR_NIP13_NO_NONCE_TAG;
+    }
+    
+    // Search for nonce tag
+    cJSON* tag = NULL;
+    cJSON_ArrayForEach(tag, tags) {
+        if (!cJSON_IsArray(tag) || cJSON_GetArraySize(tag) < 2) {
+            continue;
+        }
+        
+        // Check if this is a nonce tag
+        cJSON* tag_type = cJSON_GetArrayItem(tag, 0);
+        if (!tag_type || !cJSON_IsString(tag_type)) {
+            continue;
+        }
+        
+        const char* tag_name = cJSON_GetStringValue(tag_type);
+        if (!tag_name || strcmp(tag_name, "nonce") != 0) {
+            continue;
+        }
+        
+        // Extract nonce value (second element)
+        cJSON* nonce_item = cJSON_GetArrayItem(tag, 1);
+        if (!nonce_item || !cJSON_IsString(nonce_item)) {
+            return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+        }
+        
+        const char* nonce_str = cJSON_GetStringValue(nonce_item);
+        if (!nonce_str) {
+            return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+        }
+        
+        // Parse nonce value
+        char* endptr;
+        uint64_t nonce_val = strtoull(nonce_str, &endptr, 10);
+        if (*endptr != '\0') {
+            return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+        }
+        
+        if (nonce_out) *nonce_out = nonce_val;
+        
+        // Extract target difficulty (third element, optional)
+        if (cJSON_GetArraySize(tag) >= 3) {
+            cJSON* target_item = cJSON_GetArrayItem(tag, 2);
+            if (target_item && cJSON_IsString(target_item)) {
+                const char* target_str = cJSON_GetStringValue(target_item);
+                if (target_str) {
+                    char* endptr2;
+                    long target_val = strtol(target_str, &endptr2, 10);
+                    if (*endptr2 == '\0' && target_val >= 0) {
+                        if (target_difficulty_out) *target_difficulty_out = (int)target_val;
+                    }
+                }
+            }
+        }
+        
+        return NOSTR_SUCCESS;
+    }
+    
+    // No nonce tag found
+    return NOSTR_ERROR_NIP13_NO_NONCE_TAG;
+}
+
+/**
+ * Validate just the nonce tag format (without PoW calculation)
+ *
+ * @param nonce_tag_array JSON array representing a nonce tag
+ * @return NOSTR_SUCCESS if valid format, error code otherwise
+ */
+int nostr_validate_nonce_tag(cJSON* nonce_tag_array) {
+    if (!nonce_tag_array || !cJSON_IsArray(nonce_tag_array)) {
+        return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+    }
+    
+    int array_size = cJSON_GetArraySize(nonce_tag_array);
+    if (array_size < 2) {
+        return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+    }
+    
+    // First element should be "nonce"
+    cJSON* tag_type = cJSON_GetArrayItem(nonce_tag_array, 0);
+    if (!tag_type || !cJSON_IsString(tag_type)) {
+        return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+    }
+    
+    const char* tag_name = cJSON_GetStringValue(tag_type);
+    if (!tag_name || strcmp(tag_name, "nonce") != 0) {
+        return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+    }
+    
+    // Second element should be a valid nonce (numeric string)
+    cJSON* nonce_item = cJSON_GetArrayItem(nonce_tag_array, 1);
+    if (!nonce_item || !cJSON_IsString(nonce_item)) {
+        return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+    }
+    
+    const char* nonce_str = cJSON_GetStringValue(nonce_item);
+    if (!nonce_str) {
+        return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+    }
+    
+    // Validate nonce is a valid number
+    char* endptr;
+    strtoull(nonce_str, &endptr, 10);
+    if (*endptr != '\0') {
+        return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+    }
+    
+    // Third element (target difficulty) is optional, but if present should be valid
+    if (array_size >= 3) {
+        cJSON* target_item = cJSON_GetArrayItem(nonce_tag_array, 2);
+        if (target_item && cJSON_IsString(target_item)) {
+            const char* target_str = cJSON_GetStringValue(target_item);
+            if (target_str) {
+                char* endptr2;
+                strtol(target_str, &endptr2, 10);
+                if (*endptr2 != '\0') {
+                    return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+                }
+            }
+        }
+    }
+    
+    return NOSTR_SUCCESS;
+}
+
+/**
+ * Validate Proof of Work for an event according to NIP-13
+ *
+ * @param event Complete event JSON object to validate
+ * @param min_difficulty Minimum difficulty required by the relay (0 = no requirement)
+ * @param validation_flags Bitflags for validation options
+ * @param result_info Optional output struct for detailed results (can be NULL)
+ * @return NOSTR_SUCCESS if PoW is valid and meets requirements, error code otherwise
+ */
+int nostr_validate_pow(cJSON* event, int min_difficulty, int validation_flags,
+                      nostr_pow_result_t* result_info) {
+    if (!event) {
+        return NOSTR_ERROR_INVALID_INPUT;
+    }
+    
+    // Initialize result info if provided
+    if (result_info) {
+        result_info->actual_difficulty = 0;
+        result_info->committed_target = -1;
+        result_info->nonce_value = 0;
+        result_info->has_nonce_tag = 0;
+        result_info->error_detail[0] = '\0';
+    }
+    
+    // Get event ID for PoW calculation
+    cJSON* id_item = cJSON_GetObjectItem(event, "id");
+    if (!id_item || !cJSON_IsString(id_item)) {
+        if (result_info) {
+            snprintf(result_info->error_detail, sizeof(result_info->error_detail),
+                    "Missing or invalid event ID");
+        }
+        return NOSTR_ERROR_EVENT_INVALID_ID;
+    }
+    
+    const char* event_id = cJSON_GetStringValue(id_item);
+    if (!event_id) {
+        if (result_info) {
+            snprintf(result_info->error_detail, sizeof(result_info->error_detail),
+                    "Event ID is not a string");
+        }
+        return NOSTR_ERROR_EVENT_INVALID_ID;
+    }
+    
+    // Calculate actual PoW difficulty
+    int actual_difficulty = nostr_calculate_pow_difficulty(event_id);
+    if (actual_difficulty < 0) {
+        if (result_info) {
+            snprintf(result_info->error_detail, sizeof(result_info->error_detail),
+                    "Failed to calculate PoW difficulty");
+        }
+        return actual_difficulty; // Return the specific error from calculation
+    }
+    
+    if (result_info) {
+        result_info->actual_difficulty = actual_difficulty;
+    }
+    
+    // Check if minimum difficulty requirement is met
+    if (min_difficulty > 0 && actual_difficulty < min_difficulty) {
+        if (result_info) {
+            snprintf(result_info->error_detail, sizeof(result_info->error_detail),
+                    "Insufficient difficulty: %d < %d", actual_difficulty, min_difficulty);
+        }
+        return NOSTR_ERROR_NIP13_INSUFFICIENT;
+    }
+    
+    // Extract nonce information if validation flags require it
+    uint64_t nonce_value = 0;
+    int committed_target = -1;
+    int nonce_extract_result = nostr_extract_nonce_info(event, &nonce_value, &committed_target);
+    
+    if (result_info) {
+        result_info->nonce_value = nonce_value;
+        result_info->committed_target = committed_target;
+        result_info->has_nonce_tag = (nonce_extract_result == NOSTR_SUCCESS) ? 1 : 0;
+    }
+    
+    // Validate nonce tag presence if required
+    if (validation_flags & NOSTR_POW_VALIDATE_NONCE_TAG) {
+        if (nonce_extract_result == NOSTR_ERROR_NIP13_NO_NONCE_TAG) {
+            if (result_info) {
+                snprintf(result_info->error_detail, sizeof(result_info->error_detail),
+                        "Missing required nonce tag");
+            }
+            return NOSTR_ERROR_NIP13_NO_NONCE_TAG;
+        } else if (nonce_extract_result != NOSTR_SUCCESS) {
+            if (result_info) {
+                snprintf(result_info->error_detail, sizeof(result_info->error_detail),
+                        "Invalid nonce tag format");
+            }
+            return nonce_extract_result;
+        }
+        
+        // If strict format validation is enabled, validate the nonce tag structure
+        if (validation_flags & NOSTR_POW_STRICT_FORMAT) {
+            cJSON* tags = cJSON_GetObjectItem(event, "tags");
+            if (tags && cJSON_IsArray(tags)) {
+                cJSON* tag = NULL;
+                cJSON_ArrayForEach(tag, tags) {
+                    if (cJSON_IsArray(tag) && cJSON_GetArraySize(tag) >= 2) {
+                        cJSON* tag_type = cJSON_GetArrayItem(tag, 0);
+                        if (tag_type && cJSON_IsString(tag_type)) {
+                            const char* tag_name = cJSON_GetStringValue(tag_type);
+                            if (tag_name && strcmp(tag_name, "nonce") == 0) {
+                                int validation_result = nostr_validate_nonce_tag(tag);
+                                if (validation_result != NOSTR_SUCCESS) {
+                                    if (result_info) {
+                                        snprintf(result_info->error_detail, sizeof(result_info->error_detail),
+                                                "Nonce tag failed strict format validation");
+                                    }
+                                    return validation_result;
+                                }
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    
+    // Validate committed target difficulty if required
+    if (validation_flags & NOSTR_POW_VALIDATE_TARGET_COMMIT) {
+        if (nonce_extract_result == NOSTR_SUCCESS && committed_target == -1) {
+            if (result_info) {
+                snprintf(result_info->error_detail, sizeof(result_info->error_detail),
+                        "Missing committed target difficulty in nonce tag");
+            }
+            return NOSTR_ERROR_NIP13_INVALID_NONCE_TAG;
+        }
+        
+        // Check for target/difficulty mismatch if rejecting lower targets
+        if (validation_flags & NOSTR_POW_REJECT_LOWER_TARGET) {
+            // According to NIP-13: "if you require 40 bits to reply to your thread and see
+            // a committed target of 30, you can safely reject it even if the note has 40 bits difficulty"
+            // This means we reject if committed_target < min_difficulty, not actual_difficulty
+            if (committed_target != -1 && min_difficulty > 0 && committed_target < min_difficulty) {
+                if (result_info) {
+                    snprintf(result_info->error_detail, sizeof(result_info->error_detail),
+                            "Committed target (%d) is lower than required minimum (%d)",
+                            committed_target, min_difficulty);
+                }
+                return NOSTR_ERROR_NIP13_TARGET_MISMATCH;
+            }
+        }
+    }
+    
+    // All validations passed
+    if (result_info) {
+        snprintf(result_info->error_detail, sizeof(result_info->error_detail),
+                "PoW validation successful");
+    }
+    
+    return NOSTR_SUCCESS;
+}

nostr_core/nip013.h

@@ -8,11 +8,41 @@
 #include "nip001.h"
 #include <stdint.h>
 
+// PoW validation flags
+#define NOSTR_POW_VALIDATE_NONCE_TAG     0x01  // Require and validate nonce tag format
+#define NOSTR_POW_VALIDATE_TARGET_COMMIT  0x02  // Validate committed target difficulty
+#define NOSTR_POW_REJECT_LOWER_TARGET    0x04  // Reject if committed target < actual difficulty
+#define NOSTR_POW_STRICT_FORMAT          0x08  // Strict nonce tag format validation
+
+// Convenience combinations
+#define NOSTR_POW_VALIDATE_BASIC         (NOSTR_POW_VALIDATE_NONCE_TAG)
+#define NOSTR_POW_VALIDATE_FULL          (NOSTR_POW_VALIDATE_NONCE_TAG | NOSTR_POW_VALIDATE_TARGET_COMMIT)
+#define NOSTR_POW_VALIDATE_ANTI_SPAM     (NOSTR_POW_VALIDATE_FULL | NOSTR_POW_REJECT_LOWER_TARGET)
+
+// Result information structure (optional output)
+typedef struct {
+    int actual_difficulty;        // Calculated difficulty (leading zero bits)
+    int committed_target;         // Target difficulty from nonce tag (-1 if none)
+    uint64_t nonce_value;        // Nonce value from tag (0 if none)
+    int has_nonce_tag;           // 1 if nonce tag present, 0 otherwise
+    char error_detail[256];      // Detailed error description
+} nostr_pow_result_t;
+
 // Function declarations
-int nostr_add_proof_of_work(cJSON* event, const unsigned char* private_key, 
+int nostr_add_proof_of_work(cJSON* event, const unsigned char* private_key,
                            int target_difficulty, int max_attempts,
                            int progress_report_interval, int timestamp_update_interval,
                            void (*progress_callback)(int current_difficulty, uint64_t nonce, void* user_data),
                            void* user_data);
 
+// PoW validation functions
+int nostr_validate_pow(cJSON* event, int min_difficulty, int validation_flags,
+                      nostr_pow_result_t* result_info);
+
+int nostr_calculate_pow_difficulty(const char* event_id_hex);
+
+int nostr_extract_nonce_info(cJSON* event, uint64_t* nonce_out, int* target_difficulty_out);
+
+int nostr_validate_nonce_tag(cJSON* nonce_tag_array);
+
 #endif // NIP013_H

nostr_core/nip042.c

@@ -0,0 +1,628 @@
+/*
+ * NOSTR Core Library - NIP-042: Authentication of clients to relays
+ * 
+ * Implements client authentication through signed ephemeral events
+ */
+
+#include "nip042.h"
+#include "nip001.h"
+#include "utils.h"
+#include "../cjson/cJSON.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+
+// Forward declarations for crypto functions
+int nostr_secp256k1_get_random_bytes(unsigned char* buf, size_t len);
+
+// =============================================================================
+// CLIENT-SIDE FUNCTIONS
+// =============================================================================
+
+/**
+ * Create NIP-42 authentication event (kind 22242)
+ */
+cJSON* nostr_nip42_create_auth_event(const char* challenge, 
+                                      const char* relay_url,
+                                      const unsigned char* private_key,
+                                      time_t timestamp) {
+    if (!challenge || !relay_url || !private_key) {
+        return NULL;
+    }
+
+    // Validate challenge format
+    size_t challenge_len = strlen(challenge);
+    if (challenge_len < NOSTR_NIP42_MIN_CHALLENGE_LENGTH || 
+        challenge_len >= NOSTR_NIP42_MAX_CHALLENGE_LENGTH) {
+        return NULL;
+    }
+
+    // Create tags array with relay and challenge
+    cJSON* tags = cJSON_CreateArray();
+    if (!tags) {
+        return NULL;
+    }
+
+    // Add relay tag
+    cJSON* relay_tag = cJSON_CreateArray();
+    if (!relay_tag) {
+        cJSON_Delete(tags);
+        return NULL;
+    }
+    cJSON_AddItemToArray(relay_tag, cJSON_CreateString("relay"));
+    cJSON_AddItemToArray(relay_tag, cJSON_CreateString(relay_url));
+    cJSON_AddItemToArray(tags, relay_tag);
+
+    // Add challenge tag
+    cJSON* challenge_tag = cJSON_CreateArray();
+    if (!challenge_tag) {
+        cJSON_Delete(tags);
+        return NULL;
+    }
+    cJSON_AddItemToArray(challenge_tag, cJSON_CreateString("challenge"));
+    cJSON_AddItemToArray(challenge_tag, cJSON_CreateString(challenge));
+    cJSON_AddItemToArray(tags, challenge_tag);
+
+    // Create authentication event using existing function
+    // Note: Empty content as per NIP-42 specification
+    cJSON* auth_event = nostr_create_and_sign_event(
+        NOSTR_NIP42_AUTH_EVENT_KIND,
+        "",  // Empty content
+        tags,
+        private_key,
+        timestamp
+    );
+
+    cJSON_Delete(tags);
+    return auth_event;
+}
+
+/**
+ * Create AUTH message JSON for relay communication
+ */
+char* nostr_nip42_create_auth_message(cJSON* auth_event) {
+    if (!auth_event) {
+        return NULL;
+    }
+
+    // Create AUTH message array: ["AUTH", <event-json>]
+    cJSON* message_array = cJSON_CreateArray();
+    if (!message_array) {
+        return NULL;
+    }
+
+    cJSON_AddItemToArray(message_array, cJSON_CreateString("AUTH"));
+    cJSON_AddItemToArray(message_array, cJSON_Duplicate(auth_event, 1));
+
+    char* message_string = cJSON_PrintUnformatted(message_array);
+    cJSON_Delete(message_array);
+
+    return message_string;
+}
+
+/**
+ * Validate challenge string format and freshness
+ */
+int nostr_nip42_validate_challenge(const char* challenge, 
+                                   time_t received_at,
+                                   int time_tolerance) {
+    if (!challenge) {
+        return NOSTR_ERROR_INVALID_INPUT;
+    }
+
+    size_t challenge_len = strlen(challenge);
+    
+    // Check challenge length
+    if (challenge_len < NOSTR_NIP42_MIN_CHALLENGE_LENGTH) {
+        return NOSTR_ERROR_NIP42_CHALLENGE_TOO_SHORT;
+    }
+    if (challenge_len >= NOSTR_NIP42_MAX_CHALLENGE_LENGTH) {
+        return NOSTR_ERROR_NIP42_CHALLENGE_TOO_LONG;
+    }
+
+    // Check time validity if provided
+    if (received_at > 0) {
+        time_t now = time(NULL);
+        int tolerance = (time_tolerance > 0) ? time_tolerance : NOSTR_NIP42_DEFAULT_TIME_TOLERANCE;
+        
+        if (now - received_at > tolerance) {
+            return NOSTR_ERROR_NIP42_CHALLENGE_EXPIRED;
+        }
+    }
+
+    return NOSTR_SUCCESS;
+}
+
+/**
+ * Parse AUTH challenge message from relay
+ */
+int nostr_nip42_parse_auth_challenge(const char* message,
+                                     char* challenge_out,
+                                     size_t challenge_size) {
+    if (!message || !challenge_out || challenge_size == 0) {
+        return NOSTR_ERROR_INVALID_INPUT;
+    }
+
+    cJSON* json = cJSON_Parse(message);
+    if (!json || !cJSON_IsArray(json)) {
+        if (json) cJSON_Delete(json);
+        return NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT;
+    }
+
+    // Check array has exactly 2 elements
+    if (cJSON_GetArraySize(json) != 2) {
+        cJSON_Delete(json);
+        return NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT;
+    }
+
+    // Check first element is "AUTH"
+    cJSON* message_type = cJSON_GetArrayItem(json, 0);
+    if (!message_type || !cJSON_IsString(message_type) || 
+        strcmp(cJSON_GetStringValue(message_type), "AUTH") != 0) {
+        cJSON_Delete(json);
+        return NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT;
+    }
+
+    // Get challenge string
+    cJSON* challenge_item = cJSON_GetArrayItem(json, 1);
+    if (!challenge_item || !cJSON_IsString(challenge_item)) {
+        cJSON_Delete(json);
+        return NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT;
+    }
+
+    const char* challenge_str = cJSON_GetStringValue(challenge_item);
+    if (!challenge_str || strlen(challenge_str) >= challenge_size) {
+        cJSON_Delete(json);
+        return NOSTR_ERROR_NIP42_INVALID_CHALLENGE;
+    }
+
+    strcpy(challenge_out, challenge_str);
+    cJSON_Delete(json);
+
+    return NOSTR_SUCCESS;
+}
+
+// =============================================================================
+// SERVER-SIDE FUNCTIONS
+// =============================================================================
+
+/**
+ * Generate cryptographically secure challenge string
+ */
+int nostr_nip42_generate_challenge(char* challenge_out, size_t length) {
+    if (!challenge_out || length < NOSTR_NIP42_MIN_CHALLENGE_LENGTH || 
+        length > NOSTR_NIP42_MAX_CHALLENGE_LENGTH / 2) {
+        return NOSTR_ERROR_INVALID_INPUT;
+    }
+
+    // Generate random bytes
+    unsigned char random_bytes[NOSTR_NIP42_MAX_CHALLENGE_LENGTH / 2];
+    if (nostr_secp256k1_get_random_bytes(random_bytes, length) != 1) {
+        return NOSTR_ERROR_CRYPTO_FAILED;
+    }
+
+    // Convert to hex string (reusing existing function)
+    nostr_bytes_to_hex(random_bytes, length, challenge_out);
+
+    return NOSTR_SUCCESS;
+}
+
+/**
+ * Verify NIP-42 authentication event
+ */
+int nostr_nip42_verify_auth_event(cJSON* auth_event,
+                                  const char* expected_challenge,
+                                  const char* relay_url,
+                                  int time_tolerance) {
+    if (!auth_event || !expected_challenge || !relay_url) {
+        return NOSTR_ERROR_INVALID_INPUT;
+    }
+
+    // First validate basic event structure using existing function
+    int structure_result = nostr_validate_event_structure(auth_event);
+    if (structure_result != NOSTR_SUCCESS) {
+        return structure_result;
+    }
+
+    // Validate NIP-42 specific structure
+    int nip42_structure_result = nostr_nip42_validate_auth_event_structure(
+        auth_event, relay_url, expected_challenge, time_tolerance);
+    if (nip42_structure_result != NOSTR_SUCCESS) {
+        return nip42_structure_result;
+    }
+
+    // Finally verify cryptographic signature using existing function
+    return nostr_verify_event_signature(auth_event);
+}
+
+/**
+ * Parse AUTH message from client
+ */
+int nostr_nip42_parse_auth_message(const char* message, cJSON** auth_event_out) {
+    if (!message || !auth_event_out) {
+        return NOSTR_ERROR_INVALID_INPUT;
+    }
+
+    cJSON* json = cJSON_Parse(message);
+    if (!json || !cJSON_IsArray(json)) {
+        if (json) cJSON_Delete(json);
+        return NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT;
+    }
+
+    // Check array has exactly 2 elements
+    if (cJSON_GetArraySize(json) != 2) {
+        cJSON_Delete(json);
+        return NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT;
+    }
+
+    // Check first element is "AUTH"
+    cJSON* message_type = cJSON_GetArrayItem(json, 0);
+    if (!message_type || !cJSON_IsString(message_type) || 
+        strcmp(cJSON_GetStringValue(message_type), "AUTH") != 0) {
+        cJSON_Delete(json);
+        return NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT;
+    }
+
+    // Get event object
+    cJSON* event_item = cJSON_GetArrayItem(json, 1);
+    if (!event_item || !cJSON_IsObject(event_item)) {
+        cJSON_Delete(json);
+        return NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT;
+    }
+
+    // Duplicate the event for the caller
+    *auth_event_out = cJSON_Duplicate(event_item, 1);
+    cJSON_Delete(json);
+
+    if (!*auth_event_out) {
+        return NOSTR_ERROR_MEMORY_FAILED;
+    }
+
+    return NOSTR_SUCCESS;
+}
+
+/**
+ * Create "auth-required" error response
+ */
+char* nostr_nip42_create_auth_required_message(const char* subscription_id,
+                                               const char* event_id,
+                                               const char* reason) {
+    const char* default_reason = "authentication required";
+    const char* message_reason = reason ? reason : default_reason;
+
+    cJSON* response = cJSON_CreateArray();
+    if (!response) {
+        return NULL;
+    }
+
+    if (subscription_id) {
+        // CLOSED message for subscriptions
+        cJSON_AddItemToArray(response, cJSON_CreateString("CLOSED"));
+        cJSON_AddItemToArray(response, cJSON_CreateString(subscription_id));
+        
+        char prefix_message[512];
+        snprintf(prefix_message, sizeof(prefix_message), "auth-required: %s", message_reason);
+        cJSON_AddItemToArray(response, cJSON_CreateString(prefix_message));
+    } else if (event_id) {
+        // OK message for events
+        cJSON_AddItemToArray(response, cJSON_CreateString("OK"));
+        cJSON_AddItemToArray(response, cJSON_CreateString(event_id));
+        cJSON_AddItemToArray(response, cJSON_CreateBool(0)); // false
+        
+        char prefix_message[512];
+        snprintf(prefix_message, sizeof(prefix_message), "auth-required: %s", message_reason);
+        cJSON_AddItemToArray(response, cJSON_CreateString(prefix_message));
+    } else {
+        cJSON_Delete(response);
+        return NULL;
+    }
+
+    char* message_string = cJSON_PrintUnformatted(response);
+    cJSON_Delete(response);
+
+    return message_string;
+}
+
+/**
+ * Create "restricted" error response
+ */
+char* nostr_nip42_create_restricted_message(const char* subscription_id,
+                                            const char* event_id,
+                                            const char* reason) {
+    const char* default_reason = "access restricted";
+    const char* message_reason = reason ? reason : default_reason;
+
+    cJSON* response = cJSON_CreateArray();
+    if (!response) {
+        return NULL;
+    }
+
+    if (subscription_id) {
+        // CLOSED message for subscriptions
+        cJSON_AddItemToArray(response, cJSON_CreateString("CLOSED"));
+        cJSON_AddItemToArray(response, cJSON_CreateString(subscription_id));
+        
+        char prefix_message[512];
+        snprintf(prefix_message, sizeof(prefix_message), "restricted: %s", message_reason);
+        cJSON_AddItemToArray(response, cJSON_CreateString(prefix_message));
+    } else if (event_id) {
+        // OK message for events
+        cJSON_AddItemToArray(response, cJSON_CreateString("OK"));
+        cJSON_AddItemToArray(response, cJSON_CreateString(event_id));
+        cJSON_AddItemToArray(response, cJSON_CreateBool(0)); // false
+        
+        char prefix_message[512];
+        snprintf(prefix_message, sizeof(prefix_message), "restricted: %s", message_reason);
+        cJSON_AddItemToArray(response, cJSON_CreateString(prefix_message));
+    } else {
+        cJSON_Delete(response);
+        return NULL;
+    }
+
+    char* message_string = cJSON_PrintUnformatted(response);
+    cJSON_Delete(response);
+
+    return message_string;
+}
+
+// =============================================================================
+// URL NORMALIZATION FUNCTIONS
+// =============================================================================
+
+/**
+ * Normalize relay URL for comparison
+ */
+char* nostr_nip42_normalize_url(const char* url) {
+    if (!url) {
+        return NULL;
+    }
+
+    size_t url_len = strlen(url);
+    char* normalized = malloc(url_len + 1);
+    if (!normalized) {
+        return NULL;
+    }
+
+    strcpy(normalized, url);
+
+    // Remove trailing slash
+    if (url_len > 1 && normalized[url_len - 1] == '/') {
+        normalized[url_len - 1] = '\0';
+    }
+
+    // Convert to lowercase for domain comparison
+    for (size_t i = 0; normalized[i]; i++) {
+        if (normalized[i] >= 'A' && normalized[i] <= 'Z') {
+            normalized[i] = normalized[i] + ('a' - 'A');
+        }
+    }
+
+    return normalized;
+}
+
+/**
+ * Check if two relay URLs match after normalization
+ */
+int nostr_nip42_urls_match(const char* url1, const char* url2) {
+    if (!url1 || !url2) {
+        return -1;
+    }
+
+    char* norm1 = nostr_nip42_normalize_url(url1);
+    char* norm2 = nostr_nip42_normalize_url(url2);
+
+    if (!norm1 || !norm2) {
+        free(norm1);
+        free(norm2);
+        return -1;
+    }
+
+    int result = (strcmp(norm1, norm2) == 0) ? 1 : 0;
+
+    free(norm1);
+    free(norm2);
+
+    return result;
+}
+
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+
+/**
+ * Get string description of authentication state
+ */
+const char* nostr_nip42_auth_state_str(nostr_auth_state_t state) {
+    switch (state) {
+        case NOSTR_AUTH_STATE_NONE:
+            return "none";
+        case NOSTR_AUTH_STATE_CHALLENGE_RECEIVED:
+            return "challenge_received";
+        case NOSTR_AUTH_STATE_AUTHENTICATING:
+            return "authenticating";
+        case NOSTR_AUTH_STATE_AUTHENTICATED:
+            return "authenticated";
+        case NOSTR_AUTH_STATE_REJECTED:
+            return "rejected";
+        default:
+            return "unknown";
+    }
+}
+
+/**
+ * Initialize authentication context structure
+ */
+int nostr_nip42_init_auth_context(nostr_auth_context_t* ctx,
+                                  const char* relay_url,
+                                  const char* challenge,
+                                  int time_tolerance) {
+    if (!ctx || !relay_url || !challenge) {
+        return NOSTR_ERROR_INVALID_INPUT;
+    }
+
+    memset(ctx, 0, sizeof(nostr_auth_context_t));
+
+    ctx->relay_url = malloc(strlen(relay_url) + 1);
+    if (!ctx->relay_url) {
+        return NOSTR_ERROR_MEMORY_FAILED;
+    }
+    strcpy(ctx->relay_url, relay_url);
+
+    ctx->challenge = malloc(strlen(challenge) + 1);
+    if (!ctx->challenge) {
+        free(ctx->relay_url);
+        ctx->relay_url = NULL;
+        return NOSTR_ERROR_MEMORY_FAILED;
+    }
+    strcpy(ctx->challenge, challenge);
+
+    ctx->timestamp = time(NULL);
+    ctx->time_tolerance = (time_tolerance > 0) ? time_tolerance : NOSTR_NIP42_DEFAULT_TIME_TOLERANCE;
+
+    return NOSTR_SUCCESS;
+}
+
+/**
+ * Free authentication context structure
+ */
+void nostr_nip42_free_auth_context(nostr_auth_context_t* ctx) {
+    if (!ctx) {
+        return;
+    }
+
+    free(ctx->relay_url);
+    free(ctx->challenge);
+    free(ctx->pubkey_hex);
+
+    memset(ctx, 0, sizeof(nostr_auth_context_t));
+}
+
+/**
+ * Validate authentication event structure (without signature verification)
+ */
+int nostr_nip42_validate_auth_event_structure(cJSON* auth_event,
+                                              const char* relay_url,
+                                              const char* challenge,
+                                              int time_tolerance) {
+    if (!auth_event || !relay_url || !challenge) {
+        return NOSTR_ERROR_INVALID_INPUT;
+    }
+
+    // Check event kind is 22242
+    cJSON* kind_item = cJSON_GetObjectItem(auth_event, "kind");
+    if (!kind_item || !cJSON_IsNumber(kind_item) || 
+        (int)cJSON_GetNumberValue(kind_item) != NOSTR_NIP42_AUTH_EVENT_KIND) {
+        return NOSTR_ERROR_NIP42_AUTH_EVENT_INVALID;
+    }
+
+    // Check timestamp is within tolerance
+    cJSON* created_at_item = cJSON_GetObjectItem(auth_event, "created_at");
+    if (!created_at_item || !cJSON_IsNumber(created_at_item)) {
+        return NOSTR_ERROR_EVENT_INVALID_CREATED_AT;
+    }
+
+    time_t event_time = (time_t)cJSON_GetNumberValue(created_at_item);
+    time_t now = time(NULL);
+    int tolerance = (time_tolerance > 0) ? time_tolerance : NOSTR_NIP42_DEFAULT_TIME_TOLERANCE;
+    
+    if (abs((int)(now - event_time)) > tolerance) {
+        return NOSTR_ERROR_NIP42_TIME_TOLERANCE;
+    }
+
+    // Check tags contain required relay and challenge
+    cJSON* tags_item = cJSON_GetObjectItem(auth_event, "tags");
+    if (!tags_item || !cJSON_IsArray(tags_item)) {
+        return NOSTR_ERROR_EVENT_INVALID_TAGS;
+    }
+
+    int found_relay = 0, found_challenge = 0;
+
+    cJSON* tag_item;
+    cJSON_ArrayForEach(tag_item, tags_item) {
+        if (!cJSON_IsArray(tag_item) || cJSON_GetArraySize(tag_item) < 2) {
+            continue;
+        }
+
+        cJSON* tag_name = cJSON_GetArrayItem(tag_item, 0);
+        cJSON* tag_value = cJSON_GetArrayItem(tag_item, 1);
+
+        if (!cJSON_IsString(tag_name) || !cJSON_IsString(tag_value)) {
+            continue;
+        }
+
+        const char* name = cJSON_GetStringValue(tag_name);
+        const char* value = cJSON_GetStringValue(tag_value);
+
+        if (strcmp(name, "relay") == 0) {
+            if (nostr_nip42_urls_match(value, relay_url) == 1) {
+                found_relay = 1;
+            }
+        } else if (strcmp(name, "challenge") == 0) {
+            if (strcmp(value, challenge) == 0) {
+                found_challenge = 1;
+            }
+        }
+    }
+
+    if (!found_relay) {
+        return NOSTR_ERROR_NIP42_URL_MISMATCH;
+    }
+
+    if (!found_challenge) {
+        return NOSTR_ERROR_NIP42_INVALID_CHALLENGE;
+    }
+
+    return NOSTR_SUCCESS;
+}
+
+// =============================================================================
+// WEBSOCKET CLIENT INTEGRATION STUB FUNCTIONS
+// =============================================================================
+// Note: These will need to be implemented when WebSocket client structure is available
+
+int nostr_ws_authenticate(struct nostr_ws_client* client,
+                         const unsigned char* private_key,
+                         int time_tolerance) {
+    // TODO: Implement when WebSocket client structure is available
+    (void)client;
+    (void)private_key;
+    (void)time_tolerance;
+    return NOSTR_ERROR_NETWORK_FAILED; // Placeholder
+}
+
+nostr_auth_state_t nostr_ws_get_auth_state(struct nostr_ws_client* client) {
+    // TODO: Implement when WebSocket client structure is available
+    (void)client;
+    return NOSTR_AUTH_STATE_NONE; // Placeholder
+}
+
+int nostr_ws_has_valid_challenge(struct nostr_ws_client* client) {
+    // TODO: Implement when WebSocket client structure is available
+    (void)client;
+    return 0; // Placeholder
+}
+
+int nostr_ws_get_challenge(struct nostr_ws_client* client,
+                          char* challenge_out,
+                          size_t challenge_size) {
+    // TODO: Implement when WebSocket client structure is available
+    (void)client;
+    (void)challenge_out;
+    (void)challenge_size;
+    return NOSTR_ERROR_NETWORK_FAILED; // Placeholder
+}
+
+int nostr_ws_store_challenge(struct nostr_ws_client* client,
+                            const char* challenge) {
+    // TODO: Implement when WebSocket client structure is available
+    (void)client;
+    (void)challenge;
+    return NOSTR_ERROR_NETWORK_FAILED; // Placeholder
+}
+
+int nostr_ws_clear_auth_state(struct nostr_ws_client* client) {
+    // TODO: Implement when WebSocket client structure is available
+    (void)client;
+    return NOSTR_ERROR_NETWORK_FAILED; // Placeholder
+}

nostr_core/nip042.h

@@ -0,0 +1,281 @@
+/*
+ * NOSTR Core Library - NIP-042: Authentication of clients to relays
+ * 
+ * Implements client authentication through signed ephemeral events
+ */
+
+#ifndef NIP042_H
+#define NIP042_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <time.h>
+#include "../cjson/cJSON.h"
+#include "nostr_common.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// NIP-42 CONSTANTS AND DEFINITIONS
+// =============================================================================
+
+#define NOSTR_NIP42_AUTH_EVENT_KIND 22242
+#define NOSTR_NIP42_DEFAULT_CHALLENGE_LENGTH 32
+#define NOSTR_NIP42_DEFAULT_TIME_TOLERANCE 600  // 10 minutes in seconds
+#define NOSTR_NIP42_MAX_CHALLENGE_LENGTH 256
+#define NOSTR_NIP42_MIN_CHALLENGE_LENGTH 16
+
+// Authentication states for WebSocket client integration
+typedef enum {
+    NOSTR_AUTH_STATE_NONE = 0,               // No authentication attempted
+    NOSTR_AUTH_STATE_CHALLENGE_RECEIVED = 1,  // Challenge received from relay
+    NOSTR_AUTH_STATE_AUTHENTICATING = 2,      // AUTH event sent, waiting for OK
+    NOSTR_AUTH_STATE_AUTHENTICATED = 3,       // Successfully authenticated
+    NOSTR_AUTH_STATE_REJECTED = 4            // Authentication rejected
+} nostr_auth_state_t;
+
+// Challenge storage structure
+typedef struct {
+    char challenge[NOSTR_NIP42_MAX_CHALLENGE_LENGTH];
+    time_t received_at;
+    int is_valid;
+} nostr_auth_challenge_t;
+
+// Authentication context for relay verification
+typedef struct {
+    char* relay_url;
+    char* challenge;
+    time_t timestamp;
+    int time_tolerance;
+    char* pubkey_hex;
+} nostr_auth_context_t;
+
+// =============================================================================
+// CLIENT-SIDE FUNCTIONS (for nostr clients)
+// =============================================================================
+
+/**
+ * Create NIP-42 authentication event (kind 22242)
+ * @param challenge Challenge string received from relay
+ * @param relay_url Relay URL (normalized)
+ * @param private_key 32-byte private key for signing
+ * @param timestamp Event timestamp (0 for current time)
+ * @return cJSON event object or NULL on error
+ */
+cJSON* nostr_nip42_create_auth_event(const char* challenge, 
+                                      const char* relay_url,
+                                      const unsigned char* private_key,
+                                      time_t timestamp);
+
+/**
+ * Create AUTH message JSON for relay communication
+ * @param auth_event Authentication event (kind 22242)
+ * @return JSON string for AUTH message or NULL on error (caller must free)
+ */
+char* nostr_nip42_create_auth_message(cJSON* auth_event);
+
+/**
+ * Validate challenge string format and freshness
+ * @param challenge Challenge string to validate
+ * @param received_at Time when challenge was received (0 for no time check)
+ * @param time_tolerance Maximum age in seconds (0 for default)
+ * @return NOSTR_SUCCESS or error code
+ */
+int nostr_nip42_validate_challenge(const char* challenge, 
+                                   time_t received_at,
+                                   int time_tolerance);
+
+/**
+ * Parse AUTH challenge message from relay
+ * @param message Raw message from relay
+ * @param challenge_out Output buffer for challenge string
+ * @param challenge_size Size of challenge buffer
+ * @return NOSTR_SUCCESS or error code
+ */
+int nostr_nip42_parse_auth_challenge(const char* message,
+                                     char* challenge_out,
+                                     size_t challenge_size);
+
+// =============================================================================
+// SERVER-SIDE FUNCTIONS (for relay implementations)
+// =============================================================================
+
+/**
+ * Generate cryptographically secure challenge string
+ * @param challenge_out Output buffer for challenge (must be at least length*2+1)
+ * @param length Desired challenge length in bytes (16-128)
+ * @return NOSTR_SUCCESS or error code
+ */
+int nostr_nip42_generate_challenge(char* challenge_out, size_t length);
+
+/**
+ * Verify NIP-42 authentication event
+ * @param auth_event Authentication event to verify
+ * @param expected_challenge Challenge that was sent to client
+ * @param relay_url Expected relay URL
+ * @param time_tolerance Maximum timestamp deviation in seconds
+ * @return NOSTR_SUCCESS or error code
+ */
+int nostr_nip42_verify_auth_event(cJSON* auth_event,
+                                  const char* expected_challenge,
+                                  const char* relay_url,
+                                  int time_tolerance);
+
+/**
+ * Parse AUTH message from client
+ * @param message Raw AUTH message from client
+ * @param auth_event_out Output pointer to parsed event (caller must free)
+ * @return NOSTR_SUCCESS or error code
+ */
+int nostr_nip42_parse_auth_message(const char* message, cJSON** auth_event_out);
+
+/**
+ * Create "auth-required" error response
+ * @param subscription_id Subscription ID (for CLOSED) or NULL (for OK)
+ * @param event_id Event ID (for OK) or NULL (for CLOSED)
+ * @param reason Human-readable reason
+ * @return JSON string for response or NULL on error (caller must free)
+ */
+char* nostr_nip42_create_auth_required_message(const char* subscription_id,
+                                               const char* event_id,
+                                               const char* reason);
+
+/**
+ * Create "restricted" error response
+ * @param subscription_id Subscription ID (for CLOSED) or NULL (for OK)
+ * @param event_id Event ID (for OK) or NULL (for CLOSED)  
+ * @param reason Human-readable reason
+ * @return JSON string for response or NULL on error (caller must free)
+ */
+char* nostr_nip42_create_restricted_message(const char* subscription_id,
+                                            const char* event_id,
+                                            const char* reason);
+
+// =============================================================================
+// URL NORMALIZATION FUNCTIONS
+// =============================================================================
+
+/**
+ * Normalize relay URL for comparison (removes trailing slashes, etc.)
+ * @param url Original URL
+ * @return Normalized URL string or NULL on error (caller must free)
+ */
+char* nostr_nip42_normalize_url(const char* url);
+
+/**
+ * Check if two relay URLs match after normalization
+ * @param url1 First URL
+ * @param url2 Second URL  
+ * @return 1 if URLs match, 0 if they don't, -1 on error
+ */
+int nostr_nip42_urls_match(const char* url1, const char* url2);
+
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+
+/**
+ * Get string description of authentication state
+ * @param state Authentication state
+ * @return Human-readable string
+ */
+const char* nostr_nip42_auth_state_str(nostr_auth_state_t state);
+
+/**
+ * Initialize authentication context structure
+ * @param ctx Context to initialize
+ * @param relay_url Relay URL
+ * @param challenge Challenge string
+ * @param time_tolerance Time tolerance in seconds
+ * @return NOSTR_SUCCESS or error code
+ */
+int nostr_nip42_init_auth_context(nostr_auth_context_t* ctx,
+                                  const char* relay_url,
+                                  const char* challenge,
+                                  int time_tolerance);
+
+/**
+ * Free authentication context structure
+ * @param ctx Context to free
+ */
+void nostr_nip42_free_auth_context(nostr_auth_context_t* ctx);
+
+/**
+ * Validate authentication event structure (without signature verification)
+ * @param auth_event Event to validate
+ * @param relay_url Expected relay URL
+ * @param challenge Expected challenge
+ * @param time_tolerance Maximum timestamp deviation in seconds  
+ * @return NOSTR_SUCCESS or error code
+ */
+int nostr_nip42_validate_auth_event_structure(cJSON* auth_event,
+                                              const char* relay_url,
+                                              const char* challenge,
+                                              int time_tolerance);
+
+// =============================================================================
+// WEBSOCKET CLIENT INTEGRATION
+// =============================================================================
+
+// Forward declaration for WebSocket client
+struct nostr_ws_client;
+
+/**
+ * Authenticate WebSocket client with relay
+ * @param client WebSocket client handle
+ * @param private_key 32-byte private key for authentication
+ * @param time_tolerance Maximum timestamp deviation in seconds (0 for default)
+ * @return NOSTR_SUCCESS or error code
+ */
+int nostr_ws_authenticate(struct nostr_ws_client* client,
+                         const unsigned char* private_key,
+                         int time_tolerance);
+
+/**
+ * Get current authentication state of WebSocket client
+ * @param client WebSocket client handle
+ * @return Current authentication state
+ */
+nostr_auth_state_t nostr_ws_get_auth_state(struct nostr_ws_client* client);
+
+/**
+ * Check if WebSocket client has stored valid challenge
+ * @param client WebSocket client handle
+ * @return 1 if valid challenge exists, 0 otherwise
+ */
+int nostr_ws_has_valid_challenge(struct nostr_ws_client* client);
+
+/**
+ * Get stored challenge from WebSocket client
+ * @param client WebSocket client handle
+ * @param challenge_out Output buffer for challenge
+ * @param challenge_size Size of output buffer
+ * @return NOSTR_SUCCESS or error code
+ */
+int nostr_ws_get_challenge(struct nostr_ws_client* client,
+                          char* challenge_out,
+                          size_t challenge_size);
+
+/**
+ * Store challenge in WebSocket client (internal function)
+ * @param client WebSocket client handle
+ * @param challenge Challenge string to store
+ * @return NOSTR_SUCCESS or error code
+ */
+int nostr_ws_store_challenge(struct nostr_ws_client* client,
+                            const char* challenge);
+
+/**
+ * Clear authentication state in WebSocket client
+ * @param client WebSocket client handle
+ * @return NOSTR_SUCCESS or error code
+ */
+int nostr_ws_clear_auth_state(struct nostr_ws_client* client);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NIP042_H

nostr_core/nostr_common.c

@@ -38,6 +38,20 @@ const char* nostr_strerror(int error_code) {
         case NOSTR_ERROR_EVENT_INVALID_KIND: return "Event has invalid kind";
         case NOSTR_ERROR_EVENT_INVALID_TAGS: return "Event has invalid tags";
         case NOSTR_ERROR_EVENT_INVALID_CONTENT: return "Event has invalid content";
+        case NOSTR_ERROR_NIP13_INSUFFICIENT: return "NIP-13: Insufficient PoW difficulty";
+        case NOSTR_ERROR_NIP13_NO_NONCE_TAG: return "NIP-13: Missing nonce tag";
+        case NOSTR_ERROR_NIP13_INVALID_NONCE_TAG: return "NIP-13: Invalid nonce tag format";
+        case NOSTR_ERROR_NIP13_TARGET_MISMATCH: return "NIP-13: Target difficulty mismatch";
+        case NOSTR_ERROR_NIP13_CALCULATION: return "NIP-13: PoW calculation error";
+        case NOSTR_ERROR_NIP42_INVALID_CHALLENGE: return "NIP-42: Invalid challenge";
+        case NOSTR_ERROR_NIP42_CHALLENGE_EXPIRED: return "NIP-42: Challenge expired";
+        case NOSTR_ERROR_NIP42_AUTH_EVENT_INVALID: return "NIP-42: Authentication event invalid";
+        case NOSTR_ERROR_NIP42_URL_MISMATCH: return "NIP-42: Relay URL mismatch";
+        case NOSTR_ERROR_NIP42_TIME_TOLERANCE: return "NIP-42: Timestamp outside tolerance";
+        case NOSTR_ERROR_NIP42_NOT_AUTHENTICATED: return "NIP-42: Client not authenticated";
+        case NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT: return "NIP-42: Invalid message format";
+        case NOSTR_ERROR_NIP42_CHALLENGE_TOO_SHORT: return "NIP-42: Challenge too short";
+        case NOSTR_ERROR_NIP42_CHALLENGE_TOO_LONG: return "NIP-42: Challenge too long";
         default: return "Unknown error";
     }
 }

nostr_core/nostr_common.h

@@ -36,6 +36,31 @@
 #define NOSTR_ERROR_EVENT_INVALID_TAGS -36
 #define NOSTR_ERROR_EVENT_INVALID_CONTENT -37
 
+// Authentication Rules System Error Codes
+#define NOSTR_ERROR_AUTH_RULES_DISABLED -50
+#define NOSTR_ERROR_AUTH_RULES_DENIED -51
+#define NOSTR_ERROR_AUTH_RULES_DB_FAILED -52
+#define NOSTR_ERROR_AUTH_RULES_INVALID_RULE -53
+#define NOSTR_ERROR_AUTH_RULES_CACHE_FAILED -54
+#define NOSTR_ERROR_AUTH_RULES_BACKEND_NOT_FOUND -55
+
+// NIP-13 PoW-specific error codes
+#define NOSTR_ERROR_NIP13_INSUFFICIENT -100
+#define NOSTR_ERROR_NIP13_NO_NONCE_TAG -101
+#define NOSTR_ERROR_NIP13_INVALID_NONCE_TAG -102
+#define NOSTR_ERROR_NIP13_TARGET_MISMATCH -103
+#define NOSTR_ERROR_NIP13_CALCULATION -104
+
+// NIP-42 Authentication-specific error codes
+#define NOSTR_ERROR_NIP42_INVALID_CHALLENGE -200
+#define NOSTR_ERROR_NIP42_CHALLENGE_EXPIRED -201
+#define NOSTR_ERROR_NIP42_AUTH_EVENT_INVALID -202
+#define NOSTR_ERROR_NIP42_URL_MISMATCH -203
+#define NOSTR_ERROR_NIP42_TIME_TOLERANCE -204
+#define NOSTR_ERROR_NIP42_NOT_AUTHENTICATED -205
+#define NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT -206
+#define NOSTR_ERROR_NIP42_CHALLENGE_TOO_SHORT -207
+#define NOSTR_ERROR_NIP42_CHALLENGE_TOO_LONG -208
 
 // Constants
 #define NOSTR_PRIVATE_KEY_SIZE 32

nostr_core/nostr_core.h

@@ -42,7 +42,14 @@
  *   - nostr_nip44_encrypt()             -> Encrypt with ChaCha20 + HMAC
  *   - nostr_nip44_encrypt_with_nonce()  -> Encrypt with specific nonce (testing)
  *   - nostr_nip44_decrypt()             -> Decrypt ChaCha20 + HMAC messages
- * 
+ *
+ * NIP-42 AUTHENTICATION:
+ *   - nostr_nip42_create_auth_event()   -> Create authentication event (kind 22242)
+ *   - nostr_nip42_verify_auth_event()   -> Verify authentication event (relay-side)
+ *   - nostr_nip42_generate_challenge()  -> Generate challenge string (relay-side)
+ *   - nostr_ws_authenticate()           -> Authenticate WebSocket client
+ *   - nostr_ws_get_auth_state()         -> Get client authentication state
+ *
  * BIP39 MNEMONICS:
  *   - nostr_bip39_mnemonic_from_bytes() -> Generate mnemonic from entropy
  *   - nostr_bip39_mnemonic_validate()   -> Validate mnemonic phrase
@@ -65,7 +72,16 @@
  *   - nostr_hex_to_bytes()              -> Convert hex string to bytes
  *   - base64_encode()                   -> Base64 encoding
  *   - base64_decode()                   -> Base64 decoding
- * 
+ *
+ * REQUEST VALIDATION & AUTHENTICATION:
+ *   - nostr_validate_request()          -> Unified request validation (events + auth rules)
+ *   - nostr_request_validator_init()    -> Initialize authentication system
+ *   - nostr_auth_check_upload()         -> Validate file upload requests
+ *   - nostr_auth_check_delete()         -> Validate file delete requests
+ *   - nostr_auth_check_publish()        -> Validate event publish requests
+ *   - nostr_auth_rule_add()             -> Add authentication rule
+ *   - nostr_auth_rule_remove()          -> Remove authentication rule
+ *
  * SYSTEM FUNCTIONS:
  *   - nostr_crypto_init()               -> Initialize crypto subsystem
  *   - nostr_crypto_cleanup()            -> Cleanup crypto subsystem
@@ -96,7 +112,11 @@
  *   nostr_bip32_key_from_seed(seed, 64, &master_key);
  *   uint32_t path[] = {44, 1237, 0, 0, 0}; // m/44'/1237'/0'/0/0
  *   nostr_bip32_derive_path(&master_key, path, 5, &derived_key);
- * 
+ *
+ * Client Authentication (NIP-42):
+ *   cJSON* auth_event = nostr_nip42_create_auth_event(challenge, relay_url, private_key, 0);
+ *   nostr_ws_authenticate(client, private_key, 600); // Auto-authenticate WebSocket
+ *
  * ============================================================================
  */
 
@@ -116,8 +136,12 @@ extern "C" {
 #include "nip011.h"  // Relay information document
 #include "nip013.h"  // Proof of Work
 #include "nip019.h"  // Bech32 encoding (nsec/npub)
+#include "nip042.h"  // Authentication of clients to relays
 #include "nip044.h"  // Encryption (modern)
 
+// Authentication and request validation system
+#include "request_validator.h"  // Request validation and authentication rules
+
 // Relay communication functions are defined in nostr_common.h
 // WebSocket functions are defined in nostr_common.h
 

nostr_core/request_validator.h

@@ -0,0 +1,274 @@
+/*
+ * NOSTR Core Library - Request Validator
+ * 
+ * Unified authentication and authorization system for NOSTR applications.
+ * Provides rule-based validation for requests with pluggable database backends.
+ * 
+ * This module combines basic NOSTR event validation with sophisticated 
+ * authentication rules to provide a single entry point for request validation
+ * across different NOSTR applications (ginxsom, c-relay, etc.).
+ */
+
+#ifndef NOSTR_REQUEST_VALIDATOR_H
+#define NOSTR_REQUEST_VALIDATOR_H
+
+#include "nostr_common.h"
+#include <time.h>
+#include <sqlite3.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Forward declaration for cJSON
+struct cJSON;
+
+// Authentication rule types
+typedef enum {
+    NOSTR_AUTH_RULE_PUBKEY_WHITELIST,
+    NOSTR_AUTH_RULE_PUBKEY_BLACKLIST,
+    NOSTR_AUTH_RULE_HASH_BLACKLIST,
+    NOSTR_AUTH_RULE_MIME_WHITELIST,
+    NOSTR_AUTH_RULE_MIME_BLACKLIST,
+    NOSTR_AUTH_RULE_SIZE_LIMIT,
+    NOSTR_AUTH_RULE_RATE_LIMIT,
+    NOSTR_AUTH_RULE_CUSTOM
+} nostr_auth_rule_type_t;
+
+// Authentication request context
+typedef struct {
+    const char* operation;        // Operation type ("upload", "delete", "list", "publish")
+    const char* auth_header;      // Raw authorization header (optional)
+    struct cJSON* event;          // NOSTR event for validation (optional)
+    
+    // Resource context (for file/blob operations)
+    const char* resource_hash;    // Resource hash (SHA-256, optional)
+    const char* mime_type;        // MIME type (optional)
+    long file_size;               // File size (optional)
+    
+    // Client context
+    const char* client_ip;        // Client IP for rate limiting (optional)
+    void* app_context;            // Application-specific context (optional)
+} nostr_request_t;
+
+// Authentication result
+typedef struct {
+    int valid;                    // 0 = invalid/denied, 1 = valid/allowed
+    int error_code;               // NOSTR_SUCCESS or specific error code
+    char reason[256];             // Human-readable reason for denial
+    char pubkey[65];              // Extracted pubkey from validated event (if available)
+    int rule_id;                  // Rule ID that made the decision (0 if no rule)
+    int priority;                 // Priority of the rule that matched
+    time_t cached_until;          // Cache expiration time
+} nostr_request_result_t;
+
+// Authentication rule definition
+typedef struct {
+    int rule_id;                  // Unique rule identifier
+    nostr_auth_rule_type_t type;  // Rule type
+    char operation[32];           // Target operation ("*", "upload", "delete", "publish", etc.)
+    char target[256];             // Rule target (pubkey, hash, mime pattern, etc.)
+    char value[256];              // Rule value (size limit, rate limit, custom data)
+    int priority;                 // Rule priority (lower number = higher priority)
+    int enabled;                  // 1 = enabled, 0 = disabled
+    time_t expires_at;            // Expiration timestamp (0 = never expires)
+    char description[512];        // Human-readable description
+    time_t created_at;            // Creation timestamp
+} nostr_auth_rule_t;
+
+// Database backend interface (pluggable)
+typedef struct nostr_auth_db_interface {
+    const char* name;             // Backend name ("sqlite", "redis", etc.)
+    
+    // Database lifecycle
+    int (*init)(const char* db_path, const char* app_name);
+    void (*cleanup)(void);
+    
+    // Configuration management
+    int (*get_config)(const char* key, char* value, size_t value_size);
+    int (*set_config)(const char* key, const char* value);
+    
+    // Rule querying and management
+    int (*query_rules)(const nostr_request_t* request, nostr_auth_rule_t** rules, int* count);
+    int (*rule_add)(const nostr_auth_rule_t* rule);
+    int (*rule_remove)(int rule_id);
+    int (*rule_update)(const nostr_auth_rule_t* rule);
+    int (*rule_list)(const char* operation, nostr_auth_rule_t** rules, int* count);
+    
+    // Caching operations
+    int (*cache_get)(const char* cache_key, nostr_request_result_t* result);
+    int (*cache_set)(const char* cache_key, const nostr_request_result_t* result, int ttl);
+    int (*cache_clear)(void);
+} nostr_auth_db_interface_t;
+
+//=============================================================================
+// CORE API FUNCTIONS
+//=============================================================================
+
+/**
+ * Initialize the request validator system with application database
+ * 
+ * @param app_db_path Path to application's SQLite database
+ * @param app_name Application name for logging/identification
+ * @return NOSTR_SUCCESS on success, error code on failure
+ */
+int nostr_request_validator_init(const char* app_db_path, const char* app_name);
+
+/**
+ * Initialize with shared database (future use)
+ * 
+ * @param shared_db_path Path to shared authentication database
+ * @param app_name Application name for logging/identification
+ * @return NOSTR_SUCCESS on success, error code on failure
+ */
+int nostr_request_validator_init_shared(const char* shared_db_path, const char* app_name);
+
+/**
+ * Main request validation function - validates both NOSTR events and authentication rules
+ * 
+ * @param request Request context with operation, auth header, and resource details
+ * @param result Result structure with validation outcome and details
+ * @return NOSTR_SUCCESS on successful validation processing, error code on system failure
+ */
+int nostr_validate_request(const nostr_request_t* request, nostr_request_result_t* result);
+
+/**
+ * Check if authentication rules system is enabled
+ * 
+ * @return 1 if enabled, 0 if disabled
+ */
+int nostr_auth_rules_enabled(void);
+
+/**
+ * Cleanup request validator resources
+ */
+void nostr_request_validator_cleanup(void);
+
+//=============================================================================
+// CONVENIENCE FUNCTIONS
+//=============================================================================
+
+/**
+ * Convenience function for upload validation (ginxsom integration)
+ * 
+ * @param pubkey Uploader public key (optional, extracted from auth if NULL)
+ * @param auth_header Authorization header with NOSTR event
+ * @param hash File hash (SHA-256)
+ * @param mime_type File MIME type
+ * @param file_size File size in bytes
+ * @return NOSTR_SUCCESS if allowed, error code if denied
+ */
+int nostr_auth_check_upload(const char* pubkey, const char* auth_header, 
+                           const char* hash, const char* mime_type, long file_size);
+
+/**
+ * Convenience function for delete validation (ginxsom integration)
+ * 
+ * @param pubkey Requester public key
+ * @param auth_header Authorization header with NOSTR event
+ * @param hash File hash to delete
+ * @return NOSTR_SUCCESS if allowed, error code if denied
+ */
+int nostr_auth_check_delete(const char* pubkey, const char* auth_header, const char* hash);
+
+/**
+ * Convenience function for publish validation (c-relay integration)
+ * 
+ * @param pubkey Publisher public key
+ * @param event NOSTR event to publish
+ * @return NOSTR_SUCCESS if allowed, error code if denied
+ */
+int nostr_auth_check_publish(const char* pubkey, struct cJSON* event);
+
+//=============================================================================
+// RULE MANAGEMENT FUNCTIONS
+//=============================================================================
+
+/**
+ * Add a new authentication rule
+ * 
+ * @param rule Rule definition to add
+ * @return NOSTR_SUCCESS on success, error code on failure
+ */
+int nostr_auth_rule_add(const nostr_auth_rule_t* rule);
+
+/**
+ * Remove an authentication rule by ID
+ * 
+ * @param rule_id Rule ID to remove
+ * @return NOSTR_SUCCESS on success, error code on failure
+ */
+int nostr_auth_rule_remove(int rule_id);
+
+/**
+ * Update an existing authentication rule
+ * 
+ * @param rule Updated rule definition
+ * @return NOSTR_SUCCESS on success, error code on failure
+ */
+int nostr_auth_rule_update(const nostr_auth_rule_t* rule);
+
+/**
+ * List authentication rules for a specific operation
+ * 
+ * @param operation Target operation ("*" for all operations)
+ * @param rules Pointer to receive allocated array of rules
+ * @param count Pointer to receive number of rules returned
+ * @return NOSTR_SUCCESS on success, error code on failure
+ */
+int nostr_auth_rule_list(const char* operation, nostr_auth_rule_t** rules, int* count);
+
+/**
+ * Free rule array allocated by nostr_auth_rule_list
+ * 
+ * @param rules Rule array to free
+ * @param count Number of rules in array
+ */
+void nostr_auth_rules_free(nostr_auth_rule_t* rules, int count);
+
+//=============================================================================
+// DATABASE BACKEND MANAGEMENT
+//=============================================================================
+
+/**
+ * Register a database backend implementation
+ * 
+ * @param backend Backend interface implementation
+ * @return NOSTR_SUCCESS on success, error code on failure
+ */
+int nostr_auth_register_db_backend(const nostr_auth_db_interface_t* backend);
+
+/**
+ * Set active database backend by name
+ * 
+ * @param backend_name Name of backend to activate
+ * @return NOSTR_SUCCESS on success, error code on failure
+ */
+int nostr_auth_set_db_backend(const char* backend_name);
+
+//=============================================================================
+// CACHE MANAGEMENT
+//=============================================================================
+
+/**
+ * Clear authentication decision cache
+ * 
+ * @return NOSTR_SUCCESS on success, error code on failure
+ */
+int nostr_auth_cache_clear(void);
+
+/**
+ * Get cache statistics
+ * 
+ * @param hit_count Pointer to receive cache hit count
+ * @param miss_count Pointer to receive cache miss count
+ * @param entries Pointer to receive current number of cache entries
+ * @return NOSTR_SUCCESS on success, error code on failure
+ */
+int nostr_auth_cache_stats(int* hit_count, int* miss_count, int* entries);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* NOSTR_REQUEST_VALIDATOR_H */

tests/nip13_test.c

@@ -0,0 +1,491 @@
+/*
+ * NIP-13 Proof of Work Test Suite
+ * Tests PoW generation, difficulty calculation, nonce extraction, and validation
+ * Following TESTS POLICY: Shows expected vs actual values, prints entire JSON events
+ */
+
+#define _GNU_SOURCE  // For strdup on Linux
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include <unistd.h>
+#include "../nostr_core/nip013.h"
+#include "../nostr_core/nip001.h"
+#include "../nostr_core/nostr_common.h"
+#include "../nostr_core/utils.h"
+#include "../cjson/cJSON.h"
+
+// Ensure strdup is declared
+#ifndef strdup
+extern char *strdup(const char *s);
+#endif
+
+// Test counter for tracking progress
+static int test_count = 0;
+static int passed_tests = 0;
+
+void print_test_header(const char* test_name) {
+    test_count++;
+    printf("\n=== TEST %d: %s ===\n", test_count, test_name);
+}
+
+void print_test_result(int passed, const char* test_name) {
+    if (passed) {
+        passed_tests++;
+        printf("✅ PASS: %s\n", test_name);
+    } else {
+        printf("❌ FAIL: %s\n", test_name);
+    }
+}
+
+// Test 1: Difficulty calculation with NIP-13 example
+int test_difficulty_calculation_reference(void) {
+    print_test_header("Difficulty Calculation - NIP-13 Reference");
+    
+    // Event ID from NIP-13 spec: 000006d8c378af1779d2feebc7603a125d99eca0ccf1085959b307f64e5dd358
+    // This should have ~20 leading zero bits as stated in the spec
+    const char* event_id = "000006d8c378af1779d2feebc7603a125d99eca0ccf1085959b307f64e5dd358";
+    
+    printf("Testing event ID: %s\n", event_id);
+    printf("Expected: ~20 leading zero bits\n");
+    
+    int difficulty = nostr_calculate_pow_difficulty(event_id);
+    printf("Actual: %d leading zero bits\n", difficulty);
+    
+    if (difficulty < 0) {
+        printf("❌ Error calculating difficulty: %d (%s)\n", difficulty, nostr_strerror(difficulty));
+        return 0;
+    }
+    
+    // The NIP-13 spec example should have around 20 bits
+    if (difficulty >= 19 && difficulty <= 21) {
+        printf("✅ Difficulty calculation matches expected range (19-21 bits)\n");
+        return 1;
+    } else {
+        printf("❌ Difficulty %d is outside expected range (19-21 bits)\n", difficulty);
+        return 0;
+    }
+}
+
+// Test 2: Extract nonce info from NIP-13 reference event
+int test_nonce_extraction_reference(void) {
+    print_test_header("Nonce Extraction - NIP-13 Reference Event");
+    
+    // Complete event from NIP-13 spec
+    const char* event_json = "{"
+        "\"id\":\"000006d8c378af1779d2feebc7603a125d99eca0ccf1085959b307f64e5dd358\","
+        "\"pubkey\":\"a48380f4cfcc1ad5378294fcac36439770f9c878dd880ffa94bb74ea54a6f243\","
+        "\"created_at\":1651794653,"
+        "\"kind\":1,"
+        "\"tags\":[[\"nonce\",\"776797\",\"20\"]],"
+        "\"content\":\"It's just me mining my own business\","
+        "\"sig\":\"284622fc0a3f4f1303455d5175f7ba962a3300d136085b9566801bc2e0699de0c7e31e44c81fb40ad9049173742e904713c3594a1da0fc5d2382a25c11aba977\""
+    "}";
+    
+    printf("Input Event JSON:\n%s\n\n", event_json);
+    
+    cJSON* event = cJSON_Parse(event_json);
+    if (!event) {
+        printf("❌ JSON Parse Error\n");
+        return 0;
+    }
+    
+    uint64_t nonce_value = 0;
+    int target_difficulty = -1;
+    int result = nostr_extract_nonce_info(event, &nonce_value, &target_difficulty);
+    
+    printf("Extraction result: %d (%s)\n", result, nostr_strerror(result));
+    printf("Expected nonce: 776797\n");
+    printf("Actual nonce: %llu\n", (unsigned long long)nonce_value);
+    printf("Expected target: 20\n");
+    printf("Actual target: %d\n", target_difficulty);
+    
+    cJSON_Delete(event);
+    
+    if (result != NOSTR_SUCCESS) {
+        printf("❌ Failed to extract nonce info\n");
+        return 0;
+    }
+    
+    if (nonce_value == 776797 && target_difficulty == 20) {
+        printf("✅ Nonce extraction successful\n");
+        return 1;
+    } else {
+        printf("❌ Extracted values don't match expected\n");
+        return 0;
+    }
+}
+
+// Test 3: PoW validation with reference event
+int test_pow_validation_reference(void) {
+    print_test_header("PoW Validation - NIP-13 Reference Event");
+    
+    const char* event_json = "{"
+        "\"id\":\"000006d8c378af1779d2feebc7603a125d99eca0ccf1085959b307f64e5dd358\","
+        "\"pubkey\":\"a48380f4cfcc1ad5378294fcac36439770f9c878dd880ffa94bb74ea54a6f243\","
+        "\"created_at\":1651794653,"
+        "\"kind\":1,"
+        "\"tags\":[[\"nonce\",\"776797\",\"20\"]],"
+        "\"content\":\"It's just me mining my own business\","
+        "\"sig\":\"284622fc0a3f4f1303455d5175f7ba962a3300d136085b9566801bc2e0699de0c7e31e44c81fb40ad9049173742e904713c3594a1da0fc5d2382a25c11aba977\""
+    "}";
+    
+    printf("Input Event JSON:\n%s\n\n", event_json);
+    
+    cJSON* event = cJSON_Parse(event_json);
+    if (!event) {
+        printf("❌ JSON Parse Error\n");
+        return 0;
+    }
+    
+    // Test basic validation (no minimum difficulty)
+    nostr_pow_result_t result_info;
+    int validation_result = nostr_validate_pow(event, 0, NOSTR_POW_VALIDATE_BASIC, &result_info);
+    
+    printf("Validation result: %d (%s)\n", validation_result, nostr_strerror(validation_result));
+    printf("Actual difficulty: %d\n", result_info.actual_difficulty);
+    printf("Committed target: %d\n", result_info.committed_target);
+    printf("Nonce value: %llu\n", (unsigned long long)result_info.nonce_value);
+    printf("Has nonce tag: %d\n", result_info.has_nonce_tag);
+    printf("Error detail: %s\n", result_info.error_detail);
+    
+    cJSON_Delete(event);
+    return (validation_result == NOSTR_SUCCESS && result_info.has_nonce_tag == 1);
+}
+
+// Test 4: Generate PoW with our library and validate it
+int test_pow_generation_and_validation(void) {
+    print_test_header("PoW Generation and Validation - Our Library");
+    
+    // Create a test event for mining
+    const char* private_key_hex = "91ba716fa9e7ea2fcbad360cf4f8e0d312f73984da63d90f524ad61a6a1e7dbe";
+    unsigned char private_key[32];
+    nostr_hex_to_bytes(private_key_hex, private_key, 32);
+    
+    cJSON* tags = cJSON_CreateArray();
+    
+    printf("Creating base event...\n");
+    cJSON* event = nostr_create_and_sign_event(1, "Testing PoW generation", tags, private_key, time(NULL));
+    
+    if (!event) {
+        printf("❌ Event creation failed\n");
+        cJSON_Delete(tags);
+        return 0;
+    }
+    
+    char* original_event_str = cJSON_Print(event);
+    printf("Original event (no PoW):\n%s\n\n", original_event_str);
+    free(original_event_str);
+    
+    // Add PoW with difficulty 8 (reasonable for testing)
+    printf("Adding PoW with difficulty 8...\n");
+    int pow_result = nostr_add_proof_of_work(event, private_key, 8, 100000, 10000, 10000, NULL, NULL);
+    
+    if (pow_result != NOSTR_SUCCESS) {
+        printf("❌ PoW generation failed: %d (%s)\n", pow_result, nostr_strerror(pow_result));
+        cJSON_Delete(event);
+        return 0;
+    }
+    
+    char* pow_event_str = cJSON_Print(event);
+    printf("Event with PoW:\n%s\n\n", pow_event_str);
+    free(pow_event_str);
+    
+    // Now validate the PoW
+    printf("Validating generated PoW...\n");
+    nostr_pow_result_t result_info;
+    int validation_result = nostr_validate_pow(event, 8, NOSTR_POW_VALIDATE_FULL, &result_info);
+    
+    printf("Validation result: %d (%s)\n", validation_result, nostr_strerror(validation_result));
+    printf("Actual difficulty: %d\n", result_info.actual_difficulty);
+    printf("Committed target: %d\n", result_info.committed_target);
+    printf("Has nonce tag: %d\n", result_info.has_nonce_tag);
+    printf("Error detail: %s\n", result_info.error_detail);
+    
+    cJSON_Delete(event);
+    
+    if (validation_result == NOSTR_SUCCESS && result_info.actual_difficulty >= 8) {
+        printf("✅ PoW generation and validation successful\n");
+        return 1;
+    } else {
+        printf("❌ PoW validation failed\n");
+        return 0;
+    }
+}
+
+// Test 5: Test various validation flag combinations
+int test_validation_flags(void) {
+    print_test_header("Validation Flags - Various Combinations");
+    
+    // Use NIP-13 reference event
+    const char* event_json = "{"
+        "\"id\":\"000006d8c378af1779d2feebc7603a125d99eca0ccf1085959b307f64e5dd358\","
+        "\"pubkey\":\"a48380f4cfcc1ad5378294fcac36439770f9c878dd880ffa94bb74ea54a6f243\","
+        "\"created_at\":1651794653,"
+        "\"kind\":1,"
+        "\"tags\":[[\"nonce\",\"776797\",\"20\"]],"
+        "\"content\":\"It's just me mining my own business\","
+        "\"sig\":\"284622fc0a3f4f1303455d5175f7ba962a3300d136085b9566801bc2e0699de0c7e31e44c81fb40ad9049173742e904713c3594a1da0fc5d2382a25c11aba977\""
+    "}";
+    
+    cJSON* event = cJSON_Parse(event_json);
+    if (!event) {
+        printf("❌ JSON Parse Error\n");
+        return 0;
+    }
+    
+    int all_passed = 1;
+    nostr_pow_result_t result_info;
+    
+    // Test 1: Basic validation
+    printf("\nSubtest 1: NOSTR_POW_VALIDATE_BASIC\n");
+    int result = nostr_validate_pow(event, 0, NOSTR_POW_VALIDATE_BASIC, &result_info);
+    printf("Result: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_SUCCESS) all_passed = 0;
+    
+    // Test 2: Full validation
+    printf("\nSubtest 2: NOSTR_POW_VALIDATE_FULL\n");
+    result = nostr_validate_pow(event, 0, NOSTR_POW_VALIDATE_FULL, &result_info);
+    printf("Result: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_SUCCESS) all_passed = 0;
+    
+    // Test 3: Anti-spam validation (should pass since committed target matches actual)
+    printf("\nSubtest 3: NOSTR_POW_VALIDATE_ANTI_SPAM\n");
+    result = nostr_validate_pow(event, 0, NOSTR_POW_VALIDATE_ANTI_SPAM, &result_info);
+    printf("Result: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_SUCCESS) all_passed = 0;
+    
+    // Test 4: Minimum difficulty requirement (15 bits - should pass)
+    printf("\nSubtest 4: Minimum difficulty 15 bits\n");
+    result = nostr_validate_pow(event, 15, NOSTR_POW_VALIDATE_BASIC, &result_info);
+    printf("Result: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_SUCCESS) all_passed = 0;
+    
+    // Test 5: Too high minimum difficulty (30 bits - should fail)
+    printf("\nSubtest 5: Minimum difficulty 30 bits (should fail)\n");
+    result = nostr_validate_pow(event, 30, NOSTR_POW_VALIDATE_BASIC, &result_info);
+    printf("Result: %d (%s)\n", result, nostr_strerror(result));
+    if (result == NOSTR_SUCCESS) {
+        printf("❌ Should have failed but didn't\n");
+        all_passed = 0;
+    } else if (result == NOSTR_ERROR_NIP13_INSUFFICIENT) {
+        printf("✅ Correctly failed with insufficient difficulty\n");
+    } else {
+        printf("❌ Failed with unexpected error\n");
+        all_passed = 0;
+    }
+    
+    cJSON_Delete(event);
+    return all_passed;
+}
+
+// Test 6: Error conditions and edge cases
+int test_error_conditions(void) {
+    print_test_header("Error Conditions and Edge Cases");
+    
+    int all_passed = 1;
+    
+    // Test 1: NULL event
+    printf("\nSubtest 1: NULL event\n");
+    int result = nostr_validate_pow(NULL, 0, NOSTR_POW_VALIDATE_BASIC, NULL);
+    printf("Expected: NOSTR_ERROR_INVALID_INPUT (-1)\n");
+    printf("Actual: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_ERROR_INVALID_INPUT) all_passed = 0;
+    
+    // Test 2: Event without ID
+    printf("\nSubtest 2: Event without ID\n");
+    const char* no_id_json = "{\"kind\":1,\"content\":\"test\",\"tags\":[]}";
+    cJSON* no_id_event = cJSON_Parse(no_id_json);
+    result = nostr_validate_pow(no_id_event, 0, NOSTR_POW_VALIDATE_BASIC, NULL);
+    printf("Expected: NOSTR_ERROR_EVENT_INVALID_ID (-31)\n");
+    printf("Actual: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_ERROR_EVENT_INVALID_ID) all_passed = 0;
+    cJSON_Delete(no_id_event);
+    
+    // Test 3: Event without nonce tag when required
+    printf("\nSubtest 3: Event without nonce tag when required\n");
+    const char* no_nonce_json = "{"
+        "\"id\":\"f1e582c90f071c0110cc5bcac2dcc6d8c32250e3cc26fcbe93470d918f2ffaf0\","
+        "\"kind\":1,\"content\":\"test\",\"tags\":[]"
+    "}";
+    cJSON* no_nonce_event = cJSON_Parse(no_nonce_json);
+    result = nostr_validate_pow(no_nonce_event, 0, NOSTR_POW_VALIDATE_NONCE_TAG, NULL);
+    printf("Expected: NOSTR_ERROR_NIP13_NO_NONCE_TAG (-101)\n");
+    printf("Actual: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_ERROR_NIP13_NO_NONCE_TAG) all_passed = 0;
+    cJSON_Delete(no_nonce_event);
+    
+    // Test 4: Invalid hex ID
+    printf("\nSubtest 4: Invalid hex ID\n");
+    result = nostr_calculate_pow_difficulty("invalid_hex_string");
+    printf("Expected: NOSTR_ERROR_NIP13_CALCULATION (-104)\n");
+    printf("Actual: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_ERROR_NIP13_CALCULATION) all_passed = 0;
+    
+    // Test 5: Wrong length hex ID
+    printf("\nSubtest 5: Wrong length hex ID\n");
+    result = nostr_calculate_pow_difficulty("f1e582c90f071c0110cc5bcac2dcc6d8c32250e3cc26fcbe93470d918f2ffa"); // 63 chars instead of 64
+    printf("Expected: NOSTR_ERROR_NIP13_CALCULATION (-104)\n");
+    printf("Actual: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_ERROR_NIP13_CALCULATION) all_passed = 0;
+    
+    return all_passed;
+}
+
+// Test 7: Integration with nak-generated PoW events
+int test_nak_integration(void) {
+    print_test_header("Integration with nak-generated PoW events");
+    
+    // Generate a test event with nak and PoW difficulty 8
+    printf("Generating PoW event with nak (difficulty 8)...\n");
+    
+    // Create a temporary key for this test
+    char temp_key[] = "/tmp/nip13_test_key_XXXXXX";
+    int fd = mkstemp(temp_key);
+    if (fd == -1) {
+        printf("❌ Failed to create temporary key file\n");
+        return 0;
+    }
+    
+    // Write test key to file (same as used in other tests)
+    const char* test_key = "91ba716fa9e7ea2fcbad360cf4f8e0d312f73984da63d90f524ad61a6a1e7dbe";
+    ssize_t bytes_written = write(fd, test_key, strlen(test_key));
+    close(fd);
+    
+    if (bytes_written != (ssize_t)strlen(test_key)) {
+        printf("❌ Failed to write test key to temporary file\n");
+        unlink(temp_key);
+        return 0;
+    }
+    
+    // Generate event with PoW using nak
+    char cmd[1024];
+    snprintf(cmd, sizeof(cmd), "nak event --sec %s -c \"PoW test from nak\" --pow 8 --ts %ld", 
+             test_key, (long)time(NULL));
+    
+    printf("Executing: %s\n", cmd);
+    FILE* pipe = popen(cmd, "r");
+    if (!pipe) {
+        printf("❌ Failed to execute nak command\n");
+        unlink(temp_key);
+        return 0;
+    }
+    
+    char event_json[4096] = {0};
+    if (!fgets(event_json, sizeof(event_json), pipe)) {
+        printf("❌ Failed to read nak output\n");
+        pclose(pipe);
+        unlink(temp_key);
+        return 0;
+    }
+    pclose(pipe);
+    unlink(temp_key);
+    
+    // Remove trailing newline
+    event_json[strcspn(event_json, "\n")] = 0;
+    
+    printf("nak-generated event:\n%s\n\n", event_json);
+    
+    // Parse and validate the event
+    cJSON* event = cJSON_Parse(event_json);
+    if (!event) {
+        printf("❌ Failed to parse nak-generated JSON\n");
+        return 0;
+    }
+    
+    // Validate the PoW
+    nostr_pow_result_t result_info;
+    int validation_result = nostr_validate_pow(event, 8, NOSTR_POW_VALIDATE_FULL, &result_info);
+    
+    printf("Validation result: %d (%s)\n", validation_result, nostr_strerror(validation_result));
+    printf("Actual difficulty: %d\n", result_info.actual_difficulty);
+    printf("Committed target: %d\n", result_info.committed_target);
+    printf("Has nonce tag: %d\n", result_info.has_nonce_tag);
+    printf("Error detail: %s\n", result_info.error_detail);
+    
+    cJSON_Delete(event);
+    
+    if (validation_result == NOSTR_SUCCESS && result_info.actual_difficulty >= 8) {
+        printf("✅ nak-generated PoW event validates successfully\n");
+        return 1;
+    } else {
+        printf("❌ nak-generated PoW event validation failed\n");
+        return 0;
+    }
+}
+
+int main(void) {
+    printf("=== NIP-13 Proof of Work Test Suite ===\n");
+    printf("Following TESTS POLICY: Shows expected vs actual values, prints entire JSON events\n");
+    printf("Tests both PoW generation and validation functionality\n");
+    
+    // Initialize crypto library
+    if (nostr_init() != NOSTR_SUCCESS) {
+        printf("❌ Failed to initialize nostr library\n");
+        return 1;
+    }
+    
+    int all_passed = 1;
+    int test_result;
+    
+    // Test 1: Basic difficulty calculation
+    test_result = test_difficulty_calculation_reference();
+    print_test_result(test_result, "Difficulty Calculation - NIP-13 Reference");
+    if (!test_result) all_passed = 0;
+    
+    // Test 2: Nonce extraction
+    test_result = test_nonce_extraction_reference();
+    print_test_result(test_result, "Nonce Extraction - NIP-13 Reference Event");
+    if (!test_result) all_passed = 0;
+    
+    // Test 3: Basic PoW validation
+    test_result = test_pow_validation_reference();
+    print_test_result(test_result, "PoW Validation - NIP-13 Reference Event");
+    if (!test_result) all_passed = 0;
+    
+    // Test 4: PoW generation and validation
+    test_result = test_pow_generation_and_validation();
+    print_test_result(test_result, "PoW Generation and Validation - Our Library");
+    if (!test_result) all_passed = 0;
+    
+    // Test 5: Validation flags
+    test_result = test_validation_flags();
+    print_test_result(test_result, "Validation Flags - Various Combinations");
+    if (!test_result) all_passed = 0;
+    
+    // Test 6: Error conditions
+    test_result = test_error_conditions();
+    print_test_result(test_result, "Error Conditions and Edge Cases");
+    if (!test_result) all_passed = 0;
+    
+    // Test 7: nak integration (optional - may fail if nak not available)
+    printf("\n=== Optional nak Integration Test ===\n");
+    test_result = test_nak_integration();
+    if (test_result) {
+        print_test_result(test_result, "Integration with nak-generated PoW events");
+    } else {
+        printf("⚠️  SKIP: Integration with nak-generated PoW events (nak may not be available)\n");
+        // Don't fail the entire test suite for this optional test
+    }
+    
+    // Summary
+    printf("\n=== TEST SUMMARY ===\n");
+    printf("Total tests: %d\n", test_count);
+    printf("Passed: %d\n", passed_tests);
+    printf("Failed: %d\n", test_count - passed_tests);
+    
+    if (all_passed) {
+        printf("🎉 ALL TESTS PASSED! NIP-13 PoW implementation is working correctly.\n");
+        printf("✅ PoW generation works\n");
+        printf("✅ PoW difficulty calculation works\n");
+        printf("✅ Nonce extraction works\n");
+        printf("✅ PoW validation works\n");
+        printf("✅ Error handling works\n");
+    } else {
+        printf("❌ SOME TESTS FAILED. Please review the output above.\n");
+    }
+    
+    nostr_cleanup();
+    return all_passed ? 0 : 1;
+}

tests/nip42_test.c

@@ -0,0 +1,690 @@
+/*
+ * NIP-42 Authentication of Clients to Relays Test Suite
+ * Tests auth challenge generation, event creation, validation, and message parsing
+ * Following TESTS POLICY: Shows expected vs actual values, prints entire JSON events
+ */
+
+#define _GNU_SOURCE  // For strdup on Linux
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include <unistd.h>
+#include "../nostr_core/nip042.h"
+#include "../nostr_core/nip001.h"
+#include "../nostr_core/nostr_common.h"
+#include "../nostr_core/utils.h"
+#include "../cjson/cJSON.h"
+
+// Ensure strdup is declared
+#ifndef strdup
+extern char *strdup(const char *s);
+#endif
+
+// Test counter for tracking progress
+static int test_count = 0;
+static int passed_tests = 0;
+
+void print_test_header(const char* test_name) {
+    test_count++;
+    printf("\n=== TEST %d: %s ===\n", test_count, test_name);
+}
+
+void print_test_result(int passed, const char* test_name) {
+    if (passed) {
+        passed_tests++;
+        printf("✅ PASS: %s\n", test_name);
+    } else {
+        printf("❌ FAIL: %s\n", test_name);
+    }
+}
+
+void print_json_comparison(const char* label, cJSON* expected, cJSON* actual) {
+    char* expected_str = cJSON_Print(expected);
+    char* actual_str;
+    
+    if (actual) {
+        actual_str = cJSON_Print(actual);
+    } else {
+        actual_str = strdup("NULL");
+    }
+    
+    printf("%s Expected JSON:\n%s\n", label, expected_str ? expected_str : "NULL");
+    printf("%s Actual JSON:\n%s\n", label, actual_str ? actual_str : "NULL");
+    
+    if (expected_str) free(expected_str);
+    if (actual_str) free(actual_str);
+}
+
+// Test 1: Challenge generation
+int test_challenge_generation(void) {
+    print_test_header("Challenge Generation");
+    
+    nostr_auth_challenge_t challenge1, challenge2;
+    
+    printf("Generating first challenge...\n");
+    int result1 = nostr_nip42_generate_challenge(challenge1.challenge, NOSTR_NIP42_DEFAULT_CHALLENGE_LENGTH);
+    printf("Result: %d (%s)\n", result1, nostr_strerror(result1));
+    
+    if (result1 != NOSTR_SUCCESS) {
+        printf("❌ Failed to generate first challenge\n");
+        return 0;
+    }
+    
+    printf("First challenge: %s\n", challenge1.challenge);
+    printf("Challenge length: %lu\n", strlen(challenge1.challenge));
+    printf("Expected length: %d\n", NOSTR_NIP42_DEFAULT_CHALLENGE_LENGTH * 2);
+    
+    if (strlen(challenge1.challenge) != NOSTR_NIP42_DEFAULT_CHALLENGE_LENGTH * 2) {
+        printf("❌ Challenge length incorrect\n");
+        return 0;
+    }
+    
+    printf("Generating second challenge...\n");
+    int result2 = nostr_nip42_generate_challenge(challenge2.challenge, NOSTR_NIP42_DEFAULT_CHALLENGE_LENGTH);
+    printf("Result: %d (%s)\n", result2, nostr_strerror(result2));
+    
+    if (result2 != NOSTR_SUCCESS) {
+        printf("❌ Failed to generate second challenge\n");
+        return 0;
+    }
+    
+    printf("Second challenge: %s\n", challenge2.challenge);
+    
+    // Challenges should be different (extremely high probability)
+    if (strcmp(challenge1.challenge, challenge2.challenge) == 0) {
+        printf("❌ Two challenges are identical (highly unlikely)\n");
+        return 0;
+    }
+    
+    printf("✅ Challenges are different (good entropy)\n");
+    return 1;
+}
+
+// Test 2: AUTH message creation (server-side challenge)
+int test_auth_message_creation(void) {
+    print_test_header("AUTH Message Creation - Server Challenge");
+    
+    nostr_auth_challenge_t challenge;
+    int gen_result = nostr_nip42_generate_challenge(challenge.challenge, NOSTR_NIP42_DEFAULT_CHALLENGE_LENGTH);
+    
+    if (gen_result != NOSTR_SUCCESS) {
+        printf("❌ Failed to generate challenge for message test\n");
+        return 0;
+    }
+    
+    printf("Generated challenge: %s\n", challenge.challenge);
+    
+    // Create AUTH challenge message: ["AUTH", "challenge_string"]
+    cJSON* message_array = cJSON_CreateArray();
+    if (!message_array) {
+        printf("❌ Failed to create message array\n");
+        return 0;
+    }
+    
+    cJSON_AddItemToArray(message_array, cJSON_CreateString("AUTH"));
+    cJSON_AddItemToArray(message_array, cJSON_CreateString(challenge.challenge));
+    
+    char* auth_message = cJSON_PrintUnformatted(message_array);
+    cJSON_Delete(message_array);
+    
+    if (!auth_message) {
+        printf("❌ Failed to create AUTH message\n");
+        return 0;
+    }
+    
+    int result = NOSTR_SUCCESS;
+    
+    printf("Message creation result: %d (%s)\n", result, nostr_strerror(result));
+    printf("AUTH message: %s\n", auth_message);
+    
+    // Parse the message to verify format
+    cJSON* parsed = cJSON_Parse(auth_message);
+    if (!parsed) {
+        printf("❌ AUTH message is not valid JSON\n");
+        return 0;
+    }
+    
+    // Check if it's an array with 2 elements
+    if (!cJSON_IsArray(parsed) || cJSON_GetArraySize(parsed) != 2) {
+        printf("❌ AUTH message is not a 2-element array\n");
+        cJSON_Delete(parsed);
+        return 0;
+    }
+    
+    // Check first element is "AUTH"
+    cJSON* first = cJSON_GetArrayItem(parsed, 0);
+    if (!cJSON_IsString(first) || strcmp(cJSON_GetStringValue(first), "AUTH") != 0) {
+        printf("❌ First element is not 'AUTH'\n");
+        cJSON_Delete(parsed);
+        return 0;
+    }
+    
+    // Check second element is our challenge string
+    cJSON* second = cJSON_GetArrayItem(parsed, 1);
+    if (!cJSON_IsString(second) || strcmp(cJSON_GetStringValue(second), challenge.challenge) != 0) {
+        printf("❌ Second element is not our challenge string\n");
+        printf("Expected: %s\n", challenge.challenge);
+        printf("Actual: %s\n", cJSON_GetStringValue(second));
+        cJSON_Delete(parsed);
+        free(auth_message);
+        return 0;
+    }
+    
+    printf("✅ AUTH challenge message format is correct\n");
+    cJSON_Delete(parsed);
+    free(auth_message);
+    return 1;
+}
+
+// Test 3: Authentication event creation (client-side)
+int test_auth_event_creation(void) {
+    print_test_header("Authentication Event Creation - Client Side");
+    
+    const char* private_key_hex = "91ba716fa9e7ea2fcbad360cf4f8e0d312f73984da63d90f524ad61a6a1e7dbe";
+    const char* relay_url = "wss://relay.example.com";
+    const char* challenge_string = "test_challenge_12345678901234567890123456789012";
+    
+    unsigned char private_key[32];
+    nostr_hex_to_bytes(private_key_hex, private_key, 32);
+    
+    printf("Private key (hex): %s\n", private_key_hex);
+    printf("Relay URL: %s\n", relay_url);
+    printf("Challenge: %s\n", challenge_string);
+    
+    cJSON* auth_event = nostr_nip42_create_auth_event(challenge_string, relay_url, private_key, 0);
+    
+    if (!auth_event) {
+        printf("❌ Failed to create authentication event\n");
+        return 0;
+    }
+    
+    char* event_str = cJSON_Print(auth_event);
+    printf("Created Auth Event JSON:\n%s\n", event_str);
+    free(event_str);
+    
+    // Validate the event structure
+    int structure_result = nostr_validate_event_structure(auth_event);
+    printf("Structure validation result: %d (%s)\n", structure_result, nostr_strerror(structure_result));
+    
+    if (structure_result != NOSTR_SUCCESS) {
+        printf("❌ Auth event failed structure validation\n");
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    
+    // Validate the event signature
+    int crypto_result = nostr_verify_event_signature(auth_event);
+    printf("Signature validation result: %d (%s)\n", crypto_result, nostr_strerror(crypto_result));
+    
+    if (crypto_result != NOSTR_SUCCESS) {
+        printf("❌ Auth event failed signature validation\n");
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    
+    // Check kind is 22242
+    cJSON* kind = cJSON_GetObjectItem(auth_event, "kind");
+    if (!cJSON_IsNumber(kind) || cJSON_GetNumberValue(kind) != 22242) {
+        printf("❌ Auth event kind is not 22242\n");
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    
+    // Check for relay tag
+    cJSON* tags = cJSON_GetObjectItem(auth_event, "tags");
+    int found_relay = 0, found_challenge = 0;
+    
+    if (cJSON_IsArray(tags)) {
+        cJSON* tag = NULL;
+        cJSON_ArrayForEach(tag, tags) {
+            if (cJSON_IsArray(tag) && cJSON_GetArraySize(tag) >= 2) {
+                cJSON* tag_name = cJSON_GetArrayItem(tag, 0);
+                cJSON* tag_value = cJSON_GetArrayItem(tag, 1);
+                
+                if (cJSON_IsString(tag_name) && cJSON_IsString(tag_value)) {
+                    if (strcmp(cJSON_GetStringValue(tag_name), "relay") == 0) {
+                        found_relay = 1;
+                        if (strcmp(cJSON_GetStringValue(tag_value), relay_url) != 0) {
+                            printf("❌ Relay tag value incorrect\n");
+                            printf("Expected: %s\n", relay_url);
+                            printf("Actual: %s\n", cJSON_GetStringValue(tag_value));
+                            cJSON_Delete(auth_event);
+                            return 0;
+                        }
+                    } else if (strcmp(cJSON_GetStringValue(tag_name), "challenge") == 0) {
+                        found_challenge = 1;
+                        if (strcmp(cJSON_GetStringValue(tag_value), challenge_string) != 0) {
+                            printf("❌ Challenge tag value incorrect\n");
+                            printf("Expected: %s\n", challenge_string);
+                            printf("Actual: %s\n", cJSON_GetStringValue(tag_value));
+                            cJSON_Delete(auth_event);
+                            return 0;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    
+    if (!found_relay) {
+        printf("❌ Missing relay tag\n");
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    
+    if (!found_challenge) {
+        printf("❌ Missing challenge tag\n");
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    
+    printf("✅ Authentication event created successfully with correct tags\n");
+    cJSON_Delete(auth_event);
+    return 1;
+}
+
+// Test 4: Authentication event validation (server-side)
+int test_auth_event_validation(void) {
+    print_test_header("Authentication Event Validation - Server Side");
+    
+    // Create a valid auth event first
+    const char* private_key_hex = "91ba716fa9e7ea2fcbad360cf4f8e0d312f73984da63d90f524ad61a6a1e7dbe";
+    const char* relay_url = "wss://relay.example.com";
+    const char* challenge_string = "validation_challenge_1234567890123456789012";
+    
+    unsigned char private_key[32];
+    nostr_hex_to_bytes(private_key_hex, private_key, 32);
+    
+    cJSON* auth_event = nostr_nip42_create_auth_event(challenge_string, relay_url, private_key, 0);
+    
+    if (!auth_event) {
+        printf("❌ Failed to create auth event for validation test\n");
+        return 0;
+    }
+    
+    char* event_str = cJSON_Print(auth_event);
+    printf("Auth Event to validate:\n%s\n", event_str);
+    free(event_str);
+    
+    // Test successful validation
+    printf("Testing successful validation...\n");
+    int result = nostr_nip42_verify_auth_event(auth_event, challenge_string, relay_url, 0);
+    printf("Validation result: %d (%s)\n", result, nostr_strerror(result));
+    
+    if (result != NOSTR_SUCCESS) {
+        printf("❌ Valid auth event failed validation\n");
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    printf("✅ Valid auth event passed validation\n");
+    
+    // Test wrong relay URL
+    printf("\nTesting wrong relay URL...\n");
+    result = nostr_nip42_verify_auth_event(auth_event, challenge_string, "wss://wrong.relay.com", 0);
+    printf("Expected: NOSTR_ERROR_NIP42_URL_MISMATCH (-206)\n");
+    printf("Actual: %d (%s)\n", result, nostr_strerror(result));
+    
+    if (result != NOSTR_ERROR_NIP42_URL_MISMATCH) {
+        printf("❌ Wrong relay validation didn't fail correctly\n");
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    printf("✅ Wrong relay URL correctly rejected\n");
+    
+    // Test wrong challenge
+    printf("\nTesting wrong challenge...\n");
+    result = nostr_nip42_verify_auth_event(auth_event, "wrong_challenge_string_here", relay_url, 0);
+    printf("Expected: NOSTR_ERROR_NIP42_INVALID_CHALLENGE (-203)\n");
+    printf("Actual: %d (%s)\n", result, nostr_strerror(result));
+    
+    if (result != NOSTR_ERROR_NIP42_INVALID_CHALLENGE) {
+        printf("❌ Wrong challenge validation didn't fail correctly\n");
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    printf("✅ Wrong challenge correctly rejected\n");
+    
+    cJSON_Delete(auth_event);
+    return 1;
+}
+
+// Test 5: AUTH message parsing (client-side)
+int test_auth_message_parsing(void) {
+    print_test_header("AUTH Message Parsing - Client Side");
+    
+    // Test parsing challenge message
+    const char* challenge_msg = "[\"AUTH\", \"test_challenge_from_server_123456789012\"]";
+    printf("Parsing AUTH challenge message: %s\n", challenge_msg);
+    
+    char extracted_challenge[NOSTR_NIP42_MAX_CHALLENGE_LENGTH];
+    int result = nostr_nip42_parse_auth_challenge(challenge_msg, extracted_challenge, sizeof(extracted_challenge));
+    
+    printf("Parse result: %d (%s)\n", result, nostr_strerror(result));
+    printf("Expected challenge: test_challenge_from_server_123456789012\n");
+    printf("Extracted challenge: %s\n", extracted_challenge);
+    
+    if (result != NOSTR_SUCCESS) {
+        printf("❌ Failed to parse valid AUTH message\n");
+        return 0;
+    }
+    
+    if (strcmp(extracted_challenge, "test_challenge_from_server_123456789012") != 0) {
+        printf("❌ Extracted challenge doesn't match expected\n");
+        return 0;
+    }
+    printf("✅ AUTH challenge message parsed correctly\n");
+    
+    // Test invalid message format
+    printf("\nTesting invalid message format...\n");
+    const char* invalid_msg = "[\"WRONG\", \"challenge\"]";
+    result = nostr_nip42_parse_auth_challenge(invalid_msg, extracted_challenge, sizeof(extracted_challenge));
+    
+    printf("Parse result: %d (%s)\n", result, nostr_strerror(result));
+    printf("Expected: NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT (-205)\n");
+    
+    if (result != NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT) {
+        printf("❌ Invalid message format should have failed\n");
+        return 0;
+    }
+    printf("✅ Invalid message format correctly rejected\n");
+    
+    return 1;
+}
+
+// Test 6: AUTH response message creation (client-side)
+int test_auth_response_creation(void) {
+    print_test_header("AUTH Response Message Creation - Client Side");
+    
+    // Create an auth event first
+    const char* private_key_hex = "91ba716fa9e7ea2fcbad360cf4f8e0d312f73984da63d90f524ad61a6a1e7dbe";
+    const char* relay_url = "wss://relay.example.com";
+    const char* challenge_string = "response_test_challenge_1234567890123456";
+    
+    unsigned char private_key[32];
+    nostr_hex_to_bytes(private_key_hex, private_key, 32);
+    
+    cJSON* auth_event = nostr_nip42_create_auth_event(challenge_string, relay_url, private_key, 0);
+    
+    if (!auth_event) {
+        printf("❌ Failed to create auth event for response test\n");
+        return 0;
+    }
+    
+    char* auth_response = nostr_nip42_create_auth_message(auth_event);
+    int result = auth_response ? NOSTR_SUCCESS : NOSTR_ERROR_MEMORY_FAILED;
+    
+    printf("Response creation result: %d (%s)\n", result, nostr_strerror(result));
+    printf("AUTH response message: %s\n", auth_response ? auth_response : "NULL");
+    
+    if (result != NOSTR_SUCCESS) {
+        printf("❌ Failed to create AUTH response message\n");
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    
+    // Parse and validate the response format
+    cJSON* parsed = cJSON_Parse(auth_response);
+    if (!parsed) {
+        printf("❌ AUTH response is not valid JSON\n");
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    
+    // Should be ["AUTH", <event-json>]
+    if (!cJSON_IsArray(parsed) || cJSON_GetArraySize(parsed) != 2) {
+        printf("❌ AUTH response is not a 2-element array\n");
+        cJSON_Delete(parsed);
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    
+    cJSON* first = cJSON_GetArrayItem(parsed, 0);
+    if (!cJSON_IsString(first) || strcmp(cJSON_GetStringValue(first), "AUTH") != 0) {
+        printf("❌ First element is not 'AUTH'\n");
+        cJSON_Delete(parsed);
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    
+    cJSON* second = cJSON_GetArrayItem(parsed, 1);
+    if (!cJSON_IsObject(second)) {
+        printf("❌ Second element is not an object (event)\n");
+        cJSON_Delete(parsed);
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    
+    // Check if the event in the response matches our created event
+    cJSON* response_kind = cJSON_GetObjectItem(second, "kind");
+    if (!cJSON_IsNumber(response_kind) || cJSON_GetNumberValue(response_kind) != 22242) {
+        printf("❌ Response event kind is not 22242\n");
+        cJSON_Delete(parsed);
+        cJSON_Delete(auth_event);
+        return 0;
+    }
+    
+    printf("✅ AUTH response message format is correct\n");
+    cJSON_Delete(parsed);
+    cJSON_Delete(auth_event);
+    free(auth_response);
+    return 1;
+}
+
+// Test 7: Error conditions and edge cases
+int test_error_conditions(void) {
+    print_test_header("Error Conditions and Edge Cases");
+    
+    int all_passed = 1;
+    
+    // Test 1: NULL parameters
+    printf("\nSubtest 1: NULL parameters\n");
+    int result = nostr_nip42_generate_challenge(NULL, 32);
+    printf("Expected: NOSTR_ERROR_INVALID_INPUT (-1)\n");
+    printf("Actual: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_ERROR_INVALID_INPUT) all_passed = 0;
+    
+    // Test 2: Invalid challenge length
+    printf("\nSubtest 2: Invalid challenge in validation\n");
+    const char* private_key_hex = "91ba716fa9e7ea2fcbad360cf4f8e0d312f73984da63d90f524ad61a6a1e7dbe";
+    const char* relay_url = "wss://relay.example.com";
+    const char* valid_challenge = "valid_challenge_1234567890123456789012345";
+    
+    unsigned char private_key[32];
+    nostr_hex_to_bytes(private_key_hex, private_key, 32);
+    
+    cJSON* auth_event = nostr_nip42_create_auth_event(valid_challenge, relay_url, private_key, 0);
+    if (auth_event) {
+        result = nostr_nip42_verify_auth_event(auth_event, "short", relay_url, 0);  // Too short
+        printf("Expected: NOSTR_ERROR_NIP42_INVALID_CHALLENGE (-203)\n");
+        printf("Actual: %d (%s)\n", result, nostr_strerror(result));
+        if (result != NOSTR_ERROR_NIP42_INVALID_CHALLENGE) all_passed = 0;
+        cJSON_Delete(auth_event);
+    } else {
+        printf("❌ Failed to create auth event for validation test\n");
+        all_passed = 0;
+    }
+    
+    // Test 3: Invalid JSON parsing
+    printf("\nSubtest 3: Invalid JSON in message parsing\n");
+    char challenge_buffer[NOSTR_NIP42_MAX_CHALLENGE_LENGTH];
+    result = nostr_nip42_parse_auth_challenge("invalid json", challenge_buffer, sizeof(challenge_buffer));
+    printf("Expected: NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT (-205)\n");
+    printf("Actual: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT) all_passed = 0;
+    
+    // Test 4: Wrong array size
+    printf("\nSubtest 4: Wrong array size in message parsing\n");
+    result = nostr_nip42_parse_auth_challenge("[\"AUTH\"]", challenge_buffer, sizeof(challenge_buffer));  // Only 1 element
+    printf("Expected: NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT (-205)\n");
+    printf("Actual: %d (%s)\n", result, nostr_strerror(result));
+    if (result != NOSTR_ERROR_NIP42_INVALID_MESSAGE_FORMAT) all_passed = 0;
+    
+    return all_passed;
+}
+
+// Test 8: Full authentication flow simulation
+int test_full_auth_flow(void) {
+    print_test_header("Full Authentication Flow Simulation");
+    
+    const char* private_key_hex = "91ba716fa9e7ea2fcbad360cf4f8e0d312f73984da63d90f524ad61a6a1e7dbe";
+    const char* relay_url = "wss://test-relay.nostr.com";
+    
+    unsigned char private_key[32];
+    nostr_hex_to_bytes(private_key_hex, private_key, 32);
+    
+    printf("=== STEP 1: Server generates challenge ===\n");
+    nostr_auth_challenge_t challenge;
+    int result = nostr_nip42_generate_challenge(challenge.challenge, NOSTR_NIP42_DEFAULT_CHALLENGE_LENGTH);
+    if (result != NOSTR_SUCCESS) {
+        printf("❌ Failed to generate challenge\n");
+        return 0;
+    }
+    printf("Generated challenge: %s\n", challenge.challenge);
+    
+    printf("\n=== STEP 2: Server sends AUTH message ===\n");
+    cJSON* message_array = cJSON_CreateArray();
+    cJSON_AddItemToArray(message_array, cJSON_CreateString("AUTH"));
+    cJSON_AddItemToArray(message_array, cJSON_CreateString(challenge.challenge));
+    char* auth_message = cJSON_PrintUnformatted(message_array);
+    cJSON_Delete(message_array);
+    
+    if (!auth_message) {
+        printf("❌ Failed to create AUTH message\n");
+        return 0;
+    }
+    printf("Server sends: %s\n", auth_message);
+    
+    printf("\n=== STEP 3: Client parses AUTH message ===\n");
+    char parsed_challenge[NOSTR_NIP42_MAX_CHALLENGE_LENGTH];
+    result = nostr_nip42_parse_auth_challenge(auth_message, parsed_challenge, sizeof(parsed_challenge));
+    if (result != NOSTR_SUCCESS) {
+        printf("❌ Failed to parse AUTH message\n");
+        free(auth_message);
+        return 0;
+    }
+    printf("Client extracted challenge: %s\n", parsed_challenge);
+    
+    if (strcmp(challenge.challenge, parsed_challenge) != 0) {
+        printf("❌ Parsed challenge doesn't match original\n");
+        free(auth_message);
+        return 0;
+    }
+    
+    printf("\n=== STEP 4: Client creates auth event ===\n");
+    cJSON* auth_event = nostr_nip42_create_auth_event(parsed_challenge, relay_url, private_key, 0);
+    if (!auth_event) {
+        printf("❌ Failed to create auth event\n");
+        return 0;
+    }
+    
+    char* event_str = cJSON_Print(auth_event);
+    printf("Client created auth event:\n%s\n", event_str);
+    free(event_str);
+    
+    printf("\n=== STEP 5: Client sends AUTH response ===\n");
+    char* auth_response = nostr_nip42_create_auth_message(auth_event);
+    if (!auth_response) {
+        printf("❌ Failed to create AUTH response\n");
+        cJSON_Delete(auth_event);
+        free(auth_message);
+        return 0;
+    }
+    printf("Client sends: %s\n", auth_response);
+    
+    printf("\n=== STEP 6: Server validates auth event ===\n");
+    result = nostr_nip42_verify_auth_event(auth_event, challenge.challenge, relay_url, 0);
+    printf("Server validation result: %d (%s)\n", result, nostr_strerror(result));
+    
+    if (result != NOSTR_SUCCESS) {
+        printf("❌ Server validation failed\n");
+        cJSON_Delete(auth_event);
+        free(auth_message);
+        free(auth_response);
+        return 0;
+    }
+    
+    printf("✅ FULL AUTHENTICATION FLOW COMPLETED SUCCESSFULLY!\n");
+    printf("✅ Challenge generated -> Message sent -> Challenge parsed -> Event created -> Response sent -> Event validated\n");
+    
+    cJSON_Delete(auth_event);
+    free(auth_message);
+    free(auth_response);
+    return 1;
+}
+
+int main(void) {
+    printf("=== NIP-42 Authentication of Clients to Relays Test Suite ===\n");
+    printf("Following TESTS POLICY: Shows expected vs actual values, prints entire JSON events\n");
+    printf("Tests both client-side and server-side authentication functionality\n");
+    
+    // Initialize crypto library
+    if (nostr_init() != NOSTR_SUCCESS) {
+        printf("❌ Failed to initialize nostr library\n");
+        return 1;
+    }
+    
+    int all_passed = 1;
+    int test_result;
+    
+    // Test 1: Challenge generation
+    test_result = test_challenge_generation();
+    print_test_result(test_result, "Challenge Generation");
+    if (!test_result) all_passed = 0;
+    
+    // Test 2: AUTH message creation
+    test_result = test_auth_message_creation();
+    print_test_result(test_result, "AUTH Message Creation - Server Challenge");
+    if (!test_result) all_passed = 0;
+    
+    // Test 3: Auth event creation
+    test_result = test_auth_event_creation();
+    print_test_result(test_result, "Authentication Event Creation - Client Side");
+    if (!test_result) all_passed = 0;
+    
+    // Test 4: Auth event validation
+    test_result = test_auth_event_validation();
+    print_test_result(test_result, "Authentication Event Validation - Server Side");
+    if (!test_result) all_passed = 0;
+    
+    // Test 5: AUTH message parsing
+    test_result = test_auth_message_parsing();
+    print_test_result(test_result, "AUTH Message Parsing - Client Side");
+    if (!test_result) all_passed = 0;
+    
+    // Test 6: AUTH response creation
+    test_result = test_auth_response_creation();
+    print_test_result(test_result, "AUTH Response Message Creation - Client Side");
+    if (!test_result) all_passed = 0;
+    
+    // Test 7: Error conditions
+    test_result = test_error_conditions();
+    print_test_result(test_result, "Error Conditions and Edge Cases");
+    if (!test_result) all_passed = 0;
+    
+    // Test 8: Full authentication flow
+    test_result = test_full_auth_flow();
+    print_test_result(test_result, "Full Authentication Flow Simulation");
+    if (!test_result) all_passed = 0;
+    
+    // Summary
+    printf("\n=== TEST SUMMARY ===\n");
+    printf("Total tests: %d\n", test_count);
+    printf("Passed: %d\n", passed_tests);
+    printf("Failed: %d\n", test_count - passed_tests);
+    
+    if (all_passed) {
+        printf("🎉 ALL TESTS PASSED! NIP-42 Authentication implementation is working correctly.\n");
+        printf("✅ Challenge generation works\n");
+        printf("✅ AUTH message creation/parsing works\n");
+        printf("✅ Authentication event creation works\n");
+        printf("✅ Authentication event validation works\n");
+        printf("✅ Full authentication flow works\n");
+        printf("✅ Error handling works\n");
+    } else {
+        printf("❌ SOME TESTS FAILED. Please review the output above.\n");
+    }
+    
+    nostr_cleanup();
+    return all_passed ? 0 : 1;
+}