onepub-dev / onepub-dev/reVault

Support plaintext, encrypted, signed, and unsigned archive modes

Open
#227 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

Context

reVault currently presents a lockbox as an encrypted archive whose owner signs
every committed change. We also want to support archives which are intentionally
plaintext, unsigned, or both. Encryption and signing solve different problems
and should be modelled independently rather than treating "not encrypted" as
"not protected" or treating AEAD integrity as proof of authorship.

Related: #211, #226, and #228. #228 defines how a valid signer becomes a
trusted and authorized author.

Required archive modes

Content Commit Meaning
encrypted signed Confidential content with authenticated authorship
encrypted unsigned Confidential content and AEAD tamper detection, but no named author
plaintext signed Publicly readable content whose signed state can be verified and attributed after signer trust is established
plaintext unsigned Publicly readable archive with structural checksums only; no authenticity or authorship claim

The default should remain encrypted and signed. Plaintext and unsigned modes
must be explicit choices.

Security semantics

  • Encryption provides confidentiality. Its AEAD also detects modification by a
    party that does not possess the content key, but it does not identify the
    human author of a commit.
  • Signing binds a signer key to the exact committed archive state. It can be
    used for plaintext or encrypted content.
  • A signed plaintext archive has real value for public distribution, release
    artifacts, policy bundles, shared reference material, and audit evidence, but
    only when the verifier already trusts or deliberately pins the signing key.
  • A cryptographically valid signature made by an unknown key must not be
    reported as trusted authorship.
  • An unsigned plaintext archive can detect accidental corruption through
    checksums, but an attacker can rewrite both the content and checksums.
  • Whole-file rollback remains possible without an external freshness anchor,
    even when the selected archive state is signed.

Inspection must report these properties separately:

confidentiality: encrypted | plaintext
commit protection: signed | unsigned
signature validity: valid | invalid | absent | unverifiable
signer trust: trusted | untrusted | unknown | not-applicable
author authorization: authorized | unauthorized | unknown | not-applicable
freshness: current | stale | unknown

Format implications

The current format has encrypted content pages, public key-directory pages, and
an encrypted commit-auth object. Supporting all four modes requires an explicit,
versioned protection descriptor that is bound into the commit or archive root.
An attacker must not be able to convert a signed archive into an unsigned one,
or an encrypted archive into a plaintext one, by changing an unprotected flag.

Design decisions include:

  • whether this is a new archive format version or a compatible extension;
  • how plaintext pages are framed, checksummed, compressed, scanned, and
    recovered without reusing encrypted-page semantics incorrectly;
  • whether signed archive metadata is public so a signature can be inspected
    before content access, and what identity/privacy information that leaks;
  • how a plaintext archive represents the absence of a content key and key
    directory;
  • whether an unsigned archive omits commit-auth records entirely or carries an
    explicit signed/unsigned mode in a common commit envelope;
  • how mixed-mode history is handled, or whether changing mode always creates a
    newly exported archive with a new history;
  • how recovery distinguishes corruption from deliberate unsigned modification.

The mode, format version, lockbox UUID, commit sequence, complete logical root,
previous commit reference, and relevant algorithm identifiers must be covered
by the signed message when signing is enabled.

CLI and API behavior

Proposed creation/export vocabulary:

--encrypted | --plaintext
--signed | --unsigned

The normal creation path should select --encrypted --signed without requiring
flags. Plaintext and unsigned creation should require explicit intent and clear
warnings. Automation must have a non-interactive acknowledgement mechanism
rather than silently weakening protection.

Open, inspect, verify, copy, export, import, compact, recover, and migrate must
preserve the selected properties. Operations must not silently add, remove, or
change a protection mode. Converting modes should be an explicit operation that
creates a newly committed/exported artifact and reports what provenance is lost.

Existing planning notes

  • rust/revault_lockbox_api/ARCHIVE_FORMAT.md documents the current header,
    encrypted page area, public key directory, commit roots, owner signatures,
    checksums, and rollback limitation.
  • rust/revault_lockbox_api/README.md documents the current encrypted-and-signed
    product model and write-authority API.
  • docs/archive_v2_restructure_proposal.md explores an append-only segment/frame
    format and is the natural place to assess a mode-bearing frame design.
  • docs/format_versioning_and_migrations.md defines independent archive format
    versioning and the rule that imports create a new commit/signature history.
  • docs/migration_guide.md already states that migration does not copy old
    signature history.
  • rust/AGENTS.md requires migration tooling whenever the archive format
    changes.

Plan

  1. Write a short threat model and normative semantics for the four-mode matrix.
  2. Decide whether the current format can be extended safely or requires an
    archive format version bump.
  3. Define a canonical protection descriptor and bind it against downgrade and
    mode-confusion attacks.
  4. Specify plaintext page/frame encoding, checksums, compression, limits,
    recovery behavior, and metadata exposure.
  5. Specify the common commit envelope for signed and unsigned archives,
    including how absence of signatures is represented.
  6. Define creation, conversion, inspection, verification, import/export,
    compaction, and recovery APIs for every mode.
  7. Define CLI defaults, explicit opt-outs, warnings, and automation behavior.
  8. Update format, API, user, security, and troubleshooting documentation.
  9. Provide exporters/migrators for every affected historical format.
  10. Add a full mode matrix of round-trip, corruption, tampering, downgrade,
    truncation, recovery, migration, and cross-version tests.
  11. Complete a security review before plaintext or unsigned modes are declared
    production-ready.

Acceptance criteria

  • All four modes have precise, non-overlapping security claims.
  • Encrypted and signed remains the default.
  • Plaintext and unsigned modes require explicit user intent.
  • Mode and signature stripping/downgrade are detected where authenticity is
    claimed.
  • Inspection never conflates AEAD validity, checksum validity, signature
    validity, signer trust, author authorization, or freshness.
  • Signed plaintext archives can be verified without claiming an unknown signer
    is trusted.
  • Conversion between modes is explicit and documents provenance/history loss.
  • Format documentation and migration tooling ship with any format change.
  • Every mode is covered by positive, negative, recovery, and interoperability
    tests.

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 rust/revault_lockbox_api/ARCHIVE_FORMAT.md and README.md, then read docs/archive_v2_restructure_proposal.md and docs/format_versioning_and_migrations.md. Map the four protection modes, format-version and migration constraints, and the affected CLI/API operations before proposing the descriptor and envelope. Done means the threat model, format and migration decisions, APIs, warnings, and full mode-matrix tests are specified.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.