Skip to main content

Crate pq_objectstore

Crate pq_objectstore 

Source
Expand description

§pq-objectstore

Post-quantum encrypted object storage for Rust and TypeScript.

Encrypt locally with ML-KEM-768 + AES-256-GCM, then store ciphertext on any S3-compatible backend — or seal bytes in WASM and let a Cloudflare Worker / Next.js route write them to R2.

Application / Celld / Next.js Worker
        │
        ▼
┌───────────────────────┐
│    pq-objectstore     │
│  ML-KEM-768 + AES-GCM │
└──────────┬────────────┘
           │ ciphertext (PQOS)
           ▼
     S3 / R2 / MinIO / RustFS

§Quick starts

§1. Rust store (Tokio + S3/R2)

use pq_objectstore::{
    PqObjectStore,
    backend::MemoryBackend,
    key::{KeyId, LocalKeyProvider},
};

let key_id = KeyId::new("workspace-a-v1")?;
let keys = LocalKeyProvider::generate(key_id.clone())?;

let store = PqObjectStore::builder()
    .backend(MemoryBackend::new())
    .key_provider(keys)
    .key_id_validated(key_id)
    .build()?;

store.put_bytes("agents/123/memory.bin", b"secret").await?;
let plaintext = store.get_bytes("agents/123/memory.bin").await?;
assert_eq!(plaintext, b"secret");

§2. Rust seal bytes (no backend)

use pq_objectstore::crypto::generate_keypair;
use pq_objectstore::key::KeyId;
use pq_objectstore::seal::{open, seal};

let (secret, public) = generate_keypair();
let key_id = KeyId::new("workspace-a-v1").unwrap();
let ciphertext = seal(b"secret", &public, &key_id).unwrap();
assert_eq!(open(&ciphertext, &secret).unwrap(), b"secret");

§3. Cookbook: TypeScript + Cloudflare Worker + R2

Build the WASM package once (no Tokio / AWS SDK):

rustup target add wasm32-unknown-unknown
wasm-pack build --target web --out-dir pkg \
  -- --no-default-features --features "wasm,local-keys"

Cargo dependency equivalent:

pq-objectstore = { version = "0.2", default-features = false, features = ["wasm", "local-keys"] }

§Worker flow

TS Worker                         pq-objectstore (wasm)
─────────                         ────────────────────
plaintext ── seal() ────────────► PQOS ciphertext
     │
     └── await env.MY_BUCKET.put(key, ct)

ct = await env.MY_BUCKET.get(key)
plaintext ◄── open(ct, secretSeed)

§Example Worker (TypeScript)

import init, {
  PqosKeypair,
  seal,
  open,
  peekKeyId,
} from "../pkg/pq_objectstore.js";

export interface Env {
  MY_BUCKET: R2Bucket;
  // 64-byte ML-KEM seed, base64 — never commit real secrets
  PQ_SECRET_SEED_B64: string;
}

let wasmReady: Promise<void> | undefined;

function ensureWasm() {
  wasmReady ??= init().then(() => undefined);
  return wasmReady;
}

function loadKeys(env: Env): PqosKeypair {
  const seed = Uint8Array.from(atob(env.PQ_SECRET_SEED_B64), (c) =>
    c.charCodeAt(0),
  );
  return PqosKeypair.fromSecretSeed(seed);
}

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    await ensureWasm();
    const keys = loadKeys(env);
    const keyId = "workspace-a-v1";
    const url = new URL(req.url);
    const objectKey = url.pathname.replace(/^\//, "") || "demo.bin";

    if (req.method === "PUT") {
      const plaintext = new Uint8Array(await req.arrayBuffer());
      const ciphertext = seal(plaintext, keys.publicKey, keyId);
      await env.MY_BUCKET.put(objectKey, ciphertext);
      return new Response(null, { status: 204 });
    }

    if (req.method === "GET") {
      const obj = await env.MY_BUCKET.get(objectKey);
      if (!obj) return new Response("not found", { status: 404 });
      const ct = new Uint8Array(await obj.arrayBuffer());
      // peekKeyId(ct) selects which seed to use after rotation
      const _which = peekKeyId(ct);
      const plaintext = open(ct, keys.secretSeed);
      return new Response(plaintext, {
        headers: { "content-type": "application/octet-stream" },
      });
    }

    return new Response("method not allowed", { status: 405 });
  },
};

§Next.js note

Same WASM module works from a Cloudflare-hosted Next.js route or OpenNext Worker: import pkg/pq_objectstore.js, await init(), then seal / open before env.MY_BUCKET.put / .get. Keep the 64-byte secret seed in Worker secrets (wrangler secret), not in the client bundle.

See also wasm (feature wasm) and seal.

§Architecture

Each object receives a unique AES-256-GCM data-encryption key (DEK). That DEK is wrapped using an ML-KEM-768 shared secret derived from a long-lived key. Object payloads use a chunked STREAM construction.

§Security model

The storage backend is untrusted. Payload contents and DEKs are protected; object keys/paths and sizes are not. Prefer opaque object IDs when metadata confidentiality matters.

§Features

  • store (default): async PqObjectStore + backends
  • s3 (default): Cloudflare R2 / AWS S3 / MinIO / RustFS backend
  • local-keys (default): key::LocalKeyProvider
  • wasm: wasm-bindgen exports (PqosKeypair, seal, open, peekKeyId)
  • tracing: optional structured logging (never logs secrets)

Re-exports§

pub use error::Error;
pub use error::Result;
pub use key::KeyId;
pub use seal::SealInfo;
pub use seal::open;
pub use seal::peek_header;
pub use seal::seal;
pub use seal::seal_with_info;
pub use key::KeyProvider;store
pub use store::EncryptedObjectStore;store
pub use store::EncryptedReader;store
pub use store::ListPage;store
pub use store::ListedObject;store
pub use store::ObjectMetadata;store
pub use store::PqObjectStore;store
pub use store::PqObjectStoreBuilder;store
pub use store::PutResult;store
pub use key::LocalKeyProvider;local-keys

Modules§

backendstore
Object storage backends.
crypto
Cryptographic primitives used by encrypted objects.
error
Crate-owned error types for pq-objectstore.
format
Versioned encrypted object binary format.
key
Key identifiers and providers.
seal
Sync byte seal/open API (no object backend).
storestore
High-level encrypted object store API.
wasmwasm
wasm-bindgen exports for Cloudflare Workers / Next.js.