Function validate_session_key

openhands/app_server/sandbox/session_auth.py:37–100

Validate an ``X-Session-API-Key`` and return the associated sandbox. Security: This function enforces that session API keys are only valid for RUNNING sandboxes. This is a critical security measure to prevent leaked keys from being used to access user secrets after a san

(session_api_key: str | None)

async def validate_session_key(session_api_key: str | None) -> SandboxInfo:
    """Validate an ``X-Session-API-Key`` and return the associated sandbox.

    Security:
        This function enforces that session API keys are only valid for RUNNING
        sandboxes. This is a critical security measure to prevent leaked keys
        from being used to access user secrets after a sandbox has been paused,
        stopped, or deleted.

    Raises:
        HTTPException(401): if the key is missing or does not map to a sandbox.
        HTTPException(401): if the sandbox is not in RUNNING state.
        HTTPException(401): in SAAS mode if the sandbox has no owning user.
    """
    if not session_api_key:
        raise HTTPException(
            status.HTTP_401_UNAUTHORIZED,
            detail='X-Session-API-Key header is required',
        )

    # The sandbox service is scoped to users. To look up a sandbox by session
    # key (which could belong to *any* user) we need an admin context.  This
    # is the same pattern used in webhook_router.valid_sandbox().
    state = InjectorState()
    setattr(state, USER_CONTEXT_ATTR, ADMIN)

    async with get_sandbox_service(state) as sandbox_service:
        sandbox_info = await sandbox_service.get_sandbox_by_session_api_key(
            session_api_key
        )

    if sandbox_info is None:
        raise HTTPException(
            status.HTTP_401_UNAUTHORIZED, detail='Invalid session API key'
        )

    # Security: Reject session keys for non-running sandboxes.
    # This prevents leaked keys from being used to access secrets after
    # the sandbox has been paused, stopped, or deleted.
    if sandbox_info.status != SandboxStatus.RUNNING:
        _logger.warning(
            'Session key rejected for non-running sandbox',
            extra={
                'sandbox_id': sandbox_info.id,
                'status': sandbox_info.status.value,
            },
        )
        raise HTTPException(
            status.HTTP_401_UNAUTHORIZED,
            detail='Sandbox is not running',
        )

    if not sandbox_info.created_by_user_id:
        if get_global_config().app_mode == AppMode.SAAS:
            _logger.error(
                'Sandbox had no user specified',
                extra={'sandbox_id': sandbox_info.id},
            )