Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
23 changes: 22 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ geekTrust 是 aTrust VPN 的纯用户态客户端。它不创建虚拟网卡、

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

Expand Down Expand Up @@ -128,6 +128,27 @@ listen = "127.0.0.1:8081"

SOCKS5 和 HTTP 代理没有身份认证,只应监听 `127.0.0.1`。如果改成 `0.0.0.0`,同一网络中的其他设备也能使用你的 VPN 会话。

### 部署兼容选项

所有控制器默认采用严格模式,不再根据学校域名启用兼容行为。
在配置文件中添加 `[compatibility]`,只开启目标部署需要的选项:

```toml
[compatibility]
fallback_app_id = ""
fallback_gateways = []
gateway_server_name = ""
missing_gateway_group_fallback = false
tcp_to_l3_fallback = false
```

应用 ID 和网关地址仅用于缺失数据时的兜底;已有资源规则和非空网关组优先。
TCP→L3 回退不覆盖认证拒绝、连接不允许、不可达或取消。
TLS 域名覆盖仍验证证书;选项拼写错误会拒绝加载配置。
修改后重新启动客户端;关闭选项后,缓存会话不会恢复旧的兜底网关。
旧的顶层 `app_id` 已移除,请明确填写 `compatibility.fallback_app_id`。
上海科大的可选值和进程元数据覆盖示例见 [config.example.toml](config.example.toml)。

### browser 兼容模式

只有在控制器不支持 client 模式时,才把 `client_type` 设为 `browser`。browser 模式不能绑定授信终端,会话彻底失效后可能再次要求短信。
Expand Down
43 changes: 43 additions & 0 deletions auth/auth.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
// Package auth defines the authentication boundary shared by embedders and the
// controller. It contains no terminal, storage, or school-specific behavior.
package auth

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

var ErrUnsupported = errors.New("unsupported authentication method")
var ErrRequired = errors.New("authentication input required")

type UnsupportedError struct{ Method string }

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

type Challenge struct {
Method string
ExpiresAt time.Time
}

type RequiredError struct{ Challenge Challenge }

func (e *RequiredError) Error() string { return ErrRequired.Error() }
func (e *RequiredError) Unwrap() error { return ErrRequired }

// Handler waits for user input using ctx. The caller owns how the prompt is
// displayed; the SDK never includes the submitted answer in an event or log.
type Handler func(context.Context, Challenge) (string, error)

type ControllerRequest struct {
URL, DeviceID, Platform, ClientType, LoginDomain string
// CSRFToken comes from the initial controller authConfig response.
CSRFToken string
}

// ControllerLogin replaces the built-in identity-to-CAS authentication chain.
// On success it leaves the authenticated controller cookies in http.Client.Jar.
// The SDK checks onlineInfo and fetches policy before accepting the session.
type ControllerLogin func(context.Context, *http.Client, ControllerRequest) error
16 changes: 12 additions & 4 deletions client/README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# client

`client` 封装认证、会话、资源解析和 TCP/UDP 连接,供项目内复用。
`client` 封装认证、会话、资源解析和 TCP/UDP 连接,供其他 Go 项目直接引用。
它不启动代理监听器,也不创建 TUN 或修改系统路由、DNS。

```go
import "geektrust/client"
import "github.com/ShanghaitechGeekPie/geektrust/client"

c, err := client.New(client.Options{
ControllerURL: controllerURL,
Expand All @@ -25,7 +25,15 @@ defer conn.Close()
- `ClientMode` 默认为 false,即 browser 模式;设为 true 后,首次短信验证成功时会尝试绑定授信终端。
- `BlobStore` 收到的是凭据或会话的明文字节,调用方负责保密、原子写入和持久化。同一 passkey 使用同一认证器串行更新计数器;保存失败不会提交断言。
- 认证遵循调用方的 context,允许等待短信输入;网络连接和解析设有超时。连接建立后,用 `SetDeadline` 控制读写。`Close` 会取消操作并关闭自有连接。
- TCP 优先遵循服务端 L3 偏好,否则先尝试流式 TCP;协议不兼容或连接建立失败时可退回 L3,明确的目标拒绝和取消不会触发回退。
- 上海科大保留旧配置的 `app_id` 兜底和网关/DNS 覆盖;其他控制器默认要求资源策略明确授权。
- TCP 优先遵循服务端 L3 偏好,否则先尝试流式 TCP;仅显式设置 `Compatibility.TCPToL3Fallback` 后,网关明确不支持流式命令或在建立阶段提前关闭时才可退回 L3,明确的目标拒绝和取消不会触发回退。
- 所有控制器均默认严格模式,不按域名推断兼容行为。`Options.Compatibility` 使用公开的 `deployment.Compatibility`,与 TOML `[compatibility]` 字段一一对应;可分别配置应用 ID、缺失网关地址、TLS 域名、缺失网关组和 TCP→L3 回退。网关列表只筛选已分配线路,不覆盖非空的网关组。删除或关闭选项后,新客户端立即采用严格行为,缓存会话不会恢复旧的兜底地址。
- `LoginDomain` 显式选择 CAS 域;默认从控制器发现。`ControllerLogin` 可替换整个控制器登录流程,通过共享 HTTP CookieJar 建立会话,SDK 随后检查在线状态和资源。`ChallengeHandler` 接收带到期时间的短信验证请求;未提供交互处理器返回 `auth.ErrRequired`,未知认证方式返回 `auth.ErrUnsupported`。
- 默认 TLS 验证 CA。`GatewayTrustStore` 是显式启用的私有证书 TOFU 兜底,正常 CA 验证通过时不强制检查已有 pin;调用方负责持久保存 pin。
- UDP 保留数据报边界,payload 上限为 1372 字节。`ExchangePacket` 仅支持未分片 IPv4 ICMP Echo;实际可用性取决于控制器授权和网关支持。IPv6 目标未实现。

`Info.Implemented` 仅表示库已经实现的协议能力;`Resources` 表示控制器下发的授权范围,
`OpenTransport` 返回已建立线路和实际分配的 IPv4 地址。它们均不保证任意目标可达。
`Compatibility.ProcessIdentity` 可以覆盖流式 TCP 和 L3 的进程名、平台和路径,并统一重新计算指纹。
未配置时保留各自已实现的协议元数据;这些值与宿主操作系统无关,不代表平台连接验证结果。

`Options.CheckTarget` 可在解析出真实 IPv4 地址后、打开目标传输前执行调用方的路由限制;同样适用于 ICMP。回调必须支持并发调用,只能进一步限制访问,不能扩大控制器授权范围。库本身不决定系统路由。
81 changes: 55 additions & 26 deletions client/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,22 @@ import (
"log/slog"
"net"
"net/http"
"net/netip"
"net/url"
"strconv"
"strings"
"sync"
"time"
"unicode"

"geektrust/internal/config"
"geektrust/internal/idsauth"
"geektrust/internal/l3"
"geektrust/internal/resolver"
"geektrust/internal/session"
"geektrust/internal/tunnel"
"github.com/ShanghaitechGeekPie/geektrust/auth"
"github.com/ShanghaitechGeekPie/geektrust/deployment"
"github.com/ShanghaitechGeekPie/geektrust/internal/config"
"github.com/ShanghaitechGeekPie/geektrust/internal/idsauth"
"github.com/ShanghaitechGeekPie/geektrust/internal/l3"
"github.com/ShanghaitechGeekPie/geektrust/internal/resolver"
"github.com/ShanghaitechGeekPie/geektrust/internal/session"
"github.com/ShanghaitechGeekPie/geektrust/internal/tunnel"
)

// BlobStore is scoped to a single identity/deployment by the embedding application.
Expand Down Expand Up @@ -105,7 +109,10 @@ func ValidatePasskey(b []byte) error {
}

type Options struct {
AppID string
// CheckTarget may reject a resolved IPv4 destination before transport opens.
// It is called concurrently and cannot grant access outside controller policy.
CheckTarget func(netip.Addr) error
Compatibility deployment.Compatibility
Gateways []string
DNS []string
ControllerURL string
Expand All @@ -114,14 +121,15 @@ type Options struct {
LoginDomain string
ClientMode bool
Authenticator Authenticator
ControllerLogin auth.ControllerLogin
ChallengeHandler auth.Handler
SessionStore BlobStore
Transport http.RoundTripper
DialContext func(context.Context, string, string) (net.Conn, error)
DisableSystemResolver bool
GatewayTLSConfig *tls.Config
GatewayTrustStore GatewayTrustStore
Logger *slog.Logger
PromptSMS func(context.Context) (string, error)
}

type Capabilities struct{ IPv4TCP, IPv4UDP, IPv4ICMP, IPv6Targets, IPv6Gateway bool }
Expand All @@ -132,7 +140,8 @@ type Resource struct {
type Info struct {
Gateways, DNS []string
Resources []Resource
Capabilities Capabilities
// Implemented describes library support, not negotiated or authorized access.
Implemented Capabilities
}
type TransportInfo struct {
Gateway string
Expand All @@ -157,17 +166,18 @@ var ErrDatagramTooLarge = errors.New("UDP datagram exceeds tunnel MTU")
var ErrDenied = errors.New("target is not authorized by controller policy")

type Client struct {
provider *session.Provider
manager *tunnel.Manager
dialer *l3.Dialer
resolver *resolver.Resolver
ctx context.Context
cancel context.CancelFunc
mu sync.Mutex
closed bool
conns map[*ownedConn]struct{}
transport *http.Transport
events chan Event
checkTarget func(netip.Addr) error
provider *session.Provider
manager *tunnel.Manager
dialer *l3.Dialer
resolver *resolver.Resolver
ctx context.Context
cancel context.CancelFunc
mu sync.Mutex
closed bool
conns map[*ownedConn]struct{}
transport *http.Transport
events chan Event
}

func New(opts Options) (*Client, error) {
Expand All @@ -178,22 +188,32 @@ func New(opts Options) (*Client, error) {
if len(opts.DeviceID) != 32 || strings.Trim(opts.DeviceID, "0123456789ABCDEF") != "" {
return nil, errors.New("persistent 32-character uppercase hexadecimal device ID required")
}
if opts.Authenticator == nil {
if opts.Authenticator == nil && opts.ControllerLogin == nil {
return nil, errors.New("authenticator required")
}
if opts.Platform == "" {
opts.Platform = "Mac"
}
if len(opts.Platform) > 64 || strings.IndexFunc(opts.Platform, unicode.IsControl) >= 0 {
return nil, errors.New("platform must be at most 64 bytes without control characters")
}
if opts.Logger == nil {
opts.Logger = slog.New(slog.NewTextHandler(io.Discard, nil))
}
mode := "browser"
if opts.ClientMode {
mode = "client"
}
cfg := &config.Config{BaseURL: strings.TrimRight(opts.ControllerURL, "/"), DeviceID: opts.DeviceID, Platform: opts.Platform, LoginDomain: opts.LoginDomain, ClientType: mode, AppID: opts.AppID, Gateways: append([]string(nil), opts.Gateways...), DNS: append([]string(nil), opts.DNS...)}
p := session.NewProvider(cfg, opts.Logger, opts.PromptSMS)
p.Authenticate = opts.Authenticator.Authenticate
cfg := &config.Config{BaseURL: strings.TrimRight(opts.ControllerURL, "/"), DeviceID: opts.DeviceID, Platform: opts.Platform, LoginDomain: opts.LoginDomain, ClientType: mode, Compatibility: opts.Compatibility.Clone(), Gateways: append([]string(nil), opts.Gateways...), DNS: append([]string(nil), opts.DNS...)}
if err := cfg.Compatibility.Validate(); err != nil {
return nil, err
}
p := session.NewProvider(cfg, opts.Logger, nil)
if opts.Authenticator != nil {
p.Authenticate = opts.Authenticator.Authenticate
}
p.ControllerLogin = opts.ControllerLogin
p.ChallengeHandler = opts.ChallengeHandler
p.Transport = opts.Transport
var ownedTransport *http.Transport
if p.Transport == nil {
Expand All @@ -219,7 +239,7 @@ func New(opts Options) (*Client, error) {
m.GatewayTrustStore = opts.GatewayTrustStore
d := &l3.Dialer{Manager: m, Provider: p, Logger: opts.Logger}
ctx, cancel := context.WithCancel(context.Background())
c := &Client{transport: ownedTransport, provider: p, manager: m, dialer: d, resolver: resolver.NewWithDialerOptions(p, d, opts.DialContext, opts.DisableSystemResolver), ctx: ctx, cancel: cancel, conns: make(map[*ownedConn]struct{}), events: make(chan Event, 16)}
c := &Client{checkTarget: opts.CheckTarget, transport: ownedTransport, provider: p, manager: m, dialer: d, resolver: resolver.NewWithDialerOptions(p, d, opts.DialContext, opts.DisableSystemResolver), ctx: ctx, cancel: cancel, conns: make(map[*ownedConn]struct{}), events: make(chan Event, 16)}
p.AddObserver(clientObserver{c})
go p.CheckLoop(ctx, 5*time.Minute)
return c, nil
Expand Down Expand Up @@ -267,7 +287,7 @@ func (c *Client) Connect(parent context.Context) (Info, error) {
if c.closed {
return Info{}, ErrClosed
}
info := Info{Gateways: append([]string(nil), cred.Gateways...), DNS: append([]string(nil), cred.DNS...), Capabilities: Capabilities{IPv4TCP: true, IPv4UDP: true, IPv6Gateway: true}}
info := Info{Gateways: append([]string(nil), cred.Gateways...), DNS: append([]string(nil), cred.DNS...), Implemented: Capabilities{IPv4TCP: true, IPv4UDP: true, IPv4ICMP: true, IPv6Gateway: true}}
for _, r := range cred.Policy.IPRules {
address := ""
switch {
Expand Down Expand Up @@ -341,6 +361,15 @@ func (c *Client) DialContext(parent context.Context, network, address string) (n
if target.AppID == "" {
return nil, ErrDenied
}
if c.checkTarget != nil {
ip, err := netip.ParseAddr(target.IP)
if err != nil {
return nil, err
}
if err := c.checkTarget(ip.Unmap()); err != nil {
return nil, err
}
}
var conn net.Conn
if protocol == "tcp" {
conn, err = c.dialer.Dial(ctx, target.IP, port, target.AppID, target.Domain)
Expand Down
2 changes: 1 addition & 1 deletion client/client_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import (

"golang.org/x/net/dns/dnsmessage"

"geektrust/internal/idsauth"
"github.com/ShanghaitechGeekPie/geektrust/internal/idsauth"
)

type testGatewayPins struct {
Expand Down
Loading
Loading