Skip to content

feat(observability): describe credential preparation outcomes #5395

Open
afourniernv/OpenShell
#10

Description

@afourniernv

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

  1. changed the title [-]feat(observability): correlate credential preparation and withholding[/-] [+]feat(observability): describe credential preparation outcomes[/+] on Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:triage-neededOpened without agent diagnostics and needs triage

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions