From c9c9309f921f516588fcbb08d8b261b22b0baf53 Mon Sep 17 00:00:00 2001 From: Stephen Phillips Date: Tue, 10 Nov 2026 10:56:51 +0000 Subject: [PATCH] docs: add SECURITY and CONTRIBUTING, note unsigned builds - SECURITY.md: private reporting, security model, where data goes (src/shared/endpoints.ts already pointed at this file) - CONTRIBUTING.md: setup, `npm run ci`, IPC and docs rules - README: unsigned-build SmartScreen note, link new docs - Replace a LAN IP in a speech-server error example with loopback Co-Authored-By: Claude Opus 5.5 --- CONTRIBUTING.md | 32 ++++++++++++++++++++++++++++++++ README.md | 10 ++++++++-- SECURITY.md | 33 +++++++++++++++++++++++++++++++++ src/shared/speech-server.ts | 2 +- 4 files changed, 74 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..92a2122 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,32 @@ +# Contributing + +Thanks for taking a look. Issues and pull requests are welcome. This is a spare-time project, so reviews may take a while. + +## Getting started + +Requires Node.js 22 and npm. + +```bash +npm install +npm run build +npm start +``` + +See the [README](README.md) for the dev loop (`npm run dev` plus `npm start`). + +## Before opening a PR + +```bash +npm run ci # typecheck + unit tests + build, the same as GitHub Actions +``` + +Then try the change in the running app: both panes, and the voice jewels if you touched speech. + +## Guidelines + +- **Small vertical slices.** One behaviour per PR, with tests for pure logic in `tests/`. +- **IPC rules are non-negotiable.** The renderer only uses `window.fileman`. New file operations take absolute paths that main validates with `resolveLocalPath`. Secrets never cross to the renderer. See [SECURITY.md](SECURITY.md). +- **Docs move with code.** If you change a decision, add or update an ADR in [`docs/adr/`](docs/adr/). If you finish a roadmap item, update [ROADMAP.md](ROADMAP.md). +- **Security issues** go through private reporting, not public issues. See [SECURITY.md](SECURITY.md). + +By contributing, you agree that your contributions are licensed under the [MIT License](LICENSE). diff --git a/README.md b/README.md index 83ab52f..15f520f 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,11 @@ Artifacts land in `release/`: - `ZeroGFileMan--Setup.exe` — NSIS installer (choose install dir) - `ZeroGFileMan--Portable.exe` — portable single file -Unsigned by default (`signAndEditExecutable: false`). App id: `com.happymonkeyai.zerogfileman`. Window/installer icon lives in `build/` (`npm run icon:render` regenerates png/ico from the SVG). +Packaged builds are Windows x64 only for now. + +> **Unsigned builds.** The executables are not code-signed, so Windows SmartScreen will show "Windows protected your PC" the first time you run one. Choose **More info → Run anyway**, or build from source if you'd rather not trust a downloaded binary. + +Signing is off (`signAndEditExecutable: false`). App id: `com.happymonkeyai.zerogfileman`. Window/installer icon lives in `build/` (`npm run icon:render` regenerates png/ico from the SVG). ## What it does @@ -60,7 +64,9 @@ Unsigned by default (`signAndEditExecutable: false`). App id: `com.happymonkeyai | [ROADMAP.md](ROADMAP.md) | Next slices (layouts, view modes, CI) | | [MCP.md](MCP.md) | Intent → MCP routing | | [docs/adr/](docs/adr/) | Decisions | +| [CONTRIBUTING.md](CONTRIBUTING.md) | How to build, test and send a PR | +| [SECURITY.md](SECURITY.md) | Reporting vulnerabilities; what leaves your machine | ## License -MIT +[MIT](LICENSE) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..e113a8e --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,33 @@ +# Security + +## Reporting a vulnerability + +Please report security issues privately through GitHub: **Security → Report a vulnerability** on this repository. Do not open a public issue for anything exploitable. + +Include what you found, how to reproduce it, and the version or commit. This is a personal project maintained in spare time, so expect a reply within a couple of weeks, not hours. + +Only the latest commit on `main` is supported. + +## Security model + +ZeroG FileMan is a local Electron app. It works on your own files with your own user permissions. These rules hold: + +- **Renderer isolation.** The page talks to the app only through the `window.fileman` preload bridge. The main process validates every path it is given (`resolveLocalPath`) before touching the filesystem, and the window refuses to navigate away from the app's own origin. +- **No shell interpolation.** External programs, such as a terminal opened at a folder, are spawned with argument arrays, never through a shell string. +- **Secrets stay in main.** The optional speech server API key is encrypted with Electron `safeStorage`. The renderer can save, clear or check the key, but cannot read it back. If OS encryption is unavailable, the key is held in memory only and never written to disk. +- **Narrow network surface.** The page CSP allows `fetch` connections only to the app itself and to the Hugging Face hosts that the built-in Whisper engine downloads its model from (once, then cached). The UI fonts (Inter, JetBrains Mono) load from Google Fonts. Requests to a user-configured speech server are made by the main process (see [ADR-0005](docs/adr/0005-server-speech-requests-in-main.md)). + +### Where your data goes + +| Speech engine | Audio leaves the machine? | +|---------------|---------------------------| +| Demo (typed transcript) | No | +| Built-in Whisper | No. Only the model download contacts Hugging Face. | +| OpenAI-compatible server | Yes, to the URL you configure, along with your API key if one is set. Use `https` for anything not on this machine. | + +There is no telemetry. Other than the font and model downloads and your configured speech server, the app makes no network requests. + +## Out of scope + +- Anything that requires an attacker who already runs code as your user. +- Unsigned Windows builds triggering SmartScreen (see the README). diff --git a/src/shared/speech-server.ts b/src/shared/speech-server.ts index 34d0e4e..4b68b31 100644 --- a/src/shared/speech-server.ts +++ b/src/shared/speech-server.ts @@ -235,7 +235,7 @@ export async function transcribeViaServer( fetchImpl: typeof fetch = fetch ): Promise { if (!isSupportedEndpoint(request.url)) { - throw new Error('Speech server URL must be an http:// or https:// address, e.g. http://10.0.10.46:8888/v1/audio/transcriptions'); + throw new Error('Speech server URL must be an http:// or https:// address, e.g. http://127.0.0.1:8080/v1/audio/transcriptions'); } if (!request.model.trim()) { throw new Error('Speech server model name is required');