mfa

type AMRProvider interface {
	AMR() []string
}

type AsyncMethod interface {
	Async() bool
}

type BackupMethod interface {
	Backup() bool
}

type CallbackHandler interface {
	HandleCallback(ctx *azugo.Context) error
}

type Driver interface {
	// Open creates a Method over the shared store from the configuration entry.
	Open(store Store, cfg *contract.MFAMethodConfig) (Method, error)
}

type Enrollment struct {
	ID     string
	UserID string
	Method string
	// Label is the user-facing name of the device or app.
	Label string
	// Secret is the driver-specific enrollment data; never surfaced to clients.
	Secret     []byte
	CreatedAt  time.Time
	LastUsedAt *time.Time
}

type EnrollmentData struct {
	// Data is surfaced to the client, e.g. {"secret":"...","uri":"otpauth://..."} for TOTP.
	Data map[string]any
	// State is opaque driver state the library hands back to FinishEnroll; never surfaced.
	State []byte
}

type ExclusiveMethod interface {
	Exclusive() bool
}

type Method interface {
	// BeginEnroll returns enrollment data for the user.
	BeginEnroll(ctx context.Context, userID string, info contract.UserInfo) (EnrollmentData, error)
	// FinishEnroll verifies the enrollment response against state and returns the secret the
	// library stores; a wrong response returns ErrInvalidResponse.
	FinishEnroll(ctx context.Context, userID string, state []byte, response map[string]any) ([]byte, error)
	// BeginVerify starts a challenge across the user's enrollments. challengeID is the opaque
	// server-side handle; data is surfaced to the client. Both are empty for self-contained
	// methods (TOTP).
	BeginVerify(ctx context.Context, userID string) (challengeID string, data map[string]any, err error)
	// Verify evaluates response against challengeID and the user's enrollments. response is nil
	// when polling an async method.
	Verify(ctx context.Context, userID, challengeID string, response map[string]any) (Verification, error)
}

type Registry interface {
	// Get returns the method available under name, or ErrUnknownMethod.
	Get(ctx context.Context, name string) (Method, error)
	// Names returns every available method name, configured entries first.
	Names(ctx context.Context) ([]string, error)
}

type Store interface {
	// List returns userID's enrollments, oldest first.
	List(ctx context.Context, userID string) ([]*Enrollment, error)
	// Enroll persists e under its ID, replacing an enrollment with the same ID.
	Enroll(ctx context.Context, e *Enrollment) error
	// CompareAndSwap replaces the secret of userID's enrollment id only when its current value
	// equals expected. It returns false when the enrollment is missing or has changed, allowing
	// one-time factors to be consumed exactly once across concurrent requests.
	CompareAndSwap(ctx context.Context, userID, id string, expected, replacement []byte) (bool, error)
	// Touch records that userID's enrollment id passed verification at at, or ErrNotEnrolled.
	Touch(ctx context.Context, userID, id string, at time.Time) error
	// Revoke removes userID's enrollment id, or ErrNotEnrolled.
	Revoke(ctx context.Context, userID, id string) error
}

type Verification struct {
	Result VerifyResult
	// EnrollmentID names the enrollment that satisfied the factor, when the method knows it.
	EnrollmentID string
}

type VerifyResult string