DEV Community: yuus_company

API key design: entropy math, prefixes, and why sk_live_ is genius

yuus_company — Sun, 06 Sep 2026 04:41:06 +0000

At some point every backend grows an API key system. Most teams improvise the format — and the format matters more than you'd think. Here's the 10-minute version of what I wish I'd known.

1. Length is entropy — do the math once

The security of a key comes from its random body. With a character set of size C and body length L:

entropy = L × log₂(C) bits

Some real numbers for the usual A-Za-z0-9 set (C = 62, log₂ ≈ 5.95):

Body length	Entropy	Verdict
16 chars	~95 bits	weak-ish for a public key
22 chars	~131 bits	the common baseline (≥128 bits)
32 chars	~190 bits	comfortable margin, still short enough to handle

If you exclude look-alike characters (0/O, 1/l/I) for human readability, the set shrinks — just add 2–3 characters of length and you're back to the same strength.

(A UUID v4, by the way, is 122 bits. It clears the bar, but keeps reading...)

2. The prefix is not decoration

Stripe's sk_live_ / sk_test_ and GitHub's ghp_ prefixes do three jobs:

Environment safety — you can tell at a glance (and assert in code!) that a test key never hits production endpoints.
Incident triage — when a key fragment shows up in a log or error report, the prefix tells you instantly which environment leaked.
Secret scanning — this is the big one. A distinctive prefix is a regex-able pattern. GitHub secret scanning, truffleHog, and friends can detect your keys in public commits and auto-revoke them. A bare random string or UUID is invisible to these tools.

This is why "just use a UUID" is the wrong answer even though the entropy is fine.

3. Storage rules (the part everyone gets wrong)

Hash the key server-side (SHA-256 is fine — keys are high-entropy, unlike passwords, so you don't need bcrypt's slowness). Store the hash, compare hashes on auth.
Show the plaintext exactly once, at issue time. If the user loses it, they rotate.
Keep a short displayable suffix (...x7Kq) so users can identify keys in a dashboard without you storing the secret.
Track created / expires / last-used per key and reap unused ones.
Have a rotation path before you need it: issue new → dual-accept window → revoke old.

4. Prototyping a format

Before committing to a format, it's worth generating a batch and looking at it: does it survive double-click selection? Does it wrap badly in your docs? Is the chunked version (XXXX-XXXX-...) actually more readable for your case?

I put together a small API key generator for exactly this — configurable prefix, body length, chunking, and character rules, generated locally with crypto.getRandomValues (nothing sent to any server). Handy for staging keys and for eyeballing format candidates with your team.

TL;DR

≥128 bits of entropy: 22+ random chars over A-Za-z0-9.
Always use a distinctive prefix — it's what makes secret scanning work.
Store hashes, show plaintext once, track usage, plan rotation.
UUIDs pass the entropy test but fail the operability test.

No, you can't decrypt a bcrypt hash — here's what to do instead

yuus_company — Sun, 06 Sep 2026 04:41:04 +0000

"bcrypt decode", "bcrypt hash to text", "bcrypt decrypt online" — these searches get thousands of hits a month, and every result promising to do it is either confused or a scam. Let's clear this up properly.

bcrypt is a hash, not encryption

Encryption is a two-way street: encrypt with a key, decrypt with a key. A hash is a one-way function by design. bcrypt takes a password and produces a fixed digest; there is no key, and no inverse function exists. This isn't a limitation to work around — it's the entire point. If a database leaks, the attacker gets digests, not passwords.

So when someone asks "how do I decrypt this bcrypt hash?", the real question is almost always one of these three:

Case 1: "I need to check if a password matches"

You never decode the hash — you hash the candidate password with the same salt and compare. Every bcrypt library does this for you:

// Node.js
const bcrypt = require("bcryptjs");
const ok = await bcrypt.compare("hunter2", storedHash); // true / false

# Python
import bcrypt
ok = bcrypt.checkpw(b"hunter2", stored_hash)

The salt is embedded in the hash string itself (that's what the $2b$10$... prefix carries), so compare needs nothing else.

Case 2: "A user forgot their password"

You can't recover it, and that's correct behavior. The only legitimate flow is a reset: send a time-limited, single-use token to a verified channel, let the user set a new password, hash the new one. Any site that can email you your old password is storing it wrong — treat that as a red flag as a user, and never build it as a developer.

Case 3: "I'm testing / doing a CTF and need to crack it"

What people call "decrypting" here is really guessing: hash candidate passwords until one matches. Tools like hashcat automate this against wordlists. This is exactly the attack bcrypt is built to resist — its work factor (cost) makes each guess slow, so strong passwords remain out of reach even offline. It works only against weak passwords, and only do this on systems you're authorized to test.

Reading a bcrypt string

$2b$10$N9qo8uLOickgx2ZMRZoMye.IjPeVUxkJDrz8vd3AJlDpMH0W3iBGe
 │  │  └──────────┬─────────┘└──────────────┬───────────────┘
 │  │            salt (22 chars)          digest (31 chars)
 │  └─ cost factor: 2¹⁰ = 1,024 rounds
 └─ algorithm version

The cost factor is the tunable part. 10 is a common default; raise it as hardware gets faster. Each +1 doubles the work.

Try it yourself

If you want to see how the same password produces different hashes (random salt) and how compare still works, I built a small bcrypt hash generator that runs entirely in the browser — generate, tweak the cost factor, and verify, with nothing sent to a server.

TL;DR

bcrypt cannot be decrypted. Nothing can "convert a bcrypt hash to text."
To verify: bcrypt.compare(candidate, hash).
Forgot password → reset flow, never recovery.
"Cracking" = brute-force guessing, which bcrypt deliberately makes slow.

JSON to Kotlin data class: Gson vs Moshi vs kotlinx.serialization annotations

yuus_company — Sun, 06 Sep 2026 04:41:02 +0000

Turning a JSON payload into a Kotlin data class looks trivial until you hit the details: which annotations, what about snake_case, what happens to missing fields? The answers differ meaningfully across the three mainstream libraries. Here's the same payload, three ways.

The JSON:

{
  "user_id": "u-1042",
  "display_name": "Yush",
  "is_verified": true,
  "follower_count": 1204,
  "last_login": null
}

Gson

data class UserProfile(
    @SerializedName("user_id") val userId: String,
    @SerializedName("display_name") val displayName: String,
    @SerializedName("is_verified") val isVerified: Boolean,
    @SerializedName("follower_count") val followerCount: Int,
    @SerializedName("last_login") val lastLogin: String?
)

The catch everyone learns the hard way: Gson ignores Kotlin null-safety. It uses reflection and will happily write null into a non-nullable val if the field is missing — you get the crash later, far from the parse site. Default values are also ignored unless every field has one. Gson is fine for legacy codebases, but it predates Kotlin and it shows.

Moshi (with KSP codegen)

@JsonClass(generateAdapter = true)
data class UserProfile(
    @Json(name = "user_id") val userId: String,
    @Json(name = "display_name") val displayName: String,
    @Json(name = "is_verified") val isVerified: Boolean,
    @Json(name = "follower_count") val followerCount: Int,
    @Json(name = "last_login") val lastLogin: String?
)

With codegen (generateAdapter = true), Moshi enforces nullability at parse time: a missing non-nullable field throws a clear JsonDataException naming the field. Default values work as expected. This is the pragmatic choice for Android projects already on OkHttp/Retrofit.

kotlinx.serialization

@Serializable
data class UserProfile(
    @SerialName("user_id") val userId: String,
    @SerialName("display_name") val displayName: String,
    @SerialName("is_verified") val isVerified: Boolean,
    @SerialName("follower_count") val followerCount: Int,
    @SerialName("last_login") val lastLogin: String? = null
)

Compiler-plugin based, zero reflection, multiplatform (JVM/JS/Native/Wasm). Two behaviors worth knowing: unknown JSON keys fail by default (turn on ignoreUnknownKeys = true in the Json {} config for API work), and fields with default values are skipped during serialization unless you set encodeDefaults = true. If you're starting fresh or targeting KMP, this is the one.

Quick comparison

	Gson	Moshi (codegen)	kotlinx.serialization
Null-safety enforced	❌ silently breaks	✅ throws clearly	✅ throws clearly
Default values	unreliable	✅	✅
Reflection at runtime	yes	no (codegen)	no (compiler plugin)
Multiplatform	❌	❌	✅
Best for	legacy code	Android + Retrofit	new code, KMP

Generating the boilerplate

Writing @SerialName for thirty fields by hand is nobody's idea of fun. I use this JSON to Kotlin converter — paste the payload, and it derives the data class with nested classes and nullable types from the actual values, in the browser (nothing uploaded). Then switch the annotations to whichever library your project uses.

TL;DR

Gson silently violates Kotlin null-safety; prefer Moshi or kotlinx.serialization.
Moshi: best drop-in for Android/Retrofit stacks.
kotlinx.serialization: default for new projects and multiplatform — remember ignoreUnknownKeys.

Avro schemas for Kafka developers: the 10-minute practical guide

yuus_company — Sun, 06 Sep 2026 04:41:00 +0000

If you work with Kafka long enough, someone puts Avro in front of you. The docs are dense, so here's the working knowledge you actually need: what a schema looks like, the two rules that cause 90% of production errors, and how to debug a binary payload.

Why Avro instead of JSON?

Two reasons: size (binary encoding, field names aren't repeated in every message — a JSON message of 500 bytes often becomes ~100) and contracts (the schema is enforced at produce time, so a malformed message never enters the topic). With a schema registry, consumers always know how to decode what producers wrote — including messages written under older schema versions.

The schema, minimally

{
  "type": "record",
  "name": "OrderCreated",
  "namespace": "com.shop.events",
  "fields": [
    { "name": "orderId", "type": "string" },
    { "name": "amount", "type": "long" },
    { "name": "currency", "type": "string", "default": "KRW" },
    { "name": "couponCode", "type": ["null", "string"], "default": null }
  ]
}

The parts that trip people up:

There is no "optional" keyword. An optional field is a union with null — ["null", "string"] — and the default must be null, with "null" listed first in the union. Order matters; ["string", "null"] with a null default is invalid.
Defaults are not runtime fallbacks. A default is used when a reader decodes data written by an older schema that lacked the field. Producers still must set every field.
Timestamps are long with a logical type: { "type": "long", "logicalType": "timestamp-millis" }.

The two evolution rules that matter

Schema evolution is why Avro exists, and it boils down to:

Adding a field? It must have a default. Otherwise old messages can't be read with the new schema (BACKWARD compatibility breaks — the registry will reject it).
Removing a field? Only remove fields that had a default. Never rename — a rename is a remove plus an add, and old data loses the value silently. Add an alias instead.

Everything else (changing types, reordering unions) — check against your registry's compatibility mode before assuming.

Debugging: "what's actually in this message?"

Binary Avro is unreadable in kafka-console-consumer, and the classic gotcha is the magic byte: messages produced through Confluent serializers carry a 5-byte header (0x00 + 4-byte schema ID) before the Avro payload. If your decoder chokes immediately, that header is usually why.

For quick inspection without spinning up kafka-avro-console-consumer, I use these browser tools (client-side only, nothing uploaded):

Avro decoder — paste base64/hex bytes + the schema, get JSON back
Avro schema generator — paste a sample JSON message, get a starting-point schema with proper null unions
Avro message generator — generate test payloads from a schema

TL;DR

Optional field = ["null", "type"], null first, default null.
New fields need defaults; never rename, alias instead.
Defaults serve schema evolution, not producer laziness.
Decoder failing on byte 0? Strip the 5-byte Confluent header.

How to verify a file checksum on macOS, Linux, and Windows (and why you should)

yuus_company — Sun, 06 Sep 2026 03:28:01 +0000

You download an installer, a firmware image, or a database dump. Next to the download link the site lists something like:

SHA-256: 3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b

Most people ignore it. Here's why you shouldn't, and the fastest way to check it on every OS.

What a checksum actually proves

A cryptographic hash (SHA-256, MD5, ...) is a fingerprint of a file's exact bytes. If even one bit changes — a corrupted download, a truncated transfer, or a tampered binary — the hash changes completely.

Comparing your local hash against the published one proves two things:

Integrity — the file wasn't corrupted in transit.
Authenticity (partially) — the file is the one the publisher hashed. (Full authenticity needs a signature, but a checksum from a trusted HTTPS page is a solid baseline.)

The commands, per OS

macOS / Linux:

shasum -a 256 file.zip     # works on both
sha256sum file.zip         # Linux (coreutils)
md5 file.zip               # macOS MD5
md5sum file.zip            # Linux MD5

Windows (cmd):

certutil -hashfile file.zip SHA256

Windows (PowerShell):

Get-FileHash file.zip -Algorithm SHA256

Then eyeball-compare the output against the published value — or pipe it:

echo "3a7bd3e2...  file.zip" | shasum -a 256 -c

Which algorithm should you trust?

Algorithm	Verdict
MD5	Fine for duplicate detection and cache keys. Not for security — collisions are practical.
SHA-1	Legacy compatibility only.
SHA-256	The default. Use this.
SHA-512	Also fine; sometimes faster than SHA-256 on 64-bit CPUs.

The rule of thumb: if an attacker could benefit from forging a matching file, MD5 and SHA-1 are out.

When you don't have a terminal handy

Sometimes you're on a locked-down machine, or you just want to check a file quickly without remembering flags. Browser-based tools can hash files locally with the Web Crypto API — the file never leaves your machine.

I use this file hash tool: drag the file in, paste the expected checksum, and it auto-detects which algorithm matches. It streams large files in 8MB chunks, so multi-GB files work without freezing the tab.

Whatever tool you use, verify that it computes hashes client-side — uploading a sensitive file to hash it defeats the purpose.

TL;DR

Always check the checksum for installers, firmware, and backups.
shasum -a 256 / certutil -hashfile ... SHA256 / Get-FileHash cover every OS.
Prefer SHA-256. Keep MD5 for non-adversarial jobs.
Browser tools work too, as long as hashing happens locally.