mfa

type Action ¶

type Action string

Action identifies an MFA security observation, never a credential or authority.

const (
	Enrolled            Action = "enrolled"
	Disabled            Action = "disabled"
	Verified            Action = "verified"
	RecoveryRegenerated Action = "recovery_regenerated"
	Reencrypted         Action = "reencrypted"
	Retired             Action = "retired"
	Rejected            Action = "rejected"
)

type Address ¶

type Address struct {
	Namespace keyspace.Namespace
	Provider  auth.ProviderName
	Model     string
}

Address is the persistence boundary. A model/provider shares one TOTP factor across its guards; guard names do not create independent factor enrollments.

func (a Address) Key() (string, error)

func (a Address) SubjectKey(identity model.Identity) (string, error)

func (a Address) Validate() error

type Backend ¶

type Backend interface {
	Within(context.Context, Address, model.Identity, func(context.Context, *database.Tx) error, func(context.Context, *database.Tx, value.Optional[Record], temporal.DateTime) (Change, error)) (value.Optional[Record], error)
	Prune(context.Context, Address, int) (uint64, error)
}

Backend owns one read-committed transaction. Within invokes prepare exactly once to lock the application model BEFORE reading/locking the factor record. That model lock serializes creation even when no factor row exists. It then calls change once with owned state and server time, validates its result and deadline, persists it and commits. Callback errors, panic/Goexit or cancellation roll back all database changes. Never suppress failures, detach callbacks, retry mutations or acquire model locks after factor/credential locks.

Callbacks use only the supplied transaction for database writes. The runtime may consult its bounded MFA lockout store before protected writes; external effects (email, publishing) require an outbox. After-commit failure may retain a Committed database outcome; an error is not permission to retry blindly. Prune deletes only expired pending factors and acquires no model locks.

type Change ¶

type Change struct {
	// contains filtered or unexported fields
}

Change explicitly selects replacement or removal. Zero is invalid. Before adds a strict pre-commit deadline, used to prevent late enrollment confirmation.

func Remove() Change

func Replace(record Record) Change

func (c Change) Before(until temporal.DateTime) Change

func (c Change) Deadline() value.Optional[temporal.DateTime]

func (c Change) Next() value.Optional[Record]

func (c Change) Removes() bool

func (c Change) Validate(address Address, subject model.Identity) error

type Config ¶

type Config struct {
	Namespace          keyspace.Namespace
	Issuer             string
	EnrollmentLifetime time.Duration
	Window             int
	RecoveryCodes      int
	MaxConcurrent      int
	Timeout            time.Duration
}

func DefaultConfig(namespace keyspace.Namespace, issuer string) Config

func (c Config) Validate() error

type Enrollment ¶

type Enrollment[M any] struct {
	// contains filtered or unexported fields
}

Enrollment is returned only after the pending encrypted factor commits. Secret and URI are explicit disclosure boundaries for the enrolled account.

func (e Enrollment[M]) CreatedAt() temporal.DateTime

func (e Enrollment[M]) ExpiresAt() temporal.DateTime

func (Enrollment[M]) Format(s fmt.State, _ rune)

func (e Enrollment[M]) ID() EnrollmentID[M]

func (e Enrollment[M]) Secret() TOTPSecret

func (e Enrollment[M]) Subject() M

func (e Enrollment[M]) URI() secret.String

type EnrollmentID ¶

type EnrollmentID[M any] struct {
	// contains filtered or unexported fields
}

EnrollmentID preserves the model type. Parsing identifies a pending factor; it does not authenticate or authorize confirmation.

func ParseEnrollmentID[M any](text string) (EnrollmentID[M], error)

func (id EnrollmentID[M]) IsZero() bool

func (EnrollmentID[M]) JSONContract() contract.JSON[EnrollmentID[M]]

func (id EnrollmentID[M]) MarshalJSON() ([]byte, error)

func (id EnrollmentID[M]) String() string

func (id *EnrollmentID[M]) UnmarshalJSON(data []byte) error

type Factors ¶

type Factors[M model.Identifiable, K any] struct {
	// contains filtered or unexported fields
}

Factors owns one model/provider's TOTP factor across guards. A separate typed MFA throttle is mandatory; never reuse the password-attempt declaration.

func New[M model.Identifiable, K any](store *Store, provider auth.Provider[M, K], binding Model[M, K], attempts lockout.Throttle[K]) (*Factors[M, K], error)

func (f *Factors[M, K]) Confirm(ctx context.Context, password auth.PasswordResult[M, K], id EnrollmentID[M], code TOTPCode) (RecoveryCodes[M], error)

func (f *Factors[M, K]) Disable(ctx context.Context, password auth.PasswordResult[M, K], response Response) (M, error)

func (f *Factors[M, K]) Enroll(ctx context.Context, password auth.PasswordResult[M, K]) (Enrollment[M], error)

func (f *Factors[M, K]) HasEnrolledFactor(_ context.Context, subject M) (bool, error)

func (f *Factors[M, K]) Prune(ctx context.Context, limit int) (uint64, error)

func (f *Factors[M, K]) Reencrypt(ctx context.Context, password auth.PasswordResult[M, K], response Response) error

func (f *Factors[M, K]) RegenerateRecovery(ctx context.Context, password auth.PasswordResult[M, K], response Response) (RecoveryCodes[M], error)

func (f *Factors[M, K]) RetireIn(ctx context.Context, parent *database.Tx, reference model.Reference[M, K]) (M, error)

func (f *Factors[M, K]) Validate() error

func (f *Factors[M, K]) Verifier(response Response) (auth.SecondFactor[M, K], error)

func (f *Factors[M, K]) WithObserver(observer Observer[M, K]) (*Factors[M, K], error)

type Model ¶

type Model[M model.Identifiable, K any] struct {
	Lock         func(context.Context, *database.Tx, K) (value.Optional[M], error)
	Enabled      func(M) bool
	SetEnabled   func(context.Context, *database.Tx, M, bool) (M, error)
	AccountLabel func(M) (string, error)
	CanDisable   func(context.Context, M) (bool, error)
	Invalidate   func(context.Context, *database.Tx, M) error
}

Model maps stored fields and normal generated mutations to MFA. Lock uses a generated ForUpdate query on the supplied transaction and preserves K. SetEnabled returns the complete updated model and must preserve identity. Invalidate joins tx (for example auth.Revocations.Invalidate) and revokes every registered credential guard. CanDisable enforces required-factor domain policy. Link the factors to login with PasswordLogin.WithSecondFactor(factors): an enrolled model then always requires MFA, whatever RequiresMFA returns. Callbacks must not commit, retry, send external messages or acquire other pools.

type Notice ¶

type Notice[M any, K any] struct {
	// contains filtered or unexported fields
}

Notice exposes only the affected typed reference and action. It contains no model snapshot, password, factor secret, submitted code or credential. The initiator remains attribution.FromContext(ctx); affected subject is not actor.

func (n Notice[M, K]) Action() Action

func (Notice[M, K]) Format(s fmt.State, _ rune)

func (n Notice[M, K]) Subject() model.Reference[M, K]

type Observer ¶

type Observer[M any, K any] struct {
	Changed  func(context.Context, *database.Tx, Notice[M, K]) error
	Rejected func(context.Context, Notice[M, K]) error
}

Observer maps MFA observations to application-owned event DTOs. Changed runs inside the mutation transaction: use events.Topic.Enqueue for durable dispatch, events.Topic.AfterCommit for process-local dispatch, or audit through this tx. Never perform external I/O there. Failure rolls back factor/model/credentials. Rejected is an immediate, process-local observation of a nonmatching factor or confirmed lockout. The enclosing mutation rolls back; do not persist a rejection through that transaction. No callback runs for malformed input, absent/inactive factors, missing models or infrastructure failures. Rejected errors remain causes of the denial and cannot turn it into success.

type Record ¶

type Record struct {
	ID             model.ID[Record]
	Address        Address
	Subject        model.Identity
	Ciphertext     encryption.Ciphertext
	CreatedAt      temporal.DateTime
	PendingUntil   value.Optional[temporal.DateTime]
	ConfirmedAt    value.Optional[temporal.DateTime]
	LastStep       value.Optional[int64]
	RecoveryHashes []RecoveryHash
}

Record is the trusted storage-adapter boundary, never a transport DTO. A pending record has an expiry but no confirmation, replay step or recovery hashes. A confirmed record has no pending expiry. ID changes on reenrollment.

func (r Record) Clone() Record

func (Record) Format(s fmt.State, _ rune)

func (Record) LogValue() slog.Value

func (Record) MarshalJSON() ([]byte, error)

func (r Record) Validate(address Address, subject model.Identity) error

type RecoveryCode ¶

type RecoveryCode struct {
	// contains filtered or unexported fields
}

RecoveryCode is a distinct canonical 256-bit random factor encoded as 43 unpadded base64url characters. It is not a password, TOTP code or proof. Only the digest is persisted; consumption must be atomic with factor completion.

func ParseRecoveryCode(raw secret.String) (RecoveryCode, error)

func (RecoveryCode) Format(s fmt.State, _ rune)

func (RecoveryCode) JSONContract() contract.JSON[RecoveryCode]

func (RecoveryCode) LogValue() slog.Value

func (RecoveryCode) MarshalJSON() ([]byte, error)

func (c RecoveryCode) Secret() secret.String

func (c *RecoveryCode) UnmarshalJSON(data []byte) error

func (c RecoveryCode) Validate() error

type RecoveryCodes ¶

type RecoveryCodes[M any] struct {
	// contains filtered or unexported fields
}

RecoveryCodes exposes an owned slice only after the factor mutation commits. Ordinary serialization cannot disclose the private collection or model.

func (r RecoveryCodes[M]) Codes() []RecoveryCode

func (RecoveryCodes[M]) Format(s fmt.State, _ rune)

func (r RecoveryCodes[M]) ID() EnrollmentID[M]

func (r RecoveryCodes[M]) Subject() M

type RecoveryHash ¶

type RecoveryHash struct {
	// contains filtered or unexported fields
}

RecoveryHash is a redacted SHA-256 digest of a high-entropy RecoveryCode, sharing the credential-hash implementation used by sessions and tokens. Encoded is an explicit persistence boundary, never an authentication proof.

func ParseRecoveryHash(encoded string) (RecoveryHash, error)

func (h RecoveryHash) Encoded() string

func (RecoveryHash) Format(s fmt.State, _ rune)

func (h RecoveryHash) IsZero() bool

func (RecoveryHash) LogValue() slog.Value

func (RecoveryHash) MarshalJSON() ([]byte, error)

type Response ¶

type Response struct {
	// contains filtered or unexported fields
}

Response is an explicit choice of TOTP or recovery factor. Enrollment confirmation accepts only TOTPCode and cannot receive this alternative.

func RecoveryResponse(code RecoveryCode) (Response, error)

func TOTPResponse(code TOTPCode) (Response, error)

func (Response) Format(s fmt.State, _ rune)

func (r Response) Validate() error

type Rotation ¶

type Rotation struct {
	Reencrypted uint64
	Changed     uint64
	Failed      uint64
	Next        RotationCursor
	Done        bool
}

Rotation reports one bounded batch. Reencrypted counts committed replacements; Changed counts factors that changed concurrently (a later run re-examines them if still stale); Failed counts envelopes that could not be decrypted with the retained keys. Done reports that no stale factor remained after Next when the batch was read.

type RotationBackend ¶

type RotationBackend interface {
	// StaleCiphertexts returns at most limit factors whose envelope was not
	// produced by the active key, ordered by Owner and strictly after the
	// cursor (empty starts from the beginning).
	StaleCiphertexts(ctx context.Context, active encryption.KeyID, after string, limit int) ([]StoredCiphertext, error)
	// ReplaceCiphertext stores next only while the factor still has the same
	// owner, generation and envelope. False means it changed concurrently.
	ReplaceCiphertext(ctx context.Context, stored StoredCiphertext, next encryption.Ciphertext) (bool, error)
}

RotationBackend is the storage contract for password-free key rotation across every address sharing the store. Implementations never load domain models.

type RotationCursor ¶

type RotationCursor struct {
	// contains filtered or unexported fields
}

RotationCursor resumes rotation after the last examined factor. The zero value starts from the beginning. It is opaque and not a model reference.

func (c RotationCursor) IsZero() bool

type Store ¶

type Store struct {
	// contains filtered or unexported fields
}

Store borrows a transactional backend and immutable encryption keyring. One store bounds work across all model bindings. Construction performs no I/O.

func NewStore(backend Backend, keys *encryption.Keyring, config Config) (*Store, error)

func (s *Store) ReencryptStale(ctx context.Context, after RotationCursor, limit int) (Rotation, error)

func (s *Store) Validate() error

type StoredCiphertext ¶

type StoredCiphertext struct {
	Owner      string
	Generation model.ID[Record]
	Ciphertext encryption.Ciphertext
}

StoredCiphertext is one stored factor envelope selected for key rotation. It carries the opaque subject key and factor generation that bind the envelope's encryption context, never a model, identity or plaintext.

type TOTPCode ¶

type TOTPCode struct {
	// contains filtered or unexported fields
}

TOTPCode preserves six ASCII digits, including leading zeroes. It is a typed unverified input. No trimming, Unicode digit conversion or truncation occurs.

func ParseTOTPCode(raw secret.String) (TOTPCode, error)

func (TOTPCode) Format(s fmt.State, _ rune)

func (TOTPCode) JSONContract() contract.JSON[TOTPCode]

func (TOTPCode) LogValue() slog.Value

func (TOTPCode) MarshalJSON() ([]byte, error)

func (c TOTPCode) Secret() secret.String

func (c *TOTPCode) UnmarshalJSON(data []byte) error

func (c TOTPCode) Validate() error

type TOTPSecret ¶

type TOTPSecret struct {
	// contains filtered or unexported fields
}

TOTPSecret is a canonical unpadded uppercase base32 160-bit secret. Only Secret deliberately reveals it for encrypted persistence or authenticated enrollment delivery. Plain database storage and ordinary response serialization are not supported. This type does not promise memory erasure.

func GenerateTOTPSecret() (TOTPSecret, error)

func ParseTOTPSecret(encoded secret.String) (TOTPSecret, error)

func (TOTPSecret) Format(s fmt.State, _ rune)

func (TOTPSecret) LogValue() slog.Value

func (TOTPSecret) MarshalJSON() ([]byte, error)

func (s TOTPSecret) Secret() secret.String

func (s TOTPSecret) Validate() error

type TransactionalBackend ¶

type TransactionalBackend interface {
	WithinIn(context.Context, *database.Tx, Address, model.Identity, func(context.Context, *database.Tx) error, func(context.Context, *database.Tx, value.Optional[Record], temporal.DateTime) (Change, error)) (value.Optional[Record], error)
}

TransactionalBackend joins the credential creation transaction. It verifies exact pool ownership, uses a savepoint, restores schema settings and never commits. The same model-before-factor ordering and callback rules apply.