3.9 KiB
Repository instructions
Architecture boundary
crates/storage owns all password-store behavior and all objects stored in or
derived from a password-store repository. This includes filesystem layout,
.gpg-id handling, GPG-compatible encryption and key handling, Git,
synchronization, conflict handling, entry parsing, password generation, OTP,
QR payloads, server/application identities, HTTPS Git credentials, and
secure-secret-storage orchestration. Git remotes are typed HTTPS or optional
SSH endpoints; reject local, helper, executable, and unknown transports before
entering Git transport code. Builds without the ssh feature must still parse
SSH endpoints and return a typed unsupported-transport error before connection
or repository mutation.
The CLI, Ratatui, Iced, Swift, SwiftUI, AutoFill, and watchOS code may collect input, invoke the Rust API, and present Rust-provided state. They must not duplicate storage rules, derive domain state from display strings, or directly read or mutate a password-store repository.
Application code must not launch external processes. Do not invoke pass,
git, gpg, shell commands, or helper executables. Use pure Rust libraries.
Use FFI only where an operating-system API has no feasible Rust interface,
such as Apple authentication and secure-storage APIs; keep domain decisions in
crates/storage.
Keep project crates free of unsafe Rust. Isolate any unavoidable future FFI
implementation in the smallest platform-specific module and document its
safety contract.
Compatibility
Compatibility means the upstream pass repository format and observable
behavior, including pass-otp; IronStorage must not introduce a competing
on-disk format. Prove new behavior with fixtures usable by both upstream tools
and crates/storage without executing those tools at application runtime.
Required checks
Run these from the repository root before committing:
cargo fmt --all -- --check
RUSTFLAGS="-D warnings" cargo check --workspace --all-targets
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
For Apple project changes, also run xcodegen generate from apple/ and build
the affected simulator targets.
Updating the Simulator app
Treat the booted simulator and its app container as persistent test state. To
update IronStorage, build for that simulator and install the new .app over
the existing installation with xcrun simctl install <device-udid> <app-path>.
Keep the same device UDID and bundle identifier.
Do not uninstall IronStorage, erase or recreate the simulator, reset its keychain, install app-data packages, or delete its app container during an app update. Those are destructive reset operations, not update steps, and can remove preferences, repositories, credentials, and biometric enrollment state.
Simulator biometric validation
For initial setup only, select Features > Face ID > Enrolled before enabling Biometric Unlock in the iPhone app. The user must then enable Biometric Unlock and enter the GPG passphrase once so the protected passphrase is enrolled.
For normal validation, do not toggle Enrolled again. Tap the entry's Unlock control first so an authentication request is active, then select Features > Face ID > Matching Face and verify the app changes from locked to unlocked. A matching face presented before Unlock does nothing. Use Non-matching Face to test rejection without changing enrollment.
Apple's biometryCurrentSet access control invalidates a protected Keychain
item when Face ID is re-enrolled. Clearing or toggling Enrolled is therefore
a destructive negative test, not part of the normal unlock sequence. Only do it
when the issue explicitly requires changed-enrollment coverage and the user is
available to enter the GPG passphrase again. When deliberately returning to a
manual baseline, disable Biometric Unlock in IronStorage while the protected
record is still valid, then clear Enrolled.