Skip to content

Commit 38b8690

Browse files
MiguelMedeirosMiguelMedeiros
committed
Add MIT License, rename package, and update README and development documentation
1 parent 9d089d0 commit 38b8690

File tree

4 files changed

+149
-66
lines changed

4 files changed

+149
-66
lines changed

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Pubky
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 25 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,47 @@
1-
# PKDNS Resolver - Chrome Extension
1+
# PKDNS Resolver Extension
22

3-
Resolve [Pkarr](https://github.com/pubky/pkarr) public keys to DNS records directly in your browser. Navigate to websites hosted on sovereign, self-signed domains powered by the BitTorrent Mainline DHT.
3+
> Resolve [Pkarr](https://github.com/pubky/pkarr) public keys to DNS records directly in your browser.
44
5-
## Features
5+
[![CI](https://github.com/pubky/pkdns-resolver-extension/actions/workflows/ci.yml/badge.svg)](https://github.com/pubky/pkdns-resolver-extension/actions/workflows/ci.yml)
6+
[![License](https://img.shields.io/badge/license-MIT-purple)](./LICENSE)
7+
[![Chrome MV3](https://img.shields.io/badge/Chrome-Manifest%20V3-4285F4?logo=googlechrome&logoColor=white)](https://developer.chrome.com/docs/extensions/mv3/)
68

7-
- **Omnibox** — Type `pk` in the address bar followed by a public key to resolve it instantly
8-
- **Popup** — Click the extension icon to paste a key, view DNS records, and navigate
9-
- **Context Menu** — Right-click selected text to resolve it as a PKDNS key
10-
- **Auto-redirect** — Automatically navigate to websites when A/CNAME/HTTPS records are found
11-
- **Recent History** — Quick access to previously resolved keys
9+
A Chrome extension to navigate websites hosted on sovereign domains powered by the [Mainline DHT](https://en.wikipedia.org/wiki/Mainline_DHT). Type a public key, get DNS records, visit the site.
1210

13-
## How It Works
14-
15-
1. You provide a 52-character z-base32 Pkarr public key
16-
2. The extension fetches the signed DNS packet from Pkarr HTTP relays
17-
3. The binary payload is parsed to extract DNS records (A, AAAA, CNAME, TXT, HTTPS, etc.)
18-
4. Records are displayed in a clean UI, with an option to visit the resolved website
19-
20-
No WASM or heavy dependencies — the extension uses pure JavaScript DNS parsing for maximum compatibility and minimal footprint (~80KB total).
21-
22-
## Installation
23-
24-
### From Source
11+
## Install
2512

2613
```bash
27-
# Clone and install
28-
git clone <repo-url>
29-
cd pkdns-extension
14+
git clone https://github.com/pubky/pkdns-resolver-extension.git
15+
cd pkdns-resolver-extension
3016
npm install
31-
32-
# Build
3317
npm run build
3418
```
3519

36-
Then load in Chrome:
37-
3820
1. Open `chrome://extensions/`
3921
2. Enable **Developer mode**
40-
3. Click **Load unpacked**
41-
4. Select the `dist/` folder
42-
43-
### Development
44-
45-
```bash
46-
npm run dev
47-
```
48-
49-
This runs Vite in watch mode, rebuilding on file changes.
22+
3. Click **Load unpacked** and select the `dist/` folder
5023

5124
## Usage
5225

53-
### Omnibox (Address Bar)
54-
55-
1. Type `pk` in the address bar and press **Tab** or **Space**
56-
2. Paste or type a public key
57-
3. Press **Enter** to resolve
58-
59-
### Popup
60-
61-
1. Click the PKDNS extension icon in the toolbar
62-
2. Paste a public key and click **Resolve**
63-
3. View DNS records or click **Visit Website**
64-
65-
### Context Menu
26+
- **Omnibox** — Type `pk` + **Tab**, paste a public key, press **Enter**
27+
- **Popup** — Click the extension icon, paste a key, click **Resolve**
28+
- **Context Menu** — Select a key on any page, right-click **Resolve with PKDNS**
6629

67-
1. Select a public key on any web page
68-
2. Right-click and select **Resolve with PKDNS**
30+
## Development
6931

70-
## Configuration
71-
72-
Default relays:
73-
74-
- `https://pkarr.pubky.app`
75-
- `https://pkarr.pubky.org`
32+
```bash
33+
npm run dev # watch mode
34+
npm run build # production build
35+
npm test # run tests
36+
npm run lint # lint
37+
```
7638

77-
## Tech Stack
39+
## Related
7840

79-
- TypeScript
80-
- Vite (bundler)
81-
- Tailwind CSS
82-
- `dns-packet` (pure JS DNS wire-format parser)
83-
- Chrome Extension Manifest V3
41+
- [pkarr](https://github.com/pubky/pkarr) — Public Key Addressable Resource Records
42+
- [pkdns](https://github.com/pubky/pkdns) — DNS server for Pkarr domains
43+
- [mainline](https://github.com/pubky/mainline) — BitTorrent Mainline DHT
8444

8545
## License
8646

87-
MIT
47+
[MIT](./LICENSE)

‎docs/DEVELOPMENT.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Development Guide
2+
3+
## Prerequisites
4+
5+
- Node.js 20+
6+
- npm
7+
8+
## Scripts
9+
10+
| Command | Description |
11+
|---------|-------------|
12+
| `npm run dev` | Start development mode (watch) |
13+
| `npm run build` | Type-check and build for production |
14+
| `npm run test` | Run tests |
15+
| `npm run test:watch` | Run tests in watch mode |
16+
| `npm run test:coverage` | Run tests with coverage |
17+
| `npm run lint` | Lint the codebase |
18+
| `npm run lint:fix` | Lint and auto-fix issues |
19+
| `npm run format` | Format all files with Prettier |
20+
| `npm run format:check` | Check formatting without changes |
21+
22+
## Project Structure
23+
24+
```
25+
src/
26+
├── background/ # Chrome service worker (omnibox, context menu, navigation)
27+
├── popup/ # Extension popup UI
28+
├── resolve/ # Full resolution page with DNS records
29+
├── favorites/ # Favorites management page
30+
├── recent/ # Recently resolved keys page
31+
├── history/ # Resolution history with stats and charts
32+
├── relays/ # Relay management and testing page
33+
├── settings/ # Extension settings page
34+
├── how-it-works/ # Help and documentation page
35+
├── lib/ # Shared libraries
36+
│ ├── pkarr.ts # Key validation and parsing
37+
│ ├── resolver.ts # Resolution logic (fetch, verify, cache)
38+
│ ├── dns.ts # DNS packet parsing and formatting
39+
│ ├── storage.ts # Chrome storage abstraction
40+
│ ├── cache.ts # Caching layer with TTL
41+
│ ├── history.ts # Resolution history and statistics
42+
│ ├── i18n.ts # Internationalization engine
43+
│ └── constants.ts # Relay URLs, storage keys, limits
44+
├── locales/ # Translation files (9 languages)
45+
└── styles/ # Global styles and Tailwind configuration
46+
```
47+
48+
## Tech Stack
49+
50+
- **TypeScript** — Type-safe codebase
51+
- **Vite** — Fast builds with multi-entry support
52+
- **Tailwind CSS** — Utility-first styling with dark mode
53+
- **dns-packet** — Pure JS DNS wire-format parser
54+
- **Chart.js** — Resolution history charts
55+
- **Vitest** — Unit testing
56+
- **ESLint + Prettier** — Code quality and formatting
57+
- **Chrome Extension Manifest V3** — Modern extension platform
58+
59+
## Features
60+
61+
- **Omnibox** — Type `pk` in the address bar followed by a public key to resolve it instantly
62+
- **Popup** — Click the extension icon to paste a key, view DNS records, and navigate
63+
- **Context Menu** — Right-click selected text to resolve it as a PKDNS key
64+
- **Auto-redirect** — Automatically navigate when A/CNAME/HTTPS records are found
65+
- **Favorites** — Save and label frequently used keys
66+
- **History** — Track resolution history with stats and charts
67+
- **Relay Management** — Configure, add, remove, and test Pkarr HTTP relays
68+
- **Internationalization** — 9 languages (EN, PT-BR, ES, DE, FR, IT, ZH, JA, AR)
69+
- **Dark Mode** — Full dark theme support
70+
71+
## Configuration
72+
73+
### Default Relays
74+
75+
| Relay | URL |
76+
|-------|-----|
77+
| Pubky App | `https://pkarr.pubky.app` |
78+
| Pubky Org | `https://pkarr.pubky.org` |
79+
80+
Relays can be customized through the **Relays** page in the extension settings.
81+
82+
## How It Works
83+
84+
1. You provide a 52-character z-base32 Pkarr public key
85+
2. The extension fetches the signed DNS packet from Pkarr HTTP relays
86+
3. The binary payload is parsed to extract DNS records (A, AAAA, CNAME, TXT, HTTPS, etc.)
87+
4. Records are displayed in a clean UI, with an option to visit the resolved website
88+
89+
No WASM or heavy dependencies — pure JavaScript DNS parsing for maximum compatibility and minimal footprint.
90+
91+
## Contributing
92+
93+
1. Fork the repository
94+
2. Create a feature branch (`git checkout -b feature/my-feature`)
95+
3. Commit your changes
96+
4. Push to the branch and open a pull request
97+
98+
Make sure all checks pass before submitting:
99+
100+
```bash
101+
npm run lint && npm run format:check && npm test && npm run build
102+
```

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "pkdns-extension",
2+
"name": "pkdns-resolver-extension",
33
"version": "1.0.0",
44
"description": "Chrome extension to resolve Pkarr public keys to DNS records",
55
"private": true,

0 commit comments

Comments
 (0)