Skip to content

Session Management API

Auto-generated API documentation for web session management.

Terminology

This module manages workspace identification through browser cookies. Despite the module name "session", it primarily handles workspace IDs for data isolation rather than conversation sessions.

session

Session management functions for PitLane AI web application.

Note: In this module, 'session_id' refers to the workspace identifier (UUID stored in browser cookie), which is distinct from the 'agent_session_id' (Claude SDK session ID for conversation resumption).

validate_session_safely(session)

Validate session with constant-time checks to prevent timing attacks.

Performs validation checks in a consistent order regardless of where validation fails, making it harder for attackers to probe for valid session IDs.

PARAMETER DESCRIPTION
session

Session ID from cookie (may be None)

TYPE: str | None

RETURNS DESCRIPTION
bool

Tuple of (is_valid, session_id)
str | None
  • is_valid: True if session is valid and exists
tuple[bool, str | None]
  • session_id: The validated session ID if valid, None otherwise
Source code in packages/pitlane-web/src/pitlane_web/session.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
def validate_session_safely(session: str | None) -> tuple[bool, str | None]:
    """Validate session with constant-time checks to prevent timing attacks.

    Performs validation checks in a consistent order regardless of where validation
    fails, making it harder for attackers to probe for valid session IDs.

    Args:
        session: Session ID from cookie (may be None)

    Returns:
        Tuple of (is_valid, session_id)
        - is_valid: True if session is valid and exists
        - session_id: The validated session ID if valid, None otherwise
    """
    # Always check format first (constant time for UUID validation)
    is_valid_format = is_valid_session_id(session) if session else False

    # Always check workspace existence (even if format invalid, to maintain constant timing)
    # This prevents attackers from using timing to determine if a UUID exists
    # Use cached version for better performance
    exists = workspace_exists_cached(session) if is_valid_format else False

    # Return result
    is_valid = is_valid_format and exists
    validated_session = session if is_valid else None

    return (is_valid, validated_session)

update_workspace_metadata_safe(session_id)

Safely update workspace metadata with proper error logging.

PARAMETER DESCRIPTION
session_id

Session ID to update

TYPE: str

Source code in packages/pitlane-web/src/pitlane_web/session.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
def update_workspace_metadata_safe(session_id: str) -> None:
    """Safely update workspace metadata with proper error logging.

    Args:
        session_id: Session ID to update
    """
    try:
        update_workspace_metadata(session_id)
    except FileNotFoundError as e:
        logger.warning(f"Workspace metadata file not found for session {session_id}: {e}")
    except PermissionError as e:
        logger.error(f"Permission denied updating workspace metadata for session {session_id}: {e}")
    except Exception as e:
        logger.error(f"Unexpected error updating workspace metadata for session {session_id}: {e}", exc_info=True)