docs(extensibility): streamline extension authentication guidance

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

Author: drew

docs/extensibility/isolation-backends.mdx

@@ -18,7 +18,12 @@ or policy model.
 ## The Interface
 
 Each step returns a new type, so the supervisor can't start an agent on a
-boundary that hasn't been confirmed.
+boundary that hasn't been confirmed. The traits are defined in
+[`contract.rs`](https://github.com/NVIDIA/OpenShell/blob/main/crates/openshell-isolation-interface/src/contract.rs)
+in the
+[`openshell-isolation-interface`](https://github.com/NVIDIA/OpenShell/tree/main/crates/openshell-isolation-interface)
+crate. `OpenShellRuntimeBackend` is implemented in
+[`openshell-sandbox-backend`](https://github.com/NVIDIA/OpenShell/tree/main/crates/openshell-sandbox-backend).
 
 | Rust surface | What it does | Returns |
 |---|---|---|

docs/extensibility/overview.mdx

@@ -44,68 +44,43 @@ and runtime-specific isolation inside the provisioned workload.
 
 ## Authentication
 
-When the gateway has JWT signing configured, OpenShell attaches a short-lived bearer token to every call it makes to a [gateway interceptor](/extensibility/gateway-interceptors) or [supervisor middleware](/extensibility/supervisor-middleware) service. Your service validates this token to confirm that the call comes from your gateway or one of its sandboxes.
+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.
 
-### Tokens OpenShell Sends
+| Claim | Value |
+|---|---|
+| `iss` | `openshell-gateway:<gateway_id>` |
+| `aud` | The registration's `audience`. Defaults to `urn:openshell:extension:interceptor:<name>` or `urn:openshell:extension:middleware:<name>`. |
+| `caller_kind` | `gateway`, or `supervisor` for middleware calls from a sandbox. |
+| `sandbox_id` | The calling sandbox, when `caller_kind` is `supervisor`. |
 
-Each token is an EdDSA-signed JWT scoped to one service registration:
-
-<ParamField path="iss" type="string">
-  `openshell-gateway:<gateway_id>`.
-</ParamField>
-
-<ParamField path="aud" type="string">
-  The registration's `audience`. Defaults to `urn:openshell:extension:interceptor:<name>` or `urn:openshell:extension:middleware:<name>`.
-</ParamField>
-
-<ParamField path="caller_kind" type="'gateway' | 'supervisor'">
-  `gateway` for calls from the gateway, or `supervisor` for middleware calls from a sandbox supervisor.
-</ParamField>
-
-<ParamField path="sandbox_id" type="string">
-  The calling sandbox. Present only when `caller_kind` is `supervisor`.
-</ParamField>
-
-Authenticated network services use `https://` endpoints. OpenShell verifies the service certificate against platform trust roots, or against the private CA in the registration's `tls_ca_cert_path`, and always checks the hostname.
-
-### Establish Trust in the Gateway
-
-Before your service can validate tokens, configure it with three values from the gateway operator:
-
-- The gateway URL.
-- The gateway ID. Tokens use `openshell-gateway:<gateway_id>` as their issuer.
-- The gateway's public signing key or JWKS.
-
-Configure these values directly instead of discovering them from the gateway. A key fetched from an unverified source does not prove which gateway it belongs to.
+### Validate Each Token
 
-To pick up new keys later, fetch `/.well-known/openid-configuration` from the configured gateway URL over TLS, then fetch the keys from its `jwks_uri`. This document looks like OIDC discovery, but its `issuer` is `openshell-gateway:<gateway_id>` rather than the gateway URL. Compare the token's `iss` with that value, not with the URL.
+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`.
 
-### Validate Each Token
+For each request, check that:
 
-Cache keys by `kid` and check that:
+- `typ` is `openshell-ext+jwt` and `alg` is `EdDSA`. Pin the algorithm; don't read it from the token.
+- The signature, expiry, and exact audience are valid.
+- `iss` is `openshell-gateway:<gateway_id>`, not the gateway URL.
+- `caller_kind` and `sandbox_id` match what your service accepts.
 
-- `typ` is exactly `openshell-ext+jwt`.
-- `alg` is `EdDSA`. Pin the algorithm instead of reading it from the token.
-- The signature, issuer, exact audience, and expiry are valid.
-- `caller_kind` is one your service accepts, and `sandbox_id` matches your expectations when your service scopes behavior per sandbox.
+OpenShell reuses a token until it rotates, so don't reject a repeated `jti`.
 
-OpenShell reuses a token until it rotates, so do not reject a repeated `jti` as a replay.
+Services must use `https://` endpoints. OpenShell verifies the certificate and hostname against platform roots, or against `tls_ca_cert_path` for a private CA.
 
 ### Confirm the Audience at Startup
 
-Return the audience your service expects in the `expected_audience` field of its `Describe` manifest. After authentication succeeds, the gateway compares this value with the operator-configured `audience` and refuses to start when they differ. A strict service may reject a token with the wrong audience before returning its manifest, in which case gateway startup reports an authentication failure. Leave the field empty to skip this check.
+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.
 
 ### Run Without Authentication
 
-Set `allow_insecure_transport = true` on a registration to use a plaintext `http://` endpoint. OpenShell then sends no token, and your service cannot distinguish OpenShell from any other client that can reach it. The gateway logs a warning for the registration at every startup.
-
-Use this setting for local development, or on a network that already authenticates callers.
+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.
 
 ### Current Limitations
 
-- Tokens are bearer credentials. A captured token remains valid until it expires unless your service adds proof of possession or request binding.
-- Extension tokens share a signing key with other tokens the gateway issues, so you cannot rotate or revoke extension credentials independently.
-- mTLS client authentication and overlapping signing-key rotation are not available.
+- Tokens are bearer credentials: a captured token works until it expires.
+- Extension tokens share the gateway's signing key, so you can't rotate or revoke them separately.
+- mTLS client authentication and overlapping key rotation aren't available.
 
 ## Building Extensions