If you discover a security vulnerability in the Sovereign Network API Client, please report it responsibly:

1. DO NOT open a public GitHub issue
2. Email: security@sovereignnetwork.io
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if available)

We will respond within 48 hours and provide updates on remediation progress.

The Sovereign Network uses QUIC (UDP port 9334) for all backend communication:

• Post-Quantum Cryptography: CRYSTALS-Kyber512 for key encapsulation, CRYSTALS-Dilithium2 for signatures
• TLS 1.3 Mandatory: All QUIC connections enforce TLS 1.3
• HTTP/3 Compatibility: HTTP requests converted to ZHTP protocol over QUIC

Important: This TypeScript client uses standard fetch() API, which requires:

1. Browser: HTTP-to-QUIC gateway on port 8000 (ZHTP backend on 9334)
2. React Native: Custom QUIC fetch adapter using platform-specific libraries
3. Electron: Same as browser (gateway required)

All identity IDs, DIDs, contract IDs, and parameters are validated before sending to backend:

- Identity IDs: 64-character hex strings
- DIDs: Format `did:zhtp:[hex64]`
- Contract IDs: Alphanumeric, hyphens, underscores only (no path traversal)
- Guardian IDs: 64-character hex strings
- Domain names: SSRF protection (rejects internal IPs)

Enhanced passphrase requirements for backup/recovery operations:

- Minimum length: 16 characters (increased from 12)
- Minimum entropy: 60 bits
- Complexity requirement: 3 of 4 character types (upper, lower, numbers, symbols)
- Weak pattern detection: Rejects common passwords and sequences

All errors are sanitized before logging to prevent credential leakage:

- Passphrases, tokens, keys, seeds automatically redacted
- Debug logs sanitize error messages
- JSON bodies scrubbed of sensitive fields

Client-side rate limiting protects against brute force:

- Login: 5 attempts per 5 minutes per identity
- Sign-in: 5 attempts per 5 minutes per DID
- Backup import: 3 attempts per hour (global)

Responses validated before parsing:

- Rejects non-JSON responses
- Prevents content-type confusion attacks

Per-operation timeout configuration:

- Default: 10 seconds
- Configurable per request
- Prevents hanging connections

All query parameters use URLSearchParams:

- Automatic encoding
- Injection prevention
- Consistent parameter handling

Electron IPC responses validated:

- Structure validation
- Type checking
- URL format validation

❌ DON'T:

console.log('Login attempt:', { password, seedPhrase });

✅ DO:

// Errors are automatically sanitized
if (config.debugMode) {
  console.log('Login attempt for user:', userId);
}

Seed phrases are returned only once during signup:

const identity = await api.signup(request);
// identity.seedPhrases ONLY available immediately after signup
// Store in secure encrypted storage immediately
// DO NOT log, cache unencrypted, or transmit over insecure channels

Secure storage options:

• Browser: IndexedDB with Web Crypto API encryption
• React Native: react-native-encrypted-storage or Keychain/Keystore
• Electron: electron-store with encryption or OS keychain

The library enforces strong passphrases, but educate users:

✅ Good: "Correct-Horse-Battery-Staple-2024!"
❌ Bad: "password123456"

For production React Native apps:

import { ZhtpApi } from '@sovereign-network/api-client/react-native';

// Pin ZHTP node certificates
const pinnedCerts = ['sha256/AAAAAAA...'];
const api = new ZhtpApi(configProvider, customFetchWithPinning);

Session tokens are bearer tokens - protect them:

- Store in HTTP-only cookies (browser) or secure storage (mobile)
- Never expose in URLs or localStorage
- Implement token refresh mechanism
- Clear on logout

Client-side rate limiting is not sufficient:

// Backend MUST implement server-side rate limiting
// Client-side limiting only provides UX feedback

Even with input validation, sanitize on backend:

// Client validates format
validateDid(did);

// Backend MUST re-validate and sanitize

The library does not cryptographically sign requests. For sensitive operations:

// Implement request signing in your application
const signature = await signRequest(payload, privateKey);
await api.sendWalletPayment({ ...payload, signature });

All validation in this library is client-side. The backend MUST:

• Re-validate all inputs
• Implement authorization checks
• Rate limit requests
• Log security events

The library does not handle:

• Session expiration
• Token refresh
• Multi-device session management

Applications must implement these features.

For browser environments, implement CSRF protection:

// Add CSRF token to state-changing requests
headers: {
  'X-CSRF-Token': csrfToken,
}

Applications should configure security headers:

Content-Security-Policy: default-src 'self'
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
Permissions-Policy: geolocation=(), microphone=(), camera=()

1. Always use HTTPS in production
2. Never log passphrases, seed phrases, or session tokens
3. Store sensitive data encrypted
4. Implement proper session management
5. Use certificate pinning for mobile apps
6. Implement server-side validation and authorization
7. Rate limit on both client and server
8. Monitor for suspicious activity
9. Keep dependencies updated (npm audit regularly)
10. Follow principle of least privilege

1. Use strong, unique passphrases (16+ characters)
2. Write down seed phrases and store offline
3. Never share seed phrases or passphrases
4. Enable biometric authentication when available
5. Verify application authenticity before use
6. Keep software updated
7. Use hardware security keys when possible

# Run all tests including security tests
npm test

# Run only security tests
npm test -- --grep "security"

# Check for vulnerabilities
npm audit

# Type check
npm run type-check

• Input validation works for all ID formats
• Rate limiting triggers after configured attempts
• Weak passphrases are rejected
• Errors do not leak credentials in debug mode
• Session tokens not exposed in logs
• QUIC connection works (or gateway configured)
• Certificate pinning works (mobile)
• Config validation prevents malicious IPC data (Electron)

• Data Minimization: Library does not collect telemetry
• Right to Erasure: Applications must handle identity deletion
• Data Portability: Backup export provides encrypted data portability

• Encryption: TLS 1.3 mandatory via QUIC
• Tokenization: Applications must implement wallet address tokenization
• Audit Logging: Applications must log financial transactions

• Access Control: Applications must implement authorization
• Logging: Applications must log security events
• Incident Response: Follow responsible disclosure process

Critical Fixes:

• P0-1: Error sanitization prevents credential logging
• P0-2: Comprehensive input validation for all ID parameters
• P1-2: Enhanced passphrase requirements (16 chars, 60 bits entropy)

High Priority Fixes:

• P2-1: Client-side rate limiting for authentication
• P2-4: Content-Type validation prevents response confusion
• P2-5: Secure URL construction prevents injection
• P2-6: Electron IPC config validation

Medium Priority Fixes:

• P2-2: Configurable timeouts per operation
• P2-8: Updated vulnerable dependencies (js-yaml, semantic-release)

Enhancements:

• Added QUIC architecture documentation
• Security utilities module for validation/sanitization
• Comprehensive security testing suite

• Basic input validation
• HTTP transport (deprecated - now QUIC)
• Session token management
• Retry logic with exponential backoff

• OWASP Top 10
• CWE Top 25
• QUIC Protocol
• Post-Quantum Cryptography
• React Native Security
• Electron Security

• Security Issues: security@sovereignnetwork.io
• General Support: support@sovereignnetwork.io
• Documentation: https://docs.sovereignnetwork.io
• GitHub: https://github.com/SOVEREIGN-NET/Sovereign-Network-API-Client

Last Updated: December 5, 2025 Security Assessment: Comprehensive security audit completed December 2025