Skip to content

Commit 0b74308

Browse files
committed
docs(middleware): reorganize protocol guides
Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
1 parent 408382a commit 0b74308

8 files changed

Lines changed: 545 additions & 248 deletions

File tree

‎architecture/sandbox-limits.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ Middleware also validates every non-body envelope component. Important examples
7373
include 64 KiB service config, 4 KiB request context, 32 KiB target data, 128
7474
request headers totaling 64 KiB, 64 header mutations, 32 findings per stage,
7575
and 64 metadata entries. The detailed external contract lives in
76-
[Supervisor Middleware](../docs/extensibility/supervisor-middleware.mdx).
76+
[Supervisor Middleware](../docs/extensibility/supervisor-middleware/index.mdx).
7777

7878
The work semaphore bounds aggregate buffered middleware input to approximately
7979
`32 × 4 MiB`, plus bounded envelope and parser overhead. It is a concurrency

‎architecture/sandbox.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -240,7 +240,7 @@ against body-aware L7 policy before later stages or the upstream can observe
240240
them. Requests, results, chain length, execution time, and diagnostics are
241241
bounded; external free-form diagnostic text is not exposed in responses or
242242
security logs. See
243-
[Supervisor Middleware](../docs/extensibility/supervisor-middleware.mdx) for
243+
[Supervisor Middleware](../docs/extensibility/supervisor-middleware/index.mdx) for
244244
configuration and protocol details.
245245

246246
`https://inference.local` is special. It bypasses OPA network policy and is

‎docs/extensibility/supervisor-middleware.mdx‎

Lines changed: 0 additions & 246 deletions
This file was deleted.
Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3+
# SPDX-License-Identifier: Apache-2.0
4+
title: "Configure Supervisor Middleware"
5+
sidebar-title: "Configure Middleware"
6+
description: "Choose, register, and attach supervisor middleware to sandbox traffic."
7+
keywords: "Supervisor Middleware, Configuration, Network Policy, Extension Authentication"
8+
position: 2
9+
---
10+
11+
Configure middleware in two places. Register operator-run services in gateway TOML, then attach built-in or registered middleware to destination hosts in sandbox policy.
12+
13+
## Choose a middleware type
14+
15+
| Type | Registration | Payload limit | Deployment |
16+
| --- | --- | --- | --- |
17+
| Built-in | None. | Defined by OpenShell. | Runs inside the supervisor. |
18+
| Operator-run service | Required in gateway TOML. | Set by the operator, up to the service capability. | Runs as a separate service reachable by the gateway and supervisors. |
19+
20+
`openshell/regex` is an example built-in middleware. It replaces simple, self-contained token patterns in UTF-8 HTTP bodies and client WebSocket text messages. The initial pattern recognizes `sk-` tokens. It does not infer values from fields such as a JSON `password` property, and it does not guarantee that it will detect or remove every sensitive value.
21+
22+
Its `config` accepts `mode: redact`, which is also the default. Policy validation rejects unknown fields and non-string values. Custom expressions are not configurable.
23+
24+
Operator-run services advertise the operation and phase pairs they support. V1 defines `HTTP_REQUEST/PRE_CREDENTIALS`, `HTTP_RESPONSE/PRE_RETURN`, and `WEBSOCKET_MESSAGE/PRE_CREDENTIALS`. A service may advertise any combination.
25+
26+
## Register an operator-run service
27+
28+
Start the service before the gateway, then add its registration to the local gateway TOML:
29+
30+
```toml
31+
[[openshell.supervisor.middleware]]
32+
name = "local-content-guard"
33+
grpc_endpoint = "https://content-guard.example:50051"
34+
tls_ca_cert_path = "/etc/openshell/content-guard-ca.pem"
35+
audience = "urn:example:content-guard"
36+
max_payload_bytes = 262144
37+
timeout = "500ms"
38+
```
39+
40+
| Field | Description |
41+
| --- | --- |
42+
| `name` | Operator-owned name used by policy attachments and diagnostics. Names must be unique. The `openshell/` namespace is reserved for built-ins. |
43+
| `grpc_endpoint` | Service address reachable from the gateway and sandbox supervisors. Authenticated extensions use TLS `https://`. |
44+
| `tls_ca_cert_path` | Optional PEM trust roots for a private HTTPS service. Custom roots replace platform roots and retain hostname verification. |
45+
| `audience` | Exact audience expected by the service. Defaults to `urn:openshell:extension:middleware:<name>`. |
46+
| `allow_insecure_transport` | Allows plaintext `http://` without a bearer credential. Defaults to `false`. Use it only on a network that already authenticates callers. |
47+
| `max_payload_bytes` | Operator ceiling for inspectable logical payloads across all advertised bindings, up to the 4 MiB platform maximum. |
48+
| `timeout` | Optional service-wide RPC timeout from `10ms` through `30s`. Defaults to `500ms`. |
49+
50+
Each binding returned by `Describe` may advertise a shorter timeout. OpenShell uses the smaller of the binding and service values. The service timeout applies to `Describe` and `ValidateConfig`. The effective binding timeout applies to request evaluation, response preflight and unit results, WebSocket preflight, and each WebSocket message. Response and WebSocket streams have no connection-wide deadline.
51+
52+
The gateway calls `Describe` and validates every registration before it accepts traffic. Startup fails if a service is unavailable, returns an invalid capability, or exposes duplicate bindings for one operation and phase. The manifest `name` is diagnostic metadata and does not need to match the operator registration name.
53+
54+
Registration is static. Restart the gateway after you add, remove, or change a service. See [Gateway Configuration](/reference/gateway-config#supervisor-middleware-services) for the full TOML context.
55+
56+
## Authenticate OpenShell callers
57+
58+
When gateway JWT signing is configured, OpenShell attaches a short-lived EdDSA bearer token to every remote middleware RPC. Gateway calls use `caller_kind: gateway`. Sandbox supervisor calls use `caller_kind: supervisor` and include the sandbox ID. Supervisors request credentials by registration name through `RefreshSandboxToken`; the gateway authorizes that name against the sandbox's effective policy.
59+
60+
Return the expected audience in the `expected_audience` field of the `Describe` manifest. After authentication succeeds, OpenShell compares this field with the operator-configured audience and refuses to start on a mismatch. A strict service may reject the token before returning its manifest, in which case startup reports an authentication failure. Leave the field empty to skip the consistency check.
61+
62+
Provision the trusted gateway URL, expected gateway ID, and public key or JWKS with the service. The expected issuer is exactly `openshell-gateway:<gateway_id>`. After initial trust is established, `GET /.well-known/openid-configuration` and its `jwks_uri` provide key refresh. This document is OIDC-shaped, but its `issuer` is the gateway identity rather than the URL that serves the document. Compare `iss` with the configured value and fetch updates only over authenticated TLS from the trusted gateway URL.
63+
64+
Cache keys by `kid` and validate:
65+
66+
- `typ` is exactly `openshell-ext+jwt`.
67+
- `alg` is pinned to `EdDSA` rather than selected from the token.
68+
- The signature, expected issuer, exact audience, and positive expiry.
69+
- `caller_kind`, plus the sandbox identity when the service scopes behavior per sandbox.
70+
71+
Extension tokens and sandbox-to-gateway bootstrap tokens use the same signing key but have different audiences and `typ` values. Each extension token also carries a `jti`. OpenShell reuses a token until rotation and does not track `jti`, so do not reject a repeated value as a replay. Per-request replay resistance requires proof of possession or request binding.
72+
73+
Set `allow_insecure_transport = true` only when the surrounding network authenticates callers. OpenShell then sends no credential to the service, and the gateway refuses to mint one if asked. The gateway logs a warning for the registration at every startup.
74+
75+
## Attach middleware in policy
76+
77+
Add configurations to the top-level `network_middlewares` map. Each map key is a stable policy-local identity:
78+
79+
```yaml
80+
network_middlewares:
81+
regex-redactor:
82+
name: Redact API tokens
83+
middleware: openshell/regex
84+
order: 10
85+
config:
86+
mode: redact
87+
on_error: fail_closed
88+
endpoints:
89+
include: ["*.example.com"]
90+
exclude: ["trusted.example.com"]
91+
```
92+
93+
The optional `name` defaults to the map key. `middleware` names a built-in or operator-run registration. A policy accepts at most 10 configurations.
94+
95+
`include` selects destination hosts. `exclude` takes precedence. Each configuration accepts at most 32 combined patterns. Matching is case-insensitive and uses the same exact-host and DNS glob behavior as network policy endpoints. `*` matches one DNS label, `**` matches one or more labels, and an intra-label pattern such as `*-api.example.com` works. Policy validation rejects brace alternates such as `{prod,staging}`.
96+
97+
Matching configurations run once each by ascending `order`. Order values must be unique across the complete policy, even when selectors do not overlap. The default is `0`, so set explicit values when a policy has multiple configurations.
98+
99+
See [Policy Schema](/reference/policy-schema#network-middleware) for the complete field reference.
100+
101+
## Choose failure behavior
102+
103+
`on_error` applies after OpenShell selects a supported binding and that stage fails. Failures include an unavailable service, rejected configuration, invalid result, timeout, or payload over the stage limit.
104+
105+
| Value | Request behavior | Response behavior | WebSocket behavior |
106+
| --- | --- | --- | --- |
107+
| `fail_closed` | Denies the request. This is the default. | Returns `502 response_delivery_failed` before commitment or aborts delivery after commitment. | Rejects the upgrade or closes the connection. |
108+
| `fail_open` | Skips the failed stage. | Disables the stage and continues with the retained input. | Disables a broken stage for the rest of the connection and continues the remaining chain. |
109+
110+
A valid upstream response can still exceed middleware envelope limits or contain header bytes that the middleware protocol cannot represent. OpenShell relays the original response when every selected response stage uses `fail_open`. Any selected `fail_closed` stage causes the canonical `502` delivery failure. Malformed or unsafe HTTP does not qualify for this bypass.
111+
112+
An unsupported binding or message class is a coverage gap, not a middleware failure. `on_error` does not make an HTTP-only service inspect WebSocket messages, and it does not make V1 inspect binary messages.
113+
114+
Use `fail_open` only when bypassing the stage preserves the intended security policy. OpenShell emits a detection finding for a bypass and a separate state-change finding when it disables a WebSocket stage.
115+
116+
An explicit deny result always stops the chain, regardless of `on_error`. Middleware decisions also remain enforced when the endpoint uses `enforcement: audit`. To observe traffic without blocking it, return an allow decision with findings.
117+
118+
Continue with the [HTTP request guide](/extensibility/supervisor-middleware/http) or [WebSocket session guide](/extensibility/supervisor-middleware/websocket) for protocol-specific results and limits.
119+
120+
## Run the content guard example
121+
122+
The [content guard example](https://github.com/NVIDIA/OpenShell/tree/main/examples/supervisor-middleware-content-guard) implements request, response, and WebSocket bindings in one service. It matches configured literal terms in UTF-8 request bodies, complete response bodies, and client WebSocket text messages. It supports redaction and denial but is not a general PII detector.
123+
124+
The example includes a policy, local fixture, and smoke launcher.

0 commit comments

Comments
 (0)