onepub-dev / onepub-dev/reVault
Support plaintext, encrypted, signed, and unsigned archive modes
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.mddocuments the current header,
encrypted page area, public key directory, commit roots, owner signatures,
checksums, and rollback limitation.rust/revault_lockbox_api/README.mddocuments the current encrypted-and-signed
product model and write-authority API.docs/archive_v2_restructure_proposal.mdexplores an append-only segment/frame
format and is the natural place to assess a mode-bearing frame design.docs/format_versioning_and_migrations.mddefines independent archive format
versioning and the rule that imports create a new commit/signature history.docs/migration_guide.mdalready states that migration does not copy old
signature history.rust/AGENTS.mdrequires migration tooling whenever the archive format
changes.
Plan
- Write a short threat model and normative semantics for the four-mode matrix.
- Decide whether the current format can be extended safely or requires an
archive format version bump. - Define a canonical protection descriptor and bind it against downgrade and
mode-confusion attacks. - Specify plaintext page/frame encoding, checksums, compression, limits,
recovery behavior, and metadata exposure. - Specify the common commit envelope for signed and unsigned archives,
including how absence of signatures is represented. - Define creation, conversion, inspection, verification, import/export,
compaction, and recovery APIs for every mode. - Define CLI defaults, explicit opt-outs, warnings, and automation behavior.
- Update format, API, user, security, and troubleshooting documentation.
- Provide exporters/migrators for every affected historical format.
- Add a full mode matrix of round-trip, corruption, tampering, downgrade,
truncation, recovery, migration, and cross-version tests. - 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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