rok-plugins

rok — Read-Only Keys

A Rust cryptography library implementing a dual-key system with hierarchical read-key delegation, multi-recipient encryption, and post-quantum hybrid support.

The core idea: a spend key (Ed25519) acts as the root of trust—it signs data and derives read keys (X25519). Read keys are scope-bound and hierarchical, enabling fine-grained access delegation without exposing the spend key.

Spend Key (Ed25519)
  └── Root Read Key (scope: /)
        ├── /finance
        │     ├── /finance/q1
        │     └── /finance/q2
        └── /legal
              └── /legal/contracts

A key at /finance can decrypt anything at /finance, /finance/q1, /finance/q2—but not /legal. Read keys can be delegated (exported) to third parties who can then derive child keys further, without ever gaining access to parent scopes.

Features

• Hierarchical read keys — scope-based derivation with ancestor/descendant access control
• Multi-recipient encryption — encrypt once, grant access to many; each recipient gets an independently wrapped data key
• Scope-based group encryption — encrypt to a scope and any ancestor key holder can automatically decrypt, no recipient listing required
• Post-quantum hybrid — X25519 + ML-KEM-768 combined via HKDF; secure if either algorithm holds
• Dual serialization — compact binary format (ROK\x01 magic header) and Protocol Buffers
• Authenticated envelopes — every ciphertext is signed by the spend key (Ed25519)
• Key export/import — delegate read keys with Base58-encoded portable format
• Sectioned envelopes — bundle multiple encrypted sections (each at its own scope) into a single .roks file; a /finance key decrypts only the finance section while a root key decrypts everything
• Selective disclosure credentials — encrypt individual attributes under different scopes
• Zero-copy zeroization — secrets are zeroized on drop via the zeroize crate

Architecture

┌─────────────────────────────────────────────────┐
│           rok-cli          │     rok-mcp        │
│     12 commands, clap CLI  │  MCP server for    │
│                            │  Claude Code       │
├──────────────────┬─────────┴────────────────────┤
│     rok-sdk      │                              │
│  Vault, Pipeline,│         rok-pq               │
│  Policy, Identity│    ML-KEM-768 hybrid         │
├──────────────────┴──────────────────────────────┤
│                  rok-core                       │
│  Keys, Derivation, Encryption, Envelope, Signing│
└─────────────────────────────────────────────────┘

Crate	Description
rok-core	Cryptographic primitives: key types, HKDF derivation, encryption/decryption, envelope format, signing, Base58 encoding
rok-pq	Post-quantum module: ML-KEM-768 encapsulation, X25519+ML-KEM hybrid combiner, and end-to-end hybrid envelope encrypt/decrypt
rok-sdk	High-level abstractions: encrypted vault, data pipeline, access policy engine, selective disclosure credentials
rok-cli	Command-line interface with 12 commands for key management, encryption, signing, and delegation
rok-mcp	MCP server for Claude Code — encrypted memory backed by Fileverse with auto-sync, scoped access, and key delegation

Cryptographic Primitives

Purpose	Algorithm	Details
Signing	Ed25519	Spend key signs all envelopes
Key agreement	X25519 ECDH	Ephemeral-static for per-envelope shared secrets
Post-quantum KEM	ML-KEM-768	NIST FIPS 203 lattice-based KEM
Data encryption	ChaCha20-Poly1305	AEAD for payload encryption
Key wrapping	AES-256-GCM-SIV	Per-recipient data key wrapping
Key derivation	HKDF-SHA256	Domain-separated derivation with unique tags
Key identifiers	SHA-256 truncated	First 8 bytes of SHA-256(public_key)
Key encoding	Base58Check	Tagged encoding with 4-byte checksums

Domain Separation Tags

Each HKDF derivation uses a unique domain tag to prevent cross-protocol attacks:

Tag	Purpose
rok-v1-spend-to-root-read	Spend key to root read key
rok-v1-read-child-derive	Parent read key to child (step-wise per path component)
rok-v1-key-wrap	ECDH shared secret to wrapping key
rok-v1-hybrid-combine	Combine X25519 + ML-KEM shared secrets
rok-v1-pq-key-derive	Derive PQ key seed from read key secret + scope

Installation

From source

git clone https://github.com/manojkgorle/ethmumbai-rok.git
cd read-only-keys
cargo build --release

The binary is at target/release/rok.

Requirements

• Rust 1.75+
• protobuf compiler (protoc) for proto code generation

CLI Usage

Key Generation

Generate a spend keypair and its root read key:

rok keygen --label mykey