Unified, Secure, High-Performance RDAP Client — TypeScript (archived)
[](https://www.npmjs.com/package/rdapify) [](https://www.npmjs.com/package/rdapify) [](LICENSE) [](https://github.com/rdapify/RDAPify/actions/workflows/ci.yml) [](https://codecov.io/gh/rdapify/RDAPify) [](https://www.typescriptlang.org/) [](https://github.com/rdapify/RDAPify/blob/main/CHANGELOG.md) [](SECURITY.md) [](https://rdapify.com) [](https://github.com/rdapify/RDAPify) > **Alpha software** > > RDAPify is under active development. Core functionality (RDAP queries, caching, SSRF protection) is stable and tested, but APIs and interfaces may change before v1.0. We welcome [issues](https://github.com/rdapify/RDAPify/issues) and [feedback](https://github.com/rdapify/RDAPify/discussions) from the community while the project evolves. **RDAPify** unifies RDAP queries across all global registries (Verisign, ARIN, RIPE, APNIC, LACNIC) with robust security protection, exceptional performance, and an integrated developer experience. This isn't just another RDAP client — it's a complete platform for processing registration data securely. > **Note:** This project eliminates the need for traditional WHOIS protocol, while maintaining backward compatibility when needed. ## 🚀 Why RDAPify? Direct RDAP queries are complex — each registry uses different formats, rate limits, and security procedures. Instead of reinventing the wheel for every project: ```diff - Maintaining multiple WHOIS/RDAP implementations - Manually handling registry differences - Constant worry about SSRF vulnerabilities - Unpredictable performance without caching + One unified solution, rigorously tested, open source ``` RDAPify intelligently addresses these challenges: - ✅ **Data Normalization**: Consistent response regardless of source registry - ✅ **SSRF Protection**: Prevent attacks on internal infrastructure - ✅ **Exceptional Performance**: Smart caching, parallel processing, memory optimization - ✅ **Node.js Compatibility**: Verified working on Node.js 20+; Bun, Deno, and Cloudflare Workers also supported - ✅ **GDPR-ready**: Built-in tools for automatically redacting personal data ## 📦 Quick Installation ```bash # Using npm npm install rdapify # Using yarn yarn add rdapify # Using pnpm pnpm add rdapify ``` ```bash # Using Bun bun add rdapify ``` ## Compatibility | rdapify | @rdapify/pro | rdapify-nd | rdapify-py | |---------|-------------|------------|------------| | 0.4.x | 0.4.x | 0.4.x | 0.4.x | | 0.3.x | 0.2.x | 0.1.x | 0.2.x | **MSRV (Rust):** 1.77 — applies to `rdapify-nd`, `rdapify-py`, and `@rdapify/pro` ## ⚡ Get Started in 30 Seconds ### Basic Usage ```typescript import { RDAPClient } from 'rdapify'; // Create a client with default settings const client = new RDAPClient(); // Query a domain const result = await client.domain('example.com'); console.log({ domain: result.query, registrar: result.registrar?.name, status: result.status, nameservers: result.nameservers, created: result.events.find((e) => e.eventAction === 'registration')?.eventDate, expires: result.events.find((e) => e.eventAction === 'expiration')?.eventDate, }); ``` ### With Security & Performance Options ```typescript import { RDAPClient } from 'rdapify'; // Create a secure client with optimized defaults const client = new RDAPClient({ cache: true, // In-memory LRU cache (1 hour TTL) privacy: true, // Automatic PII redaction (GDPR/CCPA) retry: { maxAttempts: 3, backoff: 'exponential', }, }); // Query domain, IP, ASN, nameserver, or entity const domain = await client.domain('example.com'); const ip = await client.ip('8.8.8.8'); const asn = await client.asn('AS15169'); const ns = await client.nameserver('ns1.example.com'); const entity = await client.entity('ARIN-HN-1', 'https://rdap.arin.net/registry'); ``` **Example Output:** ```json { "query": "example.com", "registrar": "Internet Assigned Numbers Authority", "status": ["clientDeleteProhibited", "clientTransferProhibited", "clientUpdateProhibited"], "nameservers": ["a.iana-servers.net", "b.iana-servers.net"], "created": "1995-08-14T04:00:00Z", "expires": "2026-08-13T04:00:00Z" } ``` ### With Nameserver & Entity Queries (v0.1.7+) ```typescript import { RDAPClient } from 'rdapify'; const client = new RDAPClient(); // Query a nameserver — auto-discovers server via IANA DNS bootstrap const ns = await client.nameserver('ns1.example.com'); console.log(ns.ldhName); // "ns1.example.com" console.log(ns.ipAddresses); // { v4: ['93.184.216.34'], v6: [...] } console.log(ns.status); // ['active'] // Query an entity — requires explicit server URL (no global IANA bootstrap) const entity = await client.entity('ARIN-HN-1', 'https://rdap.arin.net/registry'); console.log(entity.handle); // "ARIN-HN-1" console.log(entity.roles); // ['registrar', 'technical'] ``` ### With Monitoring & Metrics (v0.1.2+) ```typescript import { RDAPClient } from 'rdapify'; // Create client with monitoring enabled const client = new RDAPClient({ cache: true, logging: { level: 'info', // debug, info, warn, error enabled: true, }, }); // Perform queries await client.domain('example.com'); await client.ip('8.8.8.8'); // Get performance metrics const metrics = client.getMetrics(); console.log(`Success Rate: ${metrics.successRate}%`); console.log(`Avg Response Time: ${metrics.avgResponseTime}ms`); console.log(`Cache Hit Rate: ${metrics.cacheHitRate}%`); // Get connection pool statistics const poolStats = client.getConnectionPoolStats(); console.log(`Active Connections: ${poolStats.activeConnections}`); // Get recent logs const logs = client.getLogs(10); logs.forEach((log) => { console.log(`[${log.level}] ${log.message}`); }); // Clean up resources client.destroy(); ``` ### With Authentication & Proxy (v0.1.2+) ```typescript import { RDAPClient, AuthenticationManager, ProxyManager } from 'rdapify'; // Setup authentication const auth = new AuthenticationManager({ type: 'bearer', // 'basic' | 'bearer' | 'apiKey' | 'oauth2' token: 'your-api-token', }); // Setup proxy const proxy = new ProxyManager({ host: 'proxy.example.com', port: 8080, protocol: 'http', // 'http' | 'https' | 'socks4' | 'socks5' auth: { username: 'proxyuser', password: 'proxypass', }, }); // Add bypass patterns proxy.addBypass('*.internal.com'); // Use in your HTTP client configuration const headers = auth.getAuthHeaders(); const proxyUrl = proxy.shouldBypass('example.com') ? undefined : proxy.getProxyUrl(); ``` ### With Advanced Features (v0.1.2+) ```typescript import { RDAPClient, RetryStrategy, QueryPriorityQueue, PersistentCache, CompressionManager, } from 'rdapify'; // Setup retry strategy with circuit breaker const retry = new RetryStrategy({ strategy: 'exponential-jitter', maxAttempts: 5, circuitBreaker: { enabled: true, threshold: 3, timeout: 60000, }, }); // Setup priority queue const queue = new QueryPriorityQueue(5, async (domain) => { return await client.domain(domain); }); // Enqueue with priority await queue.enqueue('critical.com', 'high'); await queue.enqueue('normal.com', 'normal'); await queue.enqueue('background.com', 'low'); // Setup persistent cache const cache = new PersistentCache({ storage: 'file', path: './cache/rdap-cache.json', ttl: 3600000, // 1 hour autoSave: true, }); // Setup compression const compression = new CompressionManager({ enabled: true, types: ['br', 'gzip', 'deflate'], }); ``` ## 🌟 Core Features ### 🔒 Enterprise Security - **Built-in SSRF Protection**: Prevent queries to internal IP addresses or dangerous domains - **Certificate Validation**: Reject insecure connections to RDAP servers - **Rate Limiting**: Prevent service blocking due to excessive requests - **Secure Data Handling**: PII redaction according to GDPR/CCPA requirements - **Authentication Support** (v0.1.1+): Basic, Bearer Token, API Key, OAuth2 - **Proxy Support** (v0.1.1+): HTTP/HTTPS/SOCKS4/SOCKS5 with authentication - **Full Audit Trail**: Track all critical operations for compliance purposes ### ⚡ Exceptional Performance - **Smart Caching**: In-memory LRU cache with configurable TTL - **Persistent Cache** (v0.1.1+): File-based cache that survives restarts - **Connection Pooling** (v0.1.2+): HTTP connection reuse for 30-40% performance improvement - **Batch Processing**: Process multiple queries efficiently (5-10x faster) - **Response Compression** (v0.1.1+): gzip/brotli support for 60-80% bandwidth reduction - **Retry Strategies** (v0.1.1+): Circuit breaker with exponential backoff - **Query Prioritization** (v0.1.1+): High/normal/low priority queue - **Registry Discovery**: Automatic IANA Bootstrap for finding the correct registry - **Optimized Parsing**: Fast JSONPath-based normalization ### 📊 Monitoring & Observability (v0.1.2+) - **Metrics Collection**: Track query performance, success rates, and cache effectiveness - **Request/Response Logging**: Detailed logging with configurable levels (debug, info, warn, error) - **Performance Analysis**: Monitor response times, identify bottlenecks, and optimize queries - **Connection Pool Stats**: Track connection reuse and resource utilization - **Time-based Filtering**: Analyze metrics over specific time periods - **Export Capabilities**: Export metrics and logs for external analysis ### 🧩 Seamless Integration - **Full TypeScript Support**: Strongly typed with embedded documentation - **Node.js 20+ Support**: Verified working (Node.js, Bun, Deno, Cloudflare Workers) - **Enhanced Validation** (v0.1.1+): IDN domains, IPv6 zones, ASN ranges - **Nameserver & Entity Queries** (v0.1.7+): `client.nameserver()` and `client.entity()` with full RDAP support - **CLI Tool** (v0.1.7+): `rdapify domain/ip/asn/nameserver/entity` with `--json`, `--no-cache`, `--timeout`, `--server` flags - **Web Playground**: Try RDAPify live at [rdapify.com/playground](https://rdapify.com/playground) - **Pre-built Templates**: For AWS Lambda, Azure Functions, Kubernetes, and more (planned) ### 📊 Advanced Analytics (Planned) Future releases will include: - **Customizable Dashboards**: Track critical domains and assets - **Automated Reports**: Schedule expiration alerts and important changes - **Pattern Detection**: Identify suspicious registration behaviors or potential attacks - **Relationship Visualization**: Understand complex ownership and registration networks ## 🏗️ Core Architecture ```mermaid graph LR A[Application] --> B(RDAP Client) B --> C{Registry Discovery} C -->|IANA Bootstrap| D[(Cache Layer)] B --> E[Normalization] E -->|JSONPath| F[Raw Responses] F --> G[Unified Format] G --> H[PII Redaction] H --> I[Final Response] D -->|Prefetching| C style B fill:#4CAF50,stroke:#388E3C style D fill:#FF9800,stroke:#F57C00 style G fill:#2196F3,stroke:#0D47A1 ``` ## 🛡️ Security as a Core Principle We don't treat security as an add-on feature — it's fundamental to our design. RDAPify protects your applications from: | Threat | Protection Mechanism | Criticality | | -------------- | ---------------------------------------- | ------------ | | SSRF | Domain validation, blocking internal IPs | 🔴 Critical | | DoS | Rate limiting, timeouts | 🟠 Important | | Data Leaks | PII redaction, no raw response storage | 🔴 Critical | | MitM | Mandatory HTTPS, certificate validation | 🟠 Important | | Data Injection | Schema validation, strict parsing | 🟠 Important | Read our [Security Whitepaper](docs/security/whitepaper.md) for deeper technical details and advanced scenarios. ## 📚 Documentation RDAPify provides comprehensive documentation in the repository: - **[Getting Started](docs/getting_started/)** - Installation, quick start, and first query - **[API Reference](docs/api_reference/)** - Complete TypeScript API documentation - **[Core Concepts](docs/core_concepts/)** - RDAP fundamentals, architecture, and normalization - **[Security Guide](docs/security/)** - SSRF protection, PII redaction, and best practices - **[Guides](docs/guides/)** - Error handling, caching strategies, and performance optimization - **[Examples](examples/)** - Real-world code examples and use cases > **Tip**: Full API and guide documentation is available in the [`docs/`](docs/) directory. ## 🌐 Interactive Playground Try RDAPify directly in your browser — no installation required: **[rdapify.com/playground](https://rdapify.com/playground)** ## 📊 Performance Benchmarks Measured on the **native backend** (`rdapify-nd`, `cargo bench`, Criterion, Linux x86-64, mock HTTP server). TypeScript pipeline benchmarks are ~10-20× higher latency: | Scenario | Latency | |----------|---------| | Query — no cache (bootstrap + fetch + normalise) | ~180 µs | | Query — **cache hit** | **~2.3 µs** (~80× faster) | | Cache read (DashMap, fresh TTL) | ~124 ns | | SSRF URL validation | ~141–295 ns | > **With the native backend** (`npm install rdapify-nd`), the five core query methods > run inside compiled Rust rather than the TypeScript pipeline — lower per-call > overhead for high-throughput scenarios. > > ```ts > const client = new RDAPClient({ backend: 'auto' }); // uses rdapify-nd if installed > ``` ## 👥 Community & Support RDAPify is an open source project. Get help or contribute: ### 🐛 Bug Reports & Feature Requests - **[GitHub Issues](https://github.com/rdapify/RDAPify/issues)** - Report bugs or request features ### 💬 Questions & Discussions - **[GitHub Discussions](https://github.com/rdapify/RDAPify/discussions)** - Ask questions, share ideas, and show what you've built ### 📧 Direct Contact - **General inquiries**: contact@rdapify.com - **Security issues**: security@rdapify.com (see [SECURITY.md](SECURITY.md)) - **Support**: support@rdapify.com ### 🤝 Contributing - **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines - **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** - Community standards ## 🚧 Project Status **Current Release**: v0.3.0 (Alpha) ### 🎉 What's New in v0.3.0 **Streaming, Monitoring & Runtime Maturity** - ✅ **Streaming Batch API**: `client.streamBatch(queries[])` — `AsyncIterable