Skip to content

Latest commit

 

History

History

java

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 

README.md

dealcode (Java)

Collision-free, random-looking codes from a counter. Java implementation of the dealcode spec.

Install

<dependency>
  <groupId>io.algorix</groupId>
  <artifactId>dealcode</artifactId>
  <version>1.0.1</version>
</dependency>

Requires Java 17+. Zero runtime dependencies — AES and SHA-256 come from the JDK's built-in JCE providers.

Quickstart

import io.algorix.dealcode.Dealcode;

Dealcode codec = Dealcode.builder()
        .key("0a1b...64-hex-chars-from-your-secret-manager")
        .build();

codec.encode(0);        // e.g. "767a5b"   (6 hex chars)
codec.encode(1);        // e.g. "421163"   never collides with any other counter
codec.decode("421163"); // 1 (given the encoding above)

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

Dealcode.builder()
    .key(bytesOrString)   // byte[] | String (required)
    .alphabet("hex")      // "dec" | "hex" | "base32" | "crockford" | "base36"
                          // | "base58" | "base62" | "base64url" | custom string
    .minLength(6)         // codes start at this length...
    .maxLength(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();
Dealcode coupon = Dealcode.builder().key(key).alphabet("crockford")
        .domain("coupons").build();                       // human-friendly, e.g. "7Q4WKZ"
Dealcode order = Dealcode.builder().key(key).alphabet("dec")
        .minLength(8).domain("orders").build();           // digits only
Dealcode fixed = Dealcode.builder().key(key).alphabet("hex")
        .minLength(16).maxLength(16).build();             // constant-length

The preset alphabet strings are exposed as constants on io.algorix.dealcode.Alphabets.

decode throws InvalidCodeException 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 throws CounterRangeException outside [0, codec.maxCounter()]. All errors subclass DealcodeException (an IllegalArgumentException). maxCounter() is the inclusive maximum — the counter space may be exactly 2^63 (e.g. 16-char hex), which doesn't fit a long as a count, but its maximum always does.

Fixed-length cycling mode

For code shapes that must never grow (airline-PNR-style), CyclingDealcode keeps a fixed length and uses the counter space in cycles: each cycle fills the entire radix^length code space exactly once, then the next cycle refills the same space through a different permutation (SPEC §11).

import io.algorix.dealcode.CyclingDealcode;

CyclingDealcode codec = CyclingDealcode.builder()
        .key(System.getenv("DEALCODE_KEY"))
        .alphabet("crockford")
        .length(6)                     // always exactly 6 chars; 2 <= L <= 128,
                                       // 100 <= radix^L <= 2^63
        .domain("bookings")
        .build();

String code = codec.encode(n);         // cycle is implied: n / capacity
long cycle = codec.cycleOf(n);         // persist this with the code!
long back = codec.decode(code, cycle); // == n; the cycle is required

Operational rule: codes repeat across cycles by design, so keep at most one cycle's codes live per uniqueness scope and store the cycle with each code — a global UNIQUE(code) index WILL fire; use UNIQUE(cycle, code) and retire cycle e's codes before issuing from cycle e + 1. Decoding under a wrong (but in-range) cycle is not an error — it returns a different counter — so the stored cycle is the source of truth.

capacity() returns a BigInteger because the per-cycle capacity may be exactly 2^63 (the largest allowed, e.g. an 8-char alphabet at length 21), which doesn't fit a signed long; maxCycle() (= (2^63 − 1) / capacity) always does.

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:

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
  ...
);
Dealcode codec = Dealcode.builder()
        .key(System.getenv("DEALCODE_KEY"))
        .domain("orders")
        .build();

String createOrder(Connection conn) throws SQLException {
    long n;
    try (ResultSet rs = conn.createStatement()
            .executeQuery("SELECT nextval('order_code_seq')")) {
        rs.next();
        n = rs.getLong(1);
    }
    String code = codec.encode(n);
    try (PreparedStatement ps =
            conn.prepareStatement("INSERT INTO orders (id, code) VALUES (?, ?)")) {
        ps.setLong(1, n);
        ps.setString(2, code);
        ps.executeUpdate();
    }
    return code;
}

Optional<Order> findOrder(Connection conn, String code) {
    long n;
    try {
        n = codec.decode(code);      // malformed codes never reach the DB
    } catch (InvalidCodeException e) {
        return Optional.empty();
    }
    return findOrderById(conn, n);
}

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.

Thread safety & performance

A Dealcode instance is immutable and thread-safe — the underlying AES Cipher is kept per-thread in a ThreadLocal — so create one per namespace at startup and share it freely. Encoding is ten AES-CBC-MAC rounds — a few microseconds, O(1) in the counter value.

Building & tests

mvn test    # runs the NIST FF1 vectors, the shared spec vectors, and behavioural tests

The conformance tests read ../testvectors/ from the repository root.

License

MIT — see LICENSE.