upstream-ory-kratos/identity/manager.go

// Copyright © 2023 Ory Corp
// SPDX-License-Identifier: Apache-2.0

package identity

import (
	"context"
	"encoding/json"
	"fmt"
	"maps"
	"slices"
	"sort"
	"strings"
	"time"

	stderrors "errors"

	"github.com/gofrs/uuid"
	"github.com/mohae/deepcopy"
	"github.com/pkg/errors"
	"golang.org/x/sync/errgroup"

	"github.com/ory/herodot"
	"github.com/ory/jsonschema/v3"
	"github.com/ory/kratos/courier"
	"github.com/ory/kratos/courier/template"
	"github.com/ory/kratos/courier/template/email"
	"github.com/ory/kratos/courier/template/sms"
	"github.com/ory/kratos/driver/config"
	"github.com/ory/kratos/schema"
	"github.com/ory/kratos/x"
	"github.com/ory/kratos/x/transaction"
	"github.com/ory/x/logrusx"
	"github.com/ory/x/otelx"
	"github.com/ory/x/popx"
	"github.com/ory/x/sqlcon"
)

func ErrProtectedFieldModified() *herodot.DefaultError {
	return herodot.ErrForbidden().
		WithReasonf(`A field was modified that updates one or more credentials-related settings. This action was blocked because an unprivileged method was used to execute the update. This is either a configuration issue or a bug and should be reported to the system administrator.`)
}

type (
	managerDependencies interface {
		config.Provider
		PoolProvider
		PrivilegedPoolProvider
		otelx.Provider
		courier.Provider
		ValidationProvider
		ActiveCredentialsCounterStrategyProvider
		logrusx.Provider
		transaction.PersistenceProvider
		PendingTraitsChangePersistenceProvider
		template.Dependencies
	}
	ManagementProvider interface {
		IdentityManager() *Manager
	}
	Manager struct {
		r managerDependencies
	}

	ManagerOptions struct {
		ExposeValidationErrors    bool
		AllowWriteProtectedTraits bool
		ExcludedCredentialTypes   []CredentialsType
	}

	ManagerOption func(*ManagerOptions)
)

func NewManager(r managerDependencies) *Manager {
	return &Manager{r: r}
}

func ManagerExposeValidationErrorsForInternalTypeAssertion(options *ManagerOptions) {
	options.ExposeValidationErrors = true
}

func ManagerAllowWriteProtectedTraits(options *ManagerOptions) {
	options.AllowWriteProtectedTraits = true
}

// ManagerWithoutCredentialTypes excludes the given credential types from the
// identity persist: Update leaves their rows untouched. Strategies that
// persist those credentials themselves (e.g. through the locked
// UpdateCredentialsConfig path) set this so the persist cannot clobber a
// concurrent locked write.
func ManagerWithoutCredentialTypes(cts ...CredentialsType) ManagerOption {
	return func(options *ManagerOptions) {
		options.ExcludedCredentialTypes = append(options.ExcludedCredentialTypes, cts...)
	}
}

func newManagerOptions(opts []ManagerOption) *ManagerOptions {
	var o ManagerOptions
	for _, f := range opts {
		f(&o)
	}
	return &o
}

func (m *Manager) Create(ctx context.Context, i *Identity, opts ...ManagerOption) (err error) {
	ctx, span := m.r.Tracer(ctx).Tracer().Start(ctx, "identity.Manager.Create")
	defer otelx.End(span, &err)

	if i.SchemaID == "" {
		i.SchemaID = m.r.Config().DefaultIdentityTraitsSchemaID(ctx)
	}

	o := newManagerOptions(opts)
	if err := m.ValidateIdentity(ctx, i, o); err != nil {
		return err
	}

	if err := m.r.PrivilegedIdentityPool().CreateIdentity(ctx, i); err != nil {
		if errors.Is(err, sqlcon.ErrUniqueViolation()) {
			return m.findExistingAuthMethod(ctx, err, i)
		}
		return err
	}

	return nil
}

// maxParallelConflictLookups bounds how many conflict lookups run against the
// database concurrently.
const maxParallelConflictLookups = 8

// A match either carries the conflicting identity directly (credential lookup)
// or just its ID (address lookup).
type conflictMatch struct {
	found       *Identity
	identityID  uuid.UUID
	address     string
	addressType string
}

type conflictLookup func(ctx context.Context) (*conflictMatch, error)

// findFirstConflict returns the match of the lowest-index lookup, or
// sqlcon.ErrNoRows if no lookup matches. Outside a transaction all lookups run
// concurrently, bounded by maxParallelConflictLookups.
func findFirstConflict(ctx context.Context, lookups []conflictLookup) (*conflictMatch, error) {
	// Inside a transaction the single connection must not run concurrent queries, so the lookups run
	// sequentially and stop at the first match.
	if popx.InTransaction(ctx) {
		for _, lookup := range lookups {
			match, err := lookup(ctx)
			if errors.Is(err, sqlcon.ErrNoRows()) {
				continue
			} else if err != nil {
				return nil, err
			} else if match == nil {
				continue
			}
			return match, nil
		}
		return nil, sqlcon.ErrNoRows()
	}

	// Each goroutine records its own outcome (match and error) into a distinct
	// slice element, then always returns nil so the group never cancels a
	// still-running higher-priority lookup. After Wait the outcomes are resolved
	// in priority order, matching the sequential path: a lower-priority error
	// can neither mask a higher-priority match nor be returned
	// non-deterministically.
	type outcome struct {
		match *conflictMatch
		err   error
	}
	results := make([]outcome, len(lookups))
	eg := new(errgroup.Group)
	eg.SetLimit(maxParallelConflictLookups)
	for i, lookup := range lookups {
		eg.Go(func() error {
			match, err := lookup(ctx)
			if errors.Is(err, sqlcon.ErrNoRows()) {
				return nil
			}
			results[i] = outcome{match: match, err: err}
			return nil
		})
	}
	if err := eg.Wait(); err != nil {
		return nil, err
	}
	for _, r := range results {
		if r.err != nil {
			return nil, r.err
		}
		if r.match != nil {
			return r.match, nil
		}
	}
	return nil, sqlcon.ErrNoRows()
}

func (m *Manager) ConflictingIdentity(ctx context.Context, i *Identity) (found *Identity, foundConflictAddress string, conflictAddressType string, err error) {
	ctx, span := m.r.Tracer(ctx).Tracer().Start(ctx, "identity.Manager.ConflictingIdentity")
	defer otelx.End(span, &err)

	// Lookups are ordered by priority: credential identifiers first, then
	// verifiable addresses, then recovery addresses. The lowest-index match
	// wins, so the reported conflict is deterministic.
	var lookups []conflictLookup
	for _, ct := range slices.Sorted(maps.Keys(i.Credentials)) {
		for _, identifier := range i.Credentials[ct].Identifiers {
			lookups = append(lookups, func(ctx context.Context) (*conflictMatch, error) {
				conflicting, _, err := m.r.PrivilegedIdentityPool().FindByCredentialsIdentifier(ctx, ct, identifier)
				if err != nil {
					return nil, err
				}
				return &conflictMatch{found: conflicting, address: identifier, addressType: ct.String()}, nil
			})
		}
	}
	for _, va := range i.VerifiableAddresses {
		lookups = append(lookups, func(ctx context.Context) (*conflictMatch, error) {
			conflictingAddress, err := m.r.PrivilegedIdentityPool().FindVerifiableAddressByValue(ctx, va.Via, va.Value)
			if err != nil {
				return nil, err
			}
			return &conflictMatch{identityID: conflictingAddress.IdentityID, address: conflictingAddress.Value, addressType: va.Via}, nil
		})
	}
	for _, ra := range i.RecoveryAddresses {
		lookups = append(lookups, func(ctx context.Context) (*conflictMatch, error) {
			conflictingAddress, err := m.r.PrivilegedIdentityPool().FindRecoveryAddressByValue(ctx, ra.Via, ra.Value)
			if err != nil {
				return nil, err
			}
			return &conflictMatch{identityID: conflictingAddress.IdentityID, address: conflictingAddress.Value, addressType: ra.Via}, nil
		})
	}

	// Fanning out separate lookups (instead of a single UNION query in the
	// persister) composes with both the OSS and the multi-region persister,
	// which overrides FindByCredentialsIdentifier with region-aware logic.
	match, err := findFirstConflict(ctx, lookups)
	if err != nil {
		return nil, "", "", err
	}

	if match.found != nil {
		// FindByCredentialsIdentifier does not expand identity credentials.
		if err := m.r.PrivilegedIdentityPool().HydrateIdentityAssociations(ctx, match.found, ExpandCredentials); err != nil {
			return nil, "", "", err
		}
		return match.found, match.address, match.addressType, nil
	}
	conflicting, err := m.r.PrivilegedIdentityPool().GetIdentity(ctx, match.identityID, ExpandCredentials)
	if err != nil {
		return nil, "", "", err
	}
	return conflicting, match.address, match.addressType, nil
}

func (m *Manager) findExistingAuthMethod(ctx context.Context, e error, i *Identity) (err error) {
	if !m.r.Config().SelfServiceFlowRegistrationLoginHints(ctx) {
		return &ErrDuplicateCredentials{error: e}
	}

	found, foundConflictAddress, conflictingAddressType, err := m.ConflictingIdentity(ctx, i)
	if err != nil {
		if errors.Is(err, sqlcon.ErrNoRows()) {
			return &ErrDuplicateCredentials{error: e}
		}
		return err
	}

	// We need to sort the credentials for the error message to be deterministic.
	var creds []Credentials
	for _, cred := range found.Credentials {
		creds = append(creds, cred)
	}
	sort.Slice(creds, func(i, j int) bool {
		return creds[i].Type < creds[j].Type
	})

	duplicateCredErr := &ErrDuplicateCredentials{error: e}
	// OIDC credentials are not email addresses but the sub claim from the OIDC provider.
	// This is useless for the user, so in that case, we don't set the identifier hint.
	if conflictingAddressType != CredentialsTypeOIDC.String() {
		duplicateCredErr.SetIdentifierHint(strings.Trim(foundConflictAddress, " "))
	}

	for _, cred := range creds {
		if cred.Config == nil {
			continue
		}

		// Basically, we only have password, oidc, and webauthn as first factor credentials.
		// We don't care about second factor, because they don't help the user understand how to sign
		// in to the first factor (obviously).
		switch cred.Type {
		case CredentialsTypePassword:
			if duplicateCredErr.IdentifierHint() == "" && len(cred.Identifiers) == 1 {
				duplicateCredErr.SetIdentifierHint(cred.Identifiers[0])
			}

			var cfg CredentialsPassword
			if err := json.Unmarshal(cred.Config, &cfg); err != nil {
				// just ignore this credential if the config is invalid
				continue
			}
			if cfg.HashedPassword == "" {
				// just ignore this credential if the hashed password is empty
				continue
			}

			duplicateCredErr.AddCredentialsType(cred.Type)
		case CredentialsTypeCodeAuth:
			duplicateCredErr.AddCredentialsType(cred.Type)
		case CredentialsTypeOIDC:
			var cfg CredentialsOIDC
			if err := json.Unmarshal(cred.Config, &cfg); err != nil {
				return errors.WithStack(herodot.ErrInternalServerError().WithReasonf("Unable to JSON decode identity credentials %s for identity %s.", cred.Type, found.ID))
			}

			available := make([]string, 0, len(cfg.Providers))
			for _, provider := range cfg.Providers {
				available = append(available, provider.Provider)
			}

			duplicateCredErr.AddCredentialsType(cred.Type)
			duplicateCredErr.availableOIDCProviders = available
		case CredentialsTypeWebAuthn:
			var cfg CredentialsWebAuthnConfig
			if err := json.Unmarshal(cred.Config, &cfg); err != nil {
				return errors.WithStack(herodot.ErrInternalServerError().WithReasonf("Unable to JSON decode identity credentials %s for identity %s.", cred.Type, found.ID))
			}

			if duplicateCredErr.IdentifierHint() == "" && len(cred.Identifiers) == 1 {
				duplicateCredErr.SetIdentifierHint(cred.Identifiers[0])
			}
			for _, webauthn := range cfg.Credentials {
				if webauthn.IsPasswordless {
					duplicateCredErr.AddCredentialsType(cred.Type)
					break
				}
			}

			// DeviceAuthn is currently not to be used as a first factor.
		case CredentialsTypeDeviceAuthn:
			continue

		case CredentialsTypePasskey:
			var cfg CredentialsWebAuthnConfig
			if err := json.Unmarshal(cred.Config, &cfg); err != nil {
				return errors.WithStack(herodot.ErrInternalServerError().WithReasonf("Unable to JSON decode identity credentials %s for identity %s.", cred.Type, found.ID))
			}

			if duplicateCredErr.IdentifierHint() == "" && len(cred.Identifiers) == 1 {
				duplicateCredErr.SetIdentifierHint(cred.Identifiers[0])
			}
			for _, webauthn := range cfg.Credentials {
				if webauthn.IsPasswordless {
					duplicateCredErr.AddCredentialsType(cred.Type)
					break
				}
			}
		}
	}

	return duplicateCredErr
}

type ErrDuplicateCredentials struct {
	error

	availableCredentials   []CredentialsType
	availableOIDCProviders []string
	identifierHint         string
}

var _ schema.DuplicateCredentialsHinter = (*ErrDuplicateCredentials)(nil)

func (e *ErrDuplicateCredentials) Unwrap() error {
	return e.error
}

func (e *ErrDuplicateCredentials) AddCredentialsType(ct CredentialsType) {
	e.availableCredentials = append(e.availableCredentials, ct)
}

func (e *ErrDuplicateCredentials) SetIdentifierHint(hint string) {
	if hint != "" {
		e.identifierHint = hint
	}
}

func (e *ErrDuplicateCredentials) AvailableCredentials() []string {
	res := make([]string, len(e.availableCredentials))
	for k, v := range e.availableCredentials {
		res[k] = string(v)
	}
	slices.Sort(res)

	return res
}

func (e *ErrDuplicateCredentials) AvailableOIDCProviders() []string {
	if e.availableOIDCProviders == nil {
		return []string{}
	}
	slices.Sort(e.availableOIDCProviders)
	return e.availableOIDCProviders
}

func (e *ErrDuplicateCredentials) IdentifierHint() string {
	return e.identifierHint
}

func (e *ErrDuplicateCredentials) HasHints() bool {
	return len(e.availableCredentials) > 0 || len(e.availableOIDCProviders) > 0 || len(e.identifierHint) > 0
}

type FailedIdentity struct {
	Identity *Identity
	Error    *herodot.DefaultError
}

type CreateIdentitiesError struct {
	failedIdentities map[*Identity]*herodot.DefaultError
}

func NewCreateIdentitiesError(capacity int) *CreateIdentitiesError {
	return &CreateIdentitiesError{
		failedIdentities: make(map[*Identity]*herodot.DefaultError, capacity),
	}
}

func (e *CreateIdentitiesError) Error() string {
	e.init()
	return fmt.Sprintf("create identities error: %d identities failed", len(e.failedIdentities))
}

func (e *CreateIdentitiesError) Unwrap() []error {
	e.init()
	var errs []error
	for _, err := range e.failedIdentities {
		errs = append(errs, err)
	}
	return errs
}

func (e *CreateIdentitiesError) AddFailedIdentity(ident *Identity, err *herodot.DefaultError) {
	e.init()
	e.failedIdentities[ident] = err
}

func (e *CreateIdentitiesError) Merge(other *CreateIdentitiesError) {
	e.init()
	for k, v := range other.failedIdentities {
		e.failedIdentities[k] = v
	}
}

func (e *CreateIdentitiesError) Contains(ident *Identity) bool {
	e.init()
	_, found := e.failedIdentities[ident]
	return found
}

func (e *CreateIdentitiesError) Find(ident *Identity) *FailedIdentity {
	e.init()
	if err, found := e.failedIdentities[ident]; found {
		return &FailedIdentity{Identity: ident, Error: err}
	}

	return nil
}

func (e *CreateIdentitiesError) ErrOrNil() error {
	if e == nil || len(e.failedIdentities) == 0 {
		return nil
	}
	return e
}

func (e *CreateIdentitiesError) init() {
	if e.failedIdentities == nil {
		e.failedIdentities = map[*Identity]*herodot.DefaultError{}
	}
}

func (m *Manager) CreateIdentities(ctx context.Context, identities []*Identity, opts ...ManagerOption) (err error) {
	ctx, span := m.r.Tracer(ctx).Tracer().Start(ctx, "identity.Manager.CreateIdentities")
	defer otelx.End(span, &err)

	createIdentitiesError := NewCreateIdentitiesError(len(identities))
	validIdentities := make([]*Identity, 0, len(identities))
	for _, ident := range identities {
		if ident.SchemaID == "" {
			ident.SchemaID = m.r.Config().DefaultIdentityTraitsSchemaID(ctx)
		}

		o := newManagerOptions(opts)
		if err := m.ValidateIdentity(ctx, ident, o); err != nil {
			reason := err.Error()
			if e, ok := stderrors.AsType[*herodot.DefaultError](err); ok {
				reason = e.Reason()
			}
			createIdentitiesError.AddFailedIdentity(ident, herodot.ErrBadRequest().WithReason(reason).WithWrap(err))
			continue
		}
		validIdentities = append(validIdentities, ident)
	}

	if err := m.r.PrivilegedIdentityPool().CreateIdentities(ctx, validIdentities); err != nil {
		if partialErr := new(CreateIdentitiesError); errors.As(err, &partialErr) {
			createIdentitiesError.Merge(partialErr)
		} else {
			return err
		}
	}

	return createIdentitiesError.ErrOrNil()
}

func (m *Manager) requiresPrivilegedAccess(ctx context.Context, original, updated *Identity, o *ManagerOptions) (err error) {
	_, span := m.r.Tracer(ctx).Tracer().Start(ctx, "identity.Manager.requiresPrivilegedAccess")
	defer otelx.End(span, &err)

	switch {
	case o.AllowWriteProtectedTraits:
		return nil

	case !CredentialsEqual(updated.Credentials, original.Credentials),
		!VerifiableAddressesEqual(updated.VerifiableAddresses, original.VerifiableAddresses),
		!RecoveryAddressesEqual(updated.RecoveryAddresses, original.RecoveryAddresses):
		// reset the identity
		*updated = *original
		return errors.WithStack(ErrProtectedFieldModified())
	}

	return nil
}

func (m *Manager) Update(ctx context.Context, updated *Identity, opts ...ManagerOption) (err error) {
	ctx, span := m.r.Tracer(ctx).Tracer().Start(ctx, "identity.Manager.Update")
	defer otelx.End(span, &err)

	o := newManagerOptions(opts)
	if err := m.ValidateIdentity(ctx, updated, o); err != nil {
		return err
	}

	original, err := m.r.PrivilegedIdentityPool().GetIdentityConfidential(ctx, updated.ID)
	if err != nil {
		return err
	}

	if err := m.requiresPrivilegedAccess(ctx, original, updated, o); err != nil {
		return err
	}

	mods := []UpdateIdentityModifier{DiffAgainst(original)}
	if len(o.ExcludedCredentialTypes) > 0 {
		mods = append(mods, WithoutCredentialTypes(o.ExcludedCredentialTypes...))
	}
	return m.r.PrivilegedIdentityPool().UpdateIdentity(ctx, updated, mods...)
}

func (m *Manager) UpdateSchemaID(ctx context.Context, id uuid.UUID, schemaID string, opts ...ManagerOption) (err error) {
	ctx, span := m.r.Tracer(ctx).Tracer().Start(ctx, "identity.Manager.UpdateSchemaID")
	defer otelx.End(span, &err)

	o := newManagerOptions(opts)
	original, err := m.r.PrivilegedIdentityPool().GetIdentityConfidential(ctx, id)
	if err != nil {
		return err
	}

	if !o.AllowWriteProtectedTraits && original.SchemaID != schemaID {
		return errors.WithStack(ErrProtectedFieldModified())
	}

	original.SchemaID = schemaID
	if err := m.ValidateIdentity(ctx, original, o); err != nil {
		return err
	}

	return m.r.PrivilegedIdentityPool().UpdateIdentity(ctx, original)
}

func (m *Manager) SetTraits(ctx context.Context, id uuid.UUID, traits Traits, opts ...ManagerOption) (_ *Identity, err error) {
	ctx, span := m.r.Tracer(ctx).Tracer().Start(ctx, "identity.Manager.SetTraits")
	defer otelx.End(span, &err)

	o := newManagerOptions(opts)
	original, err := m.r.PrivilegedIdentityPool().GetIdentityConfidential(ctx, id)
	if err != nil {
		return nil, err
	}

	// original is used to check whether protected traits were modified
	updated := deepcopy.Copy(original).(*Identity)
	updated.Traits = traits
	if err := m.ValidateIdentity(ctx, updated, o); err != nil {
		return nil, err
	}

	if err := m.requiresPrivilegedAccess(ctx, original, updated, o); err != nil {
		return nil, err
	}

	return updated, nil
}

// RefreshAvailableAAL refreshes the available AAL for the identity.
//
// This method is a no-op if everything is up-to date.
//
// Please make sure to load all credentials before using this method.
func (m *Manager) RefreshAvailableAAL(ctx context.Context, i *Identity) (err error) {
	if len(i.Credentials) == 0 {
		if err := m.r.PrivilegedIdentityPool().HydrateIdentityAssociations(ctx, i, ExpandCredentials); err != nil {
			return err
		}
	}

	aalBefore := i.InternalAvailableAAL
	if err := i.SetAvailableAAL(ctx, m); err != nil {
		return err
	}

	if aalBefore.String != i.InternalAvailableAAL.String || aalBefore.Valid != i.InternalAvailableAAL.Valid {
		return m.r.PrivilegedIdentityPool().UpdateIdentityColumns(ctx, i, "available_aal")
	}

	return nil
}

func (m *Manager) UpdateTraits(ctx context.Context, id uuid.UUID, traits Traits, opts ...ManagerOption) (err error) {
	ctx, span := m.r.Tracer(ctx).Tracer().Start(ctx, "identity.Manager.UpdateTraits")
	defer otelx.End(span, &err)

	updated, err := m.SetTraits(ctx, id, traits, opts...)
	if err != nil {
		return err
	}

	return m.r.PrivilegedIdentityPool().UpdateIdentity(ctx, updated)
}

func (m *Manager) ValidateIdentity(ctx context.Context, i *Identity, o *ManagerOptions) (err error) {
	// Safeguard against callers that write to i.Credentials directly with a
	// Type field that does not match its map key. Must run before
	// IdentityValidator.Validate, because the schema-extension pass calls
	// SetCredentials and would silently repair Type — masking the bug
	// while still allowing the malformed Config to overwrite the existing
	// credential row.
	if err := ValidateCredentialsIntegrity(i.Credentials); err != nil {
		return err
	}

	if err := m.r.IdentityValidator().Validate(ctx, i); err != nil {
		var validationErr *jsonschema.ValidationError
		if errors.As(err, &validationErr) && !o.ExposeValidationErrors {
			return herodot.ErrBadRequest().WithReasonf("%s", err).WithWrap(err)
		}
		return err
	}

	if err := i.SetAvailableAAL(ctx, m); err != nil {
		return err
	}

	return nil
}

func (m *Manager) CountActiveFirstFactorCredentials(ctx context.Context, i *Identity) (count int, err error) {
	// This trace is more noisy than it's worth in diagnostic power.
	// ctx, span := m.r.Tracer(ctx).Tracer().Start(ctx, "identity.Manager.CountActiveFirstFactorCredentials")
	// defer otelx.End(span, &err)

	for _, strategy := range m.r.ActiveCredentialsCounterStrategies(ctx) {
		current, err := strategy.CountActiveFirstFactorCredentials(ctx, i.Credentials)
		if err != nil {
			return 0, err
		}

		count += current
	}
	return count, nil
}

func (m *Manager) CountActiveMultiFactorCredentials(ctx context.Context, i *Identity) (count int, err error) {
	// This trace is more noisy than it's worth in diagnostic power.
	// ctx, span := m.r.Tracer(ctx).Tracer().Start(ctx, "identity.Manager.CountActiveMultiFactorCredentials")
	// defer otelx.End(span, &err)

	for _, strategy := range m.r.ActiveCredentialsCounterStrategies(ctx) {
		current, err := strategy.CountActiveMultiFactorCredentials(ctx, i.Credentials)
		if err != nil {
			return 0, err
		}

		count += current
	}
	return count, nil
}

var ErrConcurrentModification = stderrors.New("concurrent modification detected")

// AddressRef identifies a verifiable address by its value and channel.
// Used by the notify_previous_addresses hook to persist the set of
// addresses that should receive a change notification.
type AddressRef struct {
	Value string `json:"value"`
	Via   string `json:"via"`
}

// sendIdentityNotifications queues a notification template to each target via
// the appropriate courier channel, sharing the courier, identity-model, and
// error-collection plumbing across the concrete notification types. buildEmail
// and buildSMS construct the channel-specific template for a single recipient
// from the identity model and a shared RFC3339 timestamp. Errors from individual
// targets are collected and returned as a joined error but do not short-circuit
// the batch — a failure to notify one recipient must not prevent others from
// being notified.
func (m *Manager) sendIdentityNotifications(
	ctx context.Context,
	spanName string,
	targets []AddressRef,
	i *Identity,
	buildEmail func(to string, identity map[string]any, at string) courier.EmailTemplate,
	buildSMS func(to string, identity map[string]any, at string) courier.SMSTemplate,
) (err error) {
	ctx, span := m.r.Tracer(ctx).Tracer().Start(ctx, spanName)
	defer otelx.End(span, &err)

	if len(targets) == 0 {
		return nil
	}

	c, err := m.r.Courier(ctx)
	if err != nil {
		return err
	}

	model, err := x.StructToMap(i)
	if err != nil {
		return errors.WithStack(err)
	}
	at := time.Now().UTC().Format(time.RFC3339)

	var errs []error
	for _, t := range targets {
		switch t.Via {
		case AddressTypeEmail:
			if _, qerr := c.QueueEmail(ctx, buildEmail(t.Value, model, at)); qerr != nil {
				m.r.Logger().WithError(qerr).
					WithField("via", t.Via).
					Warn("Failed to queue identity notification email.")
				errs = append(errs, qerr)
			}
		case AddressTypeSMS:
			if _, qerr := c.QueueSMS(ctx, buildSMS(t.Value, model, at)); qerr != nil {
				m.r.Logger().WithError(qerr).
					WithField("via", t.Via).
					Warn("Failed to queue identity notification SMS.")
				errs = append(errs, qerr)
			}
		default:
			m.r.Logger().
				WithField("via", t.Via).
				Warn("Skipping identity notification target with unsupported Via.")
		}
	}

	return stderrors.Join(errs...)
}

// SendVerifiableAddressChangedNotifications queues a change notification to
// each target via the appropriate courier channel. Errors from individual
// targets are collected and returned as a joined error but do not
// short-circuit the batch — a failure to notify one recipient should not
// prevent others from receiving their notification.
func (m *Manager) SendVerifiableAddressChangedNotifications(ctx context.Context, targets []AddressRef, i *Identity) error {
	return m.sendIdentityNotifications(ctx, "identity.Manager.SendVerifiableAddressChangedNotifications", targets, i,
		func(to string, identity map[string]any, at string) courier.EmailTemplate {
			return email.NewVerifiableAddressChanged(m.r, &email.VerifiableAddressChangedModel{To: to, Identity: identity, ChangedAt: at})
		},
		func(to string, identity map[string]any, at string) courier.SMSTemplate {
			return sms.NewVerifiableAddressChanged(m.r, &sms.VerifiableAddressChangedModel{To: to, Identity: identity, ChangedAt: at})
		},
	)
}

// SendAuthenticatorKeyAddedNotifications queues a security notification to each
// target via the appropriate courier channel after a new authenticator key was
// enrolled or an existing key's secret was rotated. Errors from individual
// targets are collected and returned as a joined error but do not short-circuit
// the batch — callers must never fail the enrollment/rotate flow on a courier
// error; they should log and continue.
func (m *Manager) SendAuthenticatorKeyAddedNotifications(ctx context.Context, targets []AddressRef, i *Identity) error {
	return m.sendIdentityNotifications(ctx, "identity.Manager.SendAuthenticatorKeyAddedNotifications", targets, i,
		func(to string, identity map[string]any, at string) courier.EmailTemplate {
			return email.NewAuthenticatorKeyAdded(m.r, &email.AuthenticatorKeyAddedModel{To: to, Identity: identity, AddedAt: at})
		},
		func(to string, identity map[string]any, at string) courier.SMSTemplate {
			return sms.NewAuthenticatorKeyAdded(m.r, &sms.AuthenticatorKeyAddedModel{To: to, Identity: identity, AddedAt: at})
		},
	)
}