auth

Documentation

Overview

Package auth provides transport-neutral authentication flows. Package auth 提供与传输层无关的认证流程。

Index

• Variables
• func ValidateStaticPassword(password string) error
• func VerifyCredential(expected, got string) bool
• type AccessTokenValidator
• type IssueOptions
• type LoginAuthenticator
  • func NewStaticPassword(userID, expectedPassword string) (LoginAuthenticator, error)
• type LoginAuthenticatorFunc
  • func (f LoginAuthenticatorFunc) Authenticate(ctx context.Context, username, password string) (userID string, ok bool, err error)
• type RefreshResult
• type Service
  • func New(auth TokenManager, login LoginAuthenticator) (*Service, error)
  • func (s *Service) Login(ctx context.Context, username, password string, opts IssueOptions) (Tokens, bool, error)
  • func (s *Service) Logout(ctx context.Context, refresh string) error
  • func (s *Service) Refresh(ctx context.Context, refresh string) (RefreshResult, bool, error)
  • func (s *Service) RevokeAllSessions(ctx context.Context, userID string) error
  • func (s *Service) RevokeSession(ctx context.Context, userID, sessionID string) (bool, error)
• type TokenManager
• type Tokens

Variables

var (
	// ErrStaticPasswordUserIDEmpty reports an empty user ID for static password auth.
	// ErrStaticPasswordUserIDEmpty 表示固定密码认证使用了空 user ID。
	ErrStaticPasswordUserIDEmpty = errors.New("static password user id is required")
	// ErrPasswordEmpty reports an empty password.
	// ErrPasswordEmpty 表示密码为空。
	ErrPasswordEmpty = errors.New("password is empty")
	// ErrPasswordContainsSpace reports whitespace in a static password.
	// ErrPasswordContainsSpace 表示固定密码中包含空白字符。
	ErrPasswordContainsSpace = errors.New("password must not contain whitespace")
	// ErrPasswordInvalidCharacter reports a character outside visible ASCII.
	// ErrPasswordInvalidCharacter 表示存在可见 ASCII 之外的字符。
	ErrPasswordInvalidCharacter = errors.New("password must contain only ASCII letters, digits, and common symbols")
)

var (
	// ErrServiceMisconfigured reports missing Service dependencies.
	// ErrServiceMisconfigured 表示 Service 缺少依赖。
	ErrServiceMisconfigured = errors.New("auth service is misconfigured")
	// ErrTokenManagerMissing reports a missing token manager.
	// ErrTokenManagerMissing 表示缺少 token manager。
	ErrTokenManagerMissing = errors.New("token manager is required")
	// ErrLoginAuthenticatorMissing reports a missing login authenticator.
	// ErrLoginAuthenticatorMissing 表示缺少登录校验器。
	ErrLoginAuthenticatorMissing = errors.New("login authenticator is required")
	// ErrUserIDEmpty reports a successful login without a user ID.
	// ErrUserIDEmpty 表示登录成功但缺少 user ID。
	ErrUserIDEmpty = errors.New("authenticated user id is required")
)

Functions

func ValidateStaticPassword

func ValidateStaticPassword(password string) error

ValidateStaticPassword validates a static password using visible ASCII only. ValidateStaticPassword 使用仅可见 ASCII 规则校验静态密码。

func VerifyCredential

func VerifyCredential(expected, got string) bool

VerifyCredential compares two credential strings using an exact byte match. VerifyCredential 使用精确字节匹配比较两段凭据。

Types

type AccessTokenValidator

type AccessTokenValidator interface {
	ValidateAccessToken(ctx context.Context, token string) (authjwt.Claims, bool, error)
}

AccessTokenValidator validates access tokens. AccessTokenValidator 校验 access token。

type IssueOptions

type IssueOptions = authjwt.IssueOptions

IssueOptions controls token issuance behavior. IssueOptions 控制 token 签发行为。

type LoginAuthenticator

type LoginAuthenticator interface {
	Authenticate(ctx context.Context, username, password string) (userID string, ok bool, err error)
}

LoginAuthenticator verifies login credentials. Implementations may ignore username. LoginAuthenticator 校验登录凭据。 实现可以忽略 username。

func NewStaticPassword

func NewStaticPassword(userID, expectedPassword string) (LoginAuthenticator, error)

NewStaticPassword builds a LoginAuthenticator backed by one fixed password. NewStaticPassword 构造一个使用固定密码的 LoginAuthenticator。

type LoginAuthenticatorFunc

type LoginAuthenticatorFunc func(ctx context.Context, username, password string) (userID string, ok bool, err error)

LoginAuthenticatorFunc adapts a function to LoginAuthenticator. LoginAuthenticatorFunc 将函数适配为 LoginAuthenticator。

func (LoginAuthenticatorFunc) Authenticate

func (f LoginAuthenticatorFunc) Authenticate(ctx context.Context, username, password string) (userID string, ok bool, err error)

type RefreshResult

type RefreshResult = authjwt.RefreshResult

RefreshResult carries refreshed tokens. RefreshResult 保存刷新后的 token。

type Service

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

Service runs authentication flows without transport code. Service 执行与传输层无关的认证流程。

func New

func New(auth TokenManager, login LoginAuthenticator) (*Service, error)

New returns a Service. Call New(tokenManager, loginAuthenticator). New 返回 Service。 调用 New(tokenManager, loginAuthenticator)。

func (*Service) Login

func (s *Service) Login(ctx context.Context, username, password string, opts IssueOptions) (Tokens, bool, error)

Login verifies credentials and issues tokens. ok reports whether the credentials were accepted. Login 校验凭据并签发 token。 ok 表示凭据是否通过校验。

func (*Service) Logout

func (s *Service) Logout(ctx context.Context, refresh string) error

Logout revokes a refresh token. Logout 吊销 refresh token。

func (*Service) Refresh

func (s *Service) Refresh(ctx context.Context, refresh string) (RefreshResult, bool, error)

Refresh rotates a refresh token. ok reports whether the refresh token was accepted. Refresh 轮换 refresh token。 ok 表示 refresh token 是否通过校验。

func (*Service) RevokeAllSessions

func (s *Service) RevokeAllSessions(ctx context.Context, userID string) error

RevokeAllSessions revokes all sessions for userID. RevokeAllSessions 吊销 userID 的全部 session。

func (*Service) RevokeSession

func (s *Service) RevokeSession(ctx context.Context, userID, sessionID string) (bool, error)

RevokeSession revokes one session. ok reports whether the session belonged to userID. RevokeSession 吊销一个 session。 ok 表示该 session 是否属于 userID。

type TokenManager

type TokenManager interface {
	AccessTokenValidator
	IssueSessionTokens(ctx context.Context, userID string, opts IssueOptions) (access string, accessExp time.Time, refresh string, refreshExp time.Time, err error)
	RotateRefreshTokens(ctx context.Context, oldRefresh string) (RefreshResult, bool, error)
	RevokeRefresh(ctx context.Context, refresh string) error
	RevokeSession(ctx context.Context, userID, sessionID string) (bool, error)
	RevokeAllSessions(ctx context.Context, userID string) error
}

TokenManager provides token and session operations for Service. TokenManager 为 Service 提供 token 与 session 操作。

type Tokens

type Tokens struct {
	Access           string
	AccessExpiresAt  time.Time
	Refresh          string
	RefreshExpiresAt time.Time
}

Tokens contains access and refresh tokens. Tokens 保存 access 与 refresh token。