auth

package
v0.0.0-...-a9529a6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 3, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

Documentation

Overview

Package auth implements SCKey account authentication and server join helpers.

Package auth 实现 SCKey 账号认证和服务器入服辅助能力。

Index

Constants

View Source
const DefaultEndpoint = "https://api.sckey.net"

DefaultEndpoint is the default SCKey API endpoint used by ClientConfig.

DefaultEndpoint 是 ClientConfig 默认使用的 SCKey API 根地址。

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	// Code is the response code from the API envelope.
	//
	// Code 是 API envelope 中的响应码。
	Code int `json:"code"`

	// Message is the response message from the API envelope.
	//
	// Message 是 API envelope 中的响应消息。
	Message string `json:"msg"`
}

APIError is returned when SCKey responds with a non-zero envelope code.

APIError 表示 SCKey 返回了非零 envelope code。

func (APIError) Error

func (e APIError) Error() string

Error returns the SCKey API error message, falling back to the numeric code when the server did not send a message.

Error 返回 SCKey API 错误消息;服务端未返回消息时回退为数字错误码。

type Authenticator

type Authenticator interface {
	JoinServer(ctx context.Context) (*JoinToken, error)
	VerifyServerJoin(ctx context.Context, joinToken string) error
}

Authenticator joins and verifies SCKey server sessions.

Authenticator 负责加入和验证 SCKey 服务器会话。

type CaptchaRequest

type CaptchaRequest struct {
	// Contact is the phone number or email address that receives the captcha.
	//
	// Contact 是接收验证码的手机号或邮箱。
	Contact string `json:"contact"`
}

CaptchaRequest requests a captcha for a phone number or email address.

CaptchaRequest 请求发送手机号或邮箱验证码。

type Client

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

Client sends SCKey API requests.

Client 发送 SCKey API 请求。

func NewClient

func NewClient(token string) *Client

NewClient creates a client using the default configuration and token.

NewClient 使用默认配置和 token 创建客户端。

func (*Client) BuildURL

func (c *Client) BuildURL(path string) string

BuildURL resolves path against the client's API endpoint.

BuildURL 根据客户端 API 根地址解析 path。

func (*Client) CheckQQStatus

func (c *Client) CheckQQStatus(ctx context.Context, state string) (*QQStatus, error)

CheckQQStatus checks whether QQ OAuth login for state has completed.

CheckQQStatus 检查 state 对应的 QQ OAuth 登录是否已经完成。

func (*Client) CreateRole

func (c *Client) CreateRole(ctx context.Context, roleName string) (*RoleCreateData, error)

CreateRole creates a new role for the current account.

CreateRole 为当前账号创建新角色。

func (*Client) CurrentRole

func (c *Client) CurrentRole(ctx context.Context) (*Role, error)

CurrentRole returns the currently selected role from the API.

CurrentRole 从 API 返回当前选中的角色。

func (*Client) DeleteRole

func (c *Client) DeleteRole(ctx context.Context, roleID string) error

DeleteRole deletes a role by ID.

DeleteRole 按 ID 删除角色。

func (*Client) ExchangeQQCode

func (c *Client) ExchangeQQCode(ctx context.Context, code, state string) (*Token, error)

ExchangeQQCode exchanges an OAuth callback code for a persistent SCKey token.

ExchangeQQCode 使用 OAuth 回调 code 换取持久 SCKey token。

func (*Client) JoinServer

func (c *Client) JoinServer(ctx context.Context, serverID, serverAddress, roleID string) (*JoinToken, error)

JoinServer requests short-lived server join credentials.

JoinServer 请求短期服务器入服凭证。

func (*Client) ListRoles

func (c *Client) ListRoles(ctx context.Context) (*RoleList, error)

ListRoles lists all roles of the current account.

ListRoles 列出当前账号的全部角色。

func (*Client) LoginByCode

func (c *Client) LoginByCode(ctx context.Context, contact, captcha string) (*Token, error)

LoginByCode exchanges contact and captcha for a persistent SCKey token.

LoginByCode 使用 contact 和 captcha 换取持久 SCKey token。

func (*Client) QQRedirectURL

func (c *Client) QQRedirectURL(state string) string

QQRedirectURL builds the browser URL used to start QQ OAuth login.

QQRedirectURL 构造发起 QQ OAuth 登录的浏览器 URL。

func (*Client) RoleDetail

func (c *Client) RoleDetail(ctx context.Context, roleID string) (*Role, error)

RoleDetail returns one role by ID.

RoleDetail 按 ID 返回一个角色。

func (*Client) SelectRole

func (c *Client) SelectRole(ctx context.Context, roleID string) (*RoleSelectData, error)

SelectRole selects a role for the account.

SelectRole 为账号选择角色。

func (*Client) SendCaptcha

func (c *Client) SendCaptcha(ctx context.Context, contact string) error

SendCaptcha sends a login captcha to contact.

SendCaptcha 向 contact 发送登录验证码。

func (*Client) ServerList

func (c *Client) ServerList(ctx context.Context) (*ServerList, error)

ServerList fetches the community server list.

ServerList 获取社区服务器列表。

func (*Client) Token

func (c *Client) Token() string

Token returns the persistent SCKey account token used by authenticated requests.

Token 返回认证请求使用的持久 SCKey 账号 token。

func (*Client) UpdateRole

func (c *Client) UpdateRole(ctx context.Context, roleID, roleName string) error

UpdateRole updates a role name.

UpdateRole 更新角色名称。

func (*Client) UserAgent

func (c *Client) UserAgent() string

UserAgent returns the SCKey API User-Agent string for this client.

UserAgent 返回此客户端访问 SCKey API 时使用的 User-Agent 字符串。

func (*Client) VerifyServerJoin

func (c *Client) VerifyServerJoin(ctx context.Context, serverID, joinToken, ip string) error

VerifyServerJoin verifies a client join token on the server side.

VerifyServerJoin 在服务端校验客户端入服 token。

type ClientConfig

type ClientConfig struct {
	// EndpointURL is the SCKey API base URL. It defaults to https://api.sckey.net.
	//
	// EndpointURL 是 SCKey API 根地址,默认使用 https://api.sckey.net。
	EndpointURL *url.URL

	// HTTPClient is used to send requests. It defaults to http.DefaultClient.
	//
	// HTTPClient 用于发送请求,默认使用 http.DefaultClient。
	HTTPClient *http.Client

	GameName             string
	OSDescription        string
	OSVersion            string
	OSArchitecture       string
	FrameworkDescription string
}

ClientConfig configures SCKey API requests and the client identity fields sent in the User-Agent header.

ClientConfig 配置 SCKey API 请求以及 User-Agent 中携带的客户端身份字段。

func (ClientConfig) NewClient

func (cfg ClientConfig) NewClient(token string) *Client

NewClient creates an SCKey API client from this config and fills unset fields with Survivalcraft-compatible defaults.

NewClient 基于当前配置创建 SCKey API 客户端,并为未设置字段填充与 Survivalcraft 兼容的默认值。

type CodeLoginRequest

type CodeLoginRequest struct {
	// Contact is the phone number or email address used for login.
	//
	// Contact 是用于登录的手机号或邮箱。
	Contact string `json:"contact"`

	// Captcha is the verification code sent to Contact.
	//
	// Captcha 是发送到 Contact 的验证码。
	Captcha string `json:"captcha"`
}

CodeLoginRequest exchanges a contact and captcha for a persistent SCKey token.

CodeLoginRequest 使用联系方式和验证码换取持久 SCKey token。

type DefaultAuthenticator

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

DefaultAuthenticator adapts a request Client and selected server data to Authenticator.

DefaultAuthenticator 将请求 Client 和已选择服务器数据适配为 Authenticator。

func NewDefaultAuthenticator

func NewDefaultAuthenticator(client *Client, serverID, serverIP, roleID string) *DefaultAuthenticator

NewDefaultAuthenticator creates the default SCKey server authenticator.

NewDefaultAuthenticator 创建默认 SCKey 服务器认证器。

func (*DefaultAuthenticator) JoinServer

func (a *DefaultAuthenticator) JoinServer(ctx context.Context) (*JoinToken, error)

JoinServer requests short-lived server join credentials.

JoinServer 请求短期服务器入服凭证。

func (*DefaultAuthenticator) VerifyServerJoin

func (a *DefaultAuthenticator) VerifyServerJoin(ctx context.Context, joinToken string) error

VerifyServerJoin verifies a client join token on the server side.

VerifyServerJoin 在服务端校验客户端入服 token。

type EmptyRequest

type EmptyRequest struct{}

EmptyRequest is used for SCKey endpoints that require an empty JSON object.

EmptyRequest 用于需要空 JSON 对象的 SCKey 接口。

type JoinServerRequest

type JoinServerRequest struct {
	// ServerID is the bound SCKey server ID.
	//
	// ServerID 是绑定的 SCKey 服务器 ID。
	ServerID string `json:"sid,omitempty"`

	// Address is the server address reported to the SCKey API.
	//
	// Address 是上报给 SCKey API 的服务器地址。
	Address string `json:"address"`

	// RoleID is the selected role ID.
	//
	// RoleID 是选中的角色 ID。
	RoleID string `json:"roleId,omitempty"`
}

JoinServerRequest requests short-lived credentials for joining an SCKey server.

JoinServerRequest 请求加入 SCKey 服务器所需的短期凭证。

type JoinServerResponse

type JoinServerResponse struct {
	// GUID is the SCKey player GUID returned for this join attempt.
	//
	// GUID 是本次入服返回的 SCKey 玩家 GUID。
	GUID string `json:"guid"`

	// Token is the short-lived join token verified by the server.
	//
	// Token 是由服务器校验的短期入服 token。
	Token string `json:"token"`

	// ExpiresTime is the expiration time returned by the SCKey API.
	//
	// ExpiresTime 是 SCKey API 返回的过期时间。
	ExpiresTime int `json:"expireTime"`

	// RoleName is the selected role name.
	//
	// RoleName 是选中的角色名称。
	RoleName string `json:"roleName"`
}

JoinServerResponse is the SCKey response for a server join request.

JoinServerResponse 是 SCKey 服务器入服请求的响应数据。

type JoinToken

type JoinToken struct {
	// GUID is the SCKey player GUID returned for this join attempt.
	//
	// GUID 是本次入服返回的 SCKey 玩家 GUID。
	GUID uuid.UUID

	// Token is the short-lived join token verified by the server.
	//
	// Token 是由服务器校验的短期入服 token。
	Token string

	// ExpiresTime is the API-provided expiration time.
	//
	// ExpiresTime 是 API 返回的过期时间。
	ExpiresTime int

	// RoleName is the selected role name.
	//
	// RoleName 是选中的角色名称。
	RoleName string
}

JoinToken contains the short-lived credentials sent in ConnectionRequest.

JoinToken 包含 ConnectionRequest 中发送的短期入服凭证。

type QQCodeRequest

type QQCodeRequest struct {
	// Code is the OAuth callback authorization code.
	//
	// Code 是 OAuth 回调授权码。
	Code string `json:"code"`

	// State is the login state generated before opening the QQ authorization URL.
	//
	// State 是打开 QQ 授权地址前生成的登录状态。
	State string `json:"state"`
}

QQCodeRequest exchanges a QQ OAuth callback code for a persistent SCKey token.

QQCodeRequest 使用 QQ OAuth 回调 code 换取持久 SCKey token。

type QQStatus

type QQStatus struct {
	// Completed reports whether QQ login has completed.
	//
	// Completed 表示 QQ 登录是否已经完成。
	Completed bool

	// Token is set when Completed is true.
	//
	// Token 在 Completed 为 true 时设置。
	Token *Token

	// Message is the API status message.
	//
	// Message 是 API 状态消息。
	Message string
}

QQStatus is the result of a QQ login status check.

QQStatus 是 QQ 登录状态检查结果。

type QQStatusRequest

type QQStatusRequest struct {
	// State is the login state generated before opening the QQ authorization URL.
	//
	// State 是打开 QQ 授权地址前生成的登录状态。
	State string `json:"state"`
}

QQStatusRequest checks whether QQ OAuth login for a state has completed.

QQStatusRequest 检查某个 state 对应的 QQ OAuth 登录是否完成。

type Role

type Role struct {
	// ID is the role identifier.
	//
	// ID 是角色标识符。
	ID string `json:"id"`

	// UID is the numeric account identifier.
	//
	// UID 是数字账号标识。
	UID int `json:"uid"`

	// RoleName is the display name of the role.
	//
	// RoleName 是角色显示名称。
	RoleName string `json:"roleName"`

	// CreatedAt is the role creation time.
	//
	// CreatedAt 是角色创建时间。
	CreatedAt string `json:"createdAt"`

	// UpdatedAt is the role update time.
	//
	// UpdatedAt 是角色更新时间。
	UpdatedAt string `json:"updatedAt"`

	// IsDeleted reports whether the role is deleted.
	//
	// IsDeleted 表示角色是否已删除。
	IsDeleted int `json:"isDeleted"`
}

Role is one SCKey account role.

Role 是一个 SCKey 账号角色。

type RoleCreateData

type RoleCreateData struct {
	// RoleID is the created role ID.
	//
	// RoleID 是创建出的角色 ID。
	RoleID string `json:"roleId"`

	// RoleName is the created role name.
	//
	// RoleName 是创建出的角色名称。
	RoleName string `json:"roleName"`
}

RoleCreateData is the response returned by role creation.

RoleCreateData 是角色创建接口返回的数据。

type RoleCreateRequest

type RoleCreateRequest struct {
	// RoleName is the new role name.
	//
	// RoleName 是新角色名称。
	RoleName string `json:"roleName"`
}

RoleCreateRequest creates a role with RoleName.

RoleCreateRequest 创建名为 RoleName 的角色。

type RoleIDRequest

type RoleIDRequest struct {
	// RoleID is the role identifier.
	//
	// RoleID 是角色标识符。
	RoleID string `json:"roleId"`
}

RoleIDRequest identifies a role by ID.

RoleIDRequest 通过 ID 标识一个角色。

type RoleList

type RoleList struct {
	// Total is the number of roles returned by the API.
	//
	// Total 是 API 返回的角色数量。
	Total int `json:"total"`

	// Roles contains the account roles.
	//
	// Roles 包含账号角色。
	Roles []Role `json:"roles"`
}

RoleList is the response returned by the role list endpoint.

RoleList 是角色列表接口返回的数据。

func (*RoleList) LookupName

func (l *RoleList) LookupName(name string) *Role

LookupName returns the first role with name.

LookupName 返回第一个名称为 name 的角色。

func (*RoleList) LookupNameFold

func (l *RoleList) LookupNameFold(name string) *Role

LookupNameFold returns the first role with name using case-insensitive matching.

LookupNameFold 使用大小写无关匹配返回第一个名称为 name 的角色。

type RoleSelectData

type RoleSelectData struct {
	// RoleID is the selected role ID.
	//
	// RoleID 是选中的角色 ID。
	RoleID string `json:"roleId"`

	// RoleName is the selected role name.
	//
	// RoleName 是选中的角色名称。
	RoleName string `json:"roleName"`
}

RoleSelectData is the response returned by role selection.

RoleSelectData 是选择角色接口返回的数据。

type RoleUpdateRequest

type RoleUpdateRequest struct {
	// RoleID is the role identifier.
	//
	// RoleID 是角色标识符。
	RoleID string `json:"roleId"`

	// RoleName is the new role name.
	//
	// RoleName 是新的角色名称。
	RoleName string `json:"roleName"`
}

RoleUpdateRequest updates a role name.

RoleUpdateRequest 更新角色名称。

type ServerList

type ServerList struct {
	// List contains the community servers.
	//
	// List 包含社区服务器。
	List []ServerListEntry `json:"list"`
}

ServerList is the response returned by the community server list endpoint.

ServerList 是社区服务器列表接口返回的数据。

func (*ServerList) LookupID

func (l *ServerList) LookupID(id string) *ServerListEntry

LookupID returns the first entry with id.

LookupID 返回第一个 ID 为 id 的条目。

func (*ServerList) LookupIP

func (l *ServerList) LookupIP(ip string) *ServerListEntry

LookupIP returns the first entry with ip.

LookupIP 返回第一个 IP 为 ip 的条目。

func (*ServerList) LookupName

func (l *ServerList) LookupName(name string) *ServerListEntry

LookupName returns the first entry with name.

LookupName 返回第一个名称为 name 的条目。

func (*ServerList) LookupNameFold

func (l *ServerList) LookupNameFold(name string) *ServerListEntry

LookupNameFold returns the first entry with name using case-insensitive matching.

LookupNameFold 使用大小写无关匹配返回第一个名称为 name 的条目。

type ServerListEntry

type ServerListEntry struct {
	// ID is the server identifier.
	//
	// ID 是服务器标识符。
	ID string `json:"id"`

	// Name is the display name shown in the server list.
	//
	// Name 是服务器列表展示名称。
	Name string `json:"name"`

	// IP is the server address.
	//
	// IP 是服务器地址。
	IP string `json:"ip"`

	// Version is the supported game version.
	//
	// Version 是支持的游戏版本。
	Version string `json:"version"`

	// Level controls which list section the server belongs to.
	//
	// Level 控制服务器所属的列表分区。
	Level int `json:"level"`

	// NeedLogin reports whether SCKey login is required.
	//
	// NeedLogin 表示是否需要 SCKey 登录。
	NeedLogin bool `json:"needLogin"`

	// GroupJoinMode controls how children are selected when joining a group server.
	//
	// GroupJoinMode 控制加入群组服务器时如何选择子服务器。
	GroupJoinMode int `json:"groupJoinMode"`

	// JoinWeight is the weighted join value used for group child selection.
	//
	// JoinWeight 是群组子服务器选择时使用的权重。
	JoinWeight int `json:"join_weight"`

	// Children contains child servers for a group server.
	//
	// Children 包含群组服务器的子服务器。
	Children []ServerListEntry `json:"children"`
}

ServerListEntry is one server entry in the community server list.

ServerListEntry 是社区服务器列表中的一个服务器条目。

type Token

type Token struct {
	// AccessToken is the bearer token used when requesting server join tokens.
	//
	// AccessToken 是申请服务器入服 token 时使用的 bearer token。
	AccessToken string `json:"token"`
}

Token contains the persistent SCKey account token returned by account login.

Token 包含账号登录返回的持久 SCKey 账号 token。

func (*Token) Valid

func (t *Token) Valid() bool

Valid reports whether the token can be used for authenticated SCKey API calls.

Valid 表示 token 是否可用于带认证的 SCKey API 调用。

type VerifyServerJoinRequest

type VerifyServerJoinRequest struct {
	// ServerID is the bound SCKey server ID.
	//
	// ServerID 是绑定的 SCKey 服务器 ID。
	ServerID string `json:"serverId"`

	// JoinToken is the short-lived token received from the client.
	//
	// JoinToken 是客户端发送的短期入服 token。
	JoinToken string `json:"joinToken"`

	// IP is the remote client IP address.
	//
	// IP 是远端客户端 IP 地址。
	IP string `json:"ip"`
}

VerifyServerJoinRequest verifies a short-lived SCKey join token.

VerifyServerJoinRequest 校验短期 SCKey 入服 token。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址