onepub-dev / onepub-dev/reVault

Expose a public session-state API for open and default lockboxes

Open
#224 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
4
Forks
0
Avg merge
1h 55m
Merged PRs (30d)
1

Description

Problem

External callers need to determine:

  1. whether a particular lockbox is currently open in the session agent; and
  2. which lockbox, if any, is configured as the session default.

The public Rust API currently exposes revault_vault_api::list(), which returns the agent's Vec<CachedLockbox>, and revault_vault_api::is_running(). This is enough to inspect cached/open lockboxes, but there is no public API for reading the default lockbox.

Default-lockbox persistence is currently owned by the CLI in revault_cli/src/commands/session.rs via the private .default-lockbox file. Other callers would have to invoke and parse lbx session or duplicate this private file-format and path logic.

The default lockbox and open state are independent: a default may be configured while its session has expired or was explicitly closed.

Intended API

Move default-lockbox state ownership into revault_vault_api and expose a cohesive, read-only session-state API. The exact naming may be refined during implementation, but the intended shape is:

pub struct SessionState {
    pub agent_running: bool,
    pub default_lockbox: Option<PathBuf>,
    pub open_lockboxes: Vec<CachedLockbox>,
}

pub fn session_state() -> Result<SessionState>;
pub fn default_lockbox() -> Result<Option<PathBuf>>;
pub fn is_lockbox_open(path: impl AsRef<Path>) -> Result<bool>;

The existing setters/clearers used by the CLI should also move behind public or appropriately scoped revault_vault_api functions so there is one owner for persistence and canonicalisation.

Required semantics

  • session_state() must not start the session agent or prompt for credentials.
  • If the agent is not reachable, report agent_running = false and an empty open_lockboxes list.
  • Reading the default lockbox must not imply that it is open.
  • is_lockbox_open should compare the lockbox identity where possible, with canonical-path handling for equivalent paths.
  • Expired entries must report as closed.
  • The API must not expose content keys or other secret material.
  • Existing lbx session, lbx session default, move, close-all, and stop behavior must use the shared API without regression.
  • Public language bindings should be updated where this API is intended to be available outside Rust.

Acceptance criteria

  • Public callers can retrieve the configured default lockbox without parsing CLI output or private files.
  • Public callers can determine whether a specified lockbox is currently open.
  • Public callers can retrieve a single coherent session-state snapshot.
  • Default-but-closed and open-but-not-default states are represented distinctly.
  • A stopped or unavailable agent is handled without starting it.
  • Tests cover default set/clear, TTL expiry, explicit close, agent stop, canonical/alternate paths, and default updates after lockbox moves.
  • CLI session commands are refactored to use the shared vault API.
  • Rust API documentation, user documentation, and applicable language bindings are updated.
  • cargo xtask check-required passes.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with revault_cli/src/commands/session.rs and the existing revault_vault_api::list() and is_running() entry points to trace default-lockbox persistence and session-agent access. Review the session command behavior and existing tests before defining the shared API. Done means the acceptance criteria pass, including stopped-agent handling, expiry and path cases, CLI refactoring, documentation, bindings, and cargo xtask check-required.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api, cli, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.