nostr_core_lib/todo.md

Nostr Event Validation Implementation Checklist

Implementation Plan: NIP-001 Event Validation

1. Create Test Suite tests/nip01_validation_test.c (FIRST - Test-Driven Development)

• Use nak command line tool to generate valid test events
• Create test vectors with known valid events
• Test valid event validation (should pass)
• Test invalid structure cases:
  • Missing required fields
  • Wrong field types
  • Invalid hex string lengths
  • Invalid timestamps
  • Invalid kind values
  • Invalid tag structures
• Test invalid cryptographic cases:
  • Wrong event ID
  • Invalid signature
  • Mismatched pubkey
• Test edge cases and boundary conditions
• Follow TESTS POLICY: Show expected vs actual values, print full JSON events

2. Add Error Codes to nostr_core/nostr_common.h

• Add validation-specific error codes after existing NIP error codes (line ~21):

  #define NOSTR_ERROR_EVENT_INVALID_STRUCTURE -30
  #define NOSTR_ERROR_EVENT_INVALID_ID -31
  #define NOSTR_ERROR_EVENT_INVALID_PUBKEY -32
  #define NOSTR_ERROR_EVENT_INVALID_SIGNATURE -33
  #define NOSTR_ERROR_EVENT_INVALID_CREATED_AT -34
  #define NOSTR_ERROR_EVENT_INVALID_KIND -35
  #define NOSTR_ERROR_EVENT_INVALID_TAGS -36
  #define NOSTR_ERROR_EVENT_INVALID_CONTENT -37
  

3. Update Error String Function in nostr_core/nostr_common.c

• Add cases for new error codes in nostr_strerror() function

4. Add Function Declarations to nostr_core/nip001.h

• Add validation function declarations after existing function:

  // Event validation functions
  int nostr_validate_event_structure(cJSON* event);
  int nostr_verify_event_signature(cJSON* event);
  int nostr_validate_event(cJSON* event);
  

5. Implement Functions in nostr_core/nip001.c

• nostr_validate_event_structure() - Structure validation:

  • Check required fields exist: id, pubkey, created_at, kind, tags, content, sig
  • Validate field types (strings, numbers, arrays)
  • Validate hex string formats (id: 64 chars, pubkey: 64 chars, sig: 128 chars)
  • Validate created_at is valid timestamp
  • Validate kind is valid integer (0-65535)
  • Validate tags is array of string arrays
  • Validate content is string

• nostr_verify_event_signature() - Cryptographic verification:

  • Generate serialized event string: [0,<pubkey>,<created_at>,<kind>,<tags>,<content>]
  • Calculate SHA-256 hash of serialized event
  • Convert hash to hex string and compare with event.id
  • Verify Schnorr signature using existing nostr_schnorr_verify() from utils.h
  • Use hex conversion functions from utils.h

• nostr_validate_event() - Complete validation:

  • Call nostr_validate_event_structure() first
  • If structure valid, call nostr_verify_event_signature()
  • Return appropriate error codes

6. Update Build System

• Ensure new test compiles with existing build.sh
• Test compilation of all new code

7. Integration Testing

• Test with real Nostr events from network
• Test with events created by existing nostr_create_and_sign_event()
• Verify compatibility with existing relay functions

Technical Implementation Details

Required Dependencies (Already Available):

• nostr_sha256() from nostr_core/utils.h
• nostr_schnorr_verify() from nostr_core/utils.h
• nostr_hex_to_bytes() from nostr_core/utils.h
• nostr_bytes_to_hex() from nostr_core/utils.h
• cJSON library for JSON parsing

Validation Logic Based on NIP-01 and nostr-tools Reference:

1. Structure Validation: Fast checks on JSON structure and basic format
2. Cryptographic Validation: Expensive signature verification only after structure passes
3. Two-tier approach: Allows early exit on malformed events

Error Handling Strategy:

• Return specific error codes for different validation failures
• Enable caller to understand exactly what failed
• Maintain consistency with existing error code patterns

Files to Modify:

• nostr_core/nostr_common.h (add error codes)
• nostr_core/nostr_common.c (update error strings)
• nostr_core/nip001.h (add function declarations)
• nostr_core/nip001.c (implement functions)
• tests/nip01_validation_test.c (create new file)

Testing Priority:

1. Structure validation with malformed events
2. Cryptographic validation with tampered events
3. Valid event validation end-to-end
4. Integration with existing event creation functions
5. Performance testing with large numbers of events