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

selfservice/strategy/code/strategy_verification.go

@@ -0,0 +1,492 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package code
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"github.com/gofrs/uuid"
+	"github.com/pkg/errors"
+	"go.opentelemetry.io/otel/attribute"
+
+	"github.com/ory/kratos/identity"
+	"github.com/ory/kratos/schema"
+	"github.com/ory/kratos/selfservice/flow"
+	"github.com/ory/kratos/selfservice/flow/settings"
+	"github.com/ory/kratos/selfservice/flow/verification"
+	"github.com/ory/kratos/text"
+	"github.com/ory/kratos/ui/container"
+	"github.com/ory/kratos/ui/node"
+	"github.com/ory/kratos/x"
+	"github.com/ory/x/decoderx"
+	"github.com/ory/x/otelx"
+	"github.com/ory/x/sqlcon"
+	"github.com/ory/x/sqlxx"
+)
+
+func (s *Strategy) VerificationStrategyID() string {
+	return string(verification.VerificationStrategyCode)
+}
+
+// PopulateVerificationMethod set's the appropriate UI nodes on this flow
+//
+// If the flow's state is `sent_email`, the `code` input and the success notification is set
+// Otherwise, the default email input is added.
+// If the flow is a browser flow, the CSRF token is added to the UI.
+func (s *Strategy) PopulateVerificationMethod(r *http.Request, f *verification.Flow) error {
+	return s.PopulateMethod(r, f)
+}
+
+func (s *Strategy) decodeVerification(r *http.Request) (*updateVerificationFlowWithCodeMethod, error) {
+	var body updateVerificationFlowWithCodeMethod
+
+	compiler, err := decoderx.HTTPRawJSONSchemaCompiler(verificationMethodSchema)
+	if err != nil {
+		return nil, errors.WithStack(err)
+	}
+
+	if err := decoderx.Decode(r, &body, compiler,
+		decoderx.HTTPDecoderUseQueryAndBody(),
+		decoderx.HTTPKeepRequestBody(true),
+		decoderx.HTTPDecoderAllowedMethods("POST", "GET"),
+		decoderx.HTTPDecoderSetValidatePayloads(true),
+		decoderx.HTTPDecoderJSONFollowsFormFormat(),
+	); err != nil {
+		return nil, errors.WithStack(err)
+	}
+
+	return &body, nil
+}
+
+// handleVerificationError is a convenience function for handling all types of errors that may occur (e.g. validation error).
+func (s *Strategy) handleVerificationError(r *http.Request, f *verification.Flow, body *updateVerificationFlowWithCodeMethod, err error) error {
+	if f != nil {
+		f.UI.SetCSRF(s.deps.GenerateCSRFToken(r))
+		email := ""
+		if body != nil {
+			email = body.Email
+		}
+		label := text.NewInfoNodeInputEmail()
+		inputType := node.InputAttributeTypeEmail
+		if channels, chErr := s.deps.Config().CourierChannels(r.Context()); chErr == nil {
+			for _, ch := range channels {
+				if ch.ID == "sms" {
+					label = text.NewInfoNodeInputEmailOrPhone()
+					inputType = node.InputAttributeTypeText
+					break
+				}
+			}
+		}
+		f.UI.GetNodes().Upsert(
+			node.NewInputField("email", email, node.CodeGroup, inputType, node.WithRequiredInputAttribute).WithMetaLabel(label),
+		)
+	}
+
+	return err
+}
+
+// swagger:model updateVerificationFlowWithCodeMethod
+type updateVerificationFlowWithCodeMethod struct {
+	// The email address or phone number to verify
+	//
+	// If the provided address belongs to a valid account, a verification email or SMS will be sent.
+	//
+	// If you want to notify the email address if the account does not exist, see
+	// the [notify_unknown_recipients flag](https://www.ory.com/docs/kratos/self-service/flows/verify-email-account-activation#attempted-verification-notifications)
+	//
+	// If a code was already sent, including this field in the payload will invalidate the sent code and re-send a new code.
+	//
+	// required: false
+	Email string `form:"email" json:"email"`
+
+	// Sending the anti-csrf token is only required for browser login flows.
+	CSRFToken string `form:"csrf_token" json:"csrf_token"`
+
+	// Method is the method that should be used for this verification flow
+	//
+	// Allowed values are `link` and `code`.
+	//
+	// required: true
+	Method verification.VerificationStrategy `json:"method"`
+
+	// Code from the recovery email
+	//
+	// If you want to submit a code, use this field, but make sure to _not_ include the email field, as well.
+	//
+	// required: false
+	Code string `json:"code" form:"code"`
+
+	// The id of the flow
+	Flow string `json:"-" form:"-"`
+
+	// Transient data to pass along to any webhooks
+	//
+	// required: false
+	TransientPayload json.RawMessage `json:"transient_payload,omitempty" form:"transient_payload"`
+}
+
+// getMethod returns the method of this submission or "" if no method could be found
+func (body *updateVerificationFlowWithCodeMethod) getMethod() verification.VerificationStrategy {
+	if body.Method != "" {
+		return body.Method
+	}
+	if body.Code != "" {
+		return verification.VerificationStrategyCode
+	}
+
+	return ""
+}
+
+func (s *Strategy) Verify(w http.ResponseWriter, r *http.Request, f *verification.Flow) (err error) {
+	ctx, span := s.deps.Tracer(r.Context()).Tracer().Start(r.Context(), "selfservice.strategy.code.Strategy.Verify")
+	span.SetAttributes(attribute.String("selfservice_flows_verification_use", s.deps.Config().SelfServiceFlowVerificationUse(ctx)))
+	defer otelx.End(span, &err)
+
+	body, err := s.decodeVerification(r)
+	if err != nil {
+		return s.handleVerificationError(r, nil, body, err)
+	}
+
+	f.TransientPayload = body.TransientPayload
+
+	if err := flow.MethodEnabledAndAllowed(ctx, f.GetFlowName(), s.VerificationStrategyID(), string(body.getMethod()), s.deps); err != nil {
+		return s.handleVerificationError(r, f, body, err)
+	}
+
+	if err := f.Valid(s.deps.Clock()); err != nil {
+		return s.handleVerificationError(r, f, body, err)
+	}
+
+	switch f.State {
+	case flow.StateChooseMethod:
+		fallthrough
+	case flow.StateEmailSent:
+		return s.verificationHandleFormSubmission(ctx, w, r, f, body)
+	case flow.StatePassedChallenge:
+		return s.retryVerificationFlowWithMessage(ctx, w, r, f.Type, text.NewErrorValidationVerificationRetrySuccess())
+	default:
+		return s.retryVerificationFlowWithMessage(ctx, w, r, f.Type, text.NewErrorValidationVerificationStateFailure())
+	}
+}
+
+func (s *Strategy) handleLinkClick(ctx context.Context, w http.ResponseWriter, r *http.Request, f *verification.Flow, code string) error {
+	// Pre-fill the code
+	if codeField := f.UI.Nodes.Find("code"); codeField != nil {
+		codeField.Attributes.SetValue(code)
+	}
+
+	// In the verification flow, we can't enforce CSRF if the flow is opened from an email, so we initialize the CSRF
+	// token here, so all subsequent interactions are protected
+	csrfToken := s.deps.CSRFHandler().RegenerateToken(w, r)
+	f.UI.SetCSRF(csrfToken)
+	f.CSRFToken = csrfToken
+
+	if err := s.deps.VerificationFlowPersister().UpdateVerificationFlow(ctx, f); err != nil {
+		return err
+	}
+
+	// we always redirect to the browser UI here to allow API flows to complete aswell
+	// TODO: In the future, we might want to redirect to a custom URI scheme here, to allow to open an app on the device of
+	// the user to handle the flow directly.
+	http.Redirect(w, r, f.AppendTo(s.deps.Config().SelfServiceFlowVerificationUI(ctx)).String(), http.StatusSeeOther)
+
+	return errors.WithStack(flow.ErrCompletedByStrategy)
+}
+
+func (s *Strategy) verificationHandleFormSubmission(ctx context.Context, w http.ResponseWriter, r *http.Request, f *verification.Flow, body *updateVerificationFlowWithCodeMethod) error {
+	if len(body.Code) > 0 {
+		if r.Method == http.MethodGet {
+			// Special case: in the code strategy we send out links as well, that contain the code
+			return s.handleLinkClick(ctx, w, r, f, body.Code)
+		}
+
+		// If not GET: try to use the submitted code
+		return s.verificationUseCode(ctx, w, r, body.Code, f)
+	} else if len(body.Email) == 0 {
+		// If no code and no email was provided, fail with a validation error
+		return s.handleVerificationError(r, f, body, schema.NewRequiredError("#/email", "email"))
+	}
+
+	if err := flow.EnsureCSRF(s.deps, r, f.Type, s.deps.Config().DisableAPIFlowEnforcement(ctx), s.deps.GenerateCSRFToken, body.CSRFToken); err != nil {
+		return s.handleVerificationError(r, f, body, err)
+	}
+
+	if err := s.deps.VerificationCodePersister().DeleteVerificationCodesOfFlow(ctx, f.ID); err != nil {
+		return s.handleVerificationError(r, f, body, err)
+	}
+
+	via := hackyInferChannel(body.Email)
+
+	ptc, ptcErr := s.deps.PendingTraitsChangePersister().GetPendingTraitsChangeByVerificationFlow(ctx, f.ID)
+	if ptcErr != nil {
+		if !errors.Is(ptcErr, sqlcon.ErrNoRows()) {
+			return s.handleVerificationError(r, f, body, ptcErr)
+		}
+		if err := s.deps.CodeSender().SendVerificationCode(ctx, f, via, body.Email); err != nil {
+			if !errors.Is(err, ErrUnknownAddress()) {
+				return s.handleVerificationError(r, f, body, err)
+			}
+			// Continue execution
+		}
+	} else {
+		// Re-check whether the proposed address is still unclaimed before resending.
+		// Another identity may have claimed it between the failed code submission and this resend.
+		existingAddr, addrErr := s.deps.PrivilegedIdentityPool().FindVerifiableAddressByValue(ctx, ptc.NewAddressVia, ptc.NewAddressValue)
+		if addrErr != nil && !errors.Is(addrErr, sqlcon.ErrNoRows()) {
+			return s.handleVerificationError(r, f, body, addrErr)
+		}
+		if addrErr == nil && existingAddr.IdentityID != ptc.IdentityID {
+			if err := s.updateVerificationFlowWithMessage(ctx, w, r, f, text.NewErrorValidationDuplicateCredentials(), http.StatusBadRequest); err != nil {
+				return s.retryVerificationFlowWithError(ctx, w, r, f.Type, err)
+			}
+			return errors.WithStack(flow.ErrCompletedByStrategy)
+		}
+
+		proposedIdentity, err := s.deps.IdentityPool().GetIdentity(ctx, ptc.IdentityID, identity.ExpandDefault)
+		if err != nil {
+			return s.handleVerificationError(r, f, body, err)
+		}
+		if err := s.SendVerificationCode(ctx, f, proposedIdentity, ptc); err != nil {
+			return s.handleVerificationError(r, f, body, err)
+		}
+	}
+
+	f.State = flow.StateEmailSent
+
+	if err := s.PopulateVerificationMethod(r, f); err != nil {
+		return s.handleVerificationError(r, f, body, err)
+	}
+
+	// PopulateVerificationMethod sets the email "code sent" message unconditionally.
+	// Override it with the message that matches the channel the code was sent over.
+	f.UI.Messages.Set(text.VerificationCodeSentMessage(via))
+
+	if body.Email != "" {
+		f.UI.Nodes.Append(
+			node.NewInputField("email", body.Email, node.CodeGroup, node.InputAttributeTypeSubmit).
+				WithMetaLabel(text.NewInfoNodeResendOTP()),
+		)
+	}
+
+	if err := s.deps.VerificationFlowPersister().UpdateVerificationFlow(ctx, f); err != nil {
+		return s.handleVerificationError(r, f, body, err)
+	}
+
+	return nil
+}
+
+func (s *Strategy) updateVerificationFlowWithMessage(ctx context.Context, w http.ResponseWriter, r *http.Request, f *verification.Flow, message *text.Message, statusCode int) error {
+	f.UI.Messages.Clear()
+	f.UI.Messages.Add(message)
+
+	if err := s.deps.VerificationFlowPersister().UpdateVerificationFlow(ctx, f); err != nil {
+		return err
+	}
+
+	if x.IsBrowserRequest(r) {
+		http.Redirect(w, r, f.AppendTo(s.deps.Config().SelfServiceFlowVerificationUI(ctx)).String(), http.StatusSeeOther)
+	} else {
+		s.deps.Writer().WriteCode(w, r, statusCode, f)
+	}
+	return nil
+}
+
+func (s *Strategy) verificationUseCode(ctx context.Context, w http.ResponseWriter, r *http.Request, codeString string, f *verification.Flow) error {
+	code, err := s.deps.VerificationCodePersister().UseVerificationCode(ctx, f.ID, codeString)
+	if errors.Is(err, ErrCodeNotFound()) {
+		if err := s.updateVerificationFlowWithMessage(ctx, w, r, f, text.NewErrorValidationVerificationCodeInvalidOrAlreadyUsed(), http.StatusOK); err != nil {
+			return s.retryVerificationFlowWithError(ctx, w, r, f.Type, err)
+		}
+		return errors.WithStack(flow.ErrCompletedByStrategy)
+	} else if err != nil {
+		return s.retryVerificationFlowWithError(ctx, w, r, f.Type, err)
+	}
+
+	var identityID uuid.UUID
+	var addressVia string
+	var ptcIdentity *identity.Identity
+
+	if code.VerifiableAddress == nil {
+		// Pending-change path: no persisted address — look up by verification flow ID.
+		ptc, ptcErr := s.deps.PendingTraitsChangePersister().GetPendingTraitsChangeByVerificationFlow(ctx, f.ID)
+		if ptcErr != nil {
+			if !errors.Is(ptcErr, sqlcon.ErrNoRows()) {
+				return s.retryVerificationFlowWithError(ctx, w, r, f.Type, ptcErr)
+			}
+			// PTC vanished between code issuance and use — show the standard
+			// "invalid or already used" message.
+			if err := s.updateVerificationFlowWithMessage(ctx, w, r, f, text.NewErrorValidationVerificationCodeInvalidOrAlreadyUsed(), http.StatusOK); err != nil {
+				return s.retryVerificationFlowWithError(ctx, w, r, f.Type, err)
+			}
+			return errors.WithStack(flow.ErrCompletedByStrategy)
+		}
+
+		// Security note: the verification flow is unauthenticated by design. The
+		// user clicks a link from email/SMS. The pending change is bound to the
+		// identity via IdentityID, but we cannot validate session ownership at
+		// completion time. The security model relies on:
+		//   1. The verification code is sent to the *new* address (attacker needs inbox access).
+		//   2. The verification flow has a TTL (enforced by the flow handler).
+		//   3. The one-time code is consumed on use (cannot be replayed).
+		// Creation of pending changes is gated by a privileged session check;
+		// ApplyPendingTraitsChange revalidates the session atomically with the apply.
+		updatedIdentity, applyErr := s.deps.SettingsHookExecutor().ApplyPendingTraitsChange(ctx, w, r, ptc)
+		if applyErr != nil {
+			if errors.Is(applyErr, identity.ErrConcurrentModification) ||
+				errors.Is(applyErr, settings.ErrPendingTraitsChangeSessionInvalid) {
+				if err := s.updateVerificationFlowWithMessage(ctx, w, r, f, text.NewErrorValidationVerificationCodeInvalidOrAlreadyUsed(), http.StatusOK); err != nil {
+					return s.retryVerificationFlowWithError(ctx, w, r, f.Type, err)
+				}
+				return errors.WithStack(flow.ErrCompletedByStrategy)
+			}
+			if errors.Is(applyErr, sqlcon.ErrUniqueViolation()) {
+				if err := s.updateVerificationFlowWithMessage(ctx, w, r, f, text.NewErrorValidationDuplicateCredentials(), http.StatusBadRequest); err != nil {
+					return s.retryVerificationFlowWithError(ctx, w, r, f.Type, err)
+				}
+				return errors.WithStack(flow.ErrCompletedByStrategy)
+			}
+			return s.retryVerificationFlowWithError(ctx, w, r, f.Type, applyErr)
+		}
+
+		ptcIdentity = updatedIdentity
+		addressVia = ptc.NewAddressVia
+		identityID = ptc.IdentityID
+	} else {
+		// Normal path: update the existing verifiable address directly.
+		address := code.VerifiableAddress
+		address.Verified = true
+		verifiedAt := sqlxx.NullTime(time.Now().UTC())
+		address.VerifiedAt = &verifiedAt
+		address.Status = identity.VerifiableAddressStatusCompleted
+		if err := s.deps.PrivilegedIdentityPool().UpdateVerifiableAddress(ctx, address, "verified", "verified_at", "status"); err != nil {
+			return s.retryVerificationFlowWithError(ctx, w, r, f.Type, err)
+		}
+
+		addressVia = address.Via
+		identityID = code.VerifiableAddress.IdentityID
+	}
+
+	var i *identity.Identity
+	if ptcIdentity != nil {
+		i = ptcIdentity
+	} else {
+		i, err = s.deps.IdentityPool().GetIdentity(ctx, identityID, identity.ExpandDefault)
+		if err != nil {
+			return s.retryVerificationFlowWithError(ctx, w, r, f.Type, err)
+		}
+	}
+
+	// Remainder is shared between both paths.
+	returnTo := f.ContinueURL(ctx, s.deps.Config())
+
+	f.UI = &container.Container{
+		Method: "GET",
+		Action: returnTo.String(),
+	}
+
+	f.State = flow.StatePassedChallenge
+	f.SetCSRFToken(flow.GetCSRFToken(s.deps, w, r, f.Type))
+	if addressVia == identity.AddressTypeSMS {
+		f.UI.Messages.Set(text.NewInfoSelfServiceVerificationPhoneSuccessful())
+	} else {
+		f.UI.Messages.Set(text.NewInfoSelfServiceVerificationSuccessful())
+	}
+	f.UI.Nodes.Append(node.NewAnchorField("continue", returnTo.String(), node.CodeGroup, text.NewInfoNodeLabelContinue()).
+		WithMetaLabel(text.NewInfoNodeLabelContinue()))
+
+	if err := s.deps.VerificationFlowPersister().UpdateVerificationFlow(ctx, f); err != nil {
+		return s.retryVerificationFlowWithError(ctx, w, r, flow.TypeBrowser, err)
+	}
+
+	if err := s.deps.VerificationExecutor().PostVerificationHook(w, r, f, i); err != nil {
+		return s.retryVerificationFlowWithError(ctx, w, r, f.Type, err)
+	}
+
+	return nil
+}
+
+func (s *Strategy) retryVerificationFlowWithMessage(ctx context.Context, w http.ResponseWriter, r *http.Request, ft flow.Type, message *text.Message) error {
+	s.deps.
+		Logger().
+		WithRequest(r).
+		WithField("message", message).
+		Debug("A verification flow is being retried because a validation error occurred.")
+
+	f, err := verification.NewFlow(s.deps,
+		s.deps.Config().SelfServiceFlowVerificationRequestLifespan(ctx), s.deps.CSRFHandler().RegenerateToken(w, r), r, verification.Strategies{s}, ft)
+	if err != nil {
+		return s.handleVerificationError(r, f, nil, err)
+	}
+
+	f.UI.Messages.Add(message)
+
+	if err := s.deps.VerificationFlowPersister().CreateVerificationFlow(ctx, f); err != nil {
+		return s.handleVerificationError(r, f, nil, err)
+	}
+
+	if x.IsJSONRequest(r) {
+		s.deps.Writer().WriteError(w, r, flow.NewFlowReplacedError(text.NewErrorSystemGeneric("An error occured, please use the new flow.")).WithFlow(f))
+	} else {
+		http.Redirect(w, r, f.AppendTo(s.deps.Config().SelfServiceFlowVerificationUI(ctx)).String(), http.StatusSeeOther)
+	}
+
+	return errors.WithStack(flow.ErrCompletedByStrategy)
+}
+
+func (s *Strategy) retryVerificationFlowWithError(ctx context.Context, w http.ResponseWriter, r *http.Request, ft flow.Type, verErr error) error {
+	s.deps.
+		Logger().
+		WithRequest(r).
+		WithError(verErr).
+		Debug("A verification flow is being retried because an error occurred.")
+
+	f, err := verification.NewFlow(s.deps,
+		s.deps.Config().SelfServiceFlowVerificationRequestLifespan(ctx), s.deps.CSRFHandler().RegenerateToken(w, r), r, verification.Strategies{s}, ft)
+	if err != nil {
+		return s.handleVerificationError(r, f, nil, err)
+	}
+
+	var toReturn error
+
+	if expired := new(flow.ExpiredError); errors.As(verErr, &expired) {
+		f.UI.Messages.Add(text.NewErrorValidationVerificationFlowExpired(s.deps.Clock(), expired.ExpiredAt))
+		toReturn = expired.WithFlow(f)
+	} else if err := f.UI.ParseError(node.LinkGroup, verErr); err != nil {
+		return err
+	}
+
+	if err := s.deps.VerificationFlowPersister().CreateVerificationFlow(ctx, f); err != nil {
+		return s.handleVerificationError(r, f, nil, err)
+	}
+
+	if x.IsJSONRequest(r) {
+		if toReturn == nil {
+			toReturn = flow.NewFlowReplacedError(text.NewErrorSystemGeneric("An error occured, please retry the flow.")).
+				WithFlow(f)
+		}
+		s.deps.Writer().WriteError(w, r, toReturn)
+	} else {
+		http.Redirect(w, r, f.AppendTo(s.deps.Config().SelfServiceFlowVerificationUI(ctx)).String(), http.StatusSeeOther)
+	}
+
+	return errors.WithStack(flow.ErrCompletedByStrategy)
+}
+
+func (s *Strategy) SendVerificationCode(ctx context.Context, f *verification.Flow, i *identity.Identity, a identity.VerifiableAddressLike) (err error) {
+	rawCode := GenerateCode()
+
+	if _, err = s.deps.VerificationCodePersister().CreateVerificationCode(ctx, &CreateVerificationCodeParams{
+		RawCode:           rawCode,
+		ExpiresIn:         s.deps.Config().SelfServiceCodeMethodLifespan(ctx),
+		VerifiableAddress: a,
+		FlowID:            f.ID,
+	}); err != nil {
+		return err
+	}
+
+	return s.deps.CodeSender().SendVerificationCodeTo(ctx, f, i, rawCode, a)
+}