feat: Add session ID file (#279)

* feat: Add session ID file

* Add support for differentiating between tokens and session IDs in logout

* Remove `clear_auth_token_file` command

* Add `SessionID{File,List,Info}` tests

* test: Update `add_zabbix_endpoint` comments, order

* Rename: "Session ID file" -> "Session file"

* rename default session file

* docs: Update auth + config options

* Update changelog

* Fix `SessionFile` subclass inheritance

* Add INFO log for successful session file save

* Simplify `SessionFile` API

* Docs: Add explainer on session file purpose

Author: pederhan

Diff for: CHANGELOG

@@ -12,11 +12,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Environment variable `ZABBIX_URL` to specify the URL for the Zabbix API.
+- Session file for storing Zabbix API sessions for multiple URLs and users.
+  - This allows for multiple Zabbix instances to be used without re-authenticating.
+  - The session file is stored in the application's data directory by default with the name `.zabbix-cli_session.json`.
+- `app.use_session_file` configuration option to enable or disable session file usage.
 
 ### Changed
 
 - Authentication info from environment variables now take priority over the configuration file.
 
+### Deprecated
+
+- Auth token file. Use the new session file instead. Session files are now created by default if `app.use_auth_token_file` is set to `true` in the configuration file.
+- `app.use_auth_token_file` configuration option. Use `app.use_session_file` instead.
+
 ## [3.4.2](https://github.com/unioslo/zabbix-cli/releases/tag/3.4.2) - 2024-12-16
 
 ### Changed

Diff for: docs/guide/authentication.md

@@ -2,27 +2,24 @@
 
 Zabbix-cli provides several ways to authenticate. They are tried in the following order:
 
-1. [Token - Environment variables](#environment-variables)
-1. [Token - Config file](#config-file)
-1. [Token - Auth token file](#auth-token-file)
+1. [API Token - Environment variables](#environment-variables)
+1. [API Token - Config file](#config-file)
+1. [Session file](#session-file)
 1. [Password - Environment variables](#environment-variables_1)
 1. [Password - Config file](#config-file_1)
 1. [Password - Auth file](#auth-file)
 1. [Password - Prompt](#prompt)
 
-## Token
+## API Token
 
-The application supports authenticating with an API or session token. API tokens are created in the Zabbix frontend or via `zabbix-cli create_token`. A session token is obtained by logging in to the Zabbix API with a username and password.
-
-!!! info "Session vs API token"
-    Semantically, a session token and API token are the same thing from an API authentication perspective. They are both sent as the `auth` parameter in the Zabbix API requests.
+The application supports authenticating with an API token. API tokens are created in the Zabbix frontend or via `zabbix-cli create_token`.
 
 ### Environment variables
 
 The API token can be set as an environment variable:
 
 ```bash
-export ZABBIX_API_TOKEN="API TOKEN"
+export ZABBIX_API_TOKEN="API_TOKEN"
 ```
 
 ### Config file
@@ -34,19 +31,21 @@ The token can be set directly in the config file:
 auth_token = "API_TOKEN"
 ```
 
-### Auth token file
+## Session file
+
+The application can store and reuse session tokens between runs. Multiple sessions can be stored at the same time, which allows for switching between different users and/or Zabbix servers seamlessly without having to re-authenticate.
 
-The application can store and reuse session tokens between runs. This feature is enabled by default and configurable via the following options:
+This feature is enabled by default and configurable via the following options:
 
 ```toml
 [app]
-# Enable token file storage (default: true)
-use_auth_token_file = true
+# Enable persistent sessions (default: true)
+use_session_file = true
 
 # Customize token file location (optional)
-auth_token_file = "/path/to/auth/token/file"
+session_file = "/path/to/auth/token/file"
 
-# Enforce secure file permissions (default: true, no effect on Windows)
+# Enforce secure file permissions (600) (default: true, no effect on Windows)
 allow_insecure_auth_file = false
 ```
 
@@ -117,6 +116,14 @@ They are processed in the following order:
 
 The URL should not include `/api_jsonrpc.php`.
 
+### Environment variables
+
+The URL can also be set as an environment variable:
+
+```bash
+export ZABBIX_URL="http://zabbix.example.com"
+```
+
 ### Config file
 
 The URL of the Zabbix API can be set in the config file:
@@ -127,14 +134,6 @@ The URL of the Zabbix API can be set in the config file:
 url = "http://zabbix.example.com"
 ```
 
-### Environment variables
-
-The URL can also be set as an environment variable:
-
-```bash
-export ZABBIX_URL="http://zabbix.example.com"
-```
-
 ### Prompt
 
 When all other methods fail, the application will prompt for the URL of the Zabbix API.

Diff for: docs/guide/configuration.md

@@ -183,8 +183,8 @@ To do this, we need to add Field() for every field in the model, and also ensure
     export_directory = "/path/to/exports"
     export_format = "json"
     export_timestamps = true
-    use_auth_token_file = true
-    auth_token_file = "/path/to/auth_token_file"
+    use_session_file = true
+    session_file = "/path/to/session_file.json"
     auth_file = "/path/to/auth_token_file"
     history = true
     history_file = "/path/to/history_file.history"
@@ -304,39 +304,39 @@ To do this, we need to add Field() for every field in the model, and also ensure
 
     ----
 
-    #### `use_auth_token_file`
+    #### `use_session_file`
 
-    Whether to use an auth token file to save session token once authenticated. Allows for reusing the token in subsequent sessions.
+    Whether to save session tokens to a file for persistent user sessions.
 
     Type: `bool`
 
     Default: `true`
 
     ```toml
     [app]
-    use_auth_token_file = true
+    use_session_file = true
     ```
 
     ----
 
-    #### `auth_token_file`
+    #### `session_file`
 
-    Paht to the auth token file.
+    Path to the session file.
 
     Type: `str`
 
-    Default: `"<DATA_DIR>/zabbix-cli/.zabbix-cli_auth_token"`
+    Default: `"<DATA_DIR>/zabbix-cli/.zabbix-cli_session.json"`
 
     ```toml
     [app]
-    auth_token_file = "/path/to/auth_token_file"
+    session_file = "/path/to/session_file.json"
     ```
 
     ----
 
     #### `auth_file`
 
-    Paht to a file containing username and password in the format `username:password`. Alternative to specifying `username` and `password` in the configuration file.
+    Path to a file containing username and password in the format `username:password`. Alternative to specifying `username` and `password` in the configuration file.
 
     Type: `str`
 

Diff for: tests/conftest.py

@@ -8,7 +8,6 @@
 import pytest
 import typer
 from packaging.version import Version
-from pytest_httpserver import HTTPServer
 from typer.testing import CliRunner
 from zabbix_cli.app import StatefulApp
 from zabbix_cli.config.model import Config
@@ -113,18 +112,6 @@ def zabbix_client_mock_version(
     yield zabbix_client
 
 
-def add_httpserver_version_endpoint(
-    httpserver: HTTPServer, version: Version, id: int = 0
-) -> None:
-    """Add an endpoint emulating the Zabbix apiiinfo.version method."""
-    httpserver.expect_oneshot_request(
-        "/api_jsonrpc.php",
-        json={"jsonrpc": "2.0", "method": "apiinfo.version", "params": {}, "id": id},
-        method="POST",
-        headers={"Content-Type": "application/json-rpc"},
-    ).respond_with_json({"jsonrpc": "2.0", "result": str(version), "id": id})
-
-
 @pytest.fixture(name="force_color")
 def force_color() -> Generator[Any, Any, Any]:
     import os

Diff for: tests/data/zabbix-cli.toml

@@ -14,7 +14,7 @@ export_directory = "/path/to/exports"
 export_format = "json"
 export_timestamps = false
 use_colors = true
-use_auth_token_file = true
+use_session_file = true
 auth_token_file = "/path/to/auth_token_file"
 auth_file = "/path/to/auth_file"
 use_paging = false

Diff for: tests/pyzabbix/test_client.py

@@ -13,7 +13,8 @@
 from zabbix_cli.pyzabbix.client import add_param
 from zabbix_cli.pyzabbix.client import append_param
 
-from tests.conftest import add_httpserver_version_endpoint
+from tests.utils import add_zabbix_endpoint
+from tests.utils import add_zabbix_version_endpoint
 
 
 @pytest.mark.parametrize(
@@ -184,33 +185,66 @@ def test_client_auth_method(
     version: Version,
     expect_method: AuthMethod,
 ) -> None:
+    """Test that the correct auth method (body/header) is used based on the Zabbix server version."""
     # Add endpoint for version check
     zabbix_client.set_url(httpserver.url_for("/api_jsonrpc.php"))
 
     # Set a mock token we can use for testing
     zabbix_client.auth = "token123"
 
     # Add endpoint that returns the parametrized version
-    add_httpserver_version_endpoint(httpserver, version, id=0)
+    add_zabbix_version_endpoint(httpserver, str(version), id=0)
 
     assert zabbix_client.version == version
 
-    data = {"jsonrpc": "2.0", "method": "fake.method", "params": {}, "id": 1}
-    headers = {}
-
+    headers: dict[str, str] = {}
+    auth = None
     # We expect auth token to be in header on >= 6.4.0
     if expect_method == "header":
         headers["Authorization"] = f"Bearer {zabbix_client.auth}"
     else:
-        data["auth"] = zabbix_client.auth
+        auth = zabbix_client.auth
 
-    httpserver.expect_oneshot_request(
-        "/api_jsonrpc.php",
-        json=data,
+    add_zabbix_endpoint(
+        httpserver,
+        method="test.method.do_stuff",
+        params={},
+        response="authtoken123456789",
         headers=headers,
-        method="POST",
-    ).respond_with_json({"jsonrpc": "2.0", "result": "authtoken123456789", "id": 1})
+        auth=auth,
+    )
 
     # Will fail if the auth method is not set correctly
-    resp = zabbix_client.do_request("fake.method")
+    resp = zabbix_client.do_request("test.method.do_stuff")
     assert resp.result == "authtoken123456789"
+
+    httpserver.check_assertions()
+    httpserver.check_handler_errors()
+
+
+AuthType = Literal["token", "sessionid"]
+
+
+@pytest.mark.parametrize(
+    "auth_type,auth",
+    [
+        pytest.param("token", "authtoken123456789", id="token"),
+        pytest.param("token", "", id="token (empty string)"),
+        pytest.param("sessionid", "sessionid123456789", id="sessionid"),
+        pytest.param("sessionid", "", id="sessionid (empty string)"),
+    ],
+)
+def test_client_logout(httpserver: HTTPServer, auth_type: AuthType, auth: str) -> None:
+    add_zabbix_version_endpoint(httpserver, "7.0.0")
+
+    # We only expect a logout request if we are using a sessionid and have an auth token
+    if auth_type == "sessionid" and auth:
+        add_zabbix_endpoint(httpserver, "user.logout", {}, True)
+    zabbix_client = ZabbixAPI(server=httpserver.url_for("/api_jsonrpc.php"))
+    zabbix_client.auth = auth
+    if auth_type == "token":
+        zabbix_client.use_api_token = True
+    zabbix_client.logout()
+
+    httpserver.check_assertions()
+    httpserver.check_handler_errors()