Skip to content

Security: WillBettleheim/Helios

Security

SECURITY.md

Security

HELIOS handles health information, so it is built to assume that files, servers and other web pages may be hostile. It is still a research prototype: nobody has independently audited it, and no software can be made impossible to hack. This page says what is protected, what isn't, and how to report a problem.

Reporting a vulnerability

Please don't open a public issue for a security problem. Use Report a vulnerability on the repository's Security tab, if it's available, or contact the maintainer privately through their GitHub profile.

Include what you found, how to reproduce it and the possible impact. Don't test against other people's data or devices.

What is protected

Attacks through the page

Risk Protection
Injected scripts (XSS) A Content Security Policy allows only the app's own scripts and blocks inline scripts and eval. All stored text is also escaped before display
Stolen data sent to another site The policy lets the page connect only to itself and this machine, and blocks loading images from elsewhere
Altered script or style files Each file has a Subresource Integrity hash, so the browser refuses a changed file
Being embedded in another site (clickjacking) The app stays hidden if it finds itself inside a frame
Leaks through links No referrer is sent, and there are no third-party scripts, fonts, analytics or dependencies

Malicious or damaged files

Risk Protection
Hostile backups, sync bundles or saved data Everything passes through a sanitizer that drops unknown fields, limits text, and checks numbers and dates
Prototype pollution Keys such as __proto__ and constructor are discarded
Crashes from malformed data Bad list entries are dropped, and an unreadable record is set aside so the next save can't overwrite it
Filling up storage Record counts and file sizes are limited
A backup redirecting your sync Restoring a backup never changes this device's settings, and only web addresses are accepted as a sync server

Your data at rest

Risk Protection
Someone reading the device's storage Optional privacy lock: AES-256-GCM, with a key from PBKDF2-SHA-256 at 600,000 iterations. Older records are strengthened on the next unlock
Someone at an unlocked screen Changing or removing the lock needs the current PIN. The app auto-locks when idle, including after the device sleeps
PIN guessing in the app Wrong attempts are limited, with waits that double. PINs need at least 6 characters
Readable backups Encrypted backups are available in Settings. A plain backup warns you first, since it includes your journal
Changed encrypted data AES-GCM detects tampering, and unusual encryption settings are refused

The sync relay

The relay only ever receives ciphertext, and it treats every request as hostile:

  • Listens on this machine unless told otherwise, and answers browsers only from allowed origins
  • Accepts only well-formed channel ids and bundles, with limits on request size, rate, devices, channels and total storage
  • Stores bundles so built-in property names can't be abused, in an owner-only file written atomically
  • Expires bundles after 90 days, times out slow connections, and sends safe response headers

The project

  • npm start serves on this machine only, so the files (including .git) aren't exposed to your network.
  • There are no runtime dependencies to compromise.
  • Attack tests in test/security.test.js run with npm test, and a GitHub workflow runs the tests and CodeQL scanning.
  • The offline cache stores only the app's own files.

What is not protected

Please read these before relying on HELIOS for anything sensitive.

  • Without a privacy lock, the record is plain text in the browser's storage.
  • A short PIN can be guessed offline. Someone who copies the encrypted record can try PINs on their own computer, where the attempt limit doesn't apply. Use a long passphrase. Clearing browser data also resets the in-app attempt limit.
  • A compromised device or browser defeats all of this. Malware, a malicious browser extension or someone with your unlocked device can read what you can read.
  • Whoever controls the server controls the app. A server that can change index.html could also change the security policy and the integrity hashes.
  • Some protections are weaker on static hosts. A policy set in the page can't include frame-ancestors, so the frame protection relies on JavaScript. Send the policy and frame-ancestors 'none' as HTTP headers where you can.
  • The relay has no user accounts. Knowing the channel id is the access control, and the id comes from a slow hash of the crew passphrase. A weak passphrase weakens it. A malicious relay can't read bundles, but it could withhold them or serve older ones.
  • Voice control sends audio to the browser's speech service. In Chrome this is processed online. It only runs if you turn it on.
  • Encryption needs a secure context, meaning https:// or localhost.

Running it safely

  1. Set a privacy lock with a long passphrase, and use the encrypted backup.
  2. Serve it over HTTPS, with the security headers set by the server.
  3. To use a relay on another machine:
    • Put it behind HTTPS.
    • Start it with HOST=0.0.0.0 ALLOW_ORIGIN=https://your-app-address node tools/sync-server.js.
    • Add the relay's https:// origin to connect-src in index.html, then run npm run version.
  4. Use a crew passphrase of several random words.

Checking it yourself

Run the attack tests along with the rest of the test suite:

npm test

Settings → Security status shows the current state on the device, including anything the page policy has blocked.

There aren't any published security advisories