daniel156161
cea8a7e994
- Add the n8n community node package with credentials, command mapping, direct serve TCP client, and browser-cli protocol crypto helpers. - Cover Ed25519 signing, canonical JSON, PQ transport encryption, request mapping, and security behavior with unit tests. - Harden serve-http with per-address rate limiting, an 8 MB request body cap, and clear warnings when binding plain HTTP beyond loopback. - Stop one-shot --key overrides from being persisted automatically; document explicit remote trust and keep key-management behind the keys policy tier. - Make HTML-to-Markdown conversion safer by bounding tree depth and dropping unsafe link/image URL schemes. - Bump package and extension release metadata to 0.16.3.
91 lines
4.3 KiB
Markdown
91 lines
4.3 KiB
Markdown
# n8n-nodes-browser-cli
|
|
An [n8n](https://n8n.io) community node that controls a **real, visible browser**
|
|
from your workflows via [browser-cli](https://chromewebstore.google.com/detail/browser-cli/hekaebjhbhhdbmakimmaklbblbmccahp).
|
|
|
|
browser-cli drives a running browser through a native-messaging host and a
|
|
browser extension — it **cannot be installed inside the n8n container**. So this
|
|
node speaks the `browser-cli serve` protocol **directly**: a length-framed TCP
|
|
connection authenticated with an Ed25519 key, with request/response bodies
|
|
encrypted end-to-end via an ML-KEM-768 (post-quantum) key exchange — the same
|
|
wire protocol the `browser-cli --remote` client uses.
|
|
|
|
```
|
|
n8n workflow ──TCP (Ed25519 + ML-KEM-768)──▶ browser-cli serve (remote host) ──▶ browser
|
|
```
|
|
|
|
Because the payloads are end-to-end encrypted, the endpoint is safe to expose on
|
|
an untrusted network without a TLS proxy in front of it.
|
|
|
|
## Remote setup (on the browser machine)
|
|
Install browser-cli, register the extension, trust your n8n key, then start
|
|
`serve` opening exactly the command tiers you need (it is **safe-only by default**):
|
|
|
|
```bash
|
|
uv tool install real-browser-cli
|
|
browser-cli install brave # one-time: register the extension/native host
|
|
|
|
# On the n8n side, generate a client key and print its public key:
|
|
browser-cli auth keygen -o n8n_key.pem
|
|
|
|
# On the browser machine, trust that public key (optionally scope its policy):
|
|
browser-cli auth trust <pubkey-hex> --allow-control
|
|
|
|
# Expose the browser. Open only what your workflow needs:
|
|
browser-cli serve --host 0.0.0.0 --port 8765 \
|
|
--authorized-keys ~/.browser_cli/authorized_keys --allow-read-page --allow-control
|
|
```
|
|
|
|
Paste the contents of `n8n_key.pem` into the n8n credential.
|
|
|
|
## n8n credential — "Browser CLI API"
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| Host | host of the `serve` endpoint, e.g. `browser-host.example` |
|
|
| Port | `serve` TCP port (default `8765`) |
|
|
| Ed25519 Private Key | PKCS8 PEM from `browser-cli auth keygen` (empty only for `--no-auth` loopback) |
|
|
| Browser Alias | optional `_route` target — required if the endpoint serves multiple browsers |
|
|
| Use TLS | wrap the connection in TLS (only for a TLS-terminating proxy; the protocol is already encrypted) |
|
|
| Ignore SSL Issues | when TLS is on, accept a self-signed proxy cert |
|
|
|
|
## Operations
|
|
Every operation maps to one raw browser-cli command, each subject to the server
|
|
policy tier noted below.
|
|
|
|
| Resource | Operation | Command | Server flag needed |
|
|
|----------|-----------|---------|--------------------|
|
|
| Tab | List | `tabs.list` | safe (default) |
|
|
| Tab | Open | `navigate.open` | `--allow-control` |
|
|
| Tab | Close | `tabs.close` (ids / inactive / duplicates) | `--allow-control` |
|
|
| Tab | Get HTML | `tabs.html` | `--allow-read-page` |
|
|
| Page | Get Info | `page.info` | safe (default) |
|
|
| Page | Extract Text / Links / Images / HTML / Markdown | `extract.*` | `--allow-read-page` |
|
|
| DOM | Query | `dom.query` | `--allow-read-page` |
|
|
| DOM | Click / Type | `dom.click` / `dom.type` | `--allow-control` |
|
|
| DOM | Eval | `dom.eval` | `--allow-dangerous` |
|
|
| Client | List | `clients.list` | safe (default) |
|
|
| Command | Execute | any command name + JSON args | per command |
|
|
| Gateway | Health | pings with `tabs.list` | safe (default) |
|
|
|
|
**Command → Execute** is the escape hatch: any command string the server policy
|
|
allows (`tabs.query`, `session.save`, `windows.list`, …) with a JSON args object.
|
|
Use it for anything the typed operations don't cover.
|
|
|
|
> Note: `serve` returns the **raw** command result (no SDK post-processing).
|
|
> `extract.markdown` therefore returns the page payload as the extension hands it
|
|
> back, not the CLI's rendered Markdown. For clean text use **Extract Text**.
|
|
|
|
## Develop / build
|
|
```bash
|
|
cd n8n-nodes-browser-cli
|
|
npm install # add --ignore-scripts if a transitive native dep
|
|
# (isolated-vm) fails to compile on your Node version
|
|
npm test # pure unit tests: command mapping + crypto known-answer vectors
|
|
npm run build # tsc -> dist/, copies the icon
|
|
```
|
|
|
|
Then install into n8n as a [community node](https://docs.n8n.io/integrations/community-nodes/installation/)
|
|
(`n8n-nodes-browser-cli`), or symlink `dist/` into `~/.n8n/custom` for local testing.
|
|
|
|
## License
|
|
PolyForm Noncommercial License 1.0.0 — same as browser-cli.
|