DEV Community: Miller Elias

Stop Uploading Signed Contracts to SaaS: How to Build 100% Client-Side PDF Signing in TypeScript

Miller Elias — Sat, 24 Oct 2026 16:07:31 +0000

Every week, millions of developers and business owners upload sensitive non-disclosure agreements, offer letters, and vendor contracts to third-party e-sign platforms just to slap a handwritten signature on page 4.

Think about the privacy equation: to perform what is essentially a 2D composite placement of a signature glyph onto an existing document, we routinely transmit proprietary PDFs over public networks to external server farms, exposing them to server-side cache retention, worker logs, and third-party data breach vectors.

Why are we sending contracts across the wire for something modern client-side JavaScript can execute in under 30 milliseconds?

In this deep dive, we'll break down the mechanics of building a zero-upload, 100% in-browser PDF signing engine using TypeScript, pdfjs-dist, and pdf-lib. We'll solve the three biggest technical headaches along the way: PostScript coordinate inversion, Retina canvas blur, and instant client-side chroma keying for physical stamp uploads.

1. The Core Misconception: Visual Signing vs. Cryptographic PDF Bloat

Many developers assume that allowing a user to sign a document requires a heavyweight digital certificate infrastructure (PKI / X.509 cryptographic signing).

While certified digital signatures (such as eIDAS Qualified Electronic Signatures) serve regulated high-trust legal niches, the vast majority of day-to-day business documents—standard commercial contracts, invoices, rental leases, and internal acknowledgments—rely on Simple Electronic Signatures (SES). Under the US ESIGN Act and EU eIDAS regulations, an SES simply requires demonstrating intent through an applied mark or image.

The fatal architectural flaw of many in-browser PDF signers is that they take the easy route: they rasterize the entire PDF page into a giant JPEG, paste the signature on top, and stitch it back together.

Doing that destroys all vector sharpness, wipes out searchable text streams, and blows up a 400KB contract into a 15MB file.

A production-grade signer must preserve the underlying document's vector integrity, embedding the signature as a transparent overlay directly into the PDF's existing content stream.

2. The Coordinate System Nightmare: Screen Space vs. PostScript

The single biggest gotcha when placing signatures on a PDF is that web browsers and PDF engines disagree on where the universe begins.

Screen Canvas Space (DOM / HTML5 Canvas)

Origin (0, 0) is at the top-left. X increments to the right, and Y increments downwards.

PDF Cartesian Point Space (PostScript standard)

Origin (0, 0) is at the bottom-left. Measurements are in typographic points (1/72 of an inch). X increments to the right, and Y increments upwards.

If you naively take the pixel position from your drag-and-drop React overlay and pass it to pdf-lib, your signature will end up upside-down or hovering in the opposite quadrant of the page.

Here is the exact mathematical conversion formula:

// Screen coordinate: element.x, element.y (measured from top-left)
// Canvas dimensions: canvasWidth, canvasHeight (rendered by PDF.js)
// Actual PDF Page dimensions: pdfPageWidth, pdfPageHeight (from PDF document spec)

const scaleFactorX = pdfPageWidth / canvasWidth;
const scaleFactorY = pdfPageHeight / canvasHeight;

const pdfWidth = element.width * scaleFactorX;
const pdfHeight = element.height * scaleFactorY;

const pdfX = element.x * scaleFactorX;

// Invert the Y-axis: subtract the element's bottom edge from the total height
const pdfY = pdfPageHeight - (element.y + element.height) * scaleFactorY;

With this mapping, regardless of whether the user views the document on a mobile screen, a 1080p monitor, or a 4K display, the signature lands on the exact millimeter of the signing line.

3. High-DPI Capture: Eliminating the "Blurry Signature" Problem

When capturing freehand signatures via HTML5 canvas, the default canvas resolution produces fuzzy, jagged strokes on Retina and high-density mobile screens.

To get fountain-pen smoothness, you must decouple the canvas's physical drawing buffer from its CSS presentation width using window.devicePixelRatio:

function setupCrispCanvas(canvas: HTMLCanvasElement) {
  const ctx = canvas.getContext('2d');
  if (!ctx) return;

  const dpr = window.devicePixelRatio || 1;
  const rect = canvas.getBoundingClientRect();

  // Set internal raster buffer to high-DPI resolution
  canvas.width = rect.width * dpr;
  canvas.height = rect.height * dpr;

  // Scale the rendering context so coordinate math stays in CSS pixels
  ctx.scale(dpr, dpr);

  // Smooth out drawing paths
  ctx.lineCap = 'round';
  ctx.lineJoin = 'round';
  ctx.lineWidth = 2.5;
  ctx.strokeStyle = '#0F172A';
}

When users draw with a finger or stylus, their input coordinates map directly to CSS space, while the underlying image data exports at crisp, print-ready 300+ DPI.

4. Real-Time Chroma Keying: Stripping White Backgrounds from Stamp Uploads

A common user story is signing on a piece of paper, taking a photo on a smartphone, and uploading it.

The problem? The photo has an off-white or yellowish paper background. If you drop that JPEG onto a contract, it casts an ugly opaque box over the text and signature lines underneath.

Instead of sending the image to a cloud AI background-remover, you can perform instant luminance thresholding right in an offscreen canvas:

function makeSignatureTransparent(imageSrc: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const img = new Image();
    img.crossOrigin = 'anonymous';
    img.onload = () => {
      const canvas = document.createElement('canvas');
      canvas.width = img.naturalWidth;
      canvas.height = img.naturalHeight;

      const ctx = canvas.getContext('2d');
      if (!ctx) return reject('Canvas context unavailable');

      ctx.drawImage(img, 0, 0);

      const imgData = ctx.getImageData(0, 0, canvas.width, canvas.height);
      const data = imgData.data;

      // Iterate through RGBA values (4 bytes per pixel)
      for (let i = 0; i < data.length; i += 4) {
        const r = data[i];
        const g = data[i + 1];
        const b = data[i + 2];

        // If the pixel is near-white paper (brightness > 225), set Alpha to 0
        if (r > 225 && g > 225 && b > 225) {
          data[i + 3] = 0;
        }
      }

      ctx.putImageData(imgData, 0, 0);
      resolve(canvas.toDataURL('image/png'));
    };
    img.onerror = reject;
    img.src = imageSrc;
  });
}

This takes under 15ms for an average mobile snapshot, transforming paper scans into clean transparent PNG stamps that blend seamlessly over contract lines.

5. The Complete Client-Side Embedding Pipeline

Once the user places their signature, typed name, or date stamp onto the document canvas, we burn the graphic into the PDF binary using pdf-lib:

import { PDFDocument } from 'pdf-lib';

interface SignatureElement {
  pageNumber: number; // 1-indexed
  pngDataUrl: string;
  x: number;
  y: number;
  width: number;
  height: number;
}

export async function signPdfDocument(
  pdfFile: File,
  elements: SignatureElement[],
  renderedCanvasWidth: number,
  renderedCanvasHeight: number
): Promise<Uint8Array> {
  const arrayBuffer = await pdfFile.arrayBuffer();
  const pdfDoc = await PDFDocument.load(arrayBuffer, { ignoreEncryption: true });

  for (const el of elements) {
    const targetPage = pdfDoc.getPage(el.pageNumber - 1);
    const { width: pageWidth, height: pageHeight } = targetPage.getSize();

    // Decode base64 PNG data into a binary buffer
    const base64Data = el.pngDataUrl.split(',')[1];
    const binaryString = atob(base64Data);
    const bytes = new Uint8Array(binaryString.length);
    for (let i = 0; i < binaryString.length; i++) {
      bytes[i] = binaryString.charCodeAt(i);
    }

    // Embed as a native PNG object inside the PDF
    const embeddedImage = await pdfDoc.embedPng(bytes);

    // Compute inverted coordinate offsets
    const scaleFactorX = pageWidth / renderedCanvasWidth;
    const scaleFactorY = pageHeight / renderedCanvasHeight;

    const pdfWidth = el.width * scaleFactorX;
    const pdfHeight = el.height * scaleFactorY;
    const pdfX = el.x * scaleFactorX;
    const pdfY = pageHeight - (el.y + el.height) * scaleFactorY;

    // Stamp directly onto the page without re-rasterizing the document
    targetPage.drawImage(embeddedImage, {
      x: Math.max(0, pdfX),
      y: Math.max(0, pdfY),
      width: pdfWidth,
      height: pdfHeight,
    });
  }

  return await pdfDoc.save();
}

Because this only modifies the target page stream and embeds a compressed PNG object, the exported PDF retains 100% of its original fonts, selectable paragraphs, and minimal file size.

6. Inspecting the Live Pipeline

If you want to test how this coordinate translation and client-side stamp thresholding behave with actual multi-page PDFs, you can try out the live implementation over at VersaPDF's Sign Tool.

You can even keep your browser's DevTools Network tab open while dropping signatures: you will see zero outbound file payloads, as the entire rendering, thresholding, and byte-compilation pipeline runs strictly inside local memory.

What's Next?

Client-side document tooling has matured to the point where browsers can handle virtually every common office workflow. Have you transitioned any document processing tasks from server-side workers to client WebAssembly/Web APIs? How are you handling PDF coordinate discrepancies in your projects? Let's discuss below!

Why Drawing a Black Box on a PDF Doesn't Work (And How to Build Real In-Browser Redaction)

Miller Elias — Sat, 24 Oct 2026 16:02:42 +0000

We've all seen the news headlines: a high-profile legal case or government report releases a "redacted" document, only for an investigative journalist to press Ctrl+A -> Ctrl+C, paste it into Notepad, and instantly expose all the classified names and bank accounts.
It happened in the Paul Manafort legal filings. It happened in police department releases. And it happens every day in corporate contracts.
Why does this keep happening in 2026? And more importantly: what does it actually take to programmatically redact a PDF the right way, without sending confidential documents to a random cloud server?
In this post, we'll dive into the internals of the PDF object model, look at why "visual masking" is a dangerous illusion, and walk through how we engineered a 100% client-side redaction engine in TypeScript using pdfjs-dist and pdf-lib.

1. The "Black Box" Illusion: Why Naive Redaction Fails

To understand why PDFs leak secrets, you have to understand how PDF content streams work.
A PDF is not an image; it is an arbitrary container of vector instructions, font glyph tables, and text rendering commands. When you open a PDF editor or use a typical library to draw a black rectangle over sensitive text, here is what gets emitted into the PDF Content Stream:

% What you think happened:
% "The text is destroyed and covered with black ink"
% What actually happens in the PDF Content Stream:
BT
/F1 12 Tf
72 712 Td
(CONFIDENTIAL_SOCIAL_SECURITY_NUMBER_HERE) Tj
ET
0 0 0 rg
70 710 200 15 re
f

Look closely at that stream:

BT ... ET tells the PDF viewer to place text glyphs on the canvas at coordinate (72, 712).
re and f simply tell the graphics state to paint a filled black rectangle over those coordinates. The underlying glyph data, font encoding dictionary, and text extraction coordinates are still 100% present in the byte stream. Any PDF parser, screen reader, or basic clipboard copy command will extract the secret word-for-word. Even worse, if someone opens the document in Adobe Acrobat Pro, Inkscape, or Adobe Illustrator, they can simply click on the black box, press the Delete key, and view the original text beneath it completely undamaged. ## 2. The Two Architectural Approaches to True Redaction To genuinely redact content, the sensitive glyphs must cease to exist in the resulting binary. There are two primary ways to achieve this: ### Approach A: Content Stream Surgery (AST Rewriting) Parse the raw PDF content stream, calculate glyph bounding boxes according to font metrics and affine transformation matrices (cm), split text operators (Tj, TJ), remove the target ranges, and strip corresponding references in bookmarks, metadata, and structural trees. Pros: Keeps the file 100% vector, resulting in razor-sharp text and minimal file size. Cons: Immensely complex and fragile. If the text is part of an XObject Form, an embedded Type 3 font, or masked behind non-standard clipping paths, glyph leakage can still slip through undetected. ### Approach B: Pixel-Level Burning & Selective Page Rasterization (The Hybrid Pipeline) For documents containing sensitive data, the safest guarantee against zero-day text-extraction leaks is physical pixel flattening:
Render the affected page to an offscreen bitmap at high DPI.
Paint opaque pixels directly over the target areas, permanently overwriting the raw RGBA buffer.
Export as a flattened bitmap and embed it back into a pristine document. The challenge? Rasterizing a 200-page document turns a 2MB PDF into a sluggish 80MB bloated monstrosity and destroys selectable text across the entire file. The Solution: A Hybrid Selective Pipeline. ## 3. Implementing the Hybrid Redaction Engine in the Browser When building this in modern client-side JavaScript, the goal was two-fold:
Zero Server Footprint: Confidential legal documents should never leave the user's device.
Selective Sanitization: Untouched pages must remain 100% vector and pristine; only pages with active redactions undergo physical destruction. Here is how the core export pipeline looks:

import { PDFDocument } from 'pdf-lib';
import * as pdfjsLib from 'pdfjs-dist';
interface RedactionBox {
  pageIndex: number; // 0-based
  x: number;         // Normalized (0.0 to 1.0)
  y: number;         // Normalized (0.0 to 1.0)
  width: number;
  height: number;
  color: 'black' | 'white';
}
export async function sanitizePdf(
  file: File,
  redactions: RedactionBox[]
): Promise<Uint8Array> {
  const arrayBuffer = await file.arrayBuffer();

  // 1. Load original document in both pdf-lib (for page manipulation) 
  // and PDF.js (for high-fidelity rendering)
  const originalPdfDoc = await PDFDocument.load(arrayBuffer, { ignoreEncryption: true });
  const pdfJsDoc = await pdfjsLib.getDocument({ data: arrayBuffer }).promise;
  const newPdfDoc = await PDFDocument.create();
  const totalPages = originalPdfDoc.getPageCount();
  for (let i = 0; i < totalPages; i++) {
    const pageRedactions = redactions.filter((box) => box.pageIndex === i);
    if (pageRedactions.length === 0) {
      // Pristine page: Copy directly without touching vectors or bloating file size
      const [copiedPage] = await newPdfDoc.copyPages(originalPdfDoc, [i]);
      newPdfDoc.addPage(copiedPage);
    } else {
      // Tainted page: Perform physical pixel-level burning
      const pdfJsPage = await pdfJsDoc.getPage(i + 1);

      // Use 2.0x scale (~200 DPI) for crisp archival quality
      const scale = 2.0;
      const viewport = pdfJsPage.getViewport({ scale });
      const canvas = document.createElement('canvas');
      canvas.width = viewport.width;
      canvas.height = viewport.height;
      const ctx = canvas.getContext('2d');
      if (!ctx) throw new Error('Canvas 2D context unavailable');
      // 1. Render original visual layer
      ctx.fillStyle = '#ffffff';
      ctx.fillRect(0, 0, viewport.width, viewport.height);
      await pdfJsPage.render({ canvasContext: ctx, viewport }).promise;
      // 2. Physically burn opaque blocks into the raster buffer
      // This obliterates underlying pixel data beyond mathematical recovery
      for (const box of pageRedactions) {
        const rx = Math.round(box.x * viewport.width);
        const ry = Math.round(box.y * viewport.height);
        const rw = Math.round(box.width * viewport.width);
        const rh = Math.round(box.height * viewport.height);
        ctx.fillStyle = box.color === 'white' ? '#ffffff' : '#000000';
        ctx.fillRect(rx, ry, rw, rh);
      }
      // 3. Compress to high-quality JPEG binary to prevent PNG alpha layer artifacts
      const blob = await new Promise<Blob | null>((resolve) =>
        canvas.toBlob(resolve, 'image/jpeg', 0.94)
      );
      if (!blob) throw new Error('Failed to export sanitized canvas');
      const imageBytes = await blob.arrayBuffer();
      const embeddedImage = await newPdfDoc.embedJpg(imageBytes);
      // 4. Construct a new sanitized PDF page with identical dimensions
      const originalPage = originalPdfDoc.getPage(i);
      const { width, height } = originalPage.getSize();
      const sanitizedPage = newPdfDoc.addPage([width, height]);
      sanitizedPage.drawImage(embeddedImage, {
        x: 0,
        y: 0,
        width,
        height,
      });
    }
  }
  // Save sanitized binary
  return await newPdfDoc.save();
}

4. Key Gotchas & Lessons Learned

If you are building something similar, watch out for these traps:

Coordinate System Inversion

DOM coordinates originate at the top-left (0, 0). The standard PDF Cartesian coordinate system originates at the bottom-left (0, 0). Furthermore, PDF pages can have arbitrary rotations (/Rotate 90, 180, or 270).
Storing redaction bounding boxes as normalized percentages (0.0 - 1.0) relative to the viewport makes cross-coordinate mapping significantly simpler and prevents misalignment during high-DPI rasterization.

Metadata Sanitization

Even if you burn the page pixels, do not forget to strip Document Info dictionaries (Author, Keywords, Title, Subject) and XMP metadata streams. In many real-world breaches, the page content was blanked out, but the document metadata still contained the original author's name, revision logs, and internal file paths.

Alpha Channels Can Be Deceptive

If you export to PNG with semi-transparency or anti-aliased edge smoothing, sub-pixel rendering can sometimes leave hints of glyph outlines at the perimeter. Forcing an opaque background fill and converting to flat JPEG buffers completely eliminates this risk.

5. Live Architecture & Verification

If you want to inspect how this selective rasterization pipeline behaves with real multi-page documents, you can test a live implementation over at VersaPDF's Redact Tool.
Opening your browser's DevTools Network tab will confirm that zero document bytes are transmitted to any remote server: the canvas rendering, raster destruction, and pdf-lib assembly run strictly within the client's local memory.

Discussion

How are you approaching document sanitization in your own stacks? Are you relying on native poppler/qpdf CLI utilities on the server, or moving toward zero-knowledge browser runtimes? Let’s talk in the comments!

The HTTP Status Codes You're Probably Using Wrong (And How to Fix Them)

Miller Elias — Sat, 24 Oct 2026 15:56:31 +0000

How many times have you inspected an API response in production, only to find:

HTTP/1.1 200 OK
{
  "code": 403,
  "status": "error",
  "message": "User not authorized"
}

Or an endpoint returning 400 Bad Request for everything from invalid JSON syntax to failed business logic rules?

HTTP status codes are the standardized language of the web. When used correctly, they make client-side error handling trivial, improve reverse proxy caching (Cloudflare, Nginx), and save engineers hours of debugging. When misused, they turn API integrations into a guessing game.

Let's dive into the most frequently confused status codes, their real RFC definitions, and how to apply them cleanly in your APIs.

1. 401 Unauthorized vs. 403 Forbidden

This is by far the most abused pair in modern API design — largely because HTTP's original naming in RFC 9110 is somewhat misleading.

+---------------------------------------------------------+
|                  Client sends a request                 |
+---------------------------------------------------------+
                            |
             Does the server know who you are?
             (Valid token / session / API key?)
               /                               \
             NO                                 YES
             /                                   \
   401 Unauthorized                      Is the user allowed
 (Better name: Unauthenticated)          to touch this resource?
                                           /                 \
                                         NO                   YES
                                         /                     \
                                   403 Forbidden           200/201/etc.

401 Unauthorized actually means Unauthenticated. The client has not provided valid credentials (missing Authorization header, expired JWT, or invalid API key). Crucially, a 401 response typically includes a WWW-Authenticate header telling the client how to authenticate.
403 Forbidden means: “I know exactly who you are, but you don't have permission to do this.” Sending new authentication tokens will not change the outcome unless the user's role or permissions change.

💡 Rule of thumb: If logging in again might fix it, use 401. If logging in won't help because your account lacks admin privileges, use 403.

2. 400 Bad Request vs. 422 Unprocessable Content

Before RFC 9110 (and RFC 4918 WebDAV), teams dumped every validation failure into 400. Modern REST design prefers separating syntax from semantics:

400 Bad Request: The server cannot parse the request at all. This means malformed JSON (missing closing bracket), invalid query string encoding, or invalid HTTP headers. The payload literally cannot be parsed by the deserializer.
422 Unprocessable Content (formerly Unprocessable Entity): The syntax is completely valid (clean JSON, well-formed fields), but the business validation failed.

// Example: POST /api/users
// Payload sent: {"email": "not-an-email", "age": -5}
// The JSON parsed successfully, but the fields are invalid.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "errors": [
    { "field": "email", "message": "Must be a valid email address" },
    { "field": "age", "message": "Must be greater than 0" }
  ]
}

Separating these two allows frontend clients to easily route 422 responses directly to UI form validation states, while treating 400 as an unexpected client-side bug.

3. The Redirect Quagmire: 301/302 vs. 307/308

Back in the early days of HTTP/1.0, browsers did something unintended: when they received a 301 Moved Permanently or 302 Found in response to a POST request, they would rewrite the follow-up request method to GET.

This behavior became de facto standard, breaking form submissions and API mutations. To resolve this without breaking legacy websites, the IETF introduced 307 and 308:

Code	Name	Semantic	Preserves POST/PUT Method?
301	Moved Permanently	Resource permanently at new URL	❌ Usually rewritten to `GET`
302	Found	Temporary redirect	❌ Usually rewritten to `GET`
307	Temporary Redirect	Temporary redirect	✅ Guaranteed to preserve method & body
308	Permanent Redirect	Permanent redirect	✅ Guaranteed to preserve method & body

💡 In modern APIs: If you enforce HTTPS redirects or route versioning (e.g., /api/v1/checkout → /api/v2/checkout), use 308 Permanent Redirect or 307 Temporary Redirect. Using 301 or 302 on a POST payload will result in the client sending an empty GET to the new endpoint!

4. 502 Bad Gateway vs. 504 Gateway Timeout

When debugging backend infrastructure behind a reverse proxy (Nginx, Envoy, Cloudflare, AWS ALB), these two indicate completely different root causes:

502 Bad Gateway: The reverse proxy contacted the upstream service (e.g., your Node/Python/Go container), and the upstream sent an invalid or abruptly closed response (e.g., upstream process crashed with an OOM error, segfaulted, or returned corrupt HTTP).
504 Gateway Timeout: The reverse proxy contacted upstream, but the upstream took too long to respond (exceeded proxy_read_timeout or ALB timeout). Often caused by unindexed database locks, third-party API stalls, or CPU starvation.

5. When to Return 204 No Content

204 No Content is designed for actions that succeed but have nothing meaningful to return in the response body.

Good use cases:
- DELETE /api/items/42: The item is gone; returning empty body with 204 is clean.
- PUT /api/users/me/preferences: Saved successfully, and the client already knows what state it sent.
Watch out for:
- A 204 response must never include a message body (not even {}).
- If your frontend relies on receiving the updated object timestamp or auto-generated fields (like updated_at), return 200 OK with the entity instead.

A Handy Reference for Everyday Debugging

With over 60 standardized status codes across RFC 9110 and related extensions (from 206 Partial Content for video streaming to 429 Too Many Requests with Retry-After), keeping track of exact caching semantics, headers, and troubleshooting steps is tough.

When designing APIs or debugging production logs, I frequently reference this HTTP Status Codes Directory. It has quick RFC references, cause-and-solution breakdowns, and raw response snippets for every status code without the clutter of reading through 200-page IETF specs.

Quick Summary Cheat-Sheet

1xx -> Hold on (Protocol upgrades, Expect: 100-continue)
2xx -> Here you go (200 OK, 201 Created, 204 No Content)
3xx -> Go over there (Use 307/308 for APIs to preserve POST/PUT)
4xx -> You (the client) messed up (401 unauthenticated, 403 forbidden, 422 validation)
5xx -> We (the server/infra) messed up (502 crashed upstream, 504 timed out upstream)

What's your API design pet peeve?

Do you enforce 204 on deletes, or prefer returning { "success": true }? How do you structure your error response schemas? Let's discuss in the comments below!

From DevTools to Code: Stop Manually Translating cURL Commands

Miller Elias — Sat, 24 Oct 2026 15:50:00 +0000

We've all been there:

You open Chrome / Firefox DevTools.
You inspect an API request on the Network tab that works perfectly.
You right-click and hit "Copy as cURL (bash)".
You paste it in your terminal — 200 OK. Magic! ✨
Now you need to reproduce this exact call in your backend (Python, Node.js, Go, or PHP).

And then the tedious part begins: stripping headers, escaping double quotes, formatting JSON payloads, mapping cookies, and figuring out whether the authorization header needs Bearer or Basic auth.

Manually translating cURL into production code is not just boring — it’s error-prone. Here’s a breakdown of why this process trips developers up, what to watch out for, and how to automate it seamlessly.

The Subtle Traps of Manual cURL Conversion

A typical cURL command copied from the browser looks something like this:

curl 'https://api.example.com/v1/orders?status=active' \
  -X POST \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'User-Agent: Mozilla/5.0 ...' \
  -H 'Accept-Language: en-US,en;q=0.9' \
  --data-raw '{"order_id":12345,"items":[{"id":1,"qty":2}],"notes":"Don'\''t forget sauce"}' \
  --compressed

When you translate this by hand, three things usually go wrong:

1. Escaping Quotes & Multiline Strings

Notice that 'Don'\''t forget sauce'? Bash has weird string escaping rules. When you copy that directly into Python or JavaScript, string delimiters often break, causing subtle JSON parse errors that take 15 minutes of head-scratching to debug.

2. Bloated Browser Headers

DevTools exports everything — Sec-Ch-Ua, Sec-Fetch-Dest, Accept-Encoding, Cache-Control, etc.
In code, you usually only care about:

Content-Type
Authorization
Custom app headers (e.g., X-API-Key)

Copying 25 headers into your codebase creates technical debt and can cause unexpected CORS or cache behavior.

3. Payload Serialization Discrepancies

--data vs --data-raw vs --data-binary
application/x-www-form-urlencoded vs multipart/form-data vs application/json

In Python requests, sending a form uses data=..., while sending JSON uses json=.... If you accidentally pass a raw string to data= with a JSON header, Python won't serialize it properly, leading to mysterious 400 Bad Request responses.

The Target: What Clean Target Code Should Look Like

Let's look at how that cURL command maps cleanly to modern idioms across the most common stacks:

Modern JavaScript (Fetch API)

With Node.js 18+ having native fetch, you rarely need external dependencies for straightforward HTTP calls:

const response = await fetch('https://api.example.com/v1/orders?status=active', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer eyJhbGciOi...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    order_id: 12345,
    items: [{ id: 1, qty: 2 }],
    notes: "Don't forget sauce"
  }),
});

const data = await response.json();
console.log(data);

Python (Requests / HTTPX)

In Python, idiomatic code avoids manual string concatenation:

import requests

url = "https://api.example.com/v1/orders"
params = {"status": "active"}

headers = {
    "Authorization": "Bearer eyJhbGciOi...",
    "Content-Type": "application/json",
}

payload = {
    "order_id": 12345,
    "items": [{"id": 1, "qty": 2}],
    "notes": "Don't forget sauce",
}

response = requests.post(url, params=params, headers=headers, json=payload)
print(response.status_code, response.json())

Go (`net/http`)

Go requires more boilerplate, making manual conversion especially tedious:

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    payload := map[string]any{
        "order_id": 12345,
        "items": []map[string]any{
            {"id": 1, "qty": 2},
        },
        "notes": "Don't forget sauce",
    }
    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", "https://api.example.com/v1/orders?status=active", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer eyJhbGciOi...")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
}

Automating the Workflow

Unless you are learning HTTP semantics from scratch, writing this boilerplate manually every day is a waste of engineering time.

Whenever I'm reverse-engineering an API or migrating endpoints, I keep a dedicated web utility open in a pinned tab. If you haven't found a clean one yet, check out this interactive cURL Converter.

A few things that make a converter actually good:

Two-way support: Not just cURL → Code, but converting code back to cURL when you need to reproduce a bug on an SSH box or share a minimal reproduction with DevOps.
Multiple targets: Handling Fetch, Axios, Python Requests, HTTPX, Go, and PowerShell out of the box.
Header filtering: Letting you inspect headers, query params, and auth tokens separately so you don't paste unwanted tracking cookies into your codebase.

Pro-Tips for Working with cURL in Dev & CI/CD

To wrap up, here are 3 quick cURL command tips that make terminal debugging much faster:

Print HTTP status and response time without headers:

   curl -o /dev/null -s -w 'Status: %{http_code} | Time: %{time_total}s\n' https://api.example.com/health

Follow redirects automatically: Always add -L (or --location) if you suspect an unexpected 301/302 is swallowing your payload.
Fail silently in scripts: Use -fsSL in Docker builds or CI workflows so that non-200 responses trigger a proper exit code instead of continuing silently.

What's your API debugging setup?

Do you prefer copying from browser DevTools, drafting queries in Postman / Bruno / Insomnia, or scripting directly with cURL? Drop your workflow in the comments below!

How PDF Merging Actually Works Under the Hood (And Why Most Implementations Mess It Up)

Miller Elias — Mon, 12 Oct 2026 03:50:35 +0000

Merging PDF files sounds like a trivial Sunday afternoon project. Grab file A, grab file B, glue them together, download. How hard could it be?

If you've ever inspected what popular libraries actually do—or worse, tried to write a parser yourself—you know that PDF is not a stream of formatted text. It’s a 30-year-old PostScript-derived, semi-random-access object graph masquerading as a document format.

Let's walk through what actually happens when you merge two PDF files, why naive approaches destroy document fidelity, and how modern browser runtimes can handle the entire pipeline without uploading sensitive files to an external server.

The Naive Trap: Canvas Rasterization

Before getting into the internals, we have to talk about the anti-pattern that plagues far too many open-source projects and SaaS utilities: the rasterization pipeline.

It usually looks like this:

Render each page of Document A onto an HTML5 <canvas> using pdf.js.
Convert that canvas to a PNG or JPEG blob (canvas.toDataURL()).
Re-encode those images into a brand-new PDF using a generator like jsPDF.

[Vector PDF] ──> [Rasterize to 72/150 DPI Bitmap] ──> [Re-wrap into new PDF]

It works on a prototype demo, but in production, it's a disaster:

Text searchability is obliterated: Ctrl+F stops working because glyph strings were converted into flat pixels.
File sizes explode: A 200 KB contract with crisp vector typography suddenly turns into a 35 MB blob of compressed JPEGs.
Print degradation: Vector shapes and true type fonts scale infinitely; rasterized canvases become blurry pixel soup when sent to high-DPI office printers.
Metadata stripped: Hyperlinks, form fields, and bookmark outlines vanish.

To merge PDFs properly, you cannot treat pages as images. You must treat them as object graphs.

What a PDF File Actually Looks Like

At its core (as standardized in ISO 32000), a PDF is divided into four distinct regions:

┌──────────────────────────────────────────┐
│  1. Header (%PDF-1.7)                    │
├──────────────────────────────────────────┤
│  2. Body                                 │
│     1 0 obj << /Type /Catalog ... >>     │
│     2 0 obj << /Type /Pages ... >>       │
│     3 0 obj << /Type /Page ... >>        │
│     4 0 obj << /Length 284 >> stream ... │
├──────────────────────────────────────────┤
│  3. Cross-Reference Table (xref)          │
│     0000000000 65535 f                   │
│     0000000015 00000 n                   │
│     0000000128 00000 n                   │
├──────────────────────────────────────────┤
│  4. Trailer                              │
│     << /Size 5 /Root 1 0 R >>            │
│     startxref                            │
│     1024                                 │
│     %%EOF                                │
└──────────────────────────────────────────┘

Notice the architecture: PDF readers do not read from top to bottom.

When a PDF engine opens a file:

It seeks directly to the last 1,024 bytes to find the %%EOF marker and the startxref pointer.
It reads the byte offset of the Cross-Reference Table (xref) or Cross-Reference Stream.
The xref table tells the engine the exact physical byte positions of every indirect object (1 0 obj, 2 0 obj, etc.) in the file.
It resolves the /Root dictionary (the Catalog), traverses the /Pages tree, and loads only what is needed to display page 1.

Every page is a node inside a tree structure, pointing to resources, content streams, and font dictionaries.

The Real Technical Hurdles of Merging

When you combine File A (10 pages) and File B (15 pages) into a single document, you cannot simply concatenate the byte buffers. Here is what makes combining them non-trivial.

1. Object Number ID Collisions

In File A:

4 0 obj
<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
endobj

In File B:

4 0 obj
<< /Type /XObject /Subtype /Image /Width 600 /Height 400 ... >>
endobj

Both documents have an object numbered 4 0 obj. If you put them in the same file without remapping, the parser hits an ID collision.

The merger must parse the indirect object table, maintain an ID translation map (SourceDocA_Obj4 -> TargetDoc_Obj18), and rewrite every indirect reference (4 0 R -> 18 0 R) across dictionaries, stream descriptors, and arrays.

2. The `/Pages` Hierarchy & Inherited Attributes

Pages in a PDF are not a flat array; they form a tree structure.

          /Pages (Root)
         /             \
    /Pages (Branch)    /Pages (Branch)
     /        \          /        \
  /Page      /Page    /Page      /Page

Here is a common edge case: according to the PDF specification, attributes like /MediaBox (the page width/height), /Rotate, and /Resources can be defined on an ancestor /Pages node rather than on the individual /Page leaf.

If you extract a /Page dictionary from File A that relies on an inherited /Rotate 90 or an inherited font resource from its parent /Pages node, and you clone only the leaf node into the target document without flattening inherited properties, the page will render blank or rotated incorrectly.

A solid merger must traverse up the source document's tree, resolve any inherited attributes, and explicitly hoist them into the newly copied page dictionary.

3. Font Subsets and Duplication

When software like InDesign, Word, or LaTeX compiles a PDF, it rarely embeds full font files. Instead, it embeds font subsets—packaging only the exact glyphs used in the document (often prefixed with a random tag, like XYZABC+Roboto-Regular).

If File A and File B both use Roboto-Regular, their subset dictionaries will have entirely different glyph mapping tables (CMap / ToUnicode).

You cannot blindly merge or deduplicate /Font objects simply because their base names match. Each font subset must either remain isolated as an independent indirect object or undergo full CMap reconciliation to avoid turning characters into garbled question marks.

Doing It Right in Modern JavaScript

Thanks to libraries like pdf-lib, we don't have to write raw byte stream re-mappers by hand for standard workflows. pdf-lib handles object re-indexing, indirect reference translation, and stream cloning purely in memory.

Here is a lean, battle-tested pattern for combining multiple PDF files in modern TypeScript:

import { PDFDocument } from 'pdf-lib';

interface MergeProgressCallback {
  (current: number, total: number): void;
}

/**
 * Merges multiple PDF ArrayBuffers into a single Uint8Array
 * without re-encoding or rasterizing vector streams.
 */
export async function mergePdfBuffers(
  pdfBuffers: ArrayBuffer[],
  onProgress?: MergeProgressCallback
): Promise<Uint8Array> {
  // 1. Create a pristine target document
  const mergedDoc = await PDFDocument.create();

  for (let i = 0; i < pdfBuffers.length; i++) {
    const buffer = pdfBuffers[i];

    // 2. Load the source PDF into an isolated object graph
    const srcDoc = await PDFDocument.load(buffer, {
      ignoreEncryption: true,
      parseSpeed: 1, // Balance between memory footprint and parsing speed
    });

    // 3. Resolve page indices and copy references
    const pageIndices = srcDoc.getPageIndices();
    const copiedPages = await mergedDoc.copyPages(srcDoc, pageIndices);

    // 4. Add pages to the target tree while preserving original MediaBox geometry
    for (const page of copiedPages) {
      mergedDoc.addPage(page);
    }

    if (onProgress) {
      onProgress(i + 1, pdfBuffers.length);
    }
  }

  // 5. Serialize the unified object graph and reconstruct the xref table
  return await mergedDoc.save({
    useObjectStreams: true, // Compresses indirect objects into streams
  });
}

Why this approach works:

Zero rasterization: copyPages transfers raw /Contents streams and referenced font dictionaries directly into the new document catalog.
Dimension preservation: If File 1 is an A4 portrait contract and File 2 is an A3 landscape spreadsheet, each page's native /MediaBox and /CropBox remain untouched. They coexist naturally without artificial margins.
Selectable text: Vector glyph coordinates and /ToUnicode mapping streams stay fully intact.

Memory Management in the Browser

Running this inside Node.js or a Go worker is relatively straightforward because server processes can allocate large heaps. Doing this entirely inside a user's browser tab is where real-world constraints kick in.

A modern browser tab typically hits an Out-Of-Memory (OOM) ceiling when JavaScript heap allocations push past 1.5 GB to 2 GB (especially on mobile WebKit).

When merging 10 files that are 50 MB each, you aren't just handling 500 MB of data:

Each file starts as a File or Blob.
It gets unpacked into an ArrayBuffer.
The parser converts byte streams into JavaScript objects (dictionaries, arrays, numbers).
The new document builds an internal intermediate representation.
The serializer creates a final Uint8Array.

If you hold references to all parsed source documents in a single array simultaneously, your tab will crash.

Practical Optimizations:

Sequential Processing & Garbage Collection: Load, copy, and immediately let the source document fall out of scope before loading the next one.

   // ❌ Bad: Keeps all source docs in memory at once
   const loadedDocs = await Promise.all(buffers.map(b => PDFDocument.load(b)));

   // ✅ Good: One at a time, allowing GC to collect completed source documents
   for (const buf of buffers) {
     const doc = await PDFDocument.load(buf);
     const pages = await mergedDoc.copyPages(doc, doc.getPageIndices());
     pages.forEach(p => mergedDoc.addPage(p));
     // 'doc' can now be garbage-collected
   }

Revoke Object URLs Promptly: When triggering the file download:

   const blob = new Blob([mergedBytes], { type: 'application/pdf' });
   const url = URL.createObjectURL(blob);

   const a = document.createElement('a');
   a.href = url;
   a.download = 'merged-document.pdf';
   a.click();

   // Don't leak the blob in the browser's internal URL store
   setTimeout(() => URL.revokeObjectURL(url), 10_000);

Offloading to Web Workers: Parsing heavy documents can block the main UI thread for several seconds, freezing CSS animations and user inputs. Moving the PDFDocument.load and mergedDoc.save calls into a dedicated Web Worker keeps your UI running at a smooth 60 FPS while background threads crunch byte arrays.

Handling Tricky Edge Cases

If you are implementing this in production, keep these three edge cases on your radar:

Linearized PDFs ("Fast Web View"): Linearized PDFs store a primary hint stream near the front of the file so web viewers can show page 1 before downloading the full file. When merging, linearization tables are invalid and must be stripped; the target file needs a standard xref table reconstruction.
AcroForms (Fillable Forms): If Document A has a text field called first_name and Document B also has a field called first_name, merging them naively can cause field values to overwrite each other. In a production pipeline, form fields either need unique namespace prefixes or should be flattened prior to merging depending on the use case.
Encrypted Documents: Even if a PDF doesn't ask for a password to open, it might carry an "Owner Password" with permission flags that restrict content extraction. Handling this gracefully requires checking isEncrypted flags and notifying the user upfront.

Wrapping Up

Building tools that touch PDFs requires respecting the format's architecture. The moment you step away from lossy image-conversion tricks and start working directly with object trees and byte streams, you get results that are fast, lightweight, and faithful to the original documents.

If you want to see this kind of client-side stream cloning in action without sending documents through a remote cloud queue, you can try out the implementation over at VersaPDF's Merge Tool. It processes the entire pipeline locally in the browser sandbox, illustrating how much heavy lifting modern web runtimes can achieve.

What edge cases have you run into when working with binary document formats in the browser? Let's discuss in the comments below.

Stop Treating Base64 Like Black Magic: A Veteran's Candid Guide

Miller Elias — Fri, 09 Oct 2026 06:52:47 +0000

Let’s be honest for a second: Base64 is one of those primitives almost every developer touches every week, yet an alarming number of people still treat it like mysterious wizardry.
I’ve lost count of how many PRs I’ve reviewed where someone said, "Don't worry, the sensitive token is encrypted with Base64," or watched a junior engineer spend half an afternoon staring at their screen because window.btoa() blew up on a simple emoji.

Let’s pull up a chair, skip the academic jargon, and talk about what Base64 actually is, how the math works in plain English, and the real-world traps you need to dodge in production.

1. It’s Not Encryption (Please Stop Saying That)

First things first: Base64 is NOT encryption. It never was, and it never will be.
Here is the simple analogy: if encryption is a locked steel bank vault requiring a secret key, Base64 is simply folding a letter into an origami crane so it fits into an odd-shaped envelope. Anyone who intercepts the crane can unfold it in two seconds flat.

Why was it invented?

Back when the early plumbing of the internet was laid down, legacy network protocols (like early SMTP email relays) were built strictly for 7-bit ASCII text.
If you tried to send raw binary—like an image or an executable file—through those pipes, intermediate routers would randomly drop the highest bit, mangle carriage returns, or choke on null bytes (\0).

Base64 was the pragmatic survival fix: take any raw binary stream, chop it up, and translate it into a safe, polite subset of 64 standard printable ASCII characters (`A–Z`, `a–z`, `0–9`, `+`, `/`) that no router on earth could misunderstand.

2. The Simple Math: Why 3 Bytes Turn Into 4 Characters

You don’t need a computer science degree to understand the bit-twiddling here. It’s just basic grade-school arithmetic:

A regular byte has 8 bits.
The Base64 dictionary has 64 characters. Because $2^6 = 64$, you only need 6 bits to represent each character.
How do you make 8-bit pieces fit into 6-bit pieces without wasting space? Find the common denominator: 24 bits. Take 3 raw bytes ($3 \times 8 = 24\text{ bits}$). Now slice that exact same 24-bit window into 4 chunks of 6 bits each ($4 \times 6 = 24\text{ bits}$). Look up those 6-bit values in the Base64 index table, and boom: 3 input bytes become 4 printable characters.

Raw Bytes (3 x 8 = 24 bits):
[ 01001000 ]   [ 01101001 ]   [ 00100001 ]  --> ASCII "Hi!"
Re-sliced into 6-bit chunks (4 x 6 = 24 bits):
[ 010010 ]     [ 000110 ]     [ 100100 ]     [ 100001 ]
   ↓              ↓              ↓              ↓
 Index 18       Index 6        Index 36       Index 33
   ↓              ↓              ↓              ↓
   S              G              k              h
---------------------------------------------------------
Output String: "SGkh"

The Inescapable 33% Tax

Notice what just happened? You fed in 3 bytes, and got 4 characters back.
That means Base64 introduces a mathematical, non-negotiable +33.33% payload expansion. If you convert a 9 MB image into Base64, you now have a 12 MB string traveling across the wire. Always factor this in before embedding assets into an API response!

What’s with the `=` at the end?

If your input doesn't divide evenly by 3, you’ll have 1 or 2 leftover bytes. The encoder pads the missing bits with zeroes and slaps one or two = characters on the tail (= or ==).

Historically, this was just a courtesy flag telling older parsers: "Hey, ignore the extra zero padding at the very end."

3. The URL Trap: Standard Base64 vs Base64URL

Here’s a classic gotcha that has triggered countless late-night production incidents:
Standard Base64 reserves two special punctuation characters: + and /.
Now imagine you take a signed token or user payload, encode it with standard Base64, and pass it as a URL query parameter:

https://myapp.com/confirm?token=ab+cd/ef==

Here is what goes wrong:

The HTTP server interprets + as an encoded space (" ").
Your routing framework sees / and treats it as a path delimiter.
The = sign collides with key-value query parameter parsing. By the time your backend code reads token, the string is already corrupted. Your cryptographic signature verification fails, and you're left debugging ghost errors. The Fix: Always use Base64URL (RFC 4648 §5) on the web. It simply swaps + for -, swaps / for _, and strips the trailing = padding entirely. This is why JSON Web Tokens (which start with eyJhbGci...) look so clean—they are strictly Base64URL. --- ## 4. The JavaScript Landmine: Why btoa() Hates You If you write JavaScript in the browser, you’ve probably tried this in your console:

window.btoa("Hello, World 🚀");
// 💥 Uncaught DOMException: Failed to execute 'btoa' on 'Window': 
// The string to be encoded contains characters outside of the Latin1 range.

Why does it crash?

window.btoa() is a legacy API from the early browser days. It strictly expects single-byte characters within the Latin-1 range (ASCII 0 to 255). The second you feed it a Chinese character, an accented letter, or a modern emoji, its UTF-16 code point exceeds 255, and the runtime immediately throws an InvalidCharacterError.

How to do it cleanly today

Forget fragile legacy hacks like unescape(encodeURIComponent()). Modern browsers give us the native TextEncoder API:

// Robust UTF-8 to Base64 Encoder
function toBase64(str) {
  const bytes = new TextEncoder().encode(str);
  const binString = Array.from(bytes, (byte) => String.fromCharCode(byte)).join('');
  return window.btoa(binString);
}
// Robust Base64 to UTF-8 Decoder
function fromBase64(base64) {
  const binString = window.atob(base64);
  const bytes = Uint8Array.from(binString, (char) => char.charCodeAt(0));
  return new TextDecoder().decode(bytes);
}
console.log(toBase64("Hello, World 🚀")); 
// Outputs cleanly: "SGVsbG8sIOS4lueVjCDwn5mp"

By serializing the string into an explicit array of 8-bit UTF-8 octets first, every single byte fed to `btoa` is guaranteed to stay within `0..255`.

5. Stop Stuffing Big Images Into Data URLs

Every frontend developer discovers data:image/png;base64,... and thinks: "Awesome! I can save an HTTP request by embedding the image directly in my CSS or JSON!"
Here is the reality check:

You destroy browser caching: If an image lives as an independent static file, the browser caches it aggressively via HTTP headers. When embedded into an API response or CSS, users re-download that payload on every single page request.
You blow up bundle size: Remember that 33% expansion tax? A 300 KB image turns into 400 KB over the wire.
You punish the JS engine: Giant string allocations inside JSON payloads force browser memory managers and garbage collectors (GC) to work overtime. Rule of Thumb: Only use Data URLs for micro-assets under 2 KB (like tiny placeholders or inline SVGs). Store everything else in object storage behind a CDN. --- ## 6. A Sanity Check on Debugging When you're knee-deep in debugging—checking an Authorization: Basic header, inspecting webhook payloads, or testing an API response—you just want to quickly encode or decode a string. A critical security reminder: Never paste sensitive production credentials into random, unverified online tools. Many ad-filled converter sites send your inputs to a remote backend server, meaning your customer tokens and auth headers could sit in third-party server access logs. When I need to inspect Base64 strings quickly, I stick to tools that run 100% client-side in the browser. CodeKivo's Base64 Encoder & Decoder is a great example of doing this right:
100% In-Memory Execution: Operates entirely within your local browser sandbox—zero network requests, zero remote logging.
Full UTF-8 & Emoji Support: Handles multi-byte Unicode strings cleanly without throwing Latin-1 errors.

- One-Click URL-Safe Toggle: Instantly switches between RFC 4648 Standard and Base64URL formats so you don't have to manually swap `-` and `_`.

Summary

At the end of the day, Base64 isn't complicated once you understand its purpose:

It's a courier, not a bodyguard: Never use it to hide sensitive data.
Account for the 33% bloat: Don't blindly embed binary files into JSON.
Use Base64URL in web requests: Save yourself from URL-escaping nightmares.
Normalize Unicode before calling btoa(): Always use TextEncoder. Master these basic fundamentals, and you’ll spend far less time troubleshooting silly production bugs.