Development

Development

Contributions are welcome: reports from real TVs, fixes, docs and translations. The ground rules are in CONTRIBUTING.md.

How it fits together

TV app (webos-app/src, ES5)
   │  runs commands through the Homebrew Channel's exec service, as root
   ▼
ssh-doctor.sh (POSIX sh for busybox)
   │  checks, repairs, settings, startup hook
   ├─► dropbear, authorized_keys, /etc/shadow copy, /var/lib/webosbrew
   └─► pair-server.js (Node.js on the TV, only while pairing)
          ▲
          │  http://TV:28622
   pair.html + pair.js + sshkey.js + sha512crypt.js (ES5, any phone browser)

File	What it is
ssh-doctor.sh	Every check and repair, one POSIX sh file. Commands answer in text or --json
webos-app/src/	The TV app: index.html, app.js, style.css, i18n.js
pair-server.js	The pairing page's server. Checks the code, takes one public key or password hash, waits for OK on the TV
pair.html, pair.js	The page a phone or computer opens
sshkey.js	Makes Ed25519 key pairs in the browser with TweetNaCl, in OpenSSH's format
sha512crypt.js	SHA-512 crypt ($6$), so passwords are hashed before they leave the screen
keyinfo.js	Reads public key lines and works out fingerprints, for the pairing server
tests/	The fake TV and every check

Building and testing

No TV needed:

sh tests/run.sh busybox          # the script against a fake TV (also dash and bash)
shellcheck -s sh ssh-doctor.sh tests/fakebin/* webos-app/build.sh
node tests/check-i18n.js         # every text in the TV app translated
sh webos-app/build.sh            # the IPK (needs ares-package from @webos-tools/cli)
node tests/check-sshkey.js .cache/tweetnacl-1.0.3-nacl-fast.min.js      # browser keys work with ssh-keygen
node tests/check-sha512crypt.js .cache/tweetnacl-1.0.3-nacl-fast.min.js # hashes match glibc crypt()
node tests/ui-check.js           # TV screens and the pairing page in a browser (Playwright)

tests/run.sh builds a fake TV in a temporary folder (its own /proc, /etc/shadow, Homebrew Channel and authorized_keys) by pointing SD_ROOT at it, so it needs no root and changes nothing on your machine.

Ground rules, short version

• Never leave someone with no way in.
• Only the Homebrew Channel's SSH. Detect others, never change them.
• No writes to system partitions.
• Passwords never travel or rest in the clear.
• POSIX sh (ShellCheck clean) and ES5 only.
• A test for every change in behavior.
• Plain words for TV owners, two spaces between sentences, no em dashes.

Translating

The TV app speaks English, Russian and Spanish, picked from the TV's menu language. Every string is in webos-app/src/i18n.js. To add a language, add its table there, run node tests/check-i18n.js until nothing is missing, and open a pull request. Native speakers checking the existing ones are just as welcome.

AI-assisted pull requests

Welcome, held to the same standard: say AI was used, review every change yourself, and test it on a real TV. Coding agents read AGENTS.md by themselves.

Releases

Pushing a v* tag runs the tests, builds the IPK, publishes it with its Homebrew Channel manifest, ssh-doctor.sh and SHA256SUMS, and refreshes the ohmybahgosh.dev repository.