161 lines
6.8 KiB
Markdown
161 lines
6.8 KiB
Markdown
# IronStorage
|
|
|
|
IronStorage is a native client for
|
|
[`pass`](https://git.zx2c4.com/password-store/about/) and
|
|
[`pass-otp`](https://github.com/tadfisher/pass-otp).
|
|
|
|
`pass` stores entries as GPG-encrypted `.gpg` files in an ordinary directory
|
|
tree (normally `~/.password-store`), selects one or more recipients through
|
|
`.gpg-id` files, and can track changes in Git. IronStorage keeps that format
|
|
and the first-party `pass` command behavior. `pass-otp` compatibility adds
|
|
`otpauth://` secrets, OTP generation, and QR import/export.
|
|
|
|
The compatibility target includes init, list/show, find/grep, insert/edit,
|
|
generate, remove, move/copy, and Git-backed commit and synchronization flows.
|
|
Remote synchronization is HTTPS-only and uses server/application credentials
|
|
kept in the operating system's secure store.
|
|
|
|
The central `ironstorage` Rust crate owns repository access, Git,
|
|
GPG-compatible encryption and key handling, entries, OTP, synchronization,
|
|
and platform-secure credential orchestration. Applications are presentation
|
|
and interaction adapters only. Runtime subprocesses—including `pass`, `git`,
|
|
and `gpg`—are forbidden; compatibility is implemented in Rust.
|
|
|
|
Candidate libraries and the pending project-license decision are tracked in
|
|
[`DEPENDENCIES.md`](DEPENDENCIES.md).
|
|
|
|
The shared TOML schema, path rules, editor precedence, and HTTPS remote format
|
|
are documented in [`docs/configuration.md`](docs/configuration.md).
|
|
Embedded Git, HTTPS synchronization, merge behavior, and commit signing are
|
|
documented in [`docs/git-synchronization.md`](docs/git-synchronization.md).
|
|
Native credential storage, opaque secret references, user-presence policy, and
|
|
bounded caching are documented in
|
|
[`docs/secure-secret-storage.md`](docs/secure-secret-storage.md).
|
|
Shared authentication generations, explicit user activity, inactivity expiry,
|
|
and relock cleanup are documented in
|
|
[`docs/authentication-leases.md`](docs/authentication-leases.md).
|
|
Clipboard cleanup/race behavior and platform-neutral QR rendering are
|
|
documented in [`docs/presentation.md`](docs/presentation.md).
|
|
Pass-OTP URI compatibility, RFC code generation, and atomic HOTP counters are
|
|
documented in [`docs/otp.md`](docs/otp.md).
|
|
The complete command matrix, shell completion interface, deliberate no-process
|
|
differences, and executable security audit are documented in
|
|
[`docs/cli-parity.md`](docs/cli-parity.md).
|
|
The Mutt-inspired terminal interaction model, default keys, and complete TUI
|
|
operation matrix are documented in [`apps/tui/COMMANDS.md`](apps/tui/COMMANDS.md).
|
|
Desktop parity, native platform smoke checks, accessibility limitations, and
|
|
the executable security audit are documented in
|
|
[`docs/desktop-audit.md`](docs/desktop-audit.md).
|
|
Lossless structured entry fields, semantic/sensitivity metadata, conflict
|
|
tokens, and atomic frontend saves are documented in
|
|
[`docs/entry-documents.md`](docs/entry-documents.md).
|
|
The capability-scoped password-store layout and atomic mutation guarantees are
|
|
documented in [`docs/repository-core.md`](docs/repository-core.md).
|
|
The embedded OpenPGP backend, exported-key model, secret-provider boundary, and
|
|
GnuPG compatibility evidence are documented in
|
|
[`docs/cryptography.md`](docs/cryptography.md).
|
|
Hierarchical `.gpg-id` resolution, signed policies, selective reencryption, and
|
|
the rollback/commit contract are documented in
|
|
[`docs/recipient-policies.md`](docs/recipient-policies.md).
|
|
Typed list/show/find/decrypted-grep models and secret presentation selection are
|
|
documented in [`docs/read-domains.md`](docs/read-domains.md).
|
|
Insert modes, concurrency-safe edit sessions, and the secure CLI editor-file
|
|
boundary are documented in [`docs/write-domains.md`](docs/write-domains.md).
|
|
Unbiased password generation, character-set validation, in-place replacement,
|
|
and presentation actions are documented in
|
|
[`docs/password-generation.md`](docs/password-generation.md).
|
|
Rollback-safe remove, move, and copy transactions, destination rules, and
|
|
selective subtree reencryption are documented in
|
|
[`docs/tree-mutations.md`](docs/tree-mutations.md).
|
|
|
|
## Project layout
|
|
|
|
```text
|
|
crates/storage password-store domain and storage library
|
|
crates/apple UniFFI boundary for Apple presentation code
|
|
apps/cli pass-compatible command-line frontend
|
|
apps/tui Ratatui frontend
|
|
apps/desktop Iced desktop frontend for macOS, Windows, and Linux
|
|
apple/ iPhone, AutoFill, and watchOS presentation targets
|
|
```
|
|
|
|
The Apple project is generated with XcodeGen:
|
|
|
|
```sh
|
|
cd apple
|
|
xcodegen generate
|
|
```
|
|
|
|
## Building
|
|
|
|
Install a stable Rust toolchain satisfying the workspace manifest (Rust 1.92
|
|
or newer) before building. Commands below run from the repository root unless
|
|
they explicitly change directory. Cargo places debug artifacts in
|
|
`target/debug/` and optimized artifacts in `target/release/`.
|
|
|
|
Build every Rust crate and application in debug or release mode:
|
|
|
|
```sh
|
|
cargo build --workspace
|
|
cargo build --workspace --release
|
|
```
|
|
|
|
Build one frontend at a time:
|
|
|
|
```sh
|
|
# pass-compatible CLI: target/{debug,release}/ironstorage
|
|
cargo build --package ironstorage-cli
|
|
cargo build --package ironstorage-cli --release
|
|
|
|
# Ratatui terminal UI: target/{debug,release}/ironstorage-tui
|
|
cargo build --package ironstorage-tui
|
|
cargo build --package ironstorage-tui --release
|
|
|
|
# Iced desktop UI: target/{debug,release}/ironstorage-desktop
|
|
cargo build --package ironstorage-desktop
|
|
cargo build --package ironstorage-desktop --release
|
|
```
|
|
|
|
On macOS, install `cargo-packager` once, then build an application bundle or
|
|
install the release bundle directly into `~/Applications`:
|
|
|
|
```sh
|
|
cargo install cargo-packager --locked
|
|
cargo bundle-macos
|
|
cargo bundle-macos --out-dir "$HOME/Applications"
|
|
```
|
|
|
|
The first bundle command writes `target/release/IronStorage.app`. The install
|
|
form replaces `~/Applications/IronStorage.app` with the freshly built bundle.
|
|
|
|
Build only the shared storage library or the Rust Apple bridge:
|
|
|
|
```sh
|
|
cargo build --package ironstorage --lib
|
|
cargo build --package ironstorage --lib --release
|
|
cargo build --package ironstorage-apple --lib
|
|
cargo build --package ironstorage-apple --lib --release
|
|
```
|
|
|
|
The iPhone application, AutoFill extension, and watchOS companion require
|
|
macOS, Xcode, XcodeGen, and the Rust Apple targets used by
|
|
`apple/build_rust_core.bash`. Generate the Xcode project after cloning or after
|
|
changing `apple/project.yml`, then build the simulator configuration. The Xcode
|
|
pre-build phase selects the matching Rust debug or release profile.
|
|
|
|
```sh
|
|
cd apple
|
|
xcodegen generate
|
|
|
|
# Debug simulator build
|
|
xcodebuild -project IronStorage.xcodeproj -scheme IronStorage \
|
|
-configuration Debug -sdk iphonesimulator build CODE_SIGNING_ALLOWED=NO
|
|
|
|
# Release simulator build
|
|
xcodebuild -project IronStorage.xcodeproj -scheme IronStorage \
|
|
-configuration Release -sdk iphonesimulator build CODE_SIGNING_ALLOWED=NO
|
|
```
|
|
|
|
For a signed device or archive build, select the desired application target in
|
|
Xcode and configure the development team and signing identities there.
|