auvrynt 1.0.2 → 1.0.5

package/docs/security.md

@@ -1,100 +1,138 @@
-# Security Model
-
-Auvrynt exposes local coding capabilities over MCP. Treat it as remote access
-to your development machine.
-
-The security model is simple:
-
-- you choose a narrow filesystem allowlist
-- the MCP endpoint requires OAuth approval with your Owner password
-- Host headers are allowlisted from the configured public URL
-- every coding action happens through explicit MCP tool calls
-
-## Filesystem Allowlist
-
-Auvrynt only opens workspaces under configured roots.
-
-Good examples:
-
-```text
-~/work
-~/personal/open-source
-```
-
-Avoid broad roots:
-
-```text
-~
-/
-C:\
-```
-
-The narrower the root, the easier it is to reason about what the MCP client can
-reach.
-
-## Owner Password
-
-`auvrynt init` generates an Owner password and stores it in:
-
-```text
-~/.auvrynt/auth.json
-```
-
-When an MCP client connects, Auvrynt shows an approval page. Enter the Owner
-password only when you intentionally want that client to access this server.
-
-For env-driven deployments, set a long random value:
-
-```bash
-AUVRYNT_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)"
-```
-
-## Public URL And Host Allowlist
-
-Auvrynt needs `AUVRYNT_PUBLIC_BASE_URL` so MCP clients can discover OAuth
-metadata and connect to the correct resource.
-
-The value should be the origin only:
-
-```text
-https://your-tunnel-host.example.com
-```
-
-Do not include `/mcp` in `AUVRYNT_PUBLIC_BASE_URL`.
-
-By default, Auvrynt derives allowed Host headers from the local host and public
-URL. Use `AUVRYNT_ALLOWED_HOSTS=*` only for intentional local debugging.
-
-## Tunnels
-
-Auvrynt does not manage tunnels. Your tunnel or reverse proxy should point to:
-
-```text
-http://127.0.0.1:49321
-```
-
-Prefer adding Cloudflare Access, Tailscale identity controls, or equivalent
-protection in front of public tunnels. Auvrynt OAuth still protects the MCP
-endpoint, but the tunnel URL should not be treated as a secret.
-
-## Shell Access
-
-The shell tool is powerful by design. It is meant for tests, builds, git, and
-package scripts.
-
-Filesystem path containment applies to Auvrynt file tools. Shell commands run
-as local commands and can do what your user account can do. This is why the MCP
-client must be trusted and the Owner password must stay private.
-
-## Worktrees
-
-Managed worktrees reduce accidental edits to your active checkout, but they are
-not a security boundary. They are a workflow boundary for isolated coding
-sessions.
-
-## Logs
-
-By default, Auvrynt logs requests and tool calls. Shell command previews are
-disabled unless `AUVRYNT_LOG_SHELL_COMMANDS=1`.
-
-Do not enable shell command logging if commands may contain secrets.
+# Security Model
+
+Auvrynt exposes local coding capabilities over MCP. Treat it as remote access
+to your development machine.
+
+The security model is simple:
+
+- you choose a narrow filesystem allowlist
+- the MCP endpoint requires OAuth approval with your Owner token (or Owner token as `Authorization: Bearer` for header-only clients such as Clusy)
+- OAuth scopes are enforced per tool call
+- workspace rooms are owned by the OAuth client that opened them
+- Host headers are allowlisted from the configured public URL
+- forwarded client IPs are trusted only from an immediate loopback proxy
+- every coding action happens through explicit MCP tool calls
+
+## Filesystem Allowlist
+
+Auvrynt only opens workspaces under configured roots.
+
+Good examples:
+
+```text
+~/work
+~/personal/open-source
+```
+
+Avoid broad roots:
+
+```text
+~
+/
+C:\
+```
+
+The narrower the root, the easier it is to reason about what the MCP client can
+reach.
+
+## Workspace Room Ownership
+
+Every workspace opened through MCP is assigned to the authenticated OAuth client
+that created it. Workspace-bound tools validate this ownership before resolving
+the filesystem root or invoking an integration. Another OAuth client cannot use
+a leaked `workspaceId` to read, edit, run processes, or call integration tools in
+that room.
+
+Room ownership does not provide file locking. Two owner-protected workspaces can
+still point to the same checkout, so use separate managed worktrees when multiple
+clients must edit one Git repository concurrently.
+
+## Owner Token
+
+`auvrynt init` generates an Owner token and stores it in:
+
+```text
+~/.auvrynt/auth.json
+```
+
+When an MCP client connects, Auvrynt shows an approval page. Enter the Owner
+token only when you intentionally want that client to access this server. Normal
+startup does not print the secret; run `auvrynt token` locally when you explicitly
+need to retrieve it.
+
+For env-driven deployments, set a long random value:
+
+```bash
+AUVRYNT_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)"
+```
+
+## Public URL And Host Allowlist
+
+Auvrynt needs `AUVRYNT_PUBLIC_BASE_URL` so MCP clients can discover OAuth
+metadata and connect to the correct resource.
+
+The value should be the origin only:
+
+```text
+https://your-tunnel-host.example.com
+```
+
+Do not include `/mcp` in `AUVRYNT_PUBLIC_BASE_URL`.
+
+By default, Auvrynt derives allowed Host headers from the local host and public
+URL. Use `AUVRYNT_ALLOWED_HOSTS=*` only for intentional local debugging. Reverse
+proxy forwarding information is accepted only when the immediate proxy is on
+loopback; there is no option to trust arbitrary forwarding headers.
+
+## Tunnels
+
+Auvrynt does not manage tunnels. Your tunnel or reverse proxy should point to:
+
+```text
+http://127.0.0.1:49321
+```
+
+Prefer adding Cloudflare Access, Tailscale identity controls, or equivalent
+protection in front of public tunnels. Auvrynt OAuth still protects the MCP
+endpoint, but the tunnel URL should not be treated as a secret.
+
+## Shell Access
+
+The shell tool is powerful by design. It is meant for tests, builds, git, and
+package scripts.
+
+Filesystem path containment applies to Auvrynt file tools. Shell commands run
+as local commands and can do what your user account can do. This is why the MCP
+client must be trusted and the Owner token must stay private.
+
+The `auvrynt:process` scope should therefore be treated as local command-execution
+permission, not as a filesystem sandbox.
+
+## Blender Python
+
+Normal Blender tools require `auvrynt:blender` and are bound to a `.blend` file
+inside the opened workspace. The arbitrary `blender_execute_python` escape hatch
+also requires `auvrynt:blender-python`, which is excluded from the default OAuth
+scope set because Python executed inside Blender has the privileges of the local
+user account.
+
+## Browser Network Access
+
+Playwright browser tools validate each HTTP(S) request, redirect, DNS result, and
+WebSocket destination against local/private/reserved network ranges. Service
+workers are disabled in managed browser contexts so they cannot bypass request
+routing. Intentional localhost development pages are allowed, while unrelated
+LAN, metadata, and private-network destinations remain blocked.
+
+## Worktrees
+
+Managed worktrees reduce accidental edits to your active checkout, but they are
+not a security boundary. They are a workflow boundary for isolated coding
+sessions.
+
+## Logs
+
+By default, Auvrynt logs requests and tool calls. Shell command previews are
+disabled unless `AUVRYNT_LOG_SHELL_COMMANDS=1`.
+
+Do not enable shell command logging if commands may contain secrets.

package/docs/setup.md

@@ -1,132 +1,172 @@
-# Setup Guide
-
-This guide is for users who want ChatGPT or another MCP host to work in local
-projects through Auvrynt.
-
-## Requirements
-
-- Node `>=20.12 <27`; Node 22 LTS is recommended
-- npm
-- Git
-- Bash, including Git Bash or WSL on Windows
-- a public HTTPS URL that forwards to the local Auvrynt server
-
-Auvrynt does not create the public tunnel for you. Use Cloudflare Tunnel,
-ngrok, Pinggy, Tailscale Funnel, or your own HTTPS reverse proxy.
-
-## Install And Configure
-
-Run:
-
-```bash
-npx auvrynt init
-```
-
-The setup flow asks one question at a time.
-
-### Project Roots
-
-Choose the folders ChatGPT is allowed to open through Auvrynt. Keep this
-narrow.
-
-Examples:
-
-```text
-~/personal,~/work
-```
-
-```text
-/Users/alice/dev,/Users/alice/work
-```
-
-```text
-C:\Users\alice\dev,C:\Users\alice\work
-```
-
-### Local Port
-
-The default is `49321`.
-
-The local MCP URL is:
-
-```text
-http://127.0.0.1:49321/mcp
-```
-
-### Public Base URL
-
-Start your tunnel or reverse proxy before entering this value. Point the tunnel
-at:
-
-```text
-http://127.0.0.1:49321
-```
-
-Enter the public origin without `/mcp`:
-
-```text
-https://your-tunnel-host.example.com
-```
-
-Configure the MCP client with the full MCP endpoint:
-
-```text
-https://your-tunnel-host.example.com/mcp
-```
-
-## Start The Server
-
-Run:
-
-```bash
-npx auvrynt start
-```
-
-If your tunnel URL changes for one run, override it without rewriting config:
-
-```bash
-AUVRYNT_PUBLIC_BASE_URL="https://new-tunnel.example.com" npx auvrynt start
-```
-
-For a stable public URL, persist it:
-
-```bash
-npx auvrynt config set publicBaseUrl https://auvrynt.example.com
-npx auvrynt start
-```
-
-## Approve The Client
-
-When ChatGPT, Claude, or another MCP client connects, Auvrynt shows an Owner
-password approval page. Enter the Owner password printed during setup.
-
-The default config files are:
-
-```text
-~/.auvrynt/config.json
-~/.auvrynt/auth.json
-```
-
-Keep `auth.json` private.
-
-## Check Your Setup
-
-Run:
-
-```bash
+# Setup Guide
+
+This guide is for users who want ChatGPT, Claude, Grok, Lovable, Bolt, or another MCP host to work in local
+projects through Auvrynt.
+
+## Requirements
+
+- Node `>=20.12 <27`; Node 22 LTS is recommended
+- npm
+- Git for Windows (includes the Bash runtime used by agent shell tools)
+- Windows PowerShell or cmd.exe
+- Internet access for the managed Cloudflare quick tunnel
+
+`auvrynt start` installs Cloudflare Tunnel when needed and creates a temporary
+public URL automatically.
+
+## Install And Start
+
+Run:
+
+```powershell
+npm install -g auvrynt
+cd C:\path\to\your\project
+auvrynt start
+```
+
+The first start creates local configuration and asks which optional
+integrations to enable. The launch directory becomes the only project root
+available to that managed instance.
+
+Run `auvrynt init` only if you want to configure foreground `auvrynt serve`
+manually. That setup flow asks one question at a time:
+
+### Project Roots
+
+Choose the folders ChatGPT is allowed to open through Auvrynt. Keep this
+narrow.
+
+Example: `C:\Users\alice\dev,C:\Users\alice\work`.
+
+### Local Port
+
+The default is `49321`.
+
+The local MCP URL is:
+
+```text
+http://127.0.0.1:49321/mcp
+```
+
+### Public Base URL
+
+This setting applies to foreground `auvrynt serve`; managed `auvrynt start`
+creates its own Cloudflare URL. Point your independently managed tunnel at:
+
+```text
+http://127.0.0.1:49321
+```
+
+Enter the public origin without `/mcp`:
+
+```text
+https://your-tunnel-host.example.com
+```
+
+Configure the MCP client with the full MCP endpoint:
+
+```text
+https://your-tunnel-host.example.com/mcp
+```
+
+## Start The Server
+
+Run:
+
+```powershell
+auvrynt start
+```
+
+The command starts in the background and returns only after both the local
+server and Cloudflare tunnel are ready. It always limits web-agent file access
+to the directory where you ran it.
+
+Use `auvrynt add web` (or another profile) to update the running instance
+without restarting the server or tunnel. Use `auvrynt restart` to reload only
+the Auvrynt server while preserving the tunnel URL, `auvrynt restart hard` to
+recreate both processes, or `auvrynt stop` to stop both managed processes.
+
+To move the running web-agent boundary to another project without changing the
+tunnel URL, open that directory and run:
+
+```powershell
+auvrynt change
+```
+
+For an independently managed stable URL, configure it and use foreground
+`auvrynt serve`:
+
+```powershell
+auvrynt config set publicBaseUrl https://auvrynt.example.com
+auvrynt serve
+```
+
+## Approve The Client
+
+When ChatGPT, Claude, Grok, Lovable, Bolt, or another MCP client connects, Auvrynt shows an Owner
+token approval page. Enter the Owner token shown during setup, or retrieve it later with `auvrynt token`.
+
+The default config files are:
+
+```text
+~/.auvrynt/config.json
+~/.auvrynt/auth.json
+```
+
+Keep `auth.json` private.
+
+## Connect Grok
+
+Start Auvrynt with the integrations you need, then copy the public MCP URL from
+`auvrynt status`:
+
+```powershell
+auvrynt start web
+auvrynt status
+```
+
+In Grok, open `grok.com/connectors`, choose **New Connector** → **Custom**, and
+paste the URL ending in `/mcp`. Grok must use the public HTTPS URL; it cannot
+reach `127.0.0.1`. Complete the Auvrynt Owner-token approval when prompted.
+
+For a URL that survives tunnel restarts, configure a reserved ngrok URL with
+`auvrynt tunnel` before creating the Grok connector. Cloudflare quick-tunnel
+URLs are temporary and must be replaced in Grok when they change.
+
+## Connect Clusy (header auth)
+
+Clusy cloud MCP only supports **Streamable HTTP** and **custom headers**. It does
+not open Auvrynt’s `/authorize` page.
+
+1. Start Auvrynt and copy the public URL ending in `/mcp` from `auvrynt status`.
+2. Run `auvrynt token` and copy the Owner token (keep it private).
+3. In Clusy → **Settings → MCP servers** → Add server:
+   - Transport: **Streamable HTTP** (not STDIO)
+   - URL: `https://your-public-host/mcp`
+   - Custom header name: `Authorization`
+   - Custom header value: `Bearer <owner-token>`
+4. Save, then approve individual tools in Clusy when prompted.
+
+Rebuild/restart Auvrynt after upgrading so Owner-Bearer verification is active.
+
+## Check Your Setup
+
+Run:
+
+```bash
 npx auvrynt doctor
-```
-
-The doctor command reports the resolved config, Node version, Node ABI, platform,
-Git, Bash, public URL, allowed hosts, and SQLite native dependency status.
-
-## Running From A Local Checkout
-
-If you are developing Auvrynt itself instead of using the published package:
-
-```bash
-npm install --include=dev
-npm run dev
-```
-
-The same setup rules apply.
+```
+
+The doctor command reports the resolved config, Node version, Node ABI, platform,
+Git, Bash, public URL, allowed hosts, and SQLite native dependency status.
+
+## Running From A Local Checkout
+
+If you are developing Auvrynt itself instead of using the published package:
+
+```bash
+npm install --include=dev
+npm run dev
+```
+
+The same setup rules apply.

package/docs/source-layout.md

@@ -0,0 +1,60 @@
+# Source Layout
+
+Auvrynt keeps package entry points at the root of `src` and groups implementation code by responsibility.
+
+## Entry points
+
+- `src/cli.ts` — command routing only. It compiles to the published `dist/cli.js` executable.
+- `src/server.ts` — HTTP, OAuth, MCP transport, session, readiness, and shutdown composition. It compiles to the published `dist/server.js` entry point.
+
+These files intentionally remain at the root because `package.json` publishes those output paths.
+
+## Domain folders
+
+```text
+src/
+├── auth/            OAuth, sessions, rooms, connected-client state
+├── cli/             commands, foreground serving, lifecycle management
+├── db/              SQLite client and schema
+├── infrastructure/  configuration, logging, HTTP/SSE, queues, payload budgets
+├── integrations/
+│   ├── blender/
+│   ├── dotnet/
+│   ├── godot/
+│   ├── images/
+│   ├── playwright/
+│   └── serena/
+├── process/         managed processes, retries, crash recovery, background lifecycle
+├── server/          MCP policy, tool registration, UI resources, tool families
+├── tools/           shared MCP tool adapters
+├── tunnels/         Cloudflare and ngrok implementations
+└── workspace/       workspace registry, persistence, worktrees, search, skills
+```
+
+## Root compatibility files
+
+Most non-test `src/*.ts` files are intentionally tiny re-export facades. They preserve existing import paths while implementation code lives in the domain folders. New runtime implementation must not be added to these facades.
+
+All non-entry root runtime files are now compatibility facades. The final three implementation bodies (`blender-tools.ts`, `serena-manager.ts`, `serena-tools.ts`) have been moved into their respective integration domain folders:
+
+- `src/integrations/blender/blender-tools.ts`
+- `src/integrations/serena/serena-manager.ts`
+- `src/integrations/serena/serena-tools.ts`
+
+The root files re-export from the domain paths. New server code imports the organized domain paths directly.
+
+## Tests
+
+Tests currently remain beside their historical root import paths because `scripts/run-tests.mjs` treats each `src/*.test.ts` file as an executable test entry point. Tests may be colocated with implementations in a later dedicated test-runner migration, but production code should not depend on test location.
+
+## Placement rules
+
+- Add authentication or session state under `auth/`.
+- Add transport, configuration, logging, or bounded-resource helpers under `infrastructure/`.
+- Add workspace filesystem and persistence behavior under `workspace/`.
+- Add process ownership or lifecycle behavior under `process/`.
+- Add integration-specific behavior under its `integrations/<name>/` folder.
+- Keep `cli.ts` and `server.ts` composition-only.
+- Do not add new root implementation files.
+
+`src/architecture-boundaries.test.ts` enforces these rules.