From 004cc3a3ee31936f49bc97a682bb44c1e0268539 Mon Sep 17 00:00:00 2001
From: luxick <git@luxick.de>
Date: Mon, 5 Jan 2026 13:18:04 +0100
Subject: [PATCH] Add Readme

---
 README.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8c14268
--- /dev/null
+++ b/README.md
@@ -0,0 +1,113 @@
+# luxtools-client
+
+Small local HTTP helper that lets the Dokuwiki plugin `luxtools` open folders on the same machine.
+
+This program runs on the user’s machine and listens on a loopback address only (defaults to `127.0.0.1:8765`). The plugin calls it to open a folder in the OS file manager.
+
+## What it does
+
+- Exposes `GET /health` for a simple health check.
+- Exposes `GET /open?path=...` and `POST /open` to open a folder.
+- Normalizes and validates the requested path:
+  - Accepts absolute paths only.
+  - If a file path is provided, it opens the containing directory.
+  - Accepts `file://...` URLs (handy when the caller passes a file URL).
+- Optionally restricts which folders can be opened via `-allow` prefixes.
+
+## Build
+
+Requires Go 1.22+.
+
+```bash
+go build -o luxtools-client .
+```
+
+## Run
+
+```bash
+./luxtools-client
+```
+
+On startup, if you don’t pass `-token`, the server generates a random token and prints it to the logs. Put that token into the Dokuwiki plugin configuration.
+
+### Flags
+
+- `-listen` (default `127.0.0.1:8765`): listen address (`host:port`). Must be loopback.
+- `-token` (default empty): shared secret token. If empty, a token is generated and logged at startup.
+- `-allow` (repeatable): allowed path prefix. If you specify one or more, the requested path must start with one of them.
+
+Examples:
+
+```bash
+# Listen on a different local port
+./luxtools-client -listen 127.0.0.1:9000
+
+# Use an explicit token (recommended for stable config)
+./luxtools-client -token "your-shared-secret"
+
+# Restrict opens to your home directory (repeat -allow as needed)
+./luxtools-client -allow "$HOME"
+```
+
+## API
+
+### Auth
+
+Requests must include the token using the `X-Filetools-Token` header.
+
+- Header: `X-Filetools-Token: <token>`
+- For `GET /open`, a `token=...` query parameter is also accepted as a fallback.
+
+### `GET /health`
+
+Returns JSON:
+
+```json
+{"ok": true, "time": "2026-01-05T12:34:56Z"}
+```
+
+### `POST /open`
+
+Request body:
+
+```json
+{"path": "/absolute/path"}
+```
+
+Response:
+
+```json
+{"ok": true, "message": "opened"}
+```
+
+Example:
+
+```bash
+curl -sS -X POST \
+  -H 'Content-Type: application/json' \
+  -H 'X-Filetools-Token: your-shared-secret' \
+  --data '{"path":"/tmp"}' \
+  http://127.0.0.1:8765/open
+```
+
+### `GET /open?path=...`
+
+For GET callers, success returns `204 No Content` (to reduce console noise in certain callers).
+
+Example:
+
+```bash
+curl -i \
+  -H 'X-Filetools-Token: your-shared-secret' \
+  'http://127.0.0.1:8765/open?path=/tmp'
+```
+
+## OS support
+
+- Linux: uses `xdg-open`.
+- Windows: uses `explorer.exe`.
+
+## Notes / security
+
+- The server refuses to bind to non-loopback addresses.
+- Use `-allow` to prevent opening arbitrary folders if other local processes can reach the port.