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

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

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 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 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
	// ListJobs returns the jobs matching f, newest first, and whether
	// more follow.
	ListJobs(ctx context.Context, f JobFilter) ([]Job, 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

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