Preview draft. Copy and visuals are pending review and may change before launch.

Concept

The principle of least astonishment in authorization design

Nothing has to be misconfigured for a system to violate this principle. It only has to do something a reasonable person wouldn't have expected.

← Back to the library

Foundations and Principles · Published 2026-09-06

Predictability as its own requirement

Least astonishment holds that a system should behave the way a reasonable, familiar person would expect it to, and that a surprising outcome is itself a defect worth fixing — independent of whether that particular surprise happens to be safe. A permission grant broader than what the requester believed they were asking for, or an access that silently persists well past when someone assumed it would end, both violate the principle even when nothing in the system was actually misconfigured according to its own logic.

This matters because a system's users, including the engineers building on top of it, make decisions based on their mental model of how it behaves — and every gap between that mental model and the system's actual behavior is a place a mistake can quietly happen, entirely independent of whether the underlying logic technically did what it was told to do.

Distinct from making a control merely bearable

This is a different concern from psychological acceptability, which is about a control being tolerable enough that people actually go along with it rather than routing around it. A control can be perfectly bearable — people happily follow it — and still violate least astonishment if what it actually does doesn't match what a reasonable person following it expected to happen. The two principles address genuinely different failure modes and both matter independently.