OpenShell/proto/supervisor_middleware.proto

// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";

package openshell.middleware.v1;

import "google/protobuf/empty.proto";
import "google/protobuf/struct.proto";

// SupervisorMiddleware lets an operator-run service inspect and transform
// sandbox HTTP requests and client WebSocket text messages before OpenShell
// injects credentials.
service SupervisorMiddleware {
  // Describe returns the service manifest and declared bindings.
  rpc Describe(google.protobuf.Empty) returns (MiddlewareManifest);

  // ValidateConfig checks service-specific configuration for one binding.
  rpc ValidateConfig(ValidateConfigRequest) returns (ValidateConfigResponse);

  // EvaluateHttpRequest returns an allow, deny, or mutation decision for one
  // buffered HTTP request.
  rpc EvaluateHttpRequest(HttpRequestEvaluation) returns (HttpRequestResult);

  // EvaluateWebSocketSession opens one ordered, phase-specific stream for a
  // single middleware stage and WebSocket upgrade attempt. The current
  // implementation supports client-to-upstream text messages at
  // PRE_CREDENTIALS; PRE_RETURN is reserved for upstream-to-client messages.
  // A request may go unanswered when the session terminates. For every opened
  // stage stream, OpenShell attempts at most one session_end before closing the
  // stream when its transport is still writable.
  rpc EvaluateWebSocketSession(stream WebSocketSessionEvent)
      returns (stream WebSocketSessionEventResult);
}

// MiddlewareManifest describes one middleware service and the bindings it
// exposes. The service is the operator-run gRPC server implementing
// SupervisorMiddleware.
message MiddlewareManifest {
  // Human-readable middleware service name used only for diagnostics. This is
  // not required to match an operator-owned registration name.
  string name = 1;
  // Release version of the middleware service implementation, used for
  // diagnostics.
  string service_version = 2;
  // Bindings exposed by this middleware service.
  repeated MiddlewareBinding bindings = 3;
  // Exact JWT audience this service verifies on inbound OpenShell calls.
  // After authenticated Describe succeeds, OpenShell rejects the registration
  // unless this matches the operator-configured audience. A strict verifier may
  // reject an incorrect audience before returning this manifest. Empty skips
  // this post-authentication consistency check.
  string expected_audience = 4;
}

// MiddlewareBinding declares one operation and phase supported by a service.
message MiddlewareBinding {
  // Supported operation.
  SupervisorMiddlewareOperation operation = 1;
  // Supported evaluation phase. PR 1 supports PRE_CREDENTIALS. PRE_RETURN is
  // reserved for the return-path follow-up and is rejected by current
  // manifest validation.
  SupervisorMiddlewarePhase phase = 2;
  // Maximum logical payload or replacement this binding can process. For
  // HTTP_REQUEST this is the request body; for WEBSOCKET_MESSAGE this is one
  // complete message. Required for every payload-bearing operation.
  uint64 max_payload_bytes = 3;
  // Optional binding-specific RPC timeout. Empty uses the operator-configured
  // service timeout, or the 500ms platform default when that is also omitted.
  // A non-empty value may shorten but cannot extend the operator timeout.
  // Values use an integer with an `ms` or `s` suffix and must be between
  // 10ms and 30s.
  string timeout = 4;
}

// ValidateConfigRequest contains one policy configuration to validate.
message ValidateConfigRequest {
  // Service-specific policy configuration.
  google.protobuf.Struct config = 1;
  // Built-in middleware name or operator-owned registration name.
  string middleware_name = 2;
}

// ValidateConfigResponse reports whether a policy configuration is accepted.
message ValidateConfigResponse {
  // True when the service accepts the configuration.
  bool valid = 1;
  // Human-readable validation failure reason. Empty when valid is true.
  string reason = 2;
}

// HttpRequestEvaluation contains one buffered HTTP request to evaluate.
message HttpRequestEvaluation {
  // Evaluation phase selected for this request.
  SupervisorMiddlewarePhase phase = 1;
  // Sandbox and request identity available to the supervisor.
  // The encoded context is limited to 4 KiB.
  RequestContext context = 2;
  // Validated service-specific policy configuration.
  // The encoded configuration is limited to 64 KiB.
  google.protobuf.Struct config = 3;
  // Destination and HTTP request target.
  // The encoded target is limited to 32 KiB.
  HttpRequestTarget target = 4;
  // HTTP request headers before OpenShell injects credentials, in wire
  // order. Repeated header names are preserved as separate entries. Protected
  // credential, routing, framing, and hop-by-hop headers are omitted.
  // At most 128 lines and 64 KiB of encoded headers are included.
  repeated HttpHeader headers = 5;
  // Buffered request body, limited to 4 MiB. Empty for a bodyless request.
  bytes body = 6;
  // Built-in middleware name or operator-owned registration name.
  string middleware_name = 7;
}

// HttpHeader is one request header line.
message HttpHeader {
  // Lowercased header name.
  string name = 1;
  // Header value with surrounding whitespace trimmed.
  string value = 2;
}

// Supervisor operation selected for middleware evaluation.
enum SupervisorMiddlewareOperation {
  SUPERVISOR_MIDDLEWARE_OPERATION_UNSPECIFIED = 0;
  SUPERVISOR_MIDDLEWARE_OPERATION_HTTP_REQUEST = 1;
  SUPERVISOR_MIDDLEWARE_OPERATION_WEBSOCKET_MESSAGE = 2;
}

// Ordered phase within a supervisor operation.
enum SupervisorMiddlewarePhase {
  SUPERVISOR_MIDDLEWARE_PHASE_UNSPECIFIED = 0;
  SUPERVISOR_MIDDLEWARE_PHASE_PRE_CREDENTIALS = 1;
  SUPERVISOR_MIDDLEWARE_PHASE_PRE_RETURN = 2;
}

// Why OpenShell is ending a middleware stream.
enum WebSocketSessionEndReason {
  WEB_SOCKET_SESSION_END_REASON_UNSPECIFIED = 0;
  WEB_SOCKET_SESSION_END_REASON_NORMAL_CLOSE = 1;
  WEB_SOCKET_SESSION_END_REASON_PEER_DISCONNECT = 2;
  WEB_SOCKET_SESSION_END_REASON_POLICY_RELOAD = 3;
  WEB_SOCKET_SESSION_END_REASON_MIDDLEWARE_DENIAL = 4;
  WEB_SOCKET_SESSION_END_REASON_MIDDLEWARE_FAILURE = 5;
  WEB_SOCKET_SESSION_END_REASON_PROTOCOL_ERROR = 6;
  WEB_SOCKET_SESSION_END_REASON_CANCELLATION = 7;
  WEB_SOCKET_SESSION_END_REASON_UPSTREAM_REJECTED = 8;
  WEB_SOCKET_SESSION_END_REASON_POLICY_DENIAL = 9;
  // The middleware stage voluntarily declined inspection during preflight.
  // This is a successful stage-local outcome, not a cancellation or denial of
  // the WebSocket upgrade.
  WEB_SOCKET_SESSION_END_REASON_STAGE_SKIPPED = 10;
}

// WebSocketSessionEvent is one ordered event in a stage-local stream.
// Message sequence numbers identify logical messages session-wide. A stage
// receives a strictly increasing subset of those numbers; gaps are valid when
// session messages are not delivered to that stage.
message WebSocketSessionEvent {
  oneof event {
    WebSocketPreflight preflight = 1;
    WebSocketSessionStart session_start = 2;
    WebSocketMessage message = 3;
    WebSocketSessionEnd session_end = 4;
  }
}

// WebSocketPreflight lets a service decline this upgrade before OpenShell
// contacts upstream. It deliberately excludes query data, arbitrary request
// headers, and message payloads.
message WebSocketPreflight {
  string session_id = 1;
  SupervisorMiddlewarePhase phase = 2;
  RequestContext context = 3;
  // Admitted HTTP WebSocket-upgrade target. The method is GET, query is always
  // empty, and path never includes a query string.
  HttpRequestTarget target = 4;
  repeated string requested_subprotocols = 5;
  // Built-in middleware name or operator-owned registration name.
  string middleware_name = 6;
  google.protobuf.Struct config = 7;
}

// WebSocketSessionStart reports bounded metadata known only after the
// upstream 101 response validates. Empty selected_subprotocol means none.
message WebSocketSessionStart {
  string selected_subprotocol = 1;
}

// WebSocketMessage contains one complete reconstructed logical message.
message WebSocketMessage {
  // Session-global sequence starting at 1. Values delivered to one stage must
  // strictly increase but need not be contiguous. Reject zero, duplicates, and
  // regressions; accept gaps.
  uint64 sequence = 1;
  // One complete logical payload. Protobuf string decoding enforces UTF-8 for
  // text messages. Raw frame mechanics are never exposed. Limited to 4 MiB by
  // the platform and the binding-specific cap.
  oneof payload {
    string text = 2;
    bytes binary = 3;
  }
}

// WebSocketSessionEnd is OpenShell's best-effort terminal notification for one
// opened stage stream. A stage receives at most one such notification.
message WebSocketSessionEnd {
  WebSocketSessionEndReason reason = 1;
}

// WebSocketPreflightAction is the service's one-time scoping decision.
enum WebSocketPreflightAction {
  // Invalid response value handled according to the policy failure mode.
  WEB_SOCKET_PREFLIGHT_ACTION_UNSPECIFIED = 0;
  // Inspect this session after the upstream accepts the upgrade.
  WEB_SOCKET_PREFLIGHT_ACTION_INSPECT = 1;
  // Voluntarily decline inspection without denying the upgrade. This is a
  // successful decision and does not engage on_error.
  WEB_SOCKET_PREFLIGHT_ACTION_SKIP = 2;
  // Authoritatively deny the upgrade before upstream contact. This is a
  // successful decision and is enforced regardless of on_error.
  WEB_SOCKET_PREFLIGHT_ACTION_DENY = 3;
}

message WebSocketPreflightDecision {
  WebSocketPreflightAction action = 1;
  // Free-form service diagnostic. OpenShell never exposes this to the
  // workload or security logs. Limited to 4 KiB before discarding.
  string reason = 2;
  // Optional stable machine-readable code for a deny decision. Because
  // preflight runs before the HTTP upgrade completes, OpenShell may return
  // this code to the requester. Codes follow the same format and 64-byte
  // maximum as HttpRequestResult.reason_code.
  string reason_code = 3;
  // Audit-safe findings produced during preflight. At most 32 findings of at
  // most 4 KiB encoded each are accepted.
  repeated Finding findings = 4;
  // Non-secret service-defined metadata included in diagnostics. At most 64
  // entries and 32 KiB of combined key/value data are accepted.
  map<string, string> metadata = 5;
}

// WebSocketMessageResult contains the decision and optional replacement for
// one message. A replacement must use the same variant as the input payload.
message WebSocketMessageResult {
  // Must exactly match the sequence of the corresponding WebSocketMessage.
  uint64 sequence = 1;
  Decision decision = 2;
  // Absence preserves the input unchanged. Oneof presence distinguishes an
  // empty replacement from no replacement, and string decoding enforces UTF-8.
  oneof replacement {
    string text = 3;
    bytes binary = 4;
  }
  // Free-form service diagnostic. OpenShell never exposes this to the
  // workload or security logs. Limited to 4 KiB before discarding.
  string reason = 5;
  // Optional stable machine-readable code for OCSF only. Unlike the HTTP
  // reason_code, this value is never put in a WebSocket close frame.
  string reason_code = 6;
  repeated Finding findings = 7;
  map<string, string> metadata = 8;
}

// WebSocketSessionEventResult is an evaluation result for a preflight or message
// event. Session start and end events do not produce results.
message WebSocketSessionEventResult {
  oneof result {
    WebSocketPreflightDecision preflight_decision = 1;
    WebSocketMessageResult message_result = 2;
  }
}

// RequestContext identifies the sandbox request being evaluated.
message RequestContext {
  // Request id used to correlate middleware and supervisor logs.
  string request_id = 1;
  // Sandbox id that originated the request.
  string sandbox_id = 2;
  // Workload process that originated the request, when available.
  Process originating_process = 3;
}

// HttpRequestTarget describes the admitted HTTP destination and request target.
message HttpRequestTarget {
  // Request scheme, such as "http", "https", "ws", or "wss".
  string scheme = 1;
  // Destination hostname selected by network policy.
  string host = 2;
  // Destination TCP port.
  uint32 port = 3;
  // HTTP request method.
  string method = 4;
  // Request path without the query string.
  string path = 5;
  // Raw request query string without the leading question mark.
  string query = 6;
}

// Process identifies a workload process and its executable ancestry.
message Process {
  // Executable path for the originating process.
  string binary = 1;
  // Process id within the sandbox.
  uint32 pid = 2;
  // Executable paths for ancestor processes, nearest parent first.
  repeated string ancestors = 3;
}

// Decision controls whether OpenShell continues processing the current
// evaluation unit.
enum Decision {
  // Invalid response value handled according to the policy failure mode.
  DECISION_UNSPECIFIED = 0;
  // Continue processing the current request or message and apply any returned
  // mutations.
  DECISION_ALLOW = 1;
  // Reject the current request or message. The operation-specific result
  // defines the enclosing protocol behavior.
  DECISION_DENY = 2;
}

// Finding is an audit-safe observation produced during evaluation.
message Finding {
  // Stable, service-defined finding type.
  string type = 1;
  // Human-readable finding label that does not contain request content.
  string label = 2;
  // Number of matching observations represented by this finding.
  uint32 count = 3;
  // Service-defined confidence level.
  string confidence = 4;
  // Service-defined severity level.
  string severity = 5;
}

// ExistingHeaderAction controls how a header write behaves when the
// case-insensitive header name is already present. Every action writes the
// value when the header is absent.
enum ExistingHeaderAction {
  EXISTING_HEADER_ACTION_UNSPECIFIED = 0;
  // Add another field value without changing existing values.
  EXISTING_HEADER_ACTION_APPEND = 1;
  // Remove every existing value, then add the new value.
  EXISTING_HEADER_ACTION_OVERWRITE = 2;
  // Leave the existing values unchanged.
  EXISTING_HEADER_ACTION_SKIP = 3;
}

// WriteHeader proposes one header value and defines collision behavior.
message WriteHeader {
  string name = 1;
  string value = 2;
  ExistingHeaderAction on_existing = 3;
}

// RemoveHeader removes every value for a case-insensitive header name.
message RemoveHeader {
  string name = 1;
}

// HeaderMutation is one ordered request-header operation.
message HeaderMutation {
  oneof operation {
    WriteHeader write = 1;
    RemoveHeader remove = 2;
  }
}

// HttpRequestResult contains the decision and optional request mutations.
message HttpRequestResult {
  // Allow or deny decision for this request.
  Decision decision = 1;
  // Free-form service diagnostic. OpenShell does not relay this text into
  // denied responses or security logs. Limited to 4 KiB before discarding.
  string reason = 2;
  // Replacement request body when has_body is true. Limited to 4 MiB.
  bytes body = 3;
  // True when body should replace the request body, including with an empty body.
  bool has_body = 4;
  // Ordered request-header mutations applied before the next middleware and
  // before forwarding. Header writes are restricted to the
  // "x-openshell-middleware-" namespace. Removes may target other visible
  // request headers, but credential, routing, framing, and hop-by-hop headers
  // are always protected. A violating result is a middleware failure handled
  // according to the policy failure mode. At most 64 operations, 32 KiB of
  // validated name/value data, and 64 KiB encoded are accepted.
  repeated HeaderMutation header_mutations = 5;
  // Audit-safe findings produced during evaluation. For operator-run services,
  // OpenShell logs platform-owned fields derived from the operator-owned
  // registration name rather than service-provided type, label, confidence,
  // or metadata text.
  // At most 32 findings of at most 4 KiB encoded each are accepted per stage.
  // A policy selects at most 10 stages, so one chain retains at most 320.
  repeated Finding findings = 6;
  // Non-secret service-defined metadata included in diagnostics. At most 64
  // entries and 32 KiB of combined key/value data are accepted.
  map<string, string> metadata = 7;
  // Optional stable machine-readable code for a deny decision. Codes must
  // start with a lowercase ASCII letter and contain only lowercase ASCII
  // letters, digits, and underscores, with a maximum length of 64 bytes.
  // OpenShell may return this code to the requester, unlike free-form reason.
  string reason_code = 8;
}