From 08a4133ed82dc9251ff08363f8589e969a00b4fe Mon Sep 17 00:00:00 2001 From: abruption Date: Mon, 19 Oct 2026 13:58:01 +0900 Subject: [PATCH 1/4] chore: prepare v0.3.1 transport hardening release --- CHANGELOG.md | 4 ++++ README.ko.md | 6 ++--- README.md | 6 ++--- VERSION | 2 +- docs/releases/v0.3.1.md | 52 +++++++++++++++++++++++++++++++++++++++++ docs/usage.ko.md | 30 ++++++++++++------------ docs/usage.md | 28 +++++++++++----------- 7 files changed, 92 insertions(+), 36 deletions(-) create mode 100644 docs/releases/v0.3.1.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f208c4d..b389e41 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ - Preserve upstream CONNECT response remainder bytes in raw tunnels (#33). - Reject malformed upstream WebSocket frames before forwarding payloads or sending pong responses (#34). +These fixes were merged in [PR #35](https://github.com/abruption/dots-tailscale/pull/35). All 157 offline tests passed on Linux Python 3.11/3.13; focused proxy and shim suites also passed on actual Python 3.8 and 3.13. The candidate has not been deployed to Dots. Startup-readiness (#25) and execution-context diagnostics (#26) remain open and are not included in this release candidate. + +See the [release preparation notes](docs/releases/v0.3.1.md). + ## v0.3.0 — 2026-10-18 - Add `dots-ts cli` for socket-aware Tailscale commands and a read-only `doctor` that reports installation, process, socket, backend, proxy and optional TCP reachability separately. diff --git a/README.ko.md b/README.ko.md index d4ac7f2..e056b19 100644 --- a/README.ko.md +++ b/README.ko.md @@ -26,7 +26,7 @@ Linux x86_64, Git, Python 3, OpenSSH와 사용자 계정의 22번 포트 바인 ```bash cd /workspace HTTPS_PROXY=http://browser-proxy:8889 HTTP_PROXY=http://browser-proxy:8889 \ - git clone --branch v0.3.0 --depth 1 https://github.com/abruption/dots-tailscale.git + git clone --branch v0.3.1 --depth 1 https://github.com/abruption/dots-tailscale.git cd dots-tailscale bash tailscale-setup.sh check bash tailscale-setup.sh install @@ -35,9 +35,9 @@ bash /workspace/.dots-tailscale/start.sh login 최초 로그인 URL을 승인한 뒤 SSH 공개키를 설치 경로의 `authorized_keys`에 등록하세요. 호스트 키 지문은 클라우드 컴퓨터의 GUI 터미널에서 확인한 후 SSH로 접속합니다. 환경이 교체되면 `bash /workspace/.dots-tailscale/start.sh`로 기존 설치를 수동 기동하세요. -## v0.3.0: 진단과 비공개 HTTP 접속 +## v0.3.1: 진단과 비공개 HTTP 접속 -아래 도구를 사용하려면 [v0.3.0](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.0)의 소스 파일 네 개를 함께 설치하세요. +아래 도구를 사용하려면 [v0.3.1](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.1)의 소스 파일 네 개를 함께 설치하세요. ```bash /workspace/.dots-tailscale/dots-ts doctor diff --git a/README.md b/README.md index a3decc4..387d0a9 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ The clone command explicitly uses the Dots proxy because direct GitHub HTTPS fai ```bash cd /workspace HTTPS_PROXY=http://browser-proxy:8889 HTTP_PROXY=http://browser-proxy:8889 \ - git clone --branch v0.3.0 --depth 1 https://github.com/abruption/dots-tailscale.git + git clone --branch v0.3.1 --depth 1 https://github.com/abruption/dots-tailscale.git cd dots-tailscale bash tailscale-setup.sh check bash tailscale-setup.sh install @@ -35,9 +35,9 @@ bash /workspace/.dots-tailscale/start.sh login The first login prints an approval URL. Add the client public key to the installed SSH `authorized_keys` file and verify the host-key fingerprint over the cloud computer's GUI terminal before connecting. After environment replacement, start the existing installation with `bash /workspace/.dots-tailscale/start.sh`. The scripts do not register automatic startup. -## v0.3.0: diagnostics and private HTTP access +## v0.3.1: diagnostics and private HTTP access -Install all four source files from [v0.3.0](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.0) to use these helpers. +Install all four source files from [v0.3.1](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.1) to use these helpers. ```bash /workspace/.dots-tailscale/dots-ts doctor diff --git a/VERSION b/VERSION index 0d91a54..9e11b32 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.3.0 +0.3.1 diff --git a/docs/releases/v0.3.1.md b/docs/releases/v0.3.1.md new file mode 100644 index 0000000..31c7466 --- /dev/null +++ b/docs/releases/v0.3.1.md @@ -0,0 +1,52 @@ +# v0.3.1 release preparation + +This PR prepares the version and download instructions. Tag creation, GitHub Release publication and live deployment require their respective maintainer actions after review. The v0.3.1 URLs in the candidate documentation become available when the release is published; the current published release remains v0.3.0 until then. + +## Release summary + +v0.3.1 fixes three proxy/transport defects from [PR #35](https://github.com/abruption/dots-tailscale/pull/35): + +- **Proxy apply and recovery (#32):** open and validate the private log before stopping the current daemon. Replacement and rollback reuse the same descriptor even if the path changes. +- **CONNECT data preservation (#33):** forward raw tunnel bytes buffered with the upstream response exactly once and in order. For TLS interception on port443, reject unexpected pre-handshake bytes before reporting success rather than discard them. +- **WebSocket framing (#34):** reject masked/reserved-bit frames, invalid control frames, malformed lengths and continuation sequences before forwarding their payloads or sending pong. Valid fragmentation and interleaved control frames remain supported. + +Tailscale remains **1.102.4**. Installation still requires all four source files together: `tailscale-setup.sh`, `shim.py`, `dots-ts` and `dots_proxy.py`. Installation state and keys must be preserved during staged upgrades. + +## Verification and remaining scope + +- [Implementation CI](https://github.com/abruption/dots-tailscale/actions/runs/39201120437) passed **157** tests on each of Python3.11 and3.13, plus Bash syntax/ShellCheck. +- Focused proxy tests: 34 total, one Linux-only skip on macOS; focused shim tests: 45 passed, on actual Python3.8 and3.13. +- [Codex review of the final implementation commit](https://github.com/abruption/dots-tailscale/pull/35#issuecomment-6259931703) reported no major issues. The Linux reset/EOF finding was addressed in `89e0f37`. +- Process-control tests use inert mocks and disposable files. Shim tests use isolated transports/socket peers. No live deployment or forced outage is established by these results. +- The current 24-hour watchdog experiment belongs to #20 and uses the installed v0.3.0 environment; its pending results are not v0.3.1 deployment evidence. +- **#25 and #26 remain open in the v0.3.1 milestone and are not implemented here.** Decide whether to include them before publication or explicitly release the three completed fixes first. Do not close the whole milestone while those issues remain unresolved. +- VM replacement recovery, permanent automatic startup and automatic updates are not provided. No full WebSocket text UTF-8/close-status validation or new frame memory limit is claimed. + +## Publication checklist + +- [ ] Review this preparation PR and decide the remaining #25/#26 release scope. +- [ ] Merge the selected release scope, confirm `VERSION=0.3.1`, and require passing checks on the exact final commit. +- [ ] Create an annotated `v0.3.1` tag on that commit when publication is authorized. Verify an existing tag; never move it to hide a changed release. +- [ ] Package the reviewed tag only: `dots-tailscale-v0.3.1.zip`, `dots-tailscale-v0.3.1.tar.gz`, plus the four individual source files. +- [ ] Compare archive source bytes with the individual files; generate `SHA256SUMS` and attach it as the seventh asset. Exclude workspace state, local untracked files, credentials, certificates and logs. +- [ ] Create/review a draft release, attach the seven assets and publish only after its exact tag/asset digests and notes are checked. +- [ ] Verify public links, latest-release selection and uploaded asset hashes. Date the changelog using the actual publication date. + +Suggested archive commands after the tag exists, in Bash with `set -euo pipefail` and a pre-created private absolute `artifact_dir`: + +```bash +git archive --format=zip --prefix=dots-tailscale-v0.3.1/ \ + --output="$artifact_dir/dots-tailscale-v0.3.1.zip" v0.3.1 +git archive --format=tar.gz --prefix=dots-tailscale-v0.3.1/ \ + --output="$artifact_dir/dots-tailscale-v0.3.1.tar.gz" v0.3.1 +for file in tailscale-setup.sh shim.py dots-ts dots_proxy.py; do + git show "v0.3.1:$file" > "$artifact_dir/$file" +done +( + cd "$artifact_dir" + sha256sum dots-tailscale-v0.3.1.zip dots-tailscale-v0.3.1.tar.gz \ + tailscale-setup.sh shim.py dots-ts dots_proxy.py > SHA256SUMS +) +``` + +Publishing does not upgrade Dots automatically. A deployed update needs its own staged backup/restart/rollback procedure and external strict-host-key SSH verification. diff --git a/docs/usage.ko.md b/docs/usage.ko.md index 1f2e7a3..30bca95 100644 --- a/docs/usage.ko.md +++ b/docs/usage.ko.md @@ -4,7 +4,7 @@ `/workspace`가 환경 교체 후에도 유지되는 Dots 환경에서 실행합니다. 설치·인증 상태와 실행 중에만 필요한 파일을 다른 위치에 두어 재기동 시 기존 장치 신원을 이어 사용합니다. -공개 저장소 주소는 `https://github.com/abruption/dots-tailscale`입니다. 최초 공개 시 실제 clone과 raw 다운로드를 확인했습니다. [v0.3.0 릴리스](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.0)는 ZIP·tar.gz와 `tailscale-setup.sh`·`shim.py`·`dots-ts`·`dots_proxy.py` 개별 파일을 제공합니다. `main`은 이후 변경될 수 있으므로 같은 소스로 다시 설치하려면 검토한 tag나 commit을 지정하세요. +공개 저장소 주소는 `https://github.com/abruption/dots-tailscale`입니다. 최초 공개 시 실제 clone과 raw 다운로드를 확인했습니다. [v0.3.1 릴리스](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.1)는 ZIP·tar.gz와 `tailscale-setup.sh`·`shim.py`·`dots-ts`·`dots_proxy.py` 개별 파일을 제공합니다. `main`은 이후 변경될 수 있으므로 같은 소스로 다시 설치하려면 검토한 tag나 commit을 지정하세요. @@ -45,12 +45,12 @@ Linux x86_64, Python 3, OpenSSH, `timeout`, `flock`, `openssl`, `ssh-keygen`, `c Git이 설치된 VM 터미널에서 HTTPS로 저장소를 clone한 뒤 설치 스크립트를 실행합니다. Git 네트워크 요청에만 프록시 환경변수를 적용합니다. 인증서 검증은 유지합니다. -v0.3.0은 `tailscale-setup.sh`, `shim.py`, `dots-ts`, `dots_proxy.py` 네 파일을 함께 준비해야 합니다. 이전 v0.2.0은 기존 두 파일로 설치하며 새 도구가 포함되지 않습니다. +v0.3.1은 `tailscale-setup.sh`, `shim.py`, `dots-ts`, `dots_proxy.py` 네 파일을 함께 준비해야 합니다. 이전 v0.2.0은 기존 두 파일로 설치하며 새 도구가 포함되지 않습니다. ```bash cd /workspace HTTPS_PROXY=http://browser-proxy:8889 HTTP_PROXY=http://browser-proxy:8889 \ - git clone --branch v0.3.0 --depth 1 'https://github.com/abruption/dots-tailscale' dots-tailscale + git clone --branch v0.3.1 --depth 1 'https://github.com/abruption/dots-tailscale' dots-tailscale cd dots-tailscale bash tailscale-setup.sh check bash tailscale-setup.sh install @@ -87,9 +87,9 @@ ssh -o StrictHostKeyChecking=ask -i /path/to/client_private_key 'agent@ -## v0.3.0 도구와 선택적 애플리케이션 프록시 +## v0.3.1 도구와 선택적 애플리케이션 프록시 -아래 명령은 v0.3.0 파일을 함께 설치한 경우에만 사용할 수 있으며, v0.2.0에는 없습니다. `dots-ts`는 Python 3 표준 라이브러리를 사용하며 자기 위치에서 설치 경로를 찾습니다. 전역 `tailscale` 명령·소켓 심볼릭 링크·셸 프로필 변경은 필요하지 않습니다. +아래 명령은 v0.3.1 파일을 함께 설치한 경우에만 사용할 수 있으며, v0.2.0에는 없습니다. `dots-ts`는 Python 3 표준 라이브러리를 사용하며 자기 위치에서 설치 경로를 찾습니다. 전역 `tailscale` 명령·소켓 심볼릭 링크·셸 프로필 변경은 필요하지 않습니다. ```bash /workspace/.dots-tailscale/dots-ts cli status @@ -121,16 +121,16 @@ ssh -o StrictHostKeyChecking=ask -i /path/to/client_private_key 'agent@ @@ -166,7 +166,7 @@ bash /workspace/.dots-tailscale/start.sh check shim 수정이 포함된 업데이트는 **setup.sh만 교체해서 완료되지 않습니다.** 다음 절차는 운영자가 별도로 수행할 배치·복구 절차이며 현재 자동 updater로 구현돼 있지 않습니다. 2026-10-14 shim 수정본의 실환경 배포 후 DERP ping과 엄격한 호스트 키 검증을 유지한 SSH 연결은 성공했습니다. 수정본 상태에서 이후 VM 교체를 거친 복구는 아직 관찰하지 않았습니다. 자세한 범위는 아래 [현재 확인한 범위](#current-validation)를 참고하세요. -v0.3.0으로 업데이트할 때는 같은 commit의 `dots-ts`와 `dots_proxy.py`도 준비합니다. 아래 호환성 블록은 기존 setup·shim만 검증하므로 두 Python 도구는 실행하지 않고 추가 구문 검사하고 네 파일의 해시를 기록하세요. 배포·되돌리기에서도 `setup.sh`와 `shim/shim.py`에 더해 설치 루트의 `dots-ts`·`dots_proxy.py`를 권한 `700`으로 함께 관리합니다. `outbound-proxy.json`과 노드 신원 파일은 보존하세요. 문서나 코드 갱신 중 부수적인 단계로 프록시를 적용하거나 데몬을 재시작하지 마세요. +v0.3.1으로 업데이트할 때는 같은 commit의 `dots-ts`와 `dots_proxy.py`도 준비합니다. 아래 호환성 블록은 기존 setup·shim만 검증하므로 두 Python 도구는 실행하지 않고 추가 구문 검사하고 네 파일의 해시를 기록하세요. 배포·되돌리기에서도 `setup.sh`와 `shim/shim.py`에 더해 설치 루트의 `dots-ts`·`dots_proxy.py`를 권한 `700`으로 함께 관리합니다. `outbound-proxy.json`과 노드 신원 파일은 보존하세요. 문서나 코드 갱신 중 부수적인 단계로 프록시를 적용하거나 데몬을 재시작하지 마세요. ```bash python3 -c 'from pathlib import Path; [compile(Path(p).read_text(), p, "exec") for p in ("dots-ts", "dots_proxy.py")]' @@ -204,10 +204,10 @@ sha256sum tailscale-setup.sh shim.py dots-ts dots_proxy.py ``` -3. 기존 **setup/shim 코드 파일만** 별도 보관합니다. v0.3.0은 기존 `dots-ts`·`dots_proxy.py`도 포함하고 업데이트 전 파일이 없었다면 그 사실을 기록합니다. state·CA·SSH 개인키는 복제하거나 삭제하지 않습니다. -4. GUI 터미널에서 실행 파일/명령행이 설치된 `shim/shim.py`와 일치하는 정확한 listener PID를 확인해 해당 프로세스만 종료합니다. 광범위한 `pkill python` 등은 사용하지 않습니다. 중복 shim이 없음을 확인한 뒤 `setup.sh`와 `shim/shim.py`에 검토한 파일을 모드 `700`으로 배치합니다. v0.3.0은 검토한 `dots-ts`·`dots_proxy.py`도 설치 루트에 모드 `700`으로 배치합니다. 이때 Tailscale 연결이 잠시 끊길 수 있습니다. +3. 기존 **setup/shim 코드 파일만** 별도 보관합니다. v0.3.1은 기존 `dots-ts`·`dots_proxy.py`도 포함하고 업데이트 전 파일이 없었다면 그 사실을 기록합니다. state·CA·SSH 개인키는 복제하거나 삭제하지 않습니다. +4. GUI 터미널에서 실행 파일/명령행이 설치된 `shim/shim.py`와 일치하는 정확한 listener PID를 확인해 해당 프로세스만 종료합니다. 광범위한 `pkill python` 등은 사용하지 않습니다. 중복 shim이 없음을 확인한 뒤 `setup.sh`와 `shim/shim.py`에 검토한 파일을 모드 `700`으로 배치합니다. v0.3.1은 검토한 `dots-ts`·`dots_proxy.py`도 설치 루트에 모드 `700`으로 배치합니다. 이때 Tailscale 연결이 잠시 끊길 수 있습니다. 5. 독립 터미널에서 설치된 `start.sh`를 실행합니다. 연결에 의존하는 셸에서 계속할 수밖에 없는 경우에는 먼저 제한 시간과 로그 경로를 지정한 분리 실행 및 코드 롤백 계획을 준비하세요. 이 문서는 자동 롤백이 있다고 주장하지 않습니다. -6. 설치된 코드 파일의 SHA-256이 검토한 소스와 일치하는지 확인합니다. v0.3.0은 네 파일을 모두 대조합니다. backend `Running`, 로컬 SSH 배너, 클라이언트의 tailnet ping, 엄격한 호스트 키 검증을 유지한 SSH 공개키 로그인·명령 실행을 각각 검사하고 종료코드·일시를 기록합니다. +6. 설치된 코드 파일의 SHA-256이 검토한 소스와 일치하는지 확인합니다. v0.3.1은 네 파일을 모두 대조합니다. backend `Running`, 로컬 SSH 배너, 클라이언트의 tailnet ping, 엄격한 호스트 키 검증을 유지한 SSH 공개키 로그인·명령 실행을 각각 검사하고 종료코드·일시를 기록합니다. 7. 실패 시 독립 터미널에서 이전 **코드만** 복원하고 필요한 프로세스를 다시 기동합니다. 실패·롤백 결과를 기록하며 인증 파일 초기화로 해결하지 않습니다. 환경 교체 후에는 `start.sh`를 직접 실행해야 합니다. 자동 시작이나 Dots 자동화 등록 기능은 구현하지 않았으며, Dots 자동화로 기동하는 방식도 시험하지 않았습니다. diff --git a/docs/usage.md b/docs/usage.md index bff1bab..cf1996e 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -6,7 +6,7 @@ These instructions target a user-level installation in an environment that prese ## Published version and verification -The initial public repository clone and raw downloads were verified against the prepared source. [Release v0.3.0](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.0) includes ZIP and tar.gz archives plus `tailscale-setup.sh`, `shim.py`, `dots-ts`, and `dots_proxy.py` as individual assets. The installation examples pin the source to `v0.3.0`. The bundled Tailscale version remains `1.102.4`. +The initial public repository clone and raw downloads were verified against the prepared source. [Release v0.3.1](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.1) includes ZIP and tar.gz archives plus `tailscale-setup.sh`, `shim.py`, `dots-ts`, and `dots_proxy.py` as individual assets. The installation examples pin the source to `v0.3.1`. The bundled Tailscale version remains `1.102.4`. ![Dots desktop terminal screenshot of installation checks and Tailscale version](assets/dots-tailscale-ssh-verification.png) @@ -50,12 +50,12 @@ The local shim does not configure a global proxy or route unrelated applications Clone the repository from `https://github.com/abruption/dots-tailscale` into `/workspace` so the setup script and `shim.py` are available together. Cloning requires Git and GitHub HTTPS access through the cloud computer's proxy. The setup requires Linux x86_64, Python 3, `timeout`, `flock`, OpenSSL, `ssh-keygen`, and `/usr/sbin/sshd`. Installation additionally requires curl, tar, and sha256sum. Binding port 22 must be allowed for the current user; root or systemd is not required. -For v0.3.0, keep all four source files together: `tailscale-setup.sh`, `shim.py`, `dots-ts`, and `dots_proxy.py`. The older v0.2.0 installation uses only the original two files and does not include these helpers. +For v0.3.1, keep all four source files together: `tailscale-setup.sh`, `shim.py`, `dots-ts`, and `dots_proxy.py`. The older v0.2.0 installation uses only the original two files and does not include these helpers. ```bash cd /workspace HTTPS_PROXY=http://browser-proxy:8889 HTTP_PROXY=http://browser-proxy:8889 \ - git clone --branch v0.3.0 --depth 1 'https://github.com/abruption/dots-tailscale' dots-tailscale + git clone --branch v0.3.1 --depth 1 'https://github.com/abruption/dots-tailscale' dots-tailscale cd dots-tailscale bash tailscale-setup.sh check bash tailscale-setup.sh install @@ -139,9 +139,9 @@ There is no VM cron, systemd service, or automatic startup registration in this -## v0.3.0 helpers and optional application proxies +## v0.3.1 helpers and optional application proxies -These commands require the v0.3.0 files installed together; they are not available in release v0.2.0. `dots-ts` uses Python 3's standard library and finds the installation from its own location. No global `tailscale` command, socket symlink, or shell profile change is needed. +These commands require the v0.3.1 files installed together; they are not available in release v0.2.0. `dots-ts` uses Python 3's standard library and finds the installation from its own location. No global `tailscale` command, socket symlink, or shell profile change is needed. ```bash /workspace/.dots-tailscale/dots-ts cli status @@ -173,16 +173,16 @@ Applying a changed configuration requires an explicit daemon restart and can int Application proxies listen on loopback for explicitly configured local clients. They are distinct from the daemon's TLS/WebSocket shim on `127.0.0.1:18089`. Do not use that shim as an application HTTP proxy. Set a proxy on an individual curl request or child process; there is no global environment, browser, MCP, or ChatGPT connector propagation. Local processes that can reach the loopback proxy can attempt to use it, so network policy and API authentication are still required. -### Install v0.3.0 without Git +### Install v0.3.1 without Git Download all four release files into a separate source directory. Stop if any request fails, and review the files and hashes before installation: ```bash ( set -euo pipefail - mkdir -p /workspace/dots-tailscale-v0.3.0 - cd /workspace/dots-tailscale-v0.3.0 - DOTS_TS_REF=v0.3.0 + mkdir -p /workspace/dots-tailscale-v0.3.1 + cd /workspace/dots-tailscale-v0.3.1 + DOTS_TS_REF=v0.3.1 for file in tailscale-setup.sh shim.py dots-ts dots_proxy.py; do curl -fsSL --proxy http://browser-proxy:8889 --connect-timeout 5 --max-time 60 \ "https://github.com/abruption/dots-tailscale/releases/download/${DOTS_TS_REF}/${file}" \ @@ -195,13 +195,13 @@ Download all four release files into a separate source directory. Stop if any re After all downloads succeed and you have reviewed the files, run these commands for a fresh installation: ```bash -cd /workspace/dots-tailscale-v0.3.0 +cd /workspace/dots-tailscale-v0.3.1 bash tailscale-setup.sh check bash tailscale-setup.sh install bash /workspace/.dots-tailscale/start.sh login ``` -Keep all four files in the same directory before running setup. If the release-asset host is unavailable, use the same tag and filenames at `https://raw.githubusercontent.com/abruption/dots-tailscale/v0.3.0/`, or transfer the reviewed files from another trusted device. For an existing installation, use the update procedure below; `install` does not overwrite differing installed source files. +Keep all four files in the same directory before running setup. If the release-asset host is unavailable, use the same tag and filenames at `https://raw.githubusercontent.com/abruption/dots-tailscale/v0.3.1/`, or transfer the reviewed files from another trusted device. For an existing installation, use the update procedure below; `install` does not overwrite differing installed source files. ### Optional noninteractive authentication @@ -242,7 +242,7 @@ Custom paths are available through `--home` and `--probe-root`. No periodic exec There is no automatic updater. Stage and review `tailscale-setup.sh` and `shim.py` together outside `/workspace/.dots-tailscale`, using a selected commit or release rather than updating installed files in place from a moving branch. Record that version and both SHA-256 hashes. Validate the staged shell syntax and parse the staged Python source before changing the installation. -When updating to v0.3.0, also stage `dots-ts` and `dots_proxy.py` from that exact commit. The compatibility block below validates the original setup/shim pair; it does not validate the new helpers. Additionally compile both Python helpers without executing them and record all four source hashes. In the deployment and rollback steps, include `dots-ts` and `dots_proxy.py` at the installation root alongside `setup.sh` and `shim/shim.py`, with mode `700`. Preserve `outbound-proxy.json` and node identity files. Do not apply a proxy configuration or restart the daemon as an incidental documentation/update step. +When updating to v0.3.1, also stage `dots-ts` and `dots_proxy.py` from that exact commit. The compatibility block below validates the original setup/shim pair; it does not validate the new helpers. Additionally compile both Python helpers without executing them and record all four source hashes. In the deployment and rollback steps, include `dots-ts` and `dots_proxy.py` at the installation root alongside `setup.sh` and `shim/shim.py`, with mode `700`. Preserve `outbound-proxy.json` and node identity files. Do not apply a proxy configuration or restart the daemon as an incidental documentation/update step. ```bash python3 -c 'from pathlib import Path; [compile(Path(p).read_text(), p, "exec") for p in ("dots-ts", "dots_proxy.py")]' @@ -282,8 +282,8 @@ Use a separate staging checkout at `/workspace/dots-tailscale` (adjust the path Use this deployment sequence when the shim changes: 1. Open the cloud computer's platform GUI terminal, independently of Tailscale SSH. Keep that terminal available for recovery. Record the installed `setup.sh` and `shim/shim.py` hashes, the node address, and the public SSH host-key fingerprint outside the VM. Confirm an authenticated baseline and record it separately from the candidate version. -2. Save private rollback copies of the old `setup.sh` and `shim/shim.py` source files only; for v0.3.0 also include existing `dots-ts` and `dots_proxy.py` and record whether they were absent before the update. Leave authentication state, CA keys, SSH host keys, and authorized keys in place; do not copy state into another installation. Have a bounded, detached restart plan and a rollback plan ready before stopping a process. The detached action must survive loss of the SSH session; this repository does not implement that updater for you. -3. Identify the running shim by its exact command line and installed script path. From the independent terminal, stop only that identified shim PID. Do not use broad process-name termination. Confirm it exited and that no duplicate shim remains. Install the staged `shim.py` at `shim/shim.py` and the staged `tailscale-setup.sh` at `setup.sh`, with mode `700`. For v0.3.0, also place the staged `dots-ts` and `dots_proxy.py` at the installation root with mode `700`. +2. Save private rollback copies of the old `setup.sh` and `shim/shim.py` source files only; for v0.3.1 also include existing `dots-ts` and `dots_proxy.py` and record whether they were absent before the update. Leave authentication state, CA keys, SSH host keys, and authorized keys in place; do not copy state into another installation. Have a bounded, detached restart plan and a rollback plan ready before stopping a process. The detached action must survive loss of the SSH session; this repository does not implement that updater for you. +3. Identify the running shim by its exact command line and installed script path. From the independent terminal, stop only that identified shim PID. Do not use broad process-name termination. Confirm it exited and that no duplicate shim remains. Install the staged `shim.py` at `shim/shim.py` and the staged `tailscale-setup.sh` at `setup.sh`, with mode `700`. For v0.3.1, also place the staged `dots-ts` and `dots_proxy.py` at the installation root with mode `700`. 4. Execute the prepared detached startup, then compare the installed source hashes with the staged hashes. Confirm a single shim and the expected daemon processes. Check Tailscale CLI state and the local SSH banner in the independent terminal, then test external DERP connectivity and a real SSH command with strict host-key verification. Record the results against the candidate version. 5. If validation fails, use the independent terminal to stop only the identified candidate shim, restore the old source files, and run startup again. Recheck the old hashes and baseline connection. Preserve existing state and keys throughout rollback; investigate any unexpected host-key change instead of accepting it. From bae1d7dd04db1a428f67bbee5327b01112cda30e Mon Sep 17 00:00:00 2001 From: abruption Date: Mon, 19 Oct 2026 14:02:53 +0900 Subject: [PATCH 2/4] docs: include startup and context fixes in v0.3.1 scope --- CHANGELOG.md | 4 +++- docs/releases/v0.3.1.md | 8 +++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b389e41..f5ffc09 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,11 +2,13 @@ ## v0.3.1 — unreleased +- Wait for transient startup backend states within a bounded readiness deadline and distinguish authentication, approval and query failures (#25). +- Explain read-only installation/runtime access and socket visibility in the current execution context, with safe GUI-terminal guidance (#26). - Validate and retain the proxy apply log descriptor before stopping the current daemon, including rollback launches (#32). - Preserve upstream CONNECT response remainder bytes in raw tunnels (#33). - Reject malformed upstream WebSocket frames before forwarding payloads or sending pong responses (#34). -These fixes were merged in [PR #35](https://github.com/abruption/dots-tailscale/pull/35). All 157 offline tests passed on Linux Python 3.11/3.13; focused proxy and shim suites also passed on actual Python 3.8 and 3.13. The candidate has not been deployed to Dots. Startup-readiness (#25) and execution-context diagnostics (#26) remain open and are not included in this release candidate. +These fixes were merged in [PR #35](https://github.com/abruption/dots-tailscale/pull/35). All 157 offline tests passed on Linux Python 3.11/3.13; focused proxy and shim suites also passed on actual Python 3.8 and 3.13. The candidate has not been deployed to Dots. Startup-readiness (#25) and execution-context diagnostics (#26) are also planned for this release; their implementation PRs must pass review and merge before publication. See the [release preparation notes](docs/releases/v0.3.1.md). diff --git a/docs/releases/v0.3.1.md b/docs/releases/v0.3.1.md index 31c7466..9760643 100644 --- a/docs/releases/v0.3.1.md +++ b/docs/releases/v0.3.1.md @@ -4,8 +4,10 @@ This PR prepares the version and download instructions. Tag creation, GitHub Rel ## Release summary -v0.3.1 fixes three proxy/transport defects from [PR #35](https://github.com/abruption/dots-tailscale/pull/35): +v0.3.1 includes startup-readiness and execution-context diagnostics (#25/#26), together with three proxy/transport fixes from [PR #35](https://github.com/abruption/dots-tailscale/pull/35): +- **Startup readiness (#25):** wait for transient backend states within an overall deadline and distinguish authentication, approval and query failures. +- **Execution-context diagnostics (#26):** report read-only filesystem/access and socket visibility in the current context, with independent GUI-terminal guidance. - **Proxy apply and recovery (#32):** open and validate the private log before stopping the current daemon. Replacement and rollback reuse the same descriptor even if the path changes. - **CONNECT data preservation (#33):** forward raw tunnel bytes buffered with the upstream response exactly once and in order. For TLS interception on port443, reject unexpected pre-handshake bytes before reporting success rather than discard them. - **WebSocket framing (#34):** reject masked/reserved-bit frames, invalid control frames, malformed lengths and continuation sequences before forwarding their payloads or sending pong. Valid fragmentation and interleaved control frames remain supported. @@ -19,12 +21,12 @@ Tailscale remains **1.102.4**. Installation still requires all four source files - [Codex review of the final implementation commit](https://github.com/abruption/dots-tailscale/pull/35#issuecomment-6259931703) reported no major issues. The Linux reset/EOF finding was addressed in `89e0f37`. - Process-control tests use inert mocks and disposable files. Shim tests use isolated transports/socket peers. No live deployment or forced outage is established by these results. - The current 24-hour watchdog experiment belongs to #20 and uses the installed v0.3.0 environment; its pending results are not v0.3.1 deployment evidence. -- **#25 and #26 remain open in the v0.3.1 milestone and are not implemented here.** Decide whether to include them before publication or explicitly release the three completed fixes first. Do not close the whole milestone while those issues remain unresolved. +- **#25 and #26 are part of the intended release scope.** Their implementation PRs require passing checks, review and merge before publication. Do not close the milestone or tag a candidate that omits them. - VM replacement recovery, permanent automatic startup and automatic updates are not provided. No full WebSocket text UTF-8/close-status validation or new frame memory limit is claimed. ## Publication checklist -- [ ] Review this preparation PR and decide the remaining #25/#26 release scope. +- [ ] Review and merge the #25 and #26 implementation PRs, then review this preparation PR against the final combined code. - [ ] Merge the selected release scope, confirm `VERSION=0.3.1`, and require passing checks on the exact final commit. - [ ] Create an annotated `v0.3.1` tag on that commit when publication is authorized. Verify an existing tag; never move it to hide a changed release. - [ ] Package the reviewed tag only: `dots-tailscale-v0.3.1.zip`, `dots-tailscale-v0.3.1.tar.gz`, plus the four individual source files. From 8402889cd6fc384d27eb5124a01107327137de35 Mon Sep 17 00:00:00 2001 From: abruption Date: Mon, 19 Oct 2026 14:03:09 +0900 Subject: [PATCH 3/4] docs: link v0.3.1 implementation prerequisites --- CHANGELOG.md | 2 +- docs/releases/v0.3.1.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f5ffc09..f3b49b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ - Preserve upstream CONNECT response remainder bytes in raw tunnels (#33). - Reject malformed upstream WebSocket frames before forwarding payloads or sending pong responses (#34). -These fixes were merged in [PR #35](https://github.com/abruption/dots-tailscale/pull/35). All 157 offline tests passed on Linux Python 3.11/3.13; focused proxy and shim suites also passed on actual Python 3.8 and 3.13. The candidate has not been deployed to Dots. Startup-readiness (#25) and execution-context diagnostics (#26) are also planned for this release; their implementation PRs must pass review and merge before publication. +These fixes were merged in [PR #35](https://github.com/abruption/dots-tailscale/pull/35). All 157 offline tests passed on Linux Python 3.11/3.13; focused proxy and shim suites also passed on actual Python 3.8 and 3.13. The candidate has not been deployed to Dots. Startup-readiness [PR #36](https://github.com/abruption/dots-tailscale/pull/36) and execution-context diagnostics [PR #37](https://github.com/abruption/dots-tailscale/pull/37) are integrated into the release candidate; review and merge both before publication. See the [release preparation notes](docs/releases/v0.3.1.md). diff --git a/docs/releases/v0.3.1.md b/docs/releases/v0.3.1.md index 9760643..adf4539 100644 --- a/docs/releases/v0.3.1.md +++ b/docs/releases/v0.3.1.md @@ -21,7 +21,7 @@ Tailscale remains **1.102.4**. Installation still requires all four source files - [Codex review of the final implementation commit](https://github.com/abruption/dots-tailscale/pull/35#issuecomment-6259931703) reported no major issues. The Linux reset/EOF finding was addressed in `89e0f37`. - Process-control tests use inert mocks and disposable files. Shim tests use isolated transports/socket peers. No live deployment or forced outage is established by these results. - The current 24-hour watchdog experiment belongs to #20 and uses the installed v0.3.0 environment; its pending results are not v0.3.1 deployment evidence. -- **#25 and #26 are part of the intended release scope.** Their implementation PRs require passing checks, review and merge before publication. Do not close the milestone or tag a candidate that omits them. +- **#25 and #26 are part of the intended release scope.** [PR #36](https://github.com/abruption/dots-tailscale/pull/36) and [PR #37](https://github.com/abruption/dots-tailscale/pull/37) are integrated into this candidate and require passing checks, review and merge before publication. Do not close the milestone or tag a candidate that omits them. - VM replacement recovery, permanent automatic startup and automatic updates are not provided. No full WebSocket text UTF-8/close-status validation or new frame memory limit is claimed. ## Publication checklist From 45e069b1b72c336b9dc05cd994d7a99cca22edf2 Mon Sep 17 00:00:00 2001 From: abruption Date: Mon, 19 Oct 2026 14:44:49 +0900 Subject: [PATCH 4/4] docs: finalize v0.3.1 publication record --- CHANGELOG.md | 4 ++-- docs/releases/v0.3.1.md | 7 ++++--- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f3b49b1..d240870 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## v0.3.1 — unreleased +## v0.3.1 — 2026-10-19 - Wait for transient startup backend states within a bounded readiness deadline and distinguish authentication, approval and query failures (#25). - Explain read-only installation/runtime access and socket visibility in the current execution context, with safe GUI-terminal guidance (#26). @@ -8,7 +8,7 @@ - Preserve upstream CONNECT response remainder bytes in raw tunnels (#33). - Reject malformed upstream WebSocket frames before forwarding payloads or sending pong responses (#34). -These fixes were merged in [PR #35](https://github.com/abruption/dots-tailscale/pull/35). All 157 offline tests passed on Linux Python 3.11/3.13; focused proxy and shim suites also passed on actual Python 3.8 and 3.13. The candidate has not been deployed to Dots. Startup-readiness [PR #36](https://github.com/abruption/dots-tailscale/pull/36) and execution-context diagnostics [PR #37](https://github.com/abruption/dots-tailscale/pull/37) are integrated into the release candidate; review and merge both before publication. +These fixes were merged in [PR #35](https://github.com/abruption/dots-tailscale/pull/35). The final combined candidate passed all 178 offline tests on Linux Python 3.11/3.13; focused proxy, shim, CLI and readiness suites also passed on actual Python 3.8/3.13. The candidate has not been deployed to Dots. Startup-readiness [PR #36](https://github.com/abruption/dots-tailscale/pull/36) and execution-context diagnostics [PR #37](https://github.com/abruption/dots-tailscale/pull/37) are merged and included in this release. See the [release preparation notes](docs/releases/v0.3.1.md). diff --git a/docs/releases/v0.3.1.md b/docs/releases/v0.3.1.md index adf4539..32066c9 100644 --- a/docs/releases/v0.3.1.md +++ b/docs/releases/v0.3.1.md @@ -1,6 +1,6 @@ # v0.3.1 release preparation -This PR prepares the version and download instructions. Tag creation, GitHub Release publication and live deployment require their respective maintainer actions after review. The v0.3.1 URLs in the candidate documentation become available when the release is published; the current published release remains v0.3.0 until then. +Release preparation record for v0.3.1. The implementation PRs and the integrated candidate were reviewed before publication. Tag creation, asset validation and publication follow the checklist below; installed environments require a separate explicit deployment. ## Release summary @@ -17,16 +17,17 @@ Tailscale remains **1.102.4**. Installation still requires all four source files ## Verification and remaining scope - [Implementation CI](https://github.com/abruption/dots-tailscale/actions/runs/39201120437) passed **157** tests on each of Python3.11 and3.13, plus Bash syntax/ShellCheck. +- [Combined candidate CI](https://github.com/abruption/dots-tailscale/actions/runs/39205008955) passed all **178** tests on Linux Python 3.11/3.13 after the explicit-login/approval follow-up. [PR #36 re-review](https://github.com/abruption/dots-tailscale/pull/36#issuecomment-6260462216) and [PR #38 re-review](https://github.com/abruption/dots-tailscale/pull/38#issuecomment-6260469116) reported no additional findings. - Focused proxy tests: 34 total, one Linux-only skip on macOS; focused shim tests: 45 passed, on actual Python3.8 and3.13. - [Codex review of the final implementation commit](https://github.com/abruption/dots-tailscale/pull/35#issuecomment-6259931703) reported no major issues. The Linux reset/EOF finding was addressed in `89e0f37`. - Process-control tests use inert mocks and disposable files. Shim tests use isolated transports/socket peers. No live deployment or forced outage is established by these results. - The current 24-hour watchdog experiment belongs to #20 and uses the installed v0.3.0 environment; its pending results are not v0.3.1 deployment evidence. -- **#25 and #26 are part of the intended release scope.** [PR #36](https://github.com/abruption/dots-tailscale/pull/36) and [PR #37](https://github.com/abruption/dots-tailscale/pull/37) are integrated into this candidate and require passing checks, review and merge before publication. Do not close the milestone or tag a candidate that omits them. +- **#25 and #26 are included.** [PR #36](https://github.com/abruption/dots-tailscale/pull/36) and [PR #37](https://github.com/abruption/dots-tailscale/pull/37) were reviewed, passed CI and merged before the release preparation PR. - VM replacement recovery, permanent automatic startup and automatic updates are not provided. No full WebSocket text UTF-8/close-status validation or new frame memory limit is claimed. ## Publication checklist -- [ ] Review and merge the #25 and #26 implementation PRs, then review this preparation PR against the final combined code. +- [x] Review and merge the #25 and #26 implementation PRs, then review this preparation PR against the final combined code. - [ ] Merge the selected release scope, confirm `VERSION=0.3.1`, and require passing checks on the exact final commit. - [ ] Create an annotated `v0.3.1` tag on that commit when publication is authorized. Verify an existing tag; never move it to hide a changed release. - [ ] Package the reviewed tag only: `dots-tailscale-v0.3.1.zip`, `dots-tailscale-v0.3.1.tar.gz`, plus the four individual source files.