diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..4c1d22e --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,3 @@ +# Global code ownership for Toolglass +# Every file and directory is reviewed by the core maintainer +* @ajithakdev diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ebb8779..f870ba8 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -11,7 +11,7 @@ npm install npm run dev ``` -Requires **Node 20+**. +Requires **Node 20+** (or Node 22/26 via nvm). | Script | Purpose | |---|---| @@ -37,24 +37,25 @@ This project uses **strict TypeScript** (`strict: true` in `tsconfig.json`). All ## Testing -Tests use **Vitest** with `jsdom` environment. Test files live alongside source as `*.test.ts` / `*.test.tsx`. +Tests use **Vitest** with `jsdom` environment. Test files live alongside source as `*.test.ts` / `*.test.tsx` (e.g. `src/tools//.test.ts`). ```bash npm test # run all tests once -npm test -- tests/crypto # run a specific test file or path +npm test src/tools/password/ # run tests for a specific tool npm run test:coverage # coverage report ``` -Crypto-related tools (password, hash, JWT, UUID, ObjectId, NanoID) have dedicated test suites — run those explicitly when touching crypto paths. +Zero/minimal external dependencies: Prefer native browser Web APIs (e.g. Web Crypto, URL, Canvas, DOMParser, regex). Introducing new runtime dependencies requires prior maintainer discussion and strong justification (as done for established standards like `marked`, `dompurify`, and `qrcode`). ## Adding a new tool -Tools follow a registry pattern — no routing config to touch. +Tools follow a modular registry pattern: 1. Create `src/tools//Tool.tsx` with a default-export component. -2. Append an entry to `src/tools/registry.ts`: +2. Create unit and component tests alongside it (`src/tools//.test.ts`, `Tool.test.tsx`). +3. Append an entry to `src/tools/registry.tsx`: -```ts +```tsx { slug: 'my-tool', title: 'My Tool', @@ -66,7 +67,12 @@ Tools follow a registry pattern — no routing config to touch. }, ``` -The tool auto-appears on the landing page and gets a route at `/#/tools/`. +4. Add the slug to the appropriate category in `CATEGORIES` within `src/pages/Landing.tsx`. +5. The tool will auto-appear on the landing page and gets a route at `/#/tools/`. + +## Code of Conduct + +We are committed to providing a welcoming, inclusive, and harassment-free experience for all contributors. Please review and adhere to our [Code of Conduct](../CODE_OF_CONDUCT.md) in all project interactions. ## Branch and commit naming diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 8242f69..5493ebc 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -23,10 +23,11 @@ npm run dev # 3. Verify … ``` -If this PR touches crypto paths (password, hash, JWT, UUID, ObjectId, NanoID), run: +To run the unit and component test suite: ```bash -npm test -- tests/crypto +npm test # Run all tests +npm test src/tools// # Run tests for a specific tool ``` ## Breaking changes diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..021420e --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,122 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders at **ajithakdev@gmail.com** or by opening a +private discussion/inquiry with the repository maintainers. All complaints will +be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), +version 2.1, available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). diff --git a/README.md b/README.md index a1c186e..02e9a31 100644 --- a/README.md +++ b/README.md @@ -5,105 +5,108 @@ **Frosted developer utilities — beautifully fast, 100% client-side.** [![License: MIT](https://img.shields.io/badge/License-MIT-blueviolet.svg)](LICENSE) -[![React](https://img.shields.io/badge/React-18-149eca.svg)](https://react.dev) +[![React](https://img.shields.io/badge/React-19-149eca.svg)](https://react.dev) [![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6.svg)](https://www.typescriptlang.org) -[![Vite](https://img.shields.io/badge/Vite-5-646cff.svg)](https://vitejs.dev) +[![Vite](https://img.shields.io/badge/Vite-8-646cff.svg)](https://vitejs.dev) +[![CI/CD](https://github.com/ajithakdev/toolglass/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/ajithakdev/toolglass/actions/workflows/ci-cd.yml) -🔗 **Live:** https://ajithakdev.github.io/toolglass/ +🔗 **Try it live:** [ajithakdev.github.io/toolglass](https://ajithakdev.github.io/toolglass/) --- -Toolglass bundles nine of the utilities you reach for every day into a single glassmorphic, pastel-gradient interface. No backend. No analytics. No data ever leaves your browser. +We built Toolglass because we were tired of opening ad-riddled websites just to decode a JWT, test a regex, or format a timestamp. Most online utility sites leak your sensitive data to backend servers or track your keystrokes. -## 🧰 Tools +Toolglass is a zero-telemetry, offline-first suite of developer tools running entirely inside your browser. No backend. No cookies. No analytics. When you paste an API secret or inspect a token, it never touches the network. -| | Tool | What it does | -|---|---|---| -| 🔐 | **Password Generator** | CSPRNG passwords, rejection-sampled, strength meter (bits of entropy) | -| 🪪 | **JWT Generator** | Sign HS256 JSON Web Tokens with custom header / payload / secret | -| 🆔 | **UUID v4** | Bulk RFC 4122 v4 UUIDs | -| 🍃 | **Mongo ObjectId** | 24-char BSON ObjectIds (timestamp + machine + counter) | -| ⚡ | **NanoID** | URL-safe compact IDs with configurable alphabet & length | -| #️⃣ | **Hash Generator** | SHA-1 / 256 / 384 / 512 via Web Crypto | -| 🧬 | **Base64** | Unicode-safe encode / decode | -| ⏱️ | **Timestamp** | Unix ⇄ ISO ⇄ local time | -| `{}` | **JSON Formatter** | Beautify, minify, validate with error positions | +--- + +## 🧰 Available Tools + +| Category | Tools | +|---|---| +| **Generators** | • [Password Generator](https://ajithakdev.github.io/toolglass/#/tools/password) (CSPRNG, rejection-sampled, entropy meter)
• [UUID v4](https://ajithakdev.github.io/toolglass/#/tools/uuid) (RFC 4122 bulk generation)
• [NanoID](https://ajithakdev.github.io/toolglass/#/tools/nanoid) (URL-safe compact IDs)
• [Mongo ObjectId](https://ajithakdev.github.io/toolglass/#/tools/objectid) (24-char BSON IDs with embedded timestamp)
• [QR Code](https://ajithakdev.github.io/toolglass/#/tools/qr) (Instant canvas/SVG generation & PNG download) | +| **Encoders & Decoders** | • [Base64](https://ajithakdev.github.io/toolglass/#/tools/base64) (Unicode-safe encode/decode)
• [URL Encoder](https://ajithakdev.github.io/toolglass/#/tools/url) (`encodeURIComponent` with full parameter parsing)
• [JWT Decoder](https://ajithakdev.github.io/toolglass/#/tools/jwt-decode) (Header/payload breakdown & expiration badges) | +| **Converters & Formatters** | • [JSON Formatter](https://ajithakdev.github.io/toolglass/#/tools/json) (Beautify, minify, syntax validation with line errors)
• [Color Converter](https://ajithakdev.github.io/toolglass/#/tools/color) (Hex ⇄ RGB ⇄ HSL with live alpha slider)
• [JSON to TypeScript](https://ajithakdev.github.io/toolglass/#/tools/json-to-ts) (Generates interfaces or types automatically) | +| **Security & Crypto** | • [Hash Generator](https://ajithakdev.github.io/toolglass/#/tools/hash) (SHA-1, SHA-256, SHA-384, SHA-512 via Web Crypto)
• [JWT Signer](https://ajithakdev.github.io/toolglass/#/tools/jwt) (Local HMAC-SHA256 signature generation) | +| **API & Networking** | • [API Tester](https://ajithakdev.github.io/toolglass/#/tools/api-tester) (In-browser HTTP client with cURL import and sanitized headers) | +| **Utilities** | • [Timestamp Converter](https://ajithakdev.github.io/toolglass/#/tools/timestamp) (Unix epoch ⇄ ISO 8601 ⇄ relative time & batch mode)
• [Regex Tester](https://ajithakdev.github.io/toolglass/#/tools/regex) (Real-time regex engine with visual match highlights)
• [Markdown Preview](https://ajithakdev.github.io/toolglass/#/tools/markdown) (Live GitHub-flavored preview with DOMPurify sanitization) | + +--- -## ✨ Highlights +## 💡 Key Principles -- **Cryptographically strong** — every random byte uses `crypto.getRandomValues` / `crypto.subtle`. Never `Math.random`. -- **Modular** — tools live in self-contained folders; a single `registry.ts` drives routes + landing cards. -- **Tiny** — each tool is lazy-loaded, ~1–3 KB gzipped per tool. -- **Accessible** — semantic markup, keyboard-focusable, aria-live toasts, respects `prefers-reduced-motion`. -- **Pretty** — glassmorphism, pastel gradients, framer-motion micro-interactions. +1. **Zero Network Calls:** Everything executes on the client thread using standard Web APIs (`crypto.subtle`, `crypto.getRandomValues`, `DOMParser`). +2. **Cryptographic Rigor:** Randomness is strictly backed by CSPRNG with rejection sampling to eliminate modulo bias. We never use `Math.random()`. +3. **Instant Keyboard Navigation:** Hit `⌘K` or `Ctrl+K` anywhere to open the command palette and jump between tools without taking your hands off the keyboard. +4. **Shareable State:** Key tool configurations sync to URL query params (debounced) so you can bookmark or share exact settings with teammates. +5. **No Bloat:** Every tool is code-split via dynamic `React.lazy()` imports. The initial load is tiny (~130 KB gzipped) and tools load on demand. -## 🧱 Stack +--- -- **React 18** + **TypeScript 5** -- **Vite 5** (fast HMR, ES2022 output) -- **react-router-dom** (HashRouter — GH Pages friendly) -- **framer-motion** -- **Web Crypto API** +## 🛠️ Local Development -## 🚀 Quick start +Toolglass uses standard modern frontend tooling (React 19, TypeScript, Vite, Vitest): ```bash +# Clone the repository git clone https://github.com/ajithakdev/toolglass.git cd toolglass + +# Install dependencies npm install + +# Start local dev server with HMR npm run dev ``` -Requires Node 20+. +### Common Scripts -| Script | Purpose | -|---|---| -| `npm run dev` | Local dev server with HMR | -| `npm run build` | Type-check + production build (`dist/`) | -| `npm run preview` | Serve the production build locally | -| `npm run lint` | ESLint | -| `npm run deploy` | Build & publish to `gh-pages` | +```bash +npm run dev # Start local dev server at http://localhost:5173 +npm run build # Strict type-check (tsc -b) followed by production Vite build +npm run preview # Preview production bundle locally +npm run lint # Run ESLint across code and tests +npm test # Run Vitest test suite once +npm run test:coverage # Generate test coverage report +``` -## 🗂️ Architecture +--- + +## 🗂️ Project Structure ``` src/ -├─ main.tsx # entry + HashRouter -├─ App.tsx # shell, nav, routes -├─ index.css # tokens, theme, glass utilities -├─ lib/ # framework-free helpers (cn, …) -├─ hooks/ # reusable hooks (useClipboard, …) -├─ components/ -│ ├─ ToolLayout.tsx # consistent tool page chrome -│ └─ ui/ # GlassCard · Button · Field · Toggle · Slider · Output · Toast · CopyButton -├─ pages/ -│ ├─ Landing.tsx # tool cards grid -│ └─ ToolPage.tsx # dynamic tool loader (code-split via React.lazy) -└─ tools/ - ├─ registry.ts # single source of truth - ├─ password/ jwt/ uuid/ objectid/ nanoid/ - └─ hash/ base64/ timestamp/ json/ +├── components/ # Reusable glass UI widgets (Buttons, Inputs, CommandPalette) +├── hooks/ # Custom hooks (useClipboard, useTheme, useUrlState) +├── pages/ +│ ├── Landing.tsx # Main dashboard with categorized tool grid +│ ├── ToolPage.tsx # Dynamic lazy loader with ErrorBoundary & Suspense +│ └── NotFound.tsx # Custom 404 page +├── tools/ # Self-contained tool modules +│ ├── registry.tsx # Single source of truth for tool metadata & routing +│ └── / +│ ├── Tool.tsx # Main React UI component +│ ├── .ts # Pure business logic / calculations +│ └── .test.ts(x) # Unit and component tests +└── App.tsx # Shell with global navigation and theme providers ``` -### ➕ Adding a new tool - -1. Create `src/tools//Tool.tsx` with a default-export component. -2. Append an entry to `src/tools/registry.ts` (lazy-imported). -3. It auto-appears on the landing page and gets a route at `/#/tools/`. +--- -## 🔐 Security notes +## 🤝 Contributing -- All randomness uses `crypto.getRandomValues` and `crypto.subtle` — never `Math.random`. -- Password generation uses **rejection sampling** to eliminate modulo bias, plus a final **Fisher–Yates shuffle** so the guaranteed class-coverage chars are not stuck at the start. -- Strength meter reports **bits of entropy** based on the active alphabet size. -- Everything runs in-browser — no network calls, no storage, no tracking. +We love contributions! Toolglass was built to make contributing new utilities frictionless: -## 🤝 Contributing +- Adding a new tool usually requires just **one self-contained folder** under `src/tools/` and a registration line in `src/tools/registry.tsx`. +- We maintain a **zero external runtime dependencies** rule for individual tools — rely on native browser APIs. +- Check out our **[Contributing Guide](.github/CONTRIBUTING.md)** for detailed step-by-step instructions. +- All contributors are expected to follow our **[Code of Conduct](CODE_OF_CONDUCT.md)**. +- See our **[Security Policy](SECURITY.md)** for responsible vulnerability disclosure. -PRs welcome — adding a new tool is intentionally a tiny diff (one folder + one registry line). Open an issue first if proposing a large change. +--- ## 📄 License -[MIT](LICENSE) © ajithakdev +Distributed under the [MIT License](LICENSE). Built with ✦ by [ajithakdev](https://github.com/ajithakdev). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..bb47d17 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,39 @@ +# Security Policy + +Toolglass is designed to operate with **zero telemetry, zero analytics, and no backend server**. For offline utilities (CSPRNG passwords, UUIDs, JWT decoding, hashes, timestamps, etc.), all computation runs 100% locally in your browser — no inputs, tokens, or cryptographic keys ever leave your machine. + +## Supported Versions + +We actively maintain and provide security patches for the latest version of Toolglass on the `main` branch. + +| Version | Supported | +| ------- | ------------------ | +| 1.0.x (main) | :white_check_mark: | +| < 1.0.0 | :x: | + +## Security Principles in Toolglass + +- **CSPRNG Only:** Cryptographic operations strictly use `window.crypto.getRandomValues()` and `crypto.subtle`. We never use `Math.random()` for security-sensitive tools. +- **Zero Third-Party Telemetry:** Toolglass has no analytics trackers, tracking cookies, or diagnostic logging. In the API Tester, HTTP requests and headers are dispatched exclusively to user-specified target servers upon explicit user action, and are never intercepted or relayed through any intermediary server. +- **Client-Side Sanitization:** Rendered outputs (e.g. Markdown preview, cURL commands) use strict sanitization (`DOMPurify`, POSIX shell escaping) to prevent XSS and shell injection vulnerabilities. + +## Reporting a Vulnerability + +If you discover a potential security vulnerability or privacy leak within Toolglass, **please do not open a public GitHub issue.** + +Instead, please report it responsibly through one of the following channels: + +1. **GitHub Private Vulnerability Reporting:** Use the [Security Advisory Reporting](https://github.com/ajithakdev/toolglass/security/advisories/new) tab on this repository. +2. **Direct Email:** Contact the repository maintainer directly at **ajithakdev@gmail.com**. + +### What to Include + +To help us triage and resolve the issue quickly, please provide: +- A description of the vulnerability and its potential impact. +- Steps to reproduce the issue, including sample input or proof-of-concept code. +- Details regarding your environment (browser version, OS). + +### Our Commitment + +- **Acknowledgment:** We will acknowledge receipt of your vulnerability report within 48 hours. +- **Fix & Disclosure:** We will work promptly on a patch and coordinate a coordinated public disclosure with proper credit once the fix is deployed.