Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
6229bfe
docs: Milestone 4a plan — accessibility audit, e2e smoke, final SECUR…
downlevel Oct 28, 2026
2fc628e
fix(core): the reported KDBX version changes only once the file is re…
downlevel Oct 29, 2026
6a5e1a4
feat(ui): accessibility audit with axe and Playwright, KDBX conversio…
downlevel Oct 29, 2026
aad5931
test: Tauri e2e smoke test in CI, README screenshots
downlevel Oct 29, 2026
3674b65
docs: final SECURITY.md and README, accessibility report, PRD decisions
downlevel Oct 29, 2026
ddf656d
test: audit the settled page, report the e2e log as a public annotation
downlevel Oct 29, 2026
d243e30
test: tolerate cancelled animations; run the e2e test with a session bus
downlevel Oct 29, 2026
1cb1f79
ci: report only test results and app logs from a failed e2e run
downlevel Oct 29, 2026
2bf0989
test(e2e): report what the webview shows when a step fails
downlevel Oct 29, 2026
b768045
test(e2e): report whether SvelteKit's bootstrap ran and its imports load
downlevel Oct 29, 2026
4ed52f7
fix(app): load the window at "/" so the UI starts on Linux and macOS
downlevel Oct 29, 2026
ed7ebc2
test(e2e): read element text from the DOM
downlevel Oct 29, 2026
2ef1eef
docs: 4a review log — CI findings and the Linux startup fix
downlevel Oct 29, 2026
e63f65e
fix: 4a inspection — version after a non-durable save, Home/End witho…
downlevel Oct 29, 2026
863c07b
docs: 4a review log — third inspection
downlevel Oct 29, 2026
5c20eca
fix: 4a third inspection — verify the KDBX 3.1 HeaderHash, guard the …
downlevel Oct 29, 2026
0dc6afc
fix(core): read the KDBX 3 HeaderHash as XML (4a inspection M4A-R11)
downlevel Oct 29, 2026
12e7848
docs: 4a review log — final targeted inspection approved
downlevel Oct 29, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 101 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,23 @@ jobs:
# tauri::generate_context! needs the built frontend to exist.
pnpm build

# Accessibility audit (axe, keyboard, focus, reduced motion) on the demo
# build in Chromium: the same on every OS, so it runs once.
- name: Accessibility audit (Linux)
if: runner.os == 'Linux'
working-directory: crates/app/ui
run: |
pnpm exec playwright install --with-deps chromium
pnpm test:web
- name: Upload the accessibility report
if: failure() && runner.os == 'Linux'
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: a11y-report
path: crates/app/ui/test-results/
retention-days: 7
if-no-files-found: ignore

- name: Clippy (workspace)
run: cargo clippy --workspace --all-targets -- -D warnings
- name: Test (app)
Expand All @@ -157,6 +174,90 @@ jobs:
retention-days: 7
if-no-files-found: error

# The real app (Rust backend, IPC, WebKitGTK) on copies of the KeePassXC
# fixtures, driven through tauri-driver. Runs on every event: it verifies
# branches too, not only pull requests.
e2e:
name: e2e (ubuntu-24.04)
runs-on: ubuntu-24.04
timeout-minutes: 45
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Install the Rust toolchain from rust-toolchain.toml
run: rustup toolchain install
- name: Install Tauri prerequisites, WebKitWebDriver, Xvfb and KeePassXC
run: |
sudo apt-get update
sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev librsvg2-dev \
libayatana-appindicator3-dev libxdo-dev libssl-dev \
webkit2gtk-driver xvfb dbus
sudo apt-get install -y --no-install-recommends keepassxc
- uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
with:
key: e2e
- name: Install tauri-driver
run: cargo install tauri-driver --locked --version 2.1.0
- uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
with:
package_json_file: crates/app/ui/package.json
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
cache: pnpm
cache-dependency-path: |
crates/app/ui/pnpm-lock.yaml
crates/app/e2e/pnpm-lock.yaml
- name: Build the app (debug, no installer, unsigned)
working-directory: crates/app/ui
run: |
pnpm install --frozen-lockfile
pnpm tauri build --debug --no-bundle
- name: Smoke test
run: |
set -o pipefail
echo "KEYRUST_E2E_DIR=$RUNNER_TEMP/keyrust-e2e" >> "$GITHUB_ENV"
export KEYRUST_E2E_DIR="$RUNNER_TEMP/keyrust-e2e" KEYRUST_LOG=info
pnpm --dir crates/app/e2e install --frozen-lockfile
pnpm --dir crates/app/e2e check
# A session bus, as on a desktop: without one GTK waits ~25 s for the
# desktop portal before the window appears.
xvfb-run -a dbus-run-session -- pnpm --dir crates/app/e2e test 2>&1 |
tee "$RUNNER_TEMP/e2e.log"
# The file the real app saved is still a database KeePassXC reads, with
# the new title; the KDBX 3.1 copy was opened but never written.
- name: KeePassXC reads the saved file
run: |
printf '%s\n' keyrust-test-password |
keepassxc-cli show -q -a Title "$KEYRUST_E2E_DIR/vaults/keepassxc-rich.kdbx" \
"/Work/Dev/GitHub (e2e)" | tee "$RUNNER_TEMP/title.txt"
test "$(cat "$RUNNER_TEMP/title.txt")" = "GitHub (e2e)"
cmp "$KEYRUST_E2E_DIR/vaults/keepassxc-kdbx31.kdbx" tests/fixtures/keepassxc-kdbx31.kdbx
# Job logs need a login to read; annotations are public. The logs carry no
# field values (logging policy) and the fixture password is public.
- name: Report the end of the log as an annotation
if: failure()
run: |
if [ -f "$RUNNER_TEMP/e2e.log" ]; then
# Test results and app logs only, without the D-Bus and portal noise;
# an annotation holds about 4 KB.
clean=$(sed 's/\x1b\[[0-9;]*[A-Za-z]//g' "$RUNNER_TEMP/e2e.log")
{ grep -m 2 -E 'page (state|boot)' <<<"$clean" | cut -c 1-1200
grep -E '^\[(0-0|wry)|Error|keyrust_' <<<"$clean" |
grep -vE 'WARNING|dbus-daemon|page (state|boot)|^\[0-0\] *$' | tail -c 1500
} |
python3 -c "import sys; print('::error title=e2e log (filtered)::' + sys.stdin.read().replace('%','%25').replace('\r','').replace('\n','%0A'))"
fi
- name: Upload logs and screenshots
if: failure()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: e2e-logs
path: |
${{ runner.temp }}/e2e.log
${{ runner.temp }}/keyrust-e2e/artifacts/
retention-days: 7
if-no-files-found: ignore

deny:
name: cargo deny
runs-on: ubuntu-24.04
Expand Down
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

173 changes: 133 additions & 40 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,62 +2,155 @@

[![CI](https://github.com/downlevel/keyrust/actions/workflows/ci.yml/badge.svg)](https://github.com/downlevel/keyrust/actions/workflows/ci.yml)

**A modern KeePass client, written in Rust.**
**A calm, minimal KeePass client for the desktop, written in Rust.**

Keyrust is an open source password manager for Linux, Windows and macOS. It reads and writes the
standard **KDBX** format, so your database stays a plain file you own: open it with KeePassXC,
KeePassDX (Android) or Strongbox (iOS), and sync it with Syncthing, Nextcloud or Dropbox. No
account, no cloud, no telemetry, no network access.

> **Status: alpha, not audited.** Keyrust opens and saves real databases and is tested against
> KeePassXC in CI, but it is young software. Keep backups of your database.

![The Keyrust vault: groups, entries and the details of an entry](docs/screenshots/vault.png)

<p>
<img src="docs/screenshots/unlock.png" alt="Unlock screen with recent databases" width="32%">
<img src="docs/screenshots/editor-generator.png" alt="Entry editor with the password generator" width="32%">
<img src="docs/screenshots/settings.png" alt="Settings: clipboard, auto-lock and generator" width="32%">
</p>

The screenshots show the built-in demo data.

## Features

- Create, open and save KDBX databases protected by a master password. New databases use KDBX 4
with Argon2id, calibrated to about one second on your computer.
- Groups (nested) and entries with title, username, password, URL and notes; entry history; a
recycle bin with restore.
- Instant search over titles, usernames and URLs (never passwords).
- Password generator using the system's secure random source, with a strength estimate.
- Copy to the clipboard from the Rust process, cleared automatically after a delay, on lock and on
exit.
- Auto-lock on inactivity, when the screen locks, when the computer sleeps, and optionally when
the window is minimized.
- Safe saving: atomic writes, and detection of changes made by another app before saving
(*Reload* or *Keep mine*). A write that lands in the instant between the last check and the
save cannot be detected ([details](SECURITY.md#what-keyrust-does-not-protect-against)).
- Database settings: name, cipher, key-derivation parameters, recycle bin, master password.
- Everything works from the keyboard, with a command palette (Ctrl+K) and a shortcuts panel.
- Accessibility checked in CI: WCAG 2.1 AA contrast, visible focus, screen-reader roles and
announcements, reduced motion ([details](docs/ACCESSIBILITY.md)).

### Not in this version

Auto-type, browser integration, keyfiles, hardware keys, TOTP codes, import from other password
managers, attachments in the UI (existing attachments are preserved), a dark theme, and merging
sync conflicts. Some are planned ([roadmap](docs/TASKS.md)); auto-type, a browser extension and a
sync server of our own are not ([product requirements](docs/PRD.md)).

## Security in one minute

- The file is encrypted and authenticated (KDBX4). Its safety rests on your master password.
- Key-derivation parameters are checked before the key is derived, so a file tampered with by a
sync provider cannot freeze your computer.
- Passwords are not in the entry list, the details or search results, and copying happens in Rust.
The webview sees a password only while you edit, reveal or generate it.
- The vault locks itself, from the Rust process, even if the UI hangs.
- Memory-safe Rust, `unsafe` confined to a few operating-system calls, no hand-written
cryptography, audited dependencies, fuzzing of the file parser.
- Not protected: malware on an unlocked computer, a weak master password, a sync provider deleting
or rolling back your file.

The full threat model is in [SECURITY.md](SECURITY.md).

Keyrust is an open source desktop password manager for Linux, Windows and macOS. It reads and
writes the standard **KDBX4** format, so your database stays a plain file you own: open it with
KeePassXC, KeePassDX (Android) or Strongbox (iOS), and sync it with Syncthing, Nextcloud or
Dropbox. No account, no cloud, no telemetry.

> **Status: pre-alpha.** Milestone 2 (UI) runs on demo data; opening real databases arrives in Milestone 3.
> Do not store real passwords in it.

## Planned features (v1)

- Create, open and save KDBX4 databases protected by a master password (Argon2id).
- Entries (title, username, password, URL, notes) organised in groups; recycle bin.
- Instant search, configurable password generator.
- Copy to clipboard with automatic clearing; auto-lock on inactivity, screen lock, sleep and
(optionally) minimize.
- Two-way compatibility with KeePassXC, verified by automated tests.
- Full keyboard navigation.
## Architecture

Out of scope: auto-type, browser extension, a sync server of our own. See [docs/PRD.md](docs/PRD.md).
```mermaid
flowchart LR
subgraph rust["Keyrust process (Rust)"]
core["crates/core<br/>vault, KDBX, crypto"]
app["crates/app<br/>Tauri shell, IPC commands,<br/>clipboard, auto-lock"]
os["crates/os<br/>screen lock, sleep"]
end
ui["Webview<br/>crates/app/ui (Svelte)"]
file[("KDBX file")]
clip["Clipboard"]
sys["Operating system"]
ui <-->|IPC| app
app --> core
app --> os
core <--> file
app --> clip
os <--> sys
```

## Why another KeePass client?
`crates/core` is the vault and the file format, with no UI dependency, built on keepass-rs and
RustCrypto. `crates/app` is the Tauri 2 desktop shell: the only way the UI reaches the vault is a
fixed list of IPC commands. `crates/os` detects screen lock and sleep, and is the only crate with
`unsafe` code. Details are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## Compatibility

- **KeePassXC:** tested automatically both ways in CI on Linux, Windows and macOS. Keyrust opens
files made by KeePassXC and saves them without losing custom fields, attachments, history or
anything it does not display, and KeePassXC reads every file Keyrust writes.
- **KeePassDX and Strongbox:** use the same format, but have not been verified by hand yet.
- **KDBX 3.1 and 4.0:** open normally; the first save converts the file to KDBX 4.1, and Keyrust
tells you so when you open it. Very old clients that only read KDBX 3.1 cannot open the
converted file.

## Keyrust and KeePassXC

[KeePassXC](https://keepassxc.org) is mature and full-featured, and Keyrust uses it as the
reference for compatibility. The comparison below is as of KeePassXC 2.7.

| | KeePassXC 2.7 | Keyrust 0.1 |
|---|---|---|
| KDBX 4 format | ✅ | ✅ |
| Auto-type | ✅ | ❌ |
| Browser integration | ✅ | ❌ |
| Keyfiles, YubiKey | ✅ | ❌ |
| TOTP codes | ✅ | ❌ |
| Import (CSV, 1Password, Bitwarden…) | ✅ | ❌ |
| KeeShare, SSH agent | ✅ | ❌ |
| Interface | Feature-rich | Minimal, three columns, keyboard-first |
| Language | C++ | Rust (memory-safe) |
| Where passwords are held | One C++ / Qt process | The Rust process; the UI webview only while you edit, reveal or generate one |
| Compatibility with KeePassXC | — | Verified in CI against `keepassxc-cli` |

If you need any of the features Keyrust lacks, KeePassXC is the right choice, and your database
works in both.

KeePassXC is excellent and battle-tested; Keyrust aims at a calmer, more minimal everyday
experience on top of the same file format, with memory-safe code and visible engineering
quality: a written threat model ([SECURITY.md](SECURITY.md)), compatibility tests against
KeePassXC itself, fuzzing and CI on three operating systems.
## Building

## Architecture
Prerequisites for each OS are in [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). In short:

```sh
cd crates/app/ui
pnpm install
pnpm tauri dev # run the desktop app
pnpm tauri build # build an installer for this OS
```
crates/core vault, crypto and KDBX4 format (no UI dependencies) — keepass-rs, RustCrypto
crates/app Tauri 2 desktop shell + SvelteKit / Svelte 5 UI (crates/app/ui)
crates/os screen lock and suspend detection; the only crate with (FFI) unsafe code
```

Secrets stay on the Rust side: the webview only receives what it displays, and copying a
password to the clipboard happens in Rust. Details in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

The KDBX4 compatibility of keepass-rs with KeePassXC has been verified in
[spike 0001](docs/spikes/0001-keepass-rs-kdbx4.md).
`pnpm dev` alone runs the UI in a browser on demo data (password `secret`).

## Building

See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for prerequisites on each OS. In short:
## Testing

```sh
cargo test -p keyrust-core # core tests (KeePassXC compatibility needs keepassxc-cli)
cd crates/app/ui && pnpm install
pnpm tauri dev # run the desktop app
cargo test -p keyrust-core # core; KeePassXC compatibility needs keepassxc-cli
cd crates/app/ui
pnpm test # UI unit and component tests (Vitest)
pnpm test:web # accessibility audit in Chromium (Playwright + axe)
```

The end-to-end test of the real app (`crates/app/e2e`, WebdriverIO and tauri-driver) runs in CI
on Linux. See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

## Documentation

- [Product requirements](docs/PRD.md) · [Architecture](docs/ARCHITECTURE.md) · [Design](docs/DESIGN.md)
· [Accessibility](docs/ACCESSIBILITY.md)
- [Roadmap](docs/TASKS.md) · [Development guide](docs/DEVELOPMENT.md) · [Contributing](CONTRIBUTING.md)
- [Security policy and threat model](SECURITY.md)

Expand Down
Loading
Loading