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

identity/credentials.go

@@ -0,0 +1,356 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package identity
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/gofrs/uuid"
+	"github.com/pkg/errors"
+	"github.com/wI2L/jsondiff"
+
+	"github.com/ory/herodot"
+	"github.com/ory/kratos/ui/node"
+	"github.com/ory/x/sqlxx"
+)
+
+// Authenticator Assurance Level (AAL)
+//
+// The authenticator assurance level can be one of "aal1", "aal2", or "aal3". A higher number means that it is harder
+// for an attacker to compromise the account.
+//
+// Generally, "aal1" implies that one authentication factor was used while AAL2 implies that two factors (e.g.
+// password + TOTP) have been used.
+//
+// To learn more about these levels please head over to: https://www.ory.com/kratos/docs/concepts/credentials
+//
+// swagger:model authenticatorAssuranceLevel
+type AuthenticatorAssuranceLevel string
+
+const (
+	NoAuthenticatorAssuranceLevel AuthenticatorAssuranceLevel = "aal0"
+	AuthenticatorAssuranceLevel1  AuthenticatorAssuranceLevel = "aal1"
+	AuthenticatorAssuranceLevel2  AuthenticatorAssuranceLevel = "aal2"
+)
+
+type NullableAuthenticatorAssuranceLevel struct {
+	sql.NullString
+}
+
+// NewNullableAuthenticatorAssuranceLevel returns a new NullableAuthenticatorAssuranceLevel
+func NewNullableAuthenticatorAssuranceLevel(aal AuthenticatorAssuranceLevel) NullableAuthenticatorAssuranceLevel {
+	switch aal {
+	case NoAuthenticatorAssuranceLevel:
+		fallthrough
+	case AuthenticatorAssuranceLevel1:
+		fallthrough
+	case AuthenticatorAssuranceLevel2:
+		return NullableAuthenticatorAssuranceLevel{sql.NullString{
+			String: string(aal),
+			Valid:  true,
+		}}
+	default:
+		return NullableAuthenticatorAssuranceLevel{sql.NullString{}}
+	}
+}
+
+// ToAAL returns the AuthenticatorAssuranceLevel value of the given NullableAuthenticatorAssuranceLevel.
+func (n NullableAuthenticatorAssuranceLevel) ToAAL() (AuthenticatorAssuranceLevel, bool) {
+	if !n.Valid {
+		return "", false
+	}
+	switch n.String {
+	case string(NoAuthenticatorAssuranceLevel):
+		return NoAuthenticatorAssuranceLevel, true
+	case string(AuthenticatorAssuranceLevel1):
+		return AuthenticatorAssuranceLevel1, true
+	case string(AuthenticatorAssuranceLevel2):
+		return AuthenticatorAssuranceLevel2, true
+	default:
+		return "", false
+	}
+}
+
+// CredentialsType  represents several different credential types, like password credentials, passwordless credentials,
+// and so on.
+//
+// swagger:enum CredentialsType
+type CredentialsType string
+
+// Please make sure to add all of these values to the test that ensures they are created during migration
+const (
+	CredentialsTypePassword        CredentialsType = "password"
+	CredentialsTypeOIDC            CredentialsType = "oidc"
+	CredentialsTypeTOTP            CredentialsType = "totp"
+	CredentialsTypeLookup          CredentialsType = "lookup_secret"
+	CredentialsTypeWebAuthn        CredentialsType = "webauthn"
+	CredentialsTypeCodeAuth        CredentialsType = "code"
+	CredentialsTypePasskey         CredentialsType = "passkey"
+	CredentialsTypeProfile         CredentialsType = "profile"
+	CredentialsTypeSAML            CredentialsType = "saml"
+	CredentialsTypeDeviceAuthn     CredentialsType = "deviceauthn"
+	CredentialsTypeIdentifierFirst CredentialsType = "identifier_first" // TODO(jonas): Used only for SDK compatibility. We should refactor all the places that use "CredentialType" as a method identifier (flow.Active fields, etc.)
+)
+
+func (c CredentialsType) String() string {
+	return string(c)
+}
+
+func (c CredentialsType) ToUiNodeGroup() node.UiNodeGroup {
+	switch c {
+	case CredentialsTypePassword:
+		return node.PasswordGroup
+	case CredentialsTypeOIDC, CredentialsTypeSAML:
+		return node.OpenIDConnectGroup
+	case CredentialsTypeTOTP:
+		return node.TOTPGroup
+	case CredentialsTypeWebAuthn:
+		return node.WebAuthnGroup
+	case CredentialsTypeLookup:
+		return node.LookupGroup
+	case CredentialsTypeCodeAuth:
+		return node.CodeGroup
+	case CredentialsTypePasskey:
+		return node.PasskeyGroup
+	case CredentialsTypeDeviceAuthn:
+		return node.DeviceAuthnGroup
+	case CredentialsTypeIdentifierFirst:
+		return node.IdentifierFirstGroup
+	default:
+		return node.DefaultGroup
+	}
+}
+
+var AllCredentialTypes = []CredentialsType{
+	CredentialsTypePassword,
+	CredentialsTypeOIDC,
+	// CredentialsTypeSAML, placeholder for the OEL version
+	CredentialsTypeTOTP,
+	CredentialsTypeLookup,
+	CredentialsTypeWebAuthn,
+	CredentialsTypeCodeAuth,
+	CredentialsTypePasskey,
+	CredentialsTypeDeviceAuthn,
+}
+
+const (
+	// CredentialsTypeRecoveryLink is a special credential type linked to the link strategy (recovery flow).
+	// It is not used within the credentials object itself.
+	CredentialsTypeRecoveryLink CredentialsType = "link_recovery"
+	CredentialsTypeRecoveryCode CredentialsType = "code_recovery"
+)
+
+// ParseCredentialsType parses a string into a CredentialsType or returns false as the second argument.
+func ParseCredentialsType(in string) (CredentialsType, bool) {
+	switch t := CredentialsType(in); t {
+	case CredentialsTypePassword,
+		CredentialsTypeOIDC,
+		CredentialsTypeSAML,
+		CredentialsTypeTOTP,
+		CredentialsTypeLookup,
+		CredentialsTypeWebAuthn,
+		CredentialsTypeCodeAuth,
+		CredentialsTypeRecoveryLink,
+		CredentialsTypeRecoveryCode,
+		CredentialsTypeDeviceAuthn,
+		CredentialsTypePasskey:
+		return t, true
+	}
+	return "", false
+}
+
+// Credentials represents a specific credential type
+//
+// swagger:model identityCredentials
+type Credentials struct {
+	ID uuid.UUID `json:"-" db:"id"`
+
+	// Type discriminates between different types of credentials.
+	Type                     CredentialsType `json:"type" db:"-"`
+	IdentityCredentialTypeID uuid.UUID       `json:"-" db:"identity_credential_type_id"`
+
+	// Identifiers represent a list of unique identifiers this credential type matches.
+	Identifiers []string `json:"identifiers" db:"-"`
+
+	// Config contains the concrete credential payload. This might contain the bcrypt-hashed password, the email
+	// for passwordless authentication or access_token and refresh tokens from OpenID Connect flows.
+	Config sqlxx.JSONRawMessage `json:"config,omitempty" db:"config"`
+
+	// Version refers to the version of the credential. Useful when changing the config schema.
+	Version int `json:"version" db:"version"`
+
+	IdentityID uuid.UUID `json:"-" faker:"-" db:"identity_id"`
+
+	// CreatedAt is a helper struct field for gobuffalo.pop.
+	CreatedAt time.Time `json:"created_at" db:"created_at"`
+
+	// UpdatedAt is a helper struct field for gobuffalo.pop.
+	UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
+	NID       uuid.UUID `json:"-"  faker:"-" db:"nid"`
+}
+
+func (c Credentials) TableName(context.Context) string {
+	return "identity_credentials"
+}
+
+func (c Credentials) GetID() uuid.UUID {
+	return c.ID
+}
+
+// Signature returns a unique string signature for the credential.
+func (c Credentials) Signature() string {
+	sortedIdentifiers := slices.Clone(c.Identifiers)
+	slices.Sort(sortedIdentifiers)
+	identifiersStr := strings.Join(sortedIdentifiers, ",")
+
+	// Normalize JSON config to remove whitespace and key ordering differences
+	var normalizedConfig any
+	if len(c.Config) > 0 {
+		if err := json.Unmarshal(c.Config, &normalizedConfig); err != nil {
+			// there is not much we can do when unmarshal fails except use the raw value
+			normalizedConfig = c.Config
+		}
+	}
+	return fmt.Sprintf("%v|%v|%d|%+v|%v|%v", c.Type, identifiersStr, c.Version, normalizedConfig, c.IdentityID, c.NID)
+}
+
+type (
+	// swagger:ignore
+	CredentialIdentifier struct {
+		ID                        uuid.UUID  `db:"id"`
+		Identifier                string     `db:"identifier"`
+		IdentityID                *uuid.UUID `json:"-" db:"identity_id"`
+		IdentityCredentialsID     uuid.UUID  `json:"-" db:"identity_credential_id"`
+		IdentityCredentialsTypeID uuid.UUID  `json:"-" db:"identity_credential_type_id"`
+		CreatedAt                 time.Time  `json:"created_at" db:"created_at"`
+		UpdatedAt                 time.Time  `json:"updated_at" db:"updated_at"`
+		NID                       uuid.UUID  `json:"-"  faker:"-" db:"nid"`
+	}
+
+	// swagger:ignore
+	CredentialsTypeTable struct {
+		ID   uuid.UUID       `json:"-" db:"id"`
+		Name CredentialsType `json:"-" db:"name"`
+	}
+
+	// swagger:ignore
+	ActiveCredentialsCounter interface {
+		ID() CredentialsType
+		CountActiveFirstFactorCredentials(context.Context, map[CredentialsType]Credentials) (int, error)
+		CountActiveMultiFactorCredentials(context.Context, map[CredentialsType]Credentials) (int, error)
+	}
+
+	// swagger:ignore
+	ActiveCredentialsCounterStrategyProvider interface {
+		ActiveCredentialsCounterStrategies(context.Context) []ActiveCredentialsCounter
+	}
+)
+
+func (c CredentialsTypeTable) TableName(context.Context) string {
+	return "identity_credential_types"
+}
+
+func (c CredentialIdentifier) TableName(context.Context) string {
+	return "identity_credential_identifiers"
+}
+
+// ValidateCredentialsIntegrity returns a BadRequest error if any entry in
+// the credentials map has a Type field that does not equal its map key.
+//
+// The internal helpers (SetCredentials, SetCredentialsWithConfig,
+// UpsertCredentialsConfig) always force these two to match, so this only
+// trips for callers that write to the map directly — notably the PATCH
+// /admin/identities/{id} handler, which decodes the patched JSON straight
+// into Identity. Caught early, this is a malformed request. Caught late,
+// it has two destructive failure modes: a misleading 500 from the
+// persister when the type is unknown, or a silent overwrite of the
+// existing credential's config (e.g. hashed_password) when schema
+// validation later repairs Type but not Config.
+func ValidateCredentialsIntegrity(creds map[CredentialsType]Credentials) error {
+	for k, c := range creds {
+		if c.Type != k {
+			return errors.WithStack(herodot.ErrBadRequest().WithReasonf(
+				"credentials.%s.type must equal %q, got %q", k, string(k), string(c.Type),
+			))
+		}
+	}
+	return nil
+}
+
+func CredentialsEqual(a, b map[CredentialsType]Credentials) bool {
+	if len(a) != len(b) {
+		return false
+	}
+
+	if len(a) == 0 && len(b) == 0 {
+		return true
+	}
+
+	for k, expect := range b {
+		actual, found := a[k]
+		if !found {
+			return false
+		}
+
+		// Try to normalize configs (remove spaces etc).
+		patch, err := jsondiff.CompareJSON(actual.Config, expect.Config)
+		if err != nil {
+			return false
+		}
+
+		if len(patch) > 0 {
+			return false
+		}
+
+		expectIdentifiers, actualIdentifiers := make(map[string]struct{}, len(expect.Identifiers)), make(map[string]struct{}, len(actual.Identifiers))
+		for _, i := range expect.Identifiers {
+			expectIdentifiers[i] = struct{}{}
+		}
+		for _, i := range actual.Identifiers {
+			actualIdentifiers[i] = struct{}{}
+		}
+		if !reflect.DeepEqual(expectIdentifiers, actualIdentifiers) {
+			return false
+		}
+	}
+
+	return true
+}
+
+// UpdateConfig adapts a typed, in-place credential-config mutation into the
+// raw mutate form PrivilegedPool.UpdateCredentialsConfig takes:
+//
+//	pool.UpdateCredentialsConfig(ctx, id, ct, identity.UpdateConfig(mutate))
+//
+// T must model the complete stored config shape: unknown fields do not
+// survive the roundtrip. An empty or JSON-null config is rejected before
+// mutate runs. mutate must be pure (it may run more than once on database
+// retries); returning an error aborts without persisting.
+func UpdateConfig[T any](mutate func(*T) error) func(config []byte) ([]byte, error) {
+	return func(config []byte) ([]byte, error) {
+		if len(config) == 0 || bytes.Equal(config, []byte("null")) {
+			return nil, errors.WithStack(herodot.ErrInternalServerError().WithReason("The stored credential configuration is empty and cannot be updated."))
+		}
+		var decoded T
+		if err := json.Unmarshal(config, &decoded); err != nil {
+			return nil, errors.WithStack(herodot.ErrInternalServerError().WithReason("The stored credential configuration could not be decoded.").WithDebug(err.Error()).WithWrap(err))
+		}
+		if err := mutate(&decoded); err != nil {
+			return nil, err
+		}
+		encoded, err := json.Marshal(&decoded)
+		if err != nil {
+			return nil, errors.WithStack(herodot.ErrInternalServerError().WithReason("The updated credential configuration could not be encoded.").WithDebug(err.Error()).WithWrap(err))
+		}
+		return encoded, nil
+	}
+}