store

type Account struct {
	ID     string
	UserID string
	// Provider is the id of the provider that asserted this identity, e.g.
	// "google". It is the host's own name for it, matched exactly.
	Provider string
	// ProviderAccountID is the provider's stable subject identifier — not
	// the email address, which users change.
	ProviderAccountID string
	// Email is what the provider asserted at the last sign-in, normalised.
	Email string
	// EmailVerified records whether the provider claimed to have verified
	// the address. It is the provider's claim, not a fact.
	EmailVerified bool
	// AccessTokenEncrypted and RefreshTokenEncrypted hold the provider's
	// own OAuth tokens, if the host chose to keep them for calling the
	// provider's API later. They are ciphertext (AES-256-GCM, via the
	// crypto package) rather than plaintext, because a database that leaks
	// these leaks live access to the user's account at the provider.
	// Both are nil when token persistence is off, which is the default.
	AccessTokenEncrypted  []byte
	RefreshTokenEncrypted []byte
	// TokenExpiresAt is when AccessTokenEncrypted stops working.
	TokenExpiresAt *time.Time
	// Scopes are what the provider granted.
	Scopes    []string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type AccountStore interface {
	CreateAccount(ctx context.Context, a *Account) error
	GetAccount(ctx context.Context, id string) (*Account, error)
	// GetAccountByProvider looks up the link by the provider's own subject
	// identifier. This is the query every social sign-in makes, and the
	// (provider, provider_account_id) index it needs must be UNIQUE.
	GetAccountByProvider(ctx context.Context, provider, providerAccountID string) (*Account, error)
	ListAccountsByUser(ctx context.Context, userID string) ([]*Account, error)
	UpdateAccount(ctx context.Context, a *Account) error
	DeleteAccount(ctx context.Context, id string) error
}

type BoundDevice struct {
	ID        string
	UserID    string
	Name      string
	TokenHash string
	UserAgent string
	IPAddress string
	// ExpiresAt is nil for a device that stays signed in until revoked,
	// which is the pin package's default.
	ExpiresAt  *time.Time
	LastUsedAt *time.Time
	RevokedAt  *time.Time
	CreatedAt  time.Time
}

type BoundDeviceStore interface {
	CreateBoundDevice(ctx context.Context, d *BoundDevice) error
	GetBoundDevice(ctx context.Context, id string) (*BoundDevice, error)
	// GetBoundDeviceByTokenHash returns revoked and expired devices too:
	// the service reads both columns itself. token_hash must be UNIQUE.
	GetBoundDeviceByTokenHash(ctx context.Context, hash string) (*BoundDevice, error)
	// ListBoundDevicesByUser lists every device of one user, revoked ones
	// included, oldest first.
	ListBoundDevicesByUser(ctx context.Context, userID string) ([]*BoundDevice, error)
	// TouchBoundDevice records a use at at, and reports ErrNotFound for a
	// device that is gone or revoked, so a use racing a revocation cannot
	// write over it.
	TouchBoundDevice(ctx context.Context, id string, at time.Time) error
	// RevokeBoundDevice revokes the device at at. Revoking a revoked device
	// keeps the first instant and is not an error; a missing one is
	// ErrNotFound.
	RevokeBoundDevice(ctx context.Context, id string, at time.Time) error
	// RevokeAllBoundDevices revokes every live device of userID and reports
	// how many it revoked.
	RevokeAllBoundDevices(ctx context.Context, userID string, at time.Time) (int, error)
}

type DeviceAuthorization struct {
	ID              string
	DeviceCodeHash  string
	UserCode        string
	ClientID        string
	Scope           string
	Status          DeviceAuthorizationStatus
	UserID          *string // set once Status is Approved
	ExpiresAt       time.Time
	IntervalSeconds int
	LastPolledAt    *time.Time
	CreatedAt       time.Time
}

type DeviceAuthorizationStatus string

type DeviceAuthorizationStore interface {
	CreateDeviceAuthorization(ctx context.Context, d *DeviceAuthorization) error
	GetDeviceAuthorizationByDeviceCodeHash(ctx context.Context, hash string) (*DeviceAuthorization, error)
	GetDeviceAuthorizationByUserCode(ctx context.Context, userCode string) (*DeviceAuthorization, error)
	UpdateDeviceAuthorization(ctx context.Context, d *DeviceAuthorization) error
	DeleteDeviceAuthorization(ctx context.Context, id string) error
}

type EmailLoginKind string

type EmailLoginStore interface {
	CreateEmailLoginToken(ctx context.Context, t *EmailLoginToken) error
	// GetEmailLoginTokenByHash resolves a magic link.
	GetEmailLoginTokenByHash(ctx context.Context, hash string) (*EmailLoginToken, error)
	// GetEmailLoginTokenByEmail resolves the outstanding token for an
	// address, which is how a code redemption finds the record it must
	// count a failed guess against.
	GetEmailLoginTokenByEmail(ctx context.Context, email string, kind EmailLoginKind) (*EmailLoginToken, error)
	// MarkEmailLoginTokenUsed marks the token used, and reports
	// ErrNotFound if it was already used or is gone.
	//
	// This is a compare-and-set, not an update, and the difference is the
	// single-use property. Reading a token, seeing UsedAt is nil, and
	// writing it back lets two concurrent redemptions of one link both
	// observe an unused token and both succeed -- one credential, two
	// sessions. In SQL:
	//
	//	UPDATE email_login_tokens SET used_at = $2
	//	 WHERE id = $1 AND used_at IS NULL
	//
	// and no rows affected means somebody else won, which is ErrNotFound.
	// Callers treat winning this as the authorisation to proceed, so an
	// implementation that always reports success has removed the control
	// rather than weakened it.
	MarkEmailLoginTokenUsed(ctx context.Context, id string, usedAt time.Time) error

	// IncrementEmailLoginTokenAttempts adds one to the token's failed-guess
	// count and returns the new value, or ErrNotFound if it is gone.
	//
	// Atomic for the same reason, and it matters more here: the returned
	// count is what decides when a six-digit code is burned, and read-then-
	// write loses increments under concurrency. An attacker guessing in
	// parallel would get many tries charged as one, which is the entire
	// budget MaxCodeAttempts exists to impose. In SQL:
	//
	//	UPDATE email_login_tokens SET attempts = attempts + 1
	//	 WHERE id = $1 RETURNING attempts
	//
	// Return the value the database computed, never one added in Go.
	IncrementEmailLoginTokenAttempts(ctx context.Context, id string) (int, error)
	// DeleteEmailLoginTokens removes every outstanding token of that kind
	// for the address.
	//
	// Requesting a new credential must invalidate the old one. If ten
	// codes were live at once, guessing would be ten times easier, and an
	// attacker can ask for as many as they like.
	DeleteEmailLoginTokens(ctx context.Context, email string, kind EmailLoginKind) error
}

type EmailLoginToken struct {
	ID    string
	Email string
	Kind  EmailLoginKind
	// TokenHash is the hash of the credential. For a link it is the hash
	// of the token alone; for a code it is the hash of the address and the
	// code together, so that a code is only ever valid for the address it
	// was sent to.
	TokenHash string
	// Attempts counts failed redemptions of a code. It is what makes a
	// six-digit credential survivable at all -- see MaxCodeAttempts.
	Attempts  int
	ExpiresAt time.Time
	UsedAt    *time.Time
	CreatedAt time.Time
}

type EmailVerificationStore interface {
	CreateEmailVerificationToken(ctx context.Context, t *EmailVerificationToken) error
	GetEmailVerificationTokenByHash(ctx context.Context, hash string) (*EmailVerificationToken, error)
	MarkEmailVerificationTokenUsed(ctx context.Context, id string) error
	DeleteUserEmailVerificationTokens(ctx context.Context, userID string) error
}

type EmailVerificationToken struct {
	ID        string
	UserID    string
	TokenHash string
	ExpiresAt time.Time
	UsedAt    *time.Time
	CreatedAt time.Time
}

type FailedLoginAttempt struct {
	ID        string
	Email     string
	IPAddress string
	CreatedAt time.Time
}

type Invitation struct {
	ID          string
	TeamID      string
	Email       string
	TokenHash   string
	Role        Role
	Status      InvitationStatus
	InvitedByID string
	ExpiresAt   time.Time
	AcceptedAt  *time.Time
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

type InvitationStatus string

type InvitationStore interface {
	CreateInvitation(ctx context.Context, i *Invitation) error
	GetInvitation(ctx context.Context, id string) (*Invitation, error)
	GetInvitationByTokenHash(ctx context.Context, hash string) (*Invitation, error)
	ListInvitationsByTeam(ctx context.Context, teamID string) ([]*Invitation, error)
	UpdateInvitation(ctx context.Context, i *Invitation) error
}

type LockoutStore interface {
	RecordFailedLoginAttempt(ctx context.Context, a *FailedLoginAttempt) error
	// CountRecentFailedLoginAttempts is called on every login attempt, not
	// only on failures -- it is what the temporary lockout is derived from.
	// Index (email, created_at).
	CountRecentFailedLoginAttempts(ctx context.Context, email string, since time.Time) (int, error)
	ClearFailedLoginAttempts(ctx context.Context, email string) error
	LockAccount(ctx context.Context, userID string) error
	IsAccountLocked(ctx context.Context, userID string) (bool, error)
	UnlockAccount(ctx context.Context, userID string) error
}

type Member struct {
	ID          string
	TeamID      string
	UserID      *string
	Role        Role
	DisplayName string
	Email       string
	IsActive    bool
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

type MemberStore interface {
	CreateMember(ctx context.Context, m *Member) error
	GetMember(ctx context.Context, id string) (*Member, error)
	GetMemberByUserAndTeam(ctx context.Context, userID, teamID string) (*Member, error)
	ListMembersByTeam(ctx context.Context, teamID string) ([]*Member, error)
	ListMembershipsByUser(ctx context.Context, userID string) ([]*Member, error)
	UpdateMember(ctx context.Context, m *Member) error
	DeleteMember(ctx context.Context, id string) error
}

type PINCredential struct {
	UserID    string
	PINHash   string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type PINStore interface {
	// SetPINCredential creates the user's PIN, or replaces the one they
	// have. UserID must be UNIQUE: a user has one PIN.
	SetPINCredential(ctx context.Context, c *PINCredential) error
	GetPINCredential(ctx context.Context, userID string) (*PINCredential, error)
	// DeletePINCredential is idempotent: deleting a PIN that is not there
	// is not an error.
	DeletePINCredential(ctx context.Context, userID string) error
}

type PasswordResetStore interface {
	CreatePasswordResetToken(ctx context.Context, t *PasswordResetToken) error
	GetPasswordResetTokenByHash(ctx context.Context, hash string) (*PasswordResetToken, error)
	MarkPasswordResetTokenUsed(ctx context.Context, id string) error
	DeleteUserPasswordResetTokens(ctx context.Context, userID string) error
}

type PasswordResetToken struct {
	ID        string
	UserID    string
	TokenHash string
	ExpiresAt time.Time
	UsedAt    *time.Time
	CreatedAt time.Time
}

type PendingTwoFactorSession struct {
	ID        string
	UserID    string
	TokenHash string
	ExpiresAt time.Time
	CreatedAt time.Time
}

type PendingTwoFactorStore interface {
	CreatePendingTwoFactorSession(ctx context.Context, s *PendingTwoFactorSession) error
	GetPendingTwoFactorSessionByHash(ctx context.Context, hash string) (*PendingTwoFactorSession, error)
	DeletePendingTwoFactorSession(ctx context.Context, id string) error
}

type PersonalAccessToken struct {
	ID         string
	UserID     string
	Name       string
	TokenHash  string
	Scopes     []string
	ExpiresAt  *time.Time
	LastUsedAt *time.Time
	RevokedAt  *time.Time
	CreatedAt  time.Time
}

type PersonalAccessTokenStore interface {
	CreatePersonalAccessToken(ctx context.Context, t *PersonalAccessToken) error
	GetPersonalAccessToken(ctx context.Context, id string) (*PersonalAccessToken, error)
	GetPersonalAccessTokenByHash(ctx context.Context, hash string) (*PersonalAccessToken, error)
	ListPersonalAccessTokensByUser(ctx context.Context, userID string) ([]*PersonalAccessToken, error)
	UpdatePersonalAccessToken(ctx context.Context, t *PersonalAccessToken) error
}

type RefreshToken struct {
	ID        string
	UserID    string
	TokenHash string
	ExpiresAt time.Time
	RevokedAt *time.Time
	UserAgent string
	IPAddress string
	// TeamID is the team the session acts in, nil for none. It is set by
	// user.Service.SwitchTeam and carried across rotation, and it reaches
	// the validated claims as Claims.TeamID. An adapter must persist it:
	// one that drops it fails closed, as a session without a team, but
	// SwitchTeam then appears to do nothing. A schema with teams can
	// reference them from it with a cascade, so deleting a team ends the
	// sessions acting in it.
	TeamID    *string
	CreatedAt time.Time
}

type RefreshTokenStore interface {
	CreateRefreshToken(ctx context.Context, t *RefreshToken) error
	GetRefreshTokenByHash(ctx context.Context, hash string) (*RefreshToken, error)
	RevokeRefreshToken(ctx context.Context, id string) error
	// ConsumeRefreshToken revokes the token only if it is not revoked yet,
	// and reports whether this call was the one that revoked it. It must be
	// a single atomic step: of any number of concurrent calls on one id,
	// exactly one reports true. Refresh relies on it to make a refresh
	// token single-use; a read followed by an unconditional write lets
	// every concurrent caller win. An unknown id reports false.
	ConsumeRefreshToken(ctx context.Context, id string) (bool, error)
	// TouchRefreshToken pushes a token's expiry out to expiresAt, and
	// reports ErrNotFound if it is gone or already revoked.
	//
	// It exists for the sliding expiry of user.SessionModeOpaque, where
	// this row is the session and using it keeps it alive. Refusing a
	// revoked row matters: without that check a session revoked between a
	// request's lookup and its extension would be quietly resurrected with
	// a fresh lifetime. In SQL:
	//
	//	UPDATE refresh_tokens SET expires_at = $2
	//	 WHERE id = $1 AND revoked_at IS NULL
	//
	// Nothing calls it in the default SessionModeJWT, where a refresh
	// token is rotated rather than extended.
	TouchRefreshToken(ctx context.Context, id string, expiresAt time.Time) error
	RevokeAllUserRefreshTokens(ctx context.Context, userID string) error
	ListActiveRefreshTokens(ctx context.Context, userID string) ([]*RefreshToken, error)
}

type Role string

type Superuser struct {
	ID           string
	Email        string
	PasswordHash string
	DisplayName  string
	IsActive     bool
	CreatedBy    *string
	LastLoginAt  *time.Time
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

type SuperuserRefreshToken struct {
	ID          string
	SuperuserID string
	TokenHash   string
	ExpiresAt   time.Time
	RevokedAt   *time.Time
	UserAgent   string
	IPAddress   string
	CreatedAt   time.Time
}

type SuperuserRefreshTokenStore interface {
	CreateSuperuserRefreshToken(ctx context.Context, t *SuperuserRefreshToken) error
	GetSuperuserRefreshTokenByHash(ctx context.Context, hash string) (*SuperuserRefreshToken, error)
	RevokeSuperuserRefreshToken(ctx context.Context, id string) error
	// ConsumeSuperuserRefreshToken is RefreshTokenStore.ConsumeRefreshToken
	// for operator tokens: revoke only if live, atomically, and report
	// whether this call did it.
	ConsumeSuperuserRefreshToken(ctx context.Context, id string) (bool, error)
	RevokeAllSuperuserRefreshTokens(ctx context.Context, superuserID string) error
	// ListActiveSuperuserRefreshTokens returns the unrevoked, unexpired
	// tokens for one operator, oldest first: their sessions.
	ListActiveSuperuserRefreshTokens(ctx context.Context, superuserID string) ([]*SuperuserRefreshToken, error)
}

type SuperuserStore interface {
	CreateSuperuser(ctx context.Context, s *Superuser) error
	GetSuperuserByID(ctx context.Context, id string) (*Superuser, error)
	GetSuperuserByEmail(ctx context.Context, email string) (*Superuser, error)
	ListSuperusers(ctx context.Context) ([]*Superuser, error)
	UpdateSuperuser(ctx context.Context, s *Superuser) error
	CountSuperusers(ctx context.Context) (int, error)
}

type SuperuserTwoFactorStore interface {
	CreateSuperuserTOTPSettings(ctx context.Context, t *TOTPSettings) error
	GetSuperuserTOTPSettings(ctx context.Context, superuserID string) (*TOTPSettings, error)
	UpdateSuperuserTOTPSettings(ctx context.Context, t *TOTPSettings) error
	DeleteSuperuserTOTPSettings(ctx context.Context, superuserID string) error

	CreateSuperuserPendingTwoFactorSession(ctx context.Context, p *PendingTwoFactorSession) error
	GetSuperuserPendingTwoFactorSessionByHash(ctx context.Context, hash string) (*PendingTwoFactorSession, error)
	DeleteSuperuserPendingTwoFactorSession(ctx context.Context, id string) error
}

type TOTPSettings struct {
	ID                 string
	UserID             string
	SecretEncrypted    []byte
	Enabled            bool
	VerifiedAt         *time.Time
	RecoveryCodeHashes []string
	RecoveryCodesUsed  int
	CreatedAt          time.Time
	UpdatedAt          time.Time
}

type TOTPStore interface {
	CreateTOTPSettings(ctx context.Context, t *TOTPSettings) error
	GetTOTPSettingsByUserID(ctx context.Context, userID string) (*TOTPSettings, error)
	UpdateTOTPSettings(ctx context.Context, t *TOTPSettings) error
	DeleteTOTPSettings(ctx context.Context, userID string) error
}

type Team struct {
	ID        string
	Name      string
	Slug      string
	OwnerID   string
	CreatedAt time.Time
	UpdatedAt time.Time
}

type TeamStore interface {
	CreateTeam(ctx context.Context, t *Team) error
	GetTeam(ctx context.Context, id string) (*Team, error)
	GetTeamBySlug(ctx context.Context, slug string) (*Team, error)
	UpdateTeam(ctx context.Context, t *Team) error
	DeleteTeam(ctx context.Context, id string) error
}

type TxRunner interface {
	RunInTx(ctx context.Context, fn func(ctx context.Context) error) error
}

type User struct {
	ID              string
	Email           string
	PasswordHash    string
	EmailVerified   bool
	EmailVerifiedAt *time.Time
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type UserStore interface {
	CreateUser(ctx context.Context, u *User) error
	GetUserByID(ctx context.Context, id string) (*User, error)
	GetUserByEmail(ctx context.Context, email string) (*User, error)
	UpdateUser(ctx context.Context, u *User) error
}

type WebAuthnChallenge struct {
	ID string
	// TokenHash is the hash of the handle held by the browser. The handle
	// itself is never stored, for the same reason a refresh token is not:
	// a leaked table should not yield live credentials.
	//
	// It must be UNIQUE. It is the only thing a ceremony is found by.
	TokenHash string
	// UserID is the account a *registration* ceremony belongs to, and nil
	// for a discoverable login, which names no user by design.
	//
	// authit never looks a challenge up by it, and never reads it back.
	// It is denormalised out of Data so a host can put a foreign key here
	// and have in-flight ceremonies cascade away with the account -- the
	// same reason WebAuthnCredential carries fields it does not strictly
	// need.
	UserID    *string
	Data      []byte
	ExpiresAt time.Time
	CreatedAt time.Time
}

type WebAuthnChallengeStore interface {
	CreateWebAuthnChallenge(ctx context.Context, c *WebAuthnChallenge) error

	// ConsumeWebAuthnChallenge atomically deletes the challenge and returns
	// what it held, or ErrNotFound if no row matched.
	//
	// Atomic is the whole method. Two callers presenting the same handle
	// concurrently must not both receive a row: exactly one deletes it and
	// sees it, and every other gets ErrNotFound. That race is precisely
	// what lets a captured assertion be replayed, and removing it is the
	// only reason this port is not just a map.
	//
	// In SQL it is one statement:
	//
	//	DELETE FROM webauthn_challenges WHERE token_hash = $1 RETURNING ...
	//
	// What matters is that the DELETE decides, not the read. Reading the
	// row first and returning it is fine -- the read may even be stale --
	// so long as the caller returns it only when its own delete removed
	// exactly one row, and reports ErrNotFound when it removed none. A
	// read that decides, with the delete as an afterthought, is the broken
	// version: two callers both read, both return, and the assertion is
	// accepted twice.
	//
	// Expiry is not judged here. An expired row is returned like any other
	// and refused by the passkey package; consuming it is still right,
	// since a spent challenge should not linger either way.
	ConsumeWebAuthnChallenge(ctx context.Context, tokenHash string) (*WebAuthnChallenge, error)
}

type WebAuthnCredential struct {
	ID     string
	UserID string
	// CredentialID is the authenticator's own identifier for this
	// credential, as raw bytes. Not a string: it is arbitrary binary.
	CredentialID []byte
	// Data is the opaque, authoritative credential record. See above.
	Data []byte

	// Name is a user-facing label ("MacBook Touch ID", "YubiKey"), so
	// somebody with four passkeys can tell which to revoke.
	Name string
	// Transports are the authenticator's reported transports ("internal",
	// "usb", "nfc", "hybrid"), useful for tailoring UI prompts.
	Transports []string
	// BackupEligible and BackupState describe whether the credential is a
	// syncing passkey and whether it is currently backed up. A credential
	// that is not backup-eligible lives on exactly one device, so losing
	// that device loses the credential -- which is worth telling a user
	// before it is their only one.
	BackupEligible bool
	BackupState    bool
	// CloneWarning records that an assertion arrived with a signature
	// counter that did not advance, which is evidence the credential's
	// private key exists in more than one place. It is a column rather
	// than only a field inside Data so that "find every compromised
	// credential" is a query.
	CloneWarning bool

	LastUsedAt *time.Time
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

type WebAuthnCredentialStore interface {
	CreateWebAuthnCredential(ctx context.Context, c *WebAuthnCredential) error
	GetWebAuthnCredential(ctx context.Context, id string) (*WebAuthnCredential, error)
	// GetWebAuthnCredentialByCredentialID is the lookup every assertion
	// makes. Its index must be UNIQUE; see the type's documentation.
	GetWebAuthnCredentialByCredentialID(ctx context.Context, credentialID []byte) (*WebAuthnCredential, error)
	ListWebAuthnCredentialsByUser(ctx context.Context, userID string) ([]*WebAuthnCredential, error)
	UpdateWebAuthnCredential(ctx context.Context, c *WebAuthnCredential) error
	DeleteWebAuthnCredential(ctx context.Context, id string) error
}