DEV Community: Alejandro Rodriguez

HMAC over JSON in TypeScript — why verify fails in production

Alejandro Rodriguez — Sun, 23 Aug 2026 03:01:14 +0000

In the previous post we treated bytes as Uint8Array and skimmed HMAC for a JSON body. The one-liner looked fine. Then production hit: client signs, server verifies, ok === false with the “same” payload.

This piece is only about that failure mode. HMAC is message authentication (integrity + authenticity with a shared secret). It is not encryption. It does not replace TLS. The examples use encloom; the habits apply with Web Crypto or @noble/hashes too.

Not a compliance guide. About bytes on the wire.

What HMAC actually signs

HMAC-SHA256 takes a key and a message, both as bytes. The tag is deterministic for that pair. If either side feeds different bytes—different UTF-8 of the secret, different JSON serialization, hex vs Base64 of the tag—verification fails even when humans “see the same JSON.”

import {
  hmacSha256SignSync,
  hmacSha256VerifySync,
} from "encloom/hmac";
import { utf8ToBuffer, bufferToBase64, base64ToBuffer } from "encloom/helpers/encoding";

const key = utf8ToBuffer("api-shared-secret");
const msg = utf8ToBuffer('{"action":"ping","id":1}');

const mac = hmacSha256SignSync(key, msg);
const ok = hmacSha256VerifySync(key, msg, mac);

console.log({ macB64: bufferToBase64(mac), ok });

hmacSha256VerifySync returns a boolean and compares the tag as bytes (equalConstTime). Decode Base64 or hex first and use that API. Do not invent a === on encoded strings.

The production bug: re-stringify after parse

A convenience helper signs JSON.stringify(data) for you. That is safe only if the verifier uses the same byte sequence.

This is the trap:

Client builds an object, signs JSON.stringify(object) (compact).
The HTTP client, a logger, or the server serializes again—pretty-print, a DTO with an extra field, a different key order.
Verify runs over those new bytes.

JSON.parse of the wire string and JSON.stringify of that object often keeps key order in modern JS. The usual break is a second serialization that is not the wire: JSON.stringify(obj, null, 2), a mapped DTO (receivedAt, stripped undefined), or Unicode escapes (\u0061 vs a). Key order can still bite if something rebuilds the object from scratch.

Before — same payload, different bytes → `ok === false`

import {
  hmacSha256SignJsonUtf8KeyBase64Sync,
  hmacSha256VerifySync,
} from "encloom/hmac";
import { utf8ToBuffer, base64ToBuffer } from "encloom/helpers/encoding";

const secret = "api-shared-secret";
const body = { action: "ping", id: 1 };

// Client signs compact JSON.stringify(body)
const macB64 = hmacSha256SignJsonUtf8KeyBase64Sync(secret, body);
// MAC over: {"action":"ping","id":1}

// Server (or axios interceptor, or a DTO mapper) serializes again
const pretty = JSON.stringify(body, null, 2);
const extraField = JSON.stringify({ ...body, receivedAt: "2026-08-22T00:00:00.000Z" });

const okPretty = hmacSha256VerifySync(
  utf8ToBuffer(secret),
  utf8ToBuffer(pretty),
  base64ToBuffer(macB64)
);
const okDto = hmacSha256VerifySync(
  utf8ToBuffer(secret),
  utf8ToBuffer(extraField),
  base64ToBuffer(macB64)
);

console.log({ okPretty, okDto }); // false, false — same “JSON”, different UTF-8

After — sign and verify the wire (preferred)

Agree that the MAC covers the exact request body bytes, not a re-built object.

import {
  hmacSha256SignUtf8KeyBase64Sync,
  hmacSha256VerifySync,
} from "encloom/hmac";
import { utf8ToBuffer, base64ToBuffer } from "encloom/helpers/encoding";

const secret = "api-shared-secret";

// Client: MAC over the exact string that will be POSTed
const rawBody = JSON.stringify({ action: "ping", id: 1 });
const macB64 = hmacSha256SignUtf8KeyBase64Sync(
  secret,
  utf8ToBuffer(rawBody)
);

// POST rawBody with header X-Signature: macB64

// Server: verify the raw body from the framework (before JSON.parse)
function verifyRequest(rawBody: string, macB64: string): boolean {
  return hmacSha256VerifySync(
    utf8ToBuffer(secret),
    utf8ToBuffer(rawBody),
    base64ToBuffer(macB64)
  );
}

console.log(verifyRequest(rawBody, macB64)); // true

In Express/Fastify/etc., read the raw body (or a buffered string) before JSON.parse for the MAC path. Parse for business logic after verify succeeds.

Signing only the body is enough to catch tampering of that body. A reused MAC can still be posted to another path. If that matters, put more than the body under the MAC—for example METHOD + path + timestamp + rawBody as one UTF-8 string both sides build the same way—and reject old timestamps.

If you must sign objects — canonical JSON

If both sides only have objects, define a canonical form: sorted keys, no extra spaces, UTF-8, and the same number serialization. A minimal sketch:

function canonicalJson(value: unknown): string {
  if (value === null || typeof value !== "object") {
    return JSON.stringify(value);
  }
  if (Array.isArray(value)) {
    return `[${value.map(canonicalJson).join(",")}]`;
  }
  const obj = value as Record<string, unknown>;
  const keys = Object.keys(obj).sort();
  return `{${keys
    .map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`)
    .join(",")}}`;
}

Then HMAC over utf8ToBuffer(canonicalJson(body)) on both sides. Homegrown canonicalization has edge cases (dates, undefined, bigint). Prefer signing the wire when you control the HTTP stack.

Encoding checklist

Before debugging crypto, check these mismatches:

Item	Agree on
Secret	Same UTF-8 bytes (trim, no accidental newline in env vars)
Message	Raw body or one canonical serializer
Tag transport	Base64 or hex—decode before verify
Algorithm	HMAC-SHA256 vs SHA512 (do not mix)

Hex vs Base64 of the same tag are different strings; both sides must use the same encoding on the wire and decode to Uint8Array before verify.

What HMAC does not give you

Confidentiality — anyone who sees the body still reads it. Use TLS; add AES-GCM (or similar) if you need ciphertext at rest or beyond transport.
Non-repudiation — shared secret means either party can forge tags. For “only this private key signed,” use ECDSA / similar.
Replay protection — a valid MAC can be resent. Bind method, path, and a timestamp (or nonce) into the signed bytes, as above, if that matters.

When this pattern fits

Use shared-secret HMAC when client and server (or two backends) already share a secret, you need tamper detection on a payload, and you can pin the exact bytes under the MAC.

Skip it for public clients that cannot hold a secret (use user auth + server-side checks), or when you need asymmetric proof of origin.

References

encloom on npm · repo · encloom/hmac
Previous: Buffer vs Uint8Array in TypeScript crypto
Related: Web Crypto HMAC, RFC 2104

Buffer vs Uint8Array in TypeScript crypto (and why it hurts)

Alejandro Rodriguez — Mon, 17 Aug 2026 06:34:15 +0000

In Node, Buffer shows up everywhere. In the browser and on the edge, the real contract is typed arrays (Uint8Array)—and often Web Crypto.

When you mix those worlds—an API on Node, a client in the browser, a Worker in between—crypto stops being “call SHA-256” and turns into:

converting types at every boundary
guessing whether a helper accepts string | Buffer | Uint8Array
pulling half a library for a single primitive

This post follows that thread (Uint8Array end to end) through four flows: hashing, HMAC, AES-GCM, and ECDSA over a digest. The snippets use encloom; the same ideas apply if you prefer @noble/* plus Web Crypto by hand.

This is not a threat-modeling or compliance guide. It is about bytes and APIs.

The contract: explicit bytes

A string is not a cryptographic message until you define an encoding. UTF-8 is the usual choice for JSON APIs:

import { sha256Sync, sha256Utf8HexSync } from "encloom/sha2";
import { utf8ToBuffer, bufferToHex } from "encloom/helpers/encoding";

const digest = sha256Sync(utf8ToBuffer("hello"));
console.log(bufferToHex(digest));

// Shortcut when you only need hex of a UTF-8 string
console.log(sha256Utf8HexSync("hello"));

Uint8Array in the public API avoids “sometimes Buffer, sometimes not” across runtimes. The cost is one conversion line; the win is predictable typing.

Naming note: helpers like utf8ToBuffer return Uint8Array. The Buffer suffix is an enc-utils-style name, not Node’s Buffer.

Per-module imports

If your bundler tree-shakes and the package sets sideEffects: false, import the subpath you actually use:

import { sha256Sync } from "encloom/sha2";
import { aesGcmEncryptSync } from "encloom/aes-gcm";

Same idea as preferring lodash/get over import _ from "lodash" when you need one function. On the frontend and in Workers, size shows up.

HMAC: integrity for a JSON body

Same byte contract: the MAC is computed over Uint8Array, not a loose string or a Node Buffer. Scenario: client and server share a secret and want to detect payload tampering. No encryption here—message authentication only.

import {
  hmacSha256SignJsonUtf8KeyBase64Sync,
  hmacSha256VerifySync,
} from "encloom/hmac";
import { utf8ToBuffer, base64ToBuffer } from "encloom/helpers/encoding";

const secret = "api-shared-secret";
const body = { action: "ping", id: 1 };

const macB64 = hmacSha256SignJsonUtf8KeyBase64Sync(secret, body);

// Same serialization the helper used when signing
const msg = utf8ToBuffer(JSON.stringify(body));
const ok = hmacSha256VerifySync(
  utf8ToBuffer(secret),
  msg,
  base64ToBuffer(macB64)
);

console.log({ macB64, ok });

A detail that breaks verification in production: if one side signs the object and the other re-parses JSON from the wire and runs JSON.stringify again, key order can change. Agree on canonical bytes (or sign an already-stable string) between client and server.

AES-GCM: JSON in an envelope

Same thread: plaintext and key as Uint8Array; the helper only serializes the result to strings for transport. GCM gives confidentiality plus integrity (the tag). encryptJsonAes256GcmSync generates a random key and IV and returns an envelope (iv, key, stream). Decryption returns unknown—narrow it at the call site.

import {
  encryptJsonAes256GcmSync,
  decryptJsonAes256GcmSync,
} from "encloom/aes-gcm";

const wire = encryptJsonAes256GcmSync({ user: "ana", role: "admin" });
// wire: { iv, key, stream } — the key travels inside the envelope

const again = decryptJsonAes256GcmSync(wire) as {
  user: string;
  role: string;
};

console.log(again.user);

Important so the example is not misread: anyone who has the full wire can decrypt, because the key is in the object. That fits a local sealed blob, or a layer you later protect with another key / KMS / ECIES. It is not “I encrypted with a shared secret and only send the ciphertext.”

If you manage the key yourself, the low-level API is aesGcmEncryptSync(nonce, key, plaintext). There the operational rule is: do not reuse the same (key, nonce) pair; 12-byte nonces are the usual size.

ECDSA (secp256k1): sign the digest

Explicit bytes again: UTF-8 → Uint8Array, then the digest, then the signature. Many examples sign raw plaintext; in this API sign / verify expect the message hash (e.g. SHA-256). verify does not return a boolean: if the signature is invalid, it throws.

import { generateKeyPair, sign, verify } from "encloom/ecdsa";
import { sha256Sync } from "encloom/sha2";
import { utf8ToBuffer } from "encloom/helpers/encoding";

const { privateKey, publicKey } = generateKeyPair();
const digest = sha256Sync(utf8ToBuffer("transfer:42"));

const sig = sign(privateKey, digest);
verify(publicKey, digest, sig); // ok; on failure → throw

For Ethereum-style pipelines, keccak256 lives in encloom/sha3. Keccak-256 ≠ SHA3-256 (FIPS); they are different domains—do not mix them up.

When this approach helps (and when it doesn’t)

It makes sense if you:

share the same byte-oriented code across Node / browser / edge
use a few primitives and care what lands in the bundle
prefer types that do not lie (Uint8Array vs “stringly bytes”)

It adds little if you already live inside a stack that covers ~80% of your case (e.g. a full wallet SDK) and you do not care about size or buffer types.

References

Package and module docs: encloom on npm · repo
Related ideas: Web Crypto (SubtleCrypto), the @noble family for pure-JS implementations

Switch Success and Error Without Touching Your Frontend

Alejandro Rodriguez — Sun, 16 Aug 2026 21:06:25 +0000

Your app already calls the API. What you need now is the other half: the 404, the 500, the empty list — without asking anyone to break staging, and without if (mock) in the client.

In this article you’ll:

Define several named responses on the same endpoint
Pick which one is active with a single JSON key
Hit the same URL with curl and get 200, 404, or 500

The frontend keeps the same base URL (http://localhost:3001). You only edit the mock file.

This is a CLI (mock-server), not an embeddable SDK.

Prerequisites

Node.js >= 22.12
A project with a package.json (recommended)

Setup

npm install http-mock-json --save-dev
npx mock-server init
npx mock-server start

init creates mocks/, adds a mock:start script, and can scaffold a first file. The server listens on port 3001. Watch mode is always on: save a mock and it reloads.

If you already have the server running, skip this section and open your JSON.

One endpoint, several scenarios

Each HTTP method has two pieces:

Piece	Role
`responses`	Named scenarios (`name`, `statusCode`, `body`)
`nameResponse`	Which scenario is returned

The URL does not change. Only nameResponse does.

Open mocks/animals.json (or create it) and use this:

{
  "data/animals": {
    "GET": {
      "nameResponse": "success",
      "responses": [
        {
          "name": "success",
          "statusCode": "200",
          "body": {
            "animals": [
              { "id": 1, "name": "Lion" },
              { "id": 2, "name": "Tiger" }
            ]
          }
        },
        {
          "name": "not-found",
          "statusCode": "404",
          "body": {
            "message": "No animals found"
          }
        },
        {
          "name": "server-error",
          "statusCode": "500",
          "body": {
            "message": "Internal server error"
          }
        }
      ]
    }
  }
}

nameResponse must match one of the name values. Here the default is "success".

Call it

curl -i http://localhost:3001/data/animals

You should see:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"animals":[{"id":1,"name":"Lion"},{"id":2,"name":"Tiger"}]}

Point your app at http://localhost:3001. Same GET as production — this body is the happy path.

Flip to 404

Change only this line:

"nameResponse": "not-found"

Save. Watch reloads. Run the same curl again:

HTTP/1.1 404 Not Found

{"message":"No animals found"}

No new route. No frontend change. Same GET /data/animals.

Flip to 500

"nameResponse": "server-error"

Save and curl once more:

HTTP/1.1 500 Internal Server Error

{"message":"Internal server error"}

That is the whole feature: same URL, different backend behavior, one string in JSON.

`nameResponse`	Status	Body
`success`	200	list of animals
`not-found`	404	error message
`server-error`	500	error message

Use the 404 for empty/not-found UI. Use the 500 for the generic failure banner. Switch back to success when you need the list again.

Same idea on POST

You can attach another responses array to POST on the same path. nameResponse is per method:

{
  "data/animals": {
    "GET": {
      "nameResponse": "success",
      "responses": [
        {
          "name": "success",
          "statusCode": "200",
          "body": {
            "animals": [
              { "id": 1, "name": "Lion" }
            ]
          }
        },
        {
          "name": "server-error",
          "statusCode": "500",
          "body": { "message": "Internal server error" }
        }
      ]
    },
    "POST": {
      "nameResponse": "created",
      "responses": [
        {
          "name": "created",
          "statusCode": "201",
          "body": {
            "id": 3,
            "name": "Eagle",
            "created": true
          }
        },
        {
          "name": "server-error",
          "statusCode": "500",
          "body": { "message": "Could not save animal" }
        }
      ]
    }
  }
}

curl -i -X POST http://localhost:3001/data/animals \
  -H "Content-Type: application/json" \
  -d '{"name":"Eagle"}'

With "nameResponse": "created" you get 201. Set it to "server-error" and the same POST returns 500.

GET and POST do not share nameResponse. You can have a healthy list and a failing create at the same time.

What you just got

Several scenarios on one endpoint, in a file the team can review
200 / 404 / 500 (and 201 on POST) without touching the client
A switch that is one key: nameResponse

Mock Your API in 5 Minutes with JSON (No Backend Required)

Alejandro Rodriguez — Sun, 09 Aug 2026 16:47:50 +0000

Your frontend needs the API now. The backend isn’t ready, staging is down, or you want to trigger a 500 without asking anyone to break the server.

In this article you’ll:

Install a local mock server
Define an endpoint in a JSON file
Call it with curl (or from your app) as if it were the real API

This isn’t an embeddable SDK — it’s a CLI that boots HTTP on your machine. Your app talks to http://localhost:3001 the same way it would talk to staging.

Prerequisites

Node.js >= 22.12
A project with a package.json (recommended)

1. Install

npm install http-mock-json --save-dev

The CLI binary is mock-server.

2. Initialize

npx mock-server init

By default this will:

Create a mocks/ directory
Add a mock:start script to your package.json (mock-server start -p 3001)
Prompt you to create a first mock

For the prompts, you can use something like:

Prompt	Example
JSON file name	`animals` → `mocks/animals.json`
Endpoint	`data/animals`
Methods	`GET`

The scaffold sets nameResponse to "success" and includes two empty responses: success (200) and error (404).

3. Fill in the response bodies

Open mocks/animals.json and make it look like this:

{
  "data/animals": {
    "GET": {
      "nameResponse": "success",
      "responses": [
        {
          "name": "success",
          "statusCode": "200",
          "body": {
            "animals": [
              { "id": 1, "name": "Lion" },
              { "id": 2, "name": "Tiger" }
            ]
          }
        },
        {
          "name": "error",
          "statusCode": "404",
          "body": {
            "message": "No animals found"
          }
        }
      ]
    }
  }
}

What you need on day one:

Piece	Role
Top-level key	Endpoint path (`data/animals`)
Uppercase method	`GET`, `POST`, etc.
`nameResponse`	Which scenario is returned by default
`responses[]`	Named scenarios with `name`, `statusCode`, and `body`

4. Start the server

npx mock-server start

Or, if init added the script:

npm run mock:start

Both listen on port 3001 by default (http://localhost:3001).

On start, every mock file is validated. Errors block startup — fix them and run again.

Watch mode is always on: save a mock file and the server reloads.

5. Try it

curl -i http://localhost:3001/data/animals

(Use port 3001 if you started via the init script.)

You should see something like:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"animals":[{"id":1,"name":"Lion"},{"id":2,"name":"Tiger"}]}

In your frontend, point the API base URL at that local host. Same HTTP calls — different “backend.”

10-second bonus: flip to the error scenario

Change this in the JSON:

"nameResponse": "error"

Save the file (watch reloads) and run curl again. You now get the 404 with the error message — without touching the frontend.

That’s the core idea: same URL, different backend behavior, controlled from JSON.

What you just got

A local mock server in minutes
An endpoint defined in a file the team can read and version
Success ↔ error by editing a single key

I Built a Free Planning Poker App with SvelteKit and Cloudflare Durable Objects

Alejandro Rodriguez — Sun, 09 Aug 2026 05:03:49 +0000

Scrum teams need Planning Poker often — and they rarely want another account, another SaaS login, or a shared spreadsheet.

So I built Planning Poker Free: open-source, no signup, create a room, share the link, and estimate in real time.

Live app: planningpoker.free
Source: github.com/alejandrorodrom/planning-poker-free

The problem

Most estimation tools ask for accounts, orgs, or paid seats before the team can vote. For a 15-minute refinement, that friction is too high.

I wanted something closer to:

Create a room
Share /room/{id}
Vote
Reveal and discuss

No accounts. Optional password. Done.

What it does

Rooms: public or password-protected
Roles: moderator, voter, observer (with handoff if the moderator drops)
Decks: modified Fibonacci, Fibonacci, powers of two, T-shirt, sequential
Aggregation: consensus, mode, median, or mean
Voting UX: hidden/revealed cards, optional auto-reveal
Teams: overall + per-team results
Export: Markdown, CSV, or a photo.

Stack

Layer	Choice
UI	Svelte 5
App framework	SvelteKit
Language	TypeScript
Runtime	Cloudflare Workers
Realtime state	Durable Objects + WebSockets

Each room is its own Durable Object: one in-memory state machine plus WebSocket fan-out. No Redis, no always-on Node process — the room wakes when people join and stays consistent while they’re connected.

That combo is the interesting part for me: realtime multiplayer UX without babysitting infrastructure.

Design choices that mattered

No accounts on purpose

Session rejoin uses localStorage so people can refresh and come back. Last active tab wins. Simple, good enough for estimation sessions.

Moderators can hand off

If the moderator goes offline, someone else can claim moderation. Real meetings are messy; the tool should survive that.

Export is not optional

After the call, teams want notes. Markdown/CSV export makes the session useful beyond the live board.

Try it

Open planningpoker.free
Create a room
Share the link with your team
Vote and reveal

If you find a bug or want a feature, open an issue or PR on GitHub.

What’s next

If you use it with your team, tell me what broke — or what you wished existed.

Built and maintained by Alejandro Rodriguez Romero / RODRIGUEZROM.

DEV Community: Alejandro Rodriguez

HMAC over JSON in TypeScript — why verify fails in production

What HMAC actually signs

The production bug: re-stringify after parse

Before — same payload, different bytes → ok === false

After — sign and verify the wire (preferred)

If you must sign objects — canonical JSON

Encoding checklist

What HMAC does not give you

When this pattern fits

References

Buffer vs Uint8Array in TypeScript crypto (and why it hurts)

The contract: explicit bytes

Per-module imports

HMAC: integrity for a JSON body

AES-GCM: JSON in an envelope

ECDSA (secp256k1): sign the digest

When this approach helps (and when it doesn’t)

References

Switch Success and Error Without Touching Your Frontend

Prerequisites

Setup

One endpoint, several scenarios

Call it

Flip to 404

Flip to 500

Same idea on POST

What you just got

Links

Mock Your API in 5 Minutes with JSON (No Backend Required)

Prerequisites

1. Install

2. Initialize

3. Fill in the response bodies

4. Start the server

5. Try it

10-second bonus: flip to the error scenario

What you just got

Links

I Built a Free Planning Poker App with SvelteKit and Cloudflare Durable Objects

The problem

What it does

Stack

Design choices that mattered

No accounts on purpose

Moderators can hand off

Export is not optional

Try it

What’s next

Before — same payload, different bytes → `ok === false`