IronStorage/README.md

IronStorage

IronStorage is a native client for pass and 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 endpoints are typed in the storage crate as credential-free HTTPS or feature-gated SSH. HTTPS synchronization uses server/application credentials kept in the operating system's secure store; SSH transport dependencies and runtime are compiled only with the optional ssh Cargo feature. The standard CLI, TUI, and desktop applications enable it; the Apple bridge keeps it disabled unless an Apple target explicitly opts in.

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.

IronStorage is MIT licensed. Dependency licenses and the completed packaging review are tracked in DEPENDENCIES.md.

The shared TOML schema, path rules, editor precedence, and Git remote formats are documented in docs/configuration.md. Embedded Git, HTTPS synchronization, merge behavior, and commit signing are documented in docs/git-synchronization.md. The complete SSH lifecycle, failure, algorithm, dependency, target, and release matrix is documented in docs/ssh-transport-audit.md. Native credential storage, opaque secret references, user-presence policy, and bounded caching are documented in docs/secure-secret-storage.md. Shared authentication generations, explicit user activity, inactivity expiry, and relock cleanup are documented in docs/authentication-leases.md. Clipboard cleanup/race behavior and platform-neutral QR rendering are documented in docs/presentation.md. Pass-OTP URI compatibility, RFC code generation, and atomic HOTP counters are documented in 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. The Mutt-inspired terminal interaction model, default keys, and complete TUI operation matrix are documented in apps/tui/COMMANDS.md. Desktop parity, native platform smoke checks, accessibility limitations, and the executable security audit are documented in docs/desktop-audit.md. Lossless structured entry fields, semantic/sensitivity metadata, conflict tokens, and atomic frontend saves are documented in docs/entry-documents.md. The capability-scoped password-store layout and atomic mutation guarantees are documented in docs/repository-core.md. The embedded OpenPGP backend, exported-key model, secret-provider boundary, and GnuPG compatibility evidence are documented in docs/cryptography.md. Hierarchical .gpg-id resolution, signed policies, selective reencryption, and the rollback/commit contract are documented in docs/recipient-policies.md. Typed list/show/find/decrypted-grep models and secret presentation selection are documented in docs/read-domains.md. Insert modes, concurrency-safe edit sessions, and the secure CLI editor-file boundary are documented in docs/write-domains.md. Unbiased password generation, character-set validation, in-place replacement, and presentation actions are documented in docs/password-generation.md. Rollback-safe remove, move, and copy transactions, destination rules, and selective subtree reencryption are documented in docs/tree-mutations.md.

Project layout

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:

cd apple
xcodegen generate

Apple App Store metadata, archive verification, submission, and paired iPhone and Watch release checks are documented in apple/AppStore/DISTRIBUTION.md.

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:

cargo build --workspace
cargo build --workspace --release

Build one frontend at a time:

# 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:

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. The bundle contains the matching ironstorage CLI and ironstorage-tui binaries; Settings can install links to them in ~/.local/bin. All three bundled applications support configured HTTPS, ssh://, and scp-like SSH remotes through the same storage-owned transport selection.

Build only the shared storage library or the Rust Apple bridge:

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.

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.