You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a3ed8c7
Browse filesBrowse the repository at this point in the historyBrowse files
docs: refresh architecture and extensibility pages (#3741)
* docs(readme): show Rust SDK installation command
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
* docs(architecture): lead with policy enforcement
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
* docs(architecture): reuse README how it works text
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
* docs(architecture): refresh architecture page and diagrams
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
* docs(extensibility): simplify extension points diagram and overview
Redraw the extension points diagram as two left-to-right rows for the
data plane and control plane, describe which layers each extension point
extends, and move authentication after Building Extensions as
Authenticating Extensions with updated cross-page links.
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
---------
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Copy file name to clipboardExpand all lines: docs/extensibility/gateway-interceptors.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -97,7 +97,7 @@ phases = ["validate"]
97
97
98
98
The gateway supports `http://`, `https://`, and `unix://` interceptor endpoints. When gateway JWT signing is configured, authenticated network interceptors use `https://`; Unix sockets remain available for local integrations. HTTPS uses platform trust roots unless `tls_ca_cert_path` supplies a private CA, and normal hostname verification remains enabled. The gateway calls `Describe` and builds an immutable execution plan during startup. An unavailable service, invalid manifest, missing credential, or unauthorized configured binding prevents the gateway from starting.
99
99
100
-
When gateway JWT signing is configured, the gateway authenticates every call to the interceptor with a short-lived token. [Extension Authentication](/extensibility/overview#authentication) describes how your service validates it. Set `allow_insecure_transport = true` to use a plaintext `http://` endpoint without authentication, for local development or on a network that already authenticates callers.
100
+
When gateway JWT signing is configured, the gateway authenticates every call to the interceptor with a short-lived token. [Authenticating Extensions](/extensibility/overview#authenticating-extensions) describes how your service validates it. Set `allow_insecure_transport = true` to use a plaintext `http://` endpoint without authentication, for local development or on a network that already authenticates callers.
101
101
102
102
Registration is static. Restart the gateway after adding, removing, or changing an interceptor. See [Gateway Configuration](/how-it-works/gateways/configuration#gateway-interceptors) for the complete field reference.
11
+
12
12
13
13
Extensibility sits at the core of OpenShell. OpenShell is designed to run
14
14
everywhere and adapt to the infrastructure, governance, and workload
15
15
requirements of each deployment. Its extension points add deployment-specific
16
16
behavior while preserving the same API, policy model, and security boundaries.
17
17
18
+
You can extend each layer of OpenShell:
19
+
20
+
-**Control plane:** Gateway interceptors govern API operations.
21
+
-**Data plane:** Middleware processes agent traffic, and isolation backends
22
+
control the sandboxed workload.
23
+
-**Infrastructure:** Drivers connect OpenShell to compute runtimes and secret
@@ -42,46 +50,6 @@ Isolation backends connect the supervisor to the sandbox runtime. They provide
42
50
a consistent contract for process launch, terminal streams, signals, status,
43
51
and runtime-specific isolation inside the provisioned workload.
44
52
45
-
## Authentication
46
-
47
-
When the gateway has JWT signing configured, OpenShell sends a short-lived bearer token with every call to a [gateway interceptor](/extensibility/gateway-interceptors) or [supervisor middleware](/extensibility/supervisor-middleware) service. Validate it to confirm the call comes from your gateway or one of its sandboxes.
48
-
49
-
| Claim | Value |
50
-
|---|---|
51
-
|`iss`|`openshell-gateway:<gateway_id>`|
52
-
|`aud`| The registration's `audience`. Defaults to `urn:openshell:extension:interceptor:<name>` or `urn:openshell:extension:middleware:<name>`. |
53
-
|`caller_kind`|`gateway`, or `supervisor` for middleware calls from a sandbox. |
54
-
|`sandbox_id`| The calling sandbox, when `caller_kind` is `supervisor`. |
55
-
56
-
### Validate Each Token
57
-
58
-
Get the gateway ID and public signing key (or JWKS) from the gateway operator and configure them in your service. Don't trust a key discovered from an unverified source. To pick up rotated keys, fetch `/.well-known/openid-configuration` from the gateway over TLS and follow its `jwks_uri`.
59
-
60
-
For each request, check that:
61
-
62
-
-`typ` is `openshell-ext+jwt` and `alg` is `EdDSA`. Pin the algorithm; don't read it from the token.
63
-
- The signature, expiry, and exact audience are valid.
64
-
-`iss` is `openshell-gateway:<gateway_id>`, not the gateway URL.
65
-
-`caller_kind` and `sandbox_id` match what your service accepts.
66
-
67
-
OpenShell reuses a token until it rotates, so don't reject a repeated `jti`.
68
-
69
-
Services must use `https://` endpoints. OpenShell verifies the certificate and hostname against platform roots, or against `tls_ca_cert_path` for a private CA.
70
-
71
-
### Confirm the Audience at Startup
72
-
73
-
Return your expected audience in the `expected_audience` field of your `Describe` manifest. The gateway refuses to start if it doesn't match the configured `audience`. Leave it empty to skip the check.
74
-
75
-
### Run Without Authentication
76
-
77
-
Set `allow_insecure_transport = true` on a registration to use a plaintext `http://` endpoint with no token. Your service then can't tell OpenShell apart from any other client, and the gateway logs a warning at every startup. Use this only for local development or on a network that already authenticates callers.
78
-
79
-
### Current Limitations
80
-
81
-
- Tokens are bearer credentials: a captured token works until it expires.
82
-
- Extension tokens share the gateway's signing key, so you can't rotate or revoke them separately.
83
-
- mTLS client authentication and overlapping key rotation aren't available.
84
-
85
53
## Building Extensions
86
54
87
55
Start with the narrowest extension point that owns the behavior you need. Keep
@@ -112,7 +80,7 @@ Use Unix domain sockets when the gateway and extension share a host. Use
112
80
`https://` when a service crosses a host or pod boundary. Plaintext `http://`
113
81
is intended for explicitly enabled development deployments; authenticated
114
82
network extensions use TLS and short-lived gateway-issued credentials. Refer
115
-
to [Authentication](#authentication) for how services validate those credentials.
83
+
to [Authenticating Extensions](#authenticating-extensions) for how services validate those credentials.
116
84
117
85
The [governance interceptor example](https://github.com/NVIDIA/OpenShell/tree/main/examples/governance-interceptor)
118
86
and [content guard middleware example](https://github.com/NVIDIA/OpenShell/tree/main/examples/supervisor-middleware-content-guard)
@@ -137,3 +105,43 @@ extensions follow the same compatibility checks.
137
105
Use `openshell gateway info` to inspect the negotiated extension families,
138
106
implementation versions, protocol versions, and capabilities active on a
139
107
gateway.
108
+
109
+
## Authenticating Extensions
110
+
111
+
When the gateway has JWT signing configured, OpenShell sends a short-lived bearer token with every call to a [gateway interceptor](/extensibility/gateway-interceptors) or [supervisor middleware](/extensibility/supervisor-middleware) service. Validate it to confirm the call comes from your gateway or one of its sandboxes.
112
+
113
+
| Claim | Value |
114
+
|---|---|
115
+
|`iss`|`openshell-gateway:<gateway_id>`|
116
+
|`aud`| The registration's `audience`. Defaults to `urn:openshell:extension:interceptor:<name>` or `urn:openshell:extension:middleware:<name>`. |
117
+
|`caller_kind`|`gateway`, or `supervisor` for middleware calls from a sandbox. |
118
+
|`sandbox_id`| The calling sandbox, when `caller_kind` is `supervisor`. |
119
+
120
+
### Validate Each Token
121
+
122
+
Get the gateway ID and public signing key (or JWKS) from the gateway operator and configure them in your service. Don't trust a key discovered from an unverified source. To pick up rotated keys, fetch `/.well-known/openid-configuration` from the gateway over TLS and follow its `jwks_uri`.
123
+
124
+
For each request, check that:
125
+
126
+
-`typ` is `openshell-ext+jwt` and `alg` is `EdDSA`. Pin the algorithm; don't read it from the token.
127
+
- The signature, expiry, and exact audience are valid.
128
+
-`iss` is `openshell-gateway:<gateway_id>`, not the gateway URL.
129
+
-`caller_kind` and `sandbox_id` match what your service accepts.
130
+
131
+
OpenShell reuses a token until it rotates, so don't reject a repeated `jti`.
132
+
133
+
Services must use `https://` endpoints. OpenShell verifies the certificate and hostname against platform roots, or against `tls_ca_cert_path` for a private CA.
134
+
135
+
### Confirm the Audience at Startup
136
+
137
+
Return your expected audience in the `expected_audience` field of your `Describe` manifest. The gateway refuses to start if it doesn't match the configured `audience`. Leave it empty to skip the check.
138
+
139
+
### Run Without Authentication
140
+
141
+
Set `allow_insecure_transport = true` on a registration to use a plaintext `http://` endpoint with no token. Your service then can't tell OpenShell apart from any other client, and the gateway logs a warning at every startup. Use this only for local development or on a network that already authenticates callers.
142
+
143
+
### Current Limitations
144
+
145
+
- Tokens are bearer credentials: a captured token works until it expires.
146
+
- Extension tokens share the gateway's signing key, so you can't rotate or revoke them separately.
147
+
- mTLS client authentication and overlapping key rotation aren't available.
At startup, the gateway contacts every registered service to read its capabilities and verify [protocol compatibility](/extensibility/overview#protocol-negotiation). The gateway does not start if a service is unavailable or incompatible. [Gateway Configuration](/how-it-works/gateways/configuration#supervisor-middleware-services) describes the full TOML context.
64
64
65
-
When the gateway has JWT signing configured, OpenShell authenticates every call to your service with a short-lived token. [Extension Authentication](/extensibility/overview#authentication) describes how your service validates it.
65
+
When the gateway has JWT signing configured, OpenShell authenticates every call to your service with a short-lived token. [Authenticating Extensions](/extensibility/overview#authenticating-extensions) describes how your service validates it.
0 commit comments