Your team wants request-scoped user data available as `req.user` throughout a TypeScript service by augmenting the web framework's `Request` interface globally. As the engineer setting the standard, how do you weigh that global augmentation against the alternatives?

## What you are actually deciding Module and global augmentation are program-wide edits to a type you do not own. Once `user` is on `Request`, it is on *every* `Request`: in handlers behind the auth middleware, in handlers in front of it, in health checks, in tests that build a bare request object, and inside any other library that types a parameter as `Request`. The mechanism has no notion of scope, and it has no runtime component — nothing forces anyone to assign the property. So the design question is not "can we augment" but "is the claim we are adding true across the entire program". That reframing settles most of these debates. ## The three options and what each costs **Global augmentation with an optional property.** `user?: User` is the honest version. Every call site is forced by the checker to handle `undefined`, which is exactly what the runtime allows. The cost is friction: handlers that genuinely run behind auth still have to narrow, and teams get tempted to reach for `!` at every use — which quietly restores the unsound version while looking safe. **Global augmentation with a required property.** Ergonomically lovely and a lie. It tells the checker something false about every request in the program, so a route registered before the middleware, or a test fixture without it, becomes a runtime `undefined` where the type promised a value. This is the option I would rule out by policy, because the failures it produces are silent and appear far from the declaration. **A distinct type at the boundary.** Keep the framework's `Request` untouched and give authenticated handlers their own type — `interface AuthenticatedRequest extends Request { user: User }` — produced by a middleware or wrapper whose signature is the only way to obtain it. Now the compiler proves that a handler taking an `AuthenticatedRequest` is only reachable through code that supplies the user. The cost is plumbing: a wrapper, a slightly heavier handler signature, and the need for everyone to use it. **An explicit context object.** Drop the augmentation entirely and thread a typed context (or use the framework's own store, if it has one) through the call chain. Most explicit, most testable, and the most work to retrofit into an existing codebase. ## How I would decide Ask four questions: 1. **Is the property universally present?** If yes, augmentation is defensible. If it depends on a middleware, route, or environment, the type must say so. 2. **Who else sees this type?** In a monorepo, an augmentation in one package can affect every package that shares the compilation, including ones whose maintainers never asked for it. The blast radius is a real cost. 3. **What happens when it is missing?** A missing analytics field is a nuisance; a missing `user` treated as present is an authorisation defect. The higher the stakes, the more the type should force the check. 4. **Can two augmentations collide?** Name collisions between your augmentation and a library's are hard to resolve because both declarations are outside your reach. Namespacing the added member — one `ctx` object rather than five loose fields — reduces the surface. ## The policy I would write - Augmentations live in one declarations file per package, reviewed like a public API, with a comment naming the middleware or host that supplies each member. - Added members are optional unless the value is genuinely present on every instance in the program. - Security-relevant values are never merely optional-on-the-shared-type: they get a distinct type that only the authenticating path can produce. - Prefer one namespaced member over several loose ones, to limit collisions. - Periodically audit: an augmentation whose supplying middleware was removed is invisible rot, since nothing fails when the promise stops being kept. ## The line to hold The seductive property of augmentation is that it makes a type convenient everywhere at zero apparent cost. The cost is that it also makes the type *less true* everywhere, and the type system's whole value is the accuracy of its claims. When accuracy and convenience conflict on a value that authorisation decisions depend on, accuracy wins — and the way to pay for it is a wrapper type, not a habit of asserting non-null at three hundred call sites.