Validierung an API-Grenzen durchsetzen: Trust Boundary Pattern

1. Das Trust-Boundary-Konzept: Wo Vertrauen endet

Eine Trust Boundary ist die Stelle in einer Architektur, an der Daten von einem Bereich mit geringerem Vertrauen in einen Bereich mit höherem Vertrauen wechseln, etwa vom öffentlichen Internet in die Kernlogik eines Backends. Alles, was jenseits dieser Grenze liegt, muss als potenziell fehlerhaft, manipuliert oder schlicht falsch strukturiert behandelt werden, unabhängig davon, wie vertrauenswürdig ein Client im Normalfall erscheint.

Das Trust-Boundary-Pattern für TypeScript-APIs übersetzt dieses Sicherheitskonzept in eine konkrete Architekturregel: Validierung geschieht ausschließlich an der Grenze, direkt bevor Daten ins Innere der Anwendung eintreten, nie verstreut über mehrere Schichten hinweg. Sobald ein Wert diese Grenze einmal validiert passiert hat, kann sich der restliche Code auf den geprüften TypeScript-Typ verlassen, ohne an jeder weiteren Stelle erneut zu misstrauen.

2. Warum ein Request-Body niemals als typisiert gelten darf

In vielen Express- oder Fastify-Projekten wird ein Request-Body mit einem generischen Typparameter wie Request<{}, {}, CreateOrderDto> versehen, obwohl req.body zur Laufzeit tatsächlich any ist, ein reines Framework-Versprechen ohne jede Prüfung. Diese Typannotation beschreibt lediglich, was der Entwickler erwartet, nicht was tatsächlich ankommt, ein Unterschied, der bei einem fehlerhaften Client, einem alten API-Consumer oder einem manipulierten Request sofort sichtbar wird.

Der korrekte Ausgangspunkt an jeder API-Grenze ist deshalb, den Request-Body explizit als unknown zu behandeln, bis eine echte Laufzeit-Validierung stattgefunden hat. Dieser eine gedankliche Schritt, Rohdaten grundsätzlich als unbekannt zu betrachten statt als bereits typisiert, ist die Grundvoraussetzung für ein funktionierendes Trust-Boundary-Pattern und verhindert die verbreitete Praxis, Typsicherheit durch bloße Behauptung statt durch Prüfung herzustellen.

3. Eine Validierungs-Middleware für alle Routen bauen

Statt Validierung in jedem einzelnen Route-Handler zu wiederholen, bündelt eine generische Middleware die Prüfung an einer zentralen Stelle, durch die jede Route läuft, bevor die eigentliche Handler-Logik erreicht wird. Diese Middleware nimmt ein Zod-Schema als Parameter entgegen, validiert req.body dagegen und beendet die Anfrage bei einem Fehler bereits an der Grenze, mit einer strukturierten 400er-Antwort statt eines unklaren Fehlers tief in der Geschäftslogik.

Dieses Muster macht Validierung zu einer deklarativen Eigenschaft jeder Route, sichtbar direkt in der Routendefinition, statt versteckt irgendwo im Handler-Code. Ein neuer Endpunkt bekommt Validierung quasi automatisch, sobald er dieselbe Middleware mit seinem eigenen Schema registriert, ein konsistentes Muster über die gesamte API hinweg.

import { z, type ZodType } from "zod";
import type { Request, Response, NextFunction, RequestHandler } from "express";

// Generic middleware: validates req.body against any Zod schema
function validateBody<T>(schema: ZodType<T>): RequestHandler {
  return (req: Request, res: Response, next: NextFunction) => {
    const result = schema.safeParse(req.body);

    if (!result.success) {
      res.status(400).json({
        error: "ValidationError",
        issues: result.error.flatten().fieldErrors,
      });
      return;
    }

    // Attach the validated, typed data instead of trusting req.body directly
    (req as Request & { validated: T }).validated = result.data;
    next();
  };
}

const createOrderSchema = z.object({
  customerId: z.string().uuid(),
  items: z.array(
    z.object({ sku: z.string(), quantity: z.number().int().positive() })
  ),
});

// Registered per route: validation is visible right in the route definition
app.post("/orders", validateBody(createOrderSchema), createOrderHandler);

4. Typisierte Handler-Signaturen nach der Validierung

Sobald die Middleware eine Anfrage erfolgreich validiert hat, sollte der eigentliche Handler auf die geprüften, typisierten Daten zugreifen, statt erneut auf req.body. Ein generischer Helfer-Typ, der die Handler-Signatur um den bereits validierten Typ ergänzt, macht diese Garantie im Typsystem sichtbar und verhindert, dass ein Handler versehentlich auf den ungeprüften Rohwert zugreift.

Dieser Schritt schließt den Kreis des Trust-Boundary-Patterns: Die Middleware ist die einzige Stelle, die unknown-Daten sieht, der Handler arbeitet ausschließlich mit einem bereits geprüften, spezifischen Typ. Für den restlichen Code der Anwendung, Service-Klassen, Repository-Aufrufe, Business-Logik, existiert das Problem unvalidierter Eingaben an dieser Stelle schlicht nicht mehr.

import { z } from "zod";
import type { Request, Response } from "express";

const createOrderSchema = z.object({
  customerId: z.string().uuid(),
  items: z.array(
    z.object({ sku: z.string(), quantity: z.number().int().positive() })
  ),
});

type CreateOrderInput = z.infer<typeof createOrderSchema>;

// Typed request: "validated" is guaranteed to exist and match the schema
type ValidatedRequest<T> = Request & { validated: T };

function createOrderHandler(
  req: ValidatedRequest<CreateOrderInput>,
  res: Response
): void {
  // No further validation needed: req.validated is a trusted CreateOrderInput
  const { customerId, items } = req.validated;
  const total = items.reduce((sum, item) => sum + item.quantity, 0);
  res.status(201).json({ customerId, itemCount: items.length, total });
}

5. Query-Parameter, Path-Parameter und Header konsequent einbeziehen

Das Trust-Boundary-Pattern beschränkt sich nicht auf den Request-Body. Query-Parameter kommen immer als Strings an, selbst wenn sie logisch eine Zahl oder ein Boolean repräsentieren, Path-Parameter ebenso, und Header können komplett fehlen oder mehrfach mit unterschiedlichen Werten gesendet werden. Jede dieser Quellen ist eine eigene, unabhängige Grenze zur Außenwelt und verdient ein eigenes Schema, statt stillschweigend als korrekt vorausgesetzt zu werden.

Eine erweiterte Middleware validiert deshalb req.query, req.params und relevante Header jeweils gegen ein eigenes Zod-Schema, mit expliziter Coercion für Zahlen und Booleans über z.coerce.number() beziehungsweise z.coerce.boolean(). Diese Konsequenz verhindert die häufige Lücke, bei der ein Body sorgfältig validiert wird, während eine kritische ID im Pfad ungeprüft direkt an eine Datenbankabfrage weitergereicht wird.

import { z } from "zod";

// Query params always arrive as strings, even for numeric or boolean values
const listOrdersQuerySchema = z.object({
  page: z.coerce.number().int().positive().default(1),
  pageSize: z.coerce.number().int().min(1).max(100).default(20),
  includeArchived: z.coerce.boolean().default(false),
});

// Path params equally need explicit validation, not just a type annotation
const orderParamsSchema = z.object({
  orderId: z.string().uuid(),
});

type ListOrdersQuery = z.infer<typeof listOrdersQuerySchema>;
type OrderParams = z.infer<typeof orderParamsSchema>;

function validateListOrdersRequest(rawQuery: unknown, rawParams: unknown) {
  const query: ListOrdersQuery = listOrdersQuerySchema.parse(rawQuery);
  const params: OrderParams = orderParamsSchema.parse(rawParams);
  return { query, params };
}

6. Strukturierte Fehlerausbreitung statt generischer 500er

Ein häufiger Architekturfehler ist, Validierungsfehler an der Grenze einfach durchzureichen, bis sie irgendwo als generischer 500-Fehler oder als unbehandelte Exception enden. Das Trust-Boundary-Pattern verlangt stattdessen, dass jede Validierungsfehler-Klasse an der Grenze selbst in eine passende HTTP-Antwort übersetzt wird, üblicherweise 400 für strukturell ungültige Eingaben, mit einer konsistenten, maschinenlesbaren Fehlerstruktur.

Diese strukturierte Antwort sollte pro Feld benennen, was genau ungültig war, damit ein aufrufender Client oder ein Frontend-Formular die Fehlermeldung direkt nutzen kann, statt einen kryptischen Stacktrace zu erhalten. Zods error.flatten().fieldErrors liefert genau diese Struktur direkt aus der Box, ohne dass die Anwendung ein eigenes Fehlerformat von Grund auf entwickeln müsste.

7. Interne Service-Grenzen genauso behandeln wie externe

Ein oft übersehener Aspekt des Trust-Boundary-Patterns ist, dass nicht nur die öffentliche API-Grenze zum Client relevant ist, sondern auch interne Grenzen zwischen Microservices, zwischen einem Backend und einer Message-Queue, oder zwischen zwei Modulen mit unterschiedlichen Deploy-Zyklen innerhalb desselben Monolithen. Auch hier gilt: Ein anderer Service kann eine andere Version des Vertrags implementieren, ein Feld weglassen oder unerwartet null statt eines Strings senden.

Wer Validierung nur an der äußersten, öffentlichen Grenze durchsetzt, aber internen Service-zu-Service-Aufrufen blind vertraut, verschiebt das Risiko lediglich, statt es zu beseitigen. Response-Schemas für interne API-Aufrufe, validiert mit demselben Trust-Boundary-Prinzip wie eingehende Requests, decken Versionsinkonsistenzen zwischen Services auf, bevor sie als schwer nachvollziehbarer Laufzeitfehler in der Produktion auffallen.

8. Häufige Fehler bei der Umsetzung von Trust Boundaries

Der häufigste Fehler ist eine Typannotation ohne echte Prüfung, ein Request<{}, {}, CreateOrderDto>, dem niemand eine safeParse()- oder parse()-Aufruf folgen lässt. Der zweite häufige Fehler ist doppelte, aber inkonsistente Validierung, bei der ein Frontend-Formular eigene Regeln prüft und das Backend eigene, nicht identische Regeln, sodass ein Datensatz das Frontend passiert, aber am Backend abgelehnt wird, oder umgekehrt.

Ein dritter, subtilerer Fehler ist, Validierung nur für den Body durchzuführen, aber Query-Parameter, Path-Parameter und Header unvalidiert zu lassen, in der Annahme, sie seien weniger kritisch. Gerade Path-Parameter wie eine orderId landen aber häufig direkt und ungeprüft in einer Datenbankabfrage, was sie zu einem besonders sensiblen Teil der Trust Boundary macht, nicht zu einem nachrangigen.

9. Validierung an der Grenze vs. verstreute Prüfungen im Vergleich

Die folgende Tabelle stellt konsequente Grenzvalidierung verstreuten, ad hoc eingefügten Prüfungen gegenüber, wie sie in gewachsenen Codebasen ohne bewusstes Trust-Boundary-Pattern häufig entstehen.

Ein konsequentes Trust-Boundary-Pattern verwandelt Validierung von einer Ansammlung individueller Entscheidungen in eine architektonische Konstante, die für jede neue Route automatisch gilt.

10. Zusammenfassung

Das Trust-Boundary-Pattern löst ein strukturelles Problem, das eine reine Typannotation niemals lösen kann: Ein Request-Body, ein Query-Parameter oder ein Path-Parameter ist zur Laufzeit immer unknown, unabhängig davon, was der Compiler behauptet. Validierung an API-Grenzen konsequent durchzusetzen bedeutet, diese Prüfung an einer zentralen Middleware zu bündeln, bevor Daten überhaupt in die eigentliche Geschäftslogik eintreten.

Typisierte Handler-Signaturen nach erfolgreicher Validierung machen die Garantie im Typsystem sichtbar, strukturierte Fehlerantworten mit feldbezogenen Details ersetzen generische 500er, und dasselbe Prinzip sollte konsequent auch auf interne Service-zu-Service-Grenzen angewendet werden, nicht nur auf die öffentliche API. Wer diese Grenze einmal sauber zieht, muss dem restlichen Code nie wieder misstrauen.

11. FAQ: Validierung an API-Grenzen durchsetzen