diff --git a/docs/api-spec.md b/docs/api-spec.md deleted file mode 100644 index f65983b..0000000 --- a/docs/api-spec.md +++ /dev/null @@ -1,135 +0,0 @@ -# Go DNS API Specification - -Base URL: `https:///api/v1` - -All requests require the header `X-API-Key: `. - ---- - -## Endpoints - -### `POST /dns/lookup` - -Resolve DNS records for a domain. - -**Request:** - -```json -{ - "domain": "example.com", - "types": ["A", "AAAA", "MX", "TXT", "NS", "CNAME", "SOA", "CAA", "SRV"], - "nameserver": "8.8.8.8" -} -``` - -- `domain` (required): The domain to query. -- `types` (optional): Record types to query. Defaults to all supported types. -- `nameserver` (optional): Specific nameserver to query. Defaults to system resolver. - -**Response (200):** - -```json -{ - "domain": "example.com", - "nameserver": "8.8.8.8", - "records": { - "A": [{ "value": "93.184.216.34", "ttl": 300 }], - "MX": [{ "value": "mail.example.com", "priority": 10, "ttl": 3600 }] - }, - "query_time_ms": 12 -} -``` - ---- - -### `POST /dns/propagation` - -Check DNS propagation across multiple resolvers. - -**Request:** - -```json -{ - "domain": "example.com", - "type": "A", - "resolvers": ["8.8.8.8", "1.1.1.1", "9.9.9.9"] -} -``` - -- `resolvers` (optional): Defaults to a built-in list of public resolvers. - -**Response (200):** - -```json -{ - "domain": "example.com", - "type": "A", - "results": [ - { "resolver": "8.8.8.8", "values": ["93.184.216.34"], "ttl": 300 }, - { "resolver": "1.1.1.1", "values": ["93.184.216.34"], "ttl": 280 }, - { "resolver": "9.9.9.9", "values": ["93.184.216.34"], "ttl": 295 } - ], - "consistent": true -} -``` - ---- - -### `POST /dns/validate` - -DNSSEC validation for a domain. - -**Request:** - -```json -{ - "domain": "example.com" -} -``` - -**Response (200):** - -```json -{ - "domain": "example.com", - "dnssec": true, - "chain_valid": true, - "details": "RRSIG verified for A record" -} -``` - ---- - -### `GET /health` - -Health check. No authentication required. - -**Response (200):** - -```json -{ - "status": "ok", - "version": "0.1.0" -} -``` - ---- - -## Error Responses - -All errors follow this format: - -```json -{ - "error": "invalid domain", - "code": "INVALID_DOMAIN" -} -``` - -| HTTP Status | Code | Description | -|---|---|---| -| 400 | `INVALID_DOMAIN` | Malformed or missing domain | -| 400 | `INVALID_TYPE` | Unsupported record type | -| 401 | `UNAUTHORIZED` | Missing or invalid API key | -| 500 | `DNS_ERROR` | Upstream DNS query failed | -| 500 | `INTERNAL` | Unexpected server error | diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index 0fd5730..0000000 --- a/docs/architecture.md +++ /dev/null @@ -1,78 +0,0 @@ -# VectorDNS Architecture - -## Overview - -VectorDNS uses a hybrid architecture: a Next.js frontend on Vercel and a Go DNS microservice on a VPS. - -``` -┌──────────────────────┐ ┌──────────────────────┐ -│ Vercel (Frontend) │ │ VPS (DNS API) │ -│ │ │ │ -│ Next.js 16 │ HTTP │ Go microservice │ -│ React 19 │◄──────►│ miekg/dns │ -│ Supabase SDK │ │ │ -│ Tailwind + shadcn │ │ - DNS resolution │ -│ │ │ - DNSSEC validation │ -│ Handles: │ │ - Propagation checks │ -│ - UI/SSR │ │ - Monitoring cron │ -│ - Auth (Supabase) │ │ - Change detection │ -│ - WHOIS lookups │ │ │ -│ - Static pages │ └───────────┬───────────┘ -│ │ │ -└──────────┬───────────┘ │ UDP/TCP - │ ▼ - │ ┌───────────────────────┐ - │ │ DNS Resolvers / │ - ▼ │ Authoritative NS │ -┌──────────────────────┐ └───────────────────────┘ -│ Supabase │ -│ │ -│ - Postgres DB │ -│ - Auth │ -│ - Row Level Security│ -└──────────────────────┘ -``` - -## Why Hybrid - -| Concern | Solution | -|---|---| -| Frontend hosting, SSR, auth | Vercel (serverless, zero-ops) | -| DNS resolution, monitoring | Go on VPS (persistent process, no cold starts) | -| Database, auth state | Supabase (managed Postgres) | - -## What Each Service Handles - -### Next.js (Vercel) - -- All UI rendering (SSR + client) -- Authentication via Supabase -- WHOIS lookups (whoiser library) -- Domain availability checks (IANA RDAP) -- Dashboard, notifications, settings pages -- Proxies DNS queries to the Go service - -### Go Microservice (VPS) - -- DNS record lookups via `miekg/dns` (UDP/TCP, not DoH) -- Query specific or authoritative nameservers directly -- DNSSEC validation -- DNS propagation checking across multiple resolvers -- Scheduled monitoring (native cron, no serverless time limits) -- Change detection (diff DNS snapshots, notify on changes) - -## Communication - -The Next.js API routes call the Go service over HTTPS. The Go service URL is configured via environment variable (`GO_DNS_API_URL`). Requests are authenticated with a shared API key (`GO_DNS_API_KEY`). - -``` -Next.js API route → HTTPS → Go DNS API → UDP/TCP → DNS resolvers -``` - -## Why Go Over DoH (Tangerine) - -- Direct UDP/TCP DNS queries — faster, no middleman -- Can query authoritative nameservers directly -- Supports DNSSEC validation, AXFR, propagation checks -- No cold starts, consistent latency -- No Vercel function timeout limits for monitoring jobs diff --git a/docs/feature-plan.md b/docs/feature-plan.md deleted file mode 100644 index f6cc69b..0000000 --- a/docs/feature-plan.md +++ /dev/null @@ -1,111 +0,0 @@ -# VectorDNS Feature Plan - -Decisions captured for current and future development. - ---- - -## Auth & User System - -| Feature | Decision | Priority | -|---|---|---| -| OAuth providers | GitHub + Google | MVP | -| Email/password + magic link | Yes | MVP | -| Team/org accounts | Yes, eventually — shared watchlists, role-based access (admin/viewer) | Future | -| User API keys | No — Go server is internal, called only by the Next.js backend | N/A | - -### Schema implications (teams) -- Future `teams` table with membership + roles -- `saved_domains` will need an optional `team_id` foreign key -- RLS policies will need team-aware variants - ---- - -## DNS & Monitoring - -| Feature | Decision | Priority | -|---|---|---| -| Check intervals | Daily (MVP), then hourly/daily/weekly selectable | MVP → Near-term | -| Realtime monitoring | Not now — possible distant future | Deferred | -| Custom resolvers | Fixed resolvers (Google 8.8.8.8, Cloudflare 1.1.1.1) by default; user-specified resolvers as future feature | MVP → Future | -| Propagation checks | Query multiple resolvers and compare results | Near-term | -| DNSSEC validation | Basic AD flag check (current), deep chain validation later | MVP → Future | - -### Go server implications -- Scheduler needed for flexible intervals (hourly/daily/weekly per domain) -- Resolver list should be configurable, not hardcoded (prep for custom resolvers) -- Propagation endpoint: query N resolvers in parallel, return per-resolver results - ---- - -## Alert Channels - -| Channel | Priority | -|---|---| -| In-app notification feed | MVP | -| Email (Resend) | MVP | -| Webhooks (user-configured URL) | Near-term | -| Slack integration | Future | -| Discord integration | Future | - -### Schema implications -- `notification_channels` table: user_id, type (email/webhook/slack/discord), config (jsonb), enabled -- Webhook: store URL + optional secret for HMAC signing -- Slack/Discord: store webhook URL or OAuth token - ---- - -## Dashboard & UX - -| Feature | Decision | Priority | -|---|---|---| -| Domain organization | Tags (current) + folders/groups | Near-term | -| Public sharing | Shareable links for domain DNS snapshots | Near-term | -| Data export | CSV + JSON for DNS history, saved domains, notifications | Near-term | -| Bulk operations | Add/remove/re-check multiple domains at once | Future | -| Search & filter | Filter by tag, folder, record type, change status | Near-term | - -### Schema implications (folders) -- `domain_folders` table: id, user_id, name, created_at -- `saved_domains` gets an optional `folder_id` foreign key -- RLS policies for folder ownership - -### Schema implications (public sharing) -- `shared_snapshots` table: id, saved_domain_id, share_token (unique), dns_snapshot (jsonb), expires_at, created_at -- Public access via token — no auth required to view - ---- - -## Infrastructure - -| Feature | Decision | Priority | -|---|---|---| -| Billing/paid tiers | Freemium — free tier with limits, paid for more domains/features/intervals | Future | -| DNS caching | Redis — external cache for TTL-based DNS result caching | Near-term | -| Self-hosting | Go server only — provide Dockerfile + docker-compose for the DNS API | Near-term | -| Next.js hosting | Vercel only, not self-hostable | — | - -### Freemium tier structure (draft) -- **Free**: 5 monitored domains, daily checks, in-app + email alerts -- **Pro**: 50 domains, hourly checks, webhooks, folders, export -- **Team**: everything in Pro + team accounts, shared watchlists - -### Go server additions needed -- Redis client (go-redis) for caching layer -- Cache middleware: check Redis before querying DNS, store with TTL -- docker-compose.yml with Go server + Redis for self-hosting -- Rate limiting per API key / tier (when billing is added) - ---- - -## Summary of future schema additions - -These tables will be needed as features are built: - -| Table | For | -|---|---| -| `teams` | Team/org accounts | -| `team_members` | Membership + roles | -| `domain_folders` | Folder organization | -| `shared_snapshots` | Public shareable links | -| `notification_channels` | Webhook/Slack/Discord config | -| `subscriptions` | Billing tier tracking |