> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Fetch Metadata

> Security-Middleware auf Basis der Sec-Fetch-*-Header, die Laravel-Anwendungen vor CSRF-Angriffen und Cross-Site-Requests schützt.

## Überblick

[revolution/laravel-fetch-metadata](https://github.com/invokable/laravel-fetch-metadata) ist ein Middleware-Paket, das die vom Browser gesendeten `Sec-Fetch-*`-HTTP-Header überprüft. Sie können damit anhand von Ursprung, Modus, Ziel und ob die Anfrage durch eine Nutzeraktion ausgelöst wurde, steuern, welche Requests zugelassen werden.

Indem Sie die im Browser eingebauten Sicherheitsfunktionen nutzen, verhindern Sie bösartige Requests von unerlaubten Ursprüngen, ohne die Nutzererfahrung legitimer Anwender zu beeinträchtigen.

<Info>
  In Laravel 13 wird für die Origin-Prüfung des CSRF-Schutzes nun der Header `Sec-Fetch-Site` verwendet. Details siehe [CSRF-Schutz](/de/csrf).
</Info>

Ausführliche Informationen zur Spezifikation von Fetch Metadata finden Sie in der [MDN-Dokumentation](https://developer.mozilla.org/de/docs/Glossary/Fetch_metadata_request_header).

## Installation

```bash theme={null}
composer require revolution/laravel-fetch-metadata
```

### Middleware-Alias registrieren

Registrieren Sie in `bootstrap/app.php` die Aliase der Middleware.

```php theme={null}
use Illuminate\Foundation\Configuration\Middleware;
use Revolution\FetchMetadata\Middleware\SecFetchSite;
use Revolution\FetchMetadata\Middleware\SecFetchMode;
use Revolution\FetchMetadata\Middleware\SecFetchDest;
use Revolution\FetchMetadata\Middleware\SecFetchUser;

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'sec-fetch-site' => SecFetchSite::class,
        'sec-fetch-mode' => SecFetchMode::class,
        'sec-fetch-dest' => SecFetchDest::class,
        'sec-fetch-user' => SecFetchUser::class,
    ]);
})
```

Sie können auch nur einige Middlewares verwenden. Die Alias-Namen können Sie beliebig anpassen.

## Erläuterung der Middlewares

### SecFetchSite

Der Header `Sec-Fetch-Site` gibt die Beziehung zwischen Herkunft der Anfrage und Ziel-Origin an. Standardmäßig werden nur `same-origin` und `none` (direkter Zugriff) erlaubt.

| Wert          | Beschreibung                                                               |
| ------------- | -------------------------------------------------------------------------- |
| `same-origin` | Request vom selben Origin                                                  |
| `same-site`   | Request von derselben Site (z. B. Subdomains)                              |
| `cross-site`  | Request von einer anderen Site                                             |
| `none`        | Navigationsbezogene Requests, z. B. wenn der Nutzer die URL direkt eingibt |

Details siehe [MDN-Dokumentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Site).

### SecFetchMode

Der Header `Sec-Fetch-Mode` gibt den Modus der Anfrage an. Standardmäßig werden `navigate` und `cors` erlaubt.

| Wert          | Beschreibung                                                      |
| ------------- | ----------------------------------------------------------------- |
| `navigate`    | Navigations-Requests, z. B. Klick auf Links oder Formularabsenden |
| `cors`        | CORS-Request                                                      |
| `no-cors`     | no-cors-Request                                                   |
| `same-origin` | Same-origin-Request                                               |
| `websocket`   | Anfrage zur WebSocket-Verbindung                                  |

Details siehe [MDN-Dokumentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Mode).

### SecFetchDest

Der Header `Sec-Fetch-Dest` gibt den Ressourcentyp des Anfrageziels an.

Details siehe [MDN-Dokumentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Dest).

### SecFetchUser

Der Header `Sec-Fetch-User` gibt an, ob die Anfrage durch eine Nutzeraktion ausgelöst wurde. Der einzige Wert ist `?1` (Nutzeraktion vorhanden).

<Warning>
  Wenn Sie die `SecFetchUser`-Middleware einsetzen, werden auch Suchmaschinen-Crawler und AI-Agents blockiert. Setzen Sie sie nicht auf öffentlichen Seiten ein, die indexiert werden sollen.
</Warning>

## Anwendungsbeispiele im Routing

### Grundlegende Verwendung

```php theme={null}
use Illuminate\Support\Facades\Route;
use Illuminate\Http\Request;

Route::post('user/update-password', function (Request $request) {
    //
})->middleware('sec-fetch-site');
```

### Erlaubte Werte per Parameter festlegen

```php theme={null}
Route::post('user/update-password', function (Request $request) {
    //
})->middleware('sec-fetch-site:cross-site');
```

### Mehrere Parameter angeben

```php theme={null}
Route::post('user/update-password', function (Request $request) {
    //
})->middleware('sec-fetch-site:same-origin,cross-site');
```

### Ohne Alias

```php theme={null}
use Revolution\FetchMetadata\Middleware\SecFetchSite;

Route::post('user/update-password', function (Request $request) {
    //
})->middleware(SecFetchSite::class.':same-origin,cross-site');
```

### Mehrere Middlewares kombinieren

```php theme={null}
Route::post('user/update-profile', function (Request $request) {
    //
})->middleware(['sec-fetch-site:same-origin', 'sec-fetch-mode:navigate']);
```

## Fehlerbehandlung

Wenn der Wert eines `Sec-Fetch-*`-Headers ungültig ist, wird eine `Symfony\Component\HttpKernel\Exception\BadRequestHttpException` geworfen.

In `bootstrap/app.php` können Sie die Antwort anpassen.

```php theme={null}
use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (BadRequestHttpException $e, Request $request) {
        if ($request->expectsJson()) {
            return response()->json([
                'message' => $e->getMessage(),
            ], 400);
        }
    });
})
```

## Zusammenhang mit dem CSRF-Schutz

In Laravel 13 nimmt die Middleware `PreventRequestForgery` als ersten Schritt des CSRF-Schutzes eine Origin-Prüfung mit dem Header `Sec-Fetch-Site` vor. Dieses Paket nutzt Fetch-Metadata-Header darüber hinaus feingranular und stärkt die Sicherheit Ihrer Anwendung.

Details siehe [CSRF-Schutz](/de/csrf).

<Info>
  Aktuelle Informationen finden Sie im [GitHub-Repository](https://github.com/invokable/laravel-fetch-metadata).
</Info>


## Related topics

- [Upgrade-Anleitung von Laravel 12 auf 13](/de/blog/upgrade-12-to-13.md)
- [Socialite - Laravel Bluesky](/de/packages/laravel-bluesky/socialite.md)
- [Session-Kontext und Filterung](/de/packages/laravel-copilot-sdk/session-context.md)
- [Laravel MCP](/de/mcp.md)
- [CSRF-Schutz](/de/csrf.md)