mirror of https://github.com/Shik3i/KoalaSync.git synced 2026-07-26 12:08:15 +00:00

Files

T

MacBook 5157428e74 docs: comprehensive repository polish + step-by-step user guide

Documentation Rewrites:
- AI_INIT.md: fix duplicate section numbers, add file responsibility map,
  fix stale manual mirror instruction, add room ID constraint
- PRIVACY.md: add TL;DR statement, data retention table, explicit
  <all_urls> justification, self-hosted instance disclaimer
- CONTRIBUTING.md: add local testing guide, version warning, room ID
  constraint, bug report requirements
- shared/README.md: complete event table (all 15 events), fix stale
  manifest.json reference
- docs/SYNC_GUIDE.md: Chrome→Browser, add README.md to sync list,
  drop stale RC5 reference
- server/README.md: sync env defaults with .env.example (1000/50)

New Documentation:
- docs/HOW_IT_WORKS.md: 10-step walkthrough covering room creation,
  invitation bridge flow, synchronized playback, force sync protocol,
  heartbeat system, and episode auto-sync. Includes exact data payloads.

Infrastructure Cleanup:
- docker-compose.yml: remove deprecated version key
- .dockerignore: remove dead .bat/.sh patterns
- README.md: add self-hosting extension config tip, link HOW_IT_WORKS

2026-05-04 05:41:43 +02:00

4.4 KiB

Raw Blame History

Privacy Policy

KoalaSync does not collect, store, or sell any personal data.

KoalaSync is designed with a Security-First & Volatile architecture. This means we prioritize keeping your data out of persistent storage, though certain technical data must be processed temporarily to ensure service stability and security.

1. Data Processing (In-Memory Only)

KoalaSync does not use a database. All active session data exists only in the server's RAM and is purged immediately when no longer needed.

Session Data: To synchronize playback, the server must temporarily hold your peerId, username, and the title of the video you are watching. Additionally, playback metadata (mediaTitle, playbackState, currentTime, volume, muted) is held per peer for the duration of the session. All of this is deleted as soon as you leave the room.
Room Passwords: If you set a room password, it is stored only as a secure bcrypt hash in RAM. The server never sees or stores your plaintext password.
Routing Maps: The server maintains ephemeral lookup tables (socketToRoom, peerToSocket) to route messages between peers. These contain only transport identifiers and are purged on disconnect.

Data Retention

Data Type	Maximum Retention	Trigger for Deletion
Session data (peerId, username, video metadata)	Duration of session	User leaves room or disconnects
Room state	2 hours max	Last peer leaves, or inactivity timeout
Failed auth lockout records	15 minutes	Automatic expiry
Auth failure records	1 hour	Periodic cleanup
Connection rate-limit counters	60 seconds	Automatic expiry
Event rate-limit counters	10 seconds	Automatic expiry + periodic cleanup

2. Security & Rate Limiting

To prevent abuse and brute-force attacks, the following data is processed:

Brute-Force Protection: If multiple failed password attempts are detected, the server stores the IP address and Room ID in a temporary RAM-based lockout list for a maximum of 15 minutes.
Connection Rate Limiting: IP addresses are tracked for 60 seconds to prevent connection-flooding (DoS) attacks.
Event Rate Limiting: Per-socket event counters are tracked for 10-second windows to prevent event-spamming. These are keyed by ephemeral socket IDs and cleaned up periodically.
Console Logging: The official relay server (sync.shik3i.net) outputs connection events (including IP addresses) to the server console for real-time monitoring. These logs are ephemeral and are not archived, sold, or linked to any persistent user identity.

3. Extension Permissions

The browser extension requires the following permissions:

storage: To remember your local preferences (username, server URL, room settings).
tabs & scripting: To detect and control video elements on the pages you choose to sync.
<all_urls> (host permission): Required to detect <video> elements on any website the user chooses to synchronize. The extension only activates on the specific tab the user has actively selected — it does not scan, monitor, or interact with any other tabs or pages.
alarms: To keep the background service worker alive during active sync sessions.
notifications: To display sync status updates (e.g., "Peer joined", "Force Sync initiated").
No History Access: We do not read, store, or transmit your browsing history. We only interact with the specific tab you have actively selected for synchronization.

4. Zero Third-Party Requests

KoalaSync is completely self-contained:

No CDNs or External Libraries: All scripts and styles are self-hosted.
No Analytics: We do not use Google Analytics, tracking pixels, or any third-party telemetry.
No External Fonts: We use system font stacks to prevent tracking via font services.

5. Self-Hosted Instances

This privacy policy applies to the official KoalaSync relay server at sync.shik3i.net. If you choose to self-host a relay server using our open-source Docker image, the data handling practices of that instance are the responsibility of the server operator.

Auditable & Open Source: Because KoalaSync is open source, you can verify these claims by reviewing the Server Source Code and the Extension Logic.

4.4 KiB Raw Blame History