Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ jobs:
package_json_file: crates/app/ui/package.json
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
node-version-file: crates/app/ui/.node-version
cache: pnpm
cache-dependency-path: crates/app/ui/pnpm-lock.yaml

Expand Down Expand Up @@ -202,7 +202,7 @@ jobs:
package_json_file: crates/app/ui/package.json
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
node-version-file: crates/app/ui/.node-version
cache: pnpm
cache-dependency-path: |
crates/app/ui/pnpm-lock.yaml
Expand Down
473 changes: 473 additions & 0 deletions .github/workflows/release.yml

Large diffs are not rendered by default.

40 changes: 40 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Changelog

All notable changes to Keyrust are documented in this file. The format is based on
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
[Semantic Versioning](https://semver.org/).

## [Unreleased]

## [0.1.0]

The first release: a minimal KeePass client for Linux, Windows and macOS. Alpha software, not
audited: keep backups of your database.

### Added

- Create, open and save KDBX 4 databases protected by a master password; new databases use
Argon2id calibrated to about one second.
- KDBX 3.1 and 4.0 files open normally and are converted to KDBX 4.1 on the first save, with a
notice when they are opened.
- Nested groups, entries with title, username, password, URL and notes, entry history and a
recycle bin with restore. Custom fields, attachments and history written by other clients are
preserved.
- Instant search over titles, usernames and URLs.
- Password generator with a strength estimate.
- Clipboard copy from the Rust process, cleared after a delay, on lock and on exit.
- Auto-lock on inactivity, screen lock, sleep and (optionally) minimize.
- Atomic saves with detection of changes made by another app (*Reload* or *Keep mine*).
- Database settings: name, cipher, key-derivation parameters, recycle bin, master password.
- Full keyboard use, a command palette and a shortcuts panel; accessibility checked in CI.

### Distribution

- Installers for Windows (NSIS and MSI), Linux (`.deb` and AppImage) and macOS (universal
`.dmg`), with SHA-256 checksums signed with Sigstore cosign. See
[Verifying releases](https://github.com/downlevel/keyrust/blob/main/SECURITY.md#verifying-releases).
- The installers are not code-signed for Windows or macOS: SmartScreen and Gatekeeper warn before
the first launch (see the [README](https://github.com/downlevel/keyrust/blob/main/README.md#download)).

[Unreleased]: https://github.com/downlevel/keyrust/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/downlevel/keyrust/releases/tag/v0.1.0
6 changes: 3 additions & 3 deletions Cargo.lock

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

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ exclude = ["fuzz"]
default-members = ["crates/core"]

[workspace.package]
version = "0.0.1"
version = "0.1.0"
edition = "2024"
rust-version = "1.99"
license = "GPL-3.0-or-later"
Expand Down
22 changes: 21 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,25 @@ reference for compatibility. The comparison below is as of KeePassXC 2.7.
If you need any of the features Keyrust lacks, KeePassXC is the right choice, and your database
works in both.

## Download

Installers are on the [Releases page](https://github.com/downlevel/keyrust/releases):

| System | File |
|---|---|
| Windows 10 and 11 | `Keyrust_X.Y.Z_x64-setup.exe` (or the `.msi`, for managed deployment) |
| macOS, Intel and Apple Silicon | `Keyrust_X.Y.Z_universal.dmg` |
| Debian, Ubuntu and derivatives | `Keyrust_X.Y.Z_amd64.deb` |
| Other Linux distributions (x86-64) | `Keyrust_X.Y.Z_amd64.AppImage` |

Check your download as described in [Verifying releases](SECURITY.md#verifying-releases).

The installers are not code-signed for Windows or macOS yet (the release notes say when they are).
Windows SmartScreen shows *Windows protected your PC*: choose *More info* → *Run anyway*. macOS
refuses to open the app the first time: open *System Settings → Privacy & Security* and choose
*Open Anyway*. Some corporate computers do not allow unsigned software at all; there, build from
source (below) or ask your administrator.

## Building

Prerequisites for each OS are in [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). In short:
Expand Down Expand Up @@ -151,7 +170,8 @@ on Linux. See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

- [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)
- [Roadmap](docs/TASKS.md) · [Development guide](docs/DEVELOPMENT.md) · [Releasing](docs/RELEASING.md)
· [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
- [Security policy and threat model](SECURITY.md)

## License
Expand Down
58 changes: 53 additions & 5 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ reporters are credited unless they prefer otherwise.

| Version | Supported |
|---|---|
| `0.1.x` | ✅ once released |
| `main` | ✅ best effort, until `0.1.0` is released |
| `0.1.x` | ✅ |
| `main` | ✅ best effort |
| anything else | ❌ |

## Scope
Expand Down Expand Up @@ -226,6 +226,54 @@ production CSP.

## Verifying releases

Starting with v0.1.0, release artifacts will be published with SHA-256 checksums and signatures,
and this section will explain how to verify them. Until then, build from source
([docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)).
Every release on the [Releases page](https://github.com/downlevel/keyrust/releases) carries, next
to the installers:

- `SHA256SUMS`: the SHA-256 of every installer;
- `SHA256SUMS.sigstore.json`: a [Sigstore cosign](https://docs.sigstore.dev/cosign/) signature of
`SHA256SUMS`. It is *keyless*: instead of a long-lived key, it binds the file to the GitHub
Actions run of this repository's release workflow for that tag, and is recorded in the public
Rekor transparency log.

Verifying takes two steps: the signature proves that `SHA256SUMS` was produced by Keyrust's release
workflow, and the checksum proves that your installer is the one listed there.

**1. Check the signature** (needs [cosign](https://docs.sigstore.dev/cosign/system_config/installation/) 3
or later; replace `v0.1.0` with the release you downloaded):

```sh
cosign verify-blob SHA256SUMS \
--bundle SHA256SUMS.sigstore.json \
--certificate-identity "https://github.com/downlevel/keyrust/.github/workflows/release.yml@refs/tags/v0.1.0" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
```

It must print `Verified OK`. Any other identity means the file was not signed by a Keyrust release.

**2. Check your installer** against its line of `SHA256SUMS` (you need only the installer you
downloaded, not all of them):

```sh
# Linux
grep ' Keyrust_0.1.0_amd64.deb$' SHA256SUMS | sha256sum -c -
# macOS
grep ' Keyrust_0.1.0_universal.dmg$' SHA256SUMS | shasum -a 256 -c -
```

```powershell
# Windows (PowerShell)
$file = "Keyrust_0.1.0_x64-setup.exe"
$expected = (Select-String -Path SHA256SUMS -Pattern " $([regex]::Escape($file))$").Line.Split(" ")[0]
if ((Get-FileHash $file -Algorithm SHA256).Hash -eq $expected) { "OK" } else { "MISMATCH" }
```

The check must print `OK`.

**Code signing.** Installers are signed for Windows (Authenticode) or macOS (Developer ID and
notarization) only when the maintainer has configured a certificate; the *Build* section of each
release's notes says which. Without it, SmartScreen and Gatekeeper warn before the first launch,
and the cosign check above is the way to know the installer is genuine.

**Reproducibility.** Builds are reproducible on a best-effort basis; the release notes report
whether the Linux binary came out identical when built twice, and
[docs/RELEASING.md](docs/RELEASING.md#reproducing-a-build) explains how to rebuild it yourself.
8 changes: 8 additions & 0 deletions crates/app/tauri.release.macos-adhoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"$schema": "https://schema.tauri.app/config/2",
"bundle": {
"macOS": {
"signingIdentity": "-"
}
}
}
1 change: 1 addition & 0 deletions crates/app/ui/.node-version
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
24.22.0
2 changes: 1 addition & 1 deletion crates/app/ui/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "keyrust-ui",
"version": "0.0.1",
"version": "0.1.0",
"description": "Keyrust desktop UI (SvelteKit SPA rendered by Tauri)",
"type": "module",
"scripts": {
Expand Down
6 changes: 6 additions & 0 deletions crates/app/ui/svelte.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,12 @@ const config = {
// The app has a single route and keeps its screen in state; hash routing
// makes it independent of the page URL (Tauri and the web preview alike).
router: { type: "hash" },
// SvelteKit writes the version name into _app/version.json, which Tauri embeds in
// the binary. Its default is the build time: release builds take the commit time
// instead, so two builds of one commit produce the same bytes.
...(process.env.SOURCE_DATE_EPOCH && {
version: { name: process.env.SOURCE_DATE_EPOCH },
}),
},
};

Expand Down
23 changes: 14 additions & 9 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,13 +180,18 @@ per circa 1 s sulla macchina corrente. Cifratura AES-256 o ChaCha20 come previst

## Deploy
- **Ambienti**: solo locale (`cargo tauri dev`) + release.
- **Pipeline release** (su tag `v*`): matrice tre OS → `tauri build` → artefatti firmati → bozza GitHub Release
con checksum SHA-256 e firma (minisign/cosign) degli artefatti.
- **Firma codice OS**: Windows (Authenticode) e macOS (Developer ID + notarizzazione) richiedono certificati a pagamento:
vedi Domande aperte.
- **Build riproducibili**: `Cargo.lock` e `pnpm-lock.yaml` committati, toolchain fissata (`rust-toolchain.toml`),
`SOURCE_DATE_EPOCH`; obiettivo "best effort" documentato nel README.
- **Segreti CI**: chiavi di firma come GitHub secrets, usate solo nel job di release.
- **Pipeline release** (`.github/workflows/release.yml`, su tag `v*` di un commit di `main`): matrice tre OS →
`tauri build` (NSIS + MSI, deb + AppImage, dmg universale) → `SHA256SUMS` firmato con **cosign keyless** (identità
OIDC del workflow, log Rekor) → **bozza** di GitHub Release, pubblicata a mano. Ogni altro evento è un dry run
senza release. Procedura in [RELEASING.md](RELEASING.md), verifica per gli utenti in `SECURITY.md`.
- **Firma codice OS**: **opzionale**, si attiva solo se esistono i secret dell'OS (Windows: Azure Trusted Signing
via `signCommand`; macOS: Developer ID + notarizzazione con chiave API). Senza secret gli installer escono non
firmati (macOS con firma ad hoc) e le note di release lo dichiarano.
- **Build riproducibili** ("best effort"): toolchain, Node e pnpm fissati, lockfile con `--locked` /
`--frozen-lockfile`, `SOURCE_DATE_EPOCH` (anche come versione di SvelteKit), percorsi rimappati, nessuna cache;
il job `reproducibility` ricostruisce due volte il binario Linux e riporta l'esito nelle note, senza bloccare.
- **Segreti CI**: solo i secret di firma codice, letti solo su push di tag e solo nello step di build che li usa;
cosign non ne richiede.

## Testing & osservabilità
- **Unit test `core`**: generatore (distribuzione, vincoli), ricerca, gestione gruppi/voci, parametri KDF, errori.
Expand All @@ -210,8 +215,8 @@ per circa 1 s sulla macchina corrente. Cifratura AES-256 o ChaCha20 come previst
## Domande aperte
- **Supporto KDBX4 in scrittura di keepass-rs**: verificare maturità del feature flag di salvataggio KDBX4 e la
preservazione lossless di campi custom/allegati/cronologia; se insufficiente, contribuire upstream (bonus da portfolio).
- **Firma codice Windows/macOS**: acquistare certificati (Apple Developer, Authenticode) o pubblicare in V1 solo
artefatti firmati con minisign/cosign + checksum? DA DEFINIRE.
- ~~Firma codice Windows/macOS~~: decisa in Milestone 4b. Checksum firmati con cosign keyless sempre; firma codice OS
opzionale, attivata dai secret (nessun certificato acquistato per v0.1.0).
- ~~Libreria i18n~~: decisa in Milestone 1, Paraglide JS 2.
- ~~Conflitti di sync~~: decisa in Milestone 3, rilevamento e avviso (Reload / Keep mine), niente merge in V1.
- ~~Package manager frontend~~: pnpm.
9 changes: 6 additions & 3 deletions docs/DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ crates/app/tests/ Tauri security configuration tests
crates/app/ keyrust-app: Tauri 2 crate (tauri.conf.json, capabilities/, icons/)
crates/app/ui/ SvelteKit (SPA) + Svelte 5 + TypeScript + Tailwind + shadcn-svelte
tests/fixtures/ KeePassXC-created test databases (test data only)
scripts/ helper scripts (fixture generation)
scripts/ helper scripts (fixture generation, release checks)
fuzz/ cargo-fuzz targets (separate workspace, nightly)
.github/workflows/ CI
.github/workflows/ CI (ci.yml) and releases (release.yml)
docs/ PRD, architecture, design, roadmap, plans, spikes
```

Expand All @@ -26,7 +26,7 @@ without the Tauri system libraries. Build the app explicitly with `-p keyrust-ap
| Tool | Version | Notes |
|---|---|---|
| Rust (rustup) | pinned by `rust-toolchain.toml` (1.99.1) | rustup installs it on first use |
| Node.js | 22+ | |
| Node.js | 24 (CI and releases use the exact version in `crates/app/ui/.node-version`) | |
| pnpm | 12 (via `corepack enable pnpm`) | version pinned in `crates/app/ui/package.json` |
| KeePassXC | 2.7+ | provides `keepassxc-cli` for the compatibility tests |
| cargo-deny | latest | `cargo install cargo-deny --locked` |
Expand Down Expand Up @@ -147,6 +147,9 @@ Download it from the run page on GitHub (*Actions* → run → *Artifacts*). The
Windows SmartScreen and macOS Gatekeeper will warn because they are not signed (on macOS:
right click → Open).

Releases are built by a separate workflow, `.github/workflows/release.yml`: see
[RELEASING.md](RELEASING.md).

## Web preview

The UI runs in a plain browser too: outside Tauri it uses the demo vault and in-memory settings
Expand Down
Loading
Loading