DEV Community: Peter Hallander

Modelling Swedish intestate succession in TypeScript

Peter Hallander — Mon, 12 Oct 2026 08:20:22 +0000

When someone in Sweden dies without a will, the Inheritance Code (ärvdabalken, SFS 1958:637) decides who gets what. The rules fit on two printed pages. They are also a small, well-defined algorithm: a walk over a family tree with a fixed priority order, equal splits per branch, and a couple of special cases for spouses.

I wrote that algorithm in TypeScript for a free calculator that answers "who inherits?" for Swedish users. This post explains the law for developers who do not read Swedish, and shows how each rule maps to code. The identifiers are Swedish because the output is Swedish, so I translate them as they come up.

The engine is one pure function, vemArver(input) ("who inherits"). No DOM, no I/O. It runs in the browser and under node:test.

The law in one screen

Chapter 2 of ärvdabalken defines three classes of relatives (arvsklasser). A class only inherits if every class above it is empty.

First class (2 kap. 1 §). The deceased's descendants. Children take equal shares. If a child is dead, that child's descendants step into its place, and each branch takes an equal share. This is called istadarätt, the right of representation. English legal texts call it per stirpes.
Second class (2 kap. 2 §). Parents take half each. If a parent is dead, the deceased's siblings share that parent's half, and a dead sibling's descendants step into its place. If there are no siblings or descendants of siblings, a living parent takes everything.
Third class (2 kap. 3 §). Grandparents take a quarter each. A dead grandparent's share goes to that grandparent's children (the deceased's aunts and uncles). If there are none, the other grandparent on the same side takes it. If one side has nobody, the other side takes everything.

Then two short rules close it off. 2 kap. 4 § says no other relatives inherit. Cousins get nothing. And 5 kap. 1 § says that if there is no heir under these rules, the estate goes to Allmänna arvsfonden, the state inheritance fund.

Chapter 3 then adds the surviving spouse, who inherits ahead of the children in most cases. More on that below, because it is where most of the interesting logic is.

Exact fractions, not floats

Before any tree walking, one decision shapes everything else. Shares are fractions, and the answer the user needs is "1/6", not "0.16666666666666666".

Floats fail here in two ways. First, display: a grandchild who takes one sixth must see one sixth. Second, invariants: the shares must sum to exactly 1, and with floats 1/3 + 1/3 + 1/6 + 1/6 is not reliably equal to 1. You end up with epsilon comparisons in your tests, and an epsilon test cannot tell a rounding artefact from a real bug where a branch got the wrong lot.

So the engine carries a tiny rational type and normalises on every construction:

export interface Frac { n: number; d: number }

const gcd = (a: number, b: number): number => (b === 0 ? Math.abs(a) : gcd(b, a % b));
export const frac = (n: number, d = 1): Frac => {
  if (d === 0) throw new Error('division by zero');
  if (n === 0) return { n: 0, d: 1 };
  const g = gcd(n, d);
  const s = d < 0 ? -1 : 1;
  return { n: (s * n) / g, d: (s * d) / g };
};
export const add = (a: Frac, b: Frac): Frac => frac(a.n * b.d + b.n * a.d, a.d * b.d);
export const sub = (a: Frac, b: Frac): Frac => frac(a.n * b.d - b.n * a.d, a.d * b.d);
export const mul = (a: Frac, b: Frac): Frac => frac(a.n * b.n, a.d * b.d);
export const div = (a: Frac, k: number): Frac => frac(a.n, a.d * k);
export const eq = (a: Frac, b: Frac) => a.n === b.n && a.d === b.d;

Because every value is reduced and the sign lives in the numerator, equality is a plain field comparison. frac(2, 6) and frac(1, 3) are the same object shape, so eq and deepEqual both work without a custom comparator.

Plain number is enough here. Input counts are clamped to 50 per branch, and the deepest split is roughly a quarter divided by a sibling count, so numerators and denominators stay tiny. If your domain can nest arbitrarily, use bigint for the same code.

Percentages are only computed at the very edge, for display:

export const fmtPct = (f: Frac) => {
  const v = Math.round((f.n / f.d) * 1000) / 10;
  return `${String(v).replace('.', ',')} %`;
};

The output shape: a line per branch

Each heir in the result is a line, not a person. A dead child with three children produces one line with antal: 3 (count), a share per person (var) and a share for the whole branch (totalt):

export interface Arvinge {
  key: string;
  label: string;
  antal: number;   // how many people share this line equally
  var: Frac;       // share of the estate for each person
  totalt: Frac;    // share for the whole line (var * antal)
  lagrum: string;  // the statute section that produced it
}

Two details matter. lagrum (the legal citation) travels with every line, so the UI can show "2 kap. 1 § 2 st ärvdabalken (istadarätt)" next to the number. A user, or a lawyer they show it to, can check where each share came from. And key is stable (barn-3, syskon-2), which is what lets the same people be merged when two rules hand them shares.

First class: children and representation

The first class is a single pass. A child who is alive is a branch. A dead child with living children is a branch. A dead child with no children is not a branch at all, and its share silently goes to the others, because the law divides among branches that exist.

function forstaKlassen(barn: Barn[]) {
  const grenar = barn
    .map((b, index) => ({ index, barn: { ...b, barn: clampCount(b.barn) } }))
    .filter((g) => g.barn.lever || g.barn.barn > 0);
  if (grenar.length === 0) return { lines: [], grenar };
  const lot = frac(1, grenar.length);
  const lines = grenar.map(({ index, barn: b }) => {
    const n = index + 1;
    if (b.lever) {
      return { key: `barn-${n}`, label: `Barn ${n}`, antal: 1, var: lot, totalt: lot,
               lagrum: '2 kap. 1 § ärvdabalken' };
    }
    return {
      key: `barnbarn-${n}`,
      label: `Barnbarn genom barn ${n} (${b.barn} st)`,
      antal: b.barn,
      var: div(lot, b.barn),
      totalt: lot,
      lagrum: '2 kap. 1 § 2 st ärvdabalken (istadarätt)',
    };
  });
  return { lines, grenar };
}

(grenar means branches, lever means alive, barnbarn means grandchildren.)

The filter is the whole of the representation rule. Count the branches first, then divide. Two living children and one dead child with two kids gives three branches: 1/3, 1/3, and 1/3 split into 1/6 each. If you divide by the number of children instead of the number of live branches, a childless dead child keeps eating a share that belongs to its siblings.

Second class: two halves and half siblings

The second class is easier to reason about if you stop thinking "parents first, then siblings" and start thinking "two halves of the estate, one per parent". Each half is resolved independently:

the parent is alive: the parent takes the half
the parent is dead: the siblings who share that parent split the half, with representation for dead siblings
nobody is left on that side: the half moves to the other side

That framing makes half siblings fall out naturally. 2 kap. 2 § 3 st says half siblings take part only in the share that would have gone to their own parent. A full sibling shares both parents, so a full sibling appears in both halves. A half sibling on the father's side appears only in the father's half.

function syskonPaSida(syskon: Syskon[], sida: 'mor' | 'far') {
  return syskon
    .map((s, index) => ({ index, s: { ...s, barn: clampCount(s.barn) } }))
    .filter(({ s }) =>
      (s.typ === 'hel' || s.typ === (sida === 'mor' ? 'halvMor' : 'halvFar')) &&
      (s.lever || s.barn > 0));
}

(mor is mother, far is father, hel is full sibling, halvMor and halvFar are half siblings through the mother or father.)

Each side returns either a list of lines or null for "nobody here". The combining step is where the fallback rules live:

const m = sideLines('mor');
const f = sideLines('far');
if (!m && !f) return [];
if (!m) return f!.length === 1 && f![0].key === 'far'
  ? [{ ...f![0], var: ONE, totalt: ONE, lagrum: '2 kap. 2 § 2 st ärvdabalken' }]
  : merge(scale(f!, frac(2)));
if (!f) return /* mirror image */;
return merge([...m, ...f]);

If the mother's half has nobody and the father is alive, the father takes everything. If the mother's half has nobody and the father is dead, the father's siblings get their half scaled up to the whole estate. That second case is the last sentence of 2 kap. 2 § 3 st: with no full siblings and both parents dead, the half siblings take the entire estate.

Then merge collapses lines that have the same key. A full sibling gets a quarter from each half when both parents are dead, and the user should see one line with 1/2, not two lines with 1/4:

function merge(list: Arvinge[]): Arvinge[] {
  const out = new Map<string, Arvinge>();
  for (const a of list) {
    if (isZero(a.totalt)) continue;
    const prev = out.get(a.key);
    if (!prev) { out.set(a.key, { ...a }); continue; }
    const totalt = add(prev.totalt, a.totalt);
    out.set(a.key, { ...prev, totalt, var: div(totalt, prev.antal) });
  }
  return [...out.values()];
}

Worked example: both parents dead, one full sibling and one half sibling on the mother's side. The father's half goes only to the full sibling (1/2). The mother's half is split by both (1/4 each). After merging: full sibling 3/4, half sibling 1/4. That is exactly the kind of number a float-based version would print as 0.75 and a user would not be able to check by hand.

Third class: grandparents and their children

The third class repeats the same pattern one generation up, with quarters instead of halves. Each grandparent owns a quarter. A dead grandparent's quarter goes to their children, who are the deceased's aunts and uncles. If there are no such children, the living grandparent on the same side takes the side's half. If a whole side is empty, the other side is scaled by two.

There is no representation below aunts and uncles in this class. Their children are cousins, and 2 kap. 4 § cuts cousins off completely. The code never models cousins at all. Nothing to compute means nothing to get wrong.

The surviving spouse: inheritance now, inheritance later

Here Swedish law departs from most other systems, and here the data model needs a second output.

3 kap. 1 § says that a married person's estate goes to the surviving spouse. The children do not lose their inheritance. They wait. When the surviving spouse later dies, the first deceased's heirs take a share of the spouse's estate. This deferred share is called efterarv, literally "after-inheritance". 3 kap. 2 § sets it as half of the spouse's estate as a main rule, but adjusted to whatever proportion the spouse actually received as inheritance.

The catch is särkullbarn: a child of the deceased who is not also the surviving spouse's child. A särkullbarn does not have to wait. They can take their share directly. They can also choose to wait and receive efterarv instead (3 kap. 9 §).

So the result has two lists. arvingar is who inherits now and always sums to 1. efterarvingar is who inherits from the first deceased's share when the spouse dies, expressed as shares of that future part:

const sarkull = grenar.filter((g) => !g.barn.gemensamt);
const avstar = !!input.sarkullbarnAvstar && sarkull.length > 0;
const nu: Arvinge[] = [];
const efter: Arvinge[] = [];
for (const line of klass1) {
  const n = Number(line.key.split('-').pop());
  const g = grenar.find((x) => x.index + 1 === n)!;
  if (g.barn.gemensamt || avstar) efter.push(line);
  else nu.push(line);
}
const makeDel = sub(ONE, sum(nu));

(gemensamt means "shared child", nu is "now", efter is "after", make is spouse, avstar is "waives".)

Notice the order of operations. The first class is computed exactly as if there were no spouse. Only then are branches sorted into "now" and "later". The spouse takes 1 - sum(nu). That is how 3 kap. 1 § is written: the spouse gets everything except the lots of särkullbarn who have not waived.

The deferred list is renormalised so that it reads as shares of the future part:

const efterSum = sum(efter);
const inv = isZero(efterSum) ? ONE : frac(efterSum.d, efterSum.n);
const efterNorm = isZero(efterSum) ? [] : scale(efter, inv);

With one shared child and one särkullbarn, the särkullbarn takes 1/2 now, the spouse takes 1/2, and the shared child is listed as taking 1/1 of the efterarv. This follows 3 kap. 2 § 2 st, which reduces a child's efterarv by whatever they already took out at the first death.

With no children at all, the spouse takes everything, and the second-class relatives (parents, siblings, their descendants) become the efterarv heirs. Grandparents and aunts do not, because 3 kap. 2 § lists only descendants, parents, siblings and siblings' descendants. If none exist, 3 kap. 8 § says the spouse's own heirs take everything later.

One more rule never shows up as a fraction: the spouse's floor. 3 kap. 1 § 2 st guarantees the spouse property worth four prisbasbelopp (a yearly indexed amount, 59,200 SEK for 2026), counted together with what they already own. It overrides särkullbarn and even a will. The engine cannot compute it without asset values, so it is emitted as a warning with the 2026 amount, not as a share.

Refusing is a feature

The result has a field most calculators do not have:

/** Branches the tool does not compute. Shown as "kontakta jurist". */
jurist: string[];

"Kontakta jurist" means "contact a lawyer". Every result carries a list of situations the tool deliberately does not handle:

there is a will, an inheritance contract or a prenup with special terms
the deceased did not live in Sweden, or there are assets abroad (another country's law may apply)
a grandchild or niece or nephew has also died and left children (the tool computes one generation of representation, not more)
a divorce case was pending at the death, in which case the spouse does not inherit at all (3 kap. 10 §)
in the third class, a parent of the deceased had half siblings

None of these are hard to code in isolation. Deeper representation is a recursion. The reason to refuse is about how the tool is used. A person typing their family into a free calculator usually does not know that a pending divorce case changes the answer, or that a house in Spain may bring Spanish law with it. A confident 1/4 with no caveat is worse than no answer, because people act on it.

So the scope is narrow on purpose, and the boundary is stated in the output, every time, next to the numbers. Each extra case would be one more silent assumption about the user's family. The tool says out loud what it did not do instead.

Testing it as a table of families

The test file is a list of families, each with the expected shares written as strings. A helper turns a result into a key -> "n/d" map, so a failing assertion shows the fractions directly:

const shares = (r: ArvResult, list: 'arvingar' | 'efterarvingar' = 'arvingar') =>
  Object.fromEntries(r[list].map((a) => [a.key, `${a.var.n}/${a.var.d}`]));

test('avlidet barn med två barnbarn: istadarätt per gren', () => {
  const r = run({ barn: [alive(), alive(), dead(2)] });
  assert.deepEqual(shares(r), { 'barn-1': '1/3', 'barn-2': '1/3', 'barnbarn-3': '1/6' });
});

test('båda föräldrarna döda, ett helsyskon och ett halvsyskon på mammas sida', () => {
  const r = run({ syskon: [{ typ: 'hel', lever: true, barn: 0 },
                           { typ: 'halvMor', lever: true, barn: 0 }] });
  assert.deepEqual(shares(r), { 'syskon-1': '3/4', 'syskon-2': '1/4' });
});

test('gift med ett gemensamt barn och ett särkullbarn', () => {
  const r = run({ civil: 'gift', barn: [alive(true), alive(false)] });
  assert.deepEqual(shares(r), { make: '1/2', 'barn-2': '1/2' });
  assert.deepEqual(shares(r, 'efterarvingar'), { 'barn-1': '1/1' });
});

There are 23 of these, one or more per statute paragraph, including the cases where a relative gets nothing (a half sibling on the side of the living parent, grandparents when there is a spouse, a cohabiting partner, who is not in the order of succession at all). Each expected value was worked out by hand from the statute text before the test ran. The test table is the spec, written in the law's own units.

On top of the table there is one invariant test. It runs messy families through the engine and checks that the shares sum to exactly 1:

for (const c of cases) assert.equal(fmtFrac(total(run(c))), 'allt', JSON.stringify(c));

fmtFrac returns "allt" ("everything") only for exactly 1/1. With exact fractions this is a real equality check. With floats it would be an epsilon check, and that is the test that would let a lost 1/12 slip through.

What I would tell someone modelling another country's rules

Draw the family as branches and divide by live branches, never by heads.
Resolve each half (or quarter) of the estate on its own, then merge by stable key. Half siblings and empty sides stop being special cases.
Keep the statute citation on every output line. It turns a number into a claim someone can check.
Use exact fractions. The sum-to-one invariant is your best test, and it only works without rounding.
Put the refused cases in the output, not in a FAQ. A list of what the tool did not compute is part of the answer.

The code above runs the free calculator at vittnet.nu/verktyg/vem-arver, which I built on this engine.

Swedish will-witness rules in TypeScript: 4 bugs a form engine must prevent

Peter Hallander — Wed, 07 Oct 2026 13:12:32 +0000

A Swedish will has almost no formal requirements. It must be in writing, the testator must sign it (or acknowledge an earlier signature) while two witnesses are present at the same time, and the witnesses sign it. There is no notary and no registry. That simplicity is exactly what makes it fragile: if one witness was not allowed to witness, the will, or part of it, can be void, and nobody finds out until the person is dead and the heirs start reading the document carefully.

I spent the last few months building a form engine that turns questions into Swedish legal documents (wills, cohabitation agreements, gift deeds) as PDF. Most of the interesting work was not the legal text. It was making sure the software could not produce a document that looks fine and is quietly invalid. These are the four bugs I designed out, with the code that does it.

1. Accepting a witness the law disqualifies

The rules are in chapter 10, section 4 of the Swedish Inheritance Code (10 kap. 4 § ärvdabalken). For a developer who does not read Swedish, they come in two groups.

Nobody in this group may witness the will at all:

anyone under 15
anyone who, because of a mental disorder, cannot understand what witnessing means
the testator's spouse or cohabiting partner (sambo)
the testator's relatives in a straight line up or down (parents, grandparents, children, grandchildren)
the testator's siblings
the testator's in-laws (svågerlag)

In the second group, the bar is narrower: nobody may witness a provision that benefits

themselves
their own spouse, sambo, sibling, straight-line relative or in-law
a person they act for as guardian, administrator, trustee or holder of a lasting power of attorney
a company, association, religious community or foundation where they sit on the board

One explicit exception: being named executor does not disqualify you.

The legal effect differs between the groups. The first group makes the witnessing defective. The second group is about the specific provision. In practice that distinction does not matter for a product. A user who wanted to leave the summer house to a niece does not want a will where that gift is void because the niece's husband signed as a witness. So the engine treats every one of these as a hard error that blocks checkout.

The data model is a single list of options the user picks from for each witness. Everything except none is a disqualification:

type Option = { value: string; label: string };

export const WITNESS_RELATIONS: Option[] = [
  { value: 'none',       label: 'No relation listed below' },
  { value: 'partner',    label: "Testator's spouse or sambo" },
  { value: 'lineal',     label: 'Child, grandchild, parent, grandparent or other straight-line relative' },
  { value: 'sibling',    label: 'Sibling' },
  { value: 'inlaw',      label: 'Brother-, sister-, parent-, son- or daughter-in-law' },
  { value: 'receiver',   label: 'Receives something under the will, or is close family of someone who does' },
  { value: 'board',      label: 'Board member of a company or organisation that receives something' },
  { value: 'under15',    label: 'Under 15' },
  { value: 'guardian',   label: 'Guardian, administrator or attorney-in-fact for someone involved' },
  { value: 'capacity',   label: 'Cannot understand what being a witness means' },
];

(The real labels are in Swedish. I translated them here.)

Asking the user to classify the witness is the main check, but people pick "none" without reading. So the validator also compares names against everything else in the answers: the testator, the partner, and every person who receives something.

function same(x: string, y: string): boolean {
  const norm = (s: string) => s.trim().toLowerCase().replace(/\s+/g, ' ');
  return !!x && !!y && norm(x) === norm(y);
}

// inside validate(answers)
const testators = [str(a, 't1_name')];
const receivers = [
  ...items(a, 'bequests').map((it) => str(it, 'name')),
  ...items(a, 'shares').map((it) => str(it, 'name')),
  str(a, 'partner_name'),
];

for (const i of [1, 2]) {
  const name = str(a, `w${i}_name`);
  if (!name) continue; // naming witnesses up front is optional
  const rel = str(a, `w${i}_relation`);

  if (rel && rel !== 'none') {
    issues.push({ level: 'error', field: `w${i}_relation`,
      message: `${name} cannot be a witness. ${WITNESS_ERRORS[rel]}` });
  } else if (testators.some((t) => same(t, name))) {
    issues.push({ level: 'error', field: `w${i}_name`,
      message: 'The person making the will cannot witness it.' });
  } else if (receivers.some((r) => same(r, name))) {
    issues.push({ level: 'error', field: `w${i}_name`,
      message: `${name} receives something under the will and cannot be a witness.` });
  }
}
if (same(str(a, 'w1_name'), str(a, 'w2_name'))) {
  issues.push({ level: 'error', field: 'w2_name', message: 'You need two different witnesses.' });
}

Two design notes. First, the name match is deliberately dumb: case and whitespace only, no fuzzy matching. A fuzzy match that flags "Anna Berg" against "Anna Bergström" produces false errors that teach users to ignore errors. Second, this check cannot be complete. The software cannot know that the witness is the beneficiary's brother-in-law. That is why the printed document ends with an appendix page that lists the disqualified groups as a checklist the testator reads before the signing. The validator catches the mistakes it can see, and the paper covers the rest.

2. Getting the century wrong in a personnummer

Every party in these documents is identified by a Swedish personal identity number, the personnummer. It looks simple and has four traps.

Two lengths. People write YYMMDD-NNNN (10 digits) or YYYYMMDD-NNNN (12 digits). Store one canonical form.
The check digit covers 10 digits only. It is a Luhn (mod 10) checksum over YYMMDDNNN plus the check digit. The century is not part of it.
The separator carries information. In the 10-digit form, - means the person is under 100, and + means they are 100 or older. 121212-1212 is born in 2012, 121212+1212 in 1912.
Coordination numbers. People who are not registered as residents get a samordningsnummer, which is the same format with 60 added to the day. Born on the 14th becomes 74. Your date validation rejects it unless you know.

Here is the normaliser. It returns YYYYMMDD-NNNN or null.

export function normalisePnr(raw: string, today = new Date()): string | null {
  const s = raw.replace(/\s/g, '');
  const m = /^(\d{2})?(\d{2})(\d{2})(\d{2})([-+]?)(\d{4})$/.exec(s);
  if (!m) return null;
  let [, cent, yy, mm, dd, sep, last] = m;

  // Coordination numbers add 60 to the day.
  const day = Number(dd) > 60 ? Number(dd) - 60 : Number(dd);

  if (!cent) {
    // Pick the most recent birth date that is not in the future,
    // then go back 100 years if the separator is '+'.
    let full = 2000 + Number(yy);
    if (Date.UTC(full, Number(mm) - 1, day) > today.getTime()) full -= 100;
    if (sep === '+') full -= 100;
    cent = String(full).slice(0, 2);
  }

  // Luhn over the 10 digits YYMMDDNNNC: double every other digit from the left.
  const ten = `${yy}${mm}${dd}${last}`;
  let sum = 0;
  for (let i = 0; i < 10; i++) {
    let d = Number(ten[i]) * (i % 2 === 0 ? 2 : 1);
    if (d > 9) d -= 9;
    sum += d;
  }
  if (sum % 10 !== 0) return null;

  // Reject 31 February and friends.
  const date = new Date(Date.UTC(Number(cent + yy), Number(mm) - 1, day));
  if (date.getUTCMonth() !== Number(mm) - 1 || date.getUTCDate() !== day) return null;

  return `${cent}${yy}${mm}${dd}-${last}`;
}

My first version compared only the year: if (2000 + yy > currentYear) full -= 100. That is wrong for one narrow group. Someone born in December 1926, writing their number with - in October 2026, is 99. The year check puts them in 2026, which is a future birth date, which makes their age negative. For a will, that matters: the age check (you must be 18 to make a will) then blocks a 99-year-old from writing one. Comparing the full date, as above, fixes it. It is the kind of bug no test catches unless you write the test on purpose, so write that test.

Note that the normalised output keeps the original day, +60 included. The personnummer is an identifier, not a date, and rewriting the day would produce someone else's number. Anything that needs the birth date strips the offset itself:

/** Age in whole years on `onIso` (YYYY-MM-DD) for a normalised personnummer. */
export function ageFromPnr(pnr: string, onIso: string): number | null {
  const m = /^(\d{4})(\d{2})(\d{2})-/.exec(pnr);
  if (!m) return null;
  const day = Number(m[3]) > 60 ? Number(m[3]) - 60 : Number(m[3]);
  const [y, mo, d] = onIso.split('-').map(Number);
  let age = y - Number(m[1]);
  if (mo < Number(m[2]) || (mo === Number(m[2]) && d < day)) age--;
  return age;
}

This is plain calendar arithmetic, with no Date and no time zones, which is what you want for "has this person turned 18 today".

If you need the official description of the format, Skatteverket's page on personnummer is the source.

3. Trusting answers to fields the user can no longer see

A will form has many branches. Are you married, a sambo or single? Do you have children? Do you have children from an earlier relationship? Do you want to leave specific items to specific people? Each answer shows or hides later questions.

The conditions are data, not code, so the client and the server read the same definition:

export type Cond =
  | { field: string; equals: string }
  | { field: string; in: string[] }
  | { field: string; notEmpty: true }
  | { field: string; isEmpty: true }
  | { all: Cond[] }
  | { any: Cond[] }
  | { not: Cond };

// A field that only appears for married or cohabiting testators:
{ id: 'partner_name', type: 'text', label: 'Partner name',
  showIf: { all: [ { field: 'will_kind', equals: 'individual' },
                   { field: 'civil_status', in: ['married', 'sambo'] } ] } }

The evaluator is a dozen lines:

export function test(c: Cond | undefined, s: Scope): boolean {
  if (!c) return true;
  if ('all' in c) return c.all.every((x) => test(x, s));
  if ('any' in c) return c.any.some((x) => test(x, s));
  if ('not' in c) return !test(c.not, s);
  const v = lookup(c.field, s);
  const sv = typeof v === 'string' ? v : '';
  if ('equals' in c) return sv === c.equals;
  if ('in' in c) return c.in.includes(sv);
  if ('notEmpty' in c) return Array.isArray(v) ? v.length > 0 : sv.trim() !== '';
  if ('isEmpty' in c) return Array.isArray(v) ? v.length === 0 : sv.trim() === '';
  return true;
}

Here is the bug that sounds trivial and is not. The user says they are married, enters their spouse's name and picks "my spouse gets everything". Then they change their mind, go back and pick "single". The partner fields disappear from the screen. But the client still has partner_name and main_heir: 'partner' in its state, and it posts them.

If the server validates and builds from the raw request, the document now contains a clause leaving everything to a spouse the user has said does not exist. Worse, the witness check above would compare witnesses against that phantom spouse. And separately from honest stale state, anyone can post a crafted request with fields the form never asked for.

So the first thing the server does with any request is prune it: keep only answers to fields that are visible given the other answers, clean each value by its field type, and drop everything else.

export function prune(def: DocumentDef, raw: Record<string, unknown>): Answers {
  const out: Answers = {};
  // Two passes, so a condition can depend on a field later in the form.
  for (let pass = 0; pass < 2; pass++) {
    for (const step of def.steps) {
      if (!test(step.showIf, { top: out })) {
        for (const f of step.fields) delete out[f.id];
        continue;
      }
      for (const f of step.fields) {
        if (f.type === 'info') continue;
        const visible = pass === 0 || test(f.showIf, { top: out });
        if (!visible) { delete out[f.id]; continue; }
        out[f.id] = f.type === 'repeater'
          ? cleanItems(f, raw[f.id], out)   // same idea, one level down
          : cleanValue(f, raw[f.id]);
      }
    }
  }
  return out;
}

Three properties make this safe:

The output is built from the definition, not from the input. It iterates over def.steps, so a key that is not a field can never reach out. There is no denylist to forget to update.
Every value goes through its type. cleanValue caps length, collapses whitespace, turns checkbox values into exactly 'ja' or '', strips non-digits from money fields and runs normalisePnr on personnummer fields.
The pipeline order is fixed. Every API route calls one function:

export function evaluate(def: DocumentDef, raw: Record<string, unknown>) {
  const answers = prune(def, raw);
  const schemaIssues = validateSchema(def, answers);
  // Legal checks only run once the basics hold, so document authors can rely on them.
  const legal = schemaIssues.some((i) => i.level === 'error') ? [] : def.validate(answers);
  const issues = [...schemaIssues, ...legal];
  return { answers, issues, ok: !issues.some((i) => i.level === 'error') };
}

The document's own validate() and build() only ever receive pruned answers. That contract is written in the type definition, and it is why the witness check can trust that partner_name means a partner exists.

4. A signature page that can be swapped

The witnesses sign an attestation, a short paragraph saying the testator signed in their simultaneous presence, of sound mind and free will. Their signatures prove that the testator signed this document.

Now consider a PDF layout where the testator's signature lands at the bottom of page 3 and the witness box flows to the top of page 4. Page 4 is now a sheet with a generic attestation and two witness signatures on it. Nothing on it ties it to the will on pages 1 to 3. Someone could print a different page 1 to 3 and staple the original page 4 to it.

So the renderer keeps the testator's signature block and the witness block on one page. I use pdf-lib, which gives you raw drawing primitives and no layout engine, so "keep together" is something you write yourself. The renderer tracks a cursor y and starts a new page when a block does not fit:

function ensure(ctx: Ctx, needed: number) {
  if (ctx.y - needed < MARGIN_BOTTOM) newPage(ctx);
}

Before drawing a signature block that is directly followed by a witness block, it measures both and asks for the combined height:

model.blocks.forEach((b, i) => {
  const next = model.blocks[i + 1];
  if (b.t === 'signatures' && next?.t === 'witnesses') {
    const sigH = (b.intro ? 40 : 0) + (b.placeDate !== false ? 40 : 0)
      + Math.ceil(b.signers.length / 2) * 84 + 10;
    const witTextLines = wrapRich(next.text, 10, CONTENT_W - 28, fonts, true).length;
    const witH = 26 + witTextLines * 14.5 + (next.lines?.length ?? 5) * 26 + 30;
    // Only force a break if the pair fits on an empty page at all.
    if (sigH + witH < PAGE_H - MARGIN_TOP - MARGIN_BOTTOM) ensure(ctx, sigH + witH);
  }
  block(ctx, b);
});

The witness text is wrapped with the same function that draws it, so the measured height is the drawn height. The guard on the last line matters: if the pair could never fit on one page, forcing a break would just produce an empty page and change nothing.

Two cheaper measures back this up. Every page of the document except the last gets an initials line in the footer, so the testator can initial each page. And the footer prints "page N of M" with the total, so a removed or added page is visible.

Fonts: å, ä and ö

The standard 14 PDF fonts that pdf-lib can use without embedding are encoded in WinAnsi. That covers å, ä and ö, so Swedish text appears to work, until a name contains a character outside WinAnsi and the PDF build throws. Names come from users, so that happens. Embedding real TrueType fonts through fontkit removes the class of problem:

import { PDFDocument } from 'pdf-lib';
import fontkit from '@pdf-lib/fontkit';

const doc = await PDFDocument.create();
doc.registerFontkit(fontkit);
const serif = await doc.embedFont(await loadFontBytes('Spectral-Regular'), { subset: true });

subset: true keeps only the glyphs actually used, so four embedded fonts still produce a small file. Two things that bit me: load the TTF bytes from a path that exists both in development and in the built output (I check a short list of candidate directories and cache the bytes), and set doc.setLanguage('sv-SE') so screen readers pronounce the text correctly.

Bonus: a preview you cannot copy

Before paying, the user sees the first part of the document as HTML, and the rest is blurred. A CSS blur is not protection: the text is in the DOM, and "view source" defeats it. So the server scrambles the hidden part before it sends it. The scrambler keeps word lengths, punctuation, case and digits-as-digits, so the blurred block has the same shape as the real one, but the letters come from a small deterministic generator:

function scramble(s: string): string {
  let n = 7;
  return s.replace(/[A-Za-zÅÄÖåäöÉé0-9]/g, (c) => {
    n = (n * 31 + 11) % 26;
    const ch = String.fromCharCode(97 + n);
    return /[A-ZÅÄÖÉ]/.test(c) ? ch.toUpperCase() : /\d/.test(c) ? String(n % 10) : ch;
  });
}

It is not cryptography and does not need to be. The real text never leaves the server until the order is paid.

What generalises

None of this is specific to wills. Any form that produces a document with legal weight has the same four failure modes: a rule the user has to apply to their own situation, an identifier with hidden structure, branching state that leaks between branches, and a layout that can separate the proof from the thing it proves. The fixes are also the same: encode the rule as data and check what you can, normalise identifiers at the edge, rebuild the input from the schema on the server, and measure before you paginate.

I use this engine in Vittnet, a Swedish service for wills, cohabitation agreements and gift deeds.

Puppeteer PDF headers and footers with page numbers: 7 traps

Peter Hallander — Fri, 02 Oct 2026 07:23:41 +0000

Adding "Page 3 of 7" to a Puppeteer PDF looks like one option. You set displayHeaderFooter: true,
pass a footerTemplate, and render. Then the footer is either invisible, printed on top of your
text, or there is a date and a page title at the top that you never asked for.

None of that is a bug. The header and footer are a separate little document with its own rules, and
those rules are barely documented. Here is each one, tested against Chrome 148, and a newer CSS
approach that avoids most of them.

The working version first

import puppeteer from "puppeteer";

const browser = await puppeteer.launch({ headless: true, args: ["--no-sandbox"] });
const page = await browser.newPage();
await page.setContent("<h1>Report</h1><p>Body text.</p>", { waitUntil: "load" });

await page.pdf({
  path: "report.pdf",
  format: "A4",
  printBackground: true,
  displayHeaderFooter: true,
  margin: { top: "20mm", bottom: "20mm", left: "15mm", right: "15mm" },
  headerTemplate: "<span></span>",
  footerTemplate: `
    <div style="font-size:9px; color:#888; width:100%; padding:0 15mm; text-align:right;">
      Page <span class="pageNumber"></span> of <span class="totalPages"></span>
    </div>`,
});

await browser.close();

Every line of that template is there for a reason. Here they are.

1. The text is tiny unless you set a font size

Leave font-size out and the footer still renders. In my test it came out at 0.75pt, which is
a smudge you will mistake for a rendering artefact. The template does not inherit any sensible
default, so set the size explicitly on the outer element. 9px to 10px reads like a normal
document footer.

2. Your page CSS does not reach the template

My test page set body { font-family: serif; color: red }. The body text came out red and serif.
The footer came out black, in DejaVu Sans. The template is rendered as its own document, so nothing
from the page's stylesheet applies: not fonts, not colours, not classes.

You can either use inline styles, as above, or put a <style> block inside the template itself.
Both work:

footerTemplate: `
  <style>
    .f { font-size: 9px; color: #888; width: 100%; padding: 0 15mm; text-align: right; }
  </style>
  <div class="f"><span class="pageNumber"></span> / <span class="totalPages"></span></div>`,

Only fonts already available to the browser will work here. A web font loaded by the page is not
loaded by the template.

3. Without margins, the footer prints over your content

The header and footer do not reserve any space. They are drawn at a fixed position near the page
edge, and the page margin is the only thing that keeps your content out of the way. Puppeteer's
default margin is zero.

I rendered a page full of text with displayHeaderFooter: true and no margin. The body text ran
from 6pt to 833pt down an 842pt page, straight through both the header and the footer. With
top and bottom set to 20mm, the body sat between 62pt and 782pt and the footer had clear
space. If your footer is "missing", check the margin before anything else.

The same applies to horizontal position. The template spans the full page width, which is why the
example adds padding: 0 15mm to line the footer up with the left and right margins of the body.

4. Pass both templates, even if you only want one

Set only footerTemplate and Chrome fills the header with its own default: the date on the left
and the document <title> in the middle. My test produced 10/2/26, 8:59 AM and My Doc Title
across the top of every page.

To show nothing, pass an empty element:

headerTemplate: "<span></span>",

An empty string does not do the same thing. Use the element.

5. The five special classes

Chrome fills these in for you, inside either template:

Class	Value
`pageNumber`	current page number
`totalPages`	total number of pages
`title`	the document `<title>`
`date`	the print date, formatted for the browser locale
`url`	the page URL, which is `about:blank` after `setContent`

That last one catches people out. If you render with page.setContent() rather than
page.goto(), url prints about:blank. Put the real value in the template yourself.

6. Images need to be data URIs

A logo in the header loaded from a URL does not appear. I tested a PNG served from a local HTTP
server in the header, and the same PNG as a data: URI in the footer. Only the data URI made it into
the PDF.

import { readFileSync } from "node:fs";

const logo = readFileSync("logo.png").toString("base64");

const headerTemplate = `
  <div style="font-size:9px; width:100%; padding:0 15mm;">
    <img src="data:image/png;base64,${logo}" style="height:24px">
  </div>`;

Keep it small. The image is embedded into the template for every page.

7. Background colours need print-color-adjust

A coloured header bar with background: #0000ff printed as white. printBackground: true on
page.pdf() did not change that, because the option applies to the page and not to the template.
What fixed it was one property inside the template:

-webkit-print-color-adjust: exact;

With that on the element, the bar printed blue.

The newer way: @page margin boxes

Chrome 131 added support for CSS page margin boxes. You describe the header and footer in the
page's own stylesheet, and the browser places them in the margin. No displayHeaderFooter, no
template, and it uses your page fonts and colours, because it is your page CSS.

@page {
  size: A4;
  margin: 20mm 15mm;
  @top-right     { content: "Quarterly report"; font: 9pt sans-serif; color: #888; }
  @bottom-center { content: "Page " counter(page) " of " counter(pages); font: 9pt sans-serif; color: #888; }
}

/* No running header on the cover page. */
@page :first {
  @top-right { content: none; }
}

Render it with preferCSSPageSize: true so the @page size and margins win:

await page.pdf({ path: "report.pdf", preferCSSPageSize: true, printBackground: true });

My three-page test printed "Page 1 of 3" on the cover with no running header, then "Quarterly
report" plus "Page 2 of 3" and "Page 3 of 3" on the pages after it. That :first rule is something
the template approach cannot do at all, since the same template is stamped on every page.

The limit: margin boxes hold generated content, so they suit text, counters and simple strings.
For a logo or a layout with several elements, the template approach is still the tool.

You need	Use
Page numbers, a title, a confidentiality line	`@page` margin boxes
A different first page	`@page` margin boxes
A logo or a multi-part layout	`footerTemplate` / `headerTemplate`
Support for Chrome older than 131	`footerTemplate` / `headerTemplate`

Where this leaves you

Page numbers are usually the first fix. The second is where the pages break: code blocks, tables and
headings cut in half at the page boundary, which is a separate set of print CSS rules.

I maintain MintPDF, an HTML and Markdown to PDF API. It builds
the footer template for you from pageNumbers, headerText and footerText, with the font size and
margins from traps 1 and 3 already handled, and the @page rules above work in it unchanged.

Fortnox refresh tokens are single-use, and two parallel requests will log your users out

Peter Hallander — Sun, 27 Sep 2026 13:25:24 +0000

If you integrate with Fortnox, the Swedish accounting system, there is one OAuth detail that will bite you the first time real users click fast: a refresh token can be used exactly once. Fortnox rotates it on every refresh. Spend the same one twice and the second call gets invalid_grant.

That sounds harmless until you look at how a normal app behaves.

How it breaks

The access token lives for an hour. When it has expired, the next API call refreshes it first. The obvious code looks like this:

async function call(tenant, method, path, body) {
  if (Date.now() > tenant.expires_at) {
    const t = await refresh(tenant.refresh_token); // POST /oauth-v1/token
    Object.assign(tenant, t);
    await save(tenant);
  }
  return fetch(API + path, { method, headers: { Authorization: `Bearer ${tenant.access_token}` }, body });
}

Now a user opens the app after lunch. The app loads two screens at once, or the user presses "send all" on five receipts. Five calls start within a few milliseconds. All five read the same tenant row from the database, all five see an expired access token, and all five refresh with the same refresh token.

The first one wins and gets a new pair. The other four get invalid_grant. Depending on how you handle that error, the user is either told their Fortnox connection is broken and must be reconnected, or, worse, one of the losing calls saves an error state over the good tokens the winner just stored.

Nothing was actually wrong with the connection. The user did nothing wrong. It only happens under concurrency, so it never shows up when you test one request at a time.

The fix: one refresh per refresh token

The rule is simple: for any given refresh token, only one refresh may ever be in flight. Everybody else who finds the token expired waits for that refresh and uses its result.

In a single Node process, a Map of promises keyed by the refresh token is enough:

const refreshing = new Map();

function sharedRefresh(tenant, save) {
  const key = tenant.refresh_token;
  let p = refreshing.get(key);
  if (!p) {
    // Save inside the shared promise, so the new pair is in the database
    // before anyone waiting on it reads the connection again.
    p = refresh(key).then(async (t) => { await save({ ...tenant, ...t }); return t; });
    refreshing.set(key, p);
    p.then(
      // Keep a successful result for a minute (see below).
      () => setTimeout(() => { if (refreshing.get(key) === p) refreshing.delete(key); }, 60_000).unref?.(),
      // Drop a failure at once, so the next call can try again.
      () => { if (refreshing.get(key) === p) refreshing.delete(key); },
    );
  }
  return p;
}

async function call(tenant, save, method, path, opts) {
  if (Date.now() > tenant.expires_at) Object.assign(tenant, await sharedRefresh(tenant, save));
  // ... the actual request
}

Three details matter more than they look.

1. Save before you resolve. If the promise resolved first and saved afterwards, a waiter could reload the tenant from the database in between and find the old refresh token. It would then start a second refresh with a spent token, which is exactly the bug again.

2. Keep the successful result for a while. A request that read the tenant row a moment before the new tokens were saved still carries the old refresh token. If the map entry were deleted the moment the refresh finished, that late request would find nothing in the map and start its own refresh with the spent token. Keeping the resolved promise for a minute means late readers of the old token still get the new pair.

3. Forget failures immediately. If Fortnox is down for a second, you don't want every call for the next minute to get the same cached rejection.

Two more things that are easy to miss

Refresh with the credentials that issued the token. If you have more than one Fortnox app (we have two: one for receipts, one for a point-of-sale integration), a token must be refreshed with the client ID and secret of the app that issued it. Refresh a token from app B with app A's credentials and you get a rejection that looks exactly like a revoked connection. Store which app a tenant belongs to next to the tokens.

This is per process. The Map works because our API runs as one Node process. With several instances behind a load balancer, you need the same idea with a shared lock, for example a row lock in Postgres or a Redis SET NX with a short TTL, and the other instances re-reading the tokens once the lock is released.

How to test it

The bug only exists under concurrency, so test it that way. Mock the token endpoint to be slow (100 ms is plenty) and to reject any refresh token it has already seen, expire the access token, then fire several calls at once:

await Promise.all([1, 2, 3, 4, 5].map(() => call(tenant, save, 'GET', '/companyinformation')));
// expect: exactly one POST to the token endpoint, five successful calls

Without the shared refresh, four of the five calls fail. With it, the token endpoint is hit once and all five succeed.

I found this while building KvittoFlow, a receipt and mileage app that books straight into Fortnox. A "send all" button is exactly the kind of feature that triggers it.

Validate Poland's e-invoices offline against the official XSD, then make your validator fail on purpose

Peter Hallander — Tue, 22 Sep 2026 07:02:34 +0000

Since 2026, invoices between Polish businesses are XML documents. They go to the national e-invoicing system, KSeF, in a schema called FA(3). The last exemptions end on 1 January 2027. Once KSeF accepts an invoice, you cannot edit it or withdraw it. The only fix is a correcting invoice, filed after the fact.

So when I changed the XML builder to add three new blocks to every invoice (a third party, a payment section with bank accounts, and a footer), I wanted proof that the documents were still valid before any of them reached the real system.

There are two ways to get that proof.

The slow way: the government sandbox

KSeF has a demo environment. To use it you log in through the national ID service, generate a token, open a session and send your documents. In my setup the demo token has to be regenerated every day. When something is wrong, you get an error code and a sentence in Polish, and then you fix one thing and send again.

It is the final word on whether an invoice is accepted. It is also far too slow to run every time you touch the builder.

The fast way: the XSD

The Ministry of Finance publishes the FA(3) schema as an ordinary XSD file on crd.gov.pl. It is 180 KB, it declares 331 elements, and it imports a shared type library, which imports one more. Python's lxml compiles all three without any special setup:

import glob, os, sys, urllib.request
from lxml import etree

XSD_URL = "https://crd.gov.pl/wzor/2025/06/25/13775/schemat.xsd"
XSD = "tmp/fa3/schemat.xsd"
if not os.path.exists(XSD):
    urllib.request.urlretrieve(XSD_URL, XSD)

schema = etree.XMLSchema(etree.parse(XSD))
bad = 0
for f in sorted(glob.glob("tmp/fa3/*.xml")):
    ok = schema.validate(etree.parse(f))
    print("VALID  " if ok else "INVALID", os.path.basename(f))
    if not ok:
        bad += 1
        for e in list(schema.error_log)[:4]:
            print("     line", e.line, "-", e.message)
sys.exit(1 if bad else 0)

Four documents, including fetching the two imported files, take about 1.3 seconds. No token, no login, no network round trip per invoice.

Validate what your code produces, not what you typed

The obvious move is to write a sample XML by hand and validate it. That proves you can write a valid invoice. It says nothing about your builder.

So the samples come from the real serializer. A small script calls the same function the application uses and writes the output to disk:

const samples = {
  "a-baseline":    { ...base, invoiceNumber: "TEST/A/1" },
  "b-wdt-factor":  { ...base, currency: "EUR", vatRate: "0 WDT", payment: factor },
  "c-own-account": { ...base, payment: { bankAccounts: [ownAccount] } },
  "d-footer-only": { ...base, payment: { footer: "Kapitał zakładowy: 50 000 PLN" } },
};
for (const [name, data] of Object.entries(samples))
  fs.writeFileSync(`tmp/fa3/${name}.xml`, buildFa3Xml(data));

Each sample covers one new path: nothing configured, everything at once (a foreign buyer in euros with two factor accounts and a footer), own bank account only, footer only. The baseline matters as much as the others. A change that adds optional blocks must not change the document when they are empty.

Why the order is the whole problem

FA(3) is built from xsd:sequence, so the order of elements is part of the contract. The root looks like this:

Faktura
  Naglowek
  Podmiot1              seller
  Podmiot2              buyer
  Podmiot3        0-100 third parties (factor, recipient, ...)
  PodmiotUpowazniony 0-1
  Fa                    the invoice itself; Platnosc sits inside it, after the rows
  Stopka          0-1   footer
  Zalacznik       0-1

My three new blocks land in three different places: one between the buyer and the invoice body, one deep inside the body after the line items, one after the body. An XML builder that emits them in a slightly different place produces a document that looks perfectly reasonable and is invalid.

The schema also knows things that no summary in the documentation mentions. A factor may have at most 20 bank accounts. An account number is any string of 10 to 34 characters. The third party's role is a number from a closed list, where 1 means "factor". When I read these rules in the XSD instead of in a PDF guide, I found them faster and trusted them more.

All four passed. That was the moment to worry.

Every sample was valid on the first run.

A validator that has never said no has not been tested. Maybe the schema failed to load its imports and validated nothing. Maybe the glob matched an empty folder. Maybe I validated yesterday's files. A green result from any of those looks exactly like a real one.

So I broke a document on purpose. I took the most complex sample and moved the Podmiot3 block from before Fa to after it. Same content, wrong place:

INVALID z-control.xml
     line 80 - Element '{http://crd.gov.pl/wzor/2025/06/25/13775/}Podmiot3':
     This element is not expected. Expected is one of (
     {http://crd.gov.pl/wzor/2025/06/25/13775/}Stopka,
     {http://crd.gov.pl/wzor/2025/06/25/13775/}Zalacznik ).

Now the four green results mean something. The message is also more precise than a rejection code: it names the line, the element, and the elements that would be allowed there.

If you keep one habit from this post, keep that one. Every validator, linter or test gate you add needs one input that must fail, run at least once, on purpose.

What the schema cannot tell you

The XSD checks structure: order, types, lengths, allowed values. It does not check meaning.

The NIP, the Polish tax number, is a good example. Its type in the shared library is a regular expression:

[1-9]((\d[1-9])|([1-9]\d))\d{7}

1234567890 matches it. Its checksum is wrong, so it cannot be anyone's tax number, and the schema will not notice. The same goes for arithmetic: the schema cannot see whether the line totals add up to the invoice total.

KSeF checks meaning on submission, and rejects with its own errors, for example code 450, "Błąd weryfikacji semantyki dokumentu faktury" (semantic verification failed). So the offline check is the fast first gate, not the last one. One real submission through the sandbox is still the final check. The difference is that it becomes one submission to confirm, not twenty to debug.

The setup, in short

Download the XSD once and keep it next to your tests. It pulls two more files from crd.gov.pl on compile; cache them too if your CI has no network.
Generate samples with your real builder, one per code path, plus a baseline.
Keep one sample that must fail, and look at it fail.
Treat a pass as "structurally valid", never as "accepted".

I build FakturaFlow, which sends invoices to KSeF in bulk. If you need the field-by-field map of FA(3) in Polish, which is the language the people filing these invoices work in, I keep one here: FA(3) schema guide.

wp_kses deletes tags you forgot to allow, and tells you nothing

Peter Hallander — Fri, 11 Sep 2026 06:26:25 +0000

I shipped a WordPress plugin last week whose only job is to reproduce a specific, legally prescribed document on a product page. Exact colours, exact layout, nothing editable.

It went live rendering as unstyled text.

The CSS file was correct. The markup was correct. php -l passed on every file, the official Plugin Check tool reported no errors, and reading the diff told me nothing. The bug was wp_kses, and the reason it took me an hour is that wp_kses does not fail in a way you can see.

What actually happens

wp_kses( $html, $allowed ) filters HTML against an allow-list. Everyone knows that. What is easy to miss is what it does with a tag that is not on the list.

It does not remove the element. It removes the tag and keeps the children.

wp_kses(
    '<section class="card"><p>Still here</p></section>',
    [ 'p' => [ 'class' => true ] ]
);

// => '<p>Still here</p>'

The <section> is gone. The paragraph survived. No notice, no warning, no return value to check. Run that in wp shell and watch it happen.

That behaviour is correct and deliberate: kses is a sanitiser, and throwing away a user's text because their comment had an unexpected wrapper would be much worse. But when you point kses at your own markup, the failure mode inverts. You do not lose content. You lose structure, and structure is where all your CSS hooks live.

How it looked in practice

My notice is built like this:

<section class="sbgn" role="note">
    <header class="sbgn__head">
        <span class="sbgn__emblem"></span>
        <h2 class="sbgn__title">LEGAL GUARANTEE</h2>
    </header>
    <div class="sbgn__body">
        ...
    </div>
</section>

and echoed like this:

echo wp_kses( self::markup(), SBGN_Kses::notice() );

My allow-list had div, p, span, ul, li, h1–h3, strong, b, aside, figure, figcaption, br and a.

No section. No header. No ol.

So on every product page the browser received this:

<span class="sbgn__emblem"></span>
<h2 class="sbgn__title">LEGAL GUARANTEE</h2>
<div class="sbgn__body">
    ...
</div>

The root .sbgn element carried the border, the background and the CSS custom properties everything else referenced. .sbgn__head carried the coloured header bar. Both were deleted, so:

every var(--brand) resolved to nothing, because the custom properties were declared on .sbgn
the header bar vanished entirely
<ol> was stripped too, so numbered steps quietly became bullets

The page still looked populated. All the text was there, in roughly the right order. It just had none of the design, which for this particular plugin is the entire product.

Why nothing caught it

This is the part worth internalising.

php -l passes. The PHP is valid. It always was.
Plugin Check passes. It reads the source, and the source is correct.
The CSS is served and parses. I fetched the stylesheet URL directly: HTTP 200, right content, braces balanced. I wasted time on that.
The class names match. Grepping the rendered page for class="sbgn returned sbgn__body, sbgn__title, sbgn-qr and friends. They were all present, which made it look like the CSS simply was not applying.

The tell, when I finally saw it, was an absence: class="sbgn" and class="sbgn__head" were the only two selectors in my stylesheet with no counterpart in the DOM. A missing string is much harder to notice than a wrong one.

# the check that actually found it
curl -s "$URL" | grep -o 'class="sbgn[^"]*"' | sort -u

Everything my stylesheet defined, minus the two that mattered.

The fix, and the guard

The fix is obvious once you know. List every tag you emit:

$html = array(
    'div'     => $attr,
    'section' => $attr,   // added
    'header'  => $attr,   // added
    'footer'  => $attr,   // added
    'p'       => $attr,
    'ul'      => $attr,
    'ol'      => $attr,   // added
    'li'      => $attr,
    // ...
);

Attributes are silently dropped the same way, which is its own small trap. My notice carried role="note"; role was not in the attribute list, so the element survived while its announcement to a screen reader did not. Nothing in the visual output would ever have told me.

The guard I added is a comment pointing at a one-line command, because the allow-list and the markup live in different files and will drift:

grep -ohE "<[a-z][a-z0-9]*" includes/class-*-notice.php includes/class-*-label.php \
  | tr -d '<' | sort -u

Run that, compare against the allow-list, done. If you would rather have it fail loudly in development, wp_kses gives you no hook for that, but you can diff the two strings yourself:

$out = wp_kses( $markup, $allowed );
if ( defined( 'WP_DEBUG' ) && WP_DEBUG && $out !== $markup ) {
    trigger_error( 'kses altered plugin markup', E_USER_WARNING );
}

Crude, but it turns a silent structural edit into something you can see. For your own trusted markup, where the output should be byte-identical, any difference at all is a bug.

The general lesson

I had two correct artifacts, a correct template and a correct stylesheet, and a broken page. The defect lived in the transformation between them, and every tool I owned inspected the artifacts rather than the result.

Escaping late is the right rule and I am not arguing with it. But an allow-list is a second source of truth about your own markup, and a second source of truth drifts. Whatever you are building, the check that would have caught this in five seconds is looking at what the browser actually received.

I only found it because I screenshotted the rendered output on a real install before writing the listing. That is now a release step rather than a nice-to-have.

The plugin, for the curious, shows the EU's harmonised legal guarantee notice, which becomes mandatory for anyone selling goods to EU consumers on 27 September 2026. It renders in all 24 official EU languages, and as real text rather than the flat artwork everything else in this category ships, which is the only reason a screen reader can read it at all. Free, WooCommerce optional, and I maintain it: EU Legal Guarantee Notice and GARAN Durability Label for WooCommerce.

toISOString() put 328 invoices in the wrong tax month

Peter Hallander — Sat, 05 Sep 2026 06:28:12 +0000

A customer emailed me on 1 September. Her invoices were dated 31 August, and they should have said 1 September.

She was right. 328 of them.

One line

The invoices arrive from a billing platform by webhook. Each one carries a unix timestamp, and we turn it into a date:

const issueDate = new Date(inv.date * 1000).toISOString().slice(0, 10);

That looks like it produces a date. It produces a UTC date.

Poland runs UTC+2 in summer. The billing platform runs its subscription cycle at 00:00 Europe/Warsaw. So an invoice issued at midnight on 1 September is 2026-08-31T22:00:00Z, and toISOString() renders it as 2026-08-31.

Every invoice in that run was wrong.

Why it hid for a month

The bug only fires between midnight and 02:00 local time. Every invoice issued during the working day converts correctly, because the UTC date and the Warsaw date are the same date.

The integration had been live for a month. Invoices had been arriving one or two at a time, whenever someone signed up, and every one of them was right. Then the monthly billing run went out at exactly the wrong minute, and 328 invoices landed together in the wrong month.

The failure mode was invisible until it hit at scale, at the only time of day that triggers it.

Wrong day vs wrong month

An off-by-one day on a date field is usually a cosmetic bug. This one was not, for a boring reason: 31 August and 1 September are in different VAT periods.

These invoices go to Poland's national e-invoicing system. Once an invoice is filed there it cannot be edited or withdrawn. The only remedy is issuing a correcting invoice afterwards. So the difference between "wrong day" and "wrong month" is the difference between a typo and a tax filing in the wrong period.

The 328 had not been filed yet. That was luck, not design.

Finding the wrong rows without guessing

I could have selected everything dated 31 August and moved it forward one day. That would also have moved genuinely-August invoices, because 31 August is a real date on which real invoices exist.

The tempting shortcut is to use the arrival time: if a row arrived on 1 September and is dated 31 August, fix it. That is wrong too. An invoice legitimately issued at 23:58 on 31 August, whose webhook landed at 00:01, is correctly dated and would be corrupted by the fix.

What saved me was a second, independent signal. The billing platform's own invoice numbers carry the month:

PSA-09-2026-17
     ^^ September

So the rule became: correct a row only when the invoice number says September and the row arrived on 1 September Warsaw time and the stored date is exactly one day earlier. Three facts agreeing, two of them from the source system rather than from my own inference.

That found 328 rows, zero ambiguous ones, and left the 23:58 case alone. After the fix, all 490 invoices agreed with the platform's own numbering, where 328 had not.

If you are writing a data repair script, find the second signal before you write the UPDATE. The one-signal version would have quietly broken correct rows while looking like it worked.

The fix

Intl.DateTimeFormat with an explicit time zone. The sv-SE locale is the convenient one here because its date format is already YYYY-MM-DD:

const WARSAW_YMD = new Intl.DateTimeFormat("sv-SE", {
  timeZone: "Europe/Warsaw",
  year: "numeric",
  month: "2-digit",
  day: "2-digit",
});

export function polishDate(d) {
  return WARSAW_YMD.format(d);
}

Build the formatter once outside the function. Intl.DateTimeFormat construction is not free, and this runs per invoice.

Do not be tempted by the arithmetic version:

// Wrong six months a year
const local = new Date(ts * 1000 + 2 * 3600 * 1000).toISOString().slice(0, 10);

Poland is UTC+2 in summer and UTC+1 in winter. A hardcoded offset is correct until the last Sunday in October, then silently wrong until March. Intl reads the timezone database, so DST is handled for you.

The test that catches it

Two cases, and the second is the one that matters:

// 2026-09-01 00:00 Europe/Warsaw (22:00 UTC on 31 August)
expect(polishDate(new Date(1788213600 * 1000))).toBe("2026-09-01");

// 2026-01-01 00:00 Europe/Warsaw (23:00 UTC on 31 December), UTC+1
expect(polishDate(new Date(1767222000 * 1000))).toBe("2026-01-01");

The January case fails against a hardcoded +2. Without it, the fix looks correct for six months.

I also reverted the fix and re-ran the tests, to confirm they actually caught the original bug. A test you have never seen fail is a test you have not written yet. Mine passed on the first run before I checked, which is exactly when I should have been suspicious.

The general shape

toISOString() is a timestamp serializer. It is not a date formatter. It answers "what is this instant in UTC", and if you slice the first ten characters off it, you have asserted that UTC is the calendar your users live in.

That is fine for a log line. It is not fine when the date has meaning to somebody: a tax period, an invoice date, a delivery date, a contract term, a birthday.

Three questions worth asking about any date field in your system:

Does this date belong to a place? An issue date on a Polish invoice is a Polish calendar date, no matter where the server or the billing platform is. If the answer is yes, the timezone is part of the data, not a display concern.
What happens near midnight? Every timezone bug lives between 00:00 and the UTC offset. If your tests use midday timestamps, they will all pass.
What happens in the other season? Half the year is DST. Test in January and in July.

The customer found this one before we did. She had been sending invoices through the system for six weeks, noticed the dates were a day out, and told us the same morning. That is a good customer, and it is not a substitute for a test at midnight.

I hit this building FakturaFlow, which files invoices to Poland's e-invoicing system in bulk. That link goes to a longer write-up of what else breaks at a thousand invoices a month, in Polish, since that is who has to deal with it.

If you convert a timestamp to a date anywhere in your codebase, it is worth ten minutes with grep today:

grep -rn "toISOString().slice(0, 10)" src/

That found eight more in mine. Seven turned out to be fine: a download filename, today's date in a prompt, a test fixture. Being a day out in a filename costs nothing.

The one I am still looking at is a central bank exchange-rate lookup, because the rate published "for 1 September" is a Polish calendar date too, and asking for the wrong day returns the wrong number rather than an error.

That is the test. Not "is this UTC", but who cares what day this is, and what does it cost them if it is wrong. Most of the time, nobody. Occasionally, a tax authority.

pdf-lib throws on Ł. The obvious fix silently deletes your users' data

Peter Hallander — Sun, 30 Aug 2026 08:26:50 +0000

I generate invoices in a Node serverless function with pdf-lib. It is a good library, and to its credit it did the right thing: it threw.

Error: WinAnsi cannot encode "Ł" (0x0141)

The client was called Łódź Sp. z o.o.

I did what almost everyone does when a document generator throws in production: I stripped the character that was upsetting it. The exception stopped. The tests went green. And the invoice then said ód Sp. z o.o., on a document my user was about to send to their own customer, with nothing in the logs to suggest anything had happened.

pdf-lib is not the thing being quiet here. My fix was. That distinction took me longer to see than it should have, and it is the whole point of this post.

The standard 14 fonts are Latin-1 only

PDF has fourteen fonts every reader is guaranteed to have, so you can use them without embedding anything. pdf-lib exposes them as StandardFonts:

import { PDFDocument, StandardFonts } from 'pdf-lib'

const doc = await PDFDocument.create()
const font = await doc.embedFont(StandardFonts.Helvetica)

That is the default path in every tutorial, and it is fine until it is not. Those fonts are encoded as WinAnsi (roughly Windows-1252). Their glyph set covers Western European Latin and nothing else.

Ł and ź are not in it. I checked the boundary rather than guessing, and it is narrower than people assume:

Character	Standard font
`€` `£` `’` `–` `—`	draws fine
`ř` (Czech)	throws
`ı` (Turkish)	throws
`Москва` (Cyrillic)	throws
`株式会社` (CJK)	throws

So the euro sign and curly quotes are safe, which is the part most people worry about. Names are not, which is the part that matters.

The part that makes it dangerous is the fix, not the error

The exception above is correct and helpful. It is also loud, and loud things get silenced. So people do the obvious thing to stop the crash:

// don't do this
const safe = (s) => s.replace(/[^\x20-\xFF]/g, '')
page.drawText(safe(customerName), { x, y, size, font })

I did exactly this. It stops the exception, the code goes green, and every test passes. What it actually does is delete parts of your users' data from a document they are about to send to their own customer.

There is no error to notice. The PDF is valid. Nothing in your logs suggests anything happened. The only way to find out is to render a page with non-Latin-1 text in it and look at it with your eyes.

The fix: embed a real font

Embed a TrueType or OpenType face and the problem disappears, because you are no longer restricted to a 1990s encoding table.

import fontkit from '@pdf-lib/fontkit'
import { readFile } from 'fs/promises'
import { PDFDocument } from 'pdf-lib'

const doc = await PDFDocument.create()
doc.registerFontkit(fontkit)   // required, and easy to forget

const bytes = await readFile('assets/fonts/Archivo-Regular.ttf')
const font = await doc.embedFont(bytes, { subset: true })

page.drawText('Łódź Sp. z o.o.', { x: 40, y: 700, size: 12, font })

Three things worth knowing:

registerFontkit is mandatory. Without it embedFont on a byte array throws a message about fontkit that does not obviously connect to your problem.

subset: true matters more than you think. A full Archivo weight is about 180 KB. Embedding three weights unsubsetted adds half a megabyte to every single document. With subsetting, my four-page invoice with three weights comes out at 35 KB, because only the glyphs actually used get embedded.

Cache the file reads. In a serverless function, readFile on every invocation is wasted latency. Read once into a module-level variable and reuse it across warm invocations:

let cache = null

async function loadFonts() {
  if (cache) return cache
  const dir = path.join(process.cwd(), 'assets', 'fonts')
  const [regular, semi, black] = await Promise.all([
    readFile(path.join(dir, 'Archivo-Regular.ttf')),
    readFile(path.join(dir, 'Archivo-SemiBold.ttf')),
    readFile(path.join(dir, 'Archivo-Black.ttf')),
  ])
  cache = { regular, semi, black }
  return cache
}

Also check the licence before you vendor a font. Archivo is SIL OFL, which permits embedding; plenty of commercial faces do not.

An embedded font still is not every glyph

Embedding solves the encoding problem, not the coverage problem. Archivo has no CJK. If a user types a Japanese company name, widthOfTextAtSize throws on that character and you are back where you started, just further along.

So keep a fallback, but make it visible rather than silent:

function drawable(font, s) {
  let out = ''
  for (const ch of s) {
    try {
      font.widthOfTextAtSize(ch, 10)
      out += ch
    } catch {
      out += ' '          // a gap you can see, not a deletion you cannot
    }
  }
  return out
}

A space is not a great outcome. It is a much better outcome than a name silently closing up, because a human proofreading the document has a chance of spotting it.

Two more things only rendering will tell you

While I had a rasteriser pointed at the output, two layout bugs turned up that no amount of reading the code would have found.

A six-figure total ran backwards over its own label. The totals block right-aligned the figure at 20pt Black in a column sized for four digits. At $2,160.00 it was fine. At 86,832.81 PLN it overlapped the words TOTAL DUE sitting to its left. Text does not wrap or complain when it is drawn at an absolute coordinate; it just draws.

A long company name ran off the right edge of the page. Same cause. drawText has no concept of a container, so anything longer than you imagined simply continues past the paper.

Both are obvious in a rendered image and invisible in a diff. If you generate PDFs, put a rasteriser in your test loop:

# PyMuPDF, no system dependencies
python3 -c "
import pymupdf
pymupdf.open('out.pdf')[0].get_pixmap(dpi=120).save('out.png')"

Then actually open the PNG. It takes ten seconds and it is the only test that catches this class of bug.

The short version

The standard 14 fonts are WinAnsi. They cannot draw most of the world's names.
Stripping the characters to stop the exception silently corrupts user data in a document they will send to a third party.
Embed a subsetted TrueType face with @pdf-lib/fontkit, cache the bytes, and check the licence.
Keep a fallback that leaves a visible gap rather than a clean deletion.
Render your output to an image in tests and look at it. Absolute-positioned text overlaps and overflows without any error.

I found all of this building HourToBill, where the invoice is the entire product, so a mangled client name is not a cosmetic bug. If you generate documents from anything a user typed, it is worth spending twenty minutes checking what yours does with Łódź.

We ran the same ChatGPT prompt three times in a row. Here is what changed.

Peter Hallander — Tue, 18 Aug 2026 20:38:23 +0000

We wanted to know how much a single ChatGPT answer can be trusted as a measurement. So we ran the same prompt through ChatGPT more than once, with nothing changed between runs, and recorded what came back each time.

The setup

We used DataForSEO's ChatGPT LLM Scraper on 2026-08-16. For each prompt we ran the exact same query three times, minutes apart, same settings every time. Nothing about the prompt or the account changed between runs. Any difference in the answers is the model, not us.

Email marketing apps for Shopify

The prompt was "best email marketing app for Shopify," run three times.

Across the three runs, 16 distinct domains showed up somewhere in the answers. Only 4 of those 16 appeared in all three runs.

Brand	Runs appeared in	Position
Klaviyo	3 of 3	1st, every time
Omnisend	3 of 3	2nd, every time
Mailchimp	2 of 3	4th twice, absent once

Klaviyo and Omnisend held their spots exactly. Mailchimp did not. It sat at position 4 in two runs and was missing from the answer entirely in the third. Nothing about the prompt changed between that run and the other two.

If you had only run this prompt once, and it happened to be the run without Mailchimp, you would have concluded Mailchimp does not appear for this query. Run it again and that conclusion is wrong.

A wider check: HTML-to-PDF APIs

To see if this held up outside one prompt, we ran 4 prompts about the HTML-to-PDF API category, 3 runs each, for 12 observations total.

66 distinct domains showed up across those 12 observations. Only 5 domains appeared in every run of the specific prompt they showed up on. 4 of 8 brands we were tracking appeared in some runs of a prompt and were missing from others.

The pattern from the email marketing prompt was not a one-off. The names at the top of an answer tend to hold their position. Everything below that is less settled than a single run makes it look.

What it cost to check

Running all 12 observations for the HTML-to-PDF category cost $0.004 per call, $0.048 in total. Checking whether an answer is stable is not expensive. Not checking is the part that costs something, because it produces a wrong number with the same confidence as a right one.

The conclusion

A tool that runs a prompt once and reports "brand visibility: 67%" is reporting a single sample as if it were a measurement. Based on what we saw here, that number would land differently depending on which of the three runs happened to be sampled.

The top of a ranking is stable. Klaviyo held position 1 in every run. Omnisend held position 2 in every run. That part, one run would have told you correctly.

The marginal brand is not stable. Mailchimp came and went. In the wider check, more than half the brands we tracked were inconsistent from run to run. That instability sits exactly where most brands actually are, not at the top, and it is exactly what a business paying for this kind of tracking wants to know: are we in or out, and how often.

A single run cannot answer that question. It can only tell you what happened once.

Measured on 2026-08-16 using DataForSEO's ChatGPT LLM Scraper. Same prompts, same settings, three runs each, minutes apart.

I measured 7,032 WordPress plugins to find out how anyone gets their first install

Peter Hallander — Sun, 16 Aug 2026 18:24:12 +0000

I shipped a plugin to the WordPress.org directory. It got zero installs.

That is not a complaint, it is the normal outcome. Roughly 19% of all plugins in the directory never pass zero installs, which is more than 10,500 of them. But I wanted to know why, and whether the answer was "your plugin is bad" or something structural.

So instead of reading marketing advice, I queried the directory API and counted.

Everything below is reproducible. The API is free, needs no key, and every query I used is in the article.

The short version

Search is a two phase system, and phase one is a hard filter, not a ranking. If a single word of the user's query is missing from your listing, you are excluded from that search entirely.
Phase two is where you lose, and it is ranked partly on active installs. That is the cold start trap.
Of the plugins that broke out recently, 88% had distribution before they started.
The two behaviours that actually correlate with breaking out from nothing are release cadence and resolving support threads, which are two of the five phase-two ranking inputs and the only two a plugin with no installs can move.
WordPress.org gives plugin authors no analytics whatsoever. No listing views, no impressions, no click-through. Anyone who tells you confidently what makes people click install is guessing.

How search actually works

The best-documented account traces to WP Tavern's 2017 coverage of the directory relaunch, quoting Greg Brown, the Automattic data engineer who built it. It runs on Elasticsearch, and it has two phases.

Phase one builds the candidate pool. It matches against title, excerpt, description, tags, slug, author name and contributor names. Critically: all search keywords must appear somewhere, or the plugin is excluded from the result set. Not ranked low. Excluded.

Phase two sorts that pool by last update date, compatibility with the current core version, active installs, percent of support tickets resolved, and average rating.

That split matters more than anything else in this article, because phase one is entirely yours and phase two mostly is not.

Testing the hard filter on my own plugin

I took my live plugin and measured its actual position for terms it should rank for, then checked which query words appear in its listing.

rank	term	missing words
14	disposable email blocker	none
46	block disposable email	none
50	disposable email	none
146	temporary email	none
>300	email validation	none
>300	spam registration	"spam"

Two failures, two completely different causes.

"spam registration" fails because the word spam appears nowhere in the listing. That is phase one. It is a hard exclusion, and it is free to fix.

"email validation" fails even though every word is present. That is phase two: the term is owned by WP Mail SMTP and CleanTalk on install count, and no amount of rewriting changes it.

Being able to tell those two apart is the single most useful thing I learned. One is a typo-level fix. The other is not a copy problem at all.

Here is the query, if you want to check your own. Note the -g flag, without it your shell will try to glob the square brackets:

curl -g "https://api.wordpress.org/plugins/info/1.2/?action=query_plugins&request[search]=disposable+email&request[per_page]=100&request[page]=1"

Who actually breaks out

This is the part I expected to be discouraging, and it was worse than I expected.

I swept the entire directory for plugins with 1,000 or more active installs. That is 7,032 plugins. Then I filtered to those added in the last 18 months. That leaves 167. Those are the breakouts.

Then I looked at who published them.

cause	share
Author already ran another plugin with real installs	67%
Known commercial brand with an audience off WordPress	17%
Cross-promoted from the author's own theme or membership site	3%
Legacy plugin name revived by a directory insider	1%
Company formed specifically to ride a trend	1%
Unclear, possible genuine cold start	10%

88% had some form of pre-existing distribution.

The scale of the first group is worth spelling out. One vendor launched eight breakouts off the back of a two million install plugin. Another launched three off ten million. That is not a growth tactic you can copy, it is an asset you either have or do not.

The second group is the one that fooled me at first. It looks like cold starts, because those authors have no other WordPress plugins. But it is Visa. It is Sendcloud. It is a hosting company. These are businesses with a customer base off WordPress, shipping an integration to people who already pay them. Same advantage, different platform.

When I dug into the remainder, two out of sixty-nine survived as genuine unknown-author cold starts.

What those two did

They took opposite routes, and the difference is instructive.

One is a floating WhatsApp button. Its author has exactly one plugin in the entire directory and no brand at all. It serves an extremely common, low-friction search intent that the directory's own search surfaces well.

The other is an llms.txt generator. It broke out because llms.txt did not exist before 2025. There were no incumbents with an install-count advantage, so phase two was level and phase one decided.

That second one is the only mechanism I found that beats the cold start loop rather than enduring it. When the need is new, nobody has installs yet.

The grind that does work

I filtered the breakouts down to solo developers shipping security and blocking utilities, which is my own category, and looked at their behaviour rather than their marketing.

plugin	installs	age	releases	support resolved
Advanced IP Blocker	2,000	14 mo	124	12 of 12
Vigilant	2,000	6 mo	64	15 of 15
BotBlocker	3,000	9 mo	25	4 of 4
Geo Blocker	1,000	15 mo	2	0 of 1

Advanced IP Blocker shipped 124 releases in 14 months. That is roughly nine a month. Vigilant shipped 64 in six. Both resolved every single support thread they received, both have the most ratings in the group, and both had shipped within days of when I measured.

Geo Blocker is the control case. Two releases, never touched again, one support thread left unanswered. Still at the bottom.

This is not just correlation. Last update date and percent of support tickets resolved are two of the five documented phase-two ranking inputs. The third input, active installs, is the one you cannot move. So shipping often and answering everything are not merely habits of successful plugins, they are literally the only two ranking levers available to a plugin with no users.

One more thing I noticed and cannot prove causal: those breakout readmes run 39,000 to 42,000 characters. Mine were 8,000.

Things that are simply not true

"0 active installs" does not mean zero. A WordPress core issue confirms the label really means "fewer than 10". If you are sitting at zero, you may well have users.

You cannot measure your funnel. WordPress.org exposes no listing views, no search impressions, no click-through rate, nothing comparable to App Store Connect or the Play Console. So when someone tells you that a better banner or a shorter description improves conversion, ask where the number came from. The platform does not hand anybody that data.

Do not pay for reviews or installs. It is Guideline 9. The penalty is removal of all your reviews, then removal of the plugin on a repeat. There is a real enforcement case.

An API trap that cost me an hour

request[browse]=popular silently ignores request[tag].

I confirmed it across four different tags, all returning identical results. There is no error and no warning. If you are trying to sweep a category by popularity, you cannot do it in one call. Sweep by tag without browse, or sweep browse=popular globally and filter client-side.

Also useful: query_plugins returns the added date in the bulk response, so you can find recently-published plugins without a detail call per plugin.

What I actually changed

I stopped treating this as a marketing problem.

I audited every listing for phase-one coverage, checking that every word of each target search literally appears. That found a real gap: one of my plugins says "blocklist" everywhere, while merchants type "blacklist". Free to fix, and it was excluding me from those searches entirely.

I built a rank tracker, because installs are the last thing to move and search position is the first. Without it I was editing copy blind. If rank improves after a wording change, that is phase one responding. If it refuses to move, that is phase two, and no rewrite will fix it.

And I stopped picking categories with entrenched incumbents. The llms.txt case is the whole lesson: when a requirement is brand new, everybody starts at zero installs together.

The honest conclusion

If you have an audience, use it, because that is what 88% of successful launches did.

If you do not, the directory is not going to discover you on its own. The two levers you own are shipping often and answering every support thread. Both are slow. The most rigorously documented zero-audience case I could find took about a year to reach a thousand installs, at roughly a hundred a month, and the developer says plainly it was never exponential.

The alternative is to be early to something new enough that nobody has an install-count advantage yet. That is the only shortcut in the data.

This came out of building four plugins for WordPress.org, one of which is live so far and sitting at the install count this article is about, which is rather the point. The one that prompted the research is Email Guard, a local disposable-email blocker for WooCommerce that bundles its domain list and makes no outbound requests. Every number above is reproducible from the public plugin API.

If you render user HTML, you have an SSRF problem. Here is the code that fixes it.

Peter Hallander — Sat, 15 Aug 2026 11:57:08 +0000

Every HTML-to-PDF service has the same shape. Someone hands you markup, you open it in headless Chromium, you print to PDF. If you want Mermaid diagrams or KaTeX math to work, that markup has to be allowed to run JavaScript.

Which means you have built a machine that fetches arbitrary URLs from inside your network, on request, for strangers.

Most write-ups stop at "block private IPs". That is the easy half. The hard half is that the URL your user submits is not the only URL your service requests, and an IP address has more spellings than you think.

The request you validated is not the request you make

Say you accept a URL and check it before rendering:

const url = new URL(input);
if (isPrivateIp(await resolve(url.hostname))) throw new Error("nope");
await page.goto(url);

That check covers exactly one request. The page you just loaded can issue as many more as it likes, and none of them went through your validator:

<img src="http://169.254.169.254/latest/meta-data/iam/security-credentials/">
<script>fetch('http://localhost:6379').then(r => r.text()).then(t => 
  document.title = t)</script>

The image fetch reaches your cloud metadata endpoint. The fetch hits Redis on the loopback address. A redirect from a public URL to an internal one bypasses the check too, because you validated the URL before the redirect existed.

So you need two layers, and the second one is the one that matters:

await page.setRequestInterception(true);
page.on("request", async (req) => {
  if (await isAllowedRequestUrl(req.url())) await req.continue();
  else await req.abort();
});

Every subresource, every redirect hop, every XHR. Chromium asks permission before each one.

DNS rebinding, and the asymmetry that beats it

Now the classic attack. Your validator resolves evil.example and gets a public address, so it passes. Chromium then resolves it again to make the actual request, and this time the record answers 127.0.0.1. Two lookups, two answers, and the gap between them is the vulnerability.

You cannot fully close that gap without pinning the resolved address at the socket layer. You can narrow it a lot, and there is one design decision that does most of the work:

Cache refusals. Never cache approvals.

const blockedCache = new Map();
const BLOCKED_TTL_MS = 60_000;

This looks like a performance detail. It is the security property. If you cache "this host is public" for even sixty seconds, an attacker answers public once, gets that verdict cached, and then points the record wherever they like for the rest of the window. Your cache is now defeating your own validator.

Caching the refusal is safe, because the cached answer is the "no". A host that becomes benign later is simply blocked slightly longer than necessary, and nobody is harmed by that.

The same instinct applies everywhere else in this code. When you cannot tell, refuse:

try {
  const addrs = await lookup(host, { all: true });
  isPrivate = addrs.length === 0 || addrs.some(a => isPrivateIp(a.address));
} catch {
  isPrivate = true;   // a name that will not resolve is refused, not passed through
}

A URL that will not even parse gets the same treatment. It returns false, not true. The schemes that legitimately arrive here (data:, about:, blob:) all parse fine, so a parse failure is genuinely suspicious.

And allowlist the schemes rather than blocklisting them. ftp:, ws: and chrome-extension: have no business in a document you were asked to render, and you will never think of all of them in advance.

Now the part that actually bites: parsing

Here is where I lost the most time, and where I suspect most implementations are quietly wrong. Every one of these was a real bug in my own code, found by writing the test suite rather than by reading it.

parseInt is not a validator. It takes a valid prefix and ignores the rest. parseInt("1g", 16) is 1, not an error. So ::1g parses as ::1, or worse, as something that passes a check it should have failed. Validate the shape first, parse second:

if (!/^[0-9a-f]{1,4}$/.test(hextet)) return null;

Anchor your dotted quad. IPv6 allows a trailing IPv4 form, ::ffff:127.0.0.1. If you match that suffix without anchoring both ends, then ::ffff:1.2.3.4.5, ::ffff:1.2.3 and ::ffff:1.2.3.4x all get accepted, because your regex happily consumes the part it likes and ignores the rest.

Reject zone indices, do not strip them. Node considers fe80::1%eth0 a valid IPv6 address. It is tempting to strip the %eth0 and carry on. Do not. A scoped address is not something a web page should ever be fetching, and stripping a suffix is how malformed input becomes valid input.

Judge mapped addresses by what they embed. ::ffff:127.0.0.1 and ::ffff:7f00:1 are the same address wearing different clothes. Compare the bytes, not the string, or you will block one spelling and wave the other through.

NAT64 is not where you think it is. The translation prefix is 64:ff9b::/96. The first hextet is 0x0064, so the significant bytes sit at offsets 1 to 3, not 0 to 2. Get this off by one and you block nothing.

Teredo needs all four bytes. The prefix is 2001:0000::/32. I originally checked three bytes, which was worse than useless: it blocked 2001:0001::/32 and everything else under 2001:00xx, which are ordinary public addresses. An over-broad rule is still a bug, it just fails in a direction nobody reports.

Strip the brackets. WHATWG URL keeps them: new URL("http://[::1]/").hostname is "[::1]", and Node's isIP() rejects the bracketed form. Miss this and every IPv6 literal falls through to a DNS lookup that fails, gets refused, and looks like it works. It is correct by accident for private addresses, wrong for public ones, and it will break the day you change your fallback.

What this does not do

It narrows the rebinding window. It does not eliminate it. Fully closing it means resolving the name once and pinning that address at the socket layer so the request cannot be redirected to a different one. That is not implemented here, and I would rather say so than let you assume otherwise.

It also assumes your renderer is not otherwise sandboxed. Network policy at the container level, a blocked metadata endpoint, and an egress allowlist are all better defences than anything above, because they do not depend on my parser being correct. Treat this as the layer that catches what those miss, not as the only thing standing between a stranger and your instance metadata.

The part worth stealing

If you take one thing: write the test suite before you trust the parser. Mine has thirty-one cases for the URL layer and forty-five assertions for IPv6 alone, and it found four real bugs in code I had already read twice and believed was correct. Address parsing is exactly the kind of problem where reading proves nothing, because every bug looks reasonable on the page.

The code above runs in MintPDF, a Markdown and HTML to PDF API. It is MIT licensed, so the full implementation is on GitHub if you want the rest of it.

Integrating with Poland's KSeF: five things that aren't in the docs

Peter Hallander — Sat, 15 Aug 2026 08:39:33 +0000

Poland switched to mandatory structured e-invoicing this year. Since 1 February 2026 for the largest companies, since 1 April 2026 for all active VAT payers, and from 1 January 2027 for everyone else, including the smallest and VAT-exempt.

The system is called KSeF (Krajowy System e-Faktur). You send an invoice as XML in a schema called FA(3), it validates it, assigns it a number, and returns a signed receipt. Conceptually simple. There is an OpenAPI spec and official SDKs in C# and Java.

I've spent this year building an integration against it in TypeScript on Deno, and it now files invoices in production. Below are five things that cost me real time and are not in the documentation, or are in it in a way you only recognise afterwards.

1. The receipt is issued per invoice, but fetched through the session

This is the one I'd most want to tell my past self, and it has two halves that are easy to get backwards.

You can send invoices in a batch session: one ZIP of XML files, hundreds at a time. The session returns a reference number, and it's tempting to store that and call the invoices delivered.

It isn't. The document that legally proves an invoice reached the system is the UPO (Urzędowe Poświadczenie Odbioru), and it exists per invoice. A session reference proves a session happened. If you are ever asked to produce evidence for one specific invoice, that isn't it.

But — and this is the half I got wrong first — the UPO is retrieved through the session that submitted it:

GET /api/v2/sessions/{originalSessionRef}/invoices/ksef/{ksefNumber}/upo

So the session reference isn't disposable, it's a required key. An earlier version of my code opened a fresh session to fetch UPOs and could never resolve them, because KSeF binds UPO metadata to the original session. If you lose that reference, retrieving the receipt afterwards gets considerably harder.

Practically: store the session reference and iterate per invoice. A batch of 200 means one upload and then 200 fetches, all keyed on that one session ref. Budget for it in your queue design — it dominates wall-clock time, not the upload.

2. One bad invoice doesn't fail the batch

The inverse mistake. A document that fails semantic validation is rejected individually. The other 199 in the same session go through normally.

If you treat a batch as atomic and roll the whole thing back on any error, you'll re-send invoices that were already accepted, and duplicate invoice numbers are their own category of pain. Per-invoice status tracking isn't optional.

3. Not every buyer has a tax ID, and it isn't only consumers

FA(3)'s buyer section (Podmiot2) offers a choice of identifiers. One of them is BrakID, literally "no ID":

<fa:Podmiot2>
  <fa:DaneIdentyfikacyjne>
    <fa:BrakID>1</fa:BrakID>
    <fa:Nazwa>Jan Kowalski</fa:Nazwa>
  </fa:DaneIdentyfikacyjne>
</fa:Podmiot2>

I read that as "consumer invoices" and wrote validation that required a tax ID for everything else. Both halves of that were wrong.

Wrong on scale: roughly three in four invoices in one real customer's book have no buyer tax ID. Any validation demanding one rejects most of a working invoice book, which is a spectacular way to discover your assumption.

Wrong on meaning: BrakID is not consumer-only. A taxpayer can lack a tax ID too — in Poland, unregistered business activity is the common case — and such an invoice is still fully in scope of the mandate. If you special-case "consumer", you'll misclassify them.

The subtler bug that came out of this: my validation demanded the ID while my serialiser, twelve lines further down the same file, correctly emitted BrakID. The two disagreed for months without anyone noticing, because the code path that would have surfaced it was never called in production. Worth grepping for that shape in your own code — a validator and a serialiser that encode the same rule separately will drift, and the drift is silent.

4. Session encryption keys are per-session, and generating them is async

Invoices are uploaded encrypted with a symmetric key, which is itself wrapped with the system's public key (RSA-OAEP, SHA-256).

Two traps here.

The keys are per session. They are not credentials to cache. Generate them each time you open a session.

And in the TypeScript client I use, the call that produces them became async at one point, when it migrated to Web Crypto. My code destructured it as if it were synchronous:

// silently produces undefined for every field
const { cipherKey, cipherIv, encryptionInfo } = client.crypto.getEncryptionData();

// correct
const { cipherKey, cipherIv, encryptionInfo } = await client.crypto.getEncryptionData();

Nothing throws. You get undefined for all three, send an empty encryption field, and the server rejects it several calls later with a code that means "encryption must not be empty". The stack trace points at the session-open call, which is not where the bug is.

If you're on Deno specifically, one more note: use Web Crypto (crypto.subtle) rather than the node:crypto compatibility layer for the RSA-OAEP step. The compat path silently downgraded the mask generation function to SHA-1 for us, which produces ciphertext the server won't accept, and again nothing local fails.

5. When a government API tells you the problem is your data, believe it early

The expensive one.

Authentication kept failing with HTTP 450 and a message saying the token could not be used in the context of our tax ID. 450 is not a standard status code, and the message reads exactly like the sort of thing you get when your request is malformed.

So I checked everything on my side. Token format, scopes, permissions, the certificate, the encryption, the challenge encoding. All correct. I filed a support ticket. I waited.

The actual cause: that tax ID was in a bad state in the test environment's database. Nothing I could send would ever have worked. Generating a token for a different, properly registered tax ID authenticated cleanly on the first attempt.

That cost about three weeks, and the fix would have taken an hour on day one. The ticket was never going to resolve it, because there was nothing to fix on my side and the message had been telling me so the whole time.

The generalisable lesson: when an integration fails against a government system and the error blames your data, spend an hour testing that hypothesis directly before you spend a week disproving yours. Try a different account. It's cheap and it's decisive.

Choosing an integration path at all

Stepping back, there are really three ways to reach KSeF, and the right one depends far more on where invoices are created than on engineering taste:

Direct API integration — most work up front, least friction afterwards. Right when the system issuing the invoices is yours or your vendor already supports it.
File-based — the invoicing system stays untouched and something else maps its export into FA(3) and handles the session and receipt lifecycle. Right when the invoices come out of a billing, subscription, or warehouse system that will never speak to KSeF.
The government's free web app — genuinely fine at low volume, and worth trying before paying anyone.

Most of the pain above only exists on the first path. That's the honest trade: direct integration means owning sessions, encryption, per-invoice receipts, and error semantics forever.

I ended up building the middle option as a product, and I wrote up how the three paths compare, including the exact column mapping a file needs — that page is in Polish, since that's who has to deal with this, but the structure translates.

If you're starting a KSeF integration now: read the FA(3) schema before the API docs, assume the receipt is per invoice, and test your assumptions about buyer identifiers against a real invoice book rather than a fixture.