feat: add tunnel basic auth

Author: gitlayzer

.dockerignore

@@ -0,0 +1,16 @@
+.git
+.github
+.DS_Store
+
+sealtun
+dist
+tmp
+*.tmp
+
+docs
+homepage
+packages
+
+coverage.out
+*.test
+

.github/workflows/ci.yml

@@ -31,6 +31,12 @@ jobs:
       - name: Run tests
         run: go test ./...
 
+      - name: Run vet
+        run: go vet ./...
+
+      - name: Check npm package builder syntax
+        run: node --check scripts/build-npm-packages.mjs
+
   goreleaser-snapshot:
     runs-on: ubuntu-latest
     needs: test

.github/workflows/release.yml

@@ -31,6 +31,15 @@ jobs:
           go-version: '1.25.10'
           cache: true
 
+      - name: Run tests
+        run: go test ./...
+
+      - name: Run vet
+        run: go vet ./...
+
+      - name: Check npm package builder syntax
+        run: node --check scripts/build-npm-packages.mjs
+
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v6
         with:

.gitignore

@@ -3,6 +3,7 @@
 /sealtun
 /sealtun.exe
 /packages/
+/homepage/
 
 # Generated copyright application artifacts
 /docs/copyright/

Makefile

@@ -10,14 +10,17 @@ BINARY_NAME=sealtun
 
 # Get version from git (Pure Git Hash mode)
 VERSION ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo "dev")
-NPM_VERSION ?= $(shell (git describe --tags --abbrev=0 2>/dev/null || echo v0.0.0) | sed 's/^v//')
+NPM_LATEST_RELEASE_TAG ?= $(shell git describe --tags --abbrev=0 2>/dev/null || echo v0.0.0)
+NPM_VERSION ?= $(shell echo $(NPM_LATEST_RELEASE_TAG) | sed 's/^v//')
 NPM_RELEASE_TAG ?= v$(NPM_VERSION)
 NPM_GITHUB_REPO ?= gitlayzer/sealtun
 NPM_PACKAGE_NAME ?= sealtun
 NPM_BINARY_PACKAGE_SCOPE ?= @gitlayzer
 NPM_PACKAGES_DIR ?= packages
 NPM_DIST_TAG ?= latest
-NPM_PUBLISH_FLAGS ?=
+NPM_PUBLISH_FLAGS ?= --access public
+NPM_DRY_RUN_VERSION ?= 0.0.0-dry-run.$(shell date +%Y%m%d%H%M%S)
+NPM_DRY_RUN_RELEASE_TAG ?= $(NPM_LATEST_RELEASE_TAG)
 
 # Build flags
 LDFLAGS=-ldflags "-s -w -X github.com/labring/sealtun/pkg/version.Version=$(VERSION)"
@@ -77,6 +80,8 @@ npm-publish: npm-packages
 	(cd "$(NPM_PACKAGES_DIR)" && $(NPM) publish --tag "$(NPM_DIST_TAG)" $(NPM_PUBLISH_FLAGS))
 
 ## npm-publish-dry-run: verify the npm publish payload without publishing
+npm-publish-dry-run: NPM_VERSION := $(NPM_DRY_RUN_VERSION)
+npm-publish-dry-run: NPM_RELEASE_TAG := $(NPM_DRY_RUN_RELEASE_TAG)
 npm-publish-dry-run: NPM_PUBLISH_FLAGS += --dry-run
 npm-publish-dry-run: npm-publish
 

README.md

@@ -75,7 +75,7 @@ make build
 ./sealtun --version
 ```
 
-`make build` 默认会把当前 Git short hash 注入到本地二进制的 version 中，用于确认本地二进制和已 push 的代码提交一致。正式 tag 发布时，GitHub Actions 会用 tag 版本构建 GitHub Release 产物和容器镜像。
+`make build` 默认会把当前 Git short hash 注入到本地二进制的 version 中，用于确认本地二进制和已 push 的代码提交一致。未打 tag 的本地构建会使用 `latest` 远端隧道镜像；正式 tag 发布时，GitHub Actions 会用 tag 版本构建 GitHub Release 产物和同版本容器镜像。
 
 ## 🚢 发版流程
 
@@ -94,6 +94,15 @@ git push origin vX.Y.Z
 
 推送 `v*` tag 后，GitHub Actions 会触发 GoReleaser 生成多平台二进制和 GitHub Release；Docker workflow 会同步构建并发布 `ghcr.io/gitlayzer/sealtun` 镜像。发版后建议重新执行 `make build && ./sealtun --version`，确认本地二进制显示的 Git hash 与已 push 的提交一致。
 
+GitHub Release 产物构建完成后，再发布 npm 包：
+
+```bash
+NPM_VERSION=X.Y.Z NPM_RELEASE_TAG=vX.Y.Z make npm-publish-dry-run
+NPM_VERSION=X.Y.Z NPM_RELEASE_TAG=vX.Y.Z make npm-publish
+```
+
+`make npm-publish` 会先从对应 GitHub Release 下载 GoReleaser 生成的二进制资产，生成本地 `packages/` 目录，然后先发布各平台可选依赖包，最后发布主包。`packages/` 是发包中间产物，已被 `.gitignore` 忽略，不提交到远端。
+
 ## 🚀 快速上手
 
 ### 1. 登录到 Sealos
@@ -134,6 +143,18 @@ sealtun expose 3000
 
 ```
 
+为公网业务流量启用 Basic Auth：
+```bash
+# 推荐：从环境变量读取密码，避免进入 shell history
+export SEALTUN_BASIC_AUTH_PASSWORD='change-me'
+sealtun expose 3000 --basic-auth-user admin --basic-auth-password-env SEALTUN_BASIC_AUTH_PASSWORD
+
+# 也支持一次性写法
+sealtun expose 3000 --basic-auth admin:change-me
+```
+
+Basic Auth 由 Sealtun server 代理层校验，不依赖 Ingress annotation；它只保护公网业务路径，不会拦截 `/_sealtun/ws` 隧道控制通道、健康检查或受内部 Bearer secret 保护的 metrics。
+
 Sealtun 会自动执行以下操作：
 1. 在你的 Sealos Namespace 中启动一个隧道代理 Pod。
 2. 配置 Ingress 路由规则。
@@ -212,6 +233,8 @@ tunnels:
     localPort: 3000
     protocol: https
     domain: app.example.com
+    basicAuth:
+      credential: admin:change-me
     waitDomain: false
     readyTimeout: 90s
     domainTimeout: 5m
@@ -226,6 +249,20 @@ sealtun apply -f sealtun.yaml --dry-run
 sealtun apply -f sealtun.yaml
 ```
 
+也可以使用展开的明文写法：
+```yaml
+basicAuth:
+  username: admin
+  password: change-me
+```
+
+或从环境变量读取密码：
+```yaml
+basicAuth:
+  username: admin
+  passwordEnv: SEALTUN_BASIC_AUTH_PASSWORD
+```
+
 `name` 会作为稳定 tunnel ID 使用，因此重复执行 `apply` 会更新同一个 `sealtun-<name>` 资源。自定义域名仍然遵循 CNAME 先验证再绑定的规则；新隧道如果 CNAME 未就绪，`apply` 会先保留 Sealos 官方域名并输出后续 `domain set` 指令；已有隧道则会拒绝未验证的自定义域名变更，避免误清理或覆盖正在使用的域名配置。
 
 ## 🛠️ 架构详情

README_EN.md

@@ -2,7 +2,7 @@
 
 [中文版本](./README.md)
 
-Sealtun is a powerful, elegant CLI tool that provides a `cloudflared` tunnel-like experience entirely built on **Sealos Cloud** and **Kubernetes**. 
+Sealtun is a powerful, elegant CLI tool that provides a `cloudflared` tunnel-like experience entirely built on **Sealos Cloud** and **Kubernetes**.
 
 It connects your local development machine straight to the internet by dynamically provisioning Kubernetes resources (Deployments, Services, Ingresses) and tunneling the traffic securely via bidirectional multiplexed WebSocket streams (`yamux`).
 
@@ -75,7 +75,7 @@ make build
 ./sealtun --version
 ```
 
-`make build` injects the current Git short hash into the local binary version by default, which makes it easy to verify that the local binary matches the pushed commit. Tagged releases are built by GitHub Actions using the tag version for GitHub Release assets and container images.
+`make build` injects the current Git short hash into the local binary version by default, which makes it easy to verify that the local binary matches the pushed commit. Untagged local builds use the `latest` remote tunnel image; tagged releases are built by GitHub Actions using the tag version for GitHub Release assets and matching container images.
 
 ## Release Process
 
@@ -94,6 +94,15 @@ git push origin vX.Y.Z
 
 Pushing a `v*` tag triggers GitHub Actions: GoReleaser builds multi-platform binaries and creates the GitHub Release, while the Docker workflow builds and publishes the matching `ghcr.io/gitlayzer/sealtun` image. After release, run `make build && ./sealtun --version` again to confirm that the local binary reports the Git hash that was pushed.
 
+After GitHub Release assets finish building, publish the npm packages:
+
+```bash
+NPM_VERSION=X.Y.Z NPM_RELEASE_TAG=vX.Y.Z make npm-publish-dry-run
+NPM_VERSION=X.Y.Z NPM_RELEASE_TAG=vX.Y.Z make npm-publish
+```
+
+`make npm-publish` downloads the GoReleaser binary assets from the matching GitHub Release, generates the local `packages/` directory, publishes each platform optional dependency first, and then publishes the main package. `packages/` is a publish-time artifact and is ignored by `.gitignore`, so it is not committed.
+
 ## Quick Start
 
 ### 1. Login to Sealos
@@ -134,6 +143,18 @@ sealtun expose 3000
 
 ```
 
+Enable Basic Auth for public application traffic:
+```bash
+# Recommended: read the password from the environment to avoid shell history
+export SEALTUN_BASIC_AUTH_PASSWORD='change-me'
+sealtun expose 3000 --basic-auth-user admin --basic-auth-password-env SEALTUN_BASIC_AUTH_PASSWORD
+
+# One-shot form is also supported
+sealtun expose 3000 --basic-auth admin:change-me
+```
+
+Basic Auth is enforced by the Sealtun server proxy layer, not by Ingress annotations. It protects only public application paths and does not block the `/_sealtun/ws` tunnel control channel, health checks, or metrics protected by the internal Bearer secret.
+
 Sealtun will:
 1. Spin up a tunnel proxy Pod in your Sealos namespace.
 2. Establish the Ingress routes.
@@ -212,6 +233,8 @@ tunnels:
     localPort: 3000
     protocol: https
     domain: app.example.com
+    basicAuth:
+      credential: admin:change-me
     waitDomain: false
     readyTimeout: 90s
     domainTimeout: 5m
@@ -226,6 +249,20 @@ sealtun apply -f sealtun.yaml --dry-run
 sealtun apply -f sealtun.yaml
 ```
 
+You can also use the expanded inline form:
+```yaml
+basicAuth:
+  username: admin
+  password: change-me
+```
+
+If you prefer not to store the password in the config file, use `passwordEnv`:
+```yaml
+basicAuth:
+  username: admin
+  passwordEnv: SEALTUN_BASIC_AUTH_PASSWORD
+```
+
 `name` is used as the stable tunnel ID, so repeated `apply` runs update the same `sealtun-<name>` resources. Custom domains still require verified CNAME ownership before attachment; for a new tunnel, `apply` keeps the Sealos-managed host and prints the follow-up `domain set` command when DNS is not ready. For an existing tunnel, `apply` rejects unverified custom-domain changes so it does not accidentally clear or overwrite a working domain configuration.
 
 ## Architecture Details