feat(audit): audit credential-disclosure reads (provider environment, inference bundle) #3017

User Story

As a security or compliance owner running OpenShell, I want the gateway RPCs that hand out secret-bearing material — a sandbox's provider environment, an inference bundle — to emit a structured audit event recording who requested the disclosure and when, so that credential access is as accountable as credential change, even though the read alters no state.

Problem Statement

OpenShell is gaining a structured audit trail for state-changing gateway operations (#2911) and for authentication and authorization outcomes (#2912). Neither covers credential-disclosure reads: RPCs that return secret-bearing material to a caller without changing any state. GetSandboxProviderEnvironment returns a sandbox's resolved provider credentials, and GetInferenceBundle returns inference credential material. Today these produce no audit record. A read is not a mutation, so it sits outside #2911's mutations-only scope; a successful, authorized read is not an auth failure, so it sits outside #2912. The disclosure is therefore invisible in the audit trail.

Impact / Why This Matters

After a suspected credential leak, or during a routine access review, an operator needs to answer "who pulled this sandbox's provider credentials, and when?" and "which principal fetched the inference bundle?" Those questions have no data behind them today. Mutation is accounted for and authentication is accounted for, but the moment secret material actually leaves the gateway to a caller is not. The current workaround — correlating diagnostic logs with request traces — is not a stable audit contract and may not reliably identify the principal or the resource. The audit record must name the principal and the resource disclosed, and must never contain the disclosed secret itself.

Proposed Design

Each gateway RPC that returns secret-bearing material emits one structured OCSF audit event per attempt — on success and on failure — naming the authenticated principal (taken from the session, not the request), the resource disclosed (provider or profile id, sandbox id, inference route), the outcome, and a correlation id. The event never carries credential values, tokens, or bundle contents. It reuses the same audit helper, actor model, and master toggle that govern the control-plane audit events, so disclosure-read auditing turns on and off with the rest of the trail. The OCSF class is left to the implementer — an Entity Management (3004) access/read activity or a dedicated access event both fit. Because disclosure reads can be higher-volume than mutations, a finer toggle to gate their capture is a reasonable option, but the master audit toggle governs by default.

Acceptance Criteria

• Each gateway RPC that discloses secret-bearing material (GetSandboxProviderEnvironment, GetInferenceBundle, and any peer added later) emits one audit record per attempt, on both success and failure.
• The record names the authenticated principal, the disclosed resource (stable identifier), the outcome, and a correlation id.
• No credential value, token, or bundle content appears in any record; automated tests cover representative secret canaries.
• Emission is governed by the existing [openshell.gateway.audit] master toggle.
• Contributor documentation notes that a new secret-disclosing read RPC must emit a disclosure-audit event.
• The event, its fields, and redaction behavior are documented for operators.

Alternatives Considered

• Fold into feat(audit): emit structured gateway control-plane mutation events #2911. Rejected: reads are not mutations. Adding them to the mutation catalog blurs "what changed" with "what was accessed" and gives the two very different volume and retention characteristics one owner.
• Rely on network or proxy telemetry. A proxy can see a request but not the authenticated principal established at the gateway boundary, nor the store outcome, so it cannot attribute the disclosure.
• Accept the gap. Leaves credential access unaccountable, which is precisely the case an operator most needs to reconstruct.

Agent Investigation

• The disclosing RPCs are GetSandboxProviderEnvironment and GetInferenceBundle in the gateway (crates/openshell-server/src/grpc/), with the authenticated principal already available at the boundary.
• The audit helper, principal→actor mapping, and master toggle being contributed for feat(audit): emit structured gateway control-plane mutation events #2911/feat(auth): emit structured gateway authentication and authorization events #2912 are directly reusable here — this is incremental instrumentation, not new infrastructure.
• This scope was explicitly deferred in the original audit-taxonomy design (recorded as out of the mutation scope). It has no home in the current decomposition, which is why it is filed as its own request.

Checklist

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