diff --git a/.media/domain.png b/.media/domain.png new file mode 100644 index 0000000..510e9b5 Binary files /dev/null and b/.media/domain.png differ diff --git a/.media/ipv4.png b/.media/ipv4.png new file mode 100644 index 0000000..5adcd23 Binary files /dev/null and b/.media/ipv4.png differ diff --git a/LICENSE b/LICENSE index 76d55b3..ba30d28 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023 Ryan Walters +Copyright (c) 2025 Ryan Walters Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 0076031..5fbcaac 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,203 @@ # rdap -A private RDAP query client built with React & Next.js. +[![Version][badge-version]][npm] +[![License][badge-license]][license] +[![CI][badge-ci]][ci-workflow] +[![Codecov][badge-codecov]][codecov] +[![TypeScript][badge-typescript]][typescript] +[![Next.js][badge-nextjs]][nextjs] +[![React][badge-react]][react] -## Usage +[badge-version]: https://img.shields.io/badge/version-0.2.0-blue +[badge-license]: https://img.shields.io/badge/license-MIT-green +[badge-ci]: https://github.com/Xevion/rdap/actions/workflows/ci.yml/badge.svg +[badge-codecov]: https://codecov.io/gh/Xevion/rdap/branch/master/graph/badge.svg +[badge-typescript]: https://img.shields.io/badge/TypeScript-5.9-blue +[badge-nextjs]: https://img.shields.io/badge/Next.js-15.5-black +[badge-react]: https://img.shields.io/badge/React-19.2-blue -This project uses [Next.js][nextjs] (SSG only) and React. Install [Node.js][nodejs] and [Yarn][yarn], then run the following commands: +A modern RDAP query client built with Next.js and React. Query domains, IP addresses, ASNs, and more. Now with **dark mode**. -```bash -# install dependencies -yarn -# run the development server -yarn dev -# or build and run the production server -yarn build && yarn start -``` +[![Domain query screenshot](.media/domain.png)][live-demo] +[![IPv4 query screenshot](.media/ipv4.png)][live-demo] -The project is also hosted on [my website][rdap]. +> [!TIP] +> **Try the live demo at [rdap.xevion.dev][live-demo]** to query domains, IPs, ASNs, and more in real-time. + +## What is RDAP? + +RDAP (Registration Data Access Protocol) is the modern successor to WHOIS, providing structured, machine-readable access to domain registration and network resource data. Instead of parsing inconsistent text output, RDAP delivers standardized JSON responses with richer metadata. ## Why? -Built for personal use, this project is an RDAP client; a tool that lets you execute RDAP queries on any entities that are associated with an RDAP server. -In more simpler terms, it's a tool that lets you look up information about IP addresses, domain names, and autonomous systems (a network of controlled IP addresses), and a little more. +The tool hosted by [rdap.org][rdap-client] is fantastic, but it's too simple, and isn't as overly-complicated and annoying as I want it to be. So, I built my own. **Mine has dark mode.** -The tool hosted by [rdap.org](https://client.rdap.org) is fantastic, but it's too simple, and isn't as overly-complicated and annoying as I want it to be. So, I built my own. Mine has dark mode. +Inspired by the [rdap.org client][rdap-client], this project adds several features I wanted: -But in all seriousness, my project does intend to have more features: +- **🌙 Dark Mode**: Because the blistering white of other RDAP clients is painful to look at +- **🔗 Shareable Links**: Every query generates a unique URL you can bookmark or share +- **🎨 Modern Interface**: Intuitive type detection, status badges, and responsive design +- **📊 Rich Data Display**: Comprehensive support for all RDAP entity types, DNSSEC, JSContact, vCard, and more +- **⚡ Advanced Features**: Follow referrals to registrars, modern JSContact format support, export/copy JSON responses +- **🏠 Self-Hostable**: Static site that you can deploy anywhere for complete control -- Proxying: Some RDAP servers are inaccessible over the browser, and so proxying requests through a server is necessary. -- Self Hosting: For those worried about privacy, the project can be self-hosted. -- No Tracking: The project can't track you, because it's a static site. And in terms of the proxy, you can self-host if you're worried about that. -- Better UI: I'm not a designer, but I can try. -- Dark Mode: The blistering white of the original RDAP client is painful to look at. -- Shareable Links: Each search produces a unique URL that can be shared with others to view the same query. -- Whois: RDAP is a newer protocol that is meant to replace Whois, but some servers still use Whois. I might add support for that. -- Punycode: Some domain names use punycode, which is a way to represent Unicode characters in ASCII. I might add support for working with these domains. -- Better Error Handling: The original RDAP client doesn't handle errors very well, or tell you what went wrong. I want to fix that. - - For example, when querying a TLD that does not have a RDAP server, or one that does not exist, the original client doesn't explain this very well. -- RDAP Schema Adherence: RDAP servers are supposed to follow a schema, but it appears a large number simply don't. I intend to provide handling for this. - - Essentially, two separate schemas will be available: one for basic type checking, and one for the RFC-compliant schema. - - If the server doesn't follow the RFC-compliant schema, the basic schema will be used instead. - - It's hard to tell at this moment if Typescript can handle this well, but I'll try. +## Features -[rdap]: https://rdap.xevion.dev -[nextjs]: https://nextjs.org +### Query Capabilities + +- **Multiple Input Types**: IPv4/IPv6 (with CIDR notation), domain names, TLDs, ASNs, entity handles, or raw RDAP URLs +- **Smart Auto-Detection**: Automatically identifies query types with visual feedback +- **Manual Override**: Lock query type when auto-detection isn't enough +- **Follow Referrals**: Automatically follows redirects to registrar RDAP servers for complete data +- **JSContact Support**: Modern JSContact (RFC 9553) format alongside traditional vCard + +### Supported Entity Types + +Full rendering support for all RDAP object classes: + +- **Domains**: Name, status, nameservers, DNSSEC, registrar info, creation/expiry dates +- **IP Networks**: IPv4/IPv6 ranges, allocation dates, network types, parent/child relationships +- **Autonomous Systems**: AS numbers, names, registration details +- **Entities**: Contacts, registrars, registrants with role information and public IDs +- **Nameservers**: Hostnames with IPv4/IPv6 address mappings + +### Contact Information + +- **Dual Format Support**: Both legacy vCard (jCard) and modern JSContact (RFC 9553) +- **Rich Contact Data**: Names, organizations, emails, phone numbers, addresses, URLs, titles, and roles +- **Structured Display**: Clean presentation of hierarchical contact information + +### DNS Security (DNSSEC) + +- Zone signing and delegation status indicators +- DS (Delegation Signer) records with key tags, algorithms, digest types +- DNSKEY records with flags, protocols, and public keys +- Maximum signature lifetime display + +### User Experience + +- **🎨 Theme Toggle**: Full dark mode and light mode support with persistence +- **📋 Data Export**: Copy individual values, entire JSON responses, or download as files +- **🔍 Raw View Toggle**: Switch between formatted display and raw JSON +- **📊 Status Badges**: Interactive badges for 28+ RDAP status types with hover definitions +- **⏱️ Relative Timestamps**: Human-readable event times with precise date fallback +- **📱 Responsive Design**: Mobile-first layout that adapts from phone to desktop + +### Error Handling & Validation + +- **Comprehensive HTTP Error Messages**: Clear explanations for 302, 400, 403, 404, 500 responses +- **Input Validation**: Type checking with helpful warnings when manual type doesn't match input +- **Schema Validation**: Zod-based validation with readable error messages +- **Bootstrap Integration**: Automatic IANA registry bootstrap for URL resolution + +### Technical Details + +- **Registry Bootstrap**: Automatic fetching from IANA bootstrap files (DNS, IPv4, IPv6, ASN, object tags) +- **CIDR Matching**: Proper network range matching for IP lookups +- **Internationalization**: Full Unicode domain name support +- **Type Safety**: Comprehensive TypeScript types inferred from Zod schemas +- **Static Site**: No backend required for basic usage, fully client-side queries + +## Installation & Usage + +This project uses [pnpm][pnpm] as its package manager. Make sure you have [Node.js][nodejs] installed, then run: + +```bash +# Install dependencies +pnpm install + +# Run development server +pnpm dev + +# Build for production +pnpm build + +# Start production server +pnpm start +``` + +The development server will be available at `http://localhost:3000`. + +### Additional Commands + +```bash +# Run tests +pnpm test + +# Run tests with UI +pnpm test:ui + +# Type checking +pnpm type-check + +# Linting +pnpm lint +pnpm lint:fix + +# Code formatting +pnpm format +pnpm format:check +``` + +## Tech Stack + +- **[Next.js 15][nextjs]**: React framework with static site generation (SSG only) +- **[React 19][react]**: UI library with modern hooks +- **[TypeScript 5.9][typescript]**: Type-safe development +- **[Radix UI Themes][radix]**: Accessible component primitives and design system +- **[Tailwind CSS 4][tailwind]**: Utility-first styling +- **[Zod 4][zod]**: Runtime schema validation +- **[Vitest][vitest]**: Fast unit testing framework +- **[next-themes][next-themes]**: Theme management + +## Self-Hosting + +This is a **fully static site** with no backend required for basic usage. It generates all HTML at build time and queries RDAP servers directly from your browser. + +**Key characteristics**: + +- ✅ All RDAP queries made directly from your browser to source servers +- ✅ No intermediary servers logging your lookups +- ✅ Minimal local storage (theme preference only) +- ✅ Fully self-hostable for complete control + +**Note on CORS**: Some RDAP servers don't enable CORS headers, preventing direct browser access. For these servers, you'll see an error. Future versions may include an optional proxy for these cases. + +To self-host: + +```bash +# Build the static site +pnpm build +``` + +## Contributing + +Issues and pull requests are welcome! This project uses: + +- **ESLint** for linting +- **Prettier** for code formatting +- **Husky** for git hooks +- **Conventional Commits** for commit messages + +## License + +[MIT License][license] © 2025 Ryan Walters + + + +[live-demo]: https://rdap.xevion.dev +[rdap-client]: https://client.rdap.org +[ci-workflow]: https://github.com/Xevion/rdap/actions/workflows/ci.yml +[codecov]: https://codecov.io/gh/Xevion/rdap +[pnpm]: https://pnpm.io/ [nodejs]: https://nodejs.org -[yarn]: https://yarnpkg.com +[nextjs]: https://nextjs.org +[react]: https://react.dev +[typescript]: https://www.typescriptlang.org +[radix]: https://www.radix-ui.com +[tailwind]: https://tailwindcss.com +[zod]: https://zod.dev +[vitest]: https://vitest.dev +[next-themes]: https://github.com/pacocoursey/next-themes +[license]: LICENSE +[npm]: https://www.npmjs.com/package/rdap