auth

Documentation

Overview

Package auth — HTTP client for nSelf auth server operations.

Package auth — device code polling loop for the CLI login flow.

Package auth provides CLI authentication storage and client utilities. ~/.nself/auth.json is the credential store with 0600 permissions.

Index

• Variables
• func ActivateLicense(accessToken, licenseID string) error
• func AuthServerURL() string
• func CLIAuthBaseURL() string
• func DeleteAuthFile() error
• func GetAuthFilePath() string
• func InviteTeamMember(accessToken, email string) error
• func IsLoggedIn() bool
• func RemoveTeamMember(accessToken, email string) error
• func RevokeDevice(accessToken, deviceID string) error
• func RevokeSession(accessToken string, all bool) error
• func SetTeamMemberRole(accessToken, email, role string) error
• func TransferLicense(accessToken, licenseID, toEmail string) error
• func WriteAuthFile(af *AuthFile) error
• type AccountInfo
  • func GetSession(accessToken string) (*AccountInfo, error)
• type AuthAPIError
  • func (e *AuthAPIError) Error() string
• type AuthFile
  • func ReadAuthFile() (*AuthFile, error)
• type DeviceCodeResponse
  • func DeviceAuthorize() (*DeviceCodeResponse, error)
• type DeviceEntry
  • func GetDevices(accessToken string) ([]DeviceEntry, error)
• type LicenseInfo
  • func GetLicenses(accessToken string) ([]LicenseInfo, error)
• type PollResult
  • func PollDeviceCode(ctx context.Context, deviceCode string, onPoll func(elapsed time.Duration)) (*PollResult, error)
• type TeamMember
  • func GetTeamMembers(accessToken string) ([]TeamMember, error)
• type TokenResponse
  • func PollToken(deviceCode string) (*TokenResponse, error)
  • func RefreshToken(accessToken string) (*TokenResponse, error)

Variables

var ErrNotLoggedIn = errors.New("not logged in — run 'nself login' to authenticate")

ErrNotLoggedIn is returned when no auth.json exists or token is missing.

var ErrPollTimeout = fmt.Errorf("authorization timed out — the login URL has expired. Run 'nself login' to try again")

ErrPollTimeout is returned when the device code polling window expires.

Functions

func ActivateLicense

func ActivateLicense(accessToken, licenseID string) error

ActivateLicense activates a license key on the current device.

func AuthServerURL

func AuthServerURL() string

AuthServerURL is the base URL of the auth server. Overridable via NSELF_AUTH_SERVER_URL for testing.

func CLIAuthBaseURL

func CLIAuthBaseURL() string

CLIAuthBaseURL is the web UI for the CLI device auth page.

func DeleteAuthFile

func DeleteAuthFile() error

DeleteAuthFile removes ~/.nself/auth.json if it exists. Returns nil if the file does not exist (idempotent).

func GetAuthFilePath

func GetAuthFilePath() string

GetAuthFilePath returns the path for use in help text (never reads content).

func InviteTeamMember

func InviteTeamMember(accessToken, email string) error

InviteTeamMember sends a team invitation to the given email.

func IsLoggedIn

func IsLoggedIn() bool

IsLoggedIn returns true if ~/.nself/auth.json exists and has a token.

func RemoveTeamMember

func RemoveTeamMember(accessToken, email string) error

RemoveTeamMember removes a member from the account's team.

func RevokeDevice

func RevokeDevice(accessToken, deviceID string) error

RevokeDevice revokes a specific device session.

func RevokeSession

func RevokeSession(accessToken string, all bool) error

RevokeSession calls POST /auth/signout to revoke the session server-side.

func SetTeamMemberRole

func SetTeamMemberRole(accessToken, email, role string) error

SetTeamMemberRole updates a member's role on the account's team.

func TransferLicense

func TransferLicense(accessToken, licenseID, toEmail string) error

TransferLicense transfers a license from the current account to another email.

func WriteAuthFile

func WriteAuthFile(af *AuthFile) error

WriteAuthFile writes auth credentials to ~/.nself/auth.json with 0600 perms. Creates ~/.nself/ directory with 0700 if it does not exist.

Types

type AccountInfo

type AccountInfo struct {
	Authenticated bool `json:"authenticated"`
	Account       struct {
		ID            string `json:"id"`
		Email         string `json:"email"`
		DisplayName   string `json:"display_name"`
		AvatarURL     string `json:"avatar_url"`
		Tier          string `json:"tier"`
		EmailVerified bool   `json:"email_verified"`
		MFAEnabled    bool   `json:"mfa_enabled"`
	} `json:"account"`
}

AccountInfo is the response from GET /auth/session.

func GetSession

func GetSession(accessToken string) (*AccountInfo, error)

GetSession returns the account info for the given access token.

type AuthAPIError

type AuthAPIError struct {
	Code    string `json:"error"`
	Message string `json:"message"`
	Status  int
}

AuthAPIError is returned when the auth server returns a non-2xx response.

func (*AuthAPIError) Error

func (e *AuthAPIError) Error() string

type AuthFile

type AuthFile struct {
	// SessionToken is the opaque session token for server-side session lookup.
	SessionToken string `json:"session_token"`
	// AccessToken is the RS256 JWT for subapp requests.
	AccessToken string `json:"access_token"`
	// Email is the account email (display only — not used for auth).
	Email string `json:"email"`
	// Tier is the account tier (display only).
	Tier string `json:"tier"`
	// DisplayName is the account display name (display only).
	DisplayName string `json:"display_name,omitempty"`
	// Bundles are the unlocked plugin bundles (display only).
	Bundles []string `json:"bundles,omitempty"`
	// ExpiresAt is the access token expiry as RFC3339 string.
	ExpiresAt string `json:"expires_at,omitempty"`
}

AuthFile holds the persisted auth credentials.

func ReadAuthFile

func ReadAuthFile() (*AuthFile, error)

ReadAuthFile reads and parses ~/.nself/auth.json. Returns ErrNotLoggedIn if file does not exist.

type DeviceCodeResponse

type DeviceCodeResponse struct {
	DeviceCode      string `json:"device_code"`
	UserCode        string `json:"user_code"`        // XXXX-YYYY format shown to user
	VerificationURL string `json:"verification_url"` // nself.org/auth/cli?code=...
	ExpiresInSec    int    `json:"expires_in"`
	IntervalSec     int    `json:"interval"`
}

DeviceCodeResponse is returned by the device authorization endpoint.

func DeviceAuthorize

func DeviceAuthorize() (*DeviceCodeResponse, error)

DeviceAuthorize initiates the device code flow. Returns a DeviceCodeResponse with the code to display to the user.

type DeviceEntry

type DeviceEntry struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	OS         string `json:"os"`
	LastActive string `json:"last_active"`
	IsCurrent  bool   `json:"is_current"`
}

DeviceEntry represents one registered device for an account.

func GetDevices

func GetDevices(accessToken string) ([]DeviceEntry, error)

GetDevices returns the list of registered devices for the account.

type LicenseInfo

type LicenseInfo struct {
	ID            string   `json:"id"`
	Product       string   `json:"product"`
	Tier          string   `json:"tier"`
	Bundles       []string `json:"bundles"`
	SeatsIncluded int      `json:"seats_included"`
	SeatsUsed     int      `json:"seats_used"`
	IsActive      bool     `json:"is_active"`
	ActivatedAt   string   `json:"activated_at"`
	ExpiresAt     string   `json:"expires_at"`
}

LicenseInfo represents a single license entry.

func GetLicenses

func GetLicenses(accessToken string) ([]LicenseInfo, error)

GetLicenses returns the list of active licenses for the account.

type PollResult

type PollResult struct {
	Token *TokenResponse
}

PollResult holds the outcome of a completed device code poll.

func PollDeviceCode

func PollDeviceCode(ctx context.Context, deviceCode string, onPoll func(elapsed time.Duration)) (*PollResult, error)

PollDeviceCode polls the auth server until the user authorizes the device code, the timeout expires, or the context is cancelled.

onPoll is called before each poll attempt (use for progress indicators). Pass nil to skip the callback.

Returns ErrPollTimeout if the poll window expires without user action. Returns context.Canceled/context.DeadlineExceeded if ctx is cancelled.

type TeamMember

type TeamMember struct {
	Name     string `json:"name"`
	Email    string `json:"email"`
	Role     string `json:"role"`
	JoinedAt string `json:"joined_at"`
}

TeamMember represents one member of an account's team.

func GetTeamMembers

func GetTeamMembers(accessToken string) ([]TeamMember, error)

GetTeamMembers returns the list of team members for the account.

type TokenResponse

type TokenResponse struct {
	AccessToken  string   `json:"access_token"`
	SessionToken string   `json:"session_token"`
	Email        string   `json:"email"`
	Tier         string   `json:"tier"`
	DisplayName  string   `json:"display_name,omitempty"`
	Bundles      []string `json:"bundles,omitempty"`
	ExpiresAt    string   `json:"expires_at"`
}

TokenResponse is returned when the device code is exchanged for a token.

func PollToken

func PollToken(deviceCode string) (*TokenResponse, error)

PollToken polls the auth server for the device code exchange result. Returns (nil, nil) if the user hasn't authorized yet (authorization_pending). Returns an error on timeout or other failure.

func RefreshToken

func RefreshToken(accessToken string) (*TokenResponse, error)

RefreshToken exchanges an existing session for a new access token.