durar-ai 2026.4.4

package/docs/gateway/tailscale.md

@@ -0,0 +1,136 @@
+---
+summary: "Integrated Tailscale Serve/Funnel for the Gateway dashboard"
+read_when:
+  - Exposing the Gateway Control UI outside localhost
+  - Automating tailnet or public dashboard access
+title: "Tailscale"
+---
+
+# Tailscale (Gateway dashboard)
+
+Durar can auto-configure Tailscale **Serve** (tailnet) or **Funnel** (public) for the
+Gateway dashboard and WebSocket port. This keeps the Gateway bound to loopback while
+Tailscale provides HTTPS, routing, and (for Serve) identity headers.
+
+## Modes
+
+- `serve`: Tailnet-only Serve via `tailscale serve`. The gateway stays on `127.0.0.1`.
+- `funnel`: Public HTTPS via `tailscale funnel`. Durar requires a shared password.
+- `off`: Default (no Tailscale automation).
+
+## Auth
+
+Set `gateway.auth.mode` to control the handshake:
+
+- `none` (private ingress only)
+- `token` (default when `Durar_GATEWAY_TOKEN` is set)
+- `password` (shared secret via `Durar_GATEWAY_PASSWORD` or config)
+- `trusted-proxy` (identity-aware reverse proxy; see [Trusted Proxy Auth](/gateway/trusted-proxy-auth))
+
+When `tailscale.mode = "serve"` and `gateway.auth.allowTailscale` is `true`,
+Control UI/WebSocket auth can use Tailscale identity headers
+(`tailscale-user-login`) without supplying a token/password. Durar verifies
+the identity by resolving the `x-forwarded-for` address via the local Tailscale
+daemon (`tailscale whois`) and matching it to the header before accepting it.
+Durar only treats a request as Serve when it arrives from loopback with
+Tailscale’s `x-forwarded-for`, `x-forwarded-proto`, and `x-forwarded-host`
+headers.
+HTTP API endpoints (for example `/v1/*`, `/tools/invoke`, and `/api/channels/*`)
+do **not** use Tailscale identity-header auth. They still follow the gateway's
+normal HTTP auth mode: shared-secret auth by default, or an intentionally
+configured trusted-proxy / private-ingress `none` setup.
+This tokenless flow assumes the gateway host is trusted. If untrusted local code
+may run on the same host, disable `gateway.auth.allowTailscale` and require
+token/password auth instead.
+To require explicit shared-secret credentials, set `gateway.auth.allowTailscale: false`
+and use `gateway.auth.mode: "token"` or `"password"`.
+
+## Config examples
+
+### Tailnet-only (Serve)
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "serve" },
+  },
+}
+```
+
+Open: `https://<magicdns>/` (or your configured `gateway.controlUi.basePath`)
+
+### Tailnet-only (bind to Tailnet IP)
+
+Use this when you want the Gateway to listen directly on the Tailnet IP (no Serve/Funnel).
+
+```json5
+{
+  gateway: {
+    bind: "tailnet",
+    auth: { mode: "token", token: "your-token" },
+  },
+}
+```
+
+Connect from another Tailnet device:
+
+- Control UI: `http://<tailscale-ip>:18789/`
+- WebSocket: `ws://<tailscale-ip>:18789`
+
+Note: loopback (`http://127.0.0.1:18789`) will **not** work in this mode.
+
+### Public internet (Funnel + shared password)
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "funnel" },
+    auth: { mode: "password", password: "replace-me" },
+  },
+}
+```
+
+Prefer `Durar_GATEWAY_PASSWORD` over committing a password to disk.
+
+## CLI examples
+
+```bash
+Durar gateway --tailscale serve
+Durar gateway --tailscale funnel --auth password
+```
+
+## Notes
+
+- Tailscale Serve/Funnel requires the `tailscale` CLI to be installed and logged in.
+- `tailscale.mode: "funnel"` refuses to start unless auth mode is `password` to avoid public exposure.
+- Set `gateway.tailscale.resetOnExit` if you want Durar to undo `tailscale serve`
+  or `tailscale funnel` configuration on shutdown.
+- `gateway.bind: "tailnet"` is a direct Tailnet bind (no HTTPS, no Serve/Funnel).
+- `gateway.bind: "auto"` prefers loopback; use `tailnet` if you want Tailnet-only.
+- Serve/Funnel only expose the **Gateway control UI + WS**. Nodes connect over
+  the same Gateway WS endpoint, so Serve can work for node access.
+
+## Browser control (remote Gateway + local browser)
+
+If you run the Gateway on one machine but want to drive a browser on another machine,
+run a **node host** on the browser machine and keep both on the same tailnet.
+The Gateway will proxy browser actions to the node; no separate control server or Serve URL needed.
+
+Avoid Funnel for browser control; treat node pairing like operator access.
+
+## Tailscale prerequisites + limits
+
+- Serve requires HTTPS enabled for your tailnet; the CLI prompts if it is missing.
+- Serve injects Tailscale identity headers; Funnel does not.
+- Funnel requires Tailscale v1.38.3+, MagicDNS, HTTPS enabled, and a funnel node attribute.
+- Funnel only supports ports `443`, `8443`, and `10000` over TLS.
+- Funnel on macOS requires the open-source Tailscale app variant.
+
+## Learn more
+
+- Tailscale Serve overview: [https://tailscale.com/kb/1312/serve](https://tailscale.com/kb/1312/serve)
+- `tailscale serve` command: [https://tailscale.com/kb/1242/tailscale-serve](https://tailscale.com/kb/1242/tailscale-serve)
+- Tailscale Funnel overview: [https://tailscale.com/kb/1223/tailscale-funnel](https://tailscale.com/kb/1223/tailscale-funnel)
+- `tailscale funnel` command: [https://tailscale.com/kb/1311/tailscale-funnel](https://tailscale.com/kb/1311/tailscale-funnel)

package/docs/gateway/tools-invoke-http-api.md

@@ -0,0 +1,161 @@
+---
+summary: "Invoke a single tool directly via the Gateway HTTP endpoint"
+read_when:
+  - Calling tools without running a full agent turn
+  - Building automations that need tool policy enforcement
+title: "Tools Invoke API"
+---
+
+# Tools Invoke (HTTP)
+
+Durar’s Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled and uses Gateway auth plus tool policy. Like the OpenAI-compatible `/v1/*` surface, shared-secret bearer auth is treated as trusted operator access for the whole gateway.
+
+- `POST /tools/invoke`
+- Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/tools/invoke`
+
+Default max payload size is 2 MB.
+
+## Authentication
+
+Uses the Gateway auth configuration.
+
+Common HTTP auth paths:
+
+- shared-secret auth (`gateway.auth.mode="token"` or `"password"`):
+  `Authorization: Bearer <token-or-password>`
+- trusted identity-bearing HTTP auth (`gateway.auth.mode="trusted-proxy"`):
+  route through the configured identity-aware proxy and let it inject the
+  required identity headers
+- private-ingress open auth (`gateway.auth.mode="none"`):
+  no auth header required
+
+Notes:
+
+- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `Durar_GATEWAY_TOKEN`).
+- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `Durar_GATEWAY_PASSWORD`).
+- When `gateway.auth.mode="trusted-proxy"`, the HTTP request must come from a
+  configured non-loopback trusted proxy source; same-host loopback proxies do
+  not satisfy this mode.
+- If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`.
+
+## Security boundary (important)
+
+Treat this endpoint as a **full operator-access** surface for the gateway instance.
+
+- HTTP bearer auth here is not a narrow per-user scope model.
+- A valid Gateway token/password for this endpoint should be treated like an owner/operator credential.
+- For shared-secret auth modes (`token` and `password`), the endpoint restores the normal full operator defaults even if the caller sends a narrower `x-Durar-scopes` header.
+- Shared-secret auth also treats direct tool invokes on this endpoint as owner-sender turns.
+- Trusted identity-bearing HTTP modes (for example trusted proxy auth or `gateway.auth.mode="none"` on a private ingress) honor `x-Durar-scopes` when present and otherwise fall back to the normal operator default scope set.
+- Keep this endpoint on loopback/tailnet/private ingress only; do not expose it directly to the public internet.
+
+Auth matrix:
+
+- `gateway.auth.mode="token"` or `"password"` + `Authorization: Bearer ...`
+  - proves possession of the shared gateway operator secret
+  - ignores narrower `x-Durar-scopes`
+  - restores the full default operator scope set:
+    `operator.admin`, `operator.approvals`, `operator.pairing`,
+    `operator.read`, `operator.talk.secrets`, `operator.write`
+  - treats direct tool invokes on this endpoint as owner-sender turns
+- trusted identity-bearing HTTP modes (for example trusted proxy auth, or `gateway.auth.mode="none"` on private ingress)
+  - authenticate some outer trusted identity or deployment boundary
+  - honor `x-Durar-scopes` when the header is present
+  - fall back to the normal operator default scope set when the header is absent
+  - only lose owner semantics when the caller explicitly narrows scopes and omits `operator.admin`
+
+## Request body
+
+```json
+{
+  "tool": "sessions_list",
+  "action": "json",
+  "args": {},
+  "sessionKey": "main",
+  "dryRun": false
+}
+```
+
+Fields:
+
+- `tool` (string, required): tool name to invoke.
+- `action` (string, optional): mapped into args if the tool schema supports `action` and the args payload omitted it.
+- `args` (object, optional): tool-specific arguments.
+- `sessionKey` (string, optional): target session key. If omitted or `"main"`, the Gateway uses the configured main session key (honors `session.mainKey` and default agent, or `global` in global scope).
+- `dryRun` (boolean, optional): reserved for future use; currently ignored.
+
+## Policy + routing behavior
+
+Tool availability is filtered through the same policy chain used by Gateway agents:
+
+- `tools.profile` / `tools.byProvider.profile`
+- `tools.allow` / `tools.byProvider.allow`
+- `agents.<id>.tools.allow` / `agents.<id>.tools.byProvider.allow`
+- group policies (if the session key maps to a group or channel)
+- subagent policy (when invoking with a subagent session key)
+
+If a tool is not allowed by policy, the endpoint returns **404**.
+
+Important boundary notes:
+
+- Exec approvals are operator guardrails, not a separate authorization boundary for this HTTP endpoint. If a tool is reachable here via Gateway auth + tool policy, `/tools/invoke` does not add an extra per-call approval prompt.
+- Do not share Gateway bearer credentials with untrusted callers. If you need separation across trust boundaries, run separate gateways (and ideally separate OS users/hosts).
+
+Gateway HTTP also applies a hard deny list by default (even if session policy allows the tool):
+
+- `exec` — direct command execution (RCE surface)
+- `spawn` — arbitrary child process creation (RCE surface)
+- `shell` — shell command execution (RCE surface)
+- `fs_write` — arbitrary file mutation on the host
+- `fs_delete` — arbitrary file deletion on the host
+- `fs_move` — arbitrary file move/rename on the host
+- `apply_patch` — patch application can rewrite arbitrary files
+- `sessions_spawn` — session orchestration; spawning agents remotely is RCE
+- `sessions_send` — cross-session message injection
+- `cron` — persistent automation control plane
+- `gateway` — gateway control plane; prevents reconfiguration via HTTP
+- `nodes` — node command relay can reach system.run on paired hosts
+- `whatsapp_login` — interactive setup requiring terminal QR scan; hangs on HTTP
+
+You can customize this deny list via `gateway.tools`:
+
+```json5
+{
+  gateway: {
+    tools: {
+      // Additional tools to block over HTTP /tools/invoke
+      deny: ["browser"],
+      // Remove tools from the default deny list
+      allow: ["gateway"],
+    },
+  },
+}
+```
+
+To help group policies resolve context, you can optionally set:
+
+- `x-Durar-message-channel: <channel>` (example: `slack`, `telegram`)
+- `x-Durar-account-id: <accountId>` (when multiple accounts exist)
+
+## Responses
+
+- `200` → `{ ok: true, result }`
+- `400` → `{ ok: false, error: { type, message } }` (invalid request or tool input error)
+- `401` → unauthorized
+- `429` → auth rate-limited (`Retry-After` set)
+- `404` → tool not available (not found or not allowlisted)
+- `405` → method not allowed
+- `500` → `{ ok: false, error: { type, message } }` (unexpected tool execution error; sanitized message)
+
+## Example
+
+```bash
+curl -sS http://127.0.0.1:18789/tools/invoke \
+  -H 'Authorization: Bearer secret' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "tool": "sessions_list",
+    "action": "json",
+    "args": {}
+  }'
+```