dodo-mcp 1.0.1 → 1.0.3

package/docs/TUNNEL.md

@@ -1,86 +1,147 @@
-# DODO MCP — Tunnel Guide
+# DODO MCP — Local และ Cloudflare Tunnel
 
-DODO เปิด MCP และ OAuth บน local loopback ผู้ใช้เป็นผู้สร้าง Cloudflare remotely-managed Tunnel, public hostname และ DNS เอง DODO supervise เฉพาะ process `cloudflared` ที่เริ่มในรอบปัจจุบันและไม่ติดตั้งเป็น system service
+DODO มีโหมดเชื่อมต่อระดับ installation เพียงหนึ่งโหมดในแต่ละเวลา:
 
-## Local endpoints
+- `local` — ใช้ MCP ที่ `http://127.0.0.1:21730/mcp` และไม่เริ่ม `cloudflared`
+- `tunnel` — ใช้ public HTTPS origin เป็น MCP URL หลัก และ DODO เริ่ม/หยุด
+  `cloudflared` ของตัวเองพร้อมทุก `dodo start`
 
-- MCP + OAuth: `http://127.0.0.1:21730`
-- MCP endpoint: `http://127.0.0.1:21730/mcp`
-- Local Config: `http://127.0.0.1:21731`
-- managed readiness/metrics: `http://127.0.0.1:21732` โดยค่าเริ่มต้น
+การเลือกจะถูกบันทึกใน private global config และไม่มี fallback อัตโนมัติ หากเลือก
+`tunnel` แล้ว credential, executable หรือ readiness ไม่พร้อม การเริ่ม DODO จะล้มเหลว
+พร้อมคำอธิบาย โดยไม่เปลี่ยนไปเปิด local แทน
 
-Tunnel ต้อง route health, discovery, OAuth และ MCP ทุก path ไปยัง listener `21730` เดียวกัน ห้าม route Local Config `21731`, metrics `21732`, private IPC หรือ debug endpoint ออก public
+## พอร์ตและขอบเขต
 
-## Public origin
+| บริการ | ค่าเริ่มต้น | การเปิดเผย |
+|---|---:|---|
+| MCP + OAuth upstream | `127.0.0.1:21730` | Local เท่านั้น; Tunnel route มาที่พอร์ตนี้ |
+| Local Config | `127.0.0.1:21731` | Loopback เท่านั้นเสมอ |
+| Tunnel readiness/metrics | `127.0.0.1:21732` | Loopback เท่านั้นเสมอ |
+
+Cloudflare public hostname ต้อง route **ทุก path** มาที่
+`http://127.0.0.1:21730` เพื่อให้ health, OAuth discovery, authorization และ `/mcp`
+ทำงานครบ ห้าม route พอร์ต 21731, 21732, private IPC หรือ debug endpoint ออก public
+
+แม้โหมด Tunnel ยังต้องมี listener 21730 เป็น private upstream ให้ `cloudflared`
+แต่ DODO จะ advertise public HTTPS URL เป็น endpoint ที่มีผล ส่วน Local Config ยังคง
+เข้าผ่าน loopback ยกเว้น bounded `/config` lease ที่เจ้าของเปิดชั่วคราวเอง
+
+## เลือก Local
 
 ```bash
-dodo init --public-url https://mcp.example.com
-dodo start --root /path/to/project
+dodo tunnel configure --local
+dodo start
 ```
 
-## เปิดพร้อม DODO ด้วย token ชั่วคราว
+ตรวจค่าที่ใช้อยู่:
 
 ```bash
-dodo setup --check --components cloudflared
-dodo init --public-url https://mcp.example.com
-dodo start --root /path/to/project
-# Cloudflare Tunnel token (temporary; Enter = local only):
+dodo tunnel status
 ```
 
-`dodo setup --yes` ใช้ component `all` เป็นค่าเริ่มต้นและรวม `cloudflared` บน macOS
-หรือเลือกจากเมนู `dodo --cli` ข้อ “ติดตั้ง/ตรวจ dependencies ทั้งหมด” ได้
+Local mode ไม่ใช้ public origin และไม่เริ่ม Tunnel หากต้องการกลับไป Tunnel ต้องเลือก
+ใหม่อย่างชัดเจนด้วยคำสั่งหรือหน้า Local Config แล้ว restart DODO
 
-กรอก Tunnel token ที่ Cloudflare ออกให้สำหรับ remotely-managed Tunnel Token จะอยู่
-เฉพาะใน DODO process และ environment ของ child `cloudflared` ระหว่างรอบ เมื่อ DODO
-หยุด child จะหยุดตาม กด Enter โดยไม่กรอกหรือใช้คำสั่งต่อไปนี้เพื่อเปิด local MCP เท่านั้น:
+## เลือก DODO Tunnel
+
+เจ้าของต้องสร้าง remotely-managed Tunnel, public hostname และ DNS ใน Cloudflare ก่อน
+DODO ไม่สร้าง/ลบ Tunnel, เปลี่ยน DNS, เปิด firewall หรือติดตั้ง system service
+
+บน macOS ตรวจหรือติดตั้ง executable ผ่าน setup:
 
 ```bash
-dodo start --no-tunnel
+dodo setup --check --components cloudflared
+dodo setup --yes --components cloudflared
 ```
 
-หน้า Local Config มีช่อง **Temporary Tunnel token** สำหรับเริ่ม tunnel ใน process ที่
-เปิดอยู่ได้ทันที และมีปุ่มหยุดเฉพาะ child ที่ process นี้เป็นเจ้าของ ช่องถูกล้างหลังส่ง
-Backend ตอบ `tokenStored:false` และไม่เขียนค่าลง config หรือ credential store
+จากนั้นเลือก Tunnel และบันทึก token ใน macOS Keychain ผ่าน hidden prompt:
+
+```bash
+dodo tunnel configure \
+  --tunnel \
+  --public-url https://mcp.example.com \
+  --os-credential
+
+dodo start
+```
 
-คำสั่งตรวจสถานะที่ไม่มี secret:
+Windows ใช้ Credential Manager และ Linux ใช้ Secret Service เมื่อเลือก
+`--os-credential` สำหรับ headless environment สามารถใช้ owner-controlled reference:
 
 ```bash
-dodo tunnel status
-dodo tunnel doctor
-dodo tunnel logs --lines 100
-dodo tunnel stop
+dodo tunnel configure --tunnel --public-url https://mcp.example.com --token-env DODO_OWNER_TUNNEL_TOKEN
+# หรือไฟล์ private regular file ที่เป็น absolute path
+dodo tunnel configure --tunnel --public-url https://mcp.example.com --token-file /private/path/tunnel-token
 ```
 
-`status` ใช้ authenticated owner IPC และไม่อ่าน credential ส่วน `doctor` เป็นคำสั่งตรวจแบบ explicit: ตรวจ executable, credential availability, local `/healthz`, managed `/ready` และ public `/healthz` แยกกัน Public health ที่ผ่านไม่ได้แปลว่า AI client เชื่อมต่ออยู่
+ค่า environment/file เป็น reference ที่เจ้าของดูแลเอง คำสั่งตรวจค่าและไฟล์ก่อนบันทึก
+แต่ไม่คัดลอก token เข้า config เมื่อใช้หน้า Local Config token จะเป็น write-only และ
+ถูกส่งตรงไปยัง OS credential store; หลังบันทึก UI แสดงเพียงว่ามี credential
 
-## ขอบเขตของ token
+ทุก `dodo start` ใน Tunnel mode จะอ่าน credential จาก reference เริ่ม `cloudflared`
+ผ่าน child environment และรอ readiness ก่อนถือว่า startup สำเร็จ Token ไม่อยู่ใน
+CLI argument, config JSON, log, audit, MCP response, browser storage หรือ environment
+ของ MCP jobs เมื่อ DODO หยุด child ที่ process นี้เป็นเจ้าของจะหยุดตาม
 
-DODO ไม่รับ token เป็น CLI argument และไม่ใส่ token ใน `cloudflared` argv เส้นทาง
-มาตรฐานไม่ใช้ macOS Keychain, Windows Credential Manager, Linux Secret Service,
-token file หรือ shell environment Token จาก terminal และ Local Config ถูกส่งผ่าน
-environment ของ child ที่สร้างเองเท่านั้น Tunnel diagnostics ถูกจำกัดขนาดและ redact
-ก่อนเขียนลง private state MCP jobs จะไม่ได้รับ `TUNNEL_TOKEN` หรือ
-`TUNNEL_TOKEN_FILE` แม้ owner จะใส่ชื่อไว้ใน environment allowlist
+## เปลี่ยนโหมดจากหน้าเว็บ
 
-คำสั่ง `dodo tunnel configure/start` และ credential reference รุ่นเดิมยังคงอยู่เพื่อ
-advanced/headless compatibility แต่ไม่ถูกเรียกโดย `dodo start`, `dodo --cli` หรือ
-Local Config และต้องเกิดจากคำสั่ง owner โดยตรง
+เปิด Local Config จาก URL ที่ DODO แสดงบนเครื่องเจ้าของ แล้วใช้ส่วน
+**การเชื่อมต่อ MCP**:
 
-runtime ใช้ bounded restart หลัง `cloudflared` จบ retry ของตัวเอง และ `stop` ส่งสัญญาณเฉพาะ live child handle ที่ supervisor เป็นผู้สร้าง ไม่มีการ kill saved PID หรือ process ชื่อเหมือนกัน
+1. ตั้ง Public origin เป็น HTTPS origin ของ Tunnel
+2. เลือก `DODO Tunnel`
+3. ใส่ Cloudflare Tunnel token หากยังไม่มี credential ที่บันทึกไว้
+4. กดบันทึกและ restart DODO
 
-## Client setup
+หรือเลือก `Local` แล้วบันทึกและ restart ค่าในหน้าเว็บไม่เปลี่ยน endpoint ของ process
+ที่กำลังรันอยู่ทันที หน้าเว็บจะแสดงสถานะ restart ที่ตรงกับ runtime จริง
 
-1. ใช้ `https://mcp.example.com/mcp` ใน MCP client
-2. เลือก OAuth
-3. คัดลอก exact callback จาก client
-4. ลงทะเบียนด้วย `dodo auth add-client --redirect-uri ...`
-5. ทำ browser authorization และ approve interaction จาก terminal
-6. scan tools และตรวจ surface ที่ client รายงาน
+## Remote Config ไม่เกินหนึ่งชั่วโมง
 
-## หลายโปรเจกต์
+Remote Config ใช้ได้เฉพาะเมื่อเลือก Tunnel และ DODO-owned Tunnel กำลังรันอยู่:
 
-หนึ่ง DODO process มี active workspace เดียว ถ้าต้องการทำงานพร้อมกันหลายโปรเจกต์ ให้เปิดหลาย DODO processes ด้วย port, public origin และ config directory ที่แยกกัน แต่ละ managed tunnel ต้องใช้ metrics port ที่ไม่ซ้ำ ระบบจะไม่ให้ process หนึ่ง takeover root ที่อีก process กำลัง serve
+```bash
+dodo --web
+# Remote Config: https://mcp.example.com/config
+# Pairing code (shown once): XXXX-XXXX-XXXX-XXXX
+
+dodo web --status
+dodo web --close
+```
+
+`/config` ตอบ 404 ตามค่าเริ่มต้น คำสั่ง `dodo --web` เปิดหรือเปลี่ยน lease ผ่าน
+authenticated private IPC โดยไม่ restart MCP และไม่รับ Tunnel token ผ่าน IPC URL ไม่มี
+query/fragment secret Pairing code มีอายุสั้นและใช้ได้ครั้งเดียว หลังจับคู่ browser ได้
+cookie แบบ `Secure`, `HttpOnly`, `SameSite=Strict`, `Path=/config` Lease ปิดเองภายใน
+หนึ่งชั่วโมง การเปิดใหม่ยกเลิก code/session เดิม
+
+Remote Config proxy ไปยัง Local Config loopback โดยคง Host/Origin/proxy-header checks,
+private capability, rate limit, workspace ID/epoch และ owner policy เดิม การปิด lease
+ไม่หยุด MCP หรือ Tunnel และไม่มี MCP tool สำหรับเปิดหน้า owner นี้
 
-## Security
+## ตรวจสถานะและแก้ปัญหา
+
+```bash
+dodo tunnel status
+dodo tunnel doctor
+dodo tunnel logs --lines 100
+dodo tunnel stop
+```
+
+`status` ไม่อ่าน credential ส่วน `doctor` ตรวจ executable, credential, local health,
+Tunnel readiness และ public health แยกกัน Public health ที่ผ่านพิสูจน์เพียงว่า origin
+ตอบ DODO health ไม่ได้พิสูจน์ว่า AI client เชื่อมต่อแล้ว `stop` ส่งสัญญาณเฉพาะ live
+child handle ที่ supervisor ปัจจุบันสร้าง ไม่ค้นหรือ kill process ตามชื่อ/PID เก่า
+
+## ตั้งค่า MCP client
+
+1. ใช้ `https://mcp.example.com/mcp`
+2. เลือก OAuth
+3. คัดลอก exact callback URL จาก client
+4. ลงทะเบียนด้วย `dodo auth add-client --redirect-uri <exact-callback>`
+5. ทำ browser authorization และ approve interaction จาก owner terminal
+6. scan tools และตรวจ surface ที่ client รายงาน
 
-ห้ามปิด OAuth, ใช้ Tunnel token แทน MCP OAuth, ส่ง token ใน URL หรือเปิด CORS กว้าง Tunnel provider ไม่ได้แทน owner consent ของ DODO และ DODO ไม่เรียก Cloudflare API, ไม่จัดการ DNS, ไม่สร้าง/ลบ Tunnel และไม่เปิด firewall
+หนึ่ง Tunnel รองรับ project registry ทั้ง installation ไม่ต้องสร้าง Tunnel ต่อโปรเจกต์
+แต่ทุก target ยังตรวจ OAuth identity, target ACL/scopes, workspace identity/epoch,
+trust/approval, path/secret guards, sandbox และ expected hash ตามเดิม

package/docs/WINDOWS.md

@@ -1,6 +1,6 @@
 # DODO Windows Candidate — Deferred
 
-DODO MCP 1.0.1 ยังไม่ประกาศ native Windows support โค้ดและ tests สำหรับ Windows
+DODO MCP 1.0.3 ยังไม่ประกาศ native Windows support โค้ดและ tests สำหรับ Windows
 บางส่วนมีอยู่เป็น candidate สำหรับ phase สุดท้าย แต่ยังไม่มีหลักฐานจาก Windows 11 จริง
 และ Linux Docker ไม่สามารถใช้แทนหลักฐาน Windows ได้
 

package/docs/adr/031-owner-selected-tunnel-supervision.md

@@ -1,10 +1,16 @@
 # ADR-031 — Owner-selected Cloudflare Tunnel supervision
 
-**Status:** accepted (implemented)
+**Status:** superseded in credential/lifecycle selection by ADR-048. Process ownership,
+readiness, redaction and bounded-stop decisions remain accepted.
 
 **Decision.** DODO starts only an owner-selected, trusted `cloudflared` executable owned by the current HTTP process. `dodo start` can attach it immediately; the authenticated Local Config can start or stop the same process-owned runtime. The owner still creates the remotely-managed Tunnel, public hostname and DNS in Cloudflare.
 
-The default flow uses a run-scoped token entered through a hidden terminal prompt or the authenticated loopback Local Config. The token is never persisted in global config or an OS credential store. A process-owned `TunnelRuntime` forwards it through the managed child's dedicated environment and stops that child with DODO; it is absent from argv, logs, MCP, audit and job environments. Explicit secure credential references remain supported only by advanced standalone tunnel commands for compatibility.
+The original flow used a run-scoped token entered through a hidden terminal prompt or
+the authenticated loopback Local Config. ADR-048 replaces that credential flow with one
+persistent Local/Tunnel selection and a reviewed credential reference. The invariant
+retained from this ADR is that a process-owned `TunnelRuntime` forwards the resolved
+credential through the child environment, stops that child with DODO and keeps the
+credential out of argv, logs, MCP, audit and job environments.
 
 The supervisor uses a separate authenticated singleton owner IPC endpoint, loopback readiness, bounded restarts, private bounded/redacted logs and live child handles for termination. It never signals a saved PID or searches by process name. Local Config and the metrics listener remain loopback-only and are not part of the public route.
 

package/docs/adr/044-global-launcher-and-cli-menu.md

@@ -29,9 +29,9 @@ in-flight drain, running-job refusal, resource teardown และ fresh workspac
 data plane หากล้มเหลว launcher ยังคงปิด data plane ไม่มี half-switched state
 
 `dodo --cli` เป็น terminal menu ที่เรียก owner operations เดิม ไม่ใช่ MCP tool
-เมนูไม่เปลี่ยน OAuth grant, access mode หรือ OS permission เมนูเริ่มปกติเรียก hidden
-run-scoped Tunnel prompt เดียวกับ `dodo start` ส่วนเมนู local-only ส่ง override สำหรับ
-รอบนั้น Token ไม่ผ่าน readline menu, argv, config หรือ OS credential provider
+เมนูไม่เปลี่ยน OAuth grant, access mode หรือ OS permission เมนูเริ่ม DODO ตาม
+persistent `connectionMode` ที่เจ้าของบันทึกไว้ การเลือก/เก็บ Tunnel credential ใช้
+Local Config หรือ `dodo tunnel configure` ตาม ADR-048 และไม่ผ่าน readline menu/argv
 
 STDIO คง contract `dodo stdio --root PATH` เพราะ client เป็นเจ้าของ subprocess
 lifecycle และต้องกำหนด root อย่างชัดเจน

package/docs/adr/047-temporary-remote-config.md

@@ -0,0 +1,47 @@
+# ADR-047 — Temporary Remote Config on the tunneled listener
+
+## Status
+
+Accepted in DODO MCP 1.0.2.
+
+## Context
+
+The MCP/OAuth listener is already tunneled from `127.0.0.1:21730`, while Local Config
+is intentionally bound to `127.0.0.1:21731`. Owners sometimes need to configure DODO
+from another device. Permanently routing 21731 or placing its bearer capability in a
+public URL would break the owner control boundary.
+
+## Decision
+
+`dodo --web` opens a process-memory lease at `<public-origin>/config` for at most one
+hour. The route is 404 before and after the lease. A random one-time pairing code is
+shown only in the owner terminal; the server stores only its digest. Successful pairing
+issues a random session cookie scoped to `/config` with Secure, HttpOnly and SameSite
+Strict attributes. The server stores only the session digest.
+
+The public handler is a bounded reverse proxy to the existing loopback Local Config.
+It strips client credentials and proxy headers, injects the private loopback capability,
+and leaves Local Config's workspace/epoch checks, validation, policy and audit as the
+authority. Pairing never grants MCP scopes, project access, trust or approvals. No MCP
+tool can open the lease.
+
+ADR-048 supersedes the temporary-token handoff: current source opens Remote Config only
+when the saved connection mode is Tunnel and the DODO-owned Tunnel is already running.
+Owner IPC cannot carry a Tunnel credential or switch the connection mode. Closing or
+expiry still affects only Remote Config; MCP, OAuth and Tunnel continue running.
+
+## Consequences
+
+- The owner can choose local-only MCP, tunneled MCP, or tunneled MCP plus temporary
+  Remote Config without rebinding either listener.
+- Reopening issues a new code/session and invalidates the previous pair.
+- A live Cloudflare route and public HTTPS origin remain owner prerequisites.
+- Anyone with both the public URL and current one-time code can pair during its short
+  validity, so owners must treat the code as a temporary secret and close the lease
+  when finished.
+
+## Evidence
+
+- `tests/security/remoteConfig.test.ts`
+- `tests/integration/remoteConfigUi.test.ts`
+- `tests/integration/cli.test.ts`

package/docs/adr/048-persistent-connection-mode.md

@@ -0,0 +1,58 @@
+# ADR-048 — Persistent exclusive Local/Tunnel connection mode
+
+## Status
+
+Accepted in source; unreleased.
+
+## Context
+
+The prior launch flow asked for a run-scoped Cloudflare Tunnel token each time and could
+start locally when the owner omitted it. That made the advertised endpoint depend on an
+interactive answer and allowed a configuration mistake to change the connection path.
+Owners need one installation-wide choice: always use the DODO Tunnel or always use the
+local endpoint until they explicitly change it.
+
+## Decision
+
+Global owner config stores one authoritative `connectionMode`: `local` or `tunnel`.
+Legacy `mode` and `startWithDodo` fields are accepted only during load-time migration
+and are removed from newly saved config.
+
+In Local mode DODO advertises `http://127.0.0.1:<port>/mcp`, uses the loopback origin as
+its OAuth issuer/resource and never starts `cloudflared`. In Tunnel mode DODO advertises
+the configured public HTTPS origin, starts one process-owned supervisor on every
+`dodo start`, waits for readiness and stops that child with DODO. Missing credentials,
+executable failure or readiness failure aborts startup; there is no Local fallback.
+
+The standard credential path is a reviewed OS store: macOS Keychain, Windows Credential
+Manager or Linux Secret Service. Global config stores only an opaque reference. Explicit
+environment/private-file references remain for owner-controlled headless deployments.
+The token reaches `cloudflared` through its dedicated child environment and never enters
+argv, config, logs, audit, browser storage, MCP output or MCP-job environments.
+
+Local Config may select the mode and accept a write-only token after its existing owner,
+Host, Origin, proxy-header, rate and workspace-context checks. The backend writes it to
+the OS store and returns only presence/provider. A saved change requires restart and the
+UI distinguishes saved mode from the active runtime endpoint.
+
+Remote Config remains a bounded one-hour `/config` lease. It is available only while
+Tunnel mode and the DODO-owned supervisor are active. Installation IPC cannot transmit a
+Tunnel token or change mode, and public MCP routes expose no owner control operation.
+
+## Consequences
+
+- Startup and endpoint selection are deterministic and auditable.
+- Tunnel mode fails closed instead of silently changing how clients reach DODO.
+- Credential unlock may still require an owner/OS interaction at startup.
+- The loopback MCP listener remains present as the private Tunnel upstream, but the
+  public URL is the only advertised active MCP endpoint in Tunnel mode.
+- Switching modes or public origin requires a DODO restart and client reconnect/rescan.
+
+## Evidence
+
+- `tests/integration/connectionMode.test.ts`
+- `tests/security/tunnelCredentials.test.ts`
+- `tests/security/localConfig.test.ts`
+- `tests/integration/tunnelSupervisor.test.ts`
+- `tests/security/remoteConfig.test.ts`
+- `tests/integration/remoteConfigUi.test.ts`

package/docs/adr/README.md

@@ -62,3 +62,5 @@ decisions; ADR-011+ resolve implementation ambiguities without reducing security
 - [044 — Global launcher and interactive owner menu](044-global-launcher-and-cli-menu.md)
 - [045 — Explicit project runtimes and provider-backed sub-agents](045-ai-providers-multiproject.md)
 - [046 — Personal add-and-use mode](046-personal-access-mode.md)
+- [047 — Temporary Remote Config on the tunneled listener](047-temporary-remote-config.md)
+- [048 — Persistent exclusive Local/Tunnel connection mode](048-persistent-connection-mode.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dodo-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "author": "Arthittakun",
   "description": "DODO — local-first MCP server with multi-project coding, AI providers, sub-agents, context, memory, media and workflow tools; embedded OAuth and workspace permissions.",
   "type": "module",
@@ -40,6 +40,8 @@
     "docs/RUNTIME.md",
     "docs/RELEASE_1.0.0.md",
     "docs/RELEASE_1.0.1.md",
+    "docs/RELEASE_1.0.2.md",
+    "docs/RELEASE_1.0.3.md",
     "docs/RELEASE_NOTES.md",
     "docs/SCHEDULES.md",
     "docs/SECURITY.md",

package/schemas/global-config.schema.json

@@ -359,25 +359,20 @@
     },
     "tunnel": {
       "default": {
-        "mode": "external",
-        "startWithDodo": true,
+        "connectionMode": "local",
         "metricsPort": 21732,
         "maxRestarts": 2
       },
       "type": "object",
       "properties": {
-        "mode": {
-          "default": "external",
+        "connectionMode": {
+          "default": "local",
           "type": "string",
           "enum": [
-            "external",
-            "managed"
+            "local",
+            "tunnel"
           ]
         },
-        "startWithDodo": {
-          "default": true,
-          "type": "boolean"
-        },
         "credentialRef": {
           "oneOf": [
             {
@@ -456,8 +451,7 @@
         }
       },
       "required": [
-        "mode",
-        "startWithDodo",
+        "connectionMode",
         "metricsPort",
         "maxRestarts"
       ],