A Rust CLI for file operations that carry their own inversion metadata. Undo deletes, modifications, and moves in milliseconds without external backups. Formal proofs of complete reversibility are pending.
JanusKey is a file operation utility suite that pursues complete reversibility through architectural design. Unlike traditional backup systems that restore from external state, JanusKey operations carry sufficient information for inversion—the goal is to make data loss architecturally impossible.
Every jk delete, jk modify, or jk move stores the inverse operation in an append-only log backed by content-addressed storage (SHA-256). Rolling back is a metadata lookup, not a filesystem search or a tape restore.
|
Caution
|
Formal proofs of complete reversibility are pending. The engineering mechanism (inversion metadata) is implemented in Rust. The mathematical guarantee that this construction makes data loss impossible under all allowed operations has not yet been mechanically verified. See EXPLAINME §Reversibility guarantee. |
The product is jk: reversible file operations whose inversion metadata lives in
an append-only, content-addressed log. Its implementation is main.rs + lib.rs
operations.rs + delta.rs + obliteration.rs over reversible-core.
The workspace contains two further things that are not on that path. They are listed here because the repository’s name invites the wrong inference, and because "what the code does" is the only boundary that survives review:
-
A key store with lifecycle management (
crates/januskey-cli/src/keys.rs, built as a second binaryjk-keys). It is behind the opt-inkey-lifecyclefeature, so a default build producesjkonly. It has no call edge to or from the reversibility path, and it protects no file content — the content store is plaintext. Being feature-gated removes the binary; the module is still compiled into the library and still pulls its crypto crates until it is moved out (ADR-0001 §5). Key custody is not part of this project’s identity and is scheduled to move; see ADR-0001. -
An HMAC-SHA256-chained audit log (
attestation.rs). Library-only today: thejkbinary never constructs an audit log, and the key it requires is supplied by the caller, not derived from the key store.
reversible-core is intended to be shared with ochrance, valence-shell and
aletheia. None of them depends on it yet; see ARCHITECTURE §Consumption status.
| Concept | Status | Home |
|---|---|---|
Content-addressed storage (SHA-256) |
Standard (Git, IPFS, Nix) |
Storage layer |
Append-only operation log |
Standard (event sourcing, WAL) |
Metadata store |
Transactional commit/rollback |
Standard (databases) |
Transaction manager |
CLI for reversible file operations |
Standard (various undo/trash utilities) |
|
Inversion metadata attached to every operation |
Novel packaging (operations carry their own inverse) |
Operation layer |
Maximal Principle Reduction (MPR) |
Novel vocabulary for "secure by construction" |
Design philosophy |
Every operation stores sufficient metadata for inversion:
| Operation | Inversion metadata stored |
|---|---|
Delete |
Full file content + metadata in content-addressed storage |
Modify |
Original content hash + location in content store |
Move |
Original path |
Copy |
Destination path |
Rollback is an lookup-then-execute operation against the append-only log, bounded by metadata retrieval time (milliseconds), not filesystem scan time.
Reversibility is the default. Secure obliteration (jk obliterate) is the deliberate, explicit exception. It is best-effort only:
-
Overwrite-in-place cannot guarantee physical erasure on SSDs (wear leveling), CoW filesystems (ZFS, Btrfs), or journaling filesystems.
-
The threat model for overwriting assumes rotating magnetic media. On modern media, physical destruction is the only guaranteed obliteration.
| Command | Description |
|---|---|
|
Initialize JanusKey in current directory |
|
Delete files (reversible) |
|
Modify files with sed-like syntax |
|
Move/rename files |
|
Rename in place (reversible) |
|
Overwrite then remove (NOT reversible; best-effort) |
|
Copy files |
|
Undo last operation(s) |
|
Start a transaction |
|
Commit current transaction |
|
Rollback current transaction |
|
Preview pending changes |
|
Show operation history |
|
Show current status |
|
Prune old operations |
┌────────────────────────────┐ │ JanusKey CLI │ jk delete, jk modify, jk move ├────────────────────────────┤ │ Operation Layer │ Generates inverse metadata ├────────────────────────────┤ │ Transaction Manager │ Groups ops, commit/rollback ├────────────────────────────┤ │ Metadata Store │ Append-only operation log ├────────────────────────────┤ │ Content-Addressed Storage │ SHA-256, deduplication └────────────────────────────┘
|
Caution
|
Formal proofs are pending. The claim "data loss is architecturally impossible" is an engineering intent supported by the inversion-metadata mechanism. It is not yet a mechanically verified theorem. The |
|
Caution
|
Secure obliteration is best-effort. |
|
Caution
|
MPR is design vocabulary, not a verified method. Maximal Principle Reduction describes the design philosophy of eliminating vulnerability by construction (no irreversible code path exists). It is not a formal method with mechanical tooling in this repo. |
# Build from source (requires Rust)
cargo build --workspace --release
# Include the off-path key lifecycle binary as well
cargo build --workspace --release --features key-lifecycle
# Initialize
jk init
# Run tests
cargo test --workspaceSPDX-License-Identifier: MPL-2.0 — see LICENSE.
Prose documentation is licensed under CC-BY-SA-4.0; see LICENSES/.