DEV Community: jguillaumesio

A practical playbook for running a remote dev team

jguillaumesio — Thu, 09 Jul 2026 16:00:34 +0000

We are eight people, fully remote: one lead, four developers, two product (one of them a designer), and one QA. We build a multi-tenant product: one shared codebase, plus features specific to individual tenants.

For a while it did not work. Bugs reached production regularly. We picked up work ad-hoc. Nobody had a clear picture of what was shipping next. And one QA cannot cover four developers on a codebase where a change for one client can quietly break another.

Then a new lead arrived. He did not rewrite our process from a book. He introduced five ceremonies, one at a time, each one aimed at a specific thing that was hurting us. This is the playbook: what each ceremony is, exactly how we run it, and what changed.

One honest caveat up front: we do not run fixed-length sprints. When I say "sprint review" below, read it as "release review." We run regular ceremonies over a continuous flow of work, not textbook Scrum. I think that is fine, and I will come back to it at the end.

Ship fewer bugs: put quality in the ticket, not just in QA

The worst bugs we shipped were per-tenant: a change for one client broke another. You cannot hire your way out of that fast enough. The only thing that scales is moving quality earlier, before a line of code is written. The industry name is "shift left," and the numbers are blunt: ambiguous or incomplete requirements are blamed for an estimated 50 to 60% of production defects, and a bug caught at the requirements stage costs a fraction of the same bug caught in production.

Requirements-phase defects (ambiguous acceptance criteria, missing edge cases, contradictory business rules) account for an estimated 50 to 60% of production defects, and teams that shift QA left reduce defect costs dramatically compared to teams that catch bugs in production.

Source: synthesised from IBM's Systems Sciences Institute data and Capgemini's World Quality Report

So we changed what a ticket must contain before anyone picks it up.

Every ticket gets acceptance criteria before it is estimated. Not a vague title. A concrete list of what must be true for the ticket to be done.

If a ticket is unclear, it gets an investigation first. We do not estimate something nobody understands. A short spike answers the open questions, and only then do we size it. This alone killed a class of "we did not realise it also touched X" bugs.

The multi-tenant rule: every ticket names the blast radius. Because our worst failures were cross-tenant, each ticket answers one question explicitly: does this touch shared code or a single tenant, and if shared, which tenants need checking? That one line turns an invisible risk into a checklist item.

Here is a template we paste into every non-trivial ticket:

## Acceptance criteria
- [ ] Given <state>, when <action>, then <result>
- [ ] Negative case: given <bad input>, then <handled how>

## Blast radius
- Touches: [ ] shared core   [ ] single tenant
- If shared, tenants to verify: <list>

## How to test
- <steps QA can follow without asking us>

Here is the part we have not fully solved, and I would rather be honest about it. Today the ticket creator writes the acceptance criteria, and we developers write the "how to test" notes. That works until it does not: sometimes those notes are thin, the ticket gets marked ready for release, and it should not have been. The root cause is not who typed the notes. It is that the author is effectively self-certifying. The person who wrote the code is the last person who should be the gate that says "this is releasable."

Where I think this goes next is a lighter version of what the industry calls the "Three Amigos": product, QA, and a developer shaping the criteria together, product owning the "what," QA owning "what could break," dev owning "what it touches." We do not run that ceremony yet. But even a lightweight Definition of Ready would help, and the release gate should be someone other than the author, QA when possible, a peer when QA is swamped.

Here is the checklist we are converging on, tick it against your own next ticket:

Acceptance criteria written and understood before estimation
Blast radius named: shared core or single tenant, and which tenants to verify
"How to test" steps a non-author can follow without asking questions
Release gate is someone other than the author

The regression net: the same cases, tested before every release

Acceptance criteria stop new bugs. They do nothing for the old feature that silently breaks when you touch shared code. For a multi-tenant product that is the most dangerous failure of all, and it needs its own guard: a fixed set of checks that runs before every release, not per ticket.

There are two acceptable versions of this, and you should be climbing from the second toward the first:

Automated end-to-end tests covering the critical paths: login, the core workflow, billing, and the per-tenant features that diverge from the shared core. Green suite or no release.
At minimum, a written list of must-pass scenarios, one set per important client, that QA runs before every release. Nothing ships until that list is green.

The multi-tenant rule applies here too: the list must include at least one scenario for every tenant whose behaviour differs from the shared core, because that is exactly where a "harmless" change detonates. And the list is a ratchet: the moment a regression slips through, its scenario gets added, so the same bug can never reach production twice.

This is the difference between "we tested the thing we changed" and "we proved we did not break the things we did not touch." Only the second one keeps a multi-tenant product stable as it grows.

What changed anyway: more tickets are genuinely ready for release, because more eyes hit them before they get there. The remaining gap is the self-certification one above, and naming it is the first step to closing it.

The retro: a Miro board, and votes that force focus

At the end of each release we open a Miro board with four columns:

What is good
What we learned
What is not going well
What we would want

Everyone adds notes, privately, at the same time. Writing before talking is the whole trick: it avoids the loudest voice setting the agenda and it avoids groupthink. Then everyone gets a small number of votes (we use three) to spend on the topics they most want to discuss. We only discuss the top-voted items. The rest are logged, not lost.

The retro is where every other ceremony on this page actually got tuned. It is also the ceremony most likely to become theatre. The single most common way retros fail is not the format, it is the follow-through:

The reason most retrospectives fail is not the meeting itself, it is what happens (or does not happen) afterwards. Action items get discussed, then forgotten by the next sprint.

Source: Easy Agile, Why Retrospectives Fail

This is exactly where we are weakest, so I will not pretend otherwise. We discuss the top items and we track them loosely, but we do not assign a named owner or turn each one into a Jira ticket. So some drift, and the same complaint resurfaces a few retros later. The fix we know we need is boring: two or three action items maximum, each with an owner and a ticket, revisited at the start of the next retro. An action with no owner did not really happen. We are not there yet, and writing it down here is partly to shame ourselves into it.

Planning poker: the size is disposable

We size tickets with planITpoker, but with one deliberate change: we do not vote in numbers. We vote in t-shirt sizes, XS, S, M, L, XL. Numbers invite false precision (is it really a 5 and not an 8?) and, worse, they invite someone to add them up into a velocity number and wave it around. Sizes resist both. "This is a Large" starts a conversation. "This is 8 points" starts a spreadsheet.

Everyone votes at the same time, hidden, then we reveal together. The blind reveal is the point: it kills anchoring, so a junior does not just echo the senior's card.

A wide spread, S next to XL, is not a failure of the estimate, that is the estimate doing its job. When the sizes disagree, someone knows something the others do not, a hidden dependency, an edge case, a tenant that behaves differently. The conversation that follows is the actual deliverable.

I want to be fair to the critics here, because they are the reason we dropped numbers in the first place. There is a loud, credible backlash against story points:

I don't like story points because they give a false sense of precision, and the moment management starts treating them as a productivity metric, they are weaponised against the very developers who produce them.

Source: paraphrasing Tomasz Lakomy, Why I don't like story-point-driven estimates, and Scott Logic, Story points are wasting time

They are right about the failure mode. Points become poison the instant a manager turns them into a burndown scoreboard. T-shirt sizes are our defence: there is nothing to sum, nothing to chart, nothing to weaponise. The size is disposable, the discussion is the deliverable. We use the vote to trigger a conversation, and then we mostly forget the letter.

The daily: coordination, not a status report

Fifteen minutes, same time every day, everyone on camera. Here is what it is for, and what it is not.

It is not a status report to the lead. The dailies people rightly hate are the ones where each person recites yesterday's tasks to a manager who writes them down. If that is all your daily is, it should have been an async written update, a Slack message. The critics are right about that. Keep the synchronous time for the blockers. So that is what each person actually covers: what is blocking me, and what I am about to touch, especially if it is shared code. Not a recital of yesterday's tickets.

Being fully remote, we felt the pull toward async written standups, and for pure status they would be better. But we kept the live daily for one reason it does well: coordination and surfacing blockers in real time. It is where "I am about to touch the shared billing code" meets "wait, so am I." That collision does not happen in a threaded update. So the rule is: keep it short, no solving problems in the meeting, take the deep dives to a breakout right after.

Less ad-hoc drift is one of the payoffs, not the biggest but a real one: because we sync every morning, fewer people quietly start random work, and everyone has a rough idea of what is being picked up. The bigger win is still the collisions we avoid by saying out loud what we are about to touch.

The sprint review: shared visibility, not a demo

Call it a release review in our case, since we do not run fixed sprints. The trap everyone falls into is treating this as a demo: a parade of every task, performed for an audience. Ours has no external audience at all, no clients, just the developers, product, and QA, which is exactly why we can optimise it for shared understanding instead of performance. Scrum's own guidance pushes back on the demo trap too:

The Sprint Review is not a demo. It is a working session to inspect the outcome and figure out what to do next. If it is a one-way presentation, you are doing it wrong.

Source: Scrum.org, Sprint Review: Much More Than Just A Demo

For us the real value is not the demo at all, it is shared visibility. We walk the whole internal team through what is going into the next release and what is queued behind it. Three things fall out of that:

Everyone learns the whole product. Because we discuss many tickets, including ones we will not personally pick up, more people understand more of the system. New joiners ramp faster.
Fewer PRs stuck in the review queue. When everyone already has context on a change, reviews are quick instead of archaeological.
We catch duplicates and collisions. Discussing tickets together is when someone says "that is the same as the thing I did last month" or "those two will conflict."

We do keep a separate slot for real demos: a Friday session you sign up for to show something you shipped. Honestly, it is our weakest ceremony. It tends to run long, not many people sign up, and half the time the interesting work never gets shown. The visibility review above is what earns its keep. The demo is still looking for its format.

None of this is clever. The reason shared visibility beats a polished demo is that the demo optimises for looking productive to outsiders, while the review optimises for the team actually knowing what is happening. The first is theatre. The second is the point.

The actual lesson

None of these five ceremonies is novel. You have heard of all of them. The thing worth copying is not the ceremonies, it is that each one was introduced to fix a specific, named pain:

Bugs in prod → acceptance criteria and blast radius in the ticket.
Ad-hoc chaos → the daily as coordination.
Estimates nobody trusted → blind planning poker in t-shirt sizes, with the size thrown away.
No shared picture → the review as visibility, not demo.
Everything drifting → the retro, with owned action items.

We do not do textbook Scrum. No fixed sprints, no formal Three Amigos, and one honest gap where authors still self-certify their own releases. That is fine. The goal was never to run the ceremonies correctly. It was to stop shipping bugs and start knowing what the team is doing. Pick the pain you actually have, and add the one ceremony that targets it. Then run the retro, and let it tell you what to add next.

Originally published on jguillaumesio.com

The cart timer expired while they were paying. Now what?

jguillaumesio — Fri, 03 Jul 2026 12:02:39 +0000

Here is a bug report I have received in some form at three different companies. The customer opens the payment widget, enters their card, and hits pay. While the bank is doing its 3-D Secure dance, the cart's countdown timer hits zero. The frontend, doing exactly what it was told, tears down the session. The payment succeeds a second later against a cart that no longer exists. Now there is money in the account and no order attached to it.

Every engineer who built that timer built it correctly. The countdown protects a limited resource: a concert seat, a hotel night, the last unit in stock. Holding it forever would let one abandoned tab starve every other customer. So you set a timer, and when it fires you release the hold. Clean, defensible, and completely blind to the fact that a real person had already committed their money.

That blindness is the actual subject here. The countdown-expiry bug is small. The habit that produces it is not.

The timer answers a question nobody asked at that moment

Step back and ask what the countdown is for. It exists to resolve contention: two people want the same seat, and the hold decides who gets first refusal. That is the only job. It is a fairness mechanism between customers who have not yet paid.

The moment a customer enters the payment flow, the question the timer answers stops being relevant. Contention is over. This person is not browsing, not hesitating, not sitting on a tab they forgot about. They are actively handing you money for the exact thing the hold was protecting. Firing the timer now does not serve any other customer, because no other customer can be served: the seat is about to be sold. It only serves the abstraction.

This is the tell. An engineer thinking in systems sees a timer that reached zero and a rule that says "release on zero". An engineer thinking about the product sees a person who did everything right and is about to be punished for the bank's latency. Same event, two completely different readings, and only one of them keeps the customer.

So, do you let them finish?

Yes. Almost always, yes. If the payment authorizes, honor it.

The reasoning is not sentimental. A successful authorization is the strongest possible signal of intent, far stronger than the "still holding" state the timer was guarding. Rejecting a payment you already accepted creates the worst outcome for everyone: you now have to refund, the customer sees a charge-then-refund cycle that reads as "this company is sketchy", and you have burned trust to enforce a rule that protected nobody. Forcing that refund by letting a timer kill a live payment is a self-inflicted wound.

The one case where you genuinely cannot honor it is true oversell: while this customer was in 3-D Secure, the last unit actually went to someone who completed faster. That is a real conflict, not a timer artifact. Handle it as an inventory failure with an immediate, automatic reversal and an honest message, not as a "your time ran out" error. The customer's experience should be "we were one second too slow and here is your money back instantly", never "you were too slow".

The two follow-up questions

Once you accept that a live payment should win, two design questions follow, and they are where most implementations quietly go wrong.

Do you re-lock the offer right after they paid? No. This one trips people up because the instinct is to keep the state machine consistent: the hold expired, so on the way out we should re-acquire it. But re-locking something the customer already bought is nonsense. They own it now. Payment is the terminal state, not another step that needs its slot reserved. If your code path re-locks after capture, you have a state machine that does not know the transaction is over, and that will produce its own class of bugs (double-holds, phantom availability) down the line.

Do you run a separate timer for the final step? Yes, and this is the actual fix. The browsing countdown and the payment window are two different clocks measuring two different things. The cart timer manages contention while the customer decides. The moment they commit to paying, you switch to a payment grace window: a separate, more generous timer whose only job is to give the authorization time to resolve. Bank redirects, 3-D Secure, wallet confirmations, slow networks: a 30-second cart hold that felt urgent while browsing is absurd once someone is staring at their banking app's confirmation screen. Give the final step its own clock, sized for how long a real payment actually takes.

Make expiry server-authoritative

The bug at the top of this article only reaches production when the timer lives in the browser and the browser is allowed to decide the session is dead. A frontend countdown is a display. It should never be the thing that releases inventory.

Put the authority on the server. The hold has an expiry timestamp the server owns. The frontend counts down for the human, but the decision to release is a server-side check that runs when it actually matters: when someone else tries to grab the seat, or when the payment webhook arrives. When the capture webhook lands, the server compares it against the hold and the inventory, and decides. A visual timer hitting zero is not an event that should mutate anything. It is a hint to the user, nothing more.

That single architectural move, holds expire on the server, the frontend only displays, eliminates the entire category. The countdown can hit zero and reset to "processing your payment" without ever touching the underlying reservation, because the reservation was never the frontend's to release.

The habit behind the bug

None of the above is hard. The reason it ships broken so often is not technical difficulty, it is that the timer was built as a pure systems problem. Resource, contention, TTL, release. Every line of that is correct and the sum of it fails a customer, because the model never included the customer's experience of time. To the system, zero is zero. To the person, they were three-quarters of the way through paying.

This is the engineer-versus-product gap, and it does not show up in the happy path. It shows up in exactly these seams: what happens when two clocks disagree, when the network is slow, when the user does the right thing at the wrong instant. Those edge cases are where the product actually lives, and they are the first thing a systems-only mindset drops, because from inside the system they look like correctly handled states, not like a human being told "too late" for something they already did.

The fix is not "care more". It is to make one question part of the definition of done for anything user-facing: what does the person on the other end experience when this fires? Ask it of the timer and you invent the grace window on your own. Skip it and you ship a state machine that is right about everything except the one thing it was for.

The rule I follow now

Any timer, lock, or expiry that a user can be actively working against needs two things: a server that owns the real deadline, and an answer to "what happens to someone mid-action when this fires". A countdown that can cancel a payment already in flight has neither. Give the final step its own clock, keep the authority on the server, and let a committed customer finish. The abstraction does not need protecting. The person does.

Originally published on jguillaumesio.com.

Multiple accounts in Claude Code: the complete setup

jguillaumesio — Thu, 25 Jun 2026 19:54:15 +0000

You have a personal Claude Code subscription and a work one. Or you freelance for two clients who each provide their own API key. Or you want a sandboxed account for experiments that won't pollute your main config.

Whatever the reason, Claude Code doesn't ship with a built-in "switch account" command. But the architecture makes it straightforward: everything lives in a single config directory, and you can redirect it.

How Claude Code stores state

Claude Code keeps all its state in ~/.claude by default. That includes:

Authentication tokens
Project-level settings (.claude/ inside each repo)
Conversation history
Memory files
MCP server configs

The key insight: the CLAUDE_CONFIG_DIR environment variable overrides where Claude Code looks for all of this. Point it somewhere else, and you get a completely independent instance.

Basic setup: shell aliases

Create one config directory per account:

mkdir -p ~/.claude-personal
mkdir -p ~/.claude-work

Find your Claude binary path:

which claude
# e.g. /Users/you/.nvm/versions/node/v22.15.0/bin/claude

Add aliases to your ~/.zshrc (or ~/.bashrc):

alias claude-personal='CLAUDE_CONFIG_DIR=~/.claude-personal claude'
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

Reload your shell:

source ~/.zshrc

Then authenticate each one separately:

claude-personal   # run /login inside the session
claude-work       # run /login inside the session

Each alias now opens Claude Code with its own auth, memory, and settings.

What the alias approach misses

The alias trick works, but it has gaps that will bite you in production use.

Problem 1: NVM version upgrades break absolute paths

If you hardcode the binary path in your alias (as many guides suggest), upgrading Node via NVM silently breaks it. Use just claude instead of the absolute path, and let $PATH resolve it:

# fragile
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work /Users/you/.nvm/versions/node/v22.15.0/bin/claude'

# resilient
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

Problem 2: project-level config leaks between accounts

Claude Code creates a .claude/ directory inside your project repo. That directory stores project settings, CLAUDE.md, and settings.json. These are shared across all your aliases because they live in the repo, not in the config dir.

This means your work account and personal account see the same project-level instructions. That's usually fine, but if you need different MCP servers or permissions per account per project, you'll need to handle it differently (see the wrapper script section below).

Problem 3: hooks and MCP servers are per-config-dir

If you've configured custom hooks or MCP servers in ~/.claude/settings.json, those won't exist in your new config directories. You'll need to copy or symlink the parts you want shared:

# share hooks across accounts
ln -s ~/.claude/settings.json ~/.claude-work/settings.json

Or, if you want different hooks per account, copy and customize:

cp ~/.claude/settings.json ~/.claude-work/settings.json

Problem 4: memory doesn't transfer

Each config directory has its own memory system. Your personal account won't remember what your work account learned. If you use memory-heavy workflows, that isolation is sometimes a feature, sometimes a problem.

Better approach: a wrapper script

Instead of simple aliases, a small wrapper gives you account switching with validation:

#!/usr/bin/env bash
# Save as ~/bin/claude-switch and chmod +x

ACCOUNT="${1:?Usage: claude-switch <account-name> [claude args...]}"
shift

CONFIG_DIR="$HOME/.claude-$ACCOUNT"

if [ ! -d "$CONFIG_DIR" ]; then
  echo "Account '$ACCOUNT' not found. Available accounts:"
  ls -d ~/.claude-* 2>/dev/null | sed 's|.*/.claude-||'
  exit 1
fi

CLAUDE_CONFIG_DIR="$CONFIG_DIR" exec claude "$@"

Usage:

claude-switch work
claude-switch personal --resume
claude-switch work -p "fix the login bug"

This passes all arguments through, so flags like --resume, --print, and -p all work.

Per-project account defaults

If a specific repo should always use a specific account, you can set it in a .envrc file (if you use direnv):

# /path/to/work-project/.envrc
export CLAUDE_CONFIG_DIR="$HOME/.claude-work"

Now every time you cd into that project and run claude, it automatically uses the work account. No alias needed.

Without direnv, you can add it to the project's shell history or a local .env file that your shell sources.

API key accounts vs OAuth accounts

There are two authentication modes in Claude Code, and they interact differently with multi-account setups:

OAuth (default): You run /login and authenticate through Anthropic's web flow. The token is stored in the config directory. This is what most people use with Claude Pro/Max subscriptions.

API key: You set ANTHROPIC_API_KEY as an environment variable. This bypasses the config directory's auth entirely.

For API key setups, you don't even need separate config directories for auth. You can just switch the key:

alias claude-client-a='ANTHROPIC_API_KEY=$CLIENT_A_KEY claude'
alias claude-client-b='ANTHROPIC_API_KEY=$CLIENT_B_KEY claude'

But you'll still want separate config directories if you need isolated memory, hooks, or MCP servers.

Combining both: API key + config isolation

The most robust setup for freelancers or consultants:

# ~/.zshrc
export CLIENT_A_KEY="sk-ant-..."  # or source from a secrets manager

alias claude-client-a='ANTHROPIC_API_KEY=$CLIENT_A_KEY CLAUDE_CONFIG_DIR=~/.claude-client-a claude'
alias claude-client-b='ANTHROPIC_API_KEY=$CLIENT_B_KEY CLAUDE_CONFIG_DIR=~/.claude-client-b claude'

Each client gets:

Their own API key (billing goes to the right place)
Their own memory (client context stays separate)
Their own MCP servers (different clients, different tools)
Their own hooks (different code review standards, different workflows)

Running accounts simultaneously

You can run multiple Claude Code instances in parallel, each in its own terminal tab. The config directories are independent, so there's no locking or conflict.

# Terminal 1
claude-work

# Terminal 2
claude-personal

Both sessions run concurrently without interference. This is useful when you're waiting on a long task in one account and want to work on something else in another.

Quick reference

What you want	What to set
Different auth	`CLAUDE_CONFIG_DIR`
Different API key	`ANTHROPIC_API_KEY`
Different memory	`CLAUDE_CONFIG_DIR`
Different MCP servers	`CLAUDE_CONFIG_DIR` + custom `settings.json`
Per-project default	`.envrc` with `CLAUDE_CONFIG_DIR`
All of the above	Combined alias with both env vars

Going further: multiple Claude Desktop instances

Everything above covers Claude Code (the CLI). If you also use the Claude desktop app and want two instances running side by side with different accounts, the approach is different: you need to duplicate the app itself.

On macOS, Parallels Toolbox can create an "app shortcut" that acts as a second copy of Claude. Each copy maintains its own login session, so you can run your work account in one window and your personal account in another, without logging in and out. This walkthrough shows the full setup.

The process: open Parallels Toolbox, create an app shortcut pointing to Claude, give it a distinct name (like "Claude Work"), approve it in macOS security settings, and log in with your second account. Both instances live in your dock and run independently.

This pairs well with the CLI multi-account setup: use CLAUDE_CONFIG_DIR aliases for terminal work, and Parallels app shortcuts for the desktop GUI.

What I actually use

Two config directories: ~/.claude-personal for my own projects, ~/.claude-work for client work. Direnv handles the switching per project, so I just type claude and it picks the right account. I symlink settings.json from my personal config to the work one because I want the same hooks everywhere, but memory stays separate.

The total setup took five minutes. The part that took longest was realizing I needed to re-run /login in each config directory after creating it.

Originally published on jguillaumesio.com

Cloudflare under the hood: how it works and how attackers try to get around it

jguillaumesio — Mon, 22 Jun 2026 10:21:35 +0000

1. What Cloudflare actually is

Cloudflare is not a reverse proxy running on one server somewhere. It is a globally distributed edge network with over 300 points of presence (PoPs). When you put your domain behind Cloudflare, you are routing all traffic through that network before it ever reaches your server

The mechanism is anycast routing. Cloudflare announces the same IP address from every PoP simultaneously. When a user sends a request to your site, BGP routing automatically directs it to the closest PoP, not to your origin server. From there, Cloudflare decides what to do with it

User in Tokyo
   |
   | (anycast routes to nearest PoP)
   v
Cloudflare Tokyo PoP
   |-- cached? → serve from edge, origin never touched
   |-- blocked? → return 403, origin never touched
   |-- challenge? → run Turnstile, origin never touched
   |-- clean? → forward to origin, return response
   v
Your origin server

TLS termination happens at the edge PoP, not at your origin. Cloudflare holds the certificate, decrypts the request, inspects it, then re-encrypts it for the leg to your origin (assuming SSL between Cloudflare and origin is enabled, which it should be)

This is why Cloudflare can inspect HTTPS traffic for WAF rules without a man-in-the-middle attack: you are explicitly delegating that decryption to them

2. The layers between a request and your server

A request arriving at a Cloudflare PoP passes through several decision layers in order:

DDoS mitigation runs first. Volumetric floods are absorbed at the network layer. HTTP floods are identified by rate, pattern, and reputation

IP reputation and geofencing checks the source IP against Cloudflare's threat database. IPs from known botnets, Tor exit nodes, or datacenter ranges are scored

WAF inspects the HTTP layer: headers, path, query params, body. Cloudflare maintains a managed ruleset covering OWASP Top 10 plus known CVEs

Bot management (Turnstile is the visible part) assigns each request a bot score from 1 to 99. Score 1 is almost certainly a bot. Score 99 is almost certainly human

Cache is the last layer before origin. If the response is cacheable and a fresh copy exists at the PoP, Cloudflare serves it without touching your server

3. How Turnstile works

Turnstile is Cloudflare's CAPTCHA replacement. Unlike reCAPTCHA v2, it has no image challenge: the goal is to verify a visitor is human without making them solve anything visible

1. The widget loads a JS challenge from Cloudflare's edge. The script is different per request, not a static file you can analyze once

2. The script collects passive signals:

Timing: how long did each JS operation take? Headless browsers running at full CPU speed have suspiciously uniform timing.
Interaction: did the mouse move before the form was submitted? Did keystrokes have natural delays?
Browser fingerprint: canvas rendering, WebGL renderer, installed fonts, audio context output.
Environment: is navigator.webdriver exposed? Are dev tools open?

3. Cloudflare runs those signals through a model trained on billions of requests and issues a signed token if the request looks human

4. Your backend verifies the token against Cloudflare's siteverify API:

POST https://challenges.cloudflare.com/turnstile/v0/siteverify
{
  "secret": "your-secret-key",
  "response": "token-from-widget"
}

If your backend does not make this call, the protection is entirely client-side and trivially bypassed by skipping the form submission step

4. Finding the origin server behind Cloudflare

If an attacker finds your origin IP, they can bypass Cloudflare entirely by sending requests directly to that IP. Your WAF, DDoS protection, and Turnstile all disappear

Here are the techniques commonly used, in order of how often they succeed

SSL certificate history

Before you put a domain behind Cloudflare, it had a certificate issued directly to the origin. Certificate transparency logs are public and record every certificate ever issued:

https://crt.sh/?q=example.com

If the origin IP appeared in a certificate before Cloudflare was enabled, it is in the log forever

DNS history

Before Cloudflare, your A record pointed directly to your origin. Those records are archived by SecurityTrails, DNSDumpster, and ViewDNS.info, often with timestamps showing exactly when you switched

Subdomains not behind Cloudflare

Many teams proxy www and the apex but leave other subdomains with a grey cloud (not proxied) by accident:

ftp.example.com: legacy, often points to origin
dev.example.com, staging.example.com: forgotten
api.example.com: sometimes bypasses the proxy for latency reasons

A subdomain enumeration pass reveals which subdomains resolve to a non-Cloudflare IP

MX records

Mail servers cannot be proxied through Cloudflare. Your MX record points directly to a mail server, often on the same IP block as your web server:

dig MX example.com        # → mail.example.com
dig A mail.example.com    # → 203.0.113.42

SPF records

SPF records list every IP authorized to send email on your behalf. They often include your origin server or hosting provider's IP range:

dig TXT example.com
# v=spf1 ip4:203.0.113.0/24 include:sendgrid.net ~all

Shodan + certificate fingerprint

If your origin uses a Cloudflare origin certificate, its fingerprint is the same regardless of how it is accessed. Shodan and Censys index TLS certificates across the entire IPv4 space: search for your cert fingerprint to find the raw IP

5. Bypassing Turnstile

Solving services

2captcha, Anti-Captcha, and CapSolver use human workers who run a real browser session and return the token. This works but is slow (seconds per token) and costs money per solve. Practical at low volume, expensive at scale

Headless browser spoofing

Playwright and Puppeteer combined with stealth plugins patch the detectable properties:

navigator.webdriver set to undefined
Spoofed canvas fingerprint
Realistic mouse movement and keystroke timing
Full Chrome user agent

A well-configured headless browser can pass Turnstile at a reasonable rate. Cloudflare's model is continuously updated, but it is an ongoing arms race

What actually stops most bots

The visible Turnstile widget is not the main defense. Cloudflare's bot score from network-level signals (IP reputation, ASN, request rate, TLS fingerprint) catches far more traffic than the JS challenge does. A request from AWS Lambda with a clean User-Agent still has a datacenter ASN: that alone raises the bot score before any JS runs

Turnstile alone, validated client-side only, is weak. The combination of network scoring plus behavioral analysis is what makes the system effective

6. How to actually protect your origin

Use Cloudflare Tunnel. This is the only approach that fully hides your origin IP. cloudflared opens an outbound connection from your server to Cloudflare's network. No open inbound ports, no IP to find.

cloudflared tunnel create my-tunnel
cloudflared tunnel route dns my-tunnel example.com
cloudflared tunnel run my-tunnel

If you cannot use Tunnel, firewall your origin to Cloudflare IPs only. Cloudflare publishes its full IP range at cloudflare.com/ips-v4. Allow only those ranges on 80 and 443. Drop everything else

Proxy every subdomain. Audit your DNS records. Every subdomain that should be proxied must have the orange cloud enabled. Grey-cloud records pointing to your origin are a bypass by design

Keep mail on a separate IP. Your mail server should not share an IP or IP block with your web server

Validate Turnstile server-side, always. The token must be verified by your backend on every form submission

Check your certificate history now. Run your domain through crt.sh and SecurityTrails. If your old origin IP is visible, either move to a new IP (and use Tunnel going forward) or rely entirely on the firewall approach

Originally published on jguillaumesio.com

Stop refunding payments you should never have charged

jguillaumesio — Tue, 16 Jun 2026 18:33:51 +0000

I once shipped a checkout that charged the card the instant the customer hit pay, then ran the order validation afterward. Stock check, address validation, a fraud heuristic, a third-party availability call. When any of those failed, the code did the obvious thing: it refunded the payment

It worked. It also generated a steady trickle of confused, angry emails. "Why did you charge me 89 euros and then refund it three days later?" To the customer, a charge followed by a refund does not read as "we caught a problem". It reads as "this company is sketchy and now my money is stuck in limbo for a week"

The fix was one property I had been ignoring for years: capture_method: manual

The charge-then-refund antipattern

Here is the flow almost every tutorial teaches, and the one I had shipped:

const intent = await stripe.paymentIntents.create({
  amount: 8900,
  currency: 'eur',
  payment_method: paymentMethodId,
  confirm: true,
});

// money has now left the customer's account

const order = await validateOrder(cart);
if (!order.ok) {
  await stripe.refunds.create({ payment_intent: intent.id });
  throw new Error('Order validation failed after charge');
}

The problem is the comment. By the time you run validateOrder, the money is gone. The charge has hit the customer's statement, your statement, and in cross-border cases an FX conversion. If validation fails, you are not undoing a mistake, you are issuing a second financial event that has to settle on its own timeline

That has real costs:

The customer sees a charge and a refund, days apart, and loses trust
Refunds can take 5 to 10 business days to land back on the customer's statement
You may not get every fee back, and FX swings mean the refund amount can differ from the charge
A pattern of charges-then-refunds is exactly what card networks flag as a risk signal

You did everything to be honest and it still looks bad. The flow is the problem, not your intentions

Authorize, then capture

Cards have always supported a two-step model: authorization places a hold on the funds without moving them, and capture actually moves the money. Hotels and car rental companies have used this forever. The hold sits on the customer's card, the money never leaves until you decide it should, and if you never capture, the hold simply expires

Stripe exposes this with one property on the PaymentIntent:

const intent = await stripe.paymentIntents.create({
  amount: 8900,
  currency: 'eur',
  payment_method: paymentMethodId,
  capture_method: 'manual',
  confirm: true,
});

// funds are AUTHORIZED, not captured, nothing has moved yet

const order = await validateOrder(cart);

if (order.ok) {
  await stripe.paymentIntents.capture(intent.id);
} else {
  await stripe.paymentIntents.cancel(intent.id);
}

cancel releases the hold. No charge ever appeared, so there is no refund to explain. The customer sees a pending authorization that quietly drops off. You moved the risky business logic to where it belongs: between the authorization and the capture, while the money is still reversible without a trace

What you get for free

Partial capture. You can capture less than you authorized. Authorize 89 euros for a cart, discover one item is out of stock, capture 64 euros and the rest of the hold releases automatically:

await stripe.paymentIntents.capture(intent.id, {
  amount_to_capture: 6400,
});

A real validation window. Stripe holds an uncaptured authorization for about 7 days. That is plenty of time for a synchronous stock check, and enough for some asynchronous flows too. If you never capture, you never charged

A clean audit trail. "Authorized, then cancelled" is a single coherent story in your logs and in the customer's mind. "Charged, then refunded" is two events that have to be reconciled, and that reconciliation is where money quietly goes missing

This is not Stripe-specific

The property name changes, but every serious payment provider exposes the same authorize-then-capture model:

Stripe: capture_method: 'manual' on the PaymentIntent, then paymentIntents.capture() or paymentIntents.cancel()
Adyen: set a manual capture delay, then call /payments to authorize and /payments/{id}/captures to capture
Braintree: pass submitForSettlement: false to transaction.sale, then transaction.submitForSettlement(id) later
PayPal: create the order with intent: 'AUTHORIZE', then capture the authorization

The vocabulary differs, the shape is identical: get a hold, do your work, settle or release

When you should not use it

Instant digital goods. If you deliver the moment payment succeeds and there is nothing to validate, the extra round trip buys you nothing
Subscriptions and recurring billing. These run on their own automated capture flow
Validation slower than the hold. If your checks can take longer than 7 days, the authorization will expire before you capture
Methods that do not support it. Some non-card payment methods do not offer separate auth and capture, confirm support before you build around it

The rule

If there is any business logic that can fail after the customer has paid but before you are willing to keep their money, that logic belongs between an authorization and a capture

The charge-then-refund flow is the default in almost every example online, which is exactly why it ends up in production. One property moves the risky work to the right side of the money, and the angry emails stop

Originally published on jguillaumesio.com