API reference

Key classes and methods for contributors and developers.

Authentication flow

The user enters username + password in the login window.
UserManager.authenticate(username, password) compares the hash, derives the session key on success, and returns it.
The session key is passed into UserConnectionManager and kept only in that instance.
When a connection is read, the encrypted password is decrypted with the session key.
On logout: UserConnectionManager.dispose() removes the key from RAM.

Mount / unmount flow

The UI calls SSHFSController.mount(connection) in a worker thread.
For auth_method="ask": password modal; otherwise connection.password or connection.key_path.
The argument list is built and sshfs.exe is started as a detached subprocess.
After 3 s, list_mounts() validates whether the drive is available.
The UI receives a mount_state_changed(connection_id, "mounted"|"failed", error_text) signal.
Unmount: SSHFSController.unmount(letter) with the fallback chain.

CLI IPC flow

┌────────────┐   JSON-Request    ┌──────────────┐
│ cli_main.py│ ─────────────────►│  ipc_server  │
│  (CLI EXE) │                   │  (GUI Thread)│
└────────────┘ ◄───── JSON ──────└──────────────┘
                Credentials             │
       ▼                                ▼
   spawn ssh                     UserConnMgr.lookup(key)
                                        │
                                        ▼
                                 SQLite + Decrypt

Pipe protocol

// Request
{
  "op": "connect",
  "key": "<access_key>",
  "exec": "<optional command>"
}

// Response (success)
{
  "ok": true,
  "host": "...",
  "port": 22,
  "user": "...",
  "auth_method": "password" | "key",
  "password": "...",
  "key_path": "...",
  "exec": "..."
}

// Response (error)
{ "ok": false, "error": "invalid_key" | "no_session" | "cli_disabled" }

Settings flow

The settings dialog modifies the AppSettings instance.
AppSettings.save() writes JSON.
The settings_changed signal is emitted.
Theme: QApplication.setStyleSheet(load_theme(name)) — no restart needed.
Language: i18n.set_locale(code); all widgets re-render through retranslate_ui().

Public classes & methods

`config.AppSettings`

Method	Description
`AppSettings.load() → AppSettings`	Reads `config.json`, merges it with defaults, and returns an instance.
`save() → None`	Writes current values as JSON.
`reset_to_defaults() → None`	Resets everything to defaults and persists it.

`auth_manager.UserManager`

Method	Description
`create_user(username, password) → User`	Creates a new user and hashes the password.
`authenticate(username, password) → SessionKey \| None`	Login. Returns the derived session key on success.
`change_password(user_id, old, new) → bool`	Re-encrypts all connection passwords with the new session key.
`delete_user(user_id) → None`	Cascade-deletes connections.

`auth_manager.UserConnectionManager`

Method	Description
`list() → list[Connection]`	All connections for the current user.
`get(id) → Connection`	One connection — password decrypted.
`create(connection) → int`	Creates and persists the encrypted password. Returns the ID.
`update(connection) → None`	Re-encrypt & persist.
`delete(id) → None`	Delete.
`by_access_key(key) → Connection \| None`	Used by the IPC server for CLI lookup.

`sshfs_controller.SSHFSController`

Method	Description
`mount(connection, password=None) → MountResult`	Starts a mount. Returns status plus stderr if present.
`unmount(letter) → bool`	Unmounts cleanly, with fallback strategies.
`list_mounts() → list[MountInfo]`	Current mounts.
`status_for(connection) → str`	`"mounted" / "unmounted" / "stale"`.
`cleanup_stale() → int`	Cleans up stale mount points.

`single_instance.SingleInstance`

with SingleInstance("SSHWinManager_Mutex_v1") as inst:
    if not inst.acquired:
        inst.activate_existing_window()
        sys.exit(0)
    run_app()

Generated API docs (optional)

Option A — pdoc

pip install pdoc
pdoc -o site/api src/

Option B — MkDocs Material + mkdocstrings

pip install mkdocs-material mkdocstrings[python]
mkdocs serve