Documentation
¶
Overview ¶
Package session provides session management for authenticated users.
This package defines interfaces for session storage and OAuth state management. The CLI uses a file-based store; other backends (memory, redis) can be implemented against the Store and StateStore interfaces.
Architecture ¶
Sessions store user authentication data (access tokens, user info) with automatic expiration. The Store interface supports:
- Get/Set/Delete operations
- Automatic expiration checking
- Cleanup of expired sessions
OAuth state tokens provide CSRF protection during the OAuth flow. The StateStore interface supports:
- Token generation with TTL
- Single-use validation (tokens are deleted after validation)
Usage ¶
Create a session store for CLI use:
store, err := session.NewCLIStore() // Uses ~/.config/stacktower/sessions/
Manage sessions:
// Create session
sess, err := session.New(accessToken, user, session.DefaultTTL)
if err != nil {
return err
}
store.SaveSession(ctx, sess)
// Retrieve session
sess, err := store.GetSession(ctx)
if err != nil {
return err
}
if sess == nil || sess.IsExpired() {
// Session not found or expired
}
Index ¶
- Constants
- Variables
- func GenerateID() (string, error)
- func GenerateState() (string, error)
- type CLIStore
- type FileStore
- func (s *FileStore) Cleanup(ctx context.Context) error
- func (s *FileStore) Close() error
- func (s *FileStore) Delete(ctx context.Context, sessionID string) error
- func (s *FileStore) Get(ctx context.Context, sessionID string) (*Session, error)
- func (s *FileStore) Path() string
- func (s *FileStore) Set(ctx context.Context, sess *Session) error
- type Session
- type StateStore
- type Store
Constants ¶
const ( // DefaultTTL is the default session duration. DefaultTTL = 24 * time.Hour // DefaultStateTTL is the default OAuth state token duration. DefaultStateTTL = 10 * time.Minute )
Default durations.
Variables ¶
var ( // ErrNotFound is returned when a session does not exist. // Shared with cache/integrations for consistent errors.Is checks. ErrNotFound = cache.ErrNotFound // ErrExpired is returned when a session has exceeded its TTL. ErrExpired = errors.New("expired") // ErrInvalidState is returned when an OAuth state token is invalid or already used. ErrInvalidState = errors.New("invalid or expired state token") )
Sentinel errors for session operations.
Functions ¶
func GenerateID ¶
GenerateID creates a cryptographically secure random session ID.
func GenerateState ¶
GenerateState creates a cryptographically secure random state token.
Types ¶
type CLIStore ¶
type CLIStore struct {
// contains filtered or unexported fields
}
CLIStore wraps FileStore for simple CLI token storage.
func NewCLIStore ¶
NewCLIStore creates a store for CLI token storage.
func (*CLIStore) DeleteSession ¶
DeleteSession removes the CLI session.
func (*CLIStore) GetSession ¶
GetSession retrieves the CLI session.
type FileStore ¶
type FileStore struct {
// contains filtered or unexported fields
}
FileStore is a file-based session store for CLI applications. Sessions are stored as JSON files in a config directory.
func NewFileStore ¶
NewFileStore creates a new file-based session store. If baseDir is empty, defaults to ~/.config/stacktower/sessions/
type Session ¶
type Session struct {
ID string `json:"id"`
AccessToken string `json:"access_token"`
User *github.User `json:"user"`
ExpiresAt time.Time `json:"expires_at"`
CreatedAt time.Time `json:"created_at"`
}
Session stores user session data.
type StateStore ¶
type StateStore interface {
// Generate creates a new state token and stores it with the given TTL.
// Returns the generated state token.
Generate(ctx context.Context, ttl time.Duration) (string, error)
// Validate checks if a state token is valid and removes it (single-use).
// Returns true if the token was valid and not expired.
Validate(ctx context.Context, state string) (bool, error)
// Cleanup removes expired state tokens (optional, may be no-op for Redis).
Cleanup(ctx context.Context) error
}
StateStore manages OAuth state tokens for CSRF protection. State tokens are short-lived (typically 10 minutes) and single-use. For multi-instance deployments, use Redis to share state across instances.
type Store ¶
type Store interface {
// Get retrieves a session by ID.
// Returns nil, nil if the session doesn't exist.
// Returns nil, ErrExpired if the session exists but has expired.
Get(ctx context.Context, sessionID string) (*Session, error)
// Set stores a session.
Set(ctx context.Context, session *Session) error
// Delete removes a session.
Delete(ctx context.Context, sessionID string) error
// Cleanup removes expired sessions (optional, may be no-op for Redis).
Cleanup(ctx context.Context) error
}
Store is the interface for session storage backends.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package sessiontest provides test helpers for the session package.
|
Package sessiontest provides test helpers for the session package. |