diff --git a/README.md b/README.md index e215bc4..1d044bb 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,136 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# VectorDNS + +DNS lookup, WHOIS, and domain monitoring tool. Search nameservers, check domain availability, and track DNS record changes over time. + +## Features + +- **DNS Record Lookup** — Query A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, and SRV records for any domain +- **WHOIS Lookup** — View registrar, registration/expiration dates, nameservers, and domain status +- **Domain Availability** — Check if a domain is registered or available via IANA RDAP +- **Domain Monitoring** — Save domains to a dashboard, track DNS changes over time, get alerts when records change +- **Change Detection** — Daily automated re-checks with visual diffs showing what changed +- **Notifications** — In-app notification feed + email alerts via Resend +- **Dark Mode** — Dark theme by default with light mode toggle + +## Tech Stack + +- **Framework**: Next.js 16 (App Router) + React 19 +- **Language**: TypeScript (strict mode) +- **Styling**: Tailwind CSS v4 + shadcn/ui +- **Auth & Database**: Supabase (auth, Postgres, RLS, realtime) +- **DNS**: Tangerine (DNS-over-HTTPS via Cloudflare/Google) +- **WHOIS**: whoiser (RDAP-based, free) +- **Email**: Resend +- **Deployment**: Vercel +- **Package Manager**: Bun ## Getting Started -First, run the development server: +### Prerequisites + +- [Bun](https://bun.sh) >= 1.3 +- A [Supabase](https://supabase.com) project (free tier works) +- (Optional) [Resend](https://resend.com) API key for email alerts + +### Setup ```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or +# Clone and install +git clone +cd vectordns +bun install + +# Configure environment +cp .env.local.example .env.local +# Fill in your Supabase URL, anon key, and other values + +# Run database migrations +# (see supabase/migrations/ once they exist) + +# Start dev server bun dev ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +Open [http://localhost:3000](http://localhost:3000) to see the app. -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. +### Environment Variables -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. +| Variable | Required | Description | +|---|---|---| +| `NEXT_PUBLIC_SUPABASE_URL` | Yes | Your Supabase project URL | +| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Yes | Supabase anonymous/public key | +| `SUPABASE_SERVICE_ROLE_KEY` | Yes | Service role key (for cron jobs) | +| `CRON_SECRET` | Yes | Secret to authenticate Vercel cron requests | +| `RESEND_API_KEY` | No | Resend API key for email notifications | -## Learn More +## Project Structure -To learn more about Next.js, take a look at the following resources: +``` +app/ + page.tsx # Landing page with search + layout.tsx # Root layout (theme, fonts, metadata) + globals.css # Tailwind v4 + shadcn/ui CSS vars + lookup/[domain]/page.tsx # DNS results page (public) + auth/ # Login, signup, OAuth callback + dashboard/ # Authenticated domain tracking + api/ + dns/lookup/ # DNS record lookup endpoint + whois/lookup/ # WHOIS lookup endpoint + availability/check/ # Domain availability endpoint + domains/ # Saved domains CRUD + cron/check-domains/ # Daily re-check (Vercel cron) + notifications/ # Notification endpoints +components/ + ui/ # shadcn/ui components + layout/ # Header, footer, sidebar + lookup/ # Search form, record displays + dashboard/ # Domain list, detail, diff views +lib/ + dns/ # Tangerine DNS service + whois/ # whoiser WHOIS service + availability/ # RDAP availability service + monitoring/ # Change detection + snapshot logic + notifications/ # Notification service + email/ # Resend email functions + supabase/ # Server/client/middleware clients + auth/ # Auth server actions + types/ # Shared TypeScript types +supabase/ + migrations/ # SQL schema + RLS policies +``` -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +## Current Status -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! +### Done -## Deploy on Vercel +- [x] Project scaffolding (Next.js 16, Tailwind v4, TypeScript) +- [x] shadcn/ui setup with dark mode (next-themes) +- [x] Landing page with domain search form -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +### TODO -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. +See [ROADMAP.md](./ROADMAP.md) for the full phased build plan. Next up: + +- [ ] TypeScript type definitions (`lib/types/`) +- [ ] Supabase schema + migrations + RLS +- [ ] DNS / WHOIS / availability service layers +- [ ] API routes for public lookups +- [ ] Supabase auth (GitHub, Google, email, magic link) +- [ ] DNS results page (`/lookup/[domain]`) +- [ ] Dashboard with domain tracking +- [ ] Change detection + daily cron +- [ ] Notifications (in-app + email) + +## Scripts + +```bash +bun dev # Start development server +bun run build # Production build +bun start # Start production server +bun lint # Run ESLint +bun test # Run integration tests +``` + +## License + +GPL-2.0 diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..13c9619 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,123 @@ +# VectorDNS Roadmap + +## Overview + +VectorDNS is a web-based DNS toolkit. Anyone can look up DNS records, WHOIS data, and domain availability without signing in. Authenticated users get a persistent dashboard to save domains, track DNS changes over time, and receive alerts when something changes. + +--- + +## Tech Stack + +| Layer | Choice | +|---|---| +| Framework | Next.js 16 (App Router) | +| Language | TypeScript (strict) | +| Styling | Tailwind CSS v4 + shadcn/ui | +| Auth & DB | Supabase (`@supabase/ssr`) | +| DNS Lookups | Tangerine (DNS-over-HTTPS) | +| WHOIS | whoiser (RDAP, free) | +| Availability | IANA RDAP API (free) | +| Email Alerts | Resend | +| Deployment | Vercel | +| Package Manager | Bun | + +--- + +## Phase 1 — Foundation + +Everything needed before any features can work. + +- [ ] **TypeScript types** — Define shared types for DNS records, WHOIS data, availability results, and database models (`lib/types/`) +- [ ] **Supabase schema** — Create migration files for all tables: `profiles`, `saved_domains`, `dns_history`, `availability_history`, `notifications`. Enable Row Level Security on every table. +- [ ] **Supabase client setup** — Server client, browser client, and middleware for session refresh (`lib/supabase/`). Use `@supabase/ssr` only (auth-helpers is deprecated). +- [ ] **Project config** — `.env.local.example` with all required env vars, `vercel.json` with cron schedule, typed env accessor (`lib/env.ts`) + +## Phase 2 — Core Services + +The backend logic that powers lookups. No UI yet — just service layers and API routes. + +- [ ] **DNS service** — Install `tangerine`. Create `lib/dns/` that queries all 9 record types (A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, SRV) via DNS-over-HTTPS. Returns structured results, never throws on missing records. +- [ ] **WHOIS service** — Install `whoiser`. Create `lib/whois/` that extracts registrar, dates, nameservers, status. Graceful error on unsupported TLDs. +- [ ] **Availability service** — Fetch `https://rdap.org/domain/{domain}`. 404 = available, 200 = registered. No API key needed. Create `lib/availability/`. +- [ ] **DNS lookup API** — `POST /api/dns/lookup` — public, rate-limited (30 req/min per IP) +- [ ] **WHOIS lookup API** — `POST /api/whois/lookup` — public, rate-limited (20 req/min per IP) +- [ ] **Availability check API** — `POST /api/availability/check` — public +- [ ] **Integration tests** for each API route (use `bun test`) + +## Phase 3 — Authentication + +- [ ] **Auth system** — Configure Supabase Auth with all 4 providers: GitHub OAuth, Google OAuth, email+password, magic link +- [ ] **Auth actions** — Server actions for sign in/out across all providers (`lib/auth/actions.ts`) +- [ ] **OAuth callback** — `app/auth/callback/route.ts` handles code exchange +- [ ] **Middleware** — Protect `/dashboard/*` routes, redirect unauthenticated users to login +- [ ] **Login/signup pages** — OAuth buttons, email form, magic link option + +## Phase 4 — Public UI + +Pages that work without an account. + +- [ ] **App shell** — Root layout with header (logo, nav, theme toggle, auth button), footer +- [ ] **Homepage** — *(done)* Hero, search form, feature cards +- [ ] **DNS results page** — `app/lookup/[domain]/page.tsx` — tabbed DNS records, WHOIS card, availability badge. Shareable URL. +- [ ] **Save to Dashboard button** — Shown to logged-in users on the results page + +## Phase 5 — Dashboard + +Authenticated features behind `/dashboard`. + +- [ ] **Dashboard layout** — Sidebar navigation, overview stats (saved count, recent changes, unread notifications) +- [ ] **Saved domains CRUD** — `GET/POST /api/domains`, `GET/PUT/DELETE /api/domains/[id]` +- [ ] **Domains list page** — Table/card grid of saved domains with add/delete/re-check actions +- [ ] **Domain detail page** — Tabbed view: current DNS records, DNS history timeline, change diff (old vs new), availability history, WHOIS data +- [ ] **Notes & tags** — Inline-editable notes (plain text) and tags (chip input) per domain, auto-saves on blur +- [ ] **Manual re-check** — `POST /api/domains/[id]/check` triggers fresh DNS/WHOIS/availability lookups and stores snapshots + +## Phase 6 — Monitoring & Alerts + +Automated change detection and notifications. + +- [ ] **Change detection service** — `lib/monitoring/` — compares DNS snapshots, detects added/removed records, availability flips, expiry changes +- [ ] **Daily cron job** — `GET /api/cron/check-domains` (secured with `CRON_SECRET`) — re-checks up to 50 domains per run, stores new snapshots, creates notifications on change +- [ ] **In-app notifications** — `notifications` table + API routes + bell icon with unread count in header + notification center page +- [ ] **Email alerts** — Install `resend`. Send emails on DNS changes, availability changes, expiry warnings. Respects user preference (`notification_email` toggle in profile). + +## Phase 7 — Settings & Polish + +- [ ] **User settings page** — Profile info, notification email toggle, sign out, delete account +- [ ] **Error handling** — Root error boundary (`app/error.tsx`), 404 page, loading skeletons for lookup and dashboard pages +- [ ] **Toasts** — Wire up `sonner` globally for success/error feedback +- [ ] **SEO** — Page-specific metadata, OG image, `robots.ts` (disallow dashboard/api), `sitemap.ts` + +## Phase 8 — Testing & QA + +- [ ] **Consolidate integration tests** — All API routes, change detection logic, auth flows +- [ ] **Build verification** — `bun run build` passes, zero TS errors, zero lint issues +- [ ] **Manual QA pass** — Walk through every page, both light and dark mode + +--- + +## Out of Scope (Future) + +These are explicitly not part of the current build: + +- Registrar API integration / domain purchasing +- Paid DNS API providers (architecture supports swapping, but free-only for now) +- Bulk domain scanning +- Billing / subscriptions +- Browser push notifications +- Rich text notes +- Domain sharing between users + +--- + +## Key Architecture Decisions + +| Decision | Rationale | +|---|---| +| `@supabase/ssr` not `auth-helpers` | auth-helpers is deprecated as of late 2025 | +| Tangerine (DoH) not Node `dns` | Works in serverless (Vercel), no system resolver dependency | +| IANA RDAP for availability | Free, no API key, standard protocol. Provider interface allows swapping to paid APIs later. | +| Resend not Supabase SMTP | Supabase built-in SMTP has a 3 emails/hour limit | +| In-memory rate limiting | Simple Map-based per-IP. No Redis dependency for MVP. | +| `TEXT[]` for tags | Postgres array, no separate tags table. Good enough for MVP. | +| Daily cron, 50 domains/run | Fits Vercel hobby tier (10s function timeout, 1 cron/day) |