# dealcode (Rust)
Collision-free, random-looking codes from a counter. Rust implementation of
the [dealcode spec](https://github.com/algorix-hq/dealcode/blob/main/SPEC.md).
## Install
```sh
cargo add dealcode
```
Requires Rust ≥ 1.85. The only runtime dependencies are the audited
[RustCrypto](https://github.com/RustCrypto) crates
[`aes`](https://crates.io/crates/aes) and
[`sha2`](https://crates.io/crates/sha2), used for AES and key derivation.
## Quickstart
```rust
use dealcode::Dealcode;
let codec = Dealcode::new("0a1b...64-hex-chars-from-your-secret-manager")?;
codec.encode(0)?; // "767a5b" (6 hex chars)
codec.encode(1)?; // "421163" never collides with any other counter
codec.decode("421163")?; // 1
# Ok::<(), dealcode::Error>(())
```
The key can be raw bytes (16/24/32 bytes are used as-is as an AES key) or any
string/bytes, which are deterministically expanded to an AES-256 key. Generate
one with `openssl rand -hex 32` and keep it in your secret manager — the
mapping is stable only while the key (and every other option) stays fixed.
### Options
```rust
use dealcode::Dealcode;
let codec = Dealcode::builder(key) // impl Into<Key>: &str, String, &[u8], Vec<u8>, [u8; N]
.alphabet("hex") // "dec" | "hex" | "base32" | "crockford" | "base36"
// | "base58" | "base62" | "base64url" | custom string
.min_length(6) // codes start at this length...
.max_length(15) // ...and grow one char at a time up to this
// (default: max length whose code space fits 2^63)
.domain("") // namespace: same key, unrelated codes per domain
.build()?;
```
```rust
let coupon = Dealcode::builder(key).alphabet("crockford").domain("coupons").build()?;
// human-friendly, e.g. "97HVZ6"
let order = Dealcode::builder(key).alphabet("dec").min_length(8).domain("orders").build()?;
// digits only
let fixed = Dealcode::builder(key).min_length(16).max_length(16).build()?;
// constant-length hex
```
`decode` returns `Err(Error::InvalidCode(_))` for **malformed** input — wrong
length, characters outside the alphabet, or a value outside the issuable
range. A *well-formed* code always decodes to some counter, whether or not
that counter was ever issued (inherent to a permutation — see SPEC §7).
Treat decode as parsing, not proof of existence: look the counter up before
acting on it, and note that a one-character typo in a valid code can resolve
to a *different* valid counter — add rate limiting (and, for human-typed
flows, an existence check or your own check digit).
`encode` returns `Err(Error::Range { .. })` outside `[0, codec.capacity())`.
Invalid configuration is rejected at build time with `Err(Error::Config)`.
All three are variants of `dealcode::Error`, which implements
`std::error::Error`.
## Using it with your database
Dealcode does not talk to your database — it only turns a counter into a code.
Any source of never-repeating integers works. With PostgreSQL:
```sql
CREATE SEQUENCE order_code_seq AS bigint MINVALUE 0 START WITH 0;
CREATE TABLE orders (
id bigint PRIMARY KEY, -- the counter
code text NOT NULL UNIQUE, -- safety net; alerts on config mistakes
...
);
```
```rust
use dealcode::{Dealcode, Error};
let codec = Dealcode::builder(std::env::var("DEALCODE_KEY").unwrap())
.domain("orders")
.build()?;
// on create:
let n: i64 = client.query_one("SELECT nextval('order_code_seq')", &[])?.get(0);
let code = codec.encode(n as u64)?;
client.execute("INSERT INTO orders (id, code) VALUES ($1, $2)", &[&n, &code])?;
// on lookup:
fn find_order(client: &mut Client, codec: &Dealcode, code: &str) -> Option<Row> {
let n = codec.decode(code).ok()?; // malformed codes never reach the DB
client.query_opt("SELECT * FROM orders WHERE id = $1", &[&(n as i64)]).ok()?
}
```
Sequences never hand out the same number twice (even across concurrent
transactions and rollbacks), so codes never collide. Gaps in the sequence are
invisible — codes look random anyway.
If the `UNIQUE` constraint on `code` ever fires, do not retry: it means the
key/config changed for an existing namespace. Investigate.
## Fixed-length cycling mode
For code shapes that must **never grow** (airline-PNR-style), `CyclingDealcode`
issues codes that are always exactly `length` characters. The counter space is
spent in cycles of `capacity() = radix^length` codes each; when a cycle is
exhausted, the next cycle refills the *same* code space through a different
permutation (SPEC §11).
```rust
use dealcode::CyclingDealcode;
fn main() -> Result<(), dealcode::Error> {
let pnr = CyclingDealcode::builder("your-secret-key")
.alphabet("crockford")
.length(6)
.domain("bookings")
.build()?;
let n: u64 = 3_000_000_007; // from your sequence
// counter n belongs to cycle n / pnr.capacity()
let code = pnr.encode(n)?; // always exactly 6 characters
let cycle = pnr.cycle_of(n)?; // store this next to the code!
assert_eq!(pnr.decode(&code, cycle)?, n); // the cycle is required
Ok(())
}
```
Configuration mirrors `Dealcode` (key, alphabet, domain) with a single fixed
`length`: `2 <= length <= 128` and `100 <= radix^length <= 2^63`.
**Operational rule:** codes *repeat* across cycles by design, so a global
`UNIQUE(code)` index spanning cycles WILL fire — scope uniqueness as
`UNIQUE(cycle, code)`, keep at most one cycle's codes live at a time per scope
(retire or expire cycle `e` before issuing from `e+1`), and persist each live
code's cycle (or the currently active cycle): `decode` needs it, and the
library cannot recover the cycle from the code string. Decoding with a wrong
(but in-range) cycle is *not* an error — it silently returns a different
counter; the existence check on the decoded counter is what catches it.
## Thread safety & performance
A `Dealcode` instance is immutable and `Send + Sync`; create one per namespace
at startup and share it freely (e.g. in an `Arc` or a `static`). AES round
keys and per-length FF1 parameters are precomputed at build time; encoding is
ten AES-CBC-MAC rounds — a few microseconds, O(1) in the counter value, no
locks.
## Interoperability
This crate implements format version 1 of the spec exactly and passes the
official NIST FF1-AES sample vectors plus the shared
[`testvectors/`](https://github.com/algorix-hq/dealcode/tree/main/testvectors)
suite; codes are byte-for-byte identical to those produced by every other
conforming implementation (e.g. the
[Python package](https://github.com/algorix-hq/dealcode/tree/main/python)).
## Running the tests
From `rust/`:
```sh
cargo test
cargo clippy --all-targets -- -D warnings
```
The suite covers the official NIST FF1 sample vectors, every shared
cross-language vector in
[`testvectors/`](https://github.com/algorix-hq/dealcode/tree/main/testvectors),
behavioural cases, and doctests.
## License
MIT — see [LICENSE](https://github.com/algorix-hq/dealcode/blob/main/LICENSE).