feat: cookie Secure conditionnel + sous-commande d'installation de service
Cookie: routes/auth.ts pose `secure` sur le cookie de session quand la requête arrive en HTTPS (x-forwarded-proto), sans trustProxy — durcit le cookie derrière Tailscale Serve sans casser le localhost http. Install: nouveau cli/install.ts + routeur de sous-commandes dans index.ts (install/uninstall/status/serve). Service utilisateur systemd (Linux) ou launchd (macOS), bootstrap du token, --dry-run/--no-enable. Rétrocompat stricte du daemon par défaut (runDaemon extrait). Tests: app.e2e (cookie Secure local vs HTTPS) + cli-install (fonctions pures). 203/203 verts, acceptation P1/P4 vertes. Docs: README.md + README.fr.md (installeur multi-OS, distinction utiliser/cloner, modèle de sécurité durci). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
55
README.md
55
README.md
@@ -42,6 +42,11 @@ A single Node.js daemon you run on your dev machine (`npx @johanleroy/git-arbore
|
||||
|
||||
## Quick start
|
||||
|
||||
Two paths, depending on what you want:
|
||||
|
||||
- **Just use it (most people).** Arboretum is a published npm package — you **don't need to clone this repo**. Point npm at the registry and run it (below). Do this on the machine where your Claude Code sessions run.
|
||||
- **Run from source.** Clone the repo only to hack on Arboretum or run an unreleased build.
|
||||
|
||||
### Run it (recommended)
|
||||
|
||||
Arboretum is published to a self-hosted Gitea npm registry. Point the `@johanleroy` scope at it once per machine — add to `~/.npmrc`:
|
||||
@@ -70,8 +75,17 @@ On first start, Arboretum prints a one-time **access token** and the URL to open
|
||||
|
||||
Open the URL, paste the token to log in, and you're in. The token is stored **hashed** — it is shown only once, so save it somewhere safe (a password manager). You can manage tokens later from **Settings**.
|
||||
|
||||
`npx` fetches and runs the latest published version each time. To install it once — and get the `arboretum` command on your `PATH`, which the [background service](#running-it-as-a-background-service) relies on — install it globally instead:
|
||||
|
||||
```bash
|
||||
npm i -g @johanleroy/git-arboretum
|
||||
arboretum # identical to the npx command, from the installed binary
|
||||
```
|
||||
|
||||
### Run from source
|
||||
|
||||
Only needed to **develop** Arboretum or run an unreleased build — not required just to use it. Clone the repo, install dependencies, build, then start the daemon:
|
||||
|
||||
```bash
|
||||
git clone https://git.lidge.fr/johanleroy/arboretum.git
|
||||
cd arboretum
|
||||
@@ -110,7 +124,26 @@ Open `https://<machine>.<tailnet>.ts.net` from any device on your tailnet. **Web
|
||||
|
||||
## Running it as a background service
|
||||
|
||||
For a daemon that survives logout and restarts on boot, run it under a **systemd user service**. Install a pinned version globally (`npm i -g @johanleroy/git-arboretum`), then create `~/.config/systemd/user/arboretum.service`:
|
||||
The quickest way to run Arboretum as a service that survives logout and restarts on boot is the built-in installer. Install a pinned version globally, then run `install` — it detects your OS, writes the service file, starts it, and prints the one-time token:
|
||||
|
||||
```bash
|
||||
npm i -g @johanleroy/git-arboretum
|
||||
arboretum install --allow-origin https://MACHINE.TAILNET.ts.net
|
||||
```
|
||||
|
||||
This sets up a **systemd user service** on Linux (`~/.config/systemd/user/arboretum.service`) or a **launchd LaunchAgent** on macOS (`~/Library/LaunchAgents/fr.lidge.arboretum.plist`). Every daemon flag (`--port`, `--allow-origin`, `--db`, …) is propagated to the service. Manage it with:
|
||||
|
||||
```bash
|
||||
arboretum status # service status (+ where to read logs)
|
||||
arboretum uninstall # stop and remove the service
|
||||
```
|
||||
|
||||
Logs live in `journalctl --user -u arboretum -f` (Linux) or `~/Library/Logs/arboretum/` (macOS). Run `arboretum install --dry-run …` first to print the unit/plist and the exact commands without touching anything.
|
||||
|
||||
<details>
|
||||
<summary>Prefer to set up systemd by hand? (Linux)</summary>
|
||||
|
||||
Create `~/.config/systemd/user/arboretum.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
@@ -137,12 +170,15 @@ systemctl --user enable --now arboretum
|
||||
loginctl enable-linger "$USER" # start the service at boot, without an open session
|
||||
journalctl --user -u arboretum -f # logs
|
||||
```
|
||||
</details>
|
||||
|
||||
> The one-time **access token is printed only on the very first run** (empty database). When running as a service, capture it from `journalctl`, or do one manual run before enabling the service. The token is hashed and never shown again.
|
||||
> The one-time **access token is printed by `arboretum install`** (and on the very first manual run with an empty database). The token is hashed and never shown again — store it safely.
|
||||
|
||||
## Configuration
|
||||
|
||||
All options are CLI flags:
|
||||
Commands: `arboretum` starts the daemon (the default), `arboretum serve` is an explicit alias, `arboretum install` / `uninstall` / `status` manage the background service, and `arboretum help` prints usage.
|
||||
|
||||
Daemon options are CLI flags:
|
||||
|
||||
| Flag | Default | Description |
|
||||
|---|---|---|
|
||||
@@ -154,6 +190,15 @@ All options are CLI flags:
|
||||
| `--print-token` | `false` | Hint about token re-printing (tokens are hashed and cannot be re-shown). |
|
||||
| `--i-know-this-exposes-a-terminal` | `false` | Acknowledge binding to a non-loopback address. **Avoid** — prefer Tailscale Serve. |
|
||||
|
||||
`arboretum install` accepts every daemon flag above (propagated verbatim to the service) plus:
|
||||
|
||||
| Flag | Description |
|
||||
|---|---|
|
||||
| `--bin-path <path>` | Use this binary in the service instead of `node` + the bundled script. |
|
||||
| `--label <id>` | launchd label (macOS only, default `fr.lidge.arboretum`). |
|
||||
| `--dry-run` | Print the unit/plist and commands without applying anything. |
|
||||
| `--no-enable` | Write the service file but do not enable/start it. |
|
||||
|
||||
State (the SQLite database) lives in `$XDG_DATA_HOME/arboretum` (default `~/.local/share/arboretum`).
|
||||
|
||||
## Security model
|
||||
@@ -162,9 +207,9 @@ A web terminal is remote code execution *by design*. Arboretum's guardrails are
|
||||
|
||||
- Binds to `127.0.0.1` by default; refuses non-loopback binds without an explicit flag.
|
||||
- Authenticates **every** `/api/**` request **and** every `/ws` upgrade with revocable tokens, and applies a **strict `Origin` check** (the `SameSite=Strict` cookie does not cover WebSocket upgrades — this is the anti cross-site hijacking guard).
|
||||
- Tokens are stored **hashed** (sha256) and compared in constant time; the bootstrap token is shown only once. The session cookie is an HMAC-signed payload. Login is rate-limited with exponential backoff.
|
||||
- Tokens are stored **hashed** (sha256) and compared in constant time; the bootstrap token is shown only once. The session cookie is an HMAC-signed payload, `HttpOnly` and `SameSite=Strict`, and it automatically gains the `Secure` flag when the request arrives over HTTPS (e.g. behind Tailscale Serve). Login is rate-limited with exponential backoff.
|
||||
|
||||
The recommended way to reach Arboretum from other devices is Tailscale Serve (valid HTTPS, tailnet identity, no open ports). Never expose it directly to the internet.
|
||||
Tailscale Serve is **the** way to reach Arboretum from other devices — not just a recommendation: valid HTTPS, tailnet identity, no open ports. The `--i-know-this-exposes-a-terminal` flag is an escape hatch, not a deployment mode; never expose Arboretum directly to the internet.
|
||||
|
||||
## What makes it different
|
||||
|
||||
|
||||
Reference in New Issue
Block a user