auth

type APIKey struct {
	Name       string
	Role       KeyRole           // "" (stored before roles existed) counts as data
	Networks   registry.Networks // where the key may be used from; empty: anywhere
	Scopes     Scopes            // what the key reaches; empty: everything
	Prefix     string            // first characters of the key, for recognizing it
	Hash       string
	CreatedAt  time.Time
	LastUsedAt *time.Time
	ExpiresAt  *time.Time // nil: never expires
}

type Argon2Params struct {
	Memory  uint32 // KiB
	Time    uint32
	Threads uint8
}

type Attempts struct {
	Failures      int
	LastFailureAt time.Time
}

type AuditFilter struct {
	Action, Actor, Target string
	Since, Until          time.Time // At >= Since, At < Until
	Limit, Skip           int
}

type AuditRecord struct {
	ID        string
	At        time.Time
	ExpiresAt time.Time // removed after this (the realm's retention)
	Action    string
	Actor     string // "user:<id>", "key:<name>", "anonymous", or an Actor* constant
	Target    string // "user:<id>", "key:<name>", "invitation:<id>", or ""
	Details   map[string]any
	RequestID string
	ClientIP  string
}

type AuditSource struct {
	Actor, RequestID, ClientIP string
}

type AuthChallenge struct {
	ID     string // HashToken of the value given to the caller
	Kind   string
	UserID string
	// Factor is the first factor that was proved: ProviderPassword, a provider's name, ...
	Factor string
	// NewUser and Profile are what a provider sign-in hands over with the session: kept
	// until the second step ends it.
	NewUser bool
	Profile map[string]string
	// Secret is a TOTP secret (SealToken form) of a ChallengeTOTPSetup.
	Secret string
	// SessionID is the session a re-authentication token or code is bound to; CodeHash is
	// the keyed hash of the code of a ChallengeReauthCode (set when the email is made).
	SessionID string
	CodeHash  string
	// A magic-link request: TokenHash is the hash of the link's token and CodeHash the code's;
	// CodeChallenge the PKCE challenge of the app that asked; RedirectTo where the link ends
	// ("" for the realm's app_url); Email the address when it has no user yet (sealed);
	// Purpose says what is sent (MagicLinkPurposeLink or MagicLinkPurposeNoAccount); Locale
	// the language for a new user.
	TokenHash     string
	CodeChallenge string
	RedirectTo    string
	Email         string
	Purpose       string
	Locale        string
	// Methods are how the session will say it was made (a ChallengeConsent keeps them
	// while the user accepts); Consents are the acceptances a magic-link request carried.
	Methods   []string
	Consents  map[string]string
	Attempts  int
	CreatedAt time.Time
	ExpiresAt time.Time
}

type CallbackClaims struct {
	Realm    string    `json:"r"`
	Function string    `json:"f"` // <database>/<name>
	UserID   string    `json:"u,omitempty"`
	KeyHash  string    `json:"k,omitempty"`
	Admin    bool      `json:"a,omitempty"`
	Expires  time.Time `json:"e"`
	// Calls are the functions of the caller's database this invocation may
	// ctx.call (its function.yaml `calls`); Depth counts the nested calls
	// above it; Inv is its own invocation id, the parent of what it calls.
	Calls []string `json:"c,omitempty"`
	Depth int      `json:"d,omitempty"`
	Inv   string   `json:"i,omitempty"`
	// Job and Attempt say which job attempt this run is, so it may report its
	// steps (ctx.step): only for an async function's job.
	Job     string `json:"j,omitempty"`
	Attempt int    `json:"t,omitempty"`
	// Email says the function may send custom emails (function.yaml `email: true`).
	Email bool `json:"m,omitempty"`
	// Push says the function may send push notifications (function.yaml `push:`).
	Push bool `json:"p,omitempty"`
	// Config says the function may change the app configuration (function.yaml `config: write`).
	Config bool `json:"g,omitempty"`
	// MFA and Methods are how the session of the user the call acts as was created, so that
	// rules in the function's own data calls see the same `user.mfa` and `user.methods`.
	MFA     bool     `json:"x,omitempty"`
	Methods []string `json:"y,omitempty"`
}

type Caller struct {
	User *Principal  // the user whose rules apply
	Key  *APIKey     // set for API key callers
	Func *FuncCaller // set for a function's callbacks
}

type CheckJob struct {
	Collections []string // "<database>/<collection>", resolved when the check started
	Database    string   // the scope asked for: "" every database
	Collection  string   // "" every collection of Database
	Limit       int      // invalid documents listed per collection
}

type CheckProblem struct {
	Path   string
	Reason string
}

type CheckReport struct {
	Database, Collection string
	JobID                string
	StartedAt            time.Time
	FinishedAt           time.Time
	Scanned              int64
	Invalid              int64
	// Complete is false when the scan stopped before the end: StoppedBy says why
	// ("limit" when Limit invalid documents were found, "time" for CheckMaxDuration).
	Complete  bool
	StoppedBy string
	Limit     int
	// SchemaHash identifies the schema the documents were checked against.
	SchemaHash string
	Documents  []CheckedDocument // up to Limit
}

type CheckedDocument struct {
	ID       string
	Deleted  bool // soft-deleted (in the trash)
	Problems []CheckProblem
	// MoreProblems counts the problems left out past MaxCheckProblems.
	MoreProblems int
}

type ConsentContext struct{ IP, UserAgent string }

type ConsentInput struct {
	Consent  string
	Version  string // accepted: the version; withdrawn: ignored
	Action   string
	Method   string
	Evidence string
	// Locale is the language of the text the person saw; "" uses the user's, then the realm's.
	Locale    string
	IP        string
	UserAgent string
}

type ConsentNotice struct {
	Consent string
	Version string
	// Matched is the users who hold an older version of the consent (or, for a required
	// one, none): the ones the message is for.
	Matched int
	// Queued messages were handed to the email worker; Limited were skipped because an email
	// limit was reached; the rest could not be sent to (disabled or erased users).
	Queued  int
	Limited int
}

type ConsentRecord struct {
	ID       string
	UserID   string
	Consent  string
	Version  string
	Locale   string
	TextHash string // SHA-256 of the text shown
	Action   string // ConsentAccepted or ConsentWithdrawn
	Method   string // ConsentMethodSignup, …
	Evidence string // for the admin method: the reference given
	At       time.Time
	// DeleteAt is when a retention removes the record: set at erasure, zero before.
	DeleteAt time.Time
	// IP and UserAgent are stored only when the realm lists them in compliance.consent_proof.
	IP        string
	UserAgent string
}

type ConsentRef struct{ Consent, Version string }

type ConsentRequiredError struct {
	Consents []registry.ConsentRef
	// Session is true when it is an authenticated request that is refused.
	Session bool
}

type CustomEmail struct {
	Function string // <database>/<name> of the function that asked
	To       []string
	CC       []string
	BCC      []string
	Data     map[string]any
}

type Device struct {
	ID        string
	UserID    string
	SessionID string // the session that registered it
	Platform  string
	Name      string
	TokenHash string // of the token, or of a web subscription's endpoint
	Token     string // sealed
	CreatedAt time.Time
	LastSeen  time.Time
}

type DeviceInput struct {
	Platform string
	Token    string
	Name     string
}

type EmailJob struct {
	Kind       string
	UserID     string
	Locale     string
	RedirectTo string // checked when the request was made; bound to the token the worker creates
	// To says whose address the message goes to: "" the user's current one,
	// "pending" the address they asked to change to, "previous" the one
	// before the last change.
	To string
	// Notice marks a message that only informs: no token, no link.
	Notice bool
	// InvitationID is the invitation an invitation email is for (there is no
	// user yet): the worker takes the address from it.
	InvitationID string
	// Event and CodesLeft are what a security-notice says: which change it reports and, for
	// a used recovery code, how many remain. Nothing secret.
	Event     string
	CodesLeft int
	// ChallengeID is the pending step the email is for (a re-authentication code): the
	// worker makes the secret at send time and keeps only its hash there.
	ChallengeID string
	// Custom is set on an email a function asked for with ctx.email.send. Unlike
	// the account emails it stores what the function gave: the recipients'
	// addresses and the data for the template, for as long as jobs are kept.
	Custom *CustomEmail
}

type EmailLimitedError struct {
	RetryAfter time.Duration
	// Scope says which limit it was: "recipient", "ip", "function" or
	// "invocation".
	Scope string
}

type EmailRequest struct {
	Kind       string // an email kind (verify-email, ...)
	UserID     string
	Address    string // the recipient, for the per-recipient limits only (never stored readable)
	Locale     string
	RedirectTo string // already checked against the realm's allowed redirects
	ClientIP   string // who caused it, for the per-IP limit; "" when nobody did
	RequestID  string
	// Event and CodesLeft are the fields of the same name of EmailJob.
	Event       string
	CodesLeft   int
	ChallengeID string
	// To, Notice and InvitationID are the fields of the same name of EmailJob.
	To           string
	Notice       bool
	InvitationID string
	// Custom marks an email a function asked for; Invocation is the
	// invocation that asked (the parent of the job, and what the per-invocation
	// cap counts). Address is then the user's, for to_user; Custom holds the
	// addresses of the others.
	Custom     *CustomEmail
	Invocation string
	Depth      int
}

type EmailToken struct {
	Hash       string // hex SHA-256 of the token; the record's id
	Purpose    string // verify-email, reset-password, change-email, revert-email-change or invitation
	UserID     string
	RedirectTo string // where the page after the link may send the user (already checked)
	// Address is the address the token acts on: the new one for change-email,
	// the previous one for revert-email-change, the invited one for an
	// invitation. Empty for the others.
	Address string
	// InvitationID is the invitation an invitation token accepts (UserID is empty then).
	InvitationID string
	CreatedAt    time.Time
	ExpiresAt    time.Time
	UsedAt       time.Time // zero until redeemed
}

type EraseJob struct {
	UserID string
	Email  string
	Counts map[string]int64 // "<database>/<collection>/<operation>" → documents
}

type ErrCheckRunning struct{ JobID string }

type FileDeletion struct {
	Key       string
	Reason    string // replaced, cleared, removed, abandoned…
	Attempts  int
	NotBefore time.Time // not claimed before this
	CreatedAt time.Time
}

type FileDeletionStats struct {
	Queued   int       // objects waiting to be deleted
	Retrying int       // of them, the ones that failed at least once
	Oldest   time.Time // when the oldest was queued; zero when empty
}

type FileJournalEntry struct {
	ID         string // the file's id (fl_…)
	Database   string
	Collection string
	Field      string
	DocumentID string // "" for an upload no document references yet
	Key        string // the object's key
	Caller     string // who uploaded it, for display (user:<id>, key:<name>, func:…)
	Size       int64
	Status     string
	CreatedAt  time.Time
	UpdatedAt  time.Time
	ExpiresAt  time.Time

	// A pending upload is one made before the document that will hold it exists
	// (or without the document being touched): it is attached by naming it, with
	// its token, in a write. Its details are kept here until then.
	Pending      bool
	Direct       bool      // a direct upload: the client sends the bytes to the bucket and completes it
	TokenHash    string    // SHA-256 of the secret token the creator holds
	Owner        string    // the user who made it; "" for an anonymous caller
	CallerKey    string    // who the open-uploads limit counts it for
	PendingUntil time.Time // unused, it expires then (also set for a direct upload to a document)
	Name         string
	Type         string
	SHA256       string
	UploadedAt   time.Time
	// Image is a pending upload's image details as JSON (width, height and the state of each
	// declared version), for the document that will hold it.
	Image string

	// A multipart direct upload (a file above one signed PUT): the storage's upload id, the
	// part size and the SHA-256 of each part as declared at the start. SHA256 is then their
	// composite, which storage can verify.
	MultipartID string
	PartSize    int64
	PartSHA256  []string
}

type FuncCaller struct {
	Name  string // <realm>/<database>/<function>
	Admin bool   // ctx.admin.db: full access, recorded as the function
	// What the invocation behind the token may do next (see CallbackClaims).
	Calls      []string
	Depth      int
	Invocation string
	Email      bool   // ctx.email.send
	Push       bool   // ctx.push.send
	Config     bool   // ctx.admin.config: may change the app configuration
	Job        string // the job attempt behind the token, if any (see CallbackClaims)
	Attempt    int
	Expires    time.Time
}

type Hasher struct {
	Params Argon2Params
	// contains filtered or unexported fields
}

type IdempotencyRecord struct {
	ID          string // see IdempotencyID
	Function    string // <database>/<name>, for display
	CallerActor string
	InputHash   string     // sha256 of the exact input bytes
	Mode        string     // sync | async
	Status      string     // running | done
	Result      *JobResult // nil until done; a sync call's outcome
	JobID       string     // set once done, for async; "" for sync
	CreatedAt   time.Time
	ExpiresAt   time.Time
}

type Identity struct {
	ID           string
	UserID       string
	Provider     string
	Subject      string // unique per provider
	PasswordHash string // ProviderPassword only: argon2id, PHC string format
	// Email and EmailVerified are what an external provider last reported.
	Email         string
	EmailVerified bool
	// LastUsedAt is the last successful sign-in with this identity; zero if
	// none was recorded yet.
	LastUsedAt time.Time
	// AppleRefreshToken is Apple's refresh token, sealed with the realm's secrets cipher
	// (see SealToken) and kept only to revoke it when the account goes away; AppleClientID
	// is the client id it was issued to.
	AppleRefreshToken string
	AppleClientID     string
	CreatedAt         time.Time
	UpdatedAt         time.Time
}

type IdentityUpdate struct {
	Email             *string
	EmailVerified     *bool
	LastUsedAt        *time.Time
	AppleRefreshToken *string
	AppleClientID     *string
}

type ImageJob struct {
	Collection string
	Field      string
	DocumentID string
	FileID     string
	// Version, when set, makes just that version, whatever its state: a function asked
	// for it. Params are the parameters to make it with, as JSON ("" means the declared
	// ones); the job's result carries the outcome for the function waiting on it.
	Version string
	Params  string
	// Scan makes this a job over a whole field (backd files regenerate): every file
	// whose copies no longer match what the field declares is made again, for Version only
	// when it is set. MissingOnly leaves the copies that exist alone. Rate is how many files
	// a second at most (0 for the default). DocumentID and FileID are empty.
	Scan        bool
	MissingOnly bool
	Rate        int
}

type InvalidCodeError struct{ AttemptsLeft int }

type InvalidConsentsError struct{ Reasons []string }

type InvalidDeviceError struct{ Reason string }

type InvalidLocaleError struct{ Allowed []string }

type Invitation struct {
	ID        string
	TokenHash string
	Email     string // "" if anyone holding the token may use it
	CreatedBy string // "key:<name>"
	CreatedAt time.Time
	ExpiresAt time.Time
}

type InvocationFilter struct {
	Function, RequestID string
	Since, Until        time.Time
	Limit, Skip         int
}

type InvocationRecord struct {
	ID         string
	At         time.Time
	ExpiresAt  time.Time // removed after this (the realm's log retention)
	Function   string    // <database>/<name>
	Actor      string    // "user:<id>", "key:<name>", "anonymous", or "func:<name> as ..."
	Mode       string    // sync today; async, webhook later
	Status     string    // executor.Status* (ok, function_error, timeout, memory, cpu, crash, ...)
	Code       string    // the function's own error code, when Status is function_error
	DurationMS int64
	RequestID  string
	JobID      string // async jobs (roadmap F11); empty until then
	ParentID   string // the invocation that called this one (ctx.call); empty otherwise
	Origin     string // http, function, cron, admin or backd:<event>
	Logs       []LogLine
	// Steps are what the call reported with ctx.step and ctx.progress, closed
	// when it ended; StepsOmitted counts those dropped from the middle.
	Steps        []Step
	StepsOmitted int
}

type IssuedChallenge struct {
	Token   string
	Kind    string
	Methods []string
	// Consents are the consents and versions a ChallengeConsent waits for.
	Consents []registry.ConsentRef
}

type Job struct {
	ID             string
	Database       string
	Function       string // name only; Database plus this is the function
	Input          json.RawMessage
	CallerActor    string // for display: "user:<id>", "key:<name>", "anonymous"
	CallerUserID   string // "" unless the caller was a signed-in user
	CallerKeyHash  string // "" unless the caller was an API key
	Scheduled      bool   // created by the function's cron schedule, acts as the function itself
	ActsAsFunction bool   // run as the function itself, with full access (a scheduled function run by hand)
	Origin         string // http, function (ctx.call), cron, admin or backd:<event>
	ParentID       string // the invocation that queued it with ctx.call; empty otherwise
	RerunOf        string // the finished job an administrator re-ran to make this one; empty otherwise
	Depth          int    // nested calls above it
	// Email is set on an email job: backd's own request to send a message, which
	// a worker renders and hands to the realm's delivery function. It holds no
	// message and no token.
	Email *EmailJob
	// Erase is set on an erase job (origin backd:account.erase).
	Erase *EraseJob
	// Check is set on a schema check's job (origin CheckOrigin).
	Check *CheckJob
	// Image is set on the job that makes a file's image versions (origin ImageOrigin).
	Image *ImageJob
	// Revoke is set on a job that revokes a user's Apple refresh token (origin RevokeOrigin).
	Revoke *RevokeJob
	// Push is set on the jobs of a push send (origin PushOrigin): planning an audience, a batch
	// of users, or a delivery unit.
	Push *PushJob
	// Exclusive, when set, lets only one job of that name be unfinished at a
	// time: enqueuing another fails with ErrJobExclusive.
	Exclusive     string
	TimeoutMS     int64 // the function's timeout at enqueue time, for the worker's lease
	RequestID     string
	Status        string    // queued | running | done
	Attempts      int       // times a worker claimed it
	Failures      int       // attempts that ended in a failure worth retrying
	NextAttemptAt time.Time // when a retry may be claimed; zero unless one is waiting
	CreatedAt     time.Time
	CompletedAt   time.Time // zero until done
	ExpiresAt     time.Time
	Result        *JobResult // nil until done
	// Steps are what the running (or last) attempt reported with ctx.step and
	// ctx.progress, the last being the current one; StepsOmitted counts those
	// left out of the middle when there were more than MaxSteps. A new attempt
	// starts with none.
	Steps        []Step
	StepsOmitted int
}

type JobFilter struct {
	Database, Function string    // Function is the name only; "" matches every function
	Origin             string    // exact origin, such as function:main/ship; "" matches every one
	EraseUser          string    // the erase jobs of this user
	Status             string    // queued, running or done
	Scheduled          *bool     // nil: both; true: cron runs only; false: called ones only
	Since, Until       time.Time // on created_at: from Since, before Until
	Limit, Skip        int
}

type JobResult struct {
	Status     string
	Output     json.RawMessage
	Code       string
	Message    string
	Details    json.RawMessage
	DurationMS int64
	// HTTPStatus is the function's own chosen status (ctx.error's first
	// argument) when Status is "function_error"; unused otherwise. A
	// job never answers HTTP itself, but an idempotent sync replay
	// (roadmap F12) needs it to reconstruct the original response.
	HTTPStatus int
}

type KeyOptions struct {
	TTL      time.Duration     // 0: never expires
	Role     KeyRole           // "" means data
	Networks registry.Networks // where the key may be used from; empty: anywhere
	Scopes   Scopes            // what a data key reaches; empty: everything
}

type KeyRole string

type LogLine struct {
	Level string
	Line  string
}

type LoginCode struct {
	ID     string // HashToken(code)
	UserID string
	// Method is the first factor the code stands for: the provider's name (magic links will
	// add their own), so that a second step can be asked for after the code is redeemed.
	Method        string
	CodeChallenge string
	// NewUser says the sign-in made the user, and Profile is what the provider said of them:
	// the redemption hands both over once.
	NewUser   bool
	Profile   map[string]string
	CreatedAt time.Time
	ExpiresAt time.Time
}

type MFALockedError struct{ RetryAfter time.Duration }

type MFARecord struct {
	UserID        string
	Secret        string // SealToken form
	EnabledAt     time.Time
	LastStep      int64
	RecoveryCodes []string
}

type MFAStatus struct {
	// Available says the realm lets users turn TOTP on (it may be off with users who
	// still have it).
	Available         bool
	Enabled           bool
	Methods           []string
	RecoveryCodesLeft int
	// Required says a role of the user requires MFA.
	Required bool
}

type MagicLinkInput struct {
	Email string
	// RedirectTo is where the link ends (already checked against the realm's allowed
	// redirects); "" for the realm's sign_in.app_url.
	RedirectTo string
	// CodeChallenge is the S256 PKCE challenge of a verifier only the asking app holds.
	CodeChallenge string
	Locales       []string
	IP, RequestID string
	// Consents are accepted for the account a new address gets when the link is used.
	Consents map[string]string
}

type OAuthState struct {
	ID            string // HashToken(state)
	Provider      string
	Intent        string
	CodeChallenge string // the app's PKCE challenge (S256)
	Verifier      string // backd's own PKCE verifier, for the provider
	Nonce         string
	RedirectTo    string
	InvitationID  string // HashToken of the invitation token, if one was passed
	LinkUserID    string // IntentLink: whose identity is being added
	Locales       []string
	// Consents are the consents the app accepted for a sign-up through this attempt.
	Consents  map[string]string
	CreatedAt time.Time
	ExpiresAt time.Time
}

type OnSignupInput struct {
	UserID   string            `json:"user_id"`
	Provider string            `json:"provider"`
	Profile  map[string]string `json:"profile,omitempty"`
}

type PolicyError struct{ Reason string }

type Principal struct {
	User    User
	Session Session
}

type ProviderLogin struct {
	Provider      string
	Subject       string // the provider's stable id for the person
	Email         string
	EmailVerified bool // as the provider asserts it
	// TrustsEmail: the provider's verified addresses may link an existing account
	// and mark a new one verified (Google and Apple).
	TrustsEmail bool
	Intent      string
	LinkUserID  string // IntentLink: the signed-in user
	// Invitation is the hash of the invitation token the attempt carried.
	Invitation string
	Locales    []string
	IP         string
	// Consents and UserAgent: what a sign-up through the login accepted, and the proof's context.
	Consents  map[string]string
	UserAgent string
	// Profile is what the provider says of the person (CleanProfile's fields): handed to
	// the app and to account.on_signup when the login makes a new user, and kept nowhere else.
	Profile map[string]string
}

type ProviderResult struct {
	User    User
	NewUser bool
	Linked  bool // an identity was added to an existing user
	// Profile is what the provider said of a new user (empty for anyone else).
	Profile map[string]string
}

type PushAudience struct {
	All           bool
	Roles         []string // any of
	EmailVerified *bool
	Locale        string
	CreatedBefore time.Time
	CreatedAfter  time.Time
	// Consent: only users who hold this consent (any version).
	Consent string
}

type PushCounts struct {
	Queued, Limited, NoDevices, NoConsent int
	// Units is the delivery units of the batch, those made now and those that existed.
	Units int
}

type PushDelta struct {
	Units, Queued, Limited, NoDevices, NoConsent int
	Sent, Invalid, Failed                        int
	DoneBatch, DoneUnit                          string
}

type PushJob struct {
	Kind   string
	SendID string
	// Messages are the message in each language of the realm.
	Messages map[string]push.Message
	// Batch: the users. Plan: the audience, the last user id it paged to and the next batch.
	Users     []string
	Audience  *PushAudience
	After     string
	NextBatch int
	// RequiresConsent skips users who don't hold the consent, in a batch or a plan.
	RequiresConsent string
	// Deliver: who gets it, and how many users of the unit's chunk were not delivered to.
	Recipients []PushRecipient
	Limited    int
	NoDevices  int
	NoConsent  int
}

type PushOutboxEntry struct {
	ID        string
	SendID    string
	UserID    string
	DeviceID  string
	Platform  string
	Status    string // push.Status*
	Attempt   int
	Message   push.Message
	CreatedAt time.Time
	ExpiresAt time.Time
}

type PushRecipient struct {
	UserID  string
	Locale  string
	Devices []string // device ids: tokens are loaded when the unit is delivered
}

type PushSend struct {
	ID        string
	Kind      string // the template kind, or push.RawKind
	Sender    string // function:<database>/<name>, or admin:<id>
	CreatedAt time.Time
	ExpiresAt time.Time
	// Users is the number of users named; -1 when the send has an audience.
	Users int
	// Planned says every batch exists (Batches is final).
	Planned bool
	Batches int
	// Units is the delivery units made so far (final once Planned and every batch is done).
	Units       int
	BatchesDone int
	UnitsDone   int
	// Totals, by what became of each user or device.
	Queued    int // users handed to delivery
	Limited   int // users over their limits
	NoDevices int // users with no device to reach
	NoConsent int // users who don't hold the consent the send requires
	Sent      int // devices
	Invalid   int // devices removed as dead
	Failed    int // devices not delivered to
	// CompletedAt is zero until everything is done.
	CompletedAt time.Time
}

type PushSendFilter struct {
	Kind, Sender string
	Since, Until time.Time
	Limit, Skip  int
}

type PushSendInput struct {
	Kind     string
	Sender   string
	Messages map[string]push.Message
	Users    []string
	Audience *PushAudience
	// RequiresConsent names a consent a user must hold to be sent to; the others are
	// counted as no_consent.
	RequiresConsent string
}

type PushStarted struct {
	SendID string
	// Users is the number named (-1 for an audience); Jobs the jobs created.
	Users, Jobs int
	// Known says Queued, Limited and NoDevices are final: a send that fits one batch is
	// planned at once.
	Known                                bool
	Queued, Limited, NoDevice, NoConsent int
}

type PushUserFilter = PushAudience

type ReauthGrant struct {
	Token   string
	Expires time.Time
}

type Redeemed struct {
	Principal Principal
	Token     string
	NewUser   bool
	Profile   map[string]string
	// Challenge is set instead of a session when the user needs a second step.
	Challenge *IssuedChallenge
	// RecoveryCodesLeft is set when a recovery code ended the sign-in: how many remain.
	RecoveryCodesLeft *int
}

type RefusedError struct {
	UserID string
	Reason string // disabled, network, erased
}

type RevokeJob struct {
	UserID   string
	ClientID string // the client id the token was issued to
	Token    string // sealed (SealToken)
}

type RoleReport struct {
	// DBOnly maps emails to roles assigned only in the database, which a
	// rebuild from realm.yaml wouldn't restore.
	DBOnly map[string][]string
	// Undeclared maps emails to roles realm.yaml no longer declares.
	Undeclared map[string][]string
	// NetworksDBOnly lists users with network restrictions that realm.yaml
	// doesn't set, which a rebuild from realm.yaml wouldn't restore.
	NetworksDBOnly []string
	// Admins counts the people who can use the admin API with a session:
	// emails seeded into an admin role in realm.yaml, and users holding
	// one in the database, each counted once.
	Admins int
}

type ScheduleState struct {
	Database, Function string
	Paused             bool
	ChangedAt          time.Time
	ChangedBy          string // the actor that last paused or resumed it
}

type Scope struct {
	Op       ScopeOp
	Database string // "" is every database
	Name     string // a collection (read, write) or a function (call); "" is all of the database
}

type ScopeOp string

type Scopes []Scope

type Secret struct {
	Database   string // "": realm scope
	Name       string
	Ciphertext string // base64
	Nonce      string // base64
	KeyID      string // fingerprint of the key it was encrypted with
	CreatedAt  time.Time
	UpdatedAt  time.Time
	UpdatedBy  string
}

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

type SecretCipher struct {
	KeyID string
	// contains filtered or unexported fields
}

type SecretMeta struct {
	Database  string
	Name      string
	CreatedAt time.Time
	UpdatedAt time.Time
	UpdatedBy string
}

type Session struct {
	ID         string // public id, used to list and revoke sessions
	UserID     string
	TokenHash  string
	CreatedAt  time.Time
	LastUsedAt time.Time
	ExpiresAt  time.Time
	// Methods are how the session was created: the first factor, plus "totp" or "recovery"
	// when a second factor was used; MFA says it was. Empty for sessions from before
	// they were recorded.
	Methods []string
	MFA     bool
}

type SignupRequest struct {
	Email, Password, Invitation string
	Locales                     []string // most wanted first
	RedirectTo                  string   // already checked against the realm's allowed redirects
	ClientIP, RequestID         string
	// Consents are the consents accepted at sign-up: name to version. Every required
	// consent of the realm must be there at its current version.
	Consents  map[string]string
	UserAgent string
}

type SignupResult struct {
	Principal Principal
	Token     string
	Pending   bool
	// Challenge is set instead of a session when the new user has to set a second factor
	// up first (their roles require it).
	Challenge *IssuedChallenge
}

type Step struct {
	N          int
	Name       string
	Status     string // StepRunning, StepDone, StepFailed, StepTimedOut or StepCancelled
	StartedAt  time.Time
	EndedAt    time.Time // zero while running
	DurationMS int64
	Current    float64
	Total      *float64 // nil when the step has no known size
	Message    string
	UpdatedAt  time.Time
}

type StorageUsage struct {
	Realm StorageUsageTotals
	Users []UserUsage
}

type StorageUsageTotals struct {
	Bytes int64
	Files int64
}

type Store interface {
	// CreateUser inserts a user; ErrEmailTaken if the email exists.
	CreateUser(ctx context.Context, u User) error
	UserByEmail(ctx context.Context, email string) (User, error)
	// UserByID returns the user with that id; ErrNotFound if none.
	UserByID(ctx context.Context, id string) (User, error)
	ListUsers(ctx context.Context) ([]User, error)
	// ListUsersPage returns one page of users sorted by email: the users whose
	// email sorts after `after` (all when empty), skipping skip of them, at most
	// limit; hasMore says whether more follow. Emails are unique, so `after` is
	// an exact position. It never reads more than the page. A non-empty contains
	// keeps the users whose email holds it (emails are stored lower-case, so
	// pass it lower-case): a scan of the email index, not of the documents.
	ListUsersPage(ctx context.Context, contains, after string, skip, limit int) (users []User, hasMore bool, err error)
	// AddRoles adds roles the user doesn't have yet, setting UpdatedAt.
	AddRoles(ctx context.Context, userID string, roles []string, now time.Time) error
	// RemoveRole removes a role from the user, setting UpdatedAt.
	RemoveRole(ctx context.Context, userID, role string, now time.Time) error
	// UpdateUser applies upd and sets UpdatedAt to now.
	UpdateUser(ctx context.Context, id string, upd UserUpdate, now time.Time) error
	// ListUnverifiedUsers returns up to limit users whose address is still
	// unverified and who were created before the given time, oldest first.
	ListUnverifiedUsers(ctx context.Context, createdBefore time.Time, limit int) ([]User, error)
	// EraseUser turns the user into a tombstone: it deletes their sessions and
	// sign-in methods, and sets email (the unique placeholder), ErasedAt,
	// disabled and verified, with no roles, locale, networks or pending and
	// previous addresses. Repeating it is harmless.
	EraseUser(ctx context.Context, id, placeholderEmail string, now time.Time) error
	// DeleteEmailTokensOfUser removes the user's email tokens.
	DeleteEmailTokensOfUser(ctx context.Context, userID string) error
	// DeleteEmailJobsOfUser removes the email jobs addressed to the user.
	DeleteEmailJobsOfUser(ctx context.Context, userID string) error
	// AddEraseCount adds n to the erase job's count under key
	// ("<database>/<collection>/<operation>"), atomically.
	AddEraseCount(ctx context.Context, jobID, key string, n int64) error
	// PutChallenge stores a pending step. GetChallenge returns the unexpired one with that
	// id (ErrNotFound if none); ClaimChallenge does too and deletes it, in one atomic step,
	// so a challenge works once; CountChallengeAttempt adds an attempt and returns the new
	// state; DeleteChallenge and DeleteChallengesOfUser remove them.
	PutChallenge(ctx context.Context, c AuthChallenge) error
	GetChallenge(ctx context.Context, id string, now time.Time) (AuthChallenge, error)
	ClaimChallenge(ctx context.Context, id string, now time.Time) (AuthChallenge, error)
	CountChallengeAttempt(ctx context.Context, id string, now time.Time) (AuthChallenge, error)
	DeleteChallenge(ctx context.Context, id string) error
	DeleteChallengesOfUser(ctx context.Context, userID string, kinds ...string) error
	// ChallengeOfUser returns the newest unexpired challenge of a kind that a user has
	// (ErrNotFound if none); ChallengeByToken the unexpired challenge of a kind whose link
	// token has that hash; SetChallengeSecrets stores the hashes of a challenge's link token
	// ("" leaves it) and code, and returns the unexpired challenge.
	ChallengeOfUser(ctx context.Context, userID, kind string, now time.Time) (AuthChallenge, error)
	ChallengeByToken(ctx context.Context, tokenHash, kind string, now time.Time) (AuthChallenge, error)
	SetChallengeSecrets(ctx context.Context, id, tokenHash, codeHash string, now time.Time) (AuthChallenge, error)
	// MFAOf returns a user's second-factor record (ErrNotFound if none); PutMFA stores it,
	// replacing; DeleteMFA removes it; MFAUserIDs lists the users that have one.
	MFAOf(ctx context.Context, userID string) (MFARecord, error)
	PutMFA(ctx context.Context, rec MFARecord) error
	DeleteMFA(ctx context.Context, userID string) error
	MFAUserIDs(ctx context.Context) ([]string, error)
	// AdvanceMFAStep moves the last accepted TOTP step forward to step, atomically; false
	// when step is not greater than it (a replay).
	AdvanceMFAStep(ctx context.Context, userID string, step int64) (bool, error)
	// UseRecoveryCode removes the recovery code with that keyed hash, atomically, and says
	// how many are left; ok is false when the user has no such code.
	UseRecoveryCode(ctx context.Context, userID, hash string) (left int, ok bool, err error)
	// ClearJobInput replaces a job's input with an empty object: what it held (a new user's
	// profile) is not kept after the job has run.
	ClearJobInput(ctx context.Context, jobID string) error
	// ClearRevokeToken removes the sealed token a revoke job held.
	ClearRevokeToken(ctx context.Context, jobID string) error
	// ClearEraseEmail removes the email an erase job held.
	ClearEraseEmail(ctx context.Context, jobID string) error
	// ReopenJob queues a job that ended in failure again, with a fresh
	// attempt count and expiry; false when it isn't a failed job.
	ReopenJob(ctx context.Context, id string, expiresAt time.Time) (bool, error)
	// DeleteUser removes the user with their identities and sessions.
	DeleteUser(ctx context.Context, id string) error
	// PutIdentity creates the identity, or, when one with the same provider
	// and subject exists, updates its credentials and UpdatedAt (keeping its
	// ID and CreatedAt). ErrIdentityExists when the user already has another
	// identity of the provider, or the provider account belongs to another user.
	PutIdentity(ctx context.Context, id Identity) error
	Identity(ctx context.Context, provider, subject string) (Identity, error)
	// ListIdentities returns a user's identities, oldest first.
	ListIdentities(ctx context.Context, userID string) ([]Identity, error)
	// IdentityOf returns a user's identity of a provider; ErrNotFound if none.
	IdentityOf(ctx context.Context, userID, provider string) (Identity, error)
	// UpdateIdentity applies upd to the identity with that id and sets UpdatedAt
	// to now; ErrNotFound if none.
	UpdateIdentity(ctx context.Context, id string, upd IdentityUpdate, now time.Time) error
	// DeleteIdentity removes a user's identity of a provider; ErrNotFound if none.
	DeleteIdentity(ctx context.Context, userID, provider string) error
	// PutOAuthState stores a sign-in attempt; ClaimOAuthState deletes and returns the
	// unexpired attempt with that id (ErrNotFound if none), so a state works once.
	PutOAuthState(ctx context.Context, st OAuthState) error
	ClaimOAuthState(ctx context.Context, id string, now time.Time) (OAuthState, error)
	// PutLoginCode and ClaimLoginCode are the same for the one-time login codes.
	PutLoginCode(ctx context.Context, lc LoginCode) error
	ClaimLoginCode(ctx context.Context, id string, now time.Time) (LoginCode, error)
	// DeleteSessions revokes every session of the user and says how many.
	DeleteSessions(ctx context.Context, userID string) (int64, error)

	CreateSession(ctx context.Context, s Session) error
	// SessionByTokenHash returns the session and its user; ErrNotFound if
	// either doesn't exist.
	SessionByTokenHash(ctx context.Context, hash string) (Session, User, error)
	// TouchSession records a use of the session and its new expiry.
	TouchSession(ctx context.Context, id string, lastUsed, expires time.Time) error
	// ListSessions returns the user's sessions, newest first.
	ListSessions(ctx context.Context, userID string) ([]Session, error)
	// DeleteSession revokes one session of the user; ErrNotFound if the
	// user has no session with that id.
	DeleteSession(ctx context.Context, userID, id string) error
	// DeleteOtherSessions revokes every session of the user except keepID
	// and says how many.
	DeleteOtherSessions(ctx context.Context, userID, keepID string) (int64, error)

	// PutDevice registers a device: a new one, or, when the token's hash exists, that device
	// moved to this user and session (a new id, so the earlier owner's id is dead) with the
	// new token and name. It returns what is stored and whether it moved from another user.
	PutDevice(ctx context.Context, d Device) (Device, bool, error)
	// ListDevices returns the user's devices, most recently seen first.
	ListDevices(ctx context.Context, userID string) ([]Device, error)
	// DeleteDevice removes one of the user's devices; ErrNotFound if it isn't theirs.
	DeleteDevice(ctx context.Context, userID, id string) error
	// DeleteOldestDevices removes the user's least recently seen devices beyond keep, never
	// the device keepID, and says how many.
	DeleteOldestDevices(ctx context.Context, userID string, keep int, keepID string) (int64, error)
	// DeleteStaleDevices removes the devices last seen before the time.
	DeleteStaleDevices(ctx context.Context, before time.Time) (int64, error)
	// DeleteOrphanedDevices removes the devices whose session doesn't exist or has expired.
	DeleteOrphanedDevices(ctx context.Context, now time.Time) (int64, error)
	// The realm's app configuration state and history (internal/appconfig).
	appconfig.Store
	// AppendConsentRecord adds a record to the user's append-only consent history and
	// ListConsentRecords returns it, oldest first.
	AppendConsentRecord(ctx context.Context, r ConsentRecord) error
	ListConsentRecords(ctx context.Context, userID string) ([]ConsentRecord, error)
	// ReduceConsentRecords is what an erase leaves of a user's consent records: it removes
	// their IP address and user agent and replaces the user id with a pseudonym, and, when
	// deleteAt isn't zero, sets the time a retention will remove them. It says how many.
	// DeleteConsentRecordsOf removes them all (a realm that keeps none after an erase).
	ReduceConsentRecords(ctx context.Context, userID, pseudonym string, deleteAt time.Time) (int64, error)
	DeleteConsentRecordsOf(ctx context.Context, userID string) (int64, error)
	// SetUserConsent sets the version of a consent the user holds ("" removes it: withdrawn).
	SetUserConsent(ctx context.Context, userID, consent, version string) error
	// ConsentVersionsInUse lists the distinct consent and version pairs records refer to.
	ConsentVersionsInUse(ctx context.Context) ([]ConsentRef, error)
	// DevicesByIDs returns the devices that exist among the ids. LiveDevicesOf returns the
	// devices of the users whose registering session exists and hasn't expired, by user id,
	// most recently seen first. DeleteDeviceByID removes a device whatever its owner.
	DevicesByIDs(ctx context.Context, ids []string) ([]Device, error)
	LiveDevicesOf(ctx context.Context, userIDs []string, now time.Time) (map[string][]Device, error)
	DeleteDeviceByID(ctx context.Context, id string) error
	// DeleteDevicesOfPlatform removes every device of a platform, and says how many.
	DeleteDevicesOfPlatform(ctx context.Context, platform string) (int64, error)
	// UsersByIDs returns the users that exist among the ids. AudienceUserIDs returns the ids
	// of up to limit active users (not disabled, not erased) matching the audience, after the
	// id `after`, in id order.
	UsersByIDs(ctx context.Context, ids []string) ([]User, error)
	AudienceUserIDs(ctx context.Context, a PushAudience, after string, limit int) ([]string, error)
	// The record of a push send. AddPushSend adds the delta atomically (a finished batch or
	// unit named in it counts once), sets CompletedAt when everything is done and returns the
	// record. SetPushPlanned says every batch exists, and how many; SetPushPlanPosition keeps
	// a planner job's place; UpdatePushRecipients replaces what a delivery unit still has to do.
	CreatePushSend(ctx context.Context, p PushSend) error
	PushSendByID(ctx context.Context, id string) (PushSend, error)
	// PutPushOutbox stores a delivery the capture provider took; ListPushOutbox returns the
	// newest ones.
	PutPushOutbox(ctx context.Context, e PushOutboxEntry) error
	ListPushOutbox(ctx context.Context, limit int) ([]PushOutboxEntry, error)
	// ListPushSends returns sends newest first, and whether more follow.
	ListPushSends(ctx context.Context, f PushSendFilter) ([]PushSend, bool, error)
	AddPushSend(ctx context.Context, id string, d PushDelta, now time.Time) (PushSend, error)
	SetPushPlanned(ctx context.Context, id string, batches int, now time.Time) error
	SetPushPlanPosition(ctx context.Context, jobID, after string, nextBatch int) error
	UpdatePushRecipients(ctx context.Context, jobID string, recipients []PushRecipient) error

	// CreateAPIKey stores a key; ErrKeyNameTaken if the name exists.
	CreateAPIKey(ctx context.Context, k APIKey) error
	// APIKeyByHash returns the key with that hash; ErrKeyNotFound if none.
	APIKeyByHash(ctx context.Context, hash string) (APIKey, error)
	ListAPIKeys(ctx context.Context) ([]APIKey, error)
	// DeleteAPIKey removes the named key; ErrKeyNotFound if none.
	DeleteAPIKey(ctx context.Context, name string) error
	// TouchAPIKey records a use of the key.
	TouchAPIKey(ctx context.Context, hash string, at time.Time) error

	// AppendAudit adds a record to the audit trail, which is never
	// modified: records are only removed when they expire.
	AppendAudit(ctx context.Context, rec AuditRecord) error
	// ListAudit returns records matching f, newest first, and whether
	// more follow.
	ListAudit(ctx context.Context, f AuditFilter) ([]AuditRecord, bool, error)

	CreateInvitation(ctx context.Context, inv Invitation) error
	// ClaimInvitation atomically deletes and returns the unexpired
	// invitation with that token hash; ErrNotFound if none.
	ClaimInvitation(ctx context.Context, hash string, now time.Time) (Invitation, error)
	// ClaimInvitationByID is ClaimInvitation for an invitation known by its
	// id (one sent by email: nobody holds its own token).
	ClaimInvitationByID(ctx context.Context, id string, now time.Time) (Invitation, error)
	// ListInvitations returns all invitations, newest first.
	ListInvitations(ctx context.Context) ([]Invitation, error)
	// DeleteInvitation removes an invitation by id; ErrNotFound if none.
	DeleteInvitation(ctx context.Context, id string) error

	// LoginAttempts returns the failure counter of key (zero if none).
	LoginAttempts(ctx context.Context, key string) (Attempts, error)
	// RecordLoginFailure increments key's counter atomically, setting its
	// last failure to at; the counter is deleted at expires.
	RecordLoginFailure(ctx context.Context, key string, at, expires time.Time) error
	// ClearLoginAttempts deletes key's counter.
	ClearLoginAttempts(ctx context.Context, key string) error
	// AcquireLoginLock takes the lock of key for owner until the given time,
	// atomically: it is free when nobody holds it or its lease ended at or
	// before now. false means another owner holds it. The lock serializes the
	// password checks of one account across every instance.
	AcquireLoginLock(ctx context.Context, key, owner string, now, until time.Time) (bool, error)
	// ReleaseLoginLock frees the lock if owner still holds it.
	ReleaseLoginLock(ctx context.Context, key, owner string) error

	// IncrementCounter atomically increments key's counter (creating it,
	// or restarting it at 1 if its window has already ended) and returns
	// the new count and when it resets. The same generic "N events per
	// window" primitive login throttling uses, reused for function rate
	// limits (roadmap F9), which is why it lives in the same collection.
	IncrementCounter(ctx context.Context, key string, at, expires time.Time) (count int, resetAt time.Time, err error)

	// RecordInvocation appends a function call record (roadmap F10).
	// backd never updates or deletes them; MongoDB removes them when
	// they expire.
	RecordInvocation(ctx context.Context, r InvocationRecord) error
	// ListInvocations returns records matching f, newest first, and
	// whether more follow.
	ListInvocations(ctx context.Context, f InvocationFilter) ([]InvocationRecord, bool, error)

	// EnqueueJob stores a new async job (roadmap F11), queued for a worker.
	EnqueueJob(ctx context.Context, j Job) error
	// ClaimJob atomically claims the oldest job that's never been claimed,
	// or whose lease has expired, leasing it to workerID until at plus
	// the job's own timeout plus margin. found is false when there is
	// none to claim.
	ClaimJob(ctx context.Context, workerID string, at time.Time, margin time.Duration) (j Job, found bool, err error)
	// RetryJob counts a failed attempt and queues the job again, not to be
	// claimed before notBefore (it is still the same job: same id, same input).
	RetryJob(ctx context.Context, id string, notBefore time.Time) error
	// CompleteJob records a job's result; expiresAt starts its retention
	// countdown (MongoDB removes it once past).
	CompleteJob(ctx context.Context, id string, result JobResult, completedAt, expiresAt time.Time) error
	// CancelJob ends a job that isn't done yet with the given result (status
	// "cancelled"), clearing its lease. It reports whether it did: false when
	// the job was already done (or is unknown).
	CancelJob(ctx context.Context, id string, result JobResult, steps []Step, completedAt, expiresAt time.Time) (bool, error)
	// ListJobs returns the jobs matching f, newest first, and whether
	// more follow.
	ListJobs(ctx context.Context, f JobFilter) ([]Job, bool, error)
	// JournalFile records an upload; SetFileJournalStatus moves it to a new status
	// (with the document that references it, if any) and sets when the record
	// expires; StaleFileJournal lists uploads still writing or stored that were
	// last updated before the given time.
	JournalFile(ctx context.Context, e FileJournalEntry) error
	SetFileJournalStatus(ctx context.Context, id, status, documentID string, at, expiresAt time.Time) error
	StaleFileJournal(ctx context.Context, before, now time.Time, limit int) ([]FileJournalEntry, error)
	// FileJournalEntry returns one upload's record (ErrNotFound); the others are
	// the bookkeeping of pending uploads: completing one, claiming it once by its
	// token hash (stored → attaching, ErrNotFound when it can't be taken), giving
	// a claim back, and counting a caller's open ones.
	FileJournalEntry(ctx context.Context, id string) (FileJournalEntry, error)
	CompletePendingUpload(ctx context.Context, id, name, contentType, sha256sum string, size int64, uploadedAt time.Time, image string, at time.Time) error
	ClaimPendingUpload(ctx context.Context, id, tokenHash, documentID string, now time.Time) (FileJournalEntry, error)
	// ClaimDirectUpload is the same for a direct upload waiting for its bytes (writing →
	// attaching); ReleaseUpload moves a claimed upload back to the given status.
	ClaimDirectUpload(ctx context.Context, id, tokenHash string, now time.Time) (FileJournalEntry, error)
	ReleaseUpload(ctx context.Context, id, status string, at time.Time) error
	CountOpenPendingUploads(ctx context.Context, callerKey string, now time.Time) (int, error)
	// QueueFileDeletion adds an object to delete (one per key); ClaimFileDeletions
	// returns up to limit due ones and holds them until lease; CompleteFileDeletion
	// removes one; RetryFileDeletion counts a failed attempt and holds it until
	// notBefore.
	QueueFileDeletion(ctx context.Context, d FileDeletion) error
	// AddStorageUsage adds to the realm's running totals and, for a non-empty owner,
	// the user's; StorageUsage reads them; FileDeletionStats describes the queue.
	AddStorageUsage(ctx context.Context, owner string, bytes, files int64) error
	StorageUsage(ctx context.Context, limit int) (StorageUsage, error)
	// StorageUsageOf returns the realm's totals and one user's (zero for an owner of "").
	StorageUsageOf(ctx context.Context, owner string) (realm, user StorageUsageTotals, err error)
	FileDeletionStats(ctx context.Context) (FileDeletionStats, error)
	ClaimFileDeletions(ctx context.Context, now, lease time.Time, limit int) ([]FileDeletion, error)
	CompleteFileDeletion(ctx context.Context, key string) error
	RetryFileDeletion(ctx context.Context, key string, notBefore time.Time) error
	// RenewJobLease moves the lease of a running job's attempt to until; false
	// when the job no longer runs that attempt.
	RenewJobLease(ctx context.Context, id string, attempt int, until time.Time) (bool, error)
	// SetCheckReport stores a collection's latest schema check report, replacing
	// the previous one; ListCheckReports and GetCheckReport read them (documents
	// false leaves the lists of invalid documents out).
	SetCheckReport(ctx context.Context, r CheckReport) error
	ListCheckReports(ctx context.Context, documents bool) ([]CheckReport, error)
	GetCheckReport(ctx context.Context, database, collection string) (CheckReport, bool, error)
	// ImageDeclarations returns, by "<database>/<collection>.<field>/<version>", the
	// fingerprint of each declared image version as it was when a worker last looked;
	// SetImageDeclaration records one.
	ImageDeclarations(ctx context.Context) (map[string]string, error)
	SetImageDeclaration(ctx context.Context, key, fingerprint string) error
	// SetJobSteps replaces the steps of a running job's attempt; false when the
	// job is not running that attempt (so a late write changes nothing).
	SetJobSteps(ctx context.Context, id string, attempt int, steps []Step, omitted int) (bool, error)
	// GetJob returns one job by id; found is false if there is none.
	GetJob(ctx context.Context, id string) (j Job, found bool, err error)

	// CreateEmailToken stores a token's hash with its purpose and user.
	CreateEmailToken(ctx context.Context, t EmailToken) error
	// GetEmailToken returns the token with this hash whatever its state, or
	// ErrInvalidToken when there is none.
	GetEmailToken(ctx context.Context, hash string) (EmailToken, error)
	// RedeemEmailToken atomically marks the token with this hash and purpose
	// used, if it is unused and unexpired at now, and returns it; otherwise
	// ErrInvalidToken.
	RedeemEmailToken(ctx context.Context, hash, purpose string, now time.Time) (EmailToken, error)
	// InvalidateEmailTokens marks used every unused token of the user and
	// purpose.
	InvalidateEmailTokens(ctx context.Context, userID, purpose string, now time.Time) error

	// ClaimIdempotency (roadmap F12) atomically inserts rec if its id
	// isn't already used, or returns the existing record (running or
	// done) if it is. claimed is false in the second case.
	ClaimIdempotency(ctx context.Context, rec IdempotencyRecord) (existing IdempotencyRecord, claimed bool, err error)
	// CompleteIdempotency stores a claimed key's outcome: result for a
	// sync call, jobID for async (mutually exclusive). expiresAt starts
	// its retention countdown.
	CompleteIdempotency(ctx context.Context, id string, result *JobResult, jobID string, completedAt, expiresAt time.Time) error
	// ReleaseIdempotency removes a claim that shouldn't be remembered
	// (an infrastructure failure, not a real outcome), so a retry can
	// go through cleanly instead of being stuck "running" forever.
	ReleaseIdempotency(ctx context.Context, id string) error

	// SetScheduleState stores a scheduled function's state, replacing any.
	SetScheduleState(ctx context.Context, st ScheduleState) error
	// ListScheduleStates returns every stored state.
	ListScheduleStates(ctx context.Context) ([]ScheduleState, error)
	// UpsertSecret creates or replaces the secret at (database, name),
	// keeping its original CreatedAt on an update.
	UpsertSecret(ctx context.Context, s Secret) error
	// SecretByScope returns one secret; ErrSecretNotFound if none.
	SecretByScope(ctx context.Context, database, name string) (Secret, error)
	// ListSecrets returns every secret's metadata, sorted by database
	// (realm scope, "", first) then name.
	ListSecrets(ctx context.Context) ([]Secret, error)
	// DeleteSecret removes one; ErrSecretNotFound if none.
	DeleteSecret(ctx context.Context, database, name string) error
}

type TOTPSetup struct {
	SetupID string
	Secret  string // base32, for typing in
	URI     string // otpauth://
	QR      string // a PNG data URI of the URI
	Expires time.Time
}

type ThrottledError struct{ RetryAfter time.Duration }

type User struct {
	ID            string
	Email         string // normalized: trimmed, lowercased
	EmailVerified bool
	// PendingEmail is an address the user asked to change to and hasn't
	// confirmed yet; PreviousEmail is the one before the last change, kept
	// so the old address can be told and can undo it.
	PendingEmail  string
	PreviousEmail string
	// ErasedAt is when an administrator erased the user: what is left is a
	// tombstone, the id with an anonymized email and no way to sign in.
	ErasedAt time.Time
	Roles    []string
	Disabled bool
	// Locale is the user's language: one the realm lists (see
	// RealmSettings.Languages). Empty for users from before languages existed;
	// those use the realm's default.
	Locale string
	// AdminNetworks restrict the user's admin API requests; LoginNetworks
	// their login and every request with their session. Empty: no
	// restriction beyond the realm's.
	AdminNetworks registry.Networks
	LoginNetworks registry.Networks
	// Consents is the version of each consent the user has accepted and not
	// withdrawn: the summary of their consent records, for rules and sign-in.
	Consents  map[string]string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type UserUpdate struct {
	// Email changes the address (ErrEmailTaken when another user has it).
	Email         *string
	PendingEmail  *string // set; an empty string clears it
	PreviousEmail *string // set; an empty string clears it
	EmailVerified *bool
	Disabled      *bool
	Locale        *string
	AdminNetworks *registry.Networks // set (empty clears)
	LoginNetworks *registry.Networks // set (empty clears)
}

type UserUsage struct {
	UserID string
	StorageUsageTotals
}

type Users struct {
	Store    Store
	Hasher   *Hasher
	Settings registry.RealmSettings
	Now      func() time.Time // defaults to time.Now
	Realm    string           // the realm's name, for logs
	Log      *slog.Logger     // audit records are also logged here; nil: not logged

	// Cipher encrypts and decrypts secrets (roadmap F5); nil when
	// BACKD_SECRETS_KEY isn't configured, in which case every secret
	// resolves as missing. Cache holds decrypted values briefly, shared
	// across every realm's Users (NewSecretCache); nil disables caching.
	Cipher *SecretCipher
	Cache  *SecretCache

	// Metrics counts sessions and limits; nil turns it off.
	Metrics *metrics.Metrics
	// contains filtered or unexported fields
}