Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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).
10 changes: 8 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,11 @@ Artifacts land in `release/`:
- `ZeroGFileMan-<version>-Setup.exe` — NSIS installer (choose install dir)
- `ZeroGFileMan-<version>-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

Expand All @@ -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)
33 changes: 33 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -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).
2 changes: 1 addition & 1 deletion src/shared/speech-server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -235,7 +235,7 @@ export async function transcribeViaServer(
fetchImpl: typeof fetch = fetch
): Promise<string> {
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');
Expand Down
Loading