--- title: "Clients verwenden" manual: "HTTP Guard" version: "0.1.4" permalink: "https://docs.typo3.org/permalink/netresearch/nr-http-guard:api@0.1.4" source: "Api/Index.rst" rendered: "2026-10-18T14:31:43+00:00" --- # Clients verwenden {#api} Die öffentlichen Interfaces stehen unter `\Netresearch\HttpGuard` und werden durch TYPO3-Services bereitgestellt. Anwendungen sollen gebundene PSR-18-Clients oder Public Fetch injizieren. Der interne Guzzle-Client und sein Fortschritts-/Abbruchtreiber gehören zusammen und bilden keine zusätzliche öffentliche Credential-API. ## Gewöhnliche Core-Anfragen {#api-core} Der registrierte Core-Pfad erhält die öffentliche Standardpolicy. Bereits vorhandene unterstützte Core-Middleware und Kontextrestriktionen bleiben zusätzlich wirksam. Ein gewöhnlicher Aufruf kann beispielsweise so aussehen: **Öffentlicher Abruf mit TYPO3 RequestFactory** ```php $response = $requestFactory->request( 'https://www.example.org/document.json', 'GET', ['timeout' => 10, 'http_errors' => false], ); ``` `$requestFactory` ist ein injizierter `\TYPO3\CMS\Core\Http\RequestFactory`. Für öffentliche Inhalte aus unvertrauenswürdigen URLs ist [Public Fetch](https://docs.typo3.org/permalink/netresearch/nr-http-guard:api-public-fetch@0.1.4) die engere API. RequestFactory-Anfragen übernehmen durch ein konfiguriertes Endpoint-Profil keine internen Rechte. ## Gebundene Integrationsclients {#api-endpoint} - **class EndpointClientFactoryInterface** - *Fully qualified name:* `\Netresearch\HttpGuard\EndpointClientFactoryInterface` - **forEndpoint(string $configuredEndpointId)** Erzeugt einen Client mit einem konfigurierten Endpoint-Profil. Unbekannte, fremde oder abgelaufene Bindungen werden abgelehnt. Die Profil-ID steht im vertrauenswürdigen Servicecode oder dessen Dependency-Injection-Konfiguration. Sie wird nicht aus der jeweiligen Benutzeranfrage übernommen. Das folgende Beispiel verwendet das Profil aus [Internes Endpoint-Beispiel](https://docs.typo3.org/permalink/netresearch/nr-http-guard:configuration-example@0.1.4): **Classes/Service/ErpClient.php im Sitepackage** ```php client = $factory->forEndpoint('erp-orders'); } public function sendOrder(array $order): ResponseInterface { return $this->client->sendRequest( new Request( 'POST', 'https://erp.internal.example:8443/orders', ['Content-Type' => 'application/json'], json_encode($order, JSON_THROW_ON_ERROR) ) ); } } ``` Der Client prüft Origin, Methode und alle aufgelösten Adressen bei jedem Versand. PSR-18 `sendRequest()` folgt keinem Redirect und gibt auch HTTP-Fehlerantworten wie 404 oder 500 als Response zurück. Netzwerkfehler und Policyablehnungen bleiben Exceptions. Ein Policyfehler darf nicht durch einen ungeschützten Ersatzclient umgangen werden. ## Public Fetch {#api-public-fetch} - **class PublicFetchClientInterface** - *Fully qualified name:* `\Netresearch\HttpGuard\PublicFetchClientInterface` - **fetch(Psr\\Http\\Message\\UriInterface $uri, string $method = 'GET')** Akzeptiert ausschließlich GET oder HEAD und baut einen eigenen öffentlichen Request ohne geerbte Zugangsdaten oder Body auf. Public Fetch übernimmt keine Authentifizierung, Cookies, Clientzertifikate, SSL-Keys, benutzerdefinierte Headers, Bodies oder Query-Defaults eines anderen Clients. Seine feste Headerliste besteht aus `Accept`, `Accept-Encoding` und `User-Agent`. Die Query einer zulässigen Ziel-URI bleibt Bestandteil dieser URI; sie wird nicht geloggt. Erlaubte öffentliche Redirects können eine andere Origin erreichen, ohne dass Geheimnisse eines ursprünglichen Integrationsrequests mitwandern. **Roh-URL vor Erstellung eines PSR-7-Objekts prüfen** ```php assertRawUri($rawUrl); return $this->client->fetch(new Uri($rawUrl)); } } ``` Für einen Benutzerabruf wird keine Endpoint-ID akzeptiert. Private Ziele bleiben auch dann gesperrt, wenn das Projekt ein gleichnamiges internes Endpoint-Profil besitzt. ## Roh-URLs und PSR-7 {#api-raw-uri} `TargetNormalizer::assertRawUri(string $uri)` prüft verbotene Syntax, solange die unveränderte Zeichenkette vorhanden ist. Fragmente einschließlich eines leeren `#`, Backslashes, Steuerzeichen und ungültige rohe Schreibweisen sind vor der URI-Erstellung abzulehnen. Ein PSR-7-URI-Objekt kann ein leeres Fragmentkennzeichen bereits verworfen oder Eingaben kodiert haben. Ein späterer PSR-18-Client kann diese Information nicht rekonstruieren. Deshalb prüft der TYPO3-RequestFactory-Adapter rohe Strings vor Guzzle. Eigene PSR-18-Anwendungen prüfen die ursprüngliche URL selbst, wie im Public-Fetch-Beispiel. Diese Grenze gilt auch für rohe Vault-Resource-URLs vor Erstellung eines RequestInterface-Objekts. ## Policyfehler behandeln {#api-errors} `PolicyException` implementiert `OutboundPolicyExceptionInterface`. Die Methode `reasonCode()` liefert einen stabilen Code aus [Ablehnungsgründe verstehen](https://docs.typo3.org/permalink/netresearch/nr-http-guard:operations-reasons@0.1.4). Exceptiontexte enthalten keine URL, Zugangsdaten oder Request-Bodies. Anwendungen können den Code für eine verständliche Fehlermeldung verwenden; Geheimnisse oder vollständige Requests gehören nicht in einen ergänzenden Fehlerlog. ## SDK-Optionen und Streaming {#api-sdk-options} Im kontrollierten RequestFactory-/SDK-Pfad bleiben reguläre Request-Bodies, Headers und unterstützte Authentifizierung wirksam. `timeout` und `connect_timeout` akzeptieren endliche nicht negative Zahlen, einschließlich null. `verify` akzeptiert Boolean oder ein lesbares CA-Bundle, unter Beachtung der TLS-Policy. Lesbare Clientzertifikate und SSL-Keys ermöglichen mTLS. `sink` kann in einen Dateipfad, eine Resource oder einen PSR-7-Stream schreiben, ohne eine zweite eigene Responsekopie im Guard anzulegen. Unterstützte Callbacks wie `on_headers`, `on_stats` und `progress` bleiben erhalten; ihre Exceptions beenden den zugehörigen Transfer. HTTP 1.0, 1.1 und 2 sind qualifiziert, HTTP/3 nicht. Die entsprechende IP-Familienoption kann ausschließlich `v4` oder `v6` wählen und erweitert keine Adressfreigabe. Rohe `curl`-/cURL-multi-Optionen, `stream_context`, Unix-Sockets, Proxy-Routen, eigene Handler, Transport-Sharing, verzögerter Transportversand, Debug-Dumps, unbekannte Optionen und `stream=true` werden im geschützten Pfad abgelehnt. Eine Response-Sink-Datei ist kein alternativer Stream-HTTP-Handler. Guzzle-intern erzeugte und quellgeprüfte Digest-/NTLM-Steuerung unter Guzzle 7 ist von beliebigen rohen cURL-Optionen unterschieden. Abbruch und inkrementelles Streaming benötigen einen Adapter, der den zugehörigen internen Fortschrittstreiber verwendet. Der aufgezeichnete nr-vault-Referenzadapter tut dies für seine bestehenden APIs; ein beliebiger zurückgegebener Guzzle-Client allein garantiert diese Lebensdauerbindung nicht. ## Optionale nr-vault-Migration {#api-vault} Die Extension liest keine Vault-Secrets und übernimmt Vault nicht automatisch. Der historische Referenzpatch ist für seinen aufgezeichneten nr-vault-Quellstand vorgesehen und benötigt eine bewusste Projektintegration. Resource- und OAuth-Token-Origin benötigen eigene gebundene Clients und gegebenenfalls eigene Profile. Eine private Token-Origin erbt weder eine öffentliche Resource-Freigabe noch umgekehrt. Secret-Abruf, Audit, Maskierung, Größenlimits und Vaults bestehende Cancel-/Streaming-Semantik bleiben Aufgaben des Vault-Adapters. Dessen konkrete [Referenzmigration samt Nachweisen](https://github.com/netresearch/typo3_http_guard/blob/3f929ae8794ca04ab3dd25627e94d601a2db23e0/integrations/nr-vault/EVIDENCE.md) bleibt an diesen historischen Stand gebunden. Die Extension liefert kein Vault-Overlay und übernimmt weder Deployment noch eine neue vollständige Vault-Prüfung. Der reguläre TYPO3-RequestFactory-Schutz benötigt keine Vault-Migration.