challenge

type Address ¶

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

Address is an infrastructure boundary. Models retain their concrete key type in public flows; only persistence serializes identity.

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 {
	Issue(context.Context, Address, model.Identity, Digest, time.Duration, func(context.Context, *database.Tx) (Binding, error)) (Record, error)
	Consume(context.Context, Address, Digest, func(context.Context, *database.Tx, Record) error) (value.Optional[Record], error)
	Revoke(context.Context, Address, model.Identity) (bool, error)
	Prune(context.Context, Address, int) (uint64, error)
}

Backend owns a read-committed transaction for each operation, without retries. Issue locks the stable purpose/subject row, then invokes prepare exactly once in that transaction before replacing the previous token. Consume finds the hash, acquires the same subject lock, rechecks the current hash/expiry, invokes apply once, then removes the token in that SAME transaction. Before-commit errors/panic/Goexit/cancellation roll back model changes and consumption together. After-commit failures preserve a Committed database outcome; they cannot undo persistence. Never retry based only on the presence of an error. Callbacks must use only the supplied transaction for writes; no external I/O, detached work, nested challenge operations or additional pool acquisitions. Lock order is challenge subject, then application model. Stable subject rows remain after consumption. An uncertain commit returns an error and no result.

type Binding ¶

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

Binding fingerprints the exact account state relevant to a link. Password reset includes the current email AND stored hash; verification includes the current email. Recovery flows also include a persisted Revision, so restoring an old address cannot revive old links. Bind alone compares current values. Bindings are not passwords or standalone authenticators. Keep them private.

func Bind(parts ...secret.String) (Binding, error)

func BindRevision[M any](revision Revision[M], parts ...secret.String) (Binding, error)

func ParseBinding(text string) (Binding, error)

func (b Binding) Equal(other Binding) bool

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

func (b Binding) Hex() string

func (b Binding) IsZero() bool

type Config ¶

type Config struct {
	Namespace     keyspace.Namespace
	MaxConcurrent int
	Timeout       time.Duration
}

func DefaultConfig(namespace keyspace.Namespace) Config

func (c Config) Validate() error

type Digest ¶

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

Digest is a nominal challenge hash, never interchangeable with access tokens.

func HashSecret(raw secret.String) (Digest, error)

func ParseDigest(text string) (Digest, error)

func (d Digest) Equal(other Digest) bool

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

func (d Digest) Hex() string

func (d Digest) IsZero() bool

type EmailVerification ¶

type EmailVerification struct{}

type Flow ¶

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

func New[M model.Identifiable, K any, P Purpose](store *Store, provider auth.Provider[M, K], binding Model[M, K], lifetime time.Duration) (*Flow[M, K, P], error)

func (f *Flow[M, K, P]) Consume(ctx context.Context, token Token[M, P], apply func(context.Context, *database.Tx, M) (M, error)) (M, error)

func (f *Flow[M, K, P]) Issue(ctx context.Context, reference model.Reference[M, K]) (Issued[M, P], error)

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

func (f *Flow[M, K, P]) Revoke(ctx context.Context, reference model.Reference[M, K]) (bool, error)

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

type Issued ¶

type Issued[M any, P Purpose] struct {
	// contains filtered or unexported fields
}

Issued keeps delivery information private to ordinary formatting and JSON. Use the locked Subject snapshot's email when constructing a delivery message. No built-in email delivery is performed here, nor is publication crash durable.

func (i Issued[M, P]) ExpiresAt() temporal.DateTime

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

func (i Issued[M, P]) Subject() M

func (i Issued[M, P]) Token() Token[M, P]

type Issuer ¶

type Issuer[M model.Identifiable, K any, P Purpose] interface {
	Validate() error
	Issue(context.Context, model.Reference[M, K]) (Issued[M, P], error)
}

Issuer is the model/purpose contract implemented by Flow, passwordreset.Reset and emailverification.Verification. A requester borrows the configured issuer.

type Kind ¶

type Kind string

const (
	ResetPassword Kind = "password-reset"
	VerifyEmail   Kind = "email-verification"
)

type Model ¶

type Model[M model.Identifiable, K any] struct {
	Lock    func(context.Context, *database.Tx, K) (value.Optional[M], error)
	Binding func(M) (Binding, error)
	// Eligible optionally replaces the provider's login eligibility for this
	// flow, for example so email verification works before a provider that
	// requires verified addresses admits the account. Identity checks remain.
	// False rejects like a stale link. Omit it to reuse provider eligibility.
	Eligible func(context.Context, M) (bool, error)
}

Model owns only domain mapping. Lock must use a generated ForUpdate query on the supplied transaction and return an owned full model. Binding uses stored fields, never read getters or a stale model passed from an HTTP request.

type PasswordReset ¶

type PasswordReset struct{}

type Purpose ¶

type Purpose interface {
	PasswordReset | EmailVerification
}

Purpose is closed to the supported recovery operations. It is preserved in token and issuer types; a verification token cannot reset a password.

type Record ¶

type Record struct {
	Address   Address
	Subject   model.Identity
	Hash      Digest
	Binding   Binding
	CreatedAt temporal.DateTime
	ExpiresAt temporal.DateTime
}

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

func (r Record) Live(now time.Time) bool

func (r Record) Validate(address Address) error

type RequestCallbacks ¶

type RequestCallbacks[M model.Identifiable, K, I any, P Purpose] struct {
	Lookup  func(context.Context, I) (value.Optional[model.Reference[M, K]], error)
	Deliver func(context.Context, Issued[M, P]) error
}

RequestCallbacks maps a canonical submitted identifier to a model reference and delivers ONLY to the committed issuance's stored subject address. Lookup is domain-specific; it grants no authority. Issue locks and checks the current model again. Deliver runs after commit, outside database locks, at most once. Both run in the requester's owned background dispatch, not in the caller's request. Deliver's result is not crash durable: an email/outbox adapter owns durable dispatch (for example enqueue a job carrying the issued link).

type Requests ¶

type Requests[M model.Identifiable, K, I any, P Purpose] struct {
	// contains filtered or unexported fields
}

Requests owns public recovery-request orchestration and bounds all callbacks. It returns no token/model/existence flag. Request performs only the identifier's rate-limit admission synchronously, identical for existing and missing accounts, then hands lookup, issuance and delivery to a bounded background dispatch owned by the requester, so response latency does not depend on whether the account exists. Operational failures are logged safely. Close drains the owned dispatches at shutdown.

func NewRequests[M model.Identifiable, K, I any, P Purpose](issuer Issuer[M, K, P], limiter ratelimit.Limiter[I], callbacks RequestCallbacks[M, K, I, P], logger *slog.Logger, config auth.Config) (*Requests[M, K, I, P], error)

func (r *Requests[M, K, I, P]) Close(ctx context.Context) error

func (r *Requests[M, K, I, P]) Request(ctx context.Context, identifier I) error

func (r *Requests[M, K, I, P]) Validate() error

func (r *Requests[M, K, I, P]) Wait(ctx context.Context) error

type Revision ¶

type Revision[M any] = model.ID[RevisionOwner[M]]

Revision is a persisted recovery-state generation, using the existing typed UUID codec. It is not a secret, account ID or authentication capability. Keep it on the model and replace it transactionally when protected state changes; never restore an earlier revision when restoring an earlier field value.

func NewRevision[M any]() (Revision[M], error)

type RevisionOwner ¶

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

RevisionOwner keeps a recovery-state generation separate from a model's primary key, while retaining its model owner. It is a type marker, not a stored model.

type Store ¶

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

Store borrows its backend and bounds callback capacity across every flow.

func NewStore(backend Backend, config Config) (*Store, error)

func (s *Store) Validate() error

type Token ¶

type Token[M any, P Purpose] struct {
	// contains filtered or unexported fields
}

Token retains its model and recovery purpose. Parsing validates syntax only; storage and current model state decide whether it may be consumed. Ordinary JSON/logging redacts it. Secret is the explicit delivery/transport boundary.

func ParseToken[M any, P Purpose](raw secret.String) (Token[M, P], error)

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

func (Token[M, P]) JSONContract() contract.JSON[Token[M, P]]

func (Token[M, P]) LogValue() slog.Value

func (Token[M, P]) MarshalJSON() ([]byte, error)

func (t Token[M, P]) Secret() secret.String

func (t *Token[M, P]) UnmarshalJSON(data []byte) error

func (t Token[M, P]) Validate() error