Proof-of-Work Rate Limiting

About the WebAssembly solver

The solver is shipped as a compact WebAssembly module. The reason is not bot resistance — bots can run WebAssembly perfectly well, and any attacker can re-implement the algorithm in native code in an afternoon. What WebAssembly buys us is something more modest and more honest: it keeps the honest client path within a small factor (roughly 2×) of a hand-written native solver. With a pure-JavaScript implementation, the same gap would be 10–20×, which is precisely what an attacker would exploit by reimplementing the puzzle outside the browser.

Two secondary benefits matter to us too:

• Single source of truth. The same Rust crate compiles to wasm32-unknown-unknown for the browser and to the host target for server-side verification. The solver and the verifier cannot disagree.
• Workspace alignment. Same Rust toolchain, lints, and CI path as the rest of the code base.

Integrate into your own service

The same code path runs in voyk and in your service. Two crates: voyk-pow is a pure-Rust library — no HTTP, no async runtime, no I/O — that you drop into any HTTP stack (Axum, Actix, Rocket, Warp, hyper directly, Lambda, Cloudflare Workers, Fastly Compute@Edge). voyk-pow-wasm is the companion browser solver, a thin wasm-bindgen wrapper over voyk-pow compiled to wasm32-unknown-unknown. Because the algorithm is one crate, the server verifier and the browser solver cannot disagree about the wire format.

Server side — Rust

# Cargo.toml
voyk-pow = { git = "https://github.com/loxal/lox", package = "voyk-pow" }

// HTTP handler — your framework, your route.
use voyk_pow::{ChallengeMint, Verifier, PassportMint, Subject};

// One-time at process start. Secret is 32 bytes; load from your secrets manager.
let secret: [u8; 32] = load_secret();
let mint = ChallengeMint::new(secret);
let verifier = Verifier::new(secret);
let passports = PassportMint::new(secret);

// GET /pow/challenge
let sealed = mint.mint(/* difficulty_bits */ 20, /* ttl_secs */ 30)?;
let wire = sealed.encode_base64url();    // send to client

// POST /pow/passport — verify, then mint a passport.
let received = voyk_pow::SealedChallenge::decode_base64url(&wire)?;
let solution = voyk_pow::Solution { challenge: received, answer };
verifier.verify(&solution)?;
let passport = passports.mint(Subject::ipv4_from(client_ip), 30 * 60, /* tier */ 0)?;
// set passport.encode_base64url() as a Secure;HttpOnly;SameSite=Lax cookie.

Voyk’s own /pow/challenge + /pow/passport handlers and the gate middleware live in voyk/src/pow.rs and are themselves < 400 LOC. If you’re on Axum 0.8 you can copy them verbatim.

Browser side — WebAssembly solver

# Build the .wasm + JS glue once.
cargo install wasm-pack
wasm-pack build voyk-pow-wasm --release --target web --out-dir pkg
# pkg/voyk_pow_wasm_bg.wasm   ~20 KB after wasm-opt -Oz
# pkg/voyk_pow_wasm.js        ES module loader
# pkg/voyk_pow_wasm.d.ts      TypeScript typings

// Plain JS on the page — single-shot solver (20-bit puzzle, ~300 ms desktop).
import init, { solve_once_b64 } from '/pkg/voyk_pow_wasm.js';
await init();

const ch = await (await fetch('/pow/challenge')).json();
const answer = solve_once_b64(ch.challenge);

await fetch('/pow/passport', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ challenge: ch.challenge, answer: answer.toString() }),
});
// After this, cookies carry the passport; just call protected routes normally.

For higher difficulties (24+ bits, multi-second puzzles), run the solver on a Web Worker using the resumable solve_step_b64(challenge, start, max_iters) API so the tab stays responsive while the puzzle works. See voyk-pow-wasm/README.md for the Worker example.

Hosted — no self-host, just call our verifier

If you don’t want to run a verifier, point your front-end at voyk.loxal.net/pow/* and your back-end at the same host’s validation API. The wire format and the cookie name (pow_passport) are identical to the self-hosted crate; the difference is that we hold the HMAC secret. Available on the Pro and Enterprise tiers (see Pricing below). Auth on the hosted API uses the same X-API-Key header as the rest of the voyk API.

Tier semantics — what your key buys you. All hosted calls work without a key (anonymous “public” tier). The key unlocks the knobs and lifts the per-IP demo throttle:

The challenge response echoes the resolved tier as tier: "public" | "pro" | "enterprise" so your client can verify it was credited to the expected plan. Public callers who pass ?difficulty=1&ttl=86400 still receive the server defaults — the knobs only take effect for authenticated callers. Apply for a key at info@loxal.net.

curl -H "X-API-Key: $VOYK_KEY" \
     "https://voyk.loxal.net/pow/challenge?difficulty=12&ttl=120"
# => {"challenge":"…","difficulty_bits":12,"expires_in_secs":120,"tier":"pro"}