FileSync - Moses Yebei

The Problem

Large files still need a quick, private way to move from one browser to many others without installing software or trusting a third‑party cloud. Existing services either require accounts, impose size caps, or route data through a central server that can see the contents.

What This Does

FileSync implements a peer‑to‑peer, WebRTC‑based file‑transfer hub. The browser UI lives in web/index.html and its logic under web/js/modules/webrtc/. Signalling is handled by the tiny Python server in api/main.py and api/signaling.py. Docker makes the whole stack portable (Dockerfile, deploy/docker-compose.yml). The repo ships a ready‑to‑run Docker image, a Caddy‑based HTTPS front‑end, and an optional password‑protected “room”.

How It Is Wired

Entry point – The container starts the Python signalling server (api/main.py). This process listens for WebSocket connections from the browser clients.
WebRTC setup – In the browser, web/js/modules/webrtc/user.js (967 LOC) creates a RTCPeerConnection, configuring ICE via web/js/modules/webrtc/turn.js and web/js/modules/webrtc/mode.js. It then hands the connection to web/js/modules/webrtc/file.js which streams incoming blobs directly to disk using the File System Access API.
Call hot‑spots – The internal call graph shows 763 resolved edges. Functions on, makeError, ge, e, n, r, trigger, hide, showToast, and _ are each called from 10‑13 distinct places, giving them the widest blast radius. show → trigger appears 10 times, and _setListeners → on appears 8 times, indicating that event‑listener wiring is a central concern.
External effects – The only filesystem writes are in the E2E harness (e2e/run.mjs) via fsp.copyFile and fsp.readFile. The production code does not write to the server’s filesystem; all file data stays in the browser, satisfying the “private by design” claim.
Module hubs – web/js/modules/webrtc/user.js imports 7 other modules (instability 0.88) and is the biggest source of cross‑module coupling. web/js/modules/webrtc/file.js imports 5 modules (instability 0.83). Both are candidates for refactoring to reduce cognitive load.
Unmapped paths – The static analysis could not resolve framework callbacks (e.g., React render) that eventually trigger the WebRTC flow, so those edges are not shown.

How To Use It

# 1. Clone the original repository
git clone https://github.com/moses-y/FileSync.git
cd FileSync

# 2. Generate a secret key (required for TURN auth)
python3 -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"
#   → copy the output

# 3. Insert the secret into the compose file (replace both placeholders)
sed -i "s|<SECRET_KEY>|YOUR_GENERATED_KEY|g" deploy/docker-compose.yml

# 4. Build and run the stack
docker compose -f deploy/docker-compose.yml up -d

The service becomes reachable at http://localhost (or the host’s IP). Open that URL in a modern browser, create a room, share the link/QR, and drag‑drop files. For public HTTPS deployments, follow the same steps with deploy/docker-compose-ssl.yml and configure Caddy as described in the README.

Real‑World Use

A small design studio wants to exchange multi‑gigabyte video drafts between on‑site editors and remote reviewers. They spin up FileSync on a local machine, generate a secret key, and run the Docker compose file. Reviewers open the shared link in Chrome, receive streamed files directly to their download folder, and no corporate file‑share server sees the content.

Code Health & Issues

High – Pin third‑party GitHub Actions to a commit SHA (.github/workflows/*).
Medium – Declare least‑privilege permissions for GITHUB_TOKEN (.github/workflows/checks.yml).
Medium – Pin the Docker base image by digest (Dockerfile).
Medium – Add a dependency‑vulnerability scan step to CI (.github/workflows/*).
Medium – Set persist-credentials: false on the checkout step (.github/workflows/checks.yml).
Medium – Add a non‑root USER to the container (Dockerfile).
Low – Specify timeout-minutes on workflow jobs (.github/workflows/checks.yml).
Low – Add repository convention files (.editorconfig, .gitattributes, formatter config).

Static analysis also flagged three medium‑severity maintainability concerns: broad exception handling in api/signaling.py, high branching density in several WebRTC modules, and the oversized web/js/modules/webrtc/user.js. No critical defects were found, and the repository includes tests, CI, a license, and a lockfile.

The Bottom Line

FileSync delivers a functional, Docker‑ready peer‑to‑peer file‑transfer service with a clean browser UI, but the JavaScript core is tightly coupled and cognitively dense. Security‑focused teams will appreciate the minimal server surface, yet they should address the high‑impact CI hardening issues and consider refactoring the large WebRTC modules before extensive customization. Suitable for teams comfortable with Docker and willing to invest in modest code‑base cleanup.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

44 files

JavaScript13
YAML6
Markdown2
Python2
JSON2
CSS2

ReactDocker

Module dependencies

The 10 most depended-upon modules of 16, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_web_js_modules_sink["sink"] n1_web_js_modules_webrtc_mode["mode"] n2_web_js_modules_dom["dom"] n3_web_js_modules_devBadge["devBadge"] n4_web_js_modules_webrtc_peer["peer"] n5_web_js_modules_webrtc_turn["turn"] n6_web_js_modules_webrtc_user["user"] n7_web_js_modules_webrtc_file["file"] n8_api_signaling["signaling"] n9_eb_js_vendors_client_zip_min["client-zip.min"] n0_web_js_modules_sink --> n3_web_js_modules_devBadge n7_web_js_modules_webrtc_file --> n2_web_js_modules_dom n7_web_js_modules_webrtc_file --> n5_web_js_modules_webrtc_turn n7_web_js_modules_webrtc_file --> n1_web_js_modules_webrtc_mode n7_web_js_modules_webrtc_file --> n4_web_js_modules_webrtc_peer n7_web_js_modules_webrtc_file --> n0_web_js_modules_sink n1_web_js_modules_webrtc_mode --> n3_web_js_modules_devBadge n6_web_js_modules_webrtc_user --> n2_web_js_modules_dom n6_web_js_modules_webrtc_user --> n5_web_js_modules_webrtc_turn n6_web_js_modules_webrtc_user --> n1_web_js_modules_webrtc_mode n6_web_js_modules_webrtc_user --> n7_web_js_modules_webrtc_file n6_web_js_modules_webrtc_user --> n4_web_js_modules_webrtc_peer n6_web_js_modules_webrtc_user --> n0_web_js_modules_sink n6_web_js_modules_webrtc_user --> n9_eb_js_vendors_client_zip_min

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium5

low2

Pin third-party GitHub Actions to a commit SHAhigh5 occurrences

.github/workflows

dependabot/fetch-metadata@v3, docker/login-action@v4.6.0, docker/metadata-action@v6, docker/setup-buildx-action@v4

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/checks.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium2 occurrences

Dockerfile

python:3.14-alpine, python:3.14-alpine

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/checks.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/checks.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.