Forem: Nathan Lucas

Stop Exposing Your Data: How to Pack IDs, UUIDs, and More with Obfusbit

Nathan Lucas — Mon, 04 Aug 2025 19:01:06 +0000

In our previous article, we explored the basics of using the Obfuskey class to reversibly obfuscate single integer IDs. This is a great pattern for cleaning up simple, sequential database IDs.

But what if you need to do more? What if you have multiple pieces of information you want to embed into a single, compact key? This is where the true power of the package shines through with the Obfusbit class.

Obfusbit allows you to pack multiple integer values into a single, obfuscated key string. This is perfect for when you need to embed several pieces of information, such as a user ID and a product ID, into a single token, which can lead to more efficient API calls and fewer database lookups.

Where to Find Obfuskey

You can find the full source code, documentation, and open an issue on the project's GitHub repository. Obfuskey on GitHub

Packing Multiple Values with Obfusbit

To get started with Obfusbit, you define a "schema" that specifies the name and bit length for each value you want to pack. Let's use the BASE62 alphabet, which is a great default for URL-friendly keys as it includes both uppercase and lowercase letters and digits.

from obfuskey import Obfuskey, Obfusbit, alphabets  

# Define a schema for your data  
product_schema = [  
    {"name": "category_id", "bits": 4},  # Max value 15  
    {"name": "item_id", "bits": 20},     # Max value ~1 million  
    {"name": "status", "bits": 3},      # Max value 7  
]  

# Initialize Obfusbit with a schema and BASE62 alphabet  
obfkey = Obfuskey(alphabets.BASE62, key_length=10)  
obfuscator = Obfusbit(product_schema, obfuskey=obfkey)  

# Pack your values  
packed_key = obfuscator.pack(values={"category_id": 5, "item_id": 123456, "status": 1})  
print(f"Packed Key: {packed_key}")           # 42930689

# Unpack the key to retrieve the original values  
unpacked_values = obfuscator.unpack(packed_key)  
print(f"Unpacked Values: {unpacked_values}") # {'status': 1, 'item_id': 123456, 'category_id': 5}

A More Advanced Use Case: Packing UUIDs and Saving Database Lookups

While Obfuskey is fantastic for integer IDs, what about universally unique identifiers (UUIDs)? Many modern applications use UUIDs as primary keys to avoid collisions in distributed systems.

This 128-bit integer representation of a UUID is exactly what Obfusbit can work with. The key insight here is that you can pack a UUID into an Obfusbit key string, and when you unpack it, you get the original integer back, which can then be converted back to a UUID object.

For this advanced use case, we'll stick with the robust BASE62 alphabet for its excellent balance of key length and character set.

import uuid  
from obfuskey import Obfuskey, Obfusbit, alphabets  

# Define a schema with a UUID and a small integer  
# A UUID is 128 bits long  
product_schema = [  
    {"name": "category_id", "bits": 8},  
    {"name": "product_uuid", "bits": 128},  
]  

# Initialize Obfusbit with a BASE62 alphabet and a key length of 30  
# This combination gives us plenty of room for our 136 bits of data  
obfkey = Obfuskey(alphabets.BASE62, key_length=30)  
obfuscator = Obfusbit(product_schema)  

# Let's mock a database lookup  
category_id = 42  
product_uuid = uuid.uuid4()  

# Pack the values into a single key  
values = {"category_id": category_id, "product_uuid": product_uuid.int}  
packed_key = obfuscator.pack(values=values)  
print(f"Packed Key: {packed_key}")  

# On the server, we unpack it  
unpacked_values = obfuscator.unpack(packed_key)  
retrieved_uuid = uuid.UUID(int=unpacked_values["product_uuid"])  
print(f"Retrieved UUID: {retrieved_uuid}")

How Does This Save Database Lookups?

This is where the real power comes in. In a traditional setup, if you have a URL like /products/books/123e4567..., you would have to perform a database lookup on the products table using the UUID. Then, you might need another lookup on the categories table to verify the category.

With Obfusbit, you can embed this information directly into the URL. You unpack the key and instantly have the category_id and the product_uuid. This means you can validate the category and perform your single product lookup without an additional database query. The key becomes a self-contained token of data, making your API more efficient and your code cleaner.

More Than Just a UUID: Squeezing More into Your Keys

You can pack additional bits of data, as long as the total bit length of your schema fits within the capacity of your chosen key length and alphabet. For example, packing multiple UUIDs into a single key.

Let's use the BASE58 alphabet for our final example. It's often used for cryptocurrencies and is very similar to BASE56 but excludes the ambiguous characters for better transcription and manual entry.

import uuid  
from obfuskey import Obfuskey, Obfusbit, alphabets  

# Schema for a user's interaction with a product  
interaction_schema = [  
    {"name": "user_uuid", "bits": 128},  
    {"name": "product_uuid", "bits": 128},  
    {"name": "interaction_type", "bits": 3}, # e.g., 1=like, 2=review  
]  

# Total bits: 128 + 128 + 3 = 259 bits  
# We need an even larger key capacity. A key length of 45 with BASE58 will do.  
obfkey = Obfuskey(alphabets.BASE58, key_length=45)  
obfuscator = Obfusbit(interaction_schema, obfuskey=obfkey)  

# Mock two UUIDs and an interaction type  
user_uuid = uuid.uuid4()  
product_uuid = uuid.uuid4()  
interaction_type = 1 # A 'like'  

values = {  
    "user_uuid": user_uuid.int,  
    "product_uuid": product_uuid.int,  
    "interaction_type": interaction_type,  
}  
packed_key = obfuscator.pack(values=values)  

print(f"Packed Key (Base58): {packed_key}")  

unpacked_values = obfuscator.unpack(packed_key)  
retrieved_user_uuid = uuid.UUID(int=unpacked_values["user_uuid"])  
retrieved_product_uuid = uuid.UUID(int=unpacked_values["product_uuid"])  

assert retrieved_user_uuid == user_uuid  
assert retrieved_product_uuid == product_uuid

Important Considerations

Not for Security: Remember, Obfuskey is not a cryptographic library. It's designed to make your IDs non-sequential and less predictable, not to protect sensitive information from being decoded.
Key Length and Alphabet: The combination of your chosen alphabet and key length determines the maximum integer value that can be obfuscated. You can calculate this with the formula: (len(alphabet) ** key_length) - 1. Make sure this value is large enough to handle your highest possible ID.

Conclusion

Obfusbit is a simple yet powerful tool for any Python developer who needs to create "pretty" and secure-looking, but easily reversible, identifiers. By leveraging its flexible alphabet system and powerful bit-packing capabilities, you can clean up your URLs, reduce database queries, and build more performant, elegant, and secure-looking applications.

Stay tuned for the next articles in the series, where we'll explore how to use Obfuskey in JavaScript/TypeScript and, finally, how to build a full-stack, cross-language API with these tools.

Don't Expose Your IDs: An Introduction to Obfuskey in Python

Nathan Lucas — Thu, 31 Jul 2025 22:19:00 +0000

As developers, we often deal with integer IDs in our databases. They are simple, efficient, and great for internal use. But what happens when you expose these IDs to the outside world? A URL like your-app.com/post/1 followed by your-app.com/post/2 can give away a lot of information. It reveals the total number of posts, the rate at which new posts are created, and can even make it easier for malicious actors to scrape your data.

Where to Find Obfuskey

You can find the full source code, documentation, and open an issue on the project's GitHub repository. Obfuskey on GitHub

The Ecosystem of Reversible Obfuscation

Exposing a sequential primary key is a common practice, but it's not without its drawbacks. When choosing a solution to obfuscate these IDs, developers often consider a few popular options. Here’s a look at how Obfuskey compares to some of the key players in the Python ecosystem.

Alternative	How it Works	Pros	Cons
Hashids	Creates short, unique strings from integers based on a salt and alphabet.	Keys are short, non-sequential, and human-friendly.	Output length can vary with input magnitude. Less precise control over key length.
Sqids	A modern, flexible alternative to Hashids for obfuscating multiple numbers.	Keys are often shorter, more random-looking, and avoid separator characters.	Also has variable output length depending on input magnitude.
ShortUUID	Creates short, URL-safe versions of standard UUIDs.	Keys are guaranteed to be unique and short. Great for shortening existing UUIDs.	Not designed for obfuscating sequential integers; it shortens UUIDs, which are already non-sequential.
Obfuskey	Reversible, non-cryptographic obfuscation of integers using a custom alphabet and fixed length.	Reversible without a database lookup. Keys have a guaranteed fixed length. Full control over the character set.	Not a cryptographic tool; should not be used for security-sensitive data.

Why Choose Obfuskey?

Obfuskey stands out for its clear API, precise control over a fixed-length output, and a core focus on reversible obfuscation. It provides a simple, robust solution without the overhead of more complex cryptographic or hashing libraries.

Getting Started with Obfuskey

First, let's install the library.

pip install obfuskey

Now, let's see it in action. The core of Obfuskey is the Obfuskey class. When you instantiate it, you can specify the alphabet of characters to use and the desired key length.

For our first example, let's use the BASE56 alphabet, which is designed to be URL-safe and human-friendly by avoiding characters that can be easily confused, like 0 and O, or 1 and l.

from obfuskey import Obfuskey, alphabets

# Initialize Obfuskey with the BASE56 alphabet and a key length of 8
obfuscator = Obfuskey(alphabets.BASE56, key_length=8)

# Let's obfuscate an integer ID
original_id = 1234567890
obfuscated_key = obfuscator.get_key(original_id)

print(f"Original ID: {original_id}")       # 1234567890
print(f"Obfuscated Key: {obfuscated_key}") # SdkkpiUc

# Now, let's reverse the process
retrieved_id = obfuscator.get_value(obfuscated_key)

print(f"Retrieved ID: {retrieved_id}")     # 1234567890

# Let's see what happens with a different ID
another_id = 1234567891
another_key = obfuscator.get_key(another_id)

print(f"Another ID: {another_id}")         # 1234567891
print(f"Another Key: {another_key}")       # 5FvRbydm

Notice how obfuscated_key and another_key are completely different, even though the original IDs are sequential. This is because Obfuskey uses a randomized mapping to ensure sequential inputs produce non-sequential outputs.

Customizing Your Obfuscation with Different Alphabets

Obfuskey provides several predefined alphabets for different use cases. You can choose one that best fits your needs, from short and compact to fully URL-safe.

For a very compact key that's perfect for internal APIs or systems where readability isn't a concern, you might use BASE64_URL_SAFE.

# Using a URL-safe Base64 alphabet for a shorter, more compact key
from obfuskey import Obfuskey, alphabets

compact_obfuscator = Obfuskey(alphabets.BASE64_URL_SAFE, key_length=6)

compact_key = compact_obfuscator.get_key(1001)
print(f"Compact Key (Base64): {compact_key}") # fkhvWj

compact_value = compact_obfuscator.get_value(compact_key)
print(f"Original Value: {compact_value}")     # 1001

You can even create your own custom alphabet to perfectly match your brand or application's needs. The key is that every character in your custom alphabet must be unique, just like the digits in a number system.

# A custom alphabet using only a unique set of memorable characters
from obfuskey import Obfuskey

custom_alphabet = "0123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefgh" # A unique 44-character alphabet
custom_obfuscator = Obfuskey(custom_alphabet, key_length=10)

custom_key = custom_obfuscator.get_key(987654321)
print(f"Custom Key: {custom_key}")       # MQ6gA5LPTT

custom_value = custom_obfuscator.get_value(custom_key)
print(f"Original Value: {custom_value}") # 987654321

This level of customization gives you full control over the appearance and predictability of your obfuscated keys, allowing you to tailor them exactly to your use case.

Conclusion

The Obfuskey class is a powerful tool for obscuring sequential integer IDs into reversible, non-predictable keys. This simple pattern can dramatically improve the aesthetics and security-by-obscurity of your application's URLs and identifiers.

In the next article, we'll dive into an even more powerful feature of this package: Obfusbit, which allows you to pack multiple values into a single key, including large numbers like UUIDs.

Cattri: The Ruby DSL for Clean, Scalable Class and Instance Attributes

Nathan Lucas — Wed, 23 Apr 2025 01:47:00 +0000

GitHub: https://github.com/bnlucas/cattri

Ruby gives us tools like attr_accessor, and Rails builds on this with class_attribute, cattr_accessor, and more—but if you’ve ever wrestled with their inconsistencies around visibility, subclassing, or defaults, you’re not alone.

Cattri is a minimal-footprint Ruby DSL for defining both class- and instance-level attributes with clarity, safety, and control. Let's explore what makes it a better alternative.

The Problem with Existing Attribute APIs

Ruby’s attr_* respects visibility but doesn’t support class-level or subclass-safe behavior. Rails’ class_attribute handles subclassing but ignores visibility and requires ActiveSupport. If you're building a gem and want both, you’re forced to either duplicate logic manually or take on a heavyweight dependency.

Feature/Behavior	Cattri	`attr_*` (Ruby)	`cattr_accessor` (Rails)	`class_attribute` (Rails)
🔁 Subclass-safe value duplication	✅	❌	❌	✅
🔒 Subclass-safe metadata inheritance	✅	❌	❌	✅
👁 Respects Ruby visibility (private, etc.)	✅	✅	❌	❌
🌀 Lazy defaults (via lambdas)	✅	❌	⚠️ (writer-only)	✅
🧱 Static defaults	✅	❌	⚠️ (manual)	✅
🧼 Coercion support (e.g., `->(val) { !!val }`)	✅	❌	❌	❌
🧠 Introspection (list defined attrs)	✅	❌	❌	❌
🧪 Strict error handling for missing definitions	✅	❌	❌	❌
🧩 Unified class + instance attribute API	✅	❌	❌	⚠️ (instance_reader)
⚖️ No ActiveSupport dependency	✅	✅	❌	❌

Using Ruby's `attr_accessor` for Class-Level Attributes

class Base
  class << self
    attr_accessor :config
  end
end

Base.config = { debug: false }

class Sub < Base
  self.config[:debug] = true
end

Base.config[:debug] # => true ❌ shared state

What's required?

✅ Manual class << self block
❌ Shared state across all subclasses
❌ No default support
❌ No visibility control
❌ No metadata or coercion
❌ No per-subclass copy

Using Cattri's `cattr`

class Base
  include Cattri
  cattr :config, default: -> { { debug: false } }
end

class Sub < Base
  config[:debug] = true
end

Base.config[:debug] # => false ✅ safe isolation

Using Ruby's `attr_accessor` for Instance-Level Attributes

class Base
  attr_accessor :config

  def initialize
    @config = { debug: false }
  end
end

class Sub < Base
  def initialize
    super
    @config = @config.dup  # required to avoid shared mutation
    @config[:debug] = true
  end
end

a = Base.new
b = Sub.new

a.config[:debug] # => false
b.config[:debug] # => true

What's required?

✅ Manual initialize boilerplate
✅ Explicit default values
✅ Defensive dup to avoid shared state
❌ No metadata, coercion, or introspection

Using Cattri's iattr

class Base
  include Cattri
  iattr :config, default: -> { { debug: false } }
end

class Sub < Base
  def initialize
    super
    config[:debug] = true
  end
end

Using Rails' `class_attribute`

class Base
  class_attribute :config
  class_attribute :api_key # public visibility
end

Base.config = { debug: false }

class Sub < Base
  self.config[:debug] = true
end

Base.config[:debug] # => false ✅ isolated

Benefits of class_attribute

✅ Subclass-safe value isolation (via dup)
✅ Optional instance reader/writer
❌ No visibility support
❌ No default value support (manual setup)
❌ No coercion, or introspection
⚠️ Requires ActiveSupport

To support defaults:

class Base
  class_attribute :config
  self.config = { debug: false } # must define manually
end

Using Cattri's `cattr`

class Base
  include Cattri
  cattr :config, default: -> { { debug: false } }

  private
  cattr :api_key # private visibility
end

class Sub < Base
  config[:debug] = true
end

Base.config[:debug] # => false ✅ isolated

Feature	`class_attribute` (Rails)	`cattr` (Cattri)
Subclass-safe value?	✅	✅
Metadata inheritance?	✅	✅
Default values?	❌ (must set manually)	✅ (static or lazy)
Visibility tracking?	❌	✅
Coercion support?	❌	✅
Introspection?	❌	✅
Requires ActiveSupport?	✅	❌

Why Cattri?

Cattri brings modern, minimal, and predictable behavior to attribute definition in Ruby. Whether you're building a DSL, gem configuration system, or just want clean subclass behavior without reaching for ActiveSupport, Cattri gives you:

Consistent class and instance attribute semantics
Subclass-safe isolation without boilerplate
Visibility-aware definitions that feel native to Ruby

If you’ve ever worked around the limitations of attr_*, cattr_accessor, or class_attribute, Cattri was built to make that pain go away—for good.

Try it, use it in a gem, subclass it, and see how it holds up.

Installation

bundle add cattri

Or add it in your Gemfile

gem "cattri"

Explore more or contribute: https://github.com/bnlucas/cattri

Forem: Nathan Lucas

Stop Exposing Your Data: How to Pack IDs, UUIDs, and More with Obfusbit

Where to Find Obfuskey

Packing Multiple Values with Obfusbit

A More Advanced Use Case: Packing UUIDs and Saving Database Lookups

How Does This Save Database Lookups?

More Than Just a UUID: Squeezing More into Your Keys

Important Considerations

Conclusion

Don't Expose Your IDs: An Introduction to Obfuskey in Python

Where to Find Obfuskey

The Ecosystem of Reversible Obfuscation

Why Choose Obfuskey?

Getting Started with Obfuskey

Customizing Your Obfuscation with Different Alphabets

Conclusion

Cattri: The Ruby DSL for Clean, Scalable Class and Instance Attributes

The Problem with Existing Attribute APIs

Using Ruby's attr_accessor for Class-Level Attributes

Using Cattri's cattr

Using Ruby's attr_accessor for Instance-Level Attributes

Using Rails' class_attribute

Using Cattri's cattr

Why Cattri?

Installation

Using Ruby's `attr_accessor` for Class-Level Attributes

Using Cattri's `cattr`

Using Ruby's `attr_accessor` for Instance-Level Attributes

Using Rails' `class_attribute`

Using Cattri's `cattr`