userauth

package
v0.5.40-beta Latest Latest
Warning

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

 Go to latest Published: Aug 26, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package userauth implements Kodelet-issued credentials for non-browser users.

Index

Constants

View Source 
const (
	DeviceStartPath        = "/api/auth/v1/device/start"
	DevicePollPath         = "/api/auth/v1/device/poll"
	DeviceVerificationPath = "/auth/device"
	CurrentCredentialPath  = "/api/auth/v1/credentials/current"
	MePath                 = "/api/auth/me"
	BearerTokenPrefix      = "kltu_"
)
View Source 
const (
	StatusPending  = DeviceStatusPending
	StatusApproved = DeviceStatusApproved
	StatusDenied   = DeviceStatusDenied
	StatusExpired  = DeviceStatusExpired
)

Variables

View Source 
var (
	// ErrLoginDenied indicates that the user denied the pending device login.
	ErrLoginDenied = errors.New("user login was denied")
	// ErrLoginExpired indicates that the pending device login expired before approval.
	ErrLoginExpired = errors.New("user login expired")
	// ErrLoginSuperseded indicates that a newer pending login replaced this flow locally.
	ErrLoginSuperseded = errors.New("user login was superseded by a newer local login")
)

Functions

func GenerateBearerToken 

func GenerateBearerToken() (string, error)

GenerateBearerToken creates a Kodelet user bearer from 32 cryptographically random bytes.

func NewBearerToken 

func NewBearerToken() (string, error)

NewBearerToken creates a Kodelet user bearer token.

func RevokeCredential 

func RevokeCredential(ctx context.Context, server, bearer string, client *http.Client) error

RevokeCredential revokes the bearer credential used for the request.

func ValidateBearerToken 

func ValidateBearerToken(token string) error

ValidateBearerToken checks the exact kltu_ plus canonical 32-byte base64url format.

Types

type APIError 

type APIError struct {
	Operation  string
	StatusCode int
	Message    string
}

APIError is a non-successful response returned by a user-auth endpoint.

func (*APIError) Error 

func (e *APIError) Error() string

type Credential 

type Credential struct {
	Version      int               `json:"version"`
	Server       string            `json:"server"`
	CredentialID string            `json:"credentialId"`
	BearerToken  string            `json:"bearerToken"`
	Principal    PrincipalSnapshot `json:"principal"`
	CreatedAt    time.Time         `json:"createdAt"`
	ExpiresAt    time.Time         `json:"expiresAt"`
	UpdatedAt    time.Time         `json:"updatedAt"`
}

Credential is one active Kodelet-issued bearer credential for a control plane.

func Login 

func Login(ctx context.Context, config LoginConfig) (Credential, error)

Login starts or resumes one device flow for the canonical server and polls for approval.

type DevicePollRequest 

type DevicePollRequest struct {
	AuthorizationID string `json:"authorizationId"`
	DeviceCode      string `json:"deviceCode"`
}

DevicePollRequest identifies one pending device authorization.

func (DevicePollRequest) Validate 

func (r DevicePollRequest) Validate() error

Validate checks the private polling identifiers returned by device start.

type DevicePollResponse 

type DevicePollResponse struct {
	Status       DeviceStatus      `json:"status"`
	CredentialID string            `json:"credentialId,omitempty"`
	Principal    PrincipalSnapshot `json:"principal,omitempty"`
	ExpiresAt    time.Time         `json:"expiresAt,omitempty"`
	RetryAfterMS int64             `json:"retryAfterMs,omitempty"`
}

DevicePollResponse reports the authorization state and approved credential metadata.

func (DevicePollResponse) Validate 

func (r DevicePollResponse) Validate() error

Validate checks a device-poll response against the current time.

func (DevicePollResponse) ValidateAt 

func (r DevicePollResponse) ValidateAt(now time.Time) error

ValidateAt checks status-dependent device-poll response fields.

type DeviceStartRequest 

type DeviceStartRequest struct {
	ClientName     string `json:"clientName"`
	ClientOS       string `json:"clientOS"`
	ClientArch     string `json:"clientArch"`
	KodeletVersion string `json:"kodeletVersion"`
}

DeviceStartRequest describes the Kodelet client requesting user authorization.

func (DeviceStartRequest) Validate 

func (r DeviceStartRequest) Validate() error

Validate checks that all device-start metadata is present and canonical.

type DeviceStartResponse 

type DeviceStartResponse struct {
	AuthorizationID         string    `json:"authorizationId"`
	DeviceCode              string    `json:"deviceCode"`
	UserCode                string    `json:"userCode"`
	VerificationURL         string    `json:"verificationUrl"`
	VerificationURLComplete string    `json:"verificationUrlComplete,omitempty"`
	BearerToken             string    `json:"bearerToken"`
	ExpiresAt               time.Time `json:"expiresAt"`
	PollIntervalMS          int64     `json:"pollIntervalMs"`
}

DeviceStartResponse returns the private polling values and bearer issued at flow start.

func (DeviceStartResponse) Validate 

func (r DeviceStartResponse) Validate() error

Validate checks a device-start response against the current time.

func (DeviceStartResponse) ValidateAt 

func (r DeviceStartResponse) ValidateAt(now time.Time) error

ValidateAt checks a device-start response against an explicit current time.

type DeviceStatus 

type DeviceStatus string

DeviceStatus is the current state of a device authorization. 

const (
	DeviceStatusPending  DeviceStatus = "pending"
	DeviceStatusApproved DeviceStatus = "approved"
	DeviceStatusDenied   DeviceStatus = "denied"
	DeviceStatusExpired  DeviceStatus = "expired"
)

func (DeviceStatus) Validate 

func (s DeviceStatus) Validate() error

Validate checks that a device status is one of the protocol-defined values.

type LoginConfig 

type LoginConfig struct {
	Server     string
	Store      *Store
	HTTPClient *http.Client
	// OnPending runs after pending state is securely persisted and before polling.
	OnPending func(LoginInfo)
}

LoginConfig configures one user device-login operation.

type LoginInfo 

type LoginInfo struct {
	Server                  string
	UserCode                string
	VerificationURL         string
	VerificationURLComplete string
	ExpiresAt               time.Time
	PollInterval            time.Duration
	Resumed                 bool
}

LoginInfo contains only display-safe metadata for a pending login.

type PendingLogin 

type PendingLogin struct {
	Version                 int       `json:"version"`
	Server                  string    `json:"server"`
	AuthorizationID         string    `json:"authorizationId"`
	DeviceCode              string    `json:"deviceCode"`
	UserCode                string    `json:"userCode"`
	VerificationURL         string    `json:"verificationUrl"`
	VerificationURLComplete string    `json:"verificationUrlComplete,omitempty"`
	BearerToken             string    `json:"bearerToken"`
	ExpiresAt               time.Time `json:"expiresAt"`
	PollIntervalMS          int64     `json:"pollIntervalMs"`
	CreatedAt               time.Time `json:"createdAt"`
	UpdatedAt               time.Time `json:"updatedAt"`
}

PendingLogin is one uncompleted device login and its start-only secrets.

type PrincipalSnapshot 

type PrincipalSnapshot struct {
	ID      string   `json:"id"`
	Issuer  string   `json:"issuer,omitempty"`
	Subject string   `json:"subject,omitempty"`
	Name    string   `json:"name,omitempty"`
	Email   string   `json:"email,omitempty"`
	Roles   []string `json:"roles"`
}

PrincipalSnapshot is the approved principal captured when a credential is issued.

func ValidateCredential 

func ValidateCredential(ctx context.Context, server, bearer string, client *http.Client) (PrincipalSnapshot, error)

ValidateCredential verifies a bearer and returns its current principal snapshot.

func (PrincipalSnapshot) Validate 

func (p PrincipalSnapshot) Validate() error

Validate checks the stable principal identity and normalized role set.

type Status 

type Status = DeviceStatus

Status is an alias for DeviceStatus.

type Store 

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

Store owns local non-browser user credentials and pending login state.

func NewStore 

func NewStore() (*Store, error)

NewStore opens the default local control-plane user-auth directory.

func NewStoreAt 

func NewStoreAt(root string) (*Store, error)

NewStoreAt opens a local user-auth directory at an explicit path.

func (*Store) DeleteCredential 

func (s *Store) DeleteCredential(server, expectedCredentialID string) (bool, error)

DeleteCredential removes an active credential only when its ID still matches.

func (*Store) DeletePendingLogin 

func (s *Store) DeletePendingLogin(server, expectedAuthorizationID string) (bool, error)

DeletePendingLogin removes pending state only when its authorization ID still matches.

func (*Store) LoadCredential 

func (s *Store) LoadCredential(server string) (Credential, bool, error)

LoadCredential returns the active credential for a canonical server identity.

func (*Store) LoadPendingLogin 

func (s *Store) LoadPendingLogin(server string) (PendingLogin, bool, error)

LoadPendingLogin returns the pending device login for a canonical server identity.

func (*Store) Root 

func (s *Store) Root() string

Root returns the local user-auth state directory.

func (*Store) SaveCredential 

func (s *Store) SaveCredential(credential Credential) error

SaveCredential atomically persists an active credential.

func (*Store) SavePendingLogin 

func (s *Store) SavePendingLogin(login PendingLogin) error

SavePendingLogin atomically persists a pending device login.

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.