Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
5e85b13
feat: make deployment compatibility explicit and expose reusable auth…
2018wzh Oct 2, 2026
f383a7b
feat: allow embedders to restrict resolved destinations
2018wzh Oct 2, 2026
5bb65f9
Merge pull request #4 from nanakusa-electronics/codex/geektrust-sdk-i…
vvbbnn00 Oct 5, 2026
4bdc974
refactor: unify runtime and versioned client contracts
vvbbnn00 Oct 5, 2026
b319f63
fix(config): clarify session state path override
vvbbnn00 Oct 5, 2026
32bcc3a
build: update Go toolchain and networking dependencies
vvbbnn00 Oct 7, 2026
02f41e8
refactor(sdk): unify compatibility and bind operations to session lif…
vvbbnn00 Oct 7, 2026
c7ad9e4
fix(controller): constrain redirects and validate response envelopes
vvbbnn00 Oct 7, 2026
e24a806
fix(tunnel): preserve framed TCP reads, writes and close semantics
vvbbnn00 Oct 7, 2026
802b920
feat(web): rebuild panel with shadcn UI and selectable themes
vvbbnn00 Oct 7, 2026
69b9774
fix(build): reject unsafe archive extraction paths
vvbbnn00 Oct 7, 2026
c90819f
fix(auth): compare redirect origins using default ports
vvbbnn00 Oct 7, 2026
348d829
fix(web): forward button refs for theme menu positioning
vvbbnn00 Oct 7, 2026
be085aa
fix(web): keep destructive confirmation text readable in both themes
vvbbnn00 Oct 7, 2026
5cb3d77
test(config): handle Windows line endings in the example regression
vvbbnn00 Oct 7, 2026
790f882
feat(config): warn on file permission issues unless strict mode is en…
vvbbnn00 Oct 7, 2026
101eece
fix(auth): validate gateway certificates and protocol response codes
vvbbnn00 Oct 7, 2026
81a991e
fix(runtime): validate tunnel endpoints and support custom default tr…
vvbbnn00 Oct 7, 2026
613e8e8
fix(cli): reject overlapping private file paths before startup
vvbbnn00 Oct 7, 2026
1be1bda
fix(web): restore keyboard focus after controlled dialogs close
vvbbnn00 Oct 7, 2026
40a61bc
fix(session): keep rejected caches disabled after failed reauthentica…
vvbbnn00 Oct 7, 2026
1a6e233
fix(cli): retain SMS input received before the prompt starts waiting
vvbbnn00 Oct 7, 2026
77a5636
fix(cli): reject extra login arguments before creating local identity
vvbbnn00 Oct 7, 2026
de63737
fix(cli): detect wildcard proxy conflicts with the web panel
vvbbnn00 Oct 7, 2026
e50e354
fix(proxy): finish HTTP upgrade before relaying UDP datagrams
vvbbnn00 Oct 7, 2026
05ec545
fix(resolver): cancel target lookups when their session expires
vvbbnn00 Oct 7, 2026
d1e33c7
fix(auth): preserve ECNU credential persistence errors
vvbbnn00 Oct 7, 2026
e2f50dd
fix(session): honor caller lifetime for SMS challenges
vvbbnn00 Oct 7, 2026
084aada
fix(session): retain filtered compatibility gateway fallbacks
vvbbnn00 Oct 7, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,19 @@ jobs:
with:
go-version-file: go.mod
cache: true
- uses: actions/setup-node@v6
with:
node-version: 22
cache: npm
cache-dependency-path: web/package-lock.json
- name: Build panel
run: npm --prefix web ci && npm --prefix web run build
- name: Panel regression tests
run: npm --prefix web test
- name: Unit and integration tests
run: go test ./...
- name: Race detector
run: go test -race ./client ./internal/idsauth ./internal/session ./internal/tunnel ./internal/l3
run: go test -race ./client ./internal/runtime ./internal/idsauth ./internal/session ./internal/tunnel ./internal/l3 ./internal/resolver ./internal/webui ./internal/storage
- name: Static analysis
run: go vet ./...
- name: Build packages
Expand Down
36 changes: 15 additions & 21 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
name: Release

on:
pull_request:
push:
tags:
- "v*"
Expand Down Expand Up @@ -34,12 +33,12 @@ jobs:
- name: Set up Node.js
uses: actions/setup-node@v6
with:
node-version: 20
node-version: 22
cache: npm
cache-dependency-path: web/package-lock.json

- name: Check release scripts
run: bash -n scripts/package-release.sh scripts/package-release-uv.sh
run: bash -n scripts/package-release.sh scripts/package-release-uv.sh scripts/release-targets.sh

- name: Build release packages
env:
Expand All @@ -48,11 +47,19 @@ jobs:

- name: Test
run: |
npm --prefix web test
go test ./...
go vet ./...

- name: Verify release checksums
run: cd dist && sha256sum --check SHA256SUMS
- name: Save verified packages
uses: actions/upload-artifact@v4
with:
name: verified-release
path: dist/*
if-no-files-found: error


release:
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
Expand All @@ -63,27 +70,14 @@ jobs:
timeout-minutes: 30

steps:
- name: Check out repository
uses: actions/checkout@v6
- uses: actions/checkout@v6
with:
persist-credentials: false

- name: Set up Go
uses: actions/setup-go@v6
with:
go-version-file: go.mod
cache-dependency-path: go.sum

- name: Set up Node.js
uses: actions/setup-node@v6
- name: Download verified packages
uses: actions/download-artifact@v4
with:
node-version: 20
cache: npm
cache-dependency-path: web/package-lock.json

- name: Build release packages
run: bash scripts/package-release.sh "$GITHUB_REF_NAME" dist

name: verified-release
path: dist
- name: Publish GitHub Release
env:
GH_TOKEN: ${{ github.token }}
Expand Down
62 changes: 23 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,19 @@ geekTrust 是 aTrust VPN 的纯用户态客户端。它不创建虚拟网卡、

- 使用 IDS passkey 免密码登录。
- client 模式在首次短信验证后会尝试绑定授信终端。绑定成功后,会话失效时可静默重登,通常不再要求短信。
- TCP 优先使用网关原生流式通道;不可用或不兼容时自动回退到 L3 隧道。
- TCP 优先使用网关原生流式通道;显式开启兼容选项后,流式命令不支持或提前关闭时可回退到 L3 隧道。
- UDP 和 TCP 回退流量由 gVisor 用户态 IPv4 栈处理。
- 会话自动恢复;有多条网关线路时错峰竞速,直接使用最先完成 TLS 握手的连接。

## 快速开始

从源码构建需要 Go 1.24+:
从源码构建需要 Go 1.26.8+:

```sh
go build -o geektrust ./cmd/geektrust
```

这样构建的二进制可以正常使用,但 Web 面板只显示构建提示页。需要完整面板时,安装 Node 20+ 后执行:
这样构建的二进制可以正常使用,但 Web 面板只显示构建提示页。需要完整面板时,安装 Node 22.22+ 后执行:

```sh
make build
Expand All @@ -48,7 +48,7 @@ brew install uv

1. 用系统安全随机源生成 128 位 `device_id`。
2. keystore 不存在时,通过 `uvx` 在隔离环境中运行 [shanghaitech-ids-passkey](https://github.com/vvbbnn00/shanghaitech-ids-passkey),打开浏览器完成绑定并生成 keystore。不会向全局环境安装任何 Python 包。
3. 写入 `client_type = "client"` 的配置,启用本地 SOCKS5、HTTP 代理和 Web 面板。
3. 写入 `auth.mode = "client"` 的版本 2 配置,启用本地 SOCKS5、HTTP 代理和 Web 面板。

配置文件已存在时,init 会拒绝覆盖。确实需要重建时再加 `--force`。

Expand Down Expand Up @@ -89,56 +89,40 @@ brew install uv

## 配置

推荐用 `geektrust init` 生成配置。生成结果如下(另含一行注释):
`geektrust init` 生成版本 2 配置,保留设备 ID,并使用已有 Passkey。上科大的最小手工配置为:

```toml
keystore = "./ids-passkey.keystore"
device_id = "<init 生成的 32 位大写十六进制值>"
base_url = "https://vpn.shanghaitech.edu.cn"
platform = "Mac"
client_type = "client"
state_file = "./state.enc"
gateways = []
dns = []
log_level = "info"

[inbound.socks5]
enabled = true
listen = "127.0.0.1:1080"

[inbound.http]
enabled = true
listen = "127.0.0.1:8080"
config_version = 2

[web]
enabled = true
listen = "127.0.0.1:8081"
[auth.passkey]
keystore = "./ids-passkey.keystore"
```

手工编写配置可参考 [`config.example.toml`](config.example.toml)。
相对路径以配置文件目录为准。设备身份和加密会话放在平台用户持久目录;上科大必需的网关证书域名由程序提供,证书验证继续开启。普通用户无需填写应用 ID、网关 IP 或协议回退开关。

主要配置项:
配置按 `controller`、`auth`、`proxy`、`web`、`dns`、`storage`、`logging` 分组。监听地址省略时采用默认值,空字符串表示禁用。`controller.compatibility` 选择 `auto`、`shanghaitech`、`ecnu` 或 `generic`;它用于控制器兼容适配。`auth.mode` 支持 `auto`、`client`、`browser`;browser 模式不能绑定授信终端。

- `device_id`:设备的稳定身份。修改后服务器会把它视为新设备,需要重新验证和绑定。
- `client_type`:推荐 `client`。手写配置省略该项时默认为 `browser`。
- `keystore`:passkey 私钥文件。不要泄露,也不要提交到版本库。
- `state_file`:加密的会话状态。密钥保存在同目录的 `<state_file>.key`,两个文件都只允许当前用户读写。
- `gateways`:留空时使用服务端下发的线路。
- `dns`:通常留空,仅在需要覆盖服务端下发的隧道 DNS 时设置。
文件权限检查和设置问题默认输出英文警告。在 `[storage]` 中设置 `strict_permissions = true` 后,这些问题会阻止操作。新文件仍会尝试设置私有权限;文件内容的格式校验始终保留,实际读写失败仍会报错。旧格式使用顶层 `strict_permissions`,迁移时会保留该设置。

SOCKS5 和 HTTP 代理没有身份认证,只应监听 `127.0.0.1`。如果改成 `0.0.0.0`,同一网络中的其他设备也能使用你的 VPN 会话。
旧格式继续可读,不自动重写。检查和迁移命令:

```sh
./geektrust -config config.toml config check
./geektrust -config config.toml config show
./geektrust -config config.toml config migrate
./geektrust -config config.toml config migrate --write
```

### browser 兼容模式
`migrate` 默认只预览,`--write` 保留 `.v1.bak` 备份。旧网关覆盖和新网关筛选含义不同,不能自动转换;复杂的显式兼容设置需要人工选择。设备 ID、凭据、签名计数器和原加密缓存不会被迁移命令删除或重置。

只有在控制器不支持 client 模式时,才把 `client_type` 设为 `browser`。browser 模式不能绑定授信终端,会话彻底失效后可能再次要求短信。
完整设置见 [config.example.toml](config.example.toml)。SOCKS5 和 HTTP 代理没有身份认证,默认监听回环地址;配置为非回环地址后,同一网络中的其他设备也能使用你的 VPN 会话。

## Web 面板

`run` 期间默认启用本地面板,只监听回环地址,没有身份认证:

```toml
[web]
enabled = true
listen = "127.0.0.1:8081"
```

Expand All @@ -154,7 +138,7 @@ listen = "127.0.0.1:8081"

- `listen` 必须是回环地址,且不能使用 80 端口,否则配置加载失败。需要远程访问时用 SSH 转发:`ssh -L 8081:127.0.0.1:8081 user@host`。
- 面板启动失败(如端口被占用或与代理端口冲突)只会记录警告并跳过面板,不影响 VPN 和代理。
- `enabled = false` 时不启动面板,短信只能在终端输入。
- 版本 2 使用 `listen = ""` 禁用面板;旧格式继续读取 `enabled = false`。短信只能在终端输入。

## 常用命令

Expand Down Expand Up @@ -203,7 +187,7 @@ curl -x http://127.0.0.1:8080 https://library.shanghaitech.edu.cn/qbsjk/list.htm

路由规则来自服务端下发的应用表,支持精确域名、域名后缀、精确 IP、CIDR、IP 区间和端口范围;范围越小的规则优先级越高。

域名先用公共 DNS 和系统 DNS 解析。没有可用 IPv4 结果时,再通过 VPN 查询服务端下发的校内 DNS,以解析只在校内可见的域名。`dns` 配置可覆盖这些隧道 DNS。
域名先用公共 DNS 和系统 DNS 解析。没有可用 IPv4 结果时,再通过 VPN 查询服务端下发的校内 DNS,以解析只在校内可见的域名。版本 2 的 `dns.servers` 可覆盖这些隧道 DNS;`dns.strategy = "controller"` 只走控制器 DNS。

DNS 查询先用 UDP,失败或回复被截断时改用 TCP;持续失败的服务器会暂时跳过并改用备用服务器,恢复后自动重新使用。具体超时和冷却规则见 [`docs/TECHNICAL.md`](docs/TECHNICAL.md) §12.5。

Expand Down
68 changes: 68 additions & 0 deletions auth/auth.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
package auth

import (
"context"
"errors"
"net/http"
"time"
)

type IdentityInfo struct {
Issuer string
Subject string
Kind string
}

type IdentityProvider interface {
Info(context.Context) (IdentityInfo, error)
Authenticate(context.Context, *http.Client, IdentityRequest) error
}

type IdentityRequest struct {
AllowInteraction bool
}

type CredentialStore interface {
Load(context.Context) ([]byte, error)
Save(context.Context, []byte) error
}

type Method string

const SMS Method = "sms"

var ErrInteractionRequired = errors.New("authentication interaction required")
var ErrUnsupported = errors.New("unsupported authentication method")
var ErrChallengeClosed = errors.New("authentication challenge closed")
var ErrInvalidCredential = errors.New("invalid credential")
var ErrCredentialStore = errors.New("credential store failure")

type ChallengeFailure struct {
Code int
Message string
}

type ChallengeInfo struct {
ID uint64
Method Method
Deadline time.Time
ServerExpiresAt time.Time
LastFailure *ChallengeFailure
}

type Challenge struct {
Info ChallengeInfo
Resend func(context.Context) (ChallengeInfo, error)
}

type Handler func(context.Context, Challenge) (string, error)

type UnsupportedError struct{ Method string }

func (e *UnsupportedError) Error() string { return ErrUnsupported.Error() }
func (e *UnsupportedError) Unwrap() error { return ErrUnsupported }

type RequiredError struct{ Challenge Challenge }

func (e *RequiredError) Error() string { return ErrInteractionRequired.Error() }
func (e *RequiredError) Unwrap() error { return ErrInteractionRequired }
77 changes: 77 additions & 0 deletions auth/passkey.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
package auth

import (
"context"
"errors"
"github.com/ShanghaitechGeekPie/geektrust/internal/idsauth"
"net/http"
)

type Passkey struct {
store CredentialStore
gate chan struct{}
}

func NewPasskey(s CredentialStore) (*Passkey, error) {
if s == nil {
return nil, ErrCredentialStore
}
return &Passkey{store: s, gate: make(chan struct{}, 1)}, nil
}
func (p *Passkey) Info(ctx context.Context) (IdentityInfo, error) {
b, e := p.store.Load(ctx)
if e != nil {
return IdentityInfo{}, storeError(e)
}
return InspectPasskey(b)
}
func InspectPasskey(b []byte) (IdentityInfo, error) {
k, e := idsauth.ParseKeystore(b, nil)
if e != nil {
return IdentityInfo{}, ErrInvalidCredential
}
return IdentityInfo{Issuer: k.BaseURL(), Subject: k.Username(), Kind: k.Kind()}, nil
}
func (p *Passkey) Authenticate(ctx context.Context, h *http.Client, _ IdentityRequest) error {
select {
case p.gate <- struct{}{}:
defer func() { <-p.gate }()
case <-ctx.Done():
return ctx.Err()
}
if locker, ok := p.store.(interface {
Lock(context.Context) (func(), error)
}); ok {
unlock, e := locker.Lock(ctx)
if e != nil {
return storeError(e)
}
defer unlock()
}
if e := ctx.Err(); e != nil {
return e
}
b, e := p.store.Load(ctx)
if e != nil {
return storeError(e)
}
k, e := idsauth.ParseKeystore(b, func(b []byte) error {
if e := p.store.Save(ctx, b); e != nil {
return storeError(e)
}
return nil
})
if e != nil {
return ErrInvalidCredential
}
return idsauth.NewClient(k, h).Login(ctx)
}
func storeError(e error) error {
if errors.Is(e, context.Canceled) {
return errors.Join(ErrCredentialStore, context.Canceled)
}
if errors.Is(e, context.DeadlineExceeded) {
return errors.Join(ErrCredentialStore, context.DeadlineExceeded)
}
return ErrCredentialStore
}
Loading
Loading