Refactored code by breaking the main.c up into BUD files.
This commit is contained in:
Your Name
252
AUTH_API.md
252
AUTH_API.md
@@ -49,27 +49,57 @@ The nostr_core_lib unified request validation system provides a comprehensive au
|
||||
└──────┬──────┘ ║ Structure (~100μs)║ │
|
||||
│Yes ╚═══════════════════╝ │
|
||||
▼ │
|
||||
┌─────────────────┐ ╔═══════════════════╗ │
|
||||
│ ECDSA Signature │No ║ REJECT: Invalid ║ │
|
||||
│ Verify (~2ms) ├──►║ Signature (~2ms) ║ │
|
||||
└─────────┬───────┘ ╚═══════════════════╝ │
|
||||
│Yes │
|
||||
▼ │
|
||||
┌─────────────────┐ ╔═══════════════════╗ │
|
||||
│Operation Match? │No ║ REJECT: Unauth. ║ |
|
||||
└─────────┬───────┘ ║ Operation (~200μs)║ │
|
||||
│Yes ╚═══════════════════╝ │
|
||||
▼ │
|
||||
┌─────────────┐ ╔═══════════════════╗ │
|
||||
│Event Kind? │ ║ ║ │
|
||||
└──────┬──────┘ ║ DUAL AUTH MODES ║ │
|
||||
│ ╚═══════════════════╝ │
|
||||
▼ │
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ Kind │ │ Kind │ │ Other │ │ Invalid │
|
||||
│ 22242 │ │ 24242 │ │ Kinds │ │ Kind │
|
||||
│ (NIP-42) │ │(Blossom) │ │ (Skip) │ │(Reject) │
|
||||
└─────┬────┘ └─────┬────┘ └─────┬────┘ └─────┬────┘
|
||||
│ │ │ │
|
||||
▼ │ ▼ ▼
|
||||
┌──────────┐ │ ┌──────────┐ ╔═══════════════════╗
|
||||
│ NIP-42 │ │ │ Skip │ ║ REJECT: Invalid ║
|
||||
│Challenge │ │ │ Nostr │ ║ Event Kind ║
|
||||
│Validate │ │ │Validate │ ╚═══════════════════╝
|
||||
│(~500μs) │ │ └─────┬────┘ │
|
||||
└─────┬────┘ │ │ │
|
||||
│ │ ▼ │
|
||||
│ │ ┌──────────┐ │
|
||||
│ │ │ Extract │ │
|
||||
│ │ │ Context │ │
|
||||
│ │ └─────┬────┘ │
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌────────────────────────────────────────────────────────────┐
|
||||
│ ECDSA SIGNATURE VERIFICATION │
|
||||
│ (~2ms) │
|
||||
└───────────────────────────┬────────────────────────────────┘
|
||||
│Yes
|
||||
▼ │
|
||||
┌─────────────────┐ ╔═══════════════════╗
|
||||
│Operation Match? │No ║ REJECT: Unauth. ║
|
||||
│(Kind 24242 only)├──►║ Operation (~200μs)║
|
||||
└─────────┬───────┘ ╚═══════════════════╝
|
||||
│Yes/Skip(Kind 22242)
|
||||
▼ │
|
||||
┌─────────────────┐ ╔═══════════════════╗ │
|
||||
│Event Expired? │Yes║ REJECT: Expired ║ │
|
||||
└─────────┬───────┘ ║ Event (~50μs) ║ │
|
||||
│No ╚═══════════════════╝ │
|
||||
▼ │
|
||||
│No ╚═══════════════════╝ │
|
||||
▼ │
|
||||
┌─────────────────┐ │
|
||||
│Extract Pubkey │ │
|
||||
│& Auth Context │ │
|
||||
└─────────┬───────┘ │
|
||||
│ │
|
||||
▼◄───────────────────────────────────────┘
|
||||
│ │
|
||||
▼◄───────────────────────────────────────┘
|
||||
┌─────────────────┐ ╔═══════════════════╗
|
||||
│Auth Rules │ No ║ ALLOW: Rules ║
|
||||
│Enabled? ├────►║ Disabled ║
|
||||
@@ -154,6 +184,100 @@ The nostr_core_lib unified request validation system provides a comprehensive au
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### Authentication Flow (Mermaid)
|
||||
|
||||
```mermaid
|
||||
|
||||
flowchart TD
|
||||
A[Request Received] --> B{Input Valid?}
|
||||
B -->|No| R1[REJECT: Invalid Input ~1μs]
|
||||
B -->|Yes| C{System Init?}
|
||||
C -->|No| R2[REJECT: Not Initialized]
|
||||
C -->|Yes| D{Auth Header?}
|
||||
D -->|No| SKIP[Skip Nostr Validation]
|
||||
D -->|Yes| E{Valid Base64?}
|
||||
E -->|No| R3[REJECT: Malformed Header ~10μs]
|
||||
E -->|Yes| F{Valid JSON?}
|
||||
F -->|No| R4[REJECT: Invalid JSON ~50μs]
|
||||
F -->|Yes| G{Valid Struct?}
|
||||
G -->|No| R5[REJECT: Invalid Structure ~100μs]
|
||||
G -->|Yes| H{Event Kind?}
|
||||
|
||||
%% Event Kind Branching
|
||||
H --> I[Kind 22242<br/>NIP-42]
|
||||
H --> J[Kind 24242<br/>Blossom]
|
||||
H --> K[Other Kinds<br/>Skip]
|
||||
H --> L[Invalid Kind]
|
||||
L --> R6[REJECT: Invalid Event Kind]
|
||||
|
||||
%% NIP-42 Path
|
||||
I --> M[NIP-42 Challenge<br/>Validation ~500μs]
|
||||
M --> N[ECDSA Signature<br/>Verification ~2ms]
|
||||
|
||||
%% Blossom Path
|
||||
J --> N
|
||||
|
||||
%% Skip Path
|
||||
K --> SKIP
|
||||
SKIP --> O[Extract Context]
|
||||
O --> N
|
||||
|
||||
%% Signature Verification
|
||||
N -->|No| R7[REJECT: Invalid Signature ~2ms]
|
||||
N -->|Yes| P{Operation Match?<br/>Kind 24242 only}
|
||||
P -->|No| R8[REJECT: Unauthorized Operation ~200μs]
|
||||
P -->|Yes/Skip 22242| Q{Event Expired?}
|
||||
Q -->|Yes| R9[REJECT: Expired Event ~50μs]
|
||||
Q -->|No| S[Extract Pubkey & Auth Context]
|
||||
|
||||
%% Rules Engine
|
||||
S --> T{Auth Rules Enabled?}
|
||||
T -->|No| ALLOW1[ALLOW: Rules Disabled]
|
||||
T -->|Yes| U[Generate Cache Key SHA-256]
|
||||
U --> V{Cache Hit?}
|
||||
V -->|Yes| CACHED[RETURN: Cached Decision ~100μs]
|
||||
V -->|No| W[RULE EVALUATION ENGINE<br/>Priority Order]
|
||||
|
||||
%% Rule Checks
|
||||
W --> X1{1. Pubkey Blacklisted?}
|
||||
X1 -->|Yes| DENY1[DENY: Pubkey Blocked]
|
||||
X1 -->|No| X2{2. Hash Blacklisted?}
|
||||
X2 -->|Yes| DENY2[DENY: Hash Blocked]
|
||||
X2 -->|No| X3{3. MIME Blacklisted?}
|
||||
X3 -->|Yes| DENY3[DENY: MIME Blocked]
|
||||
X3 -->|No| X4{4. Size Limit Exceeded?}
|
||||
X4 -->|Yes| DENY4[DENY: File Too Large]
|
||||
X4 -->|No| X5{5. Pubkey Whitelisted?}
|
||||
X5 -->|Yes| ALLOW2[ALLOW: Pubkey Whitelisted]
|
||||
X5 -->|No| X6{6. MIME Whitelisted?}
|
||||
X6 -->|Yes| ALLOW3[ALLOW: MIME Whitelisted]
|
||||
X6 -->|No| X7{Whitelist Rules Exist?}
|
||||
X7 -->|Yes| DENY5[DENY: Not in Whitelist]
|
||||
X7 -->|No| ALLOW4[ALLOW: Default Policy]
|
||||
|
||||
%% Final Steps
|
||||
ALLOW2 --> CACHE[Cache Decision 5min TTL]
|
||||
ALLOW3 --> CACHE
|
||||
ALLOW4 --> CACHE
|
||||
DENY1 --> CACHE
|
||||
DENY2 --> CACHE
|
||||
DENY3 --> CACHE
|
||||
DENY4 --> CACHE
|
||||
DENY5 --> CACHE
|
||||
CACHE --> RESULT[Return Result to Application]
|
||||
|
||||
%% Styling
|
||||
classDef rejectBox fill:#ff4444,stroke:#ffffff,color:#ffffff
|
||||
classDef allowBox fill:#44ff44,stroke:#ffffff,color:#000000
|
||||
classDef processBox fill:#4444ff,stroke:#ffffff,color:#ffffff
|
||||
classDef decisionBox fill:#ffff44,stroke:#000000,color:#000000
|
||||
|
||||
class R1,R2,R3,R4,R5,R6,R7,R8,R9,DENY1,DENY2,DENY3,DENY4,DENY5 rejectBox
|
||||
class ALLOW1,ALLOW2,ALLOW3,ALLOW4,CACHED allowBox
|
||||
class A,M,N,S,U,W,CACHE,RESULT,SKIP,O processBox
|
||||
class B,C,D,E,F,G,H,P,Q,T,V,X1,X2,X3,X4,X5,X6,X7 decisionBox
|
||||
```
|
||||
|
||||
### Performance Timeline (ASCII)
|
||||
|
||||
```
|
||||
@@ -186,6 +310,62 @@ Worst Case (Full Validation) - Total: ~2.7ms
|
||||
(Multiple DB Queries)
|
||||
```
|
||||
|
||||
### Dual Authentication Architecture
|
||||
|
||||
The system supports **two authentication modes** that can work independently or together:
|
||||
|
||||
#### **NIP-42 Authentication (Kind 22242)**
|
||||
- **Purpose**: Client identity authentication ("who you are")
|
||||
- **Use Case**: Relay client authentication, WebSocket connections
|
||||
- **Event Structure**: Contains `relay` URL and `challenge` tags
|
||||
- **Flow**: Challenge/response pattern with relay-generated challenges
|
||||
- **Validation**: Verifies client identity against relay URL and challenge
|
||||
- **Database Storage**: Client sessions and challenge tracking
|
||||
|
||||
#### **Blossom Protocol Authentication (Kind 24242)**
|
||||
- **Purpose**: Operation authorization ("what you can do")
|
||||
- **Use Case**: File upload/delete/list operations
|
||||
- **Event Structure**: Contains operation tag `t=upload|delete|list` and content hash `x=hash`
|
||||
- **Flow**: Direct operation authorization with expiration
|
||||
- **Validation**: Verifies operation permissions and content integrity
|
||||
- **Database Storage**: Operation-specific authentication rules
|
||||
|
||||
#### **Integration Strategy**
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ NIP-42 Auth │ │ Blossom Auth │
|
||||
│ (Kind 22242) │ │ (Kind 24242) │
|
||||
│ │ │ │
|
||||
│ Client Identity │ │ Operation Perms │
|
||||
│ Challenge/Resp │ │ File Operations │
|
||||
└─────────┬───────┘ └─────────┬───────┘
|
||||
│ │
|
||||
└──────┬─────────┬─────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐
|
||||
│ Unified Rules │
|
||||
│ Engine │
|
||||
│ │
|
||||
│ • Pubkey Rules │
|
||||
│ • Hash Rules │
|
||||
│ • MIME Rules │
|
||||
│ • Size Limits │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
#### **Event Kind Processing**
|
||||
- **Kind 22242** (NIP-42): Validates against stored challenge + relay URL
|
||||
- **Kind 24242** (Blossom): Validates operation tags + content integrity
|
||||
- **Other Kinds**: Skip Nostr validation, proceed to rule evaluation
|
||||
- **Invalid Kind**: Reject immediately
|
||||
|
||||
#### **Dual Mode Benefits**
|
||||
- **Backwards Compatibility**: Existing Blossom clients continue working
|
||||
- **Enhanced Security**: NIP-42 provides cryptographic client identity
|
||||
- **Flexible Deployment**: Relays can require either or both methods
|
||||
- **Performance**: Separate validation paths optimize for each use case
|
||||
|
||||
### Request Processing Flow (DDoS-Optimized)
|
||||
|
||||
The authentication system is designed with **performance and DDoS protection** as primary concerns. Here's the exact order of operations:
|
||||
@@ -207,22 +387,34 @@ The authentication system is designed with **performance and DDoS protection** a
|
||||
|
||||
6. **Nostr Event Structure Validation** (lines 159-166)
|
||||
- Validate event has required fields (kind, pubkey, sig, etc.)
|
||||
- Check event kind is 24242 for Blossom operations
|
||||
- **Early exit**: Invalid structure rejected before expensive crypto operations
|
||||
|
||||
7. **Cryptographic Signature Verification** (lines 159-166)
|
||||
7. **Event Kind Routing** (NEW - Dual Authentication)
|
||||
- **Kind 22242** (NIP-42): Route to NIP-42 challenge validation
|
||||
- **Kind 24242** (Blossom): Route to Blossom operation validation
|
||||
- **Other Kinds**: Skip Nostr validation, proceed to rules
|
||||
- **Invalid Kind**: Reject immediately
|
||||
|
||||
8. **NIP-42 Challenge Validation** (Kind 22242 Only)
|
||||
- Validate `relay` tag matches configured relay URL
|
||||
- Verify `challenge` tag exists and matches stored challenge
|
||||
- Check challenge expiration and single-use constraints
|
||||
- **Performance**: ~500μs additional validation overhead
|
||||
|
||||
9. **Cryptographic Signature Verification** (Both Paths)
|
||||
- **Most CPU-intensive operation** - ECDSA signature verification
|
||||
- Validates event authenticity using secp256k1
|
||||
- **Early exit**: Invalid signatures rejected before database queries
|
||||
|
||||
8. **Operation-Specific Validation** (lines 169-178)
|
||||
- Verify event authorizes the requested operation (upload/delete/list)
|
||||
- Check required tags (t=operation, x=hash, expiration)
|
||||
- Validate timestamp and expiration
|
||||
- **Early exit**: Expired or mismatched events rejected
|
||||
10. **Operation-Specific Validation** (Kind 24242 Only)
|
||||
- Verify event authorizes the requested operation (upload/delete/list)
|
||||
- Check required tags (t=operation, x=hash, expiration)
|
||||
- Validate timestamp and expiration
|
||||
- **Early exit**: Expired or mismatched events rejected
|
||||
|
||||
9. **Public Key Extraction** (lines 181-184)
|
||||
- Extract validated public key from event for rule evaluation
|
||||
11. **Public Key Extraction** (Both Paths)
|
||||
- Extract validated public key from event for rule evaluation
|
||||
- Store authentication context (NIP-42 vs Blossom) for rule processing
|
||||
|
||||
#### Phase 3: Authentication Rules (Database Queries)
|
||||
10. **Rules System Check** (line 191)
|
||||
@@ -419,6 +611,7 @@ CREATE TABLE auth_rules_[APP_ID] (
|
||||
|
||||
The system uses specific error codes for different failure scenarios:
|
||||
|
||||
### Authentication Rule Errors
|
||||
- **-50**: `NOSTR_AUTH_ERROR_INVALID_EVENT` - Malformed Nostr event
|
||||
- **-51**: `NOSTR_AUTH_ERROR_INVALID_SIGNATURE` - Invalid event signature
|
||||
- **-52**: `NOSTR_AUTH_ERROR_PUBKEY_BLOCKED` - Public key is blacklisted
|
||||
@@ -426,6 +619,17 @@ The system uses specific error codes for different failure scenarios:
|
||||
- **-54**: `NOSTR_AUTH_ERROR_MIME_RESTRICTED` - MIME type not allowed
|
||||
- **-55**: `NOSTR_AUTH_ERROR_SIZE_EXCEEDED` - File size limit exceeded
|
||||
|
||||
### NIP-42 Specific Errors
|
||||
- **-200**: `NIP42_ERROR_INVALID_RELAY_URL` - Relay URL mismatch or missing
|
||||
- **-201**: `NIP42_ERROR_INVALID_CHALLENGE` - Challenge missing or malformed
|
||||
- **-202**: `NIP42_ERROR_CHALLENGE_EXPIRED` - Challenge has expired
|
||||
- **-203**: `NIP42_ERROR_CHALLENGE_USED` - Challenge already consumed
|
||||
- **-204**: `NIP42_ERROR_CHALLENGE_NOT_FOUND` - Challenge not found in storage
|
||||
- **-205**: `NIP42_ERROR_WRONG_EVENT_KIND` - Expected kind 22242 for NIP-42
|
||||
- **-206**: `NIP42_ERROR_MISSING_TAGS` - Required relay or challenge tags missing
|
||||
- **-207**: `NIP42_ERROR_URL_NORMALIZATION` - Failed to normalize relay URL
|
||||
- **-208**: `NIP42_ERROR_VALIDATION_FAILED` - General NIP-42 validation failure
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Validation
|
||||
|
||||
Reference in New Issue
Block a user