Technical details

General overview

Offline access in Passwork is a local cache of individual items, not a full copy of vault(s). It is built after authentication and synchronization with the server.

How it works:

• Passwork keeps a list of selected items added to offline access.
• The desktop application receives this list through the API.
• Selected items are saved locally.
• The password and custom fields of the item are encrypted with a separate local key before storage.
• If the connection to the server is lost, the application uses the local cache.
• When the connection is restored, the application sends accumulated events and updates local data.

Window shown when the server is unavailable

While running, the desktop application separately monitors network status and the availability of the Passwork server. Loss of internet connection, an unavailable VPN, an API request timeout, or another transport error does not automatically switch the application to offline mode. First, the application sends a control request to the server to rule out a temporary failure.

If the server is still unavailable, the Connection error window opens. It shows the current host address and a list of technical causes to check. The window cannot be closed by clicking the background. The user must explicitly choose the next action.

The following actions are available in the window:

• Connect — sends the control request to the server again. If the server responds successfully, the application closes the window and continues the online session.
• Offline mode — available only to users who are allowed to use offline access. The application closes the window, switches the interface to offline mode, and stops sending server requests until reconnection.
• Sign out — performs a local logout without contacting the server. The application cancels active requests, clears the local session, and returns the user to the login screen.

After switching to offline mode, the top panel shows that the server is unavailable and displays a reconnect button. This button checks server availability again, refreshes the session, and returns the application to online mode only after a successful response.

info

A cold start without a network connection is handled separately: if offline access was enabled in advance, the application restores saved authentication data from local storage and opens the offline interface without showing this window.

Where the cache is stored

Offline data is stored in the same local database file as other Passwork service data:

• Windows — %APPDATA%\@passwork\app\app-data.db;
• macOS — ~/Library/Application Support/@passwork/app/app-data.db;
• Linux — ~/.config/@passwork/app/app-data.db (or the path from XDG_CONFIG_HOME).

How data is encrypted

Offline access uses two levels of protection.

Encryption of local items

Sensitive values in app-data.db are saved through safeStorage. This is a wrapper over the operating system's secret storage:

• Windows — DPAPI / Credential Manager tied to the user account;
• macOS — Keychain;
• Linux — compatible Secret Service (GNOME Keyring, KWallet, etc.).

Encryption keys are managed by the operating system and are not stored in application files. Only encrypted base64 values are written to app-data.db.

Encryption of item fields

Before each item is saved, the application additionally encrypts its secret part: the password value and custom fields.

For the local offline cache, the application generates a separate AES-256 key and stores it in safeStorage. The secret part of the item is then encrypted with AES-GCM and saved inside the local copy.

What is saved

For each synchronized item:

• item and related entity identifiers;
• name;
• login;
• URLs;
• tags;
• note;
• color;
• directory;
• encrypted password value;
• encrypted custom fields.

The password and custom fields are encrypted with a separate AES-256 layer. Other data is stored as local copy metadata and protected through safeStorage.

What is not saved

The local cache is not a full copy of all data related to an item. The following are not saved:

• Attachments;
• Item editions;
• Item action history;
• Vault and folder structure;
• Item icons.

Local copy states

An offline item has a state that determines whether it can be opened without a network connection:

State	Meaning
synchronized	The item is saved locally and available for viewing.
not_synchronized	The item is in the offline list, but the local copy was not synchronized.
revoked	Access to the item was revoked on the server.
exceeded	The item exceeds the quantity limit for the role.
outdated	The local copy is outdated according to the retentionHours rule.

warning

States are not shown in the application — they are internal logic used when working with offline items.

The outdated state is calculated locally: the application compares the current time with the last synchronization and the time the item was added. If the offline access period without synchronization has expired, the item is considered outdated.

Synchronization

Synchronization runs only when the application is online.

When offline mode is enabled for the first time:

1. The application saves the offline mode enabled flag.
2. It receives from the server the list of items added to offline access.
3. It sends the server the list of current local versions.
4. It receives changed items and the list of unavailable items.
5. It updates the local item cache and the list for the offline section.
6. It saves the time of successful synchronization.

When the network is restored:

• the application runs synchronization again;
• it sends accumulated events;
• it updates local item copies.

If an item was removed from offline access or became unavailable, the application deletes its local copy at the next synchronization.

Limitations and access

Offline access depends on the following role settings:

• Save passwords offline
• Limit offline passwords per device
• Limit offline access duration without sync (in hours)

If an administrator revokes access to an item or changes user permissions, the application learns about this only at the next server connection and synchronization. Until the connection is restored, the last locally cached version of the item remains available.

LLM version