FactorSeal Desktop
The GPUI-based graphical vault host. It can initialize a vault, unlock it with one configured factor group, host FactorSeal’s authenticated native service, and seal it from the window or tray. Password input uses zeroizing masked fields. A dedicated CLI worker receives factors over private inherited pipes, performs native biometric ceremonies, and owns the keys and database. Desktop requests go through the same authenticated native IPC as other clients. The worker drops the unlock password before serving and exits when Desktop closes its lifeline or dies.
Desktop and factorseal agent are two front ends for the same vault host. Run
one at a time. If an agent already owns the endpoint, Desktop reports its live
lease without attempting to take it over. A second Desktop invocation signals
the first instance to activate instead of starting another host.
Clicking the tray icon opens a hidden Desktop, focuses an unfocused Desktop, or hides a focused Desktop. On Niri, an already visible window is focused through the compositor’s IPC without hiding it or changing its position in the layout.
On Linux, the installed Desktop package also provides the session-bus
activation record for org.freedesktop.secrets. A keyring request while sealed
starts Desktop in the background and opens a separate access dialog. The dialog
shows the caller’s executable, working directory, process ID, and lookup
attributes; conventional SecretSpec addresses also show project, profile, and
secret name. Explicit D-Bus unlock prompts show the original requesting application
and requested collection or item paths under “Unlock system keyring”. Collection
requests explicitly say when no individual secret was specified; item names remain
encrypted until unlock. Generic keyring lookups show their supplied attributes in
the main review card. The user can deny the request or allow it and authenticate using
FactorSeal’s secure input. Unlocking and approval stay in the same popup and
reuse the secure password entry. The vault browser stays closed. New access
requires a signed grant for the specific entry, authenticated executable, project, folder, and operation, valid for one hour or until revoked. Keyring approvals bind the stored item ID, so another item with the same service name requires separate approval. The worker
checks grants for every operation. SecretSpec IPC also opens this approval flow,
using its own provider-cache scope. Project labels are caller-supplied context;
the worker authenticates the executable independently. Denial, dismissal, and
timeout return distinct D-Bus errors. The dialog only offers unlock-method
buttons when the vault has multiple methods configured.
Wi-Fi passwords appear under System integrations → Wi-Fi passwords. On Linux, the desktop registers a NetworkManager secret agent on the system bus and stores its credentials in a separate encrypted vault namespace. Personal WPA-PSK/SAE and enterprise 802.1X passwords, raw password bytes, private-key passwords, and token PINs are supported. Stored credentials are keyed by the connection UUID, setting, and property; network names are encrypted metadata.
To use it, configure the connection to store its password for the current user
(agent-owned). For personal Wi-Fi, this is
802-11-wireless-security.psk-flags=1; for enterprise passwords it is
802-1x.password-flags=1. Each certificate password or PIN has its own flags.
Use Move existing Wi-Fi passwords to migrate saved credentials from system
profiles and the current Secret Service keyring. The action copies and verifies
credentials before changing storage flags and cleaning up matching old keyring
entries. It requires NetworkManager 1.44+ and reports failures per connection.
Other running NetworkManager agents may also answer requests; use one credential
agent for predictable routing.
See the Linux Wi-Fi guide for the migration steps and checks before removing an older saved password.
When interaction is allowed, FactorSeal asks to unlock and, if needed, enter a
password using the existing masked input dialog. Noninteractive requests fail
while sealed. REQUEST_NEW prompts for replacement credentials, NOT_SAVED
prevents persistence, and cancellation dismisses pending requests. Raw binary
passwords can be saved/retrieved through the API; interactive entry is text-only.
Registration retries after NetworkManager or the system bus restarts. Network
profiles change only through the explicit migration action. Certificate configuration and verification
remain NetworkManager’s responsibility.
Each SecretSpec and keyring entry has an Access section showing recorded app grants, operations, lifetime, and revocation controls. Existing project, namespace, and secret-type grants remain valid and are labeled as inherited; revoking one removes access across its entire scope. Project grants also show their folder restriction. Older grants are attached to entries only when their stored target digest confirms the target. Grants with unknown targets can be inspected and revoked through the CLI. System-keyring relationships come from stored attributes rather than display labels.
Writes use a masked secret-entry dialog with a Save button, without creating a
persistent write grant. The incoming value can be reviewed or replaced. Native
SecretSpec IPC carries secret values through a private file descriptor. Its
current protocol supplies the value before invoking set; prompting before
that point also requires a change in SecretSpec.
On Wayland compositors supporting layer-shell, including Niri, the access prompt opens as a centered overlay outside the tiling layout. It takes keyboard focus until dismissed; Escape and Deny close it. Compositors without layer-shell receive a normal access dialog instead. No compositor window rule is required.
On Linux, theme probes run as short-lived child processes so GTK and Qt never initialize their global toolkit state inside GPUI. Desktop follows the native light/dark preference and system typography, then applies FactorSeal’s Ink tokens so the product remains recognizable across desktop environments. The XDG settings portal and relevant theme files are watched for changes.
Native integration is isolated in src/theming.rs, brand tokens in
src/branding.rs, and the window and tray in src/app.rs.
The interface follows the brand guide: a single-color chip mark, Ink and Paper surfaces, native sans-serif typography, labeled fields, and explicit sealed/unsealed states. The vault browser uses the available window space; setup and unlock forms stay compact and scroll when the window is short. The mark stays monochrome in error states, while green identifies an unsealed vault and red identifies errors. Small marks use the optical artwork, shared with the generated tray icons.
From the repository root:
devenv shell cargo build -p factorseal --binsdevenv shell -- env -u FACTORSEAL_CLI_EXECUTABLE -u FACTORSEAL_DESKTOP_EXECUTABLE cargo run -p factorseal-desktopInstall both binaries together, or set FACTORSEAL_CLI_EXECUTABLE to the absolute
CLI path. The Nix Desktop package supplies this dependency automatically.
The development command clears executable overrides inherited from an installed
NixOS package so Desktop uses the CLI and browser bridge built beside it.
An older installed CLI can reject desktop-worker, and a missing browser bridge
causes the browser registration warning. Rebuild the CLI binaries after pulling
changes; cargo run -p factorseal-desktop only rebuilds the CLI library dependency,
not its executables.
Set FACTORSEAL_TIMINGS=1 when launching Desktop to log unlock timings to
stderr, including worker setup, executable authentication, permission writes,
service readiness, and inventory loading. Desktop passes this setting to its
CLI worker. Logs contain phase names, durations, and success/error outcomes.
The worker-ready wait includes the worker’s startup phases, and host-authorization
timing includes its grant read and any batched write; these nested timings are not additive.
Readiness is reported after the native listener and lifecycle hooks are installed.
The first status probe includes caller authentication and request handling; request
lock waits are nested within handling. Linux also logs listener setup, expiry
sweeps, and Secret Service name claiming, authorization, and index loading.
SecretSpec discovery leaves an unchanged, correctly protected claim in place.
Its timings separate directory preparation and comparison from temporary-file
writing, disk flush, and rename; the latter phases appear only when replacing a claim.
Host executable identification overlaps TPM/password unsealing; only
wait_host_identities adds time after unsealing if identification is still running.
Password timings separate scratch-memory allocation, Argon2, and secure cleanup.
The store_open/verify_current_state timing covers current inventory verification
and any first-open migration. Schema v6 verifies one signed manifest, current
head metadata, and current ciphertext digests. store_chain timings apply only
to legacy migration: commit and snapshot batches include nested signature and
digest timings, followed by row-set and inventory checks.
Turso retains one encrypted snapshot per document and reuses freed pages during
writes. There is no idle compaction timer. A legacy migration repacks once when
unused pages occupy at least 64 MiB and half the database, verifying authenticated
state afterward. A signed pending flag resumes interrupted cleanup on the next
open. Current records, value-free history and personal replication history are
preserved. Large deletions can leave a physical high-water mark. Turso 0.8.2’s
experimental vacuum flag is enabled only to support this migration cleanup.
The initial unlocked view waits for inventory, then loads permissions separately;
permissions_ready records when that follow-up has reached the UI.
The installed CLI launches the separately packaged application with:
factorseal desktopfactorseal desktop --backgroundLinux currently offers password initialization because the TPM backend does not implement biometric policy. macOS and Windows expose biometric-only, password-and-biometric, and password-or-biometric policies in addition to password-only setup.
Transfer credentials and back up the vault
Section titled “Transfer credentials and back up the vault”The vault has two entry points:
- Transfer credentials imports or exports Personal credentials. It defaults to Encrypted transfer, with passphrase or post-quantum key encryption. Other managers’ file formats are available in this flow.
- Back up vault creates or restores an encrypted FactorSeal backup. The backup format is selected automatically; this flow has no format picker.
The underlying formats are:
.factorseal: a versioned, lossless archive encrypted with a separate passphrase using Argon2id and AES-256-GCM. It includes durable entries and their expiry deadlines, but intentionally excludes provider caches, application authorizations, audit history, and device keys. Restore writes every entry through the live agent so it is protected by the destination device’s hardware-backed vault keys.- Bitwarden JSON, 1Password CSV, and KeePass CSV: plaintext migration formats for Personal secrets only. Login names, passwords, URLs, TOTP seeds, notes, folders/tags where supported, and custom fields are mapped into FactorSeal’s versioned personal-secret record. Legacy FactorSeal name/value records remain readable and exportable.
- Credential Exchange (age encrypted): CXF 1.0 JSON in a standard age v1
encrypted file. Choose Passphrase or Post-quantum key. The key mode
uses ML-KEM-768 + X25519, accepts a public recipient file for export and a
private, unencrypted identity file for import, and interoperates with age
1.3+. Generate the keys with
age-keygen -pq; classical/SSH keys and mixed key files are rejected. Both modes retain age’s standard 128-bit file key. This exports Personal secrets; complete vault backups still use.factorseal. Login/API fields and TOTP credentials have standard representations; other text fields use custom sections. Unsupported source data from other formats and newly created structured fields block export; imported CXF metadata is retained on re-export. Other managers need CXF support and may require a separate age decryption step. This file workflow does not implement the OS credential picker or CXP. - 1Password 1PUX: import-only, including rich source metadata and attachments.
Import results count source items containing data preserved without full functional support. Keep the old vault and verify important credentials before depending on the new vault. Passkey source data is retained for backup; it does not enable passkey authentication. CXF file references require an attachment transport and are rejected before any items are imported.
Imports show a preview after authenticating and validating the complete input. Canceling the preview performs no vault writes. Imports keep existing entries by default; the user can explicitly choose to replace matching addresses. Records commit individually. If interrupted, retry the same file while keeping existing entries to retain completed writes. Plaintext password-manager exports require an explicit plaintext warning acknowledgement and are written with user-only file permissions before writing on Unix and Windows. New vault passwords and archive passphrases share the library strength policy; legacy unlock/decrypt remains compatible. Secret fields are always masked and do not support copying or undo.
Automatic selection uses the detected desktop environment. It prefers Qt on a Qt desktop and GTK otherwise. The choice can be overridden for development:
NATIVE_THEME_BACKEND=qt devenv shell cargo run -p factorseal-desktopNATIVE_THEME_BACKEND=gtk devenv shell cargo run -p factorseal-desktopResolve the native theme without opening the GPUI window or tray:
devenv shell cargo run -p factorseal-desktop -- --theme-probe-onlyCrash reports and logs
Section titled “Crash reports and logs”Settings → Diagnostics → Export diagnostics saves a private JSON bundle for review and sharing. The CLI provides the same export even when Desktop cannot open or the vault is sealed:
factorseal diagnosticsfactorseal diagnostics --output factorseal-diagnostics.jsonThe first command prints the storage directory. Reports live under diagnostics
in Factorseal’s state directory on Linux, or its cache directory on macOS and
Windows, outside the vault root. Set
FACTORSEAL_DIAGNOSTICS_DIR to use another location. Automatic submission requires
a configured Sentry DSN, as described below. Report an issue in the footer, or in Settings under Diagnostics once
the vault is unsealed, opens a form for describing what happened, what was expected, and
steps to reproduce. A nonempty description (up to 4,000 characters)
is required. Send report submits the description with the current Desktop
diagnostic log without requiring a crash; Cancel sends nothing. It reports successful delivery only after Sentry
acknowledges receipt; offline or delayed submissions remain queued for retry.
Desktop, CLI, and vault workers record their version, OS, architecture, PID,
startup time, lifecycle operations, and outcomes. Unlock and storage timings
are kept in a 128-event memory buffer and flushed with lifecycle events, normal
exit, or a Rust panic. This works without enabling FACTORSEAL_TIMINGS and avoids
disk writes on routine timing events. Supervised worker exits include the child
PID, exit code, and Unix signal, so the worker’s report can be correlated with
Desktop’s log.
Rust panics on any thread create a separate report with the recent log, source location, and a forced backtrace. Up to 20 recent session snapshots and 20 panic/worker-failure/manual-issue reports are retained independently, with a 256 KiB limit per file. New files and exports use owner-only permissions on Unix and Windows. Retention runs when a report is written. Deleting the diagnostics directory clears local history.
Automatic diagnostics exclude secret values, vault contents, arguments, environment variables, raw error strings, thread names, and panic payloads. They do not collect memory dumps or redirect stderr. Backtraces may contain build-time source paths, so review the export before sharing it. Release builds retain line tables; packages must retain debug symbols for useful source locations. Linux Nix packages compress the debug sections with zlib to reduce executable authentication time while preserving backtrace source locations. Descriptions entered in the issue form are sent as written and retained with queued reports for retries; do not include passwords or secret values. Drafts stay in memory until submitted.
Native faults, aborts, out-of-memory termination, forced kills, and power loss
cannot run the Rust panic hook. They leave the last persisted session snapshot;
Desktop also records an abnormal worker exit when it can observe one. A snapshot
marked running can belong to a live process or one that exited without cleanup
and is not, by itself, proof of a crash. There is no native crash stack or dump
capture. Reporting is best effort if storage becomes unavailable.
Automatic Sentry submission
Section titled “Automatic Sentry submission”Only the primary Desktop process performs HTTP delivery. The CLI, agent, and
vault worker do not link the Sentry/HTTP delivery code. Desktop submits its own
panic and abnormal-worker-exit reports, plus panic reports saved by Desktop’s
CLI worker. The footer bug button also submits an explicit snapshot of the
current Desktop log and the user’s description as a “User-reported issue”,
without a crash exception. The description appears in Sentry’s additional data
as issue_description and is excluded from unrelated crash events.
Unrequested normal session logs and unrelated CLI/agent reports are excluded.
For development, set the runtime configuration before starting Desktop:
SENTRY_DSN='<your-project-dsn>' SENTRY_ENVIRONMENT=development devenv shell cargo run -p factorseal-desktopRelease builds embed FactorSeal’s public project DSN from sentry-dsn.txt by
default. This covers Cargo release builds on every desktop platform and the Nix
Desktop package. Debug builds stay local unless explicitly configured.
Release builders can override the embedded DSN and environment:
FACTORSEAL_SENTRY_DSN='<your-project-dsn>' FACTORSEAL_SENTRY_ENVIRONMENT=production devenv shell cargo build --release -p factorseal-desktopThe Nix Desktop derivation accepts sentryDsn and sentryEnvironment override
arguments for the same purpose. A runtime SENTRY_DSN overrides the embedded
value; setting it to an empty string disables submission. An empty build-time
FACTORSEAL_SENTRY_DSN (or Nix sentryDsn = "") also disables the default.
Runtime SENTRY_ENVIRONMENT overrides
FACTORSEAL_SENTRY_ENVIRONMENT; otherwise it defaults to development for debug
builds and production for release builds. Environment labels support letters,
numbers, hyphens, and underscores, up to 64 characters. Invalid configuration
leaves local reporting available and produces a generic startup error. No
Sentry authentication token belongs in the application. The public project DSN
is intended to be embedded in distributed applications; users of release builds
should not need to configure it themselves.
With a valid HTTPS DSN, automatic submission is on by default. Settings → Diagnostics → Automatically send crash reports can pause and resume delivery. Turning it off prevents subsequent automatic crash requests; an already-running request may finish. Explicit submissions through the bug button still send and retry while this switch is off. Local recording continues, and pending crash reports can be submitted when automatic submission is enabled again. Configuring Sentry for the first time (or changing projects) sets a timestamp boundary: older local-only history is not uploaded.
The background uploader checks for incidents every five seconds. A Desktop
panic that terminates the process is submitted on the next launch. Failed
requests remain pending across restarts, subject to the existing 20-incident
retention limit. A private sentry-delivery.json file records the target,
initial timestamp boundary, accepted event IDs, and the next retry time.
Delivery is acknowledged only for successful HTTP responses. Requests time out
after ten seconds, redirects are rejected, and failures back off for at least
60 seconds while respecting Sentry quota delays and numeric Retry-After values.
Retries keep the same Sentry event ID, including if an acknowledgement could not
be saved locally. The uploader never waits inside the panic hook or key-owner
shutdown path.
To check a real Sentry project, explicitly run the ignored integration test:
SENTRY_DSN='<your-project-dsn>' devenv shell cargo test -p factorseal-desktop live_sentry_submission -- --ignored --nocaptureThis sends two events under integration-test: a manual issue while automatic
reporting is off, and a controlled panic recovered by a fresh process. It uses a
temporary diagnostics directory and requires an HTTP acknowledgement for each
event. Normal test runs skip it. Confirm the events and breadcrumbs in Sentry’s
project view to verify processing after ingestion.
Sentry events contain version-based release metadata, component/OS/architecture tags, parsed Rust exception frames, and recent operation logs as breadcrumbs. Absolute source paths are removed from submitted frames. Hostnames, user identity, environment variables, command arguments, raw panic payloads, and raw log/error strings are not captured. Sentry’s default integrations are disabled; its SDK protocol types construct the envelopes, and an acknowledged HTTP transport handles durable delivery. The local report remains available after a successful submission. Native crash-stack capture is still outside this path.