revault_api 0.6.0-x86_64-linux → 0.6.1-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfcd043a5a42316cff6809578b64c34b7521a8d71457203d67aaef9d94145ba1
-  data.tar.gz: 34a972935e1f39b4bd2e15f14e76cb89b4b365456195065e20ffc33a449ab422
+  metadata.gz: 9e9fe90ab5a17bbc634ba15e586e966b62ffde7580d881fa9f79a1cf1fb0dc19
+  data.tar.gz: 751334f4c0e08b61c968cc4f1fe53b6b7db57d739ca099c7a271deb5214c5f57
 SHA512:
-  metadata.gz: '0428102837478dd8f6c3a7c7f253873ecc350e9d1d8db4791f908b8528fde66c846c77c0bd0e49af0b2de6a0c58ba341cc6148916d236cfc2b31d5e469f16b6a'
-  data.tar.gz: 3103052d7eb2a8ca5e532f56832295a7b1f3bd7bd860838e510719f9e047cd3810b4b403273c4fa947898e865aa4e49b865a17c478ae80e40b975114fc1f523e
+  metadata.gz: 560d7aa690ef3f82e3306c0ad32faddc4fe29b599017db7e165555d87206f2aeaac5e3217abe0f88419e21f9f2a24735b7e6eb0e58b30a1023f0971d69d8acf3
+  data.tar.gz: 14f4388923f182af38ae233b431a02b2bd73addf669a97d8a3d446bf7cb4832781e378a2d361979bb17fb2627f027604dbaf8fa0c6ae71cc4fa5227c21143b55

data/README.md

@@ -1,441 +1,158 @@
-# reVault
+# reVault for Ruby
 
 reVault is a fast, local toolkit for creating secure portable archives called
-Lockboxes. Each Lockbox is encrypted, compressed, and signed. It can store:
-
-* files and directory trees
-* file permissions and symbolic links
-* variables such as API keys
-* forms such as login details
+Lockboxes. Each Lockbox is encrypted, compressed, and signed. It can store
+files and directory trees, variables such as API keys, and forms such as login
+details.
 
 Lockboxes are easy to copy, share, and back up, and they do not require a
 hosted service. The engine is designed for speed and effective compression.
 Applications can read, write, and seek within stored files without extracting
-the archive, and recover data from partial corruption.
+the archive, and recover data from partial corruption. reVault provides a
+command line tool for everyday work and APIs for application code.
 
 Read the [reVault manual](https://docs.revault.onepub.dev/) for the quick start,
 core concepts, and security model.
 
-The [project goals](manual/project-goals.md) state reVault's purpose and
-priorities. Contributors should use the [v4 work entry point](docs/archive_v4_plan.md)
-to locate the implementation branch and its plan, and the
-[documentation map](docs/documentation_map.md) to find maintained references.
-
-reVault runs on Linux, macOS, and Windows. You can use it through the command
-line interface or through libraries for supported programming languages.
-
-The main components are:
-
-* `revault_cli` for everyday command line use
-* `revault_lockbox_api` for creating and working with Lockboxes
-* `revault_vault_api` for creating and managing Vaults
-
-## The main concepts
-
-* A **Lockbox** is a portable archive with the `.lbox` extension.
-* A **key** or password controls who can open a Lockbox.
-* A **Vault** stores local profiles, contacts, keys, and remembered access to
-  Lockboxes.
-  
-
-> **Pre-release:** the Rust implementation is currently alpha software. The
-> archive format and public APIs may change between releases. Do not use it as
-> the only copy of important data, and keep vault backups and profile recovery
-> material offline.
-
-## Installation
-
-The best way to start with reVault is to install the CLI tooling.
-
-
-### crates.io
-The easist way to install the reVault CLI is from crates.io
-
-```
-cargo install revault_cli
-```
-
-
-### repo
-
-You can also install the CLI by cloning the github repo.
-
-```bash
-git clone https://github.com/onepub-dev/reVault.git
-cd reVault/rust
-cargo xtask install-cli
-cargo xtask dev-tools
-```
-
-# Initialise your vault
-
-In order to create a lockbox you must first initialise your Vault.
-
-When you install the reVault CLI, Cargo installs both `lockbox` app and its alias `lbx` into `~/.cargo/bin`.
-Ensure that directory is on your `PATH`.
-
-`cargo xtask dev-tools` installs `revault-tool`, the repository developer
-command hub. Run `revault-tool --help` to see release preparation/publication,
-binding generation and checks, conformance tests, and the `dev` commands that
-wrap repository validation tasks.
-
-To initialise your vault run:
-
-```bash
-lbx vault init
-```
-The init command will create the keys need to create/open and close lockboxes.
-The keys are stored in your reVault vault.
-
-The init command will also dump those keys to the terminal. You need to backup those
-keys safely.
-* If you loose the keys you will not be able to access any lockbox - there is no way to recover from this!!!
-* If some else gets access to those keys then they have access to all of your lockboxes.
-
-
-## CLI Quick Start
-
-Create a lockbox for the default vault profile: (recommended)
-
-```bash
-lockbox secrets.lbox create
-```
-
-For a lockbox protected by a passphrase instead of a vault profile:
-
-This form is less secure than using a profile.
-
-```bash
-lockbox secrets.lbox create --password
-```
-
-Open it for normal commands:
-
-```bash
-lockbox secrets.lbox open
-```
-
-### Persistent directory mirrors
-
-A mirror project records a one-way relationship between a host directory and
-an exclusively managed directory inside the lockbox. The project definition,
-including its include and exclude rules, is encrypted inside the lockbox and
-travels with it.
-
-```bash
-lbx secrets.lbox mirrors source create --from ./src --to /projects/source
-lbx secrets.lbox mirrors source rules add exclude target/** '*.tmp'
-lbx secrets.lbox mirrors source status
-lbx secrets.lbox mirrors source update
-```
-
-`status` previews the complete plan; `update` recalculates and applies it.
-Multiple projects can coexist when their destination directories do not
-overlap. See the [CLI guide](docs/cli_how_to.md#mirror-a-host-directory-safely)
-for ownership, deletion, rule, and safety details.
-
-The open is cached in a per-user in-memory agent which will automatically close
-it after about 30mins.  Lock it when you are done:
-
-```bash
-lockbox secrets.lbox close
-```
-
-Add files:
-
-```bash
-lockbox secrets.lbox add --recursive ./project --to project/
-lockbox secrets.lbox add ./generated.env --to secrets/prod.env
-```
-
-List and extract:
+Your Vault holds your profile and contacts. The CLI protects a new Lockbox for
+your profile by default, and you can grant access to contacts using their
+public keys. Use password access when you do not have a recipient's contact
+(public key) details.
 
-```bash
-lockbox secrets.lbox list /
-lockbox secrets.lbox list '/project/**/*.rs'
-lockbox secrets.lbox extract /project/README.md ./out/README.md
-```
-
-See [docs/cli_how_to.md](docs/cli_how_to.md) for command-focused examples.
-
-## Profiles And Sharing
-
-Create another local profile:
-
-```bash
-lockbox vault profiles create laptop
-```
-
-Create an independent encrypted vault with a fresh profile and register that
-profile's public key as a contact in the current vault:
-
-```bash
-lbx vault beget production
-# Creates production.vault.lbx with profile:production.
-# Saves only the public key locally as contact:production.
-
-lbx access grant shared.lbox contact:production
-```
-
-Use `--output` to choose the new vault path, `--contact-name` to avoid a local
-contact-name collision, or `--no-contact` to leave the current vault unchanged.
-`beget` never grants lockbox access automatically and never copies private
-material from the current vault.
-
-List profiles and export a public key:
-
-```bash
-lockbox vault profiles list
-lockbox vault profiles export ./laptop.pub --name laptop
-```
-
-Import a contact public key after independently verifying its fingerprint:
-
-```bash
-lockbox vault contacts import alice ./alice.pub \
-  --fingerprint <fingerprint> \
-  --fingerprint-channel phone-call-to-owner
-```
-
-Create a lockbox for a recipient:
-
-```bash
-lockbox shared.lbox create --for alice
-```
+Platform gems contain the matching reVault engine and provide Lockbox, Vault,
+key, and session agent classes through Fiddle.
 
-Grant or revoke access on an existing lockbox:
+## Installation and native runtime
 
-```bash
-lockbox shared.lbox access grant alice
-lockbox shared.lbox access list
-lockbox shared.lbox access revoke alice
+```shell
+gem install revault_api
 ```
 
-Exporting a private key is supported for backup and migration, but treat the
-output as a secret:
-
-```bash
-lockbox vault profiles backup ./default.profile-backup
-```
-
-Private vault keys are stored inside the local vault as secret variable records,
-not as normal files in the vault lockbox. See the CLI help and
-[CLI how-to](docs/cli_how_to.md) for vault backup and profile recovery.
-
-## Variables
-
-Variables are encrypted metadata, not files. They do not appear in file
-listings and are loaded only when variable commands or APIs request them. The
-command group is `variables`.
-
-Plain variables are for values that are useful configuration but not high-value
-secrets:
-
-```bash
-lockbox secrets.lbox variables set DATABASE_URL --value 'postgres://localhost/app'
-lockbox secrets.lbox variables set DATABASE_URL='postgres://localhost/app'
-lockbox secrets.lbox variables get DATABASE_URL
-```
-
-With a session-default lockbox, assignment syntax is also supported:
-
-```bash
-lockbox variables set DATABASE_URL='postgres://localhost/app'
-lockbox variables set DATABASE_URL 'postgres://localhost/app'
-```
-
-Secret variables are for passwords, API tokens, signing keys, and similar
-material. They use secure-memory handling in the variable path and must be provided
-through an explicit source:
-
-```bash
-lockbox secrets.lbox variables set --secret API_TOKEN --interactive
-lockbox secrets.lbox variables set --secret API_TOKEN --file ./api-token.txt
-lockbox secrets.lbox variables set --secret API_TOKEN --stdin
-lockbox secrets.lbox variables set --secret API_TOKEN --from-env API_TOKEN
-```
-
-Avoid passing secrets as command-line arguments. Shell history and process
-inspection can expose argv. Prefer `--interactive`, `--stdin`, `--file`, or
-`--from-env`.
-
-Sensitivity is chosen when a variable is created. Updating the value preserves
-that sensitivity. To change plain to secret, or secret to plain, delete and
-recreate the variable.
-
-## Avoiding Leaks
-
-Use these defaults unless you have a specific reason not to:
-
-- Use `lockbox open` and the local agent instead of repeatedly passing
-  passwords or private keys.
-- Use secret variables for credentials and tokens.
-- Do not store secrets as normal files when variable semantics are appropriate.
-- Do not pass secret values on the command line.
-- Keep private key exports offline, short-lived, and permission-restricted.
-- Prefer recipient keys over shared passwords for team access.
-- Run `lockbox secrets.lbox close` when an open should no longer be cached.
-- Use `lockbox secrets.lbox visualize` for diagnostics; it intentionally avoids
-  printing file paths, file contents, variable names, or variable values.
-
-
-Lockbox protects data inside the container. It cannot protect a secret after you
-write it to a normal terminal, shell history, clipboard, exported file, build
-log, or process environment controlled by other tooling.
-
-## Key Server, Topology, and Replication
-
-`revault_key_server` is a short-lived rendezvous service for sharing candidate
-contact public keys. A publisher uploads a payload, verifies their email, and
-shares the resulting publish code with the recipient. The recipient uses that
-code to receive the candidate key, then verifies its fingerprint independently
-before trusting it. The server does not establish profile trust and is not a
-store for private keys.
-
-### Single server
-
-A first deployment uses one server with `server_id = 0`. Publish codes include
-that server id as their first digit, followed by a random code body. Using a
-self-routing code from the start keeps pending publishes compatible if the
-deployment later gains standby servers.
-
-### Topology servers
-
-Servers publish a topology document containing the known server URLs and the
-primary/failover route for each publish-code owner id. Clients use it as follows:
-
-- For a publish, discover the cluster through a topology endpoint, select a
-  key-server member, and keep that choice sticky locally.
-- For receive and delete, read the publish code's first digit, contact that
-  owner id's primary server, then use only its configured failovers.
-- Do not fail over after a rate-limit response; hopping servers must not bypass
-  abuse controls.
-
-DNS can provide normal host resolution, but it is not the routing mechanism.
-Round-robin DNS alone can send a receive request to a server that does not own
-the corresponding publish code.
-
-### Replication and failover
-
-Each server is authoritative for the codes carrying its own server id. It sends
-signed state events—published payloads, receive counts, payload lifecycle
-tombstones, and rate-limit blocks—to configured standby peers through the separate
-`/v1/replicate` endpoint. Events carry an origin server id, epoch, and sequence
-number, so standbys apply duplicates idempotently and never replicate received
-peer events again.
-
-Replication does not make the cluster hot/hot. A standby keeps replica state
-but serves an owner's payloads only after an operator explicitly promotes it for
-that owner id. This avoids two servers consuming a single-use publish at the
-same time during a network partition. See the [key-server deployment guide](https://github.com/onepub-dev/reVault/blob/master/rust/revault_key_server/README.md), [configuration reference](https://github.com/onepub-dev/reVault/blob/master/rust/revault_key_server/KEY_SERVER_CONFIG.md), and [redundancy design](https://github.com/onepub-dev/reVault/blob/master/rust/revault_key_server/REDUNDANCY.md) for the deployment and recovery procedures.
-
-## Rust Library
-
-Use `revault_lockbox_api` when you need the portable storage engine:
-
-```rust
-use revault_lockbox_api::{Lockbox, LockboxOpen, LockboxPath, LockboxProtection, SecretVec};
-use std::path::Path;
-
-let key = SecretVec::try_from_slice(b"correct horse battery staple")?;
-let signing_key = revault_lockbox_api::OwnerSigningKeyPair::generate()?;
-let mut lockbox = Lockbox::create_file(
-    Path::new("secrets.lbox"),
-    LockboxProtection::ContentKey(key.try_clone()?),
-    &signing_key,
-)?;
-
-lockbox.add_file(&LockboxPath::new("/docs/a.txt")?, b"alpha", false)?;
-lockbox.add_file(&LockboxPath::new("/docs/b.txt")?, b"bravo", false)?;
-lockbox.commit()?;
-
-let reopened = Lockbox::open(
-    Path::new("secrets.lbox"),
-    LockboxOpen::ContentKey(&key),
-)?;
-let file = reopened.get_file(&LockboxPath::new("/docs/a.txt")?)?;
-```
-
-Use `revault_vault_api` for native applications that want the Vault and
-Session Agent behavior:
-
-```rust
-use revault_vault_api::{local_vault, SecretString};
-
-let vault = local_vault();
-let password = SecretString::try_from_bytes(b"pw".to_vec())?;
-
-vault.create_lockbox_with_password("secrets.lbox", &password)?;
-
-let lockbox = vault.open_lockbox_with_password("secrets.lbox", &password)?;
-let mut lockbox = lockbox;
-lockbox.add_file_from_path("notes.txt", &revault_lockbox_api::LockboxPath::new("/notes.txt")?)?;
-lockbox.commit()?;
-```
-
-## Documentation
-
-Performance results for Lockbox using the published pure-Rust
-`zstd-complete 0.1.0` crate, compared with encrypted GPG and unencrypted ZIP,
-are documented in the
-[benchmark report](docs/lockbox_gpg_zip_benchmark_2026_08_30.md).
-
-- [reVault manual](https://docs.revault.onepub.dev/): installation, concepts,
-  CLI workflows, language APIs, and operational guidance.
-- [CLI how-to](docs/cli_how_to.md): command examples.
-- [CI/CD with reVault](docs/ci_cd.md): proposed bootstrap and ephemeral CI
-  workflow for encrypted deployment secrets.
-- [Session Agent](docs/lockbox_session_agent.md): temporary Lockbox access
-  lifecycle, protocol, and security model.
-- [Archive format](rust/revault_lockbox_api/ARCHIVE_FORMAT.md): lockbox archive details and page
-  layout.
-- [Rust development](docs/rust_development.md): build, test, and API docs.
-- [Dependency review](rust/docs/dependency_review.md): dependency and security
-  review notes.
-
-## Development
-
-Follow the [reVault terminology standard](docs/terminology.md) when updating
-the manual, READMEs, CLI help, API guides, or other user-facing material.
-
-Run the Rust checks:
-
-```bash
-cd rust
-cargo fmt --all
-cargo check --workspace --all-targets --all-features
-cargo test --workspace
-cargo clippy --workspace --all-targets --all-features -- -D warnings
-```
-
-Generate Rust API docs:
-
-```bash
-cd rust
-revault-tool dev generate-api-docs
-```
-
-### Release checklist
-
-Before publishing a component:
-
-1. update its version and package README;
-2. regenerate class and method documentation;
-3. run the binding conformance examples;
-4. run the manual validation job;
-5. confirm migration notes and compatibility statements; and
-6. retain the tagged repository documentation as the release snapshot.
-
-For complete procedures, read the [CLI distribution guide](docs/cli_distribution.md)
-and the [binding contribution and release guide](bindings/CONTRIBUTING.md).
+RubyGems publishes a platform gem for each supported operating system and
+architecture. Each gem contains the matching reVault library and a Ruby shim;
+the package loads both through Fiddle. Install the gem matching the Ruby
+process architecture.
 
-## License
+`Revault.load(native_library_path)` can load a native library supplied by the
+application. Otherwise, reVault checks `REVAULT_LIBRARY` and then the library
+installed by the gem. A bare name uses the operating system search path.
+Selection is shared by the process and occurs before the Ruby API loads.
 
-reVault Source Available License 1.0 - see [LICENSE](LICENSE).
+The [complete method example index](https://github.com/onepub-dev/reVault/blob/main/bindings/API_EXAMPLES.md)
+is maintained in the source repository.
 
-The source remains available for inspection, modification, and redistribution.
-Derivative works must publish their corresponding source code in a publicly
-accessible repository such as GitHub or a similar service. The license also
-restricts third parties from offering reVault, modified reVault, or
-substantially similar reVault-derived functionality as a hosted, managed, or
-network-accessible service without a separate written license.
+```ruby
+runtime = Revault.load                 # only loads the native runtime
+signing = runtime.generate_profile_signing_key_pair
+public_signing_key = signing.public_key
+box = runtime.lockbox_create("\0" * 32)
+box.set_owner_signing_key(signing) # Profile becomes this Lockbox's owner
+box.add_file('/hello.txt', "hello\n", false)
+box.set_variable('owner', 'alice')
+box.set_secret_variable('token', 'secret')
+box.with_secret_variable('token') do |token|
+  # Consume the temporary mutable String only inside this block.
+end
+box.commit
+box.free
+public_signing_key.free; signing.free
+
+persistent = Revault::Vault.open_or_create('/tmp/revault-vault', Revault::SecretString.new('Vault passphrase'))
+persistent.close
+```
+
+The temporary secret String is overwritten after the block. Ruby strings are
+not reliably zeroizable once copied, so do not retain or duplicate it.
+`AgentSession` is explicit and caches selected content keys temporarily;
+ordinary Lockbox operations never contact the agent.
+
+## Core API concepts
+
+- `Revault` loads the runtime.
+- `Vault` owns persistent local state.
+- `Lockbox` owns an open archive.
+- `AgentSession` caches selected content keys.
+
+Free or close each object independently.
+
+## API documentation and support
+
+The gem source documents the public classes and methods for its release. The
+[method examples](https://github.com/onepub-dev/reVault/blob/main/bindings/API_EXAMPLES.md)
+and [Ruby conformance program](https://github.com/onepub-dev/reVault/blob/main/bindings/e2e/ruby/conformance.rb)
+cover the common operation inventory.
+
+## Create, open, and replace
+
+Open methods require existing Vaults and Lockboxes and never create missing
+state. Use open or create only when creation is acceptable and replacement
+methods only after an explicit destructive choice. `commit` persists pending
+Lockbox changes; `close` or `free` releases the handle and content key held by the current process
+without deleting the archive.
+
+Open that archive with its Lockbox password, a profile key, or a credential
+resolved from the Vault. A profile signing key becomes a Lockbox owner key only
+after explicit assignment.
+
+## Secrets, failures, and ownership
+
+A vault passphrase, Lockbox password, and 32-byte content key are different
+secrets. Prefer mutable owned strings with minimal lifetime and overwrite them
+after use. Do not copy secret values received by a callback into retained Ruby
+objects. Close objects that own native resources in `ensure` blocks.
+
+Native failures raise typed exceptions with structured details. Public code
+should not depend on transport handles or mutable global error state.
+
+## Optional session agent
+
+Ordinary Lockbox operations never start or consult the agent. Use
+`AgentSession` when Lockbox keys need to be shared across processes or remain
+available after the process that opened the Lockbox exits. Closing an entry
+forgets the cached key, not the Lockbox file or a credential stored in the
+Vault.
+
+## Platform credential store
+
+The operating system credential store can hold the Vault passphrase. The
+user's operating system login normally unlocks that store. After login,
+another process running as that user may be able to retrieve the passphrase if
+the access policy applied to the saved Vault passphrase does not require
+approval for each retrieval. Exact access depends on the operating system, the
+credential store configuration, and that access policy.
+
+A process that retrieves the Vault passphrase can open the Vault. The Vault
+can then provide access to Lockboxes through profile keys or remembered
+Lockbox passwords. Both remain encrypted inside the Vault; they are not copied
+to the operating system credential store.
+
+Agent expiry improves memory hygiene. It is not an authentication boundary
+after login if the saved Vault passphrase can be retrieved without approval.
+
+Missing or placeholder YARD class/method documentation is a binding defect.
+
+## V4 storage compatibility
+
+The v4 development core requires a matching rebuilt native runtime (or WASM
+carrier) and migration of older Vault/Lockbox containers. Migrate the Vault
+first with `lockbox doctor migrate vault --replace`, then each archive with
+`lockbox doctor migrate lockbox <path> --replace`; retain the migration backups.
+These changes do not add facade methods. Writable file opens inherit native
+transaction recovery; explicit read-only opens can report recovery required.
+A commit error may occur after publication, so reopen and inspect persisted
+state before retrying. With library handles closed, use the CLI's
+`lockbox <path> doctor compact` for explicit compaction; it discards old commit
+history. See the repository's [v4 binding contract and release checks](https://github.com/onepub-dev/reVault/blob/master/bindings/README.md#v4-storage-and-transaction-maintenance).
+## Reciprocal contact exchange
+
+Use the shared Rust-backed `ContactExchange` workflow to exchange one Profile's
+encryption and signing public keys in both directions. Sessions retain protected
+Vault credentials but release every Vault lock before network calls or user
+interaction. Compare both identities and the entire fingerprint through an
+independently authenticated channel before saving a Contact.
+
+The [exchange guide](https://github.com/onepub-dev/reVault/blob/main/bindings/EXCHANGE.md)
+documents each language's entry point, credential ownership, retries, verification,
+archive author checks, cancellation, and cleanup. The language's executable
+conformance runner covers session creation, offline status decoding and cleanup;
+the shared native/CLI tests cover reciprocal exchange and persisted archives.