DEV Community: Mohammadreza Alamnejad

RTL in practice: CSS logical properties, bidi text, icons, numerals and a testing checklist

Mohammadreza Alamnejad — Wed, 14 Oct 2026 08:21:25 +0000

The second layer of right-to-left work: the properties that don't flip, the strings that reorder themselves, and how to test so regressions don't come back.

Key takeaways

dir belongs in HTML, not CSS. Set dir on <html> (and on islands of other-direction content) so the browser's bidi algorithm, form controls and accessibility tree all agree.

Logical properties cover most layout, but not everything. transform, box-shadow, background-position, gradients and SVG coordinates are physical. Handle them with :dir().

Isolate every inserted value. <bdi>, dir="auto" and unicode-bidi: isolate in markup; FSI/PDI control characters in plain-text contexts like title, notifications and document.title.

Mirror icons by meaning, not by default. Arrows and "progress" icons flip; logos, checkmarks, media controls and clocks don't.

Format numerals with Intl, normalize input yourself, and avoid type="number" for codes and phone numbers.

Test RTL as a first-class configuration: lint for physical properties, run visual snapshots in both directions, and keep a bidi torture-string fixture.

I'm Mohammadreza Alamnejad, a UI/UX designer and developer, programmer and the founder of Arka Studio in Tehran. Everything my studio ships, including the café and restaurant platform NABZA, is Persian-first and right-to-left by default.

In an earlier article I covered the basics: lang="fa" dir="rtl" on the root, margin and padding logical properties, Jalali dates and digit normalization. This post is the follow-up for when the basics are done and the remaining bugs are the subtle ones.

1. Direction: HTML attribute first, CSS second

There are two ways to set direction: the dir attribute and the CSS direction property. Use the attribute.

<html lang="fa" dir="rtl">
  …
  <pre dir="ltr"><code>npm install</code></pre>
  <blockquote lang="en" dir="ltr">Quoted English paragraph…</blockquote>
</html>

Why the attribute wins:

It's semantic: screen readers, the :dir() pseudo-class, form controls and the bidi algorithm all use it.
CSS direction can be lost when styles fail to load, and it doesn't carry meaning into the accessibility tree.
dir is inherited, so you only set it at boundaries: the root, code blocks, embedded content in another language, and user-generated content (dir="auto").

Also set lang together with dir on foreign-language islands. lang affects font selection, hyphenation, quotes and screen reader pronunciation; dir affects layout and bidi. They are different things and you usually need both.

2. Logical properties: the full map

Most teams start with margin-inline-start and stop. Here is the wider set worth adopting everywhere:

Physical	Logical
`margin-left` / `margin-right`	`margin-inline-start` / `margin-inline-end`
`padding-left` / `padding-right`	`padding-inline-start` / `padding-inline-end`
`left` / `right`	`inset-inline-start` / `inset-inline-end`
`border-left`	`border-inline-start`
`border-top-left-radius`	`border-start-start-radius`
`border-top-right-radius`	`border-start-end-radius`
`text-align: left`	`text-align: start`
`float: left`	`float: inline-start`
`clear: left`	`clear: inline-start`
`width` / `height`	`inline-size` / `block-size`
`overflow-x`	`overflow-inline` (support is still limited, keep `overflow-x` as fallback)

A component written fully logically:

.toast {
  position: fixed;
  inset-block-end: 1rem;
  inset-inline-end: 1rem;          /* bottom-left in RTL, bottom-right in LTR */
  padding-block: 0.75rem;
  padding-inline: 1rem 1.25rem;    /* start, end */
  border-inline-start: 4px solid var(--accent);
  border-start-end-radius: 12px;
  border-end-end-radius: 12px;
  text-align: start;
  max-inline-size: 28rem;
}

Flexbox and grid already follow direction. flex-direction: row lays out from the inline start, so in RTL the first child is on the right. justify-content: flex-start and grid column lines follow too. A common bug is "fixing" this with flex-direction: row-reverse in RTL, which double-flips and puts things back in LTR order. If you find row-reverse in an RTL stylesheet, it's probably a bug.

Tailwind

Tailwind CSS (v3.3+) ships logical utilities: ms-*/me-* (margin start/end), ps-*/pe-* (padding), start-*/end-* (inset), rounded-s-*/rounded-e-*, border-s/border-e, and text-start/text-end. It also has rtl: and ltr: variants for the cases logical utilities can't express.

<button class="ps-4 pe-3 rounded-e-lg border-s-4 text-start">
  <svg class="rtl:-scale-x-100 …">…</svg>
  ادامه
</button>

Rule of thumb for a code review: ml-, mr-, pl-, pr-, left-, right-, text-left, text-right in a component are red flags unless there's a comment explaining why.

3. What logical properties don't cover

These are physical, and they're where most remaining RTL bugs live.

Transforms. translateX(100%) moves right in both directions. Drawers, carousels, slide-in toasts and "swipe to reveal" all need direction-aware transforms.

.drawer          { transform: translateX(-100%); }  /* hidden off the left (LTR) */
.drawer:dir(rtl) { transform: translateX(100%); }   /* hidden off the right (RTL) */
.drawer[open]    { transform: none; }

A trick that avoids duplicating every rule is a direction custom property:

:root            { --dir: 1; }
:root:dir(rtl)   { --dir: -1; }

.drawer          { transform: translateX(calc(-100% * var(--dir))); }
.chevron-next    { transform: scaleX(var(--dir)); }

Shadows and gradients. box-shadow: 4px 0 8px … casts to the right in both directions. linear-gradient(to right, …) is physical too. Use :dir(rtl) overrides or the --dir multiplier (calc(4px * var(--dir))).

Background position. background-position: left 1rem center for an input icon won't move. Prefer an inline element positioned with inset-inline-start, or override in :dir(rtl).

SVG and canvas. Coordinates are always left-to-right. Charts are the big case: does time run right-to-left in your Persian dashboard? There's no universal answer. Many Persian-speaking users are used to left-to-right time axes from international products, while others expect RTL. Decide deliberately, document it, and keep axis labels and tooltips in RTL text either way.

JavaScript positioning. Popover and tooltip libraries computing left from getBoundingClientRect() must know the direction. Check getComputedStyle(el).direction or the closest [dir], and prefer libraries with RTL support built in. Also watch scrollLeft: in RTL, modern browsers report 0 at the starting (right) edge and negative values as you scroll left. Code written assuming positive values will break horizontal carousels.

const isRTL = getComputedStyle(scroller).direction === 'rtl';
const distanceFromStart = isRTL ? -scroller.scrollLeft : scroller.scrollLeft;

4. Bidi text: why your punctuation jumps

The Unicode Bidirectional Algorithm (UAX #9) decides the visual order of characters with different directions. Strong characters (Persian letters, Latin letters) have a direction; neutral characters (spaces, punctuation, many symbols) take direction from their surroundings. Digits are "weak" and have their own rules. Problems appear when an LTR fragment sits at the edge of an RTL sentence, or when neutrals sit between the two.

Classic broken examples:

سفارش PO-1048 ثبت شد can render with the hyphen or the number in an unexpected position.
An English product name ending with ! or ) inside a Persian sentence: the punctuation attaches to the wrong side.
A phone number +98 912 … in a Persian paragraph shows the + at the wrong end.

In HTML: isolate

<p>سفارش <bdi>PO-1048</bdi> ثبت شد.</p>
<p>کاربر <bdi>{{ userName }}</bdi> نظر داد.</p>
<span dir="ltr">+98 912 000 0000</span>
<div dir="auto">{{ userComment }}</div>

<bdi> isolates a value whose direction you don't know: user names, product names, IDs.
dir="ltr" on a span forces a value you know is LTR (phone, email, URL, code).
dir="auto" picks direction from the first strong character; ideal for comments, messages and search queries.
In CSS, unicode-bidi: isolate gives a component the same behaviour as <bdi>; unicode-bidi: plaintext makes each paragraph pick its own direction, which is useful in chat-like lists.

In plain text: FSI and PDI

Some strings never become DOM elements: title attributes, document.title, alert(), push and system notifications, <option> text in some environments, CSV exports. There you can't use <bdi>, but you can use the Unicode isolate control characters:

const FSI = '\u2068'; // First Strong Isolate
const PDI = '\u2069'; // Pop Directional Isolate
const LRI = '\u2066'; // Left-to-Right Isolate

export const isolate = (s) => `${FSI}${s}${PDI}`;
export const isolateLtr = (s) => `${LRI}${s}${PDI}`;

document.title = `${isolate(productName)} | نبضا`;
new Notification('سفارش جدید', { body: `میز ${isolateLtr(tableCode)} سفارش داد` });

Prefer isolates (LRI, RLI, FSI + PDI) over the older embedding controls (LRE, RLE, PDF) and over sprinkling RLM/LRM marks. Isolates don't leak their effect into surrounding text. Strip these characters before comparing or storing values that will be searched, since they are invisible but real.

In i18n libraries

If you use ICU MessageFormat-style libraries, check whether interpolated arguments are isolated automatically. Some libraries can wrap arguments with isolates for you; others leave it to you. Either way, write one test with an LTR argument in an RTL message (see the torture strings below).

5. Icons: mirror by meaning

A short decision table I use with designers:

Mirror in RTL	Don't mirror
Back / forward arrows, chevrons	Logos and brand marks
Breadcrumb separators	Checkmark, plus, close (×)
"Next step", "send" when it implies direction	Play, pause, fast-forward (media follows tape direction)
Text alignment icons, list indent/outdent	Clocks and most refresh/sync circles
Progress or "reading" metaphors (book, open door)	Photos, maps, real objects
Sidebar toggle, drawer open	Numbers and letters inside icons

A few icons have no universal answer (undo/redo, the search magnifier, a phone handset). Design systems differ on them, so decide once, write it down, and apply it everywhere.

Implementation:

[dir="rtl"] .icon--directional { transform: scaleX(-1); }
/* or */
.icon--directional:dir(rtl)    { transform: scaleX(-1); }

Mark icons as directional in your icon component's API (<Icon name="chevron" directional />) instead of adding CSS at each call site. That keeps the decision in the design system, where it belongs. And if an icon contains text or numbers, never mirror it; ship a separate RTL variant.

6. Numerals: display, input and alignment

Display with `Intl`

const nf = new Intl.NumberFormat('fa-IR');
nf.format(48250000);             // Persian digits with Persian grouping
new Intl.NumberFormat('fa-IR', { style: 'percent' }).format(0.25);
new Intl.DateTimeFormat('fa-IR-u-ca-persian', { dateStyle: 'medium', timeZone: 'Asia/Tehran' })
  .format(new Date());

Use Intl instead of hand-written digit replacement for display. It handles separators, percent placement and calendars consistently. Use digit replacement only for normalization of input (below).

Input: avoid `type="number"` for codes

<input type="number"> is meant for quantities. For phone numbers, OTPs, postal codes and card numbers, it causes problems: leading zeros, spin buttons, scroll-wheel changes, and inconsistent handling of non-Latin digits across browsers and keyboards. Use text inputs with the right keyboard hint:

<label for="otp">کد تأیید</label>
<input id="otp" type="text" inputmode="numeric" autocomplete="one-time-code"
       dir="ltr" maxlength="6" pattern="[0-9۰-۹٠-٩]*">

<label for="mobile">شماره موبایل</label>
<input id="mobile" type="tel" inputmode="tel" autocomplete="tel" dir="ltr">

Then normalize before validation, in one shared function used by every form and by the server:

const PERSIAN = '۰۱۲۳۴۵۶۷۸۹';
const ARABIC  = '٠١٢٣٤٥٦٧٨٩';

export function normalizeDigits(s: string): string {
  return s.replace(/[۰-۹٠-٩]/g, (d) => {
    const i = PERSIAN.indexOf(d);
    return String(i >= 0 ? i : ARABIC.indexOf(d));
  });
}

export function normalizeMobile(raw: string): string | null {
  const s = normalizeDigits(raw).replace(/[\s\-()]/g, '');
  const m = s.match(/^(?:\+98|0098|98|0)?(9\d{9})$/);
  return m ? `0${m[1]}` : null;   // canonical 11-digit form
}

Alignment

In tables, align numeric columns to the end of the cell and use tabular figures, so digits of the same place value line up and amounts are easy to compare:

.table td.num { font-variant-numeric: tabular-nums; text-align: end; }

Check that your Persian font actually supports tnum; some don't, and you'll need a font that does for financial tables.

7. Forms, focus and caret details

Inputs inherit direction. A Persian form has RTL inputs by default. Email, URL, phone, code and password fields should be dir="ltr" so the caret and selection behave predictably; their labels stay RTL.
Search boxes should use dir="auto" because users search in both scripts.
Placeholders follow the input's direction. An LTR input with a Persian placeholder looks odd; consider ::placeholder { direction: rtl; text-align: end; } or put the hint in a visible help text instead.
Focus order follows DOM order, not visual order. Don't reorder elements visually with order or absolute positioning if it breaks keyboard navigation.
Select and date-picker popovers must open aligned to the inline start of the field.

8. Testing: make RTL a first-class configuration

Lint

Use stylelint-use-logical (from the csstools project) to flag physical properties in CSS, and an ESLint rule or code-review check for physical Tailwind classes.

{
  "plugins": ["stylelint-use-logical"],
  "rules": { "csstools/use-logical": ["always", { "except": ["float"] }] }
}

Visual snapshots in both directions

With Playwright, run key pages and components in both directions and compare screenshots:

// rtl.spec.ts
import { test, expect } from '@playwright/test';

for (const dir of ['rtl', 'ltr'] as const) {
  test(`checkout layout (${dir})`, async ({ page }) => {
    await page.goto('/checkout');
    await page.evaluate((d) => document.documentElement.setAttribute('dir', d), dir);
    await expect(page).toHaveScreenshot(`checkout-${dir}.png`, { fullPage: true });
  });
}

Even if you ship RTL only, the LTR snapshot is useful: a layout that breaks when direction flips usually has hidden physical properties.

A bidi torture-string fixture

Keep a fixture of strings and render them in every text-bearing component in Storybook or a test page:

export const bidiFixtures = [
  'سفارش PO-1048 ثبت شد.',
  'محصول iPhone 15 Pro (نسخهٔ ۲۵۶) موجود است!',
  'تماس: +98 912 000 0000',
  'ایمیل: someone@example.com را تأیید کنید.',
  'Order #۱۲۳ was paid',            // LTR sentence with Persian digits
  'می‌شود',                          // ZWNJ must survive
  '۲۵٪ تخفیف تا ۱۵ مهر',
  'نام خیلی خیلی خیلی طولانی محصول که باید در دو خط بشکند و دکمه را خراب نکند',
];

Manual checks before release

Automated tests catch regressions; a short manual pass catches meaning. On a real phone:

[ ] <html lang dir> correct; LTR islands marked
[ ] No physical properties in components (lint passes)
[ ] Drawers, toasts, carousels slide from the correct side
[ ] Shadows, gradients and input icons sit on the correct side
[ ] Horizontal scrollers start at the inline start; scrollLeft logic handles negatives
[ ] Directional icons mirrored; logos, media and checkmarks not
[ ] IDs, names, phones and emails isolated in sentences, titles and notifications
[ ] Numbers formatted with Intl; inputs accept and normalize any digits
[ ] Code, phone, email and OTP fields are dir="ltr" with RTL labels
[ ] Tables use tabular numerals and end alignment
[ ] Focus order matches reading order
[ ] Bidi fixture renders correctly in every text component
[ ] Charts have a documented time-axis direction

Closing

The first 80% of RTL is easy and well documented. The last 20% is a list of exceptions: physical transforms, invisible bidi rules, icons with meaning, and numbers that are both text and data. Write those exceptions down once, encode them in your design system and lint rules, and test them like any other configuration. Then RTL stops being a recurring bug category.

About the author

Mohammadreza Alamnejad is a UI/UX designer and developer, programmer and network security professional, and the founder of Arka Studio, a design and development studio in Tehran. He built NABZA, a Persian-first café and restaurant operations platform, along with Avenya, Natureio and Radepa. More on his founder page at Arka Studio.

Idempotency keys done right: exactly-once effects over at-least-once networks

Mohammadreza Alamnejad — Wed, 14 Oct 2026 04:19:33 +0000

Why "just retry" creates duplicate payments, and a PostgreSQL-backed design for idempotency keys that survives double clicks, timeouts, crashes and concurrent retries.

Key takeaways

Networks give you at-least-once delivery at best. Exactly-once delivery isn't achievable in general; exactly-once effects are, if the receiver de-duplicates.

An idempotency key identifies a user intent, not an HTTP attempt. Generate it once, when the user decides, and reuse it for every retry.

Store the key in the same transaction as the side effect. If the key and the effect can commit separately, you've only moved the race.

Fingerprint the request. Same key + same body = replay the stored response; same key + different body = reject with an error.

Handle in-flight duplicates explicitly (return 409 or wait), and make keys recoverable after a crash.

External calls need phases or an outbox. You can't put a payment gateway inside your database transaction, so design recovery points around it.

I'm Mohammadreza Alamnejad, a programmer and network security professional, UI/UX designer and developer, and the founder of Arka Studio in Tehran. In the café and restaurant operations platform my studio built, NABZA, several behaviours that users experience as "it just works" are idempotency underneath: a completed order becomes a sale once and only once even with a second click, duplicate payments or payments above the outstanding balance are rejected, a stock count can't be posted twice, and an offline order is submitted exactly once after reconnecting.

I mentioned idempotency briefly in a pre-launch checklist I published earlier. This post goes all the way down: the theory, the failure modes, a schema, the request lifecycle, concurrency, crash recovery and external side effects. The code is a reference implementation in TypeScript and PostgreSQL, not NABZA's source.

1. The problem: you can't tell "lost request" from "lost response"

Consider a client calling POST /payments and getting a timeout.

 Client                      Network                     Server
   │  POST /payments ───────────►│                          │
   │                             │ ───────────────────────► │  charge + commit ✔
   │                             │ ◄─────────────────────── │  201 Created
   │                    ✖ connection drops                  │
   │  (timeout)                  │                          │
   │  retry? ─────────────────── ?                          │

From the client's side, three different worlds look identical:

The request never reached the server.
The server processed it, and the response was lost.
The server is still processing it.

This is a practical cousin of the classic Two Generals' Problem: over an unreliable channel, no finite number of messages lets both sides be certain they agree. The consequence for APIs is simple. If the client never retries, you lose operations in world 1. If it always retries, you duplicate operations in world 2. Neither is acceptable for money or stock.

The way out is to make retries safe: at-least-once delivery + de-duplication at the receiver = exactly-once effect.

2. What HTTP already gives you

RFC 9110 defines GET, HEAD, OPTIONS, TRACE, PUT and DELETE as idempotent methods: sending the same request several times has the same intended effect on the server as sending it once. POST and PATCH are not idempotent by definition.

Two notes:

"Idempotent by method" is a contract you have to implement. A PUT handler that appends to a log on every call breaks it.
Most business operations ("create a payment", "complete an order", "post a stock count") are naturally POST. You need an explicit mechanism.

That mechanism is the idempotency key: a client-generated unique value sent with the request. The pattern was popularised by public payment APIs (Stripe documents it, and Brandur Leach wrote a well-known public post about implementing it on PostgreSQL), and there's an IETF HTTPAPI working group draft standardising an Idempotency-Key request header field. I'll use that header name below.

3. Rule one: one key per intent

The single most common bug I see: the key is generated inside the retry loop.

// ✖ Wrong: a new key per attempt = no de-duplication at all
async function pay(amount: number) {
  return retry(() => fetch('/payments', {
    method: 'POST',
    headers: { 'Idempotency-Key': crypto.randomUUID() },
    body: JSON.stringify({ amount }),
  }));
}

The key must be created when the user decides, and then reused by every attempt, including attempts after a page reload or an app restart.

// ✔ Right: key belongs to the intent, persisted with it
type PendingIntent = { key: string; body: unknown; createdAt: number };

export function createPaymentIntent(body: unknown): PendingIntent {
  const intent = { key: crypto.randomUUID(), body, createdAt: Date.now() };
  savePending(intent);            // IndexedDB / localStorage / device queue
  return intent;
}

export async function submit(intent: PendingIntent) {
  return retry(
    () => fetch('/payments', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'Idempotency-Key': intent.key },
      body: JSON.stringify(intent.body),
    }),
    { retries: 6, baseMs: 300, maxMs: 10_000 },
  );
}

On the UI side, a disabled button is a nice-to-have, not the guarantee. The guarantee is that two clicks that represent one decision share one key.

Retries with backoff and jitter

Retrying immediately and in lockstep from many clients turns a brief outage into a self-inflicted overload. Use exponential backoff with jitter:

export async function retry<T>(
  fn: () => Promise<Response>,
  { retries, baseMs, maxMs }: { retries: number; baseMs: number; maxMs: number },
): Promise<Response> {
  for (let attempt = 0; ; attempt++) {
    try {
      const res = await fn();
      // Retry only on outcomes that might succeed later.
      if (res.status !== 409 && res.status !== 429 && res.status < 500) return res;
      if (attempt >= retries) return res;
    } catch (e) {
      if (attempt >= retries) throw e;   // network error / timeout
    }
    const cap = Math.min(maxMs, baseMs * 2 ** attempt);
    await sleep(Math.random() * cap);    // "full jitter"
  }
}

Don't retry 400/422: those are deterministic. Do retry network errors, 5xx, 429 (honouring Retry-After) and 409 in-progress (see below).

4. The server side: a key is a small state machine

A key isn't just "seen / not seen". It moves through states:

stateDiagram-v2
    [*] --> started: first request (INSERT)
    started --> completed: effect committed + response stored
    started --> started: crash / timeout (recoverable)
    completed --> [*]: expires after retention window
    note right of started
      concurrent duplicate → 409 (in progress)
    end note
    note right of completed
      duplicate with same fingerprint → replay response
      duplicate with different fingerprint → 422
    end note

Schema

CREATE TABLE idempotency_keys (
  tenant_id        uuid        NOT NULL,
  actor_id         uuid        NOT NULL,       -- keys are scoped to who sent them
  key              text        NOT NULL CHECK (length(key) BETWEEN 8 AND 255),
  method           text        NOT NULL,
  path             text        NOT NULL,
  request_hash     bytea       NOT NULL,       -- sha256 of canonical body
  status           text        NOT NULL DEFAULT 'started'
                     CHECK (status IN ('started', 'completed')),
  recovery_point   text        NOT NULL DEFAULT 'started',
  locked_until     timestamptz,
  response_status  int,
  response_body    jsonb,
  created_at       timestamptz NOT NULL DEFAULT now(),
  updated_at       timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (tenant_id, actor_id, key)
);

CREATE INDEX idempotency_keys_gc ON idempotency_keys (created_at);

Design decisions worth calling out:

Scope. The primary key includes the tenant and the actor. A key from user A must never replay user B's response. In a multi-tenant system, that's a data leak, not just a bug.
Method and path. The same key sent to a different endpoint is a client bug; reject it rather than replaying an unrelated response.
request_hash. A fingerprint of the canonicalised body. Canonicalise (stable key order, normalised numbers) before hashing so semantically identical retries match.
recovery_point. Where a crashed request should resume. More in section 7.
locked_until. A lease, so a request that died mid-flight doesn't block the key forever.

5. The happy path, in one transaction

For operations whose side effects are all inside your database (create a sale, post a stock count, record a payment you've already confirmed), the whole thing fits in one transaction. That's the case to aim for.

import { createHash } from 'node:crypto';

const canonical = (v: unknown): string =>
  JSON.stringify(v, (_k, val) =>
    val && typeof val === 'object' && !Array.isArray(val)
      ? Object.fromEntries(Object.entries(val).sort(([a], [b]) => a.localeCompare(b)))
      : val);

export async function idempotent<T>(
  ctx: Ctx, req: { key: string; method: string; path: string; body: unknown },
  effect: (tx: Tx) => Promise<{ status: number; body: T }>,
) {
  const hash = createHash('sha256').update(canonical(req.body)).digest();

  return db.tx({ isolationLevel: 'read committed' }, async (tx) => {
    // 1. Try to claim the key. ON CONFLICT DO NOTHING makes this race-safe.
    const claimed = await tx.oneOrNone(
      `INSERT INTO idempotency_keys (tenant_id, actor_id, key, method, path, request_hash, locked_until)
       VALUES ($1, $2, $3, $4, $5, $6, now() + interval '30 seconds')
       ON CONFLICT DO NOTHING
       RETURNING key`,
      [ctx.orgId, ctx.userId, req.key, req.method, req.path, hash],
    );

    if (!claimed) {
      // 2. Someone has this key. Lock the row and decide.
      const row = await tx.one(
        `SELECT * FROM idempotency_keys
          WHERE tenant_id = $1 AND actor_id = $2 AND key = $3
          FOR UPDATE`,
        [ctx.orgId, ctx.userId, req.key],
      );
      if (row.method !== req.method || row.path !== req.path || !row.request_hash.equals(hash)) {
        return { status: 422, body: { error: 'idempotency_key_reused_with_different_request' } };
      }
      if (row.status === 'completed') {
        return { status: row.response_status, body: row.response_body, replayed: true };
      }
      return { status: 409, body: { error: 'request_in_progress' } };
    }

    // 3. We own the key: do the work in the SAME transaction.
    const result = await effect(tx);

    // 4. Store the response; commit makes key + effect visible together.
    await tx.none(
      `UPDATE idempotency_keys
          SET status = 'completed', response_status = $4, response_body = $5,
              locked_until = NULL, updated_at = now()
        WHERE tenant_id = $1 AND actor_id = $2 AND key = $3`,
      [ctx.orgId, ctx.userId, req.key, result.status, result.body],
    );
    return result;
  });
}

What happens in each failure scenario:

Scenario	Outcome
Response lost after commit; client retries	Row is `completed`, fingerprint matches → stored response replayed
Server crashes before commit	Transaction rolls back: no key, no effect. Retry starts fresh
Two identical requests arrive concurrently	One inserts; the other's `INSERT … ON CONFLICT` blocks until the first transaction commits, then sees a `completed` row → replay. (In the phased design of section 7, where a `started` key is committed before the effect finishes, the duplicate gets `409 request_in_progress` instead.)
Same key, different amount	`422`; the client has a bug and should not be "helped"
Effect throws a business error (e.g. insufficient stock)	Whole transaction rolls back. Decide whether deterministic 4xx outcomes should be stored so retries get the same answer (I usually store them; see below)

Should errors be stored? For deterministic failures (validation, "payment exceeds balance"), storing the response gives retries a consistent answer and prevents a later retry from succeeding after state changed, which would surprise the user. For transient failures (5xx, lock timeouts), don't store; let the retry try again. To store a 4xx, catch the business error inside the transaction, write the response, and commit.

6. Idempotency is not only keys: guard your state transitions

Keys de-duplicate requests. Your domain should also refuse to apply the same transition twice, because duplicates can come from places that don't carry your key: a second device, a background job, an admin tool.

-- Completing an order converts it to a sale exactly once.
UPDATE orders
   SET status = 'completed', completed_at = now()
 WHERE id = $1 AND tenant_id = $2 AND status = 'served'
RETURNING id;
-- 0 rows → already completed (or not ready): don't create the sale.

-- One sale per order, enforced by the database.
CREATE UNIQUE INDEX sales_one_per_order ON sales (tenant_id, order_id);

-- Payments can't exceed the outstanding balance (check inside the tx, with a lock).
SELECT total, paid FROM invoices WHERE id = $1 FOR UPDATE;

Think of these as defence in depth: the key handles retries of one request; conditional updates and unique constraints handle every other path to a duplicate. Natural keys (one sale per order, one count posting per count) are often stronger than any header.

7. External side effects: phases and recovery points

Things get harder when the effect includes a call you can't roll back: a bank gateway, an SMS provider, an email, a webhook to a partner. You can't hold a database transaction open across a network call to someone else's system, and you can't undo an SMS.

The approach: split the request into atomic phases, each its own transaction, and record a recovery point after each phase.

 Phase A (tx)                 External call              Phase B (tx)
 ┌─────────────────────┐      ┌───────────────┐          ┌──────────────────────┐
 │ claim key           │      │ gateway.charge│          │ record charge result │
 │ create payment row  │ ───► │ (idempotent   │ ───────► │ mark invoice paid    │
 │  status=pending     │      │  key = ours)  │          │ store response       │
 │ recovery=created    │      └───────────────┘          │ recovery=finished    │
 └─────────────────────┘                                 └──────────────────────┘

Rules that make this safe:

Pass an idempotency key downstream. Many payment and messaging APIs accept their own idempotency key or a client reference. Derive it deterministically from yours (for example payment:${paymentId}), so a resumed request reuses the same downstream key.
If the provider has no idempotency support, store enough to ask it ("what happened to reference X?") before trying again. Bank gateways typically have a verify/inquiry call; use it on recovery instead of charging again.
On a retry of a started key whose lease expired, resume from recovery_point instead of starting over.

async function resumePayment(ctx: Ctx, row: KeyRow) {
  switch (row.recovery_point) {
    case 'started':
      await phaseCreatePayment(ctx, row);              // tx: payment row + recovery='created'
    // fall through
    case 'created': {
      const p = await loadPayment(ctx, row);
      const r = await gateway.charge({ amount: p.amount, reference: `payment:${p.id}` });
      await phaseRecordResult(ctx, row, p, r);         // tx: result + recovery='finished'
    }
    // fall through
    case 'finished':
      return loadStoredResponse(ctx, row);
  }
}

Outbox for everything downstream

For effects that can happen after the response (notifications, webhooks, analytics, search indexing), use the transactional outbox pattern: write an event row in the same transaction as the business change, and let a separate worker deliver it.

CREATE TABLE outbox (
  id          bigserial   PRIMARY KEY,
  tenant_id   uuid        NOT NULL,
  event_id    uuid        NOT NULL UNIQUE,   -- consumers de-duplicate on this
  type        text        NOT NULL,
  payload     jsonb       NOT NULL,
  created_at  timestamptz NOT NULL DEFAULT now(),
  sent_at     timestamptz
);

// Worker: at-least-once delivery, with SKIP LOCKED so several workers can run.
const batch = await tx.any(
  `SELECT * FROM outbox WHERE sent_at IS NULL
    ORDER BY id LIMIT 100 FOR UPDATE SKIP LOCKED`,
);
for (const e of batch) {
  await deliver(e);                                  // may be retried → include event_id
  await tx.none(`UPDATE outbox SET sent_at = now() WHERE id = $1`, [e.id]);
}

The outbox moves the problem rather than eliminating it: the worker may deliver twice (crash after deliver, before UPDATE). That's fine, because each event carries event_id and the receiver de-duplicates. Which brings us to the other side.

Inbox: idempotent consumers

If you receive webhooks or queue messages, keep an inbox table and process each event_id once:

CREATE TABLE inbox (
  source     text NOT NULL,
  event_id   text NOT NULL,
  received_at timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (source, event_id)
);

await db.tx(async (tx) => {
  const fresh = await tx.oneOrNone(
    `INSERT INTO inbox (source, event_id) VALUES ($1, $2) ON CONFLICT DO NOTHING RETURNING 1`,
    ['gateway', event.id],
  );
  if (!fresh) return;              // already processed
  await applyEvent(tx, event);     // same transaction as the inbox insert
});

Producer outbox + consumer inbox is how you get exactly-once effects across a pipeline built on at-least-once delivery.

8. Offline queues are idempotency in slow motion

An offline-capable client is a client that retries hours later. The same rules apply, plus one more:

The key is created when the user taps "submit", stored with the queued item, and survives app restarts.
Items are submitted in order, and each is removed from the queue only after a definitive response (2xx or a stored 4xx).
The server re-validates business rules at submission time. A cached price on the device is not the truth. In NABZA's case, if a price changed while the order sat in the offline queue, the order is held for review rather than silently repriced. The key de-duplicates; the re-validation keeps the result correct.

9. Operational details that bite later

Retention. Keys can't live forever, and they can't expire too early. The retention window must be longer than the longest realistic retry horizon, including offline queues. Stripe, for example, documents that keys may be pruned once they are at least 24 hours old; offline POS clients may need a longer window. Clean up with a periodic job on the created_at index.

Key format. Accept opaque strings with length limits; recommend UUIDs (v4, or v7 for time-ordered locality). Never derive keys from guessable data like orderId + amount on the client side if a collision could merge two legitimate intents.

Response size. Store what you need to replay. If responses are large, store a reference (the created resource ID) and re-render it, accepting that the replay reflects current state.

Observability. Count replays, 409s and 422s per endpoint. A spike in 422 means a client generates keys incorrectly; a spike in replays may mean a network or timeout problem upstream.

Security. Treat keys as scoped identifiers, not secrets, but scope them to tenant and actor so they can't be used to fetch someone else's stored response. Don't store secrets or full card data in response_body.

10. Trade-offs and alternatives

Approach	Strength	Weakness
Idempotency key table (this post)	Works for any `POST`; replays exact responses	Extra write per request; retention to manage
Natural unique constraints	Simple, enforced by the DB, covers all paths	Only where a natural key exists
Conditional state transitions	Protects the domain regardless of entry point	Doesn't replay the original response
Client-chosen resource IDs + `PUT`	Idempotent by method semantics	Exposes ID generation to clients; not every operation is a "put"
Message de-duplication in a broker	Offloads work	Usually bounded windows; doesn't cover your DB writes

In practice you combine them: keys at the API edge, natural constraints and guarded transitions in the domain, outbox/inbox between services.

11. A test suite for idempotency

it('replays the original response for a duplicate', async () => {
  const key = crypto.randomUUID();
  const a = await post('/payments', { invoiceId, amount: 100_000 }, key);
  const b = await post('/payments', { invoiceId, amount: 100_000 }, key);
  expect(b.status).toBe(a.status);
  expect(b.body).toEqual(a.body);
  expect(await countPayments(invoiceId)).toBe(1);
});

it('rejects the same key with a different body', async () => {
  const key = crypto.randomUUID();
  await post('/payments', { invoiceId, amount: 100_000 }, key);
  const b = await post('/payments', { invoiceId, amount: 200_000 }, key);
  expect(b.status).toBe(422);
});

it('handles concurrent duplicates', async () => {
  const key = crypto.randomUUID();
  const results = await Promise.all(
    Array.from({ length: 10 }, () => post('/payments', { invoiceId, amount: 100_000 }, key)),
  );
  expect(await countPayments(invoiceId)).toBe(1);
  expect(results.every((r) => [201, 409].includes(r.status))).toBe(true);
});

it('does not replay another user\'s response', async () => {
  const key = crypto.randomUUID();
  await post('/payments', { invoiceId, amount: 100_000 }, key, userA);
  const b = await post('/payments', { invoiceId, amount: 100_000 }, key, userB);
  // The handler sets `Idempotent-Replayed: true` on replays; user B must never get one.
  expect(b.headers['idempotent-replayed']).toBeUndefined();
});

Add a chaos test: kill the server process between the effect and the response (or inject a fault after commit), then retry and assert a single effect.

Closing

Exactly-once isn't a property of the network; it's a property of your system's bookkeeping. Generate one key per intent, claim it in the same transaction as the effect, fingerprint the request, guard your transitions, and treat every external call as something that may need to be resumed or asked about. The reward is a product where a nervous double tap, a dropped connection or a crashed server never turns into a second charge.

Further reading (public): RFC 9110 (HTTP Semantics, section on idempotent methods); the IETF HTTPAPI draft "The Idempotency-Key HTTP Header Field"; Stripe's public API documentation on idempotent requests; Brandur Leach's public article "Implementing Stripe-like Idempotency Keys in Postgres"; and descriptions of the transactional outbox pattern, for example on microservices.io.

About the author

Mohammadreza Alamnejad is a programmer and network security professional, a UI/UX designer and developer, and the founder of Arka Studio, a design and development studio in Tehran. He built NABZA, a café and restaurant operations SaaS, along with Avenya, Natureio and Radepa. He studied Computer and IT at Sharif University of Technology and Iran University of Science and Technology. More on his founder page at Arka Studio.

Multi-tenant SaaS with branch-level RBAC in Next.js + Node: a practical architecture

Mohammadreza Alamnejad — Wed, 14 Oct 2026 01:17:28 +0000

Tenant scoping that fails closed, permissions that know about branches, and the tests that keep both honest.

Key takeaways

Resolve the tenant from the session, never from the request. A URL slug or header can select which of your memberships to use, but the server must verify that membership.

Next.js middleware is a gate, not a guard. Use it for redirects and cheap checks; do real authorization next to the data, in your Node API or server code.

Every Server Action and Route Handler is a public endpoint. Authorize inside each one, every time.

Make the database refuse cross-tenant reads. PostgreSQL row-level security with a transaction-local setting means a forgotten filter returns nothing instead of someone else's data.

Permissions are (action, scope), not role names. "Can approve purchases in branch 3" is the unit of authorization, and transfers check both ends.

Write the attacker's tests first: cross-tenant by ID, cross-branch, self-escalation, removing the last owner, and redacted fields in raw JSON.

I'm Mohammadreza Alamnejad, a programmer and network security professional, UI/UX designer and developer, and the founder of Arka Studio in Tehran. My studio built NABZA, an operations platform for cafés and restaurants with multiple organizations, branches and warehouses. Its public security page describes the principles this post is about: rows locked to their organization with row-level security, branch and warehouse scope checked on sensitive actions, the last owner can't be removed, and nobody can grant themselves more permissions.

The code below is a reference architecture I'd recommend for this kind of product, not NABZA's source code. It uses Next.js (App Router) for the web app and a Node API (Fastify here, but Express works the same way) in front of PostgreSQL. I previously published a pre-launch security checklist; this post is the implementation side of the tenant and RBAC items on that list.

1. The model: organizations, branches, memberships, assignments

The domain looks like this:

An organization (tenant) is a business: one brand, possibly many branches.
A branch belongs to one organization. Warehouses belong to a branch.
A membership links a user to an organization.
A role is a named bundle of permissions, defined per organization.
An assignment gives a membership a role, either for the whole organization or for one branch.

CREATE TABLE organizations (
  id   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  slug text NOT NULL UNIQUE,
  name text NOT NULL
);

CREATE TABLE branches (
  id      uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id  uuid NOT NULL REFERENCES organizations(id),
  name    text NOT NULL
);

CREATE TABLE memberships (
  id      uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id  uuid NOT NULL REFERENCES organizations(id),
  user_id uuid NOT NULL,
  is_owner boolean NOT NULL DEFAULT false,
  UNIQUE (org_id, user_id)
);

CREATE TABLE roles (
  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id      uuid NOT NULL REFERENCES organizations(id),
  name        text NOT NULL,
  permissions text[] NOT NULL          -- e.g. {'sales.create','inventory.transfer.approve'}
);

CREATE TABLE role_assignments (
  id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  membership_id uuid NOT NULL REFERENCES memberships(id) ON DELETE CASCADE,
  role_id       uuid NOT NULL REFERENCES roles(id),
  org_id        uuid NOT NULL REFERENCES organizations(id),
  branch_id     uuid REFERENCES branches(id),   -- NULL = all branches in the org
  UNIQUE NULLS NOT DISTINCT (membership_id, role_id, branch_id)  -- PostgreSQL 15+
);

Two design notes. First, every tenant-owned table carries org_id, even when it could be derived through a join. Redundant? Slightly. But it makes row-level security policies simple and fast, and it makes "which tenant owns this row?" a question you never have to reason about. Second, branch_id IS NULL meaning "organization-wide" keeps the model small; a shift supervisor gets a role assignment for one branch, an owner or regional manager gets one with NULL. Because branch_id can be NULL, the uniqueness rule uses NULLS NOT DISTINCT so the same organization-wide assignment can't be inserted twice.

2. Request flow: who decides what

Browser ──► Next.js middleware   (cheap: is there a session cookie? redirect if not)
        ──► Next.js server code  (Server Components / Actions / Route Handlers)
        ──► Node API             (authenticate, load membership + grants, authorize)
        ──► PostgreSQL           (RLS: rows outside app.org_id are invisible)

Each layer has one job. The mistake I see most is putting the authorization decision in the first layer because it's convenient, and then assuming everything behind it is safe.

3. Next.js middleware: a gate, not a guard

Next.js middleware runs before routing and is great for redirects. It's a bad place for authorization decisions that depend on your database, and you shouldn't treat a middleware check as the only thing protecting a route.

// middleware.ts
import { NextResponse, type NextRequest } from 'next/server';

export function middleware(req: NextRequest) {
  const hasSession = req.cookies.has('sid');
  if (!hasSession && !req.nextUrl.pathname.startsWith('/login')) {
    const url = req.nextUrl.clone();
    url.pathname = '/login';
    url.searchParams.set('next', req.nextUrl.pathname);
    return NextResponse.redirect(url);
  }
  return NextResponse.next();
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|api/health).*)'],
};

That's all middleware does here: no session, go to login. It doesn't decide which organization you belong to or what you may do.

Choosing the active organization. Users with several memberships need a way to switch. A path segment like /o/[orgSlug]/... is fine for navigation, but treat it as a request to use a membership, not as proof of one. The Node API checks it.

4. Server Actions and Route Handlers are public endpoints

A Server Action looks like a function call, but it is an HTTP endpoint anyone can invoke with crafted input. The same goes for Route Handlers. So every one of them authorizes, and none trusts IDs from the client.

// app/o/[orgSlug]/inventory/actions.ts
'use server';

import { api } from '@/lib/api'; // server-only fetch wrapper that forwards the session cookie

export async function approveTransfer(transferId: string) {
  // Don't pass orgId or branchId from the client. The API derives them.
  return api.post(`/transfers/${encodeURIComponent(transferId)}/approve`);
}

Keeping business logic and authorization in the Node API means there is exactly one place where the rules live, whether a request comes from the Next.js app, a mobile client or an integration key.

5. The Node API: build a request context once

On every request, authenticate the session, resolve the requested organization, verify the membership, and load the user's grants. Put the result on the request and pass it explicitly to services.

// api/plugins/context.ts
import fp from 'fastify-plugin';

export type Grant = { permission: string; branchId: string | null };
export type Ctx = {
  userId: string;
  orgId: string;
  membershipId: string;
  isOwner: boolean;
  grants: Grant[];
};

declare module 'fastify' {
  interface FastifyRequest { ctx: Ctx }
}

export default fp(async (app) => {
  app.addHook('preHandler', async (req, reply) => {
    const session = await app.sessions.verify(req.cookies.sid);  // your session store
    if (!session) return reply.code(401).send({ error: 'unauthenticated' });

    const requestedOrg = req.headers['x-org-slug'];  // a request, not a claim
    const m = await app.db.oneOrNone(
      `SELECT m.id, m.org_id, m.is_owner
         FROM memberships m JOIN organizations o ON o.id = m.org_id
        WHERE m.user_id = $1 AND o.slug = $2`,
      [session.userId, requestedOrg],
    );
    // Same response for "no such org" and "not your org": don't leak existence.
    if (!m) return reply.code(404).send({ error: 'not_found' });

    const grants = await app.db.any<Grant>(
      `SELECT unnest(r.permissions) AS permission, ra.branch_id AS "branchId"
         FROM role_assignments ra JOIN roles r ON r.id = ra.role_id
        WHERE ra.membership_id = $1`,
      [m.id],
    );

    req.ctx = { userId: session.userId, orgId: m.org_id,
                membershipId: m.id, isOwner: m.is_owner, grants };
  });
});

You can use AsyncLocalStorage to make the context implicit, and it works well. I still prefer passing ctx explicitly into services: it shows up in function signatures, in code review and in tests, and there's no way for a background job to accidentally run "inside" a stale request context.

6. Authorization: `can(ctx, permission, scope)`

The authorization function is small on purpose.

// api/authz.ts
import type { Ctx } from './plugins/context';

export class Forbidden extends Error { status = 403; }

export function can(ctx: Ctx, permission: string, scope?: { branchId?: string }) {
  if (ctx.isOwner) return true;
  return ctx.grants.some(
    (g) =>
      g.permission === permission &&
      (g.branchId === null || (scope?.branchId !== undefined && g.branchId === scope.branchId)),
  );
}

export function assertCan(ctx: Ctx, permission: string, scope?: { branchId?: string }) {
  if (!can(ctx, permission, scope)) throw new Forbidden(permission);
}

Note the asymmetry: a branch-scoped grant only matches when the caller names a branch and it's the right one. An action without a branch scope requires an organization-wide grant. That prevents a supervisor in branch 1 from calling an "organization-level" endpoint just because they hold the permission somewhere.

Load the target, then authorize against its scope

Never authorize against a branch ID sent by the client. Load the resource (inside the tenant transaction, see below) and use its branch.

// api/routes/transfers.ts
app.post('/transfers/:id/approve', async (req) => {
  return withTenant(req.ctx, async (tx) => {
    const t = await tx.oneOrNone(
      `SELECT id, from_branch_id, to_branch_id, status FROM transfers WHERE id = $1`,
      [req.params.id],
    );
    if (!t) throw new NotFound();               // RLS already hid other tenants' rows

    // A transfer touches two places: check both ends.
    assertCan(req.ctx, 'inventory.transfer.approve', { branchId: t.from_branch_id });
    assertCan(req.ctx, 'inventory.transfer.receive_into', { branchId: t.to_branch_id });

    const updated = await tx.result(
      `UPDATE transfers SET status = 'approved', approved_by = $2
        WHERE id = $1 AND status = 'requested'`,   // guarded transition
      [t.id, req.ctx.userId],
    );
    if (updated.rowCount === 0) throw new Conflict('already_processed');
    await audit(tx, req.ctx, 'transfer.approve', t.id, { status: t.status }, { status: 'approved' });
    return { ok: true };
  });
});

7. Tenant scoping in the database with RLS

Application checks are necessary; they're not sufficient. The database should refuse to return another tenant's rows even if a query forgets WHERE org_id = $1.

ALTER TABLE transfers ENABLE ROW LEVEL SECURITY;
ALTER TABLE transfers FORCE ROW LEVEL SECURITY;

CREATE POLICY org_isolation ON transfers
  USING      (org_id = nullif(current_setting('app.org_id', true), '')::uuid)
  WITH CHECK (org_id = nullif(current_setting('app.org_id', true), '')::uuid);

current_setting(..., true) returns NULL when the setting is missing, and org_id = NULL is never true, so a query that runs without a tenant context returns no rows. That's the fail-closed behaviour you want.

Set the value per transaction, never per connection:

// api/db/withTenant.ts
export async function withTenant<T>(ctx: Ctx, fn: (tx: Tx) => Promise<T>): Promise<T> {
  return db.tx(async (tx) => {
    // third argument `true` = local to this transaction
    await tx.none(`SELECT set_config('app.org_id', $1, true)`, [ctx.orgId]);
    return fn(tx);
  });
}

With a connection pool, a session-level SET leaks into whichever request gets that connection next. set_config(..., true) (equivalent to SET LOCAL) disappears at commit or rollback.

Two more requirements that are easy to miss:

The application's database role must not own the tables and must not be a superuser or have BYPASSRLS; owners bypass policies unless FORCE ROW LEVEL SECURITY is set, and superusers always bypass them.
Migrations and admin tooling use a different role from the application.

You can push branch scope into RLS as well, but I usually keep the database responsible for the tenant boundary and the application responsible for the branch and permission rules. Tenant leaks are catastrophic and simple to express in SQL; branch rules are richer and easier to test in code.

8. Field-level redaction in the response

Some data depends on permission, not just on scope: purchase costs, margins, wages. Remove it when you build the response, not in the React component.

// api/serializers/dailySummary.ts
export function serializeDailySummary(ctx: Ctx, s: DailySummary, branchId: string) {
  const base = { branchId, openOrders: s.openOrders, alerts: s.alerts };
  if (!can(ctx, 'finance.view', { branchId })) return base;   // no keys, not nulls
  return { ...base, netSales: s.netSales, grossMargin: s.grossMargin };
}

Omit the keys entirely rather than sending null; a null still tells the client the field exists and invites someone to wonder why.

9. Role management rules: no self-escalation, keep an owner

Role editing is where authorization systems usually break, because the endpoints that change permissions are themselves permissioned.

export async function assignRole(ctx: Ctx, tx: Tx, input: { membershipId: string; roleId: string; branchId: string | null }) {
  assertCan(ctx, 'members.manage', input.branchId ? { branchId: input.branchId } : undefined);

  if (input.membershipId === ctx.membershipId && !ctx.isOwner) {
    throw new Forbidden('cannot_change_own_roles');
  }

  const role = await tx.one(`SELECT permissions FROM roles WHERE id = $1`, [input.roleId]);
  // You can only hand out permissions you hold yourself, in that scope.
  for (const p of role.permissions) {
    assertCan(ctx, p, input.branchId ? { branchId: input.branchId } : undefined);
  }
  // ...insert assignment + audit event
}

export async function removeMember(ctx: Ctx, tx: Tx, membershipId: string) {
  assertCan(ctx, 'members.manage');
  // Lock the org's owner rows first so two concurrent removals can't both pass.
  const owners = await tx.any(
    `SELECT id FROM memberships WHERE org_id = $1 AND is_owner FOR UPDATE`, [ctx.orgId],
  );
  const isTargetOwner = owners.some((o) => o.id === membershipId);
  if (isTargetOwner && owners.length === 1) throw new Conflict('last_owner');
  // ...delete + audit event
}

Locking the owner rows before counting matters: without it, two owners removing each other at the same moment could both succeed. The same invariant should also be enforced when someone demotes an owner, not only when they remove one.

10. Tests: write the attacker's tests first

These are the tests I write before the feature tests, using Vitest and supertest against a real PostgreSQL (in a container) rather than mocks. RLS can't be tested with a mocked database.

// test/authz.spec.ts
import { describe, it, expect, beforeAll } from 'vitest';
import { seed, loginAs, http } from './helpers';

describe('tenant and branch isolation', () => {
  let s: Awaited<ReturnType<typeof seed>>;
  beforeAll(async () => { s = await seed(); }); // orgA (branch1, branch2), orgB

  it('cannot read another tenant\'s transfer by id', async () => {
    const a = await loginAs(s.orgA.owner, 'org-a');
    const res = await http(a).get(`/transfers/${s.orgB.transferId}`);
    expect(res.status).toBe(404);              // not 403: don't confirm it exists
  });

  it('branch-1 supervisor cannot approve a transfer out of branch 2', async () => {
    const sup = await loginAs(s.orgA.branch1Supervisor, 'org-a');
    const res = await http(sup).post(`/transfers/${s.orgA.transferFromBranch2}/approve`);
    expect(res.status).toBe(403);
  });

  it('cannot use an org slug you are not a member of', async () => {
    const a = await loginAs(s.orgA.owner, 'org-b');
    const res = await http(a).get('/branches');
    expect(res.status).toBe(404);
  });

  it('cannot grant yourself a role', async () => {
    const mgr = await loginAs(s.orgA.branch1Manager, 'org-a');
    const res = await http(mgr).post('/members/assign').send({
      membershipId: s.orgA.branch1Manager.membershipId, roleId: s.orgA.roles.owner, branchId: null,
    });
    expect(res.status).toBe(403);
  });

  it('cannot remove the last owner', async () => {
    const owner = await loginAs(s.orgA.owner, 'org-a');
    const res = await http(owner).delete(`/members/${s.orgA.owner.membershipId}`);
    expect(res.status).toBe(409);
  });

  it('omits financial fields for users without finance.view', async () => {
    const cashier = await loginAs(s.orgA.branch1Cashier, 'org-a');
    const res = await http(cashier).get(`/branches/${s.orgA.branch1}/daily-summary`);
    expect(res.body).not.toHaveProperty('netSales');
    expect(res.body).not.toHaveProperty('grossMargin');
  });

  it('a query without tenant context returns nothing', async () => {
    const rows = await s.appRoleDb.any('SELECT id FROM transfers'); // no set_config
    expect(rows).toHaveLength(0);
  });
});

The last test is my favourite: it proves that the database itself fails closed when application code forgets to set a tenant.

11. Pitfalls I check for in every multi-tenant Next.js app

Caching per-tenant data under a shared key. Anything cached across requests (unstable_cache, a Redis layer, a CDN) must include the organization (and, for permission-dependent responses, the user or role) in the key, or simply not be cached. React's per-request cache() is fine; cross-request caches are where leaks happen.
Static rendering of authenticated pages. Make sure pages that read the session are dynamic. A statically generated "dashboard" built with someone's data is a leak served to everyone.
Trusting IDs from forms. Hidden inputs with orgId or branchId are user input. Derive them on the server.
Background jobs without a tenant. Workers, cron jobs and exports must run inside withTenant for one organization at a time. A job that loops over "all orders" with an RLS-bypassing role is a leak waiting for a bug.
Search and analytics indexes. If you copy data into a search engine or warehouse, the tenant filter must exist there too, applied server-side.
Files and signed URLs. Storage paths should include the tenant, and URL signing should check the requester's scope at signing time.
Error messages that confirm existence. Return the same 404 for "doesn't exist" and "not yours".
Integration keys with organization-wide power. API keys should be scoped (for example to a single branch), stored hashed, and shown only once.
Role names in code. if (user.role === 'manager') scattered through the code base will drift. Check permissions, not role names.
No audit on permission changes. Every assignment, removal and ownership change should write an audit event with actor, time and before/after state.

Wrapping up

The architecture is deliberately boring: middleware redirects, the API decides, the database refuses. Each layer assumes the one in front of it might be wrong. That's what makes it safe to move fast later, when a new endpoint, a new job or a new client inevitably forgets something.

About the author

Mohammadreza Alamnejad is a programmer and network security professional, a UI/UX designer and developer, and the founder of Arka Studio, a design and development studio in Tehran. He built NABZA, a multi-tenant café and restaurant operations SaaS, along with Avenya, Natureio and Radepa. He studied Computer and IT at Sharif University of Technology and Iran University of Science and Technology. More on his founder page at Arka Studio.

The security and quality checklist I use before launching a SaaS: multi-tenant isolation, role-based access, idempotency, audit logs

Mohammadreza Alamnejad — Tue, 13 Oct 2026 01:19:29 +0000

Multi-tenant isolation, role-based access, idempotency and audit logs: the boring controls that decide whether customers can trust your numbers.

Key takeaways

Enforce tenant isolation in the data layer, not only in application code. Row-level security (or an equivalent mandatory filter) means one forgotten WHERE tenant_id = ? doesn't leak another customer's data.

Authorization is role + scope + ownership. Check who the user is, which branch, warehouse or project they may act on, and whether the target resource is inside that scope, on every sensitive request.

Hide data in the server response, not in the UI. A hidden button with the number still in the JSON is a data leak.

Every state-changing endpoint that moves money or stock must be idempotent. Double clicks, retries and offline sync must not create a second payment, sale or adjustment.

Audit logs should record actor, time, and before/after state, and be append-only for sensitive records.

Backups only count once you've restored one.

I'm Mohammadreza Alamnejad, a UI/UX designer and developer and the founder of Arka Studio. My background mixes front-end and product design with security work, and that mix shapes how I ship. Before any multi-tenant SaaS my studio builds goes in front of real users, including our café and restaurant operations platform NABZA, I go through a checklist like the one below.

This is a general checklist, not an audit report of any specific system. Where I mention NABZA, I'm only referring to behaviour that's already described publicly on its site.

1. Multi-tenant isolation

The worst bug a SaaS can ship is one customer seeing another customer's data. In a multi-tenant app, assume that somewhere, someday, a developer will forget a filter. Design so that mistake fails closed.

Checklist

[ ] Every tenant-owned table has a non-null tenant_id (or org_id) column.
[ ] Isolation is enforced in the database (row-level security, or a mandatory query layer that cannot be bypassed), not just in controllers.
[ ] The tenant is derived from the authenticated session, never from a request parameter or header the client controls.
[ ] Background jobs, exports, reports and search indexes are tenant-scoped too. These are where isolation usually breaks.
[ ] File storage paths and signed URLs include the tenant, and public files are explicitly opted in.
[ ] Caches are keyed by tenant. A shared cache key is a cross-tenant leak waiting to happen.
[ ] Automated tests log in as tenant A and try to read, update and delete tenant B's resources by ID.

A minimal PostgreSQL row-level security example:

ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
ALTER TABLE orders FORCE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON orders
  USING (tenant_id = current_setting('app.tenant_id')::uuid)
  WITH CHECK (tenant_id = current_setting('app.tenant_id')::uuid);

The application sets app.tenant_id per transaction from the verified session (SET LOCAL), and the application's database role must not be the table owner or a superuser, otherwise policies can be bypassed. NABZA's public security page describes the same principle: every row is locked to its organization with row-level security, so one organization's request doesn't see another's data.

2. Role-based access that's actually about scope

"Admin / manager / staff" is a starting point, not an authorization model. Real businesses have scope: a shift supervisor in branch 1 should not approve purchases for branch 2, and a storekeeper should only move stock out of the warehouses they are responsible for.

Checklist

[ ] Permissions are granular (e.g. inventory.transfer.approve), and roles are just bundles of them.
[ ] Every sensitive action checks role + scope + target: may this user do this action, in this branch, on this specific resource?
[ ] For transfers and similar flows, check both the source and the destination scope.
[ ] Users cannot grant themselves more permissions, or grant permissions they don't hold.
[ ] The last owner of an organization cannot be removed or demoted.
[ ] Field-level restrictions (e.g. financial figures) are applied when building the response, not with CSS or conditional rendering.
[ ] Every "hidden" field has been checked in the raw API response using the role that shouldn't see it.
[ ] Object IDs aren't trusted: check that GET /orders/123 belongs to the caller's tenant and scope (IDOR tests).
[ ] Privileged support access is limited to the specific ticket or conversation, and is logged.

The last owner rule and "no self-escalation" sound obvious, but they are among the first things I test, because they're easy to miss when roles are editable in the UI.

3. Idempotency: one intent, one effect

Users double-click. Mobile networks drop requests after the server has processed them. Clients retry. Offline queues replay. If an endpoint creates a payment, sale, stock movement or invoice, it has to be safe to call twice.

Checklist

[ ] Every state-changing request from the client carries an idempotency key (a UUID generated once per user intent, not per HTTP attempt).
[ ] The server stores the key with a hash of the request body and the result, inside the same transaction as the side effect.
[ ] A replay with the same key and body returns the original result; the same key with a different body is rejected.
[ ] State transitions are guarded (UPDATE ... WHERE status = 'ready'), so completing an order twice cannot convert it to a sale twice.
[ ] Payments are validated against the outstanding balance: duplicates and over-payments are rejected.
[ ] Offline sync submits each queued item exactly once and re-checks business rules (like price) on the server instead of trusting the cached client state.
[ ] Imports are safe to re-run: uploading the same opening-stock file twice doesn't double the stock.
[ ] Outgoing webhooks include an event ID so receivers can de-duplicate, and retries are bounded.

A simple schema:

CREATE TABLE idempotency_keys (
  tenant_id    uuid        NOT NULL,
  key          uuid        NOT NULL,
  request_hash text        NOT NULL,
  response     jsonb,
  created_at   timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (tenant_id, key)
);

Insert the key first, do the work, store the response, commit. A concurrent duplicate hits the primary key and waits or fails instead of doing the work twice.

On NABZA's public pages this shows up as product behaviour: an order is converted to a sale "once and only once, even with a second click", the kitchen ticket prints once even with two devices open, and an offline order that saw a price change is held for review instead of silently repriced. From the user's point of view, idempotency is a UX feature.

4. Audit logs that can answer "who changed this?"

When numbers don't match at the end of the day, the first question is always "who changed what, and when?" If your system can't answer, users fill the gap with suspicion.

Checklist

[ ] Important events record actor, tenant, timestamp, action, target, and before/after state.
[ ] Sensitive records (payments, stock adjustments, approved documents, published standards) are append-only. Corrections are new entries that reference the original, not edits.
[ ] The audit table can't be updated or deleted by the application role.
[ ] Manager overrides are labelled as such (e.g. "closed by manager") rather than looking like the employee did it.
[ ] Audit entries don't contain secrets, full tokens, passwords or unnecessary personal data. Mask phone numbers where full values aren't needed.
[ ] There's a UI to read the history. An audit log nobody can see doesn't build trust.

CREATE TABLE audit_events (
  id         bigserial   PRIMARY KEY,
  tenant_id  uuid        NOT NULL,
  actor_id   uuid,
  action     text        NOT NULL,
  target     text        NOT NULL,
  before     jsonb,
  after      jsonb,
  created_at timestamptz NOT NULL DEFAULT now()
);
REVOKE UPDATE, DELETE ON audit_events FROM app_role;

5. The rest of the pre-launch list

These don't fit the four headings above, but I check every one of them before launch.

Authentication and sessions

[ ] One-time codes (SMS/email) expire quickly, are single-use and are rate-limited per number and per IP.
[ ] Session cookies are HttpOnly, Secure, and SameSite; sessions are revoked on password reset and role change.
[ ] API keys are scoped (e.g. to one branch), hashed at rest, and shown only once at creation.

Input and outbound requests

[ ] Uploaded files are validated by content, not extension, then re-encoded (e.g. images converted to WebP), and only published assets are public.
[ ] Webhook destinations are validated against SSRF: no private, internal or loopback addresses, and no following redirects into them.
[ ] Outbound webhooks are signed (HMAC) with a per-endpoint secret and a timestamp to prevent replay.
[ ] Prices, discounts and totals from a client (like a guest's phone ordering from a QR menu) are never trusted; the server recalculates.

Data honesty

[ ] Missing data is shown as "unknown", never as zero. A cost of 0 and an unknown cost are different facts.
[ ] Features that depend on a third-party service that isn't configured are labelled as unavailable rather than faked.

Operations

[ ] Backups are encrypted, run daily and before each release, include an off-server copy, and have been test-restored.
[ ] Secrets live in environment or a secret manager, never in the repository; the repo history has been scanned.
[ ] Security headers (CSP, HSTS, X-Content-Type-Options, frame-ancestors) are set and tested.
[ ] Dependency and container scans are part of CI.
[ ] Error responses don't leak stack traces, SQL or internal hostnames.
[ ] Logs and alerts exist for repeated authorization failures and unusual activity.

How I run the checklist

I don't treat this as a document to tick once. Each item becomes either an automated test (cross-tenant access, idempotent replay, permission escalation attempts) or a release gate in CI. The manual part is a short adversarial session: log in as the least-privileged role, open the browser's network tab, and try to see, change or repeat something you shouldn't be able to. You'll be surprised how much a single afternoon of this catches.

Security in a SaaS isn't a feature page. It's whether a business owner can open the end-of-day report and believe it.

About the author

Mohammadreza Alamnejad is a UI/UX Designer & Developer, Founder of Arka Studio, a UI/UX and web/app design and development studio. His prior experience includes work on large Iranian products such as Achareh, Filimo, Bale and Digikala as a developer, UI/UX designer, front-end developer and in security. Read more on his founder page at Arka Studio or see NABZA, the café and restaurant operations platform his studio designed and built.

DEV Community: Mohammadreza Alamnejad

RTL in practice: CSS logical properties, bidi text, icons, numerals and a testing checklist

1. Direction: HTML attribute first, CSS second

2. Logical properties: the full map

Tailwind

3. What logical properties don't cover

4. Bidi text: why your punctuation jumps

In HTML: isolate

In plain text: FSI and PDI

In i18n libraries

5. Icons: mirror by meaning

6. Numerals: display, input and alignment

Display with Intl

Input: avoid type="number" for codes

Alignment

7. Forms, focus and caret details

8. Testing: make RTL a first-class configuration

Lint

Visual snapshots in both directions

A bidi torture-string fixture

Manual checks before release

Closing

Idempotency keys done right: exactly-once effects over at-least-once networks

1. The problem: you can't tell "lost request" from "lost response"

2. What HTTP already gives you

3. Rule one: one key per intent

Retries with backoff and jitter

4. The server side: a key is a small state machine

Schema

5. The happy path, in one transaction

6. Idempotency is not only keys: guard your state transitions

7. External side effects: phases and recovery points

Outbox for everything downstream

Inbox: idempotent consumers

8. Offline queues are idempotency in slow motion

9. Operational details that bite later

10. Trade-offs and alternatives

11. A test suite for idempotency

Closing

Multi-tenant SaaS with branch-level RBAC in Next.js + Node: a practical architecture

1. The model: organizations, branches, memberships, assignments

2. Request flow: who decides what

3. Next.js middleware: a gate, not a guard

4. Server Actions and Route Handlers are public endpoints

5. The Node API: build a request context once

6. Authorization: can(ctx, permission, scope)

Load the target, then authorize against its scope

7. Tenant scoping in the database with RLS

8. Field-level redaction in the response

9. Role management rules: no self-escalation, keep an owner

10. Tests: write the attacker's tests first

11. Pitfalls I check for in every multi-tenant Next.js app

Wrapping up

The security and quality checklist I use before launching a SaaS: multi-tenant isolation, role-based access, idempotency, audit logs

1. Multi-tenant isolation

2. Role-based access that's actually about scope

3. Idempotency: one intent, one effect

4. Audit logs that can answer "who changed this?"

5. The rest of the pre-launch list

How I run the checklist

Display with `Intl`

Input: avoid `type="number"` for codes

6. Authorization: `can(ctx, permission, scope)`