feat(auth): emit structured gateway authentication and authorization events

[krishicks]

User Story

As a security operator, I want authentication and authorization decisions at the gateway boundary emitted as structured security events, so that I can distinguish attacks from identity-provider failures and detect attempts by a sandbox principal to cross its authorized boundary.

Problem Statement

Gateway authentication and authorization failures currently surface through request failures and ordinary diagnostic logs rather than a consistent security-event contract. The gateway cannot export a structured record explaining which authentication mechanism failed, a safe reason category, or whether an authenticated sandbox principal attempted to access another sandbox or an administrator-only operation.

This issue extracts the non-overlapping authentication and boundary-finding scope from #2892. It does not own external OCSF export (#2762), relay reliability (#2642), trace correlation fields (#2640), or the general client event stream (#1933).

Impact / Why This Matters

Operators cannot reliably distinguish credential-stuffing attempts, expired credentials, issuer or identity-provider failures, and ordinary authorization mistakes. Cross-sandbox access attempts appear as request failures but do not produce an alert-grade finding that a SIEM or security workflow can identify consistently.

The current workaround is to parse gateway log text and correlate it with identity-provider logs. That loses stable reason categories, may omit the principal or request correlation, and risks exposing too much authentication detail if integrations scrape arbitrary diagnostic messages.

Proposed Design

OpenShell should emit structured security events for authentication outcomes and authorization denials at the gateway boundary. Each event should describe the mechanism, terminal outcome, low-cardinality reason category, peer address when reliably available, request or correlation identifier, and the principal type or non-secret identifier when authentication progressed far enough to establish one.

Authentication successes should be available through an explicit operator-controlled setting because they can be high-volume. Authentication failures and security-relevant authorization denials should have documented default behavior. Configuration must not change the result returned to the caller.

When an authenticated sandbox principal attempts to access another sandbox or an administrator-only operation, OpenShell should emit both the ordinary authorization-denial event and an alert-grade detection finding for the same incident. Both records should share correlation data.

Events must never include presented credentials, tokens, bearer material, raw authorization headers, or request bodies. Failure reasons should remain useful but must not reveal verification details that help an attacker distinguish sensitive credential state.

Acceptance Criteria

• Authentication failures emit a structured event containing the authentication mechanism, terminal outcome, low-cardinality reason category, request or correlation identifier, and peer address when reliably available.
• Reason categories cover the gateway's supported authentication paths without including raw parser, cryptographic, token, or identity-provider error text.
• Authentication success events can be enabled or disabled independently through documented operator configuration.
• Authorization denials identify the established principal type and authorized resource boundary without exposing credentials or confidential request data.
• A sandbox principal attempting cross-sandbox access emits an authorization-denial event and an alert-grade detection finding with shared correlation data.
• A sandbox principal attempting an administrator-only operation emits the same dual-event security signal.
• Presented credentials, tokens, SSH bearer material, raw authorization headers, and request bodies never appear in emitted records; automated tests cover representative secret canaries.
• Adding the audit instrumentation does not change authentication or authorization results returned to callers.
• The event catalog, reason categories, severity mapping, configuration defaults, and redaction guarantees are documented.

Alternatives Considered

Parse ordinary gateway logs in a SIEM. Diagnostic log wording is not a stable schema, can omit correlation fields, and encourages exporting messages that were not designed as a security boundary.

Rely only on identity-provider audit logs. The identity provider cannot observe OpenShell authorization decisions, sandbox ownership checks, or administrator-role enforcement after authentication succeeds.

Include these events in the general control-plane mutation issue. Authentication failures occur before mutation handlers and boundary violations are security decisions rather than state changes. Giving them a separate event catalog and configuration keeps one user workflow and one owning instrumentation boundary per issue.

Agent Investigation

• Gateway authentication establishes Principal data in request extensions before handlers run.
• Sandbox-scope guards currently emit ordinary tracing messages for cross-sandbox denials but no alert-grade OCSF finding.
• Authentication failures occur earlier than mutation-handler audit points and therefore require separate boundary instrumentation.
• Related: Enterprise Observability #1055, Centralized audit/event log #1933, feat(ocsf): add trace_id/span_id correlation fields to OCSF event builders #2640, feat(observability): shared telemetry relay infrastructure for supervisor and agent traces #2642, feat(observability): OCSF event export from gateway to external SIEM destinations #2762, and Enhance OpenShell's OCSF telemetry and export it off-box via OTLP #2892.