protocol

type AuthResponse ¶

type AuthResponse struct {
	Result   AuthResult
	Username string
	Home     string
	MailLoc  string
	// Groups is the list of supplementary groups the user belongs to,
	// sourced from the userdb `groups=` extra field. Used by ACL
	// evaluation to match `group=` and `group-override=` entries.
	// Empty when not configured — group= ACL entries have no effect.
	Groups []string

	// QuotaRules is the list of per-user quota rules sourced from the
	// userdb `quota_rule=` extra field. Format: `*:storage=5G`.
	QuotaRules []string

	// VolatileDir is the VOLATILEDIR modifier from the mail location (or
	// direct volatile_dir= userdb field). Carries the raw template string
	// (%u/%n/%d/%h unexpanded) — callers expand it against the resolved
	// home after auth completes.
	VolatileDir string

	// IndexDir is the INDEX= modifier from the mail location (or direct
	// index_dir= userdb field). Carries the raw template string
	// (%u/%n/%d/%h unexpanded). When set, per-folder index files live
	// here instead of co-located with the mailbox under Home.
	IndexDir string

	// ControlDir is the CONTROL= modifier from the mail location (or direct
	// control_dir= userdb field). Carries the raw template string
	// (%u/%n/%d/%h unexpanded). When set, per-folder control files
	// (yarilo-uidlist, subscriptions) live here instead of co-located
	// with the mailbox under Home.
	ControlDir string

	// AltDir is the ALT= modifier from the mail location (or direct
	// alt_dir= userdb field). Carries the raw template string
	// (%u/%n/%d/%h unexpanded). When set, cold-tiered messages live
	// under AltDir; reads check both primary and alt tiers.
	AltDir string

	Proxy bool
	Host  string
	Port  int

	// Fields carries the passdb result as a key/value bag with
	// prefix-derived scoping (see fields.go). Populated by passdb
	// implementations that opt into Phase AUTH-2's wire surface;
	// nil falls back to the typed-fields wire path.
	Fields *Fields
}

AuthResponse is the final response sent back to the client session.

Phase AUTH-2 PR 1 adds Fields alongside the legacy typed members. When a passdb populates Fields, handleAuth emits the OK reply from the bag (with prefix gating: auth_* stripped, userdb_* passed through). When Fields is nil the typed fallback path runs — that's the pre-AUTH-2 wire shape, byte-compatible for the existing SQL passdb until PR 2 swaps the Passdb interface to take a shared Fields instance directly.

type AuthResult ¶

type AuthResult int

AuthResult is the outcome of a single authentication attempt.

const (
	AuthOK AuthResult = iota
	AuthFail
	AuthTempFail
)

type Authenticator ¶ added in v1.39.0

type Authenticator interface {
	Authenticate(username, password, service, remoteIP string) (*AuthResponse, error)
}

Authenticator is the simpler legacy surface session paths (yarilo-imap, yarilo-pop3, etc.) use directly when they need to verify credentials in-process (without going over the yarilo-auth wire). Wraps a Passdb chain and projects the chain- internal Result back onto a wire-shaped AuthResponse so the caller does not need to know about Request / Result.

func NewAuthenticator(passdbs []Passdb, opts ...AuthenticatorOption) Authenticator

type AuthenticatorOption ¶ added in v1.39.0

type AuthenticatorOption func(*chainAuthenticator)

AuthenticatorOption tunes a NewAuthenticator construction.

func WithAuthenticatorCache(c *Cache) AuthenticatorOption

func WithAuthenticatorMasterUserSeparator(sep string) AuthenticatorOption

func WithAuthenticatorMasterUsers(enabled bool) AuthenticatorOption

func WithAuthenticatorMasterdb(passdbs []Passdb) AuthenticatorOption

type Cache ¶ added in v1.39.0

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

Cache is an in-process LRU cache for verified auth lookups.

• Bytes-bounded: SizeBytes caps the total payload weight; LRU eviction makes room when an insert would exceed the cap.
• Two TTLs: positive entries (successful auth) live up to TTL, negative entries (failed lookup — unknown user, wrong password) live up to NegTTL. A separate, typically shorter NegTTL means a fresh password attempt can succeed soon after the user resets their password without waiting for the full positive TTL to expire.
• Password verify on hit: the cached entry stores an HMAC of the plain password (computed with a process-local random key). On lookup, the incoming password is HMAC-ed and compared in constant time. Negative entries store an empty password slot so any incoming password triggers re-lookup against the chain if the user happens to exist now.

Caching defence-in-depth: the HMAC key is generated per Cache construction and never persisted. A memory dump reveals the HMACs (which are not invertible) but not plain passwords. The key never crosses any wire — even the master-protocol CACHE-FLUSH only carries user masks, not entries.

Cache key format is decided by the caller (typically `service\tusername`); Cache treats keys as opaque.

func NewCache(sizeBytes int64, ttl, negTTL time.Duration) *Cache

func (c *Cache) Clear() uint32

func (c *Cache) ClearByUserMask(masks []string) uint32

func (c *Cache) Insert(key, username, password string, result Result, fields *Fields)

func (c *Cache) Lookup(key, password string) (*CacheEntry, bool)

func (c *Cache) Remove(key string) bool

func (c *Cache) Stats() (hits, misses uint64, sizeBytes, entryCount int64)

type CacheEntry ¶ added in v1.39.0

type CacheEntry struct {
	Result Result
	Fields *Fields
	// contains filtered or unexported fields
}

CacheEntry is the cached value. ResultOK carries Fields (the passdb result the chain produced) and pwdMAC (HMAC of the verified plain password). ResultFail carries neither — the presence of a Fail entry alone short-circuits the chain.

pwdMAC is set only on positive entries. Empty pwdMAC on a positive entry would let any caller pass on a cache hit, so callers MUST treat (Result=OK, len(pwdMAC)=0) as cache miss.

type Chain ¶

type Chain []Passdb

Chain composes multiple Passdb backends with first-hit-wins semantics. Each entry runs under a per-entry Fields.Snapshot so a driver's partial mutations are rolled back on ResultNext. Wire surface preserved from pre-PR-2: chain exhaust without a hit returns ResultFail (matches the pre-refactor Chain that returned AuthFail when every driver answered nil).

func (c Chain) Authenticate(req *Request) (Result, error)

type Fields ¶ added in v1.39.0

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

Fields is an ordered key/value bag that carries the result of a passdb (and, eventually, userdb) lookup through the auth pipeline. Insertion order is preserved so the wire output is deterministic for any given mutation sequence — two processes that build the same Fields produce byte-identical OK responses.

Scope is derived from the key prefix at iteration / serialise time, not stored on the entry:

auth_*    → ScopeInternal — never crosses the client wire
userdb_*  → ScopeUserdb   — passed through with the prefix
                            preserved so login pods can tell
                            them apart from passdb-only fields
(other)   → ScopePassdb   — passdb-only field, emitted on the
                            wire verbatim

Phase AUTH-2 PR 1 introduces Fields alongside the legacy typed AuthResponse fields. Both populate in parallel so the existing SQL passdb + handleAuth call sites stay byte-compatible with the pre-AUTH-2 wire. PR 2 swaps the Passdb interface to take a shared Fields instance so chains can mutate it; PR 3 wires userdb prefetch through the same bag.

func NewFields() *Fields

func (f *Fields) Delete(key string)

func (f *Fields) Each(fn func(key, value string) bool)

func (f *Fields) Get(key string) (string, bool)

func (f *Fields) Has(key string) bool

func (f *Fields) Len() int

func (f *Fields) Rollback(snap *Snapshot)

func (f *Fields) Set(key, value string)

func (f *Fields) SetValidated(key, value string) error

func (f *Fields) Snapshot() *Snapshot

func (f *Fields) WireForm() []string

type MasterAuthenticator ¶ added in v1.39.0

type MasterAuthenticator interface {
	AuthenticateMaster(authzid, authid, password, service, remoteIP string) (*AuthResponse, error)
}

MasterAuthenticator extends Authenticator with the SASL PLAIN authzid surface — i.e. master-user impersonation. Session-level callers (IMAP / POP3 / Submission) type-assert opts.Auth into this interface to decide whether to honour authzid; backends that only implement Authenticator (or stub test doubles) keep working unchanged but fall back to "authzid must equal authid" behaviour at the SASL layer.

• authzid — target identity the caller wants to log in AS. When empty (or equal to authid), this is a regular login and callers should typically dispatch via Authenticate instead.
• authid — the user supplying the password (the master in an impersonation request).
• password — the master's password.
• service — login service tag (imap / pop3 / submission / lmtp). Logged + forwarded to the chain unmodified.

type MasterServer ¶ added in v1.39.0

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

MasterServer answers password-less userdb lookups and user enumeration over a separate TCP+mTLS listener. Wire-format mirrors Dovecot's auth-master-connection at the shape level (USER / PASS / LIST commands with ID-tracked responses) so admin tooling that already knows the Dovecot dialect maps over without surprises.

MasterServer is intentionally separate from the client-protocol Server: different audience (admins + backend-api vs login pods), different threat model (no untrusted credentials cross this socket), and different evolution cadence. The two share mTLS material today; splitting is a future operational knob.

func NewMasterServer(userdb Userdb, opts ...MasterServerOption) *MasterServer

func (s *MasterServer) ListenAndServe(ctx context.Context, addr string, tlsCfg *tls.Config) error

type MasterServerOption ¶ added in v1.39.0

type MasterServerOption func(*MasterServer)

MasterServerOption tunes a NewMasterServer construction.

func WithMasterCache(c *Cache) MasterServerOption

func WithMasterTokenStore(ts TokenStore) MasterServerOption

type Passdb ¶

type Passdb interface {
	Authenticate(req *Request) (Result, error)
}

Passdb is the interface that passdb backends implement. Drivers receive a chain-wide Request whose Fields bag they mutate directly; the returned Result selects the chain's next move. error is reserved for unexpected technical failures that accompany ResultTempFail — the wire never carries the error text, only the temp_fail marker, so a driver-level "connection refused" is invisible to the login pod.

type PenaltyStore ¶ added in v1.39.0

type PenaltyStore interface {
	PenaltyLookup(ip string) (int, error)
	PenaltyUpdate(ip string, count int) error
}

PenaltyStore is the cross-process auth-fail backoff store the wire Server consults pre-passdb. Implemented by *anvil.Conn so every yarilo-auth pod shares the same counters; tests can plug in a stub. Nil-safe at the call sites — Lookup returns 0 and Update is a no-op when the store is not configured.

type PenaltyToSecsFunc ¶ added in v1.39.0

type PenaltyToSecsFunc func(count int) int

PenaltyToSecsFunc maps the penalty counter returned by PenaltyStore.Lookup to the sleep duration applied before the chain runs. Caller-supplied so a deployment can tune the exponential curve without recompiling protocol — typical implementations: anvil.PenaltyToSecs (2/4/8/15 cap), linear, or capped-linear. Nil falls back to no-sleep.

type PolicyChecker ¶ added in v1.39.0

type PolicyChecker interface {
	CheckBefore(ctx context.Context, req PolicyRequest) (PolicyDecision, error)
	CheckAfter(ctx context.Context, req PolicyRequest, success, policyReject bool) (PolicyDecision, error)
	ReportAfter(ctx context.Context, req PolicyRequest, success, policyReject bool)
}

PolicyChecker is the policy-server hook surface the wire Server consults around the chain run. Implemented by *policy.Client (auth/policy package); tests can plug stubs.

Decision shape lives here so protocol does not import the policy package — single-direction dependency keeps the build graph clean.

type PolicyDecision ¶ added in v1.39.0

type PolicyDecision struct {
	Continue   bool
	Reject     bool
	TarpitSecs int
	Message    string
}

PolicyDecision is the parsed verdict. Continue=true means proceed; Reject=true means refuse; TarpitSecs>0 means sleep that many seconds then continue.

type PolicyMode ¶ added in v1.39.0

type PolicyMode struct {
	CheckBefore bool
	CheckAfter  bool
	ReportAfter bool
}

PolicyMode controls which lifecycle hooks fire. CheckBefore runs pre-passdb (block the chain on policy refusal); CheckAfter runs post-passdb with the outcome known (downgrade-success-to-fail use case); ReportAfter is fire-and-forget telemetry.

type PolicyRequest ¶ added in v1.39.0

type PolicyRequest struct {
	Username  string
	Password  string
	RemoteIP  string
	Service   string
	DeviceID  string
	SessionID string
	TLS       bool
	FailType  string
}

PolicyRequest is the input to a policy call. Mirror of the shape policy.Client accepts; defined here so the wire Server can call without the policy package import.

type Request ¶ added in v1.39.0

type Request struct {
	Username string
	Password string
	Service  string
	// RemoteIP is the client IP string (no port). Empty when the IP is
	// unavailable (in-process chain, loopback test harnesses). Passdb
	// drivers that enforce allow_nets MUST skip the check when empty.
	RemoteIP string

	// Fields is the chain-wide bag that accumulates passdb output.
	// Driver implementations MAY assume non-nil; the canonical
	// caller (Chain.Authenticate) allocates it when the Server-side
	// authenticate entry-point starts the chain.
	Fields *Fields
}

Request bundles every input a passdb needs to authenticate plus the shared Fields bag the chain mutates as it walks. Phase AUTH-2 PR 2 introduces this struct so passdb backends can write directly into the bag (the chain isolates each driver's mutations via Snapshot / Rollback on ResultNext). PR 3 will extend Request with userdb-prefetch metadata.

type Result ¶ added in v1.39.0

type Result int

Result classifies a passdb outcome. Separate from AuthResult (which is wire-shaped on AuthResponse) because ResultNext is a chain-internal signal — it never reaches the client wire.

const (
	// ResultOK — user verified, Fields populated, chain stops.
	ResultOK Result = iota
	// ResultFail — credentials rejected (password mismatch,
	// disabled account, expired credential). Chain stops; the
	// wire returns FAIL.
	ResultFail
	// ResultNext — user unknown in this driver; chain rolls back
	// any partial Fields mutations and tries the next driver.
	ResultNext
	// ResultTempFail — backend technical failure (DB down,
	// network). Chain stops with a wire-level FAIL temp_fail.
	// Always accompanies a non-nil error so the server-side log
	// has the underlying cause.
	ResultTempFail
)

func RunAuth(chain Chain, req *Request) (Result, error)

func RunMasterAuth(passdbs, masterdb Chain, target string, req *Request) (Result, error)

type SCRAMSha1Lookup ¶ added in v1.39.0

type SCRAMSha1Lookup interface {
	LookupSCRAMSha1(username string) (*sasl.ScramCredentials, error)
}

SCRAMSha1Lookup is the SHA-1 counterpart of SCRAMSha256Lookup. Same semantics, same (creds, nil) / (nil, nil) / (nil, err) contract; only the digest family of the returned verifier differs. Provided for compatibility with legacy clients that only speak SCRAM-SHA-1 — new deployments should provision SCRAM-SHA-256 verifiers instead.

type SCRAMSha256Lookup ¶ added in v1.39.0

type SCRAMSha256Lookup interface {
	LookupSCRAMSha256(username string) (*sasl.ScramCredentials, error)
}

SCRAMSha256Lookup exposes per-user SCRAM-SHA-256 verifiers to the session-layer SASL mech. Implementing this interface on the configured Authenticator (and on individual passdbs that carry verifiers in their backing store) lights up SCRAM-SHA-256 and SCRAM-SHA-256-PLUS advertisement in IMAP / POP3 / Submission.

LookupSCRAMSha256 returns:

• (creds, nil) — user exists and has a SCRAM-SHA-256 verifier. The SASL mech drives challenge-response from the returned StoredKey / ServerKey without ever seeing a plain password.
• (nil, nil) — user unknown OR stored credential is not a SCRAM verifier. The SASL mech fabricates a fake verifier so the exchange completes with a uniform auth-failed outcome and an attacker cannot probe for user existence via timing.
• (nil, err) — transient backend error. The session surfaces this as temp_fail.

Verifiers are produced by `yarilo-admin auth scram-verifier` (or any tool that emits the `{SCRAM-SHA-256}iter,salt,stored,server` blob).

type Scope ¶ added in v1.39.0

type Scope int

Scope classifies a field by its key prefix. Defined as a type so switch statements stay exhaustive when phase AUTH-2 PR 2 adds snapshot tracking.

const (
	// ScopePassdb — passdb-side fields (no prefix). Crosses the
	// client wire as `key=value`.
	ScopePassdb Scope = iota
	// ScopeUserdb — fields prefetched by passdb for the userdb
	// layer. Crosses the client wire as `userdb_key=value` so
	// login pods can split the response into passdb / userdb
	// halves the way Dovecot's auth-client does.
	ScopeUserdb
	// ScopeInternal — internal-only metadata. Never crosses the
	// client wire. Used for state-tracking fields like
	// `auth_cache_key`, `auth_failure_attempted`, etc. in later
	// AUTH-N phases.
	ScopeInternal
)

func ScopeOf(key string) Scope

type Server ¶

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

Server is the yarilo-auth TCP+mTLS server. Holds the passdb chain plus an optional userdb that enriches successful auth responses with userdb_* fields (Phase AUTH-2 PR 3) plus an optional masterdb chain + separator for master-user impersonation (Phase AUTH-3).

func NewServer(passdbs []Passdb, opts ...ServerOption) *Server

func (s *Server) ListenAndServe(ctx context.Context, addr string, tlsCfg *tls.Config) error

type ServerOption ¶ added in v1.39.0

type ServerOption func(*Server)

ServerOption tunes a NewServer construction.

func WithCache(c *Cache) ServerOption

func WithFailureDelay(d time.Duration) ServerOption

func WithInternalFailureDelay(d time.Duration) ServerOption

func WithMasterUserSeparator(sep string) ServerOption

func WithMasterUsers(enabled bool) ServerOption

func WithMasterdb(passdbs []Passdb) ServerOption

func WithPenalty(store PenaltyStore, toSecs PenaltyToSecsFunc) ServerOption

func WithPolicy(checker PolicyChecker, mode PolicyMode) ServerOption

func WithTokenStore(ts TokenStore) ServerOption

func WithUserdb(u Userdb) ServerOption

type Snapshot ¶ added in v1.39.0

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

Snapshot captures the bag's current state so it can be restored later via Rollback. Used by Chain to isolate each passdb's mutations: snapshot before the call, rollback on ResultNext so the next driver sees a clean slate. The snapshot is read-only — every mutating method on Fields is safe to call between Snapshot and Rollback / discard.

Snapshot is O(n) in the current bag size (copies the keys, vals and idx maps); chain depth + bag size are both bounded by config so the cost stays trivial.

type TokenStore ¶ added in v1.44.0

type TokenStore interface {
	Issue(username, sessionID, service string) (string, error)
	Validate(tok string) (username, sessionID, service string, ok bool)
}

TokenStore is implemented by authtoken.Store. Abstracted as an interface so tests can provide a stub without importing the concrete package.

type UserInfo ¶ added in v1.39.0

type UserInfo struct {

	// Username is the resolved canonical username this UserInfo
	// describes. Mandatory.
	Username string

	// OriginalUser is the username the client supplied before any
	// userdb-side translations (case folding, alias rewrite). Empty
	// when no translation occurred.
	OriginalUser string

	// MasterUser is the master user when this lookup arrived via
	// `master=` delegation. Populated only by Phase AUTH-3 master-
	// user flows; the field exists in PR 1 so the schema is stable.
	MasterUser string

	// LoginUser is the post-impersonation effective user. For non-
	// delegated lookups this equals Username; for master-user flows
	// it is the target user. Phase AUTH-3 populates this.
	LoginUser string

	UID               uint32
	GID               uint32
	Home              string
	Chroot            string
	SystemGroupsUser  string   // override username for system group lookup
	Groups            []string // supplementary group names
	ClientCertPresent bool     // TLS client cert auth was used

	// MailLocation overrides the global mail_location (Dovecot
	// `mail` field).
	MailLocation      string
	MailUID           uint32 // distinct from system UID
	MailGID           uint32 // distinct from system GID
	MailboxFormat     string // maildir | sdbox | mdbox
	MailAttributeDict string // dict URL for RFC 5464 METADATA

	// VolatileDir is the VOLATILEDIR modifier extracted from MailLocation
	// (or set directly via the `volatile_dir` userdb extra field). Carries
	// the raw template string (%u/%n/%d/%h not yet expanded) so callers
	// can expand it against the resolved home after userdb completes.
	VolatileDir string

	// IndexDir is the INDEX= modifier extracted from MailLocation (or set
	// directly via the `index_dir` userdb extra field). Carries the raw
	// template string (%u/%n/%d/%h not yet expanded). When set, per-folder
	// index files (yarilo.index*, yarilo-acl) are stored here instead of
	// co-located with the mailbox data under Home.
	IndexDir string

	// ControlDir is the CONTROL= modifier extracted from MailLocation (or
	// set directly via the `control_dir` userdb extra field). Carries the
	// raw template string (%u/%n/%d/%h not yet expanded). When set,
	// per-folder control files (yarilo-uidlist, subscriptions) are stored
	// here instead of co-located with the mailbox data under Home.
	ControlDir string

	// AltDir is the ALT= modifier extracted from MailLocation (or set
	// directly via the `alt_dir` userdb extra field). Carries the raw
	// template string (%u/%n/%d/%h not yet expanded). When set, messages
	// that have been cold-tiered live under AltDir; reads check both
	// primary (Home) and alt tiers.
	AltDir string

	// QuotaRules is the list of per-user quota rules (Dovecot
	// `quota_rule=` can appear multiple times for nested roots).
	QuotaRules    []string
	QuotaOverFlag string // operator-set override marker (string sentinel)

	// AllowNets is the list of IP / CIDR strings the user is
	// allowed to authenticate from. Empty means no IP restriction.
	AllowNets []string

	NoLogin        bool // reject login outright
	NoDelay        bool // bypass auth-penalty backoff (Phase AUTH-4)
	NoAuthenticate bool // auth disabled for this user
	PassExpired    bool // password expired — client must re-set
	NoPassword     bool // passdb without a password (e.g. OAuth)

	Proxy               bool
	ProxyMaybe          bool   // proxy only when remote host differs
	Host                string // proxy backend host
	Port                int    // proxy backend port (0 = default)
	DestUser            string // override target user in proxy
	ProxyMech           string // SASL mech to use against backend
	ProxyTimeout        int    // seconds
	ProxyRedirectReauth bool
	ProxyNoPipelining   bool
	SSL                 string // yes | any | required
	StartTLS            bool

	MailMaxUserIPConnections int // per-(user, IP)
	MailMaxUserConnections   int // per-user across IPs

	Service   string // IMAP | POP3 | LMTP | submission ...
	LocalName string // SNI hostname the client connected to

	// Forward carries `forward_*` fields that are passed through
	// a proxy chain unchanged. Map key is the field name WITHOUT
	// the `forward_` prefix.
	Forward map[string]string

	// Extra is the catch-all bag for fields not modelled as typed
	// struct members. Anything a userdb driver returns that does
	// not map to a typed field above ends up here, keyed by the
	// raw field name. Wire-level prefix semantics (`userdb_*=`,
	// `auth_*=`) land in Phase AUTH-2.
	Extra map[string]string

	// Password is the stored credential (or scheme-encoded hash)
	// from a passdb lookup. The master-protocol wire serialiser
	// in Phase AUTH-1 PR 2 strips this unconditionally so an
	// admin-side USER request can never leak credentials. Present
	// on the struct so passdb→userdb internal pipelines do not
	// need a parallel type.
	Password string

	// CertName is the TLS client certificate Common Name. Set by
	// the EXTERNAL SASL mechanism (Phase AUTH-5). Internal-only.
	CertName string

	// PolicyResponse is the verbatim body returned by the policy
	// HTTP endpoint in Phase AUTH-6. Internal-only.
	PolicyResponse string
}

UserInfo carries the full set of user fields a userdb lookup can return. Modelled after Dovecot 2.4's auth-fields plus the reserved field names every userdb driver writes (auth-fields.c, auth-request.c, userdb-passwd.c). The struct is intentionally comprehensive — adding fields later means breaking the protocol surface that pkg/authclient + yarilo-backend-api speak, so the shape is fixed up-front during Phase AUTH-1 and the prefix / snapshot / prefetch semantics in later phases extend BEHAVIOUR without touching DATA shape.

Zero values are the "field absent" marker; the master-protocol wire serialiser in Phase AUTH-1 PR 2 skips them. Sensitive fields (Password, CertName, PolicyResponse) are populated server-side but the wire layer filters them out unconditionally — they exist on the struct so internal pipelines can carry them without a parallel struct.

func ParseUserInfo(tokens []string) (*UserInfo, error)

func (ui *UserInfo) VisitFields(fn func(key, value string))

type Userdb ¶ added in v1.39.0

type Userdb interface {
	Lookup(username string) (*UserInfo, error)
}

Userdb is the contract every userdb backend implements. Unlike Passdb.Authenticate, Lookup takes no password — userdb answers "who is this user?" for admin tooling, master-protocol clients, and the prefetch shortcut (Phase AUTH-2) that lets a passdb short-circuit a redundant userdb round-trip.

Semantics on the return value match Passdb / Chain:

• (ui != nil, nil) — user found, ui populated
• (nil, nil) — user unknown in this backend; UserdbChain tries the next entry
• (nil, err != nil) — backend failure; UserdbChain stops and surfaces the error to the caller

type UserdbChain ¶ added in v1.39.0

type UserdbChain []Userdb

UserdbChain composes multiple Userdb backends with first-hit-wins semantics, mirroring the Passdb Chain. The first non-nil response from any backend in the chain is returned; an error from any backend short-circuits the chain (matches Dovecot's USERDB_RESULT_INTERNAL_FAILURE — "stop, do not try fallbacks").

func (c UserdbChain) Lookup(username string) (*UserInfo, error)

type UserdbIterator ¶ added in v1.39.0

type UserdbIterator interface {
	Iterate() ([]string, error)
}

UserdbIterator is implemented by userdb backends that support listing every known user. Used by `yarilo-admin backend user iterate` and by the master-protocol `LIST` command. Optional — a backend that cannot enumerate (e.g. an LDAP search with no suitable filter) simply does not implement it.

type Validator ¶ added in v1.39.0

type Validator func(value string) (string, error)

Validator parses a raw field value and returns its canonical string form. Returns an error when the value does not satisfy the field's type contract.

Canonicalisation: validators normalise equivalent inputs to a single representation. `Set("nologin", "TRUE")` then `Set("nologin", "yes")` then `Set("nologin", "1")` all land in the bag as `nologin=yes` — so two callers writing the "same" field produce byte-identical wire output.