ginxsom/docs/NIP42_INTEGRATION_PLAN.md

# NIP-42 Authentication Integration Plan

## Overview
This document outlines the integration of NIP-42 client-to-relay authentication into the existing ginxsom authentication system. The goal is to support both NIP-42 (kind 22242) and Blossom (kind 24242) authentication methods in a unified system.

## Current System Analysis

### Existing Authentication Flow
1. **Blossom Protocol (kind 24242)**: Operation-specific authorization
   - Tags: `t` (method), `x` (hash), `expiration`
   - Purpose: Authorize specific file operations (upload, delete, etc.)
   - Location: `validate_nostr_event()` in `request_validator.c:379`

2. **Rules Engine**: Policy-based access control
   - Pubkey whitelist/blacklist
   - Hash blacklist
   - MIME type restrictions
   - File size limits
   - Location: `evaluate_auth_rules()` in `request_validator.c:1029`

### Integration Points Identified
1. **Header Structure**: Extend `nostr_request_t` to support NIP-42 context
2. **Event Validation**: Support both kind 22242 (NIP-42) and 24242 (Blossom)
3. **Challenge Management**: Add challenge generation and storage
4. **Database Schema**: Add challenge storage tables
5. **Authentication Flow**: Support dual authentication modes

## NIP-42 Integration Architecture

### Dual Authentication Strategy
```
Client Authentication (NIP-42) → Operation Authorization (Blossom) → Rules Engine
```

- **NIP-42 (kind 22242)**: Proves client identity to relay
- **Blossom (kind 24242)**: Authorizes specific operations
- **Rules Engine**: Applies policy-based restrictions

### Authentication Flow Options
1. **NIP-42 Only**: Client authenticates identity, all operations allowed by rules
2. **Blossom Only**: Current system - operation-specific authorization
3. **Dual Mode**: NIP-42 identity + Blossom operation authorization
4. **Rules Only**: No cryptographic auth, rules-based access only

## Technical Implementation Plan

### 1. Extend Request Validator Header (`request_validator.h`)
```c
// Add NIP-42 support structures
typedef struct {
    char challenge[256];        // Current challenge for client
    time_t challenge_created;   // Challenge timestamp
    char relay_url[256];        // Relay URL for challenge
    int is_authenticated;       // NIP-42 auth status
    char authenticated_pubkey[65]; // Pubkey from NIP-42 auth
} nostr_nip42_context_t;

// Extend nostr_request_t
typedef struct {
    // ... existing fields ...
    nostr_nip42_context_t* nip42_context;  // NIP-42 authentication context
    const char* challenge;                  // Challenge for this request
} nostr_request_t;
```

### 2. Database Schema Extensions
```sql
-- NIP-42 challenge storage
CREATE TABLE IF NOT EXISTS nip42_challenges (
    challenge_id TEXT PRIMARY KEY,
    challenge TEXT NOT NULL,
    relay_url TEXT NOT NULL,
    created_at INTEGER NOT NULL,
    expires_at INTEGER NOT NULL,
    client_ip TEXT
);

-- NIP-42 authentication sessions
CREATE TABLE IF NOT EXISTS nip42_sessions (
    session_id TEXT PRIMARY KEY,
    pubkey TEXT NOT NULL,
    challenge_id TEXT NOT NULL,
    authenticated_at INTEGER NOT NULL,
    expires_at INTEGER NOT NULL,
    client_ip TEXT,
    FOREIGN KEY (challenge_id) REFERENCES nip42_challenges(challenge_id)
);
```

### 3. Core Functions to Add
```c
// NIP-42 challenge management
int nostr_nip42_generate_server_challenge(char* challenge_out, size_t challenge_size);
int nostr_nip42_store_challenge(const char* challenge, const char* relay_url, const char* client_ip);
int nostr_nip42_verify_challenge_response(const char* auth_header, const char* relay_url, nostr_request_result_t* result);

// Enhanced validation
int validate_nip42_event(struct cJSON* event, const char* expected_challenge, const char* relay_url);
int validate_blossom_event(struct cJSON* event, const char* expected_hash, const char* method);

// Dual authentication support
int nostr_validate_request_dual(const nostr_request_t* request, nostr_request_result_t* result);
```

### 4. Enhanced Event Validation
Extend `validate_nostr_event()` to handle both event kinds:
```c
static int validate_nostr_event(struct cJSON* event, const char* expected_hash, const char* method) {
    struct cJSON* kind_json = cJSON_GetObjectItem(event, "kind");
    int kind = cJSON_GetNumberValue(kind_json);
    
    switch (kind) {
        case 22242: // NIP-42 authentication
            return validate_nip42_event(event, expected_hash, method);
        case 24242: // Blossom authorization
            return validate_blossom_event(event, expected_hash, method);
        default:
            return NOSTR_ERROR_EVENT_INVALID_KIND;
    }
}
```

### 5. Ginxsom Integration Points

#### Main.c Changes
```c
// Add challenge endpoint
if (strcmp(request_method, "GET") == 0 && strstr(request_uri, "/.well-known/nostr/challenge")) {
    handle_nip42_challenge_request(response);
    return;
}

// Enhanced authentication in existing endpoints
int handle_upload_request(FCGX_Request* request) {
    // ... existing code ...
    
    // Check for NIP-42 challenge header
    const char* challenge_header = FCGX_GetParam("HTTP_X_NOSTR_CHALLENGE", request->envp);
    
    nostr_request_t nostr_request = {
        .operation = "upload",
        .auth_header = auth_header,
        .resource_hash = file_hash,
        .mime_type = content_type,
        .file_size = content_length,
        .challenge = challenge_header,
        .nip42_context = &nip42_ctx
    };
}
```

## Configuration Options

### New Configuration Keys
```sql
-- NIP-42 specific settings
INSERT OR REPLACE INTO auth_config VALUES ('nip42_enabled', 'true');
INSERT OR REPLACE INTO auth_config VALUES ('nip42_challenge_ttl', '600');
INSERT OR REPLACE INTO auth_config VALUES ('nip42_session_ttl', '3600');
INSERT OR REPLACE INTO auth_config VALUES ('auth_mode', 'dual'); -- dual, nip42_only, blossom_only, rules_only
INSERT OR REPLACE INTO auth_config VALUES ('relay_url', 'http://localhost:9001');
```

### Authentication Modes
1. **dual**: NIP-42 + Blossom + Rules (most secure)
2. **nip42_only**: NIP-42 + Rules (client identity required)
3. **blossom_only**: Blossom + Rules (current system)
4. **rules_only**: Rules only (no cryptographic auth)

## Testing Strategy

### Test Cases to Add
1. **NIP-42 Challenge Flow**: Generate challenge, verify response
2. **Kind 22242 Validation**: Test NIP-42 event structure and signatures
3. **Dual Authentication**: NIP-42 auth + Blossom authorization
4. **Challenge Expiration**: Test challenge TTL and cleanup
5. **Session Management**: Test session creation and expiration
6. **Mixed Mode Testing**: Different auth modes in same server
7. **Error Handling**: Invalid challenges, expired sessions, etc.

### Test File Structure
```bash
tests/
├── nip42_basic_test.sh          # Basic NIP-42 functionality
├── nip42_challenge_test.sh      # Challenge generation and validation
├── nip42_dual_auth_test.sh      # Dual authentication mode
└── nip42_integration_test.sh    # Full integration testing
```

## Build System Integration

### Files to Update
1. **build.sh**: Already includes `nip042.c` in sources
2. **nostr_core.h**: Already includes `nip042.h`
3. **Makefile**: May need to link additional NIP-42 functions

## Implementation Order

1. ✅ **Analysis Complete**: Current system understood
2. **Extend Headers**: Add NIP-42 structures to request_validator.h
3. **Database Schema**: Add challenge and session tables
4. **Core Functions**: Implement challenge management
5. **Event Validation**: Extend validation for kind 22242
6. **Request Validation**: Update nostr_validate_request()
7. **Ginxsom Integration**: Add challenge endpoints and auth checks
8. **Build Integration**: Ensure NIP-42 is compiled
9. **Testing**: Create comprehensive test suite
10. **Documentation**: Update API documentation

## Benefits of This Integration

1. **Standards Compliance**: Full NIP-42 support for Nostr ecosystem compatibility
2. **Flexible Authentication**: Support multiple auth modes based on use case
3. **Enhanced Security**: Dual authentication provides defense in depth
4. **Backward Compatibility**: Existing Blossom auth continues to work
5. **Future Proof**: Ready for Nostr relay ecosystem integration

## Migration Path

### Phase 1: Basic NIP-42 Support
- Add NIP-42 validation alongside existing system
- No breaking changes to current auth

### Phase 2: Enhanced Integration
- Add challenge management and session handling
- Optional dual authentication mode

### Phase 3: Full Integration
- Complete NIP-42 relay compatibility
- Advanced session management features

This integration maintains full backward compatibility while adding powerful new authentication capabilities that align with Nostr ecosystem standards.