From 47ead27344332d717c26ecbf72e84ddf0a0f9068 Mon Sep 17 00:00:00 2001 From: Koala <6156589+Shik3i@users.noreply.github.com> Date: Mon, 1 Jun 2026 03:21:59 +0200 Subject: [PATCH] docs: improve CONTRIBUTING.md and SECURITY.md readability - CONTRIBUTING: add ways to contribute table, project structure, setup guide - CONTRIBUTING: add website testing, translation guide, bug report template - SECURITY: add scope/out-of-scope, architecture overview, threat model - SECURITY: structured reporting timeline, responsible disclosure policy --- CONTRIBUTING.md | 170 +++++++++++++++++++++++++++++++++++------------- SECURITY.md | 98 ++++++++++++++++++++++++---- 2 files changed, 211 insertions(+), 57 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 04563c9..bf45839 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,59 +1,141 @@ # Contributing to KoalaSync -Thank you for your interest in contributing to KoalaSync! We welcome all contributions, from bug reports to new features. +Thanks for your interest in improving KoalaSync. All contributions are welcome — from bug reports and translations to core protocol changes. -## Development Workflow +--- -### 1. Prerequisites -- Node.js (v18+) -- Docker (for local server testing) +## Ways to Contribute -### 2. Setup -1. Clone the repository. -2. Run `npm install` in the root directory to install build dependencies. -3. Run the build script to synchronize protocol constants and generate browser bundles: - ```bash - node scripts/build-extension.js - ``` +| Area | Description | +|------|-------------| +| **Bug Reports** | Found a bug? Open an issue with repro steps (see template below). | +| **Code** | Fix bugs, add features, or improve the extension / server / website. | +| **Translations** | Help localize the extension and website into more languages. See [TRANSLATION.md](website/TRANSLATION.md). | +| **Documentation** | Improve docs, fix typos, or add missing examples. | +| **Security** | Found a vulnerability? See [SECURITY.md](SECURITY.md) — do NOT open a public issue. | -### 3. Testing Locally -1. Load `dist/chrome/` as an "Unpacked Extension" in Chrome (`chrome://extensions/` → Developer Mode → Load Unpacked). -2. For Firefox, load `dist/firefox/` via `about:debugging` → "Load Temporary Add-on". -3. Start the relay server: `docker-compose up --build`. -4. Use **two different browser profiles** (or Chrome + Firefox) to test multi-peer synchronization. -5. Use the extension's **Dev tab** to verify real-time video element metadata (`readyState`, `currentTime`, `paused`). +--- -### 4. Protocol Synchronization -KoalaSync uses a "Single Source of Truth" for protocol constants in `shared/constants.js`. -- **CRITICAL**: If you modify the constants, you MUST run the build script: - ```bash - node scripts/build-extension.js - ``` - This will automatically synchronize the changes to the extension and generate the browser-specific bundles in the `dist/` folder. +## Development Setup -### 5. Code Standards -- **Vanilla JS**: The extension must remain dependency-free. Do not add npm packages to the `extension/` directory. -- **Privacy**: Do not add external requests (CDNs, fonts, analytics, etc.). -- **Comments**: Maintain the existing documentation style, especially for complex sync logic. -- **Room IDs**: Room IDs are restricted to `[a-zA-Z0-9-]` (alphanumeric + hyphens only). Ensure any UI that generates room IDs follows this constraint. +### Prerequisites + +- **Node.js** v18+ +- **Docker** (for local relay server testing) + +### Quick Start + +```bash +git clone https://github.com/Shik3i/KoalaSync.git +cd KoalaSync +npm install +node scripts/build-extension.js +``` + +--- + +## Project Structure + +| Directory | Purpose | +|-----------|---------| +| `extension/` | Browser extension (Manifest V3, Chrome & Firefox) | +| `server/` | Node.js + Socket.IO relay server (Dockerized) | +| `website/` | Landing page, invitation bridge, and marketing site | +| `shared/` | Protocol constants — single source of truth | +| `scripts/` | Build and sync utilities | +| `docs/` | Architecture, sync protocol, and deep-dive guides | + +--- + +## Testing Locally + +### Extension + +1. Load `dist/chrome/` as an unpacked extension in Chrome (`chrome://extensions/` → Developer Mode → **Load unpacked**). +2. For Firefox: load `dist/firefox/` via `about:debugging` → **Load Temporary Add-on**. +3. Start the relay server: `docker compose up --build`. +4. Use **two different browser profiles** (or Chrome + Firefox) to test multi-peer sync. +5. Use the extension's **Dev tab** to inspect real-time video element state (`readyState`, `currentTime`, `paused`). + +### Website + +```bash +node website/build.js # Compile static site → www/ +python3 -m http.server 8080 -d website/www # Serve locally +``` + +Then open `http://localhost:8080`. For multi-language testing: `http://localhost:8080/de/`. + +--- + +## Protocol Constants + +KoalaSync uses a **single source of truth** for all protocol constants in `shared/constants.js`. -### 6. Version Numbers > [!IMPORTANT] -> **Do NOT manually bump version numbers.** The CI pipeline automatically injects the version from the git tag into `manifest.base.json`, `shared/constants.js`, and `package.json` during release builds. Manually changing version numbers in a PR will cause conflicts. +> After modifying `shared/constants.js`, you **must** run the build script to sync changes to the extension: +> ```bash +> node scripts/build-extension.js +> ``` +> This automatically injects constants into `content.js` and regenerates browser bundles in `dist/`. + +--- + +## Code Standards + +- **Vanilla JS**: The extension must remain dependency-free. No npm packages in `extension/`. +- **Privacy-first**: Zero external requests — no CDNs, fonts, analytics, or trackers. All assets self-hosted. +- **System font stack**: `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, ...` — never `@import` external fonts. +- **Room IDs**: Restricted to `[a-zA-Z0-9-]` (alphanumeric + hyphens only). Enforced server-side. +- **Comments**: Document complex sync logic. The codebase uses inline comments for protocol reasoning. + +--- + +## Version Numbers + +> [!CAUTION] +> **Never manually bump version numbers.** The CI pipeline injects the version from the git tag into `manifest.base.json`, `shared/constants.js`, and `package.json` during release builds. Manual bumps cause conflicts. + +--- ## Pull Request Process -1. Create a new branch for your feature or bugfix. -2. Ensure your code is tested locally (Chrome and Firefox). - - For website changes: run `node website/build.js` and verify the output. -3. Update relevant documentation (e.g., `docs/ARCHITECTURE.md` if you change the protocol). -4. Submit your PR with a clear description of the changes. -## Bug Reports -When reporting a bug, please include: -- **Browser**: Chrome / Firefox / Edge + version number. -- **Extension Version**: Visible in the popup's Dev tab. -- **Dev Tab Output**: Copy the connection status, logs, and video debug info from the Dev tab. -- **Steps to Reproduce**: A clear sequence of actions that triggers the issue. +1. **Branch** from `main` for your feature or fix. +2. **Test locally** on both Chrome and Firefox. +3. **Website changes**: Run `node website/build.js` and verify the compiled output in `www/`. +4. **Lint**: Ensure `npm run lint` passes with zero errors and zero warnings. +5. **Syntax**: Run `node -c` on every modified `.js` file. +6. **Protocol changes**: Update relevant documentation in `docs/`. +7. **Submit your PR** with a clear description and linked issue (if applicable). + +--- + +## Bug Report Template + +When filing a bug, include as much of the following as possible: + +| Field | Example | +|-------|---------| +| **Browser** | Chrome 125, Firefox 128 | +| **Extension Version** | v1.9.3 (visible in Dev tab) | +| **Dev Tab Output** | Connection status, video debug info, log entries | +| **Steps to Reproduce** | 1. Create room → 2. Join from second browser → 3. Play video | +| **Expected Behavior** | Both peers play simultaneously | +| **Actual Behavior** | Peer B remains paused | + +--- + +## Translation Contributions + +KoalaSync supports 6 languages: English, German, French, Spanish, Portuguese (Brazilian), and Russian. + +To add or improve translations: +1. Edit the locale files in `website/locales/` (for the website). +2. For extension translations, see [TRANSLATION.md](website/TRANSLATION.md). +3. Run `node website/build.js` to regenerate the static site. + +--- ## Security -If you find a security vulnerability, please do not open a public issue. Instead, refer to our [SECURITY.md](SECURITY.md) for responsible disclosure instructions. + +If you discover a security vulnerability, **do not open a public issue**. Report it privately as described in [SECURITY.md](SECURITY.md). diff --git a/SECURITY.md b/SECURITY.md index 8357983..5f7f151 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,23 +1,95 @@ # Security Policy +KoalaSync is built on a **zero-persistence, privacy-first** architecture. We take security seriously and appreciate responsible disclosure of vulnerabilities. + +--- + ## Supported Versions -We take the security of our users and their data very seriously. We actively support and patch the latest stable releases of KoalaSync. +Only the latest stable release receives security patches. -| Version | Supported | -| -------------- | ------------------ | -| Latest Release | :white_check_mark: | -| Older Versions | :x: | +| Version | Supported | +|---------|-----------| +| Latest release | :white_check_mark: Active | +| Older versions | :x: Unsupported | + +Users on older versions are encouraged to update. The server enforces a minimum client version via `MIN_VERSION`. + +--- + +## Scope + +The following components are within scope for security reports: + +| Component | Examples | +|-----------|----------| +| **Relay Server** (`server/`) | Authentication bypass, rate-limit evasion, room hijacking, DoS vectors | +| **Browser Extension** (`extension/`) | XSS via content scripts, privilege escalation, data exfiltration, tab snooping | +| **WebSocket Protocol** | Message injection, replay attacks, man-in-the-middle (WSS bypass) | +| **Website** (`website/`) | XSS, CSP bypass, invitation-hash leaks | + +### Out of Scope + +- Theoretical attacks requiring physical device access +- Social engineering or phishing +- Denial of service via resource exhaustion on self-hosted instances +- Vulnerabilities in third-party browser extensions or websites + +--- ## Reporting a Vulnerability -If you discover a security vulnerability within KoalaSync (e.g., related to the Node.js relay server, WebSocket wire protocol, or the Chrome/Firefox browser extension), please **DO NOT** report it by creating a public GitHub issue. +> [!CAUTION] +> **Do NOT open a public GitHub issue for security vulnerabilities.** Public disclosure before a patch is available puts users at risk. -Publicly disclosing a vulnerability before a patch is available puts our users at risk. Instead, please send an email privately to the project administrator at: -**koalasync_admin@koalamail.rocks** +Instead, email the project maintainer privately: -### What to expect -1. **Acknowledgment**: You should receive an acknowledgment of your report within 48 hours. -2. **Investigation**: We will investigate the issue, confirm its severity, and work on a patch. -3. **Resolution**: We will notify you when the patch is deployed to the Chrome Web Store, Mozilla Add-on Store, and our GitHub Docker releases. -4. **Disclosure**: Once the fix is confirmed and users have had time to update, we will publicly acknowledge your contribution in our release notes (unless you prefer to remain anonymous). +**`koalasync_admin@koalamail.rocks`** + +Encrypt sensitive findings with our PGP key (available on request). + +### What to Include + +- **Affected component**: Server / Extension / Website / Protocol +- **Steps to reproduce**: Clear, minimal steps to trigger the vulnerability +- **Impact**: What an attacker could achieve (data access, privilege escalation, etc.) +- **Environment**: Browser version, extension version, server configuration +- **Suggested fix** (optional): If you have ideas for a patch + +### What to Expect + +| Timeline | Action | +|----------|--------| +| **Within 48 hours** | Acknowledgment of your report | +| **Within 7 days** | Initial assessment and severity confirmation | +| **As needed** | Collaborative discussion for clarification | +| **After patch** | Notification that the fix is deployed | +| **After rollout** | Public acknowledgment in release notes (or anonymity if preferred) | + +--- + +## Architecture & Threat Model + +KoalaSync's security is grounded in its architecture: + +- **RAM-only relay**: No database, no persistent logs. All session data evaporates on disconnect. +- **bcrypt room passwords**: Plaintext passwords never stored. Brute-force protection: 5 attempts → 15-minute IP lockout. +- **Rate limiting**: Connection rate (IP-based, 60s window) and event rate (per-socket, 10s window). +- **URL-hash credential isolation**: Invitation credentials live in the URL fragment (`#join:...`) — never sent to the web server. +- **Strict CSP**: `default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'none'`. +- **No third-party requests**: Zero CDNs, fonts, analytics, or external scripts. + +If you find a way to bypass any of these protections, we want to know about it. + +--- + +## Responsible Disclosure + +We follow the principle of **coordinated vulnerability disclosure**: + +1. You report privately. +2. We investigate and develop a patch. +3. We deploy to the Chrome Web Store, Firefox Add-ons, and Docker registry. +4. We credit you publicly (unless you prefer to remain anonymous). + +We do not pursue legal action against researchers who act in good faith and follow this disclosure process.