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 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"`
}

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 CustomEmail struct {
	Function string // <database>/<name> of the function that asked
	To       []string
	CC       []string
	BCC      []string
	Data     map[string]any
}

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
	// 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
	// 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
	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
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

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 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 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
	// 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 PolicyError struct{ Reason string }

type Principal struct {
	User    User
	Session Session
}

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
}

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
}

type SignupResult struct {
	Principal Principal
	Token     string
	Pending   bool
}

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
	// 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).
	PutIdentity(ctx context.Context, id Identity) error
	Identity(ctx context.Context, provider, subject string) (Identity, 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)

	// 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 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
	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
}