feat(middleware): define the HTTP hooks API contract

docs/extensibility/supervisor-middleware/configure.mdx

@@ -96,12 +96,12 @@ network_middlewares:
 </Tab>
 <Tab title="Multiple middleware">
 
-Run two middleware for the same hosts. `regex-demo` runs before `content-guard` because it has the lower `order`, and neither runs for `trusted.example.com`:
+Run two registered services for the same hosts. `secret-scanner` runs before `content-guard` because it has the lower `order`, and neither runs for `trusted.example.com`:
 
 ```yaml showLineNumbers={false}
 network_middlewares:
-  regex-demo:
-    middleware: openshell/regex
+  secret-scanner:
+    middleware: secret-scanner
     order: 10
     endpoints:
       include: ["*.example.com"]
@@ -146,7 +146,7 @@ The map key, such as `content-guard`, is the entry's stable identity in logs. Ea
 </ParamField>
 
 <ParamField path="endpoints.include" type="string[]" required={true}>
-  Destination hosts to run the middleware for. Uses the same host patterns as network policy endpoints.
+  Destination hosts to run the middleware for. Uses the same host patterns as network policy endpoints. A pattern matches a host on every port and cannot include a port. An IPv6 host must be a complete address without brackets, such as `2001:db8::1`.
 </ParamField>
 
 <ParamField path="endpoints.exclude" type="string[]">
@@ -158,7 +158,7 @@ The map key, such as `content-guard`, is the entry's stable identity in logs. Ea
 </ParamField>
 
 <ParamField path="on_error" type="'fail_closed' | 'fail_open'" default="fail_closed">
-  What happens when the middleware fails. Refer to [Choose Failure Behavior](#choose-failure-behavior).
+  What happens when the middleware fails. Refer to [Choose Failure Behavior](#choose-failure-behavior). Services that use HTTP hooks accept only `fail_closed`.
 </ParamField>
 
 <ParamField path="config" type="object">
@@ -171,6 +171,10 @@ The map key, such as `content-guard`, is the entry's stable identity in logs. Ea
 
 [Policy Schema](/how-it-works/policies/schema#network-middleware) lists every field and limit.
 
+### Mix HTTP Hook Versions
+
+Each HTTP request or response runs through middleware of one [HTTP hook version](/extensibility/supervisor-middleware/operations#http). The gateway rejects a policy in which two entries whose endpoint selectors may overlap use different HTTP hook versions for the same operation, requests or responses. To fix it, separate the selectors or move both services to the same hook version. If a chain still mixes hook versions at runtime, OpenShell blocks the traffic with the reason `middleware_hook_versions_mixed`.
+
 ## Choose Failure Behavior
 
 Middleware fails when it cannot complete its check, for example when its service is unavailable, times out, returns an invalid result, or receives a payload over its limit. By default, OpenShell blocks the affected request, response, or WebSocket connection. The `on_error` field on a policy entry controls this behavior.
@@ -181,6 +185,8 @@ Middleware fails when it cannot complete its check, for example when its service
 
 </Warning>
 
+Middleware that uses HTTP hooks always fails closed. The gateway rejects `fail_open` on an entry whose service uses HTTP hooks, including a service that also inspects WebSocket messages. A policy stored before the service moved to HTTP hooks still loads, and supervisors block its HTTP traffic on failure and log a warning.
+
 A denial from middleware always blocks traffic, regardless of `on_error`. Middleware decisions also stay enforced when the endpoint uses `enforcement: audit`. To observe traffic without blocking it, have your middleware allow the traffic and report findings.
 
 `on_error` does not extend what middleware can inspect. The [current limitations](/extensibility/supervisor-middleware#current-limitations) apply under both settings. With the default behavior, an entry cannot select a `tls: skip` endpoint, because OpenShell cannot inspect that traffic.

docs/extensibility/supervisor-middleware/index.mdx

@@ -47,13 +47,13 @@ OpenShell checks network policy first, so middleware only sees traffic that poli
 
 Each middleware decides whether to allow, deny, or change the traffic. A denial blocks the request even when network policy allows it. If middleware fails or its service is unavailable, OpenShell blocks the affected traffic by default.
 
-Middleware can handle three operations: HTTP requests, HTTP responses, and the text messages an agent sends over a WebSocket connection. Each middleware declares which operations it supports. [Supported Operations](/extensibility/supervisor-middleware/operations) describes each one.
+Middleware can handle three operations: HTTP requests, HTTP responses, and the text messages an agent sends over a WebSocket connection. Each middleware declares which operations it supports. [Supported Operations](/extensibility/supervisor-middleware/operations) describes each one. HTTP middleware uses the HTTP hooks or the legacy HTTP hooks. The [HTTP hooks](/extensibility/supervisor-middleware/operations#http) stream request and response bodies of any size and always fail closed. The legacy HTTP hooks are deprecated for removal in 0.2.0.
 
 ## Current Limitations
 
 - Middleware does not inspect WebSocket binary messages or messages that the external service sends to the agent.
 - Response middleware cannot inspect the body of compressed, partial, or `Cache-Control: no-transform` responses.
-- Middleware cannot inspect traffic to endpoints that use `tls: skip`.
+- Middleware cannot inspect traffic to endpoints that use `tls: skip`, h2c, unsupported tunnels, raw TCP, or SQL passthrough. OpenShell [refuses or allows](/extensibility/supervisor-middleware/operations#uninspectable-traffic) such connections according to `on_error`.
 
 If your deployment requires inspection of this traffic, middleware cannot enforce that requirement today.
 
@@ -85,7 +85,7 @@ Every middleware service implements these RPCs:
 - `Describe` returns the service manifest. The manifest lists the operations the service supports, with a payload limit and optional timeout for each. It also carries [protocol negotiation](/extensibility/overview#protocol-negotiation) metadata and the [expected audience](/extensibility/overview#confirm-the-audience-at-startup).
 - `ValidateConfig` checks the `config` object from a policy entry. The gateway calls it before it accepts a policy.
 
-The service then implements an evaluation RPC for each operation it supports, as described in [Supported Operations](/extensibility/supervisor-middleware/operations).
+The service then implements an evaluation RPC for each operation it supports, as described in [Supported Operations](/extensibility/supervisor-middleware/operations). New HTTP middleware should implement [HTTP Hooks](/extensibility/supervisor-middleware/operations#http).
 
 Most gRPC servers reject incoming messages larger than 4 MiB by default. Raise your server's limit to at least 4.5 MiB so that a maximum-size payload and the rest of the message fit.