[Draft proposal] docs(examples): add a runnable ANS identity example for supervisor middleware #5011

Draft proposal — runtime validation pending. The OpenShell v0.1.6 gateway/supervisor smoke test described below has not yet been run. This issue remains open for early design feedback; runtime compatibility has not yet been established.

User Story

We recently created an ANS identity extension for OpenShell and are evaluating its supervisor middleware workflow for agents that call identity-protected HTTP services. My use case is to attach an operator-assigned, verifiable agent identity to outbound requests while keeping the signing key outside the sandbox. I need a reproducible example that exercises the actual gateway and supervisor and shows the receiving service verifying that identity. The v0.1.6 runtime test described below is proposed work, not a completed validation.

Problem Statement

OpenShell supports external supervisor middleware and documents a content-guard example. It does not currently provide a runnable request-identity example showing how an external middleware service can attach a verifiable agent identity outside the sandbox and have a receiving service validate it.

This is a proposed example and documentation contribution using the existing middleware contract. The scope is HTTP request signing and verification, with OpenShell v0.1.6 as the initial released baseline.

Impact / Why This Matters

An extension author evaluating this workflow currently has to assemble gateway authentication, middleware registration, sandbox policy, sandbox-to-identity authorization, and a verifying endpoint independently. An in-process middleware test does not establish that the actual gateway and supervisor invoke the service, apply its header mutations, or block traffic when the middleware fails.

A reproducible example would help users validate those boundaries while keeping signing keys outside the workload. It would also provide a concrete interoperability check for the external middleware contract.

Proposed Design

Add a small supervisor middleware example and link it from the middleware documentation. The example would use the existing ANS identity extension, maintained in its own repository and referenced at an immutable revision.

The user workflow would be:

1. Follow the documented prerequisites on Linux with Docker and matching OpenShell v0.1.6 components.
2. Run one launcher that generates disposable identity and trust fixtures, starts the production extension and a reference verifying endpoint, and creates a sandbox with the middleware attached.
3. Authorize the gateway-issued sandbox ID for the selected identity through operator-controlled configuration.
4. Send ordinary HTTP requests from the sandbox, observe the receiver's verified identity, and run the rejection scenarios below.
5. Clean up the example's processes, sandbox, and temporary material.

Gateway authentication and TLS-protected extension caller authentication remain enabled. The example uses generated, explicitly trusted test artifacts and does not require production credentials or a live registration service. Documentation distinguishes that fixture trust from production registration.

The initial contribution covers HTTP request identity. It uses the existing extension interface and is intended to require no OpenShell runtime changes. The exact example location and packaging would follow maintainer guidance.

Notional configuration

Within the example's complete gateway configuration:

[[openshell.supervisor.middleware]]
name = "ans-identity-example"
grpc_endpoint = "https://<reachable-middleware-host>:50051"
tls_ca_cert_path = "/path/to/example-ca.pem"
max_payload_bytes = 1048576
timeout = "500ms"
binding_policy = "allowlist"
bindings = ["http_request_pre_credentials"]

Within the example's complete sandbox policy:

network_middlewares:
  ans-identity:
    middleware: ans-identity-example
    order: 100
    on_error: fail_closed
    endpoints:
      include: ["callee.example.test"]
    config:
      mode: sign
      identity: example-agent

These are illustrative fragments. The runnable example would supply the authenticated gateway configuration, reachable local addresses, certificates, network policy, trust roots, and sandbox identity approval. Signing is placed last in the request middleware chain.

Acceptance Criteria

• A documented command runs the example from a clean checkout on the supported Linux/Docker environment with pinned component revisions and no production secrets.
• An authorized sandbox's request is verified by the receiving service, which returns the exact expected ANS identity.
• Workload-supplied forged identity headers are replaced, and the receiver verifies the operator-assigned identity.
• A sandbox without an approved identity binding cannot cause the protected operation to execute.
• An unavailable middleware service blocks the affected request, and the protected operation is not executed.
• The receiving service rejects an unsigned direct request.
• The example reports assertion failures, cleans up its resources, and distinguishes actual OpenShell runtime checks from separate verifier replay/tampering tests.
• Documentation explains the trust boundary, fixture versus production trust, supported versions, maintainer ownership, and limitations, and is linked from the supervisor middleware documentation.

Alternatives Considered

• Existing content-guard example: demonstrates the middleware lifecycle and content transformations. This example would add request signing, per-sandbox identity authorization, and verification by the receiving service.
• Existing in-process ANS demo: already checks signing, verification, replay, tampering, and caller authorization, but simulates the supervisor. It remains useful alongside a real-runtime check.
• Provider credential injection and SPIFFE token-grant examples: useful existing identity and credential workflows. This proposal demonstrates an external request-signing extension with a named agent identity and a receiving verifier.
• Gateway interceptor: suited to governing control-plane operations; this use case acts on allowed outbound HTTP requests, so supervisor middleware is the applicable extension point.
• Built-in implementation: unnecessary for the initial example; the external extension contract already supplies the required integration boundary.

Compatibility Investigation

• OpenShell v0.1.6, released October 27, 2026, introduces explicit middleware binding requirements and requires gateway authentication unless explicitly disabled. The example would exercise the authenticated configuration and require the request hook.
• The extension's vendored extension.proto, supervisor_middleware.proto, and gateway_interceptor.proto match the v0.1.6 files byte-for-byte. Some broader vendored schemas differ; this comparison does not establish runtime compatibility.
• The proposed v0.1.6 runtime smoke test has not yet been executed. Compatibility findings and repeatable evidence would accompany the eventual PR.

References: v0.1.6 release notes, middleware configuration, content-guard example.

Checklist

• I've reviewed existing issues and the published docs.
• This is a design proposal with a bounded contribution scope.