api

Documentation

Index

• Constants
• func ConnectTunnel(ctx context.Context, tlsConfig *tls.Config, quicConfig *quic.Config, ...) (*net.UDPConn, *http3.Transport, *connectip.Conn, *http.Response, error)
• func DefaultQuicConfig(keepalivePeriod time.Duration, initialPacketSize uint16) *quic.Config
• func EnrollKey(accountData models.AccountData, pubKey []byte, deviceName string) (models.AccountData, *models.APIError, error)
• func GenerateCert(privKey *ecdsa.PrivateKey, pubKey *ecdsa.PublicKey) ([][]byte, error)
• func MaintainTunnel(ctx context.Context, cfg MaintainTunnelConfig)
• func PrepareTlsConfig(privKey *ecdsa.PrivateKey, peerPubKey *ecdsa.PublicKey, cert [][]byte, ...) (*tls.Config, error)
• func Register(model, locale, jwt string, acceptTos bool) (models.AccountData, error)
• func RunHook(path string, extraEnv map[string]string)
• type MaintainTunnelConfig
• type NetBuffer
  • func NewNetBuffer(capacity int) *NetBuffer
  • func (n *NetBuffer) Get() []byte
  • func (n *NetBuffer) Put(buf []byte)
• type NetstackAdapter
  • func (n *NetstackAdapter) ReadPacket(buf []byte) (int, error)
  • func (n *NetstackAdapter) WritePacket(pkt []byte) error
• type TunnelDevice
  • func NewNetstackAdapter(dev tun.Device) TunnelDevice
  • func NewWaterAdapter(iface *water.Interface) TunnelDevice
• type WaterAdapter
  • func (w *WaterAdapter) ReadPacket(buf []byte) (int, error)
  • func (w *WaterAdapter) WritePacket(pkt []byte) error

Constants

const ConnectSNI = internal.ConnectSNI

ConnectSNI is the Cloudflare WARP MASQUE SNI value. Re-exported so callers outside the module can build TLS configs without relying on the internal package.

const ConnectURI = internal.ConnectURI

ConnectURI is the Connect-IP URI template (Cloudflare WARP MASQUE).

Functions

func ConnectTunnel

func ConnectTunnel(ctx context.Context, tlsConfig *tls.Config, quicConfig *quic.Config, connectUri string, endpoint net.Addr, useHTTP2 bool) (*net.UDPConn, *http3.Transport, *connectip.Conn, *http.Response, error)

ConnectTunnel establishes a Connect-IP tunnel with the provided endpoint. When useHTTP2 is false it dials over QUIC/HTTP3; when true it dials over TCP/HTTP2. Requires modified connect-ip-go for now to support Cloudflare's non RFC compliant implementation.

Parameters:

• ctx: context.Context - The connection context.
• tlsConfig: *tls.Config - The TLS configuration for secure communication.
• quicConfig: *quic.Config - The QUIC configuration settings (ignored in HTTP/2 mode).
• connectUri: string - The URI template for the Connect-IP request.
• endpoint: net.Addr - The remote endpoint (*net.UDPAddr for HTTP/3, *net.TCPAddr for HTTP/2).
• useHTTP2: bool - When true, connect over TCP+TLS/HTTP2 instead of QUIC/HTTP3.

Returns:

• *net.UDPConn: The UDP connection used for the QUIC session (nil in HTTP/2 mode).
• *http3.Transport: The HTTP/3 transport (nil in HTTP/2 mode).
• *connectip.Conn: The Connect-IP connection instance.
• *http.Response: The response from the Connect-IP handshake.
• error: An error if the connection setup fails.

func DefaultQuicConfig

func DefaultQuicConfig(keepalivePeriod time.Duration, initialPacketSize uint16) *quic.Config

DefaultQuicConfig mirrors internal.DefaultQuicConfig for embedders.

func EnrollKey

func EnrollKey(accountData models.AccountData, pubKey []byte, deviceName string) (models.AccountData, *models.APIError, error)

EnrollKey updates an existing user account with a new MASQUE public key.

This function sends a PATCH request to update the user's account with a new key.

Parameters:

• accountData: models.AccountData - The account data of the user being updated.
• pubKey: []byte - The new MASQUE public key in binary format.
• deviceName: string - The name of the device to enroll. (optional)

Returns:

• models.AccountData: The updated account data.
• error: An error if the update process fails.

Example:

updatedAccount, apiErr, err := EnrollKey(account, pubKey, "PC")
if err != nil {
    log.Fatalf("Key enrollment failed: %v", err)
}

func GenerateCert

func GenerateCert(privKey *ecdsa.PrivateKey, pubKey *ecdsa.PublicKey) ([][]byte, error)

GenerateCert mirrors internal.GenerateCert for embedders.

func MaintainTunnel

func MaintainTunnel(ctx context.Context, cfg MaintainTunnelConfig)

MaintainTunnel continuously connects to the MASQUE server, then starts two forwarding goroutines: one forwarding from the device to the IP connection (and handling any ICMP reply), and the other forwarding from the IP connection to the device. If an error occurs in either loop, the connection is closed and a reconnect is attempted.

Parameters:

• ctx: context.Context - The context for the connection.
• cfg: MaintainTunnelConfig - Tunnel maintenance runtime configuration.

func PrepareTlsConfig

func PrepareTlsConfig(privKey *ecdsa.PrivateKey, peerPubKey *ecdsa.PublicKey, cert [][]byte, sni string, insecure bool) (*tls.Config, error)

PrepareTlsConfig creates a TLS configuration using the provided certificate and SNI (Server Name Indication). It also verifies the peer's public key against the provided public key.

Parameters:

• privKey: *ecdsa.PrivateKey - The private key to use for TLS authentication.
• peerPubKey: *ecdsa.PublicKey - The endpoint's public key to pin to.
• cert: [][]byte - The certificate chain to use for TLS authentication.
• sni: string - The Server Name Indication (SNI) to use.
• insecure: bool - When true, skip endpoint public key pinning.

Returns:

• *tls.Config: A TLS configuration for secure communication.
• error: An error if TLS setup fails.

func Register

func Register(model, locale, jwt string, acceptTos bool) (models.AccountData, error)

Register creates a new user account by registering a WireGuard public key and generating a random Android-like device identifier. The WireGuard private key isn't stored anywhere, therefore it won't be usable. It's sole purpose is to mimic the Android app's registration process.

This function sends a POST request to the API to register a new user and returns the created account data.

Parameters:

• model: string - The device model string to register. (e.g., "PC")
• locale: string - The user's locale. (e.g., "en-US")
• jwt: string - Team token to register.
• acceptTos: bool - Whether the user accepts the Terms of Service (TOS). If false, the user will be prompted to accept.

Returns:

• models.AccountData: The account data returned from the registration process.
• error: An error if registration fails at any step.

Example:

account, err := Register("PC", "en-US", "", false)
if err != nil {
    log.Fatalf("Registration failed: %v", err)
}

func RunHook

func RunHook(path string, extraEnv map[string]string)

RunHook executes the given path as a subprocess in a fire-and-forget manner.

The path is exec'd directly with no arguments and no shell, so the caller controls exactly what runs. The parent process's environment is inherited, with extraEnv layered on top (later entries win). stdout and stderr are captured and relayed to the standard logger, one line at a time, prefixed with the hook event (taken from extraEnv["USQUE_EVENT"] when present).

If path is empty, RunHook is a no-op. The function returns immediately; the subprocess and its log relays run in background goroutines.

Parameters:

• path: string - Absolute or $PATH-resolvable executable to run.
• extraEnv: map[string]string - Additional environment variables to expose.

Types

type MaintainTunnelConfig

type MaintainTunnelConfig struct {
	TLSConfig         *tls.Config
	KeepalivePeriod   time.Duration
	InitialPacketSize uint16
	Endpoint          net.Addr
	Device            TunnelDevice
	MTU               int
	ReconnectDelay    time.Duration
	AlwaysReconnect   bool
	UseHTTP2          bool
	// OnConnect is a path to an executable run after every successful tunnel
	// connect. It is exec'd directly (no shell, no args) and runs fire-and-forget.
	OnConnect string
	// OnDisconnect is a path to an executable run after every tunnel loss.
	// It is exec'd directly (no shell, no args) and runs fire-and-forget.
	OnDisconnect string
	// HookEnv is a set of USQUE_* environment variables layered on top of the
	// parent process env for OnConnect / OnDisconnect invocations. USQUE_EVENT
	// and USQUE_ENDPOINT are set by MaintainTunnel itself.
	HookEnv map[string]string
}

MaintainTunnelConfig contains runtime settings for tunnel maintenance.

type NetBuffer

type NetBuffer struct {
	// contains filtered or unexported fields
}

NetBuffer is a pool of byte slices with a fixed capacity. Helps to reduce memory allocations and improve performance. It uses a sync.Pool to manage the byte slices. The capacity of the byte slices is set when the pool is created.

func NewNetBuffer

func NewNetBuffer(capacity int) *NetBuffer

NewNetBuffer creates a new NetBuffer with the specified capacity. The capacity must be greater than 0.

func (*NetBuffer) Get

func (n *NetBuffer) Get() []byte

Get returns a byte slice from the pool.

func (*NetBuffer) Put

func (n *NetBuffer) Put(buf []byte)

Put places a byte slice back into the pool. It checks if the capacity of the byte slice matches the pool's capacity. If it doesn't match, the byte slice is not returned to the pool.

type NetstackAdapter

type NetstackAdapter struct {
	// contains filtered or unexported fields
}

NetstackAdapter wraps a tun.Device (e.g. from netstack) to satisfy TunnelDevice.

func (*NetstackAdapter) ReadPacket

func (n *NetstackAdapter) ReadPacket(buf []byte) (int, error)

func (*NetstackAdapter) WritePacket

func (n *NetstackAdapter) WritePacket(pkt []byte) error

type TunnelDevice

type TunnelDevice interface {
	// ReadPacket reads a packet from the device (using the given mtu) and returns its contents.
	ReadPacket(buf []byte) (int, error)
	// WritePacket writes a packet to the device.
	WritePacket(pkt []byte) error
}

TunnelDevice abstracts a TUN device so that we can use the same tunnel-maintenance code regardless of the underlying implementation.

func NewNetstackAdapter

func NewNetstackAdapter(dev tun.Device) TunnelDevice

NewNetstackAdapter creates a new NetstackAdapter.

func NewWaterAdapter

func NewWaterAdapter(iface *water.Interface) TunnelDevice

NewWaterAdapter creates a new WaterAdapter.

type WaterAdapter

type WaterAdapter struct {
	// contains filtered or unexported fields
}

WaterAdapter wraps a *water.Interface so it satisfies TunnelDevice.

func (*WaterAdapter) ReadPacket

func (w *WaterAdapter) ReadPacket(buf []byte) (int, error)

func (*WaterAdapter) WritePacket

func (w *WaterAdapter) WritePacket(pkt []byte) error