auth

package
v1.0.97 Latest Latest
Warning

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

 Go to latest Published: Sep 28, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// PathDeviceAuthorization is the endpoint for device authorization.
	PathDeviceAuthorization = "/oauth/v1/device_authorization"
	// PathOAuthRevoke is the endpoint for revoking an OAuth token.
	PathOAuthRevoke = "/oauth/v1/revoke"
	// PathAppRegistration is the endpoint for application registration.
	PathAppRegistration = "/oauth/v1/app/registration"
	// PathOAuthTokenV2 is the endpoint for requesting an OAuth token (v2).
	PathOAuthTokenV2 = "/open-apis/authen/v2/oauth/token"
	// PathUserInfoV1 is the endpoint for fetching user information.
	PathUserInfoV1 = "/open-apis/authen/v1/user_info"
	// PathApplicationInfoV6Prefix is the prefix endpoint for fetching application info.
	PathApplicationInfoV6Prefix = "/open-apis/application/v6/applications/"
)

Common authentication paths used for logging and API calls.

Variables

View Source 
var (
	ErrRegistrationDenied   = errors.New("app registration denied by user")
	ErrRegistrationExpired  = errors.New("device code expired, please try again")
	ErrRegistrationTimedOut = errors.New("app registration timed out, please try again")
)

Terminal registration outcomes, exposed for typed classification by callers.

View Source 
var TokenRetryCodes = map[int]bool{
	output.LarkErrTokenInvalid: true,
	output.LarkErrTokenExpired: true,
}

TokenRetryCodes contains error codes that allow retry after token refresh.

Functions

func ApplicationInfoPath added in v1.0.4 

func ApplicationInfoPath(appId string) string

ApplicationInfoPath returns the full API path for querying an application's information.

func BuildVerificationURL 

func BuildVerificationURL(baseURL, cliVersion string) string

BuildVerificationURL appends CLI tracking parameters to the verification URL.

func FetchRemoteScopes added in v1.0.94 

func FetchRemoteScopes(brand core.LarkBrand) (map[string][]string, bool)

FetchRemoteScopes fetches and binary-validates the remote scopes.json. It returns (domain -> user_scopes, true) when the whole file is usable, or (nil, false) when the caller should fall back to the local set. Any failure (network / timeout / non-2xx / empty / bad JSON / structure mismatch / malformed scope) returns (nil, false) silently — no warning, no telemetry.

func GetValidAccessToken 

func GetValidAccessToken(httpClient *http.Client, opts UATCallOptions) (string, error)

GetValidAccessToken obtains a valid access token for the given user.

func IsNeedUserAuthorizationError added in v1.0.26 

func IsNeedUserAuthorizationError(err error) bool

IsNeedUserAuthorizationError reports whether err represents a missing-UAT failure. It matches the legacy *NeedAuthorizationError sentinel, which is preserved in the Cause chain of the typed missing-UAT error, so errors.As traverses into the typed *errs.AuthenticationError as well.

func MaskToken 

func MaskToken(token string) string

MaskToken masks a token for safe logging.

func MissingScopes 

func MissingScopes(storedScope string, required []string) []string

MissingScopes returns the elements of required that are absent from storedScope. storedScope is a space-separated list of granted scope strings (as stored in the token).

func NewNeedUserAuthorizationError added in v1.0.56 

func NewNeedUserAuthorizationError(userOpenID string) error

NewNeedUserAuthorizationError builds the typed *errs.AuthenticationError returned when no valid UAT exists for userOpenID. The Message keeps the need_user_authorization marker, the Hint converges on the same auth-login recovery vocabulary as the token-missing surface in internal/client, and the legacy *NeedAuthorizationError sentinel is preserved in the Cause chain for errors.As / errors.Is traversal.

func RemoveStoredToken 

func RemoveStoredToken(appId, userOpenId string) error

RemoveStoredToken removes a stored UAT.

func RevokeToken added in v1.0.53 

func RevokeToken(httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, token, tokenTypeHint string) error

RevokeToken revokes a previously issued OAuth token.

func SetStoredToken 

func SetStoredToken(token *StoredUAToken) error

SetStoredToken persists a UAT.

func TokenStatus 

func TokenStatus(token *StoredUAToken) string

TokenStatus determines the freshness of a stored token.

func VerifyUserToken 

func VerifyUserToken(ctx context.Context, sdk *lark.Client, accessToken string) error

VerifyUserToken calls /authen/v1/user_info to confirm the token is accepted server-side. Returns nil on success or an error describing why the server rejected the token.

Types

type AppRegUserInfo 

type AppRegUserInfo struct {
	OpenID      string
	TenantBrand string // "feishu" or "lark"
}

AppRegUserInfo contains user info returned from app registration.

type AppRegistrationResponse 

type AppRegistrationResponse struct {
	DeviceCode              string
	UserCode                string
	VerificationUri         string
	VerificationUriComplete string
	ExpiresIn               int
	Interval                int
}

AppRegistrationResponse is the response from the app registration begin endpoint.

func RequestAppRegistration 

func RequestAppRegistration(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, errOut io.Writer) (*AppRegistrationResponse, error)

RequestAppRegistration initiates the device flow. The registration protocol always bootstraps on Feishu; brand selects the user-facing verification host. The request is bounded by ctx and a begin timeout.

type AppRegistrationResult 

type AppRegistrationResult struct {
	ClientID     string
	ClientSecret string
	UserInfo     *AppRegUserInfo
}

AppRegistrationResult is the result of a successful app registration poll.

func RegisterAppWithDiscovery added in v1.0.69 

func RegisterAppWithDiscovery(ctx context.Context, httpClient *http.Client, resp *AppRegistrationResponse, errOut io.Writer) (*AppRegistrationResult, core.LarkBrand, error)

RegisterAppWithDiscovery polls for credentials, mirroring the official SDK flow: the first poll and the (at most one) cross-brand switch are immediate, non-error responses without complete credentials keep polling, and one deadline from the begin expiry bounds all waits and in-flight requests. The returned brand is the one the credentials were issued on.

type DeviceAuthResponse 

type DeviceAuthResponse struct {
	DeviceCode              string `json:"device_code"`
	UserCode                string `json:"user_code"`
	VerificationUri         string `json:"verification_uri"`
	VerificationUriComplete string `json:"verification_uri_complete"`
	ExpiresIn               int    `json:"expires_in"`
	Interval                int    `json:"interval"`
}

DeviceAuthResponse is the response from the device authorization endpoint.

func RequestDeviceAuthorization 

func RequestDeviceAuthorization(httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, scope string, errOut io.Writer) (*DeviceAuthResponse, error)

RequestDeviceAuthorization requests a device authorization code.

type DeviceFlowResult 

type DeviceFlowResult struct {
	OK      bool
	Token   *DeviceFlowTokenData
	Error   string
	Message string
}

DeviceFlowResult is the result of polling the token endpoint.

func PollDeviceToken 

func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) (*DeviceFlowResult, error)

PollDeviceToken polls the token endpoint until authorization completes or times out. Typed policy errors are returned unchanged so callers can surface their recovery fields instead of treating them as transient network failures.

type DeviceFlowTokenData 

type DeviceFlowTokenData struct {
	AccessToken      string
	RefreshToken     string
	ExpiresIn        int
	RefreshExpiresIn int
	Scope            string
	StatusMessage    string
}

DeviceFlowTokenData contains the token data from a successful device flow.

type NeedAuthorizationError 

type NeedAuthorizationError struct {
	UserOpenId string
}

NeedAuthorizationError is the sentinel preserved in the Cause chain of the typed missing-UAT error so existing errors.As(&NeedAuthorizationError{}) consumers keep matching after the construction site moved to the typed taxonomy. It is never surfaced on the wire on its own.

func (*NeedAuthorizationError) Error 

func (e *NeedAuthorizationError) Error() string

Error returns the error message for NeedAuthorizationError.

type OAuthEndpoints 

type OAuthEndpoints struct {
	DeviceAuthorization string
	Revoke              string
	Token               string
}

OAuthEndpoints contains the OAuth endpoint URLs.

func ResolveOAuthEndpoints 

func ResolveOAuthEndpoints(brand core.LarkBrand) OAuthEndpoints

ResolveOAuthEndpoints resolves OAuth endpoint URLs based on brand.

type SecurityPolicyError 

type SecurityPolicyError = errs.SecurityPolicyError

SecurityPolicyError is preserved as a Go type alias so existing errors.As(&SecurityPolicyError{}) consumers (cmd/root.go etc.) keep working. The concrete struct lives in errs/types.go.

type SecurityPolicyTransport 

type SecurityPolicyTransport struct {
	Base http.RoundTripper
}

SecurityPolicyTransport is an http.RoundTripper that intercepts all responses and checks for security policy errors.

func (*SecurityPolicyTransport) BaseRoundTripper added in v1.0.82 

func (t *SecurityPolicyTransport) BaseRoundTripper() http.RoundTripper

func (*SecurityPolicyTransport) RoundTrip 

func (t *SecurityPolicyTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper.

func (*SecurityPolicyTransport) WithBaseRoundTripper added in v1.0.82 

func (t *SecurityPolicyTransport) WithBaseRoundTripper(base http.RoundTripper) http.RoundTripper

type StoredUAToken 

type StoredUAToken struct {
	UserOpenId       string `json:"userOpenId"`
	AppId            string `json:"appId"`
	AccessToken      string `json:"accessToken"`
	RefreshToken     string `json:"refreshToken"`
	ExpiresAt        int64  `json:"expiresAt"`        // Unix ms
	RefreshExpiresAt int64  `json:"refreshExpiresAt"` // Unix ms
	Scope            string `json:"scope"`
	GrantedAt        int64  `json:"grantedAt"` // Unix ms
}

StoredUAToken represents a stored user access token.

func GetStoredToken 

func GetStoredToken(appId, userOpenId string) (*StoredUAToken, error)

GetStoredToken reads the stored UAT and preserves storage and decode errors.

type UATCallOptions 

type UATCallOptions struct {
	UserOpenId string
	AppId      string
	AppSecret  string
	Domain     core.LarkBrand
	ErrOut     io.Writer // diagnostic/status output (caller injects f.IOStreams.ErrOut)
}

UATCallOptions contains options for UAT API calls.

func NewUATCallOptions 

func NewUATCallOptions(cfg *core.CliConfig, errOut io.Writer) UATCallOptions

NewUATCallOptions creates UATCallOptions from a CLI config.

type UATStatus 

type UATStatus struct {
	Authorized       bool   `json:"authorized"`
	UserOpenId       string `json:"userOpenId"`
	Scope            string `json:"scope,omitempty"`
	ExpiresAt        int64  `json:"expiresAt,omitempty"`
	RefreshExpiresAt int64  `json:"refreshExpiresAt,omitempty"`
	GrantedAt        int64  `json:"grantedAt,omitempty"`
	TokenStatus      string `json:"tokenStatus,omitempty"`
}

UATStatus represents the status of a user access token.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.