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;