Help us shape the future of Go! Take the 2026 Go Developer Survey

auth

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ApiKeyClientIdSetting = setting.Setting[uuid.UUID]{
	Env: "MESHSTACK_API_KEY",
	Short: func(envKey string) string {
		return fmt.Sprintf("The client id of a meshStack API key, which mints tokens together with its secret. Also read from %s.", envKey)
	},
	Long: func(envKey string) string {
		return fmt.Sprintf("The client id of a meshStack API key, which mints tokens together with its secret, also read from `%s`.", envKey)
	},
	Parse: setting.ParseTextUnmarshaler[uuid.UUID],
}
View Source
var ApiKeyClientSecretSetting = setting.Setting[string]{
	Env: "MESHSTACK_API_SECRET",
	Short: func(envKey string) string {
		return fmt.Sprintf("The client secret belonging to the API key. Also read from %s.", envKey)
	},
	Long: func(envKey string) string {
		return fmt.Sprintf("The client secret belonging to the API key, also read from `%s`.", envKey)
	},
	Parse: setting.ParseText[string],
}
View Source
var ApiTokenSetting = setting.Setting[jwt.JWT]{
	Env: "MESHSTACK_API_TOKEN",
	Short: func(envKey string) string {
		return fmt.Sprintf("A meshStack access token to send as it is. Also read from %s.", envKey)
	},
	Long: func(envKey string) string {
		return fmt.Sprintf("A meshStack access token to send as it is, also read from `%s`.\n\n"+
			"The token is minted elsewhere, so nothing renews it and nothing asks for a workspace: it "+
			"already carries the one it was minted for. A building block runner's token is the usual "+
			"one to bring here, to see what a run sees, and such a token may not be allowed to list "+
			"workspaces at all.", envKey)
	},
	Parse: setting.ParseTextUnmarshaler[jwt.JWT],
}

Functions

func BrowserLoginEnded added in v0.4.0

func BrowserLoginEnded(ctx context.Context, p *profile.Profile) bool

BrowserLoginEnded is also true for a browser login that a logout removed. It reads only the stored files of p, and calls no meshStack.

func Login added in v0.2.0

func Login(ctx context.Context, withAuth credential.Name, opts ResolveSessionOptions) (_ Session, _ StoreFunc, unlock func() error, err error)

Login holds the profiles it stores until unlock, so that no other command that stores them, such as meshstack profile, stores over the profile of a login waiting for the browser. Where Login fails, it holds nothing. An unlock before the credential is stored also takes back the tokens that the login cached.

func ResolveWorkspace added in v0.3.0

func ResolveWorkspace(ctx context.Context, opts ResolveSessionOptions) (meshstack.Workspace, error)

ResolveWorkspace resolves the workspace that a session of opts works in, as ResolveSession does, and is NoWorkspace where no setting names one and the profile has no default workspace.

Types

type ApiKeyDetails added in v0.3.0

type ApiKeyDetails struct {
	DisplayName      string    `json:"displayName"`
	OwnedByWorkspace string    `json:"ownedByWorkspace"`
	ExpiresAt        time.Time `json:"expiresAt,omitzero"`
	// ExpiresOn is the expiry date, set only by a meshStack that does not send the expiry time
	// yet. It is not turned into a time: the date of an ephemeral key is the day it expires on,
	// not the last day it works.
	ExpiresOn        string                   `json:"expiresOn,omitzero"`
	Permissions      []string                 `json:"permissions"`
	PermissionGroups client.ApiKeyPermissions `json:"-"`
}

type ApiKeyStatus added in v0.3.0

type ApiKeyStatus struct {
	ClientId uuid.UUID      `json:"clientId"`
	Details  *ApiKeyDetails `json:"details,omitzero"`
}

type Credential added in v0.3.0

type Credential struct {
	credential.Credential

	// Sources must never carry a secret, as a status shows them.
	Sources []string
	// Stored is set for the credential the profile stores, and not for one that settings provide.
	Stored bool
	// contains filtered or unexported fields
}

Credential is the credential of a Session, with where it came from, and its token cache, shared with every other process using the same profile and credential.

func CacheFor added in v0.3.0

func CacheFor(p *profile.Profile, cred credential.Credential) Credential

func (Credential) Load added in v0.3.0

func (c Credential) Load(ctx context.Context) error

func (Credential) Modify added in v0.3.0

func (c Credential) Modify(ctx context.Context, action func() error) error

func (Credential) Read added in v0.3.0

func (c Credential) Read(ctx context.Context, action func() error) error

func (Credential) Write added in v0.3.0

func (c Credential) Write(ctx context.Context) error

Write stores the cache even when it is nil, because the identity alone is what lets a later Modify write back the token it mints.

func (Credential) WriteOver added in v0.3.0

func (c Credential) WriteOver(ctx context.Context) (restore func(context.Context) error, err error)

WriteOver is Write for a login, whose restore puts back the cache file it replaced, or removes the one it created, so that a failed login leaves no token behind. The file it replaced may belong to an earlier login of the profile, which stays stored when the new one fails.

type CredentialStatus added in v0.3.0

type CredentialStatus struct {
	Profile   profile.Name        `json:"profile"`
	Endpoint  xurl.URL            `json:"endpoint"`
	Kind      credential.Name     `json:"credential"`
	Sources   []string            `json:"sources"`
	Workspace meshstack.Workspace `json:"workspace,omitzero"`
	// Token is read from the cached access token without verifying it, and is nil while none is
	// cached.
	Token *TokenStatus `json:"token,omitzero"`

	// OidcLogin is set for a browser login. ApiKey is set for an API key, and for an API token that
	// an API key minted.
	OidcLogin *OidcLoginStatus `json:"oidcLogin,omitzero"`
	ApiKey    *ApiKeyStatus    `json:"apiKey,omitzero"`

	Unused []UnusedCredential `json:"unusedCredentials,omitzero"`
}

CredentialStatus never carries a secret. A part that cannot be read is logged as a warning and left at its zero value.

type OidcLoginStatus added in v0.3.0

type OidcLoginStatus struct {
	Issuer      xurl.URL              `json:"issuer"`
	AccessLevel meshstack.AccessLevel `json:"accessLevel"`
	// SessionEndsAt is an upper bound, as a logout or an administrator can end the session
	// earlier.
	SessionEndsAt time.Time `json:"sessionEndsAt,omitzero"`
}

func (OidcLoginStatus) SessionEnded added in v0.3.0

func (o OidcLoginStatus) SessionEnded() bool

type ResolveSessionOptions

type ResolveSessionOptions struct {
	SettingSources

	// UserAgent is required: it names the front end in every request, and the releases to check
	// against.
	http.UserAgent
}

func (ResolveSessionOptions) HttpClient added in v0.4.0

func (opts ResolveSessionOptions) HttpClient() (http.Client, error)

HttpClient is for a request that the meshStack client does not make, such as the download of the API docs. It carries the user agent of the front end, as the session's client does.

type Session

type Session struct {
	CurrentProfile *profile.Profile

	Credential Credential
	Client     func() (client.Client, error)
	MeshInfo   func() (client.MeshInfo, error)
	// contains filtered or unexported fields
}

func ResolveSession

func ResolveSession(ctx context.Context, opts ResolveSessionOptions) (Session, error)

func StoredSession added in v0.3.0

func StoredSession(ctx context.Context, p *profile.Profile, opts ResolveSessionOptions) (Session, error)

func (Session) GetBearerToken

func (s Session) GetBearerToken(ctx context.Context) (out http.BearerToken, err error)

func (Session) RefreshBearerToken

func (s Session) RefreshBearerToken(ctx context.Context, rejected http.BearerToken) (out http.BearerToken, err error)

func (Session) Scope added in v0.4.0

func (s Session) Scope() string

Scope names the profile, and the workspace where the settings choose it: only a browser login works in that workspace, while an API key works in the one that owns it.

func (Session) Status added in v0.3.0

func (s Session) Status(ctx context.Context) CredentialStatus

Status never renews a browser login, which would rotate its refresh token. Only an API key, or an API token it minted, calls meshStack, to read the key's own details.

type SettingSources

type SettingSources = setting.Sources

type StoreFunc added in v0.2.0

type StoreFunc func(context.Context) error

type TokenStatus added in v0.3.0

type TokenStatus struct {
	ExpiresAt   time.Time             `json:"expiresAt,omitzero"`
	User        string                `json:"user,omitzero"`
	Email       string                `json:"email,omitzero"`
	Workspace   meshstack.Workspace   `json:"workspace,omitzero"`
	ClientId    string                `json:"clientId,omitzero"`
	AccessLevel meshstack.AccessLevel `json:"accessLevel,omitzero"`
}

func (TokenStatus) Expired added in v0.3.0

func (t TokenStatus) Expired() bool

type UnusedCredential added in v0.3.0

type UnusedCredential struct {
	Kind credential.Name `json:"credential"`
	// Selected is set for the credential the profile selects, which a flag or the environment
	// replaces.
	Selected bool `json:"selected,omitzero"`
	// ClientId is set for an API key.
	ClientId string `json:"clientId,omitzero"`
	// Token is the cached token of a browser login or an API token.
	Token *TokenStatus `json:"token,omitzero"`
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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