arxid (Rust reference implementation)
arxid obfuscates a sequential integer id into a keyed, unordered,
reversible form. It is a balanced Feistel network with an ARX (Add-Rotate-XOR)
round function, format-preserving over 40 bits, plus an optional 7-character
base62 encoding.
This crate is the reference implementation of
spec/SPEC.md.
It is a pure library: no server, no HTTP, no network, no I/O.
Quickstart
use Arxid;
# // your secret manager
// Load your own random key. Never hardcode one, and never copy a key out of
// documentation - including this page.
let arxid = new;
let code = arxid.obfuscate;
assert_eq!;
let s = arxid.obfuscate_str; // 7-character base62
assert_eq!;
assert_eq!;
Keys stored as raw bytes are read big-endian, so a key written by one service is read identically by another:
use Arxid;
let from_bytes = from_key_bytes;
assert_eq!;
Consecutive ids do not produce codes in any recoverable order:
use Arxid;
let arxid = new;
let codes: = .map.collect;
let ascending = codes.windows.filter.count;
assert!; // no monotone structure
Note what is not claimed: that neighbouring ids never land on adjacent codes. That is not a property of a good permutation, and spec v1 was wrong to assert it. See SPEC.md §11.
The key can also be passed per call:
use ;
let key = 42;
assert_eq!;
Domain
The permutation is defined over [0, MAX_ID] where MAX_ID = 2^40 - 1.
Anything outside is reduced with & MAX_ID, so the functions are total and
never panic:
use ;
assert_eq!;
String decoding is stricter and returns None instead of panicking:
use from_base62;
assert_eq!; // wrong length
assert_eq!; // invalid character
assert_eq!; // above MAX_ID
Features
| Feature | Default | What it does |
|---|---|---|
std |
on | Links std. Turn off for no_std targets. |
alloc |
on (via std) |
Enables allocation. Required by encoding. |
encoding |
on | The base62 string layer (obfuscate_str, to_base62, ...). |
zeroize |
on | Wipes the key from memory on drop. |
wasm |
off | Exposes the core through wasm-bindgen. |
no_std is supported: the core permutation needs only core, and the base62
layer needs only alloc.
[]
= { = "0.2", = false, = ["encoding", "zeroize"] }
wasm is an optional build target, not the portability mechanism.
Interoperability across languages comes from native ports validated against
/vectors/vectors.json.
Interoperability
The canonical test vectors in /vectors/vectors.json are the interop contract.
tests/vectors.rs checks every one of them, in both directions. A port that
disagrees with those vectors is a bug in the port.
Regenerate the vectors from this crate with:
cargo run --example gen_vectors > ../../vectors/vectors.json
Security
Full threat model: SPEC.md §9.
Recovering an id from a code without the key is not computationally infeasible. arxid raises enumeration from "count upward" to "do some work". It is not encryption, not a MAC (no authentication, no integrity — every well-formed in-range code decodes to some id), and has had no independent cryptographic audit. ID obfuscation is not access control.
Operationally: random key per deployment, loaded from the environment or a secret manager and never committed; a separate key per resource type, since there is no tweak and one key is one global mapping; and do not echo internal ids back in responses or errors.
This crate implements spec v2. Spec v1 (crate 0.1.x) is withdrawn — it used 4 rounds, which review showed to be separable from a random permutation at ~2^13 chosen queries. Codes issued by 0.1.x do not decode here.
License
MIT. See LICENSE.