Authentication System

Relevant source files

The following files were used as context for generating this wiki page:

• osmosis_ai/auth/flow.py
• osmosis_ai/auth/credentials.py
• osmosis_ai/auth/local_server.py
• osmosis_ai/auth/config.py
• osmosis_ai/auth/platform_client.py
• osmosis_ai/cli_commands.py

The Authentication System in the Osmosis SDK provides a secure, multi-workspace mechanism for users to authenticate the CLI with the Osmosis Platform. It leverages an OAuth-style flow using a local loopback server to capture tokens from a web-based login, ensuring that sensitive credentials never require manual entry in the terminal.

The system is designed to support multiple workspaces (organizations), allowing users to switch between different environments while maintaining independent access tokens and user identity information. All credentials are encrypted via filesystem permissions and stored locally for persistent CLI access.

Sources: osmosis_ai/auth/flow.py, osmosis_ai/auth/credentials.py, osmosis_ai/auth/config.py

Login Flow Orchestration

The login process is orchestrated by the login function, which coordinates a local HTTP server, the user's web browser, and the Osmosis Platform API. The flow ensures CSRF protection through a state parameter and handles automatic port discovery within a specific range.

Sequence of Authentication

1. Port Discovery: The system searches for an available port between 8976 and 8985.
2. Server Initialization: A LocalAuthServer is started on the discovered port.
3. Browser Redirect: The CLI opens the system browser to the Osmosis Platform's /cli-auth endpoint.
4. Callback Capture: The local server listens for a GET request at /callback containing a token and state.
5. Verification: The captured token is sent back to the platform's /api/cli/verify endpoint for validation and to retrieve user/organization metadata.

Local Callback Server

The LocalAuthServer (a subclass of HTTPServer) and AuthCallbackHandler manage the loopback communication. This component is responsible for receiving the authentication token and providing visual feedback to the user in their browser after a successful or failed login attempt.

Key Components

• CSRF Validation: Compares the state returned by the platform against the expected_state generated at the start of the flow.
• State Management: Uses threading.Event objects (_token_event, _verification_event) to synchronize the asynchronous HTTP request with the CLI's main execution thread.
• HTML Response: Serves dynamically generated HTML pages to indicate "Login Successful" or "Login Failed" to the user.

Sources: osmosis_ai/auth/local_server.py:17-80, osmosis_ai/auth/local_server.py:230-264

Credential Management

The system supports a multi-tenant architecture where credentials for different workspaces are stored in a centralized JSON file.

Data Structures

The system uses several dataclasses to represent identity and access:

Class	Description	Fields
UserInfo	Identity of the authenticated user.	id, email, name
OrganizationInfo	Metadata about the workspace.	id, name, role
WorkspaceCredentials	Combined token and identity data.	access_token, expires_at, user, organization
CredentialsStore	The root container for all local auth.	active_workspace, workspaces (dict)

Sources: osmosis_ai/auth/credentials.py:16-105

Storage and Security

Credentials are saved to ~/.config/osmosis/credentials.json. The system enforces strict filesystem permissions:

• Directory: Created with mode 0o700 (read/write/execute for owner only).
• File: Created with mode 0o600 (read/write for owner only).
• Atomicity: Uses a temporary file (.tmp) and a rename operation to ensure the credentials file is never left in a corrupted state during writes.

Sources: osmosis_ai/auth/credentials.py:133-165, osmosis_ai/auth/config.py:15-16

Platform API Interaction

The platform_client provides an authenticated wrapper for interacting with the Osmosis Platform. It includes automatic error handling and session cleanup logic.

Authentication Headers

Every request to the platform via platform_request automatically injects the following headers:

req_headers = {
    "Authorization": f"Bearer {credentials.access_token}",
    "Content-Type": "application/json",
    "User-Agent": f"osmosis-cli/{PACKAGE_VERSION}",
}

Sources: osmosis_ai/auth/platform_client.py:82-87

Automatic Session Cleanup

If the platform returns an HTTP 401 Unauthorized response, the system assumes the token has been revoked or expired. It triggers _handle_401_and_cleanup(), which:

1. Identifies the active workspace.
2. Deletes the credentials for that specific workspace from the local store.
3. Raises an AuthenticationExpiredError, prompting the user to run osmosis login again.

Sources: osmosis_ai/auth/platform_client.py:34-44

Workspace Switching

The CLI allows users to maintain multiple active sessions. The CredentialsStore tracks which workspace is currently "active" for API calls.

Workspace Management Functions

Function	File Path	Description
set_active_workspace	credentials.py	Changes the active_workspace pointer in the JSON store.
get_all_workspaces	credentials.py	Returns a list of all logged-in organizations and their status.
delete_workspace_credentials	credentials.py	Removes a specific workspace and updates the active pointer if necessary.

Sources: osmosis_ai/auth/credentials.py:228-278

Summary

The Osmosis Authentication System provides a robust, developer-friendly CLI login experience. By combining a local loopback server with persistent, multi-workspace storage, it allows users to securely manage access to various organizations. The integration of automatic 401 handling ensures that the local state remains synchronized with the platform's session lifecycle.