PasskeyHome

A native macOS SwiftUI app for managing passkeys stored in KeePassXC (.kdbx) vaults, built on KDBXKit.

Passkeys that KeePassXC's browser extension saves land as protected KPEX_PASSKEY_* custom attributes on vault entries, paired with KPXC_BROWSER_* database-level custom data. PasskeyHome reads (and writes) those attributes directly via KDBXKit — no KeePassXC CLI or GUI required — and presents them in a native macOS UI with onboarding, diagnostics, import, and export.

Status

Early spike. The read + write path, onboarding, and pairing detection all build and run; see spike-2-findings.md for the detailed session write-up.

Area	State
KDBX read (Argon2id / AES-KDF, ChaCha20 / AES256CBC)	✅
KPEX_PASSKEY_* attribute read	✅
KPXC_BROWSER_* pairing detection	✅
KDBX write (protected attributes)	✅
SwiftUI app: onboarding → unlock → passkey list	✅
Import / export envelope	🚧
Packaging (.app + DMG)	✅ (self-signed, see scripts/package.sh)

Requirements

• macOS 15+ (Sequohia / v15 SDK)
• Xcode 16+ / Swift 6+
• KeePassXC (for vault creation + browser-extension pairing)

Targets

This is a single SwiftPM package with three executables:

Target	What it does
PasskeyHome	SwiftUI macOS app. Empty state → onboarding → open .kdbx → unlock → passkey list with pairing banner.
passkeyhome-verify	Headless: runs the app's exact KDBX read + passkey detection + pairing detection against a vault. Exits non-zero on zero passkeys.
passkeyhome-fixup	Writes KPEX_PASSKEY_* protected attributes + a KPXC_BROWSER_* pairing key using KDBXKit's writer. Seeds the test vault and proves the write path.

Build

swift build

Run the GUI app from the build output, or use the headless tools:

.build/debug/passkeyhome-verify Fixtures/test-vault.kdbx

Package as a .app + DMG

swift build -c release
scripts/package.sh
# → dist/PasskeyHome.app and dist/PasskeyHome.dmg

The bundle is self-signed and relocatable (all deps are system libs). On a target Mac, strip the quarantine attribute before first launch:

xattr -dr com.apple.quarantine /Applications/PasskeyHome.app

Layout

Sources/
  PasskeyHome/        SwiftUI app (views, theme, detection, backup health)
  PasskeyHomeCore/    Shared import/export envelope used by app + tools
  PasskeyHomeVerify/  Headless verify CLI
  PasskeyHomeFixup/   Fixture builder / write-path exerciser
scripts/package.sh   .app bundle + DMG packaging
Fixtures/            test-vault.kdbx (seeded by passkeyhome-fixup)
shots/               screenshots

License

MIT.