feat(auth): bind sandbox credential RPCs to the running sandbox

[pierzchalski]

User Story

As a gateway operator, I want credential RPCs to identify the running sandbox, so its bearer alone cannot grant credential access or refresh.

Problem Statement

GetSandboxProviderEnvironment and RefreshSandboxToken check bearer validity, sandbox scope, persisted runtime generation, and token lineage, not whether the caller is the running sandbox. Another bearer holder satisfying gateway reachability and configured TLS client authentication can pass these checks.

The token is held by the sandbox's supervisor process, not the workload; "the running sandbox" below means that process. This is defense in depth for any exposure of a current bearer, which architecture/gateway.md:359-361 accepts as bounded by the token TTL. Merged #3562 removed the legacy non-expiring admission path, and open #3110 separates sandbox identity from TLS; neither adds caller binding, and this work should be sequenced after #3110. #1955 plans to retire GetSandboxProviderEnvironment, so this request covers credential RPCs and their replacements.

Impact / Why This Matters

An accepted caller can read provider credentials or refresh the token. Short lifetimes and rotation limit exposure but do not identify the presenter.

Proposed Design

After startup and initial credential acquisition, require the gateway to establish that subsequent credential reads and refreshes come from the running sandbox. Leave the mechanism open.

Acceptance Criteria

• Tests allow bound-sandbox credential reads and refreshes, including replacement paths, but reject the same valid bearer presented elsewhere despite satisfying other transport requirements.
• Authorized restart and reconnection work; bindings that no longer identify a live sandbox fail.

Alternatives Considered

Shorter expiry, rotation, and network restrictions limit exposure or access, not caller binding.

Agent Investigation

Read credential handlers and session authentication at main a8f98ec, including merged #3562; nothing executed.

• crates/openshell-server/src/grpc/policy.rs:3355-3374: sandbox scope checked before environment loading.
• crates/openshell-server/src/auth/sandbox_jwt.rs:273-307: session JWT validation and persisted authorization except for refresh.
• crates/openshell-server/src/auth/sandbox_session.rs:248-300, :309-333: sandbox phase, runtime generation, auth epoch, and token lineage checks; refresh replay window.
• crates/openshell-server/src/grpc/auth_rpc.rs:151-237: refresh accepts the current token or a previous token within the replay window with a matching request hash, not caller-origin evidence.

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request

[johntmyers]

Can you elaborate on this a little more? A step by step explanation of the security problem you are solving or a specific challenge you ran into while using OpenShell?

[shleder]

The security issue with bearer-based credential RPCs (GetSandboxProviderEnvironment and RefreshSandboxToken) is the classic lack of channel binding: any workload, subshell, or leaked process table reader that captures the bearer token can impersonate the sandbox to the gateway.

To bind credential issuance directly to the running sandbox process rather than trusting ambient network tokens, two kernel-level patterns are standard in hardened sandbox runtimes:

1. Local Socket Peer Authentication (SO_PEERCRED / SO_PEERPIDFD):
   Instead of exposing credential RPCs over a generic TCP/mTLS listener, route sandbox-to-gateway requests over a dedicated UNIX domain socket. On Linux, the gateway can query getsockopt(fd, SOL_SOCKET, SO_PEERCRED, ...) or SO_PEERPIDFD upon connection. The kernel authoritatively reports the caller's PID, UID, and GID. The gateway then verifies that this PID belongs to the sandbox's cgroup v2 scope (/proc/<pid>/cgroup) before returning credentials or refreshing tokens. An external caller cannot spoof SO_PEERCRED.

2. Push-at-Spawn via SCM_RIGHTS (Eliminating Credential RPCs Entirely):
   A more robust architecture is to avoid credential RPC endpoints inside the guest workload altogether. The supervisor fetches or generates the task credentials before dropping privileges, places them into an anonymous in-memory file (memfd_create), and passes the file descriptor into the child process across fork()/execve() via SCM_RIGHTS. The sandbox workload reads the credentials once from the inherited FD, and the gateway does not need to expose persistent credential-reading RPCs to the sandboxed network namespace (CLONE_NEWNET).

In Vetto, we isolate agent toolchains in sub-4ms unprivileged sandboxes while mediating sensitive host resources through an explicit SCM_RIGHTS descriptor broker and L7 semantic proxy, ensuring that ambient bearer tokens are never exposed to untrusted tool calls.

---

Disclaimer: I am the author/maintainer of Vetto, an open-source (Apache-2.0) daemon-less sandbox layer for AI coding agents.