Documentation
¶
Overview ¶
Package session provides session management for authenticated users.
This package defines interfaces for session storage and OAuth state management, with implementations for different backends:
- memory: In-memory storage for development/testing
- redis: Redis-backed storage for production multi-instance deployments
- file: File-based storage for CLI applications
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:
// Development
store := memory.NewStore()
// Production
store, err := redis.NewStore(ctx, redis.Config{
Addr: "localhost:6379",
})
// CLI
store, err := file.NewStore("") // Uses ~/.config/stacktower/sessions/
Manage sessions:
// Create session
sess, err := session.New(accessToken, user, session.DefaultTTL)
if err != nil {
return err
}
store.Set(ctx, sess)
// Retrieve session
sess, err := store.Get(ctx, sessionID)
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. ErrNotFound = errors.New("not found") // 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.
func MockLocal ¶
func MockLocal() *Session
MockLocal creates a mock session for local development without authentication. This is used when --no-auth is enabled in standalone mode. The mock user has ID "local" and no GitHub access token.
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