Skip to main content

Crate dealcode

Crate dealcode 

Source
Expand description

Collision-free, random-looking codes from a counter.

Dealcode maps a non-negative integer counter n (from a database sequence or any other source that never repeats) to a short, fixed-alphabet, random-looking string called a code, and back. The mapping is a keyed bijection (FF1 format-preserving encryption per NIST SP 800-38G), so two different counters can never produce the same code, and a code decodes back to its counter for anyone holding the key.

This crate implements format version 1 of the dealcode spec exactly; codes are byte-for-byte interoperable with every other conforming implementation.

§Quickstart

use dealcode::Dealcode;

let codec = Dealcode::new("0a1b...64-hex-chars-from-your-secret-manager")?;

let code = codec.encode(1)?;        // "421163" — 6 hex chars
assert_eq!(code.len(), 6);
assert_eq!(codec.decode(&code)?, 1); // never collides with any other counter

Codes start at min_length characters and grow by one character only when the current length is exhausted; the growth schedule, alphabet handling, and tweak derivation are all fixed by the spec.

§Configuration

use dealcode::Dealcode;

let coupons = Dealcode::builder("your-secret-key")
    .alphabet("crockford")   // human-friendly codes, e.g. "7Q4WKZ"
    .min_length(6)
    .max_length(10)
    .domain("coupons")       // same key, unrelated codes per domain
    .build()?;

let orders = Dealcode::builder("your-secret-key")
    .alphabet("dec")         // digits only
    .min_length(8)
    .domain("orders")
    .build()?;

let n = coupons.decode(&coupons.encode(42)?)?;
assert_eq!(n, 42);

Immutability rule: for a given code namespace, the entire configuration — key, alphabet, min_length, max_length, domain — must never change once codes have been issued.

§Keys

Any non-empty key material is accepted (Key): raw bytes of exactly 16/24/32 bytes are used directly as the AES key; any other bytes, and all strings (a hex-looking string is not auto-decoded), are expanded to an AES-256 key via SHA-256("dealcode/v1/kdf" ‖ material). Prefer at least 128 bits of randomness, e.g. openssl rand -hex 32.

Modules§

alphabets
Alphabet presets and normalization rules (SPEC.md §3).

Structs§

Builder
Configures and builds a Dealcode codec.
CyclingBuilder
Configures and builds a CyclingDealcode codec.
CyclingDealcode
A fixed-length cycling codec (dealcode mode v1c, SPEC.md §11): codes are always exactly length characters, and the counter space is spent in cycles of capacity = radix^length codes each.
Dealcode
A dealcode codec: a bijective counter <-> code mapping (SPEC.md).
Key
Key material for a Dealcode codec (SPEC.md §2.1).

Enums§

Error
All the ways dealcode can refuse to work, in three distinguishable kinds (SPEC.md §8).