Repository navigation
Description
User Story
I run OpenShell workloads that call protected APIs. I need to distinguish credential preparation failures from policy and upstream failures without exposing credentials.
Problem Statement
The existing credential stage does not identify the preparation mechanism, placement or bounded result. A configured provider or an upstream status code does not establish what OpenShell prepared for a particular request.
Impact / Why This Matters
Operators can mistake credential resolution/signing failures for policy denials or assume a credential was used merely because a provider was configured.
Proposed Design
Enrich the existing credential-preparation spans with bounded mechanism, placement and preparation outcomes for static header/body substitution, Basic authentication, SigV4 and token grants. Distinguish prepared, not-needed, refused, failed and stale preparation at the actual preparation sites.
Preparation does not prove transmission or upstream receipt. A request stopped before preparation has no preparation stage; that is not a new "withheld" event. Preserve credential custody, endpoint/placement restrictions, policy ordering and existing OCSF records. Do not add tokens, claims, exchange bodies or a new audit summary.
Suggested UX
Expand a request's credential stage to see how preparation finished, then inspect later stages separately to determine whether forwarding occurred. Join existing security records using the request ID.
Acceptance Criteria
- Mechanism, placement and bounded preparation outcomes describe work that actually ran.
- Unused resolvers and removed headers do not imply credential preparation or delivery.
- Preparation refusals, operational failures and staleness remain distinguishable without exposing secrets.
- Existing enforcement, credential delivery behavior, public contracts and audit emissions remain unchanged.
Alternatives Considered
Provider configuration alone does not show per-request preparation. Upstream status codes cannot prove which credential OpenShell supplied. Additional security-log summaries would duplicate existing per-control records.
Agent Investigation
The current HTTP correlation core already supplies the credential-stage boundary. This change adds span metadata at static and token-grant preparation sites without adding a provider API, configuration knob or OCSF field.
Component of #5210. It does not depend on remote middleware RPC tracing.
Checklist
- I've reviewed existing issues and the published docs.
- This is a design proposal, not a "please build this" request.
Activity
[-]feat(observability): correlate credential preparation and withholding[/-][+]feat(observability): describe credential preparation outcomes[/+]