Download the PHP package niktomo/kasumi without Composer

Kasumi 霞

日本語 | English

Reversible 63-bit integer scrambling for Laravel — no bcmath, no GMP, no extra extensions.

The same scramble() call encodes and decodes — no separate methods needed.

Why

Sequential integer IDs are a liability when exposed in URLs or API responses:

• Enumeration — an attacker iterates /users/1, /users/2, … to harvest data or probe for IDOR vulnerabilities.
• Business intelligence leakage — order ID 5983 tells a competitor "this store has ~6000 orders." Two observations an hour apart reveal the transaction rate.
• User-count estimation — in social games and SaaS products, sequential user IDs let rivals track your growth in real time.

Kasumi scrambles IDs into opaque, fixed-length strings at the application layer, keeping your database schema and indexes untouched.

Obfuscation, not encryption. Kasumi hides the structure of IDs but does not provide cryptographic security. The salt space is 32 bits (~2 billion values), which is brute-forceable given enough known plaintext pairs. Do not rely on Kasumi as the sole defence against unauthorized access. Always enforce server-side authorization checks independently.

How it works

Based on this algorithm, applied independently to the upper 32 bits and lower 32 bits of the input:

The function is involutory — applying it twice returns the original value:

• salt × x mod 2³² — multiplication disperses bits across the 32-bit space
• reverseBits32(…) — bit reversal mixes upper and lower halves
• inverseSalt × … — multiplication by the modular inverse makes the whole operation self-inverse

All arithmetic uses native PHP integers. No bcmath or GMP required.

Compared to alternatives

Requirements

• PHP ^8.2
• Laravel ^12.0

Installation

Generate a salt and write it to .env:

This adds KASUMI_SCRAMBLE_SALT=<odd integer> to your .env. Keep this value secret and stable — changing it invalidates all existing scrambled values.

Usage

Facade

Dependency Injection

Standalone (without Laravel)

Custom Encoder

Implement Kasumi\Encoder to use a different string representation:

ChecksumEncoder

ChecksumEncoder is a decorator that wraps any Encoder and adds tamper detection. It appends a 5-character base36 checksum derived from the inner encoding:

• 2-character prefix — prepended to the output for a quick validity check
• 3 filler characters — inserted at fixed positions inside the body as noise

Output length is 2 + innerLength + 3. With Base36Encoder (14 chars), the total is 19 characters.

decode() throws \InvalidArgumentException for any string that was not produced by this encoder — wrong length, tampered prefix, or tampered body all fail.

ChecksumEncoder can also wrap a custom encoder:

Artisan Commands

Config

Publish the config file:

config/kasumi.php:

Notes

• scramble(0) returns 0 (trivial fixed point). Avoid passing 0 if this is a concern.
• Valid input range: [0, PHP_INT_MAX] (63-bit non-negative integers).
• The salt must be an odd integer. kasumi:salt:generate guarantees this.
• No bcmath or GMP extension required — all arithmetic uses native PHP integers.
• The encoded string is always exactly 14 characters (two zero-padded base36 halves) when using Base36Encoder, or 19 characters when wrapped with ChecksumEncoder.
• To unscramble, pass the ScrambledValue directly to scramble(). Avoid calling toInt() on the scrambled value before passing it back, as the intermediate value may exceed PHP_INT_MAX.

License

MIT