Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

20.9 KB
Raw Blame
// Package session provides durable, revocable session-based
// authentication for automated clients. Each session maps a high-entropy
// token to an agentId, allowing agents to authenticate with a single
// environment variable (PINCHTAB_SESSION) instead of the server bearer token.
package session

import (
	"context"
	"crypto/rand"
	"crypto/sha256"
	"crypto/subtle"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"os"
	"path/filepath"
	"strings"
	"sync"
	"time"
)

// Session represents a durable, revocable authenticated session.
type Session struct {
	ID         string    `json:"id"`
	AgentID    string    `json:"agentId"`
	Label      string    `json:"label,omitempty"`
	Browser    string    `json:"browser,omitempty"`
	TokenHash  [32]byte  `json:"-"`
	CreatedAt  time.Time `json:"createdAt"`
	LastSeenAt time.Time `json:"lastSeenAt"`
	ExpiresAt  time.Time `json:"expiresAt,omitempty"`
	Status     string    `json:"status"`
	Grants     []string  `json:"grants,omitempty"`
}

// The auth modes sessions.agent.mode may name. ModeRequired is vocabulary, not
// behaviour: it is refused by config validation, because accepting it would
// promise session-only auth that the bearer token and the dashboard cookie still
// bypass. This package owns the set so the validator and the predicate cannot
// hold two copies of it.
const (
	ModeOff       = "off"
	ModePreferred = "preferred"
	ModeRequired  = "required"
)

// NormalizeMode is the canonical reading of a sessions.agent.mode value: case
// folded and trimmed, the way this codebase reads every other config enum. The
// validator and the predicate both go through it so the accepted set is spelled
// once, and so "Off" means off rather than being a typo that leaves an auth
// mechanism on.
func NormalizeMode(mode string) string {
	return strings.ToLower(strings.TrimSpace(mode))
}

// ModeServes reports whether a mode value leaves agent sessions serving. It is an
// allowlist, not a denylist: an empty value is the default (ModePreferred) and
// nothing else serves, so a value the validator refuses can never be read as
// "preferred" by a process that started anyway.
func ModeServes(mode string) bool {
	switch NormalizeMode(mode) {
	case "", ModePreferred:
		return true
	default:
		return false
	}
}

// Config controls store behavior.
type Config struct {
	Enabled     bool
	Mode        string
	IdleTimeout time.Duration
	MaxLifetime time.Duration
	PersistPath string
}

// LifecycleEvent describes a session-state transition that downstream
// components (orchestrator binding eviction, instance current-tab cleanup)
// may want to react to.
type LifecycleEvent struct {
	SessionID string
	AgentID   string
	Reason    string // "revoked" | "expired" | "pruned"
}

// LifecycleHook receives events after a store mutation has committed.
// Hooks are invoked outside the store lock; they may do I/O but must not
// re-enter the store synchronously in a way that risks recursion.
type LifecycleHook func(LifecycleEvent)

// Store manages authenticated sessions with persistence.
type Store struct {
	mu            sync.Mutex
	sessions      map[string]*Session   // keyed by session ID
	byTokenHash   map[[32]byte]*Session // secondary index: token hash → session (mirrors `sessions`)
	cfg           Config
	now           func() time.Time
	lastTouchSave time.Time // last time a LastSeen-only update was flushed (debounce gate)

	// Persistence is split off the data lock: a snapshot is built under mu (with
	// a monotonic saveSeq), then marshalled + written under saveMu so routine
	// session traffic isn't serialized behind disk I/O. writtenSeq (guarded by
	// saveMu) lets a writer skip a snapshot older than one already on disk, so a
	// stale snapshot can never clobber a fresher one.
	saveMu     sync.Mutex
	saveSeq    uint64 // guarded by mu
	writtenSeq uint64 // guarded by saveMu

	// hooksMu protects lifecycleHooks. Held only for very short reads /
	// writes so it never blocks anything else. Separate from `mu` so a
	// caller adding a hook never serializes against in-flight mutations.
	hooksMu        sync.RWMutex
	lifecycleHooks []LifecycleHook
}

// touchPersistInterval bounds how often a LastSeen-only update is flushed to
// disk; in-memory LastSeenAt is always current, so this only delays durability
// of the idle-timeout clock by < interval (negligible vs the multi-day idle timeout).
const touchPersistInterval = 30 * time.Second

const (
	DefaultIdleTimeout = 7 * 24 * time.Hour
	DefaultMaxLifetime = 30 * 24 * time.Hour

	StatusActive  = "active"
	StatusRevoked = "revoked"
	StatusExpired = "expired"

	LifecycleReasonRevoked = "revoked"
	LifecycleReasonExpired = "expired"
	LifecycleReasonPruned  = "pruned"
)

// OnLifecycle registers a hook for session lifecycle events. Hooks run
// outside the store lock after a mutation has committed, so they may
// perform I/O without blocking other store operations. Multiple hooks
// run concurrently in separate goroutines.
func (s *Store) OnLifecycle(fn LifecycleHook) {
	if s == nil || fn == nil {
		return
	}
	s.hooksMu.Lock()
	s.lifecycleHooks = append(s.lifecycleHooks, fn)
	s.hooksMu.Unlock()
}

// dispatchLifecycle fires the given events to every registered hook, each hook
// in its own goroutine. Must be called after the store lock has been released —
// never under s.mu.
func (s *Store) dispatchLifecycle(events []LifecycleEvent) {
	if s == nil || len(events) == 0 {
		return
	}
	s.hooksMu.RLock()
	hooks := make([]LifecycleHook, len(s.lifecycleHooks))
	copy(hooks, s.lifecycleHooks)
	s.hooksMu.RUnlock()
	if len(hooks) == 0 {
		return
	}
	// One goroutine per hook (not per event × hook): bounds a revoke/prune burst
	// to the small, fixed number of hooks and delivers events to each hook in
	// order. Hooks still run concurrently with one another. events is built fresh
	// per call and not mutated after dispatch, so the goroutines share it read-only.
	for _, fn := range hooks {
		fn := fn
		go func() {
			for _, evt := range events {
				fn(evt)
			}
		}()
	}
}

// NewStore creates a new session store.
func NewStore(cfg Config) *Store {
	s := &Store{
		sessions:    make(map[string]*Session),
		byTokenHash: make(map[[32]byte]*Session),
		now:         time.Now,
	}
	s.applyConfig(cfg)
	s.loadPersisted()
	return s
}

func (s *Store) applyConfig(cfg Config) {
	if cfg.IdleTimeout <= 0 {
		cfg.IdleTimeout = DefaultIdleTimeout
	}
	if cfg.MaxLifetime <= 0 {
		cfg.MaxLifetime = DefaultMaxLifetime
	}
	if cfg.Mode == "" {
		cfg.Mode = ModePreferred
	}
	s.cfg = cfg
}

// Create generates a new session and returns the session ID and
// plaintext token. The token is returned exactly once and is never stored.
func (s *Store) Create(agentID, label, browser string) (sessionID, sessionToken string, err error) {
	if s == nil {
		return "", "", fmt.Errorf("store is nil")
	}

	id, err := generateSessionID()
	if err != nil {
		return "", "", err
	}
	token, err := generateToken()
	if err != nil {
		return "", "", err
	}

	now := s.now()
	session := &Session{
		ID:         id,
		AgentID:    strings.TrimSpace(agentID),
		Label:      strings.TrimSpace(label),
		Browser:    strings.TrimSpace(browser),
		TokenHash:  hashToken(token),
		CreatedAt:  now,
		LastSeenAt: now,
		Status:     StatusActive,
	}

	job, persist := s.registerSession(session, now)
	if persist {
		s.writeSnapshot(job)
	}

	return id, token, nil
}

// registerSession stamps the lifetime from config and installs the session in both
// indexes, all under s.mu. It exists so Create names neither s.cfg nor the maps:
// the expiry used to be built from s.cfg.MaxLifetime BEFORE the lock was taken,
// which is a race against UpdateConfig, and a rule about where a field may be read
// is only enforceable when the reads have a named home.
func (s *Store) registerSession(session *Session, now time.Time) (snapshotJob, bool) {
	s.mu.Lock()
	defer s.mu.Unlock()
	session.ExpiresAt = now.Add(s.cfg.MaxLifetime)
	s.sessions[session.ID] = session
	s.byTokenHash[session.TokenHash] = session
	return s.snapshotLocked()
}

// Authenticate validates a token and returns the associated session.
// It updates LastSeenAt on success.
func (s *Store) Authenticate(token string) (*Session, bool) {
	return s.authenticate(token, true)
}

// AuthenticateWithoutTouch validates a token without updating LastSeenAt.
func (s *Store) AuthenticateWithoutTouch(token string) (*Session, bool) {
	return s.authenticate(token, false)
}

func (s *Store) authenticate(token string, touch bool) (*Session, bool) {
	if s == nil {
		return nil, false
	}
	token = strings.TrimSpace(token)
	if token == "" {
		return nil, false
	}

	hash := hashToken(token)
	now := s.now()

	var (
		match      *Session
		ok         bool
		expiredEvt *LifecycleEvent
		job        snapshotJob
		persist    bool
	)

	func() {
		s.mu.Lock()
		defer s.mu.Unlock()

		sess, found := s.byTokenHash[hash]
		if !found || sess.Status != StatusActive {
			return
		}
		// Defense-in-depth: the map key already matched, but keep a constant-time
		// compare on the single candidate so the final match path is timing-safe.
		if subtle.ConstantTimeCompare(hash[:], sess.TokenHash[:]) != 1 {
			return
		}
		if s.isExpired(sess, now) {
			sess.Status = StatusExpired
			job, persist = s.snapshotLocked()
			expiredEvt = &LifecycleEvent{SessionID: sess.ID, AgentID: sess.AgentID, Reason: LifecycleReasonExpired}
			return
		}
		if touch {
			sess.LastSeenAt = now
			job, persist = s.maybeSnapshotTouchLocked(now)
		}
		match = cloneSessionLocked(sess)
		ok = true
	}()

	if persist {
		s.writeSnapshot(job)
	}
	if expiredEvt != nil {
		s.dispatchLifecycle([]LifecycleEvent{*expiredEvt})
	}
	return match, ok
}

// Touch updates LastSeenAt for an active, unexpired session.
func (s *Store) Touch(sessionID string) bool {
	if s == nil {
		return false
	}

	now := s.now()

	s.mu.Lock()

	sess, ok := s.sessions[strings.TrimSpace(sessionID)]
	if !ok || sess.Status != StatusActive {
		s.mu.Unlock()
		return false
	}
	if s.isExpired(sess, now) {
		sess.Status = StatusExpired
		job, persist := s.snapshotLocked()
		s.mu.Unlock()
		if persist {
			s.writeSnapshot(job)
		}
		return false
	}
	sess.LastSeenAt = now
	job, persist := s.maybeSnapshotTouchLocked(now)
	s.mu.Unlock()
	if persist {
		s.writeSnapshot(job)
	}
	return true
}

// cloneSessionLocked returns a copy no caller can use to mutate store-owned
// state outside the store lock: the Grants slice is cloned rather than aliased.
// Caller must hold s.mu.
func cloneSessionLocked(sess *Session) *Session {
	cp := *sess
	cp.Grants = append([]string(nil), sess.Grants...)
	return &cp
}

// Get returns a defensive copy of a session by its public ID.
func (s *Store) Get(sessionID string) (*Session, bool) {
	if s == nil {
		return nil, false
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	sess, ok := s.sessions[strings.TrimSpace(sessionID)]
	if !ok {
		return nil, false
	}
	return cloneSessionLocked(sess), true
}

// List returns defensive copies of all sessions.
func (s *Store) List() []Session {
	if s == nil {
		return nil
	}
	s.mu.Lock()
	defer s.mu.Unlock()

	out := make([]Session, 0, len(s.sessions))
	for _, sess := range s.sessions {
		out = append(out, *cloneSessionLocked(sess))
	}
	return out
}

// SetGrants replaces a session's capability grants and persists the change. The
// input is cloned so the store owns the slice. Returns false if no such session.
func (s *Store) SetGrants(sessionID string, grants []string) bool {
	if s == nil {
		return false
	}
	s.mu.Lock()
	sess, ok := s.sessions[strings.TrimSpace(sessionID)]
	if !ok {
		s.mu.Unlock()
		return false
	}
	sess.Grants = append([]string(nil), grants...)
	job, persist := s.snapshotLocked()
	s.mu.Unlock()
	if persist {
		s.writeSnapshot(job)
	}
	return true
}

// Revoke marks a session as revoked.
func (s *Store) Revoke(sessionID string) bool {
	if s == nil {
		return false
	}

	var (
		event   LifecycleEvent
		job     snapshotJob
		persist bool
	)
	revoked := func() bool {
		s.mu.Lock()
		defer s.mu.Unlock()

		sess, ok := s.sessions[strings.TrimSpace(sessionID)]
		if !ok {
			return false
		}
		sess.Status = StatusRevoked
		job, persist = s.snapshotLocked()
		event = LifecycleEvent{SessionID: sess.ID, AgentID: sess.AgentID, Reason: LifecycleReasonRevoked}
		return true
	}()
	if !revoked {
		return false
	}
	if persist {
		s.writeSnapshot(job)
	}
	s.dispatchLifecycle([]LifecycleEvent{event})
	return true
}

// UpdateConfig applies new configuration.
func (s *Store) UpdateConfig(cfg Config) {
	if s == nil {
		return
	}
	s.mu.Lock()
	s.applyConfig(cfg)
	events := s.pruneExpiredLocked()
	job, persist := s.snapshotLocked()
	s.mu.Unlock()
	if persist {
		s.writeSnapshot(job)
	}
	s.dispatchLifecycle(events)
}

// MaintenanceInterval is how often RunMaintenance sweeps expired sessions.
const MaintenanceInterval = 5 * time.Minute

// PruneExpired drops revoked and expired sessions, persists the result, and
// dispatches the resulting lifecycle events so downstream bindings are cleared.
func (s *Store) PruneExpired() {
	if s == nil {
		return
	}
	s.mu.Lock()
	events := s.pruneExpiredLocked()
	var (
		job     snapshotJob
		persist bool
	)
	if len(events) > 0 {
		job, persist = s.snapshotLocked()
	}
	s.mu.Unlock()
	if persist {
		s.writeSnapshot(job)
	}
	s.dispatchLifecycle(events)
}

// RunMaintenance sweeps expired sessions until ctx is done. Expiry is otherwise
// only noticed when a session's own token is presented again, so a session that
// is simply abandoned — the usual end of an agent run — is never detected, and
// it plus any downstream binding keyed on its id survive for the life of the
// process.
func (s *Store) RunMaintenance(ctx context.Context) {
	if s == nil {
		return
	}
	t := time.NewTicker(MaintenanceInterval)
	defer t.Stop()
	for {
		select {
		case <-ctx.Done():
			return
		case <-t.C:
			s.PruneExpired()
		}
	}
}

// Enabled is the ONE predicate every consumer of agent sessions asks — the front
// door's session branch, the session API's handlers and their registration. enabled
// and mode were a two-field encoding of one question, and the halves drifted: mode
// was documented as reducing the auth surface while nothing read it.
func (s *Store) Enabled() bool {
	if s == nil {
		return false
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	return s.cfg.Enabled && ModeServes(s.cfg.Mode)
}

// DisabledBy names the settings switching agent sessions off, so a refusal can
// prescribe a command that works. Two fields reach the one predicate, and an
// operator who disabled through one of them is not helped by being told to set
// the other. Empty when the store serves.
func (s *Store) DisabledBy() []string {
	if s == nil {
		return []string{SettingEnabled}
	}
	s.mu.Lock()
	defer s.mu.Unlock()

	var off []string
	if !s.cfg.Enabled {
		off = append(off, SettingEnabled)
	}
	if !ModeServes(s.cfg.Mode) {
		off = append(off, SettingMode)
	}
	return off
}

// PersistPath returns the file the store persists to, so a caller rebuilding
// the config from elsewhere can carry it over instead of recomputing it.
func (s *Store) PersistPath() string {
	if s == nil {
		return ""
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	return s.cfg.PersistPath
}

func (s *Store) isExpired(sess *Session, now time.Time) bool {
	if !sess.ExpiresAt.IsZero() && now.After(sess.ExpiresAt) {
		return true
	}
	if s.cfg.IdleTimeout > 0 && now.Sub(sess.LastSeenAt) > s.cfg.IdleTimeout {
		return true
	}
	return false
}

// pruneExpiredLocked removes revoked/expired sessions. Caller must hold
// s.mu. Returns lifecycle events the caller is responsible for dispatching
// AFTER releasing the lock.
func (s *Store) pruneExpiredLocked() []LifecycleEvent {
	now := s.now()
	var events []LifecycleEvent
	for id, sess := range s.sessions {
		if sess.Status == StatusRevoked {
			delete(s.sessions, id)
			delete(s.byTokenHash, sess.TokenHash)
			events = append(events, LifecycleEvent{SessionID: sess.ID, AgentID: sess.AgentID, Reason: LifecycleReasonPruned})
			continue
		}
		if s.isExpired(sess, now) {
			delete(s.sessions, id)
			delete(s.byTokenHash, sess.TokenHash)
			events = append(events, LifecycleEvent{SessionID: sess.ID, AgentID: sess.AgentID, Reason: LifecycleReasonPruned})
		}
	}
	return events
}

type persistedStore struct {
	SavedAt  time.Time          `json:"savedAt"`
	Sessions []persistedSession `json:"sessions"`
}

type persistedSession struct {
	ID         string    `json:"id"`
	AgentID    string    `json:"agentId"`
	Label      string    `json:"label,omitempty"`
	Browser    string    `json:"browser,omitempty"`
	TokenHash  string    `json:"tokenHash"`
	CreatedAt  time.Time `json:"createdAt"`
	LastSeenAt time.Time `json:"lastSeenAt"`
	ExpiresAt  time.Time `json:"expiresAt,omitempty"`
	Status     string    `json:"status"`
	Grants     []string  `json:"grants,omitempty"`
}

// toPersisted maps an in-memory Session to its on-disk record.
func (sess *Session) toPersisted() persistedSession {
	return persistedSession{
		ID:         sess.ID,
		AgentID:    sess.AgentID,
		Label:      sess.Label,
		Browser:    sess.Browser,
		TokenHash:  hex.EncodeToString(sess.TokenHash[:]),
		CreatedAt:  sess.CreatedAt,
		LastSeenAt: sess.LastSeenAt,
		ExpiresAt:  sess.ExpiresAt,
		Status:     sess.Status,
		// Clone Grants: snapshots are marshalled outside s.mu, so the record must
		// not alias store-owned slices that a concurrent SetGrants could mutate.
		Grants: append([]string(nil), sess.Grants...),
	}
}

// toSession maps an on-disk record back to an in-memory Session, decoding and
// validating the token hash. ok=false means the record is malformed and should
// be skipped.
func (rec persistedSession) toSession() (*Session, bool) {
	tokenHash, err := hex.DecodeString(strings.TrimSpace(rec.TokenHash))
	if err != nil || len(tokenHash) != sha256.Size {
		return nil, false
	}
	var hash [32]byte
	copy(hash[:], tokenHash)

	return &Session{
		ID:         rec.ID,
		AgentID:    rec.AgentID,
		Label:      rec.Label,
		Browser:    rec.Browser,
		TokenHash:  hash,
		CreatedAt:  rec.CreatedAt,
		LastSeenAt: rec.LastSeenAt,
		ExpiresAt:  rec.ExpiresAt,
		Status:     rec.Status,
		Grants:     append([]string(nil), rec.Grants...),
	}, true
}

func (s *Store) loadPersisted() {
	s.mu.Lock()
	defer s.mu.Unlock()

	if s.cfg.PersistPath == "" {
		return
	}

	data, err := os.ReadFile(s.cfg.PersistPath)
	if err != nil {
		return
	}
	var persisted persistedStore
	if err := json.Unmarshal(data, &persisted); err != nil {
		return
	}

	now := s.now()
	for _, rec := range persisted.Sessions {
		sess, ok := rec.toSession()
		if !ok {
			continue
		}
		if sess.Status != StatusActive {
			continue
		}
		if s.isExpired(sess, now) {
			continue
		}
		s.sessions[sess.ID] = sess
		s.byTokenHash[sess.TokenHash] = sess
	}
}

// snapshotJob is a self-contained persistence snapshot stamped with a sequence,
// built under s.mu and written outside it.
type snapshotJob struct {
	snapshot persistedStore
	seq      uint64
	path     string
}

// snapshotLocked builds a self-contained value-copy snapshot of every session
// and stamps it with a monotonic sequence. Caller must hold s.mu. ok=false when
// persistence is disabled (no PersistPath), in which case there is nothing to write.
func (s *Store) snapshotLocked() (snapshotJob, bool) {
	if s.cfg.PersistPath == "" {
		return snapshotJob{}, false
	}
	s.saveSeq++
	snapshot := persistedStore{
		SavedAt:  s.now().UTC(),
		Sessions: make([]persistedSession, 0, len(s.sessions)),
	}
	for _, sess := range s.sessions {
		snapshot.Sessions = append(snapshot.Sessions, sess.toPersisted())
	}
	return snapshotJob{snapshot: snapshot, seq: s.saveSeq, path: s.cfg.PersistPath}, true
}

// maybeSnapshotTouchLocked builds a snapshot for a LastSeen-only update at most
// once per touchPersistInterval. Caller must hold s.mu; the resulting write
// happens after the lock is released. The next real mutation's snapshot
// opportunistically flushes any debounced LastSeen for all sessions.
func (s *Store) maybeSnapshotTouchLocked(now time.Time) (snapshotJob, bool) {
	if now.Sub(s.lastTouchSave) < touchPersistInterval {
		return snapshotJob{}, false
	}
	s.lastTouchSave = now
	return s.snapshotLocked()
}

// writeSnapshot marshals and atomically writes a snapshot outside s.mu. Writers
// serialize on saveMu; a snapshot older than one already written is skipped so a
// stale snapshot can never clobber a fresher one.
func (s *Store) writeSnapshot(job snapshotJob) {
	if job.path == "" {
		return
	}
	s.saveMu.Lock()
	defer s.saveMu.Unlock()
	if job.seq <= s.writtenSeq {
		return
	}
	s.writtenSeq = job.seq

	data, err := json.MarshalIndent(job.snapshot, "", "  ")
	if err != nil {
		return
	}
	if err := os.MkdirAll(filepath.Dir(job.path), 0755); err != nil {
		return
	}
	tmpPath := job.path + ".tmp"
	if err := os.WriteFile(tmpPath, data, 0600); err != nil {
		return
	}
	_ = os.Rename(tmpPath, job.path)
}

func generateSessionID() (string, error) {
	return generatePrefixedHex(idRandomBytes)
}

func generateToken() (string, error) {
	return generatePrefixedHex(tokenRandomBytes)
}

func generatePrefixedHex(size int) (string, error) {
	buf := make([]byte, size)
	if _, err := rand.Read(buf); err != nil {
		return "", err
	}
	return IDPrefix + hex.EncodeToString(buf), nil
}

func hashToken(token string) [32]byte {
	return sha256.Sum256([]byte(strings.TrimSpace(token)))
}