snapshot of https://github.com/ory/kratos.git (master, 2026-09-15; blobs > 131072B omitted)

selfservice/strategy/oidc/oidcerr/oidcerr.go

@@ -0,0 +1,75 @@
+// Copyright © 2026 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+// Package oidcerr defines structured errors raised by the OIDC strategy.
+//
+// The Step type and its constants name the high-level callback phase that
+// failed. The test login flow's debug renderer buckets failures by Step;
+// non-test flows ignore it.
+package oidcerr
+
+import "errors"
+
+// Step identifies the OIDC callback phase that produced an error.
+type Step string
+
+const (
+	StepStateValidate  Step = "state_validate"
+	StepProviderDenied Step = "provider_denied"
+	StepTokenExchange  Step = "token_exchange"
+	StepIDTokenVerify  Step = "id_token_verify"
+	StepClaimsDecode   Step = "claims_decode"
+	StepCallback       Step = "callback"
+)
+
+// stepReasons crosswalks a Step to the reason string surfaced in the test
+// debug payload's StepError.Reason field.
+var stepReasons = map[Step]string{
+	StepStateValidate:  "state_invalid",
+	StepProviderDenied: "access_denied",
+	StepTokenExchange:  "exchange_failed",
+	StepIDTokenVerify:  "verification_failed",
+	StepClaimsDecode:   "claims_invalid",
+	StepCallback:       "callback_failed",
+}
+
+// Reason returns the reason string surfaced in the test debug payload's
+// StepError.Reason field. Defined on Step (not *CallbackStepError) because
+// herodot.ReasonCarrier picks up any error type with a Reason() method and
+// would clobber the herodot DefaultError reason on the wire.
+func (s Step) Reason() string {
+	return stepReasons[s]
+}
+
+// CallbackStepError tags an OIDC callback error with the step it belongs to.
+// It wraps the underlying error transparently: errors.As walks past it to
+// find the inner *herodot.DefaultError, so existing handlers and writers
+// behave identically.
+type CallbackStepError struct {
+	Step Step
+	err  error
+}
+
+func (e *CallbackStepError) Error() string { return e.err.Error() }
+func (e *CallbackStepError) Unwrap() error { return e.err }
+
+// Wrap tags err with a step hint. Pass-through for nil. The wrap is the
+// outermost layer so callers that errors.As on *herodot.DefaultError keep
+// working without changes.
+func Wrap(step Step, err error) error {
+	if err == nil {
+		return nil
+	}
+	return &CallbackStepError{Step: step, err: err}
+}
+
+// Unwrap walks err's chain looking for a *CallbackStepError tag. It returns
+// a pointer to the tagged error if found, or a fresh fallback tagged with
+// StepCallback otherwise. The returned value is never nil — callers can
+// always read e.Step / e.Step.Reason() without a nil check.
+func Unwrap(err error) *CallbackStepError {
+	if se, ok := errors.AsType[*CallbackStepError](err); ok {
+		return se
+	}
+	return &CallbackStepError{Step: StepCallback, err: err}
+}

selfservice/strategy/oidc/oidcerr/oidcerr_test.go

@@ -0,0 +1,87 @@
+// Copyright © 2026 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package oidcerr_test
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/ory/herodot"
+	"github.com/ory/kratos/selfservice/strategy/oidc/oidcerr"
+)
+
+func TestUnwrap(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name       string
+		err        error
+		wantStep   oidcerr.Step
+		wantReason string
+	}{
+		{
+			name:       "state validate",
+			err:        oidcerr.Wrap(oidcerr.StepStateValidate, herodot.ErrBadRequest().WithReason("invalid state")),
+			wantStep:   oidcerr.StepStateValidate,
+			wantReason: "state_invalid",
+		},
+		{
+			name:       "provider denied",
+			err:        oidcerr.Wrap(oidcerr.StepProviderDenied, herodot.ErrBadRequest().WithReason("access_denied: user refused")),
+			wantStep:   oidcerr.StepProviderDenied,
+			wantReason: "access_denied",
+		},
+		{
+			name:       "token exchange",
+			err:        oidcerr.Wrap(oidcerr.StepTokenExchange, errors.New("oauth2: cannot fetch token")),
+			wantStep:   oidcerr.StepTokenExchange,
+			wantReason: "exchange_failed",
+		},
+		{
+			name:       "id_token verify",
+			err:        oidcerr.Wrap(oidcerr.StepIDTokenVerify, herodot.ErrForbidden().WithReason("Could not verify id_token")),
+			wantStep:   oidcerr.StepIDTokenVerify,
+			wantReason: "verification_failed",
+		},
+		{
+			name:       "claims decode",
+			err:        oidcerr.Wrap(oidcerr.StepClaimsDecode, herodot.ErrUpstreamError().WithReason("provider did not return a subject")),
+			wantStep:   oidcerr.StepClaimsDecode,
+			wantReason: "claims_invalid",
+		},
+		{
+			name:       "explicit callback bucket",
+			err:        oidcerr.Wrap(oidcerr.StepCallback, errors.New("missing code")),
+			wantStep:   oidcerr.StepCallback,
+			wantReason: "callback_failed",
+		},
+		{
+			name:       "untagged error falls back to callback",
+			err:        errors.New("some unrelated failure"),
+			wantStep:   oidcerr.StepCallback,
+			wantReason: "callback_failed",
+		},
+		{
+			name:       "untagged herodot error falls back to callback",
+			err:        herodot.ErrInternalServerError().WithReason("oops"),
+			wantStep:   oidcerr.StepCallback,
+			wantReason: "callback_failed",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			e := oidcerr.Unwrap(tc.err)
+			assert.Equal(t, tc.wantStep, e.Step)
+			assert.Equal(t, tc.wantReason, e.Step.Reason())
+		})
+	}
+}
+
+func TestWrap_NilPassthrough(t *testing.T) {
+	t.Parallel()
+	assert.Nil(t, oidcerr.Wrap(oidcerr.StepCallback, nil))
+}