Skip to main content

pq_objectstore/
lib.rs

1//! # pq-objectstore
2//!
3//! Post-quantum encrypted object storage for Rust **and** TypeScript.
4//!
5//! Encrypt locally with ML-KEM-768 + AES-256-GCM, then store ciphertext on any
6//! S3-compatible backend — or seal bytes in WASM and let a Cloudflare Worker /
7//! Next.js route write them to R2.
8//!
9//! ```text
10//! Application / Celld / Next.js Worker
11//!         │
12//!         ▼
13//! ┌───────────────────────┐
14//! │    pq-objectstore     │
15//! │  ML-KEM-768 + AES-GCM │
16//! └──────────┬────────────┘
17//!            │ ciphertext (PQOS)
18//!            ▼
19//!      S3 / R2 / MinIO / RustFS
20//! ```
21//!
22//! # Quick starts
23//!
24//! ## 1. Rust store (Tokio + S3/R2)
25//!
26//! ```no_run
27//! # #[cfg(all(feature = "store", feature = "local-keys"))]
28//! # {
29//! use pq_objectstore::{
30//!     PqObjectStore,
31//!     backend::MemoryBackend,
32//!     key::{KeyId, LocalKeyProvider},
33//! };
34//!
35//! # async fn example() -> pq_objectstore::Result<()> {
36//! let key_id = KeyId::new("workspace-a-v1")?;
37//! let keys = LocalKeyProvider::generate(key_id.clone())?;
38//!
39//! let store = PqObjectStore::builder()
40//!     .backend(MemoryBackend::new())
41//!     .key_provider(keys)
42//!     .key_id_validated(key_id)
43//!     .build()?;
44//!
45//! store.put_bytes("agents/123/memory.bin", b"secret").await?;
46//! let plaintext = store.get_bytes("agents/123/memory.bin").await?;
47//! assert_eq!(plaintext, b"secret");
48//! # Ok(())
49//! # }
50//! # }
51//! ```
52//!
53//! ## 2. Rust seal bytes (no backend)
54//!
55//! ```
56//! use pq_objectstore::crypto::generate_keypair;
57//! use pq_objectstore::key::KeyId;
58//! use pq_objectstore::seal::{open, seal};
59//!
60//! let (secret, public) = generate_keypair();
61//! let key_id = KeyId::new("workspace-a-v1").unwrap();
62//! let ciphertext = seal(b"secret", &public, &key_id).unwrap();
63//! assert_eq!(open(&ciphertext, &secret).unwrap(), b"secret");
64//! ```
65//!
66//! ## 3. Cookbook: TypeScript + Cloudflare Worker + R2
67//!
68//! Build the WASM package once (no Tokio / AWS SDK):
69//!
70//! ```bash
71//! rustup target add wasm32-unknown-unknown
72//! wasm-pack build --target web --out-dir pkg \
73//!   -- --no-default-features --features "wasm,local-keys"
74//! ```
75//!
76//! Cargo dependency equivalent:
77//!
78//! ```toml
79//! pq-objectstore = { version = "0.2", default-features = false, features = ["wasm", "local-keys"] }
80//! ```
81//!
82//! ### Worker flow
83//!
84//! ```text
85//! TS Worker                         pq-objectstore (wasm)
86//! ─────────                         ────────────────────
87//! plaintext ── seal() ────────────► PQOS ciphertext
88//!      │
89//!      └── await env.MY_BUCKET.put(key, ct)
90//!
91//! ct = await env.MY_BUCKET.get(key)
92//! plaintext ◄── open(ct, secretSeed)
93//! ```
94//!
95//! ### Example Worker (TypeScript)
96//!
97//! ```ts
98//! import init, {
99//!   PqosKeypair,
100//!   seal,
101//!   open,
102//!   peekKeyId,
103//! } from "../pkg/pq_objectstore.js";
104//!
105//! export interface Env {
106//!   MY_BUCKET: R2Bucket;
107//!   // 64-byte ML-KEM seed, base64 — never commit real secrets
108//!   PQ_SECRET_SEED_B64: string;
109//! }
110//!
111//! let wasmReady: Promise<void> | undefined;
112//!
113//! function ensureWasm() {
114//!   wasmReady ??= init().then(() => undefined);
115//!   return wasmReady;
116//! }
117//!
118//! function loadKeys(env: Env): PqosKeypair {
119//!   const seed = Uint8Array.from(atob(env.PQ_SECRET_SEED_B64), (c) =>
120//!     c.charCodeAt(0),
121//!   );
122//!   return PqosKeypair.fromSecretSeed(seed);
123//! }
124//!
125//! export default {
126//!   async fetch(req: Request, env: Env): Promise<Response> {
127//!     await ensureWasm();
128//!     const keys = loadKeys(env);
129//!     const keyId = "workspace-a-v1";
130//!     const url = new URL(req.url);
131//!     const objectKey = url.pathname.replace(/^\//, "") || "demo.bin";
132//!
133//!     if (req.method === "PUT") {
134//!       const plaintext = new Uint8Array(await req.arrayBuffer());
135//!       const ciphertext = seal(plaintext, keys.publicKey, keyId);
136//!       await env.MY_BUCKET.put(objectKey, ciphertext);
137//!       return new Response(null, { status: 204 });
138//!     }
139//!
140//!     if (req.method === "GET") {
141//!       const obj = await env.MY_BUCKET.get(objectKey);
142//!       if (!obj) return new Response("not found", { status: 404 });
143//!       const ct = new Uint8Array(await obj.arrayBuffer());
144//!       // peekKeyId(ct) selects which seed to use after rotation
145//!       const _which = peekKeyId(ct);
146//!       const plaintext = open(ct, keys.secretSeed);
147//!       return new Response(plaintext, {
148//!         headers: { "content-type": "application/octet-stream" },
149//!       });
150//!     }
151//!
152//!     return new Response("method not allowed", { status: 405 });
153//!   },
154//! };
155//! ```
156//!
157//! ### Next.js note
158//!
159//! Same WASM module works from a Cloudflare-hosted Next.js route or OpenNext
160//! Worker: import `pkg/pq_objectstore.js`, `await init()`, then `seal` /
161//! `open` before `env.MY_BUCKET.put` / `.get`. Keep the 64-byte secret seed in
162//! Worker secrets (`wrangler secret`), not in the client bundle.
163//!
164//! See also [`mod@wasm`] (feature `wasm`) and [`mod@seal`].
165//!
166//! # Architecture
167//!
168//! Each object receives a unique AES-256-GCM data-encryption key (DEK). That DEK
169//! is wrapped using an ML-KEM-768 shared secret derived from a long-lived key.
170//! Object payloads use a chunked STREAM construction.
171//!
172//! # Security model
173//!
174//! The storage backend is untrusted. Payload contents and DEKs are protected;
175//! object keys/paths and sizes are not. Prefer opaque object IDs when metadata
176//! confidentiality matters.
177//!
178//! # Features
179//!
180//! - `store` (default): async [`PqObjectStore`] + backends
181//! - `s3` (default): Cloudflare R2 / AWS S3 / MinIO / RustFS backend
182//! - `local-keys` (default): [`key::LocalKeyProvider`]
183//! - `wasm`: `wasm-bindgen` exports (`PqosKeypair`, `seal`, `open`, `peekKeyId`)
184//! - `tracing`: optional structured logging (never logs secrets)
185
186#![cfg_attr(docsrs, feature(doc_cfg))]
187#![forbid(unsafe_code)]
188#![deny(missing_docs)]
189#![warn(clippy::all)]
190
191pub mod crypto;
192pub mod error;
193pub mod format;
194pub mod key;
195pub mod seal;
196
197#[cfg(feature = "store")]
198pub mod backend;
199#[cfg(feature = "store")]
200pub mod store;
201
202#[cfg(feature = "wasm")]
203#[cfg_attr(docsrs, doc(cfg(feature = "wasm")))]
204pub mod wasm;
205
206pub use error::{Error, Result};
207pub use key::KeyId;
208pub use seal::{SealInfo, open, peek_header, seal, seal_with_info};
209
210#[cfg(feature = "store")]
211pub use key::KeyProvider;
212#[cfg(feature = "store")]
213pub use store::{
214    EncryptedObjectStore, EncryptedReader, ListPage, ListedObject, ObjectMetadata, PqObjectStore,
215    PqObjectStoreBuilder, PutResult,
216};
217
218#[cfg(feature = "local-keys")]
219pub use key::LocalKeyProvider;