DEV Community: Vitalii Popov

Two credentials, two threat models: auth for a content API

Vitalii Popov — Thu, 23 Jul 2026 21:03:19 +0000

A headless content API has two kinds of callers, and it's tempting to secure them the same way. That's the mistake.

There's a human logging into an admin UI to edit content, and there's a machine — a website, a build step — pulling published content through a delivery endpoint. They authenticate with different credentials, and those credentials have opposite properties. Treat them identically and you either make the machine path painfully slow or the human path dangerously weak.

I built a small headless content API (Depot) partly to get this boundary right. Here's the reasoning.

The two credentials

A session proves "this human is logged in." Short-lived, rides in an httpOnly cookie, checked on management routes.

A delivery token proves "this machine may read this account's published content." Long-lived, sent as a Bearer header, checked on every public read.

Two auth surfaces, kept explicit:

/**
 * - requireUser()  — admin session (httpOnly JWT cookie) for the management API.
 * - requireToken() — a `depot_…` bearer token for the public delivery API.
 */

Why they get different hashing

Here's the part people get wrong. Both credentials get stored as hashes — never plaintext — but not the same kind of hash, and the reason is entropy.

Passwords are low-entropy. Humans pick summer2024. An attacker who steals your DB will brute-force guesses against the stored hashes, so you want hashing to be deliberately slow — that's exactly what bcrypt's cost factor buys you:

import bcrypt from "bcryptjs";

const ROUNDS = 10; // deliberately slow — the point is to resist brute force

export function hashPassword(plain: string): Promise<string> {
  return bcrypt.hash(plain, ROUNDS);
}

export function verifyPassword(plain: string, hash: string): Promise<boolean> {
  return bcrypt.compare(plain, hash);
}

Tokens are high-entropy. I generate them — 32 random bytes — so there's nothing to guess. A stolen hash can't be reversed by brute force because the keyspace is astronomically large. That means I don't need bcrypt's slowness, and I very much don't want it: this hash runs on every single delivery request. So tokens get a fast SHA-256:

/**
 * A token is `depot_<43 base64url chars>` — 32 bytes of entropy. Because it's
 * high-entropy we store a fast SHA-256 hash (not bcrypt): bcrypt is for
 * low-entropy human passwords; for random tokens SHA-256 is safe and fast
 * enough to hash on every delivery request. The plaintext is shown once.
 */
export function generateToken(): string {
  const bytes = crypto.getRandomValues(new Uint8Array(32));
  return PREFIX + toBase64Url(bytes);
}

export async function hashToken(token: string): Promise<string> {
  const data = new TextEncoder().encode(token);
  const digest = await crypto.subtle.digest("SHA-256", data);
  return toHex(new Uint8Array(digest));
}

The rule of thumb: bcrypt for what humans choose, SHA-256 for what you generate. Using bcrypt on a per-request delivery token would add real latency to every read for zero security gain. Using SHA-256 on a password would be a serious vulnerability. Same "hash the secret" instinct, opposite implementations.

One more detail: the plaintext token is shown once, at creation. After that only the hash exists in the DB. If the database leaks, the tokens in it are useless — same guarantee as passwords.

The guard, and the ownership check hiding in it

The token guard does the read-path auth. Note what it returns:

export async function requireToken(req: Request) {
  const token = bearer(req);
  if (!token || !looksLikeToken(token)) throw unauthorized("Provide a delivery token");

  const hash = await hashToken(token);
  const row = await db.query.apiTokens.findFirst({
    where: eq(apiTokens.tokenHash, hash),
  });
  if (!row) throw unauthorized("Invalid delivery token");

  // Fire-and-forget last-used bookkeeping; never block the read on it.
  void db.update(apiTokens)
    .set({ lastUsedAt: new Date() })
    .where(eq(apiTokens.id, row.id))
    .catch(() => {});

  return { userId: row.userId, allowedOrigins: row.allowedOrigins };
}

Two things worth calling out.

It returns userId, not just "valid: true". Every downstream query scopes to that user. A valid token for account A can never read account B's content — the ownership boundary is carried by the auth result itself, not re-checked ad hoc in each route. Getting this wrong is how multi-tenant APIs leak data across tenants.

Last-used tracking is fire-and-forget. I want to know when a token was last used, but I will not make a content read wait on a bookkeeping write — void + .catch(() => {}) means it updates opportunistically and can never fail the request it's attached to.

Rate limiting, isolated so it's testable

The delivery API is public, so it needs a rate limit. The interesting decision here isn't the algorithm (fixed window) — it's that the algorithm is a pure function with no framework imports, so it can be unit-tested in isolation:

/**
 * Pure fixed-window rate-limiting algorithm — no framework imports, so it can
 * be unit-tested under `node --test`. `rate-limit.ts` wraps this with the HTTP
 * concerns (throwing 429s, deriving the client key).
 */
export function checkLimit(key: string, opts: RateLimit, now = Date.now()) {
  const existing = buckets.get(key);
  if (!existing || now >= existing.resetAt) {
    const resetAt = now + opts.windowMs;
    buckets.set(key, { count: 1, resetAt });
    return { ok: true, remaining: opts.limit - 1, resetAt };
  }
  existing.count += 1;
  const remaining = Math.max(0, opts.limit - existing.count);
  return { ok: existing.count <= opts.limit, remaining, resetAt: existing.resetAt };
}

The now = Date.now() default is the whole trick: tests inject a fixed clock and assert window behaviour deterministically, with no setTimeout and no flakiness. Security-adjacent logic is exactly the code you want pinned by fast, boring tests.

CORS, scoped per token

The delivery API is meant to be called from browsers, so it needs CORS. Blanket Access-Control-Allow-Origin: * on an authenticated endpoint is the lazy answer. Instead each token carries its own allowedOrigins — the guard returns them, and the response echoes the origin only if it's on that token's allowlist. The reach of a token is scoped at the token level, not globally.

The takeaway

Auth isn't a layer you add at the end — it's a set of decisions about the shape of your credentials:

Match the hash to the secret's entropy. bcrypt (slow) for human passwords, SHA-256 (fast) for high-entropy generated tokens.
Show generated secrets once, store only the hash. A DB leak should hand the attacker nothing usable.
Carry the ownership boundary in the auth result, so tenant isolation isn't re-litigated per route.
Isolate security-adjacent logic (rate limiting) from the framework so it's deterministically testable. None of these are exotic. They're just decisions that are cheap to make correctly up front and expensive to retrofit.

Depot is open source — code and a live demo. It's part of a set of Contentful/Next.js projects I keep public at vitaliipopov.dev.

Building a custom Contentful Rich Text editor: the round-trip problem

Vitalii Popov — Thu, 16 Jul 2026 23:05:53 +0000

Contentful lets you replace the UI of a Rich Text field with your own App. That sounds like a front-end job — build a nicer editor, mount it in the field location, done.

It isn't. The editor UI is the easy 20%. The hard 80% is a small file most people never think about: the layer that converts between your editor's internal model and Contentful's stored document — losslessly, in both directions.

I built one on top of PlateJS (which is a Slate editor underneath), and this post is about that conversion layer — the part that actually decides whether the whole thing works.

Two models that don't match

Contentful Rich Text is a fixed JSON schema (@contentful/rich-text-types): a document whose content is a tree of blocks, inlines and text nodes, where formatting lives on text nodes as an array of marks:

{
  "nodeType": "document",
  "content": [
    {
      "nodeType": "paragraph",
      "content": [
        { "nodeType": "text", "value": "Hello ", "marks": [] },
        { "nodeType": "text", "value": "world", "marks": [{ "type": "bold" }] }
      ]
    }
  ]
}

Slate/Plate uses a different shape for the same idea: { type, children } elements, and text nodes where marks are just boolean props:

[
  {
    type: "p",
    children: [
      { text: "Hello " },
      { text: "world", bold: true }
    ]
  }
]

Same document, two representations. The editor speaks Plate; the field stores Contentful. So you need two functions:

Contentful document ──deserialize()──▶ Plate value ──▶ editor
       field       ◀──serialize()──── Plate value ◀── (debounced onChange)

And they have to be exact inverses. If serialize(deserialize(doc)) isn't equal to doc, then simply opening an entry and saving it — without touching anything — silently corrupts content. That's the round-trip problem.

The design decision that made it tractable

The temptation is to write a clever generic converter. I did the opposite: I made the two models mirror each other on purpose, so the transform is a thin, explicit mapping instead of a guessing game.

Plate node types are named to shadow Contentful's node types — p, h1, ul, li, blockquote, embedded-entry-block — so the mapping is just two lookup tables that are literal inverses of each other:

const BLOCK_TO_CF: Record<string, string> = {
  p: BLOCKS.PARAGRAPH,
  h1: BLOCKS.HEADING_1,
  h2: BLOCKS.HEADING_2,
  h3: BLOCKS.HEADING_3,
  blockquote: BLOCKS.QUOTE,
  hr: BLOCKS.HR,
  ul: BLOCKS.UL_LIST,
  ol: BLOCKS.OL_LIST,
  li: BLOCKS.LIST_ITEM,
};

// the inverse falls out for free
const CF_TO_BLOCK = Object.fromEntries(
  Object.entries(BLOCK_TO_CF).map(([k, v]) => [v, k]),
);

Marks get the same treatment — a bold mark on a Contentful text node becomes a bold: true prop on a Plate leaf, and back:

const MARK_PROPS = ["bold", "italic", "underline", "code"] as const;
const MARK_TO_CF: Record<(typeof MARK_PROPS)[number], string> = {
  bold: MARKS.BOLD,
  italic: MARKS.ITALIC,
  underline: MARKS.UNDERLINE,
  code: MARKS.CODE,
};
const CF_TO_MARK = Object.fromEntries(
  Object.entries(MARK_TO_CF).map(([k, v]) => [v, k]),
);

Deriving each inverse table with Object.fromEntries instead of hand-writing it isn't just less typing — it makes the inverse structurally guaranteed. You can't forget to add the reverse mapping for a node type, because there's only one source of truth.

The edge cases are the whole game

A demo with a bold paragraph round-trips fine. Real content breaks on the corners. The ones that mattered:

Empty nodes. Slate requires every element to have at least one child. Contentful is fine with an empty block. So deserializing has to backfill:

const children = node.content.map(cfNodeToPlate).filter(Boolean);
const ensureChildren = children.length ? children : [{ text: "" }];

Skip this and Slate throws the moment it tries to render an empty paragraph.

Void nodes — embeds. An embedded entry or asset has no editable text; it's a card that resolves its title through the CMA. In Slate terms that's a void node, and voids still need a dummy text child to satisfy the schema:

case BLOCKS.EMBEDDED_ENTRY:
  return {
    type: "embedded-entry-block",
    entryId: node.data?.target?.sys?.id,  // carry the id, nothing else
    children: [{ text: "" }],             // required, even though it's void
  };

The only thing you keep is the entry id. Everything visible about that card is resolved live — get the transform wrong here and you either lose the reference or store an invalid node the CDA rejects.

Unsupported node types. A generic editor doesn't implement every Contentful block. The safe move is to skip what you don't understand rather than crash or fabricate:

const plateType = CF_TO_BLOCK[node.nodeType];
if (!plateType) return null; // skip gracefully

Contentful-valid nesting. Lists have to be ul > li > p, not ul > li with raw text. If the editor produces the wrong nesting, the value looks fine in Plate and fails validation only when you save. The mapping has to produce schema-valid structure, not just structurally-similar structure.

Pin it with round-trip tests

None of this is provable by clicking around. The transform is a pure function with no React and no Contentful SDK in sight, which means it's trivially unit-testable — and the test that matters is the round-trip identity:

// for a representative document:
expect(serialize(deserialize(doc))).toEqual(doc);

Because the module is framework-free, the tests run in plain node --test without booting the editor. That's the payoff of keeping the conversion layer isolated: the riskiest part of the app is also the cheapest part to test exhaustively.

The takeaway

If you build a custom Contentful editor — or any editor that has to persist to a schema you don't control — treat the conversion layer as the core of the project, not an afterthought. Concretely:

Make the two models mirror each other so the mapping is explicit, not inferred.
Derive inverse tables from one source so you can't desync them.
Enumerate the edge cases — empty nodes, void nodes, unsupported types, valid nesting — because that's where round-trip breaks.
Isolate it from the framework and pin it with round-trip tests, since silent corruption is invisible until it isn't. The editor UI is what people see. The transform is what keeps their content intact.

The full editor is open source — code and a live demo. It's part of a set of Contentful/Next.js projects I keep public at vitaliipopov.dev.