auth

Documentation

Overview

Package auth manages credentials for the Timestripe CLI.

Two credential types are supported:

• "bearer": personal API token
• "oauth": OAuth2 authorization-code + PKCE access/refresh token pair

Credentials are persisted to $XDG_CONFIG_HOME/timestripe/credentials.json.

Index

• Constants
• Variables
• type Credentials
  • func LoginPKCE(ctx context.Context, scopes []string, userAgent string) (*Credentials, error)
  • func Resolve(ctx context.Context) (*Credentials, error)
  • func (c *Credentials) Expired() bool
• type Store
  • func DefaultStore() Store
• type Type

Constants

const ClientID = "timestripe-cli"

ClientID is the OAuth client identifier for the CLI.

Variables

var ErrNotFound = errors.New("no credentials stored; run `timestripe auth login`")

ErrNotFound is returned when no credentials are stored.

Types

type Credentials

type Credentials struct {
	Type         Type      `json:"type"`
	AccessToken  string    `json:"accessToken"`
	RefreshToken string    `json:"refreshToken,omitempty"`
	ExpiresAt    time.Time `json:"expiresAt,omitempty"`
	// Backend is the Timestripe site root the user signed into.
	// Used to pin subsequent requests to the same environment.
	Backend string `json:"backend,omitempty"`
}

Credentials is the persisted auth state for a user.

func LoginPKCE

func LoginPKCE(ctx context.Context, scopes []string, userAgent string) (*Credentials, error)

LoginPKCE runs the OAuth2 authorization-code flow with PKCE against a loopback redirect on an OS-assigned random port. The backend accepts any 127.0.0.1 loopback redirect URI, so no static port registration is needed.

userAgent, if non-empty, is sent on the token-exchange request so the OAuth server can identify the CLI client.

Flow:

1. Start an HTTP server on 127.0.0.1:0 (OS picks a free port).
2. Open the user's browser to the authorization URL.
3. Wait for the browser to hit /callback with ?code=...&state=....
4. Exchange code + PKCE verifier for tokens.

func Resolve

func Resolve(ctx context.Context) (*Credentials, error)

Resolve returns the caller's current credentials, respecting the TIMESTRIPE_TOKEN environment override (which wins over any stored creds). Callers should pass ctx through to token-refresh flows when Expired().

func (*Credentials) Expired

func (c *Credentials) Expired() bool

Expired reports whether the access token has (or is about to) expire. Always false for bearer tokens (personal API keys do not expire client-side).

type Store

type Store interface {
	Load() (*Credentials, error)
	Save(*Credentials) error
	Delete() error
}

Store persists credentials to some backend.

func DefaultStore

func DefaultStore() Store

DefaultStore returns the file-backed credentials store.

type Type

type Type string

Type enumerates supported credential kinds.

const (
	TypeBearer Type = "bearer"
	TypeOAuth  Type = "oauth"
)